diff --git a/README.md b/README.md index cf6cd9f20..f0e4b08d9 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@

Homepage · + Open Source + · Docs · Start Cloud Trial @@ -53,20 +55,20 @@ ### Fast and Flexible Multi-Agent Automation Framework -> CrewAI is a lean, lightning-fast Python framework built entirely from scratch—completely **independent of LangChain or other agent frameworks**. -> It empowers developers with both high-level simplicity and precise low-level control, ideal for creating autonomous AI agents tailored to any scenario. +> CrewAI is an open-source Python framework with high-level abstractions and low-level APIs for building production-ready multi-agent workflows. +> It gives developers autonomous agent collaboration through Crews and precise, event-driven control through Flows. -- **CrewAI Crews**: Optimize for autonomy and collaborative intelligence. -- **CrewAI Flows**: The **enterprise and production architecture** for building and deploying multi-agent systems. Enable granular, event-driven control, single LLM calls for precise task orchestration and supports Crews natively +- **CrewAI Crews**: Optimize for autonomy and collaborative intelligence with role-based AI agents. +- **CrewAI Flows**: Build event-driven automations that combine precise workflow control, single LLM calls, and native support for Crews. With over 100,000 developers certified through our community courses at [learn.crewai.com](https://learn.crewai.com), CrewAI is rapidly becoming the -standard for enterprise-ready AI automation. +standard for production-ready agentic automation. # CrewAI AMP Suite -CrewAI AMP Suite is a comprehensive bundle tailored for organizations that require secure, scalable, and easy-to-manage agent-driven automation. +For organizations that need a commercial control plane around CrewAI, [CrewAI AMP Suite](https://www.crewai.com/enterprise) adds managed deployment, observability, governance, security, and enterprise support. -You can try one part of the suite the [Crew Control Plane for free](https://app.crewai.com) +You can try one part of the suite, the [Crew Control Plane, for free](https://app.crewai.com). ## Crew Control Plane Key Features: @@ -88,7 +90,6 @@ intelligent automations. - [Getting Started](#getting-started) - [Key Features](#key-features) - [Understanding Flows and Crews](#understanding-flows-and-crews) -- [CrewAI vs LangGraph](#how-crewai-compares) - [Examples](#examples) - [Quick Tutorial](#quick-tutorial) - [Write Job Descriptions](#write-job-descriptions) @@ -96,11 +97,11 @@ intelligent automations. - [Stock Analysis](#stock-analysis) - [Using Crews and Flows Together](#using-crews-and-flows-together) - [Connecting Your Crew to a Model](#connecting-your-crew-to-a-model) -- [How CrewAI Compares](#how-crewai-compares) -- [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq) +- [When to Use CrewAI](#when-to-use-crewai) - [Contribution](#contribution) - [Telemetry](#telemetry) - [License](#license) +- [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq) ## Build with AI @@ -134,15 +135,15 @@ This installs the official [CrewAI Skills](https://github.com/crewAIInc/skills) CrewAI Logo -CrewAI unlocks the true potential of multi-agent automation, delivering the best-in-class combination of speed, flexibility, and control with either Crews of AI Agents or Flows of Events: +CrewAI unlocks the true potential of multi-agent automation, delivering speed, flexibility, and control through Crews of AI agents and event-driven Flows: -- **Standalone Framework**: Built from scratch, independent of LangChain or any other agent framework. +- **Purpose-built architecture**: Designed specifically for agent orchestration, with a lightweight Python core and clean primitives for real-world automation. - **High Performance**: Optimized for speed and minimal resource usage, enabling faster execution. -- **Flexible Low Level Customization**: Complete freedom to customize at both high and low levels - from overall workflows and system architecture to granular agent behaviors, internal prompts, and execution logic. -- **Ideal for Every Use Case**: Proven effective for both simple tasks and highly complex, real-world, enterprise-grade scenarios. +- **Flexible Low-Level Customization**: Complete freedom to customize everything from workflows and system architecture to agent behaviors, internal prompts, and execution logic. +- **Ideal for Every Use Case**: Proven effective for simple tasks, complex workflows, and production-grade automation. - **Robust Community**: Backed by a rapidly growing community of over **100,000 certified** developers offering comprehensive support and resources. -CrewAI empowers developers and enterprises to confidently build intelligent automations, bridging the gap between simplicity, flexibility, and performance. +CrewAI empowers developers and teams to build intelligent automations that balance simplicity, flexibility, and production-grade control. ## Getting Started @@ -433,16 +434,17 @@ In addition to the sequential process, you can use the hierarchical process, whi ## Key Features -CrewAI stands apart as a lean, standalone, high-performance multi-AI Agent framework delivering simplicity, flexibility, and precise control—free from the complexity and limitations found in other agent frameworks. +CrewAI gives developers a practical foundation for building agentic systems that move from prototype to production: autonomous collaboration where it helps, explicit workflow control where it matters, and Python-native customization throughout. -- **Standalone & Lean**: Completely independent from other frameworks like LangChain, offering faster execution and lighter resource demands. -- **Flexible & Precise**: Easily orchestrate autonomous agents through intuitive [Crews](https://docs.crewai.com/concepts/crews) or precise [Flows](https://docs.crewai.com/concepts/flows), achieving perfect balance for your needs. -- **Seamless Integration**: Effortlessly combine Crews (autonomy) and Flows (precision) to create complex, real-world automations. -- **Deep Customization**: Tailor every aspect—from high-level workflows down to low-level internal prompts and agent behaviors. -- **Reliable Performance**: Consistent results across simple tasks and complex, enterprise-level automations. -- **Thriving Community**: Backed by robust documentation and over 100,000 certified developers, providing exceptional support and guidance. +- **Crews for autonomy**: Model teams of specialized AI agents with roles, goals, tools, and tasks. +- **Flows for control**: Build event-driven workflows with state, branching, routing, and production logic. +- **Seamless integration**: Combine Crews and Flows to create complex, real-world automations. +- **Python-native customization**: Customize prompts, tools, execution paths, state, and integrations without fighting the framework. +- **Agent-ready capabilities**: Use tools, memory, knowledge, checkpointing, async execution, and MCP/A2A support for more capable production agents. +- **Production-ready patterns**: Add deterministic steps, human input, structured outputs, and checkpointing as your system grows. +- **Thriving community**: Backed by robust documentation and over 100,000 certified developers, providing exceptional support and guidance. -Choose CrewAI to easily build powerful, adaptable, and production-ready AI automations. +Choose CrewAI to build powerful, adaptable, and production-ready AI automations. ## Examples @@ -580,16 +582,17 @@ CrewAI supports using various LLMs through a variety of connection options. By d Please refer to the [Connect CrewAI to LLMs](https://docs.crewai.com/how-to/LLM-Connections/) page for details on configuring your agents' connections to models. -## How CrewAI Compares +## When to Use CrewAI -**CrewAI's Advantage**: CrewAI combines autonomous agent intelligence with precise workflow control through its unique Crews and Flows architecture. The framework excels at both high-level orchestration and low-level customization, enabling complex, production-grade systems with granular control. +Use CrewAI when you need more than a single prompt or chatbot: multi-step work, specialized agents, tool use, structured outputs, human review, or workflows that combine autonomous reasoning with explicit business logic. -- **LangGraph**: While LangGraph provides a foundation for building agent workflows, its approach requires significant boilerplate code and complex state management patterns. The framework's tight coupling with LangChain can limit flexibility when implementing custom agent behaviors or integrating with external systems. +CrewAI is especially useful when you want to: -_P.S. CrewAI demonstrates significant performance advantages over LangGraph, executing 5.76x faster in certain cases like this QA task example ([see comparison](https://github.com/crewAIInc/crewAI-examples/tree/main/Notebooks/CrewAI%20Flows%20%26%20Langgraph/QA%20Agent)) while achieving higher evaluation scores with faster completion times in certain coding tasks, like in this example ([detailed analysis](https://github.com/crewAIInc/crewAI-examples/blob/main/Notebooks/CrewAI%20Flows%20%26%20Langgraph/Coding%20Assistant/coding_assistant_eval.ipynb))._ - -- **Autogen**: While Autogen excels at creating conversational agents capable of working together, it lacks an inherent concept of process. In Autogen, orchestrating agents' interactions requires additional programming, which can become complex and cumbersome as the scale of tasks grows. -- **ChatDev**: ChatDev introduced the idea of processes into the realm of AI agents, but its implementation is quite rigid. Customizations in ChatDev are limited and not geared towards production environments, which can hinder scalability and flexibility in real-world applications. +- Coordinate multiple agents with clear roles and tasks. +- Wrap agent work in deterministic, event-driven workflows. +- Keep application logic in regular Python. +- Move from experiment to production without changing frameworks. +- Add tools, memory, checkpointing, and async execution as your system grows. ## Contribution @@ -698,7 +701,7 @@ CrewAI is released under the [MIT License](https://github.com/crewAIInc/crewAI/b - [What exactly is CrewAI?](#q-what-exactly-is-crewai) - [How do I install CrewAI?](#q-how-do-i-install-crewai) -- [Does CrewAI depend on LangChain?](#q-does-crewai-depend-on-langchain) +- [Is CrewAI a standalone framework?](#q-is-crewai-a-standalone-framework) - [Is CrewAI open-source?](#q-is-crewai-open-source) - [Does CrewAI collect data from users?](#q-does-crewai-collect-data-from-users) @@ -707,7 +710,6 @@ CrewAI is released under the [MIT License](https://github.com/crewAIInc/crewAI/b - [Can CrewAI handle complex use cases?](#q-can-crewai-handle-complex-use-cases) - [Can I use CrewAI with local AI models?](#q-can-i-use-crewai-with-local-ai-models) - [What makes Crews different from Flows?](#q-what-makes-crews-different-from-flows) -- [How is CrewAI better than LangChain?](#q-how-is-crewai-better-than-langchain) - [Does CrewAI support fine-tuning or training custom models?](#q-does-crewai-support-fine-tuning-or-training-custom-models) ### Resources and Community @@ -723,7 +725,7 @@ CrewAI is released under the [MIT License](https://github.com/crewAIInc/crewAI/b ### Q: What exactly is CrewAI? -A: CrewAI is a standalone, lean, and fast Python framework built specifically for orchestrating autonomous AI agents. Unlike frameworks like LangChain, CrewAI does not rely on external dependencies, making it leaner, faster, and simpler. +A: CrewAI is a lean, fast Python framework built specifically for orchestrating autonomous AI agents and production-ready agentic workflows. ### Q: How do I install CrewAI? @@ -739,9 +741,9 @@ For additional tools, use: uv pip install 'crewai[tools]' ``` -### Q: Does CrewAI depend on LangChain? +### Q: Is CrewAI a standalone framework? -A: No. CrewAI is built entirely from the ground up, with no dependencies on LangChain or other agent frameworks. This ensures a lean, fast, and flexible experience. +A: Yes. CrewAI is a standalone Python framework with its own primitives for agents, tasks, crews, flows, tools, and orchestration. ### Q: Can CrewAI handle complex use cases? @@ -755,10 +757,6 @@ A: Absolutely! CrewAI supports various language models, including local ones. To A: Crews provide autonomous agent collaboration, ideal for tasks requiring flexible decision-making and dynamic interaction. Flows offer precise, event-driven control, ideal for managing detailed execution paths and secure state management. You can seamlessly combine both for maximum effectiveness. -### Q: How is CrewAI better than LangChain? - -A: CrewAI provides simpler, more intuitive APIs, faster execution speeds, more reliable and consistent results, robust documentation, and an active community—addressing common criticisms and limitations associated with LangChain. - ### Q: Is CrewAI open-source? A: Yes, CrewAI is open-source and actively encourages community contributions and collaboration. @@ -797,11 +795,11 @@ A: Absolutely! CrewAI agents can easily integrate with external tools, APIs, and ### Q: Is CrewAI suitable for production environments? -A: Yes, CrewAI is explicitly designed with production-grade standards, ensuring reliability, stability, and scalability for enterprise deployments. +A: Yes, CrewAI is designed with production-grade patterns that support reliable, stable, and scalable agentic workflows. ### Q: How scalable is CrewAI? -A: CrewAI is highly scalable, supporting simple automations and large-scale enterprise workflows involving numerous agents and complex tasks simultaneously. +A: CrewAI is highly scalable, supporting simple automations and large-scale workflows involving numerous agents and complex tasks simultaneously. ### Q: Does CrewAI offer debugging and monitoring tools? diff --git a/docs/docs.json b/docs/docs.json index 1b8b03806..c71b081ee 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -586,8 +586,538 @@ "tag": "Edge" }, { - "version": "v1.15.0", + "version": "v1.15.1", "default": true, + "tabs": [ + { + "tab": "Home", + "icon": "house", + "groups": [ + { + "group": "Welcome", + "pages": [ + "index" + ] + } + ] + }, + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Get Started", + "pages": [ + "v1.15.1/en/introduction", + "v1.15.1/en/guides/coding-tools/build-with-ai", + "v1.15.1/en/skills", + "v1.15.1/en/installation", + "v1.15.1/en/quickstart" + ] + }, + { + "group": "Guides", + "pages": [ + { + "group": "Strategy", + "icon": "compass", + "pages": [ + "v1.15.1/en/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agents", + "icon": "user", + "pages": [ + "v1.15.1/en/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "icon": "users", + "pages": [ + "v1.15.1/en/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "icon": "code-branch", + "pages": [ + "v1.15.1/en/guides/flows/first-flow", + "v1.15.1/en/guides/flows/mastering-flow-state", + "v1.15.1/en/guides/flows/conversational-flows", + "v1.15.1/en/guides/flows/inputs-id-deprecation" + ] + }, + { + "group": "Tools", + "icon": "wrench", + "pages": [ + "v1.15.1/en/guides/tools/publish-custom-tools" + ] + }, + { + "group": "Coding Tools", + "icon": "terminal", + "pages": [ + "v1.15.1/en/guides/coding-tools/agents-md", + "v1.15.1/en/guides/coding-tools/build-with-ai" + ] + }, + { + "group": "Advanced", + "icon": "gear", + "pages": [ + "v1.15.1/en/guides/advanced/customizing-prompts", + "v1.15.1/en/guides/advanced/fingerprinting" + ] + }, + { + "group": "Migration", + "icon": "shuffle", + "pages": [ + "v1.15.1/en/guides/migration/migrating-from-langgraph", + "v1.15.1/en/guides/migration/upgrading-crewai" + ] + } + ] + }, + { + "group": "Core Concepts", + "pages": [ + "v1.15.1/en/concepts/agents", + "v1.15.1/en/concepts/agent-capabilities", + "v1.15.1/en/concepts/tasks", + "v1.15.1/en/concepts/crews", + "v1.15.1/en/concepts/flows", + "v1.15.1/en/concepts/production-architecture", + "v1.15.1/en/concepts/knowledge", + "v1.15.1/en/concepts/skills", + "v1.15.1/en/concepts/llms", + "v1.15.1/en/concepts/files", + "v1.15.1/en/concepts/processes", + "v1.15.1/en/concepts/collaboration", + "v1.15.1/en/concepts/training", + "v1.15.1/en/concepts/memory", + "v1.15.1/en/concepts/reasoning", + "v1.15.1/en/concepts/planning", + "v1.15.1/en/concepts/testing", + "v1.15.1/en/concepts/cli", + "v1.15.1/en/concepts/tools", + "v1.15.1/en/concepts/event-listener", + "v1.15.1/en/concepts/checkpointing" + ] + }, + { + "group": "MCP Integration", + "pages": [ + "v1.15.1/en/mcp/overview", + "v1.15.1/en/mcp/dsl-integration", + "v1.15.1/en/mcp/stdio", + "v1.15.1/en/mcp/sse", + "v1.15.1/en/mcp/streamable-http", + "v1.15.1/en/mcp/multiple-servers", + "v1.15.1/en/mcp/security" + ] + }, + { + "group": "Tools", + "pages": [ + "v1.15.1/en/tools/overview", + { + "group": "File & Document", + "icon": "folder-open", + "pages": [ + "v1.15.1/en/tools/file-document/overview", + "v1.15.1/en/tools/file-document/filereadtool", + "v1.15.1/en/tools/file-document/filewritetool", + "v1.15.1/en/tools/file-document/pdfsearchtool", + "v1.15.1/en/tools/file-document/docxsearchtool", + "v1.15.1/en/tools/file-document/mdxsearchtool", + "v1.15.1/en/tools/file-document/xmlsearchtool", + "v1.15.1/en/tools/file-document/txtsearchtool", + "v1.15.1/en/tools/file-document/jsonsearchtool", + "v1.15.1/en/tools/file-document/csvsearchtool", + "v1.15.1/en/tools/file-document/directorysearchtool", + "v1.15.1/en/tools/file-document/directoryreadtool", + "v1.15.1/en/tools/file-document/ocrtool", + "v1.15.1/en/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "Web Scraping & Browsing", + "icon": "globe", + "pages": [ + "v1.15.1/en/tools/web-scraping/overview", + "v1.15.1/en/tools/web-scraping/scrapewebsitetool", + "v1.15.1/en/tools/web-scraping/scrapeelementfromwebsitetool", + "v1.15.1/en/tools/web-scraping/scrapflyscrapetool", + "v1.15.1/en/tools/web-scraping/seleniumscrapingtool", + "v1.15.1/en/tools/web-scraping/scrapegraphscrapetool", + "v1.15.1/en/tools/web-scraping/spidertool", + "v1.15.1/en/tools/web-scraping/browserbaseloadtool", + "v1.15.1/en/tools/web-scraping/hyperbrowserloadtool", + "v1.15.1/en/tools/web-scraping/stagehandtool", + "v1.15.1/en/tools/web-scraping/firecrawlcrawlwebsitetool", + "v1.15.1/en/tools/web-scraping/firecrawlscrapewebsitetool", + "v1.15.1/en/tools/web-scraping/oxylabsscraperstool", + "v1.15.1/en/tools/web-scraping/brightdata-tools", + "v1.15.1/en/tools/web-scraping/youai-contents" + ] + }, + { + "group": "Search & Research", + "icon": "magnifying-glass", + "pages": [ + "v1.15.1/en/tools/search-research/overview", + "v1.15.1/en/tools/search-research/serperdevtool", + "v1.15.1/en/tools/search-research/bravesearchtool", + "v1.15.1/en/tools/search-research/exasearchtool", + "v1.15.1/en/tools/search-research/linkupsearchtool", + "v1.15.1/en/tools/search-research/githubsearchtool", + "v1.15.1/en/tools/search-research/websitesearchtool", + "v1.15.1/en/tools/search-research/codedocssearchtool", + "v1.15.1/en/tools/search-research/youtubechannelsearchtool", + "v1.15.1/en/tools/search-research/youtubevideosearchtool", + "v1.15.1/en/tools/search-research/tavilysearchtool", + "v1.15.1/en/tools/search-research/tavilyextractortool", + "v1.15.1/en/tools/search-research/tavilyresearchtool", + "v1.15.1/en/tools/search-research/arxivpapertool", + "v1.15.1/en/tools/search-research/serpapi-googlesearchtool", + "v1.15.1/en/tools/search-research/serpapi-googleshoppingtool", + "v1.15.1/en/tools/search-research/databricks-query-tool", + "v1.15.1/en/tools/search-research/youai-search" + ] + }, + { + "group": "Database & Data", + "icon": "database", + "pages": [ + "v1.15.1/en/tools/database-data/overview", + "v1.15.1/en/tools/database-data/mysqltool", + "v1.15.1/en/tools/database-data/pgsearchtool", + "v1.15.1/en/tools/database-data/snowflakesearchtool", + "v1.15.1/en/tools/database-data/nl2sqltool", + "v1.15.1/en/tools/database-data/qdrantvectorsearchtool", + "v1.15.1/en/tools/database-data/weaviatevectorsearchtool", + "v1.15.1/en/tools/database-data/mongodbvectorsearchtool", + "v1.15.1/en/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "AI & Machine Learning", + "icon": "brain", + "pages": [ + "v1.15.1/en/tools/ai-ml/overview", + "v1.15.1/en/tools/ai-ml/dalletool", + "v1.15.1/en/tools/ai-ml/visiontool", + "v1.15.1/en/tools/ai-ml/aimindtool", + "v1.15.1/en/tools/ai-ml/llamaindextool", + "v1.15.1/en/tools/ai-ml/langchaintool", + "v1.15.1/en/tools/ai-ml/ragtool", + "v1.15.1/en/tools/ai-ml/codeinterpretertool", + "v1.15.1/en/tools/ai-ml/daytona", + "v1.15.1/en/tools/ai-ml/e2bsandboxtools" + ] + }, + { + "group": "Cloud & Storage", + "icon": "cloud", + "pages": [ + "v1.15.1/en/tools/cloud-storage/overview", + "v1.15.1/en/tools/cloud-storage/s3readertool", + "v1.15.1/en/tools/cloud-storage/s3writertool", + "v1.15.1/en/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "v1.15.1/en/tools/integration/overview", + "v1.15.1/en/tools/integration/bedrockinvokeagenttool", + "v1.15.1/en/tools/integration/crewaiautomationtool", + "v1.15.1/en/tools/integration/mergeagenthandlertool" + ] + }, + { + "group": "Automation", + "icon": "bolt", + "pages": [ + "v1.15.1/en/tools/automation/overview", + "v1.15.1/en/tools/automation/apifyactorstool", + "v1.15.1/en/tools/automation/composiotool", + "v1.15.1/en/tools/automation/multiontool", + "v1.15.1/en/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "v1.15.1/en/observability/tracing", + "v1.15.1/en/observability/overview", + "v1.15.1/en/observability/arize-phoenix", + "v1.15.1/en/observability/braintrust", + "v1.15.1/en/observability/datadog", + "v1.15.1/en/observability/galileo", + "v1.15.1/en/observability/langdb", + "v1.15.1/en/observability/langfuse", + "v1.15.1/en/observability/langtrace", + "v1.15.1/en/observability/maxim", + "v1.15.1/en/observability/mlflow", + "v1.15.1/en/observability/neatlogs", + "v1.15.1/en/observability/openlit", + "v1.15.1/en/observability/opik", + "v1.15.1/en/observability/patronus-evaluation", + "v1.15.1/en/observability/portkey", + "v1.15.1/en/observability/weave", + "v1.15.1/en/observability/truefoundry" + ] + }, + { + "group": "Learn", + "pages": [ + "v1.15.1/en/learn/overview", + "v1.15.1/en/learn/llm-selection-guide", + "v1.15.1/en/learn/conditional-tasks", + "v1.15.1/en/learn/coding-agents", + "v1.15.1/en/learn/create-custom-tools", + "v1.15.1/en/learn/custom-llm", + "v1.15.1/en/learn/custom-manager-agent", + "v1.15.1/en/learn/customizing-agents", + "v1.15.1/en/learn/dalle-image-generation", + "v1.15.1/en/learn/force-tool-output-as-result", + "v1.15.1/en/learn/hierarchical-process", + "v1.15.1/en/learn/human-input-on-execution", + "v1.15.1/en/learn/human-in-the-loop", + "v1.15.1/en/learn/human-feedback-in-flows", + "v1.15.1/en/learn/kickoff-async", + "v1.15.1/en/learn/kickoff-for-each", + "v1.15.1/en/learn/llm-connections", + "v1.15.1/en/learn/litellm-removal-guide", + "v1.15.1/en/learn/multimodal-agents", + "v1.15.1/en/learn/replay-tasks-from-latest-crew-kickoff", + "v1.15.1/en/learn/sequential-process", + "v1.15.1/en/learn/using-annotations", + "v1.15.1/en/learn/execution-hooks", + "v1.15.1/en/learn/llm-hooks", + "v1.15.1/en/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "v1.15.1/en/telemetry" + ] + } + ] + }, + { + "tab": "AMP", + "icon": "briefcase", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "v1.15.1/en/enterprise/introduction" + ] + }, + { + "group": "Build", + "pages": [ + "v1.15.1/en/enterprise/features/automations", + { + "group": "Crew Studio", + "icon": "pencil", + "pages": [ + "v1.15.1/en/enterprise/features/crew-studio", + "v1.15.1/en/enterprise/features/merged-step-card" + ] + }, + "v1.15.1/en/enterprise/features/marketplace", + "v1.15.1/en/enterprise/features/agent-repositories", + "v1.15.1/en/enterprise/features/tools-and-integrations", + "v1.15.1/en/enterprise/features/pii-trace-redactions", + "v1.15.1/en/enterprise/features/a2a" + ] + }, + { + "group": "Operate", + "pages": [ + "v1.15.1/en/enterprise/features/traces", + "v1.15.1/en/enterprise/features/webhook-streaming", + "v1.15.1/en/enterprise/features/hallucination-guardrail", + "v1.15.1/en/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "Manage", + "pages": [ + "v1.15.1/en/enterprise/features/sso", + "v1.15.1/en/enterprise/features/rbac", + { + "group": "Secrets Manager", + "icon": "lock", + "pages": [ + "v1.15.1/en/enterprise/features/secrets-manager/overview", + "v1.15.1/en/enterprise/features/secrets-manager/usage", + { + "group": "AWS", + "icon": "aws", + "pages": [ + "v1.15.1/en/enterprise/features/secrets-manager/aws", + "v1.15.1/en/enterprise/features/secrets-manager/aws-workload-identity" + ] + }, + { + "group": "GCP", + "icon": "google", + "pages": [ + "v1.15.1/en/enterprise/features/secrets-manager/gcp", + "v1.15.1/en/enterprise/features/secrets-manager/gcp-workload-identity" + ] + }, + { + "group": "Azure", + "icon": "microsoft", + "pages": [ + "v1.15.1/en/enterprise/features/secrets-manager/azure", + "v1.15.1/en/enterprise/features/secrets-manager/azure-workload-identity" + ] + }, + "v1.15.1/en/enterprise/features/secrets-manager/verify-rotation" + ] + } + ] + }, + { + "group": "Integration Docs", + "pages": [ + "v1.15.1/en/enterprise/integrations/asana", + "v1.15.1/en/enterprise/integrations/box", + "v1.15.1/en/enterprise/integrations/clickup", + "v1.15.1/en/enterprise/integrations/databricks", + "v1.15.1/en/enterprise/integrations/github", + "v1.15.1/en/enterprise/integrations/gmail", + "v1.15.1/en/enterprise/integrations/google_calendar", + "v1.15.1/en/enterprise/integrations/google_contacts", + "v1.15.1/en/enterprise/integrations/google_docs", + "v1.15.1/en/enterprise/integrations/google_drive", + "v1.15.1/en/enterprise/integrations/google_sheets", + "v1.15.1/en/enterprise/integrations/google_slides", + "v1.15.1/en/enterprise/integrations/hubspot", + "v1.15.1/en/enterprise/integrations/jira", + "v1.15.1/en/enterprise/integrations/linear", + "v1.15.1/en/enterprise/integrations/microsoft_excel", + "v1.15.1/en/enterprise/integrations/microsoft_onedrive", + "v1.15.1/en/enterprise/integrations/microsoft_outlook", + "v1.15.1/en/enterprise/integrations/microsoft_sharepoint", + "v1.15.1/en/enterprise/integrations/microsoft_teams", + "v1.15.1/en/enterprise/integrations/microsoft_word", + "v1.15.1/en/enterprise/integrations/notion", + "v1.15.1/en/enterprise/integrations/salesforce", + "v1.15.1/en/enterprise/integrations/shopify", + "v1.15.1/en/enterprise/integrations/slack", + "v1.15.1/en/enterprise/integrations/snowflake", + "v1.15.1/en/enterprise/integrations/stripe", + "v1.15.1/en/enterprise/integrations/zendesk" + ] + }, + { + "group": "Triggers", + "pages": [ + "v1.15.1/en/enterprise/guides/automation-triggers", + "v1.15.1/en/enterprise/guides/gmail-trigger", + "v1.15.1/en/enterprise/guides/google-calendar-trigger", + "v1.15.1/en/enterprise/guides/google-drive-trigger", + "v1.15.1/en/enterprise/guides/outlook-trigger", + "v1.15.1/en/enterprise/guides/onedrive-trigger", + "v1.15.1/en/enterprise/guides/microsoft-teams-trigger", + "v1.15.1/en/enterprise/guides/slack-trigger", + "v1.15.1/en/enterprise/guides/hubspot-trigger", + "v1.15.1/en/enterprise/guides/salesforce-trigger", + "v1.15.1/en/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "v1.15.1/en/enterprise/guides/build-crew", + "v1.15.1/en/enterprise/guides/prepare-for-deployment", + "v1.15.1/en/enterprise/guides/deploy-to-amp", + "v1.15.1/en/enterprise/guides/monorepo-deployments", + "v1.15.1/en/enterprise/guides/private-package-registry", + "v1.15.1/en/enterprise/guides/kickoff-crew", + "v1.15.1/en/enterprise/guides/update-crew", + "v1.15.1/en/enterprise/guides/enable-crew-studio", + "v1.15.1/en/enterprise/guides/capture_telemetry_logs", + "v1.15.1/en/enterprise/guides/datadog", + "v1.15.1/en/enterprise/guides/azure-openai-setup", + "v1.15.1/en/enterprise/guides/vertex-ai-workload-identity-setup", + "v1.15.1/en/enterprise/guides/tool-repository", + "v1.15.1/en/enterprise/guides/custom-mcp-server", + "v1.15.1/en/enterprise/guides/react-component-export", + "v1.15.1/en/enterprise/guides/team-management", + "v1.15.1/en/enterprise/guides/human-in-the-loop", + "v1.15.1/en/enterprise/guides/webhook-automation" + ] + }, + { + "group": "Resources", + "pages": [ + "v1.15.1/en/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API Reference", + "icon": "magnifying-glass", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "v1.15.1/en/api-reference/introduction", + "v1.15.1/en/api-reference/inputs", + "v1.15.1/en/api-reference/kickoff", + "v1.15.1/en/api-reference/resume", + "v1.15.1/en/api-reference/status" + ] + } + ] + }, + { + "tab": "Examples", + "icon": "code", + "groups": [ + { + "group": "Examples", + "pages": [ + "v1.15.1/en/examples/example", + "v1.15.1/en/examples/cookbooks" + ] + } + ] + }, + { + "tab": "Changelog", + "icon": "clock", + "groups": [ + { + "group": "Release Notes", + "pages": [ + "v1.15.1/en/changelog" + ] + } + ] + } + ], + "tag": "Latest" + }, + { + "version": "v1.15.0", "tabs": [ { "tab": "Home", @@ -1053,6 +1583,7 @@ "v1.15.0/en/enterprise/guides/update-crew", "v1.15.0/en/enterprise/guides/enable-crew-studio", "v1.15.0/en/enterprise/guides/capture_telemetry_logs", + "v1.15.0/en/enterprise/guides/datadog", "v1.15.0/en/enterprise/guides/azure-openai-setup", "v1.15.0/en/enterprise/guides/vertex-ai-workload-identity-setup", "v1.15.0/en/enterprise/guides/tool-repository", @@ -1112,8 +1643,7 @@ } ] } - ], - "tag": "Latest" + ] }, { "version": "v1.14.7", @@ -9276,8 +9806,515 @@ "tag": "Edge" }, { - "version": "v1.15.0", + "version": "v1.15.1", "default": true, + "tabs": [ + { + "tab": "Início", + "icon": "house", + "groups": [ + { + "group": "Bem-vindo", + "pages": [ + "v1.15.1/pt-BR/index" + ] + } + ] + }, + { + "tab": "Documentação", + "icon": "book-open", + "groups": [ + { + "group": "Começando", + "pages": [ + "v1.15.1/pt-BR/introduction", + "v1.15.1/pt-BR/guides/coding-tools/build-with-ai", + "v1.15.1/pt-BR/skills", + "v1.15.1/pt-BR/installation", + "v1.15.1/pt-BR/quickstart" + ] + }, + { + "group": "Guias", + "pages": [ + { + "group": "Estratégia", + "icon": "compass", + "pages": [ + "v1.15.1/pt-BR/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agentes", + "icon": "user", + "pages": [ + "v1.15.1/pt-BR/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "icon": "users", + "pages": [ + "v1.15.1/pt-BR/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "icon": "code-branch", + "pages": [ + "v1.15.1/pt-BR/guides/flows/first-flow", + "v1.15.1/pt-BR/guides/flows/mastering-flow-state", + "v1.15.1/pt-BR/guides/flows/conversational-flows", + "v1.15.1/pt-BR/guides/flows/inputs-id-deprecation" + ] + }, + { + "group": "Ferramentas", + "icon": "wrench", + "pages": [ + "v1.15.1/pt-BR/guides/tools/publish-custom-tools" + ] + }, + { + "group": "Ferramentas de Codificação", + "icon": "terminal", + "pages": [ + "v1.15.1/pt-BR/guides/coding-tools/agents-md" + ] + }, + { + "group": "Avançado", + "icon": "gear", + "pages": [ + "v1.15.1/pt-BR/guides/advanced/customizing-prompts", + "v1.15.1/pt-BR/guides/advanced/fingerprinting" + ] + }, + { + "group": "Migração", + "icon": "shuffle", + "pages": [ + "v1.15.1/pt-BR/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "Conceitos-Chave", + "pages": [ + "v1.15.1/pt-BR/concepts/agents", + "v1.15.1/pt-BR/concepts/agent-capabilities", + "v1.15.1/pt-BR/concepts/tasks", + "v1.15.1/pt-BR/concepts/crews", + "v1.15.1/pt-BR/concepts/flows", + "v1.15.1/pt-BR/concepts/production-architecture", + "v1.15.1/pt-BR/concepts/knowledge", + "v1.15.1/pt-BR/concepts/skills", + "v1.15.1/pt-BR/concepts/llms", + "v1.15.1/pt-BR/concepts/files", + "v1.15.1/pt-BR/concepts/processes", + "v1.15.1/pt-BR/concepts/collaboration", + "v1.15.1/pt-BR/concepts/training", + "v1.15.1/pt-BR/concepts/memory", + "v1.15.1/pt-BR/concepts/reasoning", + "v1.15.1/pt-BR/concepts/planning", + "v1.15.1/pt-BR/concepts/testing", + "v1.15.1/pt-BR/concepts/cli", + "v1.15.1/pt-BR/concepts/tools", + "v1.15.1/pt-BR/concepts/event-listener", + "v1.15.1/pt-BR/concepts/checkpointing" + ] + }, + { + "group": "Integração MCP", + "pages": [ + "v1.15.1/pt-BR/mcp/overview", + "v1.15.1/pt-BR/mcp/dsl-integration", + "v1.15.1/pt-BR/mcp/stdio", + "v1.15.1/pt-BR/mcp/sse", + "v1.15.1/pt-BR/mcp/streamable-http", + "v1.15.1/pt-BR/mcp/multiple-servers", + "v1.15.1/pt-BR/mcp/security" + ] + }, + { + "group": "Ferramentas", + "pages": [ + "v1.15.1/pt-BR/tools/overview", + { + "group": "Arquivo & Documento", + "icon": "folder-open", + "pages": [ + "v1.15.1/pt-BR/tools/file-document/overview", + "v1.15.1/pt-BR/tools/file-document/filereadtool", + "v1.15.1/pt-BR/tools/file-document/filewritetool", + "v1.15.1/pt-BR/tools/file-document/pdfsearchtool", + "v1.15.1/pt-BR/tools/file-document/docxsearchtool", + "v1.15.1/pt-BR/tools/file-document/mdxsearchtool", + "v1.15.1/pt-BR/tools/file-document/xmlsearchtool", + "v1.15.1/pt-BR/tools/file-document/txtsearchtool", + "v1.15.1/pt-BR/tools/file-document/jsonsearchtool", + "v1.15.1/pt-BR/tools/file-document/csvsearchtool", + "v1.15.1/pt-BR/tools/file-document/directorysearchtool", + "v1.15.1/pt-BR/tools/file-document/directoryreadtool" + ] + }, + { + "group": "Web Scraping & Navegação", + "icon": "globe", + "pages": [ + "v1.15.1/pt-BR/tools/web-scraping/overview", + "v1.15.1/pt-BR/tools/web-scraping/scrapewebsitetool", + "v1.15.1/pt-BR/tools/web-scraping/scrapeelementfromwebsitetool", + "v1.15.1/pt-BR/tools/web-scraping/scrapflyscrapetool", + "v1.15.1/pt-BR/tools/web-scraping/seleniumscrapingtool", + "v1.15.1/pt-BR/tools/web-scraping/scrapegraphscrapetool", + "v1.15.1/pt-BR/tools/web-scraping/spidertool", + "v1.15.1/pt-BR/tools/web-scraping/browserbaseloadtool", + "v1.15.1/pt-BR/tools/web-scraping/hyperbrowserloadtool", + "v1.15.1/pt-BR/tools/web-scraping/stagehandtool", + "v1.15.1/pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool", + "v1.15.1/pt-BR/tools/web-scraping/firecrawlscrapewebsitetool", + "v1.15.1/pt-BR/tools/web-scraping/oxylabsscraperstool" + ] + }, + { + "group": "Pesquisa", + "icon": "magnifying-glass", + "pages": [ + "v1.15.1/pt-BR/tools/search-research/overview", + "v1.15.1/pt-BR/tools/search-research/serperdevtool", + "v1.15.1/pt-BR/tools/search-research/bravesearchtool", + "v1.15.1/pt-BR/tools/search-research/exasearchtool", + "v1.15.1/pt-BR/tools/search-research/linkupsearchtool", + "v1.15.1/pt-BR/tools/search-research/githubsearchtool", + "v1.15.1/pt-BR/tools/search-research/websitesearchtool", + "v1.15.1/pt-BR/tools/search-research/codedocssearchtool", + "v1.15.1/pt-BR/tools/search-research/youtubechannelsearchtool", + "v1.15.1/pt-BR/tools/search-research/youtubevideosearchtool" + ] + }, + { + "group": "Dados", + "icon": "database", + "pages": [ + "v1.15.1/pt-BR/tools/database-data/overview", + "v1.15.1/pt-BR/tools/database-data/mysqltool", + "v1.15.1/pt-BR/tools/database-data/pgsearchtool", + "v1.15.1/pt-BR/tools/database-data/snowflakesearchtool", + "v1.15.1/pt-BR/tools/database-data/nl2sqltool", + "v1.15.1/pt-BR/tools/database-data/qdrantvectorsearchtool", + "v1.15.1/pt-BR/tools/database-data/weaviatevectorsearchtool" + ] + }, + { + "group": "IA & Machine Learning", + "icon": "brain", + "pages": [ + "v1.15.1/pt-BR/tools/ai-ml/overview", + "v1.15.1/pt-BR/tools/ai-ml/dalletool", + "v1.15.1/pt-BR/tools/ai-ml/visiontool", + "v1.15.1/pt-BR/tools/ai-ml/aimindtool", + "v1.15.1/pt-BR/tools/ai-ml/llamaindextool", + "v1.15.1/pt-BR/tools/ai-ml/langchaintool", + "v1.15.1/pt-BR/tools/ai-ml/ragtool", + "v1.15.1/pt-BR/tools/ai-ml/codeinterpretertool", + "v1.15.1/pt-BR/tools/ai-ml/daytona" + ] + }, + { + "group": "Cloud & Armazenamento", + "icon": "cloud", + "pages": [ + "v1.15.1/pt-BR/tools/cloud-storage/overview", + "v1.15.1/pt-BR/tools/cloud-storage/s3readertool", + "v1.15.1/pt-BR/tools/cloud-storage/s3writertool", + "v1.15.1/pt-BR/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "v1.15.1/pt-BR/tools/integration/overview", + "v1.15.1/pt-BR/tools/integration/bedrockinvokeagenttool", + "v1.15.1/pt-BR/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "Automação", + "icon": "bolt", + "pages": [ + "v1.15.1/pt-BR/tools/automation/overview", + "v1.15.1/pt-BR/tools/automation/apifyactorstool", + "v1.15.1/pt-BR/tools/automation/composiotool", + "v1.15.1/pt-BR/tools/automation/multiontool" + ] + } + ] + }, + { + "group": "Observabilidade", + "pages": [ + "v1.15.1/pt-BR/observability/tracing", + "v1.15.1/pt-BR/observability/overview", + "v1.15.1/pt-BR/observability/arize-phoenix", + "v1.15.1/pt-BR/observability/braintrust", + "v1.15.1/pt-BR/observability/datadog", + "v1.15.1/pt-BR/observability/galileo", + "v1.15.1/pt-BR/observability/langdb", + "v1.15.1/pt-BR/observability/langfuse", + "v1.15.1/pt-BR/observability/langtrace", + "v1.15.1/pt-BR/observability/maxim", + "v1.15.1/pt-BR/observability/mlflow", + "v1.15.1/pt-BR/observability/openlit", + "v1.15.1/pt-BR/observability/opik", + "v1.15.1/pt-BR/observability/patronus-evaluation", + "v1.15.1/pt-BR/observability/portkey", + "v1.15.1/pt-BR/observability/weave", + "v1.15.1/pt-BR/observability/truefoundry" + ] + }, + { + "group": "Aprenda", + "pages": [ + "v1.15.1/pt-BR/learn/overview", + "v1.15.1/pt-BR/learn/llm-selection-guide", + "v1.15.1/pt-BR/learn/conditional-tasks", + "v1.15.1/pt-BR/learn/coding-agents", + "v1.15.1/pt-BR/learn/create-custom-tools", + "v1.15.1/pt-BR/learn/custom-llm", + "v1.15.1/pt-BR/learn/custom-manager-agent", + "v1.15.1/pt-BR/learn/customizing-agents", + "v1.15.1/pt-BR/learn/dalle-image-generation", + "v1.15.1/pt-BR/learn/force-tool-output-as-result", + "v1.15.1/pt-BR/learn/hierarchical-process", + "v1.15.1/pt-BR/learn/human-input-on-execution", + "v1.15.1/pt-BR/learn/human-in-the-loop", + "v1.15.1/pt-BR/learn/human-feedback-in-flows", + "v1.15.1/pt-BR/learn/kickoff-async", + "v1.15.1/pt-BR/learn/kickoff-for-each", + "v1.15.1/pt-BR/learn/llm-connections", + "v1.15.1/pt-BR/learn/multimodal-agents", + "v1.15.1/pt-BR/learn/replay-tasks-from-latest-crew-kickoff", + "v1.15.1/pt-BR/learn/sequential-process", + "v1.15.1/pt-BR/learn/using-annotations", + "v1.15.1/pt-BR/learn/execution-hooks", + "v1.15.1/pt-BR/learn/llm-hooks", + "v1.15.1/pt-BR/learn/tool-hooks" + ] + }, + { + "group": "Telemetria", + "pages": [ + "v1.15.1/pt-BR/telemetry" + ] + } + ] + }, + { + "tab": "AMP", + "icon": "briefcase", + "groups": [ + { + "group": "Começando", + "pages": [ + "v1.15.1/pt-BR/enterprise/introduction" + ] + }, + { + "group": "Construir", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/automations", + { + "group": "Crew Studio", + "icon": "pencil", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/crew-studio", + "v1.15.1/pt-BR/enterprise/features/merged-step-card" + ] + }, + "v1.15.1/pt-BR/enterprise/features/marketplace", + "v1.15.1/pt-BR/enterprise/features/agent-repositories", + "v1.15.1/pt-BR/enterprise/features/tools-and-integrations", + "v1.15.1/pt-BR/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "Operar", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/traces", + "v1.15.1/pt-BR/enterprise/features/webhook-streaming", + "v1.15.1/pt-BR/enterprise/features/hallucination-guardrail", + "v1.15.1/pt-BR/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "Gerenciar", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/rbac", + { + "group": "Secrets Manager", + "icon": "lock", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/secrets-manager/overview", + "v1.15.1/pt-BR/enterprise/features/secrets-manager/usage", + { + "group": "AWS", + "icon": "aws", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/secrets-manager/aws", + "v1.15.1/pt-BR/enterprise/features/secrets-manager/aws-workload-identity" + ] + }, + { + "group": "GCP", + "icon": "google", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp", + "v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity" + ] + }, + { + "group": "Azure", + "icon": "microsoft", + "pages": [ + "v1.15.1/pt-BR/enterprise/features/secrets-manager/azure", + "v1.15.1/pt-BR/enterprise/features/secrets-manager/azure-workload-identity" + ] + }, + "v1.15.1/pt-BR/enterprise/features/secrets-manager/verify-rotation" + ] + } + ] + }, + { + "group": "Documentação de Integração", + "pages": [ + "v1.15.1/pt-BR/enterprise/integrations/asana", + "v1.15.1/pt-BR/enterprise/integrations/box", + "v1.15.1/pt-BR/enterprise/integrations/clickup", + "v1.15.1/pt-BR/enterprise/integrations/databricks", + "v1.15.1/pt-BR/enterprise/integrations/github", + "v1.15.1/pt-BR/enterprise/integrations/gmail", + "v1.15.1/pt-BR/enterprise/integrations/google_calendar", + "v1.15.1/pt-BR/enterprise/integrations/google_contacts", + "v1.15.1/pt-BR/enterprise/integrations/google_docs", + "v1.15.1/pt-BR/enterprise/integrations/google_drive", + "v1.15.1/pt-BR/enterprise/integrations/google_sheets", + "v1.15.1/pt-BR/enterprise/integrations/google_slides", + "v1.15.1/pt-BR/enterprise/integrations/hubspot", + "v1.15.1/pt-BR/enterprise/integrations/jira", + "v1.15.1/pt-BR/enterprise/integrations/linear", + "v1.15.1/pt-BR/enterprise/integrations/microsoft_excel", + "v1.15.1/pt-BR/enterprise/integrations/microsoft_onedrive", + "v1.15.1/pt-BR/enterprise/integrations/microsoft_outlook", + "v1.15.1/pt-BR/enterprise/integrations/microsoft_sharepoint", + "v1.15.1/pt-BR/enterprise/integrations/microsoft_teams", + "v1.15.1/pt-BR/enterprise/integrations/microsoft_word", + "v1.15.1/pt-BR/enterprise/integrations/notion", + "v1.15.1/pt-BR/enterprise/integrations/salesforce", + "v1.15.1/pt-BR/enterprise/integrations/shopify", + "v1.15.1/pt-BR/enterprise/integrations/slack", + "v1.15.1/pt-BR/enterprise/integrations/snowflake", + "v1.15.1/pt-BR/enterprise/integrations/stripe", + "v1.15.1/pt-BR/enterprise/integrations/zendesk" + ] + }, + { + "group": "Guias", + "pages": [ + "v1.15.1/pt-BR/enterprise/guides/build-crew", + "v1.15.1/pt-BR/enterprise/guides/prepare-for-deployment", + "v1.15.1/pt-BR/enterprise/guides/deploy-to-amp", + "v1.15.1/pt-BR/enterprise/guides/monorepo-deployments", + "v1.15.1/pt-BR/enterprise/guides/private-package-registry", + "v1.15.1/pt-BR/enterprise/guides/kickoff-crew", + "v1.15.1/pt-BR/enterprise/guides/training-crews", + "v1.15.1/pt-BR/enterprise/guides/update-crew", + "v1.15.1/pt-BR/enterprise/guides/enable-crew-studio", + "v1.15.1/pt-BR/enterprise/guides/capture_telemetry_logs", + "v1.15.1/pt-BR/enterprise/guides/datadog", + "v1.15.1/pt-BR/enterprise/guides/azure-openai-setup", + "v1.15.1/pt-BR/enterprise/guides/tool-repository", + "v1.15.1/pt-BR/enterprise/guides/custom-mcp-server", + "v1.15.1/pt-BR/enterprise/guides/react-component-export", + "v1.15.1/pt-BR/enterprise/guides/team-management", + "v1.15.1/pt-BR/enterprise/guides/human-in-the-loop", + "v1.15.1/pt-BR/enterprise/guides/webhook-automation" + ] + }, + { + "group": "Triggers", + "pages": [ + "v1.15.1/pt-BR/enterprise/guides/automation-triggers", + "v1.15.1/pt-BR/enterprise/guides/gmail-trigger", + "v1.15.1/pt-BR/enterprise/guides/google-calendar-trigger", + "v1.15.1/pt-BR/enterprise/guides/google-drive-trigger", + "v1.15.1/pt-BR/enterprise/guides/outlook-trigger", + "v1.15.1/pt-BR/enterprise/guides/onedrive-trigger", + "v1.15.1/pt-BR/enterprise/guides/microsoft-teams-trigger", + "v1.15.1/pt-BR/enterprise/guides/slack-trigger", + "v1.15.1/pt-BR/enterprise/guides/hubspot-trigger", + "v1.15.1/pt-BR/enterprise/guides/salesforce-trigger", + "v1.15.1/pt-BR/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "Recursos", + "pages": [ + "v1.15.1/pt-BR/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "Referência da API", + "icon": "magnifying-glass", + "groups": [ + { + "group": "Começando", + "pages": [ + "v1.15.1/pt-BR/api-reference/introduction", + "v1.15.1/pt-BR/api-reference/inputs", + "v1.15.1/pt-BR/api-reference/kickoff", + "v1.15.1/pt-BR/api-reference/resume", + "v1.15.1/pt-BR/api-reference/status" + ] + } + ] + }, + { + "tab": "Exemplos", + "icon": "code", + "groups": [ + { + "group": "Exemplos", + "pages": [ + "v1.15.1/pt-BR/examples/example", + "v1.15.1/pt-BR/examples/cookbooks" + ] + } + ] + }, + { + "tab": "Notas de Versão", + "icon": "clock", + "groups": [ + { + "group": "Notas de Versão", + "pages": [ + "v1.15.1/pt-BR/changelog" + ] + } + ] + } + ], + "tag": "Latest" + }, + { + "version": "v1.15.0", "tabs": [ { "tab": "Início", @@ -9705,6 +10742,7 @@ "v1.15.0/pt-BR/enterprise/guides/update-crew", "v1.15.0/pt-BR/enterprise/guides/enable-crew-studio", "v1.15.0/pt-BR/enterprise/guides/capture_telemetry_logs", + "v1.15.0/pt-BR/enterprise/guides/datadog", "v1.15.0/pt-BR/enterprise/guides/azure-openai-setup", "v1.15.0/pt-BR/enterprise/guides/tool-repository", "v1.15.0/pt-BR/enterprise/guides/custom-mcp-server", @@ -9779,8 +10817,7 @@ } ] } - ], - "tag": "Latest" + ] }, { "version": "v1.14.7", @@ -17659,8 +18696,527 @@ "tag": "Edge" }, { - "version": "v1.15.0", + "version": "v1.15.1", "default": true, + "tabs": [ + { + "tab": "홈", + "icon": "house", + "groups": [ + { + "group": "환영합니다", + "pages": [ + "v1.15.1/ko/index" + ] + } + ] + }, + { + "tab": "기술 문서", + "icon": "book-open", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "v1.15.1/ko/introduction", + "v1.15.1/ko/guides/coding-tools/build-with-ai", + "v1.15.1/ko/skills", + "v1.15.1/ko/installation", + "v1.15.1/ko/quickstart" + ] + }, + { + "group": "가이드", + "pages": [ + { + "group": "전략", + "icon": "compass", + "pages": [ + "v1.15.1/ko/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "에이전트 (Agents)", + "icon": "user", + "pages": [ + "v1.15.1/ko/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "크루 (Crews)", + "icon": "users", + "pages": [ + "v1.15.1/ko/guides/crews/first-crew" + ] + }, + { + "group": "플로우 (Flows)", + "icon": "code-branch", + "pages": [ + "v1.15.1/ko/guides/flows/first-flow", + "v1.15.1/ko/guides/flows/mastering-flow-state", + "v1.15.1/ko/guides/flows/conversational-flows", + "v1.15.1/ko/guides/flows/inputs-id-deprecation" + ] + }, + { + "group": "도구", + "icon": "wrench", + "pages": [ + "v1.15.1/ko/guides/tools/publish-custom-tools" + ] + }, + { + "group": "코딩 도구", + "icon": "terminal", + "pages": [ + "v1.15.1/ko/guides/coding-tools/agents-md" + ] + }, + { + "group": "고급", + "icon": "gear", + "pages": [ + "v1.15.1/ko/guides/advanced/customizing-prompts", + "v1.15.1/ko/guides/advanced/fingerprinting" + ] + }, + { + "group": "마이그레이션", + "icon": "shuffle", + "pages": [ + "v1.15.1/ko/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "핵심 개념", + "pages": [ + "v1.15.1/ko/concepts/agents", + "v1.15.1/ko/concepts/tasks", + "v1.15.1/ko/concepts/agent-capabilities", + "v1.15.1/ko/concepts/crews", + "v1.15.1/ko/concepts/flows", + "v1.15.1/ko/concepts/production-architecture", + "v1.15.1/ko/concepts/knowledge", + "v1.15.1/ko/concepts/skills", + "v1.15.1/ko/concepts/llms", + "v1.15.1/ko/concepts/files", + "v1.15.1/ko/concepts/processes", + "v1.15.1/ko/concepts/collaboration", + "v1.15.1/ko/concepts/training", + "v1.15.1/ko/concepts/memory", + "v1.15.1/ko/concepts/reasoning", + "v1.15.1/ko/concepts/planning", + "v1.15.1/ko/concepts/testing", + "v1.15.1/ko/concepts/cli", + "v1.15.1/ko/concepts/tools", + "v1.15.1/ko/concepts/event-listener", + "v1.15.1/ko/concepts/checkpointing" + ] + }, + { + "group": "MCP 통합", + "pages": [ + "v1.15.1/ko/mcp/overview", + "v1.15.1/ko/mcp/dsl-integration", + "v1.15.1/ko/mcp/stdio", + "v1.15.1/ko/mcp/sse", + "v1.15.1/ko/mcp/streamable-http", + "v1.15.1/ko/mcp/multiple-servers", + "v1.15.1/ko/mcp/security" + ] + }, + { + "group": "도구 (Tools)", + "pages": [ + "v1.15.1/ko/tools/overview", + { + "group": "파일 & 문서", + "icon": "folder-open", + "pages": [ + "v1.15.1/ko/tools/file-document/overview", + "v1.15.1/ko/tools/file-document/filereadtool", + "v1.15.1/ko/tools/file-document/filewritetool", + "v1.15.1/ko/tools/file-document/pdfsearchtool", + "v1.15.1/ko/tools/file-document/docxsearchtool", + "v1.15.1/ko/tools/file-document/mdxsearchtool", + "v1.15.1/ko/tools/file-document/xmlsearchtool", + "v1.15.1/ko/tools/file-document/txtsearchtool", + "v1.15.1/ko/tools/file-document/jsonsearchtool", + "v1.15.1/ko/tools/file-document/csvsearchtool", + "v1.15.1/ko/tools/file-document/directorysearchtool", + "v1.15.1/ko/tools/file-document/directoryreadtool", + "v1.15.1/ko/tools/file-document/ocrtool", + "v1.15.1/ko/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "웹 스크래핑 & 브라우징", + "icon": "globe", + "pages": [ + "v1.15.1/ko/tools/web-scraping/overview", + "v1.15.1/ko/tools/web-scraping/scrapewebsitetool", + "v1.15.1/ko/tools/web-scraping/scrapeelementfromwebsitetool", + "v1.15.1/ko/tools/web-scraping/scrapflyscrapetool", + "v1.15.1/ko/tools/web-scraping/seleniumscrapingtool", + "v1.15.1/ko/tools/web-scraping/scrapegraphscrapetool", + "v1.15.1/ko/tools/web-scraping/spidertool", + "v1.15.1/ko/tools/web-scraping/browserbaseloadtool", + "v1.15.1/ko/tools/web-scraping/hyperbrowserloadtool", + "v1.15.1/ko/tools/web-scraping/stagehandtool", + "v1.15.1/ko/tools/web-scraping/firecrawlcrawlwebsitetool", + "v1.15.1/ko/tools/web-scraping/firecrawlscrapewebsitetool", + "v1.15.1/ko/tools/web-scraping/oxylabsscraperstool", + "v1.15.1/ko/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "검색 및 연구", + "icon": "magnifying-glass", + "pages": [ + "v1.15.1/ko/tools/search-research/overview", + "v1.15.1/ko/tools/search-research/serperdevtool", + "v1.15.1/ko/tools/search-research/bravesearchtool", + "v1.15.1/ko/tools/search-research/exasearchtool", + "v1.15.1/ko/tools/search-research/linkupsearchtool", + "v1.15.1/ko/tools/search-research/githubsearchtool", + "v1.15.1/ko/tools/search-research/websitesearchtool", + "v1.15.1/ko/tools/search-research/codedocssearchtool", + "v1.15.1/ko/tools/search-research/youtubechannelsearchtool", + "v1.15.1/ko/tools/search-research/youtubevideosearchtool", + "v1.15.1/ko/tools/search-research/tavilysearchtool", + "v1.15.1/ko/tools/search-research/tavilyextractortool", + "v1.15.1/ko/tools/search-research/tavilyresearchtool", + "v1.15.1/ko/tools/search-research/arxivpapertool", + "v1.15.1/ko/tools/search-research/serpapi-googlesearchtool", + "v1.15.1/ko/tools/search-research/serpapi-googleshoppingtool", + "v1.15.1/ko/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "데이터베이스 & 데이터", + "icon": "database", + "pages": [ + "v1.15.1/ko/tools/database-data/overview", + "v1.15.1/ko/tools/database-data/mysqltool", + "v1.15.1/ko/tools/database-data/pgsearchtool", + "v1.15.1/ko/tools/database-data/snowflakesearchtool", + "v1.15.1/ko/tools/database-data/nl2sqltool", + "v1.15.1/ko/tools/database-data/qdrantvectorsearchtool", + "v1.15.1/ko/tools/database-data/weaviatevectorsearchtool", + "v1.15.1/ko/tools/database-data/mongodbvectorsearchtool", + "v1.15.1/ko/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "인공지능 & 머신러닝", + "icon": "brain", + "pages": [ + "v1.15.1/ko/tools/ai-ml/overview", + "v1.15.1/ko/tools/ai-ml/dalletool", + "v1.15.1/ko/tools/ai-ml/visiontool", + "v1.15.1/ko/tools/ai-ml/aimindtool", + "v1.15.1/ko/tools/ai-ml/llamaindextool", + "v1.15.1/ko/tools/ai-ml/langchaintool", + "v1.15.1/ko/tools/ai-ml/ragtool", + "v1.15.1/ko/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "클라우드 & 스토리지", + "icon": "cloud", + "pages": [ + "v1.15.1/ko/tools/cloud-storage/overview", + "v1.15.1/ko/tools/cloud-storage/s3readertool", + "v1.15.1/ko/tools/cloud-storage/s3writertool", + "v1.15.1/ko/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "v1.15.1/ko/tools/integration/overview", + "v1.15.1/ko/tools/integration/bedrockinvokeagenttool", + "v1.15.1/ko/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "자동화", + "icon": "bolt", + "pages": [ + "v1.15.1/ko/tools/automation/overview", + "v1.15.1/ko/tools/automation/apifyactorstool", + "v1.15.1/ko/tools/automation/composiotool", + "v1.15.1/ko/tools/automation/multiontool", + "v1.15.1/ko/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "v1.15.1/ko/observability/tracing", + "v1.15.1/ko/observability/overview", + "v1.15.1/ko/observability/arize-phoenix", + "v1.15.1/ko/observability/braintrust", + "v1.15.1/ko/observability/datadog", + "v1.15.1/ko/observability/galileo", + "v1.15.1/ko/observability/langdb", + "v1.15.1/ko/observability/langfuse", + "v1.15.1/ko/observability/langtrace", + "v1.15.1/ko/observability/maxim", + "v1.15.1/ko/observability/mlflow", + "v1.15.1/ko/observability/neatlogs", + "v1.15.1/ko/observability/openlit", + "v1.15.1/ko/observability/opik", + "v1.15.1/ko/observability/patronus-evaluation", + "v1.15.1/ko/observability/portkey", + "v1.15.1/ko/observability/weave" + ] + }, + { + "group": "학습", + "pages": [ + "v1.15.1/ko/learn/overview", + "v1.15.1/ko/learn/llm-selection-guide", + "v1.15.1/ko/learn/conditional-tasks", + "v1.15.1/ko/learn/coding-agents", + "v1.15.1/ko/learn/create-custom-tools", + "v1.15.1/ko/learn/custom-llm", + "v1.15.1/ko/learn/custom-manager-agent", + "v1.15.1/ko/learn/customizing-agents", + "v1.15.1/ko/learn/dalle-image-generation", + "v1.15.1/ko/learn/force-tool-output-as-result", + "v1.15.1/ko/learn/hierarchical-process", + "v1.15.1/ko/learn/human-input-on-execution", + "v1.15.1/ko/learn/human-in-the-loop", + "v1.15.1/ko/learn/human-feedback-in-flows", + "v1.15.1/ko/learn/kickoff-async", + "v1.15.1/ko/learn/kickoff-for-each", + "v1.15.1/ko/learn/llm-connections", + "v1.15.1/ko/learn/multimodal-agents", + "v1.15.1/ko/learn/replay-tasks-from-latest-crew-kickoff", + "v1.15.1/ko/learn/sequential-process", + "v1.15.1/ko/learn/using-annotations", + "v1.15.1/ko/learn/execution-hooks", + "v1.15.1/ko/learn/llm-hooks", + "v1.15.1/ko/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "v1.15.1/ko/telemetry" + ] + } + ] + }, + { + "tab": "엔터프라이즈", + "icon": "briefcase", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "v1.15.1/ko/enterprise/introduction" + ] + }, + { + "group": "빌드", + "pages": [ + "v1.15.1/ko/enterprise/features/automations", + { + "group": "Crew Studio", + "icon": "pencil", + "pages": [ + "v1.15.1/ko/enterprise/features/crew-studio", + "v1.15.1/ko/enterprise/features/merged-step-card" + ] + }, + "v1.15.1/ko/enterprise/features/marketplace", + "v1.15.1/ko/enterprise/features/agent-repositories", + "v1.15.1/ko/enterprise/features/tools-and-integrations", + "v1.15.1/ko/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "운영", + "pages": [ + "v1.15.1/ko/enterprise/features/traces", + "v1.15.1/ko/enterprise/features/webhook-streaming", + "v1.15.1/ko/enterprise/features/hallucination-guardrail", + "v1.15.1/ko/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "관리", + "pages": [ + "v1.15.1/ko/enterprise/features/rbac", + { + "group": "Secrets Manager", + "icon": "lock", + "pages": [ + "v1.15.1/ko/enterprise/features/secrets-manager/overview", + "v1.15.1/ko/enterprise/features/secrets-manager/usage", + { + "group": "AWS", + "icon": "aws", + "pages": [ + "v1.15.1/ko/enterprise/features/secrets-manager/aws", + "v1.15.1/ko/enterprise/features/secrets-manager/aws-workload-identity" + ] + }, + { + "group": "GCP", + "icon": "google", + "pages": [ + "v1.15.1/ko/enterprise/features/secrets-manager/gcp", + "v1.15.1/ko/enterprise/features/secrets-manager/gcp-workload-identity" + ] + }, + { + "group": "Azure", + "icon": "microsoft", + "pages": [ + "v1.15.1/ko/enterprise/features/secrets-manager/azure", + "v1.15.1/ko/enterprise/features/secrets-manager/azure-workload-identity" + ] + }, + "v1.15.1/ko/enterprise/features/secrets-manager/verify-rotation" + ] + } + ] + }, + { + "group": "통합 문서", + "pages": [ + "v1.15.1/ko/enterprise/integrations/asana", + "v1.15.1/ko/enterprise/integrations/box", + "v1.15.1/ko/enterprise/integrations/clickup", + "v1.15.1/ko/enterprise/integrations/databricks", + "v1.15.1/ko/enterprise/integrations/github", + "v1.15.1/ko/enterprise/integrations/gmail", + "v1.15.1/ko/enterprise/integrations/google_calendar", + "v1.15.1/ko/enterprise/integrations/google_contacts", + "v1.15.1/ko/enterprise/integrations/google_docs", + "v1.15.1/ko/enterprise/integrations/google_drive", + "v1.15.1/ko/enterprise/integrations/google_sheets", + "v1.15.1/ko/enterprise/integrations/google_slides", + "v1.15.1/ko/enterprise/integrations/hubspot", + "v1.15.1/ko/enterprise/integrations/jira", + "v1.15.1/ko/enterprise/integrations/linear", + "v1.15.1/ko/enterprise/integrations/microsoft_excel", + "v1.15.1/ko/enterprise/integrations/microsoft_onedrive", + "v1.15.1/ko/enterprise/integrations/microsoft_outlook", + "v1.15.1/ko/enterprise/integrations/microsoft_sharepoint", + "v1.15.1/ko/enterprise/integrations/microsoft_teams", + "v1.15.1/ko/enterprise/integrations/microsoft_word", + "v1.15.1/ko/enterprise/integrations/notion", + "v1.15.1/ko/enterprise/integrations/salesforce", + "v1.15.1/ko/enterprise/integrations/shopify", + "v1.15.1/ko/enterprise/integrations/slack", + "v1.15.1/ko/enterprise/integrations/snowflake", + "v1.15.1/ko/enterprise/integrations/stripe", + "v1.15.1/ko/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "v1.15.1/ko/enterprise/guides/build-crew", + "v1.15.1/ko/enterprise/guides/prepare-for-deployment", + "v1.15.1/ko/enterprise/guides/deploy-to-amp", + "v1.15.1/ko/enterprise/guides/monorepo-deployments", + "v1.15.1/ko/enterprise/guides/private-package-registry", + "v1.15.1/ko/enterprise/guides/kickoff-crew", + "v1.15.1/ko/enterprise/guides/training-crews", + "v1.15.1/ko/enterprise/guides/update-crew", + "v1.15.1/ko/enterprise/guides/enable-crew-studio", + "v1.15.1/ko/enterprise/guides/capture_telemetry_logs", + "v1.15.1/ko/enterprise/guides/datadog", + "v1.15.1/ko/enterprise/guides/azure-openai-setup", + "v1.15.1/ko/enterprise/guides/tool-repository", + "v1.15.1/ko/enterprise/guides/custom-mcp-server", + "v1.15.1/ko/enterprise/guides/react-component-export", + "v1.15.1/ko/enterprise/guides/team-management", + "v1.15.1/ko/enterprise/guides/human-in-the-loop", + "v1.15.1/ko/enterprise/guides/webhook-automation" + ] + }, + { + "group": "트리거", + "pages": [ + "v1.15.1/ko/enterprise/guides/automation-triggers", + "v1.15.1/ko/enterprise/guides/gmail-trigger", + "v1.15.1/ko/enterprise/guides/google-calendar-trigger", + "v1.15.1/ko/enterprise/guides/google-drive-trigger", + "v1.15.1/ko/enterprise/guides/outlook-trigger", + "v1.15.1/ko/enterprise/guides/onedrive-trigger", + "v1.15.1/ko/enterprise/guides/microsoft-teams-trigger", + "v1.15.1/ko/enterprise/guides/slack-trigger", + "v1.15.1/ko/enterprise/guides/hubspot-trigger", + "v1.15.1/ko/enterprise/guides/salesforce-trigger", + "v1.15.1/ko/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "학습 자원", + "pages": [ + "v1.15.1/ko/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API 레퍼런스", + "icon": "magnifying-glass", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "v1.15.1/ko/api-reference/introduction", + "v1.15.1/ko/api-reference/inputs", + "v1.15.1/ko/api-reference/kickoff", + "v1.15.1/ko/api-reference/resume", + "v1.15.1/ko/api-reference/status" + ] + } + ] + }, + { + "tab": "예시", + "icon": "code", + "groups": [ + { + "group": "예시", + "pages": [ + "v1.15.1/ko/examples/example", + "v1.15.1/ko/examples/cookbooks" + ] + } + ] + }, + { + "tab": "변경 로그", + "icon": "clock", + "groups": [ + { + "group": "릴리스 노트", + "pages": [ + "v1.15.1/ko/changelog" + ] + } + ] + } + ], + "tag": "Latest" + }, + { + "version": "v1.15.0", "tabs": [ { "tab": "홈", @@ -18100,6 +19656,7 @@ "v1.15.0/ko/enterprise/guides/update-crew", "v1.15.0/ko/enterprise/guides/enable-crew-studio", "v1.15.0/ko/enterprise/guides/capture_telemetry_logs", + "v1.15.0/ko/enterprise/guides/datadog", "v1.15.0/ko/enterprise/guides/azure-openai-setup", "v1.15.0/ko/enterprise/guides/tool-repository", "v1.15.0/ko/enterprise/guides/custom-mcp-server", @@ -18174,8 +19731,7 @@ } ] } - ], - "tag": "Latest" + ] }, { "version": "v1.14.7", @@ -26246,8 +27802,527 @@ "tag": "Edge" }, { - "version": "v1.15.0", + "version": "v1.15.1", "default": true, + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "v1.15.1/ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "v1.15.1/ar/introduction", + "v1.15.1/ar/guides/coding-tools/build-with-ai", + "v1.15.1/ar/skills", + "v1.15.1/ar/installation", + "v1.15.1/ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "v1.15.1/ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "v1.15.1/ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "v1.15.1/ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "v1.15.1/ar/guides/flows/first-flow", + "v1.15.1/ar/guides/flows/mastering-flow-state", + "v1.15.1/ar/guides/flows/conversational-flows", + "v1.15.1/ar/guides/flows/inputs-id-deprecation" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "v1.15.1/ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "v1.15.1/ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "v1.15.1/ar/guides/advanced/customizing-prompts", + "v1.15.1/ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "v1.15.1/ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "v1.15.1/ar/concepts/agents", + "v1.15.1/ar/concepts/agent-capabilities", + "v1.15.1/ar/concepts/tasks", + "v1.15.1/ar/concepts/crews", + "v1.15.1/ar/concepts/flows", + "v1.15.1/ar/concepts/production-architecture", + "v1.15.1/ar/concepts/knowledge", + "v1.15.1/ar/concepts/skills", + "v1.15.1/ar/concepts/llms", + "v1.15.1/ar/concepts/files", + "v1.15.1/ar/concepts/processes", + "v1.15.1/ar/concepts/collaboration", + "v1.15.1/ar/concepts/training", + "v1.15.1/ar/concepts/memory", + "v1.15.1/ar/concepts/reasoning", + "v1.15.1/ar/concepts/planning", + "v1.15.1/ar/concepts/testing", + "v1.15.1/ar/concepts/cli", + "v1.15.1/ar/concepts/tools", + "v1.15.1/ar/concepts/event-listener", + "v1.15.1/ar/concepts/checkpointing" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "v1.15.1/ar/mcp/overview", + "v1.15.1/ar/mcp/dsl-integration", + "v1.15.1/ar/mcp/stdio", + "v1.15.1/ar/mcp/sse", + "v1.15.1/ar/mcp/streamable-http", + "v1.15.1/ar/mcp/multiple-servers", + "v1.15.1/ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "v1.15.1/ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "v1.15.1/ar/tools/file-document/overview", + "v1.15.1/ar/tools/file-document/filereadtool", + "v1.15.1/ar/tools/file-document/filewritetool", + "v1.15.1/ar/tools/file-document/pdfsearchtool", + "v1.15.1/ar/tools/file-document/docxsearchtool", + "v1.15.1/ar/tools/file-document/mdxsearchtool", + "v1.15.1/ar/tools/file-document/xmlsearchtool", + "v1.15.1/ar/tools/file-document/txtsearchtool", + "v1.15.1/ar/tools/file-document/jsonsearchtool", + "v1.15.1/ar/tools/file-document/csvsearchtool", + "v1.15.1/ar/tools/file-document/directorysearchtool", + "v1.15.1/ar/tools/file-document/directoryreadtool", + "v1.15.1/ar/tools/file-document/ocrtool", + "v1.15.1/ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "v1.15.1/ar/tools/web-scraping/overview", + "v1.15.1/ar/tools/web-scraping/scrapewebsitetool", + "v1.15.1/ar/tools/web-scraping/scrapeelementfromwebsitetool", + "v1.15.1/ar/tools/web-scraping/scrapflyscrapetool", + "v1.15.1/ar/tools/web-scraping/seleniumscrapingtool", + "v1.15.1/ar/tools/web-scraping/scrapegraphscrapetool", + "v1.15.1/ar/tools/web-scraping/spidertool", + "v1.15.1/ar/tools/web-scraping/browserbaseloadtool", + "v1.15.1/ar/tools/web-scraping/hyperbrowserloadtool", + "v1.15.1/ar/tools/web-scraping/stagehandtool", + "v1.15.1/ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "v1.15.1/ar/tools/web-scraping/firecrawlscrapewebsitetool", + "v1.15.1/ar/tools/web-scraping/oxylabsscraperstool", + "v1.15.1/ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "v1.15.1/ar/tools/search-research/overview", + "v1.15.1/ar/tools/search-research/serperdevtool", + "v1.15.1/ar/tools/search-research/bravesearchtool", + "v1.15.1/ar/tools/search-research/exasearchtool", + "v1.15.1/ar/tools/search-research/linkupsearchtool", + "v1.15.1/ar/tools/search-research/githubsearchtool", + "v1.15.1/ar/tools/search-research/websitesearchtool", + "v1.15.1/ar/tools/search-research/codedocssearchtool", + "v1.15.1/ar/tools/search-research/youtubechannelsearchtool", + "v1.15.1/ar/tools/search-research/youtubevideosearchtool", + "v1.15.1/ar/tools/search-research/tavilysearchtool", + "v1.15.1/ar/tools/search-research/tavilyextractortool", + "v1.15.1/ar/tools/search-research/tavilyresearchtool", + "v1.15.1/ar/tools/search-research/arxivpapertool", + "v1.15.1/ar/tools/search-research/serpapi-googlesearchtool", + "v1.15.1/ar/tools/search-research/serpapi-googleshoppingtool", + "v1.15.1/ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "v1.15.1/ar/tools/database-data/overview", + "v1.15.1/ar/tools/database-data/mysqltool", + "v1.15.1/ar/tools/database-data/pgsearchtool", + "v1.15.1/ar/tools/database-data/snowflakesearchtool", + "v1.15.1/ar/tools/database-data/nl2sqltool", + "v1.15.1/ar/tools/database-data/qdrantvectorsearchtool", + "v1.15.1/ar/tools/database-data/weaviatevectorsearchtool", + "v1.15.1/ar/tools/database-data/mongodbvectorsearchtool", + "v1.15.1/ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "v1.15.1/ar/tools/ai-ml/overview", + "v1.15.1/ar/tools/ai-ml/dalletool", + "v1.15.1/ar/tools/ai-ml/visiontool", + "v1.15.1/ar/tools/ai-ml/aimindtool", + "v1.15.1/ar/tools/ai-ml/llamaindextool", + "v1.15.1/ar/tools/ai-ml/langchaintool", + "v1.15.1/ar/tools/ai-ml/ragtool", + "v1.15.1/ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "v1.15.1/ar/tools/cloud-storage/overview", + "v1.15.1/ar/tools/cloud-storage/s3readertool", + "v1.15.1/ar/tools/cloud-storage/s3writertool", + "v1.15.1/ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "v1.15.1/ar/tools/integration/overview", + "v1.15.1/ar/tools/integration/bedrockinvokeagenttool", + "v1.15.1/ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "v1.15.1/ar/tools/automation/overview", + "v1.15.1/ar/tools/automation/apifyactorstool", + "v1.15.1/ar/tools/automation/composiotool", + "v1.15.1/ar/tools/automation/multiontool", + "v1.15.1/ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "v1.15.1/ar/observability/tracing", + "v1.15.1/ar/observability/overview", + "v1.15.1/ar/observability/arize-phoenix", + "v1.15.1/ar/observability/braintrust", + "v1.15.1/ar/observability/datadog", + "v1.15.1/ar/observability/galileo", + "v1.15.1/ar/observability/langdb", + "v1.15.1/ar/observability/langfuse", + "v1.15.1/ar/observability/langtrace", + "v1.15.1/ar/observability/maxim", + "v1.15.1/ar/observability/mlflow", + "v1.15.1/ar/observability/neatlogs", + "v1.15.1/ar/observability/openlit", + "v1.15.1/ar/observability/opik", + "v1.15.1/ar/observability/patronus-evaluation", + "v1.15.1/ar/observability/portkey", + "v1.15.1/ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "v1.15.1/ar/learn/overview", + "v1.15.1/ar/learn/llm-selection-guide", + "v1.15.1/ar/learn/conditional-tasks", + "v1.15.1/ar/learn/coding-agents", + "v1.15.1/ar/learn/create-custom-tools", + "v1.15.1/ar/learn/custom-llm", + "v1.15.1/ar/learn/custom-manager-agent", + "v1.15.1/ar/learn/customizing-agents", + "v1.15.1/ar/learn/dalle-image-generation", + "v1.15.1/ar/learn/force-tool-output-as-result", + "v1.15.1/ar/learn/hierarchical-process", + "v1.15.1/ar/learn/human-input-on-execution", + "v1.15.1/ar/learn/human-in-the-loop", + "v1.15.1/ar/learn/human-feedback-in-flows", + "v1.15.1/ar/learn/kickoff-async", + "v1.15.1/ar/learn/kickoff-for-each", + "v1.15.1/ar/learn/llm-connections", + "v1.15.1/ar/learn/multimodal-agents", + "v1.15.1/ar/learn/replay-tasks-from-latest-crew-kickoff", + "v1.15.1/ar/learn/sequential-process", + "v1.15.1/ar/learn/using-annotations", + "v1.15.1/ar/learn/execution-hooks", + "v1.15.1/ar/learn/llm-hooks", + "v1.15.1/ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "v1.15.1/ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "v1.15.1/ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "v1.15.1/ar/enterprise/features/automations", + { + "group": "استوديو الطاقم", + "icon": "pencil", + "pages": [ + "v1.15.1/ar/enterprise/features/crew-studio", + "v1.15.1/ar/enterprise/features/merged-step-card" + ] + }, + "v1.15.1/ar/enterprise/features/marketplace", + "v1.15.1/ar/enterprise/features/agent-repositories", + "v1.15.1/ar/enterprise/features/tools-and-integrations", + "v1.15.1/ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "v1.15.1/ar/enterprise/features/traces", + "v1.15.1/ar/enterprise/features/webhook-streaming", + "v1.15.1/ar/enterprise/features/hallucination-guardrail", + "v1.15.1/ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "v1.15.1/ar/enterprise/features/rbac", + { + "group": "Secrets Manager", + "icon": "lock", + "pages": [ + "v1.15.1/ar/enterprise/features/secrets-manager/overview", + "v1.15.1/ar/enterprise/features/secrets-manager/usage", + { + "group": "AWS", + "icon": "aws", + "pages": [ + "v1.15.1/ar/enterprise/features/secrets-manager/aws", + "v1.15.1/ar/enterprise/features/secrets-manager/aws-workload-identity" + ] + }, + { + "group": "GCP", + "icon": "google", + "pages": [ + "v1.15.1/ar/enterprise/features/secrets-manager/gcp", + "v1.15.1/ar/enterprise/features/secrets-manager/gcp-workload-identity" + ] + }, + { + "group": "Azure", + "icon": "microsoft", + "pages": [ + "v1.15.1/ar/enterprise/features/secrets-manager/azure", + "v1.15.1/ar/enterprise/features/secrets-manager/azure-workload-identity" + ] + }, + "v1.15.1/ar/enterprise/features/secrets-manager/verify-rotation" + ] + } + ] + }, + { + "group": "التكاملات", + "pages": [ + "v1.15.1/ar/enterprise/integrations/asana", + "v1.15.1/ar/enterprise/integrations/box", + "v1.15.1/ar/enterprise/integrations/clickup", + "v1.15.1/ar/enterprise/integrations/databricks", + "v1.15.1/ar/enterprise/integrations/github", + "v1.15.1/ar/enterprise/integrations/gmail", + "v1.15.1/ar/enterprise/integrations/google_calendar", + "v1.15.1/ar/enterprise/integrations/google_contacts", + "v1.15.1/ar/enterprise/integrations/google_docs", + "v1.15.1/ar/enterprise/integrations/google_drive", + "v1.15.1/ar/enterprise/integrations/google_sheets", + "v1.15.1/ar/enterprise/integrations/google_slides", + "v1.15.1/ar/enterprise/integrations/hubspot", + "v1.15.1/ar/enterprise/integrations/jira", + "v1.15.1/ar/enterprise/integrations/linear", + "v1.15.1/ar/enterprise/integrations/microsoft_excel", + "v1.15.1/ar/enterprise/integrations/microsoft_onedrive", + "v1.15.1/ar/enterprise/integrations/microsoft_outlook", + "v1.15.1/ar/enterprise/integrations/microsoft_sharepoint", + "v1.15.1/ar/enterprise/integrations/microsoft_teams", + "v1.15.1/ar/enterprise/integrations/microsoft_word", + "v1.15.1/ar/enterprise/integrations/notion", + "v1.15.1/ar/enterprise/integrations/salesforce", + "v1.15.1/ar/enterprise/integrations/shopify", + "v1.15.1/ar/enterprise/integrations/slack", + "v1.15.1/ar/enterprise/integrations/snowflake", + "v1.15.1/ar/enterprise/integrations/stripe", + "v1.15.1/ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "v1.15.1/ar/enterprise/guides/build-crew", + "v1.15.1/ar/enterprise/guides/prepare-for-deployment", + "v1.15.1/ar/enterprise/guides/deploy-to-amp", + "v1.15.1/ar/enterprise/guides/monorepo-deployments", + "v1.15.1/ar/enterprise/guides/private-package-registry", + "v1.15.1/ar/enterprise/guides/kickoff-crew", + "v1.15.1/ar/enterprise/guides/training-crews", + "v1.15.1/ar/enterprise/guides/update-crew", + "v1.15.1/ar/enterprise/guides/enable-crew-studio", + "v1.15.1/ar/enterprise/guides/capture_telemetry_logs", + "v1.15.1/ar/enterprise/guides/datadog", + "v1.15.1/ar/enterprise/guides/azure-openai-setup", + "v1.15.1/ar/enterprise/guides/tool-repository", + "v1.15.1/ar/enterprise/guides/custom-mcp-server", + "v1.15.1/ar/enterprise/guides/react-component-export", + "v1.15.1/ar/enterprise/guides/team-management", + "v1.15.1/ar/enterprise/guides/human-in-the-loop", + "v1.15.1/ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "v1.15.1/ar/enterprise/guides/automation-triggers", + "v1.15.1/ar/enterprise/guides/gmail-trigger", + "v1.15.1/ar/enterprise/guides/google-calendar-trigger", + "v1.15.1/ar/enterprise/guides/google-drive-trigger", + "v1.15.1/ar/enterprise/guides/outlook-trigger", + "v1.15.1/ar/enterprise/guides/onedrive-trigger", + "v1.15.1/ar/enterprise/guides/microsoft-teams-trigger", + "v1.15.1/ar/enterprise/guides/slack-trigger", + "v1.15.1/ar/enterprise/guides/hubspot-trigger", + "v1.15.1/ar/enterprise/guides/salesforce-trigger", + "v1.15.1/ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "v1.15.1/ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "v1.15.1/ar/api-reference/introduction", + "v1.15.1/ar/api-reference/inputs", + "v1.15.1/ar/api-reference/kickoff", + "v1.15.1/ar/api-reference/resume", + "v1.15.1/ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "v1.15.1/ar/examples/example", + "v1.15.1/ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "v1.15.1/ar/changelog" + ] + } + ] + } + ], + "tag": "Latest" + }, + { + "version": "v1.15.0", "tabs": [ { "tab": "الرئيسية", @@ -26687,6 +28762,7 @@ "v1.15.0/ar/enterprise/guides/update-crew", "v1.15.0/ar/enterprise/guides/enable-crew-studio", "v1.15.0/ar/enterprise/guides/capture_telemetry_logs", + "v1.15.0/ar/enterprise/guides/datadog", "v1.15.0/ar/enterprise/guides/azure-openai-setup", "v1.15.0/ar/enterprise/guides/tool-repository", "v1.15.0/ar/enterprise/guides/custom-mcp-server", @@ -26761,8 +28837,7 @@ } ] } - ], - "tag": "Latest" + ] }, { "version": "v1.14.7", @@ -32537,110 +34612,110 @@ "redirects": [ { "source": "/api-reference", - "destination": "/v1.15.0/en/api-reference/introduction" + "destination": "/v1.15.1/en/api-reference/introduction" }, { "source": "/introduction", - "destination": "/v1.15.0/en/introduction" + "destination": "/v1.15.1/en/introduction" }, { "source": "/skills", - "destination": "/v1.15.0/en/skills" + "destination": "/v1.15.1/en/skills" }, { "source": "/installation", - "destination": "/v1.15.0/en/installation" + "destination": "/v1.15.1/en/installation" }, { "source": "/quickstart", - "destination": "/v1.15.0/en/quickstart" + "destination": "/v1.15.1/en/quickstart" }, { "source": "/changelog", - "destination": "/v1.15.0/en/changelog" + "destination": "/v1.15.1/en/changelog" }, { "source": "/telemetry", - "destination": "/v1.15.0/en/telemetry" + "destination": "/v1.15.1/en/telemetry" }, { "source": "/concepts/:path*", - "destination": "/v1.15.0/en/concepts/:path*" + "destination": "/v1.15.1/en/concepts/:path*" }, { "source": "/guides/:path*", - "destination": "/v1.15.0/en/guides/:path*" + "destination": "/v1.15.1/en/guides/:path*" }, { "source": "/tools/:path*", - "destination": "/v1.15.0/en/tools/:path*" + "destination": "/v1.15.1/en/tools/:path*" }, { "source": "/learn/:path*", - "destination": "/v1.15.0/en/learn/:path*" + "destination": "/v1.15.1/en/learn/:path*" }, { "source": "/mcp/:path*", - "destination": "/v1.15.0/en/mcp/:path*" + "destination": "/v1.15.1/en/mcp/:path*" }, { "source": "/observability/:path*", - "destination": "/v1.15.0/en/observability/:path*" + "destination": "/v1.15.1/en/observability/:path*" }, { "source": "/enterprise/:path*", - "destination": "/v1.15.0/en/enterprise/:path*" + "destination": "/v1.15.1/en/enterprise/:path*" }, { "source": "/en/enterprise/guides/deploy-crew", - "destination": "/v1.15.0/en/enterprise/guides/deploy-to-amp" + "destination": "/v1.15.1/en/enterprise/guides/deploy-to-amp" }, { "source": "/ko/enterprise/guides/deploy-crew", - "destination": "/v1.15.0/ko/enterprise/guides/deploy-to-amp" + "destination": "/v1.15.1/ko/enterprise/guides/deploy-to-amp" }, { "source": "/pt-BR/enterprise/guides/deploy-crew", - "destination": "/v1.15.0/pt-BR/enterprise/guides/deploy-to-amp" + "destination": "/v1.15.1/pt-BR/enterprise/guides/deploy-to-amp" }, { "source": "/api-reference/:path*", - "destination": "/v1.15.0/en/api-reference/:path*" + "destination": "/v1.15.1/en/api-reference/:path*" }, { "source": "/en/api-reference", - "destination": "/v1.15.0/en/api-reference/introduction" + "destination": "/v1.15.1/en/api-reference/introduction" }, { "source": "/pt-BR/api-reference", - "destination": "/v1.15.0/pt-BR/api-reference/introduction" + "destination": "/v1.15.1/pt-BR/api-reference/introduction" }, { "source": "/ko/api-reference", - "destination": "/v1.15.0/ko/api-reference/introduction" + "destination": "/v1.15.1/ko/api-reference/introduction" }, { "source": "/examples/:path*", - "destination": "/v1.15.0/en/examples/:path*" + "destination": "/v1.15.1/en/examples/:path*" }, { "source": "/en/:slug*", - "destination": "/v1.15.0/en/:slug*", + "destination": "/v1.15.1/en/:slug*", "permanent": false }, { "source": "/pt-BR/:slug*", - "destination": "/v1.15.0/pt-BR/:slug*", + "destination": "/v1.15.1/pt-BR/:slug*", "permanent": false }, { "source": "/ko/:slug*", - "destination": "/v1.15.0/ko/:slug*", + "destination": "/v1.15.1/ko/:slug*", "permanent": false }, { "source": "/ar/:slug*", - "destination": "/v1.15.0/ar/:slug*", + "destination": "/v1.15.1/ar/:slug*", "permanent": false } ], diff --git a/docs/edge/ar/changelog.mdx b/docs/edge/ar/changelog.mdx index 65c16c8cd..3656cacf7 100644 --- a/docs/edge/ar/changelog.mdx +++ b/docs/edge/ar/changelog.mdx @@ -4,6 +4,62 @@ description: "تحديثات المنتج والتحسينات وإصلاحات icon: "clock" mode: "wide" --- + + ## v1.15.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1) + + ## ما الذي تغير + + ### الميزات + - تهيئة مستودعات Git للمشاريع المولدة (#6364) + - طلب تعريفات مشروع CrewAI بشكل صريح (#6358) + - فتح صفحة النشر بعد نشر CLI (#6343) + + ### إصلاحات الأخطاء + - إصلاح حل رابط معرف صفحة النشر (#6365) + - إصلاح عرض قالب الطاقم JSON (#6359) + - إصلاح تثبيت إصدار الطاقم JSON (#6342) + - إصلاح تجاوز إعادة التوجيه SSRF في عمليات السحب (#6331) + + ### الوثائق + - تحسين وضع المصدر المفتوح في README (#6363) + - تحسين دعوة العمل لإعداد وكيل البرمجة (#6344) + - إضافة لقطة وتغيير السجل للإصدار 1.15.1a1 (#6362) + + ## المساهمون + + @joaomdmoura, @lorenzejay, @oalami, @theCyberTech, @vinibrsl + + + + + ## v1.15.1a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1a1) + + ## ما الذي تغير + + ### الميزات + - تتبع بيانات الزر TUI + - يتطلب تعريفات مشروع CrewAI بشكل صريح + - فتح صفحة النشر بعد نشر CLI + + ### إصلاحات الأخطاء + - إصلاح عرض قالب الطاقم بصيغة JSON + - إصلاح تثبيت إصدار الطاقم بصيغة JSON + - إصلاح تجاوز إعادة التوجيه SSRF في عمليات جلب البيانات + + ### الوثائق + - تحسين دعوة إعداد وكيل البرمجة + - لقطة وتغيير السجل للإصدار v1.15.0 + + ## المساهمون + + @joaomdmoura, @lorenzejay, @theCyberTech, @vinibrsl + + + ## v1.15.0 diff --git a/docs/edge/ar/enterprise/guides/datadog.mdx b/docs/edge/ar/enterprise/guides/datadog.mdx index 1a3ee818f..7a5f05b12 100644 --- a/docs/edge/ar/enterprise/guides/datadog.mdx +++ b/docs/edge/ar/enterprise/guides/datadog.mdx @@ -21,12 +21,11 @@ CrewAI supports two log-ingestion paths to Datadog — both are first-class and - The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. Each log event ships as a single billable line with structured attributes — see the [log schema reference](#log-schema-reference) for the full field contract. **Setup:** 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). - 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. - 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + 2. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. @@ -57,10 +56,10 @@ Either path lands the same structured facets in Datadog (`@automation_id`, `@kic ## Log schema reference -This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). +This schema applies to the **Datadog Agent path** — structured stdout JSON logs emitted by every CrewAI worker container. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). -When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. +Every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. ### Why JSON output @@ -79,20 +78,6 @@ When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single J -### Enabling JSON output - -`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. - -```shell -CREWAI_LOG_FORMAT=json -``` - -Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. - - - The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. - - ### Example events A single info-level log inside an active automation kickoff: @@ -135,7 +120,7 @@ An error with a Python exception is collapsed into a single event with the trace } ``` -The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. +Without JSON output, that same error would produce ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. ### Schema v1 fields @@ -237,7 +222,7 @@ Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matche Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. - If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + If nothing appears, confirm the Datadog Agent is tailing container stdout and that the deployment is running a recent enough CrewAI Enterprise build. Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). @@ -280,7 +265,7 @@ The `$service` template variable defaults to `*` and will catch every CrewAI dep | All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | | Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | | Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | -| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments (pre-structured-logs AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | | Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | ## Next steps diff --git a/docs/edge/en/changelog.mdx b/docs/edge/en/changelog.mdx index e8e5193e3..8291887d6 100644 --- a/docs/edge/en/changelog.mdx +++ b/docs/edge/en/changelog.mdx @@ -4,6 +4,62 @@ description: "Product updates, improvements, and bug fixes for CrewAI" icon: "clock" mode: "wide" --- + + ## v1.15.1 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1) + + ## What's Changed + + ### Features + - Initialize Git repositories for generated projects (#6364) + - Require explicit CrewAI project definitions (#6358) + - Open deployment page after CLI deploy (#6343) + + ### Bug Fixes + - Fix deployment page link ID resolution (#6365) + - Fix JSON crew template rendering (#6359) + - Fix JSON crew version pin (#6342) + - Fix SSRF redirect bypass in scraping fetches (#6331) + + ### Documentation + - Improve open source positioning in README (#6363) + - Improve coding agent setup call-to-action (#6344) + - Add snapshot and changelog for version 1.15.1a1 (#6362) + + ## Contributors + + @joaomdmoura, @lorenzejay, @oalami, @theCyberTech, @vinibrsl + + + + + ## v1.15.1a1 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1a1) + + ## What's Changed + + ### Features + - Track TUI button telemetry + - Require explicit CrewAI project definitions + - Open deployment page after CLI deploy + + ### Bug Fixes + - Fix JSON crew template rendering + - Fix JSON crew version pin + - Fix SSRF redirect bypass in scraping fetches + + ### Documentation + - Improve coding agent setup CTA + - Snapshot and changelog for v1.15.0 + + ## Contributors + + @joaomdmoura, @lorenzejay, @theCyberTech, @vinibrsl + + + ## v1.15.0 diff --git a/docs/edge/en/enterprise/features/agent-control-plane/overview.mdx b/docs/edge/en/enterprise/features/agent-control-plane/overview.mdx index 1e3d4de8b..d4a03e02f 100644 --- a/docs/edge/en/enterprise/features/agent-control-plane/overview.mdx +++ b/docs/edge/en/enterprise/features/agent-control-plane/overview.mdx @@ -20,7 +20,7 @@ The **Agent Control Plane** (ACP) is the operations hub for everything you have - Monitor the **health** of every live automation (crew or flow), with `Critical` / `Warning` / `Healthy` breakdowns and execution counts. - Track **LLM consumption** — tokens and cost — per automation, per provider, and per model, with a delta vs the previous period. - Drill into any single automation or model provider for time-series charts and per-provider breakdowns. -- Apply organization-wide **Rules** (today: PII Redaction) across many automations at once instead of editing each deployment individually. +- Apply organization-wide **Rules** (today: PII Redaction and Cost Limit) across many automations at once instead of editing each deployment individually. ![Agent Control Plane overview](/images/enterprise/acp-overview-automations-sankey.png) @@ -33,7 +33,7 @@ The **Agent Control Plane** (ACP) is the operations hub for everything you have The two tabs answer two different questions: - **Automations** — *"How is my fleet behaving right now, and what is it costing me?"* See [Monitoring](/en/enterprise/features/agent-control-plane/monitoring). -- **Rules** — *"How do I enforce a policy (e.g. PII redaction) across many deployments without re-deploying each one?"* See [Rules](/en/enterprise/features/agent-control-plane/rules). +- **Rules** — *"How do I enforce a policy (e.g. PII redaction or a spend budget) across many deployments without re-deploying each one?"* See [Rules](/en/enterprise/features/agent-control-plane/rules). ## Requirements @@ -42,7 +42,7 @@ The two tabs answer two different questions: - **Enterprise Plan or Ultra Plan** is required to create or edit [Rules](/en/enterprise/features/agent-control-plane/rules). Lower-tier organizations can open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* Monitoring (the Automations tab) is available on all plans where the feature is enabled. + **Enterprise Plan or Ultra Plan** is required to create or edit **PII Redaction** [Rules](/en/enterprise/features/agent-control-plane/rules). Lower-tier organizations can open the Rules tab and view existing rules, but the PII editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* **Cost Limit** rules and Monitoring (the Automations tab) are available on all plans where the feature is enabled. - The **Agent Control Plane** feature must be enabled for your organization. If you don't see it in the sidebar, ask your account owner to request enablement. @@ -56,7 +56,7 @@ The two tabs answer two different questions: Watch fleet health and LLM spend with metric cards, an interactive sankey, per-automation tables, and drill-down side panels for any automation or provider. - Apply organization-wide PII Redaction policies scoped by tools and tags. Changes take effect on the next execution — no re-deploy required. + Apply organization-wide PII Redaction and Cost Limit policies scoped by tools and tags. Changes take effect on the next execution — no re-deploy required. diff --git a/docs/edge/en/enterprise/features/agent-control-plane/rules.mdx b/docs/edge/en/enterprise/features/agent-control-plane/rules.mdx index 755afbcc4..fd7108e3f 100644 --- a/docs/edge/en/enterprise/features/agent-control-plane/rules.mdx +++ b/docs/edge/en/enterprise/features/agent-control-plane/rules.mdx @@ -16,7 +16,7 @@ mode: "wide" ## Overview -Rules let you apply policies — today: **PII Redaction** — across many automations at once, instead of configuring each deployment individually. Open the **Rules** tab in the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview) to manage them. +Rules let you apply policies — today **PII Redaction** and **Cost Limit** — across many automations at once, instead of configuring each deployment individually. Open the **Rules** tab in the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview) to manage them. ![Rules list](/images/enterprise/acp-rules-list.png) @@ -27,26 +27,78 @@ Each rule card shows the name, description, the **scope** the rule applies to (s ## Requirements - **Enterprise Plan or Ultra Plan** is required to create or edit PII Redaction rules. Lower-tier organizations can still open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* — contact your account owner or sales to upgrade. + **Enterprise Plan or Ultra Plan** is required to create or edit **PII Redaction** rules. Lower-tier organizations can still open the Rules tab and view existing rules, but the PII editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* — contact your account owner or sales to upgrade. **Cost Limit** rules are **not** plan-gated and can be created on any plan where the Agent Control Plane is enabled. - The **Agent Control Plane** feature must be enabled for your organization. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements). - The `manage` [RBAC permission](/en/enterprise/features/rbac) on Agent Control Plane is required to create, edit, toggle, or delete rules. The `read` permission is enough to view them. - All rule changes are versioned for auditing. -## Available rule types +## Rule types -| Type | What it does | -|------|---------------| -| **PII Redaction** | Applies PII redaction to executions of every matching automation, using the same entity catalog and custom recognizers documented in [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions). | +Every rule is one of the types below. Open the tab for the policy you want to enforce. + + + +Applies PII redaction to executions of every matching automation, using the same entity catalog and custom recognizers documented in [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions). + + +Creating or editing PII Redaction rules requires an **Enterprise** or **Ultra** plan. On lower tiers the PII editor renders read-only with an "Enterprise" lock pill. + + +**Configuration** — in the **PII Mask Type** table, check each entity type you want covered and choose how to handle it: + +- **Mask** — replaces the match with the entity label (e.g. ``). +- **Redact** — removes the matched text entirely. + +See [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions) for the full entity catalog and how to add organization-level custom recognizers. + + + +Emails the recipients you choose when a matching automation's LLM spend exceeds a budget threshold in the selected period. Available on **all plans** where the Agent Control Plane is enabled — it is not Enterprise-gated. + + +Cost Limit rules are **notify-only**. They never pause, throttle, or stop a run — they only send an email so a human can decide what to do. Adjust the budget or remove the rule if you no longer want the alert. + + +**Configuration** + +| Field | Description | +|-------|-------------| +| **Budget period** | The window spend is measured over: **Daily**, **Weekly**, or **Monthly** (default *Monthly*). Spend resets at the start of each calendar period. | +| **Threshold (USD)** | The dollar amount that triggers an alert. Must be greater than `0`. The alert fires once the automation's spend for the current period exceeds this value. | +| **Recipient emails** | Up to 50 email addresses. Type an address and press **Enter** or comma to add it as a chip; **Backspace** removes the last chip. These do not need to be CrewAI users. | +| **Notify roles** | Optionally select organization [roles](/en/enterprise/features/rbac); the alert is sent to every member of the chosen roles. Roles with no members can't be selected. You must provide at least one recipient — an email or a role. | +| **Re-alert frequency** | How often the alert can re-fire while an automation stays over budget: **Once per period**, **Every hour while over**, **Every 4h while over**, or **Daily while over**. Re-alerts are capped at 24 per period. | + +**How spend is measured and matched** + +- The threshold is evaluated **per automation**, not summed across the whole scope. Each engaged automation has its own running total for the period. +- A rule can match many automations via its conditions (tools/tags), and a single automation can be covered by **multiple** Cost Limit rules at once. Each rule tracks its own budget and alert state independently — they don't merge. +- A background check compares each engaged automation's period-to-date spend against the threshold and sends the email when it's exceeded. Because the check runs periodically, expect a short delay between crossing the threshold and the email arriving. + +**The alert email** + +When an automation goes over budget, recipients get an email summarizing the overage — the automation name, the **current spend**, the **budget threshold**, and how far over it is in both dollars and percent (e.g. `$0.38` current vs a `$0.10` budget = `+277%`). The email reiterates that the run was **not** paused. + + More rule types will be added over time. ## Creating a rule + + - Rule edit side panel with conditions and PII mask type + New Rule side panel configured for PII Redaction with the PII mask type table + + + + New Rule side panel configured for Cost Limit with budget period, threshold, and recipient emails + + + @@ -54,11 +106,11 @@ More rule types will be added over time. - Give the rule a clear name (e.g. *Mask PII (CC)*) and a description explaining when it applies. Both show up on the rule card and in the Engaged Automations modal. + Give the rule a clear name (e.g. *Mask PII (CC)* or *Monthly $100 budget*) and a description explaining when it applies. Both show up on the rule card and in the Engaged Automations modal. - Today only **PII Redaction** is available. + Choose **PII Redaction** or **Cost Limit**. The type determines which configuration section appears below the conditions. The type is fixed once the rule is created — to switch, create a new rule. @@ -70,8 +122,8 @@ More rule types will be added over time. Leaving a picker empty means "no filter on this dimension". Leaving both empty means the rule applies to **every** automation in the organization. - - Check each entity type you want covered and choose **Mask** (replaces with the entity label, e.g. ``) or **Redact** (removes the matched text entirely). See [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions) for the full entity catalog and how to add organization-level custom recognizers. + + The editor shows the configuration for the type you picked — the **PII Mask Type** table for PII Redaction, or the budget fields for Cost Limit. See [Rule types](#rule-types) for what each field does. @@ -91,12 +143,14 @@ This is the fastest way to sanity-check a rule's scope before enabling it — fo ## Org-wide rules vs per-deployment settings -PII Redaction can be configured in two places: +Both PII Redaction and Cost Limit can be configured in two places: org-wide as a Rule on this page, or per-deployment under that deployment's **Settings**. When an enabled org-wide rule's scope matches a deployment, the rule takes precedence over the deployment-owned setting while it's attached. -- **Per-deployment** — under **Settings → PII Protection** on each individual deployment ([guide](/en/enterprise/features/pii-trace-redactions)) -- **Org-wide** — as a Rule on this page +| Policy | Per-deployment setting | What an attached org-wide rule does | +|--------|------------------------|-------------------------------------| +| **PII Redaction** | **Settings → PII Protection** ([guide](/en/enterprise/features/pii-trace-redactions)) | The rule's entity configuration **overrides** the deployment's PII settings for that deployment's executions. | +| **Cost Limit** | **Settings → Cost Alerts** | The deployment's manual cost alert is **paused** and the attached cost rule(s) fire instead. The per-deployment form stays editable as a fallback. | -When an enabled org-wide rule's scope matches a deployment, the rule's entity configuration **overrides** the deployment-owned PII settings for that deployment's executions — the rule becomes the single source of truth while it's attached. Disable or detach the rule (or change its scope so it no longer matches) and the deployment falls back to its own PII Protection settings. +Disable or detach the rule (or change its scope so it no longer matches) and the deployment falls back to its own per-deployment settings. Prefer org-wide rules when you want to enforce a consistent policy across many deployments; reserve per-deployment configuration for one-off exceptions. diff --git a/docs/edge/en/enterprise/guides/datadog.mdx b/docs/edge/en/enterprise/guides/datadog.mdx index 1db2eae88..003519c79 100644 --- a/docs/edge/en/enterprise/guides/datadog.mdx +++ b/docs/edge/en/enterprise/guides/datadog.mdx @@ -17,12 +17,11 @@ CrewAI supports two log-ingestion paths to Datadog — both are first-class and - The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. Each log event ships as a single billable line with structured attributes — see the [log schema reference](#log-schema-reference) for the full field contract. **Setup:** 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). - 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. - 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + 2. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. @@ -53,10 +52,10 @@ Either path lands the same structured facets in Datadog (`@automation_id`, `@kic ## Log schema reference -This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). +This schema applies to the **Datadog Agent path** — structured stdout JSON logs emitted by every CrewAI worker container. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). -When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. +Every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. ### Why JSON output @@ -75,20 +74,6 @@ When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single J -### Enabling JSON output - -`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. - -```shell -CREWAI_LOG_FORMAT=json -``` - -Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. - - - The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. - - ### Example events A single info-level log inside an active automation kickoff: @@ -131,7 +116,7 @@ An error with a Python exception is collapsed into a single event with the trace } ``` -The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. +Without JSON output, that same error would produce ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. ### Schema v1 fields @@ -233,7 +218,7 @@ Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matche Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. - If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + If nothing appears, confirm the Datadog Agent is tailing container stdout and that the deployment is running a recent enough CrewAI Enterprise build. Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). @@ -276,7 +261,7 @@ The `$service` template variable defaults to `*` and will catch every CrewAI dep | All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | | Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | | Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | -| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments (pre-structured-logs AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | | Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | ## Next steps diff --git a/docs/edge/en/installation.mdx b/docs/edge/en/installation.mdx index 66f80d248..381b92c8a 100644 --- a/docs/edge/en/installation.mdx +++ b/docs/edge/en/installation.mdx @@ -5,15 +5,49 @@ icon: wrench mode: "wide" --- -### Watch: Building CrewAI Agents & Flows with Coding Agent Skills +

+
+

+ Coding agent setup +

+

Set up CrewAI in your coding agent

+

+ Copy a ready-to-paste setup prompt for Claude Code, Codex, Cursor, or any coding agent. It installs the official CrewAI skills, checks the CLI, and points the agent at the right docs before it edits code. +

+
-Install our coding agent skills (Claude Code, Codex, ...) to quickly get your coding agents up and running with CrewAI. - - + const button = event.currentTarget; + const resetTimeout = button.dataset.resetTimeout; + if (resetTimeout) { + window.clearTimeout(Number(resetTimeout)); + } + try { + await navigator.clipboard.writeText(prompt); + button.textContent = "Copied"; + } catch { + button.textContent = "Copy failed"; + } finally { + button.dataset.resetTimeout = String(window.setTimeout(() => { + button.textContent = "Copy agent setup prompt"; + delete button.dataset.resetTimeout; + }, 1600)); + } + }} + > + Copy agent setup prompt + + + View coding-agent guide + +
+ + +### Watch: Building CrewAI Agents & Flows with Coding Agent Skills diff --git a/docs/edge/ko/changelog.mdx b/docs/edge/ko/changelog.mdx index 1aae820b2..3bc2a9332 100644 --- a/docs/edge/ko/changelog.mdx +++ b/docs/edge/ko/changelog.mdx @@ -4,6 +4,62 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정" icon: "clock" mode: "wide" --- + + ## v1.15.1 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1) + + ## 변경 사항 + + ### 기능 + - 생성된 프로젝트에 대한 Git 저장소 초기화 (#6364) + - 명시적인 CrewAI 프로젝트 정의 필요 (#6358) + - CLI 배포 후 배포 페이지 열기 (#6343) + + ### 버그 수정 + - 배포 페이지 링크 ID 해상도 수정 (#6365) + - JSON 크루 템플릿 렌더링 수정 (#6359) + - JSON 크루 버전 고정 수정 (#6342) + - 스크래핑 페치에서 SSRF 리디렉션 우회 수정 (#6331) + + ### 문서 + - README에서 오픈 소스 위치 개선 (#6363) + - 코딩 에이전트 설정을 위한 행동 촉구 개선 (#6344) + - 버전 1.15.1a1에 대한 스냅샷 및 변경 로그 추가 (#6362) + + ## 기여자 + + @joaomdmoura, @lorenzejay, @oalami, @theCyberTech, @vinibrsl + + + + + ## v1.15.1a1 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1a1) + + ## 변경 사항 + + ### 기능 + - TUI 버튼 텔레메트리 추적 + - 명시적인 CrewAI 프로젝트 정의 필요 + - CLI 배포 후 배포 페이지 열기 + + ### 버그 수정 + - JSON 크루 템플릿 렌더링 수정 + - JSON 크루 버전 고정 수정 + - 스크래핑 페치에서 SSRF 리다이렉트 우회 수정 + + ### 문서 + - 코딩 에이전트 설정 CTA 개선 + - v1.15.0에 대한 스냅샷 및 변경 로그 + + ## 기여자 + + @joaomdmoura, @lorenzejay, @theCyberTech, @vinibrsl + + + ## v1.15.0 diff --git a/docs/edge/ko/enterprise/guides/datadog.mdx b/docs/edge/ko/enterprise/guides/datadog.mdx index 0d6016bf1..948376875 100644 --- a/docs/edge/ko/enterprise/guides/datadog.mdx +++ b/docs/edge/ko/enterprise/guides/datadog.mdx @@ -21,12 +21,11 @@ CrewAI supports two log-ingestion paths to Datadog — both are first-class and - The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. Each log event ships as a single billable line with structured attributes — see the [log schema reference](#log-schema-reference) for the full field contract. **Setup:** 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). - 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. - 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + 2. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. @@ -57,10 +56,10 @@ Either path lands the same structured facets in Datadog (`@automation_id`, `@kic ## Log schema reference -This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). +This schema applies to the **Datadog Agent path** — structured stdout JSON logs emitted by every CrewAI worker container. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). -When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. +Every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. ### Why JSON output @@ -79,20 +78,6 @@ When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single J -### Enabling JSON output - -`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. - -```shell -CREWAI_LOG_FORMAT=json -``` - -Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. - - - The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. - - ### Example events A single info-level log inside an active automation kickoff: @@ -135,7 +120,7 @@ An error with a Python exception is collapsed into a single event with the trace } ``` -The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. +Without JSON output, that same error would produce ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. ### Schema v1 fields @@ -237,7 +222,7 @@ Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matche Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. - If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + If nothing appears, confirm the Datadog Agent is tailing container stdout and that the deployment is running a recent enough CrewAI Enterprise build. Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). @@ -280,7 +265,7 @@ The `$service` template variable defaults to `*` and will catch every CrewAI dep | All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | | Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | | Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | -| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments (pre-structured-logs AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | | Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | ## Next steps diff --git a/docs/edge/pt-BR/changelog.mdx b/docs/edge/pt-BR/changelog.mdx index 55b56eef7..8935e2841 100644 --- a/docs/edge/pt-BR/changelog.mdx +++ b/docs/edge/pt-BR/changelog.mdx @@ -4,6 +4,62 @@ description: "Atualizações de produto, melhorias e correções do CrewAI" icon: "clock" mode: "wide" --- + + ## v1.15.1 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1) + + ## O Que Mudou + + ### Funcionalidades + - Inicializar repositórios Git para projetos gerados (#6364) + - Exigir definições explícitas de projetos CrewAI (#6358) + - Abrir a página de implantação após o deploy pelo CLI (#6343) + + ### Correções de Bugs + - Corrigir a resolução do ID do link da página de implantação (#6365) + - Corrigir a renderização do template de equipe em JSON (#6359) + - Corrigir o bloqueio da versão da equipe em JSON (#6342) + - Corrigir a bypass de redirecionamento SSRF em fetches de scraping (#6331) + + ### Documentação + - Melhorar o posicionamento de código aberto no README (#6363) + - Melhorar a chamada para ação na configuração do agente de codificação (#6344) + - Adicionar snapshot e changelog para a versão 1.15.1a1 (#6362) + + ## Contribuidores + + @joaomdmoura, @lorenzejay, @oalami, @theCyberTech, @vinibrsl + + + + + ## v1.15.1a1 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1a1) + + ## O que Mudou + + ### Funcionalidades + - Rastrear a telemetria dos botões TUI + - Exigir definições explícitas de projetos CrewAI + - Abrir a página de implantação após o deploy via CLI + + ### Correções de Bugs + - Corrigir a renderização do template de equipe em JSON + - Corrigir o pin de versão da equipe em JSON + - Corrigir a bypass de redirecionamento SSRF em fetches de scraping + + ### Documentação + - Melhorar o CTA de configuração do agente de codificação + - Snapshot e changelog para v1.15.0 + + ## Contribuidores + + @joaomdmoura, @lorenzejay, @theCyberTech, @vinibrsl + + + ## v1.15.0 diff --git a/docs/edge/pt-BR/enterprise/guides/datadog.mdx b/docs/edge/pt-BR/enterprise/guides/datadog.mdx index 391c11eac..2d1c23dab 100644 --- a/docs/edge/pt-BR/enterprise/guides/datadog.mdx +++ b/docs/edge/pt-BR/enterprise/guides/datadog.mdx @@ -21,12 +21,11 @@ CrewAI supports two log-ingestion paths to Datadog — both are first-class and - The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. Each log event ships as a single billable line with structured attributes — see the [log schema reference](#log-schema-reference) for the full field contract. **Setup:** 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). - 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. - 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + 2. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. @@ -57,10 +56,10 @@ Either path lands the same structured facets in Datadog (`@automation_id`, `@kic ## Log schema reference -This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). +This schema applies to the **Datadog Agent path** — structured stdout JSON logs emitted by every CrewAI worker container. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). -When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. +Every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. ### Why JSON output @@ -79,20 +78,6 @@ When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single J -### Enabling JSON output - -`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. - -```shell -CREWAI_LOG_FORMAT=json -``` - -Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. - - - The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. - - ### Example events A single info-level log inside an active automation kickoff: @@ -135,7 +120,7 @@ An error with a Python exception is collapsed into a single event with the trace } ``` -The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. +Without JSON output, that same error would produce ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. ### Schema v1 fields @@ -237,7 +222,7 @@ Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matche Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. - If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + If nothing appears, confirm the Datadog Agent is tailing container stdout and that the deployment is running a recent enough CrewAI Enterprise build. Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). @@ -280,7 +265,7 @@ The `$service` template variable defaults to `*` and will catch every CrewAI dep | All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | | Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | | Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | -| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments (pre-structured-logs AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | | Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | ## Next steps diff --git a/docs/images/enterprise/acp-rules-edit-cost-limit.png b/docs/images/enterprise/acp-rules-edit-cost-limit.png new file mode 100644 index 000000000..89fc144a4 Binary files /dev/null and b/docs/images/enterprise/acp-rules-edit-cost-limit.png differ diff --git a/docs/index.mdx b/docs/index.mdx index ff6466f27..2afb9373a 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -27,9 +27,133 @@ mode: "wide"
- Get started - View changelog - API Reference + + Get started + + + + Coding-agent guide + + + API Reference +
diff --git a/docs/v1.15.1/ar/api-reference/inputs.mdx b/docs/v1.15.1/ar/api-reference/inputs.mdx new file mode 100644 index 000000000..1a6ecce37 --- /dev/null +++ b/docs/v1.15.1/ar/api-reference/inputs.mdx @@ -0,0 +1,8 @@ +--- +title: "GET /inputs" +description: "الحصول على المدخلات المطلوبة لطاقمك" +openapi: "/v1.15.1/enterprise-api.en.yaml GET /inputs" +mode: "wide" +--- + + diff --git a/docs/v1.15.1/ar/api-reference/introduction.mdx b/docs/v1.15.1/ar/api-reference/introduction.mdx new file mode 100644 index 000000000..60f7bb118 --- /dev/null +++ b/docs/v1.15.1/ar/api-reference/introduction.mdx @@ -0,0 +1,135 @@ +--- +title: "مقدمة" +description: "المرجع الكامل لواجهة برمجة تطبيقات CrewAI AMP REST" +icon: "code" +mode: "wide" +--- + +# واجهة برمجة تطبيقات CrewAI AMP + +مرحبًا بك في مرجع واجهة برمجة تطبيقات CrewAI AMP. تتيح لك هذه الواجهة التفاعل برمجيًا مع الأطقم المنشورة، مما يمكّنك من دمجها مع تطبيقاتك وسير عملك وخدماتك. + +## البدء السريع + + + + انتقل إلى صفحة تفاصيل طاقمك في لوحة تحكم CrewAI AMP وانسخ رمز Bearer من علامة تبويب الحالة. + + + + استخدم نقطة النهاية `GET /inputs` لمعرفة المعاملات التي يتوقعها طاقمك. + + + + استدعِ `POST /kickoff` مع مدخلاتك لبدء تنفيذ الطاقم واستلام + `kickoff_id`. + + + + استخدم `GET /status/{kickoff_id}` للتحقق من حالة التنفيذ واسترجاع النتائج. + + + +## المصادقة + +تتطلب جميع طلبات API المصادقة باستخدام رمز Bearer. أدرج رمزك في ترويسة `Authorization`: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +### أنواع الرموز + +| نوع الرمز | النطاق | حالة الاستخدام | +| :-------------------- | :------------------------ | :----------------------------------------------------------- | +| **Bearer Token** | وصول على مستوى المؤسسة | عمليات الطاقم الكاملة، مثالي للتكامل بين الخوادم | +| **User Bearer Token** | وصول محدد بالمستخدم | صلاحيات محدودة، مناسب للعمليات الخاصة بالمستخدم | + + + يمكنك العثور على كلا نوعي الرموز في علامة تبويب الحالة من صفحة تفاصيل طاقمك في + لوحة تحكم CrewAI AMP. + + +## عنوان URL الأساسي + +لكل طاقم منشور نقطة نهاية API فريدة خاصة به: + +``` +https://your-crew-name.crewai.com +``` + +استبدل `your-crew-name` بعنوان URL الفعلي لطاقمك من لوحة التحكم. + +## سير العمل النموذجي + +1. **الاكتشاف**: استدعِ `GET /inputs` لفهم ما يحتاجه طاقمك +2. **التنفيذ**: أرسل المدخلات عبر `POST /kickoff` لبدء المعالجة +3. **المراقبة**: استعلم عن `GET /status/{kickoff_id}` حتى الاكتمال +4. **النتائج**: استخرج المخرجات النهائية من الاستجابة المكتملة + +## معالجة الأخطاء + +تستخدم الواجهة أكواد حالة HTTP القياسية: + +| الكود | المعنى | +| ----- | :----------------------------------------- | +| `200` | نجاح | +| `400` | طلب غير صالح - تنسيق مدخلات غير صحيح | +| `401` | غير مصرّح - رمز bearer غير صالح | +| `404` | غير موجود - المورد غير موجود | +| `422` | خطأ في التحقق - مدخلات مطلوبة مفقودة | +| `500` | خطأ في الخادم - تواصل مع الدعم | + +## الاختبار التفاعلي + + + **لماذا لا يوجد زر "إرسال"؟** نظرًا لأن كل مستخدم CrewAI AMP لديه عنوان URL + فريد للطاقم، نستخدم **وضع المرجع** بدلاً من بيئة تفاعلية لتجنب + الالتباس. يوضح لك هذا بالضبط كيف يجب أن تبدو الطلبات بدون + أزرار إرسال غير فعالة. + + +تعرض لك كل صفحة نقطة نهاية: + +- **تنسيق الطلب الدقيق** مع جميع المعاملات +- **أمثلة الاستجابة** لحالات النجاح والخطأ +- **عينات الكود** بلغات متعددة (cURL، Python، JavaScript، إلخ) +- **أمثلة المصادقة** بتنسيق رمز Bearer الصحيح + +### **لاختبار واجهتك الفعلية:** + + + + انسخ أمثلة cURL واستبدل العنوان URL + الرمز بقيمك الحقيقية + + + استورد الأمثلة في أداة اختبار API المفضلة لديك + + + +**مثال على سير العمل:** + +1. **انسخ مثال cURL هذا** من أي صفحة نقطة نهاية +2. **استبدل `your-actual-crew-name.crewai.com`** بعنوان URL الحقيقي لطاقمك +3. **استبدل رمز Bearer** برمزك الحقيقي من لوحة التحكم +4. **نفّذ الطلب** في طرفيتك أو عميل API + +## هل تحتاج مساعدة؟ + + + + احصل على مساعدة في تكامل API واستكشاف الأخطاء وإصلاحها + + + إدارة أطقمك وعرض سجلات التنفيذ + + diff --git a/docs/v1.15.1/ar/api-reference/kickoff.mdx b/docs/v1.15.1/ar/api-reference/kickoff.mdx new file mode 100644 index 000000000..84c8ddeac --- /dev/null +++ b/docs/v1.15.1/ar/api-reference/kickoff.mdx @@ -0,0 +1,8 @@ +--- +title: "POST /kickoff" +description: "بدء تنفيذ الطاقم" +openapi: "/v1.15.1/enterprise-api.en.yaml POST /kickoff" +mode: "wide" +--- + + diff --git a/docs/v1.15.1/ar/api-reference/resume.mdx b/docs/v1.15.1/ar/api-reference/resume.mdx new file mode 100644 index 000000000..acc497219 --- /dev/null +++ b/docs/v1.15.1/ar/api-reference/resume.mdx @@ -0,0 +1,6 @@ +--- +title: "POST /resume" +description: "استئناف تنفيذ الطاقم مع التغذية الراجعة البشرية" +openapi: "/v1.15.1/enterprise-api.en.yaml POST /resume" +mode: "wide" +--- diff --git a/docs/v1.15.1/ar/api-reference/status.mdx b/docs/v1.15.1/ar/api-reference/status.mdx new file mode 100644 index 000000000..b33611cb2 --- /dev/null +++ b/docs/v1.15.1/ar/api-reference/status.mdx @@ -0,0 +1,6 @@ +--- +title: "GET /status/{kickoff_id}" +description: "الحصول على حالة التنفيذ" +openapi: "/v1.15.1/enterprise-api.en.yaml GET /status/{kickoff_id}" +mode: "wide" +--- diff --git a/docs/v1.15.1/ar/changelog.mdx b/docs/v1.15.1/ar/changelog.mdx new file mode 100644 index 000000000..3656cacf7 --- /dev/null +++ b/docs/v1.15.1/ar/changelog.mdx @@ -0,0 +1,1939 @@ +--- +title: "سجل التغييرات" +description: "تحديثات المنتج والتحسينات وإصلاحات الأخطاء لـ CrewAI" +icon: "clock" +mode: "wide" +--- + + ## v1.15.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1) + + ## ما الذي تغير + + ### الميزات + - تهيئة مستودعات Git للمشاريع المولدة (#6364) + - طلب تعريفات مشروع CrewAI بشكل صريح (#6358) + - فتح صفحة النشر بعد نشر CLI (#6343) + + ### إصلاحات الأخطاء + - إصلاح حل رابط معرف صفحة النشر (#6365) + - إصلاح عرض قالب الطاقم JSON (#6359) + - إصلاح تثبيت إصدار الطاقم JSON (#6342) + - إصلاح تجاوز إعادة التوجيه SSRF في عمليات السحب (#6331) + + ### الوثائق + - تحسين وضع المصدر المفتوح في README (#6363) + - تحسين دعوة العمل لإعداد وكيل البرمجة (#6344) + - إضافة لقطة وتغيير السجل للإصدار 1.15.1a1 (#6362) + + ## المساهمون + + @joaomdmoura, @lorenzejay, @oalami, @theCyberTech, @vinibrsl + + + + + ## v1.15.1a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.1a1) + + ## ما الذي تغير + + ### الميزات + - تتبع بيانات الزر TUI + - يتطلب تعريفات مشروع CrewAI بشكل صريح + - فتح صفحة النشر بعد نشر CLI + + ### إصلاحات الأخطاء + - إصلاح عرض قالب الطاقم بصيغة JSON + - إصلاح تثبيت إصدار الطاقم بصيغة JSON + - إصلاح تجاوز إعادة التوجيه SSRF في عمليات جلب البيانات + + ### الوثائق + - تحسين دعوة إعداد وكيل البرمجة + - لقطة وتغيير السجل للإصدار v1.15.0 + + ## المساهمون + + @joaomdmoura, @lorenzejay, @theCyberTech, @vinibrsl + + + + + ## v1.15.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.0) + + ## ما الذي تغير + + ### الميزات + - تتبع استخدام تدفق المحادثات في التليمتري + - دعم تدفقات المحادثات في واجهة سطر الأوامر TUI + - إضافة تحميل تدفق موحد بالإعلان + - إضافة دعم تدفق CLI بالإعلان + - إضافة تعبير "if" اختياري إلى خطوات each.do + - إضافة إجراء عميل فردي إلى تعريفات التدفق + - إضافة إجراءات الطاقم إلى تعريف التدفق + - إضافة تحميل تعريف الطاقم داخل السطر + - إضافة إجراء مركب `each` إلى تعريف التدفق + - تنفيذ دعم وضع DMN في إنشاء الطاقم وتنفيذه + + ### إصلاحات الأخطاء + - إصلاح تطبيق أذونات المالك فقط على ملفات الاعتماد + - إصلاح مدخلات بدء حالة تدفق مخطط JSON + - إصلاح تجاوز مسار الرابط الرمزي في استخراج أرشيف المهارة + - تجميع استخدام الرموز عبر جميع مكالمات LLM + - إزالة أداة Exa المكررة + - حل مشاكل الطاقم JSON + - إصلاح معالجة الطاقم JSON وتعزيز وظيفة إعادة تعيين الذاكرة + + ### الوثائق + - تحديث وثائق التثبيت والبدء السريع لمشاريع الطاقم التي تعتمد على JSON + - إضافة دليل تكامل Datadog مع لوحة عمليات قابلة للاستيراد + - إضافة صفحة استوديو "بطاقة واحدة لكل خطوة" + - إضافة لقطات وتغييرات للإصدارات السابقة التي تؤدي إلى v1.15.0 + + ### الأداء + - تحسين تجربة بدء تشغيل crewai run + - الحفاظ على تقدم طريقة التدفق مرئيًا للطاقم المتداخل + + ### إعادة الهيكلة + - إزالة `StateProxy` من الوصول إلى حالة التدفق + - دمج `crewai run` و `crewai flow kickoff` + - تمييز أنواع حالة تعريف التدفق + - توصيل التكوين والاستمرارية من تعريف التدفق إلى وقت التشغيل + + ## المساهمون + + @gabemilani, @github-code-quality[bot], @greysonlalonde, @iris-clawd, @jessemiller, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech, @vinibrsl + + + + + ## v1.14.8a5 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a5) + + ## ما الذي تغير + + ### الميزات + - جعل المراجع التصريحية تعمل عبر التدفقات والفرق (#6326) + + ### إصلاحات الأخطاء + - إصلاح مدخلات بدء حالة تدفق مخطط JSON (#6325) + + ### الوثائق + - وضع بطاقة واحدة لكل خطوة تحت استوديو الفريق وإزالة لافتة التوزيع (AGE-107) (#6317) + - تحديث اللقطة وسجل التغييرات للإصدار v1.14.8a4 (#6319) + + ### إعادة الهيكلة + - إزالة `StateProxy` من الوصول إلى حالة التدفق (#6327) + + ## المساهمون + + @jessemiller, @vinibrsl + + + + + ## v1.14.8a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a4) + + ## ما الذي تغير + + ### الميزات + - دعم تدفقات المحادثة في واجهة سطر الأوامر TUI. + + ### إصلاحات الأخطاء + - إصلاح مسار التوجيه الرمزي في استخراج أرشيف المهارات. + - التحقق من صحة مسارات تعريف التدفق الإعلاني. + + ### الوثائق + - تحديث اللقطة وسجل التغييرات للإصدار v1.14.8a3. + + ## المساهمون + + @lorenzejay, @theCyberTech, @vinibrsl + + + + + ## v1.14.8a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a3) + + ## ما الذي تغير + + ### الميزات + - إضافة تحميل تدفق موحد إعلاني + - تحسين تجربة بدء تشغيل crewai run + - دمج `crewai run` و `crewai flow kickoff` + - الحفاظ على تقدم طريقة التدفق مرئيًا للفرق المتداخلة + - إضافة دعم واجهة سطر الأوامر الإعلانية للتدفق + - السماح باستخدام `@router()` كطريقة بدء لتدفق + - إضافة مخططات مخرجات مكتوبة لأدوات CrewAI + + ### إصلاحات الأخطاء + - تثبيت opentelemetry على ~=1.42.0 + + ### الوثائق + - إضافة صفحة استوديو "بطاقة واحدة لكل خطوة" + + ## المساهمون + + @jessemiller, @joaomdmoura, @lucasgomide, @vinibrsl + + + + + ## v1.14.8a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a2) + + ## ما الذي تغير + + ### الميزات + - إضافة إجراء عميل واحد إلى تعريفات التدفق + - التحقق من تعبيرات CEL للتدفق عند تحميل التعريف + + ### الوثائق + - إضافة دليل تكامل Datadog مع لوحة عمليات قابلة للاستيراد + - تحديث اللقطة وسجل التغييرات للإصدار v1.14.8a1 + + ## المساهمون + + @joaomdmoura, @lucasgomide, @vinibrsl + + + + + ## v1.14.8a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a1) + + ## ما الذي تغير + + ### الميزات + - إضافة تعبير if اختياري إلى خطوات each.do + + ### إصلاحات الأخطاء + - إصلاح مشكلات JSON crew + + ### الوثائق + - تحديث snapshot و changelog للإصدار v1.14.8a + + ## المساهمون + + @joaomdmoura, @vinibrsl + + + + + ## v1.14.8a + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.8a) + + ## ما الذي تغير + + ### الميزات + - إضافة إجراء كتلة نصية/كود إلى FlowDefinition + - إضافة إجراءات الطاقم إلى FlowDefinition + - إضافة إجراء مركب `each` إلى FlowDefinition + - تنفيذ دعم وضع DMN في إنشاء الطاقم وتنفيذه + - تحسين وظيفة إعادة تعيين الذاكرة ومعالجة الطاقم بتنسيق JSON + - إضافة تعبيرات إلى إجراءات FlowDefinition + - تنفيذ أدوات تشغيل تعريف التدفق بدون كود Python + - دفع التغذية الراجعة البشرية من تعريف التدفق + - توصيل التكوين والاستمرارية من FlowDefinition إلى وقت التشغيل + - إضافة `crewai run --definition` للتدفقات التصريحية + - دعم تراجع نشر ZIP وتشغيل مشاريع الطاقم بتنسيق JSON + - تقديم الطواقم بتنسيق JSON أولاً + + ### إصلاحات الأخطاء + - إصلاح أداة Exa المكررة + - إصلاح استخدام الرموز المجمعة عبر جميع استدعاءات LLM + - حل المشكلات المتعلقة بتحميل الطاقم ومنطق التحقق + + ### الوثائق + - توثيق حقول FlowDefinition في مخطط JSON + - تحديث وثائق التثبيت والبدء السريع لمشاريع الطاقم بتنسيق JSON أولاً + - تحديث سجل التغييرات والإصدار لـ v1.14.7 + + ## المساهمون + + @gabemilani, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech, @vinibrsl + + + + + ## v1.14.7 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهات خلفية افتراضية قابلة للتوصيل للذاكرة، والمعرفة، وrag، وflow. + - عرض السبب الحقيقي للإنهاء، ومعلمات العينة، وresponse.id في أحداث LLM. + - تصنيف مشغلات DSL كزخارف واعية للمسار. + - إضافة واجهة برمجة تطبيقات الدردشة لتدفقات المحادثة. + - جعل واجهة القفل قابلة للتجاوز. + - بناء FlowDefinition من بيانات التعريف الخاصة بـ Flow DSL. + - إضافة مزود LLM من Snowflake Cortex الأصلي. + - إضافة دعم لملفات الوكلاء المدربين من crew. + + ### إصلاحات الأخطاء + - إصلاح نقطة التحقق لإعادة بناء BaseLLM مخصص كـ LLM ملموس عند الاستعادة. + - تقييد الاستعادة على علامة لمنع اللقطات الحية من إعادة التشغيل كاستئناف. + - تحديد حالة وقت التشغيل لكل تشغيل للحد من النمو وعزل التشغيل المتزامن. + - إصلاح إعدادات التتبع على crewai-login. + - احترام suppress_flow_events لأحداث تنفيذ الطريقة. + - استعادة [project.scripts] في حزمة crewai لتثبيت أداة uv. + - حل مشكلات CVE الخاصة بـ pip-audit لـ aiohttp وdocling وdocling-core. + - إصلاح إدخال الملفات الذي لا يعمل بشكل موثوق. + - إصلاح تاريخ نتائج أدوات Snowflake Claude غير المكتملة. + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.7. + - تحديث وثائق جامع OpenTelemetry. + - تحديث دليل NVIDIA Nemotron LLM. + - إضافة دليل تكامل Databricks. + - إضافة دليل تكامل Snowflake. + + ### الأداء + - تحسين سرعة استيراد crewai من خلال تحميل مستندات docling بشكل كسول. + + ### إعادة الهيكلة + - تبسيط تقييم شروط التدفق ليكون بلا حالة لكل حدث. + - فصل منطق المحادثة عن وقت التشغيل وإضافة تعريف المحادثة. + - تقسيم `flow.py` إلى DSL، وتعريف، ووقت تشغيل. + + ## المساهمون + + @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @gvieira, @jessemiller, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl + + + + + ## v1.14.7rc2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc2) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - استعادة البوابة على علامة لمنع اللقطات الحية من إعادة التشغيل كاستئناف + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.7rc1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.14.7rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7rc1) + + ## ما الذي تغير + + ### الميزات + - إضافة `reset_runtime_state` لإطلاق حالة الحافلة المتراكمة + - التعامل مع دعم كل من الموجهات المخصصة + - فصل منطق المحادثة عن وقت التشغيل وإضافة `conversational_definition` + + ### إصلاحات الأخطاء + - إصلاح نطاق حالة وقت التشغيل لكل تشغيل للحد من النمو وعزل التشغيلات المتزامنة + - إصلاح إعدادات القياس عن بُعد على `crewai-login` + - إصلاح احترام `suppress_flow_events` لفعاليات تنفيذ الأساليب + + ### الوثائق + - تحديث صور OpenTelemetry + - تحديث الوثائق لتعكس الحالة الجديدة لجمع بيانات OpenTelemetry + - تحديث سجل التغييرات والإصدار لـ v1.14.7a4 + + ### إعادة الهيكلة + - تبسيط تقييم شرط التدفق ليكون بلا حالة لكل حدث + - تحسين دورة توجيه المحادثة مع تقليل مسار واحد + + ## المساهمون + + @greysonlalonde, @lorenzejay, @lucasgomide, @vinibrsl + + + + + ## v1.14.7a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a4) + + ## ما الذي تغير + + ### الميزات + - نقل وقت التشغيل @listen/@router لقراءة من FlowDefinition + - إضافة واجهات خلفية افتراضية قابلة للتوصيل للذاكرة، والمعرفة، وrag، وflow + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.7a3 + + ## المساهمون + + @greysonlalonde, @mattatcha, @vinibrsl + + + + + ## v1.14.7a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a3) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح تعرض `ask_for_human_input` في `AgentExecutor` التجريبي + - حل مشكلات CVEs الخاصة بـ pip-audit لـ `aiohttp`، `docling`، `docling-core`، و `pip` + + ### إعادة هيكلة + - نقل `@start` لقراءة من `FlowDefinition` + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.7a2 + + ## المساهمون + + @greysonlalonde، @lorenzejay، @vinibrsl + + + + + ## v1.14.7a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a2) + + ## ما الذي تغير + + ### الميزات + - إضافة دعم تتبع تدفقات المحادثة. + - تحديث وثائق تدفق المحادثة لاستخدام `handle_turn`. + - عرض السبب الحقيقي لإنهاء المحادثة، ومعلمات العينة، و`response.id` في أحداث LLM. + - تصنيف مشغلات DSL كزخارف واعية بالمسار. + - تنفيذ واجهة برمجة التطبيقات للدردشة لتدفقات المحادثة. + - جعل قفل الخلفية قابلاً للتجاوز في متجر القفل. + - تقسيم أحادي تدفق DSL إلى وحدات زخرفية مركزة. + - تسطيح استخدام ذاكرة التخزين المؤقت LiteLLM/أعداد الأسباب الفرعية في `_usage_to_dict`. + - بناء `FlowDefinition` من بيانات التعريف الخاصة بتدفق DSL. + + ### الوثائق + - إضافة دليل NVIDIA Nemotron LLM. + - توثيق عمليات نشر المونوريبو. + - تحديث سجل التغييرات والإصدار لـ v1.14.7a1. + + ## المساهمون + + @alex-clawd, @gvieira, @lorenzejay, @lucasgomide, @mattatcha, @vinibrsl + + + + + ## v1.14.7a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.7a1) + + ## ما الذي تغير + + ### الميزات + - إضافة دعم ملفات الوكلاء المدربين + - إضافة مزود LLM الأصلي لـ Snowflake Cortex + - إضافة دليل تكامل Databricks + - إضافة دليل تكامل Snowflake + + ### إصلاحات الأخطاء + - إصلاح CLI عن طريق استعادة `[project.scripts]` في حزمة crewai لتثبيت أداة UV + - حل مشكلات موثوقية إدخال الملفات + - إصلاح تاريخ نتائج الأدوات غير المكتملة في Snowflake Claude + - التعامل مع استدعاءات الأدوات الممثلة كسلاسل لـ Snowflake Claude + - إعادة تفعيل مستمعي `or_` متعدد المصادر عبر دورات مدفوعة بالموجه + + ### الأداء + - تحسين سرعة استيراد crewai عن طريق تحميل استيرادات docling بشكل كسول + + ### إعادة هيكلة + - تقسيم `flow.py` إلى DSL، تعريف، وتشغيل + + ## المساهمون + + @Luzk, @alex-clawd, @devin-ai-integration[bot], @greysonlalonde, @jessemiller, @lorenzejay, @vinibrsl + + + + + ## v1.14.6 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6) + + ## ما الذي تغير + + ### الميزات + - تحسين StdioTransport لمنع تسرب متغيرات البيئة + - تعزيز تكوين التخطيط ومعالجة الملاحظات + - إعلان env_vars على DatabricksQueryTool + - إضافة وثائق خطة التحكم في الوكيل + + ### إصلاحات الأخطاء + - إصلاح تسرب المخرجات المنظمة في حلقات استدعاء الأدوات + - حذف ردود الاستدعاء غير القابلة للعودة وحالة المحول في نقطة التحقق + - تسلسل الحقول من النوع [BaseModel] كـ JSON schema في نقطة التحقق + - تجنب مهمة orphan task_started عند استعادة نطاق الاستئناف + - السماح لـ AgentExecutor بالاستعادة من نقطة التحقق + - تصحيح خطأ الكتابة من mongodb إلى pymongo في package_dependencies + + ### الوثائق + - إضافة كتلة تنقل وثائق ACP (بيتا) إلى صفحات خطة التحكم في الوكيل + - إزالة المراجع إلى العمليات التوافقية من صفحة العمليات + - إعادة هيكلة صفحة نقاط التحقق + - توثيق خطوة تثبيت حزمة الإدارة لمرة واحدة + - نقل Secrets Manager / Workload Identity من replicated-config + - إزالة تعبيرات `{" "}` JSX التي تكسر عرض `` + + ### إعادة الهيكلة + - نقل مستودع المهارات إلى experimental + CREWAI_EXPERIMENTAL gate + + ## المساهمون + + @akaKuruma, @alex-clawd, @github-actions[bot], @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @lucasgomide, @mattatcha, @thiagomoretto, @vinibrsl + + + + + ## v1.14.6a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6a2) + + ## ما الذي تغير + + ### الميزات + - تحسين `StdioTransport` لمنع تسرب متغيرات البيئة + - تحسين تكوين التخطيط ومعالجة المراقبة + - إعلان `env_vars` على `DatabricksQueryTool` + - إضافة وثائق خطة التحكم بالوكيل + + ### إصلاحات الأخطاء + - إصلاح تسرب المخرجات المنظمة في حلقات استدعاء الأدوات + - حذف الاستدعاءات غير القابلة للعودة وحالة المحول في نقاط التحقق + - تسلسل حقول `type[BaseModel]` كـ JSON schema في نقاط التحقق + - تجنب `task_started` اليتيمة عند استعادة نطاق الاستئناف + - السماح لـ `AgentExecutor` بالاستعادة من نقطة تحقق + - تصحيح خطأ مطبعي في MongoDB إلى `pymongo` في تبعيات الحزمة + + ### الوثائق + - إعادة هيكلة صفحة نقاط التحقق + - توثيق خطوة تثبيت حزمة الإدارة لمرة واحدة + - نقل Secrets Manager / Workload Identity من replicated-config + - إزالة إدخال Skills Repository من سجل التغييرات + + ## المساهمون + + @github-actions[bot], @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @lucasgomide, @mattatcha, @thiagomoretto, @vinibrsl + + + + + ## v1.14.6a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.6a1) + + ## ما الذي تغير + + ### الميزات + - توليد ملاحظات إصدار مصنفة للمؤسسات + + ### إصلاحات الأخطاء + - تعزيز تسلسل حالة وقت التشغيل عبر حقول الكيان + - تحديث idna إلى 3.15 لمعالجة مشكلة الأمان GHSA-65pc-fj4g-8rjx + - إزالة تعبيرات JSX `{" "}` التي تعطل عرض `` + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.5 + + ## المساهمون + + @akaKuruma, @alex-clawd, @greysonlalonde + + + + + ## v1.14.5 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5) + + ## ما الذي تغير + + ### الميزات + - إلغاء استخدام `CrewAgentExecutor`، وتعيين وكلاء الطاقم الافتراضيين إلى `AgentExecutor` + - تحسين أدوات صندوق الرمل Daytona + - إضافة معلمة بدء `restore_from_state_id` + - إضافة تسليط الضوء على `ExaSearchTool`، وإعادة تسميته من `EXASearchTool` + + ### إصلاحات الأخطاء + - إصلاح تسرب الذاكرة في `git.py` باستخدام `cached_property` + - عرض استدعاءات الأدوات المتدفقة عندما تكون `available_functions` غائبة + - ضمان تحميل أحداث `skills` للتتبع + - تصحيح مسار نقطة النهاية للحالة من `/{kickoff_id}/status` إلى `/status/{kickoff_id}` + - استعادة كتلة الشيفرة المفقودة في دليل التدفق الأول للغة البرتغالية (pt-BR) + - منع `result_as_answer` من إرجاع رسائل الخطأ أو الكتل المرتبطة كإجابة نهائية + - الحفاظ على مخرجات المهام عبر تفريغ الدفعات غير المتزامنة + - دائمًا استعادة `task.output_pydantic` في كتلة finally + - التعامل مع إدخال `BaseModel` في `convert_to_model` + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.5 + - إضافة دليل ترقية OSS و انتقال الطاقم إلى التدفق + - توثيق متغيرات البيئة الإضافية لأدوات المطور + - إضافة وثائق لـ `TavilyGetResearch` + + ### إعادة الهيكلة + - استخراج واجهة سطر الأوامر إلى حزمة مستقلة `crewai-cli` + + ## المساهمون + + @NIK-TIGER-BILL, @akaKuruma, @cgoeppinger, @github-actions[bot], @greysonlalonde, @heitorado, @irfaan101, @iris-clawd, @lorenzejay, @manisrinivasan2k1, @minasami-pr, @mislavivanda, @theCyberTech, @theishangoswami, @wishhyt + + + + + ## v1.14.5a7 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a7) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.5a6 + + ### تغييرات كسرية + - إلغاء حقل function_calling_llm + + ## المساهمون + + @greysonlalonde, @heitorado + + + + + ## v1.14.5a6 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a6) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح استدعاءات الأدوات المتدفقة عندما تكون available_functions غائبة + - رفع اعتماد langsmith إلى الإصدار >=0.8.0 لمعالجة GHSA-3644-q5cj-c5c7 + - حل مشاكل الأماكن الشاغرة لكتل التعليمات البرمجية غير المترجمة في وثائق البرتغالية البرازيلية + + ### الوثائق + - إضافة وثائق لـ TavilyGetResearch + - تحديث سجل التغييرات والإصدار لـ v1.14.5a5 + + ## المساهمون + + @greysonlalonde, @heitorado, @iris-clawd, @lorenzejay, @manisrinivasan2k1 + + + + + ## v1.14.5a5 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a5) + + ## ما الذي تغير + + ### الميزات + - إلغاء استخدام CrewAgentExecutor، وتعيين وكلاء Crew الافتراضيين إلى AgentExecutor + - تحسين أدوات صندوق الرمل Daytona + + ### إصلاحات الأخطاء + - إصلاح كتلة الكود المفقودة في دليل التدفق الأول باللغة البرتغالية (pt-BR) + - تسجيل أخطاء المراجعة المسبقة والتقطير HITL، إضافة learn_strict + - تصحيح urllib3 للثغرات الأمنية + - تصحيح gitpython و langchain-core؛ تجاهل CVE paramiko غير المصححة + - تحديث جميع حزم مساحة العمل المنشورة على uv lock/sync + + ### الوثائق + - إضافة دليل ترحيل لـ `inputs.id` إلى `restoreFromStateId` + - إضافة دليل ترقية OSS ودليل ترحيل crew-to-flow + - تحديث سجل التغييرات والإصدار لـ v1.14.5a4 + + ## المساهمون + + @akaKuruma, @greysonlalonde, @iris-clawd, @lorenzejay, @mislavivanda + + + + + ## v1.14.5a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a4) + + ## ما الذي تغير + + ### الميزات + - تحديث قوائم LLM + + ### إصلاحات الأخطاء + - إصلاح مشكلة الاعتماد من خلال نقل `textual` إلى `crewai-cli` وإضافة `certifi` + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.5a3 + + ## المساهمون + + @cgoeppinger, @greysonlalonde + + + + + ## v1.14.5a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a3) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح مسار نقطة النهاية للحالة من /{kickoff_id}/status إلى /status/{kickoff_id} + - تحديث تبعية gitpython إلى الإصدار >=3.1.47 للامتثال الأمني + + ### إعادة هيكلة + - استخراج واجهة سطر الأوامر إلى حزمة crewai-cli المستقلة + + ### الوثائق + - تحديث سجل التغييرات والإصدار للإصدار v1.14.5a2 + + ## المساهمون + + @greysonlalonde, @iris-clawd + + + + + ## v1.14.5a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a2) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح استعادة مخرجات المهام في كتلة finally + - تضمين `thoughts_token_count` في رموز الإكمال + - الحفاظ على مخرجات المهام عبر تفريغ دفعات غير متزامنة + - تمرير kwargs إلى استدعاءات المحمل في `CrewAIRagAdapter` + - منع `result_as_answer` من إرجاع رسالة كتلة الخطاف كإجابة نهائية + - منع `result_as_answer` من إرجاع خطأ كإجابة نهائية + - استخدام `acall` لتحويل المخرجات في المسارات غير المتزامنة + - منع تغيير كلمات التوقف المشتركة في LLM عبر الوكلاء + - التعامل مع مدخلات `BaseModel` في `convert_to_model` + + ### الوثائق + - توثيق متغيرات البيئة الإضافية + - تحديث سجل التغييرات والإصدار لـ v1.14.5a1 + + ## المساهمون + + @NIK-TIGER-BILL, @greysonlalonde, @lorenzejay, @minasami-pr, @theCyberTech, @wishhyt + + + + + ## v1.14.5a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.5a1) + + ## ما الذي تغير + + ### الميزات + - إضافة معلمة بدء `restore_from_state_id` + - إضافة تسليط الضوء على ExaSearchTool وإعادة تسميته من EXASearchTool + + ### إصلاحات الأخطاء + - إصلاح المواقع المفقودة لـ crewai في تدفق الإصدار + - ضمان تحميل أحداث المهارات للآثار + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.4 + + ## المساهمون + + @akaKuruma, @github-actions[bot], @greysonlalonde, @lorenzejay, @theishangoswami + + + + + ## v1.14.4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.4) + + ## ما الذي تغير + + ### الميزات + - إضافة دعم لمفتاح الاستمرارية المخصص في @persist + - إضافة دعم واجهة برمجة التطبيقات للردود لمزود Azure OpenAI + - تمرير credential_scopes إلى عميل Azure AI Inference + - إضافة دليل إعداد هوية عبء العمل لـ Vertex AI + - إضافة Tavily Research والحصول على Research + - إضافة أدوات MCP من You.com للبحث، البحث، واستخراج المحتوى + + ### إصلاحات الأخطاء + - إصلاح مشكلة السقوط عند عدم تطابق تعبير JSON regex مع JSON صالح + - إصلاح للحفاظ على tool_calls عندما تحتوي الاستجابة أيضًا على نص + - إصلاح لتمرير base_url و api_key إلى instructor.from_provider + - إصلاح لتحذير وإرجاع فارغ عندما لا يُرجع خادم MCP الأصلي أي أدوات + - إصلاح لاستخدام متغير الرسائل الموثقة في معالجات غير البث + - إصلاح لحماية مساعدي وصف دردشة الطاقم ضد فشل LLM + - إصلاح لإعادة تعيين الرسائل والتكرارات بين الاستدعاءات + - إصلاح لتمرير ملف trained-agents من خلال replay و test + - إصلاح لاحترام ملف trained-agents المخصص في الاستدلال + - إصلاح لربط الوكلاء المخصصين بالمهام فقط بالطاقم لملفات الإدخال متعددة الأنماط + - إصلاح لتسلسل callable الحواجز كـ null لتسجيل JSON + - إصلاح إعادة تسمية force_final_answer لتجنب توجيه ذاتي + - إصلاح زيادة litellm لإصلاح SSTI؛ تجاهل CVE غير القابل للإصلاح في pip + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.4a1 + - إضافة صفحة أدوات E2B Sandbox + - إضافة وثائق أدوات صندوق Daytona + + ## المساهمون + + @EdwardIrby, @dependabot[bot], @factory-droid-oss, @factory-droid[bot], @greysonlalonde, @kunalk16, @lorenzejay, @lucasgomide, @manisrinivasan2k1, @mattatcha, @vinibrsl + + + + + ## v1.14.4a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.4a1) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح مساعدي وصف دردشة الطاقم ضد فشل LLM. + - إعادة تعيين الرسائل والتكرارات بين الاستدعاءات في المنفذ. + - تمرير ملف الوكلاء المدربين عبر إعادة التشغيل والاختبار في CLI. + - احترام ملف الوكلاء المدربين المخصص أثناء الاستدلال في الوكيل. + - ربط الوكلاء المخصصين بالمهام فقط بالطاقم لضمان وصول ملفات الإدخال متعددة الوسائط إلى LLM. + - تسلسل استدعاءات الحواجز كـ null لتسجيل النقاط في JSON. + - إعادة تسمية `force_final_answer` في agent_executor لتجنب جهاز التوجيه الذاتي الإشارة. + - تحديث `litellm` لإصلاح SSTI وتجاهل CVE pip غير القابل للإصلاح. + + ### الوثائق + - إضافة صفحة أدوات Sandbox E2B. + - إضافة وثائق أدوات Sandbox Daytona. + - إضافة دليل إعداد هوية عبء العمل لـ Vertex AI. + - إضافة أدوات MCP من You.com للبحث، البحث، واستخراج المحتوى. + - تحديث سجل التغييرات والإصدار لـ v1.14.3. + + ## المساهمون + + @EdwardIrby, @dependabot[bot], @factory-droid-oss, @factory-droid[bot], @greysonlalonde, @lorenzejay, @manisrinivasan2k1, @mattatcha + + + + + ## v1.14.3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.3) + + ## ما الذي تغير + + ### الميزات + - إضافة أحداث دورة الحياة لعمليات نقطة التحقق + - إضافة دعم لـ e2b + - الرجوع إلى DefaultAzureCredential عند عدم توفير مفتاح API في تكامل Azure + - إضافة دعم Bedrock V4 + - إضافة أدوات Daytona sandbox لوظائف محسّنة + - إضافة دعم نقطة التحقق والتفرع للوكلاء المستقلين + + ### إصلاحات الأخطاء + - إصلاح execution_id ليكون منفصلًا عن state.id + - حل مشكلة إعادة تشغيل أحداث الطريقة المسجلة عند استئناف نقطة التحقق + - إصلاح تسلسل مراجع class initial_state كـ JSON schema + - الحفاظ على مهارات الوكلاء التي تحتوي على بيانات وصفية فقط + - تمرير أسماء @CrewBase الضمنية إلى أحداث الطاقم + - دمج بيانات التنفيذ عند تهيئة دفعة مكررة + - إصلاح تسلسل حقول مراجع class Task لنقاط التحقق + - التعامل مع نتيجة BaseModel في حلقة إعادة المحاولة guardrail + - الحفاظ على thought_signature في استدعاءات أدوات Gemini للبث + - إصدار task_started عند استئناف التفرع وإعادة تصميم واجهة المستخدم النصية لنقطة التحقق + - استخدام تواريخ مستقبلية في اختبارات تقليم نقطة التحقق لمنع الفشل المعتمد على الوقت + - إصلاح ترتيب التشغيل الجاف والتعامل مع الفرع القديم الذي تم التحقق منه في إصدار أدوات التطوير + - ترقية lxml إلى >=6.1.0 لرقعة الأمان + - رفع python-dotenv إلى >=1.2.2 لرقعة الأمان + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.3 + - إضافة صفحة "بناء باستخدام الذكاء الاصطناعي" وتحديث التنقل لجميع اللغات + - إزالة الأسئلة الشائعة حول التسعير من صفحة البناء باستخدام الذكاء الاصطناعي عبر جميع المواقع + + ### الأداء + - تحسين MCP SDK وأنواع الأحداث لتقليل بدء التشغيل البارد بنسبة ~29% + + ### إعادة الهيكلة + - إعادة هيكلة مساعدي نقطة التحقق للقضاء على التكرار وتشديد تلميحات نوع الحالة + + ## المساهمون + + @MatthiasHowellYopp, @akaKuruma, @alex-clawd, @github-actions[bot], @github-advanced-security[bot], @greysonlalonde, @iris-clawd, @lorenzejay, @mattatcha, @renatonitta + + + + + ## v1.14.3a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.3a3) + + ## ما الذي تغير + + ### الميزات + - إضافة دعم لـ e2b + - تنفيذ التراجع إلى DefaultAzureCredential عند عدم توفير مفتاح API + + ### إصلاحات الأخطاء + - ترقية lxml إلى >=6.1.0 لمعالجة مشكلة الأمان GHSA-vfmq-68hx-4jfw + + ### الوثائق + - إزالة الأسئلة الشائعة حول التسعير من صفحة البناء باستخدام الذكاء الاصطناعي عبر جميع اللغات + + ### الأداء + - تحسين وقت بدء التشغيل البارد بنسبة ~29% من خلال التحميل الكسول لمجموعة أدوات MCP وأنواع الأحداث + + ## المساهمون + + @alex-clawd, @github-advanced-security[bot], @greysonlalonde, @iris-clawd, @lorenzejay, @mattatcha + + + + + ## v1.14.3a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.3a2) + + ## ما الذي تغير + + ### الميزات + - إضافة دعم لـ bedrock V4 + - إضافة أدوات Daytona sandbox لوظائف محسّنة + - إضافة صفحة "البناء باستخدام الذكاء الاصطناعي" — مستندات أصلية للذكاء الاصطناعي لوكلاء البرمجة + - إضافة "البناء باستخدام الذكاء الاصطناعي" إلى التنقل في صفحة "البدء" وملفات الصفحات لجميع اللغات (en, ko, pt-BR, ar) + + ### إصلاحات الأخطاء + - إصلاح انتشار أسماء @CrewBase الضمنية إلى أحداث الطاقم + - حل مشكلة تكرار تهيئة الدفعات في دمج بيانات التنفيذ الوصفية + - إصلاح تسلسل حقول مرجع فئة Task لعمليات التحقق من النقاط + - التعامل مع نتيجة BaseModel في حلقة إعادة المحاولة للحدود + - تحديث python-dotenv إلى الإصدار >=1.2.2 للامتثال الأمني + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.3a1 + - تحديث الأوصاف وتطبيق الترجمات الفعلية + + ## المساهمون + + @MatthiasHowellYopp, @github-actions[bot], @greysonlalonde, @iris-clawd, @lorenzejay, @renatonitta + + + + + ## v1.14.3a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.3a1) + + ## ما الذي تغير + + ### الميزات + - إضافة دعم نقاط التحقق والفروع لوكلاء مستقلين + + ### إصلاحات الأخطاء + - الحفاظ على thought_signature في استدعاءات أداة البث Gemini + - إصدار task_started عند استئناف الفرع وإعادة تصميم واجهة المستخدم النصية لنقاط التحقق + - تصحيح ترتيب التشغيل الجاف ومعالجة الفرع القديم الذي تم التحقق منه في إصدار أدوات التطوير + - استخدام تواريخ مستقبلية في اختبارات تقليم نقاط التحقق لمنع الفشل المعتمد على الوقت (#5543) + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.2 + + ## المساهمون + + @alex-clawd, @greysonlalonde + + + + + ## v1.14.2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2) + + ## ما الذي تغير + + ### الميزات + - إضافة أوامر استئناف النقاط التفتيش، والاختلاف، والتنظيف مع تحسين إمكانية الاكتشاف. + - إضافة معلمة `from_checkpoint` إلى `Agent.kickoff` والطرق ذات الصلة. + - إضافة أوامر إدارة القوالب لقوالب المشاريع. + - إضافة تلميحات استئناف إلى إصدار أدوات المطور عند الفشل. + - إضافة واجهة سطر الأوامر للتحقق من النشر وتعزيز سهولة استخدام تهيئة LLM. + - إضافة تقسيم النقاط التفتيشية مع تتبع النسب. + - إثراء تتبع رموز LLM مع رموز الاستدلال ورموز إنشاء التخزين المؤقت. + + ### إصلاحات الأخطاء + - إصلاح المطالبة بشأن تعارضات الفروع القديمة في إصدار أدوات المطور. + - تصحيح الثغرات في `authlib` و `langchain-text-splitters` و `pypdf`. + - تحديد نطاق معالجات البث لمنع تلوث أجزاء التشغيل المتقاطعة. + - إرسال نقاط التفتيش عبر واجهات Flow في TUI. + - استخدام نمط البحث المتكرر لاكتشاف نقاط التفتيش بتنسيق JSON. + - التعامل مع مخططات JSON الدائرية في أداة حل MCP. + - الحفاظ على معلمات استدعاء أداة Bedrock من خلال إزالة القيمة الافتراضية الصحيحة. + - إصدار حدث flow_finished بعد استئناف HITL. + - إصلاح ثغرات متنوعة من خلال تحديث التبعيات، بما في ذلك `requests` و `cryptography` و `pytest`. + - إصلاح لإيقاف تمرير وضع صارم إلى واجهة برمجة التطبيقات Bedrock Converse. + + ### الوثائق + - توثيق المعلمات المفقودة وإضافة قسم النقاط التفتيشية. + - تحديث سجل التغييرات والإصدار للإصدار v1.14.2 ومرشحي الإصدار السابقين. + - إضافة توثيق ميزة A2A الخاصة بالشركات وتحديث وثائق A2A المفتوحة المصدر. + + ## المساهمون + + @Yanhu007، @alex-clawd، @github-actions[bot]، @greysonlalonde، @iris-clawd، @lorenzejay، @lucasgomide + + + + + ## v1.14.2rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2rc1) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح معالجة مخططات JSON الدائرية في أداة MCP + - إصلاح ثغرة أمنية من خلال تحديث python-multipart إلى 0.0.26 + - إصلاح ثغرة أمنية من خلال تحديث pypdf إلى 6.10.1 + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.2a5 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.14.2a5 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a5) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.2a4 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.14.2a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a4) + + ## ما الذي تغير + + ### الميزات + - إضافة تلميحات استئناف إلى إصدار أدوات المطورين عند الفشل + + ### إصلاحات الأخطاء + - إصلاح توجيه وضع الصرامة إلى واجهة برمجة تطبيقات Bedrock Converse + - إصلاح إصدار pytest إلى 9.0.3 لثغرة الأمان GHSA-6w46-j5rx-g56g + - رفع الحد الأدنى لـ OpenAI إلى >=2.0.0 + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.2a3 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.14.2a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a3) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة سطر الأوامر للتحقق من النشر + - تحسين سهولة استخدام تهيئة LLM + + ### إصلاحات الأخطاء + - تجاوز pypdf و uv إلى إصدارات مصححة لـ CVE-2026-40260 و GHSA-pjjw-68hj-v9mw + - ترقية requests إلى >=2.33.0 لمعالجة ثغرة ملف مؤقت CVE + - الحفاظ على معلمات استدعاء أداة Bedrock من خلال إزالة القيمة الافتراضية الصحيحة + - تنظيف مخططات الأدوات لوضع صارم + - إصلاح اختبار تسلسل تضمين MemoryRecord + + ### الوثائق + - تنظيف لغة A2A الخاصة بالمؤسسات + - إضافة وثائق ميزات A2A الخاصة بالمؤسسات + - تحديث وثائق A2A الخاصة بالمصادر المفتوحة + - تحديث سجل التغييرات والإصدار لـ v1.14.2a2 + + ## المساهمون + + @Yanhu007, @greysonlalonde + + + + + ## v1.14.2a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a2) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة مستخدم نصية لنقطة التحقق مع عرض شجري، ودعم التفرع، ومدخلات/مخرجات قابلة للتعديل + - إثراء تتبع رموز LLM مع رموز الاستدلال ورموز إنشاء التخزين المؤقت + - إضافة معلمة `from_checkpoint` إلى طرق الانطلاق + - تضمين `crewai_version` في نقاط التحقق مع إطار عمل الهجرة + - إضافة تفرع نقاط التحقق مع تتبع السلالة + + ### إصلاحات الأخطاء + - إصلاح توجيه الوضع الصارم إلى مزودي Anthropic وBedrock + - تعزيز NL2SQLTool مع وضع القراءة فقط الافتراضي، والتحقق من الاستعلامات، والاستعلامات المعلمة + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.2a1 + + ## المساهمون + + @alex-clawd, @github-actions[bot], @greysonlalonde, @lucasgomide + + + + + ## v1.14.2a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a1) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح إصدار حدث flow_finished بعد استئناف HITL + - إصلاح إصدار التشفير إلى 46.0.7 لمعالجة CVE-2026-39892 + + ### إعادة هيكلة + - إعادة هيكلة لاستخدام I18N_DEFAULT المشترك + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.14.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.1) + + ## ما الذي تغير + + ### الميزات + - إضافة متصفح TUI لنقاط التفتيش غير المتزامنة + - إضافة دالة aclose()/close() ومدير سياق غير متزامن لمخرجات البث + + ### إصلاحات الأخطاء + - إصلاح التعبير النمطي لزيادة إصدار pyproject.toml + - تنظيف أسماء الأدوات في مرشحات زخرفة الخطاف + - إصلاح تسجيل معالجات نقاط التفتيش عند إنشاء CheckpointConfig + - رفع إصدار transformers إلى 5.5.0 لحل CVE-2026-1839 + - إزالة غلاف FilteredStream لـ stdout/stderr + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.1rc1 + + ### إعادة الهيكلة + - استبدال القائمة المحظورة الثابتة باستبعاد حقل BaseTool الديناميكي في توليد المواصفات + - استبدال التعبير النمطي بـ tomlkit في واجهة سطر أوامر أدوات التطوير + - استخدام كائن PRINTER المشترك + - جعل BaseProvider نموذجاً أساسياً مع مميز نوع المزود + + ## المساهمون + + @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay + + + + + ## v1.14.1rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.1rc1) + + ## ما الذي تغير + + ### الميزات + - إضافة متصفح TUI لنقطة التحقق غير المتزامنة + - إضافة aclose()/close() ومدير سياق غير متزامن لمخرجات البث + + ### إصلاحات الأخطاء + - إصلاح زيادة إصدارات pyproject.toml باستخدام التعبيرات العادية + - تنظيف أسماء الأدوات في مرشحات ديكور المكونات + - زيادة إصدار transformers إلى 5.5.0 لحل CVE-2026-1839 + - تسجيل معالجات نقطة التحقق عند إنشاء CheckpointConfig + + ### إعادة الهيكلة + - استبدال القائمة المحظورة الثابتة باستبعاد حقل BaseTool الديناميكي في توليد المواصفات + - استبدال التعبيرات العادية بـ tomlkit في واجهة سطر الأوامر devtools + - استخدام كائن PRINTER المشترك + - جعل BaseProvider نموذجًا أساسيًا مع مميز نوع المزود + - إزالة غلاف stdout/stderr لـ FilteredStream + - إزالة flow/config.py غير المستخدمة + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.0 + + ## المساهمون + + @greysonlalonde, @iris-clawd, @joaomdmoura + + + + + ## v1.14.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0) + + ## ما الذي تغير + + ### الميزات + - إضافة أوامر CLI لقائمة/معلومات نقاط التحقق + - إضافة guardrail_type و name لتمييز التتبع + - إضافة SqliteProvider لتخزين نقاط التحقق + - إضافة CheckpointConfig للتسجيل التلقائي لنقاط التحقق + - تنفيذ تسجيل حالة وقت التشغيل، نظام الأحداث، وإعادة هيكلة المنفذ + + ### إصلاحات الأخطاء + - إضافة حماية من SSRF وتجاوز المسار + - إضافة التحقق من المسار وعنوان URL لأدوات RAG + - استبعاد متجهات التضمين من تسلسل الذاكرة لتوفير الرموز + - التأكد من وجود دليل الإخراج قبل الكتابة في قالب التدفق + - رفع litellm إلى >=1.83.0 لمعالجة CVE-2026-35030 + - إزالة حقل فهرسة SEO الذي يتسبب في عرض الصفحة العربية بشكل غير صحيح + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.0 + - تحديث أدلة البدء السريع والتثبيت لتحسين الوضوح + - إضافة قسم مزودي التخزين، تصدير JsonProvider + - إضافة دليل علامة AMP التدريبية + + ### إعادة الهيكلة + - تنظيف واجهة برمجة تطبيقات نقاط التحقق + - إزالة CodeInterpreterTool وإهمال معلمات تنفيذ الكود + + ## المساهمون + + @alex-clawd, @github-actions[bot], @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide + + + + + ## v1.14.0a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0a4) + + ## ما الذي تغير + + ### الميزات + - إضافة guardrail_type و name لتمييز الآثار + - إضافة SqliteProvider لتخزين نقاط التحقق + - إضافة CheckpointConfig للتخزين التلقائي لنقاط التحقق + - تنفيذ نقاط التحقق لحالة التشغيل، نظام الأحداث، وإعادة هيكلة المنفذ + + ### إصلاحات الأخطاء + - استبعاد متجهات التضمين من تسلسل الذاكرة لتوفير الرموز + - رفع litellm إلى >=1.83.0 لمعالجة CVE-2026-35030 + + ### الوثائق + - تحديث أدلة البدء السريع والتثبيت لتحسين الوضوح + - إضافة قسم مقدمي التخزين وتصدير JsonProvider + + ### الأداء + - استخدام JSONB لعمود بيانات نقاط التحقق + + ### إعادة الهيكلة + - إزالة CodeInterpreterTool وإهمال معلمات تنفيذ الكود + + ## المساهمون + + @alex-clawd, @github-actions[bot], @greysonlalonde, @joaomdmoura, @lorenzejay, @lucasgomide + + + + + ## v1.14.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0a3) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.0a2 + + ## المساهمون + + @joaomdmoura + + + + + ## v1.14.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0a2) + + # ملاحظات الإصدار 1.14.0a2 + + ## التعليمات: + - ترجم جميع عناوين الأقسام والوصف بشكل طبيعي + - احتفظ بتنسيق markdown (##، ###، -، إلخ) كما هو + - احتفظ بجميع الأسماء الصحيحة، ومعرفات الشيفرة، وأسماء الفئات، والمصطلحات التقنية دون تغيير + (مثل "CrewAI"، "LiteAgent"، "ChromaDB"، "MCP"، "@username") + - احتفظ بقسم ## المساهمون وأسماء مستخدمي GitHub كما هي + - لا تضف أو تزيل أي محتوى، فقط ترجم + + ## المميزات الجديدة + - تمت إضافة دعم لـ "ChromaDB" لتحسين أداء قاعدة البيانات. + - تحسينات على "LiteAgent" لزيادة الكفاءة. + + ## الإصلاحات + - إصلاح مشكلة تتعلق بـ "MCP" التي كانت تؤدي إلى تعطل التطبيق. + - معالجة الأخطاء المتعلقة بواجهة المستخدم في "CrewAI". + + ## المساهمون + - @username1 + - @username2 + - @username3 + + + + + ## v1.13.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0) + + ## ما الذي تغير + + ### الميزات + - إضافة نموذج RuntimeState RootModel لتوحيد تسلسل الحالة + - تعزيز مستمع الأحداث مع نطاقات جديدة للقياس عن أحداث المهارة والذاكرة + - إضافة امتداد A2UI مع دعم v0.8/v0.9، والمخططات، والوثائق + - إصدار بيانات استخدام الرموز في حدث LLMCallCompletedEvent + - تحديث تلقائي لمستودع اختبار النشر أثناء الإصدار + - تحسين مرونة الإصدار المؤسسي وتجربة المستخدم + + ### إصلاحات الأخطاء + - إضافة بيانات اعتماد مستودع الأدوات إلى تثبيت crewai + - إضافة بيانات اعتماد مستودع الأدوات إلى بناء uv في نشر الأدوات + - تمرير بيانات التعريف عبر الإعدادات بدلاً من معلمات الأدوات + - معالجة نماذج GPT-5.x التي لا تدعم معلمة API `stop` + - إضافة GPT-5 وسلسلة o إلى بادئات الرؤية متعددة الوسائط + - مسح ذاكرة التخزين المؤقت uv للحزم التي تم نشرها حديثًا في الإصدار المؤسسي + - تحديد lancedb أقل من 0.30.1 لضمان التوافق مع Windows + - إصلاح مستويات أذونات RBAC لتتناسب مع خيارات واجهة المستخدم الفعلية + - إصلاح عدم الدقة في قدرات الوكيل عبر جميع اللغات + + ### الوثائق + - إضافة فيديو توضيحي لمهارات وكيل البرمجة إلى صفحات البدء + - إضافة دليل شامل لتكوين SSO + - إضافة مصفوفة شاملة لأذونات RBAC ودليل النشر + - تحديث سجل التغييرات والإصدار إلى v1.13.0 + + ### الأداء + - تقليل الحمل الزائد للإطار باستخدام حافلة الأحداث الكسولة، وتخطي التتبع عند تعطيله + + ### إعادة الهيكلة + - تحويل Flow إلى Pydantic BaseModel + - تحويل فئات LLM إلى Pydantic BaseModel + - استبدال InstanceOf[T] بتعليقات نوع عادية + - إزالة دليل LLM الخاص بالطرف الثالث غير المستخدم + + ## المساهمون + + @alex-clawd, @dependabot[bot], @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @thiagomoretto + + + + + ## v1.13.0a7 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a7) + + ## ما الذي تغير + + ### الميزات + - إضافة امتداد A2UI مع دعم v0.8/v0.9، والمخططات، والوثائق + + ### إصلاحات الأخطاء + - إصلاح بادئات الرؤية متعددة الأنماط عن طريق إضافة GPT-5 وسلسلة o + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a6 + + ## المساهمون + + @alex-clawd, @greysonlalonde, @joaomdmoura + + + + + ## v1.13.0a6 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a6) + + ## ما الذي تغير + + ### الوثائق + - إصلاح مستويات أذونات RBAC لتتوافق مع خيارات واجهة المستخدم الفعلية (#5210) + - تحديث سجل التغييرات والإصدار لـ v1.13.0a5 (#5200) + + ### الأداء + - تقليل عبء العمل على الإطار من خلال تنفيذ حافلة أحداث كسولة وتجاوز التتبع عند تعطيله (#5187) + + ## المساهمون + + @alex-clawd, @joaomdmoura, @lucasgomide + + + + + ## v1.13.0a5 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a5) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a4 + + ## المساهمون + + @greysonlalonde, @joaomdmoura + + + + + ## v1.13.0a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a4) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a3 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.13.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a3) + + ## ما الذي تغير + + ### الميزات + - إصدار بيانات استخدام الرمز في LLMCallCompletedEvent + - استخراج ونشر بيانات الأداة إلى AMP + + ### إصلاح الأخطاء + - التعامل مع نماذج GPT-5.x التي لا تدعم معلمة API `stop` + + ### الوثائق + - إصلاح عدم الدقة في قدرات الوكيل عبر جميع اللغات + - إضافة نظرة عامة على قدرات الوكيل وتحسين وثائق المهارات + - إضافة دليل شامل لتكوين SSO + - تحديث سجل التغييرات والإصدار لـ v1.13.0rc1 + + ### إعادة الهيكلة + - تحويل Flow إلى Pydantic BaseModel + - تحويل فئات LLM إلى Pydantic BaseModel + - استبدال InstanceOf[T] بتعليقات نوع عادية + - إزالة الطرق غير المستخدمة + + ## المساهمون + + @dependabot[bot], @greysonlalonde, @iris-clawd, @lorenzejay, @lucasgomide, @thiagomoretto + + + + + ## v1.13.0rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a2 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.13.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2) + + ## ما الذي تغير + + ### الميزات + - تحديث تلقائي لمستودع اختبار النشر أثناء الإصدار + - تحسين مرونة إصدار المؤسسات وتجربة المستخدم + + ### الوثائق + - تحديث سجل التغييرات والإصدار للإصدار v1.13.0a1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.13.0a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح الروابط المعطلة في سير العمل الوثائقي عن طريق تثبيت Node على LTS 22 + - مسح ذاكرة التخزين المؤقت لـ uv للحزم المنشورة حديثًا في الإصدار المؤسسي + + ### الوثائق + - إضافة مصفوفة شاملة لأذونات RBAC ودليل النشر + - تحديث سجل التغييرات والإصدار للإصدار v1.12.2 + + ## المساهمون + + @greysonlalonde, @iris-clawd, @joaomdmoura + + + + + ## v1.12.2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2) + + ## ما الذي تغير + + ### الميزات + - إضافة مرحلة إصدار المؤسسات إلى إصدار أدوات المطورين + + ### إصلاحات الأخطاء + - الحفاظ على قيمة إرجاع الطريقة كإخراج تدفق لـ @human_feedback مع emit + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.1 + - مراجعة سياسة الأمان وتعليمات الإبلاغ + + ## المساهمون + + @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech + + + + + ## v1.12.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1) + + ## ما الذي تغير + + ### الميزات + - إضافة request_id إلى HumanFeedbackRequestedEvent + - إضافة Qdrant Edge كخلفية تخزين لنظام الذاكرة + - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات + - إضافة دعم اللغة العربية إلى سجل التغييرات وأدوات الإصدار + - إضافة ترجمة باللغة العربية الفصحى لجميع الوثائق + - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر + - إضافة مهارات الوكيل + - تنفيذ root_scope تلقائيًا لعزل الذاكرة الهيكلية + - تنفيذ مزودين متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope) + + ### إصلاحات الأخطاء + - إصلاح بيانات اعتماد غير صحيحة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + - إصلاح حفظ ذاكرة الوكيل + - حل جميع أخطاء mypy الصارمة عبر حزمة crewai + - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta + - إصلاح خطأ القيمة عند عدم دعم الملفات + - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق + - إصلاح جميع أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات النوع في CI + - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6) + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0 + - إضافة CONTRIBUTING.md + - إضافة دليل لاستخدام CrewAI بدون LiteLLM + + ## المساهمون + + @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @lucasgomide، @nicoferdi96 + + + + + ## v1.12.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة + - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات + - إضافة دعم اللغة العربية لسجل التغييرات وأدوات الإصدار + - إضافة ترجمة اللغة العربية الفصحى لجميع الوثائق + - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر + - تنفيذ مهارات الوكيل + - تنفيذ نطاق الجذر التلقائي لعزل الذاكرة الهرمية + - تنفيذ موفري خدمات متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope) + + ### إصلاح الأخطاء + - إصلاح بيانات الاعتماد السيئة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + - حل أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات نوع CI + - حل جميع أخطاء mypy الصارمة عبر حزمة crewai-tools + - حل جميع أخطاء mypy عبر حزمة crewai + - إصلاح حفظ الذاكرة في الوكيل + - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta + - رفع خطأ القيمة عند عدم دعم الملفات + - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق + - استخدام فحص None بدلاً من isinstance للذاكرة في تعلم التغذية الراجعة البشرية + - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6) + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0 + - إضافة CONTRIBUTING.md + - إضافة دليل لاستخدام CrewAI بدون LiteLLM + + ### إعادة الهيكلة + - إعادة هيكلة لتجنب تكرار تنفيذ المهام المتزامنة / غير المتزامنة وبدء التشغيل في الوكيل + - تبسيط الأنابيب الداخلية من litellm (عد الرموز، ردود النداء، اكتشاف الميزات، الأخطاء) + + ## المساهمون + + @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @nicoferdi96 + + + + + ## v1.12.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح بيانات الاعتماد الخاطئة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0a2 + + ## المساهمون + + @akaKuruma, @greysonlalonde + + + + + ## v1.12.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a2) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0a1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.12.0a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a1) + + ## ما الذي تغير + + ### الميزات + - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات + - إضافة دعم اللغة العربية لسجل التغييرات وأدوات الإصدار + - إضافة ترجمة اللغة العربية الفصحى لجميع الوثائق + - إضافة مزودي خدمات متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope) + - إضافة مهارات الوكيل + - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر + - تنفيذ نطاق الجذر التلقائي لعزل الذاكرة الهيكلية + + ### إصلاح الأخطاء + - إصلاح حفظ ذاكرة الوكيل + - حل أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات نوع CI + - حل جميع أخطاء mypy الصارمة عبر حزمة crewai-tools + - حل جميع أخطاء mypy عبر حزمة crewai + - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta + - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6) + - رفع خطأ القيمة عند عدم دعم الملفات + - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق + + ### الوثائق + - إضافة CONTRIBUTING.md + - إضافة دليل لاستخدام CrewAI بدون LiteLLM + - تحديث سجل التغييرات والإصدار لـ v1.11.1 + + ### إعادة الهيكلة + - إعادة هيكلة لإزالة التكرار في تنفيذ المهام المتزامنة وغير المتزامنة وبدء التشغيل في الوكيل + - فصل الأنابيب الداخلية عن litellm (عد الرموز، ردود الفعل، اكتشاف الميزات، الأخطاء) + + ## المساهمون + + @alex-clawd، @greysonlalonde، @iris-clawd، @lorenzejay، @nicoferdi96 + + + + + ## v1.11.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.1) + + ## ما تغيّر + + ### الميزات + - إضافة مُسلسِل flow_structure() لفحص فئة Flow. + + ### إصلاحات الأخطاء + - إصلاح ثغرات أمنية بتحديث pypdf و tinytag و langchain-core. + - الحفاظ على تهيئة LLM الكاملة عبر استئناف HITL لمزودي غير OpenAI. + - منع اجتياز المسار في FileWriterTool. + - إصلاح انهيار lock_store عندما لا تكون حزمة redis مثبتة. + - تمرير cache_function من BaseTool إلى CrewStructuredTool. + + ### التوثيق + - إضافة دليل نشر الأدوات المخصصة مع الترجمات. + - تحديث سجل التغييرات والإصدار لـ v1.11.0. + - إضافة توثيق مستمعي الأحداث المفقود. + + ### إعادة الهيكلة + - استبدال urllib بـ requests في محمّل PDF. + - استبدال حقول callback والنموذج من نوع Any بأنواع قابلة للتسلسل. + + ## المساهمون + + @alex-clawd, @danielfsbarreto, @dependabot[bot], @greysonlalonde, @lorenzejay, @lucasgomide, @mattatcha, @theCyberTech, @vinibrsl + + + + + ## v1.11.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.0) + + ## ما تغيّر + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.11.0rc2 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.11.0rc2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.0rc2) + + ## ما تغيّر + + ### إصلاحات الأخطاء + - تحسين معالجة استجابات LLM والتسلسل. + - ترقية الاعتماديات الانتقالية المعرضة للخطر (authlib، PyJWT، snowflake-connector-python). + - استبدال `os.system` بـ `subprocess.run` في تثبيت pip بالوضع غير الآمن. + + ### التوثيق + - تحديث صفحة أداة Exa Search بتسمية ووصف وخيارات تهيئة محسّنة. + - إضافة خوادم MCP المخصصة في دليل الإرشادات. + - تحديث توثيق جامعي OTEL. + - تحديث توثيق MCP. + - تحديث سجل التغييرات والإصدار لـ v1.11.0rc1. + + ## المساهمون + + @10ishq, @greysonlalonde, @joaomdmoura, @lucasgomide, @mattatcha, @theCyberTech, @vinibrsl + + + + + ## v1.11.0rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.0rc1) + + ## ما تغيّر + + ### الميزات + - إضافة مصادقة رمز Plus API في a2a + - تنفيذ نمط التخطيط والتنفيذ + + ### إصلاحات الأخطاء + - حل مشكلة هروب صندوق حماية مفسر الكود + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.2rc2 + + ## المساهمون + + @Copilot, @greysonlalonde, @lorenzejay, @theCyberTech + + + + + ## v1.10.2rc2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.2rc2) + + ## ما تغيّر + + ### إصلاحات الأخطاء + - إزالة الأقفال الحصرية من عمليات التخزين للقراءة فقط + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.2rc1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.10.2rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.2rc1) + + ## ما تغيّر + + ### الميزات + - إضافة أمر الإصدار وتشغيل نشر PyPI + + ### إصلاحات الأخطاء + - إصلاح القفل الآمن عبر العمليات والخيوط للإدخال/الإخراج غير المحمي + - نشر contextvars عبر جميع حدود الخيوط والمنفذين + - نشر ContextVars إلى خيوط المهام غير المتزامنة + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.2a1 + + ## المساهمون + + @danglies007, @greysonlalonde + + + + + ## v1.10.2a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.2a1) + + ## ما تغيّر + + ### الميزات + - إضافة دعم البحث عن الأدوات وتوفير الرموز وحقن الأدوات المناسبة ديناميكيًا أثناء التنفيذ لـ Anthropic. + - تقديم المزيد من أدوات Brave Search. + - إنشاء إجراء للإصدارات الليلية. + + ### إصلاحات الأخطاء + - إصلاح LockException تحت التنفيذ المتزامن متعدد العمليات. + - حل مشكلات تجميع نتائج الأدوات المتوازية في رسالة مستخدم واحدة. + - معالجة حلول أدوات MCP والقضاء على جميع الاتصالات المشتركة القابلة للتغيير. + - تحديث معالجة معاملات LLM في دالة human_feedback. + - إضافة طرق list/dict المفقودة إلى LockedListProxy و LockedDictProxy. + - نشر سياق contextvars إلى خيوط استدعاء الأدوات المتوازية. + - ترقية اعتمادية gitpython إلى >=3.1.41 لحل ثغرة اجتياز مسار CVE. + + ### إعادة الهيكلة + - إعادة هيكلة فئات الذاكرة لتكون قابلة للتسلسل. + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.1. + + ## المساهمون + + @akaKuruma, @github-actions[bot], @giulio-leone, @greysonlalonde, @joaomdmoura, @jonathansampson, @lorenzejay, @lucasgomide, @mattatcha + + + + + ## v1.10.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1) + + ## ما تغيّر + + ### الميزات + - ترقية Gemini GenAI + + ### إصلاحات الأخطاء + - ضبط قيمة مستمع المنفذ لتجنب التكرار + - تجميع أجزاء استجابة الدوال المتوازية في كائن Content واحد في Gemini + - إظهار مخرجات التفكير من نماذج التفكير في Gemini + - تحميل أدوات MCP والمنصة عندما تكون أدوات الوكيل None + - دعم بيئات Jupyter مع حلقات أحداث قيد التشغيل في A2A + - استخدام معرّف مجهول للتتبعات المؤقتة + - تمرير ترويسة plus بشكل مشروط + - تخطي تسجيل معالج الإشارة في الخيوط غير الرئيسية لقياس الأداء عن بعد + - حقن أخطاء الأدوات كملاحظات وحل تعارضات الأسماء + - ترقية pypdf من 4.x إلى 6.7.4 لحل تنبيهات Dependabot + - حل تنبيهات أمان Dependabot الحرجة والعالية + + ### التوثيق + - تحديث توثيق بث webhook + - ضبط لغة التوثيق من AOP إلى AMP + + ### المساهمون + @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta + + diff --git a/docs/v1.15.1/ar/concepts/agent-capabilities.mdx b/docs/v1.15.1/ar/concepts/agent-capabilities.mdx new file mode 100644 index 000000000..f2a1e142c --- /dev/null +++ b/docs/v1.15.1/ar/concepts/agent-capabilities.mdx @@ -0,0 +1,147 @@ +--- +title: "قدرات الوكيل" +description: "فهم الطرق الخمس لتوسيع وكلاء CrewAI: الأدوات، MCP، التطبيقات، المهارات، والمعرفة." +icon: puzzle-piece +mode: "wide" +--- + +## نظرة عامة + +يمكن توسيع وكلاء CrewAI بـ **خمسة أنواع مميزة من القدرات**، كل منها يخدم غرضًا مختلفًا. فهم متى تستخدم كل نوع — وكيف يعملون معًا — هو المفتاح لبناء وكلاء فعّالين. + + + + **دوال قابلة للاستدعاء** — تمنح الوكلاء القدرة على اتخاذ إجراءات. البحث على الويب، عمليات الملفات، استدعاءات API، تنفيذ الكود. + + + **خوادم أدوات عن بُعد** — تربط الوكلاء بخوادم أدوات خارجية عبر Model Context Protocol. نفس تأثير الأدوات، لكن مستضافة خارجيًا. + + + **تكاملات المنصة** — تربط الوكلاء بتطبيقات SaaS (Gmail، Slack، Jira، Salesforce) عبر منصة CrewAI. تعمل محليًا مع رمز تكامل المنصة. + + + **خبرة المجال** — تحقن التعليمات والإرشادات والمواد المرجعية في إرشادات الوكلاء. المهارات تخبر الوكلاء *كيف يفكرون*. + + + **حقائق مُسترجعة** — توفر للوكلاء بيانات من المستندات والملفات وعناوين URL عبر البحث الدلالي (RAG). المعرفة تعطي الوكلاء *ما يحتاجون معرفته*. + + + +--- + +## التمييز الأساسي + +أهم شيء يجب فهمه: **هذه القدرات تنقسم إلى فئتين**. + +### قدرات الإجراء (الأدوات، MCP، التطبيقات) + +تمنح الوكلاء القدرة على **فعل أشياء** — استدعاء APIs، قراءة الملفات، البحث على الويب، إرسال رسائل البريد الإلكتروني. عند التنفيذ، تتحول الأنواع الثلاثة إلى نفس التنسيق الداخلي (مثيلات `BaseTool`) وتظهر في قائمة أدوات موحدة يمكن للوكيل استدعاؤها. + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool + +agent = Agent( + role="Researcher", + goal="Find and compile market data", + backstory="Expert market analyst", + tools=[SerperDevTool(), FileReadTool()], # أدوات محلية + mcps=["https://mcp.example.com/sse"], # أدوات خادم MCP عن بُعد + apps=["gmail", "google_sheets"], # تكاملات المنصة +) +``` + +### قدرات السياق (المهارات، المعرفة) + +تُعدّل **إرشادات** الوكيل — بحقن الخبرة أو التعليمات أو البيانات المُسترجعة قبل أن يبدأ الوكيل في التفكير. لا تمنح الوكلاء إجراءات جديدة؛ بل تُشكّل كيف يفكر الوكلاء وما هي المعلومات التي يمكنهم الوصول إليها. + +```python +from crewai import Agent + +agent = Agent( + role="Security Auditor", + goal="Audit cloud infrastructure for vulnerabilities", + backstory="Expert in cloud security with 10 years of experience", + skills=["./skills/security-audit"], # تعليمات المجال + knowledge_sources=[pdf_source, url_source], # حقائق مُسترجعة +) +``` + +--- + +## متى تستخدم ماذا + +| تحتاج إلى... | استخدم | مثال | +| :------------------------------------------------------- | :---------------- | :--------------------------------------- | +| الوكيل يبحث على الويب | **الأدوات** | `tools=[SerperDevTool()]` | +| الوكيل يستدعي API عن بُعد عبر MCP | **MCP** | `mcps=["https://api.example.com/sse"]` | +| الوكيل يرسل بريد إلكتروني عبر Gmail | **التطبيقات** | `apps=["gmail"]` | +| الوكيل يتبع إجراءات محددة | **المهارات** | `skills=["./skills/code-review"]` | +| الوكيل يرجع لمستندات الشركة | **المعرفة** | `knowledge_sources=[pdf_source]` | +| الوكيل يبحث على الويب ويتبع إرشادات المراجعة | **الأدوات + المهارات** | استخدم كليهما معًا | + +--- + +## دمج القدرات + +في الممارسة العملية، غالبًا ما يستخدم الوكلاء **أنواعًا متعددة من القدرات معًا**. إليك مثال واقعي: + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +# وكيل بحث مجهز بالكامل +researcher = Agent( + role="Senior Research Analyst", + goal="Produce comprehensive market analysis reports", + backstory="Expert analyst with deep industry knowledge", + + # الإجراء: ما يمكن للوكيل فعله + tools=[ + SerperDevTool(), # البحث على الويب + FileReadTool(), # قراءة الملفات المحلية + CodeInterpreterTool(), # تشغيل كود Python للتحليل + ], + mcps=["https://data-api.example.com/sse"], # الوصول لـ API بيانات عن بُعد + apps=["google_sheets"], # الكتابة في Google Sheets + + # السياق: ما يعرفه الوكيل + skills=["./skills/research-methodology"], # كيفية إجراء البحث + knowledge_sources=[company_docs], # بيانات خاصة بالشركة +) +``` + +--- + +## جدول المقارنة + +| الميزة | الأدوات | MCP | التطبيقات | المهارات | المعرفة | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **يمنح الوكيل إجراءات** | ✅ | ✅ | ✅ | ❌ | ❌ | +| **يُعدّل الإرشادات** | ❌ | ❌ | ❌ | ✅ | ✅ | +| **يتطلب كود** | نعم | إعداد فقط | إعداد فقط | Markdown فقط | إعداد فقط | +| **يعمل محليًا** | نعم | يعتمد | نعم (مع متغير بيئة) | غير متاح | نعم | +| **يحتاج مفاتيح API** | لكل أداة | لكل خادم | رمز التكامل | لا | المُضمّن فقط | +| **يُعيَّن على Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` | +| **يُعيَّن على Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` | + +--- + +## تعمّق أكثر + +هل أنت مستعد لمعرفة المزيد عن كل نوع من أنواع القدرات؟ + + + + إنشاء أدوات مخصصة، استخدام كتالوج OSS مع أكثر من 75 خيارًا، تكوين التخزين المؤقت والتنفيذ غير المتزامن. + + + الاتصال بخوادم MCP عبر stdio أو SSE أو HTTP. تصفية الأدوات، تكوين المصادقة. + + + بناء حزم المهارات مع SKILL.md، حقن خبرة المجال، استخدام الكشف التدريجي. + + + إضافة المعرفة من ملفات PDF وCSV وعناوين URL والمزيد. تكوين المُضمّنات والاسترجاع. + + diff --git a/docs/v1.15.1/ar/concepts/agents.mdx b/docs/v1.15.1/ar/concepts/agents.mdx new file mode 100644 index 000000000..685320db2 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/agents.mdx @@ -0,0 +1,383 @@ +--- +title: الوكلاء +description: دليل تفصيلي حول إنشاء وإدارة الوكلاء ضمن إطار عمل CrewAI. +icon: robot +mode: "wide" +--- + +## نظرة عامة على الوكيل + +في إطار عمل CrewAI، الـ `Agent` هو وحدة مستقلة يمكنها: + +- أداء مهام محددة +- اتخاذ قرارات بناءً على دوره وهدفه +- استخدام الأدوات لتحقيق الأهداف +- التواصل والتعاون مع وكلاء آخرين +- الاحتفاظ بذاكرة التفاعلات +- تفويض المهام عند السماح بذلك + + + فكّر في الوكيل كعضو فريق متخصص بمهارات وخبرات ومسؤوليات محددة. + على سبيل المثال، قد يتفوق وكيل `Researcher` في جمع وتحليل المعلومات، + بينما قد يكون وكيل `Writer` أفضل في إنشاء المحتوى. + + + +يتضمن CrewAI AMP منشئ وكلاء مرئي يبسّط إنشاء وتهيئة الوكلاء بدون كتابة كود. صمم وكلاءك بصريًا واختبرهم في الوقت الفعلي. + +![Visual Agent Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +يُمكّن منشئ الوكلاء المرئي من: + +- تهيئة وكلاء بديهية بواجهات نماذج +- اختبار والتحقق في الوقت الفعلي +- مكتبة قوالب مع أنواع وكلاء مهيأة مسبقًا +- تخصيص سهل لخصائص وسلوكيات الوكيل + + +## خصائص الوكيل + +| الخاصية | المعامل | النوع | الوصف | +| :-------------------------------------- | :----------------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------- | +| **الدور** | `role` | `str` | يحدد وظيفة الوكيل وخبرته ضمن الطاقم. | +| **الهدف** | `goal` | `str` | الهدف الفردي الذي يوجه عملية اتخاذ القرار لدى الوكيل. | +| **الخلفية** | `backstory` | `str` | يوفر سياقًا وشخصية للوكيل، مما يثري التفاعلات. | +| **LLM** _(اختياري)_ | `llm` | `Union[str, LLM, Any]` | نموذج اللغة الذي يشغّل الوكيل. افتراضيًا النموذج المحدد في `OPENAI_MODEL_NAME` أو "gpt-4". | +| **الأدوات** _(اختياري)_ | `tools` | `List[BaseTool]` | القدرات أو الوظائف المتاحة للوكيل. افتراضيًا قائمة فارغة. | +| **LLM استدعاء الدوال** _(اختياري)_ | `function_calling_llm` | `Optional[Any]` | نموذج لغة لاستدعاء الأدوات، يتجاوز LLM الطاقم إذا حُدد. | +| **الحد الأقصى للتكرارات** _(اختياري)_ | `max_iter` | `int` | الحد الأقصى للتكرارات قبل أن يقدم الوكيل أفضل إجابته. الافتراضي 20. | +| **الحد الأقصى لـ RPM** _(اختياري)_ | `max_rpm` | `Optional[int]` | الحد الأقصى للطلبات في الدقيقة لتجنب حدود المعدل. | +| **الحد الأقصى لوقت التنفيذ** _(اختياري)_ | `max_execution_time` | `Optional[int]` | الحد الأقصى للوقت (بالثواني) لتنفيذ المهمة. | +| **الوضع المفصل** _(اختياري)_ | `verbose` | `bool` | تفعيل سجلات التنفيذ المفصلة للتصحيح. الافتراضي False. | +| **السماح بالتفويض** _(اختياري)_ | `allow_delegation` | `bool` | السماح للوكيل بتفويض المهام لوكلاء آخرين. الافتراضي False. | +| **دالة الخطوة** _(اختياري)_ | `step_callback` | `Optional[Any]` | دالة تُستدعى بعد كل خطوة للوكيل، تتجاوز دالة الطاقم. | +| **التخزين المؤقت** _(اختياري)_ | `cache` | `bool` | تفعيل التخزين المؤقت لاستخدام الأدوات. الافتراضي True. | +| **قالب النظام** _(اختياري)_ | `system_template` | `Optional[str]` | قالب أمر نظام مخصص للوكيل. | +| **قالب الأمر** _(اختياري)_ | `prompt_template` | `Optional[str]` | قالب أمر مخصص للوكيل. | +| **قالب الاستجابة** _(اختياري)_ | `response_template` | `Optional[str]` | قالب استجابة مخصص للوكيل. | +| **السماح بتنفيذ الكود** _(اختياري)_ | `allow_code_execution` | `Optional[bool]` | تفعيل تنفيذ الكود للوكيل. الافتراضي False. | +| **الحد الأقصى لإعادة المحاولة** _(اختياري)_ | `max_retry_limit` | `int` | الحد الأقصى لإعادات المحاولة عند حدوث خطأ. الافتراضي 2. | +| **احترام نافذة السياق** _(اختياري)_ | `respect_context_window` | `bool` | إبقاء الرسائل تحت حجم نافذة السياق عبر التلخيص. الافتراضي True. | +| **وضع تنفيذ الكود** _(اختياري)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | وضع تنفيذ الكود: 'safe' (باستخدام Docker) أو 'unsafe' (مباشر). الافتراضي 'safe'. | +| **متعدد الوسائط** _(اختياري)_ | `multimodal` | `bool` | ما إذا كان الوكيل يدعم القدرات متعددة الوسائط. الافتراضي False. | +| **حقن التاريخ** _(اختياري)_ | `inject_date` | `bool` | ما إذا كان يتم حقن التاريخ الحالي تلقائيًا في المهام. الافتراضي False. | +| **تنسيق التاريخ** _(اختياري)_ | `date_format` | `str` | سلسلة تنسيق التاريخ عند تفعيل inject_date. الافتراضي "%Y-%m-%d" (تنسيق ISO). | +| **الاستدلال** _(اختياري)_ | `reasoning` | `bool` | ما إذا كان يجب على الوكيل التأمل وإنشاء خطة قبل تنفيذ المهمة. الافتراضي False. | +| **الحد الأقصى لمحاولات الاستدلال** _(اختياري)_ | `max_reasoning_attempts` | `Optional[int]` | الحد الأقصى لمحاولات الاستدلال قبل تنفيذ المهمة. إذا None، سيحاول حتى الاستعداد. | +| **المُضمّن** _(اختياري)_ | `embedder` | `Optional[Dict[str, Any]]` | تهيئة المُضمّن المستخدم من قبل الوكيل. | +| **مصادر المعرفة** _(اختياري)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | مصادر المعرفة المتاحة للوكيل. | +| **استخدام أمر النظام** _(اختياري)_ | `use_system_prompt` | `Optional[bool]` | ما إذا كان يُستخدم أمر النظام (لدعم نموذج o1). الافتراضي True. | + +## إنشاء الوكلاء + +هناك طريقتان شائعتان لإنشاء الوكلاء في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفهم **مباشرة في الكود**. + +### تهيئة JSONC (موصى بها) + +المشاريع الجديدة التي تُنشأ عبر `crewai create crew ` تستخدم تهيئة JSON-first. يُعرّف كل Agent في `agents/.jsonc`، ويحدد `crew.jsonc` أي Agents تدخل في الـ crew. + +```jsonc agents/researcher.jsonc +{ + "role": "{topic} Senior Data Researcher", + "goal": "Uncover cutting-edge developments in {topic}", + "backstory": "You find the most relevant information and present it clearly.", + "llm": "openai/gpt-4o", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +استخدم `{placeholder}` داخل `role` أو `goal` أو `backstory`. ضع القيم الافتراضية في `inputs` داخل `crew.jsonc`؛ وسيطلب `crewai run` أي قيم ناقصة. يمكن وضع حقول السلوك مثل `verbose` و `allow_delegation` و `max_iter` و `memory` و `cache` و `planning_config` في المستوى الأعلى أو داخل `settings`. + + +يدعم JSONC التعليقات والفواصل النهائية. إذا وُجد `agents/.jsonc` و `agents/.json` معًا، يستخدم CrewAI ملف JSONC. + + +### تهيئة YAML الكلاسيكية + +المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew --classic` تستخدم `config/agents.yaml` وفئة `@CrewBase` في `crew.py`. + +تظل تهيئة YAML مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تفضل تعريف الوكلاء من خلال فئة `@CrewBase`. + +بعد إنشاء مشروع كلاسيكي، انتقل إلى ملف `src//config/agents.yaml` وعدّل القالب ليتوافق مع متطلباتك. + + +ستُستبدل المتغيرات في ملفات YAML (مثل `{topic}`) بقيم من مدخلاتك عند تشغيل الطاقم: +```python Code +crew.kickoff(inputs={'topic': 'AI Agents'}) +``` + + +إليك مثالًا على كيفية تهيئة الوكلاء باستخدام YAML: + +```yaml agents.yaml +# src//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 في الكود، أنشئ فئة طاقم ترث من `CrewBase`: + +```python Code +# src//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 + ) +``` + + + يجب أن تتطابق الأسماء المستخدمة في ملفات YAML (`agents.yaml`) مع أسماء + الطرق في كود Python. + + +### تعريف مباشر في الكود + +يمكنك إنشاء الوكلاء مباشرة في الكود بإنشاء فئة `Agent`. إليك مثالًا شاملًا يوضح جميع المعاملات المتاحة: + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool + +# إنشاء وكيل بجميع المعاملات المتاحة +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", + function_calling_llm=None, + verbose=False, + allow_delegation=False, + max_iter=20, + max_rpm=None, + max_execution_time=None, + max_retry_limit=2, + allow_code_execution=False, + code_execution_mode="safe", + respect_context_window=True, + use_system_prompt=True, + multimodal=False, + inject_date=False, + date_format="%Y-%m-%d", + reasoning=False, + max_reasoning_attempts=None, + tools=[SerperDevTool()], + knowledge_sources=None, + embedder=None, + system_template=None, + prompt_template=None, + response_template=None, + step_callback=None, +) +``` + +دعنا نستعرض بعض تركيبات المعاملات الرئيسية لحالات الاستخدام الشائعة: + +#### وكيل بحث أساسي + +```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 +) +``` + +#### وكيل تطوير الكود + +```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", + max_execution_time=300, + max_retry_limit=3 +) +``` + +#### وكيل تحليل طويل المدى + +```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, + function_calling_llm="gpt-4o-mini" +) +``` + +### تفاصيل المعاملات + +#### المعاملات الحرجة + +- `role` و `goal` و `backstory` مطلوبة وتشكّل سلوك الوكيل +- `llm` يحدد نموذج اللغة المستخدم (افتراضي: GPT-4 من OpenAI) + +#### الذاكرة والسياق + +- `memory`: تفعيل للحفاظ على سجل المحادثة +- `respect_context_window`: يمنع مشاكل حد الرموز +- `knowledge_sources`: إضافة قواعد معرفة خاصة بالمجال + +#### التحكم في التنفيذ + +- `max_iter`: الحد الأقصى للمحاولات قبل تقديم أفضل إجابة +- `max_execution_time`: المهلة بالثواني +- `max_rpm`: تحديد معدل استدعاءات API +- `max_retry_limit`: إعادات المحاولة عند الخطأ + +#### تنفيذ الكود + + + `allow_code_execution` و`code_execution_mode` مهجوران. تمت إزالة `CodeInterpreterTool` من `crewai-tools`. استخدم خدمة بيئة معزولة مخصصة مثل [E2B](https://e2b.dev) أو [Modal](https://modal.com) لتنفيذ الكود بأمان. + + +- `allow_code_execution` _(مهجور)_: كان يُمكّن تنفيذ الكود المدمج عبر `CodeInterpreterTool`. +- `code_execution_mode` _(مهجور)_: كان يتحكم في وضع التنفيذ (`"safe"` لـ Docker، `"unsafe"` للتنفيذ المباشر). + +#### الميزات المتقدمة + +- `multimodal`: تفعيل القدرات متعددة الوسائط لمعالجة النص والمحتوى المرئي +- `reasoning`: تمكين الوكيل من التأمل وإنشاء خطط قبل تنفيذ المهام +- `inject_date`: حقن التاريخ الحالي تلقائيًا في أوصاف المهام + +#### القوالب + +- `system_template`: يحدد السلوك الأساسي للوكيل +- `prompt_template`: ينظم تنسيق الإدخال +- `response_template`: ينسّق استجابات الوكيل + + + عند استخدام القوالب المخصصة، تأكد من تعريف كل من `system_template` و + `prompt_template`. `response_template` اختياري لكن يُوصى به + لتنسيق مخرجات متسق. + + +## أدوات الوكيل + +يمكن تجهيز الوكلاء بأدوات متنوعة لتعزيز قدراتهم. يدعم CrewAI أدوات من: + +- [مجموعة أدوات CrewAI](https://github.com/joaomdmoura/crewai-tools) +- [أدوات LangChain](https://python.langchain.com/docs/integrations/tools) + +إليك كيفية إضافة أدوات لوكيل: + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool, WikipediaTools + +# إنشاء الأدوات +search_tool = SerperDevTool() +wiki_tool = WikipediaTools() + +# إضافة أدوات للوكيل +researcher = Agent( + role="AI Technology Researcher", + goal="Research the latest AI developments", + tools=[search_tool, wiki_tool], + verbose=True +) +``` + +## التفاعل المباشر مع الوكيل عبر `kickoff()` + +يمكن استخدام الوكلاء مباشرة بدون المرور بمهمة أو سير عمل طاقم باستخدام طريقة `kickoff()`. يوفر هذا طريقة أبسط للتفاعل مع وكيل عندما لا تحتاج إلى إمكانيات تنسيق الطاقم الكاملة. + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool + +# إنشاء وكيل +researcher = Agent( + role="AI Technology Researcher", + goal="Research the latest AI developments", + tools=[SerperDevTool()], + verbose=True +) + +# استخدام kickoff() للتفاعل مباشرة مع الوكيل +result = researcher.kickoff("What are the latest developments in language models?") + +# الوصول إلى الاستجابة الخام +print(result.raw) +``` + +## اعتبارات مهمة وأفضل الممارسات + +### الأمان وتنفيذ الكود + + + `allow_code_execution` و`code_execution_mode` مهجوران وتمت إزالة `CodeInterpreterTool`. استخدم خدمة بيئة معزولة مخصصة مثل [E2B](https://e2b.dev) أو [Modal](https://modal.com) لتنفيذ الكود بأمان. + + +### تحسين الأداء + +- استخدم `respect_context_window: true` لمنع مشاكل حد الرموز +- عيّن `max_rpm` مناسبًا لتجنب تحديد المعدل +- فعّل `cache: true` لتحسين الأداء للمهام المتكررة +- اضبط `max_iter` و `max_retry_limit` بناءً على تعقيد المهمة + +### إدارة الذاكرة والسياق + +- استفد من `knowledge_sources` للمعلومات الخاصة بالمجال +- هيّئ `embedder` عند استخدام نماذج تضمين مخصصة +- استخدم القوالب المخصصة للتحكم الدقيق في سلوك الوكيل + +### التعاون بين الوكلاء + +- فعّل `allow_delegation: true` عندما يحتاج الوكلاء للعمل معًا +- استخدم `step_callback` لمراقبة وتسجيل تفاعلات الوكلاء +- فكّر في استخدام نماذج LLM مختلفة لأغراض مختلفة + +### توافق النموذج + +- عيّن `use_system_prompt: false` للنماذج القديمة التي لا تدعم رسائل النظام +- تأكد من أن `llm` المختار يدعم الميزات التي تحتاجها diff --git a/docs/v1.15.1/ar/concepts/checkpointing.mdx b/docs/v1.15.1/ar/concepts/checkpointing.mdx new file mode 100644 index 000000000..7cb52ece8 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/checkpointing.mdx @@ -0,0 +1,423 @@ +--- +title: Checkpointing +description: حفظ حالة التنفيذ تلقائيا حتى تتمكن الطواقم والتدفقات والوكلاء من الاستئناف بعد الفشل. +icon: floppy-disk +mode: "wide" +--- + +الـ Checkpointing يحفظ لقطة من حالة التنفيذ أثناء التشغيل بحيث يمكن لطاقم أو تدفق أو وكيل الاستئناف بعد الفشل أو التفرع إلى فرع بديل. + + + + كيف يعمل الـ Checkpointing: الأحداث والتخزين والوراثة. + + + دليل 5 دقائق: تشغيل، إيقاف، استئناف. + + + وصفات مركزة على المهام لسير العمل الشائع. + + + `CheckpointConfig` والأحداث والمزودات وسطر الأوامر. + + + +## الشرح + +### ما هي نقطة الحفظ + +تلتقط نقطة الحفظ كل ما يحتاجه CrewAI لإعادة إنشاء تشغيل أثناء سيره: الحالة الكاملة للطاقم أو التدفق أو الوكيل — التكوين، وذاكرة الوكلاء ومصادر المعرفة، وتقدم المهام، والمخرجات الوسيطة، والحالة الداخلية والسمات — إلى جانب مدخلات الـ kickoff، وسجل الأحداث حتى تلك النقطة، ومعرف نسب يربط نقطة الحفظ بالتشغيل الذي جاءت منه. + +الاستعادة تعيد بناء تلك الحالة وتستمر. تتخطى المهام المكتملة، وتعاد ترطيب الذاكرة والمعرفة، ويعمل العمل التابع على نفس المخرجات التي أنتجها التشغيل الأصلي. التفرع يجري نفس الاستعادة تحت نسب جديد، بحيث يكتب الفرع الجديد والتشغيل الأصلي نقاط الحفظ جنبا إلى جنب دون أن يطمس أحدهما الآخر. + +### متى تكتب نقاط الحفظ + +الـ Checkpointing مدفوع بالأحداث. يشترك وقت التشغيل في الأحداث التي تحددها عبر `on_events` ويكتب نقطة حفظ عند إطلاق أحدها. الافتراضي `task_completed` ينتج نقطة حفظ لكل مهمة منتهية — توازن معقول بين الدقة واستخدام القرص. الأحداث عالية التردد مثل `llm_call_completed` متاحة للاستعادة الدقيقة لكنها تكتب ملفات أكثر بكثير. + +### التخزين + +يتضمن CrewAI مزودين: + +- `JsonProvider` يكتب ملفا لكل نقطة حفظ. قابل للقراءة وسهل التفقد. +- `SqliteProvider` يكتب إلى قاعدة بيانات SQLite واحدة. أفضل لنقاط الحفظ عالية التردد. + +كلاهما يحذف أقدم نقاط الحفظ عند تحديد `max_checkpoints`. + + +كتابة نقاط الحفظ بأفضل جهد. فشل نقطة حفظ يسجل لكنه لا يقاطع التشغيل. + + +### نموذج الوراثة + +`Crew` و`Flow` و`Agent` كلها تقبل وسيط `checkpoint`. يرث الأبناء من الأب ما لم يحددوا قيمتهم الخاصة أو يمرروا `False` للانسحاب. فعل الـ Checkpointing مرة واحدة على الطاقم وتشارك كل الوكلاء، أو استبعد وكيلا واحدا بشكل انتقائي. + +## درس تطبيقي: استئناف طاقم فاشل + +هذا الدليل يستغرق حوالي 5 دقائق. ستشغل طاقما بمهمتين، توقفه في المنتصف، ثم تستأنف من نقطة الحفظ المحفوظة. + + + + ```python + from crewai import Agent, Crew, Task + + researcher = Agent(role="Researcher", goal="Research", backstory="Expert") + writer = Agent(role="Writer", goal="Write", backstory="Expert") + + crew = Crew( + agents=[researcher, writer], + tasks=[ + Task(description="Research AI trends", agent=researcher, expected_output="bullets"), + Task(description="Write a summary", agent=writer, expected_output="paragraph"), + ], + checkpoint=True, + ) + ``` + + + ```python + result = crew.kickoff() + ``` + + اضغط `Ctrl+C` بعد انتهاء المهمة الأولى. في `./.checkpoints/`، الملف بصيغة `_.json` هو نقطة الحفظ. + + + ```python + from crewai import CheckpointConfig + + result = crew.kickoff( + from_checkpoint=CheckpointConfig( + restore_from="./.checkpoints/_.json", + ), + ) + ``` + + يتم تخطي مهمة البحث، ويعمل الكاتب على مخرجات البحث المحفوظة، وينتهي الطاقم. + + + +## ادلة عملية + + + + ```python + crew = Crew(agents=[...], tasks=[...], checkpoint=True) + ``` + + يكتب إلى `./.checkpoints/` عند كل `task_completed`. + + + + ```python + from crewai import Crew, CheckpointConfig + + crew = Crew( + agents=[...], + tasks=[...], + checkpoint=CheckpointConfig( + location="./my_checkpoints", + on_events=["task_completed", "crew_kickoff_completed"], + max_checkpoints=5, + ), + ) + ``` + + + + + ```python JsonProvider + from crewai import Crew, CheckpointConfig + from crewai.state import JsonProvider + + crew = Crew( + agents=[...], + tasks=[...], + checkpoint=CheckpointConfig( + location="./my_checkpoints", + provider=JsonProvider(), + max_checkpoints=5, + ), + ) + ``` + ```python SqliteProvider + from crewai import Crew, CheckpointConfig + from crewai.state import SqliteProvider + + crew = Crew( + agents=[...], + tasks=[...], + checkpoint=CheckpointConfig( + location="./.checkpoints.db", + provider=SqliteProvider(), + max_checkpoints=50, + ), + ) + ``` + + + + SQLite يفعل وضع journal WAL للقراءات المتزامنة. يفضل لنقاط الحفظ عالية التردد. + + + + + ```python + crew = Crew( + agents=[ + Agent(role="Researcher", ...), + Agent(role="Writer", ..., checkpoint=False), + ], + tasks=[...], + checkpoint=True, + ) + ``` + + + + `fork()` يستعيد نقطة حفظ تحت نسب جديد بحيث لا يتصادم التشغيل الجديد مع الأصلي. + + ```python + config = CheckpointConfig(restore_from="./my_checkpoints/.json") + crew = Crew.fork(config, branch="experiment-a") + result = crew.kickoff(inputs={"strategy": "aggressive"}) + ``` + + تسمية `branch` اختيارية؛ يتم إنشاء واحدة إذا أغفلت. + + + + + + ```python + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, write_task, review_task], + checkpoint=CheckpointConfig(location="./crew_cp"), + ) + ``` + + المشغل الافتراضي: `task_completed`. + + + ```python + from crewai.flow.flow import Flow, start, listen + from crewai import CheckpointConfig + + class MyFlow(Flow): + @start() + def step_one(self): + return "data" + + @listen(step_one) + def step_two(self, data): + return process(data) + + flow = MyFlow( + checkpoint=CheckpointConfig( + location="./flow_cp", + on_events=["method_execution_finished"], + ), + ) + result = flow.kickoff() + ``` + + + ```python + agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + checkpoint=CheckpointConfig( + location="./agent_cp", + on_events=["lite_agent_execution_completed"], + ), + ) + result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}]) + ``` + + + + + + سجل معالجا على أي حدث واستدع `state.checkpoint()`. + + + ```python Sync + from __future__ import annotations + + from typing import TYPE_CHECKING, Any + + from crewai.events.event_bus import crewai_event_bus + from crewai.events.types.llm_events import LLMCallCompletedEvent + + if TYPE_CHECKING: + from crewai.state.runtime import RuntimeState + + + @crewai_event_bus.on(LLMCallCompletedEvent) + def on_llm_done(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None: + path = state.checkpoint("./my_checkpoints") + print(f"تم حفظ نقطة الحفظ: {path}") + ``` + ```python Async + from __future__ import annotations + + from typing import TYPE_CHECKING, Any + + from crewai.events.event_bus import crewai_event_bus + from crewai.events.types.llm_events import LLMCallCompletedEvent + + if TYPE_CHECKING: + from crewai.state.runtime import RuntimeState + + + @crewai_event_bus.on(LLMCallCompletedEvent) + async def on_llm_done_async(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None: + path = await state.acheckpoint("./my_checkpoints") + print(f"تم حفظ نقطة الحفظ: {path}") + ``` + + + يتم تمرير وسيط `state` تلقائيا عندما يقبل المعالج ثلاثة معاملات. راجع [Event Listeners](/ar/concepts/event-listener) لقائمة الأحداث الكاملة. + + + + ```bash + crewai checkpoint + crewai checkpoint --location ./my_checkpoints + crewai checkpoint --location ./.checkpoints.db + ``` + + + Checkpoint TUI tree view + + + اللوحة اليسرى تجمع نقاط الحفظ حسب الفرع؛ التفرعات تتداخل تحت أبيها. اختيار نقطة حفظ يفتح لوحة التفاصيل مع بياناتها الوصفية وحالة الكيان وتقدم المهام. **Resume** يكمل التشغيل؛ **Fork** يبدأ فرعا جديدا. + + + Checkpoint detail overview tab + + + لوحة التفاصيل تعرض منطقتين قابلتين للتحرير: + + - **Inputs** — مدخلات الـ kickoff الأصلية، معبأة مسبقا وقابلة للتحرير. + + + Editable kickoff inputs + + + - **مخرجات المهام** — مخرجات المهام المكتملة. تحرير مخرج والضغط على **Fork** يبطل المهام التابعة لتعاد بالسياق المعدل. + + + Editable task outputs + + + + Fork confirmation panel + + + + مفيد لاستكشاف "ماذا لو": تفرع، عدل، راقب. + + + + + ```bash + crewai checkpoint list ./my_checkpoints + crewai checkpoint info ./my_checkpoints/.json + crewai checkpoint info ./.checkpoints.db + ``` + + + +## المرجع + +### `CheckpointConfig` + + + وجهة التخزين. مجلد لـ `JsonProvider`، مسار ملف قاعدة بيانات لـ `SqliteProvider`. + + + + أنواع الأحداث التي تطلق نقطة حفظ. `CheckpointEventType` هو `Literal` — مدقق الأنواع يكمل تلقائيا ويرفض القيم غير المدعومة. راجع [أنواع الأحداث](#أنواع-الأحداث) للقائمة الكاملة. + + + + واجهة التخزين. `JsonProvider` أو `SqliteProvider`. + + + + الحد الاقصى لنقاط الحفظ المحتفظ بها. الأقدم تحذف بعد كل كتابة. + + + + نقطة الحفظ المراد استعادتها عند تمريرها عبر `from_checkpoint`. + + +### قيم حقل `checkpoint` + +مقبولة في `Crew` و`Flow` و`Agent`. + + + يرث من الأب. + + + + تفعيل بالإعدادات الافتراضية. + + + + انسحاب صريح. يوقف الوراثة. + + + + إعدادات مخصصة. + + +### أنواع الأحداث + +يقبل `on_events` أي مجموعة من قيم `CheckpointEventType`. الافتراضي `["task_completed"]` يكتب نقطة حفظ لكل مهمة منتهية، و`["*"]` يطابق جميع الأحداث. + + +`["*"]` والأحداث عالية التردد مثل `llm_call_completed` تكتب نقاط حفظ كثيرة وقد تضر بالاداء. استخدمها مع `max_checkpoints`. + + + + +- **Task** — `task_started`, `task_completed`, `task_failed`, `task_evaluation` +- **Crew** — `crew_kickoff_started`, `crew_kickoff_completed`, `crew_kickoff_failed`, `crew_train_started`, `crew_train_completed`, `crew_train_failed`, `crew_test_started`, `crew_test_completed`, `crew_test_failed`, `crew_test_result` +- **Agent** — `agent_execution_started`, `agent_execution_completed`, `agent_execution_error`, `lite_agent_execution_started`, `lite_agent_execution_completed`, `lite_agent_execution_error`, `agent_evaluation_started`, `agent_evaluation_completed`, `agent_evaluation_failed` +- **Flow** — `flow_created`, `flow_started`, `flow_finished`, `flow_paused`, `method_execution_started`, `method_execution_finished`, `method_execution_failed`, `method_execution_paused`, `human_feedback_requested`, `human_feedback_received`, `flow_input_requested`, `flow_input_received` +- **LLM** — `llm_call_started`, `llm_call_completed`, `llm_call_failed`, `llm_stream_chunk`, `llm_thinking_chunk` +- **LLM Guardrail** — `llm_guardrail_started`, `llm_guardrail_completed`, `llm_guardrail_failed` +- **Tool** — `tool_usage_started`, `tool_usage_finished`, `tool_usage_error`, `tool_validate_input_error`, `tool_selection_error`, `tool_execution_error` +- **Memory** — `memory_save_started`, `memory_save_completed`, `memory_save_failed`, `memory_query_started`, `memory_query_completed`, `memory_query_failed`, `memory_retrieval_started`, `memory_retrieval_completed`, `memory_retrieval_failed` +- **Knowledge** — `knowledge_search_query_started`, `knowledge_search_query_completed`, `knowledge_query_started`, `knowledge_query_completed`, `knowledge_query_failed`, `knowledge_search_query_failed` +- **Reasoning** — `agent_reasoning_started`, `agent_reasoning_completed`, `agent_reasoning_failed` +- **MCP** — `mcp_connection_started`, `mcp_connection_completed`, `mcp_connection_failed`, `mcp_tool_execution_started`, `mcp_tool_execution_completed`, `mcp_tool_execution_failed`, `mcp_config_fetch_failed` +- **Observation** — `step_observation_started`, `step_observation_completed`, `step_observation_failed`, `plan_refinement`, `plan_replan_triggered`, `goal_achieved_early` +- **Skill** — `skill_discovery_started`, `skill_discovery_completed`, `skill_loaded`, `skill_activated`, `skill_load_failed` +- **Logging** — `agent_logs_started`, `agent_logs_execution` +- **A2A** — `a2a_delegation_started`, `a2a_delegation_completed`, `a2a_conversation_started`, `a2a_conversation_completed`, `a2a_message_sent`, `a2a_response_received`, `a2a_polling_started`, `a2a_polling_status`, `a2a_push_notification_registered`, `a2a_push_notification_received`, `a2a_push_notification_sent`, `a2a_push_notification_timeout`, `a2a_streaming_started`, `a2a_streaming_chunk`, `a2a_agent_card_fetched`, `a2a_authentication_failed`, `a2a_artifact_received`, `a2a_connection_error`, `a2a_server_task_started`, `a2a_server_task_completed`, `a2a_server_task_canceled`, `a2a_server_task_failed`, `a2a_parallel_delegation_started`, `a2a_parallel_delegation_completed`, `a2a_transport_negotiated`, `a2a_content_type_negotiated`, `a2a_context_created`, `a2a_context_expired`, `a2a_context_idle`, `a2a_context_completed`, `a2a_context_pruned` +- **إشارات النظام** — `SIGTERM`, `SIGINT`, `SIGHUP`, `SIGTSTP`, `SIGCONT` +- **حرف بدل** — `"*"` يطابق جميع الأحداث. + + + +### مزودات التخزين + + + ملف واحد لكل نقطة حفظ بصيغة `_.json` داخل `location`. + + + + ملف قاعدة بيانات واحد في `location` مع journaling WAL. + + +### سطر الأوامر + +| الامر | الغرض | +|:------|:------| +| `crewai checkpoint` | تشغيل TUI؛ كشف التخزين تلقائيا. | +| `crewai checkpoint --location ` | تشغيل TUI على موقع محدد. | +| `crewai checkpoint list ` | سرد نقاط الحفظ. | +| `crewai checkpoint info ` | تفقد ملف نقطة حفظ أو آخر مدخل في قاعدة بيانات SQLite. | diff --git a/docs/v1.15.1/ar/concepts/cli.mdx b/docs/v1.15.1/ar/concepts/cli.mdx new file mode 100644 index 000000000..e89829eb9 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/cli.mdx @@ -0,0 +1,302 @@ +--- +title: واجهة سطر الأوامر +description: تعرّف على كيفية استخدام واجهة سطر أوامر CrewAI للتفاعل مع CrewAI. +icon: terminal +mode: "wide" +--- + + + منذ الإصدار 0.140.0، بدأ CrewAI AMP عملية نقل مزود تسجيل الدخول. + لذلك، تم تحديث تدفق المصادقة عبر CLI. المستخدمون الذين يسجلون الدخول + باستخدام Google، أو الذين أنشأوا حساباتهم بعد 3 يوليو 2025 لن يتمكنوا + من تسجيل الدخول مع الإصدارات القديمة من مكتبة `crewai`. + + +## نظرة عامة + +توفر واجهة سطر أوامر CrewAI مجموعة من الأوامر للتفاعل مع CrewAI، مما يتيح لك إنشاء وتدريب وتشغيل وإدارة الأطقم والتدفقات. + +## التثبيت + +لاستخدام واجهة سطر أوامر CrewAI، تأكد من تثبيت CrewAI: + +```shell Terminal +pip install crewai +``` + +## الاستخدام الأساسي + +الهيكل الأساسي لأمر CrewAI CLI هو: + +```shell Terminal +crewai [COMMAND] [OPTIONS] [ARGUMENTS] +``` + +## الأوامر المتاحة + +### 1. إنشاء + +إنشاء طاقم أو تدفق جديد. + +```shell Terminal +crewai create [OPTIONS] TYPE NAME +``` + +- `TYPE`: اختر بين "crew" أو "flow" +- `NAME`: اسم الطاقم أو التدفق + +مثال: + +```shell Terminal +crewai create crew my_new_crew +crewai create flow my_new_flow +``` + +افتراضيًا، ينشئ `crewai create crew` مشروعًا JSON-first يحتوي على `crew.jsonc` و `agents/*.jsonc`. استخدم `crewai create crew my_new_crew --classic` فقط إذا أردت البنية القديمة Python/YAML مع `crew.py` و `config/agents.yaml` و `config/tasks.yaml`. + +### 2. الإصدار + +عرض الإصدار المثبت من CrewAI. + +```shell Terminal +crewai version [OPTIONS] +``` + +- `--tools`: (اختياري) عرض الإصدار المثبت من أدوات CrewAI + +### 3. التدريب + +تدريب الطاقم لعدد محدد من التكرارات. + +```shell Terminal +crewai train [OPTIONS] +``` + +- `-n, --n_iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5) +- `-f, --filename TEXT`: مسار ملف مخصص للتدريب (افتراضي: "trained_agents_data.pkl") + +### 4. الإعادة + +إعادة تنفيذ الطاقم من مهمة محددة. + +```shell Terminal +crewai replay [OPTIONS] +``` + +- `-t, --task_id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة + +### 5. سجل مخرجات المهام + +استرجاع أحدث مخرجات مهام crew.kickoff(). + +```shell Terminal +crewai log-tasks-outputs +``` + +### 6. إعادة تعيين الذاكرة + +إعادة تعيين ذاكرة الطاقم (طويلة، قصيرة، الكيانات، أحدث مخرجات التشغيل). + +```shell Terminal +crewai reset-memories [OPTIONS] +``` + +- `-l, --long`: إعادة تعيين الذاكرة طويلة المدى +- `-s, --short`: إعادة تعيين الذاكرة قصيرة المدى +- `-e, --entities`: إعادة تعيين ذاكرة الكيانات +- `-k, --kickoff-outputs`: إعادة تعيين أحدث مخرجات التشغيل +- `-kn, --knowledge`: إعادة تعيين تخزين المعرفة +- `-akn, --agent-knowledge`: إعادة تعيين تخزين معرفة الوكيل +- `-a, --all`: إعادة تعيين جميع الذاكرات + +### 7. الاختبار + +اختبار الطاقم وتقييم النتائج. + +```shell Terminal +crewai test [OPTIONS] +``` + +- `-n, --n_iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3) +- `-m, --model TEXT`: نموذج LLM لتشغيل الاختبارات (افتراضي: "gpt-4o-mini") + +### 8. التشغيل + +تشغيل الطاقم أو التدفق. + +```shell Terminal +crewai run +``` + + + بدءًا من الإصدار 0.103.0، يمكن استخدام أمر `crewai run` لتشغيل + كل من الأطقم القياسية والتدفقات. للتدفقات، يكتشف تلقائيًا النوع + من pyproject.toml ويشغّل الأمر المناسب. هذه هي الطريقة الموصى بها + لتشغيل كل من الأطقم والتدفقات. + + +### 9. الدردشة + +بدءًا من الإصدار `0.98.0`، عند تشغيل أمر `crewai chat`، تبدأ جلسة تفاعلية مع طاقمك. سيرشدك المساعد الذكي بطلب المدخلات اللازمة لتنفيذ الطاقم. بمجرد توفير جميع المدخلات، سينفذ الطاقم مهامه. + +```shell Terminal +crewai chat +``` + + +مهم: عيّن خاصية `chat_llm` في تعريف الـ crew لتفعيل هذا الأمر. + +للـ crews بنمط JSON-first، أضفها إلى `crew.jsonc`: + +```jsonc +{ + "name": "My Crew", + "agents": ["researcher"], + "tasks": [], + "chat_llm": "openai/gpt-4o" +} +``` + +للـ crews الكلاسيكية Python/YAML، عيّنها في `crew.py`: + +```python +@crew +def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + chat_llm="gpt-4o", + ) +``` + + +### 10. النشر + +نشر الطاقم أو التدفق إلى [CrewAI AMP](https://app.crewai.com). + +- **المصادقة**: تحتاج لتكون مصادقًا للنشر إلى CrewAI AMP. + + ```shell Terminal + crewai login + ``` + +- **إنشاء نشر**: + ```shell Terminal + crewai deploy create + ``` + +- **نشر الطاقم**: + ```shell Terminal + crewai deploy push + ``` + +- **حالة النشر**: + ```shell Terminal + crewai deploy status + ``` + +- **سجلات النشر**: + ```shell Terminal + crewai deploy logs + ``` + +- **عرض النشرات**: + ```shell Terminal + crewai deploy list + ``` + +- **حذف النشر**: + ```shell Terminal + crewai deploy remove + ``` + +### 11. إدارة المؤسسة + +إدارة مؤسسات CrewAI AMP. + +```shell Terminal +crewai org [COMMAND] [OPTIONS] +``` + +- `list`: عرض جميع المؤسسات +- `current`: عرض المؤسسة النشطة حاليًا +- `switch`: التبديل إلى مؤسسة محددة + +### 12. تسجيل الدخول + +المصادقة مع CrewAI AMP باستخدام تدفق رمز الجهاز الآمن. + +```shell Terminal +crewai login +``` + +### 13. إدارة التهيئة + +إدارة إعدادات تهيئة CLI لـ CrewAI. + +```shell Terminal +crewai config [COMMAND] [OPTIONS] +``` + +- `list`: عرض جميع معاملات التهيئة +- `set`: تعيين معامل تهيئة +- `reset`: إعادة تعيين جميع المعاملات إلى القيم الافتراضية + +### 14. إدارة التتبع + +إدارة تفضيلات جمع التتبع لعمليات الطاقم والتدفق. + +```shell Terminal +crewai traces [COMMAND] +``` + +- `enable`: تفعيل جمع التتبع +- `disable`: تعطيل جمع التتبع +- `status`: عرض حالة جمع التتبع الحالية + +#### كيف يعمل التتبع + +يتم التحكم في جمع التتبع بفحص ثلاثة إعدادات بترتيب الأولوية: + +1. **علامة صريحة في الكود** (الأولوية الأعلى): + ```python + crew = Crew(agents=[...], tasks=[...], tracing=True) # تفعيل دائمًا + crew = Crew(agents=[...], tasks=[...], tracing=False) # تعطيل دائمًا + crew = Crew(agents=[...], tasks=[...]) # فحص الأولويات الأدنى + ``` + +2. **متغير البيئة** (الأولوية الثانية): + ```env + CREWAI_TRACING_ENABLED=true + ``` + +3. **تفضيل المستخدم** (الأولوية الأدنى): + ```shell Terminal + crewai traces enable + ``` + + +**لتفعيل التتبع**، استخدم أيًا من هذه الطرق: +- عيّن `tracing=True` في كود الطاقم/التدفق، أو +- أضف `CREWAI_TRACING_ENABLED=true` إلى ملف `.env`، أو +- شغّل `crewai traces enable` + +**لتعطيل التتبع**، استخدم أيًا من هذه الطرق: +- عيّن `tracing=False` في كود الطاقم/التدفق، أو +- أزل أو عيّن `false` لمتغير `CREWAI_TRACING_ENABLED`، أو +- شغّل `crewai traces disable` + + + + يتعامل CrewAI CLI مع المصادقة لمستودع الأدوات تلقائيًا عند + إضافة حزم إلى مشروعك. فقط أضف `crewai` قبل أي أمر `uv` + لاستخدامه. مثلًا `crewai uv add requests`. + + + + تُخزن إعدادات التهيئة في `~/.config/crewai/settings.json`. بعض + الإعدادات مثل اسم المؤسسة ومعرّفها للقراءة فقط وتُدار من خلال + أوامر المصادقة والمؤسسة. + diff --git a/docs/v1.15.1/ar/concepts/collaboration.mdx b/docs/v1.15.1/ar/concepts/collaboration.mdx new file mode 100644 index 000000000..a0cae9139 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/collaboration.mdx @@ -0,0 +1,363 @@ +--- +title: التعاون +description: كيفية تمكين الوكلاء من العمل معًا وتفويض المهام والتواصل بفعالية داخل فرق CrewAI. +icon: screen-users +mode: "wide" +--- + +## نظرة عامة + +يُمكّن التعاون في CrewAI الوكلاء من العمل معًا كفريق عن طريق تفويض المهام وطرح الأسئلة للاستفادة من خبرات بعضهم البعض. عندما يكون `allow_delegation=True`، يحصل الوكلاء تلقائيًا على أدوات تعاون قوية. + +## البدء السريع: تفعيل التعاون + +```python +from crewai import Agent, Crew, Task + +# تفعيل التعاون للوكلاء +researcher = Agent( + role="Research Specialist", + goal="Conduct thorough research on any topic", + backstory="Expert researcher with access to various sources", + allow_delegation=True, # الإعداد الرئيسي للتعاون + 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, # يُمكّن طرح الأسئلة على الوكلاء الآخرين + verbose=True +) + +# يمكن للوكلاء الآن التعاون تلقائيًا +crew = Crew( + agents=[researcher, writer], + tasks=[...], + verbose=True +) +``` + +## كيف يعمل تعاون الوكلاء + +عندما يكون `allow_delegation=True`، يوفر CrewAI تلقائيًا للوكلاء أداتين قويتين: + +### 1. **أداة تفويض العمل** +تسمح للوكلاء بتعيين مهام لزملاء الفريق ذوي الخبرة المحددة. + +```python +# يحصل الوكيل تلقائيًا على هذه الأداة: +# Delegate work to coworker(task: str, context: str, coworker: str) +``` + +### 2. **أداة طرح الأسئلة** +تُمكّن الوكلاء من طرح أسئلة محددة لجمع المعلومات من الزملاء. + +```python +# يحصل الوكيل تلقائيًا على هذه الأداة: +# Ask question to coworker(question: str, context: str, coworker: str) +``` + +## التعاون في الممارسة + +إليك مثالًا كاملًا يوضح تعاون الوكلاء في مهمة إنشاء المحتوى: + +```python +from crewai import Agent, Crew, Task, Process + +# إنشاء وكلاء تعاونيين +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 +) + +# إنشاء مهمة تشجع التعاون +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 # الكاتب يقود، لكن يمكنه تفويض البحث إلى الباحث +) + +# إنشاء طاقم تعاوني +crew = Crew( + agents=[researcher, writer, editor], + tasks=[article_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff() +``` + +## أنماط التعاون + +### النمط 1: بحث ← كتابة ← تحرير +```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] # يحصل على مخرجات البحث كسياق +) + +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] # يحصل على مسودة المقال كسياق +) +``` + +### النمط 2: مهمة واحدة تعاونية +```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 # الوكيل القائد، لكن يمكنه التفويض إلى الباحث +) +``` + +## التعاون الهرمي + +للمشاريع المعقدة، استخدم عملية هرمية مع وكيل مدير: + +```python +from crewai import Agent, Crew, Task, Process + +# وكيل المدير ينسق الفريق +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 +) + +# وكلاء متخصصون +researcher = Agent( + role="Researcher", + goal="Provide accurate research and analysis", + backstory="Expert researcher with deep analytical skills", + allow_delegation=False, # المتخصصون يركزون على خبرتهم + verbose=True +) + +writer = Agent( + role="Writer", + goal="Create compelling content", + backstory="Skilled writer who creates engaging content", + allow_delegation=False, + verbose=True +) + +# مهمة يقودها المدير +project_task = Task( + description="Create a comprehensive market analysis report with recommendations", + expected_output="Executive summary, detailed analysis, and strategic recommendations", + agent=manager # المدير سيفوّض إلى المتخصصين +) + +# طاقم هرمي +crew = Crew( + agents=[manager, researcher, writer], + tasks=[project_task], + process=Process.hierarchical, # المدير ينسق كل شيء + manager_llm="gpt-4o", # تحديد LLM للمدير + verbose=True +) +``` + +## أفضل ممارسات التعاون + +### 1. **تحديد الأدوار بوضوح** +```python +# جيد: أدوار محددة ومتكاملة +researcher = Agent(role="Market Research Analyst", ...) +writer = Agent(role="Technical Content Writer", ...) + +# تجنب: أدوار متداخلة أو غامضة +agent1 = Agent(role="General Assistant", ...) +agent2 = Agent(role="Helper", ...) +``` + +### 2. **تفعيل التفويض الاستراتيجي** +```python +# فعّل التفويض للمنسقين والعامين +lead_agent = Agent( + role="Content Lead", + allow_delegation=True, # يمكنه التفويض إلى المتخصصين + ... +) + +# عطّل للمتخصصين المركّزين (اختياري) +specialist_agent = Agent( + role="Data Analyst", + allow_delegation=False, # يركز على الخبرة الأساسية + ... +) +``` + +### 3. **مشاركة السياق** +```python +# استخدم معامل context لاعتماديات المهام +writing_task = Task( + description="Write article based on research", + agent=writer, + context=[research_task], # يشارك نتائج البحث + ... +) +``` + +### 4. **أوصاف المهام الواضحة** +```python +# أوصاف محددة وقابلة للتنفيذ +Task( + description="""Research competitors in the AI chatbot space. + Focus on: pricing models, key features, target markets. + Provide data in a structured format.""", + ... +) + +# تجنب: أوصاف غامضة لا توجه التعاون +Task(description="Do some research about chatbots", ...) +``` + +## استكشاف أخطاء التعاون وإصلاحها + +### المشكلة: الوكلاء لا يتعاونون +**الأعراض:** يعمل الوكلاء بمعزل، لا يحدث تفويض +```python +# الحل: تأكد من تفعيل التفويض +agent = Agent( + role="...", + allow_delegation=True, # هذا مطلوب! + ... +) +``` + +### المشكلة: كثرة الذهاب والإياب +**الأعراض:** يطرح الوكلاء أسئلة مفرطة، تقدم بطيء +```python +# الحل: وفّر سياقًا أفضل وأدوارًا محددة +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.""", + ... +) +``` + +### المشكلة: حلقات التفويض +**الأعراض:** يفوّض الوكلاء ذهابًا وإيابًا بلا نهاية +```python +# الحل: تسلسل هرمي واضح ومسؤوليات +manager = Agent(role="Manager", allow_delegation=True) +specialist1 = Agent(role="Specialist A", allow_delegation=False) # لا إعادة تفويض +specialist2 = Agent(role="Specialist B", allow_delegation=False) +``` + +## ميزات التعاون المتقدمة + +### قواعد التعاون المخصصة +```python +# تعيين إرشادات تعاون محددة في خلفية الوكيل +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 +) +``` + +### مراقبة التعاون +```python +def track_collaboration(output): + """تتبع أنماط التعاون""" + 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, # مراقبة التعاون + verbose=True +) +``` + +## الذاكرة والتعلم + +تمكين الوكلاء من تذكر التعاونات السابقة: + +```python +agent = Agent( + role="Content Lead", + memory=True, # يتذكر التفاعلات السابقة + allow_delegation=True, + verbose=True +) +``` + +مع تفعيل الذاكرة، يتعلم الوكلاء من التعاونات السابقة ويحسّنون قرارات التفويض بمرور الوقت. + +## الخطوات التالية + +- **جرّب الأمثلة**: ابدأ بمثال التعاون الأساسي +- **جرّب أدوارًا مختلفة**: اختبر تركيبات أدوار وكلاء مختلفة +- **راقب التفاعلات**: استخدم `verbose=True` لرؤية التعاون في العمل +- **حسّن أوصاف المهام**: المهام الواضحة تؤدي إلى تعاون أفضل +- **وسّع النطاق**: جرّب العمليات الهرمية للمشاريع المعقدة + +يحوّل التعاون وكلاء الذكاء الاصطناعي الفرديين إلى فرق قوية يمكنها معالجة التحديات المعقدة ومتعددة الأوجه معًا. diff --git a/docs/v1.15.1/ar/concepts/crews.mdx b/docs/v1.15.1/ar/concepts/crews.mdx new file mode 100644 index 000000000..05f643c90 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/crews.mdx @@ -0,0 +1,245 @@ +--- +title: الأطقم +description: فهم واستخدام الأطقم في إطار عمل CrewAI مع خصائص ووظائف شاملة. +icon: people-group +mode: "wide" +--- + +## نظرة عامة + +يمثل الطاقم في CrewAI مجموعة تعاونية من الوكلاء يعملون معًا لتحقيق مجموعة من المهام. يحدد كل طاقم استراتيجية تنفيذ المهام وتعاون الوكلاء وسير العمل العام. + +## خصائص الطاقم + +| الخاصية | المعامل | الوصف | +| :------------------------------------ | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **المهام** | `tasks` | قائمة المهام المعيّنة للطاقم. | +| **الوكلاء** | `agents` | قائمة الوكلاء الذين يشكلون جزءًا من الطاقم. | +| **العملية** _(اختياري)_ | `process` | تدفق العملية (مثل تسلسلي، هرمي) الذي يتبعه الطاقم. الافتراضي `sequential`. | +| **الوضع المفصل** _(اختياري)_ | `verbose` | مستوى التفصيل في التسجيل أثناء التنفيذ. الافتراضي `False`. | +| **LLM المدير** _(اختياري)_ | `manager_llm` | نموذج اللغة المستخدم بواسطة وكيل المدير في العملية الهرمية. **مطلوب عند استخدام العملية الهرمية.** | +| **LLM استدعاء الدوال** _(اختياري)_ | `function_calling_llm` | إذا مُرر، سيستخدم الطاقم هذا LLM لاستدعاء دوال الأدوات لجميع الوكلاء. يمكن لكل وكيل أن يكون له LLM خاص يتجاوز LLM الطاقم. | +| **التهيئة** _(اختياري)_ | `config` | إعدادات تهيئة اختيارية للطاقم، بتنسيق `Json` أو `Dict[str, Any]`. | +| **الحد الأقصى لـ RPM** _(اختياري)_ | `max_rpm` | الحد الأقصى للطلبات في الدقيقة. الافتراضي `None`. | +| **الذاكرة** _(اختياري)_ | `memory` | تُستخدم لتخزين ذاكرات التنفيذ (قصيرة المدى، طويلة المدى، ذاكرة الكيانات). | +| **التخزين المؤقت** _(اختياري)_ | `cache` | يحدد ما إذا كان يُستخدم تخزين مؤقت لنتائج تنفيذ الأدوات. الافتراضي `True`. | +| **المُضمّن** _(اختياري)_ | `embedder` | تهيئة المُضمّن المستخدم من قبل الطاقم. الافتراضي `{"provider": "openai"}`. | +| **دالة الخطوة** _(اختياري)_ | `step_callback` | دالة تُستدعى بعد كل خطوة لكل وكيل. | +| **دالة المهمة** _(اختياري)_ | `task_callback` | دالة تُستدعى بعد اكتمال كل مهمة. | +| **مشاركة الطاقم** _(اختياري)_ | `share_crew` | ما إذا كنت تريد مشاركة معلومات الطاقم الكاملة وتنفيذه مع فريق CrewAI. | +| **ملف سجل المخرجات** _(اختياري)_ | `output_log_file` | عيّن True لحفظ السجلات كـ logs.txt أو وفّر مسار ملف. الافتراضي `None`. | +| **وكيل المدير** _(اختياري)_ | `manager_agent` | يعيّن وكيلًا مخصصًا سيُستخدم كمدير. | +| **التخطيط** *(اختياري)* | `planning` | يضيف قدرة التخطيط للطاقم. | +| **LLM التخطيط** *(اختياري)* | `planning_llm` | نموذج اللغة المستخدم بواسطة AgentPlanner في عملية التخطيط. | +| **مصادر المعرفة** _(اختياري)_ | `knowledge_sources` | مصادر المعرفة المتاحة على مستوى الطاقم، يمكن لجميع الوكلاء الوصول إليها. | +| **البث** _(اختياري)_ | `stream` | تفعيل مخرجات البث لتلقي تحديثات في الوقت الفعلي. الافتراضي `False`. | + + +**الحد الأقصى لـ RPM للطاقم**: تعيّن خاصية `max_rpm` الحد الأقصى للطلبات في الدقيقة التي يمكن للطاقم تنفيذها لتجنب حدود المعدل وستتجاوز إعدادات `max_rpm` الفردية للوكلاء إذا عيّنتها. + + +## إنشاء الأطقم + +هناك طريقتان رئيسيتان لإنشاء الأطقم في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفها **مباشرة في الكود** للمشاريع الكلاسيكية والحالات المتقدمة. + +### تهيئة JSONC (موصى بها) + +المشاريع الجديدة التي تُنشأ عبر `crewai create crew ` تستخدم `crew.jsonc` لإعدادات الـ crew والمهام، وملفًا منفصلًا لكل Agent داخل `agents/`. يكتشف `crewai run` ملف `crew.jsonc` أو `crew.json`، ويحمّل الـ Agents المشار إليها، ويطلب قيم placeholders الناقصة، ثم يبدأ الـ crew. + +```jsonc crew.jsonc +{ + "name": "Market Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research", + "description": "Research {topic} and collect the most relevant facts.", + "expected_output": "Structured research notes about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis", + "description": "Analyze the research and write a concise report.", + "expected_output": "A markdown report with findings and recommendations.", + "agent": "analyst", + "context": ["research"], + "output_file": "output/report.md" + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "AI Agents" + } +} +``` + +كل عنصر في `agents` يُحل أولًا إلى `agents/.jsonc` ثم إلى `agents/.json`. للـ crews الهرمية، استخدم `"process": "hierarchical"` مع `manager_llm` أو `manager_agent`. + + +شغّل مشاريع JSON crew من مصادر تثق بها فقط. أدوات `custom:` ومراجع `{"python": "module.attribute"}` تنفذ كود Python محليًا عند تحميل الـ crew. + + +### تهيئة YAML الكلاسيكية + +المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew --classic` تستخدم `crew.py` و `config/agents.yaml` و `config/tasks.yaml` والمزيّنات `@CrewBase` و `@agent` و `@task` و `@crew`. + +تظل هذه الطريقة مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تحتاج تحكمًا صريحًا عبر 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: + """Description of your crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' + + @before_kickoff + def prepare_inputs(self, inputs): + inputs['additional_data'] = "Some extra information" + return inputs + + @after_kickoff + def process_output(self, output): + output.raw += "\nProcessed after kickoff." + return output + + @agent + def agent_one(self) -> Agent: + return Agent( + config=self.agents_config['agent_one'], # type: ignore[index] + verbose=True + ) + + @task + def task_one(self) -> Task: + return Task( + config=self.tasks_config['task_one'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + + +سيتم تنفيذ المهام بالترتيب الذي عُرّفت به. + + +فئة `CrewBase`، مع هذه المزيّنات، تؤتمت جمع الوكلاء والمهام، مما يقلل الحاجة للإدارة اليدوية. + +### تعريف مباشر في الكود (بديل) + +بدلاً من ذلك، يمكنك تعريف الطاقم مباشرة في الكود بدون ملفات تهيئة YAML. + +## مخرجات الطاقم + +تُغلّف مخرجات الطاقم في فئة `CrewOutput`. توفر هذه الفئة طريقة منظمة للوصول إلى نتائج تنفيذ الطاقم، بما في ذلك تنسيقات متنوعة مثل السلاسل النصية الخام وJSON ونماذج Pydantic. + +### خصائص مخرجات الطاقم + +| الخاصية | المعامل | النوع | الوصف | +| :--------------- | :------------- | :------------------------- | :--------------------------------------------------------------------------------------------------- | +| **Raw** | `raw` | `str` | المخرجات الخام للطاقم. هذا هو التنسيق الافتراضي. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | كائن نموذج Pydantic يمثل المخرجات المنظمة. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | قاموس يمثل مخرجات JSON. | +| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | قائمة كائنات `TaskOutput`، كل منها يمثل مخرجات مهمة. | +| **Token Usage** | `token_usage` | `Dict[str, Any]` | ملخص استخدام الرموز. | + +## استخدام الذاكرة + +يمكن للأطقم استخدام الذاكرة (قصيرة المدى، طويلة المدى، وذاكرة الكيانات) لتحسين تنفيذها وتعلمها بمرور الوقت. + +## استخدام التخزين المؤقت + +يمكن استخدام التخزين المؤقت لتخزين نتائج تنفيذ الأدوات، مما يجعل العملية أكثر كفاءة. + +## مقاييس استخدام الطاقم + +بعد تنفيذ الطاقم، يمكنك الوصول إلى خاصية `usage_metrics` لعرض مقاييس استخدام نموذج اللغة (LLM) لجميع المهام المنفذة. + +```python Code +crew = Crew(agents=[agent1, agent2], tasks=[task1, task2]) +crew.kickoff() +print(crew.usage_metrics) +``` + +## عملية تنفيذ الطاقم + +- **العملية التسلسلية**: تُنفذ المهام واحدة تلو الأخرى، مما يسمح بتدفق عمل خطي. +- **العملية الهرمية**: ينسق وكيل مدير الطاقم، ويفوّض المهام ويتحقق من النتائج. + +### تشغيل الطاقم + +بمجرد تجميع طاقمك، ابدأ سير العمل بطريقة `kickoff()`. + +```python Code +result = my_crew.kickoff() +print(result) +``` + +### طرق مختلفة لتشغيل الطاقم + +#### الطرق المتزامنة + +- `kickoff()`: يبدأ عملية التنفيذ وفقًا لتدفق العملية المحدد. +- `kickoff_for_each()`: ينفذ المهام بالتتابع لكل مدخل. + +#### الطرق غير المتزامنة + +| الطريقة | النوع | الوصف | +|--------|------|-------------| +| `akickoff()` | غير متزامن أصلي | async/await أصلي عبر سلسلة التنفيذ بأكملها | +| `akickoff_for_each()` | غير متزامن أصلي | تنفيذ غير متزامن أصلي لكل مدخل في قائمة | +| `kickoff_async()` | مبني على الخيوط | يغلّف التنفيذ المتزامن في `asyncio.to_thread` | +| `kickoff_for_each_async()` | مبني على الخيوط | غير متزامن مبني على الخيوط لكل مدخل في قائمة | + + +لأحمال العمل عالية التزامن، يُوصى بـ `akickoff()` و `akickoff_for_each()` لأنها تستخدم async أصلي. + + +### بث تنفيذ الطاقم + +للرؤية في الوقت الفعلي لتنفيذ الطاقم، يمكنك تفعيل البث: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +streaming = crew.kickoff(inputs={"topic": "AI"}) +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +``` + +### الإعادة من مهمة محددة + +يمكنك الآن الإعادة من مهمة محددة باستخدام أمر CLI `replay`. + +```shell +crewai log-tasks-outputs +``` + +ثم للإعادة من مهمة محددة: + +```shell +crewai replay -t +``` diff --git a/docs/v1.15.1/ar/concepts/event-listener.mdx b/docs/v1.15.1/ar/concepts/event-listener.mdx new file mode 100644 index 000000000..41be56cb8 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/event-listener.mdx @@ -0,0 +1,236 @@ +--- +title: "مستمعو الأحداث" +description: "الاستفادة من أحداث CrewAI لبناء تكاملات مخصصة ومراقبة" +icon: spinner +mode: "wide" +--- + +## نظرة عامة + +يوفر CrewAI نظام أحداث قوي يتيح لك الاستماع والتفاعل مع الأحداث المختلفة التي تحدث أثناء تنفيذ طاقمك. تُمكّنك هذه الميزة من بناء تكاملات مخصصة وحلول مراقبة وأنظمة تسجيل أو أي وظائف أخرى تحتاج للتشغيل بناءً على أحداث CrewAI الداخلية. + +## كيف يعمل + +يستخدم CrewAI بنية ناقل أحداث لإرسال الأحداث طوال دورة حياة التنفيذ. يُبنى نظام الأحداث على المكونات التالية: + +1. **CrewAIEventsBus**: ناقل أحداث فريد يدير تسجيل الأحداث وإرسالها +2. **BaseEvent**: الفئة الأساسية لجميع الأحداث في النظام +3. **BaseEventListener**: فئة أساسية مجردة لإنشاء مستمعي أحداث مخصصين + +عندما تحدث إجراءات محددة في CrewAI (مثل بدء تنفيذ طاقم، أو إكمال وكيل لمهمة، أو استخدام أداة)، يرسل النظام أحداثًا مقابلة. يمكنك تسجيل معالجات لهذه الأحداث لتنفيذ كود مخصص عند حدوثها. + + +يوفر CrewAI AMP ميزة تتبع أوامر مدمجة تستفيد من نظام الأحداث لتتبع وتخزين وتصور جميع الأوامر والاستكمالات والبيانات الوصفية المرتبطة. + +![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png) + +مع تتبع الأوامر يمكنك: + +- عرض السجل الكامل لجميع الأوامر المرسلة إلى LLM +- تتبع استخدام الرموز والتكاليف +- تصحيح إخفاقات استدلال الوكيل +- مشاركة تسلسلات الأوامر مع فريقك +- مقارنة استراتيجيات الأوامر المختلفة +- تصدير التتبعات للامتثال والتدقيق + + +## إنشاء مستمع أحداث مخصص + +لإنشاء مستمع أحداث مخصص، تحتاج إلى: + +1. إنشاء فئة ترث من `BaseEventListener` +2. تنفيذ طريقة `setup_listeners` +3. تسجيل معالجات للأحداث التي تهمك +4. إنشاء مثيل من مستمعك في الملف المناسب + +إليك مثالًا بسيطًا: + +```python +from crewai.events import ( + CrewKickoffStartedEvent, + CrewKickoffCompletedEvent, + AgentExecutionCompletedEvent, +) +from crewai.events 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}") +``` + +## تسجيل المستمع بشكل صحيح + +مجرد تعريف فئة المستمع ليس كافيًا. تحتاج لإنشاء مثيل منه والتأكد من استيراده في تطبيقك. + +```python +# في ملف crew.py +from crewai import Agent, Crew, Task +from my_listeners import MyCustomListener + +# إنشاء مثيل من المستمع +my_listener = MyCustomListener() + +class MyCustomCrew: + def crew(self): + return Crew( + agents=[...], + tasks=[...], + ) +``` + +## أنواع الأحداث المتاحة + +يوفر CrewAI مجموعة واسعة من الأحداث يمكنك الاستماع إليها: + +### أحداث الطاقم + +- **CrewKickoffStartedEvent**: يُرسل عند بدء تنفيذ الطاقم +- **CrewKickoffCompletedEvent**: يُرسل عند اكتمال تنفيذ الطاقم +- **CrewKickoffFailedEvent**: يُرسل عند فشل تنفيذ الطاقم +- **CrewTestStartedEvent**: يُرسل عند بدء اختبار الطاقم +- **CrewTestCompletedEvent**: يُرسل عند اكتمال اختبار الطاقم +- **CrewTestFailedEvent**: يُرسل عند فشل اختبار الطاقم +- **CrewTrainStartedEvent**: يُرسل عند بدء تدريب الطاقم +- **CrewTrainCompletedEvent**: يُرسل عند اكتمال تدريب الطاقم +- **CrewTrainFailedEvent**: يُرسل عند فشل تدريب الطاقم + +### أحداث الوكيل + +- **AgentExecutionStartedEvent**: يُرسل عند بدء تنفيذ وكيل لمهمة +- **AgentExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ وكيل لمهمة +- **AgentExecutionErrorEvent**: يُرسل عند مواجهة وكيل لخطأ أثناء التنفيذ +- **LiteAgentExecutionStartedEvent**: يُرسل عند بدء تنفيذ LiteAgent +- **LiteAgentExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ LiteAgent + +### أحداث المهام + +- **TaskStartedEvent**: يُرسل عند بدء تنفيذ مهمة +- **TaskCompletedEvent**: يُرسل عند اكتمال تنفيذ مهمة +- **TaskFailedEvent**: يُرسل عند فشل تنفيذ مهمة + +### أحداث استخدام الأدوات + +- **ToolUsageStartedEvent**: يُرسل عند بدء تنفيذ أداة +- **ToolUsageFinishedEvent**: يُرسل عند اكتمال تنفيذ أداة +- **ToolUsageErrorEvent**: يُرسل عند مواجهة خطأ في تنفيذ أداة + +### أحداث MCP + +- **MCPConnectionStartedEvent**: يُرسل عند بدء الاتصال بخادم MCP +- **MCPConnectionCompletedEvent**: يُرسل عند اكتمال الاتصال بخادم MCP +- **MCPConnectionFailedEvent**: يُرسل عند فشل الاتصال بخادم MCP +- **MCPToolExecutionStartedEvent**: يُرسل عند بدء تنفيذ أداة MCP +- **MCPToolExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ أداة MCP +- **MCPToolExecutionFailedEvent**: يُرسل عند فشل تنفيذ أداة MCP + +### أحداث المعرفة + +- **KnowledgeRetrievalStartedEvent**: يُرسل عند بدء استرجاع المعرفة +- **KnowledgeRetrievalCompletedEvent**: يُرسل عند اكتمال استرجاع المعرفة +- **KnowledgeQueryStartedEvent**: يُرسل عند بدء استعلام المعرفة +- **KnowledgeQueryCompletedEvent**: يُرسل عند اكتمال استعلام المعرفة +- **KnowledgeQueryFailedEvent**: يُرسل عند فشل استعلام المعرفة + +### أحداث حواجز LLM + +- **LLMGuardrailStartedEvent**: يُرسل عند بدء التحقق من الحاجز +- **LLMGuardrailCompletedEvent**: يُرسل عند اكتمال التحقق من الحاجز +- **LLMGuardrailFailedEvent**: يُرسل عند فشل التحقق من الحاجز + +### أحداث التدفق + +- **FlowCreatedEvent**: يُرسل عند إنشاء تدفق +- **FlowStartedEvent**: يُرسل عند بدء تنفيذ تدفق +- **FlowFinishedEvent**: يُرسل عند اكتمال تنفيذ تدفق +- **FlowPausedEvent**: يُرسل عند إيقاف تدفق مؤقتًا بانتظار ملاحظات بشرية + +### أحداث LLM + +- **LLMCallStartedEvent**: يُرسل عند بدء استدعاء LLM +- **LLMCallCompletedEvent**: يُرسل عند اكتمال استدعاء LLM +- **LLMCallFailedEvent**: يُرسل عند فشل استدعاء LLM +- **LLMStreamChunkEvent**: يُرسل لكل جزء مستلم أثناء بث استجابات LLM + +### أحداث الذاكرة + +- **MemoryQueryStartedEvent**: يُرسل عند بدء استعلام الذاكرة +- **MemoryQueryCompletedEvent**: يُرسل عند اكتمال استعلام الذاكرة +- **MemorySaveStartedEvent**: يُرسل عند بدء حفظ الذاكرة +- **MemorySaveCompletedEvent**: يُرسل عند اكتمال حفظ الذاكرة + +### أحداث الاستدلال + +- **AgentReasoningStartedEvent**: يُرسل عند بدء وكيل الاستدلال حول مهمة +- **AgentReasoningCompletedEvent**: يُرسل عند انتهاء عملية الاستدلال +- **AgentReasoningFailedEvent**: يُرسل عند فشل عملية الاستدلال + +### أحداث A2A (وكيل إلى وكيل) + +- **A2ADelegationStartedEvent**: يُرسل عند بدء تفويض A2A +- **A2ADelegationCompletedEvent**: يُرسل عند اكتمال تفويض A2A +- **A2AConversationStartedEvent**: يُرسل عند بدء محادثة A2A متعددة الأدوار +- **A2AConversationCompletedEvent**: يُرسل عند انتهاء محادثة A2A + +## هيكل معالج الأحداث + +يستقبل كل معالج حدث معاملين: + +1. **source**: الكائن الذي أرسل الحدث +2. **event**: مثيل الحدث، يحتوي على بيانات خاصة بالحدث + +هيكل كائن الحدث يعتمد على نوع الحدث، لكن جميع الأحداث ترث من `BaseEvent` وتتضمن: + +- **timestamp**: الوقت الذي أُرسل فيه الحدث +- **type**: معرّف نصي لنوع الحدث + +## الاستخدام المتقدم: المعالجات المحددة النطاق + +لمعالجة الأحداث المؤقتة، يمكنك استخدام مدير سياق `scoped_handlers`: + +```python +from crewai.events import crewai_event_bus, CrewKickoffStartedEvent + +with crewai_event_bus.scoped_handlers(): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def temp_handler(source, event): + print("This handler only exists within this context") + + # قم بشيء يرسل أحداثًا + +# خارج السياق، يتم إزالة المعالج المؤقت +``` + +## حالات الاستخدام + +يمكن استخدام مستمعي الأحداث لأغراض متنوعة: + +1. **التسجيل والمراقبة**: تتبع تنفيذ طاقمك وتسجيل الأحداث المهمة +2. **التحليلات**: جمع بيانات عن أداء وسلوك طاقمك +3. **التصحيح**: إعداد مستمعين مؤقتين لتصحيح مشاكل محددة +4. **التكامل**: ربط CrewAI بأنظمة خارجية مثل منصات المراقبة وقواعد البيانات أو خدمات الإشعارات +5. **السلوك المخصص**: تشغيل إجراءات مخصصة بناءً على أحداث محددة + +## أفضل الممارسات + +1. **اجعل المعالجات خفيفة**: يجب أن تكون معالجات الأحداث خفيفة وتتجنب العمليات الحاجبة +2. **معالجة الأخطاء**: أدرج معالجة أخطاء مناسبة في معالجات الأحداث لمنع الاستثناءات من التأثير على التنفيذ الرئيسي +3. **التنظيف**: إذا خصص مستمعك موارد، تأكد من تنظيفها بشكل صحيح +4. **الاستماع الانتقائي**: استمع فقط للأحداث التي تحتاج فعلاً لمعالجتها +5. **الاختبار**: اختبر مستمعي الأحداث بمعزل لضمان سلوكهم كما هو متوقع + +بالاستفادة من نظام أحداث CrewAI، يمكنك توسيع وظائفه ودمجه بسلاسة مع بنيتك التحتية الحالية. diff --git a/docs/v1.15.1/ar/concepts/files.mdx b/docs/v1.15.1/ar/concepts/files.mdx new file mode 100644 index 000000000..66516a093 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/files.mdx @@ -0,0 +1,267 @@ +--- +title: الملفات +description: تمرير الصور وملفات PDF والصوت والفيديو والنصوص إلى وكلائك للمعالجة متعددة الوسائط. +icon: file-image +--- + +## نظرة عامة + +يدعم CrewAI مدخلات الملفات متعددة الوسائط الأصلية، مما يتيح لك تمرير الصور وملفات PDF والصوت والفيديو والنصوص مباشرة إلى وكلائك. يتم تنسيق الملفات تلقائيًا وفقًا لمتطلبات API لكل مزود LLM. + + +يتطلب دعم الملفات حزمة `crewai-files` الاختيارية. ثبّتها بـ: + +```bash +uv add 'crewai[file-processing]' +``` + + + +واجهة معالجة الملفات حاليًا في مرحلة الوصول المبكر. + + +## أنواع الملفات + +يدعم CrewAI خمسة أنواع ملفات محددة بالإضافة إلى فئة `File` العامة التي تكتشف النوع تلقائيًا: + +| النوع | الفئة | حالات الاستخدام | +|:-----|:------|:----------| +| **صورة** | `ImageFile` | صور، لقطات شاشة، مخططات، رسوم بيانية | +| **PDF** | `PDFFile` | مستندات، تقارير، أوراق بحثية | +| **صوت** | `AudioFile` | تسجيلات صوتية، بودكاست، اجتماعات | +| **فيديو** | `VideoFile` | تسجيلات شاشة، عروض تقديمية | +| **نص** | `TextFile` | ملفات كود، سجلات، ملفات بيانات | +| **عام** | `File` | اكتشاف تلقائي للنوع من المحتوى | + +```python +from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile + +image = ImageFile(source="screenshot.png") +pdf = PDFFile(source="report.pdf") +audio = AudioFile(source="meeting.mp3") +video = VideoFile(source="demo.mp4") +text = TextFile(source="data.csv") + +file = File(source="document.pdf") +``` + +## مصادر الملفات + +يقبل معامل `source` أنواع إدخال متعددة ويكتشف تلقائيًا المعالج المناسب: + +### من مسار + +```python +from crewai_files import ImageFile + +image = ImageFile(source="./images/chart.png") +``` + +### من عنوان URL + +```python +from crewai_files import ImageFile + +image = ImageFile(source="https://example.com/image.png") +``` + +### من بايتات + +```python +from crewai_files import ImageFile, FileBytes + +image_bytes = download_image_from_api() +image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png")) +image = ImageFile(source=image_bytes) +``` + +## استخدام الملفات + +يمكن تمرير الملفات على مستويات متعددة، حيث تأخذ المستويات الأكثر تحديدًا الأولوية. + +### مع الأطقم + +مرر الملفات عند تشغيل طاقم: + +```python +from crewai import Crew +from crewai_files import ImageFile + +crew = Crew(agents=[analyst], tasks=[analysis_task]) + +result = crew.kickoff( + inputs={"topic": "Q4 Sales"}, + input_files={ + "chart": ImageFile(source="sales_chart.png"), + "report": PDFFile(source="quarterly_report.pdf"), + } +) +``` + +### مع المهام + +أرفق الملفات بمهام محددة: + +```python +from crewai import Task +from crewai_files import ImageFile + +task = Task( + description="Analyze the sales chart and identify trends in {chart}", + expected_output="A summary of key trends", + input_files={ + "chart": ImageFile(source="sales_chart.png"), + } +) +``` + +### مع التدفقات + +مرر الملفات إلى التدفقات، والتي تنتقل تلقائيًا إلى الأطقم: + +```python +from crewai.flow.flow import Flow, start +from crewai_files import ImageFile + +class AnalysisFlow(Flow): + @start() + def analyze(self): + return self.analysis_crew.kickoff() + +flow = AnalysisFlow() +result = flow.kickoff( + input_files={"image": ImageFile(source="data.png")} +) +``` + +### مع الوكلاء المستقلين + +مرر الملفات مباشرة إلى تشغيل الوكيل: + +```python +from crewai import Agent +from crewai_files import ImageFile + +agent = Agent( + role="Image Analyst", + goal="Analyze images", + backstory="Expert at visual analysis", + llm="gpt-4o", +) + +result = agent.kickoff( + messages="What's in this image?", + input_files={"photo": ImageFile(source="photo.jpg")}, +) +``` + +## أولوية الملفات + +عند تمرير الملفات على مستويات متعددة، تتجاوز المستويات الأكثر تحديدًا المستويات الأوسع: + +``` +Flow input_files < Crew input_files < Task input_files +``` + +على سبيل المثال، إذا عرّف كل من التدفق والمهمة ملفًا باسم `"chart"`، تُستخدم نسخة المهمة. + +## دعم المزودين + +تدعم المزودات المختلفة أنواع ملفات مختلفة. يقوم CrewAI تلقائيًا بتنسيق الملفات وفقًا لواجهة كل مزود. + +| المزود | صورة | PDF | صوت | فيديو | نص | +|:---------|:-----:|:---:|:-----:|:-----:|:----:| +| **OpenAI** (completions API) | ✓ | | | | | +| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | | +| **Anthropic** (claude-3.x) | ✓ | ✓ | | | | +| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ | +| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | | +| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | | + + +تدعم نماذج Google Gemini جميع أنواع الملفات بما في ذلك الفيديو (حتى ساعة واحدة، 2 جيجابايت). استخدم Gemini عندما تحتاج لمعالجة محتوى الفيديو. + + + +إذا مررت نوع ملف لا يدعمه المزود (مثل الفيديو إلى OpenAI)، ستتلقى خطأ `UnsupportedFileTypeError`. اختر مزودك بناءً على أنواع الملفات التي تحتاج لمعالجتها. + + +## كيف تُرسل الملفات + +يختار CrewAI تلقائيًا الطريقة المثلى لإرسال الملفات إلى كل مزود: + +| الطريقة | الوصف | متى تُستخدم | +|:-------|:------------|:----------| +| **Inline Base64** | الملف مضمّن مباشرة في الطلب | ملفات صغيرة (< 5 ميجابايت عادة) | +| **File Upload API** | الملف يُرفع بشكل منفصل، يُشار إليه بمعرّف | ملفات كبيرة تتجاوز العتبة | +| **URL Reference** | عنوان URL مباشر يُمرر إلى النموذج | مصدر الملف هو عنوان URL بالفعل | + +### طرق الإرسال حسب المزود + +| المزود | Inline Base64 | File Upload API | URL References | +|:---------|:-------------:|:---------------:|:--------------:| +| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ | +| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ | +| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ | +| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) | +| **Azure OpenAI** | ✓ | | ✓ | + + +لا تحتاج لإدارة هذا بنفسك. يستخدم CrewAI تلقائيًا الطريقة الأكثر كفاءة بناءً على حجم الملف وقدرات المزود. المزودات بدون واجهات رفع الملفات تستخدم inline base64 لجميع الملفات. + + +## أوضاع معالجة الملفات + +تحكم في كيفية معالجة الملفات عندما تتجاوز حدود المزود: + +```python +from crewai_files import ImageFile, PDFFile + +image = ImageFile(source="large.png", mode="strict") +image = ImageFile(source="large.png", mode="auto") +image = ImageFile(source="large.png", mode="warn") +pdf = PDFFile(source="large.pdf", mode="chunk") +``` + +## قيود المزودين + +لكل مزود حدود محددة لأحجام الملفات والأبعاد: + +### OpenAI +- **الصور**: حد أقصى 20 ميجابايت، حتى 10 صور لكل طلب +- **PDF**: حد أقصى 32 ميجابايت، حتى 100 صفحة +- **الصوت**: حد أقصى 25 ميجابايت، حتى 25 دقيقة + +### Anthropic +- **الصور**: حد أقصى 5 ميجابايت، أقصى 8000x8000 بكسل، حتى 100 صورة +- **PDF**: حد أقصى 32 ميجابايت، حتى 100 صفحة + +### Google Gemini +- **الصور**: حد أقصى 100 ميجابايت +- **PDF**: حد أقصى 50 ميجابايت +- **الصوت**: حد أقصى 100 ميجابايت، حتى 9.5 ساعة +- **الفيديو**: حد أقصى 2 جيجابايت، حتى ساعة واحدة + +### AWS Bedrock +- **الصور**: حد أقصى 4.5 ميجابايت، أقصى 8000x8000 بكسل +- **PDF**: حد أقصى 3.75 ميجابايت، حتى 100 صفحة + +## الإشارة إلى الملفات في الأوامر + +استخدم اسم مفتاح الملف في أوصاف المهام للإشارة إلى الملفات: + +```python +task = Task( + description=""" + Analyze the provided materials: + 1. Review the chart in {sales_chart} + 2. Cross-reference with data in {quarterly_report} + 3. Summarize key findings + """, + expected_output="Analysis summary with key insights", + input_files={ + "sales_chart": ImageFile(source="chart.png"), + "quarterly_report": PDFFile(source="report.pdf"), + } +) +``` diff --git a/docs/v1.15.1/ar/concepts/flows.mdx b/docs/v1.15.1/ar/concepts/flows.mdx new file mode 100644 index 000000000..62d34b335 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/flows.mdx @@ -0,0 +1,1163 @@ +--- +title: التدفقات +description: تعلّم كيفية إنشاء وإدارة سير عمل الذكاء الاصطناعي باستخدام تدفقات CrewAI. +icon: arrow-progress +mode: "wide" +--- + +## نظرة عامة + +تدفقات CrewAI هي ميزة قوية مصممة لتبسيط إنشاء وإدارة سير عمل الذكاء الاصطناعي. تتيح التدفقات للمطورين دمج وتنسيق مهام البرمجة وفرق Crew بكفاءة، مما يوفر إطار عمل متين لبناء أتمتة ذكاء اصطناعي متطورة. + +تتيح لك التدفقات إنشاء سير عمل منظم يعتمد على الأحداث. فهي توفر طريقة سلسة لربط مهام متعددة وإدارة الحالة والتحكم في تدفق التنفيذ في تطبيقات الذكاء الاصطناعي الخاصة بك. باستخدام التدفقات، يمكنك بسهولة تصميم وتنفيذ عمليات متعددة الخطوات تستفيد من الإمكانيات الكاملة لـ CrewAI. + +1. **تبسيط إنشاء سير العمل**: ربط فرق Crew والمهام المتعددة بسهولة لإنشاء سير عمل ذكاء اصطناعي معقد. + +2. **إدارة الحالة**: تجعل التدفقات إدارة ومشاركة الحالة بين المهام المختلفة في سير العمل أمرًا سهلًا للغاية. + +3. **بنية تعتمد على الأحداث**: مبنية على نموذج يعتمد على الأحداث، مما يتيح سير عمل ديناميكي وسريع الاستجابة. + +4. **تحكم مرن في التدفق**: تنفيذ المنطق الشرطي والحلقات والتفرع ضمن سير العمل. + +## البدء + +لنقم بإنشاء تدفق بسيط حيث ستستخدم OpenAI لإنشاء مدينة عشوائية في مهمة واحدة ثم استخدام تلك المدينة لإنشاء حقيقة ممتعة في مهمة أخرى. + +```python Code + +from crewai.flow.flow import Flow, listen, start +from dotenv import load_dotenv +from litellm import completion + +load_dotenv() + +class ExampleFlow(Flow): + model = "gpt-4o-mini" + + @start() + def generate_city(self): + print("Starting flow") + # Each flow state automatically gets a unique ID + print(f"Flow State ID: {self.state['id']}") + + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": "Return the name of a random city in the world.", + }, + ], + ) + + random_city = response["choices"][0]["message"]["content"] + # Store the city in our state + self.state["city"] = random_city + print(f"Random City: {random_city}") + + return random_city + + @listen(generate_city) + def generate_fun_fact(self, random_city): + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": f"Tell me a fun fact about {random_city}", + }, + ], + ) + + fun_fact = response["choices"][0]["message"]["content"] + # Store the fun fact in our state + self.state["fun_fact"] = fun_fact + return fun_fact + + + +flow = ExampleFlow() +flow.plot() +result = flow.kickoff() + +print(f"Generated fun fact: {result}") +``` +![Flow Visual image](/images/crewai-flow-1.png) +في المثال أعلاه، أنشأنا تدفقًا بسيطًا يولّد مدينة عشوائية باستخدام OpenAI ثم يولّد حقيقة ممتعة عن تلك المدينة. يتكون التدفق من مهمتين: `generate_city` و `generate_fun_fact`. مهمة `generate_city` هي نقطة البداية للتدفق، ومهمة `generate_fun_fact` تستمع لمخرجات مهمة `generate_city`. + +يتلقى كل مثيل من التدفق تلقائيًا معرّفًا فريدًا (UUID) في حالته، مما يساعد في تتبع وإدارة عمليات تنفيذ التدفق. يمكن للحالة أيضًا تخزين بيانات إضافية (مثل المدينة المولّدة والحقيقة الممتعة) التي تستمر طوال تنفيذ التدفق. + +عند تشغيل التدفق، سيقوم بما يلي: +1. توليد معرّف فريد لحالة التدفق +2. توليد مدينة عشوائية وتخزينها في الحالة +3. توليد حقيقة ممتعة عن تلك المدينة وتخزينها في الحالة +4. طباعة النتائج في وحدة التحكم + +يمكن أن يكون المعرّف الفريد للحالة والبيانات المخزّنة مفيدًا لتتبع عمليات تنفيذ التدفق والحفاظ على السياق بين المهام. + +**ملاحظة:** تأكد من إعداد ملف `.env` لتخزين `OPENAI_API_KEY` الخاص بك. هذا المفتاح ضروري للمصادقة على طلبات OpenAI API. + +### @start() + +يحدد المزخرف `@start()` نقاط الدخول للتدفق. يمكنك: + +- تعريف عدة نقاط بداية غير مشروطة: `@start()` +- ربط البداية بدالة سابقة أو تسمية موجّه: `@start("method_or_label")` +- توفير شرط قابل للاستدعاء للتحكم في وقت تنفيذ البداية + +جميع دوال `@start()` المستوفية للشروط ستُنفَّذ (غالبًا بالتوازي) عند بدء أو استئناف التدفق. + +### @listen() + +يُستخدم المزخرف `@listen()` لتحديد دالة كمستمع لمخرجات مهمة أخرى في التدفق. ستُنفَّذ الدالة المزخرفة بـ `@listen()` عندما تُصدر المهمة المحددة مخرجاتها. يمكن للدالة الوصول إلى مخرجات المهمة التي تستمع إليها كمعامل. + +#### الاستخدام + +يمكن استخدام المزخرف `@listen()` بعدة طرق: + +1. **الاستماع لدالة بالاسم**: يمكنك تمرير اسم الدالة التي تريد الاستماع إليها كسلسلة نصية. عند اكتمال تلك الدالة، سيتم تشغيل دالة المستمع. + + ```python Code + @listen("generate_city") + def generate_fun_fact(self, random_city): + # Implementation + ``` + +2. **الاستماع لدالة مباشرة**: يمكنك تمرير الدالة نفسها. عند اكتمال تلك الدالة، سيتم تشغيل دالة المستمع. + ```python Code + @listen(generate_city) + def generate_fun_fact(self, random_city): + # Implementation + ``` + +### مخرجات التدفق + +الوصول إلى مخرجات التدفق والتعامل معها أمر أساسي لدمج سير عمل الذكاء الاصطناعي في التطبيقات أو الأنظمة الأكبر. توفر تدفقات CrewAI آليات مباشرة لاسترداد المخرجات النهائية والوصول إلى النتائج الوسيطة وإدارة الحالة العامة للتدفق. + +#### استرداد المخرجات النهائية + +عند تشغيل تدفق، يتم تحديد المخرجات النهائية بواسطة آخر دالة تكتمل. تُعيد دالة `kickoff()` مخرجات هذه الدالة الأخيرة. + +إليك كيفية الوصول إلى المخرجات النهائية: + + +```python Code +from crewai.flow.flow import Flow, listen, start + +class OutputExampleFlow(Flow): + @start() + def first_method(self): + return "Output from first_method" + + @listen(first_method) + def second_method(self, first_output): + return f"Second method received: {first_output}" + + +flow = OutputExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() + +print("---- Final Output ----") +print(final_output) +``` + +```text Output +---- Final Output ---- +Second method received: Output from first_method +``` + + +![Flow Visual image](/images/crewai-flow-2.png) + +في هذا المثال، `second_method` هي آخر دالة تكتمل، لذا ستكون مخرجاتها هي المخرجات النهائية للتدفق. +ستُعيد دالة `kickoff()` المخرجات النهائية، التي تُطبع بعد ذلك في وحدة التحكم. ستولّد دالة `plot()` ملف HTML الذي سيساعدك على فهم التدفق. + +#### الوصول إلى الحالة وتحديثها + +بالإضافة إلى استرداد المخرجات النهائية، يمكنك أيضًا الوصول إلى الحالة وتحديثها داخل التدفق. يمكن استخدام الحالة لتخزين ومشاركة البيانات بين الدوال المختلفة في التدفق. بعد تشغيل التدفق، يمكنك الوصول إلى الحالة لاسترداد أي معلومات تمت إضافتها أو تحديثها أثناء التنفيذ. + +إليك مثال على كيفية تحديث الحالة والوصول إليها: + + + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class StateExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + self.state.message = "Hello from first_method" + self.state.counter += 1 + + @listen(first_method) + def second_method(self): + self.state.message += " - updated by second_method" + self.state.counter += 1 + return self.state.message + +flow = StateExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() +print(f"Final Output: {final_output}") +print("Final State:") +print(flow.state) +``` + +```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) + +في هذا المثال، يتم تحديث الحالة بواسطة كل من `first_method` و `second_method`. +بعد تشغيل التدفق، يمكنك الوصول إلى الحالة النهائية لرؤية التحديثات التي أجرتها هذه الدوال. + +من خلال ضمان إعادة مخرجات الدالة الأخيرة وتوفير الوصول إلى الحالة، تجعل تدفقات CrewAI من السهل دمج نتائج سير عمل الذكاء الاصطناعي في التطبيقات أو الأنظمة الأكبر، +مع الحفاظ على الوصول إلى الحالة طوال تنفيذ التدفق. + +## مقاييس استخدام التدفق + +بعد اكتمال تنفيذ التدفق، يمكنك الوصول إلى الخاصية `usage_metrics` لعرض إجمالي استخدام التوكنات عبر **كل استدعاء لنموذج اللغة** يتم خلال التشغيل — بما في ذلك الاستدعاءات من كل فريق (Crew) ينظمه التدفق، والاستدعاءات داخل أدوات الـ Agents، والاستدعاءات المباشرة لـ `LLM.call(...)` من دوال التدفق. هذا هو المكافئ على جانب الـ SDK للإجماليات المعروضة في واجهة CrewAI Enterprise. + +```python Code +from crewai import LLM +from crewai.flow.flow import Flow, listen, start + +class UsageMetricsFlow(Flow): + @start() + def run_first_crew(self): + self.state.first_result = FirstCrew().crew().kickoff() + + @listen(run_first_crew) + def call_llm_directly(self): + # استدعاء مباشر لنموذج اللغة — يُحسب أيضًا ضمن flow.usage_metrics + llm = LLM(model="openai/gpt-4o-mini") + self.state.summary = llm.call("لخّص النقاط الرئيسية.") + + @listen(call_llm_directly) + def run_second_crew(self): + self.state.second_result = SecondCrew().crew().kickoff() + +flow = UsageMetricsFlow() +flow.kickoff() + +print(flow.usage_metrics) +# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369, +# cached_prompt_tokens=0, reasoning_tokens=0, +# cache_creation_tokens=0, successful_requests=5) +``` + + + `flow.usage_metrics` **ليست** نفس `flow.kickoff().token_usage`. هذه الأخيرة + ترجع فقط `CrewOutput.token_usage` لـ **آخر** دالة `@listen` أعادت + `CrewOutput`، مما يعني أنها تعكس فقط الفريق الأخير وتتجاهل الفرق السابقة + وكذلك أي استدعاءات مباشرة لـ `LLM.call(...)`. استخدم `flow.usage_metrics` + كلما احتجت إلى الإجمالي **الكامل** للتوكنات لتنفيذ التدفق. + + +كل حقل في [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد هو مجموع جميع استدعاءات نموذج اللغة التي حدثت خلال استدعاء واحد لـ `flow.kickoff()`. تتم إعادة تعيين العدادات عند الاستدعاء التالي لـ `kickoff()` (وفي كل تكرار من `kickoff_for_each`)، لذلك لن تتكرر العدّات عبر التشغيلات المتتالية. يمكن قراءة هذه الخاصية بأمان في أي وقت بعد اكتمال `kickoff()`؛ قراءتها أثناء التنفيذ تُرجع المجموع الجزئي المتراكم حتى تلك اللحظة. + +## إدارة حالة التدفق + +إدارة الحالة بفعالية أمر بالغ الأهمية لبناء سير عمل ذكاء اصطناعي موثوق وقابل للصيانة. توفر تدفقات CrewAI آليات قوية لإدارة الحالة غير المهيكلة والمهيكلة، +مما يتيح للمطورين اختيار النهج الأنسب لاحتياجات تطبيقاتهم. + +### إدارة الحالة غير المهيكلة + +في إدارة الحالة غير المهيكلة، يتم تخزين جميع الحالات في خاصية `state` لفئة `Flow`. +يوفر هذا النهج مرونة، مما يمكّن المطورين من إضافة أو تعديل خصائص الحالة أثناء التشغيل دون تحديد مخطط صارم. +حتى مع الحالات غير المهيكلة، تولّد تدفقات CrewAI تلقائيًا معرّفًا فريدًا (UUID) لكل مثيل حالة وتحافظ عليه. + +```python Code +from crewai.flow.flow import Flow, listen, start + +class UnstructuredExampleFlow(Flow): + + @start() + def first_method(self): + # The state automatically includes an 'id' field + print(f"State ID: {self.state['id']}") + self.state['counter'] = 0 + self.state['message'] = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated" + + @listen(second_method) + def third_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = UnstructuredExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**ملاحظة:** يتم توليد حقل `id` تلقائيًا والحفاظ عليه طوال تنفيذ التدفق. لا تحتاج إلى إدارته أو تعيينه يدويًا، وسيتم الحفاظ عليه حتى عند تحديث الحالة ببيانات جديدة. + +**النقاط الرئيسية:** + +- **المرونة:** يمكنك إضافة خصائص ديناميكيًا إلى `self.state` دون قيود محددة مسبقًا. +- **البساطة:** مثالي لسير العمل البسيط حيث يكون هيكل الحالة بسيطًا أو متغيرًا بشكل كبير. + +### إدارة الحالة المهيكلة + +تستفيد إدارة الحالة المهيكلة من مخططات محددة مسبقًا لضمان الاتساق وسلامة الأنواع عبر سير العمل. +باستخدام نماذج مثل `BaseModel` من Pydantic، يمكن للمطورين تحديد الشكل الدقيق للحالة، مما يتيح تحققًا أفضل وإكمالًا تلقائيًا في بيئات التطوير. + +تتلقى كل حالة في تدفقات CrewAI تلقائيًا معرّفًا فريدًا (UUID) للمساعدة في تتبع وإدارة مثيلات الحالة. يتم توليد هذا المعرّف وإدارته تلقائيًا بواسطة نظام التدفق. + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + + +class ExampleState(BaseModel): + # Note: 'id' field is automatically added to all states + counter: int = 0 + message: str = "" + + +class StructuredExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + # Access the auto-generated ID if needed + print(f"State ID: {self.state.id}") + self.state.message = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state.counter += 1 + self.state.message += " - updated" + + @listen(second_method) + def third_method(self): + self.state.counter += 1 + self.state.message += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = StructuredExampleFlow() +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**النقاط الرئيسية:** + +- **مخطط محدد:** يحدد `ExampleState` هيكل الحالة بوضوح، مما يعزز قابلية قراءة الكود وصيانته. +- **سلامة الأنواع:** يضمن استخدام Pydantic التزام خصائص الحالة بالأنواع المحددة، مما يقلل من أخطاء وقت التشغيل. +- **الإكمال التلقائي:** يمكن لبيئات التطوير المتكاملة توفير إكمال تلقائي أفضل وفحص أخطاء بناءً على نموذج الحالة المحدد. + +### الاختيار بين إدارة الحالة غير المهيكلة والمهيكلة + +- **استخدم إدارة الحالة غير المهيكلة عندما:** + + - يكون حالة سير العمل بسيطة أو ديناميكية للغاية. + - تكون المرونة أولوية على تعريفات الحالة الصارمة. + - يكون النماذج الأولية السريعة مطلوبة دون عبء تحديد المخططات. + +- **استخدم إدارة الحالة المهيكلة عندما:** + - يتطلب سير العمل هيكل حالة محدد جيدًا ومتسق. + - تكون سلامة الأنواع والتحقق مهمتين لموثوقية تطبيقك. + - تريد الاستفادة من ميزات بيئة التطوير المتكاملة مثل الإكمال التلقائي وفحص الأنواع لتجربة مطور أفضل. + +من خلال توفير خيارات إدارة الحالة غير المهيكلة والمهيكلة، تمكّن تدفقات CrewAI المطورين من بناء سير عمل ذكاء اصطناعي مرن ومتين في آن واحد، ملبيةً مجموعة واسعة من متطلبات التطبيقات. + +## استمرارية التدفق + +يتيح مزخرف @persist الاستمرارية التلقائية للحالة في تدفقات CrewAI، مما يسمح لك بالحفاظ على حالة التدفق عبر عمليات إعادة التشغيل أو تنفيذات سير العمل المختلفة. يمكن تطبيق هذا المزخرف على مستوى الفئة أو مستوى الدالة، مما يوفر مرونة في كيفية إدارة استمرارية الحالة. + +### الاستمرارية على مستوى الفئة + +عند التطبيق على مستوى الفئة، يقوم مزخرف @persist باستمرارية حالات جميع دوال التدفق تلقائيًا: + +```python +@persist # Using SQLiteFlowPersistence by default +class MyFlow(Flow[MyState]): + @start() + def initialize_flow(self): + # This method will automatically have its state persisted + self.state.counter = 1 + print("Initialized flow. State ID:", self.state.id) + + @listen(initialize_flow) + def next_step(self): + # The state (including self.state.id) is automatically reloaded + self.state.counter += 1 + print("Flow state is persisted. Counter:", self.state.counter) +``` + +### الاستمرارية على مستوى الدالة + +للتحكم الأكثر دقة، يمكنك تطبيق @persist على دوال محددة: + +```python +class AnotherFlow(Flow[dict]): + @persist # Persists only this method's state + @start() + def begin(self): + if "runs" not in self.state: + self.state["runs"] = 0 + self.state["runs"] += 1 + print("Method-level persisted runs:", self.state["runs"]) +``` + +### تفرع الحالة المستمرة + +يدعم `@persist` نمطين متميزين للترطيب في `kickoff` / `kickoff_async`: + +- `kickoff(inputs={"id": })` — **استئناف**: يحمّل أحدث لقطة لـ UUID المقدم ويستمر في الكتابة تحت نفس `flow_uuid`. يمتد التاريخ. +- `kickoff(restore_from_state_id=)` — **تفرع**: يحمّل أحدث لقطة لـ UUID المقدم، يرطّب حالة التشغيل الجديد منها، ثم يعيّن `state.id` جديدًا (مولّدًا تلقائيًا، أو `inputs["id"]` إذا تم تثبيته). تذهب كتابات `@persist` للتشغيل الجديد تحت `state.id` الجديد؛ يتم الحفاظ على تاريخ تدفق المصدر. + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + print(f"[id={self.state.id}] counter={self.state.counter}") + +# التشغيل 1: حالة جديدة، العداد 0 -> 1، محفوظ تحت flow_1.state.id +flow_1 = CounterFlow() +flow_1.kickoff() + +# التفرع: ترطيب من أحدث لقطة لـ flow_1، لكن باستخدام state.id جديد +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# يبدأ flow_2.state.counter بـ 1 (مرطّب)، ثم تزيده step() إلى 2. +# flow_2.state.id != flow_1.state.id؛ تاريخ flow_1 لم يتغيّر. +``` + +إذا لم يطابق `restore_from_state_id` المقدم أي حالة مستمرة، يعود kickoff بصمت إلى السلوك الافتراضي — نفس سلوك `inputs["id"]` عند عدم العثور عليه. الجمع بين `restore_from_state_id` و `from_checkpoint` يطلق `ValueError`؛ اختر مصدر ترطيب واحدًا. تثبيت `inputs["id"]` أثناء التفرع يشارك مفتاح الاستمرارية مع تدفق آخر — عادةً ما تريد استخدام `restore_from_state_id` فقط. + +### كيف تعمل + +1. **تعريف الحالة الفريد** + - تتلقى كل حالة تدفق UUID فريد تلقائيًا + - يتم الحفاظ على المعرّف عبر تحديثات الحالة واستدعاءات الدوال + - يدعم كلًا من الحالات المهيكلة (Pydantic BaseModel) وغير المهيكلة (القاموس) + +2. **واجهة SQLite الافتراضية** + - SQLiteFlowPersistence هي واجهة التخزين الافتراضية + - يتم حفظ الحالات تلقائيًا في قاعدة بيانات SQLite محلية + - معالجة أخطاء متينة تضمن رسائل واضحة في حالة فشل عمليات قاعدة البيانات + +3. **معالجة الأخطاء** + - رسائل خطأ شاملة لعمليات قاعدة البيانات + - تحقق تلقائي من الحالة أثناء الحفظ والتحميل + - ملاحظات واضحة عند مواجهة مشاكل في عمليات الاستمرارية + +### اعتبارات مهمة + +- **أنواع الحالة**: يتم دعم كل من الحالات المهيكلة (Pydantic BaseModel) وغير المهيكلة (القاموس) +- **المعرّف التلقائي**: يتم إضافة حقل `id` تلقائيًا إذا لم يكن موجودًا +- **استعادة الحالة**: يمكن للتدفقات الفاشلة أو المُعاد تشغيلها إعادة تحميل حالتها السابقة تلقائيًا +- **التنفيذ المخصص**: يمكنك توفير تنفيذ FlowPersistence الخاص بك لاحتياجات التخزين المتخصصة + +### المزايا التقنية + +1. **تحكم دقيق من خلال الوصول المنخفض المستوى** + - وصول مباشر لعمليات الاستمرارية لحالات الاستخدام المتقدمة + - تحكم دقيق عبر مزخرفات الاستمرارية على مستوى الدوال + - قدرات مدمجة لفحص الحالة وتصحيح الأخطاء + - رؤية كاملة لتغييرات الحالة وعمليات الاستمرارية + +2. **موثوقية معززة** + - استعادة تلقائية للحالة بعد أعطال النظام أو إعادة التشغيل + - تحديثات حالة قائمة على المعاملات لسلامة البيانات + - معالجة أخطاء شاملة مع رسائل خطأ واضحة + - تحقق متين أثناء عمليات حفظ وتحميل الحالة + +3. **بنية قابلة للتوسع** + - واجهة استمرارية قابلة للتخصيص من خلال واجهة FlowPersistence + - دعم لحلول تخزين متخصصة تتجاوز SQLite + - متوافقة مع كل من الحالات المهيكلة (Pydantic) وغير المهيكلة (dict) + - تكامل سلس مع أنماط تدفق CrewAI الحالية + +تركز بنية نظام الاستمرارية على الدقة التقنية وخيارات التخصيص، مما يتيح للمطورين الحفاظ على التحكم الكامل في إدارة الحالة مع الاستفادة من ميزات الموثوقية المدمجة. + +## التحكم في التدفق + +### المنطق الشرطي: `or` + +تتيح لك دالة `or_` في التدفقات الاستماع لعدة دوال وتشغيل دالة المستمع عندما تُصدر أي من الدوال المحددة مخرجاتها. + + + +```python Code +from crewai.flow.flow import Flow, listen, or_, start + +class OrExampleFlow(Flow): + + @start() + def start_method(self): + return "Hello from the start method" + + @listen(start_method) + def second_method(self): + return "Hello from the second method" + + @listen(or_(start_method, second_method)) + def logger(self, result): + print(f"Logger: {result}") + + + +flow = OrExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Logger: Hello from the start method +Logger: Hello from the second method +``` + + + +![Flow Visual image](/images/crewai-flow-4.png) + +عند تشغيل هذا التدفق، سيتم تشغيل دالة `logger` بواسطة مخرجات إما `start_method` أو `second_method`. +تُستخدم دالة `or_` للاستماع لعدة دوال وتشغيل دالة المستمع عندما تُصدر أي من الدوال المحددة مخرجاتها. + +### المنطق الشرطي: `and` + +تتيح لك دالة `and_` في التدفقات الاستماع لعدة دوال وتشغيل دالة المستمع فقط عندما تُصدر جميع الدوال المحددة مخرجاتها. + + + +```python Code +from crewai.flow.flow import Flow, and_, listen, start + +class AndExampleFlow(Flow): + + @start() + def start_method(self): + self.state["greeting"] = "Hello from the start method" + + @listen(start_method) + def second_method(self): + self.state["joke"] = "What do computers eat? Microchips." + + @listen(and_(start_method, second_method)) + def logger(self): + print("---- Logger ----") + print(self.state) + +flow = AndExampleFlow() +flow.plot() +flow.kickoff() +``` + +```text Output +---- Logger ---- +{'greeting': 'Hello from the start method', 'joke': 'What do computers eat? Microchips.'} +``` + + + +![Flow Visual image](/images/crewai-flow-5.png) + +عند تشغيل هذا التدفق، سيتم تشغيل دالة `logger` فقط عندما يُصدر كل من `start_method` و `second_method` مخرجاتهما. +تُستخدم دالة `and_` للاستماع لعدة دوال وتشغيل دالة المستمع فقط عندما تُصدر جميع الدوال المحددة مخرجاتها. + +### الموجّه + +يتيح لك مزخرف `@router()` في التدفقات تحديد منطق توجيه شرطي بناءً على مخرجات دالة. +يمكنك تحديد مسارات مختلفة بناءً على مخرجات الدالة، مما يتيح لك التحكم في تدفق التنفيذ ديناميكيًا. + + + +```python Code +import random +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + success_flag: bool = False + +class RouterFlow(Flow[ExampleState]): + + @start() + def start_method(self): + print("Starting the structured flow") + random_boolean = random.choice([True, False]) + self.state.success_flag = random_boolean + + @router(start_method) + def second_method(self): + if self.state.success_flag: + return "success" + else: + return "failed" + + @listen("success") + def third_method(self): + print("Third method running") + + @listen("failed") + def fourth_method(self): + print("Fourth method running") + + +flow = RouterFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Starting the structured flow +Third method running +Fourth method running +``` + + + +![Flow Visual image](/images/crewai-flow-6.png) + +في المثال أعلاه، تولّد `start_method` قيمة منطقية عشوائية وتعيّنها في الحالة. +تستخدم `second_method` مزخرف `@router()` لتحديد منطق توجيه شرطي بناءً على قيمة المنطقية. +إذا كانت القيمة `True`، تُعيد الدالة `"success"`، وإذا كانت `False`، تُعيد `"failed"`. +تستمع `third_method` و `fourth_method` لمخرجات `second_method` وتُنفَّذ بناءً على القيمة المُعادة. + +عند تشغيل هذا التدفق، ستتغير المخرجات بناءً على القيمة المنطقية العشوائية المولّدة بواسطة `start_method`. + +### الإنسان في الحلقة (التغذية الراجعة البشرية) + + +يتطلب مزخرف `@human_feedback` **CrewAI الإصدار 1.8.0 أو أعلى**. + + +يتيح مزخرف `@human_feedback` سير عمل يتضمن تدخلًا بشريًا من خلال إيقاف تنفيذ التدفق مؤقتًا لجمع تغذية راجعة من إنسان. هذا مفيد لبوابات الموافقة ومراجعة الجودة ونقاط القرار التي تتطلب حكمًا بشريًا. + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="Do you approve this content?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + def generate_content(self): + return "Content to be reviewed..." + + @listen("approved") + def on_approval(self, result: HumanFeedbackResult): + print(f"Approved! Feedback: {result.feedback}") + + @listen("rejected") + def on_rejection(self, result: HumanFeedbackResult): + print(f"Rejected. Reason: {result.feedback}") +``` + +عند تحديد `emit`، يتم تفسير التغذية الراجعة الحرة للإنسان بواسطة LLM وتُختصر إلى إحدى النتائج المحددة، والتي تُشغل بعد ذلك مزخرف `@listen` المقابل. + +يمكنك أيضًا استخدام `@human_feedback` دون توجيه لجمع التغذية الراجعة ببساطة: + +```python Code +@start() +@human_feedback(message="Any comments on this output?") +def my_method(self): + return "Output for review" + +@listen(my_method) +def next_step(self, result: HumanFeedbackResult): + # Access feedback via result.feedback + # Access original output via result.output + pass +``` + +يمكنك الوصول إلى جميع التغذيات الراجعة المُجمّعة أثناء التدفق عبر `self.last_human_feedback` (الأحدث) أو `self.human_feedback_history` (جميع التغذيات الراجعة كقائمة). + +للحصول على دليل كامل حول التغذية الراجعة البشرية في التدفقات، بما في ذلك **التغذية الراجعة غير المتزامنة/غير الحاجبة** مع مزودين مخصصين (Slack، webhooks، إلخ)، انظر [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows). + +## إضافة Agents إلى التدفقات + +يمكن دمج Agents بسلاسة في تدفقاتك، مما يوفر بديلًا خفيف الوزن لفرق Crew الكاملة عندما تحتاج إلى تنفيذ مهام أبسط وأكثر تركيزًا. إليك مثال على كيفية استخدام Agent ضمن تدفق لإجراء أبحاث السوق: + +```python +import asyncio +from typing import Any, Dict, List + +from crewai_tools import SerperDevTool +from pydantic import BaseModel, Field + +from crewai.agent import Agent +from crewai.flow.flow import Flow, listen, start + + +# Define a structured output format +class MarketAnalysis(BaseModel): + key_trends: List[str] = Field(description="List of identified market trends") + market_size: str = Field(description="Estimated market size") + competitors: List[str] = Field(description="Major competitors in the space") + + +# Define flow state +class MarketResearchState(BaseModel): + product: str = "" + analysis: MarketAnalysis | None = None + + +# Create a flow class +class MarketResearchFlow(Flow[MarketResearchState]): + @start() + def initialize_research(self) -> Dict[str, Any]: + print(f"Starting market research for {self.state.product}") + return {"product": self.state.product} + + @listen(initialize_research) + async def analyze_market(self) -> Dict[str, Any]: + # Create an Agent for market research + analyst = Agent( + role="Market Research Analyst", + goal=f"Analyze the market for {self.state.product}", + backstory="You are an experienced market analyst with expertise in " + "identifying market trends and opportunities.", + tools=[SerperDevTool()], + verbose=True, + ) + + # Define the research query + query = f""" + Research the market for {self.state.product}. Include: + 1. Key market trends + 2. Market size + 3. Major competitors + + Format your response according to the specified structure. + """ + + # Execute the analysis with structured output format + result = await analyst.kickoff_async(query, response_format=MarketAnalysis) + if result.pydantic: + print("result", result.pydantic) + else: + print("result", result) + + # Return the analysis to update the state + return {"analysis": result.pydantic} + + @listen(analyze_market) + def present_results(self, analysis) -> None: + print("\nMarket Analysis Results") + print("=====================") + + if isinstance(analysis, dict): + # If we got a dict with 'analysis' key, extract the actual analysis object + market_analysis = analysis.get("analysis") + else: + market_analysis = analysis + + if market_analysis and isinstance(market_analysis, MarketAnalysis): + print("\nKey Market Trends:") + for trend in market_analysis.key_trends: + print(f"- {trend}") + + print(f"\nMarket Size: {market_analysis.market_size}") + + print("\nMajor Competitors:") + for competitor in market_analysis.competitors: + print(f"- {competitor}") + else: + print("No structured analysis data available.") + print("Raw analysis:", analysis) + + +# Usage example +async def run_flow(): + flow = MarketResearchFlow() + flow.plot("MarketResearchFlowPlot") + result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"}) + return result + + +# Run the flow +if __name__ == "__main__": + asyncio.run(run_flow()) +``` + +![Flow Visual image](/images/crewai-flow-7.png) + +يوضح هذا المثال عدة ميزات رئيسية لاستخدام Agents في التدفقات: + +1. **المخرجات المهيكلة**: استخدام نماذج Pydantic لتحديد تنسيق المخرجات المتوقع (`MarketAnalysis`) يضمن سلامة الأنواع والبيانات المهيكلة في جميع أنحاء التدفق. + +2. **إدارة الحالة**: تحافظ حالة التدفق (`MarketResearchState`) على السياق بين الخطوات وتخزّن كلًا من المدخلات والمخرجات. + +3. **تكامل الأدوات**: يمكن لـ Agents استخدام أدوات (مثل `WebsiteSearchTool`) لتعزيز قدراتهم. + +## إضافة فرق Crew إلى التدفقات + +إنشاء تدفق مع فرق Crew متعددة في CrewAI أمر مباشر. + +يمكنك إنشاء مشروع CrewAI جديد يتضمن جميع الهيكلية اللازمة لإنشاء تدفق مع فرق Crew متعددة عن طريق تشغيل الأمر التالي: + +```bash +crewai create flow name_of_flow +``` + +سيولّد هذا الأمر مشروع CrewAI جديد مع هيكل المجلدات اللازم. يتضمن المشروع المولّد فريق Crew مُعد مسبقًا يُسمى `poem_crew` ويعمل بالفعل. يستخدم الـ embedded crew الابتدائي بنية Python/YAML الكلاسيكية؛ أما crews المستقلة الجديدة التي تُنشأ عبر `crewai create crew` فتستخدم بنية JSON-first. + +### هيكل المجلدات + +بعد تشغيل أمر `crewai create flow name_of_flow`، سترى هيكل مجلدات مشابه للتالي: + +| المجلد/الملف | الوصف | +| :--------------------- | :----------------------------------------------------------------- | +| `name_of_flow/` | المجلد الجذر للتدفق. | +| ├── `crews/` | يحتوي على مجلدات لفرق Crew المحددة. | +| │ └── `poem_crew/` | مجلد لـ "poem_crew" مع إعداداته وسكربتاته. | +| │ ├── `config/` | مجلد ملفات الإعداد لـ "poem_crew". | +| │ │ ├── `agents.yaml` | ملف YAML يحدد الـ Agents لـ "poem_crew". | +| │ │ └── `tasks.yaml` | ملف YAML يحدد المهام لـ "poem_crew". | +| │ ├── `poem_crew.py` | سكربت وظائف "poem_crew". | +| ├── `tools/` | مجلد للأدوات الإضافية المُستخدمة في التدفق. | +| │ └── `custom_tool.py` | تنفيذ أداة مخصصة. | +| ├── `main.py` | السكربت الرئيسي لتشغيل التدفق. | +| ├── `README.md` | وصف المشروع والتعليمات. | +| ├── `pyproject.toml` | ملف إعداد تبعيات المشروع والإعدادات. | +| └── `.gitignore` | يحدد الملفات والمجلدات المراد تجاهلها في التحكم بالإصدارات. | + +### بناء فرق Crew الخاصة بك + +في مجلد `crews`، يمكنك تحديد فرق Crew متعددة. سيكون لكل فريق مجلده الخاص الذي يحتوي على ملفات الإعداد وملف تعريف الفريق. على سبيل المثال، يحتوي مجلد `poem_crew` على: + +- `config/agents.yaml`: يحدد الـ Agents للفريق. +- `config/tasks.yaml`: يحدد المهام للفريق. +- `poem_crew.py`: يحتوي على تعريف الفريق، بما في ذلك الـ Agents والمهام والفريق نفسه. + +يمكنك نسخ ولصق وتعديل `poem_crew` لإنشاء crews كلاسيكية مضمّنة أخرى. + +للـ crews المضمّنة بنمط JSON-first، استخدم مجلدًا يحتوي على `crew.jsonc` و `agents/*.jsonc`: + +```text +crews/ +└── research_crew/ + ├── agents/ + │ └── researcher.jsonc + └── crew.jsonc +``` + +ثم حمّلها من خطوة في Flow: + +```python +from pathlib import Path +from crewai.project import load_crew + +crew, default_inputs = load_crew( + Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc" +) +result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"}) +``` + +### ربط فرق Crew في `main.py` + +ملف `main.py` هو حيث تنشئ التدفق وتربط فرق Crew معًا. يمكنك تحديد التدفق باستخدام فئة `Flow` والمزخرفات `@start` و `@listen` لتحديد تدفق التنفيذ. + +إليك مثال على كيفية ربط `poem_crew` في ملف `main.py`: + +```python Code +#!/usr/bin/env python +from random import randint + +from pydantic import BaseModel +from crewai.flow.flow import Flow, listen, start +from .crews.poem_crew.poem_crew import PoemCrew + + +class PoemState(BaseModel): + sentence_count: int = 1 + poem: str = "" + +class PoemFlow(Flow[PoemState]): + + @start() + def generate_sentence_count(self): + print("Generating sentence count") + self.state.sentence_count = randint(1, 5) + + @listen(generate_sentence_count) + def generate_poem(self): + print("Generating poem") + result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count}) + + print("Poem generated", result.raw) + self.state.poem = result.raw + + @listen(generate_poem) + def save_poem(self): + print("Saving poem") + with open("poem.txt", "w") as f: + f.write(self.state.poem) + +def kickoff(): + poem_flow = PoemFlow() + poem_flow.kickoff() + + +def plot(): + poem_flow = PoemFlow() + poem_flow.plot("PoemFlowPlot") + +if __name__ == "__main__": + kickoff() + plot() +``` + +في هذا المثال، تحدد فئة `PoemFlow` تدفقًا يولّد عدد الجمل، ويستخدم `PoemCrew` لتوليد قصيدة، ثم يحفظ القصيدة في ملف. يتم بدء التدفق باستدعاء دالة `kickoff()`. سيتم توليد PoemFlowPlot بواسطة دالة `plot()`. + +![Flow Visual image](/images/crewai-flow-8.png) + +### تشغيل التدفق + +(اختياري) قبل تشغيل التدفق، يمكنك تثبيت التبعيات بتشغيل: + +```bash +crewai install +``` + +بمجرد تثبيت جميع التبعيات، تحتاج إلى تفعيل البيئة الافتراضية بتشغيل: + +```bash +source .venv/bin/activate +``` + +بعد تفعيل البيئة الافتراضية، يمكنك تشغيل التدفق بتنفيذ أحد الأوامر التالية: + +```bash +crewai run +``` + +أو + +```bash +uv run kickoff +``` + +سيُنفَّذ التدفق، ويجب أن ترى المخرجات في وحدة التحكم. + +## رسم التدفقات + +يمكن أن يوفر تصوير سير عمل الذكاء الاصطناعي رؤى قيمة حول هيكل ومسارات تنفيذ تدفقاتك. تقدم CrewAI أداة تصوير قوية تتيح لك إنشاء رسوم بيانية تفاعلية لتدفقاتك، مما يسهّل فهم وتحسين سير عمل الذكاء الاصطناعي. + +### ما هي الرسوم البيانية؟ + +الرسوم البيانية في CrewAI هي تمثيلات بصرية لسير عمل الذكاء الاصطناعي. تعرض المهام المختلفة واتصالاتها وتدفق البيانات بينها. يساعد هذا التصوير في فهم تسلسل العمليات وتحديد الاختناقات وضمان توافق منطق سير العمل مع توقعاتك. + +### كيفية إنشاء رسم بياني + +توفر CrewAI طريقتين مريحتين لإنشاء رسوم بيانية لتدفقاتك: + +#### الخيار 1: استخدام دالة `plot()` + +إذا كنت تعمل مباشرة مع مثيل تدفق، يمكنك إنشاء رسم بياني باستدعاء دالة `plot()` على كائن التدفق. ستُنشئ هذه الدالة ملف HTML يحتوي على الرسم البياني التفاعلي لتدفقك. + +```python Code +# Assuming you have a flow instance +flow.plot("my_flow_plot") +``` + +سيُنشئ هذا ملفًا باسم `my_flow_plot.html` في مجلدك الحالي. يمكنك فتح هذا الملف في متصفح ويب لعرض الرسم البياني التفاعلي. + +#### الخيار 2: استخدام سطر الأوامر + +إذا كنت تعمل ضمن مشروع CrewAI منظم، يمكنك إنشاء رسم بياني باستخدام سطر الأوامر. هذا مفيد بشكل خاص للمشاريع الأكبر حيث تريد تصوير إعداد التدفق بالكامل. + +```bash +crewai flow plot +``` + +سيُنشئ هذا الأمر ملف HTML مع الرسم البياني لتدفقك، مشابهًا لدالة `plot()`. سيتم حفظ الملف في مجلد مشروعك، ويمكنك فتحه في متصفح ويب لاستكشاف التدفق. + +### فهم الرسم البياني + +سيعرض الرسم البياني المولّد عُقدًا تمثل المهام في تدفقك، مع حواف موجّهة تشير إلى تدفق التنفيذ. الرسم البياني تفاعلي، مما يتيح لك التكبير والتصغير والتمرير فوق العقد لرؤية تفاصيل إضافية. + +من خلال تصوير تدفقاتك، يمكنك الحصول على فهم أوضح لهيكل سير العمل، مما يسهّل تصحيح الأخطاء وتحسين عمليات الذكاء الاصطناعي والتواصل بشأنها مع الآخرين. + +### الخلاصة + +رسم تدفقاتك هو ميزة قوية في CrewAI تعزز قدرتك على تصميم وإدارة سير عمل الذكاء الاصطناعي المعقدة. سواء اخترت استخدام دالة `plot()` أو سطر الأوامر، فإن إنشاء الرسوم البيانية سيوفر لك تمثيلًا بصريًا لسير عملك، مما يساعد في التطوير والعرض. + +## الخطوات التالية + +إذا كنت مهتمًا باستكشاف أمثلة إضافية للتدفقات، لدينا مجموعة متنوعة من التوصيات في مستودع الأمثلة. إليك أربعة أمثلة تدفق محددة، كل منها يعرض حالات استخدام فريدة لمساعدتك في مطابقة نوع مشكلتك الحالية مع مثال محدد: + +1. **تدفق الرد التلقائي على البريد الإلكتروني**: يوضح هذا المثال حلقة لا نهائية حيث تعمل مهمة خلفية باستمرار لأتمتة ردود البريد الإلكتروني. إنها حالة استخدام رائعة للمهام التي تحتاج إلى التنفيذ بشكل متكرر دون تدخل يدوي. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow) + +2. **تدفق تقييم العملاء المحتملين**: يعرض هذا التدفق إضافة تغذية راجعة بشرية والتعامل مع فروع شرطية مختلفة باستخدام الموجّه. إنه مثال ممتاز لكيفية دمج اتخاذ القرارات الديناميكية والرقابة البشرية في سير عملك. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow) + +3. **تدفق كتابة كتاب**: يتفوق هذا المثال في ربط فرق Crew متعددة معًا، حيث تُستخدم مخرجات فريق واحد بواسطة فريق آخر. على وجه التحديد، يقوم فريق واحد بوضع مخطط لكتاب كامل، ويقوم فريق آخر بإنشاء فصول بناءً على المخطط. في النهاية، يتم ربط كل شيء لإنتاج كتاب كامل. هذا التدفق مثالي للعمليات المعقدة متعددة الخطوات التي تتطلب تنسيقًا بين مهام مختلفة. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows) + +4. **تدفق مساعد الاجتماعات**: يوضح هذا التدفق كيفية بث حدث واحد لتشغيل إجراءات متابعة متعددة. على سبيل المثال، بعد اكتمال اجتماع، يمكن للتدفق تحديث لوحة Trello وإرسال رسالة Slack وحفظ النتائج. إنه مثال رائع للتعامل مع نتائج متعددة من حدث واحد، مما يجعله مثاليًا لإدارة المهام الشاملة وأنظمة الإشعارات. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow) + +من خلال استكشاف هذه الأمثلة، يمكنك الحصول على رؤى حول كيفية الاستفادة من تدفقات CrewAI لحالات استخدام متنوعة، من أتمتة المهام المتكررة إلى إدارة العمليات المعقدة متعددة الخطوات مع اتخاذ القرارات الديناميكية والتغذية الراجعة البشرية. + +أيضًا، شاهد فيديو YouTube الخاص بنا حول كيفية استخدام التدفقات في CrewAI أدناه! + + + +## تشغيل التدفقات + +هناك طريقتان لتشغيل التدفق: + +### استخدام واجهة Flow API + +يمكنك تشغيل تدفق برمجيًا عن طريق إنشاء مثيل من فئة التدفق واستدعاء دالة `kickoff()`: + +```python +flow = ExampleFlow() +result = flow.kickoff() +``` + +### بث تنفيذ التدفق + +للحصول على رؤية فورية لتنفيذ التدفق، يمكنك تفعيل البث لتلقي المخرجات فور توليدها: + +```python +class StreamingFlow(Flow): + stream = True # Enable streaming + + @start() + def research(self): + # Your flow implementation + pass + +# Iterate over streaming output +flow = StreamingFlow() +streaming = flow.kickoff() +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access final result +result = streaming.result +``` + +تعرّف على المزيد حول البث في دليل [بث تنفيذ التدفق](/ar/learn/streaming-flow-execution). + +## الذاكرة في التدفقات + +يتمتع كل تدفق تلقائيًا بإمكانية الوصول إلى نظام [الذاكرة](/concepts/memory) الموحد في CrewAI. يمكنك تخزين الذكريات واسترجاعها واستخراجها مباشرة داخل أي دالة تدفق باستخدام ثلاث دوال مساعدة مدمجة. + +### الدوال المدمجة + +| الدالة | الوصف | +| :--- | :--- | +| `self.remember(content, **kwargs)` | تخزين المحتوى في الذاكرة. تقبل `scope` و `categories` و `metadata` و `importance` اختياريًا. | +| `self.recall(query, **kwargs)` | استرجاع الذكريات ذات الصلة. تقبل `scope` و `categories` و `limit` و `depth` اختياريًا. | +| `self.extract_memories(content)` | تفكيك النص الخام إلى عبارات ذاكرة منفصلة ومستقلة. | + +يتم إنشاء مثيل `Memory()` افتراضي تلقائيًا عند تهيئة التدفق. يمكنك أيضًا تمرير مثيل مخصص: + +```python +from crewai.flow.flow import Flow +from crewai import Memory + +custom_memory = Memory( + recency_weight=0.5, + recency_half_life_days=7, + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) + +flow = MyFlow(memory=custom_memory) +``` + +### مثال: تدفق البحث والتحليل + +```python +from crewai.flow.flow import Flow, listen, start + + +class ResearchAnalysisFlow(Flow): + @start() + def gather_data(self): + # Simulate research findings + findings = ( + "PostgreSQL handles 10k concurrent connections with connection pooling. " + "MySQL caps at around 5k. MongoDB scales horizontally but adds complexity." + ) + + # Extract atomic facts and remember each one + memories = self.extract_memories(findings) + for mem in memories: + self.remember(mem, scope="/research/databases") + + return findings + + @listen(gather_data) + def analyze(self, raw_findings): + # Recall relevant past research (from this run or previous runs) + past = self.recall("database performance and scaling", limit=10, depth="shallow") + + context_lines = [f"- {m.record.content}" for m in past] + context = "\n".join(context_lines) if context_lines else "No prior context." + + return { + "new_findings": raw_findings, + "prior_context": context, + "total_memories": len(past), + } + + +flow = ResearchAnalysisFlow() +result = flow.kickoff() +print(result) +``` + +نظرًا لأن الذاكرة تستمر عبر عمليات التشغيل (مدعومة بـ LanceDB على القرص)، فإن خطوة `analyze` ستستدعي النتائج من عمليات التنفيذ السابقة أيضًا -- مما يتيح تدفقات تتعلم وتراكم المعرفة بمرور الوقت. + +انظر [وثائق الذاكرة](/concepts/memory) لمزيد من التفاصيل حول النطاقات والشرائح والتسجيل المركب وإعداد المُضمِّن والمزيد. + +### استخدام CLI + +بدءًا من الإصدار 0.103.0، يمكنك تشغيل التدفقات باستخدام أمر `crewai run`: + +```shell +crewai run +``` + +يكتشف هذا الأمر تلقائيًا ما إذا كان مشروعك تدفقًا (بناءً على إعداد `type = "flow"` في pyproject.toml الخاص بك) ويشغّله وفقًا لذلك. هذه هي الطريقة الموصى بها لتشغيل التدفقات من سطر الأوامر. + +أمر `crewai flow kickoff` القديم deprecated. استخدم `crewai run` لكل من فرق Crew والتدفقات. diff --git a/docs/v1.15.1/ar/concepts/knowledge.mdx b/docs/v1.15.1/ar/concepts/knowledge.mdx new file mode 100644 index 000000000..807e0801e --- /dev/null +++ b/docs/v1.15.1/ar/concepts/knowledge.mdx @@ -0,0 +1,1095 @@ +--- +title: المعرفة +description: ما هي المعرفة في CrewAI وكيفية استخدامها. +icon: book +mode: "wide" +--- + +## نظرة عامة + +المعرفة في CrewAI هي نظام قوي يتيح لوكلاء الذكاء الاصطناعي الوصول إلى مصادر المعلومات الخارجية واستخدامها أثناء مهامهم. +فكّر فيها كمنح وكلائك مكتبة مرجعية يمكنهم الرجوع إليها أثناء العمل. + + + الفوائد الرئيسية لاستخدام المعرفة: + - تعزيز الوكلاء بمعلومات خاصة بالمجال + - دعم القرارات ببيانات من العالم الحقيقي + - الحفاظ على السياق عبر المحادثات + - بناء الاستجابات على معلومات واقعية + + +## أمثلة البدء السريع + + +لمصادر المعرفة المستندة إلى الملفات، تأكد من وضع ملفاتك في مجلد `knowledge` في جذر مشروعك. +أيضًا، استخدم المسارات النسبية من مجلد `knowledge` عند إنشاء المصدر. + + +### إعداد عميل المتجه (RAG) + +يوفر CrewAI تجريدًا لعميل RAG محايد بالنسبة للمزود لمتاجر المتجهات. المزود الافتراضي هو ChromaDB، ويتم دعم Qdrant أيضًا. يمكنك التبديل بين المزودين باستخدام أدوات الإعداد. + +المدعوم حاليًا: +- ChromaDB (افتراضي) +- Qdrant + +```python Code +from crewai.rag.config.utils import set_rag_config, get_rag_client, clear_rag_config + +# ChromaDB (default) +from crewai.rag.chromadb.config import ChromaDBConfig +set_rag_config(ChromaDBConfig()) +chromadb_client = get_rag_client() + +# Qdrant +from crewai.rag.qdrant.config import QdrantConfig +set_rag_config(QdrantConfig()) +qdrant_client = get_rag_client() + +# Example operations (same API for any provider) +client = qdrant_client # or chromadb_client +client.create_collection(collection_name="docs") +client.add_documents( + collection_name="docs", + documents=[{"id": "1", "content": "CrewAI enables collaborative AI agents."}], +) +results = client.search(collection_name="docs", query="collaborative agents", limit=3) + +clear_rag_config() # optional reset +``` + +عميل RAG هذا منفصل عن التخزين المدمج في المعرفة. استخدمه عندما تحتاج إلى تحكم مباشر في متجر المتجهات أو خطوط أنابيب استرجاع مخصصة. + +### مثال المعرفة النصية الأساسية + +```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?"}) +``` + +### مثال معرفة محتوى الويب + + + تحتاج إلى تثبيت `docling` لكي يعمل المثال التالي: `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."} +) +``` + +## مصادر المعرفة المدعومة + +يدعم CrewAI أنواعًا متعددة من مصادر المعرفة جاهزة للاستخدام: + + + + - سلاسل نصية خام + - ملفات نصية (.txt) + - مستندات PDF + + + - ملفات CSV + - جداول بيانات Excel + - مستندات JSON + + + +### مصدر معرفة الملفات النصية +```python +from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource + +text_source = TextFileKnowledgeSource( + file_paths=["document.txt", "another.txt"] +) +``` + +### مصدر معرفة PDF +```python +from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource + +pdf_source = PDFKnowledgeSource( + file_paths=["document.pdf", "another.pdf"] +) +``` + +### مصدر معرفة CSV +```python +from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource + +csv_source = CSVKnowledgeSource( + file_paths=["data.csv"] +) +``` + +### مصدر معرفة Excel +```python +from crewai.knowledge.source.excel_knowledge_source import ExcelKnowledgeSource + +excel_source = ExcelKnowledgeSource( + file_paths=["spreadsheet.xlsx"] +) +``` + +### مصدر معرفة JSON +```python +from crewai.knowledge.source.json_knowledge_source import JSONKnowledgeSource + +json_source = JSONKnowledgeSource( + file_paths=["data.json"] +) +``` + + + يُرجى التأكد من إنشاء مجلد ./knowledge. يجب وضع جميع ملفات المصادر (مثل .txt و .pdf و .xlsx و .json) في هذا المجلد للإدارة المركزية. + + +## معرفة Agent مقابل معرفة Crew: دليل شامل + + +**فهم مستويات المعرفة**: يدعم CrewAI المعرفة على مستوى كل من Agent و Crew. يوضح هذا القسم بالضبط كيف يعمل كل منهما، ومتى يتم تهيئتهما، ويعالج المفاهيم الخاطئة الشائعة حول التبعيات. + + +### كيف تعمل تهيئة المعرفة فعليًا + +إليك ما يحدث بالضبط عند استخدام المعرفة: + +#### معرفة على مستوى Agent (مستقلة) +```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 +``` + +#### ما يحدث أثناء `crew.kickoff()` + +عند استدعاء `crew.kickoff()`، إليك التسلسل الدقيق: + +```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() +``` + +#### استقلالية التخزين + +يستخدم كل مستوى معرفة مجموعات تخزين مستقلة: + +```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 +``` + +### أمثلة عملية كاملة + +#### المثال 1: معرفة Agent فقط +```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 +``` + +#### المثال 2: معرفة Agent و 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 +``` + +#### المثال 3: عدة Agents بمعارف مختلفة +```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-generativeai", + "config": {"model_name": "gemini-embedding-001"} + } +) + +# Each agent gets only their specific knowledge +# Each can use different embedding providers +``` + + +على عكس الاسترجاع من قاعدة بيانات متجهات باستخدام أداة، فإن الوكلاء المُحمّلين مسبقًا بالمعرفة لن يحتاجوا إلى شخصية أو مهمة استرجاع. +ما عليك سوى إضافة مصادر المعرفة ذات الصلة التي يحتاجها Agent أو Crew للعمل. + +يمكن إضافة مصادر المعرفة على مستوى Agent أو Crew. +مصادر المعرفة على مستوى Crew سيستخدمها **جميع الوكلاء** في الفريق. +مصادر المعرفة على مستوى Agent سيستخدمها **الوكيل المحدد** المُحمّل بالمعرفة. + + +## إعداد المعرفة + +يمكنك تهيئة إعداد المعرفة لـ Crew أو Agent. + +```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`: هو عدد المستندات ذات الصلة المُعادة. القيمة الافتراضية هي 3. + `score_threshold`: هو الحد الأدنى لدرجة اعتبار المستند ذا صلة. القيمة الافتراضية هي 0.35. + + +## معاملات المعرفة المدعومة + + + قائمة مصادر المعرفة التي توفر المحتوى للتخزين والاستعلام. يمكن أن تشمل ملفات PDF و CSV و Excel و JSON والملفات النصية أو المحتوى النصي. + + + اسم المجموعة التي سيتم تخزين المعرفة فيها. يُستخدم لتحديد مجموعات معرفة مختلفة. القيمة الافتراضية هي "knowledge" إذا لم يتم تحديدها. + + +إعداد تخزين مخصص لإدارة كيفية تخزين المعرفة واسترجاعها. إذا لم يتم تحديده، سيتم إنشاء تخزين افتراضي. + + +## شفافية تخزين المعرفة + + +**فهم تخزين المعرفة**: يخزّن CrewAI مصادر المعرفة تلقائيًا في مجلدات خاصة بالمنصة باستخدام ChromaDB للتخزين المتجهي. فهم هذه المواقع والإعدادات الافتراضية يساعد في النشر في بيئة الإنتاج وتصحيح الأخطاء وإدارة التخزين. + + +### أين يخزّن CrewAI ملفات المعرفة + +بشكل افتراضي، يستخدم CrewAI نفس نظام التخزين مثل الذاكرة، حيث يخزّن المعرفة في مجلدات خاصة بالمنصة: + +#### مواقع التخزين الافتراضية حسب المنصة + +**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}\ +``` + +### معرفة موقع تخزين المعرفة + +لرؤية المكان الذي يخزّن فيه CrewAI ملفات المعرفة بالضبط: + +```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.") +``` + +### التحكم في مواقع تخزين المعرفة + +#### الخيار 1: متغير البيئة (موصى به) +```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=[...] +) +``` + +#### الخيار 2: تخزين معرفة مخصص +```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 +``` + +#### الخيار 3: تخزين معرفة خاص بالمشروع +```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 +``` + +### سلوك مزود التضمين الافتراضي + + +**مزود التضمين الافتراضي**: يستخدم CrewAI افتراضيًا تضمينات OpenAI (`text-embedding-3-small`) لتخزين المعرفة، حتى عند استخدام مزودي LLM مختلفين. يمكنك تخصيص هذا بسهولة ليتوافق مع إعدادك. + + +#### فهم السلوك الافتراضي +```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 +) +``` + +#### تخصيص مزودي تضمين المعرفة +```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-generativeai", + "config": { + "model_name": "gemini-embedding-001", + "api_key": "your-google-key" + } + } +) +``` + +#### إعداد تضمينات Azure OpenAI + +عند استخدام تضمينات Azure OpenAI: +1. تأكد من نشر نموذج التضمين في منصة Azure أولًا +2. ثم تحتاج إلى استخدام الإعداد التالي: + +```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" + } + } +) +``` + +## الميزات المتقدمة + +### إعادة صياغة الاستعلام + +ينفذ CrewAI آلية إعادة صياغة استعلام ذكية لتحسين استرجاع المعرفة. عندما يحتاج وكيل إلى البحث في مصادر المعرفة، يتم تحويل موجّه المهمة الخام تلقائيًا إلى استعلام بحث أكثر فعالية. + +#### كيف تعمل إعادة صياغة الاستعلام + +1. عندما ينفذ وكيل مهمة بمصادر معرفة متاحة، يتم تشغيل دالة `_get_knowledge_search_query` +2. يُستخدم LLM الخاص بالوكيل لتحويل موجّه المهمة الأصلي إلى استعلام بحث محسّن +3. يُستخدم هذا الاستعلام المحسّن بعد ذلك لاسترجاع المعلومات ذات الصلة من مصادر المعرفة + +#### فوائد إعادة صياغة الاستعلام + + + + من خلال التركيز على المفاهيم الرئيسية وإزالة المحتوى غير ذي الصلة، تساعد إعادة صياغة الاستعلام في استرجاع معلومات أكثر صلة. + + + تم تصميم الاستعلامات المُعاد صياغتها لتكون أكثر تحديدًا ووعيًا بالسياق لاسترجاع قاعدة بيانات المتجهات. + + + +#### مثال + +```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?" +``` + +الاستعلام المُعاد صياغته أكثر تركيزًا على الحاجة الأساسية للمعلومات ويزيل التعليمات غير ذات الصلة حول تنسيق المخرجات. + + + هذه الآلية تلقائية بالكامل ولا تتطلب أي إعداد من المستخدمين. يُستخدم LLM الخاص بالوكيل لتنفيذ إعادة صياغة الاستعلام، لذا فإن استخدام LLM أكثر قدرة يمكن أن يحسّن جودة الاستعلامات المُعاد صياغتها. + + +### أحداث المعرفة + +يُصدر CrewAI أحداثًا أثناء عملية استرجاع المعرفة يمكنك الاستماع إليها باستخدام نظام الأحداث. تتيح لك هذه الأحداث مراقبة وتصحيح أخطاء وتحليل كيفية استرجاع المعرفة واستخدامها بواسطة وكلائك. + +#### أحداث المعرفة المتاحة + +- **KnowledgeRetrievalStartedEvent**: يُصدر عندما يبدأ وكيل في استرجاع المعرفة من المصادر +- **KnowledgeRetrievalCompletedEvent**: يُصدر عند اكتمال استرجاع المعرفة، بما في ذلك الاستعلام المُستخدم والمحتوى المُسترجع +- **KnowledgeQueryStartedEvent**: يُصدر عند بدء استعلام مصادر المعرفة +- **KnowledgeQueryCompletedEvent**: يُصدر عند اكتمال الاستعلام بنجاح +- **KnowledgeQueryFailedEvent**: يُصدر عند فشل استعلام مصادر المعرفة +- **KnowledgeSearchQueryFailedEvent**: يُصدر عند فشل استعلام بحث + +#### مثال: مراقبة استرجاع المعرفة + +```python +from crewai.events import ( + KnowledgeRetrievalStartedEvent, + KnowledgeRetrievalCompletedEvent, + 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() +``` + +لمزيد من المعلومات حول استخدام الأحداث، انظر وثائق [مستمعي الأحداث](/ar/concepts/event-listener). + +### مصادر المعرفة المخصصة + +يتيح لك CrewAI إنشاء مصادر معرفة مخصصة لأي نوع من البيانات عن طريق توسيع فئة `BaseKnowledgeSource`. لنقم بإنشاء مثال عملي يجلب ويعالج مقالات أخبار الفضاء. + +#### مثال مصدر معرفة أخبار الفضاء + + + +```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/) +``` + + + +## تصحيح الأخطاء واستكشاف المشاكل + +### تصحيح مشاكل المعرفة + +#### التحقق من تهيئة معرفة Agent +```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)}") +``` + +#### التحقق من مواقع تخزين المعرفة +```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}") +``` + +#### اختبار استرجاع المعرفة +```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") +``` + +#### فحص مجموعات المعرفة +```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") +``` + +#### التحقق من معالجة المعرفة +```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]}...") +``` + +### مشاكل تخزين المعرفة الشائعة + +**أخطاء "الملف غير موجود":** +```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)}") +``` + +**أخطاء "عدم تطابق أبعاد التضمين":** +```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"}} +) +``` + +**أخطاء "رفض إذن ChromaDB":** +```bash +# Fix storage permissions +chmod -R 755 ~/.local/share/CrewAI/ +``` + +**المعرفة لا تستمر بين عمليات التشغيل:** +```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")) +``` + +### أوامر إعادة تعيين المعرفة + +```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 +``` + +### مسح المعرفة + +إذا كنت بحاجة إلى مسح المعرفة المخزّنة في CrewAI، يمكنك استخدام أمر `crewai reset-memories` مع خيار `--knowledge`. + +```bash Command +crewai reset-memories --knowledge +``` + +هذا مفيد عندما تكون قد حدّثت مصادر المعرفة وتريد التأكد من أن الوكلاء يستخدمون أحدث المعلومات. + +## أفضل الممارسات + + + + - حافظ على أحجام القطع مناسبة لنوع المحتوى + - ضع في اعتبارك تداخل المحتوى للحفاظ على السياق + - نظّم المعلومات ذات الصلة في مصادر معرفة منفصلة + + + + - اضبط أحجام القطع بناءً على تعقيد المحتوى + - أعدّ نماذج تضمين مناسبة + - ضع في اعتبارك استخدام مزودي تضمين محليين لمعالجة أسرع + + + + - مع هيكل الملفات النموذجي الذي يوفره CrewAI، يتم تضمين مصادر المعرفة في كل مرة يتم فيها تشغيل kickoff. + - إذا كانت مصادر المعرفة كبيرة، فإن هذا يؤدي إلى عدم كفاءة وزيادة وقت الاستجابة، حيث يتم تضمين نفس البيانات في كل مرة. + - لحل هذه المشكلة، قم بتهيئة معامل knowledge مباشرة بدلاً من معامل knowledge_sources. + - رابط للمشكلة للحصول على فكرة كاملة [Github Issue](https://github.com/crewAIInc/crewAI/issues/2755) + + + + - استخدم المعرفة على مستوى Agent للمعلومات الخاصة بالدور + - استخدم المعرفة على مستوى Crew للمعلومات المشتركة التي يحتاجها جميع الوكلاء + - عيّن المُضمّنات على مستوى Agent إذا كنت بحاجة إلى استراتيجيات تضمين مختلفة + - استخدم تسمية مجموعات متسقة بالحفاظ على أدوار Agent وصفية + - اختبر تهيئة المعرفة بالتحقق من agent.knowledge بعد kickoff + - راقب مواقع التخزين لفهم أين يتم تخزين المعرفة + - أعد تعيين المعرفة بشكل مناسب باستخدام أنواع الأوامر الصحيحة + + + + - عيّن `CREWAI_STORAGE_DIR` إلى موقع معروف في الإنتاج + - اختر مزودي تضمين صريحين ليتوافقوا مع إعداد LLM وتجنب تعارضات مفاتيح API + - راقب حجم تخزين المعرفة مع نموه مع إضافات المستندات + - نظّم مصادر المعرفة حسب المجال أو الغرض باستخدام أسماء المجموعات + - ضمّن مجلدات المعرفة في استراتيجيات النسخ الاحتياطي والنشر + - عيّن أذونات ملفات مناسبة لملفات المعرفة ومجلدات التخزين + - استخدم متغيرات البيئة لمفاتيح API والإعدادات الحساسة + + diff --git a/docs/v1.15.1/ar/concepts/llms.mdx b/docs/v1.15.1/ar/concepts/llms.mdx new file mode 100644 index 000000000..67b09281b --- /dev/null +++ b/docs/v1.15.1/ar/concepts/llms.mdx @@ -0,0 +1,1513 @@ +--- +title: 'نماذج اللغة الكبيرة (LLMs)' +description: 'دليل شامل لإعداد واستخدام نماذج اللغة الكبيرة (LLMs) في مشاريع CrewAI' +icon: 'microchip-ai' +mode: "wide" +--- + +## نظرة عامة + +يتكامل CrewAI مع مزودي LLM متعددين من خلال حزم SDK الأصلية للمزودين، مما يمنحك المرونة لاختيار النموذج المناسب لحالة الاستخدام الخاصة بك. سيساعدك هذا الدليل على فهم كيفية إعداد واستخدام مزودي LLM المختلفين في مشاريع CrewAI. + + +## ما هي نماذج اللغة الكبيرة؟ + +نماذج اللغة الكبيرة (LLMs) هي الذكاء الأساسي وراء وكلاء CrewAI. تمكّن الوكلاء من فهم السياق واتخاذ القرارات وتوليد استجابات شبيهة بالبشر. إليك ما تحتاج معرفته: + + + + نماذج اللغة الكبيرة هي أنظمة ذكاء اصطناعي مدربة على كميات هائلة من البيانات النصية. تدعم ذكاء وكلاء CrewAI، مما يمكّنهم من فهم وتوليد نصوص شبيهة بالبشر. + + + تحدد نافذة السياق مقدار النص الذي يمكن لـ LLM معالجته في وقت واحد. النوافذ الأكبر (مثل 128K رمز) تتيح سياقًا أكثر لكنها قد تكون أكثر تكلفة وأبطأ. + + + تتحكم درجة الحرارة (0.0 إلى 1.0) في عشوائية الاستجابة. القيم المنخفضة (مثل 0.2) تنتج مخرجات أكثر تركيزًا وحتمية، بينما القيم الأعلى (مثل 0.8) تزيد الإبداع والتنوع. + + + يقدم كل مزود LLM (مثل OpenAI و Anthropic و Google) نماذج مختلفة بقدرات وأسعار وميزات متفاوتة. اختر بناءً على احتياجاتك من الدقة والسرعة والتكلفة. + + + +## إعداد LLM الخاص بك + +هناك أماكن مختلفة في كود CrewAI حيث يمكنك تحديد النموذج المُستخدم. بمجرد تحديد النموذج، ستحتاج إلى توفير الإعداد (مثل مفتاح API) لكل مزود نموذج تستخدمه. انظر قسم [أمثلة إعداد المزودين](#أمثلة-إعداد-المزودين) لمزودك. + + + + أبسط طريقة للبدء. عيّن النموذج في بيئتك مباشرة، من خلال ملف `.env` أو في كود تطبيقك. إذا استخدمت `crewai create` لبدء مشروعك، سيكون مُعيّنًا بالفعل. + + ```bash .env + MODEL=model-id # e.g. gpt-4o, gemini-2.0-flash, claude-3-sonnet-... + + # Be sure to set your API keys here too. See the Provider + # section below. + ``` + + + لا تقم أبدًا بتأكيد مفاتيح API في التحكم بالإصدارات. استخدم ملفات البيئة (.env) أو إدارة أسرار نظامك. + + + + أنشئ ملف YAML لتعريف إعدادات الوكلاء. هذه الطريقة رائعة للتحكم بالإصدارات والتعاون بين الفريق: + + ```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... + # (see provider configuration examples below for more) + ``` + + + يتيح لك إعداد YAML: + - التحكم بإصدارات إعدادات الوكلاء + - التبديل بسهولة بين النماذج المختلفة + - مشاركة الإعدادات بين أعضاء الفريق + - توثيق خيارات النماذج وأغراضها + + + + لأقصى مرونة، أعدّ LLMs مباشرة في كود Python: + + ```python {4,8} + from crewai import LLM + + # Basic configuration + llm = LLM(model="model-id-here") # gpt-4o, gemini-2.0-flash, anthropic/claude... + + # Advanced configuration with detailed parameters + llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + temperature=0.7, # Higher for more creative outputs + timeout=120, # Seconds to wait for response + max_tokens=4000, # Maximum length of response + top_p=0.9, # Nucleus sampling parameter + frequency_penalty=0.1 , # Reduce repetition + presence_penalty=0.1, # Encourage topic diversity + response_format={"type": "json"}, # For structured outputs + seed=42 # For reproducible results + ) + ``` + + + شرح المعاملات: + - `temperature`: تتحكم في العشوائية (0.0-1.0) + - `timeout`: أقصى وقت انتظار للاستجابة + - `max_tokens`: تحدد طول الاستجابة + - `top_p`: بديل لدرجة الحرارة للعينات + - `frequency_penalty`: تقلل تكرار الكلمات + - `presence_penalty`: تشجع موضوعات جديدة + - `response_format`: تحدد هيكل المخرجات + - `seed`: تضمن مخرجات متسقة + + + + + + يوفر CrewAI تكاملات SDK أصلية لـ OpenAI و Anthropic و Google (Gemini API) و Azure و AWS Bedrock و Snowflake Cortex -- لا حاجة لتثبيت إضافي بخلاف الملحقات الخاصة بالمزود (مثل `uv add "crewai[openai]"`). + + جميع المزودين الآخرين مدعومون بواسطة **LiteLLM**. إذا كنت تخطط لاستخدام أي منهم، أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + +## أمثلة إعداد المزودين + +يدعم CrewAI العديد من مزودي LLM، كل منهم يقدم ميزات فريدة وطرق مصادقة وقدرات نماذج. +في هذا القسم، ستجد أمثلة مفصلة تساعدك في اختيار وإعداد وتحسين LLM الأنسب لاحتياجات مشروعك. + + + + يوفر CrewAI تكاملًا أصليًا مع OpenAI من خلال OpenAI Python SDK. + + ```toml Code + # Required + OPENAI_API_KEY=sk-... + + # Optional + OPENAI_BASE_URL= + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4o", + api_key="your-api-key", # Or set OPENAI_API_KEY + temperature=0.7, + max_tokens=4000 + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4o", + api_key="your-api-key", + base_url="https://api.openai.com/v1", # Optional custom endpoint + organization="org-...", # Optional organization ID + project="proj_...", # Optional project ID + temperature=0.7, + max_tokens=4000, + max_completion_tokens=4000, # For newer models + top_p=0.9, + frequency_penalty=0.1, + presence_penalty=0.1, + stop=["END"], + seed=42, # For reproducible outputs + stream=True, # Enable streaming + timeout=60.0, # Request timeout in seconds + max_retries=3, # Maximum retry attempts + logprobs=True, # Return log probabilities + top_logprobs=5, # Number of most likely tokens + reasoning_effort="medium" # For o1 models: low, medium, high + ) + ``` + + **المخرجات المهيكلة:** + ```python Code + from pydantic import BaseModel + from crewai import LLM + + class ResponseFormat(BaseModel): + name: str + age: int + summary: str + + llm = LLM( + model="openai/gpt-4o", + ) + ``` + + **متغيرات البيئة المدعومة:** + - `OPENAI_API_KEY`: مفتاح OpenAI API (مطلوب) + - `OPENAI_BASE_URL`: عنوان URL مخصص لـ OpenAI API (اختياري) + + **الميزات:** + - دعم استدعاء الدوال الأصلي (باستثناء نماذج o1) + - مخرجات منظمة مع JSON schema + - دعم البث للاستجابات في الوقت الفعلي + - تتبع استخدام الرموز + - دعم تسلسلات التوقف (باستثناء نماذج o1) + - احتمالات السجل لرؤى على مستوى الرموز + - التحكم في جهد الاستدلال لنماذج o1 + + **النماذج المدعومة:** + + | النموذج | نافذة السياق | الأفضل لـ | + |---------------------|------------------|-----------------------------------------------| + | gpt-4.1 | 1M tokens | أحدث نموذج بقدرات محسّنة | + | gpt-4.1-mini | 1M tokens | إصدار فعال بسياق كبير | + | gpt-4.1-nano | 1M tokens | متغير فائق الكفاءة | + | gpt-4o | 128,000 tokens | محسّن للسرعة والذكاء | + | gpt-4o-mini | 200,000 tokens | فعال من حيث التكلفة بسياق كبير | + | gpt-4-turbo | 128,000 tokens | المحتوى الطويل، تحليل المستندات | + | gpt-4 | 8,192 tokens | مهام الدقة العالية، الاستدلال المعقد | + | o1 | 200,000 tokens | الاستدلال المتقدم، حل المشكلات المعقدة | + | o1-preview | 128,000 tokens | معاينة قدرات الاستدلال | + | o1-mini | 128,000 tokens | نموذج استدلال فعال | + | o3-mini | 200,000 tokens | نموذج استدلال خفيف | + | o4-mini | 200,000 tokens | استدلال فعال من الجيل التالي | + + **Responses API:** + + تقدم OpenAI واجهتي API: Chat Completions (الافتراضية) و Responses API الأحدث. تم تصميم Responses API من الأساس مع دعم أصلي متعدد الوسائط -- النص والصور والصوت واستدعاءات الدوال كلها مكوّنات أساسية. توفر أداءً أفضل مع نماذج الاستدلال وتدعم ميزات إضافية مثل السلسلة التلقائية والأدوات المدمجة. + + ```python Code + from crewai import LLM + + # Use the Responses API instead of Chat Completions + llm = LLM( + model="openai/gpt-4o", + api="responses", # Enable Responses API + store=True, # Store responses for multi-turn (optional) + auto_chain=True, # Auto-chain for reasoning models (optional) + ) + ``` + + **معاملات Responses API:** + - `api`: عيّن إلى `"responses"` لاستخدام Responses API (الافتراضي: `"completions"`) + - `instructions`: تعليمات على مستوى النظام (Responses API فقط) + - `store`: ما إذا كان يجب تخزين الاستجابات للمحادثات متعددة الأدوار + - `previous_response_id`: معرّف الاستجابة السابقة للمحادثات متعددة الأدوار + - `include`: بيانات إضافية لتضمينها في الاستجابة (مثل `["reasoning.encrypted_content"]`) + - `builtin_tools`: قائمة أدوات OpenAI المدمجة: `"web_search"`, `"file_search"`, `"code_interpreter"`, `"computer_use"` + - `parse_tool_outputs`: إعادة `ResponsesAPIResult` منظمة مع مخرجات أدوات مدمجة محللة + - `auto_chain`: تتبع واستخدام معرّفات الاستجابة تلقائيًا للمحادثات متعددة الأدوار + - `auto_chain_reasoning`: تتبع عناصر الاستدلال المشفرة للامتثال لـ ZDR + + + استخدم Responses API للمشاريع الجديدة، خاصة عند العمل مع نماذج الاستدلال (o1, o3, o4) أو عندما تحتاج دعمًا أصليًا متعدد الوسائط لـ [الملفات](/ar/concepts/files). + + + **ملاحظة:** لاستخدام OpenAI، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[openai]" + ``` + + + + توفر Meta Llama API الوصول إلى عائلة نماذج اللغة الكبيرة من Meta. + الـ API متاحة عبر [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website). + عيّن متغيرات البيئة التالية في ملف `.env`: + + ```toml Code + # Meta Llama API Key Configuration + LLAMA_API_KEY=LLM|your_api_key_here + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + from crewai import LLM + + # Initialize Meta Llama LLM + llm = LLM( + model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8", + temperature=0.8, + stop=["END"], + seed=42 + ) + ``` + + جميع النماذج المدرجة هنا https://llama.developer.meta.com/docs/models/ مدعومة. + + | معرّف النموذج | طول سياق الإدخال | طول سياق المخرجات | وسائط الإدخال | وسائط المخرجات | + | --- | --- | --- | --- | --- | + | `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | نص، صورة | نص | + | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | نص، صورة | نص | + | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | نص | نص | + | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | نص | نص | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع Snowflake Cortex REST API عبر endpoint Chat Completions المتوافق مع OpenAI. تستخدم نماذج `snowflake/...` هذا المسار بدون fallback إلى LiteLLM. يدعم Snowflake Cortex في CrewAI حاليًا Chat Completions فقط، لذلك استخدم وضع `api` الافتراضي ولا تضبط `api="responses"`. + + ```toml Code + # Required + SNOWFLAKE_PAT= + SNOWFLAKE_ACCOUNT_URL=https://.snowflakecomputing.com + + # Alternative account configuration + SNOWFLAKE_ACCOUNT= + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/openai-gpt-4.1", + temperature=0.7, + max_completion_tokens=1024, + ) + ``` + + **نماذج Claude على Cortex:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/claude-sonnet-4-5", + max_completion_tokens=1024, + stream=True, + ) + ``` + + **متغيرات البيئة المدعومة:** + - `SNOWFLAKE_PAT` أو `SNOWFLAKE_TOKEN` أو `SNOWFLAKE_JWT`: الرمز المستخدم كاعتماد Bearer + - `SNOWFLAKE_ACCOUNT_URL`: عنوان URL الكامل لحساب Snowflake + - `SNOWFLAKE_ACCOUNT` أو `SNOWFLAKE_ACCOUNT_ID` أو `SNOWFLAKE_ACCOUNT_IDENTIFIER`: معرف الحساب المستخدم لبناء URL + + تستخدم طلبات Snowflake REST الدور الافتراضي للمستخدم. تأكد من أن هذا الدور لديه `SNOWFLAKE.CORTEX_USER` أو `SNOWFLAKE.CORTEX_REST_API_USER`. لا يتطلب endpoint Cortex REST Chat Completions معاملات database أو schema أو warehouse أو role صريح. + + **الميزات:** + - اختيار provider أصلي باستخدام `model="snowflake/"` + - Chat Completions مع streaming وبدونه فقط؛ `api="responses"` غير مدعوم + - تتبع استخدام الرموز + - استدعاء الدوال لنماذج OpenAI و Claude المستضافة في Snowflake + - إزالة assistant prefill النهائي غير الصالح تلقائيًا لنماذج Claude في Snowflake + + + + يوفر CrewAI تكاملًا أصليًا مع Anthropic من خلال Anthropic Python SDK. + + ```toml Code + # Required + ANTHROPIC_API_KEY=sk-ant-... + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="anthropic/claude-3-5-sonnet-20241022", + api_key="your-api-key", # Or set ANTHROPIC_API_KEY + max_tokens=4096 # Required for Anthropic + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="anthropic/claude-3-5-sonnet-20241022", + api_key="your-api-key", + base_url="https://api.anthropic.com", # Optional custom endpoint + temperature=0.7, + max_tokens=4096, # Required parameter + top_p=0.9, + stop_sequences=["END", "STOP"], # Anthropic uses stop_sequences + stream=True, # Enable streaming + timeout=60.0, # Request timeout in seconds + max_retries=3 # Maximum retry attempts + ) + ``` + + **التفكير الموسّع (Claude Sonnet 4 وما بعده):** + + يدعم CrewAI ميزة التفكير الموسّع من Anthropic، التي تتيح لـ Claude التفكير في المشكلات بطريقة أكثر شبهًا بالبشر قبل الاستجابة. مفيد بشكل خاص لمهام الاستدلال والتحليل وحل المشكلات المعقدة. + + ```python Code + from crewai import LLM + + # Enable extended thinking with default settings + llm = LLM( + model="anthropic/claude-sonnet-4", + thinking={"type": "enabled"}, + max_tokens=10000 + ) + + # Configure thinking with budget control + llm = LLM( + model="anthropic/claude-sonnet-4", + thinking={ + "type": "enabled", + "budget_tokens": 5000 # Limit thinking tokens + }, + max_tokens=10000 + ) + ``` + + **خيارات إعداد التفكير:** + - `type`: عيّن إلى `"enabled"` لتفعيل وضع التفكير الموسّع + - `budget_tokens` (اختياري): أقصى رموز للتفكير (يساعد في التحكم بالتكاليف) + + **النماذج التي تدعم التفكير الموسّع:** + - `claude-sonnet-4` والنماذج الأحدث + - `claude-3-7-sonnet` (مع قدرات التفكير الموسّع) + + **متى تستخدم التفكير الموسّع:** + - الاستدلال المعقد وحل المشكلات متعددة الخطوات + - الحسابات الرياضية والبراهين + - تحليل الكود وتصحيح الأخطاء + - التخطيط الاستراتيجي واتخاذ القرارات + - البحث والمهام التحليلية + + **ملاحظة:** يستهلك التفكير الموسّع رموزًا إضافية لكنه يمكن أن يحسّن جودة الاستجابة بشكل كبير للمهام المعقدة. + + **متغيرات البيئة المدعومة:** + - `ANTHROPIC_API_KEY`: مفتاح Anthropic API (مطلوب) + + **الميزات:** + - دعم استخدام الأدوات الأصلي لنماذج Claude 3+ + - دعم التفكير الموسّع لـ Claude Sonnet 4+ + - دعم البث للاستجابات في الوقت الفعلي + - معالجة تلقائية لرسائل النظام + - تسلسلات التوقف للتحكم في المخرجات + - تتبع استخدام الرموز + - محادثات استخدام أدوات متعددة الأدوار + + **ملاحظات مهمة:** + - `max_tokens` معامل **مطلوب** لجميع نماذج Anthropic + - يستخدم Claude `stop_sequences` بدلاً من `stop` + - يتم التعامل مع رسائل النظام بشكل منفصل عن رسائل المحادثة + - يجب أن تكون الرسالة الأولى من المستخدم (يتم التعامل معها تلقائيًا) + - يجب أن تتناوب الرسائل بين المستخدم والمساعد + + **النماذج المدعومة:** + + | النموذج | نافذة السياق | الأفضل لـ | + |------------------------------|------------------|-----------------------------------------------| + | claude-sonnet-4 | 200,000 tokens | الأحدث مع قدرات التفكير الموسّع | + | claude-3-7-sonnet | 200,000 tokens | الاستدلال المتقدم والمهام الوكيلية | + | claude-3-5-sonnet-20241022 | 200,000 tokens | أحدث Sonnet بأفضل أداء | + | claude-3-5-haiku | 200,000 tokens | نموذج سريع وصغير للاستجابات السريعة | + | claude-3-opus | 200,000 tokens | الأكثر قدرة للمهام المعقدة | + | claude-3-sonnet | 200,000 tokens | توازن بين الذكاء والسرعة | + | claude-3-haiku | 200,000 tokens | الأسرع للمهام البسيطة | + | claude-2.1 | 200,000 tokens | سياق موسّع، هلوسات أقل | + | claude-2 | 100,000 tokens | نموذج متعدد الاستخدامات | + | claude-instant | 100,000 tokens | سريع وفعال من حيث التكلفة للمهام اليومية | + + **ملاحظة:** لاستخدام Anthropic، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[anthropic]" + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع Google Gemini من خلال Google Gen AI Python SDK. + + عيّن مفتاح API في ملف `.env`. إذا كنت بحاجة إلى مفتاح، تحقق من [AI Studio](https://aistudio.google.com/apikey). + + ```toml .env + # Required (one of the following) + GOOGLE_API_KEY= + GEMINI_API_KEY= + + # For Vertex AI Express mode (API key authentication) + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + + # For Vertex AI with service account + GOOGLE_CLOUD_PROJECT= + GOOGLE_CLOUD_LOCATION= # Defaults to us-central1 + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + api_key="your-api-key", # Or set GOOGLE_API_KEY/GEMINI_API_KEY + temperature=0.7 + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.5-flash", + api_key="your-api-key", + temperature=0.7, + top_p=0.9, + top_k=40, # Top-k sampling parameter + max_output_tokens=8192, + stop_sequences=["END", "STOP"], + stream=True, # Enable streaming + safety_settings={ + "HARM_CATEGORY_HARASSMENT": "BLOCK_NONE", + "HARM_CATEGORY_HATE_SPEECH": "BLOCK_NONE" + } + ) + ``` + + **وضع Vertex AI Express (مصادقة بمفتاح API):** + + يتيح لك وضع Vertex AI Express استخدام Vertex AI مع مصادقة بسيطة بمفتاح API بدلاً من بيانات اعتماد حساب الخدمة. هذه أسرع طريقة للبدء مع Vertex AI. + + لتفعيل وضع Express، عيّن متغيري البيئة في ملف `.env`: + ```toml .env + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + ``` + + ثم استخدم LLM كالمعتاد: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7 + ) + ``` + + + للحصول على مفتاح API لوضع Express: + - مستخدمو Google Cloud الجدد: احصل على [مفتاح API لوضع Express](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey) + - مستخدمو Google Cloud الحاليون: احصل على [مفتاح Google Cloud API مرتبط بحساب خدمة](https://cloud.google.com/docs/authentication/api-keys) + + لمزيد من التفاصيل، انظر [وثائق وضع Vertex AI Express](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey). + + + **إعداد Vertex AI (حساب خدمة):** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-1.5-pro", + project="your-gcp-project-id", + location="us-central1" # GCP region + ) + ``` + + **متغيرات البيئة المدعومة:** + - `GOOGLE_API_KEY` أو `GEMINI_API_KEY`: مفتاح Google API (مطلوب لـ Gemini API ووضع Vertex AI Express) + - `GOOGLE_GENAI_USE_VERTEXAI`: عيّن إلى `true` لاستخدام Vertex AI (مطلوب لوضع Express) + - `GOOGLE_CLOUD_PROJECT`: معرّف مشروع Google Cloud (لـ Vertex AI مع حساب خدمة) + - `GOOGLE_CLOUD_LOCATION`: موقع GCP (الافتراضي `us-central1`) + + **الميزات:** + - دعم استدعاء الدوال الأصلي لنماذج Gemini 1.5+ و 2.x + - دعم البث للاستجابات في الوقت الفعلي + - قدرات متعددة الوسائط (نص، صور، فيديو) + - إعداد إعدادات الأمان + - دعم لكل من Gemini API و Vertex AI + - معالجة تلقائية لتعليمات النظام + - تتبع استخدام الرموز + + **نماذج Gemini:** + + | النموذج | نافذة السياق | الأفضل لـ | + |--------------------------------|-----------------|-------------------------------------------------------------------| + | gemini-2.5-flash | 1M tokens | التفكير التكيفي، كفاءة التكلفة | + | gemini-2.5-pro | 1M tokens | التفكير والاستدلال المحسّن، الفهم متعدد الوسائط | + | gemini-2.0-flash | 1M tokens | ميزات الجيل التالي، السرعة، التفكير | + | gemini-2.0-flash-thinking | 32,768 tokens | الاستدلال المتقدم مع عملية التفكير | + | gemini-2.0-flash-lite | 1M tokens | كفاءة التكلفة ووقت الاستجابة المنخفض | + | gemini-1.5-pro | 2M tokens | الأفضل أداءً، الاستدلال المنطقي، البرمجة | + | gemini-1.5-flash | 1M tokens | نموذج متعدد الوسائط متوازن، جيد لمعظم المهام | + | gemini-1.5-flash-8b | 1M tokens | الأسرع والأكثر كفاءة من حيث التكلفة | + | gemini-1.0-pro | 32,768 tokens | نموذج الجيل السابق | + + **ملاحظة:** لاستخدام Google Gemini، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[google-genai]" + ``` + + القائمة الكاملة للنماذج متاحة في [وثائق نماذج Gemini](https://ai.google.dev/gemini-api/docs/models). + + + + احصل على بيانات الاعتماد من Google Cloud Console واحفظها في ملف JSON، ثم حمّلها بالكود التالي: + ```python Code + import json + + file_path = 'path/to/vertex_ai_service_account.json' + + # Load the JSON file + with open(file_path, 'r') as file: + vertex_credentials = json.load(file) + + # Convert the credentials to a JSON string + vertex_credentials_json = json.dumps(vertex_credentials) + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini-1.5-pro-latest", # or vertex_ai/gemini-1.5-pro-latest + temperature=0.7, + vertex_credentials=vertex_credentials_json + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع Azure AI Inference و Azure OpenAI من خلال Azure AI Inference Python SDK. + + ```toml Code + # Required + AZURE_API_KEY= + AZURE_ENDPOINT= + + # Optional + AZURE_API_VERSION= # Defaults to 2024-06-01 + ``` + + **الاستخدام الأساسي:** + ```python Code + llm = LLM( + model="azure/gpt-4", + api_key="", # Or set AZURE_API_KEY + endpoint="", + api_version="2024-06-01" + ) + ``` + + **ملاحظة:** لاستخدام Azure AI Inference، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[azure-ai-inference]" + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع AWS Bedrock من خلال boto3 SDK باستخدام Converse API. + + ```toml Code + # Required + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + + # Optional + AWS_SESSION_TOKEN= # For temporary credentials + AWS_DEFAULT_REGION= # Defaults to us-east-1 + AWS_REGION_NAME= # Alternative configuration for backwards compatibility with LiteLLM. Defaults to us-east-1 + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + region_name="us-east-1" + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_access_key_id="your-access-key", # Or set AWS_ACCESS_KEY_ID + aws_secret_access_key="your-secret-key", # Or set AWS_SECRET_ACCESS_KEY + aws_session_token="your-session-token", # For temporary credentials + region_name="us-east-1", + temperature=0.7, + max_tokens=4096, + top_p=0.9, + top_k=250, # For Claude models + stop_sequences=["END", "STOP"], + stream=True, # Enable streaming + guardrail_config={ # Optional content filtering + "guardrailIdentifier": "your-guardrail-id", + "guardrailVersion": "1" + }, + additional_model_request_fields={ # Model-specific parameters + "top_k": 250 + } + ) + ``` + + **متغيرات البيئة المدعومة:** + - `AWS_ACCESS_KEY_ID`: مفتاح وصول AWS (مطلوب) + - `AWS_SECRET_ACCESS_KEY`: مفتاح AWS السري (مطلوب) + - `AWS_SESSION_TOKEN`: رمز جلسة AWS لبيانات الاعتماد المؤقتة (اختياري) + - `AWS_DEFAULT_REGION`: منطقة AWS (الافتراضي `us-east-1`) + - `AWS_REGION_NAME`: منطقة AWS (الافتراضي `us-east-1`). إعداد بديل للتوافق مع LiteLLM + + **الميزات:** + - دعم استدعاء الأدوات الأصلي عبر Converse API + - استجابات بث وبدون بث + - معالجة أخطاء شاملة مع منطق إعادة المحاولة + - إعداد حواجز الحماية لتصفية المحتوى + - معاملات خاصة بالنموذج عبر `additional_model_request_fields` + - تتبع استخدام الرموز وتسجيل سبب التوقف + - دعم جميع نماذج Bedrock الأساسية + - معالجة تلقائية لتنسيق المحادثة + + **ملاحظات مهمة:** + - يستخدم Converse API الحديث للوصول الموحد للنماذج + - معالجة تلقائية لمتطلبات المحادثة الخاصة بالنموذج + - يتم التعامل مع رسائل النظام بشكل منفصل عن المحادثة + - يجب أن تكون الرسالة الأولى من المستخدم (يتم التعامل معها تلقائيًا) + - بعض النماذج (مثل Cohere) تتطلب أن تنتهي المحادثة برسالة المستخدم + + [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) هو خدمة مُدارة توفر الوصول إلى نماذج أساسية متعددة من أبرز شركات الذكاء الاصطناعي عبر واجهة API موحدة. + + | النموذج | نافذة السياق | الأفضل لـ | + |-------------------------|----------------------|-------------------------------------------------------------------| + | Amazon Nova Pro | حتى 300k tokens | أداء عالٍ، نموذج يوازن بين الدقة والسرعة والفعالية من حيث التكلفة عبر مهام متنوعة. | + | Amazon Nova Micro | حتى 128k tokens | نموذج نصي فقط عالي الأداء وفعال من حيث التكلفة ومحسّن لأقل وقت استجابة. | + | Amazon Nova Lite | حتى 300k tokens | معالجة متعددة الوسائط بأسعار معقولة للصور والفيديو والنص مع قدرات في الوقت الفعلي. | + | Claude 3.7 Sonnet | حتى 128k tokens | الأفضل أداءً للاستدلال المعقد والبرمجة ووكلاء الذكاء الاصطناعي | + | Claude 3.5 Sonnet v2 | حتى 200k tokens | نموذج متطور متخصص في هندسة البرمجيات والقدرات الوكيلية والتفاعل مع الحاسوب بتكلفة محسّنة. | + | Claude 3.5 Sonnet | حتى 200k tokens | نموذج عالي الأداء يقدم ذكاءً واستدلالًا فائقين عبر مهام متنوعة مع توازن مثالي بين السرعة والتكلفة. | + | Claude 3.5 Haiku | حتى 200k tokens | نموذج متعدد الوسائط سريع وصغير محسّن للاستجابات السريعة والتفاعلات الشبيهة بالبشر | + | Claude 3 Sonnet | حتى 200k tokens | نموذج متعدد الوسائط يوازن بين الذكاء والسرعة للنشر بكميات كبيرة. | + | Claude 3 Haiku | حتى 200k tokens | نموذج متعدد الوسائط صغير وسريع محسّن للاستجابات السريعة والتفاعلات المحادثية الطبيعية | + | Claude 3 Opus | حتى 200k tokens | أكثر النماذج متعددة الوسائط تقدمًا يتفوق في المهام المعقدة بالاستدلال الشبيه بالبشر والفهم السياقي الفائق. | + | Claude 2.1 | حتى 200k tokens | إصدار محسّن بنافذة سياق موسّعة وموثوقية محسّنة وهلوسات أقل لتطبيقات النصوص الطويلة وRAG | + | Claude | حتى 100k tokens | نموذج متعدد الاستخدامات يتفوق في الحوار المتقدم والمحتوى الإبداعي واتباع التعليمات الدقيقة. | + | Claude Instant | حتى 100k tokens | نموذج سريع وفعال من حيث التكلفة للمهام اليومية مثل الحوار والتحليل والتلخيص والأسئلة والأجوبة | + | Llama 3.1 405B Instruct | حتى 128k tokens | نموذج LLM متقدم لتوليد البيانات الاصطناعية والتقطير والاستدلال لروبوتات المحادثة والبرمجة والمهام المتخصصة. | + | Llama 3.1 70B Instruct | حتى 128k tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | Llama 3.1 8B Instruct | حتى 128k tokens | نموذج متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | Llama 3 70B Instruct | حتى 8k tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | Llama 3 8B Instruct | حتى 8k tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | Titan Text G1 - Lite | حتى 4k tokens | نموذج خفيف وفعال من حيث التكلفة محسّن لمهام اللغة الإنجليزية والضبط الدقيق مع التركيز على التلخيص وتوليد المحتوى. | + | Titan Text G1 - Express | حتى 8k tokens | نموذج متعدد الاستخدامات لمهام اللغة العامة والمحادثة وتطبيقات RAG مع دعم الإنجليزية وأكثر من 100 لغة. | + | Cohere Command | حتى 4k tokens | نموذج متخصص في اتباع أوامر المستخدم وتقديم حلول عملية للمؤسسات. | + | Jurassic-2 Mid | حتى 8,191 tokens | نموذج فعال من حيث التكلفة يوازن بين الجودة والسعر لمهام اللغة المتنوعة مثل الأسئلة والأجوبة والتلخيص وتوليد المحتوى. | + | Jurassic-2 Ultra | حتى 8,191 tokens | نموذج لتوليد النص المتقدم والفهم، يتفوق في المهام المعقدة مثل التحليل وإنشاء المحتوى. | + | Jamba-Instruct | حتى 256k tokens | نموذج بنافذة سياق موسّعة محسّن لتوليد النص الفعال من حيث التكلفة والتلخيص والأسئلة والأجوبة. | + | Mistral 7B Instruct | حتى 32k tokens | نموذج LLM يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | Mistral 8x7B Instruct | حتى 32k tokens | نموذج LLM بمعمارية MOE يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | DeepSeek R1 | 32,768 tokens | نموذج استدلال متقدم | + + **ملاحظة:** لاستخدام AWS Bedrock، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[bedrock]" + ``` + + + + ```toml Code + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_DEFAULT_REGION= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="sagemaker/" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + MISTRAL_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="mistral/mistral-large-latest", + temperature=0.7 + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + NVIDIA_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="nvidia_nim/meta/llama3-70b-instruct", + temperature=0.7 + ) + ``` + + يوفر Nvidia NIM مجموعة شاملة من النماذج لحالات الاستخدام المتنوعة، من المهام ذات الأغراض العامة إلى التطبيقات المتخصصة. + + | النموذج | نافذة السياق | الأفضل لـ | + |-------------------------------------------------------------------------|----------------|-------------------------------------------------------------------| + | nvidia/mistral-nemo-minitron-8b-8k-instruct | 8,192 tokens | نموذج لغة صغير متطور يقدم دقة فائقة لروبوتات المحادثة والمساعدين الافتراضيين وتوليد المحتوى. | + | nvidia/nemotron-4-mini-hindi-4b-instruct | 4,096 tokens | نموذج لغة صغير ثنائي اللغة هندي-إنجليزي للاستدلال على الجهاز، مصمم خصيصًا للغة الهندية. | + | nvidia/llama-3.1-nemotron-70b-instruct | 128k tokens | مخصص لتعزيز فائدة الاستجابات | + | nvidia/llama3-chatqa-1.5-8b | 128k tokens | نموذج LLM متقدم لتوليد استجابات عالية الجودة ومدركة للسياق لروبوتات المحادثة ومحركات البحث. | + | nvidia/llama3-chatqa-1.5-70b | 128k tokens | نموذج LLM متقدم لتوليد استجابات عالية الجودة ومدركة للسياق لروبوتات المحادثة ومحركات البحث. | + | nvidia/vila | 128k tokens | نموذج رؤية-لغة متعدد الوسائط يفهم النص والصور والفيديو وينشئ استجابات غنية بالمعلومات | + | nvidia/neva-22 | 4,096 tokens | نموذج رؤية-لغة متعدد الوسائط يفهم النص والصور ويولد استجابات غنية بالمعلومات | + | nvidia/nemotron-mini-4b-instruct | 8,192 tokens | مهام ذات أغراض عامة | + | nvidia/usdcode-llama3-70b-instruct | 128k tokens | نموذج LLM متطور يجيب على استعلامات معرفة OpenUSD ويولد كود USD-Python. | + | nvidia/nemotron-4-340b-instruct | 4,096 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | meta/codellama-70b | 100k tokens | نموذج LLM قادر على توليد الكود من اللغة الطبيعية والعكس. | + | meta/llama2-70b | 4,096 tokens | نموذج لغة كبير متطور قادر على توليد النص والكود استجابة للمطالبات. | + | meta/llama3-8b-instruct | 8,192 tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama3-70b-instruct | 8,192 tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | meta/llama-3.1-8b-instruct | 128k tokens | نموذج متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.1-70b-instruct | 128k tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | meta/llama-3.1-405b-instruct | 128k tokens | نموذج LLM متقدم لتوليد البيانات الاصطناعية والتقطير والاستدلال لروبوتات المحادثة والبرمجة والمهام المتخصصة. | + | meta/llama-3.2-1b-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.2-3b-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.2-11b-vision-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.2-90b-vision-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | google/gemma-7b | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/gemma-2b | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/codegemma-7b | 8,192 tokens | نموذج متطور مبني على Gemma-7B من Google متخصص في توليد الكود وإكماله. | + | google/codegemma-1.1-7b | 8,192 tokens | نموذج برمجة متقدم لتوليد الكود وإكماله والاستدلال واتباع التعليمات. | + | google/recurrentgemma-2b | 8,192 tokens | نموذج لغة بمعمارية تكرارية جديدة لاستدلال أسرع عند توليد تسلسلات طويلة. | + | google/gemma-2-9b-it | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/gemma-2-27b-it | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/gemma-2-2b-it | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/deplot | 512 tokens | نموذج فهم لغة بصرية بلقطة واحدة يترجم صور الرسوم البيانية إلى جداول. | + | google/paligemma | 8,192 tokens | نموذج لغة بصري بارع في استيعاب مدخلات النص والصور لإنتاج استجابات غنية بالمعلومات. | + | mistralai/mistral-7b-instruct-v0.2 | 32k tokens | نموذج LLM يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | mistralai/mixtral-8x7b-instruct-v0.1 | 8,192 tokens | نموذج LLM بمعمارية MOE يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | mistralai/mistral-large | 4,096 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | mistralai/mixtral-8x22b-instruct-v0.1 | 8,192 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | mistralai/mistral-7b-instruct-v0.3 | 32k tokens | نموذج LLM يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | nv-mistralai/mistral-nemo-12b-instruct | 128k tokens | أكثر نموذج لغة تقدمًا للاستدلال والبرمجة والمهام متعددة اللغات؛ يعمل على وحدة GPU واحدة. | + | mistralai/mamba-codestral-7b-v0.1 | 256k tokens | نموذج للكتابة والتفاعل مع الكود عبر مجموعة واسعة من لغات البرمجة والمهام. | + | microsoft/phi-3-mini-128k-instruct | 128K tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-mini-4k-instruct | 4,096 tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-small-8k-instruct | 8,192 tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-small-128k-instruct | 128K tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-medium-4k-instruct | 4,096 tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-medium-128k-instruct | 128K tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3.5-mini-instruct | 128K tokens | نموذج LLM خفيف متعدد اللغات يدعم تطبيقات الذكاء الاصطناعي في البيئات المحدودة بالكمون والذاكرة والحوسبة | + | microsoft/phi-3.5-moe-instruct | 128K tokens | نموذج LLM متقدم يعتمد على معمارية خليط الخبراء لتوليد محتوى فعال حوسبيًا | + | microsoft/kosmos-2 | 1,024 tokens | نموذج متعدد الوسائط رائد مصمم لفهم العناصر المرئية في الصور والاستدلال عليها. | + | microsoft/phi-3-vision-128k-instruct | 128k tokens | نموذج متعدد الوسائط مفتوح متطور يتفوق في الاستدلال عالي الجودة من الصور. | + | microsoft/phi-3.5-vision-instruct | 128k tokens | نموذج متعدد الوسائط مفتوح متطور يتفوق في الاستدلال عالي الجودة من الصور. | + | databricks/dbrx-instruct | 12k tokens | نموذج LLM للأغراض العامة بأداء متطور في فهم اللغة والبرمجة وRAG. | + | snowflake/arctic | 1,024 tokens | يقدم استدلالًا عالي الكفاءة لتطبيقات المؤسسات مع التركيز على توليد SQL والبرمجة. | + | aisingapore/sea-lion-7b-instruct | 4,096 tokens | نموذج LLM لتمثيل وخدمة التنوع اللغوي والثقافي لجنوب شرق آسيا | + | ibm/granite-8b-code-instruct | 4,096 tokens | نموذج LLM لبرمجة البرمجيات لتوليد الكود وإكماله وشرحه والتحويل متعدد الأدوار. | + | ibm/granite-34b-code-instruct | 8,192 tokens | نموذج LLM لبرمجة البرمجيات لتوليد الكود وإكماله وشرحه والتحويل متعدد الأدوار. | + | ibm/granite-3.0-8b-instruct | 4,096 tokens | نموذج لغة صغير متقدم يدعم RAG والتلخيص والتصنيف والكود والذكاء الاصطناعي الوكيلي | + | ibm/granite-3.0-3b-a800m-instruct | 4,096 tokens | نموذج خليط خبراء عالي الكفاءة لـ RAG والتلخيص واستخراج الكيانات والتصنيف | + | mediatek/breeze-7b-instruct | 4,096 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | upstage/solar-10.7b-instruct | 4,096 tokens | يتفوق في مهام NLP، خاصة في اتباع التعليمات والاستدلال والرياضيات. | + | writer/palmyra-med-70b-32k | 32k tokens | نموذج LLM رائد للاستجابات الدقيقة والمناسبة للسياق في المجال الطبي. | + | writer/palmyra-med-70b | 32k tokens | نموذج LLM رائد للاستجابات الدقيقة والمناسبة للسياق في المجال الطبي. | + | writer/palmyra-fin-70b-32k | 32k tokens | نموذج LLM متخصص في التحليل المالي وإعداد التقارير ومعالجة البيانات | + | 01-ai/yi-large | 32k tokens | نموذج قوي مدرب على الإنجليزية والصينية لمهام متنوعة بما في ذلك روبوتات المحادثة والكتابة الإبداعية. | + | deepseek-ai/deepseek-coder-6.7b-instruct | 2k tokens | نموذج برمجة قوي يقدم قدرات متقدمة في توليد الكود وإكماله وملء الفراغات | + | rakuten/rakutenai-7b-instruct | 1,024 tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | rakuten/rakutenai-7b-chat | 1,024 tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | baichuan-inc/baichuan2-13b-chat | 4,096 tokens | يدعم المحادثة بالصينية والإنجليزية والبرمجة والرياضيات واتباع التعليمات وحل الألغاز | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + + يتيح لك NVIDIA NIM تشغيل نماذج LLM قوية محليًا على جهاز Windows باستخدام WSL2 (نظام Windows الفرعي لـ Linux). + يتيح لك هذا النهج الاستفادة من وحدة GPU من NVIDIA لاستدلال ذكاء اصطناعي خاص وآمن وفعال من حيث التكلفة دون الاعتماد على الخدمات السحابية. + مثالي لسيناريوهات التطوير والاختبار أو الإنتاج حيث تكون خصوصية البيانات أو القدرات غير المتصلة مطلوبة. + + إليك دليلًا خطوة بخطوة لإعداد نموذج NVIDIA NIM محلي: + + 1. اتبع تعليمات التثبيت من [موقع NVIDIA](https://docs.nvidia.com/nim/wsl2/latest/getting-started.html) + + 2. ثبّت النموذج المحلي. لـ Llama 3.1-8b اتبع [التعليمات](https://build.nvidia.com/meta/llama-3_1-8b-instruct/deploy) + + 3. أعدّ نماذج crewai المحلية: + + ```python Code + from crewai.llm import LLM + + local_nvidia_nim_llm = LLM( + model="openai/meta/llama-3.1-8b-instruct", # it's an openai-api compatible model + base_url="http://localhost:8000/v1", + api_key="", # api_key is required, but you can use any text + ) + + # Then you can use it in your crew: + + @CrewBase + class MyCrew(): + # ... + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + llm=local_nvidia_nim_llm + ) + + # ... + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + + ```toml Code + GROQ_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="groq/llama-3.2-90b-text-preview", + temperature=0.7 + ) + ``` + | النموذج | نافذة السياق | الأفضل لـ | + |-------------------|------------------|--------------------------------------------| + | Llama 3.1 70B/8B | 131,072 tokens | مهام عالية الأداء بسياق كبير | + | Llama 3.2 Series | 8,192 tokens | مهام ذات أغراض عامة | + | Mixtral 8x7B | 32,768 tokens | أداء متوازن وسياق جيد | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + # Required + WATSONX_URL= + WATSONX_APIKEY= + WATSONX_PROJECT_ID= + + # Optional + WATSONX_TOKEN= + WATSONX_DEPLOYMENT_SPACE_ID= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="watsonx/meta-llama/llama-3-1-70b-instruct", + base_url="https://api.watsonx.ai/v1" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 1. ثبّت Ollama: [ollama.ai](https://ollama.ai/) + 2. شغّل نموذجًا: `ollama run llama3` + 3. أعدّ: + + ```python Code + llm = LLM( + model="ollama/llama3:70b", + base_url="http://localhost:11434" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + FIREWORKS_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct", + temperature=0.7 + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + PERPLEXITY_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="llama-3.1-sonar-large-128k-online", + base_url="https://api.perplexity.ai/" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + HF_TOKEN= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + + ```toml Code + SAMBANOVA_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="sambanova/Meta-Llama-3.1-8B-Instruct", + temperature=0.7 + ) + ``` + | النموذج | نافذة السياق | الأفضل لـ | + |--------------------|------------------------|----------------------------------------------| + | Llama 3.1 70B/8B | حتى 131,072 tokens | مهام عالية الأداء بسياق كبير | + | Llama 3.1 405B | 8,192 tokens | أداء عالٍ وجودة مخرجات | + | Llama 3.2 Series | 8,192 tokens | مهام عامة ومتعددة الوسائط | + | Llama 3.3 70B | حتى 131,072 tokens | أداء عالٍ وجودة مخرجات | + | Qwen2 familly | 8,192 tokens | أداء عالٍ وجودة مخرجات | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + # Required + CEREBRAS_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="cerebras/llama3.1-70b", + temperature=0.7, + max_tokens=8192 + ) + ``` + + + ميزات Cerebras: + - سرعات استدلال عالية + - أسعار تنافسية + - توازن جيد بين السرعة والجودة + - دعم نوافذ سياق طويلة + + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + OPENROUTER_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="openrouter/deepseek/deepseek-r1", + base_url="https://openrouter.ai/api/v1", + api_key=OPENROUTER_API_KEY + ) + ``` + + + نماذج Open Router: + - openrouter/deepseek/deepseek-r1 + - openrouter/deepseek/deepseek-chat + + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + NEBIUS_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="nebius/Qwen/Qwen3-30B-A3B" + ) + ``` + + + ميزات Nebius AI Studio: + - مجموعة كبيرة من النماذج مفتوحة المصدر + - حدود معدل أعلى + - أسعار تنافسية + - توازن جيد بين السرعة والجودة + + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + +## بث الاستجابات + +يدعم CrewAI بث الاستجابات من LLMs، مما يتيح لتطبيقك تلقي ومعالجة المخرجات في الوقت الفعلي فور توليدها. + + + + فعّل البث بتعيين معامل `stream` إلى `True` عند تهيئة LLM: + + ```python + from crewai import LLM + + # Create an LLM with streaming enabled + llm = LLM( + model="openai/gpt-4o", + stream=True # Enable streaming + ) + ``` + + عند تفعيل البث، يتم تسليم الاستجابات في أجزاء فور توليدها، مما يخلق تجربة مستخدم أكثر استجابة. + + + + يُصدر CrewAI أحداثًا لكل جزء يتم تلقيه أثناء البث: + + ```python + from crewai.events import ( + LLMStreamChunkEvent + ) + from crewai.events 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): + # Process each chunk as it arrives + print(f"Received chunk: {event.chunk}") + + my_listener = MyCustomListener() + ``` + + + [انقر هنا](/ar/concepts/event-listener#event-listeners) لمزيد من التفاصيل + + + + + جميع أحداث LLM في CrewAI تتضمن معلومات Agent والمهمة، مما يتيح لك تتبع وتصفية تفاعلات LLM بواسطة وكلاء أو مهام محددة: + + ```python + from crewai import LLM, Agent, Task, Crew + from crewai.events import LLMStreamChunkEvent + from crewai.events import BaseEventListener + + class MyCustomListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(LLMStreamChunkEvent) + def on_llm_stream_chunk(source, event): + if researcher.id == event.agent_id: + print("\n==============\n Got event:", event, "\n==============\n") + + + my_listener = MyCustomListener() + + llm = LLM(model="gpt-4o-mini", temperature=0, stream=True) + + researcher = Agent( + role="About User", + goal="You know everything about the user.", + backstory="""You are a master at understanding people and their preferences.""", + llm=llm, + ) + + search = Task( + description="Answer the following questions about the user: {question}", + expected_output="An answer to the question.", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[search]) + + result = crew.kickoff( + inputs={"question": "..."} + ) + ``` + + + هذه الميزة مفيدة بشكل خاص لـ: + - تصحيح سلوكيات وكلاء محددة + - تسجيل استخدام LLM حسب نوع المهمة + - مراجعة أي الوكلاء يجرون أنواع استدعاءات LLM + - مراقبة أداء مهام محددة + + + + +## استدعاءات LLM غير المتزامنة + +يدعم CrewAI استدعاءات LLM غير المتزامنة لأداء وتزامن محسّنين في سير عمل الذكاء الاصطناعي. تتيح لك الاستدعاءات غير المتزامنة تشغيل طلبات LLM متعددة بشكل متزامن دون حجب، مما يجعلها مثالية لتطبيقات الإنتاجية العالية وعمليات الوكلاء المتوازية. + + + + استخدم دالة `acall` لطلبات LLM غير المتزامنة: + + ```python + import asyncio + from crewai import LLM + + async def main(): + llm = LLM(model="openai/gpt-4o") + + # Single async call + response = await llm.acall("What is the capital of France?") + print(response) + + asyncio.run(main()) + ``` + + تدعم دالة `acall` جميع المعاملات نفسها كدالة `call` المتزامنة، بما في ذلك الرسائل والأدوات ودوال الاسترجاع. + + + + اجمع بين الاستدعاءات غير المتزامنة والبث للاستجابات المتزامنة في الوقت الفعلي: + + ```python + import asyncio + from crewai import LLM + + async def stream_async(): + llm = LLM(model="openai/gpt-4o", stream=True) + + response = await llm.acall("Write a short story about AI") + + print(response) + + asyncio.run(stream_async()) + ``` + + + +## استدعاءات LLM المهيكلة + +يدعم CrewAI الاستجابات المهيكلة من استدعاءات LLM من خلال السماح لك بتحديد `response_format` باستخدام نموذج Pydantic. يمكّن هذا الإطار من تحليل المخرجات والتحقق منها تلقائيًا، مما يسهّل دمج الاستجابة في تطبيقك دون معالجة لاحقة يدوية. + +```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') +``` + +## الميزات المتقدمة والتحسين + +تعلّم كيفية الاستفادة القصوى من إعداد LLM: + + + + يتضمن CrewAI ميزات إدارة سياق ذكية: + + ```python + from crewai import LLM + + # CrewAI automatically handles: + # 1. Token counting and tracking + # 2. Content summarization when needed + # 3. Task splitting for large contexts + + llm = LLM( + model="gpt-4", + max_tokens=4000, # Limit response length + ) + ``` + + + أفضل الممارسات لإدارة السياق: + 1. اختر نماذج بنوافذ سياق مناسبة + 2. عالج المدخلات الطويلة مسبقًا عند الإمكان + 3. استخدم التقسيم للمستندات الكبيرة + 4. راقب استخدام الرموز لتحسين التكاليف + + + + + + + اختر نافذة السياق المناسبة لمهمتك: + - المهام الصغيرة (حتى 4K رمز): النماذج القياسية + - المهام المتوسطة (بين 4K-32K): النماذج المحسّنة + - المهام الكبيرة (أكثر من 32K): نماذج السياق الكبير + + ```python + # Configure model with appropriate settings + llm = LLM( + model="openai/gpt-4-turbo-preview", + temperature=0.7, # Adjust based on task + max_tokens=4096, # Set based on output needs + timeout=300 # Longer timeout for complex tasks + ) + ``` + + - درجة حرارة منخفضة (0.1 إلى 0.3) للاستجابات الواقعية + - درجة حرارة عالية (0.7 إلى 0.9) للمهام الإبداعية + + + + + 1. راقب استخدام الرموز + 2. نفّذ تحديد المعدل + 3. استخدم التخزين المؤقت عند الإمكان + 4. عيّن حدود max_tokens مناسبة + + + + + تذكّر مراقبة استخدام الرموز بانتظام وضبط إعداداتك حسب الحاجة لتحسين التكاليف والأداء. + + + + + يستخدم CrewAI داخليًا حزم SDK أصلية لاستدعاءات LLM، مما يتيح لك إسقاط معاملات إضافية غير مطلوبة لحالة الاستخدام الخاصة بك. يمكن أن يساعد هذا في تبسيط كودك وتقليل تعقيد إعداد 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"] + ) + ``` + + + + يوفر CrewAI معترضات رسائل لعدة مزودين، مما يتيح لك الربط بدورات الطلب/الاستجابة على مستوى طبقة النقل. + + **المزودون المدعومون:** + - OpenAI + - Anthropic + + **الاستخدام الأساسي:** + ```python +import httpx +from crewai import LLM +from crewai.llms.hooks import BaseInterceptor + +class CustomInterceptor(BaseInterceptor[httpx.Request, httpx.Response]): + """Custom interceptor to modify requests and responses.""" + + def on_outbound(self, request: httpx.Request) -> httpx.Request: + """Print request before sending to the LLM provider.""" + print(request) + return request + + def on_inbound(self, response: httpx.Response) -> httpx.Response: + """Process response after receiving from the LLM provider.""" + print(f"Status: {response.status_code}") + print(f"Response time: {response.elapsed}") + return response + +# Use the interceptor with an LLM +llm = LLM( + model="openai/gpt-4o", + interceptor=CustomInterceptor() +) + ``` + + **ملاحظات مهمة:** + - يجب على كلتا الدالتين إعادة الكائن المستلم أو نوعه. + - تعديل الكائنات المستلمة قد يؤدي إلى سلوك غير متوقع أو أعطال في التطبيق. + - ليس كل المزودين يدعمون المعترضات -- تحقق من قائمة المزودين المدعومين أعلاه + + + تعمل المعترضات على مستوى طبقة النقل. مفيدة بشكل خاص لـ: + - تحويل الرسائل وتصفيتها + - تصحيح تفاعلات API + + + + +## المشاكل الشائعة والحلول + + + + + يمكن حل معظم مشاكل المصادقة بالتحقق من تنسيق مفتاح API وأسماء متغيرات البيئة. + + + ```bash + # OpenAI + OPENAI_API_KEY=sk-... + + # Anthropic + ANTHROPIC_API_KEY=sk-ant-... + ``` + + + + ضمّن دائمًا بادئة المزود في أسماء النماذج + + + ```python + # Correct + llm = LLM(model="openai/gpt-4") + + # Incorrect + llm = LLM(model="gpt-4") + ``` + + + + استخدم نماذج سياق أكبر للمهام الواسعة + + + ```python + # Large context model + llm = LLM(model="openai/gpt-4o") # 128K tokens + ``` + + diff --git a/docs/v1.15.1/ar/concepts/memory.mdx b/docs/v1.15.1/ar/concepts/memory.mdx new file mode 100644 index 000000000..541f2967a --- /dev/null +++ b/docs/v1.15.1/ar/concepts/memory.mdx @@ -0,0 +1,878 @@ +--- +title: الذاكرة +description: الاستفادة من نظام الذاكرة الموحد في CrewAI لتعزيز قدرات الوكلاء. +icon: database +mode: "wide" +--- + +## نظرة عامة + +يوفر CrewAI **نظام ذاكرة موحد** -- فئة `Memory` واحدة تستبدل أنواع الذاكرة المنفصلة (قصيرة المدى، طويلة المدى، ذاكرة الكيانات، والخارجية) بواجهة برمجة تطبيقات ذكية واحدة. تستخدم الذاكرة LLM لتحليل المحتوى عند الحفظ (استنتاج النطاق والفئات والأهمية) وتدعم الاسترجاع متعدد العمق مع تسجيل مركب يمزج بين التشابه الدلالي والحداثة والأهمية. + +يمكنك استخدام الذاكرة بأربع طرق: **مستقلة** (سكربتات، دفاتر ملاحظات)، **مع فرق Crew**، **مع Agents**، أو **داخل التدفقات**. + +## البدء السريع + +```python +from crewai import Memory + +memory = Memory() + +# Store -- the LLM infers scope, categories, and importance +memory.remember("We decided to use PostgreSQL for the user database.") + +# Retrieve -- results ranked by composite score (semantic + recency + importance) +matches = memory.recall("What database did we choose?") +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Tune scoring for a fast-moving project +memory = Memory(recency_weight=0.5, recency_half_life_days=7) + +# Forget +memory.forget(scope="/project/old") + +# Explore the self-organized scope tree +print(memory.tree()) +print(memory.info("/")) +``` + +## أربع طرق لاستخدام الذاكرة + +### مستقلة + +استخدم الذاكرة في السكربتات ودفاتر الملاحظات وأدوات سطر الأوامر أو كقاعدة معرفة مستقلة -- لا حاجة لوكلاء أو فرق Crew. + +```python +from crewai import Memory + +memory = Memory() + +# Build up knowledge +memory.remember("The API rate limit is 1000 requests per minute.") +memory.remember("Our staging environment uses port 8080.") +memory.remember("The team agreed to use feature flags for all new releases.") + +# Later, recall what you need +matches = memory.recall("What are our API limits?", limit=5) +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Extract atomic facts from a longer text +raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL +next quarter. The budget is $50k. Sarah will lead the migration.""" + +facts = memory.extract_memories(raw) +# ["Migration from MySQL to PostgreSQL planned for next quarter", +# "Database migration budget is $50k", +# "Sarah will lead the database migration"] + +for fact in facts: + memory.remember(fact) +``` + +### مع فرق Crew + +مرّر `memory=True` للإعدادات الافتراضية، أو مرّر مثيل `Memory` مُعدّ للسلوك المخصص. + +```python +from crewai import Crew, Agent, Task, Process, Memory + +# Option 1: Default memory +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + memory=True, + verbose=True, +) + +# Option 2: Custom memory with tuned scoring +memory = Memory( + recency_weight=0.4, + semantic_weight=0.4, + importance_weight=0.2, + recency_half_life_days=14, +) +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + memory=memory, +) +``` + +عند استخدام `memory=True`، ينشئ الفريق مثيل `Memory()` افتراضيًا ويمرر إعداد `embedder` الخاص بالفريق تلقائيًا. يشترك جميع الوكلاء في الفريق في ذاكرة الفريق ما لم يكن لدى الوكيل ذاكرته الخاصة. + +بعد كل مهمة، يستخرج الفريق تلقائيًا حقائق منفصلة من مخرجات المهمة ويخزّنها. قبل كل مهمة، يسترجع الوكيل السياق ذا الصلة من الذاكرة ويحقنه في موجّه المهمة. + +### مع Agents + +يمكن للوكلاء استخدام ذاكرة الفريق المشتركة (افتراضيًا) أو تلقي عرض محدد النطاق للسياق الخاص. + +```python +from crewai import Agent, Memory + +memory = Memory() + +# Researcher gets a private scope -- only sees /agent/researcher +researcher = Agent( + role="Researcher", + goal="Find and analyze information", + backstory="Expert researcher with attention to detail", + memory=memory.scope("/agent/researcher"), +) + +# Writer uses crew shared memory (no agent-level memory set) +writer = Agent( + role="Writer", + goal="Produce clear, well-structured content", + backstory="Experienced technical writer", + # memory not set -- uses crew._memory when crew has memory enabled +) +``` + +يمنح هذا النمط الباحث نتائج خاصة بينما يقرأ الكاتب من ذاكرة الفريق المشتركة. + +### مع التدفقات + +كل تدفق يحتوي على ذاكرة مدمجة. استخدم `self.remember()` و `self.recall()` و `self.extract_memories()` داخل أي دالة تدفق. + +```python +from crewai.flow.flow import Flow, listen, start + +class ResearchFlow(Flow): + @start() + def gather_data(self): + findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k." + self.remember(findings, scope="/research/databases") + return findings + + @listen(gather_data) + def write_report(self, findings): + # Recall past research to provide context + past = self.recall("database performance benchmarks") + context = "\n".join(f"- {m.record.content}" for m in past) + return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}" +``` + +انظر [وثائق التدفقات](/concepts/flows) لمزيد من المعلومات حول الذاكرة في التدفقات. + + +## النطاقات الهرمية + +### ما هي النطاقات + +يتم تنظيم الذكريات في شجرة هرمية من النطاقات، مشابهة لنظام الملفات. كل نطاق هو مسار مثل `/` أو `/project/alpha` أو `/agent/researcher/findings`. + +``` +/ + /company + /company/engineering + /company/product + /project + /project/alpha + /project/beta + /agent + /agent/researcher + /agent/writer +``` + +توفر النطاقات **ذاكرة تعتمد على السياق** -- عند الاسترجاع ضمن نطاق، تبحث فقط في ذلك الفرع من الشجرة، مما يحسّن كلًا من الدقة والأداء. + +### كيف يعمل استنتاج النطاق + +عند استدعاء `remember()` دون تحديد نطاق، يحلل LLM المحتوى وشجرة النطاقات الحالية، ثم يقترح أفضل موضع. إذا لم يكن هناك نطاق حالي مناسب، ينشئ واحدًا جديدًا. بمرور الوقت، تنمو شجرة النطاقات عضويًا من المحتوى نفسه -- لا تحتاج إلى تصميم مخطط مسبقًا. + +```python +memory = Memory() + +# LLM infers scope from content +memory.remember("We chose PostgreSQL for the user database.") +# -> might be placed under /project/decisions or /engineering/database + +# You can also specify scope explicitly +memory.remember("Sprint velocity is 42 points", scope="/team/metrics") +``` + +### تصوير شجرة النطاقات + +```python +print(memory.tree()) +# / (15 records) +# /project (8 records) +# /project/alpha (5 records) +# /project/beta (3 records) +# /agent (7 records) +# /agent/researcher (4 records) +# /agent/writer (3 records) + +print(memory.info("/project/alpha")) +# ScopeInfo(path='/project/alpha', record_count=5, +# categories=['architecture', 'database'], +# oldest_record=datetime(...), newest_record=datetime(...), +# child_scopes=[]) +``` + +### MemoryScope: عروض الأشجار الفرعية + +يقيّد `MemoryScope` جميع العمليات على فرع من الشجرة. يمكن للوكيل أو الكود الذي يستخدمه الرؤية والكتابة فقط ضمن تلك الشجرة الفرعية. + +```python +memory = Memory() + +# Create a scope for a specific agent +agent_memory = memory.scope("/agent/researcher") + +# Everything is relative to /agent/researcher +agent_memory.remember("Found three relevant papers on LLM memory.") +# -> stored under /agent/researcher + +agent_memory.recall("relevant papers") +# -> searches only under /agent/researcher + +# Narrow further with subscope +project_memory = agent_memory.subscope("project-alpha") +# -> /agent/researcher/project-alpha +``` + +### أفضل الممارسات لتصميم النطاقات + +- **ابدأ بشكل مسطح، ودع LLM ينظّم.** لا تبالغ في هندسة تسلسل النطاقات مسبقًا. ابدأ بـ `memory.remember(content)` ودع استنتاج النطاق في LLM ينشئ الهيكل مع تراكم المحتوى. + +- **استخدم أنماط `/{entity_type}/{identifier}`.** تنشأ التسلسلات الطبيعية من أنماط مثل `/project/alpha` و `/agent/researcher` و `/company/engineering` و `/customer/acme-corp`. + +- **حدد النطاق حسب الاهتمام، وليس حسب نوع البيانات.** استخدم `/project/alpha/decisions` بدلاً من `/decisions/project/alpha`. هذا يبقي المحتوى ذا الصلة معًا. + +- **حافظ على العمق ضحلًا (2-3 مستويات).** النطاقات المتداخلة بعمق تصبح متفرقة جدًا. `/project/alpha/architecture` جيد؛ `/project/alpha/architecture/decisions/databases/postgresql` عميق جدًا. + +- **استخدم النطاقات الصريحة عندما تعرف، ودع LLM يستنتج عندما لا تعرف.** إذا كنت تخزّن قرار مشروع معروف، مرّر `scope="/project/alpha/decisions"`. إذا كنت تخزّن مخرجات وكيل حرة الشكل، اترك النطاق ودع LLM يحدده. + +### أمثلة حالات الاستخدام + +**فريق متعدد المشاريع:** +```python +memory = Memory() +# Each project gets its own branch +memory.remember("Using microservices architecture", scope="/project/alpha/architecture") +memory.remember("GraphQL API for client apps", scope="/project/beta/api") + +# Recall across all projects +memory.recall("API design decisions") + +# Or within a specific project +memory.recall("API design", scope="/project/beta") +``` + +**سياق خاص لكل وكيل مع معرفة مشتركة:** +```python +memory = Memory() + +# Researcher has private findings +researcher_memory = memory.scope("/agent/researcher") + +# Writer can read from both its own scope and shared company knowledge +writer_view = memory.slice( + scopes=["/agent/writer", "/company/knowledge"], + read_only=True, +) +``` + +**دعم العملاء (سياق لكل عميل):** +```python +memory = Memory() + +# Each customer gets isolated context +memory.remember("Prefers email communication", scope="/customer/acme-corp") +memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp") + +# Shared product docs are accessible to all agents +memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs") +``` + + +## شرائح الذاكرة + +### ما هي الشرائح + +`MemorySlice` هو عرض عبر نطاقات متعددة، ربما متباعدة. على عكس النطاق (الذي يقيّد على شجرة فرعية واحدة)، تتيح لك الشريحة الاسترجاع من عدة فروع في وقت واحد. + +### متى تستخدم الشرائح مقابل النطاقات + +- **النطاق**: استخدمه عندما يجب تقييد وكيل أو كتلة كود على شجرة فرعية واحدة. مثال: وكيل يرى فقط `/agent/researcher`. +- **الشريحة**: استخدمها عندما تحتاج إلى دمج السياق من عدة فروع. مثال: وكيل يقرأ من نطاقه الخاص بالإضافة إلى معرفة الشركة المشتركة. + +### شرائح القراءة فقط + +النمط الأكثر شيوعًا: منح وكيل إمكانية القراءة من فروع متعددة دون السماح له بالكتابة في المناطق المشتركة. + +```python +memory = Memory() + +# Agent can recall from its own scope AND company knowledge, +# but cannot write to company knowledge +agent_view = memory.slice( + scopes=["/agent/researcher", "/company/knowledge"], + read_only=True, +) + +matches = agent_view.recall("company security policies", limit=5) +# Searches both /agent/researcher and /company/knowledge, merges and ranks results + +agent_view.remember("new finding") # Raises PermissionError (read-only) +``` + +### شرائح القراءة والكتابة + +عند تعطيل القراءة فقط، يمكنك الكتابة في أي من النطاقات المضمّنة، لكن يجب تحديد النطاق صراحة. + +```python +view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False) + +# Must specify scope when writing +view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"]) +``` + + +## التسجيل المركب + +يتم ترتيب نتائج الاسترجاع بواسطة مزيج مرجّح من ثلاث إشارات: + +``` +composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance +``` + +حيث: +- **similarity** = `1 / (1 + distance)` من فهرس المتجهات (0 إلى 1) +- **decay** = `0.5^(age_days / half_life_days)` -- اضمحلال أُسي (1.0 لليوم، 0.5 عند نصف العمر) +- **importance** = درجة أهمية السجل (0 إلى 1)، يتم تعيينها وقت الترميز + +قم بإعدادها مباشرة على منشئ `Memory`: + +```python +# Sprint retrospective: favor recent memories, short half-life +memory = Memory( + recency_weight=0.5, + semantic_weight=0.3, + importance_weight=0.2, + recency_half_life_days=7, +) + +# Architecture knowledge base: favor important memories, long half-life +memory = Memory( + recency_weight=0.1, + semantic_weight=0.5, + importance_weight=0.4, + recency_half_life_days=180, +) +``` + +يتضمن كل `MemoryMatch` قائمة `match_reasons` حتى تتمكن من رؤية سبب ترتيب نتيجة معينة في موضعها (مثل `["semantic", "recency", "importance"]`). + + +## طبقة تحليل LLM + +تستخدم الذاكرة LLM بثلاث طرق: + +1. **عند الحفظ** -- عندما تحذف النطاق أو الفئات أو الأهمية، يحلل LLM المحتوى ويقترح النطاق والفئات والأهمية والبيانات الوصفية (الكيانات والتواريخ والموضوعات). +2. **عند الاسترجاع** -- للاسترجاع العميق/التلقائي، يحلل LLM الاستعلام (الكلمات المفتاحية، تلميحات الوقت، النطاقات المقترحة، التعقيد) لتوجيه الاسترجاع. +3. **استخراج الذكريات** -- `extract_memories(content)` يقسم النص الخام (مثل مخرجات المهمة) إلى عبارات ذاكرة منفصلة. يستخدم الوكلاء هذا قبل استدعاء `remember()` على كل عبارة حتى يتم تخزين حقائق ذرية بدلاً من كتلة كبيرة واحدة. + +جميع التحليلات تتدهور بسلاسة عند فشل LLM -- انظر [سلوك الفشل](#سلوك-الفشل). + + +## توحيد الذاكرة + +عند حفظ محتوى جديد، يتحقق خط أنابيب الترميز تلقائيًا من وجود سجلات مماثلة في التخزين. إذا كان التشابه أعلى من `consolidation_threshold` (الافتراضي 0.85)، يقرر LLM ما يجب فعله: + +- **keep** -- السجل الحالي لا يزال دقيقًا وغير مكرر. +- **update** -- يجب تحديث السجل الحالي بمعلومات جديدة (يوفر LLM المحتوى المدمج). +- **delete** -- السجل الحالي قديم أو تم استبداله أو تناقضه. +- **insert_new** -- ما إذا كان يجب إدراج المحتوى الجديد أيضًا كسجل منفصل. + +هذا يمنع تراكم النسخ المكررة. على سبيل المثال، إذا حفظت "CrewAI ensures reliable operation" ثلاث مرات، يتعرف التوحيد على النسخ المكررة ويحتفظ بسجل واحد فقط. + +### إزالة التكرار داخل الدفعة + +عند استخدام `remember_many()`، تتم مقارنة العناصر داخل نفس الدفعة مع بعضها البعض قبل الوصول إلى التخزين. إذا كان تشابه جيب التمام >= `batch_dedup_threshold` (الافتراضي 0.98)، يتم إسقاط العنصر الأحدث بصمت. هذا يلتقط النسخ المكررة الدقيقة أو شبه الدقيقة داخل دفعة واحدة دون أي استدعاءات LLM (رياضيات متجهات خالصة). + +```python +# Only 2 records are stored (the third is a near-duplicate of the first) +memory.remember_many([ + "CrewAI supports complex workflows.", + "Python is a great language.", + "CrewAI supports complex workflows.", # dropped by intra-batch dedup +]) +``` + + +## الحفظ غير الحاجب + +`remember_many()` **غير حاجب** -- يقدم خط أنابيب الترميز إلى خيط خلفي ويعود فورًا. هذا يعني أن الوكيل يمكنه المتابعة إلى المهمة التالية بينما يتم حفظ الذكريات. + +```python +# Returns immediately -- save happens in background +memory.remember_many(["Fact A.", "Fact B.", "Fact C."]) + +# recall() automatically waits for pending saves before searching +matches = memory.recall("facts") # sees all 3 records +``` + +### حاجز القراءة + +كل استدعاء `recall()` يستدعي تلقائيًا `drain_writes()` قبل البحث، مما يضمن أن الاستعلام يرى دائمًا أحدث السجلات المستمرة. هذا شفاف -- لا تحتاج أبدًا إلى التفكير فيه. + +### إيقاف الفريق + +عند انتهاء الفريق، يستنزف `kickoff()` جميع عمليات حفظ الذاكرة المعلقة في كتلة `finally` الخاصة به، لذا لا تُفقد أي عمليات حفظ حتى لو اكتمل الفريق بينما عمليات الحفظ الخلفية قيد التنفيذ. + +### الاستخدام المستقل + +للسكربتات أو دفاتر الملاحظات حيث لا توجد دورة حياة فريق، استدعِ `drain_writes()` أو `close()` صراحة: + +```python +memory = Memory() +memory.remember_many(["Fact A.", "Fact B."]) + +# Option 1: Wait for pending saves +memory.drain_writes() + +# Option 2: Drain and shut down the background pool +memory.close() +``` + + +## المصدر والخصوصية + +يمكن لكل سجل ذاكرة أن يحمل علامة `source` لتتبع المصدر وعلامة `private` للتحكم في الوصول. + +### تتبع المصدر + +يحدد معامل `source` من أين جاءت الذاكرة: + +```python +# Tag memories with their origin +memory.remember("User prefers dark mode", source="user:alice") +memory.remember("System config updated", source="admin") +memory.remember("Agent found a bug", source="agent:debugger") + +# Recall only memories from a specific source +matches = memory.recall("user preferences", source="user:alice") +``` + +### الذكريات الخاصة + +الذكريات الخاصة مرئية فقط للاسترجاع عندما يتطابق `source`: + +```python +# Store a private memory +memory.remember("Alice's API key is sk-...", source="user:alice", private=True) + +# This recall sees the private memory (source matches) +matches = memory.recall("API key", source="user:alice") + +# This recall does NOT see it (different source) +matches = memory.recall("API key", source="user:bob") + +# Admin access: see all private records regardless of source +matches = memory.recall("API key", include_private=True) +``` + +هذا مفيد بشكل خاص في النشرات متعددة المستخدمين أو المؤسسية حيث يجب عزل ذكريات المستخدمين المختلفين. + + +## RecallFlow (الاسترجاع العميق) + +يدعم `recall()` عمقين: + +- **`depth="shallow"`** -- بحث متجهي مباشر مع تسجيل مركب. سريع (~200 مللي ثانية)، بدون استدعاءات LLM. +- **`depth="deep"` (افتراضي)** -- يشغل RecallFlow متعدد الخطوات: تحليل الاستعلام، اختيار النطاق، بحث متجهي متوازٍ، توجيه قائم على الثقة، واستكشاف متكرر اختياري عندما تكون الثقة منخفضة. + +**تخطي LLM الذكي**: الاستعلامات الأقصر من `query_analysis_threshold` (الافتراضي 200 حرف) تتخطى تحليل LLM للاستعلام بالكامل، حتى في الوضع العميق. الاستعلامات القصيرة مثل "ما قاعدة البيانات التي نستخدمها؟" هي بالفعل عبارات بحث جيدة -- تحليل LLM يضيف قيمة قليلة. هذا يوفر ~1-3 ثوانٍ لكل استرجاع للاستعلامات القصيرة النموذجية. فقط الاستعلامات الأطول (مثل أوصاف المهام الكاملة) تمر عبر تقطير LLM إلى استعلامات فرعية مستهدفة. + +```python +# Shallow: pure vector search, no LLM +matches = memory.recall("What did we decide?", limit=10, depth="shallow") + +# Deep (default): intelligent retrieval with LLM analysis for long queries +matches = memory.recall( + "Summarize all architecture decisions from this quarter", + limit=10, + depth="deep", +) +``` + +عتبات الثقة التي تتحكم في موجّه RecallFlow قابلة للإعداد: + +```python +memory = Memory( + confidence_threshold_high=0.9, # Only synthesize when very confident + confidence_threshold_low=0.4, # Explore deeper more aggressively + exploration_budget=2, # Allow up to 2 exploration rounds + query_analysis_threshold=200, # Skip LLM for queries shorter than this +) +``` + + +## إعداد المُضمِّن + +تحتاج الذاكرة إلى نموذج تضمين لتحويل النص إلى متجهات للبحث الدلالي. يمكنك إعداده بثلاث طرق. + +### التمرير إلى Memory مباشرة + +```python +from crewai import Memory + +# As a config dict +memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}) + +# As a pre-built callable +from crewai.rag.embeddings.factory import build_embedder +embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}) +memory = Memory(embedder=embedder) +``` + +### عبر إعداد مُضمِّن Crew + +عند استخدام `memory=True`، يتم تمرير إعداد `embedder` الخاص بالفريق: + +```python +from crewai import Crew + +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}, +) +``` + +### أمثلة المزودين + + + +```python +memory = Memory(embedder={ + "provider": "openai", + "config": { + "model_name": "text-embedding-3-small", + # "api_key": "sk-...", # or set OPENAI_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "ollama", + "config": { + "model_name": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "azure", + "config": { + "deployment_id": "your-embedding-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com", + "api_version": "2024-02-01", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-generativeai", + "config": { + "model_name": "gemini-embedding-001", + # "api_key": "...", # or set GOOGLE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-vertex", + "config": { + "model_name": "gemini-embedding-001", + "project_id": "your-gcp-project-id", + "location": "us-central1", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "cohere", + "config": { + "model_name": "embed-english-v3.0", + # "api_key": "...", # or set COHERE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "voyageai", + "config": { + "model": "voyage-3", + # "api_key": "...", # or set VOYAGE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "amazon-bedrock", + "config": { + "model_name": "amazon.titan-embed-text-v1", + # Uses default AWS credentials (boto3 session) + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "huggingface", + "config": { + "model_name": "sentence-transformers/all-MiniLM-L6-v2", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "jina", + "config": { + "model_name": "jina-embeddings-v2-base-en", + # "api_key": "...", # or set JINA_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "watsonx", + "config": { + "model_id": "ibm/slate-30m-english-rtrvr", + "api_key": "your-watsonx-api-key", + "project_id": "your-project-id", + "url": "https://us-south.ml.cloud.ibm.com", + }, +}) +``` + + + +```python +# Pass any callable that takes a list of strings and returns a list of vectors +def my_embedder(texts: list[str]) -> list[list[float]]: + # Your embedding logic here + return [[0.1, 0.2, ...] for _ in texts] + +memory = Memory(embedder=my_embedder) +``` + + + +### مرجع المزودين + +| المزود | المفتاح | النموذج النموذجي | ملاحظات | +| :--- | :--- | :--- | :--- | +| OpenAI | `openai` | `text-embedding-3-small` | افتراضي. عيّن `OPENAI_API_KEY`. | +| Ollama | `ollama` | `mxbai-embed-large` | محلي، لا حاجة لمفتاح API. | +| Azure OpenAI | `azure` | `text-embedding-ada-002` | يتطلب `deployment_id`. | +| Google AI | `google-generativeai` | `gemini-embedding-001` | عيّن `GOOGLE_API_KEY`. | +| Google Vertex | `google-vertex` | `gemini-embedding-001` | يتطلب `project_id`. | +| Cohere | `cohere` | `embed-english-v3.0` | دعم قوي متعدد اللغات. | +| VoyageAI | `voyageai` | `voyage-3` | محسّن للاسترجاع. | +| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | يستخدم بيانات اعتماد boto3. | +| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | sentence-transformers محلي. | +| Jina | `jina` | `jina-embeddings-v2-base-en` | عيّن `JINA_API_KEY`. | +| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | يتطلب `project_id`. | +| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | محلي، لا حاجة لمفتاح API. | +| مخصص | `custom` | -- | يتطلب `embedding_callable`. | + + +## إعداد LLM + +تستخدم الذاكرة LLM لتحليل الحفظ (استنتاج النطاق والفئات والأهمية)، وقرارات التوحيد، وتحليل استعلام الاسترجاع العميق. يمكنك إعداد النموذج المُستخدم. + +```python +from crewai import Memory, LLM + +# Default: gpt-4o-mini +memory = Memory() + +# Use a different OpenAI model +memory = Memory(llm="gpt-4o") + +# Use Anthropic +memory = Memory(llm="anthropic/claude-3-haiku-20240307") + +# Use Ollama for fully local/private analysis +memory = Memory(llm="ollama/llama3.2") + +# Use Google Gemini +memory = Memory(llm="gemini/gemini-2.0-flash") + +# Pass a pre-configured LLM instance with custom settings +llm = LLM(model="gpt-4o", temperature=0) +memory = Memory(llm=llm) +``` + +يتم تهيئة LLM **بشكل كسول** -- يتم إنشاؤه فقط عند الحاجة لأول مرة. هذا يعني أن `Memory()` لا يفشل أبدًا في وقت الإنشاء، حتى لو لم تكن مفاتيح API مُعيّنة. تظهر الأخطاء فقط عند استدعاء LLM فعليًا (مثلاً عند الحفظ بدون نطاق/فئات صريحة، أو أثناء الاسترجاع العميق). + +للتشغيل المحلي/الخاص بالكامل، استخدم نموذجًا محليًا لكل من LLM والمُضمِّن: + +```python +memory = Memory( + llm="ollama/llama3.2", + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) +``` + + +## واجهة التخزين + +- **الافتراضي**: LanceDB، مخزّن تحت `./.crewai/memory` (أو `$CREWAI_STORAGE_DIR/memory` إذا تم تعيين متغير البيئة، أو المسار الذي تمرره كـ `storage="path/to/dir"`). +- **واجهة مخصصة**: نفّذ بروتوكول `StorageBackend` (انظر `crewai.memory.storage.backend`) ومرّر مثيلًا إلى `Memory(storage=your_backend)`. + + +## الاستكشاف + +فحص التسلسل الهرمي للنطاقات والفئات والسجلات: + +```python +memory.tree() # Formatted tree of scopes and record counts +memory.tree("/project", max_depth=2) # Subtree view +memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest +memory.list_scopes("/") # Immediate child scopes +memory.list_categories() # Category names and counts +memory.list_records(scope="/project/alpha", limit=20) # Records in a scope, newest first +``` + + +## سلوك الفشل + +إذا فشل LLM أثناء التحليل (خطأ شبكة، حد معدل، استجابة غير صالحة)، تتدهور الذاكرة بسلاسة: + +- **تحليل الحفظ** -- يتم تسجيل تحذير ولا يزال يتم تخزين الذاكرة مع النطاق الافتراضي `/`، فئات فارغة، وأهمية `0.5`. +- **استخراج الذكريات** -- يتم تخزين المحتوى الكامل كذاكرة واحدة حتى لا يُفقد شيء. +- **تحليل الاستعلام** -- يتراجع الاسترجاع إلى اختيار نطاق بسيط وبحث متجهي حتى تستمر في الحصول على نتائج. + +لا يتم رفع أي استثناء لفشل التحليل هذه؛ فقط فشل التخزين أو المُضمِّن سيرفع استثناءً. + + +## ملاحظة حول الخصوصية + +يتم إرسال محتوى الذاكرة إلى LLM المُعدّ للتحليل (النطاق/الفئات/الأهمية عند الحفظ، تحليل الاستعلام والاسترجاع العميق الاختياري). للبيانات الحساسة، استخدم LLM محليًا (مثل Ollama) أو تأكد من أن مزودك يلبي متطلبات الامتثال الخاصة بك. + + +## أحداث الذاكرة + +جميع عمليات الذاكرة تُصدر أحداثًا مع `source_type="unified_memory"`. يمكنك الاستماع للتوقيت والأخطاء والمحتوى. + +| الحدث | الوصف | الخصائص الرئيسية | +| :---- | :---------- | :------------- | +| **MemoryQueryStartedEvent** | بداية الاستعلام | `query`, `limit` | +| **MemoryQueryCompletedEvent** | نجاح الاستعلام | `query`, `results`, `query_time_ms` | +| **MemoryQueryFailedEvent** | فشل الاستعلام | `query`, `error` | +| **MemorySaveStartedEvent** | بداية الحفظ | `value`, `metadata` | +| **MemorySaveCompletedEvent** | نجاح الحفظ | `value`, `save_time_ms` | +| **MemorySaveFailedEvent** | فشل الحفظ | `value`, `error` | +| **MemoryRetrievalStartedEvent** | بداية استرجاع الوكيل | `task_id` | +| **MemoryRetrievalCompletedEvent** | اكتمال استرجاع الوكيل | `task_id`, `memory_content`, `retrieval_time_ms` | + +مثال: مراقبة وقت الاستعلام: + +```python +from crewai.events import BaseEventListener, MemoryQueryCompletedEvent + +class MemoryMonitor(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(MemoryQueryCompletedEvent) + def on_done(source, event): + if getattr(event, "source_type", None) == "unified_memory": + print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms") +``` + + +## استكشاف المشاكل + +**الذاكرة لا تستمر؟** +- تأكد من أن مسار التخزين قابل للكتابة (الافتراضي `./.crewai/memory`). مرّر `storage="./your_path"` لاستخدام مجلد مختلف، أو عيّن متغير البيئة `CREWAI_STORAGE_DIR`. +- عند استخدام فريق، تأكد من تعيين `memory=True` أو `memory=Memory(...)`. + +**الاسترجاع بطيء؟** +- استخدم `depth="shallow"` لسياق الوكيل الروتيني. احتفظ بـ `depth="deep"` للاستعلامات المعقدة. +- زد `query_analysis_threshold` لتخطي تحليل LLM لمزيد من الاستعلامات. + +**أخطاء تحليل LLM في السجلات؟** +- لا تزال الذاكرة تحفظ/تسترجع بإعدادات افتراضية آمنة. تحقق من مفاتيح API وحدود المعدل وتوفر النموذج إذا كنت تريد تحليل LLM كاملاً. + +**أخطاء حفظ خلفية في السجلات؟** +- عمليات حفظ الذاكرة تعمل في خيط خلفي. تُصدر الأخطاء كـ `MemorySaveFailedEvent` لكنها لا تعطل الوكيل. تحقق من السجلات للسبب الجذري (عادة مشاكل اتصال LLM أو المُضمِّن). + +**تعارضات الكتابة المتزامنة؟** +- عمليات LanceDB مُتسلسلة بقفل مشترك وتُعاد تلقائيًا عند التعارض. هذا يتعامل مع مثيلات `Memory` المتعددة التي تشير إلى نفس قاعدة البيانات (مثل ذاكرة وكيل + ذاكرة فريق). لا حاجة لإجراء. + +**تصفح الذاكرة من الطرفية:** +```bash +crewai memory # Opens the TUI browser +crewai memory --storage-path ./my_memory # Point to a specific directory +``` + +**إعادة تعيين الذاكرة (مثلاً للاختبارات):** +```python +crew.reset_memories(command_type="memory") # Resets unified memory +# Or on a Memory instance: +memory.reset() # All scopes +memory.reset(scope="/project/old") # Only that subtree +``` + + +## مرجع الإعداد + +جميع الإعدادات تُمرر كمعاملات كلمة مفتاحية إلى `Memory(...)`. كل معامل له قيمة افتراضية معقولة. + +| المعامل | الافتراضي | الوصف | +| :--- | :--- | :--- | +| `llm` | `"gpt-4o-mini"` | LLM للتحليل (اسم نموذج أو مثيل `BaseLLM`). | +| `storage` | `"lancedb"` | واجهة التخزين (`"lancedb"`، سلسلة مسار، أو مثيل `StorageBackend`). | +| `embedder` | `None` (افتراضي OpenAI) | المُضمِّن (قاموس إعداد، دالة قابلة للاستدعاء، أو `None` لافتراضي OpenAI). | +| `recency_weight` | `0.3` | وزن الحداثة في الدرجة المركبة. | +| `semantic_weight` | `0.5` | وزن التشابه الدلالي في الدرجة المركبة. | +| `importance_weight` | `0.2` | وزن الأهمية في الدرجة المركبة. | +| `recency_half_life_days` | `30` | أيام لتنصيف درجة الحداثة (اضمحلال أُسي). | +| `consolidation_threshold` | `0.85` | التشابه الذي يُشغّل فوقه التوحيد عند الحفظ. عيّن إلى `1.0` للتعطيل. | +| `consolidation_limit` | `5` | أقصى عدد سجلات حالية للمقارنة أثناء التوحيد. | +| `default_importance` | `0.5` | الأهمية المُعيّنة عندما لا تُوفَّر ويتم تخطي تحليل LLM. | +| `batch_dedup_threshold` | `0.98` | تشابه جيب التمام لإسقاط النسخ شبه المكررة داخل دفعة `remember_many()`. | +| `confidence_threshold_high` | `0.8` | ثقة الاسترجاع التي تُعاد فوقها النتائج مباشرة. | +| `confidence_threshold_low` | `0.5` | ثقة الاسترجاع التي يُشغّل تحتها استكشاف أعمق. | +| `complex_query_threshold` | `0.7` | للاستعلامات المعقدة، استكشف أعمق تحت هذه الثقة. | +| `exploration_budget` | `1` | عدد جولات الاستكشاف المدفوعة بـ LLM أثناء الاسترجاع العميق. | +| `query_analysis_threshold` | `200` | الاستعلامات الأقصر من هذا (بالأحرف) تتخطى تحليل LLM أثناء الاسترجاع العميق. | diff --git a/docs/v1.15.1/ar/concepts/planning.mdx b/docs/v1.15.1/ar/concepts/planning.mdx new file mode 100644 index 000000000..12f5ef117 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/planning.mdx @@ -0,0 +1,155 @@ +--- +title: التخطيط +description: تعرّف على كيفية إضافة التخطيط إلى طاقم CrewAI وتحسين أدائه. +icon: ruler-combined +mode: "wide" +--- + +## نظرة عامة + +تتيح لك ميزة التخطيط في CrewAI إضافة قدرة التخطيط إلى طاقمك. عند تفعيلها، قبل كل تكرار للطاقم، +يتم إرسال جميع معلومات الطاقم إلى AgentPlanner الذي يخطط للمهام خطوة بخطوة، ويُضاف هذا المخطط إلى وصف كل مهمة. + +### استخدام ميزة التخطيط + +البدء بميزة التخطيط سهل جدًا، الخطوة الوحيدة المطلوبة هي إضافة `planning=True` إلى طاقمك: + + +```python Code +from crewai import Crew, Agent, Task, Process + +# تجميع طاقمك مع قدرات التخطيط +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, +) +``` + + +من هذه النقطة فصاعدًا، سيكون التخطيط مفعّلًا في طاقمك، وسيتم تخطيط المهام قبل كل تكرار. + + +عند تفعيل التخطيط، سيستخدم CrewAI `gpt-4o-mini` كنموذج LLM افتراضي للتخطيط، مما يتطلب مفتاح API صالحًا من OpenAI. نظرًا لأن وكلاءك قد يستخدمون نماذج LLM مختلفة، فقد يسبب ذلك ارتباكًا إذا لم يكن لديك مفتاح OpenAI API مهيأ أو إذا كنت تواجه سلوكًا غير متوقع متعلقًا باستدعاءات LLM API. + + +#### LLM التخطيط + +يمكنك الآن تحديد نموذج LLM الذي سيُستخدم لتخطيط المهام. + +عند تشغيل مثال الحالة الأساسية، سترى شيئًا مشابهًا للمخرجات أدناه، والتي تمثل مخرجات `AgentPlanner` +المسؤول عن إنشاء المنطق التدريجي لإضافته إلى مهام الوكلاء. + + +```python Code +from crewai import Crew, Agent, Task, Process + +# تجميع طاقمك مع قدرات التخطيط ونموذج LLM مخصص +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, + planning_llm="gpt-4o" +) + +# تشغيل الطاقم +my_crew.kickoff() +``` + +```markdown Result +[2024-07-15 16:49:11][INFO]: Planning the crew execution +**Step-by-Step Plan for Task Execution** + +**Task Number 1: Conduct a thorough research about AI LLMs** + +**Agent:** AI LLMs Senior Data Researcher + +**Agent Goal:** Uncover cutting-edge developments in AI LLMs + +**Task Expected Output:** A list with 10 bullet points of the most relevant information about AI LLMs + +**Task Tools:** None specified + +**Agent Tools:** None specified + +**Step-by-Step Plan:** + +1. **Define Research Scope:** + + - Determine the specific areas of AI LLMs to focus on, such as advancements in architecture, use cases, ethical considerations, and performance metrics. + +2. **Identify Reliable Sources:** + + - List reputable sources for AI research, including academic journals, industry reports, conferences (e.g., NeurIPS, ACL), AI research labs (e.g., OpenAI, Google AI), and online databases (e.g., IEEE Xplore, arXiv). + +3. **Collect Data:** + + - Search for the latest papers, articles, and reports published in 2024 and early 2025. + - Use keywords like "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025", etc. + +4. **Analyze Findings:** + + - Read and summarize the key points from each source. + - Highlight new techniques, models, and applications introduced in the past year. + +5. **Organize Information:** + + - Categorize the information into relevant topics (e.g., new architectures, ethical implications, real-world applications). + - Ensure each bullet point is concise but informative. + +6. **Create the List:** + + - Compile the 10 most relevant pieces of information into a bullet point list. + - Review the list to ensure clarity and relevance. + +**Expected Output:** + +A list with 10 bullet points of the most relevant information about AI LLMs. + +--- + +**Task Number 2: Review the context you got and expand each topic into a full section for a report** + +**Agent:** AI LLMs Reporting Analyst + +**Agent Goal:** Create detailed reports based on AI LLMs data analysis and research findings + +**Task Expected Output:** A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```' + +**Task Tools:** None specified + +**Agent Tools:** None specified + +**Step-by-Step Plan:** + +1. **Review the Bullet Points:** + - Carefully read through the list of 10 bullet points provided by the AI LLMs Senior Data Researcher. + +2. **Outline the Report:** + - Create an outline with each bullet point as a main section heading. + - Plan sub-sections under each main heading to cover different aspects of the topic. + +3. **Research Further Details:** + - For each bullet point, conduct additional research if necessary to gather more detailed information. + - Look for case studies, examples, and statistical data to support each section. + +4. **Write Detailed Sections:** + - Expand each bullet point into a comprehensive section. + - Ensure each section includes an introduction, detailed explanation, examples, and a conclusion. + - Use markdown formatting for headings, subheadings, lists, and emphasis. + +5. **Review and Edit:** + - Proofread the report for clarity, coherence, and correctness. + - Make sure the report flows logically from one section to the next. + - Format the report according to markdown standards. + +6. **Finalize the Report:** + - Ensure the report is complete with all sections expanded and detailed. + - Double-check formatting and make any necessary adjustments. + +**Expected Output:** +A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'. +``` + diff --git a/docs/v1.15.1/ar/concepts/processes.mdx b/docs/v1.15.1/ar/concepts/processes.mdx new file mode 100644 index 000000000..a49ecc227 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/processes.mdx @@ -0,0 +1,66 @@ +--- +title: العمليات +description: دليل تفصيلي حول إدارة سير العمل من خلال العمليات في CrewAI، مع تفاصيل التنفيذ المحدّثة. +icon: bars-staggered +mode: "wide" +--- + +## نظرة عامة + + + تنسّق العمليات تنفيذ المهام بواسطة الوكلاء، على غرار إدارة المشاريع في الفرق البشرية. + تضمن هذه العمليات توزيع المهام وتنفيذها بكفاءة، وفقًا لاستراتيجية محددة مسبقًا. + + +## تنفيذات العمليات + +- **تسلسلي**: ينفذ المهام بالتتابع، مما يضمن إكمال المهام بتقدم منظم. +- **هرمي**: ينظم المهام في تسلسل إداري هرمي، حيث يتم تفويض المهام وتنفيذها بناءً على سلسلة أوامر منظمة. يجب تحديد نموذج لغة المدير (`manager_llm`) أو وكيل مدير مخصص (`manager_agent`) في الطاقم لتفعيل العملية الهرمية، مما يسهّل إنشاء وإدارة المهام من قبل المدير. + +## دور العمليات في العمل الجماعي +تُمكّن العمليات الوكلاء الأفراد من العمل كوحدة متماسكة، مما يبسّط جهودهم لتحقيق أهداف مشتركة بكفاءة وتناسق. + +## تعيين العمليات للطاقم +لتعيين عملية لطاقم، حدد نوع العملية عند إنشاء الطاقم لتعيين استراتيجية التنفيذ. للعملية الهرمية، تأكد من تحديد `manager_llm` أو `manager_agent` لوكيل المدير. + +```python +from crewai import Crew, Process + +# مثال: إنشاء طاقم بعملية تسلسلية +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.sequential +) + +# مثال: إنشاء طاقم بعملية هرمية +# تأكد من توفير manager_llm أو manager_agent +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.hierarchical, + manager_llm="gpt-4o" + # أو + # manager_agent=my_manager_agent +) +``` +**ملاحظة:** تأكد من تعريف `my_agents` و `my_tasks` قبل إنشاء كائن `Crew`، وللعملية الهرمية، يُعد `manager_llm` أو `manager_agent` مطلوبًا أيضًا. + +## العملية التسلسلية + +تعكس هذه الطريقة سير عمل الفريق الديناميكي، وتتقدم عبر المهام بطريقة مدروسة ومنهجية. يتبع تنفيذ المهام الترتيب المحدد مسبقًا في قائمة المهام، حيث يعمل ناتج مهمة واحدة كسياق للمهمة التالية. + +لتخصيص سياق المهمة، استخدم معامل `context` في فئة `Task` لتحديد المخرجات التي يجب استخدامها كسياق للمهام اللاحقة. + +## العملية الهرمية + +تحاكي التسلسل الهرمي المؤسسي، حيث يسمح CrewAI بتحديد وكيل مدير مخصص أو إنشاء واحد تلقائيًا، مما يتطلب تحديد نموذج لغة المدير (`manager_llm`). يشرف هذا الوكيل على تنفيذ المهام، بما في ذلك التخطيط والتفويض والتحقق. لا يتم تعيين المهام مسبقًا؛ يخصص المدير المهام للوكلاء بناءً على قدراتهم، ويراجع المخرجات، ويقيّم اكتمال المهام. + +## فئة Process: نظرة عامة مفصلة + +تم تنفيذ فئة `Process` كتعداد (`Enum`)، مما يضمن أمان الأنواع ويقيّد قيم العملية على الأنواع المحددة (`sequential`، `hierarchical`). + +## الخلاصة + +التعاون المنظم الذي تسهّله العمليات داخل CrewAI ضروري لتمكين العمل الجماعي المنهجي بين الوكلاء. +تم تحديث هذه الوثائق لتعكس أحدث الميزات والتحسينات، مما يضمن وصول المستخدمين إلى أحدث المعلومات وأكثرها شمولاً. diff --git a/docs/v1.15.1/ar/concepts/production-architecture.mdx b/docs/v1.15.1/ar/concepts/production-architecture.mdx new file mode 100644 index 000000000..9dee3a734 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/production-architecture.mdx @@ -0,0 +1,162 @@ +--- +title: بنية الإنتاج +description: أفضل الممارسات لبناء تطبيقات ذكاء اصطناعي جاهزة للإنتاج مع CrewAI +icon: server +mode: "wide" +--- + +# عقلية التدفق أولاً + +عند بناء تطبيقات ذكاء اصطناعي إنتاجية مع CrewAI، **نوصي بالبدء بتدفق (Flow)**. + +بينما يمكن تشغيل أطقم أو وكلاء فرديين، فإن تغليفهم في تدفق يوفر الهيكل اللازم لتطبيق متين وقابل للتوسع. + +## لماذا التدفقات؟ + +1. **إدارة الحالة**: توفر التدفقات طريقة مدمجة لإدارة الحالة عبر مراحل مختلفة من تطبيقك. هذا ضروري لتمرير البيانات بين الأطقم والحفاظ على السياق ومعالجة مدخلات المستخدم. +2. **التحكم**: تتيح لك التدفقات تحديد مسارات تنفيذ دقيقة، بما في ذلك الحلقات والشرطيات ومنطق التفريع. هذا أساسي لمعالجة الحالات الاستثنائية وضمان سلوك تطبيقك بشكل متوقع. +3. **المراقبة**: توفر التدفقات هيكلًا واضحًا يسهّل تتبع التنفيذ وتصحيح الأخطاء ومراقبة الأداء. نوصي باستخدام [تتبع CrewAI](/ar/observability/tracing) للحصول على رؤى تفصيلية. ما عليك سوى تشغيل `crewai login` لتفعيل ميزات المراقبة المجانية. + +## البنية + +يبدو تطبيق CrewAI الإنتاجي النموذجي هكذا: + +```mermaid +graph TD + Start((Start)) --> Flow[Flow Orchestrator] + Flow --> State{State Management} + State --> Step1[Step 1: Data Gathering] + Step1 --> Crew1[Research Crew] + Crew1 --> State + State --> Step2{Condition Check} + Step2 -- "Valid" --> Step3[Step 3: Execution] + Step3 --> Crew2[Action Crew] + Step2 -- "Invalid" --> End((End)) + Crew2 --> End +``` + +### 1. فئة التدفق +فئة `Flow` هي نقطة الدخول. تحدد مخطط الحالة والطرق التي تنفذ منطقك. + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class AppState(BaseModel): + user_input: str = "" + research_results: str = "" + final_report: str = "" + +class ProductionFlow(Flow[AppState]): + @start() + def gather_input(self): + # ... منطق الحصول على المدخلات ... + pass + + @listen(gather_input) + def run_research_crew(self): + # ... تشغيل طاقم ... + pass +``` + +### 2. إدارة الحالة +استخدم نماذج Pydantic لتعريف حالتك. يضمن هذا أمان الأنواع ويوضح البيانات المتاحة في كل مرحلة. + +- **اجعلها بسيطة**: خزّن فقط ما تحتاجه للاستمرار بين المراحل. +- **استخدم بيانات منظمة**: تجنب القواميس غير المنظمة قدر الإمكان. + +### 3. الأطقم كوحدات عمل +فوّض المهام المعقدة إلى الأطقم. يجب أن يكون الطاقم مركّزًا على هدف محدد (مثل "البحث في موضوع"، "كتابة مقال مدونة"). + +- **لا تبالغ في هندسة الأطقم**: اجعلها مركّزة. +- **مرر الحالة بشكل صريح**: مرر البيانات الضرورية من حالة التدفق إلى مدخلات الطاقم. + +```python + @listen(gather_input) + def run_research_crew(self): + crew = ResearchCrew() + result = crew.kickoff(inputs={"topic": self.state.user_input}) + self.state.research_results = result.raw +``` + +## عناصر التحكم الأولية + +استفد من عناصر التحكم الأولية في CrewAI لإضافة المتانة والتحكم إلى أطقمك. + +### 1. حواجز المهام +استخدم [حواجز المهام](/ar/concepts/tasks#task-guardrails) للتحقق من مخرجات المهام قبل قبولها. يضمن هذا أن وكلاءك ينتجون نتائج عالية الجودة. + +```python +def validate_content(result: TaskOutput) -> Tuple[bool, Any]: + if len(result.raw) < 100: + return (False, "Content is too short. Please expand.") + return (True, result.raw) + +task = Task( + ..., + guardrail=validate_content +) +``` + +### 2. المخرجات المنظمة +استخدم دائمًا المخرجات المنظمة (`output_pydantic` أو `output_json`) عند تمرير البيانات بين المهام أو إلى تطبيقك. يمنع هذا أخطاء التحليل ويضمن أمان الأنواع. + +```python +class ResearchResult(BaseModel): + summary: str + sources: List[str] + +task = Task( + ..., + output_pydantic=ResearchResult +) +``` + +### 3. خطافات LLM +استخدم [خطافات LLM](/ar/learn/llm-hooks) لفحص أو تعديل الرسائل قبل إرسالها إلى LLM، أو لتنقية الاستجابات. + +```python +@before_llm_call +def log_request(context): + print(f"Agent {context.agent.role} is calling the LLM...") +``` + +## أنماط النشر + +عند نشر تدفقك، ضع في اعتبارك ما يلي: + +### CrewAI Enterprise +أسهل طريقة لنشر تدفقك هي استخدام CrewAI Enterprise. تتعامل مع البنية التحتية والمصادقة والمراقبة نيابة عنك. + +راجع [دليل النشر](/ar/enterprise/guides/deploy-to-amp) للبدء. + +```bash +crewai deploy create +``` + +### التنفيذ غير المتزامن +للمهام طويلة التشغيل، استخدم `kickoff_async` لتجنب حظر واجهتك البرمجية. + +### الاستمرارية +استخدم مزيّن `@persist` لحفظ حالة تدفقك في قاعدة بيانات. يتيح لك هذا استئناف التنفيذ إذا تعطلت العملية أو إذا كنت بحاجة لانتظار مدخلات بشرية. + +```python +@persist +class ProductionFlow(Flow[AppState]): + # ... +``` + +افتراضيًا، يستأنف `@persist` تدفقًا عند توفير `kickoff(inputs={"id": })`، مما يمدّ نفس تاريخ `flow_uuid`. لـ **تفرع** تدفق مستمر إلى نسبٍ جديد — ترطيب الحالة من تشغيل سابق ولكن الكتابة تحت `state.id` جديد — مرّر `restore_from_state_id`: + +```python +flow.kickoff(restore_from_state_id="") +``` + +يحصل التشغيل الجديد على `state.id` جديد (مولّد تلقائيًا، أو `inputs["id"]` إذا تم تثبيته) لذا لا تمتد كتابات `@persist` الخاصة به إلى تاريخ المصدر. الجمع مع `from_checkpoint` يطلق `ValueError`؛ اختر مصدر ترطيب واحدًا. + +## الخلاصة + +- **ابدأ بتدفق.** +- **حدد حالة واضحة.** +- **استخدم الأطقم للمهام المعقدة.** +- **انشر مع API واستمرارية.** diff --git a/docs/v1.15.1/ar/concepts/reasoning.mdx b/docs/v1.15.1/ar/concepts/reasoning.mdx new file mode 100644 index 000000000..33ec1d6e7 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/reasoning.mdx @@ -0,0 +1,148 @@ +--- +title: الاستدلال +description: "تعرّف على كيفية تفعيل واستخدام استدلال الوكيل لتحسين تنفيذ المهام." +icon: brain +mode: "wide" +--- + +## نظرة عامة + +استدلال الوكيل هو ميزة تتيح للوكلاء التأمل في المهمة وإنشاء خطة قبل التنفيذ. يساعد هذا الوكلاء على التعامل مع المهام بشكل أكثر منهجية ويضمن استعدادهم لأداء العمل المطلوب. + +## الاستخدام + +لتفعيل الاستدلال لوكيل، ما عليك سوى تعيين `reasoning=True` عند إنشاء الوكيل: + +```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, # تفعيل الاستدلال + max_reasoning_attempts=3 # اختياري: تعيين حد أقصى لمحاولات الاستدلال +) +``` + +## كيف يعمل + +عند تفعيل الاستدلال، قبل تنفيذ المهمة، سيقوم الوكيل بما يلي: + +1. التأمل في المهمة وإنشاء خطة مفصلة +2. تقييم ما إذا كان مستعدًا لتنفيذ المهمة +3. تحسين الخطة حسب الحاجة حتى يصبح مستعدًا أو يصل إلى max_reasoning_attempts +4. حقن خطة الاستدلال في وصف المهمة قبل التنفيذ + +تساعد هذه العملية الوكيل على تقسيم المهام المعقدة إلى خطوات يمكن إدارتها وتحديد التحديات المحتملة قبل البدء. + +## خيارات التهيئة + + + تفعيل أو تعطيل الاستدلال + + + + الحد الأقصى لعدد المحاولات لتحسين الخطة قبل المتابعة بالتنفيذ. إذا كانت القيمة None (الافتراضي)، سيستمر الوكيل في التحسين حتى يصبح مستعدًا. + + +## مثال + +إليك مثالًا كاملًا: + +```python +from crewai import Agent, Task, Crew + +# إنشاء وكيل مع تفعيل الاستدلال +analyst = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + backstory="You are an expert data analyst.", + reasoning=True, + max_reasoning_attempts=3 # اختياري: تعيين حد لمحاولات الاستدلال +) + +# إنشاء مهمة +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 +) + +# إنشاء طاقم وتشغيل المهمة +crew = Crew(agents=[analyst], tasks=[analysis_task]) +result = crew.kickoff() + +print(result) +``` + +## معالجة الأخطاء + +صُممت عملية الاستدلال لتكون متينة، مع معالجة أخطاء مدمجة. إذا حدث خطأ أثناء الاستدلال، سيتابع الوكيل تنفيذ المهمة بدون خطة الاستدلال. يضمن هذا إمكانية تنفيذ المهام حتى في حالة فشل عملية الاستدلال. + +إليك كيفية التعامل مع الأخطاء المحتملة في الكود الخاص بك: + +```python +from crewai import Agent, Task +import logging + +# إعداد التسجيل لالتقاط أي أخطاء في الاستدلال +logging.basicConfig(level=logging.INFO) + +# إنشاء وكيل مع تفعيل الاستدلال +agent = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + reasoning=True, + max_reasoning_attempts=3 +) + +# إنشاء مهمة +task = Task( + description="Analyze the provided sales data and identify key trends.", + expected_output="A report highlighting the top 3 sales trends.", + agent=agent +) + +# تنفيذ المهمة +# إذا حدث خطأ أثناء الاستدلال، سيتم تسجيله وسيستمر التنفيذ +result = agent.execute_task(task) +``` + +## مثال على مخرجات الاستدلال + +إليك مثالًا على شكل خطة الاستدلال لمهمة تحليل البيانات: + +``` +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. +``` + +تساعد خطة الاستدلال هذه الوكيل على تنظيم نهجه تجاه المهمة، والنظر في التحديات المحتملة، وضمان تقديم المخرجات المتوقعة. diff --git a/docs/v1.15.1/ar/concepts/skills.mdx b/docs/v1.15.1/ar/concepts/skills.mdx new file mode 100644 index 000000000..89f29a90a --- /dev/null +++ b/docs/v1.15.1/ar/concepts/skills.mdx @@ -0,0 +1,306 @@ +--- +title: المهارات +description: حزم المهارات المبنية على نظام الملفات التي تحقن خبرة المجال والتعليمات في إرشادات الوكلاء. +icon: bolt +mode: "wide" +--- + +## نظرة عامة + +المهارات هي مجلدات مستقلة توفر للوكلاء **تعليمات وإرشادات ومواد مرجعية خاصة بالمجال**. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown. + +عند التفعيل، يتم حقن تعليمات المهارة مباشرة في إرشادات مهمة الوكيل — مما يمنح الوكيل خبرة دون الحاجة لأي تغييرات في الكود. + + +**المهارات ليست أدوات.** هذه هي نقطة الارتباك الأكثر شيوعًا. + +- **المهارات** تحقن *تعليمات وسياق* في إرشادات الوكيل. تخبر الوكيل *كيف يفكر* في مشكلة ما. +- **الأدوات** تمنح الوكيل *دوال قابلة للاستدعاء* لاتخاذ إجراءات (البحث، قراءة الملفات، استدعاء APIs). + +غالبًا ما تحتاج **كليهما**: مهارات للخبرة، وأدوات للإجراء. يتم تكوينهما بشكل مستقل ويُكمّلان بعضهما. + + +--- + +## البداية السريعة + +### 1. إنشاء مجلد المهارة + +``` +skills/ +└── code-review/ + ├── SKILL.md # مطلوب — التعليمات + ├── references/ # اختياري — مستندات مرجعية + │ └── style-guide.md + └── scripts/ # اختياري — سكربتات قابلة للتنفيذ +``` + +### 2. كتابة SKILL.md الخاص بك + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## إرشادات مراجعة الكود + +عند مراجعة الكود، اتبع قائمة التحقق هذه: + +1. **الأمان**: تحقق من ثغرات الحقن وتجاوز المصادقة وكشف البيانات +2. **الأداء**: ابحث عن استعلامات N+1 والتخصيصات غير الضرورية والاستدعاءات المحظورة +3. **القابلية للقراءة**: تأكد من وضوح التسمية والتعليقات المناسبة والأسلوب المتسق +4. **الاختبارات**: تحقق من تغطية اختبار كافية للوظائف الجديدة + +### مستويات الخطورة +- **حرج**: ثغرات أمنية، مخاطر فقدان البيانات → حظر الدمج +- **رئيسي**: مشاكل أداء، أخطاء منطقية → طلب تغييرات +- **ثانوي**: مسائل أسلوبية، اقتراحات تسمية → الموافقة مع تعليقات +``` + +### 3. ربطها بوكيل + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # يحقن إرشادات المراجعة + tools=[GithubSearchTool(), FileReadTool()], # يسمح للوكيل بقراءة الكود +) +``` + +الوكيل الآن لديه **خبرة** (من المهارة) و**قدرات** (من الأدوات) معًا. + +--- + +## المهارات + الأدوات: العمل معًا + +إليك أنماط شائعة توضح كيف تُكمّل المهارات والأدوات بعضهما: + +### النمط 1: مهارات فقط (خبرة المجال، بدون إجراءات مطلوبة) + +استخدم عندما يحتاج الوكيل لتعليمات محددة لكن لا يحتاج لاستدعاء خدمات خارجية: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # إرشادات وقوالب الكتابة + # لا حاجة لأدوات — الوكيل يكتب بناءً على السياق المقدم +) +``` + +### النمط 2: أدوات فقط (إجراءات، بدون خبرة خاصة) + +استخدم عندما يحتاج الوكيل لاتخاذ إجراءات لكن لا يحتاج لتعليمات مجال محددة: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # يمكنه البحث والاستخراج + # لا حاجة لمهارات — البحث العام لا يحتاج إرشادات خاصة +) +``` + +### النمط 3: مهارات + أدوات (خبرة وإجراءات) + +النمط الأكثر شيوعًا في العالم الحقيقي. المهارة توفر *كيف* تقترب من العمل؛ الأدوات توفر *ما* يمكن للوكيل فعله: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # منهجية وقوائم تحقق التدقيق + tools=[ + SerperDevTool(), # البحث عن ثغرات معروفة + FileReadTool(), # قراءة ملفات التكوين + CodeInterpreterTool(), # تشغيل سكربتات التحليل + ], +) +``` + +### النمط 4: مهارات + MCP + +المهارات تعمل مع خوادم MCP بنفس الطريقة التي تعمل بها مع الأدوات: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # منهجية التحليل + mcps=["https://data-warehouse.example.com/sse"], # وصول بيانات عن بُعد +) +``` + +### النمط 5: مهارات + تطبيقات + +المهارات يمكن أن توجّه كيف يستخدم الوكيل تكاملات المنصة: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # قوالب الردود وقواعد التصعيد + apps=["gmail", "zendesk"], # يمكنه إرسال رسائل بريد وتحديث التذاكر +) +``` + +--- + +## المهارات على مستوى الطاقم + +يمكن تعيين المهارات على الطاقم لتُطبّق على **جميع الوكلاء**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # جميع الوكلاء يحصلون على هذه المهارات +) +``` + +المهارات على مستوى الوكيل لها الأولوية — إذا تم اكتشاف نفس المهارة في كلا المستويين، يتم استخدام نسخة الوكيل. + +--- + +## تنسيق SKILL.md + +```markdown +--- +name: my-skill +description: وصف قصير لما تفعله هذه المهارة ومتى تُستخدم. +license: Apache-2.0 # اختياري +compatibility: crewai>=0.1.0 # اختياري +metadata: # اختياري + author: your-name + version: "1.0" +allowed-tools: web-search file-read # اختياري، تجريبي +--- + +التعليمات للوكيل تُكتب هنا. يتم حقن محتوى Markdown هذا +في إرشادات الوكيل عند تفعيل المهارة. +``` + +### حقول البيانات الوصفية + +| الحقل | مطلوب | الوصف | +| :-------------- | :------- | :----------------------------------------------------------------------- | +| `name` | نعم | 1-64 حرف. أحرف صغيرة أبجدية رقمية وشرطات. يجب أن يطابق اسم المجلد. | +| `description` | نعم | 1-1024 حرف. يصف ما تفعله المهارة ومتى تُستخدم. | +| `license` | لا | اسم الترخيص أو مرجع لملف ترخيص مضمّن. | +| `compatibility` | لا | حد أقصى 500 حرف. متطلبات البيئة (منتجات، حزم، شبكة). | +| `metadata` | لا | تعيين مفتاح-قيمة نصي عشوائي. | +| `allowed-tools` | لا | قائمة أدوات معتمدة مسبقًا مفصولة بمسافات. تجريبي. | + +--- + +## هيكل المجلد + +``` +my-skill/ +├── SKILL.md # مطلوب — البيانات الوصفية + التعليمات +├── scripts/ # اختياري — سكربتات قابلة للتنفيذ +├── references/ # اختياري — مستندات مرجعية +└── assets/ # اختياري — ملفات ثابتة (إعدادات، بيانات) +``` + +يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة. + +--- + +## المهارات المحمّلة مسبقًا + +للمزيد من التحكم، يمكنك اكتشاف المهارات وتفعيلها برمجيًا: + +```python +from pathlib import Path +from crewai.skills import discover_skills, activate_skill + +# اكتشاف جميع المهارات في مجلد +skills = discover_skills(Path("./skills")) + +# تفعيلها (تحميل محتوى SKILL.md الكامل) +activated = [activate_skill(s) for s in skills] + +# تمرير إلى وكيل +agent = Agent( + role="Researcher", + goal="Find relevant information", + backstory="An expert researcher.", + skills=activated, +) +``` + +--- + +## كيف يتم تحميل المهارات + +تستخدم المهارات **الكشف التدريجي** — تحمّل فقط ما هو مطلوب في كل مرحلة: + +| المرحلة | ما يتم تحميله | متى | +| :--------- | :------------------------------------ | :------------------ | +| الاكتشاف | الاسم، الوصف، حقول البيانات الوصفية | `discover_skills()` | +| التفعيل | نص محتوى SKILL.md الكامل | `activate_skill()` | + +أثناء التنفيذ العادي للوكيل (تمرير مسارات المجلدات عبر `skills=["./skills"]`)، يتم اكتشاف المهارات وتفعيلها تلقائيًا. التحميل التدريجي مهم فقط عند استخدام الواجهة البرمجية. + +--- + +## المهارات مقابل المعرفة + +كلا المهارات والمعرفة تُعدّل إرشادات الوكيل، لكنهما يخدمان أغراضًا مختلفة: + +| الجانب | المهارات | المعرفة | +| :--- | :--- | :--- | +| **ما توفره** | تعليمات، إجراءات، إرشادات | حقائق، بيانات، معلومات | +| **كيف تُخزّن** | ملفات Markdown (SKILL.md) | مُضمّنة في مخزن متجهي (ChromaDB) | +| **كيف تُسترجع** | يتم حقن المحتوى الكامل في الإرشادات | البحث الدلالي يجد الأجزاء ذات الصلة | +| **الأفضل لـ** | المنهجيات، قوائم التحقق، أدلة الأسلوب | مستندات الشركة، معلومات المنتج، بيانات مرجعية | +| **يُعيّن عبر** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**القاعدة العامة:** إذا كان الوكيل يحتاج لاتباع *عملية*، استخدم مهارة. إذا كان يحتاج للرجوع إلى *بيانات*، استخدم المعرفة. + +--- + +## الأسئلة الشائعة + + + + يعتمد على حالة الاستخدام. المهارات والأدوات **مستقلتان** — يمكنك استخدام أيّ منهما أو كليهما أو لا شيء. + + - **مهارات فقط**: عندما يحتاج الوكيل خبرة لكن لا يحتاج إجراءات خارجية (مثال: الكتابة بإرشادات أسلوبية) + - **أدوات فقط**: عندما يحتاج الوكيل إجراءات لكن لا يحتاج منهجية خاصة (مثال: بحث بسيط على الويب) + - **كليهما**: عندما يحتاج الوكيل خبرة وإجراءات (مثال: تدقيق أمني بقوائم تحقق محددة وقدرة على فحص الكود) + + + + **لا.** حقل `allowed-tools` في SKILL.md هو بيانات وصفية تجريبية فقط — لا يُنشئ أو يحقن أي أدوات. يجب عليك دائمًا تعيين الأدوات بشكل منفصل عبر `tools=[]` أو `mcps=[]` أو `apps=[]`. + + + + المهارة على مستوى الوكيل لها الأولوية. يتم إزالة التكرار حسب الاسم — مهارات الوكيل تُعالج أولاً، لذا إذا ظهر نفس اسم المهارة في كلا المستويين، تُستخدم نسخة الوكيل. + + + + هناك تحذير ناعم عند 50,000 حرف، لكن بدون حد صارم. حافظ على تركيز المهارات وإيجازها للحصول على أفضل النتائج — الحقن الكبيرة في الإرشادات قد تُشتت انتباه الوكيل. + + diff --git a/docs/v1.15.1/ar/concepts/tasks.mdx b/docs/v1.15.1/ar/concepts/tasks.mdx new file mode 100644 index 000000000..e1fa1027c --- /dev/null +++ b/docs/v1.15.1/ar/concepts/tasks.mdx @@ -0,0 +1,1120 @@ +--- +title: المهام +description: دليل مفصل حول إدارة وإنشاء المهام ضمن إطار عمل CrewAI. +icon: list-check +mode: "wide" +--- + +## نظرة عامة + +في إطار عمل CrewAI، المهمة (`Task`) هي تكليف محدد يُنجزه وكيل (`Agent`). + +توفر المهام جميع التفاصيل اللازمة للتنفيذ، مثل الوصف والوكيل المسؤول والأدوات المطلوبة والمزيد، مما يسهّل مجموعة واسعة من تعقيدات الإجراءات. + +يمكن أن تكون المهام في CrewAI تعاونية، تتطلب عمل وكلاء متعددين معًا. تتم إدارة ذلك من خلال خصائص المهمة ويتم تنسيقه بواسطة عملية Crew، مما يعزز العمل الجماعي والكفاءة. + + +يتضمن CrewAI AMP منشئ مهام مرئي في Crew Studio يبسّط إنشاء المهام المعقدة وربطها. صمم تدفقات مهامك بصريًا واختبرها في الوقت الفعلي دون كتابة كود. + +![Task Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +يتيح منشئ المهام المرئي: + +- إنشاء المهام بالسحب والإفلات +- تبعيات المهام المرئية والتدفق +- الاختبار والتحقق في الوقت الفعلي +- المشاركة والتعاون بسهولة + + +### تدفق تنفيذ المهام + +يمكن تنفيذ المهام بطريقتين: + +- **تسلسلي**: تُنفَّذ المهام بالترتيب الذي تم تعريفها به +- **هرمي**: تُعيَّن المهام للوكلاء بناءً على أدوارهم وخبراتهم + +يتم تحديد تدفق التنفيذ عند إنشاء الفريق: + +```python Code +crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + process=Process.sequential # or Process.hierarchical +) +``` + +## خصائص المهمة + +| الخاصية | المعاملات | النوع | الوصف | +| :------------------------------------- | :---------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------- | +| **الوصف** | `description` | `str` | بيان واضح وموجز لما تستلزمه المهمة. | +| **المخرجات المتوقعة** | `expected_output` | `str` | وصف مفصل لما يبدو عليه إتمام المهمة. | +| **الاسم** _(اختياري)_ | `name` | `Optional[str]` | معرّف اسمي للمهمة. | +| **الوكيل** _(اختياري)_ | `agent` | `Optional[BaseAgent]` | الوكيل المسؤول عن تنفيذ المهمة. | +| **الأدوات** _(اختياري)_ | `tools` | `List[BaseTool]` | الأدوات/الموارد التي يقتصر الوكيل على استخدامها لهذه المهمة. | +| **السياق** _(اختياري)_ | `context` | `Optional[List["Task"]]` | مهام أخرى ستُستخدم مخرجاتها كسياق لهذه المهمة. | +| **التنفيذ غير المتزامن** _(اختياري)_ | `async_execution` | `Optional[bool]` | ما إذا كان يجب تنفيذ المهمة بشكل غير متزامن. الافتراضي False. | +| **المدخلات البشرية** _(اختياري)_ | `human_input` | `Optional[bool]` | ما إذا كان يجب أن يراجع إنسان الإجابة النهائية للوكيل. الافتراضي False. | +| **Markdown** _(اختياري)_ | `markdown` | `Optional[bool]` | ما إذا كان يجب أن توجّه المهمة الوكيل لإعادة الإجابة النهائية بتنسيق Markdown. الافتراضي False. | +| **الإعداد** _(اختياري)_ | `config` | `Optional[Dict[str, Any]]` | معاملات إعداد خاصة بالمهمة. | +| **ملف المخرجات** _(اختياري)_ | `output_file` | `Optional[str]` | مسار الملف لتخزين مخرجات المهمة. | +| **إنشاء المجلد** _(اختياري)_ | `create_directory` | `Optional[bool]` | ما إذا كان يجب إنشاء المجلد لـ output_file إذا لم يكن موجودًا. الافتراضي True. | +| **مخرجات JSON** _(اختياري)_ | `output_json` | `Optional[Type[BaseModel]]` | نموذج Pydantic لهيكلة مخرجات JSON. | +| **مخرجات Pydantic** _(اختياري)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | نموذج Pydantic لمخرجات المهمة. | +| **دالة الاسترجاع** _(اختياري)_ | `callback` | `Optional[Any]` | دالة/كائن يُنفَّذ بعد اكتمال المهمة. | +| **حارس** _(اختياري)_ | `guardrail` | `Optional[Callable]` | دالة للتحقق من مخرجات المهمة قبل الانتقال إلى المهمة التالية. | +| **حراس** _(اختياري)_ | `guardrails` | `Optional[List[Callable]]` | قائمة حراس للتحقق من مخرجات المهمة قبل الانتقال إلى المهمة التالية. | +| **أقصى محاولات الحارس** _(اختياري)_ | `guardrail_max_retries` | `Optional[int]` | الحد الأقصى لعدد المحاولات عند فشل التحقق من الحارس. الافتراضي 3. | + + + خاصية المهمة `max_retries` مهملة وستتم إزالتها في v1.0.0. + استخدم `guardrail_max_retries` بدلاً منها للتحكم في محاولات الإعادة عند فشل الحارس. + + +## إنشاء المهام + +هناك طريقتان شائعتان لإنشاء المهام في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفها **مباشرة في الكود**. + +### تهيئة JSONC (موصى بها) + +المشاريع الجديدة التي تُنشأ عبر `crewai create crew ` تعرّف المهام في `crew.jsonc`. + +````jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "reporting_analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research about {topic}.", + "expected_output": "A list of the most relevant information about {topic}.", + "agent": "researcher" + }, + { + "name": "reporting_task", + "description": "Review the research and expand it into a detailed report.", + "expected_output": "A polished markdown report.", + "agent": "reporting_analyst", + "context": ["research_task"], + "markdown": true, + "output_file": "report.md" + } + ], + "inputs": { + "topic": "AI Agents" + } +} +```` + +كل مهمة تحتاج إلى `description` و `expected_output`. يجب أن يطابق `agent` اسم Agent مذكورًا في `agents`. يشير `context` إلى أسماء مهام سابقة فقط؛ وترفض الإشارات إلى مهام لاحقة. + +### إعداد YAML الكلاسيكي + +المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew --classic` تستخدم `config/tasks.yaml` وفئة `@CrewBase` في `crew.py`. + +يظل إعداد YAML مدعومًا للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تفضل تعريف المهام من خلال فئة `@CrewBase`. + +بعد إنشاء مشروع كلاسيكي، انتقل إلى ملف `src//config/tasks.yaml` وعدّل القالب ليتوافق مع متطلبات مهامك المحددة. + + +المتغيرات في ملفات YAML (مثل `{topic}`) سيتم استبدالها بالقيم من مدخلاتك عند تشغيل الفريق: +```python Code +crew.kickoff(inputs={'topic': 'AI Agents'}) +``` + + +إليك مثال على كيفية إعداد المهام باستخدام YAML: + +````yaml 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 + markdown: true + output_file: report.md +```` + +لاستخدام إعداد YAML هذا في كودك، أنشئ فئة فريق ترث من `CrewBase`: + +```python crew.py +# src//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 + ) +``` + + + يجب أن تتطابق الأسماء المستخدمة في ملفات YAML (`agents.yaml` و `tasks.yaml`) + مع أسماء الدوال في كود Python الخاص بك. + + +### تعريف مباشر في الكود (بديل) + +بدلاً من ذلك، يمكنك تعريف المهام مباشرة في كودك دون استخدام إعداد YAML: + +```python task.py +from crewai import Task + +research_task = Task( + description=""" + Conduct a thorough research about AI Agents. + 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 AI Agents + """, + agent=researcher +) + +reporting_task = 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. + """, + agent=reporting_analyst, + markdown=True, # Enable markdown formatting for the final output + output_file="report.md" +) +``` + + + حدد وكيلًا (`agent`) مباشرة للتعيين أو دع عملية CrewAI `hierarchical` + تقرر بناءً على الأدوار والتوفر وغيرها. + + +## مخرجات المهمة + +فهم مخرجات المهام أمر بالغ الأهمية لبناء سير عمل ذكاء اصطناعي فعال. يوفر CrewAI طريقة منظمة للتعامل مع نتائج المهام من خلال فئة `TaskOutput`، التي تدعم تنسيقات مخرجات متعددة ويمكن تمريرها بسهولة بين المهام. + +يتم تغليف مخرجات المهمة في إطار عمل CrewAI داخل فئة `TaskOutput`. توفر هذه الفئة طريقة منظمة للوصول إلى نتائج المهمة، بما في ذلك تنسيقات متنوعة مثل المخرجات الخام و JSON ونماذج Pydantic. + +بشكل افتراضي، سيتضمن `TaskOutput` المخرجات `raw` فقط. سيتضمن `TaskOutput` مخرجات `pydantic` أو `json_dict` فقط إذا تم إعداد كائن `Task` الأصلي مع `output_pydantic` أو `output_json` على التوالي. + +### خصائص مخرجات المهمة + +| الخاصية | المعاملات | النوع | الوصف | +| :---------------- | :-------------- | :------------------------- | :------------------------------------------------------------------------------------------------- | +| **الوصف** | `description` | `str` | وصف المهمة. | +| **الملخص** | `summary` | `Optional[str]` | ملخص المهمة، يُنشأ تلقائيًا من أول 10 كلمات من الوصف. | +| **الخام** | `raw` | `str` | المخرجات الخام للمهمة. هذا هو التنسيق الافتراضي للمخرجات. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | كائن نموذج Pydantic يمثل المخرجات المنظمة للمهمة. | +| **قاموس JSON** | `json_dict` | `Optional[Dict[str, Any]]` | قاموس يمثل مخرجات JSON للمهمة. | +| **الوكيل** | `agent` | `str` | الوكيل الذي نفذ المهمة. | +| **تنسيق المخرجات**| `output_format` | `OutputFormat` | تنسيق مخرجات المهمة، مع خيارات تشمل RAW و JSON و Pydantic. الافتراضي هو RAW. | +| **الرسائل** | `messages` | `list[LLMMessage]` | الرسائل من آخر تنفيذ للمهمة. | + +### دوال وخصائص المهمة + +| الدالة/الخاصية | الوصف | +| :-------------- | :------------------------------------------------------------------------------------------------ | +| **json** | تُعيد تمثيل سلسلة JSON لمخرجات المهمة إذا كان تنسيق المخرجات JSON. | +| **to_dict** | تحوّل مخرجات JSON و Pydantic إلى قاموس. | +| **str** | تُعيد التمثيل النصي لمخرجات المهمة، مع أولوية Pydantic ثم JSON ثم الخام. | + +### الوصول إلى مخرجات المهمة + +بمجرد تنفيذ المهمة، يمكن الوصول إلى مخرجاتها من خلال خاصية `output` لكائن `Task`. توفر فئة `TaskOutput` طرقًا متنوعة للتفاعل مع هذه المخرجات وعرضها. + +#### مثال + +```python Code +# Example task +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +# Execute the crew +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() + +# Accessing the task output +task_output = task.output + +print(f"Task Description: {task_output.description}") +print(f"Task Summary: {task_output.summary}") +print(f"Raw Output: {task_output.raw}") +if task_output.json_dict: + print(f"JSON Output: {json.dumps(task_output.json_dict, indent=2)}") +if task_output.pydantic: + print(f"Pydantic Output: {task_output.pydantic}") +``` + +## تنسيق مخرجات Markdown + +يتيح معامل `markdown` تنسيق Markdown تلقائي لمخرجات المهام. عند تعيينه إلى `True`، ستوجّه المهمة الوكيل لتنسيق الإجابة النهائية باستخدام صيغة Markdown الصحيحة. + +### استخدام تنسيق Markdown + +```python Code +# Example task with markdown formatting enabled +formatted_task = Task( + description="Create a comprehensive report on AI trends", + expected_output="A well-structured report with headers, sections, and bullet points", + agent=reporter_agent, + markdown=True # Enable automatic markdown formatting +) +``` + +عند تعيين `markdown=True`، سيتلقى الوكيل تعليمات إضافية لتنسيق المخرجات باستخدام: + +- `#` للعناوين +- `**text**` للنص العريض +- `*text*` للنص المائل +- `-` أو `*` للقوائم النقطية +- `` `code` `` للكود المضمّن +- ` `language ``` لكتل الكود + +### إعداد YAML مع Markdown + +```yaml tasks.yaml +analysis_task: + description: > + Analyze the market data and create a detailed report + expected_output: > + A comprehensive analysis with charts and key findings + agent: analyst + markdown: true # Enable markdown formatting + output_file: analysis.md +``` + +### فوائد مخرجات Markdown + +- **تنسيق متسق**: يضمن اتباع جميع المخرجات لاتفاقيات Markdown الصحيحة +- **قابلية قراءة أفضل**: محتوى منظم مع عناوين وقوائم وتأكيد +- **جاهز للتوثيق**: يمكن استخدام المخرجات مباشرة في أنظمة التوثيق +- **توافق عبر المنصات**: Markdown مدعوم عالميًا + + + يتم إضافة تعليمات تنسيق Markdown تلقائيًا إلى موجّه المهمة + عند تعيين `markdown=True`، لذا لا تحتاج إلى تحديد متطلبات التنسيق + في وصف المهمة. + + +## تبعيات المهام والسياق + +يمكن للمهام الاعتماد على مخرجات مهام أخرى باستخدام خاصية `context`. على سبيل المثال: + +```python Code +research_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + agent=researcher +) + +analysis_task = Task( + description="Analyze the research findings and identify key trends", + expected_output="Analysis report of AI trends", + agent=analyst, + context=[research_task] # This task will wait for research_task to complete +) +``` + +## حراس المهام + +توفر حراس المهام طريقة للتحقق من مخرجات المهام وتحويلها قبل +تمريرها إلى المهمة التالية. تساعد هذه الميزة في ضمان جودة البيانات وتوفر +تغذية راجعة للوكلاء عندما لا تستوفي مخرجاتهم معايير محددة. + +يدعم CrewAI نوعين من الحراس: + +1. **حراس قائمون على الدوال**: دوال Python مع منطق تحقق مخصص، تمنحك تحكمًا كاملاً في عملية التحقق وتضمن نتائج موثوقة وحتمية. + +2. **حراس قائمون على LLM**: أوصاف نصية تستخدم LLM الخاص بالوكيل للتحقق من المخرجات بناءً على معايير لغة طبيعية. مثالية لمتطلبات التحقق المعقدة أو الذاتية. + +### الحراس القائمون على الدوال + +لإضافة حارس قائم على الدوال إلى مهمة، قدم دالة تحقق من خلال معامل `guardrail`: + +```python Code +from typing import Tuple, Union, Dict, Any +from crewai import TaskOutput + +def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]: + """Validate blog content meets requirements.""" + try: + # Check word count + word_count = len(result.raw.split()) + if word_count > 200: + return (False, "Blog content exceeds 200 words") + + # Additional validation logic here + return (True, result.raw.strip()) + except Exception as e: + return (False, "Unexpected error during validation") + +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail=validate_blog_content # Add the guardrail function +) +``` + +### الحراس القائمون على LLM (أوصاف نصية) + +بدلاً من كتابة دوال تحقق مخصصة، يمكنك استخدام أوصاف نصية تستفيد من التحقق القائم على LLM. عندما تقدم سلسلة نصية لمعامل `guardrail` أو `guardrails`، ينشئ CrewAI تلقائيًا `LLMGuardrail` يستخدم LLM الخاص بالوكيل للتحقق من المخرجات بناءً على وصفك. + +**المتطلبات**: + +- يجب أن يكون للمهمة وكيل (`agent`) مُعيّن (يستخدم الحارس LLM الخاص بالوكيل) +- قدم سلسلة نصية واضحة ووصفية تشرح معايير التحقق + +```python Code +from crewai import Task + +# Single LLM-based guardrail +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail="The blog post must be under 200 words and contain no technical jargon" +) +``` + +الحراس القائمون على LLM مفيدون بشكل خاص لـ: + +- **منطق التحقق المعقد** الذي يصعب التعبير عنه برمجيًا +- **المعايير الذاتية** مثل النبرة والأسلوب أو تقييمات الجودة +- **متطلبات اللغة الطبيعية** التي يسهل وصفها أكثر من برمجتها + +سيقوم حارس LLM بما يلي: + +1. تحليل مخرجات المهمة مقابل وصفك +2. إعادة `(True, output)` إذا امتثلت المخرجات للمعايير +3. إعادة `(False, feedback)` مع تغذية راجعة محددة إذا فشل التحقق + +**مثال مع معايير تحقق مفصلة**: + +```python Code +research_task = Task( + description="Research the latest developments in quantum computing", + expected_output="A comprehensive research report", + agent=researcher_agent, + guardrail=""" + The research report must: + - Be at least 1000 words long + - Include at least 5 credible sources + - Cover both technical and practical applications + - Be written in a professional, academic tone + - Avoid speculation or unverified claims + """ +) +``` + +### حراس متعددون + +يمكنك تطبيق حراس متعددين على مهمة باستخدام معامل `guardrails`. تُنفَّذ الحراس المتعددون بالتسلسل، حيث يتلقى كل حارس المخرجات من السابق. يتيح لك هذا سلسلة خطوات التحقق والتحويل. + +يقبل معامل `guardrails`: + +- قائمة من دوال الحراس أو أوصاف نصية +- حارس واحد (دالة أو سلسلة نصية) (مثل `guardrail`) + +**ملاحظة**: إذا تم تقديم `guardrails`، فإنه يأخذ الأولوية على `guardrail`. سيتم تجاهل معامل `guardrail` عند تعيين `guardrails`. + +```python Code +from typing import Tuple, Any +from crewai import TaskOutput, Task + +def validate_word_count(result: TaskOutput) -> Tuple[bool, Any]: + """Validate word count is within limits.""" + word_count = len(result.raw.split()) + if word_count < 100: + return (False, f"Content too short: {word_count} words. Need at least 100 words.") + if word_count > 500: + return (False, f"Content too long: {word_count} words. Maximum is 500 words.") + return (True, result.raw) + +def validate_no_profanity(result: TaskOutput) -> Tuple[bool, Any]: + """Check for inappropriate language.""" + profanity_words = ["badword1", "badword2"] # Example list + content_lower = result.raw.lower() + for word in profanity_words: + if word in content_lower: + return (False, f"Inappropriate language detected: {word}") + return (True, result.raw) + +def format_output(result: TaskOutput) -> Tuple[bool, Any]: + """Format and clean the output.""" + formatted = result.raw.strip() + # Capitalize first letter + formatted = formatted[0].upper() + formatted[1:] if formatted else formatted + return (True, formatted) + +# Apply multiple guardrails sequentially +blog_task = Task( + description="Write a blog post about AI", + expected_output="A well-formatted blog post between 100-500 words", + agent=blog_agent, + guardrails=[ + validate_word_count, # First: validate length + validate_no_profanity, # Second: check content + format_output # Third: format the result + ], + guardrail_max_retries=3 +) +``` + +في هذا المثال، تُنفَّذ الحراس بالترتيب: + +1. `validate_word_count` يتحقق من عدد الكلمات +2. `validate_no_profanity` يتحقق من اللغة غير الملائمة (باستخدام المخرجات من الخطوة 1) +3. `format_output` ينسّق النتيجة النهائية (باستخدام المخرجات من الخطوة 2) + +إذا فشل أي حارس، يتم إرسال الخطأ إلى الوكيل، وتُعاد المهمة حتى `guardrail_max_retries` مرة. + +**مزج الحراس القائمين على الدوال و LLM**: + +يمكنك الجمع بين الحراس القائمين على الدوال والنصية في نفس القائمة: + +```python Code +from typing import Tuple, Any +from crewai import TaskOutput, Task + +def validate_word_count(result: TaskOutput) -> Tuple[bool, Any]: + """Validate word count is within limits.""" + word_count = len(result.raw.split()) + if word_count < 100: + return (False, f"Content too short: {word_count} words. Need at least 100 words.") + if word_count > 500: + return (False, f"Content too long: {word_count} words. Maximum is 500 words.") + return (True, result.raw) + +# Mix function-based and LLM-based guardrails +blog_task = Task( + description="Write a blog post about AI", + expected_output="A well-formatted blog post between 100-500 words", + agent=blog_agent, + guardrails=[ + validate_word_count, # Function-based: precise word count check + "The content must be engaging and suitable for a general audience", # LLM-based: subjective quality check + "The writing style should be clear, concise, and free of technical jargon" # LLM-based: style validation + ], + guardrail_max_retries=3 +) +``` + +يجمع هذا النهج بين دقة التحقق البرمجي ومرونة التقييم القائم على LLM للمعايير الذاتية. + +### متطلبات دالة الحارس + +1. **توقيع الدالة**: + + - يجب أن تقبل معاملًا واحدًا بالضبط (مخرجات المهمة) + - يجب أن تُعيد tuple من `(bool, Any)` + - يُوصى بتلميحات الأنواع لكنها اختيارية + +2. **قيم الإعادة**: + - عند النجاح: تُعيد tuple من `(bool, Any)`. مثال: `(True, validated_result)` + - عند الفشل: تُعيد tuple من `(bool, str)`. مثال: `(False, "Error message explain the failure")` + +### أفضل ممارسات معالجة الأخطاء + +1. **استجابات أخطاء منظمة**: + +```python Code +from crewai import TaskOutput, LLMGuardrail + +def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]: + try: + # Main validation logic + 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. **فئات الأخطاء**: + + - استخدم رموز خطأ محددة + - ضمّن السياق ذا الصلة + - قدم تغذية راجعة قابلة للتنفيذ + +3. **سلسلة التحقق**: + +```python Code +from typing import Any, Dict, List, Tuple, Union +from crewai import TaskOutput + +def complex_validation(result: TaskOutput) -> Tuple[bool, Any]: + """Chain multiple validation steps.""" + # Step 1: Basic validation + if not result: + return (False, "Empty result") + + # Step 2: Content validation + try: + validated = validate_content(result) + if not validated: + return (False, "Invalid content") + + # Step 3: Format validation + formatted = format_output(validated) + return (True, formatted) + except Exception as e: + return (False, str(e)) +``` + +### التعامل مع نتائج الحارس + +عندما يُعيد حارس `(False, error)`: + +1. يتم إرسال الخطأ إلى الوكيل +2. يحاول الوكيل إصلاح المشكلة +3. تتكرر العملية حتى: + - يُعيد الحارس `(True, result)` + - يتم الوصول إلى الحد الأقصى للمحاولات (`guardrail_max_retries`) + +مثال مع معالجة إعادة المحاولة: + +```python Code +from typing import Optional, Tuple, Union +from crewai import TaskOutput, Task + +def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]: + """Validate and parse JSON output.""" + try: + # Try to parse as JSON + data = json.loads(result) + return (True, data) + except json.JSONDecodeError as e: + return (False, "Invalid JSON format") + +task = Task( + description="Generate a JSON report", + expected_output="A valid JSON object", + agent=analyst, + guardrail=validate_json_output, + guardrail_max_retries=3 # Limit retry attempts +) +``` + +## الحصول على مخرجات منظمة ومتسقة من المهام + + + من المهم أيضًا ملاحظة أن مخرجات المهمة الأخيرة في الفريق + تصبح المخرجات النهائية للفريق نفسه. + + +### استخدام `output_pydantic` + +تتيح لك خاصية `output_pydantic` تحديد نموذج Pydantic يجب أن تتوافق معه مخرجات المهمة. هذا يضمن أن المخرجات ليست منظمة فحسب، بل تم التحقق منها وفقًا لنموذج Pydantic. + +إليك مثال يوضح كيفية استخدام 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="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A compelling blog title and well-written content.", + agent=blog_agent, + output_pydantic=Blog, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Accessing Properties Directly from the Pydantic Model +print("Accessing Properties - Option 2") +title = result.pydantic.title +content = result.pydantic.content +print("Title:", title) +print("Content:", content) + +# Option 3: Accessing Properties Using the to_dict() Method +print("Accessing Properties - Option 3") +output_dict = result.to_dict() +title = output_dict["title"] +content = output_dict["content"] +print("Title:", title) +print("Content:", content) + +# Option 4: Printing the Entire Blog Object +print("Accessing Properties - Option 5") +print("Blog:", result) + +``` + +في هذا المثال: + +- يتم تعريف نموذج Pydantic Blog مع حقلي title و content. +- تستخدم المهمة task1 خاصية output_pydantic لتحديد أن مخرجاتها يجب أن تتوافق مع نموذج Blog. +- بعد تنفيذ الفريق، يمكنك الوصول إلى المخرجات المنظمة بعدة طرق كما هو موضح. + +#### شرح الوصول إلى المخرجات + +1. الفهرسة بأسلوب القاموس: يمكنك الوصول مباشرة إلى الحقول باستخدام result["field_name"]. يعمل هذا لأن فئة CrewOutput تنفذ دالة **getitem**. +2. مباشرة من نموذج Pydantic: الوصول إلى الخصائص مباشرة من كائن result.pydantic. +3. باستخدام دالة to_dict(): تحويل المخرجات إلى قاموس والوصول إلى الحقول. +4. طباعة الكائن بالكامل: ببساطة اطبع كائن result لرؤية المخرجات المنظمة. + +### استخدام `output_json` + +تتيح لك خاصية `output_json` تحديد المخرجات المتوقعة بتنسيق JSON. هذا يضمن أن مخرجات المهمة هي هيكل JSON صالح يمكن تحليله واستخدامه بسهولة في تطبيقك. + +إليك مثال يوضح كيفية استخدام `output_json`: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +# Define the Pydantic model for the blog +class Blog(BaseModel): + title: str + content: str + + +# Define the agent +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +# Define the task with output_json set to the Blog model +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A JSON object with 'title' and 'content' fields.", + agent=blog_agent, + output_json=Blog, +) + +# Instantiate the crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +# Kickoff the crew to execute the task +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Printing the Entire Blog Object +print("Accessing Properties - Option 2") +print("Blog:", result) +``` + +في هذا المثال: + +- يتم تعريف نموذج Pydantic Blog مع حقلي title و content، الذي يُستخدم لتحديد هيكل مخرجات JSON. +- تستخدم المهمة task1 خاصية output_json للإشارة إلى أنها تتوقع مخرجات JSON متوافقة مع نموذج Blog. +- بعد تنفيذ الفريق، يمكنك الوصول إلى مخرجات JSON المنظمة بطريقتين كما هو موضح. + +#### شرح الوصول إلى المخرجات + +1. الوصول إلى الخصائص باستخدام الفهرسة بأسلوب القاموس: يمكنك الوصول إلى الحقول مباشرة باستخدام result["field_name"]. هذا ممكن لأن فئة CrewOutput تنفذ دالة **getitem**، مما يتيح لك معاملة المخرجات كقاموس. في هذا الخيار، نسترد title و content من النتيجة. +2. طباعة كائن Blog بالكامل: بطباعة result، تحصل على التمثيل النصي لكائن CrewOutput. نظرًا لأن دالة **str** منفذة لإعادة مخرجات JSON، سيعرض هذا المخرجات الكاملة كسلسلة منسقة تمثل كائن Blog. + +--- + +باستخدام output_pydantic أو output_json، تضمن أن مهامك تنتج مخرجات بتنسيق متسق ومنظم، مما يسهّل معالجة البيانات واستخدامها داخل تطبيقك أو عبر مهام متعددة. + +## دمج الأدوات مع المهام + +استفد من أدوات [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) و [LangChain Tools](https://python.langchain.com/docs/integrations/tools) لتحسين أداء المهام وتفاعل الوكلاء. + +## إنشاء مهمة بأدوات + +```python Code +import os +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key + +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +research_agent = Agent( + role='Researcher', + goal='Find and summarize the latest AI news', + backstory="""You're a researcher at a large company. + You're responsible for analyzing data and providing insights + to the business.""", + verbose=True +) + +# to perform a semantic search for a specified query from a text's content across the internet +search_tool = SerperDevTool() + +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() +print(result) +``` + +يوضح هذا كيف يمكن للمهام ذات الأدوات المحددة تجاوز المجموعة الافتراضية للوكيل لتنفيذ مهام مخصصة. + +## الإشارة إلى مهام أخرى + +في CrewAI، يتم تمرير مخرجات مهمة واحدة تلقائيًا إلى المهمة التالية، لكن يمكنك تحديد مخرجات مهام بعينها، بما في ذلك عدة مهام، لاستخدامها كسياق لمهمة أخرى. + +هذا مفيد عندما تكون لديك مهمة تعتمد على مخرجات مهمة أخرى لا يتم تنفيذها مباشرة بعدها. يتم ذلك من خلال خاصية `context` للمهمة: + +```python Code +# ... + +research_ai_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +research_ops_task = Task( + description="Research the latest developments in AI Ops", + expected_output="A list of recent AI Ops developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +write_blog_task = Task( + description="Write a full blog post about the importance of AI and its latest news", + expected_output="Full blog post that is 4 paragraphs long", + agent=writer_agent, + context=[research_ai_task, research_ops_task] +) + +#... +``` + +## التنفيذ غير المتزامن + +يمكنك تعريف مهمة ليتم تنفيذها بشكل غير متزامن. هذا يعني أن الفريق لن ينتظر اكتمالها للمتابعة مع المهمة التالية. هذا مفيد للمهام التي تستغرق وقتًا طويلاً، أو التي ليست حاسمة لتنفيذ المهام التالية. + +يمكنك بعد ذلك استخدام خاصية `context` لتحديد في مهمة مستقبلية أنها يجب أن تنتظر اكتمال مخرجات المهمة غير المتزامنة. + +```python Code +#... + +list_ideas = Task( + description="List of 5 interesting ideas to explore for an article about AI.", + expected_output="Bullet point list of 5 ideas for an article.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +list_important_history = Task( + description="Research the history of AI and give me the 5 most important events.", + expected_output="Bullet point list of 5 important events.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +write_article = Task( + description="Write an article about AI, its history, and interesting ideas.", + expected_output="A 4 paragraph article about AI.", + agent=writer, + context=[list_ideas, list_important_history] # Will wait for the output of the two tasks to be completed +) + +#... +``` + +## آلية دالة الاسترجاع + +يتم تنفيذ دالة الاسترجاع بعد اكتمال المهمة، مما يتيح تشغيل إجراءات أو إشعارات بناءً على نتيجة المهمة. + +```python Code +# ... + +def callback_function(output: TaskOutput): + # Do something after the task is completed + # Example: Send an email to the manager + print(f""" + Task completed! + Task: {output.description} + Output: {output.raw} + """) + +research_task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool], + callback=callback_function +) + +#... +``` + +## الوصول إلى مخرجات مهمة محددة + +بمجرد انتهاء الفريق من التشغيل، يمكنك الوصول إلى مخرجات مهمة محددة باستخدام خاصية `output` لكائن المهمة: + +```python Code +# ... +task1 = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +#... + +crew = Crew( + agents=[research_agent], + tasks=[task1, task2, task3], + verbose=True +) + +result = crew.kickoff() + +# Returns a TaskOutput object with the description and results of the task +print(f""" + Task completed! + Task: {task1.output.description} + Output: {task1.output.raw} +""") +``` + +## آلية تجاوز الأدوات + +تحديد الأدوات في مهمة يتيح التكيف الديناميكي لقدرات الوكيل، مما يؤكد مرونة CrewAI. + +## آليات معالجة الأخطاء والتحقق + +أثناء إنشاء المهام وتنفيذها، توجد آليات تحقق معينة لضمان متانة وموثوقية خصائص المهمة. تشمل على سبيل المثال لا الحصر: + +- ضمان تعيين نوع مخرجات واحد فقط لكل مهمة للحفاظ على توقعات مخرجات واضحة. +- منع التعيين اليدوي لخاصية `id` للحفاظ على سلامة نظام المعرّفات الفريدة. + +تساعد عمليات التحقق هذه في الحفاظ على اتساق وموثوقية تنفيذ المهام ضمن إطار عمل crewAI. + +## إنشاء المجلدات عند حفظ الملفات + +يتحكم معامل `create_directory` فيما إذا كان يجب على CrewAI إنشاء المجلدات تلقائيًا عند حفظ مخرجات المهام في ملفات. هذه الميزة مفيدة بشكل خاص لتنظيم المخرجات وضمان هيكلة مسارات الملفات بشكل صحيح، خاصة عند العمل مع تسلسلات مشاريع معقدة. + +### السلوك الافتراضي + +بشكل افتراضي، `create_directory=True`، مما يعني أن CrewAI سينشئ تلقائيًا أي مجلدات مفقودة في مسار ملف المخرجات: + +```python Code +# Default behavior - directories are created automatically +report_task = Task( + description='Generate a comprehensive market analysis report', + expected_output='A detailed market analysis with charts and insights', + agent=analyst_agent, + output_file='reports/2025/market_analysis.md', # Creates 'reports/2025/' if it doesn't exist + markdown=True +) +``` + +### تعطيل إنشاء المجلدات + +إذا كنت تريد منع الإنشاء التلقائي للمجلدات والتأكد من وجود المجلد مسبقًا، عيّن `create_directory=False`: + +```python Code +# Strict mode - directory must already exist +strict_output_task = Task( + description='Save critical data that requires existing infrastructure', + expected_output='Data saved to pre-configured location', + agent=data_agent, + output_file='secure/vault/critical_data.json', + create_directory=False # Will raise RuntimeError if 'secure/vault/' doesn't exist +) +``` + +### إعداد YAML + +يمكنك أيضًا إعداد هذا السلوك في تعريفات مهام YAML: + +```yaml tasks.yaml +analysis_task: + description: > + Generate quarterly financial analysis + expected_output: > + A comprehensive financial report with quarterly insights + agent: financial_analyst + output_file: reports/quarterly/q4_2024_analysis.pdf + create_directory: true # Automatically create 'reports/quarterly/' directory + +audit_task: + description: > + Perform compliance audit and save to existing audit directory + expected_output: > + A compliance audit report + agent: auditor + output_file: audit/compliance_report.md + create_directory: false # Directory must already exist +``` + +### حالات الاستخدام + +**إنشاء المجلدات تلقائيًا (`create_directory=True`):** + +- بيئات التطوير والنماذج الأولية +- إنشاء تقارير ديناميكية مع مجلدات قائمة على التاريخ +- سير عمل آلي حيث قد يختلف هيكل المجلدات +- تطبيقات متعددة المستأجرين مع مجلدات خاصة بالمستخدمين + +**إدارة المجلدات يدويًا (`create_directory=False`):** + +- بيئات الإنتاج مع ضوابط نظام ملفات صارمة +- التطبيقات الحساسة أمنيًا حيث يجب إعداد المجلدات مسبقًا +- الأنظمة ذات متطلبات أذونات محددة +- بيئات الامتثال حيث يتم مراقبة إنشاء المجلدات + +### معالجة الأخطاء + +عندما يكون `create_directory=False` والمجلد غير موجود، سيرفع CrewAI خطأ `RuntimeError`: + +```python Code +try: + result = crew.kickoff() +except RuntimeError as e: + # Handle missing directory error + print(f"Directory creation failed: {e}") + # Create directory manually or use fallback location +``` + +شاهد الفيديو أدناه لمعرفة كيفية استخدام المخرجات المنظمة في CrewAI: + + + +## الخلاصة + +المهام هي القوة الدافعة وراء إجراءات الوكلاء في CrewAI. +من خلال تعريف المهام ونتائجها بشكل صحيح، تمهّد الطريق لعمل وكلاء الذكاء الاصطناعي بفعالية، سواء بشكل مستقل أو كوحدة تعاونية. +تجهيز المهام بالأدوات المناسبة وفهم عملية التنفيذ واتباع ممارسات التحقق المتينة أمور حاسمة لتعظيم إمكانات CrewAI، +وضمان إعداد الوكلاء بفعالية لتكليفاتهم وتنفيذ المهام كما هو مقصود. diff --git a/docs/v1.15.1/ar/concepts/testing.mdx b/docs/v1.15.1/ar/concepts/testing.mdx new file mode 100644 index 000000000..061dc7fb3 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/testing.mdx @@ -0,0 +1,49 @@ +--- +title: الاختبار +description: تعرّف على كيفية اختبار طاقم CrewAI وتقييم أدائه. +icon: vial +mode: "wide" +--- + +## نظرة عامة + +يُعد الاختبار جزءًا حيويًا من عملية التطوير، ومن الضروري التأكد من أن طاقمك يعمل كما هو متوقع. مع CrewAI، يمكنك اختبار طاقمك وتقييم أدائه بسهولة باستخدام إمكانيات الاختبار المدمجة. + +### استخدام ميزة الاختبار + +أضفنا أمر CLI `crewai test` لتسهيل اختبار طاقمك. سيقوم هذا الأمر بتشغيل طاقمك لعدد محدد من التكرارات وتوفير مقاييس أداء مفصلة. المعاملات هي `n_iterations` و `model`، وهي اختيارية وتكون قيمها الافتراضية 2 و `gpt-4o-mini` على التوالي. حاليًا، المزود الوحيد المتاح هو OpenAI. + +```bash +crewai test +``` + +إذا أردت تشغيل المزيد من التكرارات أو استخدام نموذج مختلف، يمكنك تحديد المعاملات هكذا: + +```bash +crewai test --n_iterations 5 --model gpt-4o +``` + +أو باستخدام الصيغة المختصرة: + +```bash +crewai test -n 5 -m gpt-4o +``` + +عند تشغيل أمر `crewai test`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل. + +سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية: + +
**درجات المهام (1-10 الأعلى أفضل)**
+ +| المهام/الطاقم/الوكلاء | التشغيل 1 | التشغيل 2 | المجموع المتوسط | الوكلاء | معلومات إضافية | +|:------------------|:-----:|:-----:|:----------:|:------------------------------:|:---------------------------------| +| المهمة 1 | 9.0 | 9.5 | **9.2** | Professional Insights | | +| | | | | Researcher | | +| المهمة 2 | 9.0 | 10.0 | **9.5** | Company Profile Investigator | | +| المهمة 3 | 9.0 | 9.0 | **9.0** | Automation Insights | | +| | | | | Specialist | | +| المهمة 4 | 9.0 | 9.0 | **9.0** | Final Report Compiler | Automation Insights Specialist | +| الطاقم | 9.00 | 9.38 | **9.2** | | | +| زمن التنفيذ (ثانية) | 126 | 145 | **135** | | | + +يوضح المثال أعلاه نتائج الاختبار لتشغيلين للطاقم مع مهمتين، مع الدرجة الإجمالية المتوسطة لكل مهمة والطاقم ككل. diff --git a/docs/v1.15.1/ar/concepts/tools.mdx b/docs/v1.15.1/ar/concepts/tools.mdx new file mode 100644 index 000000000..2740f723d --- /dev/null +++ b/docs/v1.15.1/ar/concepts/tools.mdx @@ -0,0 +1,290 @@ +--- +title: الأدوات +description: فهم واستخدام الأدوات ضمن إطار عمل CrewAI لتعاون الوكلاء وتنفيذ المهام. +icon: screwdriver-wrench +mode: "wide" +--- + +## نظرة عامة + +تُمكّن أدوات CrewAI الوكلاء بقدرات تتراوح من البحث على الويب وتحليل البيانات إلى التعاون وتفويض المهام بين الزملاء. +توضح هذه الوثائق كيفية إنشاء هذه الأدوات ودمجها والاستفادة منها ضمن إطار عمل CrewAI، بما في ذلك التركيز على أدوات التعاون. + + + الأدوات تمنح الوكلاء **دوال قابلة للاستدعاء** لاتخاذ إجراءات. تعمل جنبًا إلى جنب مع [MCP](/ar/mcp/overview) (خوادم أدوات عن بُعد) و[التطبيقات](/ar/concepts/agent-capabilities) (تكاملات المنصة) و[المهارات](/ar/concepts/skills) (خبرة المجال) و[المعرفة](/ar/concepts/knowledge) (حقائق مُسترجعة). راجع نظرة عامة على [قدرات الوكيل](/ar/concepts/agent-capabilities) لفهم متى تستخدم كل نوع. + + +## ما هي الأداة؟ + +الأداة في CrewAI هي مهارة أو وظيفة يمكن للوكلاء استخدامها لأداء إجراءات مختلفة. +يشمل ذلك أدوات من [مجموعة أدوات CrewAI](https://github.com/joaomdmoura/crewai-tools) و[أدوات LangChain](https://python.langchain.com/docs/integrations/tools)، +مما يُمكّن كل شيء من عمليات البحث البسيطة إلى التفاعلات المعقدة والعمل الجماعي الفعال بين الوكلاء. + + +يوفر CrewAI AMP مستودع أدوات شامل مع تكاملات جاهزة لأنظمة الأعمال الشائعة وواجهات API. انشر الوكلاء مع أدوات المؤسسة في دقائق بدلاً من أيام. + +يتضمن مستودع أدوات المؤسسة: + +- موصلات جاهزة لأنظمة المؤسسة الشائعة +- واجهة إنشاء أدوات مخصصة +- إمكانيات التحكم في الإصدارات والمشاركة +- ميزات الأمان والامتثال + + +## الخصائص الرئيسية للأدوات + +- **المنفعة**: مصممة لمهام مثل البحث على الويب وتحليل البيانات وإنشاء المحتوى وتعاون الوكلاء. +- **التكامل**: تعزز قدرات الوكلاء من خلال دمج الأدوات بسلاسة في سير عملهم. +- **القابلية للتخصيص**: توفر المرونة لتطوير أدوات مخصصة أو استخدام الأدوات الموجودة، لتلبية الاحتياجات المحددة للوكلاء. +- **معالجة الأخطاء**: تتضمن آليات معالجة أخطاء قوية لضمان التشغيل السلس. +- **آلية التخزين المؤقت**: تتميز بتخزين مؤقت ذكي لتحسين الأداء وتقليل العمليات المتكررة. +- **الدعم غير المتزامن**: تتعامل مع الأدوات المتزامنة وغير المتزامنة، مما يُمكّن العمليات غير الحاجبة. + +## استخدام أدوات CrewAI + +لتعزيز قدرات وكلائك بأدوات CrewAI، ابدأ بتثبيت حزمة الأدوات الإضافية: + +```bash +pip install 'crewai[tools]' +``` + +إليك مثالًا يوضح استخدامها: + +```python Code +import os +from crewai import Agent, Task, Crew +# استيراد أدوات crewAI +from crewai_tools import ( + DirectoryReadTool, + FileReadTool, + SerperDevTool, + WebsiteSearchTool +) + +# إعداد مفاتيح API +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key +os.environ["OPENAI_API_KEY"] = "Your Key" + +# إنشاء الأدوات +docs_tool = DirectoryReadTool(directory='./blog-posts') +file_tool = FileReadTool() +search_tool = SerperDevTool() +web_rag_tool = WebsiteSearchTool() + +# إنشاء الوكلاء +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 +) + +# تعريف المهام +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' +) + +# تجميع طاقم مع تفعيل التخطيط +crew = Crew( + agents=[researcher, writer], + tasks=[research, write], + verbose=True, + planning=True, +) + +# تنفيذ المهام +crew.kickoff() +``` + +## أدوات CrewAI المتاحة + +- **معالجة الأخطاء**: جميع الأدوات مبنية بقدرات معالجة الأخطاء، مما يسمح للوكلاء بإدارة الاستثناءات بسلاسة ومتابعة مهامهم. +- **آلية التخزين المؤقت**: جميع الأدوات تدعم التخزين المؤقت، مما يُمكّن الوكلاء من إعادة استخدام النتائج المحصلة سابقًا بكفاءة، مما يقلل الحمل على الموارد الخارجية ويسرّع وقت التنفيذ. يمكنك أيضًا تحديد تحكم أدق في آلية التخزين المؤقت باستخدام خاصية `cache_function` على الأداة. + +إليك قائمة بالأدوات المتاحة وأوصافها: + +| الأداة | الوصف | +| :------------------------------- | :--------------------------------------------------------------------------------------------- | +| **ApifyActorsTool** | أداة تدمج Apify Actors مع سير عملك لمهام استخراج البيانات من الويب والأتمتة. | +| **BrowserbaseLoadTool** | أداة للتفاعل مع المتصفحات واستخراج البيانات منها. | +| **CodeDocsSearchTool** | أداة RAG محسّنة للبحث في وثائق الكود والمستندات التقنية ذات الصلة. | +| **CodeInterpreterTool** | أداة لتفسير كود Python. | +| **ComposioTool** | تُمكّن استخدام أدوات Composio. | +| **CSVSearchTool** | أداة RAG مصممة للبحث في ملفات CSV، مخصصة للتعامل مع البيانات المنظمة. | +| **DALL-E Tool** | أداة لإنشاء الصور باستخدام DALL-E API. | +| **DirectorySearchTool** | أداة RAG للبحث في المجلدات، مفيدة للتنقل في أنظمة الملفات. | +| **DOCXSearchTool** | أداة RAG للبحث في مستندات DOCX، مثالية لمعالجة ملفات Word. | +| **DirectoryReadTool** | تسهّل قراءة ومعالجة هياكل المجلدات ومحتوياتها. | +| **ExaSearchTool** | أداة مصممة لإجراء عمليات بحث شاملة عبر مصادر بيانات متنوعة. | +| **FileReadTool** | تُمكّن قراءة واستخراج البيانات من الملفات، مع دعم تنسيقات ملفات متنوعة. | +| **FirecrawlSearchTool** | أداة للبحث في صفحات الويب باستخدام Firecrawl وإرجاع النتائج. | +| **FirecrawlCrawlWebsiteTool** | أداة لزحف صفحات الويب باستخدام Firecrawl. | +| **FirecrawlScrapeWebsiteTool** | أداة لاستخراج محتوى عناوين URL لصفحات الويب باستخدام Firecrawl. | +| **GithubSearchTool** | أداة RAG للبحث في مستودعات GitHub، مفيدة لبحث الكود والوثائق. | +| **SerperDevTool** | أداة متخصصة لأغراض التطوير، مع وظائف محددة قيد التطوير. | +| **TXTSearchTool** | أداة RAG مركّزة على البحث في ملفات النص (.txt)، مناسبة للبيانات غير المنظمة. | +| **JSONSearchTool** | أداة RAG مصممة للبحث في ملفات JSON، تخدم التعامل مع البيانات المنظمة. | +| **LlamaIndexTool** | تُمكّن استخدام أدوات LlamaIndex. | +| **MDXSearchTool** | أداة RAG مخصصة للبحث في ملفات Markdown (MDX)، مفيدة للوثائق. | +| **PDFSearchTool** | أداة RAG للبحث في مستندات PDF، مثالية لمعالجة المستندات الممسوحة ضوئيًا. | +| **PGSearchTool** | أداة RAG محسّنة للبحث في قواعد بيانات PostgreSQL، مناسبة لاستعلامات قواعد البيانات. | +| **Vision Tool** | أداة لإنشاء الصور باستخدام DALL-E API. | +| **RagTool** | أداة RAG للأغراض العامة قادرة على التعامل مع مصادر وأنواع بيانات متنوعة. | +| **ScrapeElementFromWebsiteTool** | تُمكّن استخراج عناصر محددة من المواقع، مفيدة لاستخراج البيانات المستهدف. | +| **ScrapeWebsiteTool** | تسهّل استخراج المواقع بالكامل، مثالية لجمع البيانات الشامل. | +| **WebsiteSearchTool** | أداة RAG للبحث في محتوى المواقع، محسّنة لاستخراج بيانات الويب. | +| **XMLSearchTool** | أداة RAG مصممة للبحث في ملفات XML، مناسبة لتنسيقات البيانات المنظمة. | +| **YoutubeChannelSearchTool** | أداة RAG للبحث في قنوات YouTube، مفيدة لتحليل محتوى الفيديو. | +| **YoutubeVideoSearchTool** | أداة RAG للبحث في مقاطع فيديو YouTube، مثالية لاستخراج بيانات الفيديو. | + +## إنشاء أدواتك الخاصة + + + يمكن للمطورين إنشاء `أدوات مخصصة` مصممة خصيصًا لاحتياجات وكلائهم أو + استخدام الخيارات الجاهزة. + + +هناك طريقتان رئيسيتان لإنشاء أداة CrewAI: + +### الوراثة من `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: + # منطق أداتك هنا + return "Tool's result" +``` + +## دعم الأدوات غير المتزامنة + +يدعم CrewAI الأدوات غير المتزامنة، مما يتيح لك تنفيذ أدوات تجري عمليات غير حاجبة مثل طلبات الشبكة وعمليات الإدخال/الإخراج على الملفات أو عمليات async أخرى بدون حجب مسار التنفيذ الرئيسي. + +### إنشاء أدوات غير متزامنة + +يمكنك إنشاء أدوات غير متزامنة بطريقتين: + +#### 1. استخدام مزيّن `tool` مع دوال Async + +```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.""" + # محاكاة عملية غير متزامنة + await asyncio.sleep(1) + return f"Data retrieved for {query}" +``` + +#### 2. تنفيذ طرق Async في فئات الأدوات المخصصة + +```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""" + # تنفيذك غير المتزامن هنا + await asyncio.sleep(1) + return f"Processed {query} asynchronously" +``` + +### استخدام الأدوات غير المتزامنة + +تعمل الأدوات غير المتزامنة بسلاسة في كل من سير عمل الطاقم القياسي وسير عمل التدفق: + +```python Code +# في طاقم قياسي +agent = Agent(role="researcher", tools=[async_custom_tool]) + +# في تدفق +class MyFlow(Flow): + @start() + async def begin(self): + crew = Crew(agents=[agent]) + result = await crew.kickoff_async() + return result +``` + +يتعامل إطار عمل CrewAI تلقائيًا مع تنفيذ الأدوات المتزامنة وغير المتزامنة، لذا لا تحتاج للقلق بشأن كيفية استدعائها بشكل مختلف. + +### استخدام مزيّن `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.""" + # منطق الدالة هنا + return "Result from your custom tool" +``` + +### آلية التخزين المؤقت المخصصة + + + يمكن للأدوات اختياريًا تنفيذ `cache_function` لضبط سلوك + التخزين المؤقت. تحدد هذه الدالة متى يتم تخزين النتائج مؤقتًا بناءً على شروط + محددة، مما يوفر تحكمًا دقيقًا في منطق التخزين المؤقت. + + +```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): + # في هذه الحالة، نخزّن النتيجة مؤقتًا فقط إذا كانت من مضاعفات 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, + ) + #... +``` + +## الخلاصة + +الأدوات محورية في توسيع قدرات وكلاء CrewAI، مما يمكّنهم من تنفيذ مجموعة واسعة من المهام والتعاون بفعالية. +عند بناء حلول مع CrewAI، استفد من كل من الأدوات المخصصة والموجودة لتمكين وكلائك وتعزيز نظام الذكاء الاصطناعي البيئي. فكّر في استخدام معالجة الأخطاء وآليات التخزين المؤقت ومرونة معاملات الأدوات لتحسين أداء وقدرات وكلائك. diff --git a/docs/v1.15.1/ar/concepts/training.mdx b/docs/v1.15.1/ar/concepts/training.mdx new file mode 100644 index 000000000..019532348 --- /dev/null +++ b/docs/v1.15.1/ar/concepts/training.mdx @@ -0,0 +1,197 @@ +--- +title: التدريب +description: تعرّف على كيفية تدريب وكلاء CrewAI من خلال تقديم ملاحظات مبكرة والحصول على نتائج متسقة. +icon: dumbbell +mode: "wide" +--- + +## نظرة عامة + +تتيح لك ميزة التدريب في CrewAI تدريب وكلاء الذكاء الاصطناعي باستخدام واجهة سطر الأوامر (CLI). +بتشغيل الأمر `crewai train -n `، يمكنك تحديد عدد التكرارات لعملية التدريب. + +أثناء التدريب، يستخدم CrewAI تقنيات لتحسين أداء وكلائك مع التغذية الراجعة البشرية. +يساعد هذا الوكلاء على تحسين فهمهم واتخاذ القرارات وحل المشكلات. + +### تدريب طاقمك باستخدام CLI + +لاستخدام ميزة التدريب، اتبع الخطوات التالية: + +1. افتح الطرفية أو موجه الأوامر. +2. انتقل إلى المجلد حيث يقع مشروع CrewAI. +3. شغّل الأمر التالي: + +```shell +crewai train -n -f +``` + + استبدل `` بعدد تكرارات التدريب المرغوب و`` باسم الملف المناسب المنتهي بـ `.pkl`. + + + + إذا حذفت `-f`، فإن المخرجات تُحفظ افتراضيًا في `trained_agents_data.pkl` في مجلد العمل الحالي. يمكنك تمرير مسار مطلق للتحكم في مكان كتابة الملف. + + +### تدريب طاقمك برمجيًا + +لتدريب طاقمك برمجيًا، استخدم الخطوات التالية: + +1. حدد عدد التكرارات للتدريب. +2. حدد معاملات الإدخال لعملية التدريب. +3. نفّذ أمر التدريب داخل كتلة try-except للتعامل مع الأخطاء المحتملة. + +```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}") +``` + +## كيف تُستخدم بيانات التدريب من قبل الوكلاء + +يستخدم CrewAI مخرجات التدريب بطريقتين: أثناء التدريب لدمج ملاحظاتك البشرية، وبعد التدريب لتوجيه الوكلاء باقتراحات موحدة. + +### تدفق بيانات التدريب + +```mermaid +flowchart TD + A["Start training
CLI: crewai train -n -f
or Python: crew.train(...)"] --> B["Setup training mode
- task.human_input = true
- disable delegation
- init training_data.pkl + trained file"] + + subgraph "Iterations" + direction LR + C["Iteration i
initial_output"] --> D["User human_feedback"] + D --> E["improved_output"] + E --> F["Append to training_data.pkl
by agent_id and iteration"] + end + + B --> C + F --> G{"More iterations?"} + G -- "Yes" --> C + G -- "No" --> H["Evaluate per agent
aggregate iterations"] + + H --> I["Consolidate
suggestions[] + quality + final_summary"] + I --> J["Save by agent role to trained file
(default: trained_agents_data.pkl)"] + + J --> K["Normal (non-training) runs"] + K --> L["Auto-load suggestions
from trained_agents_data.pkl"] + L --> M["Append to prompt
for consistent improvements"] +``` + +### أثناء تشغيلات التدريب + +- في كل تكرار، يسجل النظام لكل وكيل: + - `initial_output`: الإجابة الأولى للوكيل + - `human_feedback`: ملاحظاتك المضمّنة عند الطلب + - `improved_output`: إجابة المتابعة للوكيل بعد الملاحظات +- تُخزن هذه البيانات في ملف عمل باسم `training_data.pkl` مفهرس بمعرّف الوكيل الداخلي والتكرار. +- أثناء نشاط التدريب، يُلحق الوكيل تلقائيًا ملاحظاتك البشرية السابقة بأمره لتطبيق تلك التعليمات في المحاولات اللاحقة ضمن جلسة التدريب. + التدريب تفاعلي: تُعيّن المهام `human_input = true`، لذا سيتوقف التشغيل في بيئة غير تفاعلية بانتظار مدخلات المستخدم. + +### بعد اكتمال التدريب + +- عند انتهاء `train(...)`، يقيّم CrewAI بيانات التدريب المجمعة لكل وكيل وينتج نتيجة موحدة تحتوي على: + - `suggestions`: تعليمات واضحة وقابلة للتنفيذ مستخلصة من ملاحظاتك والفرق بين المخرجات الأولية/المحسنة + - `quality`: درجة من 0-10 تعكس التحسن + - `final_summary`: مجموعة خطوات عمل تفصيلية للمهام المستقبلية +- تُحفظ هذه النتائج الموحدة في اسم الملف الذي تمرره إلى `train(...)` (الافتراضي عبر CLI هو `trained_agents_data.pkl`). تُفهرس الإدخالات بدور الوكيل `role` لتطبيقها عبر الجلسات. +- أثناء التنفيذ العادي (غير التدريب)، يحمّل كل وكيل تلقائيًا `suggestions` الموحدة ويلحقها بأمر المهمة كتعليمات إلزامية. يمنحك هذا تحسينات متسقة بدون تغيير تعريفات الوكلاء. + +### ملخص الملفات + +- `training_data.pkl` (مؤقت، لكل جلسة): + - الهيكل: `agent_id -> { iteration_number: { initial_output, human_feedback, improved_output } }` + - الغرض: التقاط البيانات الخام والملاحظات البشرية أثناء التدريب + - الموقع: يُحفظ في مجلد العمل الحالي (CWD) +- `trained_agents_data.pkl` (أو اسم ملفك المخصص): + - الهيكل: `agent_role -> { suggestions: string[], quality: number, final_summary: string }` + - الغرض: استمرار التوجيه الموحد للتشغيلات المستقبلية + - الموقع: يُكتب في CWD افتراضيًا؛ استخدم `-f` لتعيين مسار مخصص (بما في ذلك المطلق) + +## اعتبارات نماذج اللغة الصغيرة + + + عند استخدام نماذج لغة أصغر (≤7 مليار معامل) لتقييم بيانات التدريب، كن على علم أنها قد تواجه تحديات في إنتاج مخرجات منظمة واتباع التعليمات المعقدة. + + +### قيود النماذج الصغيرة في تقييم التدريب + + + + غالبًا ما تواجه النماذج الأصغر صعوبة في إنتاج استجابات JSON صالحة مطلوبة لتقييمات التدريب المنظمة، مما يؤدي إلى أخطاء تحليل وبيانات غير مكتملة. + + + قد توفر النماذج تحت 7 مليار معامل تقييمات أقل دقة مع عمق استدلال محدود مقارنة بالنماذج الأكبر. + + + قد لا تُتبع معايير تقييم التدريب المعقدة بالكامل أو تُراعى من قبل النماذج الأصغر. + + + قد تفتقر التقييمات عبر تكرارات تدريب متعددة إلى الاتساق مع النماذج الأصغر. + + + +### توصيات للتدريب + + + + لجودة تدريب مثالية وتقييمات موثوقة، نوصي بشدة باستخدام نماذج بحد أدنى 7 مليار معامل أو أكبر: + + ```python + from crewai import Agent, Crew, Task, LLM + + # الحد الأدنى الموصى به لتقييم التدريب + llm = LLM(model="mistral/open-mistral-7b") + + # خيارات أفضل لتقييم تدريب موثوق + llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0") + llm = LLM(model="gpt-4o") + + # استخدم هذا LLM مع وكلائك + agent = Agent( + role="Training Evaluator", + goal="Provide accurate training feedback", + llm=llm + ) + ``` + + + توفر النماذج الأكثر قوة ملاحظات أعلى جودة مع استدلال أفضل، مما يؤدي إلى تكرارات تدريب أكثر فعالية. + + + + إذا كان يجب عليك استخدام نماذج أصغر لتقييم التدريب، كن على علم بهذه القيود: + + ```python + # استخدام نموذج أصغر (توقع بعض القيود) + llm = LLM(model="huggingface/microsoft/Phi-3-mini-4k-instruct") + ``` + + + بينما يتضمن CrewAI تحسينات للنماذج الصغيرة، توقع نتائج تقييم أقل موثوقية ودقة قد تتطلب تدخلاً بشريًا أكبر أثناء التدريب. + + + + +### نقاط مهمة يجب ملاحظتها + +- **متطلب العدد الصحيح الموجب:** تأكد من أن عدد التكرارات (`n_iterations`) هو عدد صحيح موجب. سيرمي الكود `ValueError` إذا لم يتحقق هذا الشرط. +- **متطلب اسم الملف:** تأكد من أن اسم الملف ينتهي بـ `.pkl`. سيرمي الكود `ValueError` إذا لم يتحقق هذا الشرط. +- **معالجة الأخطاء:** يتعامل الكود مع أخطاء العمليات الفرعية والاستثناءات غير المتوقعة، ويوفر رسائل خطأ للمستخدم. +- يُطبق التوجيه المدرّب في وقت الأمر؛ لا يعدّل تهيئة وكيل Python/YAML. +- يحمّل الوكلاء تلقائيًا الاقتراحات المدربة من ملف باسم `trained_agents_data.pkl` الموجود في مجلد العمل الحالي. إذا درّبت إلى اسم ملف مختلف، أعد تسميته إلى `trained_agents_data.pkl` قبل التشغيل، أو اضبط المحمّل في الكود. +- يمكنك تغيير اسم ملف المخرجات عند استدعاء `crewai train` بـ `-f/--filename`. المسارات المطلقة مدعومة إذا أردت الحفظ خارج CWD. + +من المهم ملاحظة أن عملية التدريب قد تستغرق بعض الوقت، اعتمادًا على تعقيد وكلائك وستتطلب أيضًا ملاحظاتك في كل تكرار. + +بمجرد اكتمال التدريب، سيكون وكلاؤك مجهزين بقدرات ومعرفة محسّنة، وجاهزين لمعالجة المهام المعقدة وتقديم رؤى أكثر اتساقًا وقيمة. + +تذكر تحديث وإعادة تدريب وكلائك بانتظام لضمان بقائهم على اطلاع بأحدث المعلومات والتطورات في المجال. diff --git a/docs/v1.15.1/ar/enterprise/features/agent-control-plane/monitoring.mdx b/docs/v1.15.1/ar/enterprise/features/agent-control-plane/monitoring.mdx new file mode 100644 index 000000000..db1b2c712 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/agent-control-plane/monitoring.mdx @@ -0,0 +1,112 @@ +--- +title: "راقب أتمتاتك" +description: "راقب صحة الأسطول واستهلاك LLM وسلوك كل أتمتة من تبويب Automations." +sidebarTitle: "المراقبة" +icon: "gauge" +mode: "wide" +--- + + + **تنقل وثائق ACP (إصدار تجريبي)** + + - [نظرة عامة](/ar/enterprise/features/agent-control-plane/overview) + - **المراقبة** *(أنت هنا)* + - [القواعد](/ar/enterprise/features/agent-control-plane/rules) + + +## نظرة عامة + +تبويب **Automations** هو عرض العمليات للقراءة فقط في [Agent Control Plane](/ar/enterprise/features/agent-control-plane/overview). يجمع بين بطاقتَي مقاييس و sankey تفاعلي وجدولين فرعيين — **Automations** و **Consumption** — يمكنك البحث والتصفية والفرز فيهما. + + + ![نظرة عامة على Agent Control Plane](/images/enterprise/acp-overview-automations-sankey.png) + + +تحترم جميع المخططات والجداول مُحدّد **آخر 24 ساعة / الأسبوع الماضي / آخر 30 يوماً** في أعلى اليمين. تقارن قيم الفرق النافذة المختارة بالنافذة السابقة بنفس الطول. + + + تعرض الصفوف بيانات فقط لعمليات النشر على **crewAI v1.13 أو أحدث** — تظهر عمليات النشر الأقدم في لافتة *"We've detected N other automations that we can't display"* أسفل sankey ولا تساهم بأي مقاييس حتى يتم تحديثها وإعادة نشرها. راجع [نظرة عامة — المتطلبات](/ar/enterprise/features/agent-control-plane/overview#المتطلبات). + + +## لوحة المعلومات + +يحتوي رأس الصفحة على بطاقتَي مقاييس و sankey تفاعلي. النقر على أي من البطاقتين يبدّل sankey بين وضعَين: + +- **وضع الصحة** — `إجمالي الأتمتات → حِزم الحالة (Critical / Warning / Healthy)`. انقر على حِزمة لتصفية جدول Automations إلى عمليات النشر تلك فقط. +- **وضع الاستهلاك** — `مزودو النماذج → الأتمتات → التكلفة الإجمالية`. انقر على مزود لتصفية جدول Consumption إلى ذلك المزود. + +| البطاقة | ما تعرضه | +|------|---------------| +| **Automations** | الأتمتات `active` (والعدد الإجمالي)، إجمالي `errors` في النافذة، `active executions` الحالية (والإجمالي في النافذة)، مع الفرق مقابل الفترة السابقة. | +| **Consumption** | إجمالي `cost` و `tokens used`، مع فرق التكلفة مقابل الفترة السابقة. | + + + ![نظرة عامة مع sankey الاستهلاك](/images/enterprise/acp-overview-consumption-sankey.png) + + +## جدول Automations + +التبويب الفرعي **Automations** هو تفصيل صحة الأسطول لكل deployment. كل صف هو crew أو flow منشور. + + + ![جدول الأتمتات مع تفصيل حالة الصحة](/images/enterprise/acp-automations-table.png) + + +| العمود | ما يعرضه | +|--------|---------------| +| **Automation** | اسم الـ deployment وأي وسوم مُسنَدة إليه (مثل `production`، `financial`). | +| **Last execution** | الوقت المنقضي منذ آخر تنفيذ. | +| **Health Status Breakdown** | شريط مكدّس بنسب `Critical` / `Warning` / `Healthy` لعمليات التنفيذ في النافذة. | +| **Executions with Errors** | إجمالي عمليات التنفيذ الفاشلة في النافذة. | +| **PII detection applied** | `Yes` إذا كان هناك تكوين PII لكل deployment أو [قاعدة PII](/ar/enterprise/features/agent-control-plane/rules) مطابِقة نشطة. | +| **Executions** | إجمالي عمليات التنفيذ في النافذة. | +| **Last updated** | متى أُعيد نشر الـ deployment آخر مرة. | +| **Crew Version** | إصدار `crewai` الذي يُبلِّغ عنه الـ deployment. يشير أيقونة المعلومات بجانب الإصدارات الأقل من `1.13` إلى صفوف لا يمكنها المساهمة بالمقاييس. | + +ابحث بالاسم، صفِّ حسب `Status` (`Healthy` / `Warning` / `Critical`)، وافرز بأي رأس عمود. انقر على اسم الـ deployment لفتح **لوحة الأتمتة**. + +## جدول Consumption + +التبويب الفرعي **Consumption** هو تفصيل إنفاق LLM واستخدام الرموز لكل deployment. + + + ![جدول الاستهلاك مُفصَّل حسب مزود LLM](/images/enterprise/acp-consumption-table.png) + + +| العمود | ما يعرضه | +|--------|---------------| +| **Automation** | اسم الـ deployment. | +| **Last execution** | الوقت المنقضي منذ آخر تنفيذ. | +| **Tokens used** | صف واحد لكل مزود LLM تستخدمه هذه الأتمتة، مع الفرق مقابل الفترة السابقة. | +| **Cost** | التكلفة لكل مزود LLM، مع الفرق مقابل الفترة السابقة. | +| **Total cost** | المجموع عبر جميع المزودين، مع الفرق. | +| **Executions** | إجمالي عمليات التنفيذ في النافذة. | +| **Last updated** | متى أُعيد نشر الـ deployment آخر مرة. | +| **Crew Version** | إصدار `crewai` الذي يُبلِّغ عنه الـ deployment. | + +صفِّ حسب **LLM provider** وافرز حسب `Cost` أو `Executions` أو `Last run`. + + + **عادة ما تعني الخلايا الفارغة (`—` أو `$0.00`) أن الـ deployment أدنى من crewAI v1.13.** في اللقطة أعلاه، تظهر *Automation F* (`1.7.0`) و *Automation I* (`1.12.2`) فارغة في الرموز والتكلفة — لا تزال عمليات التنفيذ تعمل، لكنها لا تُصدِر التليمتري على مستوى المزود الذي يُغذِّي هذا الجدول. حدّث هذه الـ crews وأعد نشرها لبدء جمع بيانات الاستهلاك. + + +## ذو صلة + + + + ما هو ACP، المتطلبات، مستويات الخطط، و RBAC. + + + طبّق قواعد PII Redaction على مستوى المؤسسة عبر العديد من الأتمتات. + + + تعمّق في تنفيذ واحد لرؤية تفكير الوكيل واستدعاءات الأدوات واستخدام الرموز. + + + انشر crew على إصدار crewAI يدعم Agent Control Plane. + + + + + تواصل مع فريق الدعم للمساعدة في تفسير المقاييس داخل Agent Control Plane. + diff --git a/docs/v1.15.1/ar/enterprise/features/agent-control-plane/overview.mdx b/docs/v1.15.1/ar/enterprise/features/agent-control-plane/overview.mdx new file mode 100644 index 000000000..6e9ff1925 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/agent-control-plane/overview.mdx @@ -0,0 +1,82 @@ +--- +title: نظرة عامة على Agent Control Plane +description: "مركز عمليات موحّد للأتمتات الجارية — صحة الأسطول واستهلاك LLM والسياسات على مستوى المؤسسة في مكان واحد." +sidebarTitle: نظرة عامة +icon: "book-open" +--- + + + **تنقل وثائق ACP (إصدار تجريبي)** + + - **نظرة عامة** *(أنت هنا)* + - [المراقبة](/ar/enterprise/features/agent-control-plane/monitoring) + - [القواعد](/ar/enterprise/features/agent-control-plane/rules) + + +## نظرة عامة + +**Agent Control Plane** (ACP) هو مركز العمليات لكل ما يعمل لديك على CrewAI AMP. إنها شاشة واحدة — مقسّمة إلى تبويبَي **Automations** و **Rules** — تمنح فريقك القدرة على: + +- مراقبة **حالة (الصحة)** كل أتمتة حيّة (crew أو flow) بتفصيل `Critical` / `Warning` / `Healthy` وعدد عمليات التنفيذ. +- تتبع **استهلاك LLM** — الرموز (tokens) والتكلفة — لكل أتمتة ولكل مزود ولكل نموذج، مع الفرق مقابل الفترة السابقة. +- التعمّق في أي أتمتة منفردة أو مزود نماذج لرؤية المخططات الزمنية وتفصيل البيانات لكل مزود. +- تطبيق **قواعد (Rules)** على مستوى المؤسسة (اليوم: PII Redaction) عبر العديد من الأتمتات دفعة واحدة بدلاً من تعديل كل deployment على حدة. + + + ![نظرة عامة على Agent Control Plane](/images/enterprise/acp-overview-automations-sankey.png) + + + + Agent Control Plane مُوسوم حالياً بـ **Beta** في CrewAI Platform. + + +يجيب التبويبان عن سؤالَين مختلفَين: + +- **Automations** — *"كيف يتصرف أسطولي الآن، وكم يكلّفني؟"* راجع [المراقبة](/ar/enterprise/features/agent-control-plane/monitoring). +- **Rules** — *"كيف أفرض سياسة (مثل PII redaction) عبر العديد من عمليات النشر دون إعادة نشر كل واحدة؟"* راجع [القواعد](/ar/enterprise/features/agent-control-plane/rules). + +## المتطلبات + + + يُشترط **crewAI v1.13 أو أحدث** ليتمكن أي أتمتة من تعبئة أي بيانات على هذه الصفحة — تمر بيانات الصحة وعمليات التنفيذ والأخطاء والرموز والتكلفة عبر التليمتري الذي تم تفعيله في `crewai==1.13`. تظهر عمليات النشر الأقدم في لافتة *"We've detected N other automations that we can't display"* ولا تساهم بأي صفوف حتى يتم تحديثها وإعادة نشرها. + + + + يُشترط **خطة Enterprise أو Ultra** لإنشاء أو تعديل [القواعد](/ar/enterprise/features/agent-control-plane/rules). يمكن للمؤسسات على الخطط الأدنى فتح تبويب Rules وعرض القواعد الموجودة، ولكن يُعرض المحرر للقراءة فقط مع شارة قفل "Enterprise" والتنبيه *"PII Redaction rules require an Enterprise plan."*. المراقبة (تبويب Automations) متاحة في جميع الخطط حيث يكون هذا الميزة مفعّلة. + + +- يجب أن تكون ميزة **Agent Control Plane** مفعّلة لمؤسستك. إن لم ترها في الشريط الجانبي، اطلب من مالك الحساب تفعيلها. +- داخل ACP، يحكم [RBAC](/ar/enterprise/features/rbac) الوصول: `read` للعرض في لوحة المعلومات والقواعد، و`manage` لإنشاء وتعديل وتشغيل/إيقاف وحذف القواعد. +- يمكن ضبط نطاق جميع المخططات والجداول إلى **آخر 24 ساعة** أو **الأسبوع الماضي** أو **آخر 30 يوماً** عبر مُحدّد الوقت في أعلى اليمين. تقارن قيم الفرق (`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday` وغيرها) النافذة المختارة بالنافذة السابقة بنفس الطول. + +## ما يمكنك فعله هنا + + + + راقب صحة الأسطول وإنفاق LLM عبر بطاقات المقاييس و sankey التفاعلي وجداول لكل أتمتة ولوحات جانبية للتعمق في أي أتمتة أو مزود. + + + طبّق سياسات PII Redaction على مستوى المؤسسة بنطاق محدد بالأدوات والوسوم. تسري التغييرات في التنفيذ التالي — دون الحاجة لإعادة نشر. + + + +## ذو صلة + + + + تعمّق في تنفيذ واحد لرؤية تفكير الوكيل واستدعاءات الأدوات واستخدام الرموز. + + + أدِر من يمكنه قراءة Agent Control Plane ومن يمكنه تعديل القواعد. + + + كتالوج الكيانات وضبط PII لكل deployment التي تستند إليها القواعد. + + + انشر crew على إصدار crewAI يدعم Agent Control Plane. + + + + + تواصل مع فريق الدعم للمساعدة في تفسير المقاييس أو تصميم القواعد. + diff --git a/docs/v1.15.1/ar/enterprise/features/agent-control-plane/rules.mdx b/docs/v1.15.1/ar/enterprise/features/agent-control-plane/rules.mdx new file mode 100644 index 000000000..144ec1003 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/agent-control-plane/rules.mdx @@ -0,0 +1,122 @@ +--- +title: "إعداد القواعد" +description: "طبّق سياسات على مستوى المؤسسة عبر العديد من الأتمتات من مكان واحد." +sidebarTitle: "القواعد" +icon: "shield-check" +mode: "wide" +--- + + + **تنقل وثائق ACP (إصدار تجريبي)** + + - [نظرة عامة](/ar/enterprise/features/agent-control-plane/overview) + - [المراقبة](/ar/enterprise/features/agent-control-plane/monitoring) + - **القواعد** *(أنت هنا)* + + +## نظرة عامة + +تتيح لك القواعد تطبيق سياسات — اليوم: **PII Redaction** — عبر العديد من الأتمتات دفعة واحدة، بدلاً من ضبط كل deployment على حدة. افتح تبويب **Rules** في [Agent Control Plane](/ar/enterprise/features/agent-control-plane/overview) لإدارتها. + + + ![قائمة القواعد](/images/enterprise/acp-rules-list.png) + + +تعرض كل بطاقة قاعدة الاسم والوصف و**النطاق (scope)** الذي تنطبق عليه القاعدة (الأدوات والوسوم المختارة) وعدد **الأتمتات المُفعَّلة** — عمليات النشر التي تطابق النطاق حالياً. يقوم المُفتاح على اليمين بتشغيل القاعدة أو إيقافها دون حذفها. + +## المتطلبات + + + يُشترط **خطة Enterprise أو Ultra** لإنشاء أو تعديل قواعد PII Redaction. يمكن للمؤسسات على الخطط الأدنى فتح تبويب Rules وعرض القواعد الموجودة، ولكن يُعرض المحرر للقراءة فقط مع شارة قفل "Enterprise" والتنبيه *"PII Redaction rules require an Enterprise plan."* — تواصل مع مالك حسابك أو المبيعات للترقية. + + +- يجب أن تكون ميزة **Agent Control Plane** مفعّلة لمؤسستك. راجع [نظرة عامة — المتطلبات](/ar/enterprise/features/agent-control-plane/overview#المتطلبات). +- تحتاج إلى صلاحية `manage` ضمن [RBAC](/ar/enterprise/features/rbac) على Agent Control Plane لإنشاء وتعديل وتشغيل/إيقاف وحذف القواعد. صلاحية `read` كافية لعرضها. +- تُسجَّل جميع تغييرات القواعد بإصدارات للتدقيق. + +## أنواع القواعد المتاحة + +| النوع | ما تفعله | +|------|---------------| +| **PII Redaction** | تطبّق PII redaction على عمليات التنفيذ لكل أتمتة مطابِقة، باستخدام نفس كتالوج الكيانات و recognizers المخصصة الموثَّقة في [PII Redaction للـ Traces](/ar/enterprise/features/pii-trace-redactions). | + +سيتم إضافة أنواع قواعد أخرى مع الوقت. + +## إنشاء قاعدة + + + لوحة تعديل قاعدة جانبية بالشروط ونوع قناع PII + + + + + انقر على **+ Create new** في أعلى يمين تبويب Rules، أو على **View Details** في بطاقة قاعدة موجودة. + + + + أعطِ القاعدة اسماً واضحاً (مثل *Mask PII (CC)*) ووصفاً يشرح متى تنطبق. يظهر كلاهما على بطاقة القاعدة وفي مودال Engaged Automations. + + + + اليوم **PII Redaction** فقط متاحة. + + + + تحدد الشروط الأتمتات التي تنخرط معها القاعدة. كلاهما اختياري ويستخدم دلالات **مساواة المجموعات (set-equality)**: + + - **Tools** — تنخرط فقط الأتمتات التي تتطابق مجموعة أدواتها **تطابقاً تامّاً** مع الأدوات المختارة. اختر من تطبيقات Studio و MCPs والأدوات مفتوحة المصدر وأدوات سجل Tool Repository. + - **Automations** — تنخرط فقط الأتمتات التي تتطابق مجموعة وسومها **تطابقاً تامّاً** مع الوسوم المختارة. + + ترك مُحدِّد فارغ يعني "بدون تصفية على هذا البعد". ترك كليهما فارغَين يعني أن القاعدة تنطبق على **كل** أتمتة في المؤسسة. + + + + حدّد كل نوع كيان تريد تغطيته واختر **Mask** (يستبدل بتسمية الكيان مثل ``) أو **Redact** (يحذف النص المطابِق بالكامل). راجع [PII Redaction للـ Traces](/ar/enterprise/features/pii-trace-redactions) للاطلاع على كتالوج الكيانات الكامل وكيفية إضافة recognizers مخصصة على مستوى المؤسسة. + + + + تنطبق القاعدة على عمليات التنفيذ **المستقبلية** لكل أتمتة مُفعَّلة بمجرد الحفظ. لا حاجة لإعادة النشر. + + + +## الأتمتات المُفعَّلة + +انقر على **Engaged N automations** في أي بطاقة قاعدة لرؤية أي عمليات النشر تطابقها القاعدة حالياً بالضبط، إلى جانب آخر تنفيذ لكل منها. + + + ![مودال الأتمتات المُفعَّلة](/images/enterprise/acp-rules-engaged-modal.png) + + +هذه هي أسرع طريقة للتحقق من نطاق قاعدة قبل تمكينها — على سبيل المثال، للتأكد من أن قاعدة محدَّدة بنطاق وسم `production` لا تطابق عن طريق الخطأ deployment تجريبي. + +## قواعد على مستوى المؤسسة مقابل إعدادات لكل deployment + +يمكن ضبط PII Redaction في مكانين: + +- **لكل deployment** — ضمن **Settings → PII Protection** على كل deployment على حدة ([الدليل](/ar/enterprise/features/pii-trace-redactions)) +- **على مستوى المؤسسة** — كقاعدة في هذه الصفحة + +عندما يتطابق نطاق قاعدة مُفعَّلة على مستوى المؤسسة مع deployment، يُجاوز تكوين الكيانات الخاص بالقاعدة **إعدادات PII المملوكة من قبل الـ deployment** لعمليات تنفيذ ذلك الـ deployment — تصبح القاعدة المصدر الوحيد للحقيقة طالما هي مرتبطة. عطّل القاعدة أو فُكَّ ارتباطها (أو غيِّر نطاقها بحيث لا تتطابق بعد الآن) ويعود الـ deployment إلى إعدادات PII Protection الخاصة به. + +فضّل القواعد على مستوى المؤسسة عندما تريد فرض سياسة متسقة عبر العديد من عمليات النشر؛ احتفظ بالضبط لكل deployment للاستثناءات الفردية. + +## ذو صلة + + + + ما هو ACP، المتطلبات، مستويات الخطط، و RBAC. + + + راقب الأتمتات واستهلاك LLM عبر أسطولك. + + + كتالوج الكيانات، recognizers المخصصة، والضبط لكل deployment. + + + أدِر من يمكنه إنشاء أو تعديل القواعد. + + + + + تواصل مع فريق الدعم للمساعدة في تصميم قواعد لمؤسستك. + diff --git a/docs/v1.15.1/ar/enterprise/features/agent-repositories.mdx b/docs/v1.15.1/ar/enterprise/features/agent-repositories.mdx new file mode 100644 index 000000000..ff8e9e5db --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/agent-repositories.mdx @@ -0,0 +1,155 @@ +--- +title: 'مستودعات الوكلاء' +description: 'تعرّف على كيفية استخدام مستودعات الوكلاء لمشاركة وإعادة استخدام وكلائك عبر الفرق والمشاريع' +icon: 'people-group' +mode: "wide" +--- + +تتيح مستودعات الوكلاء لمستخدمي المؤسسات تخزين ومشاركة وإعادة استخدام تعريفات الوكلاء عبر الفرق والمشاريع. تُمكّن هذه الميزة المؤسسات من الاحتفاظ بمكتبة مركزية من الوكلاء الموحدين، مما يعزز الاتساق ويقلل من ازدواجية الجهود. + + + ![Agent Repositories](/images/enterprise/agent-repositories.png) + + +## فوائد مستودعات الوكلاء + +- **التوحيد**: الحفاظ على تعريفات وكلاء متسقة عبر مؤسستك +- **إعادة الاستخدام**: إنشاء وكيل مرة واحدة واستخدامه في أطقم ومشاريع متعددة +- **الحوكمة**: تطبيق سياسات على مستوى المؤسسة لتهيئات الوكلاء +- **التعاون**: تمكين الفرق من المشاركة والبناء على عمل بعضهم البعض + +## إنشاء واستخدام مستودعات الوكلاء + +1. يجب أن يكون لديك حساب في CrewAI، جرّب [الخطة المجانية](https://app.crewai.com). +2. أنشئ وكلاء بأدوار وأهداف محددة لسير عملك. +3. هيّئ الأدوات والقدرات لكل مساعد متخصص. +4. انشر الوكلاء عبر المشاريع من خلال الواجهة المرئية أو تكامل API. + + + ![Agent Repositories](/images/enterprise/create-agent-repository.png) + + + +### تحميل الوكلاء من المستودعات + +يمكنك تحميل الوكلاء من المستودعات في الكود باستخدام معامل `from_repository` للتشغيل محليًا: + +```python +from crewai import Agent + +# إنشاء وكيل بتحميله من مستودع +# يتم تحميل الوكيل بجميع إعداداته المحددة مسبقًا +researcher = Agent( + from_repository="market-research-agent" +) +``` + +### تجاوز إعدادات المستودع + +يمكنك تجاوز إعدادات محددة من المستودع بتوفيرها في التهيئة: + +```python +researcher = Agent( + from_repository="market-research-agent", + goal="Research the latest trends in AI development", # تجاوز هدف المستودع + verbose=True # إضافة إعداد غير موجود في المستودع +) +``` + +### مثال: إنشاء طاقم مع وكلاء المستودع + +```python +from crewai import Crew, Agent, Task + +# تحميل الوكلاء من المستودعات +researcher = Agent( + from_repository="market-research-agent" +) + +writer = Agent( + from_repository="content-writer-agent" +) + +# إنشاء المهام +research_task = Task( + description="Research the latest trends in AI", + agent=researcher +) + +writing_task = Task( + description="Write a comprehensive report based on the research", + agent=writer +) + +# إنشاء الطاقم +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +# تشغيل الطاقم +result = crew.kickoff() +``` + +### مثال: استخدام `kickoff()` مع وكلاء المستودع + +يمكنك أيضًا استخدام وكلاء المستودع مباشرة مع طريقة `kickoff()` للتفاعلات الأبسط: + +```python +from crewai import Agent +from pydantic import BaseModel +from typing import List + +# تعريف تنسيق مخرجات منظم +class MarketAnalysis(BaseModel): + key_trends: List[str] + opportunities: List[str] + recommendation: str + +# تحميل وكيل من المستودع +analyst = Agent( + from_repository="market-analyst-agent", + verbose=True +) + +# الحصول على استجابة حرة +result = analyst.kickoff("Analyze the AI market in 2025") +print(result.raw) # الوصول إلى الاستجابة الخام + +# الحصول على مخرجات منظمة +structured_result = analyst.kickoff( + "Provide a structured analysis of the AI market in 2025", + response_format=MarketAnalysis +) + +# الوصول إلى البيانات المنظمة +print(f"Key Trends: {structured_result.pydantic.key_trends}") +print(f"Recommendation: {structured_result.pydantic.recommendation}") +``` + +## أفضل الممارسات + +1. **اصطلاح التسمية**: استخدم أسماء واضحة ووصفية لوكلاء المستودع +2. **التوثيق**: أدرج أوصافًا شاملة لكل وكيل +3. **إدارة الأدوات**: تأكد من توفر الأدوات المشار إليها بواسطة وكلاء المستودع في بيئتك +4. **التحكم في الوصول**: أدر الصلاحيات لضمان أن أعضاء الفريق المصرّح لهم فقط يمكنهم تعديل وكلاء المستودع + +## إدارة المؤسسة + +للتبديل بين المؤسسات أو عرض مؤسستك الحالية، استخدم واجهة سطر أوامر CrewAI: + +```bash +# عرض المؤسسة الحالية +crewai org current + +# التبديل إلى مؤسسة مختلفة +crewai org switch + +# عرض جميع المؤسسات المتاحة +crewai org list +``` + + +عند تحميل الوكلاء من المستودعات، يجب أن تكون مصادقًا ومتحولًا إلى المؤسسة الصحيحة. إذا تلقيت أخطاء، تحقق من حالة المصادقة وإعدادات المؤسسة باستخدام أوامر CLI أعلاه. + diff --git a/docs/v1.15.1/ar/enterprise/features/automations.mdx b/docs/v1.15.1/ar/enterprise/features/automations.mdx new file mode 100644 index 000000000..8f5ed5fa7 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/automations.mdx @@ -0,0 +1,104 @@ +--- +title: الأتمتة +description: "إدارة ونشر ومراقبة أطقمك المباشرة (الأتمتة) في مكان واحد." +icon: "rocket" +mode: "wide" +--- + +## نظرة عامة + +الأتمتة هي مركز العمليات المباشرة لأطقمك المنشورة. استخدمها للنشر من GitHub أو ملف ZIP، وإدارة متغيرات البيئة، وإعادة النشر عند الحاجة، ومراقبة حالة كل أتمتة. + + + ![Automations Overview](/images/enterprise/automations-overview.png) + + + +## طرق النشر + +### النشر من GitHub + +استخدم هذا للمشاريع ذات التحكم في الإصدارات والنشر المستمر. + + + + انقر على Configure GitHub وصرّح بالوصول. + + + اختر المستودع والفرع الذي تريد النشر منه. + + + فعّل النشر التلقائي للالتزامات الجديدة لإرسال التحديثات مع كل دفع. + + + أضف المتغيرات السرية فرديًا أو استخدم العرض الجماعي لمتغيرات متعددة. + + + انقر على Deploy لإنشاء الأتمتة المباشرة. + + + + + ![GitHub Deployment](/images/enterprise/deploy-from-github.png) + + +### النشر من ZIP + +انشر بسرعة بدون Git — ارفع حزمة مضغوطة من مشروعك. + + + + اختر أرشيف ZIP من جهازك. + + + وفّر أي متغيرات أو مفاتيح مطلوبة. + + + انقر على Deploy لإنشاء الأتمتة المباشرة. + + + + + ![ZIP Deployment](/images/enterprise/deploy-from-zip.png) + + +## لوحة تحكم الأتمتة + +يعرض الجدول جميع الأتمتة المباشرة مع التفاصيل الرئيسية: + +- **CREW**: اسم الأتمتة +- **STATUS**: متصل / فشل / قيد التنفيذ +- **URL**: نقطة نهاية التشغيل/الحالة +- **TOKEN**: رمز الأتمتة +- **ACTIONS**: إعادة النشر، الحذف، والمزيد + +استخدم عناصر التحكم في أعلى اليمين للتصفية والبحث: + +- البحث بالاسم +- التصفية حسب الحالة +- التصفية حسب المصدر (GitHub / Studio / ZIP) + +بعد النشر، يمكنك عرض تفاصيل الأتمتة واستخدام القائمة المنسدلة **الخيارات** لـ `الدردشة مع هذا الطاقم`، `تصدير مكون React` و`التصدير كـ MCP`. + + + ![Automations Table](/images/enterprise/automations-table.png) + + +## أفضل الممارسات + +- فضّل نشر GitHub للتحكم في الإصدارات وCI/CD +- استخدم إعادة النشر للتقدم بعد تحديثات الكود أو التهيئة أو اضبطه على النشر التلقائي مع كل دفع + +## ذات صلة + + + + انشر طاقمًا من GitHub أو ملف ZIP. + + + شغّل الأتمتة عبر webhooks أو API. + + + بث الأحداث والتحديثات في الوقت الفعلي إلى أنظمتك. + + diff --git a/docs/v1.15.1/ar/enterprise/features/crew-studio.mdx b/docs/v1.15.1/ar/enterprise/features/crew-studio.mdx new file mode 100644 index 000000000..ab945ba31 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/crew-studio.mdx @@ -0,0 +1,88 @@ +--- +title: استوديو الطاقم +description: "إنشاء أتمتة جديدة بمساعدة الذكاء الاصطناعي ومحرر مرئي واختبار متكامل." +icon: "pencil" +mode: "wide" +--- + +## نظرة عامة + +استوديو الطاقم هو مساحة عمل تفاعلية بمساعدة الذكاء الاصطناعي لإنشاء أتمتة جديدة من الصفر باستخدام اللغة الطبيعية ومحرر سير عمل مرئي. + + + ![Crew Studio Overview](/images/enterprise/crew-studio-overview.png) + + +## الإنشاء المبني على الأوامر النصية + +- صِف الأتمتة التي تريدها؛ يقوم الذكاء الاصطناعي بإنشاء الوكلاء والمهام والأدوات. +- استخدم الإدخال الصوتي عبر أيقونة الميكروفون إذا فضّلت ذلك. +- ابدأ من أوامر مدمجة لحالات الاستخدام الشائعة. + + + ![Prompt Builder](/images/enterprise/crew-studio-prompt.png) + + +## المحرر المرئي + +يعكس اللوح سير العمل كعُقد وأسهم مع ثلاث لوحات داعمة تتيح لك تهيئة سير العمل بسهولة بدون كتابة كود؛ ما يُعرف بـ "**البرمجة الحدسية لوكلاء الذكاء الاصطناعي**". + +يمكنك استخدام وظيفة السحب والإفلات لإضافة الوكلاء والمهام والأدوات إلى اللوح أو استخدام قسم الدردشة لبناء الوكلاء. يتشارك كلا النهجين الحالة ويمكن استخدامهما بالتبادل. + +- **أفكار AI (يسار)**: الاستدلال المتدفق أثناء تصميم سير العمل +- **اللوح (المركز)**: الوكلاء والمهام كعقد متصلة +- **الموارد (يمين)**: مكونات السحب والإفلات (وكلاء، مهام، أدوات) + + + ![Visual Canvas](/images/enterprise/crew-studio-canvas.png) + + +## التنفيذ والتصحيح + +انتقل إلى عرض التنفيذ لتشغيل سير العمل ومراقبته: + +- الجدول الزمني للأحداث +- سجلات مفصلة (التفاصيل، الرسائل، البيانات الخام) +- اختبارات محلية قبل النشر + + + ![Execution View](/images/enterprise/crew-studio-execution.png) + + +## النشر والتصدير + +- انشر لنشر أتمتة مباشرة +- حمّل المصدر كملف ZIP للتطوير المحلي أو التخصيص + + + ![Publish & Download](/images/enterprise/crew-studio-publish.png) + + +بعد النشر، يمكنك عرض تفاصيل الأتمتة واستخدام القائمة المنسدلة **الخيارات** لـ `الدردشة مع هذا الطاقم`، `تصدير مكون React` و`التصدير كـ MCP`. + + + ![Published Automation](/images/enterprise/crew-studio-published.png) + + +## أفضل الممارسات + +- كرر بسرعة في الاستوديو؛ انشر فقط عندما يكون مستقرًا +- اقصر الأدوات على الحد الأدنى من الصلاحيات المطلوبة +- استخدم التتبعات للتحقق من السلوك والأداء + +## ذات صلة + + + + تفعيل استوديو الطاقم. + + + بناء طاقم. + + + نشر طاقم من GitHub أو ملف ZIP. + + + تصدير مكون React. + + diff --git a/docs/v1.15.1/ar/enterprise/features/flow-hitl-management.mdx b/docs/v1.15.1/ar/enterprise/features/flow-hitl-management.mdx new file mode 100644 index 000000000..6b4096abf --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/flow-hitl-management.mdx @@ -0,0 +1,558 @@ +--- +title: "إدارة HITL للتدفقات" +description: "مراجعة بشرية بمستوى المؤسسات للتدفقات مع إشعارات البريد الإلكتروني أولاً وقواعد التوجيه وإمكانيات الاستجابة التلقائية" +icon: "users-gear" +mode: "wide" +--- + + +تتطلب ميزات إدارة Flow HITL مزيّن `@human_feedback`، المتاح في **CrewAI الإصدار 1.8.0 أو أحدث**. تنطبق هذه الميزات تحديدًا على **التدفقات (Flows)**، وليس الأطقم (Crews). + + +يوفر CrewAI Enterprise نظامًا شاملًا لإدارة الإنسان في الحلقة (HITL) للتدفقات يحوّل سير عمل الذكاء الاصطناعي إلى عمليات تعاونية بين الإنسان والذكاء الاصطناعي. تستخدم المنصة **بنية البريد الإلكتروني أولاً** التي تمكّن أي شخص لديه عنوان بريد إلكتروني من الرد على طلبات المراجعة — بدون الحاجة لحساب على المنصة. + +## نظرة عامة + + + + يمكن للمستجيبين الرد مباشرة على رسائل الإشعار لتقديم الملاحظات + + + توجيه الطلبات إلى بريد إلكتروني محدد بناءً على أنماط الطرق أو حالة التدفق + + + تهيئة استجابات احتياطية تلقائية عندما لا يرد أي شخص في الوقت المحدد + + + +### الفوائد الرئيسية + +- **نموذج ذهني بسيط**: عناوين البريد الإلكتروني عالمية؛ لا حاجة لإدارة مستخدمين أو أدوار المنصة +- **مستجيبون خارجيون**: يمكن لأي شخص لديه بريد إلكتروني الرد، حتى غير مستخدمي المنصة +- **تعيين ديناميكي**: سحب بريد المعيّن مباشرة من حالة التدفق (مثل `sales_rep_email`) +- **تهيئة مخفضة**: إعدادات أقل للتهيئة، وقت أسرع للقيمة +- **البريد الإلكتروني كقناة رئيسية**: يفضل معظم المستخدمين الرد عبر البريد الإلكتروني بدلاً من تسجيل الدخول إلى لوحة التحكم + +## إعداد نقاط المراجعة البشرية في التدفقات + +هيّئ نقاط تفتيش المراجعة البشرية داخل تدفقاتك باستخدام مزيّن `@human_feedback`. عندما يصل التنفيذ إلى نقطة مراجعة، يتوقف النظام ويُخطر المعيّن عبر البريد الإلكتروني وينتظر الاستجابة. + +```python +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ContentApprovalFlow(Flow): + @start() + def generate_content(self): + return "Generated marketing copy for Q1 campaign..." + + @human_feedback( + message="Please review this content for brand compliance:", + emit=["approved", "rejected", "needs_revision"], + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Marketing copy for review..." + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + print(f"Publishing approved content. Reviewer notes: {result.feedback}") + + @listen("rejected") + def archive_content(self, result: HumanFeedbackResult): + print(f"Content rejected. Reason: {result.feedback}") +``` + +للحصول على تفاصيل التنفيذ الكاملة، راجع دليل [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows). + +### معاملات المزيّن + +| المعامل | النوع | الوصف | +|-----------|------|-------------| +| `message` | `str` | الرسالة المعروضة للمراجع البشري | +| `emit` | `list[str]` | خيارات الاستجابة الصالحة (تُعرض كأزرار في الواجهة) | + +## تهيئة المنصة + +الوصول إلى تهيئة HITL من: **النشر** ← **الإعدادات** ← **تهيئة الإنسان في الحلقة** + + + HITL Configuration Settings + + +### إشعارات البريد الإلكتروني + +تبديل لتفعيل أو تعطيل إشعارات البريد الإلكتروني لطلبات HITL. + +| الإعداد | الافتراضي | الوصف | +|---------|---------|-------------| +| إشعارات البريد الإلكتروني | مفعّل | إرسال رسائل عند طلب الملاحظات | + + +عند التعطيل، يجب على المستجيبين استخدام واجهة لوحة التحكم أو يجب تهيئة webhooks لأنظمة إشعارات مخصصة. + + +### هدف SLA + +تعيين وقت استجابة مستهدف لأغراض التتبع والمقاييس. + +| الإعداد | الوصف | +|---------|-------------| +| هدف SLA (دقائق) | وقت الاستجابة المستهدف. يُستخدم لمقاييس لوحة التحكم وتتبع SLA | + +اتركه فارغًا لتعطيل تتبع SLA. + +## إشعارات واستجابات البريد الإلكتروني + +يستخدم نظام HITL بنية البريد الإلكتروني أولاً حيث يمكن للمستجيبين الرد مباشرة على رسائل الإشعار. + +### كيف تعمل استجابات البريد الإلكتروني + + + + عند إنشاء طلب HITL، يُرسل بريد إلكتروني إلى المستجيب المعيّن مع محتوى المراجعة والسياق. + + + يتضمن البريد عنوان رد خاص مع رمز موقّع للمصادقة. + + + يرد المستجيب ببساطة على البريد بملاحظاته — بدون حاجة لتسجيل الدخول. + + + تستقبل المنصة الرد، وتتحقق من الرمز الموقّع، وتطابق بريد المرسل. + + + تُسجل الملاحظات ويستمر التدفق مع مدخلات الإنسان. + + + +### تنسيق الاستجابة + +يمكن للمستجيبين الرد بـ: + +- **خيار emit**: إذا تطابق الرد مع خيار `emit` (مثل "approved")، يُستخدم مباشرة +- **نص حر**: أي نص استجابة يُمرر إلى التدفق كملاحظات +- **نص عادي**: يُستخدم السطر الأول من نص الرد كملاحظات + +### رسائل التأكيد + +بعد معالجة الرد، يستلم المستجيب رسالة تأكيد تشير إلى ما إذا تم إرسال الملاحظات بنجاح أو حدث خطأ. + +### أمان رمز البريد + +- الرموز موقّعة تشفيريًا للأمان +- تنتهي صلاحية الرموز بعد 7 أيام +- يجب أن يتطابق بريد المرسل مع البريد المصرّح به في الرمز +- تُرسل رسائل تأكيد/خطأ بعد المعالجة + +## قواعد التوجيه + +توجيه طلبات HITL إلى عناوين بريد إلكتروني محددة بناءً على أنماط الطرق. + + + HITL Routing Rules Configuration + + +### هيكل القاعدة + +```json +{ + "name": "Approvals to Finance", + "match": { + "method_name": "approve_*" + }, + "assign_to_email": "finance@company.com", + "assign_from_input": "manager_email" +} +``` + +### أنماط المطابقة + +| النمط | الوصف | مثال المطابقة | +|---------|-------------|---------------| +| `approve_*` | حرف بدل (أي أحرف) | `approve_payment`، `approve_vendor` | +| `review_?` | حرف واحد | `review_a`، `review_1` | +| `validate_payment` | مطابقة تامة | `validate_payment` فقط | + +### أولوية التعيين + +1. **تعيين ديناميكي** (`assign_from_input`): إذا تم تهيئته، يسحب البريد من حالة التدفق +2. **بريد ثابت** (`assign_to_email`): يرجع إلى البريد المهيأ +3. **منشئ النشر**: إذا لم تتطابق أي قاعدة، يُستخدم بريد منشئ النشر + +### مثال التعيين الديناميكي + +إذا كانت حالة تدفقك تحتوي على `{"sales_rep_email": "alice@company.com"}`، هيّئ: + +```json +{ + "name": "Route to Sales Rep", + "match": { + "method_name": "review_*" + }, + "assign_from_input": "sales_rep_email" +} +``` + +سيتم تعيين الطلب إلى `alice@company.com` تلقائيًا. + + +**حالة استخدام**: اسحب المعيّن من CRM أو قاعدة البيانات أو خطوة تدفق سابقة لتوجيه المراجعات ديناميكيًا إلى الشخص المناسب. + + +## الاستجابة التلقائية + +الاستجابة تلقائيًا لطلبات HITL إذا لم يستجب أي شخص خلال المهلة المحددة. يضمن هذا عدم تعليق التدفقات إلى أجل غير مسمى. + +### التهيئة + +| الإعداد | الوصف | +|---------|-------------| +| مفعّل | تبديل لتفعيل الاستجابة التلقائية | +| المهلة (دقائق) | الوقت المنتظر قبل الاستجابة التلقائية | +| النتيجة الافتراضية | قيمة الاستجابة (يجب أن تطابق خيار `emit`) | + + + HITL Auto-Response Configuration + + +### حالات الاستخدام + +- **الامتثال لـ SLA**: ضمان عدم تعليق التدفقات إلى أجل غير مسمى +- **الموافقة الافتراضية**: الموافقة التلقائية على الطلبات منخفضة المخاطر بعد انتهاء المهلة +- **التراجع السلس**: المتابعة بافتراضي آمن عندما يكون المراجعون غير متاحين + + +استخدم الاستجابة التلقائية بحذر. فعّلها فقط للمراجعات غير الحرجة حيث تكون الاستجابة الافتراضية مقبولة. + + +## عملية المراجعة + +### واجهة لوحة التحكم + +توفر واجهة مراجعة HITL تجربة نظيفة ومركّزة للمراجعين: + +- **عرض Markdown**: تنسيق غني لمحتوى المراجعة مع تمييز الصيغة +- **لوحة السياق**: عرض حالة التدفق وتاريخ التنفيذ والمعلومات ذات الصلة +- **إدخال الملاحظات**: تقديم ملاحظات وتعليقات مفصلة مع قرارك +- **إجراءات سريعة**: أزرار خيارات emit بنقرة واحدة مع تعليقات اختيارية + + + HITL Pending Requests List + + +### طرق الاستجابة + +يمكن للمراجعين الاستجابة عبر ثلاث قنوات: + +| الطريقة | الوصف | +|--------|-------------| +| **الرد عبر البريد** | الرد مباشرة على رسالة الإشعار | +| **لوحة التحكم** | استخدام واجهة لوحة تحكم المؤسسة | +| **API/Webhook** | استجابة برمجية عبر API | + +### السجل ومسار التدقيق + +يتم تتبع كل تفاعل HITL بجدول زمني كامل: + +- سجل القرارات (موافقة/رفض/مراجعة) +- هوية المراجع والطابع الزمني +- الملاحظات والتعليقات المقدمة +- طريقة الاستجابة (بريد/لوحة تحكم/API) +- مقاييس وقت الاستجابة + +## التحليلات والمراقبة + +تتبع أداء HITL مع تحليلات شاملة. + +### لوحة تحكم الأداء + + + HITL Metrics Dashboard + + + + + مراقبة متوسط وميديان أوقات الاستجابة حسب المراجع أو التدفق. + + + تحليل أنماط حجم المراجعة لتحسين قدرة الفريق. + + + عرض معدلات الموافقة/الرفض عبر أنواع المراجعة المختلفة. + + + تتبع نسبة المراجعات المكتملة ضمن أهداف SLA. + + + +### التدقيق والامتثال + +إمكانيات تدقيق جاهزة للمؤسسات للمتطلبات التنظيمية: + +- سجل قرارات كامل مع الطوابع الزمنية +- التحقق من هوية المراجع +- سجلات تدقيق غير قابلة للتغيير +- إمكانيات التصدير لتقارير الامتثال + +## حالات الاستخدام الشائعة + + + + **حالة الاستخدام**: أتمتة استبيانات الأمان الداخلية مع التحقق البشري + + - يولّد الذكاء الاصطناعي الردود على الاستبيانات الأمنية + - يراجع فريق الأمن ويتحقق من الدقة عبر البريد الإلكتروني + - يتم تجميع الردود المعتمدة في التقديم النهائي + - مسار تدقيق كامل للامتثال + + + + **حالة الاستخدام**: محتوى تسويقي يتطلب مراجعة قانونية/العلامة التجارية + + - يولّد الذكاء الاصطناعي نصوص تسويقية أو محتوى وسائل التواصل + - التوجيه إلى بريد فريق العلامة التجارية لمراجعة النبرة/الأسلوب + - النشر التلقائي عند الموافقة + + + + **حالة الاستخدام**: تقارير النفقات، شروط العقود، تخصيصات الميزانية + + - يعالج الذكاء الاصطناعي مسبقًا ويصنف الطلبات المالية + - التوجيه بناءً على عتبات المبالغ باستخدام التعيين الديناميكي + - الحفاظ على مسار تدقيق كامل للامتثال المالي + + + + **حالة الاستخدام**: توجيه المراجعات إلى مالكي الحسابات من CRM + + - يجلب التدفق بريد مالك الحساب من CRM + - تخزين البريد في حالة التدفق (مثل `account_owner_email`) + - استخدام `assign_from_input` للتوجيه إلى الشخص المناسب تلقائيًا + + + + **حالة الاستخدام**: التحقق من مخرجات الذكاء الاصطناعي قبل التسليم للعميل + + - يولّد الذكاء الاصطناعي محتوى أو ردود موجهة للعميل + - يراجع فريق ضمان الجودة عبر إشعار البريد الإلكتروني + - حلقات الملاحظات تحسّن أداء الذكاء الاصطناعي بمرور الوقت + + + +## واجهة Webhooks API + +عندما تتوقف تدفقاتك للملاحظات البشرية، يمكنك تهيئة webhooks لإرسال بيانات الطلب إلى تطبيقك. يتيح هذا: + +- بناء واجهات موافقة مخصصة +- التكامل مع الأدوات الداخلية (Jira، ServiceNow، لوحات تحكم مخصصة) +- توجيه الموافقات إلى أنظمة طرف ثالث +- إشعارات تطبيقات الجوال +- أنظمة القرار المؤتمتة + + + HITL Webhook Configuration + + +### تهيئة Webhooks + + + + اذهب إلى **النشر** ← **الإعدادات** ← **الإنسان في الحلقة** + + + انقر لتوسيع تهيئة **Webhooks** + + + أدخل عنوان webhook الخاص بك (يجب أن يكون HTTPS في الإنتاج) + + + انقر على **حفظ التهيئة** للتفعيل + + + +يمكنك تهيئة webhooks متعددة. يستقبل كل webhook نشط جميع أحداث HITL. + +### أحداث Webhook + +ستستقبل نقطة النهاية طلبات HTTP POST لهذه الأحداث: + +| نوع الحدث | متى يُطلق | +|------------|----------------| +| `new_request` | يتوقف تدفق ويطلب ملاحظات بشرية | + +### حمولة Webhook + +تستقبل جميع webhooks حمولة JSON بهذا الهيكل: + +```json +{ + "event": "new_request", + "request": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "flow_id": "flow_abc123", + "method_name": "review_article", + "message": "Please review this article for publication.", + "emit_options": ["approved", "rejected", "request_changes"], + "state": { + "article_id": 12345, + "author": "john@example.com", + "category": "technology" + }, + "metadata": {}, + "created_at": "2026-01-14T12:00:00Z" + }, + "deployment": { + "id": 456, + "name": "Content Review Flow", + "organization_id": 789 + }, + "callback_url": "https://api.crewai.com/...", + "assigned_to_email": "reviewer@company.com" +} +``` + +### الرد على الطلبات + +لإرسال الملاحظات، **أرسل POST إلى `callback_url`** المضمّن في حمولة webhook. + +```http +POST {callback_url} +Content-Type: application/json + +{ + "feedback": "Approved. Great article!", + "source": "my_custom_app" +} +``` + +### الأمان + + +جميع طلبات webhook موقّعة تشفيريًا باستخدام HMAC-SHA256 لضمان الأصالة ومنع التلاعب. + + +#### أمان Webhook + +- **توقيعات HMAC-SHA256**: يتضمن كل webhook توقيعًا تشفيريًا +- **أسرار لكل webhook**: لكل webhook سر توقيع فريد +- **مشفرة أثناء التخزين**: أسرار التوقيع مشفرة في قاعدة البيانات +- **التحقق من الطابع الزمني**: يمنع هجمات الإعادة + +#### ترويسات التوقيع + +يتضمن كل طلب webhook هذه الترويسات: + +| الترويسة | الوصف | +|--------|-------------| +| `X-Signature` | توقيع HMAC-SHA256: `sha256=` | +| `X-Timestamp` | الطابع الزمني Unix عند توقيع الطلب | + +#### التحقق + +تحقق بحساب: + +```python +import hmac +import hashlib + +expected = hmac.new( + signing_secret.encode(), + f"{timestamp}.{payload}".encode(), + hashlib.sha256 +).hexdigest() + +if hmac.compare_digest(expected, signature): + # توقيع صالح +``` + +### معالجة الأخطاء + +يجب أن تعيد نقطة نهاية webhook كود حالة 2xx لتأكيد الاستلام: + +| استجابتك | سلوكنا | +|---------------|--------------| +| 2xx | تم تسليم Webhook بنجاح | +| 4xx/5xx | مسجل كفشل، بدون إعادة محاولة | +| مهلة (30 ثانية) | مسجل كفشل، بدون إعادة محاولة | + +## الأمان والتحكم في الوصول المبني على الأدوار + +### الوصول إلى لوحة التحكم + +يُتحكم في وصول HITL على مستوى النشر: + +| الصلاحية | القدرة | +|------------|------------| +| `manage_human_feedback` | تهيئة إعدادات HITL، عرض جميع الطلبات | +| `respond_to_human_feedback` | الرد على الطلبات، عرض الطلبات المعيّنة | + +### تصريح استجابة البريد الإلكتروني + +للردود عبر البريد: +1. يشفّر رمز الرد البريد المصرّح به +2. يجب أن يتطابق بريد المرسل مع بريد الرمز +3. يجب ألا يكون الرمز منتهي الصلاحية (7 أيام افتراضيًا) +4. يجب أن يكون الطلب لا يزال معلقًا + +### مسار التدقيق + +يتم تسجيل جميع إجراءات HITL: +- إنشاء الطلب +- تغييرات التعيين +- إرسال الاستجابة (مع المصدر: لوحة تحكم/بريد/API) +- حالة استئناف التدفق + +## استكشاف الأخطاء وإصلاحها + +### عدم إرسال الرسائل + +1. تحقق من تفعيل "إشعارات البريد الإلكتروني" في التهيئة +2. تحقق من مطابقة قواعد التوجيه لاسم الطريقة +3. تحقق من صلاحية بريد المعيّن +4. تحقق من احتياطي منشئ النشر إذا لم تتطابق أي قواعد توجيه + +### عدم معالجة ردود البريد + +1. تحقق من عدم انتهاء صلاحية الرمز (7 أيام افتراضيًا) +2. تحقق من مطابقة بريد المرسل للبريد المعيّن +3. تأكد من أن الطلب لا يزال معلقًا (لم يتم الرد عليه بعد) + +### عدم استئناف التدفق + +1. تحقق من حالة الطلب في لوحة التحكم +2. تحقق من إمكانية الوصول إلى callback URL +3. تأكد من أن النشر لا يزال قيد التشغيل + +## أفضل الممارسات + + +**ابدأ ببساطة**: ابدأ بإشعارات البريد الإلكتروني لمنشئ النشر، ثم أضف قواعد التوجيه مع نضوج سير عملك. + + +1. **استخدم التعيين الديناميكي**: اسحب عناوين بريد المعيّنين من حالة التدفق للتوجيه المرن. + +2. **هيّئ الاستجابة التلقائية**: أعد استجابة احتياطية للمراجعات غير الحرجة لمنع تعليق التدفقات. + +3. **راقب أوقات الاستجابة**: استخدم التحليلات لتحديد الاختناقات وتحسين عملية المراجعة. + +4. **اجعل رسائل المراجعة واضحة**: اكتب رسائل واضحة وقابلة للتنفيذ في مزيّن `@human_feedback`. + +5. **اختبر تدفق البريد**: أرسل طلبات اختبار للتحقق من تسليم البريد قبل الانتقال للإنتاج. + +## الموارد ذات الصلة + + + + دليل التنفيذ لمزيّن `@human_feedback` + + + دليل خطوة بخطوة لإعداد سير عمل HITL + + + تهيئة التحكم في الوصول المبني على الأدوار لمؤسستك + + + إعداد إشعارات الأحداث في الوقت الفعلي + + diff --git a/docs/v1.15.1/ar/enterprise/features/hallucination-guardrail.mdx b/docs/v1.15.1/ar/enterprise/features/hallucination-guardrail.mdx new file mode 100644 index 000000000..7ab41ef84 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/hallucination-guardrail.mdx @@ -0,0 +1,251 @@ +--- +title: حاجز الهلوسة +description: "منع واكتشاف هلوسات الذكاء الاصطناعي في مهام CrewAI" +icon: "shield-check" +mode: "wide" +--- + +## نظرة عامة + +حاجز الهلوسة هو ميزة مؤسسية تتحقق من المحتوى المولّد بالذكاء الاصطناعي لضمان أنه مبني على الحقائق ولا يحتوي على هلوسات. يحلل مخرجات المهام مقابل سياق مرجعي ويوفر ملاحظات مفصلة عند اكتشاف محتوى محتمل الهلوسة. + +## ما هي الهلوسات؟ + +تحدث هلوسات الذكاء الاصطناعي عندما تولّد نماذج اللغة محتوى يبدو معقولاً لكنه غير صحيح من الناحية الواقعية أو غير مدعوم بالسياق المقدم. يساعد حاجز الهلوسة في منع هذه المشكلات من خلال: + +- مقارنة المخرجات مع السياق المرجعي +- تقييم الأمانة للمادة المصدرية +- توفير ملاحظات مفصلة حول المحتوى المشكل +- دعم عتبات مخصصة لصرامة التحقق + +## الاستخدام الأساسي + +### إعداد الحاجز + +```python +from crewai.tasks.hallucination_guardrail import HallucinationGuardrail +from crewai import LLM + +# الاستخدام الأساسي - سيستخدم expected_output للمهمة كسياق +guardrail = HallucinationGuardrail( + llm=LLM(model="gpt-4o-mini") +) + +# مع سياق مرجعي صريح +context_guardrail = HallucinationGuardrail( + context="AI helps with various tasks including analysis and generation.", + llm=LLM(model="gpt-4o-mini") +) +``` + +### الإضافة إلى المهام + +```python +from crewai import Task + +# إنشاء مهمتك مع الحاجز +task = Task( + description="Write a summary about AI capabilities", + expected_output="A factual summary based on the provided context", + agent=my_agent, + guardrail=guardrail # إضافة الحاجز للتحقق من المخرجات +) +``` + +## التهيئة المتقدمة + +### التحقق بعتبة مخصصة + +للتحقق الأكثر صرامة، يمكنك تعيين عتبة أمانة مخصصة (مقياس 0-10): + +```python +# حاجز صارم يتطلب درجة أمانة عالية +strict_guardrail = HallucinationGuardrail( + context="Quantum computing uses qubits that exist in superposition states.", + llm=LLM(model="gpt-4o-mini"), + threshold=8.0 # يتطلب درجة >= 8 لاجتياز التحقق +) +``` + +### تضمين سياق استجابة الأدوات + +عندما تستخدم مهمتك أدوات، يمكنك تضمين استجابات الأدوات لتحقق أكثر دقة: + +```python +# حاجز مع سياق استجابة الأدوات +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" +) +``` + +## كيف يعمل + +### عملية التحقق + +1. **تحليل السياق**: يقارن الحاجز مخرجات المهمة مع السياق المرجعي المقدم +2. **تسجيل الأمانة**: يستخدم مقيّمًا داخليًا لتعيين درجة أمانة (0-10) +3. **تحديد الحكم**: يحدد ما إذا كان المحتوى أمينًا أو يحتوي على هلوسات +4. **التحقق من العتبة**: إذا تم تعيين عتبة مخصصة، يتحقق مقابل تلك الدرجة +5. **توليد الملاحظات**: يوفر أسبابًا مفصلة عند فشل التحقق + +### منطق التحقق + +- **الوضع الافتراضي**: يستخدم التحقق المبني على الحكم (FAITHFUL مقابل HALLUCINATED) +- **وضع العتبة**: يتطلب أن تلبي درجة الأمانة العتبة المحددة أو تتجاوزها +- **معالجة الأخطاء**: يتعامل بسلاسة مع أخطاء التقييم ويوفر ملاحظات إعلامية + +## نتائج الحاجز + +يعيد الحاجز نتائج منظمة تشير إلى حالة التحقق: + +```python +# مثال على هيكل نتيجة الحاجز +{ + "valid": False, + "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context." +} +``` + +### خصائص النتيجة + +- **valid**: قيمة منطقية تشير إلى ما إذا اجتازت المخرجات التحقق +- **feedback**: شرح مفصل عند فشل التحقق، يتضمن: + - درجة الأمانة + - تصنيف الحكم + - أسباب محددة للفشل + +## التكامل مع نظام المهام + +### التحقق التلقائي + +عند إضافة حاجز إلى مهمة، يتحقق تلقائيًا من المخرجات قبل اعتبار المهمة مكتملة: + +```python +# تدفق التحقق من مخرجات المهمة +task_output = agent.execute_task(task) +validation_result = guardrail(task_output) + +if validation_result.valid: + # المهمة تكتمل بنجاح + return task_output +else: + # المهمة تفشل مع ملاحظات التحقق + raise ValidationError(validation_result.feedback) +``` + +### تتبع الأحداث + +يتكامل الحاجز مع نظام أحداث CrewAI لتوفير المراقبة: + +- **بدء التحقق**: عند بدء تقييم الحاجز +- **اكتمال التحقق**: عند انتهاء التقييم بالنتائج +- **فشل التحقق**: عند حدوث أخطاء تقنية أثناء التقييم + +## أفضل الممارسات + +### إرشادات السياق + + + + أدرج جميع المعلومات الواقعية ذات الصلة التي يجب أن يبني عليها الذكاء الاصطناعي مخرجاته: + + ```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. + """ + ``` + + + + أدرج فقط المعلومات المرتبطة مباشرة بالمهمة لتجنب الارتباك: + + ```python + # جيد: سياق مركّز + context = "The current weather in New York is 18°C with light rain." + + # تجنب: معلومات غير ذات صلة + context = "The weather is 18°C. The city has 8 million people. Traffic is heavy." + ``` + + + + تأكد من أن السياق المرجعي يعكس معلومات حالية ودقيقة. + + + +### اختيار العتبة + + + + ابدأ بدون عتبات مخصصة لفهم الأداء الأساسي. + + + + - **محتوى عالي الأهمية**: استخدم عتبة 8-10 للدقة القصوى + - **محتوى عام**: استخدم عتبة 6-7 للتحقق المتوازن + - **محتوى إبداعي**: استخدم عتبة 4-5 أو التحقق الافتراضي المبني على الحكم + + + + تتبع نتائج التحقق واضبط العتبات بناءً على الإيجابيات/السلبيات الكاذبة. + + + +## اعتبارات الأداء + +### التأثير على زمن التنفيذ + +- **عبء التحقق**: يضيف كل حاجز حوالي 1-3 ثوانٍ لكل مهمة +- **كفاءة LLM**: اختر نماذج فعالة للتقييم (مثل gpt-4o-mini) + +### تحسين التكلفة + +- **اختيار النموذج**: استخدم نماذج أصغر وفعالة لتقييم الحاجز +- **حجم السياق**: اجعل السياق المرجعي موجزًا لكن شاملًا +- **التخزين المؤقت**: فكّر في تخزين نتائج التحقق مؤقتًا للمحتوى المتكرر + +## استكشاف الأخطاء وإصلاحها + + + **الأسباب المحتملة:** + - السياق مقيّد جدًا أو غير مرتبط بمخرجات المهمة + - العتبة معينة عالية جدًا لنوع المحتوى + - السياق المرجعي يحتوي على معلومات قديمة + + **الحلول:** + - مراجعة وتحديث السياق ليتطابق مع متطلبات المهمة + - خفض العتبة أو استخدام التحقق الافتراضي المبني على الحكم + - التأكد من أن السياق حالي ودقيق + + + + **الأسباب المحتملة:** + - العتبة عالية جدًا للمهام الإبداعية أو التفسيرية + - السياق لا يغطي جميع الجوانب الصالحة للمخرجات + - نموذج التقييم محافظ بشكل مفرط + + **الحلول:** + - خفض العتبة أو استخدام التحقق الافتراضي + - توسيع السياق ليشمل محتوى مقبول أوسع + - الاختبار مع نماذج تقييم مختلفة + + + + **الأسباب المحتملة:** + - مشكلات في الاتصال بالشبكة + - نموذج LLM غير متاح أو محدود المعدل + - مخرجات مهمة أو سياق غير صالح + + **الحلول:** + - التحقق من الاتصال بالشبكة وحالة خدمة LLM + - تنفيذ منطق إعادة المحاولة للأعطال المؤقتة + - التحقق من تنسيق مخرجات المهمة قبل تقييم الحاجز + + + + تواصل مع فريق الدعم للمساعدة في تهيئة حاجز الهلوسة أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/features/marketplace.mdx b/docs/v1.15.1/ar/enterprise/features/marketplace.mdx new file mode 100644 index 000000000..e8b5b8514 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/marketplace.mdx @@ -0,0 +1,45 @@ +--- +title: السوق +description: "اكتشف وثبّت وأدِر الأصول القابلة لإعادة الاستخدام لطواقم مؤسستك." +icon: "store" +mode: "wide" +--- + +## نظرة عامة + +يوفر السوق واجهة منظمة لاكتشاف عمليات التكامل والأدوات الداخلية والأصول القابلة لإعادة الاستخدام التي تسرّع تطوير الطواقم. + + + ![نظرة عامة على السوق](/images/enterprise/marketplace-overview.png) + + +## قابلية الاكتشاف + +- تصفح حسب الفئة والقدرة +- ابحث عن الأصول بالاسم أو الكلمة المفتاحية + +## التثبيت والتفعيل + +- تثبيت بنقرة واحدة للأصول المعتمدة +- تفعيل أو تعطيل لكل طاقم حسب الحاجة +- تهيئة متغيرات البيئة والنطاقات المطلوبة + + + ![التثبيت والتهيئة](/images/enterprise/marketplace-install.png) + + +يمكنك أيضاً تنزيل القوالب مباشرة من السوق بالنقر على زر `Download` لاستخدامها محلياً أو تعديلها حسب احتياجاتك. + +## ذو صلة + + + + اربط التطبيقات الخارجية وأدِر الأدوات الداخلية التي يمكن لوكلائك استخدامها. + + + انشر وثبّت الأدوات لتعزيز قدرات طواقمك. + + + خزّن وشارك وأعد استخدام تعريفات الوكلاء عبر الفرق والمشاريع. + + diff --git a/docs/v1.15.1/ar/enterprise/features/merged-step-card.mdx b/docs/v1.15.1/ar/enterprise/features/merged-step-card.mdx new file mode 100644 index 000000000..776edfe10 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/merged-step-card.mdx @@ -0,0 +1,82 @@ +--- +title: بطاقة واحدة لكل خطوة +description: "كل خطوة على لوحة Studio هي بطاقة واحدة تجمع بين المهمة والوكيل الذي ينفّذها." +icon: "layer-group" +mode: "wide" +--- + +## نظرة عامة + +على لوحة Studio، تُمثَّل كل خطوة عمل بـ **بطاقة واحدة**. تجمع البطاقة بين عنصرين كانا في السابق في عُقد منفصلة: + +- **المهمة** — ماذا تفعل (الاسم، الوصف، المخرجات المتوقعة، وتنسيق الاستجابة). +- **الوكيل** — من ينفّذها (الوكيل المُعيَّن ونموذجه وأدواته). + +الوكيل ليس مشاركًا مستقلاً في سير العمل لديك — بل هو سمة من سمات المهمة: *أي وكيل ينفّذ هذا العمل.* وضع المهمة والوكيل في بطاقة واحدة يجعل هذه العلاقة واضحة، ويحوّل أتمتتك إلى سلسلة واحدة من وحدات العمل من اليسار إلى اليمين يسهل قراءتها بنظرة واحدة. + + + ![بطاقات الخطوات الموحّدة على اللوحة](/images/enterprise/merged-step-card-canvas.png) + + +## على اللوحة + +تعرض كل بطاقة مطوية ما يلي: + +- **اسم المهمة ووصفها** في الأعلى. +- **تذييل يلخّص الوكيل المُعيَّن** — الصورة الرمزية والاسم والنموذج والأدوات. + +لا توجد عقدة وكيل منفصلة ولا حافة عمودية من الوكيل ← المهمة. تتصل خطواتك مباشرةً ببعضها البعض بالترتيب الذي تُنفَّذ به. + +## في المحرّر + +افتح بطاقة لتحريرها. العرض الموسّع هو البطاقة نفسها في حالة مفصّلة — وليس شاشة مختلفة — منظّمة في قسمين موسومين بوضوح. + + + ![محرّر الخطوة الموسّع](/images/enterprise/merged-step-card-editor.png) + + +### المهمة — ماذا تفعل + +مفتوحة افتراضيًا، لأنها ما تحرّره عادةً: + +- **الاسم** +- **الوصف** +- **المخرجات المتوقعة** +- **تنسيق الاستجابة** — يظهر هنا لأنه يتحكم تحديدًا في ما تقرأه الخطوات اللاحقة (مثل التوجيه) من هذه الخطوة. + +### الوكيل — من ينفّذها + +يُعرض الوكيل المُعيَّن كملخّص — **الاسم والنموذج والأدوات في سطر واحد**. ويُحفَظ إعداده الأعمق خلف قسمين قابلين للطي: + +- **الدور والهدف والخلفية** +- **إعدادات الوكيل** — الاستدلال، الحد الأقصى لمحاولات الاستدلال، السماح بالتفويض، الحد الأقصى للتكرارات، وإعدادات LLM. + + + الإعداد الكامل للوكيل — الدور، الهدف، الخلفية، النموذج، الأدوات، إعدادات LLM، وكامل كتلة إعدادات الوكيل — موجود خلف القسمين القابلين للطي **الدور والهدف والخلفية** و**إعدادات الوكيل**، منظّمًا حسب عدد مرّات تحريرك له. + + +## التبديل مقابل تحرير الوكيل + +هناك طريقتان متمايزتان للتعامل مع الوكيل في البطاقة، وكل منهما تؤدي وظيفة مختلفة: + +- **التبديل (Swap)** يعيد تعيين *أي* وكيل ينفّذ هذه المهمة. استخدم عنصر التحكم **تبديل** لاختيار وكيل مختلف من هذا المشروع، أو اختيار واحد من مستودع الوكلاء، أو إنشاء وكيل جديد. هذا مقصور على نطاق المهمة. +- **تحرير** الوكيل — بفتح **الدور والهدف والخلفية** أو **إعدادات الوكيل** — يغيّر الوكيل *نفسه*. + + + ![لوحة تبديل الوكيل](/images/enterprise/merged-step-card-swap-agent.png) + + + + **الوكلاء قابلون لإعادة الاستخدام ومشتركون.** يمكن للوكيل نفسه تنفيذ أكثر من مهمة عبر مشروعك. تحرير دور الوكيل أو خلفيته أو إعداداته يحدّث ذلك الوكيل **في كل مكان يُستخدم فيه** — وليس فقط في البطاقة التي فتحتها. إذا أردت تطبيق تغيير على خطوة واحدة فقط، فقم **بالتبديل** إلى وكيل مختلف بدلاً من تحرير الوكيل المشترك. + + +## ذات صلة + + + + أنشئ الأتمتة بمساعدة الذكاء الاصطناعي ومحرّر مرئي. + + + إدارة الوكلاء وإعادة استخدامهم عبر أتمتتك. + + diff --git a/docs/v1.15.1/ar/enterprise/features/pii-trace-redactions.mdx b/docs/v1.15.1/ar/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..58f013224 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: إخفاء البيانات الشخصية في التتبعات +description: "إخفاء البيانات الحساسة تلقائياً من تتبعات تنفيذ الطواقم والتدفقات" +icon: "lock" +mode: "wide" +--- + +## نظرة عامة + +إخفاء البيانات الشخصية (PII Redaction) هو ميزة في CrewAI AMP تكتشف تلقائياً وتُقنّع معلومات التعريف الشخصية (PII) في تتبعات تنفيذ الطواقم والتدفقات. يضمن ذلك عدم كشف البيانات الحساسة مثل أرقام بطاقات الائتمان وأرقام الضمان الاجتماعي وعناوين البريد الإلكتروني والأسماء في تتبعات CrewAI AMP. يمكنك أيضاً إنشاء مُعرّفات مخصصة لحماية البيانات الخاصة بمؤسستك. + + + + إخفاء البيانات الشخصية متاح في خطة Enterprise. + يجب أن يكون إصدار النشر 1.8.0 أو أعلى. + + + + + ![نظرة عامة على إخفاء البيانات الشخصية](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## أهمية إخفاء البيانات الشخصية + +عند تشغيل وكلاء الذكاء الاصطناعي في بيئة الإنتاج، غالباً ما تمر معلومات حساسة عبر طواقمك: + +- بيانات العملاء من تكاملات CRM +- معلومات مالية من معالجات الدفع +- تفاصيل شخصية من إرسالات النماذج +- بيانات الموظفين الداخلية + +بدون إخفاء مناسب، تظهر هذه البيانات في التتبعات، مما يجعل الامتثال للوائح مثل GDPR وHIPAA وPCI-DSS أمراً صعباً. يحل إخفاء البيانات الشخصية هذه المشكلة عن طريق إقناع البيانات الحساسة تلقائياً قبل تخزينها في التتبعات. + +## كيف يعمل + +1. **الاكتشاف** - مسح بيانات أحداث التتبع بحثاً عن أنماط PII المعروفة +2. **التصنيف** - تحديد نوع البيانات الحساسة (بطاقة ائتمان، SSN، بريد إلكتروني، إلخ.) +3. **الإقناع/الإخفاء** - استبدال البيانات الحساسة بقيم مُقنّعة بناءً على تهيئتك + +``` +Original: "Contact john.doe@company.com or call 555-123-4567" +Redacted: "Contact or call " +``` + +## تفعيل إخفاء البيانات الشخصية + + + يجب أن تكون على خطة Enterprise وأن يكون إصدار النشر 1.8.0 أو أعلى لاستخدام هذه الميزة. + + + + + في لوحة تحكم CrewAI AMP، اختر طاقمك المنشور وانتقل إلى أحد عمليات النشر/الأتمتة، ثم انتقل إلى **Settings** → **PII Protection**. + + + + فعّل **PII Redaction for Traces**. سيؤدي ذلك إلى تفعيل المسح والإخفاء التلقائي لبيانات التتبع. + + + تحتاج إلى تفعيل إخفاء البيانات الشخصية يدوياً لكل عملية نشر. + + + + ![تفعيل إخفاء البيانات الشخصية](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + اختر أنواع البيانات الشخصية التي تريد اكتشافها وإخفاءها. يمكن تفعيل أو تعطيل كل كيان بشكل فردي. + + + ![تهيئة الكيانات](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + احفظ تهيئتك. سيكون إخفاء البيانات الشخصية نشطاً في جميع عمليات تنفيذ الطاقم اللاحقة، دون الحاجة لإعادة النشر. + + + +## أنواع الكيانات المدعومة + +يدعم CrewAI أنواع كيانات PII التالية، منظمة حسب الفئة. + +### الكيانات العالمية + +| الكيان | الوصف | مثال | +|--------|-------|------| +| `CREDIT_CARD` | أرقام بطاقات الائتمان/الخصم | "4111-1111-1111-1111" | +| `CRYPTO` | عناوين محافظ العملات الرقمية | "bc1qxy2kgd..." | +| `DATE_TIME` | التواريخ والأوقات | "January 15, 2024" | +| `EMAIL_ADDRESS` | عناوين البريد الإلكتروني | "john@example.com" | +| `IBAN_CODE` | أرقام الحسابات المصرفية الدولية | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | عناوين IPv4 وIPv6 | "192.168.1.1" | +| `LOCATION` | المواقع الجغرافية | "New York City" | +| `MEDICAL_LICENSE` | أرقام التراخيص الطبية | "MD12345" | +| `NRP` | الجنسيات أو المجموعات الدينية أو السياسية | - | +| `PERSON` | الأسماء الشخصية | "John Doe" | +| `PHONE_NUMBER` | أرقام الهواتف بتنسيقات مختلفة | "+1 (555) 123-4567" | +| `URL` | عناوين URL | "https://example.com" | + +### كيانات خاصة بالولايات المتحدة + +| الكيان | الوصف | مثال | +|--------|-------|------| +| `US_BANK_NUMBER` | أرقام الحسابات المصرفية الأمريكية | "1234567890" | +| `US_DRIVER_LICENSE` | أرقام رخص القيادة الأمريكية | "D1234567" | +| `US_ITIN` | رقم تعريف دافع الضرائب الفردي | "900-70-0000" | +| `US_PASSPORT` | أرقام جوازات السفر الأمريكية | "123456789" | +| `US_SSN` | أرقام الضمان الاجتماعي | "123-45-6789" | + +## إجراءات الإخفاء + +لكل كيان مُفعّل، يمكنك تهيئة كيفية إخفاء البيانات: + +| الإجراء | الوصف | مثال على المخرجات | +|---------|-------|-------------------| +| `mask` | الاستبدال بتسمية نوع الكيان | `` | +| `redact` | إزالة النص بالكامل | *(فارغ)* | + +## المُعرّفات المخصصة + +بالإضافة إلى الكيانات المدمجة، يمكنك إنشاء **مُعرّفات مخصصة** لاكتشاف أنماط PII الخاصة بمؤسستك. + + + ![المُعرّفات المخصصة](/images/enterprise/pii_mask_recognizer.png) + + +### أنواع المُعرّفات + +لديك خياران للمُعرّفات المخصصة: + +| النوع | الأفضل لـ | مثال على حالة الاستخدام | +|-------|-----------|------------------------| +| **قائم على النمط (Regex)** | بيانات منظمة بتنسيقات متوقعة | مبالغ الرواتب، معرّفات الموظفين، رموز المشاريع | +| **قائمة الحظر (Deny-list)** | مطابقة النصوص بالضبط | أسماء الشركات، الأسماء الرمزية الداخلية، مصطلحات محددة | + +### إنشاء مُعرّف مخصص + + + + انتقل إلى **Settings** → **Organization** → **Add Recognizer** في إعدادات مؤسستك. + + + + + ![تهيئة المُعرّف](/images/enterprise/pii_mask_recognizer_create.png) + + + هيّئ الحقول التالية: + - **Name**: اسم وصفي للمُعرّف + - **Entity Type**: تسمية الكيان التي ستظهر في المخرجات المُخفاة (مثل `EMPLOYEE_ID`، `SALARY`) + - **Type**: اختر بين Regex Pattern أو Deny List + - **Pattern/Values**: نمط Regex أو قائمة نصوص للمطابقة + - **Confidence Threshold**: الحد الأدنى للنتيجة (0.0-1.0) المطلوبة لتفعيل الإخفاء عند المطابقة. القيم الأعلى (مثل 0.8) تقلل الإيجابيات الخاطئة لكن قد تفوّت بعض المطابقات. القيم الأقل (مثل 0.5) تلتقط المزيد من المطابقات لكن قد تُفرط في الإخفاء. القيمة الافتراضية هي 0.8. + - **Context Words** (اختياري): كلمات تزيد ثقة الاكتشاف عند وجودها بالقرب + + + + احفظ المُعرّف. سيكون متاحاً للتفعيل في عمليات النشر الخاصة بك. + + + +### فهم أنواع الكيانات + +يحدد **Entity Type** كيفية ظهور المحتوى المُطابق في التتبعات المُخفاة: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +Input: "Employee salary: $50,000" +Output: "Employee " +``` + +### استخدام كلمات السياق + +تحسّن كلمات السياق الدقة عن طريق زيادة الثقة عند ظهور مصطلحات محددة بالقرب من النمط المُطابق: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +عندما تظهر كلمة "project" أو "code" بالقرب من "PRJ-1234"، يكون لدى المُعرّف ثقة أعلى بأنها مطابقة حقيقية، مما يقلل الإيجابيات الخاطئة. + + +## عرض التتبعات المُخفاة + +بمجرد تفعيل إخفاء البيانات الشخصية، ستعرض تتبعاتك قيماً مُخفاة بدلاً من البيانات الحساسة: + +``` +Task Output: "Customer placed order #12345. +Contact email: , phone: . +Payment processed for card ending in ." +``` + +القيم المُخفاة مُعلّمة بوضوح بأقواس زاوية وتسمية نوع الكيان (مثل ``)، مما يسهّل فهم البيانات التي تمت حمايتها مع السماح لك بتصحيح الأخطاء ومراقبة سلوك الطاقم. + + + +## أفضل الممارسات + +### اعتبارات الأداء + + + + كل كيان مُفعّل يضيف عبء معالجة. فعّل فقط الكيانات ذات الصلة ببياناتك. + + + + للمُعرّفات المخصصة، استخدم أنماطاً محددة لتقليل الإيجابيات الخاطئة وتحسين الأداء. أنماط Regex هي الأفضل عند تحديد أنماط معينة في التتبعات مثل الرواتب ومعرّفات الموظفين ورموز المشاريع وغيرها. مُعرّفات قائمة الحظر هي الأفضل عند تحديد نصوص بعينها في التتبعات مثل أسماء الشركات والأسماء الرمزية الداخلية وغيرها. + + + + تحسّن كلمات السياق الدقة عن طريق تفعيل الاكتشاف فقط عندما يتطابق النص المحيط. + + + +## استكشاف الأخطاء وإصلاحها + + + **الأسباب المحتملة:** + - نوع الكيان غير مُفعّل في التهيئة + - النمط لا يتطابق مع تنسيق البيانات + - المُعرّف المخصص يحتوي على أخطاء في الصياغة + + **الحلول:** + - تحقق من أن الكيان مُفعّل في Settings → Security + - اختبر أنماط Regex مع بيانات نموذجية + - تحقق من السجلات بحثاً عن أخطاء التهيئة + + + + **الأسباب المحتملة:** + - أنواع كيانات واسعة جداً مُفعّلة (مثل `DATE_TIME` تلتقط التواريخ في كل مكان) + - أنماط المُعرّف المخصص عامة جداً + + **الحلول:** + - عطّل الكيانات التي تسبب إيجابيات خاطئة + - اجعل الأنماط المخصصة أكثر تحديداً + - أضف كلمات سياق لتحسين الدقة + + + + **الأسباب المحتملة:** + - عدد كبير جداً من الكيانات المُفعّلة + - الكيانات القائمة على NLP (مثل `PERSON` و`LOCATION` و`NRP`) مكلفة حسابياً لأنها تستخدم نماذج تعلم الآلة + + **الحلول:** + - فعّل فقط الكيانات التي تحتاجها فعلاً + - فكّر في استخدام بدائل قائمة على الأنماط حيثما أمكن + - راقب أوقات معالجة التتبعات في لوحة التحكم + + +--- + +## مثال عملي: مطابقة نمط الراتب + +يوضح هذا المثال كيفية إنشاء مُعرّف مخصص لاكتشاف وإقناع معلومات الرواتب في تتبعاتك. + +### حالة الاستخدام + +يعالج طاقمك بيانات موظفين أو بيانات مالية تتضمن معلومات رواتب بتنسيقات مثل: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +تريد إقناع هذه القيم تلقائياً لحماية بيانات التعويضات الحساسة. + +### التهيئة + + + ![تهيئة مُعرّف الراتب](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| الحقل | القيمة | +|-------|--------| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### تحليل نمط Regex + +| مكون النمط | المعنى | +|------------|--------| +| `salary:` | يطابق النص الحرفي "salary:" | +| `\s*` | يطابق صفر أو أكثر من أحرف المسافات البيضاء | +| `\$` | يطابق علامة الدولار (مُهرّبة) | +| `\s*` | يطابق صفر أو أكثر من أحرف المسافات البيضاء بعد $ | +| `\d{1,3}` | يطابق 1-3 أرقام (مثل "1"، "50"، "125") | +| `(,\d{3})*` | يطابق الآلاف المفصولة بفواصل (مثل ",000"، ",500,000") | +| `(\.\d{2})?` | يطابق اختيارياً السنتات (مثل ".00"، ".50") | + +### أمثلة على النتائج + +``` +Original: "Employee record shows salary: $125,000.00 annually" +Redacted: "Employee record shows annually" + +Original: "Base salary:$50,000 with bonus potential" +Redacted: "Base with bonus potential" +``` + + + إضافة كلمات سياق مثل "salary" و"compensation" و"pay" و"wage" و"income" تساعد في زيادة ثقة الاكتشاف عند ظهور هذه المصطلحات بالقرب من النمط المُطابق، مما يقلل الإيجابيات الخاطئة. + + +### تفعيل المُعرّف لعمليات النشر + + + إنشاء مُعرّف مخصص على مستوى المؤسسة لا يفعّله تلقائياً لعمليات النشر. يجب عليك تفعيل كل مُعرّف يدوياً لكل عملية نشر تريد تطبيقه عليها. + + +بعد إنشاء المُعرّف المخصص، فعّله لكل عملية نشر: + + + + انتقل إلى عملية النشر/الأتمتة وافتح **Settings** → **PII Protection**. + + + + تحت **Mask Recognizers**، سترى المُعرّفات المحددة على مستوى مؤسستك. حدد المربع بجانب المُعرّفات التي تريد تفعيلها. + + + ![تفعيل المُعرّف المخصص](/images/enterprise/pii_mask_recognizers_options.png) + + + + + احفظ تغييراتك. سيكون المُعرّف نشطاً في جميع عمليات التنفيذ اللاحقة لعملية النشر هذه. + + + + + كرر هذه العملية لكل عملية نشر تحتاج فيها إلى المُعرّف المخصص. يمنحك ذلك تحكماً دقيقاً في المُعرّفات النشطة في البيئات المختلفة (مثل بيئة التطوير مقابل بيئة الإنتاج). + diff --git a/docs/v1.15.1/ar/enterprise/features/rbac.mdx b/docs/v1.15.1/ar/enterprise/features/rbac.mdx new file mode 100644 index 000000000..166e905cc --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/rbac.mdx @@ -0,0 +1,256 @@ +--- +title: "التحكم في الوصول القائم على الأدوار (RBAC)" +description: "تحكم في الوصول إلى الطواقم والأدوات والبيانات باستخدام الأدوار والنطاقات والصلاحيات الدقيقة." +icon: "shield" +mode: "wide" +--- + +## نظرة عامة + +يتيح RBAC في CrewAI AMP إدارة وصول آمنة وقابلة للتوسع من خلال طبقتين: + +1. **صلاحيات الميزات** — تتحكم في ما يمكن لكل دور القيام به عبر المنصة (إدارة، قراءة، أو بدون وصول) +2. **صلاحيات على مستوى الكيان** — وصول دقيق للأتمتات الفردية ومتغيرات البيئة واتصالات LLM ومستودعات Git + + + نظرة عامة على RBAC في CrewAI AMP + + +## المستخدمون والأدوار + +يُعيَّن لكل عضو في مساحة عمل CrewAI دور يحدد صلاحيات الوصول عبر الميزات المختلفة. + +يمكنك: + +- استخدام الأدوار المحددة مسبقاً (Owner، Member) +- إنشاء أدوار مخصصة مصممة لصلاحيات محددة +- تعيين الأدوار في أي وقت عبر لوحة الإعدادات + +يمكنك تهيئة المستخدمين والأدوار في Settings → Roles. + + + + انتقل إلى Settings → Roles في CrewAI AMP. + + + استخدم دوراً محدداً مسبقاً (Owner، Member) أو انقر على{" "} + Create role لتحديد دور مخصص. + + + اختر المستخدمين وعيّن لهم الدور. يمكنك تغيير ذلك في أي وقت. + + + +### الأدوار المحددة مسبقاً + +| الدور | الوصف | +| :---------- | :-------------------------------------------------------------------- | +| **Owner** | وصول كامل لجميع الميزات والإعدادات. لا يمكن تقييده. | +| **Member** | وصول للقراءة لمعظم الميزات، وصول إدارة لمتغيرات البيئة واتصالات LLM ومشاريع Studio. لا يمكنه تعديل إعدادات المؤسسة أو الإعدادات الافتراضية. | + +### ملخص التهيئة + +| المجال | مكان التهيئة | الخيارات | +| :-------------------- | :--------------------------------- | :-------------------------------------- | +| المستخدمون والأدوار | Settings → Roles | محددة مسبقاً: Owner، Member؛ أدوار مخصصة | +| رؤية الأتمتة | Automation → Settings → Visibility | خاص؛ قائمة بيضاء للمستخدمين/الأدوار | + +--- + +## مصفوفة صلاحيات الميزات + +لكل دور مستوى صلاحية لكل منطقة ميزة. المستويات الثلاثة هي: + +- **إدارة (Manage)** — وصول كامل للقراءة/الكتابة (إنشاء، تعديل، حذف) +- **قراءة (Read)** — وصول للعرض فقط +- **بدون وصول (No access)** — الميزة مخفية/غير قابلة للوصول + +| الميزة | Owner | Member (افتراضي) | المستويات المتاحة | الوصف | +| :------------------------ | :------ | :--------------- | :--------------------------------- | :-------------------------------------------------------------- | +| `usage_dashboards` | Manage | Read | Manage / Read / No access | عرض مقاييس وتحليلات الاستخدام | +| `crews_dashboards` | Manage | Read | Manage / Read / No access | عرض لوحات النشر والوصول إلى تفاصيل الأتمتة | +| `invitations` | Manage | Read | Manage / Read / No access | دعوة أعضاء جدد إلى المؤسسة | +| `training_ui` | Manage | Read | Manage / Read / No access | الوصول إلى واجهات التدريب/الضبط الدقيق | +| `tools` | Manage | Read | Manage / Read / No access | إنشاء وإدارة الأدوات | +| `agents` | Manage | Read | Manage / Read / No access | إنشاء وإدارة الوكلاء | +| `environment_variables` | Manage | Manage | Manage / No access | إنشاء وإدارة متغيرات البيئة | +| `llm_connections` | Manage | Manage | Manage / No access | تهيئة اتصالات مزودي LLM | +| `default_settings` | Manage | No access | Manage / No access | تعديل الإعدادات الافتراضية على مستوى المؤسسة | +| `organization_settings` | Manage | No access | Manage / No access | إدارة الفوترة والخطط وتهيئة المؤسسة | +| `studio_projects` | Manage | Manage | Manage / No access | إنشاء وتعديل المشاريع في Studio | + + + عند إنشاء دور مخصص، يمكن ضبط معظم الميزات على **Manage** أو **Read** أو **No access**. ومع ذلك، فإن `environment_variables` و`llm_connections` و`default_settings` و`organization_settings` و`studio_projects` تدعم فقط **Manage** أو **No access** — لا يوجد خيار للقراءة فقط لهذه الميزات. + + +--- + +## النشر من GitHub أو Zip + +من أكثر أسئلة RBAC شيوعاً: _"ما الصلاحيات التي يحتاجها عضو الفريق للنشر؟"_ + +### النشر من GitHub + +لنشر أتمتة من مستودع GitHub، يحتاج المستخدم إلى: + +1. **`crews_dashboards`**: على الأقل `Read` — مطلوب للوصول إلى لوحة الأتمتات حيث يتم إنشاء عمليات النشر +2. **الوصول إلى مستودع Git** (إذا كان RBAC على مستوى الكيان لمستودعات Git مفعلاً): يجب منح دور المستخدم الوصول إلى مستودع Git المحدد عبر صلاحيات مستوى الكيان +3. **`studio_projects`: `Manage`** — إذا كان يبني الطاقم في Studio قبل النشر + +### النشر من Zip + +لنشر أتمتة من ملف Zip، يحتاج المستخدم إلى: + +1. **`crews_dashboards`**: على الأقل `Read` — مطلوب للوصول إلى لوحة الأتمتات +2. **تفعيل نشر Zip**: يجب ألا تكون المؤسسة قد عطلت نشر Zip في إعدادات المؤسسة + +### مرجع سريع: الحد الأدنى من الصلاحيات للنشر + +| الإجراء | صلاحيات الميزات المطلوبة | متطلبات إضافية | +| :------------------- | :----------------------------------- | :----------------------------------------------- | +| النشر من GitHub | `crews_dashboards: Read` | وصول كيان مستودع Git (إذا كان Git RBAC مفعلاً) | +| النشر من Zip | `crews_dashboards: Read` | يجب تفعيل نشر Zip على مستوى المؤسسة | +| البناء في Studio | `studio_projects: Manage` | — | +| تهيئة مفاتيح LLM | `llm_connections: Manage` | — | +| ضبط متغيرات البيئة | `environment_variables: Manage` | وصول مستوى الكيان (إذا كان RBAC الكيان مفعلاً) | + +--- + +## التحكم في الوصول على مستوى الأتمتة (صلاحيات الكيان) + +بالإضافة إلى الأدوار على مستوى المؤسسة، يدعم CrewAI صلاحيات دقيقة على مستوى الكيان تقيد الوصول إلى موارد فردية. + +### رؤية الأتمتة + +تدعم الأتمتات إعدادات رؤية تقيد الوصول حسب المستخدم أو الدور. هذا مفيد لـ: + +- الحفاظ على خصوصية الأتمتات الحساسة أو التجريبية +- إدارة الرؤية عبر الفرق الكبيرة أو المتعاونين الخارجيين +- اختبار الأتمتات في سياقات معزولة + +يمكن تهيئة عمليات النشر كخاصة، مما يعني أن المستخدمين والأدوار المدرجين في القائمة البيضاء فقط سيتمكنون من التفاعل معها. + +يمكنك تهيئة التحكم في الوصول على مستوى الأتمتة في Automation → Settings → علامة تبويب Visibility. + + + + انتقل إلى Automation → Settings → Visibility. + + + اختر Private لتقييد الوصول. يحتفظ مالك المؤسسة دائماً + بالوصول. + + + أضف مستخدمين وأدواراً محددة مسموح لهم بالعرض والتشغيل والوصول + إلى السجلات/المقاييس/الإعدادات. + + + احفظ التغييرات، ثم تأكد من أن المستخدمين غير المدرجين في القائمة البيضاء لا يمكنهم عرض أو تشغيل + الأتمتة. + + + +### الرؤية الخاصة: نتائج الوصول + +| الإجراء | المالك | مستخدم/دور في القائمة البيضاء | غير مدرج في القائمة البيضاء | +| :--------------------------- | :---- | :---------------------------- | :-------------------------- | +| عرض الأتمتة | ✓ | ✓ | ✗ | +| تشغيل الأتمتة/API | ✓ | ✓ | ✗ | +| الوصول إلى السجلات/المقاييس/الإعدادات | ✓ | ✓ | ✗ | + + + يتمتع مالك المؤسسة دائماً بالوصول. في الوضع الخاص، يمكن فقط للمستخدمين + والأدوار المدرجين في القائمة البيضاء العرض والتشغيل والوصول إلى السجلات/المقاييس/الإعدادات. + + + + إعدادات رؤية الأتمتة في CrewAI AMP + + +### أنواع صلاحيات النشر + +عند منح وصول على مستوى الكيان لأتمتة محددة، يمكنك تعيين أنواع الصلاحيات التالية: + +| الصلاحية | ما تسمح به | +| :------------------- | :-------------------------------------------------- | +| `run` | تنفيذ الأتمتة واستخدام API الخاص بها | +| `traces` | عرض تتبعات التنفيذ والسجلات | +| `manage_settings` | تعديل، إعادة نشر، استرجاع، أو حذف الأتمتة | +| `human_in_the_loop` | الرد على طلبات الإنسان في الحلقة (HITL) | +| `full_access` | جميع ما سبق | + +### RBAC على مستوى الكيان لموارد أخرى + +عند تفعيل RBAC على مستوى الكيان، يمكن أيضاً التحكم في الوصول لهذه الموارد حسب المستخدم أو الدور: + +| المورد | يتم التحكم فيه بواسطة | الوصف | +| :-------------------- | :--------------------------------- | :------------------------------------------------------------- | +| متغيرات البيئة | علامة ميزة RBAC الكيان | تقييد أي الأدوار/المستخدمين يمكنهم عرض أو إدارة متغيرات بيئة محددة | +| اتصالات LLM | علامة ميزة RBAC الكيان | تقييد الوصول لتهيئات مزودي LLM محددة | +| مستودعات Git | إعداد RBAC لمستودعات Git بالمؤسسة | تقييد أي الأدوار/المستخدمين يمكنهم الوصول لمستودعات متصلة محددة | + +--- + +## أنماط الأدوار الشائعة + +بينما يأتي CrewAI بدوري Owner وMember، تستفيد معظم الفرق من إنشاء أدوار مخصصة. إليك الأنماط الشائعة: + +### دور المطور + +دور لأعضاء الفريق الذين يبنون وينشرون الأتمتات لكن لا يديرون إعدادات المؤسسة. + +| الميزة | الصلاحية | +| :------------------------ | :---------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Manage | +| `invitations` | Read | +| `training_ui` | Read | +| `tools` | Manage | +| `agents` | Manage | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | Manage | + +### دور المشاهد / أصحاب المصلحة + +دور للمعنيين غير التقنيين الذين يحتاجون لمراقبة الأتمتات وعرض النتائج. + +| الميزة | الصلاحية | +| :------------------------ | :---------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Read | +| `invitations` | No access | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | No access | +| `llm_connections` | No access | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | No access | + +### دور مسؤول العمليات / المنصة + +دور لمشغلي المنصة الذين يديرون إعدادات البنية التحتية لكن قد لا يبنون الوكلاء. + +| الميزة | الصلاحية | +| :------------------------ | :---------- | +| `usage_dashboards` | Manage | +| `crews_dashboards` | Manage | +| `invitations` | Manage | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | Manage | +| `organization_settings` | Read | +| `studio_projects` | No access | + +--- + + + تواصل مع فريق الدعم للمساعدة في أسئلة RBAC. + diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/aws-workload-identity.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/aws-workload-identity.mdx new file mode 100644 index 000000000..0e7c91d26 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/aws-workload-identity.mdx @@ -0,0 +1,321 @@ +--- +title: AWS Workload Identity (اتحاد OIDC) +description: تكوين AWS Secrets Manager عبر Workload Identity للوصول إلى الأسرار بشكل مراعٍ للتدوير وبدون بيانات اعتماد +sidebarTitle: بـ Workload Identity +icon: "id-badge" +--- + +## نظرة عامة + +يُكوِّن هذا الدليل AWS Secrets Manager كمزود أسرار باستخدام **Workload Identity Federation**: تُصدر CrewAI Platform رموز OIDC قصيرة الأمد، وتُبادلها للحصول على بيانات اعتماد AWS عبر STS، وتقرأ أسرارك — دون تخزين أي مفتاح وصول AWS طويل الأمد في أي مكان. + + +**لماذا هذا المسار:** تُحَلّ الأسرار وقت تنفيذ الأتمتة، لذا **تنتشر القيم المُدوَّرة إلى الإطلاق التالي بدون إعادة نشر**. إن كنت تحتاج فقط بيانات اعتماد ثابتة ولا تهتم بانتشار التدوير، راجع الدليل الأبسط [AWS — المفاتيح الثابتة / AssumeRole](/ar/enterprise/features/secrets-manager/aws). + + +### كيف يعمل وقت التشغيل + +1. يطلب عامل النشر JWT OIDC طازج من CrewAI Platform. +2. يستدعي العامل `sts:AssumeRoleWithWebIdentity` على دور IAM الذي ستُعدّه أدناه، مُقدِّماً الـ JWT. +3. تتحقق AWS STS من الـ JWT مقابل مُصدر OIDC العام لـ CrewAI Platform (لذا يجب أن يكون تنصيب منصتك قابلاً للوصول من AWS)، ثم تُعيد بيانات اعتماد AWS قصيرة الأمد. +4. يستخدم العامل تلك البيانات لاستدعاء `secretsmanager:GetSecretValue`. +5. تُحقن القيمة المجلوبة كقيمة لمتغير البيئة لإطلاق الأتمتة ذاك. + +تُخزَّن رموز موضوع OIDC مؤقتاً لنحو ساعة لتفادي إعادة الإصدار في كل إطلاق. تُجلب قيم الأسرار طازجة في كل إطلاق بغض النظر عن حالة ذاكرة OIDC المؤقتة، وهذا ما يجعل هذا المسار مراعياً للتدوير. + +## المتطلبات المسبقة + + +قبل البدء، تأكد من امتلاكك: + +- يجب أن تتضمن صورة حاوية الأتمتة إصدار CrewAI runtime رقم `1.14.5` أو أحدث. +- حساب AWS لديه إذن إنشاء مزوّدي OIDC وأدوار وسياسات IAM. +- منطقة AWS التي تعيش (أو ستعيش) فيها أسرارك، مثلاً `us-east-1`. +- مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذني `workload_identity_configs: manage` و `secret_providers: manage`. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac). +- **UUID مؤسسة CrewAI الخاصة بك.** يمكنك العثور عليه في صفحة إعدادات المؤسسة في CrewAI Platform — تُربط سياسة الثقة في الخطوة 3 دور IAM بهذه المؤسسة تحديداً. +- **يجب أن يكون تنصيب CrewAI Platform قابلاً للوصول من AWS عبر HTTPS** ليتمكّن AWS STS من جلب وثيقة اكتشاف OIDC و JWKS أثناء التحقق من الرمز. تأكد مع مسؤول المنصة من أن المضيف متاح عبر الإنترنت (أو أن AWS يمكنه الوصول إليه شبكياً عبر VPC peering أو ما يعادله). + + +## الخطوة 1 — العثور على عنوان مُصدر OIDC لـ CrewAI Platform + +ينشر تنصيب CrewAI Platform وثيقة اكتشاف OpenID Connect على `https:///.well-known/openid-configuration`. الحقل `issuer` في تلك الوثيقة هو الرابط الذي ستُسجِّله AWS كمزود OIDC موثوق. + +افتح الرابط في المتصفح (مع استبدال `` بمضيفك الفعلي، مثلاً `app.crewai.com`): + +``` +https:///.well-known/openid-configuration +``` + +ينبغي أن ترى JSON يحتوي على: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +سجّل القيمة الدقيقة لـ `issuer` — ستستخدمها في الخطوة 3. + + +إذا أعاد الرابط 404 أو 503، اتصل بمسؤول المنصة. يتطلب مُصدر OIDC تكوين مفتاح توقيع خاص وقت التنصيب. راجع دليل تنصيب المنصة لتكوين `OIDC_PRIVATE_KEY` و `OIDC_ISSUER`. + + +## الخطوة 2 — تسجيل CrewAI Platform كمزود هوية OIDC في IAM + +افتح [وحدة تحكم IAM ← Identity providers](https://console.aws.amazon.com/iam/home#/identity_providers) وانقر على **Add provider**. + +- **Provider type:** OpenID Connect. +- **Provider URL:** قيمة `issuer` من الخطوة 1 (مثلاً `https://app.crewai.com`). +- **Audience:** `sts.amazonaws.com` + +انقر على **Add provider**. + +أو عبر CLI: + +```bash +aws iam create-open-id-connect-provider \ + --url "https://" \ + --client-id-list "sts.amazonaws.com" \ + --thumbprint-list "$(echo | openssl s_client -servername -connect :443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')" +``` + +انسخ **OpenIDConnectProviderArn** من المخرجات (أو ARN المزود من الوحدة). ستستخدمه في الخطوة 3. + + +لا تتحقق AWS فعلياً من بصمة الإبهام لاستدعاءات STS WebIdentity — فهي دائماً تُعيد جلب JWKS وقت التحقق — لكن واجهة الـ API تتطلب وجود الحقل. + + +{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */} +{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */} + +## الخطوة 3 — إنشاء دور IAM + +احفظ كـ `trust-policy.json`، مع استبدال `` و `` (مضيف المُصدر **بدون** `https://` أو `http://`، مثلاً `app.crewai.com`) و `` (من المتطلبات المسبقة): + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":aud": "sts.amazonaws.com", + ":sub": "organization:" + } + } + } + ] +} +``` + +أنشئ الدور: + +```bash +aws iam create-role \ + --role-name crewai-secrets-reader \ + --assume-role-policy-document file://trust-policy.json +``` + +انسخ **Role Arn** من المخرجات — هذا هو `aws_role_arn` الخاص بك. ستلصقه في CrewAI Platform في الخطوة 6. + + +يحدّد الشرطان نطاق الثقة بدقة: يقيّد `aud` افتراض الدور إلى الرموز ذات جمهور AWS STS، ويقصر `sub` الاتحاد على مؤسسة CrewAI محددة — تُقبل فقط الرموز المُصدَرة لأتمتات تلك المؤسسة. تُعيّن CrewAI Platform كلا الادّعاءين دائماً على رموز AWS workload identity. + + +{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */} + +## الخطوة 4 — إنشاء وإرفاق سياسة IAM لوصول Secrets Manager + KMS + +احفظ كـ `secrets-policy.json`، مع استبدال العناصر النائبة بمعرّف حسابك ومنطقتك وبادئة اسم السر و ARN(s) مفاتيح KMS التي تُشفّر تلك الأسرار: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerListForUI", + "Effect": "Allow", + "Action": "secretsmanager:ListSecrets", + "Resource": "*" + }, + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:GetSecretValue" + ], + "Resource": "arn:aws:secretsmanager:::secret:-*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:Decrypt" + ], + "Resource": "arn:aws:kms:::key/" + } + ] +} +``` + +تُشغّل `SecretsManagerListForUI` ميزة **الاقتراح التلقائي لاسم السر** في نموذج متغيرات البيئة وزر **Test Connection** على بيانات الاعتماد. يقبل `secretsmanager:ListSecrets` فقط `Resource: "*"` — فهو محصور على مستوى الحساب في طبقة IAM. + +أرفق السياسة بالدور إما عبر CLI (سياسة مضمنة، أبسط) أو واجهة الوحدة؛ للبيئات التي تعيد استخدام نفس الأذونات عبر أدوار متعددة، استخدم علامة التبويب **Managed policy** لسياسة مُسمّاة قابلة لإعادة الاستخدام. + + + + ```bash + aws iam put-role-policy \ + --role-name crewai-secrets-reader \ + --policy-name SecretsManagerRead \ + --policy-document file://secrets-policy.json + ``` + + يُرفق هذا السياسة **مضمنةً** بالدور. السياسات المضمنة مرتبطة بالدور ولا يمكن إعادة استخدامها على أدوار أخرى. + + + + ```bash + POLICY_ARN=$(aws iam create-policy \ + --policy-name CrewAISecretsReader \ + --policy-document file://secrets-policy.json \ + --query 'Policy.Arn' --output text) + + aws iam attach-role-policy \ + --role-name crewai-secrets-reader \ + --policy-arn "$POLICY_ARN" + ``` + + السياسة المُدارة هي مورد IAM مستقل يمكنك إرفاقه بأدوار متعددة. + + + + 1. افتح [وحدة تحكم IAM ← Roles](https://console.aws.amazon.com/iam/home#/roles) واختر **crewai-secrets-reader**. + 2. في علامة التبويب **Permissions**، انقر على **Add permissions** ← **Create inline policy**. + 3. بدّل إلى محرر **JSON** والصق محتوى `secrets-policy.json`. + 4. انقر على **Next**، أعطِ السياسة اسماً (مثلاً `SecretsManagerRead`)، وانقر على **Create policy**. + + لإنشاء سياسة مُدارة قابلة لإعادة الاستخدام بدلاً من ذلك، استخدم **IAM ← Policies ← Create policy** ثم أرفقها بالدور من علامة التبويب **Permissions** الخاصة بالدور. + + {/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */} + + + +## الخطوة 5 — إنشاء سر واحد على الأقل في AWS + +إذا لم يكن لديك سر للاختبار، أنشئ واحداً الآن: + +```bash +aws secretsmanager create-secret \ + --region \ + --name crewai-test-keyword \ + --secret-string "hello from aws" +``` + +أو عبر [وحدة تحكم AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/) ← **Store a new secret**. + +{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */} + +## الخطوة 6 — إضافة تكوين Workload Identity في CrewAI Platform + +في CrewAI Platform، انتقل إلى **Settings** ← **Workload Identity** وانقر على **Add Workload Identity Config**. + +{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */} +{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */} + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `aws-prod`. +- **Cloud Provider:** `AWS`. +- **AWS Role ARN:** **Role Arn** من الخطوة 3. +- **AWS Region:** المنطقة التي تعيش فيها أسرارك، مثلاً `us-east-1`. +- (اختياري) حدّد **Set as default for AWS** إذا كنت ترغب في أن يكون تكوين WI هذا هو الافتراضي المُحدَّد عند إنشاء بيانات اعتماد سر مدعومة بـ AWS. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */} +{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */} + +## الخطوة 7 — إضافة بيانات اعتماد مزود أسرار مرتبطة بتكوين WI + +انتقل إلى **Settings** ← **Secret Provider Credentials** وانقر على **Add Credential**. + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `aws-prod-wi`. +- **Provider:** `AWS Secrets Manager`. +- **Authentication Method:** `Workload Identity` (بدلاً من المفاتيح الثابتة / AssumeRole). +- **Workload Identity Configuration:** اختر التكوين الذي أنشأته في الخطوة 6 (مثلاً `aws-prod`). +- (اختياري) حدّد **Set as default credential for this provider**. + +سيطلب النموذج فقط **AWS Region** ضمن Workload Identity — حقول بيانات الاعتماد الثابتة (Access Key ID و Secret Access Key و Role ARN و External ID) مخفية عمداً لأنها لا تنطبق على هذا المسار؛ يأتي ARN الدور من تكوين WI المرتبط. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */} + +## الخطوة 8 — اختبار الاتصال + +بعد حفظ بيانات الاعتماد، انقر على **Test Connection**. لبيانات اعتماد workload-identity، يتحقق هذا من مصافحة OIDC: تُصدر CrewAI Platform JWT، وتبادله مع AWS STS عبر `sts:AssumeRoleWithWebIdentity`، وتؤكد أن بيانات الاعتماد الناتجة يمكنها استدعاء `sts:GetCallerIdentity` مقابل الدور المُفترَض. نتيجة خضراء تعني أن ارتباط الاتحاد سليم. + +نجاح Test Connection يُثبت أن سياسة الثقة وتسجيل مزود OIDC وشرط الجمهور موصولة جميعها بشكل صحيح. لا يُثبت ذلك أن IAM لكل سر صحيح — يُمارَس `secretsmanager:GetSecretValue` على ARN سر محدد بشكل منفصل عندما يُحَلّ متغير بيئة عند الإطلاق. راجع [استكشاف الأخطاء](#troubleshooting) لأنماط فشل المصافحة. + +## الخطوة 9 — الإشارة إلى السر في متغير بيئة + +الآن أَشِر إلى السر على أتمتة، تماماً كما تفعل مع أي متغير بيئة مدعوم بمدير أسرار. راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) لحقول النموذج والسلوك. + +الفرق الوحيد بين متغيرات البيئة المدعومة بـ WI والمدعومة بمفاتيح ثابتة هو **متى** يُقرأ السر: + +- **مدعوم بـ WI:** تُقرأ قيمة السر طازجة في كل إطلاق أتمتة. +- **مدعوم بمفاتيح ثابتة:** تُقرأ قيمة السر وقت النشر وتُدمج في صورة النشر. + +## الخطوة 10 — التحقق من التدوير + +بعد تشغيل عملية النشر، دوّر السر في AWS: + +```bash +aws secretsmanager update-secret \ + --region \ + --secret-id crewai-test-keyword \ + --secret-string "rotated value" +``` + +أطلق إطلاق أتمتة جديداً. ستكون بيئة الإطلاق ترى `"rotated value"` — بدون إعادة نشر ولا إعادة تشغيل عامل ولا انتظار TTL. + +للتأكد في السجلات (إذا كان لديك وصول إلى العامل)، ابحث عن: + +``` +Workload identity config '' (aws): N secret(s) resolved +``` + +يظهر هذا السطر لكل إطلاق ويُشير إلى استدعاء `GetSecretValue` طازج مقابل AWS. + +## استكشاف الأخطاء + +| العَرَض | السبب المحتمل | +|---|---| +| يفشل Test Connection بخطأ مصافحة | رُفض استدعاء `sts:AssumeRoleWithWebIdentity`. تحقق من أن ARN الكيان الموحَّد في سياسة الثقة يشير إلى `oidc-provider/` (المضيف **بدون** `https://` أو `http://` وبدون شرطة مائلة لاحقة)، وأن شرط الجمهور هو بالضبط `sts.amazonaws.com`، وأن شرط `sub` يطابق UUID مؤسسة CrewAI الخاصة بك، وأن رابط اكتشاف OIDC للمنصة قابل للوصول من AWS عبر الإنترنت العام. | +| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | لا يمكن لـ AWS STS الوصول إلى مضيف CrewAI Platform لجلب JWKS. تأكد من أن المضيف متاح عبر الإنترنت من AWS، وأن رابط اكتشاف OIDC يُعيد 200، وأن نقطة نهاية JWKS قابلة للوصول. | +| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | عدم تطابق سياسة الثقة. تحقق من الخطوة 3 من جديد: يجب أن يتضمن ARN الكيان الموحَّد `oidc-provider/` (المضيف **بدون** `https://` أو `http://` وبدون شرطة مائلة لاحقة)، ويجب أن يكون شرط الجمهور بالضبط `sts.amazonaws.com`، وأن يساوي شرط `sub` بالضبط `organization:`. | +| يُظهر الاقتراح التلقائي لاسم السر `AccessDenied: secretsmanager:ListSecrets` | يفتقد الدور إلى `secretsmanager:ListSecrets` مع `Resource: "*"`. أضف بيان `SecretsManagerListForUI` من الخطوة 4. | +| يفشل الإطلاق في حلّ سر رغم نجاح Test Connection | ارتباط WI سليم، لكن IAM المحصور بالمورد مفقود على السر الفاشل. راجع أذونات `secretsmanager:GetSecretValue` و `kms:Decrypt` للدور على ARN ذلك السر بعينه ومفتاح KMS الخاص به. | +| `RegionDisabledException` / لم يُعثر على أسرار | لا تطابق المنطقة في تكوين Workload Identity المكان الفعلي للسر. تحقق من الخطوة 6 من جديد. | +| لا تُلتقط القيمة المُدوَّرة في الإطلاق التالي | تأكد من أن متغير البيئة على الأتمتة يشير إلى بيانات اعتماد مدعومة بـ Workload Identity (وليس بيانات اعتماد بمفاتيح ثابتة). يدمج المسار الثابت القيم في صورة النشر. | + +### روابط مرجعية + +- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) +- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html) +- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) + +## الخطوات التالية + +- [استخدام الأسرار في متغيرات البيئة وإدارة الأذونات](/ar/enterprise/features/secrets-manager/usage) +- للتنوع متعدد السحاب، راجع أيضاً [GCP Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity) و [Azure Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity). diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/aws.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/aws.mdx new file mode 100644 index 000000000..7d7b3912b --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/aws.mdx @@ -0,0 +1,295 @@ +--- +title: AWS Secrets Manager (بيانات اعتماد ثابتة) +description: تكوين AWS Secrets Manager كمزود أسرار لـ CrewAI Platform باستخدام مفاتيح الوصول الثابتة أو AssumeRole +sidebarTitle: ببيانات اعتماد ثابتة +icon: "key" +--- + +## نظرة عامة + +يأخذك هذا الدليل عبر تكوين AWS Secrets Manager كمزود أسرار لمؤسستك على CrewAI Platform، باستخدام **بيانات الاعتماد الثابتة** (مفاتيح الوصول، اختيارياً مع AssumeRole). بنهاية الدليل، ستتمكن CrewAI Platform من قراءة الأسرار المخزّنة في حساب AWS الخاص بك وحقنها كقيم متغيرات بيئة وقت التشغيل. + + +يغطي هذا الدليل مسار **بيانات الاعتماد الثابتة** — تُحَلّ الأسرار وقت النشر وتُدمج في صورة النشر. تتطلب القيم المُدوَّرة إعادة نشر. إذا أردت أسراراً مراعية للتدوير تُحدَّث في كل إطلاق أتمتة (بدون إعادة نشر)، راجع [AWS Workload Identity (اتحاد OIDC)](/ar/enterprise/features/secrets-manager/aws-workload-identity). + + + +يغطي هذا الدليل التكوين من جانب AWS وإعداد بيانات الاعتماد في CrewAI Platform. للإشارة بعدها إلى سر من متغير بيئة، راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage). + + +## المتطلبات المسبقة + + +قبل البدء، تأكد من امتلاكك: + +- حساب AWS لديه إذن إنشاء مستخدمي IAM وسياسات يديرها العميل و(اختيارياً) أدوار IAM. +- منطقة AWS التي تعيش (أو ستعيش) فيها أسرارك، مثلاً `us-east-1`. +- مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذن `secret_providers: manage`. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## اختر طريقة المصادقة + +تدعم CrewAI Platform طريقتين لمصادقة المنصة مع AWS Secrets Manager. اختر واحدة قبل أن تبدأ — تختلف الخطوات أدناه بناءً على اختيارك. + +| الطريقة | متى تُستخدم | المقايضات | +|---|---|---| +| **مفاتيح الوصول الثابتة** | البداية، عمليات نشر بحساب واحد | أبسط إعداد؛ يجب تدوير مفاتيح الوصول يدوياً | +| **AssumeRole** | عبر الحسابات، تشديد الإنتاج | بيانات اعتماد قصيرة الأمد؛ يدعم External ID؛ يتطلب دور IAM إضافي | + +تستخدم بقية هذا الدليل علامات تبويب في الخطوات 3–5 لتتمكن من اتباع المسار المطابق لاختيارك. + +## الخطوة 1 — إنشاء مستخدم IAM + +افتح [وحدة تحكم IAM](https://console.aws.amazon.com/iam/)، انتقل إلى **Users**، ثم انقر على **Create user**. + +- الاسم المقترح: `crewai-secrets-reader`. +- اترك **Provide user access to the AWS Management Console** بدون تحديد — هذا الكيان تستخدمه CrewAI Platform برمجياً، وليس البشر. +- انقر على **Next**. + +في صفحة **Set permissions**، اترك الاختيار الافتراضي. ستُرفق السياسة في الخطوة 3. + +انقر على **Next**، راجع، وانقر على **Create user**. + +للتفاصيل الكاملة، راجع وثائق AWS: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). + +{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */} + +## الخطوة 2 — إنشاء سياسة IAM + +تحتاج CrewAI Platform إلى وصول للقراءة فقط إلى AWS Secrets Manager وإذن لفك تشفير الأسرار عبر KMS. أنشئ سياسة يديرها العميل بـ JSON التالي. + +في وحدة تحكم IAM، انتقل إلى **Policies**، ثم انقر على **Create policy**. + +اختر علامة التبويب **JSON** واستبدل المحتوى بـ: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:ListSecrets", + "secretsmanager:GetSecretValue", + "secretsmanager:DescribeSecret" + ], + "Resource": "*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:DescribeKey", + "kms:Decrypt" + ], + "Resource": "*" + } + ] +} +``` + +انقر على **Next**، ثم في صفحة **Review and create**: + +- **Policy name:** `CrewAISecretsManagerRead` +- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform` + +انقر على **Create policy**. + + +تمنح السياسة أعلاه `*` على `Resource` للبساطة. في الإنتاج، حدّد نطاق `Resource` إلى ARNs الخاصة بالأسرار التي يجب على CrewAI Platform الوصول إليها، وحدّد نطاق `kms:Decrypt` إلى ARNs مفاتيح KMS التي تُشفّر تلك الأسرار. راجع [إرشادات AWS حول أقل الامتيازات](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html). + + +{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */} +{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */} + +## الخطوة 3 — إرفاق السياسة + + + + 1. في وحدة تحكم IAM، انتقل إلى **Users** وانقر على المستخدم الذي أنشأته في الخطوة 1. + 2. في علامة التبويب **Permissions**، انقر على **Add permissions** ← **Attach policies directly**. + 3. ابحث عن `CrewAISecretsManagerRead`، حدّدها، وانقر على **Next**. + 4. انقر على **Add permissions**. + + {/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */} + + + + مع AssumeRole، تُرفَق السياسة بـ **دور** IAM منفصل (وليس مباشرة بالمستخدم). يحتاج المستخدم من الخطوة 1 فقط إلى إذن لاستدعاء `sts:AssumeRole` على ذلك الدور. + + **إنشاء الدور:** + + 1. في وحدة تحكم IAM، انتقل إلى **Roles** وانقر على **Create role**. + 2. **Trusted entity type:** AWS account. اختر **This account** (أو **Another AWS account** لإعدادات عبر الحسابات، ثم أدخل معرّف حساب AWS الذي يستضيف مستخدم IAM من الخطوة 1). + 3. (موصى به) حدّد **Require external ID** وأدخل قيمة تُولّدها بنفسك — هذا سر مشترك ستلصقه في CrewAI Platform في الخطوة 5. + 4. انقر على **Next**. + 5. أرفق سياسة `CrewAISecretsManagerRead`. + 6. انقر على **Next**، سمِّ الدور `CrewAISecretsManagerRole`، وانقر على **Create role**. + + **اسمح لمستخدم IAM بافتراض الدور:** + + 1. افتح الدور الذي أنشأته للتو وانسخ **ARN** الخاص به. + 2. في وحدة تحكم IAM، انتقل إلى **Users**، انقر على المستخدم من الخطوة 1، وفي علامة التبويب **Permissions** انقر على **Add permissions** ← **Create inline policy**. + 3. في علامة التبويب **JSON**، الصق ما يلي (استبدل `ROLE_ARN_FROM_ABOVE`): + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "ROLE_ARN_FROM_ABOVE" + } + ] + } + ``` + + 4. سمِّ السياسة `CrewAIAssumeSecretsRole` وانقر على **Create policy**. + + {/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */} + {/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */} + + + +## الخطوة 4 — الحصول على بيانات الاعتماد + + + + 1. في وحدة تحكم IAM، افتح المستخدم من الخطوة 1. + 2. انقر على علامة التبويب **Security credentials**. + 3. تحت **Access keys**، انقر على **Create access key**. + 4. اختر **Application running outside AWS** (أو **Other**) كحالة استخدام. انقر على **Next**. + 5. (اختياري) أضف وسماً وصفياً. انقر على **Create access key**. + 6. انقر على **Show** للكشف عن مفتاح الوصول السري، ثم انسخ كلاً من **Access key ID** و **Secret access key**، أو انقر على **Download .csv file**. + + + يظهر مفتاح الوصول السري مرة واحدة فقط. إذا أغلقت هذه الصفحة دون نسخه، فستحتاج إلى حذف المفتاح وإنشاء واحد جديد. + + + للتفاصيل الكاملة، راجع وثائق AWS: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). + + {/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */} + {/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */} + + + + حتى مع AssumeRole، لا تزال CrewAI Platform تحتاج إلى مفتاح وصول لمستخدم IAM — فهي تستخدم تلك المفاتيح كهوية المتصل لتنفيذ استدعاء `sts:AssumeRole`. + + 1. أنشئ مفتاح وصول للمستخدم تماماً كما هو موضح في علامة التبويب **مفاتيح الوصول الثابتة** أعلاه. + 2. افتح الدور الذي أنشأته في الخطوة 3 وانسخ: + - **Role ARN** (من ملخص الدور). + - **External ID** الذي كوّنته (إن وُجد) — قد عيّنته بنفسك في الخطوة 3، فتأكد من أنه بحوزتك. + + {/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */} + + + +## الخطوة 5 — إضافة بيانات الاعتماد في CrewAI Platform + +في CrewAI Platform، انتقل إلى **Settings** ← **Secret Provider Credentials** وانقر على **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} +{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */} + + + + املأ النموذج: + + - **Name:** اسم وصفي، مثلاً `aws-prod`. + - **Provider:** `AWS Secrets Manager`. + - **Region:** منطقة AWS التي تعيش فيها أسرارك، مثلاً `us-east-1`. يجب أن تطابق منطقة الأسرار التي تريد قراءتها. + - **Access Key ID:** القيمة من الخطوة 4. + - **Secret Access Key:** القيمة من الخطوة 4. + - (اختياري) حدّد **Set as default credential for this provider**. تُستخدم بيانات الاعتماد الافتراضية بواسطة متغيرات البيئة التي تشير إلى أسرار AWS بدون تحديد بيانات اعتماد صراحةً. + + اترك **Role ARN** و **External ID** فارغين. + + انقر على **Create**. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */} + + + + املأ النموذج: + + - **Name:** اسم وصفي، مثلاً `aws-prod-assumerole`. + - **Provider:** `AWS Secrets Manager`. + - **Region:** منطقة AWS التي تعيش فيها أسرارك. + - **Access Key ID:** مفتاح وصول مستخدم IAM من الخطوة 4 (يُستخدم لاستدعاء STS). + - **Secret Access Key:** مفتاح الوصول السري لمستخدم IAM من الخطوة 4. + - **Role ARN:** Role ARN الذي نسخته في الخطوة 4. + - **External ID:** External ID الذي عيّنته على سياسة الثقة الخاصة بالدور (احذفه إن لم يوجد). + - (اختياري) حدّد **Set as default credential for this provider**. + + انقر على **Create**. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */} + + + + +**كيف تتصرف الطريقتان وقت التشغيل:** + +- مع **مفاتيح الوصول الثابتة** فقط، تستدعي CrewAI Platform AWS Secrets Manager مباشرةً باستخدام المفاتيح التي قدّمتها. +- عند تعيين **Role ARN**، تستدعي CrewAI Platform أولاً `sts:AssumeRole` بمفاتيح الوصول المقدَّمة (و External ID إن كان مكوَّناً)، ثم تستخدم بيانات الاعتماد قصيرة الأمد التي تُعيدها STS لقراءة أسرارك. + + +{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */} + +## الخطوة 6 — إنشاء سر واحد على الأقل في AWS + +إذا لم يكن لديك بالفعل أسرار في AWS Secrets Manager، أنشئ واحداً الآن لتتمكن من التحقق من الاتصال في الخطوة 7. + +في [وحدة تحكم AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/)، انقر على **Store a new secret**. + +- **Secret type:** اختر **Other type of secret**. +- **Key/value pairs** — إما: + - إدخال زوج أو أكثر من مفتاح/قيمة (موصى به للأسرار المهيكلة)، أو + - استخدام علامة التبويب **Plaintext** لقيمة نصية واحدة. +- **Encryption key:** استخدم `aws/secretsmanager` (المفتاح الذي يديره AWS) ما لم تكن لديك متطلبات محددة لمفتاح KMS. + +انقر على **Next**، ثم أدخل: + +- **Secret name:** اسم فريد، مثلاً `crewai/openai-api-key`. +- **Description (optional):** ملاحظة قصيرة عن غرض السر. + +انقر على **Next** عبر خطوات التدوير والمراجعة، ثم انقر على **Store**. + + +**صيغة الإشارة بمفتاح JSON.** إذا خزّنت سراً بأزواج مفتاح/قيمة متعددة (كائن JSON)، يمكن لـ CrewAI Platform استخراج حقل محدد باستخدام صيغة `secret-name#json_key` في إشارات متغيرات البيئة. على سبيل المثال، يمكن الإشارة إلى سر باسم `database-credentials` بـ `{"username": "...", "password": "..."}` باسم `database-credentials#password`. راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) للتفاصيل. + + +للتفاصيل الكاملة، راجع وثائق AWS: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + +{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */} +{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */} + +## الخطوة 7 — اختبار الاتصال + +عُد إلى CrewAI Platform، في صفحة **Secret Provider Credentials**، اعثر على بيانات الاعتماد التي أنشأتها للتو وانقر على **Test Connection**. + +تؤكد رسالة نجاح أن CrewAI Platform يمكنها المصادقة مع AWS وقراءة الأسرار من حسابك. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */} + +إذا فشل الاختبار، تحقق من الأسباب الأكثر شيوعاً: + +| العَرَض | السبب المحتمل | +|---|---| +| `AccessDenied` على `secretsmanager:ListSecrets` | السياسة غير مُرفقة، أو المستخدم خاطئ. تحقق من الخطوة 3 من جديد. | +| `AccessDenied` على `kms:Decrypt` | بيان `KMSDecrypt` مفقود، أو أن أسرارك تستخدم مفتاح KMS يديره العميل لا يغطّيه `Resource: "*"`. | +| `InvalidClientTokenId` / `SignatureDoesNotMatch` | معرّف مفتاح الوصول أو مفتاح الوصول السري خاطئ. تحقق من الخطوتين 4 و 5 من جديد. | +| `RegionDisabledException` / لم يُعثر على أسرار | لا تطابق **Region** الخاصة ببيانات الاعتماد المكان الفعلي لأسرارك. | +| `AccessDenied` على `sts:AssumeRole` (AssumeRole فقط) | سياسة `sts:AssumeRole` المضمنة مفقودة على مستخدم IAM، أو لا تسمح سياسة الثقة الخاصة بالدور بهذا الكيان، أو لا يتطابق External ID. | +| ينجح الاختبار فوراً بعد إنشاء مستخدم IAM، لكنه يفشل في المرة التالية | تستغرق بيانات اعتماد IAM أحياناً دقيقة أو دقيقتين للانتشار عالمياً. أعد المحاولة. | + +## الخطوات التالية + +الآن وقد اتصلت AWS، توجّه إلى [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage) من أجل: + +- منح أعضاء المؤسسة الأذونات الصحيحة لاستخدام (أو إدارة) مدير الأسرار. +- الإشارة إلى أسرار AWS الخاصة بك من متغيرات بيئة CrewAI Platform. + +إذا كنت تريد أسراراً **مراعية للتدوير** تنتشر دون إعادة نشر، انتقل إلى [AWS Workload Identity (اتحاد OIDC)](/ar/enterprise/features/secrets-manager/aws-workload-identity) — نفس مخزن الأسرار، بدون بيانات اعتماد ثابتة، وتُجلب الأسرار في كل إطلاق. diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/azure-workload-identity.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/azure-workload-identity.mdx new file mode 100644 index 000000000..4492d6d0c --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/azure-workload-identity.mdx @@ -0,0 +1,275 @@ +--- +title: Azure Workload Identity Federation +description: تكوين Azure Key Vault عبر Microsoft Entra Workload Identity Federation للوصول إلى الأسرار بشكل مراعٍ للتدوير وبدون بيانات اعتماد +sidebarTitle: بـ Workload Identity +icon: "id-badge" +--- + +## نظرة عامة + +يُكوِّن هذا الدليل Azure Key Vault كمزود أسرار باستخدام **Microsoft Entra Workload Identity Federation**: تُصدر CrewAI Platform رموز OIDC قصيرة الأمد، وتُبادلها للحصول على رمز وصول Entra عبر منصة هوية Microsoft، وتقرأ أسرارك — دون تخزين أي سر عميل في أي مكان. + + +**لماذا هذا المسار:** تُحَلّ الأسرار وقت تنفيذ الأتمتة، لذا **تنتشر القيم المُدوَّرة إلى الإطلاق التالي بدون إعادة نشر**. إن كنت تحتاج فقط بيانات اعتماد ثابتة، راجع الدليل الأبسط [Azure Key Vault — سر العميل](/ar/enterprise/features/secrets-manager/azure). + + +### كيف يعمل وقت التشغيل + +1. يطلب عامل النشر JWT OIDC طازج من CrewAI Platform. +2. يُقدّم العامل الـ JWT إلى Microsoft Entra على `https://login.microsoftonline.com//oauth2/v2.0/token` كـ `client_assertion` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`)، مع الإشارة إلى App Registration الذي يطابق **Federated Identity Credential** الخاص به مُصدر الـ JWT وموضوعه. +3. تتحقق Entra من الـ JWT مقابل وثيقة اكتشاف OIDC و JWKS لمنصتك، ثم تُعيد رمز وصول قصير الأمد محصور بـ `https://vault.azure.net/.default`. +4. يستدعي العامل Azure Key Vault لقراءة السر. +5. تُحقن القيمة المجلوبة كقيمة لمتغير البيئة لإطلاق الأتمتة ذاك. + +تُخزَّن رموز موضوع OIDC مؤقتاً لنحو ساعة لتفادي إعادة الإصدار في كل إطلاق. تُجلب قيم الأسرار طازجة في كل إطلاق بغض النظر عن حالة ذاكرة OIDC المؤقتة، وهذا ما يجعل هذا المسار مراعياً للتدوير. + +## المتطلبات المسبقة + + +قبل البدء، تأكد من امتلاكك: + +- يجب أن تتضمن صورة حاوية الأتمتة إصدار CrewAI runtime رقم `1.14.5` أو أحدث. +- اشتراك Azure ومستأجر Microsoft Entra يمكنك إدارته. +- إذن في المستأجر لإنشاء App Registrations وإضافة Federated Identity Credentials. +- Key Vault يستخدم **Azure RBAC** للترخيص (وليس النموذج القديم لسياسة الوصول). +- مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذني `workload_identity_configs: manage` و `secret_providers: manage`. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac). +- **يجب أن يكون تنصيب CrewAI Platform قابلاً للوصول من Microsoft Entra عبر HTTPS** ليتمكّن Entra من جلب وثيقة اكتشاف OIDC و JWKS أثناء التحقق من الرمز. تأكد مع مسؤول المنصة من أن المضيف متاح عبر الإنترنت. + + +## الخطوة 1 — العثور على عنوان مُصدر OIDC لـ CrewAI Platform + +ينشر تنصيب CrewAI Platform وثيقة اكتشاف OpenID Connect على `https:///.well-known/openid-configuration`. الحقل `issuer` هناك هو الرابط الذي ستُسجِّله Microsoft Entra كمُصدر اتحاد موثوق. + +افتح الرابط في المتصفح: + +``` +https:///.well-known/openid-configuration +``` + +ينبغي أن ترى JSON يحتوي على: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +سجّل القيمة الدقيقة لـ `issuer` — ستستخدمها في الخطوة 3. + + +إذا أعاد الرابط 404 أو 503، اتصل بمسؤول المنصة. يتطلب مُصدر OIDC تكوين مفتاح توقيع خاص وقت التنصيب. راجع دليل تنصيب المنصة لتكوين `OIDC_PRIVATE_KEY` و `OIDC_ISSUER`. + + +## الخطوة 2 — إنشاء App Registration + +في [بوابة Microsoft Entra](https://entra.microsoft.com)، انتقل إلى **App registrations** وانقر على **New registration**. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- اترك **Redirect URI** فارغاً. + +انقر على **Register**. سجّل **Application (client) ID** و **Directory (tenant) ID** في لوحة نظرة عامة التطبيق — ستستخدمها في الخطوة 6. + +{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */} + +## الخطوة 3 — إضافة Federated Identity Credential + +يُخبر Federated Identity Credential Microsoft Entra: *ثِق برموز JWT المُصدَرة من هذا المُصدر، بهذا الموضوع، عندما تُقدَّم كتأكيد عميل لهذا App Registration.* + +في App Registration، انتقل إلى **Certificates & secrets** ← **Federated credentials** ← **Add credential**. + +- **Federated credential scenario:** `Other issuer`. +- **Issuer:** رابط مُصدر CrewAI Platform من الخطوة 1، مثلاً `https://`. +- **Subject identifier:** `organization:` — قيمة ادّعاء `sub` في JWT بالضبط. اعثر على UUID مؤسستك في إعدادات مؤسسة CrewAI Platform. يقصر هذا الاتحاد على مؤسسة CrewAI محددة — تُقبل فقط الرموز المُصدَرة لأتمتات تلك المؤسسة. +- **Name:** أي تسمية وصفية، مثلاً `crewai-org-prod`. +- **Audience:** `api://AzureADTokenExchange`. هذا هو الجمهور الثابت الذي تتطلبه Microsoft Entra للبيانات الموحَّدة، وهو ما تُعيّنه CrewAI Platform في ادّعاء `aud` في JWT. + +انقر على **Add**. + + +**العزل لكل مؤسسة.** يقيّد معرّف الموضوع (`organization:`) Federated Identity Credential لرموز مؤسسة CrewAI محددة. إذا كان من المفترض أن تتشارك مؤسسات CrewAI متعددة App Registration واحداً، أضف Federated Identity Credential لكل مؤسسة (كل منها بـ UUID المؤسسة). + + +للتفاصيل الكاملة، راجع وثائق Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust). + +{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */} + +## الخطوة 4 — منح App Registration وصولاً إلى Key Vault + +امنح App Registration دور **Key Vault Secrets User** على الخزنة المستهدفة — نفس الدور الذي تستخدمه لمسار بيانات الاعتماد الثابتة. استخدم إما على مستوى الخزنة (أبسط) أو لكل سر (أقل الامتيازات). + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + يمنح النطاق على مستوى الخزنة إذن `secrets/list` الذي يعتمد عليه **الاقتراح التلقائي لاسم السر** في نموذج متغير البيئة لـ CrewAI Platform. اختر هذه التبويبة إذا أردت أن يعمل الاقتراح التلقائي. + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */} + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + تُعطّل الارتباطات لكل سر **الاقتراح التلقائي لاسم السر** في نموذج متغير البيئة لـ CrewAI Platform (يتطلب الاقتراح التلقائي `secrets/list`، وهو محصور بنطاق الخزنة فقط). اكتب اسم السر الكامل بدلاً من ذلك. + + {/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */} + + + + لتعيين **على مستوى الخزنة**: + + 1. افتح Key Vault الخاص بك في بوابة Azure. + 2. انقر على **Access control (IAM)** ← **Add** ← **Add role assignment**. + 3. اختر الدور **Key Vault Secrets User** ← **Next**. + 4. انقر على **Select members**، ابحث عن App Registration `crewai-secrets-reader`، انقر على **Select**. + 5. انقر على **Review + assign**. + + لتعيين **لكل سر**، استخدم نفس التدفق لكن ابدأ من **Objects** ← **Secrets** ← اختر السر ← لوحة **Access control (IAM)** الخاصة به. تُعطّل الارتباطات لكل سر الاقتراح التلقائي (راجع تبويبة لكل سر أعلاه). + + + +## الخطوة 5 — إنشاء سر واحد على الأقل في Key Vault + +إذا لم يكن لديك سر للاختبار، أنشئ واحداً عبر Azure CLI: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + +أو عبر بوابة Azure: + +1. افتح Key Vault الخاص بك وانتقل إلى **Objects** ← **Secrets**. +2. انقر على **Generate/Import**. +3. **Upload options:** `Manual`. **Name:** اسم السر (مثلاً `openai-api-key`). **Secret value:** الصق القيمة. +4. انقر على **Create**. + + +**اصطلاحات اسم السر.** لا يمكن أن تحتوي أسماء أسرار Azure Key Vault على شرطات سفلية. تُحوّل CrewAI Platform تلقائياً الشرطات السفلية إلى شرطات عند استدعاء Azure (مثلاً، `db_password` تُرسل كـ `db-password`)، لذا يمكنك الاحتفاظ بأسماء متغيرات بيئة بنمط الشرطة السفلية — لكن السر الأساسي في Key Vault يجب أن يستخدم الشرطات. + + +## الخطوة 6 — إضافة تكوين Workload Identity في CrewAI Platform + +في CrewAI Platform، انتقل إلى **Settings** ← **Workload Identity** وانقر على **Add Workload Identity Config**. + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `azure-prod`. +- **Cloud Provider:** `Azure`. +- **Tenant ID:** **Directory (tenant) ID** الخاص بـ Microsoft Entra من الخطوة 2. +- **Client ID:** **Application (client) ID** الخاص بـ App Registration من الخطوة 2. +- (اختياري) حدّد **Set as default for Azure** إذا كنت ترغب في أن يكون هذا هو تكوين WI الافتراضي المُحدَّد عند إنشاء بيانات اعتماد سر مدعومة بـ Azure. + +**Audience** ثابت على `api://AzureADTokenExchange` — تتطلب Microsoft Entra هذا الجمهور بالضبط للبيانات الموحَّدة، لذا لا يظهر حقل Audience في النموذج. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */} +{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */} + +## الخطوة 7 — إضافة بيانات اعتماد مزود أسرار مرتبطة بتكوين WI + +انتقل إلى **Settings** ← **Secret Provider Credentials** وانقر على **Add Credential**. + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `azure-prod-wi`. +- **Provider:** `Azure Key Vault`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** اختر التكوين الذي أنشأته في الخطوة 6. +- **Key Vault URL:** اسم مضيف DNS للخزنة، مثلاً `https://my-vault.vault.azure.net`. +- (اختياري) حدّد **Set as default credential for this provider**. + +سيطلب النموذج فقط **Key Vault URL** ضمن Workload Identity — حقول بيانات الاعتماد الثابتة (Tenant ID و Client ID و Client Secret) مخفية عمداً لأنها لا تنطبق على هذا المسار؛ يأتي المستأجر والعميل من تكوين WI المرتبط. + +انقر على **Create**. + + +**App Registration واحد، خزائن متعددة.** يعيش Key Vault URL على بيانات الاعتماد، وليس على تكوين WI. لذا يمكن لـ App Registration واحد (وتكوين WI واحد) خدمة عدة Key Vaults — فقط أنشئ بيانات اعتماد مزود أسرار واحدة لكل خزنة، جميعها مرتبطة بنفس تكوين WI. + + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */} + +## الخطوة 8 — اختبار الاتصال + +بعد حفظ بيانات الاعتماد، انقر على **Test Connection**. لبيانات اعتماد workload-identity، يتحقق هذا من مصافحة OIDC: تُصدر CrewAI Platform JWT، وتُقدّمه إلى Microsoft Entra كـ `client_assertion` موحَّد، وتؤكد أن Entra تُعيد رمز وصول محصور بالخزنة. نتيجة خضراء تعني أن ارتباط الاتحاد سليم. + +نجاح Test Connection يُثبت أن مُصدر Federated Identity Credential وموضوعه وجمهوره كلها متطابقة، وأن App Registration قابل للوصول. لا يُثبت ذلك أن RBAC لكل سر في Key Vault صحيح — يُمارَس `getSecret` على سر محدد بشكل منفصل عندما يُحَلّ متغير بيئة عند الإطلاق. راجع [استكشاف الأخطاء](#troubleshooting) لأنماط فشل المصافحة. + +## الخطوة 9 — الإشارة إلى السر في متغير بيئة + +أَشِر إلى السر على أتمتة، تماماً كما تفعل مع أي متغير بيئة مدعوم بمدير أسرار. راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) لحقول النموذج والسلوك. + +## الخطوة 10 — التحقق من التدوير + +بعد تشغيل عملية النشر، دوّر السر في Key Vault: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "rotated value" +``` + +أطلق إطلاق أتمتة جديداً. ستكون بيئة الإطلاق ترى `"rotated value"` — بدون إعادة نشر ولا إعادة تشغيل عامل ولا انتظار TTL. + +للتأكد في سجلات العامل، ابحث عن: + +``` +Workload identity config '' (azure): N secret(s) resolved +``` + +يظهر هذا السطر لكل إطلاق ويُشير إلى استدعاء `getSecret` طازج مقابل Azure Key Vault. + +للتحقق من البداية إلى النهاية باستخدام البصمة، راجع [التحقق من التدوير من البداية إلى النهاية](/ar/enterprise/features/secrets-manager/verify-rotation). + +## استكشاف الأخطاء + +| العَرَض | السبب المحتمل | +|---|---| +| يفشل Test Connection بخطأ مصافحة | رفضت Microsoft Entra `client_assertion` الموحَّد. تحقق من أن **Issuer** في Federated Identity Credential يطابق قيمة `issuer` للمنصة بالضبط، وأن **Subject** هو `organization:` (يطابق ادّعاء `sub` في JWT)، وأن **Audience** هو `api://AzureADTokenExchange`، وأن رابط اكتشاف OIDC للمنصة قابل للوصول من Entra عبر الإنترنت العام. | +| `AADSTS70021: No matching federated identity record found for presented assertion` | لا يتطابق **Issuer** + **Subject** + **Audience** في Federated Identity Credential مع الـ JWT بالضبط. تحقق من الخطوة 3 من جديد: يجب أن يكون الموضوع `organization:` (يطابق ادّعاء `sub` في JWT)، ويجب أن يكون الجمهور `api://AzureADTokenExchange`. | +| `AADSTS700024: Client assertion is not within its valid time range` | ساعة مضيف CrewAI Platform منحرفة بشكل كبير عن الوقت الحقيقي. تحقق من NTP على المضيف. | +| `AADSTS50013: Assertion failed signature validation` | لم تستطع Microsoft Entra التحقق من توقيع الـ JWT. تأكد من أن `https:///oauth2/jwks` قابل للوصول من الإنترنت العام ويُقدّم JWKS صالحاً. | +| يُظهر الاقتراح التلقائي لاسم السر `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` | دور **Key Vault Secrets User** الخاص بـ App Registration محصور بسر واحد. امنح الدور على نطاق الخزنة ليُسمح بإجراء `list` في مستوى البيانات. راجع الخطوة 4. | +| يفشل الإطلاق في حلّ سر رغم نجاح Test Connection | ارتباط WI سليم، لكن RBAC لكل سر في Key Vault مفقود على السر الفاشل. راجع **Key Vault Secrets User** على ذلك السر تحديداً (أو وسّع تعيين الدور إلى نطاق الخزنة). | +| `Forbidden — request was not authorized` (الخزنة تستخدم سياسات الوصول القديمة) | لم يتم تحويل الخزنة إلى Azure RBAC. ضمن **Access configuration** للخزنة، عيّن نموذج الإذن إلى **Azure role-based access control** وأعد منح الدور من الخطوة 4. | +| `azure_vault_url is required for Azure secret resolution` (سجلات العامل) | تفتقد بيانات اعتماد مزود الأسرار إلى **Key Vault URL**. تحقق من الخطوة 7 من جديد. | +| لا تُلتقط القيمة المُدوَّرة في الإطلاق التالي | تأكد من أن متغير البيئة على الأتمتة يشير إلى بيانات اعتماد مدعومة بـ Workload Identity (وليس بيانات اعتماد بمفاتيح ثابتة). يدمج المسار الثابت القيم في صورة النشر. | + +### روابط مرجعية + +- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) +- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust) +- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) + +## الخطوات التالية + +- [استخدام الأسرار في متغيرات البيئة وإدارة الأذونات](/ar/enterprise/features/secrets-manager/usage) +- للتنوع متعدد السحاب، إعداد ما يعادله لـ AWS موجود في [AWS Workload Identity (اتحاد OIDC)](/ar/enterprise/features/secrets-manager/aws-workload-identity) وما يعادله لـ GCP في [GCP Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity). + +## مرجع لقطات الشاشة + +تُربط العناصر النائبة أعلاه بـ: + +- `01-register-app.png` — نموذج "Register an application" في بوابة Azure مع `crewai-secrets-reader`. +- `02-add-federated-credential.png` — App Registration ← Certificates & secrets ← Federated credentials ← Add credential، مع **Other issuer**، رابط مُصدر المنصة، الموضوع `organization:`، الجمهور `api://AzureADTokenExchange`. +- `03-grant-vault-rbac.png` — Key Vault ← Access control (IAM) ← Add role assignment، مع **Key Vault Secrets User** و App Registration المختار. +- `04-per-secret-rbac.png` — نفس النموذج لكن في نطاق IAM سر واحد (مسار أقل الامتيازات البديل). +- `05-amp-add-wi-config-azure.png` — نموذج "Add Workload Identity Config" في CrewAI Platform مع Cloud Provider = Azure و Tenant ID و Client ID مأهولين. +- `06-amp-wi-list-with-azure.png` — صفحة قائمة Workload Identity بعد الإنشاء، تُظهر صفوفاً لـ AWS و GCP وتكوين Azure الجديد. +- `07-amp-add-credential-azure-wi.png` — نموذج "Add Secret Provider Credential" مع Provider = Azure Key Vault، Auth = Workload Identity، تكوين WI المختار، و Key Vault URL مأهول. diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/azure.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/azure.mdx new file mode 100644 index 000000000..dbc619da8 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/azure.mdx @@ -0,0 +1,196 @@ +--- +title: Azure Key Vault +description: تكوين Azure Key Vault كمزود أسرار لـ CrewAI Platform من البداية إلى النهاية +sidebarTitle: ببيانات اعتماد ثابتة +icon: "key" +--- + +## نظرة عامة + +يأخذك هذا الدليل عبر تكوين Azure Key Vault كمزود أسرار لمؤسستك على CrewAI Platform، باستخدام **App Registration في Microsoft Entra مع سر عميل**. بنهاية الدليل، ستتمكن CrewAI Platform من قراءة الأسرار المخزّنة في Azure Key Vault الخاص بك وحقنها كقيم متغيرات بيئة وقت التشغيل. + + +يغطي هذا الدليل مسار **بيانات الاعتماد الثابتة** — تُحَلّ الأسرار وقت النشر وتُدمج في صورة النشر. تتطلب القيم المُدوَّرة إعادة نشر. إذا أردت أسراراً مراعية للتدوير تُحدَّث في كل إطلاق أتمتة، راجع [Azure Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity). + + + +يغطي هذا الدليل التكوين من جانب Azure وإعداد بيانات الاعتماد في CrewAI Platform. للإشارة بعدها إلى سر من متغير بيئة، راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage). + + +## المتطلبات المسبقة + + +قبل البدء، تأكد من امتلاكك: + +- اشتراك Azure لديه إذن إنشاء App Registrations في Microsoft Entra ومنح تعيينات أدوار على موارد Key Vault. +- Key Vault يستخدم **Azure RBAC** للترخيص (وليس النموذج القديم لسياسة الوصول). إذا كان الخزنة لا تزال تستخدم سياسات الوصول، فحوّلها إلى RBAC ضمن لوحة **Access configuration** للخزنة. +- مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذن `secret_providers: manage`. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## الخطوة 1 — إنشاء App Registration + +App Registration هي الهوية من جانب Microsoft Entra التي ستُصادق بها CrewAI Platform. + +في [بوابة Microsoft Entra](https://entra.microsoft.com)، انتقل إلى **App registrations** وانقر على **New registration**. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- اترك **Redirect URI** فارغاً. + +انقر على **Register**. سجّل **Application (client) ID** و **Directory (tenant) ID** في لوحة نظرة عامة التطبيق — ستلصق كليهما في CrewAI Platform في الخطوة 4. + +للتفاصيل الكاملة، راجع وثائق Microsoft: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). + +{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */} + +## الخطوة 2 — إنشاء سر عميل + +في App Registration، انتقل إلى **Certificates & secrets** ← **Client secrets** ← **New client secret**. + +- **Description:** `crewai-platform` +- **Expires:** اختر مدة تتطابق مع سياسة التدوير لديك (تحدّد Microsoft هذا بـ 24 شهراً كحد أقصى). + +انقر على **Add**. انسخ عمود **Value** فوراً — لا يمكن إعادة عرضه أبداً بمجرد مغادرة الصفحة. + + +أسرار العميل هي بيانات اعتماد ثابتة طويلة الأمد. خزّن القيمة بأمان (في مدير كلمات مرور أو مخزن أسرارك الخاص) ودوّرها قبل انتهاء الصلاحية. للقضاء على بيانات الاعتماد الثابتة تماماً، استخدم [Azure Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity) بدلاً من ذلك. + + +{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */} + +## الخطوة 3 — منح App Registration وصولاً إلى Key Vault + +تحتاج CrewAI Platform إلى وصول قراءة للأسرار في Key Vault الخاص بك. استخدم أحد نطاقين — **على مستوى الخزنة** للبساطة، أو **لكل سر** لأقل الامتيازات. + + + + في [وحدة تحكم Key Vault](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults)، افتح الخزنة الهدف، ثم انتقل إلى **Access control (IAM)** ← **Add** ← **Add role assignment**. + + - **Role:** **Key Vault Secrets User** + - **Assign access to:** User, group, or service principal + - **Members:** ابحث عن App Registration الخاص بك (`crewai-secrets-reader`) واختره. + + انقر على **Review + assign**. + + أو عبر Azure CLI: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */} + + + + امنح الدور على مستوى سر فردي. كرّر لكل سر ينبغي أن تصل إليه CrewAI Platform: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */} + + + + +يسمح دور **Key Vault Secrets User** بقراءة قيم الأسرار لكن ليس سرد جميع الأسرار في الخزنة. يستدعي الاقتراح التلقائي لاسم السر في CrewAI Platform أيضاً `list` — هذا الإذن مُضمَّن في الدور على نطاق الخزنة، لكن **ليس** على نطاق لكل سر. مع ارتباطات لكل سر، لن يقترح الإكمال التلقائي أسراراً؛ اكتب اسم السر الكامل بدلاً من ذلك. + + +## الخطوة 4 — إضافة بيانات الاعتماد في CrewAI Platform + +في CrewAI Platform، انتقل إلى **Settings** ← **Secret Provider Credentials** وانقر على **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `azure-prod`. +- **Provider:** `Azure Key Vault`. +- **Key Vault URL:** اسم مضيف DNS للخزنة، مثلاً `https://my-vault.vault.azure.net`. +- **Tenant ID:** **Directory (tenant) ID** الخاص بـ Microsoft Entra من الخطوة 1. +- **Client ID:** **Application (client) ID** الخاص بـ App Registration من الخطوة 1. +- **Client Secret:** **Value** الذي نسخته في الخطوة 2. +- (اختياري) حدّد **Set as default credential for this provider**. تُستخدم بيانات الاعتماد الافتراضية بواسطة متغيرات البيئة التي تشير إلى أسرار Azure بدون تحديد بيانات اعتماد صراحةً. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */} + +## الخطوة 5 — إنشاء سر واحد على الأقل في Azure Key Vault + +إذا لم يكن لديك بالفعل أسرار في Key Vault، أنشئ واحداً الآن لتتمكن من التحقق من الاتصال في الخطوة 6. + +في وحدة تحكم Key Vault، انتقل إلى **Objects** ← **Secrets** ← **Generate/Import**. + +- **Upload options:** `Manual` +- **Name:** مثلاً `openai-api-key` +- **Secret value:** الصق قيمة سرّك +- اترك الباقي على القيم الافتراضية. + +انقر على **Create**. + +أو عبر Azure CLI: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + + +**اصطلاحات اسم السر.** لا يمكن أن تحتوي أسماء أسرار Azure Key Vault على شرطات سفلية. تُحوّل CrewAI Platform تلقائياً الشرطات السفلية إلى شرطات عند استدعاء Azure (مثلاً، `db_password` تُرسل كـ `db-password`)، لذا يمكنك الاحتفاظ بأسماء متغيرات بيئة بنمط الشرطة السفلية — لكن السر الأساسي في Key Vault يجب أن يستخدم الشرطات. + + + +**صيغة الإشارة بمفتاح JSON.** يتعامل Key Vault مع قيم الأسرار كسلاسل معتمة. إذا حدث أن كانت قيمة سرّك كائن JSON، يمكن لـ CrewAI Platform استخراج حقل واحد باستخدام صيغة `secret-name#json_key` (مثلاً `database-credentials#password`). راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) للتفاصيل. + + +للتفاصيل الكاملة، راجع وثائق Microsoft: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli). + +{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */} + +## الخطوة 6 — اختبار الاتصال + +عُد إلى CrewAI Platform، في صفحة **Secret Provider Credentials**، اعثر على بيانات الاعتماد التي أنشأتها للتو وانقر على **Test Connection**. + +تؤكد رسالة نجاح أن CrewAI Platform يمكنها المصادقة مع Microsoft Entra وقراءة الأسرار من خزنتك. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */} + +إذا فشل الاختبار، تحقق من الأسباب الأكثر شيوعاً: + +| العَرَض | السبب المحتمل | +|---|---| +| `AADSTS7000215: Invalid client secret provided` | **Client Secret** الملصوق خاطئ أو منتهي الصلاحية. أعد إنشاء السر (الخطوة 2) وحدّث بيانات الاعتماد. | +| `AADSTS700016: Application not found in the directory` | لا يطابق **Tenant ID** أو **Client ID** الـ App Registration. تحقق من الخطوة 4 من جديد. | +| `Forbidden — caller does not have permission` | يفتقد App Registration إلى دور **Key Vault Secrets User** على الخزنة (أو لكل سر). تحقق من الخطوة 3 من جديد. | +| `Vault not found` / أخطاء DNS | **Key Vault URL** خاطئ، أو أن خزنتك لديها نقاط نهاية خاصة تمنع الوصول العام. تأكد من أن المضيف يستجيب لـ `curl https://.vault.azure.net/secrets?api-version=7.4`. | +| `Forbidden — request was not authorized` (الخزنة تستخدم سياسات الوصول القديمة) | لم يتم تحويل الخزنة إلى Azure RBAC. ضمن **Access configuration** للخزنة، عيّن نموذج الإذن إلى **Azure role-based access control** وأعد منح الدور من الخطوة 3. | + +## الخطوات التالية + +الآن وقد اتصل Azure Key Vault، توجّه إلى [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage) من أجل: + +- منح أعضاء المؤسسة الأذونات الصحيحة لاستخدام (أو إدارة) مدير الأسرار. +- الإشارة إلى أسرار Azure الخاصة بك من متغيرات بيئة CrewAI Platform. + +إذا كنت تريد أسراراً **مراعية للتدوير** تنتشر دون إعادة نشر، انتقل إلى [Azure Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity) — نفس الخزنة، بدون سر عميل للتدوير، وتُجلب الأسرار في كل إطلاق. + +## مرجع لقطات الشاشة + +تُربط العناصر النائبة أعلاه بـ: + +- `01-register-app.png` — نموذج "Register an application" في بوابة Azure مع `crewai-secrets-reader`. +- `02-create-client-secret.png` — App Registration ← Certificates & secrets ← Client secrets، مع صف السر المُنشأ حديثاً (عمود Value مُميَّز قبل تمويهه). +- `03-grant-vault-rbac.png` — Key Vault ← Access control (IAM) ← Add role assignment، مع اختيار **Key Vault Secrets User** و App Registration كعضو. +- `04-per-secret-rbac.png` — نفس اللوحة لكن بنطاق سر واحد (مسار أقل الامتيازات البديل). +- `05-amp-add-credential-form-azure.png` — نموذج "Add Secret Provider Credential" في CrewAI Platform: Provider = Azure Key Vault، جميع الحقول الخمسة مأهولة. +- `06-create-secret.png` — لوحة "Create a secret" في Azure Key Vault مع `openai-api-key` وقيمة ملصوقة. +- `07-test-connection-success.png` — رسالة نجاح / حالة صف في CrewAI Platform بعد النقر على **Test Connection** على بيانات الاعتماد. diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/gcp-workload-identity.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/gcp-workload-identity.mdx new file mode 100644 index 000000000..6a0b8d13a --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/gcp-workload-identity.mdx @@ -0,0 +1,273 @@ +--- +title: GCP Workload Identity Federation +description: تكوين Google Cloud Secret Manager عبر Workload Identity Federation للوصول إلى الأسرار بشكل مراعٍ للتدوير وبدون بيانات اعتماد +sidebarTitle: بـ Workload Identity +icon: "id-badge" +--- + +## نظرة عامة + +يُكوِّن هذا الدليل Google Cloud Secret Manager كمزود أسرار باستخدام **Workload Identity Federation**: تُصدر CrewAI Platform رموز OIDC قصيرة الأمد، وتُبادلها للحصول على بيانات اعتماد Google Cloud عبر خدمة Security Token Service، وتقرأ أسرارك — دون تخزين أي مفتاح حساب خدمة طويل الأمد في أي مكان. + + +**لماذا هذا المسار:** تُحَلّ الأسرار وقت تنفيذ الأتمتة، لذا **تنتشر القيم المُدوَّرة إلى الإطلاق التالي بدون إعادة نشر**. إن كنت تحتاج فقط بيانات اعتماد ثابتة، راجع الدليل الأبسط [GCP — مفتاح حساب الخدمة](/ar/enterprise/features/secrets-manager/gcp). + + +### كيف يعمل وقت التشغيل + +1. يطلب عامل النشر JWT OIDC طازج من CrewAI Platform. +2. يبادل العامل الـ JWT للحصول على بيانات اعتماد Google موحَّدة عبر [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest)، مع الإشارة إلى Workload Identity Pool Provider الذي ستُعدّه أدناه. +3. يستدعي العامل `secretmanager.googleapis.com:accessSecretVersion` لقراءة السر، باستخدام بيانات الاعتماد الموحَّدة مباشرةً (يمتلك الكيان الموحَّد `roles/secretmanager.secretAccessor` — راجع الخطوة 4). +4. تُحقن القيمة المجلوبة كقيمة لمتغير البيئة لإطلاق الأتمتة ذاك. + +تُخزَّن رموز موضوع OIDC مؤقتاً لنحو ساعة لتفادي إعادة الإصدار في كل إطلاق. تُجلب قيم الأسرار طازجة في كل إطلاق بغض النظر عن حالة ذاكرة OIDC المؤقتة، وهذا ما يجعل هذا المسار مراعياً للتدوير. + +## المتطلبات المسبقة + + +قبل البدء، تأكد من امتلاكك: + +- يجب أن تتضمن صورة حاوية الأتمتة إصدار CrewAI runtime رقم `1.14.5` أو أحدث. +- مشروع Google Cloud مع تفعيل **Secret Manager API** و **Security Token Service API** و **IAM Credentials API**. فعّلها عبر الوحدة أو: + + ```bash + gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \ + --project= + ``` + +- إذن في المشروع لإنشاء Workload Identity Pools وأدوار IAM وحسابات الخدمة و(إن لزم) الأسرار. +- مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذني `workload_identity_configs: manage` و `secret_providers: manage`. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac). +- **يجب أن يكون تنصيب CrewAI Platform قابلاً للوصول من Google Cloud عبر HTTPS** ليتمكّن GCP STS من جلب وثيقة اكتشاف OIDC و JWKS أثناء التحقق من الرمز. تأكد مع مسؤول المنصة من أن المضيف متاح عبر الإنترنت. + + +## الخطوة 1 — العثور على عنوان مُصدر OIDC لـ CrewAI Platform + +ينشر تنصيب CrewAI Platform وثيقة اكتشاف OpenID Connect على `https:///.well-known/openid-configuration`. الحقل `issuer` هناك هو الرابط الذي ستُسجِّله Google كمزود OIDC موثوق. + +افتح الرابط في المتصفح: + +``` +https:///.well-known/openid-configuration +``` + +ينبغي أن ترى JSON يحتوي على: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +سجّل القيمة الدقيقة لـ `issuer` — ستستخدمها في الخطوة 3. + + +إذا أعاد الرابط 404 أو 503، اتصل بمسؤول المنصة. يتطلب مُصدر OIDC تكوين مفتاح توقيع خاص وقت التنصيب. راجع دليل تنصيب المنصة لتكوين `OIDC_PRIVATE_KEY` و `OIDC_ISSUER`. + + +## الخطوة 2 — إنشاء Workload Identity Pool + +Workload Identity Pool هو حاوية من جانب Google Cloud للهويات الخارجية الموثوقة. ستُسجِّل CrewAI Platform كمزود داخل هذه الحوض. + +```bash +gcloud iam workload-identity-pools create crewai-pool \ + --project= \ + --location=global \ + --display-name="CrewAI Platform" +``` + +أو في [وحدة تحكم Workload Identity Pools](https://console.cloud.google.com/iam-admin/workload-identity-pools)، انقر على **Create Pool**. + +{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */} + +## الخطوة 3 — إضافة CrewAI Platform كمزود OIDC في الحوض + +```bash +gcloud iam workload-identity-pools providers create-oidc crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --display-name="CrewAI Platform OIDC" \ + --issuer-uri="https://" \ + --attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \ + --attribute-condition="assertion.organization_id != ''" +``` + +يُخبر `--attribute-mapping` Google كيفية ربط ادّعاءات JWT بسمات Google: +- `google.subject` هو معرّف الكيان — نربطه بادّعاء `sub` في JWT، الذي تُعيّنه CrewAI Platform إلى `organization:`. +- `attribute.organization` هو سمة مخصصة — نربطها بادّعاء `organization_id` في JWT لتتمكّن من الإشارة إليها في ارتباطات IAM لاحقاً. + +`--attribute-condition` هو فحص دفاع في العمق يرفض الرموز التي تفتقد لادّعاء `organization_id`. + +احصل على **اسم مورد المزود** (ستحتاجه للجمهور وارتباطات IAM): + +```bash +gcloud iam workload-identity-pools providers describe crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --format="value(name)" +``` + +يبدو الناتج هكذا: + +``` +projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider +``` + +هذه هي قيمة **Workload Identity Provider** الخاصة بك في CrewAI Platform في الخطوة 6. تحسب CrewAI Platform تلقائياً جمهور OIDC كـ `//iam.googleapis.com/` عند إصدار الرموز. + +{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */} + +## الخطوة 4 — منح الوصول إلى Secret Manager للكيان الموحَّد + +اربط دوري Secret Manager كليهما على نطاق المشروع بالكيان الموحَّد — دور يُفعّل الاقتراح التلقائي لاسم السر في نموذج متغير البيئة، والآخر يسمح بقراءة قيم الأسرار عند إطلاق الأتمتة. كلاهما مطلوبان لتعمل الميزة من البداية إلى النهاية. + +```bash +PRINCIPAL_SET="principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools/crewai-pool/attribute.organization/" + +# Required for the Secret Name autocomplete (calls secretmanager.secrets.list) +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.viewer" + +# Required to read secret values at kickoff +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" +``` + +استبدل `` برقم المشروع الرقمي (`gcloud projects describe --format='value(projectNumber)'`) و `` بـ UUID مؤسسة CrewAI Platform التي يجب أن يُسمح لها بقراءة أسرارك. يمكنك العثور على UUID المؤسسة في واجهة المنصة في صفحة إعدادات المؤسسة، أو عبر الـ API. يقصر هذا الاتحاد على مؤسسة CrewAI محددة — تُقبل فقط الرموز المُصدَرة لأتمتات تلك المؤسسة. + +أو عبر وحدة تحكم Google Cloud: + +1. افتح **IAM & Admin** ← **IAM** لمشروعك. +2. انقر على **GRANT ACCESS**. +3. **New principals:** الصق سلسلة `principalSet://...attribute.organization/` الكاملة. +4. عيّن الدور **Secret Manager Viewer** (`roles/secretmanager.viewer`). +5. انقر على **SAVE**. +6. انقر على **GRANT ACCESS** مرة أخرى وكرّر مع الدور **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + +**العزل لكل مؤسسة.** يقيّد النمط `principalSet://...attribute.organization/` الوصول إلى رموز مؤسسة محددة. إذا كانت لديك مؤسسات CrewAI متعددة تتشارك مشروع Google Cloud واحد، كرّر كلا الارتباطين لكل مؤسسة بالـ UUID الصحيح — أو استخدم شرط سمة أقل تقييداً إن لم يكن العزل ضرورياً. + + + +**تحديد نطاق `secretAccessor` لكل سر (اختياري).** إذا كنت تفضّل عدم منح `roles/secretmanager.secretAccessor` على نطاق المشروع، احذف الارتباط الثاني أعلاه واربط لكل سر بدلاً من ذلك: + +```bash +gcloud secrets add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" \ + --project= +``` + +أبقِ `roles/secretmanager.viewer` على نطاق المشروع في كلا الحالتين — `secretmanager.secrets.list` (الذي يعتمد عليه الاقتراح التلقائي) لا يمكن منحه لكل سر. + + +## الخطوة 5 — إنشاء سر واحد على الأقل في GCP + +إذا لم يكن لديك سر للاختبار، أنشئ واحداً عبر CLI `gcloud`: + +```bash +echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \ + --data-file=- \ + --project= \ + --replication-policy=automatic +``` + +أو عبر [وحدة تحكم Secret Manager](https://console.cloud.google.com/security/secret-manager): + +1. افتح **Secret Manager** في مشروع GCP الخاص بك. +2. انقر على **+ CREATE SECRET**. +3. **Name:** `crewai-test-keyword`. **Secret value:** الصق قيمتك. +4. انقر على **CREATE SECRET**. + +## الخطوة 6 — إضافة تكوين Workload Identity في CrewAI Platform + +في CrewAI Platform، انتقل إلى **Settings** ← **Workload Identity** وانقر على **Add Workload Identity Config**. + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `gcp-prod`. +- **Cloud Provider:** `GCP`. +- **Workload Identity Provider:** اسم مورد المزود من الخطوة 3، مثلاً `projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`. +- (اختياري) بدّل **Default Configuration** إذا كنت ترغب في أن يكون هذا هو تكوين WI الافتراضي المُحدَّد عند إنشاء بيانات اعتماد سر مدعومة بـ GCP. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */} +{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */} + +## الخطوة 7 — إضافة بيانات اعتماد مزود أسرار مرتبطة بتكوين WI + +انتقل إلى **Settings** ← **Secret Provider Credentials** وانقر على **Add Credential**. + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `gcp-prod-wi`. +- **Provider:** `Google Cloud Secret Manager`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** اختر التكوين الذي أنشأته في الخطوة 6. +- **Project ID:** معرّف مشروع GCP الخاص بك (نفس المشروع الذي يملك الأسرار). +- (اختياري) حدّد **Set as default credential for this provider**. + +سيطلب النموذج فقط **Project ID** ضمن Workload Identity — حقل **Service Account JSON** مخفي عمداً لأنه لا ينطبق على هذا المسار؛ تأتي الهوية الموحَّدة من تكوين WI المرتبط. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */} + +## الخطوة 8 — اختبار الاتصال + +بعد حفظ بيانات الاعتماد، انقر على **Test Connection**. لبيانات اعتماد workload-identity، يتحقق هذا من مصافحة OIDC: تُصدر CrewAI Platform JWT وتبادله عبر Security Token Service للحصول على رمز وصول Google موحَّد. نتيجة خضراء تعني أن ارتباط الاتحاد سليم. + +نجاح Test Connection يُثبت أن Workload Identity Pool ومزود OIDC وربط السمات وشرط السمة موصولة جميعها بشكل صحيح. لا يُثبت ذلك أن IAM في Secret Manager صحيح — يُمارَس `secretmanager.secrets.list` و `secretmanager.versions.access` بشكل منفصل عند تحميل الاقتراح التلقائي لاسم السر أو عندما يُحَلّ متغير بيئة عند الإطلاق. راجع [استكشاف الأخطاء](#troubleshooting) لأنماط فشل المصافحة. + +## الخطوة 9 — الإشارة إلى السر في متغير بيئة + +أَشِر إلى السر على أتمتة، تماماً كما تفعل مع أي متغير بيئة مدعوم بمدير أسرار. راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) لحقول النموذج والسلوك. + +## الخطوة 10 — التحقق من التدوير + +بعد تشغيل عملية النشر، دوّر السر في GCP بإضافة إصدار جديد (يقرأ Secret Manager دائماً أحدث إصدار مفعَّل افتراضياً): + +```bash +echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \ + --data-file=- \ + --project= +``` + +أطلق إطلاق أتمتة جديداً. ستكون بيئة الإطلاق ترى `"rotated value"` — بدون إعادة نشر ولا إعادة تشغيل عامل ولا انتظار TTL. + +للتأكد في سجلات العامل، ابحث عن: + +``` +Workload identity config '' (gcp): N secret(s) resolved +``` + +يظهر هذا السطر لكل إطلاق ويُشير إلى استدعاء `accessSecretVersion` طازج مقابل GCP. + +## استكشاف الأخطاء + +| العَرَض | السبب المحتمل | +|---|---| +| يفشل Test Connection بخطأ مصافحة | رُفض تبادل رمز STS. تحقق من وجود Workload Identity Pool، وأن مُصدر مزود OIDC يطابق قيمة `issuer` للمنصة، وأن شرط السمة يقبل ادّعاءات JWT. تأكد من أن رابط اكتشاف OIDC للمنصة قابل للوصول من GCP عبر الإنترنت العام. | +| `Could not refresh access token: invalid_target` | لا يطابق ادّعاء الجمهور الجمهور المتوقع لمزود Workload Identity. تُعيّن CrewAI Platform الجمهور تلقائياً؛ إذا خصّصته، فتأكد من أنه يطابق `//iam.googleapis.com/`. | +| `Failed to fetch JWKS from issuer` | لا يمكن لـ GCP STS الوصول إلى مضيف CrewAI Platform. تأكد من أن المضيف متاح عبر الإنترنت وأن `/.well-known/openid-configuration` يُعيد 200. | +| `Attribute condition rejected token` | يتطلب شرط السمة لمزود OIDC (الخطوة 3) `organization_id`. تُعيّن CrewAI Platform هذا الادّعاء دائماً، لذا يعني هذا عادةً تكوين حوض/مزود خاطئاً. تحقق من شرط السمة للمزود من جديد. | +| يُظهر الاقتراح التلقائي لاسم السر `PERMISSION_DENIED: secretmanager.secrets.list` | يفتقد الكيان الموحَّد إلى `roles/secretmanager.viewer` على نطاق المشروع. إذن `secretmanager.secrets.list` محصور بنطاق المشروع فقط ولا يمكن منحه لكل سر. راجع الخطوة 4. | +| يفشل الإطلاق في حلّ سر رغم نجاح Test Connection | ارتباط WI سليم، لكن `secretmanager.versions.access` مفقود على السر الفاشل. راجع `roles/secretmanager.secretAccessor` (على نطاق المشروع، أو لكل سر إذا حدّدت النطاق بهذه الطريقة في الخطوة 4). | +| لا تُلتقط القيمة المُدوَّرة في الإطلاق التالي | تأكد من أن متغير البيئة على الأتمتة يشير إلى بيانات اعتماد مدعومة بـ Workload Identity (وليس بيانات اعتماد بمفاتيح ثابتة). يدمج المسار الثابت القيم في صورة النشر. | + +### روابط مرجعية + +- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation) +- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) +- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control) + +## الخطوات التالية + +- [استخدام الأسرار في متغيرات البيئة وإدارة الأذونات](/ar/enterprise/features/secrets-manager/usage) +- للتنوع متعدد السحاب، راجع أيضاً [AWS Workload Identity (اتحاد OIDC)](/ar/enterprise/features/secrets-manager/aws-workload-identity) و [Azure Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity). diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/gcp.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/gcp.mdx new file mode 100644 index 000000000..2503d146e --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/gcp.mdx @@ -0,0 +1,189 @@ +--- +title: Google Cloud Secret Manager +description: تكوين Google Cloud Secret Manager كمزود أسرار لـ CrewAI Platform من البداية إلى النهاية +sidebarTitle: ببيانات اعتماد ثابتة +icon: "key" +--- + +## نظرة عامة + +يأخذك هذا الدليل عبر تكوين Google Cloud Secret Manager كمزود أسرار لمؤسستك على CrewAI Platform، باستخدام **بيانات اعتماد حساب خدمة**. بنهاية الدليل، ستتمكن CrewAI Platform من قراءة الأسرار المخزّنة في مشروع Google Cloud الخاص بك وحقنها كقيم متغيرات بيئة وقت التشغيل. + + +يغطي هذا الدليل مسار **بيانات الاعتماد الثابتة** — تُحَلّ الأسرار وقت النشر وتُدمج في صورة النشر. تتطلب القيم المُدوَّرة إعادة نشر. إذا أردت أسراراً مراعية للتدوير تُحدَّث في كل إطلاق أتمتة، راجع [GCP Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity). + + + +يغطي هذا الدليل التكوين من جانب GCP وإعداد بيانات الاعتماد في CrewAI Platform. للإشارة بعدها إلى سر من متغير بيئة، راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage). + + +## المتطلبات المسبقة + + +قبل البدء، تأكد من امتلاكك: + +- مشروع Google Cloud مع تفعيل **Secret Manager API**. فعّله في [وحدة تحكم APIs & Services](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com) أو عبر `gcloud`: + + ```bash + gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID + ``` + +- إذن في المشروع لإنشاء حسابات خدمة ومنح أدوار IAM و(إن لزم) إنشاء الأسرار. +- مؤسسة على CrewAI Platform يمتلك مستخدمك فيها إذن `secret_providers: manage`. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## الخطوة 1 — إنشاء حساب خدمة + +حساب الخدمة هو الهوية من جانب GCP التي ستُصادق بها CrewAI Platform. + +في [وحدة تحكم IAM & Admin ← Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)، انقر على **Create Service Account**. + +- **Service account name:** `crewai-secrets-reader` +- **Service account ID:** يُملأ تلقائياً من الاسم (مثلاً `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`) +- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform" + +انقر على **Create and Continue**. تخطَّ المنح الاختيارية في هذه الشاشة — ستُرفق الدور في الخطوة 2. انقر على **Done**. + +للتفاصيل الكاملة، راجع وثائق GCP: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create). + +{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */} + +## الخطوة 2 — منح الوصول إلى Secret Manager + +تحتاج CrewAI Platform إلى إذن لسرد وقراءة الأسرار في مشروعك. استخدم أحد نطاقين — **على مستوى المشروع** للبساطة، أو **لكل سر** لأقل الامتيازات. + + + + في [وحدة تحكم IAM](https://console.cloud.google.com/iam-admin/iam)، انقر على **Grant Access** و: + + - **New principals:** بريد حساب الخدمة من الخطوة 1. + - **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + انقر على **Save**. + + أو عبر `gcloud`: + + ```bash + gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" + ``` + + {/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */} + + + + امنح الدور فقط على الأسرار المحددة التي ينبغي أن تصل إليها CrewAI Platform. كرّر لكل سر: + + ```bash + gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" \ + --project=YOUR_PROJECT_ID + ``` + + أو في الوحدة: افتح كل سر في [Secret Manager](https://console.cloud.google.com/security/secret-manager)، انقر على **Permissions** في اللوحة اليمنى، وامنح **Secret Manager Secret Accessor** لحساب الخدمة. + + {/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */} + + + + +يمنح دور `roles/secretmanager.secretAccessor` وصول قراءة فقط لقيم الأسرار. تستدعي CrewAI Platform أيضاً `secretmanager.secrets.list` لتجربة الاقتراح التلقائي في نموذج متغير البيئة — هذا الإذن مُضمَّن في الدور على نطاق المشروع، لكن **ليس** على نطاق لكل سر. مع ارتباطات لكل سر، لن يقترح الإكمال التلقائي أسراراً؛ ستحتاج إلى كتابة اسم السر الكامل. + + +## الخطوة 3 — إنشاء مفتاح حساب الخدمة + +افتح حساب الخدمة من الخطوة 1 في [وحدة تحكم IAM & Admin ← Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts). + +- انقر على علامة التبويب **Keys**. +- انقر على **Add Key** ← **Create new key**. +- **Key type:** JSON. +- انقر على **Create**. يُنزّل المتصفح ملف JSON — احتفظ به بأمان؛ لا يمكن إعادة تنزيله. + +أو عبر `gcloud`: + +```bash +gcloud iam service-accounts keys create ./crewai-secrets-reader.json \ + --iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com +``` + + +مفتاح حساب الخدمة هو بيانات اعتماد ثابتة طويلة الأمد. خزّنه بأمان (في مدير كلمات مرور أو مخزن أسرارك الخاص) ودوّره بشكل منتظم. للقضاء على بيانات الاعتماد الثابتة تماماً، استخدم [GCP Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity) بدلاً من ذلك. + + +{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */} + +## الخطوة 4 — إضافة بيانات الاعتماد في CrewAI Platform + +في CrewAI Platform، انتقل إلى **Settings** ← **Secret Provider Credentials** وانقر على **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +املأ النموذج: + +- **Name:** اسم وصفي، مثلاً `gcp-prod`. +- **Provider:** `Google Cloud Secret Manager`. +- **Project ID:** معرّف مشروع GCP الخاص بك (مثلاً `my-crewai-prod`). +- **Service Account JSON:** الصق المحتوى الكامل لملف JSON الذي نزّلته في الخطوة 3. +- (اختياري) حدّد **Set as default credential for this provider**. تُستخدم بيانات الاعتماد الافتراضية بواسطة متغيرات البيئة التي تشير إلى أسرار GCP بدون تحديد بيانات اعتماد صراحةً. + +انقر على **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */} + +## الخطوة 5 — إنشاء سر واحد على الأقل في GCP + +إذا لم يكن لديك بالفعل أسرار في GCP Secret Manager، أنشئ واحداً الآن لتتمكن من التحقق من الاتصال في الخطوة 6. + +في [وحدة تحكم Secret Manager](https://console.cloud.google.com/security/secret-manager)، انقر على **Create secret**. + +- **Name:** اسم فريد، مثلاً `openai-api-key`. +- **Secret value:** إما لصق قيمة خام أو رفع ملف. +- اترك إعدادات التدوير والتكرار وغيرها على القيم الافتراضية ما لم تكن لديك متطلبات محددة. + +انقر على **Create secret**. + +أو عبر `gcloud`: + +```bash +echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \ + --data-file=- \ + --project=YOUR_PROJECT_ID \ + --replication-policy=automatic +``` + + +**صيغة الإشارة بمفتاح JSON.** يتعامل GCP Secret Manager مع قيم الأسرار كبيانات معتمة. إذا حدث أن كانت قيمة سرّك سلسلة JSON، يمكن لـ CrewAI Platform استخراج حقل واحد باستخدام صيغة `secret-name#json_key` (مثلاً `database-credentials#password`). راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) للتفاصيل. + + +للتفاصيل الكاملة، راجع وثائق GCP: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart). + +{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */} + +## الخطوة 6 — اختبار الاتصال + +عُد إلى CrewAI Platform، في صفحة **Secret Provider Credentials**، اعثر على بيانات الاعتماد التي أنشأتها للتو وانقر على **Test Connection**. + +تؤكد رسالة نجاح أن CrewAI Platform يمكنها المصادقة مع GCP وقراءة الأسرار من مشروعك. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */} + +إذا فشل الاختبار، تحقق من الأسباب الأكثر شيوعاً: + +| العَرَض | السبب المحتمل | +|---|---| +| `PERMISSION_DENIED` عند سرد الأسرار | يفتقد حساب الخدمة إلى `roles/secretmanager.secretAccessor`، أو حدّدت نطاقه لكل سر (لا يُمنح `list`). تحقق من الخطوة 2 من جديد. | +| `PERMISSION_DENIED` على `secretmanager.secrets.access` | نفس ما سبق، لكن لسر محدد. تأكد من أن حساب الخدمة يمتلك دور accessor على السر المعني. | +| `unauthorized_client` / `invalid_grant` | ملف Service Account JSON الملصوق غير صالح أو منتهي الصلاحية أو لحساب خدمة محذوف. أعد إنشاء المفتاح (الخطوة 3) والصقه من جديد. | +| `Project ID does not match` | لا يطابق حقل Project ID في CrewAI Platform المشروع الذي يملك حساب الخدمة / الأسرار. تحقق من الخطوة 4 من جديد. | +| `API not enabled` | Secret Manager API غير مفعَّل في المشروع. راجع المتطلبات المسبقة. | + +## الخطوات التالية + +الآن وقد اتصل GCP، توجّه إلى [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage) من أجل: + +- منح أعضاء المؤسسة الأذونات الصحيحة لاستخدام (أو إدارة) مدير الأسرار. +- الإشارة إلى أسرار GCP الخاصة بك من متغيرات بيئة CrewAI Platform. + +إذا كنت تريد أسراراً **مراعية للتدوير** تنتشر دون إعادة نشر، انتقل إلى [GCP Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity) — نفس مخزن الأسرار، بدون بيانات اعتماد ثابتة، وتُجلب الأسرار في كل إطلاق. diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/overview.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/overview.mdx new file mode 100644 index 000000000..82dbcca3d --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/overview.mdx @@ -0,0 +1,96 @@ +--- +title: نظرة عامة على مدير الأسرار +description: ربط مخازن الأسرار الخارجية بمنصة CrewAI Platform والإشارة إلى الأسرار المُدارة من متغيرات البيئة +sidebarTitle: نظرة عامة +icon: "book-open" +--- + +## نظرة عامة + +تُتيح ميزة مدير الأسرار لمؤسستك ربط مخزن أسرار خارجي — AWS Secrets Manager أو Google Cloud Secret Manager أو Azure Key Vault — والإشارة إلى تلك الأسرار مباشرةً من متغيرات البيئة على الأتمتات والطواقم لديك. بدلاً من لصق قيم نصية صريحة في المنصة، فإنك تخزّن مجموعة واحدة من بيانات الاعتماد لكل مزود وتُشير إلى الأسرار بالاسم. + +يمنحك هذا: + +- **تخزين مركزي** — إدارة الأسرار في مزوّدك بدلاً من تعديل إعدادات CrewAI Platform. لا تحتفظ CrewAI Platform بأي نسخة نصية صريحة من قيمة السر. +- **تقليل التعرّض** — لا تظهر القيم الحساسة أبداً كنص صريح في إعدادات CrewAI Platform. +- **قابلية تدقيق سحابية المنشأ** — يسجّل سجل التدقيق الخاص بمزوّدك كل قراءة لسر. + + +يتطلب مدير الأسرار (مساران: بيانات الاعتماد الثابتة و Workload Identity) إصدار CrewAI runtime رقم `1.14.5` أو أحدث في صورة حاوية الأتمتة. + + +## مساران: بيانات اعتماد ثابتة مقابل Workload Identity + +هناك طريقتان لربط CrewAI Platform بمخزن أسرار السحابة لديك. **يختلفان اختلافاً كبيراً في سلوك التدوير**، لذا اختر بناءً على مدى تكرار تدوير أسرارك ومدى صرامة وضعك الأمني. + +| الجانب | بيانات الاعتماد الثابتة | Workload Identity (اتحاد OIDC) | +|---|---|---| +| **المصادقة** | مفاتيح وصول / ملف JSON لحساب خدمة طويلة الأمد مخزّنة في CrewAI Platform | رموز قصيرة الأمد تُصدر لكل عملية عامل؛ لا تُخزَّن بيانات اعتماد ثابتة في أي مكان | +| **انتشار التدوير** | تُحَلّ وقت النشر و**تُدمج في صورة حاوية النشر** — تتطلب القيم المُدوَّرة إعادة نشر | تُحَلّ **وقت تنفيذ الأتمتة** — تنتشر القيم المُدوَّرة إلى الإطلاق التالي بدون إعادة نشر | +| **جهد الإعداد** | أقل — لصق المفاتيح / رفع ملف JSON لحساب الخدمة | أعلى — تسجيل CrewAI Platform كمزود OIDC في سحابتك وتكوين سياسات الثقة | +| **الأنسب لـ** | البداية، الأسرار قليلة التدوير، عمليات نشر بحساب واحد | الإنتاج، الأسرار كثيرة التدوير، البيئات التي تحكمها الامتثال وتمنع بيانات الاعتماد طويلة الأمد | + + +**يستخدم كلا المسارين نفس تدفق الواجهة** للإشارة إلى الأسرار في متغيرات البيئة (راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage)). الفرق بالكامل في كيفية مصادقة المنصة لسحابتك ومتى تقرأ قيمة السر. + + +### اختر دليل الإعداد الخاص بك + +| المزود | بيانات الاعتماد الثابتة | Workload Identity | +|---|---|---| +| AWS Secrets Manager | [AWS — المفاتيح الثابتة / AssumeRole](/ar/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/ar/enterprise/features/secrets-manager/aws-workload-identity) | +| Google Cloud Secret Manager | [GCP — مفتاح حساب الخدمة](/ar/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity) | +| Azure Key Vault | [Azure — السر المُعرَّف للعميل](/ar/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity) | + + +واجهتا مدير الأسرار و Workload Identity مُوسومتان حالياً بـ **Beta** في CrewAI Platform. + + +## كيف تتلاءم الأجزاء معاً + +إعداد مدير الأسرار هو تدفق من ثلاث خطوات يشمل كلاً من مزود السحابة و CrewAI Platform: + +1. **يُكوِّن المسؤول بيانات اعتماد المزود.** هذا هو العمل من جانب السحابة — ويختلف العمل اعتماداً على المسار (بيانات الاعتماد الثابتة أو Workload Identity) الذي تختاره. تغطي أدلة المزودين هذا من البداية إلى النهاية. +2. **يُشير المسؤول (أو عضو مصرَّح له) إلى سر في متغير بيئة.** من صفحة متغيرات البيئة، يختار المستخدم بيانات اعتماد المزود ويُحدّد اسم السر. راجع [استخدام مدير الأسرار](/ar/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables). +3. **تتلقى الأتمتة القيمة المحلولة وقت التشغيل.** عندما يعمل طاقم أو أتمتة، تجلب CrewAI Platform السر من مزوّدك وتحقنه كقيمة لمتغير البيئة. مع Workload Identity، يحدث هذا الجلب في كل إطلاق (مراعٍ للتدوير). مع بيانات الاعتماد الثابتة، يحدث الجلب وقت النشر وتُدمج القيمة في صورة النشر. + +## الرؤية والنطاق + + +تتّبع متغيرات البيئة المدعومة بـ WI نفس نموذج الإسناد الذي تتّبعه متغيرات البيئة العادية: لا تحلّ الأتمتة سوى متغيرات البيئة المدعومة بـ WI المُسنَدة إليها صراحةً. أَسنِد متغير WI إلى أتمتة من صفحة متغيرات البيئة الخاصة بتلك الأتمتة؛ المتغيرات المُعرَّفة على مستوى المنظمة أو في مشروع Studio لا تُحلّ عند الإطلاق حتى تُسنِدها. + + + +تُشغَّل مرحلة جلب الأسرار في كل إطلاق، لكنها لا تقوم بعمل فعلي إلا حين تكون هناك متغيرات بيئة مدعومة بـ WI مُسنَدة إلى النشر. لكل متغير مُسنَد، يُحلّ وقت التشغيل القيمة من مزوّدك السحابي في كل إطلاق لـ crew أو flow أو training أو test أو checkpoint-restore ويكتبها في بيئة العملية. عند عدم وجود أي متغير مُسنَد، تكون المرحلة بلا أثر (no-op). وإلا فإن التكلفة تتناسب مع عدد المتغيرات المُسنَدة: تأخّر إضافي بسيط لكل إطلاق بالإضافة إلى إدخال واحد في سجل تدقيق السحابة لكل متغير. + + + +على مستوى *تكوينات* Workload Identity، لا يزال النطاق اليوم عاماً على مستوى المنظمة. تُهيَّأ كل أتمتة في المنظمة استناداً إلى جميع تكوينات Workload Identity التي سجّلتها المنظمة، ولا يمكنك اليوم ربط تكوين Workload Identity محدد بأتمتة بعينها. تحديد نطاق Workload Identity لكل أتمتة موجود في خارطة الطريق. حتى ذلك الحين، سجِّل فقط تكوينات Workload Identity التي يحقّ لكل أتمتة في منظمتك استخدامها. + + +## الأذونات + +تتحكم ميزتان في CrewAI Platform بالوصول إلى مدير الأسرار: + +- `secret_providers` — تتحكم بمن يستطيع عرض أو إدارة بيانات اعتماد المزودين. +- `environment_variables` — تتحكم بمن يستطيع إنشاء وتحرير متغيرات البيئة (بما فيها تلك التي تُشير إلى أسرار). + +تتحكم ميزة ثالثة بإعداد Workload Identity: + +- `workload_identity_configs` — تتحكم بمن يستطيع عرض أو إدارة تكوينات Workload Identity. مطلوبة فقط إذا كنت تستخدم مسار Workload Identity. + +يتمتع المالكون دائماً بالوصول الكامل. لا يحصل الأعضاء على وصول إلى `secret_providers` أو `workload_identity_configs` افتراضياً ويجب منحهم الإذن عبر دور مخصص. راجع [الأذونات (RBAC)](/ar/enterprise/features/secrets-manager/usage#permissions-rbac) للحصول على المصفوفة الكاملة والتعليمات خطوة بخطوة. + +## الخطوات التالية + +اختر مسارك: + +- **بيانات الاعتماد الثابتة** (أبسط، تتطلب إعادة نشر عند التدوير): + - [تكوين AWS Secrets Manager](/ar/enterprise/features/secrets-manager/aws) + - [تكوين Google Cloud Secret Manager](/ar/enterprise/features/secrets-manager/gcp) + - [تكوين Azure Key Vault](/ar/enterprise/features/secrets-manager/azure) +- **Workload Identity** (مراعٍ للتدوير، بدون إعادة نشر): + - [تكوين AWS Workload Identity](/ar/enterprise/features/secrets-manager/aws-workload-identity) + - [تكوين GCP Workload Identity Federation](/ar/enterprise/features/secrets-manager/gcp-workload-identity) + - [تكوين Azure Workload Identity Federation](/ar/enterprise/features/secrets-manager/azure-workload-identity) +- ثم: [استخدام الأسرار في متغيرات البيئة وإدارة الأذونات](/ar/enterprise/features/secrets-manager/usage) diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/usage.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/usage.mdx new file mode 100644 index 000000000..223b10b28 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/usage.mdx @@ -0,0 +1,137 @@ +--- +title: استخدام مدير الأسرار +description: إدارة الأذونات والإشارة إلى الأسرار المُدارة من متغيرات البيئة في CrewAI Platform +sidebarTitle: الاستخدام والأذونات +icon: "list-check" +--- + +## نظرة عامة + +هذا الدليل محايد تجاه المزود. يفترض أنك (أو مسؤول آخر) قد كوّنت بالفعل بيانات اعتماد واحدة على الأقل لمزود أسرار. اختر دليل الإعداد الخاص بك بناءً على المسار الذي تريده: + +- بيانات الاعتماد الثابتة: [AWS](/ar/enterprise/features/secrets-manager/aws) · [GCP](/ar/enterprise/features/secrets-manager/gcp) +- Workload Identity (مراعٍ للتدوير): [AWS](/ar/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ar/enterprise/features/secrets-manager/gcp-workload-identity) + +استخدم هذا الدليل من أجل: + +- منح الأذونات الصحيحة لأعضاء المؤسسة. +- الإشارة إلى الأسرار من متغيرات البيئة على أتمتاتك. +- التحقق من أن كل شيء يُحَلّ بشكل صحيح وقت التشغيل. + +## الأذونات (RBAC) + +ثلاث ميزات في CrewAI Platform ذات صلة عند العمل مع مدير الأسرار: + +- `secret_providers` — تتحكم بالوصول إلى صفحة **بيانات اعتماد مزود الأسرار**. +- `workload_identity_configs` — تتحكم بالوصول إلى صفحة **Workload Identity** (ذات صلة فقط إذا كنت تستخدم مسار WI). +- `environment_variables` — تتحكم بمن يستطيع إنشاء أو تحرير متغيرات البيئة. + +لكل ميزة مستويا إجراء: `read` و `manage`. منح `manage` يستلزم تلقائياً `read`. + +### ما يجب منحه + +| الهدف | `secret_providers` | `workload_identity_configs` | `environment_variables` | +|---|---|---|---| +| استخدام بيانات اعتماد ثابتة موجودة في متغيرات البيئة (بدون تعديل المزود) | `read` | — | `manage` | +| إنشاء أو تحرير أو حذف بيانات الاعتماد الثابتة | `manage` | — | `manage` | +| استخدام بيانات اعتماد مدعومة بـ Workload Identity موجودة في متغيرات البيئة | `read` | — | `manage` | +| إنشاء أو تحرير أو حذف تكوينات Workload Identity (وبيانات الاعتماد التي تشير إليها) | `manage` | `manage` | `manage` | + + +يتمتع **المالكون** تلقائياً بالوصول الكامل إلى كل ميزة. يستبعد دور **العضو** الافتراضي عمداً `secret_providers` و `workload_identity_configs` — يجب على المسؤولين تضمين الأعضاء صراحةً عبر دور مخصص. + + +### كيفية التعيين + +1. في CrewAI Platform، انتقل إلى **Settings** ← **Roles**. من هذه الصفحة يمكنك إنشاء أدوار جديدة وتحرير أذونات كل دور وتعيين الأدوار للأعضاء الحاليين في المؤسسة. + + {/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */} + {/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */} + +2. انقر على **Create Role** لإنشاء دور جديد، أو افتح دوراً موجوداً لتحرير أذوناته. + +3. في محرر أذونات الدور، بدّل الميزات ذات الصلة وفق الجدول أعلاه: + + - `secret_providers`: اختر **read** إذا كان هذا الدور يحتاج فقط إلى استخدام بيانات الاعتماد الموجودة، أو **manage** إذا كان ينبغي أن يكون قادراً أيضاً على إنشاء بيانات الاعتماد وتحريرها وحذفها. + - `environment_variables`: اختر **manage** ليتمكن الدور من إنشاء متغيرات بيئة تُشير إلى الأسرار. + + {/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */} + {/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */} + +4. احفظ الدور. + +5. عيّن الدور للأعضاء ذوي الصلة من نفس صفحة Roles (أو قائمة أعضاء المؤسسة). + + {/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */} + +## الإشارة إلى الأسرار في متغيرات البيئة + +بمجرد وجود بيانات اعتماد للمزود وامتلاك دورك للأذونات الصحيحة، يمكنك الإشارة إلى الأسرار المُدارة من أي متغير بيئة. + +في CrewAI Platform، انتقل إلى **Environment Variables** وانقر على **Add Environment Variables**. + +{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */} + +املأ النموذج: + +- **Key** — اسم متغير البيئة. يجب أن يبدأ بحرف أو شرطة سفلية ويحتوي فقط على حروف وأرقام وشرطات سفلية. عادةً بأحرف كبيرة، مثل `OPENAI_API_KEY`. + +- **Value Source** — اختر من أين تأتي القيمة: + - **Direct Value** — قيمة نصية صريحة تكتبها. استخدم هذا عندما لا ترغب في إشراك مزود. + - **Use AWS default** (أو ما يعادله لمزوّدك) — تستخدم بيانات الاعتماد المُعلَّمة حالياً كافتراضية لذلك النوع من المزود. + - **بيانات اعتماد مُسمَّاة محددة** — اختر بيانات الاعتماد بالاسم. استخدم هذا إذا كانت لديك بيانات اعتماد متعددة لنفس المزود (مثلاً `aws-prod` و `aws-staging`) وتريد اختيار واحدة صراحةً. + + {/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */} + +- **Secret Name** — اسم السر في مزوّدك. بمجرد اختيار بيانات الاعتماد، يُقدّم هذا الحقل اقتراحاً تلقائياً: ابدأ بالكتابة، وتستعلم CrewAI Platform مزوّدك عن أسماء الأسرار المطابقة. + + استخدم الصيغة `secret-name#json_key` لاستخراج حقل واحد من سر مهيكل (JSON). على سبيل المثال، عند وجود سر `database-credentials` بقيمة `{"username": "...", "password": "..."}`، أَشِر إلى `database-credentials#password` لحقن كلمة المرور فقط. + + {/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */} + + + **ملاحظة Azure Key Vault:** لا يمكن أن تحتوي أسماء أسرار Azure على شرطات سفلية. تُحوّل CrewAI Platform تلقائياً الشرطات السفلية في حقل **Secret Name** إلى شرطات عند استدعاء Azure (مثلاً، `db_password` تُرسل كـ `db-password`). + + +انقر على **Create** لحفظ المتغير. + +{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */} + + +عند تحرير متغير بيئة موجود، يحافظ ترك حقل **Value** فارغاً على القيمة الحالية. هذا مقصود — فهو يتيح لك تغيير حقول أخرى (مثل اسم السر أو بيانات الاعتماد) دون إعادة إدخال القيمة. + + +## التحقق من العمل + +للتحقق من البداية إلى النهاية: + +1. أَشِر إلى متغير البيئة على أتمتة أو طاقم أو عملية نشر تماماً كما تفعل مع أي متغير بيئة آخر. +2. انشر الأتمتة. +3. أطلق تشغيلاً وتأكد من اكتماله بنجاح. + +### يعتمد سلوك التدوير على مسار بيانات الاعتماد + +| مسار بيانات الاعتماد | متى يُقرأ السر | ما يتطلبه التدوير | +|---|---|---| +| **بيانات الاعتماد الثابتة** (مفاتيح AWS، ملف JSON لحساب خدمة GCP) | **وقت النشر** — تُدمج القيمة في صورة النشر | إعادة نشر الأتمتة بعد تدوير السر | +| **Workload Identity** (اتحاد OIDC، AWS أو GCP) | **في كل إطلاق أتمتة** — تُجلب القيمة طازجة من سحابتك | لا شيء — يرى الإطلاق التالي بعد التدوير القيمة الجديدة | + + +**إذا كنت تحتاج أسراراً مراعية للتدوير** (بدون إعادة نشر عند التدوير)، استخدم مسار Workload Identity: [AWS WI](/ar/enterprise/features/secrets-manager/aws-workload-identity) أو [GCP WI](/ar/enterprise/features/secrets-manager/gcp-workload-identity). المقايضة هي مزيد من جهد الإعداد مقدماً (تسجيل CrewAI Platform كمزود OIDC في سحابتك) ولكن عمليات أبسط على المدى الطويل. + + +إذا فشل النشر أو التشغيل بخطأ متعلق بسرك، تحقق من الأسباب الأكثر شيوعاً: + +| العَرَض | السبب المحتمل | +|---|---| +| `no credential found` | يُشير متغير البيئة إلى مزود ولكن لم تُحدَّد بيانات اعتماد بعينها، ولا توجد بيانات اعتماد افتراضية مُعيّنة لذلك النوع من المزود. إما اختر بيانات اعتماد صراحةً على المتغير، أو علِّم بيانات اعتماد كافتراضية على صفحة **Secret Provider Credentials**. | +| `secret not found` | خطأ مطبعي في **Secret Name**، أو أن السر غير موجود في حساب/منطقة المزود التي تشير إليها بيانات الاعتماد. تحقق من كليهما. | +| تعمل الأتمتة بالقيمة القديمة بعد التدوير (مسار بيانات الاعتماد الثابتة) | القيمة السابقة مدمجة في صورة حاوية النشر. أعد نشر الأتمتة لاستيعاب القيمة المُدوَّرة. لتجنّب ذلك تماماً، حوّل بيانات الاعتماد إلى مسار Workload Identity. | +| تعمل الأتمتة بالقيمة القديمة بعد التدوير (مسار Workload Identity) | تأكد من أن متغير البيئة يُشير إلى بيانات اعتماد مدعومة بـ WI (وليس مفاتيح ثابتة). مع WI، ينبغي أن يرى الإطلاق التالي بعد التدوير القيمة الجديدة. إن لم يحدث ذلك، تحقق من أن السر قد تم تحديثه فعلاً في سحابتك (مثلاً، `aws secretsmanager get-secret-value`). | +| `JSON key not found` | عند استخدام `secret-name#json_key`، يجب أن يكون السر الأساسي كائن JSON صالحاً يحتوي على ذلك المفتاح. تحقق بقراءة السر مباشرة في مزوّدك. | + +## الخطوات التالية + +- [العودة إلى نظرة عامة على مدير الأسرار](/ar/enterprise/features/secrets-manager/overview) +- بيانات الاعتماد الثابتة: [AWS](/ar/enterprise/features/secrets-manager/aws) · [GCP](/ar/enterprise/features/secrets-manager/gcp) +- Workload Identity (مراعٍ للتدوير): [AWS](/ar/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ar/enterprise/features/secrets-manager/gcp-workload-identity) diff --git a/docs/v1.15.1/ar/enterprise/features/secrets-manager/verify-rotation.mdx b/docs/v1.15.1/ar/enterprise/features/secrets-manager/verify-rotation.mdx new file mode 100644 index 000000000..d992ceb15 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/secrets-manager/verify-rotation.mdx @@ -0,0 +1,261 @@ +--- +title: التحقق من التدوير +description: مثال طاقم مستقل يُثبت أن تدوير الأسرار ينتشر إلى عمليات النشر الجارية دون إعادة نشر. +sidebarTitle: التحقق من التدوير +icon: "arrows-rotate" +--- + +## نظرة عامة + +يوضّح لك هذا الدليل كيفية التحقق من أن **السر المُدوَّر في مزود السحابة لديك يُلتقط في أول إطلاق أتمتة لاحق** — بدون إعادة نشر ولا إعادة تشغيل عامل. هذا ذو صلة فقط عندما تكون قد كوّنت بيانات اعتماد مدعومة بـ Workload Identity ([AWS](/ar/enterprise/features/secrets-manager/aws-workload-identity)، [GCP](/ar/enterprise/features/secrets-manager/gcp-workload-identity)، [Azure](/ar/enterprise/features/secrets-manager/azure-workload-identity)). تتطلب عمليات نشر بيانات الاعتماد الثابتة إعادة نشر بعد التدوير؛ ليس هناك ما يجب التحقق منه هنا. + +تستخدم الوصفة أدناه طاقماً صغيراً مستقلاً بأداة واحدة ووكيل واحد ومهمة واحدة. لا يُشير موجه الطاقم أبداً إلى قيمة السر — بدلاً من ذلك، تقرأ أداة القيمة من `os.environ` وتُفيد ببصمة SHA-256 لما تراه. دوّر السر في مزود السحابة، أطلق مرة أخرى، وتتغير البصمة. + + +لماذا بصمة وليس القيمة الخام؟ وضع الأسرار الخام في إخراج LLM وسجلات التتبع هو متجه تسرب. البصمة كافية لتأكيد "أن القيمة تغيّرت" دون كتابة القيمة الفعلية في أي مكان يمكن رصده. + + +## المتطلبات المسبقة + +قبل تشغيل هذا التحقق: + +- بيانات اعتماد مزود أسرار مدعومة بـ WI مكوَّنة ([AWS](/ar/enterprise/features/secrets-manager/aws-workload-identity)، [GCP](/ar/enterprise/features/secrets-manager/gcp-workload-identity)، [Azure](/ar/enterprise/features/secrets-manager/azure-workload-identity)). +- متغير بيئة على عملية النشر بـ `Secret = true`، المفتاح `API_KEY` (أو أي اسم تفضّله — اضبط الأداة أدناه لتطابقه)، يُشير إلى سر في مزود السحابة. +- طريقة لتحديث قيمة السر في مزود السحابة (وصول CLI أو وحدة تحكم السحابة). +- طريقة لإطلاق عملية النشر عبر HTTP (curl أو Postman أو علامة التبويب **Run** في CrewAI Platform). + +## الخطوة 1 — هيكلة طاقم التحقق + +أنشئ مشروع crew كلاسيكيًا لأن هذا المثال يربط أداة Python عبر `crew.py`: + +```bash +crewai create crew rotation_verifier --classic --skip_provider +cd rotation_verifier +``` + +## الخطوة 2 — إضافة أداة صدى بيانات الاعتماد + +استبدل `src/rotation_verifier/tools/custom_tool.py` بأداة تقرأ متغير البيئة المدعوم بسر وتُعيد بصمة: + +```python src/rotation_verifier/tools/credential_echo_tool.py +"""Tool that verifies a runtime-injected secret without leaking the value. + +Reads the secret-backed env var (populated by the workload-identity +secrets manager at kickoff time) and returns a stable fingerprint. Never +echo raw credential values into LLM output or logs in production code — +the fingerprint alone is sufficient to confirm rotation worked. +""" + +from __future__ import annotations + +import hashlib +import os + +from crewai.tools import BaseTool + + +# Match the deployment environment variable's `key` field. +ENV_VAR_NAME = "API_KEY" + + +class CredentialEchoTool(BaseTool): + name: str = "credential_echo" + description: str = ( + "Read the API credential from the worker's environment and return a " + "fingerprint summary. Use this exactly once when asked to verify the " + "current credential. Takes no arguments." + ) + + def _run(self) -> str: + value = os.environ.get(ENV_VAR_NAME) + if not value: + return ( + f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-" + "identity secret fetch did not run, or the deployment is " + "missing the secret-backed env var." + ) + fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12] + return f"Authenticated. credential.fingerprint=sha256:{fingerprint}" +``` + +## الخطوة 3 — استبدال تكوينات الوكيل والمهمة الافتراضية + +يضم الطاقم وكيلاً واحداً ومهمة واحدة — كلاهما بأوصاف **لا تذكر أبداً** قيمة السر، لذا تبقى مفاتيح المهام مستقرة عبر عمليات التدوير. + +```yaml src/rotation_verifier/config/agents.yaml +credential_checker: + role: > + Credential Verifier + goal: > + Confirm that the workload-identity-backed secret reached this worker + process and report a fingerprint of the current value. + backstory: > + You are a no-nonsense reliability engineer responsible for verifying + that secrets fetched at runtime via workload identity are present + and fresh. You always use the credential_echo tool exactly once and + report the result verbatim — you never make up values. +``` + +```yaml src/rotation_verifier/config/tasks.yaml +verify_credential_task: + description: > + Use the credential_echo tool to read the runtime-injected credential + and produce a one-line confirmation. The current year is {current_year} + (use it only in the timestamp; do not transform the credential output). + expected_output: > + A single line in the form: + "[{current_year}] " + agent: credential_checker +``` + +## الخطوة 4 — توصيل فئة الطاقم + +```python src/rotation_verifier/crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent + +from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool + + +@CrewBase +class RotationVerifierCrew(): + """Single-task crew that verifies a workload-identity-backed secret + was successfully fetched at runtime. + + Rotate the underlying secret in the cloud provider, kickoff again, and + the credential fingerprint in the agent's report changes — without any + re-deploy, worker restart, or input change. The crew prompt itself + never references the secret value. + """ + + agents: list[BaseAgent] + tasks: list[Task] + + @agent + def credential_checker(self) -> Agent: + return Agent( + config=self.agents_config["credential_checker"], + tools=[CredentialEchoTool()], + verbose=True, + ) + + @task + def verify_credential_task(self) -> Task: + return Task(config=self.tasks_config["verify_credential_task"]) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +## الخطوة 5 — نشر الطاقم وتكوين متغير بيئة السر + +انشر هذا الطاقم على CrewAI Platform تماماً كما تنشر أي طاقم آخر. ثم على صفحة **Environment Variables** الخاصة بعملية النشر: + +- **Key:** `API_KEY` (يجب أن يطابق `ENV_VAR_NAME` في الأداة) +- **Value Source:** بيانات الاعتماد المدعومة بـ WI التي أعدّتها في [AWS WI](/ar/enterprise/features/secrets-manager/aws-workload-identity) أو [GCP WI](/ar/enterprise/features/secrets-manager/gcp-workload-identity) +- **Secret Name:** اسم السر في Secret Manager الخاص بمزود السحابة لديك + +{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */} + +## الخطوة 6 — تشغيل الإطلاق الأول + +استبدل `` و `` بالقيم من علامة التبويب **Run** الخاصة بعملية النشر. + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +عندما يكتمل الإطلاق (بضع ثوان)، تحقق من إخراج الوكيل. سترى: + +``` +[2026] Authenticated. credential.fingerprint=sha256:004421b993c9 +``` + +سجّل البصمة. هذا التجزئة مرتبط بشكل فريد بأي قيمة سر موجودة حالياً في مزود السحابة لديك. + +## الخطوة 7 — تدوير السر في مزود السحابة + + + + ```bash + aws secretsmanager update-secret \ + --region \ + --secret-id \ + --secret-string "rotated value" + ``` + + + + أضف إصداراً جديداً (يقرأ Secret Manager دائماً `latest`): + + ```bash + echo -n "rotated value" | gcloud secrets versions add \ + --data-file=- \ + --project= + ``` + + + + ```bash + az keyvault secret set \ + --vault-name \ + --name \ + --value "rotated value" + ``` + + + +## الخطوة 8 — تشغيل إطلاق ثانٍ والمقارنة + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +يُظهر إخراج الوكيل الآن **بصمة مختلفة**: + +``` +[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72 +``` + +يُثبت هذا أن التدوير التُقط بواسطة عملية النشر الجارية دون إعادة نشر ولا إعادة تشغيل عامل ولا أي إجراء آخر من قِبل المشغّل. + +## ما يتحقق منه هذا — وما لا يتحقق منه + +**يتحقق من:** +- يعمل إصدار رمز OIDC الخاص بـ WI من CrewAI Platform. +- تقبل الثقة من جانب السحابة (مزود IAM OIDC لـ AWS، Workload Identity Pool لـ GCP، Federated Identity Credential لـ Azure) الرمز. +- تمتلك الهوية من جانب السحابة (IAM Role / حساب خدمة GCP / Entra App Registration) وصولاً لقراءة السر. +- تصل قيمة السر إلى `os.environ` لعملية العامل وقت الإطلاق. +- تنتشر عمليات التدوير اللاحقة إلى الإطلاق التالي. + +**لا يتحقق من:** +- أن طواقم الإنتاج الفعلية لديك تتعامل مع التدوير بسلاسة — مثلاً، المهام طويلة الأمد التي تقرأ متغير البيئة مرة واحدة عند البدء ستستمر في استخدام القيمة القديمة حتى تنتهي المهمة. خطّط وفقاً لذلك: اقرأ الأسرار عند نقطة الاستخدام، وليس عند استيراد الوحدة. + +## لماذا لا نُشير إلى السر مباشرةً في الموجه؟ + +سيضع عرض توضيحي يبدو أبسط قيمة السر مباشرةً في وصف مهمة (مثلاً، "البحث عن `{api_key}`") ويتفحص الموجه. **لا تفعل ذلك.** لسببين: + +1. **يُسرّب السر إلى تتبعات استدعاء LLM والسجلات من جانب المزود.** يمكن لأي شخص لديه وصول للتتبعات قراءته. +2. **يُغيّر وصف المهمة في كل إطلاق.** تُحدّد CrewAI Platform المهام بتجزئة MD5 للوصف؛ القيمة المُدوَّرة تعني أن التجزئة تتغير لكل إطلاق، مما يكسر ربط المهمة من وقت النشر إلى وقت التشغيل. العَرَض: تُسجَّل سجلات المهام كـ `pending_run` إلى الأبد، أو تُسجَّل بعض مهام طاقم متعدد المهام فقط. + +يتجاوز النمط القائم على الأداة في هذا الدليل كلتا المشكلتين: الموجه ثابت، تقرأ الأداة متغير البيئة وقت التشغيل، وتصل فقط بصمة القيمة إلى LLM. + +## الخطوات التالية + +- [العودة إلى نظرة عامة على مدير الأسرار](/ar/enterprise/features/secrets-manager/overview) +- بمجرد التحقق، أَسقط طاقم التحقق. يجب أن تتبع الطواقم الفعلية النمط نفسه: الوصول إلى الأسرار عبر `os.environ` داخل أداة، وعدم استبدالها أبداً في الموجهات. diff --git a/docs/v1.15.1/ar/enterprise/features/tools-and-integrations.mdx b/docs/v1.15.1/ar/enterprise/features/tools-and-integrations.mdx new file mode 100644 index 000000000..146523f26 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/tools-and-integrations.mdx @@ -0,0 +1,261 @@ +--- +title: الأدوات والتكاملات +description: "اربط التطبيقات الخارجية وأدِر الأدوات الداخلية التي يمكن لوكلائك استخدامها." +icon: "wrench" +mode: "wide" +--- + +## نظرة عامة + +الأدوات والتكاملات هي المركز الرئيسي لربط تطبيقات الجهات الخارجية وإدارة الأدوات الداخلية التي يمكن لوكلائك استخدامها أثناء التشغيل. + + + ![نظرة عامة على الأدوات والتكاملات](/images/enterprise/crew_connectors.png) + + +## استكشاف + + + + +## تطبيقات الوكلاء (التكاملات) + +اربط تطبيقات المؤسسات (مثل Gmail وGoogle Drive وHubSpot وSlack) عبر OAuth لتمكين إجراءات الوكلاء. + +{" "} + + + انقر على Connect في أحد التطبيقات وأكمل عملية OAuth. + + + عدّل اختيارياً النطاقات والمشغلات وتوفر الإجراءات. + + + تصبح الخدمات المتصلة متاحة كأدوات لوكلائك. + + + +{" "} +![شبكة التكاملات](/images/enterprise/agent-apps.png) + +### ربط حسابك + +1. انتقل إلى Integrations +2. انقر على Connect في الخدمة المطلوبة +3. أكمل تدفق OAuth وامنح النطاقات +4. انسخ رمز Enterprise من Integration Settings + +{" "} + + ![رمز Enterprise](/images/enterprise/enterprise_action_auth_token.png) + + +### تثبيت أدوات التكامل + +لاستخدام التكاملات محلياً، تحتاج إلى تثبيت أحدث حزمة `crewai-tools`. + +```bash +uv add crewai-tools +``` + +### إعداد متغيرات البيئة + +{" "} + + لاستخدام التكاملات مع `Agent(apps=[])` يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز Enterprise الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +### مثال على الاستخدام + +{" "} + + استخدم النهج المبسط الجديد لدمج تطبيقات المؤسسات. ما عليك سوى تحديد + التطبيق وإجراءاته مباشرة في تهيئة Agent. + + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +email_agent = Agent( + role="Email Manager", + goal="Manage and organize email communications", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail', 'gmail/send_email'] # Using canonical name 'gmail' +) + +# Task to send an email +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" +) + +# Run the task +crew = Crew( + agents=[email_agent], + tasks=[email_task] +) + +# Run the crew +crew.kickoff() +``` + +### تصفية الأدوات + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Gmail actions only +gmail_agent = Agent( + role="Gmail Manager", + goal="Manage gmail communications and notifications", + backstory="An AI assistant that helps coordinate gmail communications.", + apps=['gmail/fetch_emails'] # Using canonical name with specific action +) + +notification_task = Task( + description="Find the email from john@example.com", + agent=gmail_agent, + expected_output="Email found from john@example.com" +) + +crew = Crew( + agents=[gmail_agent], + tasks=[notification_task] +) +``` + +في الطاقم المنشور، يمكنك تحديد الإجراءات المتاحة لكل تكامل من صفحة إعدادات الخدمة. + +{" "} + + ![تصفية الإجراءات](/images/enterprise/filtering_enterprise_action_tools.png) + + +### عمليات النشر المحددة النطاق (مؤسسات متعددة المستخدمين) + +يمكنك تحديد نطاق كل تكامل لمستخدم معين. على سبيل المثال، طاقم يتصل بـ Google يمكنه استخدام حساب Gmail لمستخدم محدد. + +{" "} +مفيد عندما تحتاج فرق/مستخدمون مختلفون للحفاظ على فصل الوصول إلى البيانات. + +استخدم `user_bearer_token` لتحديد نطاق المصادقة للمستخدم الطالب. إذا لم يكن المستخدم مسجل الدخول، فلن يستخدم الطاقم التكاملات المتصلة. وإلا فسيعود إلى رمز الحامل الافتراضي المهيأ لعملية النشر. + +{" "} +![رمز حامل المستخدم](/images/enterprise/user_bearer_token.png) + +{" "} +
+### الكتالوج + +#### الاتصالات والتعاون + +- Gmail — إدارة الرسائل الإلكترونية والمسودات +- Slack — إشعارات وتنبيهات مساحة العمل +- Microsoft — تكامل Office 365 وTeams + +#### إدارة المشاريع + +- Jira — تتبع المشكلات وإدارة المشاريع +- ClickUp — إدارة المهام والإنتاجية +- Asana — تنسيق مهام ومشاريع الفريق +- Notion — إدارة الصفحات وقواعد البيانات +- Linear — تتبع مشاريع البرمجيات والأخطاء +- GitHub — إدارة المستودعات والمشكلات + +#### إدارة علاقات العملاء + +- Salesforce — إدارة حسابات وفرص CRM +- HubSpot — إدارة خط أنابيب المبيعات وجهات الاتصال +- Zendesk — إدارة تذاكر دعم العملاء + +#### الأعمال والمالية + +- Stripe — معالجة المدفوعات وإدارة العملاء +- Shopify — إدارة متجر ومنتجات التجارة الإلكترونية + +#### الإنتاجية والتخزين + +- Google Sheets — مزامنة بيانات جداول البيانات +- Google Calendar — إدارة الأحداث والجداول +- Box — تخزين الملفات وإدارة المستندات + +...والمزيد قادم! + + + + +## الأدوات الداخلية + +أنشئ أدوات مخصصة محلياً، وانشرها في مستودع أدوات CrewAI AMP واستخدمها في وكلائك. + +{" "} + + قبل تشغيل الأوامر أدناه، تأكد من تسجيل الدخول إلى حساب CrewAI AMP + بتشغيل هذا الأمر: ```bash crewai login ``` + + +{" "} + + ![تفاصيل الأداة الداخلية](/images/enterprise/tools-integrations-internal.png) + + +{" "} + + + أنشئ أداة جديدة محلياً. ```bash crewai tool create your-tool ``` + + + انشر الأداة في مستودع أدوات CrewAI AMP. ```bash crewai tool + publish ``` + + + ثبّت الأداة من مستودع أدوات CrewAI AMP. ```bash crewai tool + install your-tool ``` + + + +الإدارة: + +- الاسم والوصف +- الرؤية (خاص / عام) +- متغيرات البيئة المطلوبة +- سجل الإصدارات والتنزيلات +- وصول الفرق والأدوار + +{" "} +![تفاصيل الأداة الداخلية](/images/enterprise/tool-configs.png) + + + + +## ذو صلة + + + + أنشئ وانشر وأدِر إصدارات الأدوات المخصصة لمؤسستك. + + + أتمت سير العمل وتكامل مع المنصات والخدمات الخارجية. + + diff --git a/docs/v1.15.1/ar/enterprise/features/traces.mdx b/docs/v1.15.1/ar/enterprise/features/traces.mdx new file mode 100644 index 000000000..533faae25 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/traces.mdx @@ -0,0 +1,148 @@ +--- +title: التتبعات +description: "استخدام التتبعات لمراقبة طواقمك" +icon: "timeline" +mode: "wide" +--- + +## نظرة عامة + +توفر التتبعات رؤية شاملة لعمليات تنفيذ طواقمك، مما يساعدك على مراقبة الأداء وتصحيح الأخطاء وتحسين سير عمل وكلاء الذكاء الاصطناعي. + +## ما هي التتبعات؟ + +التتبعات في CrewAI AMP هي سجلات تنفيذ مفصلة تلتقط كل جانب من جوانب عمل طاقمك، من المدخلات الأولية إلى المخرجات النهائية. تسجل: + +- أفكار الوكلاء واستدلالاتهم +- تفاصيل تنفيذ المهام +- استخدام الأدوات ومخرجاتها +- مقاييس استهلاك الرموز +- أوقات التنفيذ +- تقديرات التكلفة + +![نظرة عامة على التتبعات](/images/enterprise/traces-overview.png) + +## الوصول إلى التتبعات + + + + في لوحة تحكم CrewAI AMP، انقر على **Traces** لعرض جميع سجلات التنفيذ. + + + + سترى قائمة بجميع عمليات تنفيذ الطاقم، مرتبة حسب التاريخ. انقر على أي عملية تنفيذ لعرض تتبعها المفصل. + + + +## فهم واجهة التتبع + +تنقسم واجهة التتبع إلى عدة أقسام، يقدم كل منها رؤى مختلفة حول تنفيذ طاقمك: + +### 1. ملخص التنفيذ + +يعرض القسم العلوي مقاييس عالية المستوى حول التنفيذ: + +- **إجمالي الرموز**: عدد الرموز المستهلكة عبر جميع المهام +- **رموز الطلب**: الرموز المستخدمة في الطلبات إلى LLM +- **رموز الإكمال**: الرموز المُنشأة في استجابات LLM +- **الطلبات**: عدد استدعاءات API المُجراة +- **وقت التنفيذ**: المدة الإجمالية لتشغيل الطاقم +- **التكلفة المقدرة**: التكلفة التقريبية بناءً على استخدام الرموز + +![ملخص التنفيذ](/images/enterprise/trace-summary.png) + +### 2. المهام والوكلاء + +يعرض هذا القسم جميع المهام والوكلاء الذين كانوا جزءاً من تنفيذ الطاقم: + +- اسم المهمة وتعيين الوكيل +- الوكلاء ونماذج LLM المستخدمة لكل مهمة +- الحالة (مكتملة/فاشلة) +- وقت التنفيذ الفردي للمهمة + +![قائمة المهام](/images/enterprise/trace-tasks.png) + +### 3. المخرجات النهائية + +يعرض النتيجة النهائية التي أنتجها الطاقم بعد اكتمال جميع المهام. + +![المخرجات النهائية](/images/enterprise/final-output.png) + +### 4. الجدول الزمني للتنفيذ + +تمثيل مرئي لوقت بدء وانتهاء كل مهمة، يساعدك على تحديد نقاط الاختناق أو أنماط التنفيذ المتوازي. + +![الجدول الزمني للتنفيذ](/images/enterprise/trace-timeline.png) + +### 5. عرض المهمة المفصل + +عند النقر على مهمة محددة في الجدول الزمني أو قائمة المهام، سترى: + +![عرض المهمة المفصل](/images/enterprise/trace-detailed-task.png) + +- **مفتاح المهمة**: معرّف فريد للمهمة +- **معرّف المهمة**: معرّف تقني في النظام +- **الحالة**: الحالة الحالية (مكتملة/قيد التشغيل/فاشلة) +- **الوكيل**: الوكيل الذي نفّذ المهمة +- **LLM**: نموذج اللغة المستخدم لهذه المهمة +- **وقت البدء/الانتهاء**: متى بدأت المهمة واكتملت +- **وقت التنفيذ**: مدة هذه المهمة المحددة +- **وصف المهمة**: ما طُلب من الوكيل تنفيذه +- **المخرجات المتوقعة**: تنسيق المخرجات المطلوب +- **المدخلات**: أي مدخلات مقدمة لهذه المهمة من مهام سابقة +- **المخرجات**: النتيجة الفعلية التي أنتجها الوكيل + +## استخدام التتبعات لتصحيح الأخطاء + +التتبعات لا تقدر بثمن لاستكشاف المشكلات في طواقمك: + + + + عندما لا ينتج تنفيذ الطاقم النتائج المتوقعة، افحص التتبع لمعرفة أين حدث الخطأ. ابحث عن: + + - المهام الفاشلة + - قرارات الوكيل غير المتوقعة + - أخطاء استخدام الأدوات + - التعليمات المُساء فهمها + + + ![نقاط الفشل](/images/enterprise/failure.png) + + + + + + استخدم مقاييس التنفيذ لتحديد نقاط اختناق الأداء: + + - المهام التي استغرقت وقتاً أطول من المتوقع + - الاستخدام المفرط للرموز + - عمليات الأدوات المكررة + - استدعاءات API غير الضرورية + + + + + حلل استخدام الرموز وتقديرات التكلفة لتحسين كفاءة طاقمك: + + - فكّر في استخدام نماذج أصغر للمهام الأبسط + - صقل الطلبات لتكون أكثر إيجازاً + - خزّن المعلومات المُوصول إليها بشكل متكرر مؤقتاً + - نظّم المهام لتقليل العمليات المكررة + + + + +## الأداء والتجميع + +يجمّع CrewAI تحميلات التتبع لتقليل العبء في عمليات التشغيل ذات الحجم الكبير: + +- يقوم TraceBatchManager بتخزين الأحداث مؤقتاً وإرسالها في دفعات عبر عميل Plus API +- يقلل حركة الشبكة ويحسّن الموثوقية في الاتصالات غير المستقرة +- يُفعّل تلقائياً في مستمع التتبع الافتراضي؛ لا حاجة لتهيئة + +يوفر ذلك تتبعاً أكثر استقراراً تحت الحمل مع الحفاظ على بيانات القياس المفصلة للمهام/الوكلاء. + + + تواصل مع فريق الدعم للمساعدة في تحليل التتبعات أو أي ميزات أخرى في + CrewAI AMP. + diff --git a/docs/v1.15.1/ar/enterprise/features/webhook-streaming.mdx b/docs/v1.15.1/ar/enterprise/features/webhook-streaming.mdx new file mode 100644 index 000000000..562fe0842 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/features/webhook-streaming.mdx @@ -0,0 +1,172 @@ +--- +title: بث Webhook +description: "استخدام بث Webhook لإرسال الأحداث إلى webhook الخاص بك" +icon: "webhook" +mode: "wide" +--- + +## نظرة عامة + +يتيح لك بث أحداث Enterprise تلقي تحديثات webhook في الوقت الفعلي حول طواقمك وتدفقاتك المنشورة على CrewAI AMP، مثل استدعاءات النماذج واستخدام الأدوات وخطوات التدفق. + +## الاستخدام + +عند استخدام Kickoff API، أضف كائن `webhooks` إلى طلبك، على سبيل المثال: + +```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" + } + } +} +``` + +إذا تم تعيين `realtime` إلى `true`، يتم تسليم كل حدث بشكل فردي وفوري، على حساب أداء الطاقم/التدفق. + +## تنسيق Webhook + +يرسل كل webhook قائمة بالأحداث: + +```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." } + ] + } + } + ] +} +``` + +يختلف هيكل كائن `data` حسب نوع الحدث. راجع [قائمة الأحداث](https://github.com/crewAIInc/crewAI/tree/main/lib/crewai/src/crewai/events/types) على GitHub. + +نظراً لأن الطلبات تُرسل عبر HTTP، لا يمكن ضمان ترتيب الأحداث. إذا كنت تحتاج الترتيب، استخدم حقل `timestamp`. + +## الأحداث المدعومة + +يدعم CrewAI كلاً من أحداث النظام والأحداث المخصصة في بث أحداث Enterprise. تُرسل هذه الأحداث إلى نقطة نهاية webhook المُهيأة أثناء تنفيذ الطاقم والتدفق. + +### أحداث التدفق: + +- `flow_created` +- `flow_started` +- `flow_finished` +- `flow_plot` +- `method_execution_started` +- `method_execution_finished` +- `method_execution_failed` + +### أحداث الوكيل: + +- `agent_execution_started` +- `agent_execution_completed` +- `agent_execution_error` +- `lite_agent_execution_started` +- `lite_agent_execution_completed` +- `lite_agent_execution_error` +- `agent_logs_started` +- `agent_logs_execution` +- `agent_evaluation_started` +- `agent_evaluation_completed` +- `agent_evaluation_failed` + +### أحداث الطاقم: + +- `crew_kickoff_started` +- `crew_kickoff_completed` +- `crew_kickoff_failed` +- `crew_train_started` +- `crew_train_completed` +- `crew_train_failed` +- `crew_test_started` +- `crew_test_completed` +- `crew_test_failed` +- `crew_test_result` + +### أحداث المهام: + +- `task_started` +- `task_completed` +- `task_failed` +- `task_evaluation` + +### أحداث استخدام الأدوات: + +- `tool_usage_started` +- `tool_usage_finished` +- `tool_usage_error` +- `tool_validate_input_error` +- `tool_selection_error` +- `tool_execution_error` + +### أحداث LLM: + +- `llm_call_started` +- `llm_call_completed` +- `llm_call_failed` +- `llm_stream_chunk` + +### أحداث حواجز LLM: + +- `llm_guardrail_started` +- `llm_guardrail_completed` + +### أحداث الذاكرة: + +- `memory_query_started` +- `memory_query_completed` +- `memory_query_failed` +- `memory_save_started` +- `memory_save_completed` +- `memory_save_failed` +- `memory_retrieval_started` +- `memory_retrieval_completed` + +### أحداث المعرفة: + +- `knowledge_search_query_started` +- `knowledge_search_query_completed` +- `knowledge_search_query_failed` +- `knowledge_query_started` +- `knowledge_query_completed` +- `knowledge_query_failed` + +### أحداث الاستدلال: + +- `agent_reasoning_started` +- `agent_reasoning_completed` +- `agent_reasoning_failed` + +تتطابق أسماء الأحداث مع ناقل الأحداث الداخلي. راجع GitHub للقائمة الكاملة للأحداث. + +يمكنك إصدار أحداثك المخصصة الخاصة، وسيتم تسليمها عبر تدفق webhook جنباً إلى جنب مع أحداث النظام. + + + + القائمة الكاملة للأحداث + + + تواصل مع فريق الدعم للمساعدة في تكامل webhook أو + استكشاف الأخطاء. + + diff --git a/docs/v1.15.1/ar/enterprise/guides/automation-triggers.mdx b/docs/v1.15.1/ar/enterprise/guides/automation-triggers.mdx new file mode 100644 index 000000000..672a31814 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/automation-triggers.mdx @@ -0,0 +1,321 @@ +--- +title: "نظرة عامة على المشغلات" +description: "فهم كيفية عمل مشغلات CrewAI AMP وكيفية إدارتها وأين تجد أدلة التكامل الخاصة بكل خدمة" +icon: "face-smile" +mode: "wide" +--- + +تربط مشغلات CrewAI AMP أتمتاتك بالأحداث الفورية عبر الأدوات التي تستخدمها فرقك بالفعل. بدلاً من الاستعلام المتكرر عن الأنظمة أو الاعتماد على التشغيل اليدوي، تستمع المشغلات للتغييرات — رسائل بريد إلكتروني جديدة، تحديثات التقويم، تغييرات حالة CRM — وتطلق فوراً الطاقم أو التدفق الذي تحدده. + + + ![نظرة عامة على مشغلات الأتمتة](/images/enterprise/crew_connectors.png) + + +### أدلة التكامل + +تقدم الأدلة المفصلة شرحاً لعملية الإعداد وأمثلة على سير العمل لكل تكامل: + + + + فعّل الطواقم عند وصول رسائل بريد إلكتروني أو تحديث سلاسل المحادثات. + + +{" "} + + + استجب لأحداث التقويم عند إنشائها أو تحديثها أو إلغائها. + + + +{" "} + + + تعامل مع تحميلات وتعديلات وحذف ملفات Drive. + + + +{" "} + + + أتمت الاستجابات لرسائل Outlook الجديدة وتحديثات التقويم. + + + +{" "} + + + راقب نشاط الملفات وتغييرات المشاركة في OneDrive. + + + +{" "} + + + ابدأ سير العمل عند إنشاء محادثات Teams جديدة. + + + +{" "} + + + أطلق الأتمتات من سير عمل HubSpot وأحداث دورة الحياة. + + + +{" "} + + + اربط عمليات Salesforce بـ CrewAI لأتمتة CRM. + + + +{" "} + + + ابدأ الطواقم مباشرة من أوامر Slack. + + + + + اربط CrewAI بآلاف التطبيقات المدعومة من Zapier. + + + +## قدرات المشغلات + +مع المشغلات، يمكنك: + +- **الاستجابة للأحداث الفورية** - تنفيذ سير العمل تلقائياً عند استيفاء شروط محددة +- **التكامل مع الأنظمة الخارجية** - الاتصال بمنصات مثل Gmail وOutlook وOneDrive وJIRA وSlack وStripe والمزيد +- **توسيع نطاق الأتمتة** - التعامل مع أحداث كبيرة الحجم دون تدخل يدوي +- **الحفاظ على السياق** - الوصول إلى بيانات المشغل داخل طواقمك وتدفقاتك + +## إدارة المشغلات + +### عرض المشغلات المتاحة + +للوصول إلى مشغلات الأتمتة وإدارتها: + +1. انتقل إلى عملية النشر في لوحة تحكم CrewAI +2. انقر على علامة تبويب **Triggers** لعرض جميع تكاملات المشغلات المتاحة + + + قائمة مشغلات الأتمتة المتاحة + + +يعرض هذا العرض جميع تكاملات المشغلات المتاحة لعملية النشر، مع حالة الاتصال الحالية. + +### تفعيل وتعطيل المشغلات + +يمكن تفعيل أو تعطيل كل مشغل بسهولة باستخدام مفتاح التبديل: + + + تفعيل أو تعطيل المشغلات بالتبديل + + +- **مُفعّل (تبديل أزرق)**: المشغل نشط وسينفذ عملية النشر تلقائياً عند حدوث الأحداث المحددة +- **مُعطّل (تبديل رمادي)**: المشغل غير نشط ولن يستجيب للأحداث + +انقر ببساطة على التبديل لتغيير حالة المشغل. تسري التغييرات فوراً. + +### مراقبة عمليات تنفيذ المشغلات + +تتبع أداء وسجل عمليات التنفيذ المُشغّلة: + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## بناء أتمتات مدفوعة بالمشغلات + +قبل بناء أتمتتك، من المفيد فهم هيكل حمولات المشغلات التي ستتلقاها طواقمك وتدفقاتك. + +### قائمة فحص إعداد المشغل + +قبل ربط مشغل بالإنتاج، تأكد من: + +- ربط التكامل تحت **Tools & Integrations** وإكمال خطوات OAuth أو مفتاح API +- تفعيل تبديل المشغل في عملية النشر التي يجب أن تستجيب للأحداث +- توفير متغيرات البيئة المطلوبة (رموز API، معرّفات المستأجر، الأسرار المشتركة) +- إنشاء أو تحديث المهام التي يمكنها تحليل الحمولة الواردة في أول مهمة طاقم أو خطوة تدفق +- تحديد ما إذا كنت ستمرر سياق المشغل تلقائياً باستخدام `allow_crewai_trigger_context` +- إعداد المراقبة — سجلات webhook وسجل تنفيذ CrewAI والتنبيهات الخارجية الاختيارية + +### اختبار المشغلات محلياً باستخدام CLI + +يوفر CrewAI CLI أوامر قوية لمساعدتك في تطوير واختبار الأتمتات المدفوعة بالمشغلات دون النشر في الإنتاج. + +#### عرض المشغلات المتاحة + +اعرض جميع المشغلات المتاحة للتكاملات المتصلة: + +```bash +crewai triggers list +``` + +يعرض هذا الأمر جميع المشغلات المتاحة بناءً على تكاملاتك المتصلة، ويظهر: + +- اسم التكامل وحالة الاتصال +- أنواع المشغلات المتاحة +- أسماء وأوصاف المشغلات + +#### محاكاة تنفيذ المشغل + +اختبر طاقمك بحمولات مشغل واقعية قبل النشر: + +```bash +crewai triggers run +``` + +على سبيل المثال: + +```bash +crewai triggers run microsoft_onedrive/file_changed +``` + +يقوم هذا الأمر بـ: + +- تنفيذ طاقمك محلياً +- تمرير حمولة مشغل كاملة وواقعية +- محاكاة كيفية استدعاء طاقمك في الإنتاج بالضبط + + + **ملاحظات تطوير مهمة:** + - استخدم `crewai triggers run ` لمحاكاة تنفيذ المشغل أثناء التطوير + - استخدام `crewai run` لن يحاكي استدعاءات المشغل ولن يمرر حمولة المشغل + - بعد النشر، سيتم تنفيذ طاقمك بحمولة المشغل الفعلية + - إذا كان طاقمك يتوقع معاملات غير موجودة في حمولة المشغل، فقد يفشل التنفيذ + + +### المشغلات مع الطاقم + +تعمل تعريفات طاقمك الحالية بسلاسة مع المشغلات، تحتاج فقط إلى مهمة لتحليل الحمولة المستلمة: + +```python +@CrewBase +class MyAutomatedCrew: + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + ) + + @task + def parse_trigger_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_trigger_payload'], + agent=self.researcher(), + ) + + @task + def analyze_trigger_content(self) -> Task: + return Task( + config=self.tasks_config['analyze_trigger_data'], + agent=self.researcher(), + ) +``` + +سيتلقى الطاقم تلقائياً حمولة المشغل ويمكنه الوصول إليها عبر آليات سياق CrewAI القياسية. + + + يمكن أن تتضمن مدخلات الطاقم والتدفق `crewai_trigger_payload`. يحقن CrewAI + هذه الحمولة تلقائياً: - المهام: تُلحق بوصف المهمة الأولى افتراضياً ("Trigger Payload: {crewai_trigger_payload}") - التحكم + عبر `allow_crewai_trigger_context`: عيّن `True` للحقن دائماً، `False` لعدم + الحقن أبداً - التدفقات: أي دالة `@start()` تقبل معامل + `crewai_trigger_payload` ستستلمه + + +### التكامل مع التدفقات + +للتدفقات، لديك تحكم أكبر في كيفية التعامل مع بيانات المشغل: + +#### الوصول إلى حمولة المشغل + +جميع دوال `@start()` في تدفقاتك ستقبل معاملاً إضافياً يسمى `crewai_trigger_payload`: + +```python +from crewai.flow import Flow, start, listen + +class MyAutomatedFlow(Flow): + @start() + def handle_trigger(self, crewai_trigger_payload: dict = None): + """ + This start method can receive trigger data + """ + if crewai_trigger_payload: + # Process the trigger data + trigger_id = crewai_trigger_payload.get('id') + event_data = crewai_trigger_payload.get('payload', {}) + + # Store in flow state for use by other methods + self.state.trigger_id = trigger_id + self.state.trigger_type = event_data + + return event_data + + # Handle manual execution + return None + + @listen(handle_trigger) + def process_data(self, trigger_data): + """ + Process the data from the trigger + """ + # ... process the trigger +``` + +#### تشغيل الطواقم من التدفقات + +عند تشغيل طاقم داخل تدفق تم تشغيله بمشغل، مرر حمولة المشغل كما هي: + +```python +@start() +def delegate_to_crew(self, crewai_trigger_payload: dict = None): + """ + Delegate processing to a specialized crew + """ + crew = MySpecializedCrew() + + # Pass the trigger payload to the crew + result = crew.crew().kickoff( + inputs={ + 'a_custom_parameter': "custom_value", + 'crewai_trigger_payload': crewai_trigger_payload + }, + ) + + return result +``` + +## استكشاف الأخطاء وإصلاحها + +**المشغل لا يعمل:** + +- تحقق من أن المشغل مُفعّل في علامة تبويب Triggers الخاصة بعملية النشر +- تحقق من حالة اتصال التكامل تحت Tools & Integrations +- تأكد من تهيئة جميع متغيرات البيئة المطلوبة بشكل صحيح + +**فشل التنفيذ:** + +- تحقق من سجلات التنفيذ لتفاصيل الأخطاء +- استخدم `crewai triggers run ` للاختبار محلياً ورؤية هيكل الحمولة بالضبط +- تحقق من أن طاقمك يمكنه التعامل مع معامل `crewai_trigger_payload` +- تأكد من أن طاقمك لا يتوقع معاملات غير مضمنة في حمولة المشغل + +**مشاكل التطوير:** + +- اختبر دائماً باستخدام `crewai triggers run ` قبل النشر لرؤية الحمولة الكاملة +- تذكر أن `crewai run` لا يحاكي استدعاءات المشغل — استخدم `crewai triggers run` بدلاً من ذلك +- استخدم `crewai triggers list` للتحقق من المشغلات المتاحة لتكاملاتك المتصلة +- بعد النشر، سيتلقى طاقمك حمولة المشغل الفعلية، لذا اختبر بدقة محلياً أولاً + +تحوّل مشغلات الأتمتة عمليات نشر CrewAI إلى أنظمة استجابة مدفوعة بالأحداث يمكنها التكامل بسلاسة مع عمليات عملك وأدواتك الحالية. diff --git a/docs/v1.15.1/ar/enterprise/guides/azure-openai-setup.mdx b/docs/v1.15.1/ar/enterprise/guides/azure-openai-setup.mdx new file mode 100644 index 000000000..5bc23a120 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/azure-openai-setup.mdx @@ -0,0 +1,54 @@ +--- +title: "إعداد Azure OpenAI" +description: "تهيئة Azure OpenAI مع Crew Studio لاتصالات LLM المؤسسية" +icon: "microsoft" +mode: "wide" +--- + +يرشدك هذا الدليل خلال ربط Azure OpenAI مع Crew Studio لعمليات الذكاء الاصطناعي المؤسسية السلسة. + +## عملية الإعداد + + + + 1. في Azure، انتقل إلى [Azure AI Foundry](https://ai.azure.com/) > اختر نشر Azure OpenAI الخاص بك. + 2. في القائمة اليسرى، انقر على `Deployments`. إذا لم يكن لديك نشر، أنشئ واحداً بالنموذج المطلوب. + 3. بمجرد الإنشاء، اختر النشر وحدد موقع `Target URI` و`Key` على الجانب الأيمن من الصفحة. أبقِ هذه الصفحة مفتوحة، حيث ستحتاج هذه المعلومات. + + Azure AI Foundry + + + + + 4. في علامة تبويب أخرى، افتح `CrewAI AMP > LLM Connections`. سمِّ اتصال LLM، واختر Azure كمزود، واختر نفس النموذج الذي اخترته في Azure. + 5. في نفس الصفحة، أضف متغيرات البيئة من الخطوة 3: + - واحد بالاسم `AZURE_DEPLOYMENT_TARGET_URL` (باستخدام Target URI). يجب أن يبدو الرابط هكذا: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview + - آخر بالاسم `AZURE_API_KEY` (باستخدام Key). + 6. انقر على `Add Connection` لحفظ اتصال LLM. + + + + 7. في `CrewAI AMP > Settings > Defaults > Crew Studio LLM Settings`، عيّن اتصال LLM والنموذج الجديدين كافتراضيين. + + + + 8. تأكد من إعدادات الوصول إلى الشبكة: + - في Azure، انتقل إلى `Azure OpenAI > اختر النشر`. + - انتقل إلى `Resource Management > Networking`. + - تأكد من تفعيل `Allow access from all networks`. إذا كان هذا الإعداد مقيداً، فقد يُحظر وصول CrewAI إلى نقطة نهاية Azure OpenAI. + + + + +## التحقق + +أنت جاهز! سيستخدم Crew Studio الآن اتصال Azure OpenAI الخاص بك. اختبر الاتصال بإنشاء طاقم أو مهمة بسيطة للتأكد من أن كل شيء يعمل بشكل صحيح. + +## استكشاف الأخطاء وإصلاحها + +إذا واجهت مشكلات: + +- تحقق من أن تنسيق Target URI يتطابق مع النمط المتوقع +- تحقق من صحة مفتاح API وأنه يملك الصلاحيات المناسبة +- تأكد من تهيئة الوصول إلى الشبكة للسماح باتصالات CrewAI +- تأكد من أن نموذج النشر يتطابق مع ما هيأته في CrewAI diff --git a/docs/v1.15.1/ar/enterprise/guides/build-crew.mdx b/docs/v1.15.1/ar/enterprise/guides/build-crew.mdx new file mode 100644 index 000000000..d6cd7f242 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/build-crew.mdx @@ -0,0 +1,48 @@ +--- +title: "بناء طاقم" +description: "الطاقم هو مجموعة من الوكلاء الذين يعملون معاً لإتمام مهمة." +icon: "people-arrows" +mode: "wide" +--- + +## نظرة عامة + +يبسّط [CrewAI AMP](https://app.crewai.com) عملية **إنشاء** و**نشر** و**إدارة** وكلاء الذكاء الاصطناعي في بيئات الإنتاج. + +## البدء + + + +### التثبيت والإعداد + + + اتبع دليل التثبيت القياسي لإعداد CrewAI CLI وإنشاء مشروعك + الأول. + + +### بناء طاقمك + + + اتبع دليل البدء السريع لإنشاء أول طاقم وكلاء باستخدام تهيئة + YAML. + + +## الدعم والموارد + +للدعم الخاص بالمؤسسات أو الأسئلة، تواصل مع فريق الدعم المخصص على [support@crewai.com](mailto:support@crewai.com). + + + احجز وقتاً مع فريقنا لمعرفة المزيد عن ميزات Enterprise وكيف يمكنها + إفادة مؤسستك. + diff --git a/docs/v1.15.1/ar/enterprise/guides/capture_telemetry_logs.mdx b/docs/v1.15.1/ar/enterprise/guides/capture_telemetry_logs.mdx new file mode 100644 index 000000000..36e051fc9 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/capture_telemetry_logs.mdx @@ -0,0 +1,57 @@ +--- +title: "تصدير OpenTelemetry" +description: "تصدير التتبعات والسجلات من عمليات نشر CrewAI AMP إلى مجمّع OpenTelemetry الخاص بك" +icon: "magnifying-glass-chart" +mode: "wide" +--- + +يمكن لـ CrewAI AMP تصدير **التتبعات** و**السجلات** من OpenTelemetry من عمليات النشر مباشرة إلى مجمّعك الخاص. يتيح لك ذلك مراقبة أداء الوكلاء وتتبع استدعاءات LLM وتصحيح الأخطاء باستخدام مجموعة المراقبة الحالية. + +تتبع بيانات القياس [اتفاقيات OpenTelemetry GenAI الدلالية](https://opentelemetry.io/docs/specs/semconv/gen-ai/) بالإضافة إلى سمات خاصة بـ CrewAI. + + +تُعدّ OpenTelemetry **مسار المراقبة الموصى به** — محايدة تجاه الموردين، وتعمل مع أي خلفية متوافقة مع OTLP (Grafana, Honeycomb, NewRelic، أو مجمّعك الخاص). إذا كنت تستخدم Datadog تحديدًا، فراجع دليل [تكامل Datadog](./datadog) المخصص، الذي يغطي كلًا من مسار وكيل Datadog واستيعاب OTLP من Datadog. + + +## المتطلبات المسبقة + + + + يجب أن يكون لدى مؤسستك حساب CrewAI AMP نشط. + + + تحتاج إلى نقطة نهاية مجمّع متوافقة مع OpenTelemetry (مثل OTel Collector الخاص بك أو Datadog أو Grafana أو أي واجهة خلفية متوافقة مع OTLP). + + + +## إعداد مجمّع + +1. في CrewAI AMP، انتقل إلى **Settings** > **OpenTelemetry Collectors**. +2. انقر على **Add Collector**. +3. اختر تكاملاً: + - **OpenTelemetry Traces** و**OpenTelemetry Logs** — صدّر إلى أي مجمّع أو واجهة خلفية متوافقة مع OTLP. + - **Datadog** — أرسل التتبعات مباشرة إلى استقبال OTLP الخاص بـ Datadog، دون الحاجة إلى مجمّع منفصل أو Datadog Agent. +4. هيّئ الاتصال. تعتمد الحقول على التكامل الذي اخترته: + + + + إن **OpenTelemetry Traces** و**OpenTelemetry Logs** تكاملان منفصلان يتشاركان نفس الحقول — اختر التكامل المطابق للإشارة التي تريد تصديرها. + + - **Endpoint** — نقطة نهاية OTLP لمجمّعك (مثل `https://otel-collector.example.com:4317`). + - **Service Name** — اسم لتعريف هذه الخدمة في منصة المراقبة. + - **Custom Headers** *(اختياري)* — أضف رؤوس المصادقة أو التوجيه كأزواج مفتاح-قيمة. + - **Certificate** *(اختياري)* — قدم شهادة TLS إذا كان مجمّعك يتطلبها. + + ![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png) + + + لإعداد Datadog، راجع دليل [تكامل Datadog](./datadog) المخصص — فهو يغطي كلًا من مسار وكيل Datadog (الموصى به، أرخص لحجم السجلات الكبير) واستيعاب OTLP من Datadog، مع خطوات تهيئة كاملة للمجمّع. + + + +5. *(اختياري)* انقر على **Test Connection** للتحقق من قدرة CrewAI على الوصول إلى نقطة النهاية باستخدام بيانات الاعتماد التي قدمتها. +6. انقر على **Save**. + + + يمكنك إضافة مجمّعات متعددة — على سبيل المثال، واحد للتتبعات وآخر للسجلات، أو الإرسال إلى واجهات خلفية مختلفة لأغراض مختلفة. + diff --git a/docs/v1.15.1/ar/enterprise/guides/custom-mcp-server.mdx b/docs/v1.15.1/ar/enterprise/guides/custom-mcp-server.mdx new file mode 100644 index 000000000..eb90dc518 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/custom-mcp-server.mdx @@ -0,0 +1,136 @@ +--- +title: "خوادم MCP المخصصة" +description: "اربط خوادم MCP الخاصة بك بـ CrewAI AMP مع وصول عام أو مصادقة بمفتاح API أو OAuth 2.0" +icon: "plug" +mode: "wide" +--- + +يدعم CrewAI AMP الاتصال بأي خادم MCP يُنفّذ [Model Context Protocol](https://modelcontextprotocol.io/). يمكنك إحضار خوادم عامة لا تتطلب مصادقة، وخوادم محمية بمفتاح API أو رمز حامل، وخوادم تستخدم OAuth 2.0 للوصول المفوّض الآمن. + +## المتطلبات المسبقة + + + + تحتاج إلى حساب [CrewAI AMP](https://app.crewai.com) نشط. + + + رابط خادم MCP الذي تريد الاتصال به. يجب أن يكون الخادم متاحاً من الإنترنت ويدعم نقل Streamable HTTP. + + + +## إضافة خادم MCP مخصص + + + + انتقل إلى **Tools & Integrations** في الشريط الجانبي الأيسر لـ CrewAI AMP، ثم اختر علامة تبويب **Connections**. + + + + انقر على زر **Add Custom MCP Server**. سيظهر مربع حوار مع نموذج التهيئة. + + + + - **Name** (مطلوب): اسم وصفي لخادم MCP (مثل "My Internal Tools Server"). + - **Description**: ملخص اختياري لما يقدمه خادم MCP هذا. + - **Server URL** (مطلوب): الرابط الكامل لنقطة نهاية خادم MCP (مثل `https://my-server.example.com/mcp`). + + + + اختر إحدى طرق المصادقة الثلاث المتاحة بناءً على كيفية تأمين خادم MCP. راجع الأقسام أدناه لتفاصيل كل طريقة. + + + + إذا كان خادم MCP يتطلب رؤوساً إضافية في كل طلب (مثل معرّفات المستأجر أو رؤوس التوجيه)، انقر على **+ Add Header** وقدم اسم الرأس وقيمته. يمكنك إضافة رؤوس مخصصة متعددة. + + + + انقر على **Create MCP Server** لحفظ الاتصال. سيظهر خادم MCP المخصص الآن في قائمة الاتصالات وستكون أدواته متاحة للاستخدام في طواقمك. + + + +## طرق المصادقة + +### بدون مصادقة + +اختر هذا الخيار عندما يكون خادم MCP متاحاً للجمهور ولا يتطلب أي بيانات اعتماد. هذا شائع للخوادم مفتوحة المصدر أو الخوادم الداخلية العاملة خلف VPN. + +### رمز المصادقة + +استخدم هذه الطريقة عندما يكون خادم MCP محمياً بمفتاح API أو رمز حامل. + + + خادم MCP مخصص برمز مصادقة + + +| الحقل | مطلوب | الوصف | +|-------|-------|-------| +| **Header Name** | نعم | اسم رأس HTTP الذي يحمل الرمز (مثل `X-API-Key`، `Authorization`). | +| **Value** | نعم | مفتاح API أو رمز الحامل الخاص بك. | +| **Add to** | لا | أين يتم إرفاق بيانات الاعتماد — **Header** (افتراضي) أو **Query parameter**. | + + +إذا كان خادمك يتوقع رمز `Bearer` في رأس `Authorization`، عيّن Header Name إلى `Authorization` والقيمة إلى `Bearer `. + + +### OAuth 2.0 + +استخدم هذه الطريقة لخوادم MCP التي تتطلب تفويض OAuth 2.0. سيتعامل CrewAI مع تدفق OAuth الكامل، بما في ذلك تحديث الرمز. + + + خادم MCP مخصص مع OAuth 2.0 + + +| الحقل | مطلوب | الوصف | +|-------|-------|-------| +| **Redirect URI** | — | مُعبأ مسبقاً وللقراءة فقط. انسخ هذا الرابط وسجّله كرابط إعادة توجيه مصرّح به في مزود OAuth. | +| **Authorization Endpoint** | نعم | الرابط الذي يُوجَّه إليه المستخدمون لتفويض الوصول (مثل `https://auth.example.com/oauth/authorize`). | +| **Token Endpoint** | نعم | الرابط المستخدم لتبادل رمز التفويض برمز وصول (مثل `https://auth.example.com/oauth/token`). | +| **Client ID** | نعم | معرّف عميل OAuth الصادر من مزودك. | +| **Client Secret** | لا | سر عميل OAuth. غير مطلوب للعملاء العامين باستخدام PKCE. | +| **Scopes** | لا | قائمة نطاقات مفصولة بمسافات للطلب (مثل `read write`). | +| **Token Auth Method** | لا | كيفية إرسال بيانات اعتماد العميل عند تبادل الرموز — **Standard (POST body)** أو **Basic Auth (header)**. الافتراضي هو Standard. | +| **PKCE Supported** | لا | فعّل إذا كان مزود OAuth يدعم Proof Key for Code Exchange. موصى به لتحسين الأمان. | + + +**اكتشاف تهيئة OAuth**: إذا كان مزود OAuth يدعم OpenID Connect Discovery، انقر على رابط **Discover OAuth Config** لملء نقاط نهاية التفويض والرمز تلقائياً من رابط `/.well-known/openid-configuration` الخاص بالمزود. + + +#### إعداد OAuth 2.0 خطوة بخطوة + + + + انسخ **Redirect URI** المعروض في النموذج وأضفه كرابط إعادة توجيه مصرّح به في إعدادات تطبيق مزود OAuth. + + + + املأ **Authorization Endpoint** و**Token Endpoint** و**Client ID**، واختيارياً **Client Secret** و**Scopes**. + + + + اختر **Token Auth Method** المناسبة. معظم المزودين يستخدمون الافتراضي **Standard (POST body)**. بعض المزودين القدامى يتطلبون **Basic Auth (header)**. + + + + حدد **PKCE Supported** إذا كان مزودك يدعمه. يضيف PKCE طبقة أمان إضافية لتدفق رمز التفويض وموصى به لجميع التكاملات الجديدة. + + + + انقر على **Create MCP Server**. سيتم توجيهك إلى مزود OAuth لتفويض الوصول. بمجرد التفويض، سيخزن CrewAI الرموز ويحدّثها تلقائياً حسب الحاجة. + + + +## استخدام خادم MCP المخصص + +بمجرد الاتصال، تظهر أدوات خادم MCP المخصص جنباً إلى جنب مع الاتصالات المدمجة في صفحة **Tools & Integrations**. يمكنك: + +- **تعيين الأدوات للوكلاء** في طواقمك تماماً كأي أداة CrewAI أخرى. +- **إدارة الرؤية** للتحكم في أعضاء الفريق الذين يمكنهم استخدام الخادم. +- **تعديل أو إزالة** الاتصال في أي وقت من قائمة الاتصالات. + + +إذا أصبح خادم MCP غير قابل للوصول أو انتهت صلاحية بيانات الاعتماد، ستفشل استدعاءات الأدوات التي تستخدم ذلك الخادم. تأكد من استقرار رابط الخادم وتحديث بيانات الاعتماد. + + + + تواصل مع فريق الدعم للمساعدة في تهيئة خادم MCP المخصص أو استكشاف الأخطاء. + diff --git a/docs/v1.15.1/ar/enterprise/guides/datadog.mdx b/docs/v1.15.1/ar/enterprise/guides/datadog.mdx new file mode 100644 index 000000000..1a3ee818f --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/datadog.mdx @@ -0,0 +1,295 @@ +--- +title: "تكامل Datadog" +description: "راقب عمليات نشر CrewAI AMP المُستضافة ذاتيًا في Datadog عبر وكيل Datadog أو استيعاب OTLP من Datadog — يوفر كلا المسارين نفس الواجهات المهيكلة لاستيراد لوحة معلومات العمليات الجاهزة." +icon: "dog" +mode: "wide" +--- + + +**الترجمة قيد التقدم** — يتم عرض المحتوى باللغة الإنجليزية. + + +CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes. + + +For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs). + + +## Choose a path + +CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure. + + + + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + + **Setup:** + 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). + 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. + 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + + **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. + + + CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend. + + **Setup:** + 1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**. + 2. Configure the connection: + - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/): + - `otlp.datadoghq.com` (US1) + - `otlp.us3.datadoghq.com` (US3) + - `otlp.us5.datadoghq.com` (US5) + - `otlp.datadoghq.eu` (EU1) + - `otlp.ap1.datadoghq.com` (AP1) + - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + 3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list. + 4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step. + + ![Datadog collector configuration](/images/crewai-otel-collector-datadog.png) + + **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup. + + + +Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice. + +## Log schema reference + + +This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). + + +When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. + +### Why JSON output + + + + Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field. + + + Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration. + + + Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces. + + + The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed. + + + +### Enabling JSON output + +`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. + +```shell +CREWAI_LOG_FORMAT=json +``` + +Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. + + + The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. + + +### Example events + +A single info-level log inside an active automation kickoff: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:23.482914Z", + "level": "INFO", + "logger": "crewai_enterprise.utilities.pii_redaction", + "crewai_version": "1.14.7", + "msg": "PII tracking state reset (engines preserved)", + "automation_id": "12", + "task_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow" +} +``` + +An error with a Python exception is collapsed into a single event with the traceback as a string: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:31.218450Z", + "level": "ERROR", + "logger": "api.tasks.flow_run_task", + "crewai_version": "1.14.7", + "msg": "Flow execution failed", + "automation_id": "12", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow", + "exception": { + "type": "ValueError", + "message": "Topic cannot be empty", + "stacktrace": "Traceback (most recent call last):\n File \"/app/flow.py\", line 42, in summarize\n ...\nValueError: Topic cannot be empty\n" + } +} +``` + +The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. + +### Schema v1 fields + +Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded. + +| Field | Type | Always present | Source | +|-------|------|----------------|--------| +| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. | +| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. | +| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. | +| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. | +| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. | +| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). | +| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). | +| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. | +| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. | +| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. | +| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. | +| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. | +| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. | +| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. | + + + Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable. + + +### Stability promise + +The `schema` field declares the contract. Within `v1`, CrewAI commits to: + +- **Never removing a field** that customers may have built queries or dashboards against. +- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle. +- **Adding new fields** at any time. Consumers should ignore unknown top-level keys. + +When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate. + +## Prerequisite: promote facets + +Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account. + + + + Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event. + + + Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**. + + - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id` + - `crewai_version`, `model_id` + - `exception.type`, `exception.message` + + Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard. + + + +## Import the dashboard + + + + Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine. + + + Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**. + + + Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**. + + Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range. + + + + + Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI. + + +## What you get + +The dashboard is organized into four sections plus a placeholder for a custom drill-down widget: + +| Section | Widgets | Useful for | +|---------|---------|------------| +| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). | +| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. | +| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. | +| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. | +| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. | + +Three template variables at the top of the dashboard re-scope every widget at once: + +- **`$automation`** — filter to a single automation by name. +- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior). +- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account). + +## Verify ingestion + +Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path: + + + + Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. + + If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + + + Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). + + If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved. + + + +## Customize + +The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing. + +### Add a Recent Errors log stream + +The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures: + +1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group. +2. Drag in a **Log Stream** widget. +3. Set the filter query to `status:error $automation $version $service`. +4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`. +5. Sort by most recent, limit to 25 entries. + +Clicking any row jumps to Logs Explorer with the same filter pre-applied. + +### Add p95 latency + +Logs don't include execution duration by default. Two ways to add a latency widget: + +- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration. +- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM. + +### Re-scope to multiple deployments + +The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +|---------|--------------|-----| +| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | +| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | +| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | + +## Next steps + + + + Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends. + + + Reference for customizing widget queries against the structured facets above. + + diff --git a/docs/v1.15.1/ar/enterprise/guides/deploy-to-amp.mdx b/docs/v1.15.1/ar/enterprise/guides/deploy-to-amp.mdx new file mode 100644 index 000000000..b62faec53 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/deploy-to-amp.mdx @@ -0,0 +1,451 @@ +--- +title: "النشر على AMP" +description: "انشر طاقمك أو تدفقك على CrewAI AMP" +icon: "rocket" +mode: "wide" +--- + + + بعد إنشاء طاقم أو تدفق محلياً (أو عبر Crew Studio)، الخطوة التالية هي + نشره على منصة CrewAI AMP. يغطي هذا الدليل طرق نشر متعددة + لمساعدتك في اختيار النهج الأفضل لسير عملك. + + +## المتطلبات المسبقة + + + + يجب أن يكون لديك طاقم أو تدفق يعمل بنجاح محلياً. + اتبع [دليل التحضير](/ar/enterprise/guides/prepare-for-deployment) للتحقق من بنية مشروعك. + + + يجب أن يكون الكود في مستودع GitHub (لطريقة تكامل + GitHub) + + + + + **الطواقم مقابل التدفقات**: يمكن نشر كلا نوعي المشاريع كـ "أتمتات" على CrewAI AMP. + عملية النشر هي نفسها، لكن لهما بنى مشاريع مختلفة. + راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment) للتفاصيل. + + +## الخيار 1: النشر باستخدام CrewAI CLI + +يوفر CLI أسرع طريقة لنشر الطواقم أو التدفقات المطورة محلياً على منصة AMP. +يكتشف CLI تلقائياً نوع مشروعك من `pyproject.toml` ويبني وفقاً لذلك. + + + + إذا لم تكن قد فعلت بالفعل، ثبّت CrewAI CLI: + + ```bash + pip install crewai[tools] + ``` + + + يأتي CLI مع حزمة CrewAI الرئيسية، لكن الإضافة `[tools]` تضمن حصولك على جميع اعتماديات النشر. + + + + + + أولاً، تحتاج لمصادقة CLI مع منصة CrewAI AMP: + + ```bash + # إذا كان لديك حساب CrewAI AMP بالفعل، أو تريد إنشاء واحد: + crewai login + ``` + + عند تشغيل أي من الأمرين، سيقوم CLI بـ: + 1. عرض رابط ورمز جهاز فريد + 2. فتح متصفحك على صفحة المصادقة + 3. طلب تأكيد الجهاز + 4. إتمام عملية المصادقة + + عند المصادقة الناجحة، سترى رسالة تأكيد في الطرفية! + + + + + + من مجلد مشروعك، شغّل: + + ```bash + crewai deploy create + ``` + + سيقوم هذا الأمر بـ: + 1. اكتشاف معلومات مستودع GitHub + 2. تحديد متغيرات البيئة في ملف `.env` المحلي + 3. نقل هذه المتغيرات بأمان إلى منصة Enterprise + 4. إنشاء عملية نشر جديدة بمعرّف فريد + + عند الإنشاء الناجح، سترى رسالة مثل: + ```shell + Deployment created successfully! + Name: your_project_name + Deployment ID: 01234567-89ab-cdef-0123-456789abcdef + Current Status: Deploy Enqueued + ``` + + + + + + تتبع حالة النشر بـ: + + ```bash + crewai deploy status + ``` + + للسجلات المفصلة لعملية البناء: + + ```bash + crewai deploy logs + ``` + + + يستغرق النشر الأول عادة حوالي دقيقة واحدة. + + + + + +## أوامر CLI إضافية + +يقدم CrewAI CLI عدة أوامر لإدارة عمليات النشر: + +```bash +# عرض جميع عمليات النشر +crewai deploy list + +# الحصول على حالة النشر +crewai deploy status + +# عرض سجلات النشر +crewai deploy logs + +# دفع التحديثات بعد تغييرات الكود +crewai deploy push + +# إزالة عملية نشر +crewai deploy remove +``` + +## الخيار 2: النشر مباشرة عبر واجهة الويب + +يمكنك أيضاً نشر طواقمك أو تدفقاتك مباشرة عبر واجهة ويب CrewAI AMP بربط حساب GitHub. لا يتطلب هذا النهج استخدام CLI على جهازك المحلي. تكتشف المنصة تلقائياً نوع مشروعك وتتعامل مع البناء بشكل مناسب. + + + + + +تحتاج لدفع طاقمك إلى مستودع GitHub. إذا لم تكن قد أنشأت طاقماً بعد، يمكنك [اتباع هذا الدليل](/ar/quickstart). + + + + + + 1. سجّل الدخول إلى [CrewAI AMP](https://app.crewai.com) + 2. انقر على زر "Connect GitHub" + + + ![زر ربط GitHub](/images/enterprise/connect-github.png) + + + + + + + بعد ربط حساب GitHub، ستتمكن من اختيار المستودع للنشر: + + + ![اختيار المستودع](/images/enterprise/select-repo.png) + + + + إذا كان Crew أو Flow داخل مجلد فرعي في monorepo، فوسّع **Advanced** + وعيّن دليل عمل قبل النشر. راجع + [النشر من Monorepo](/ar/enterprise/guides/monorepo-deployments). + + + + + + + قبل النشر، ستحتاج لإعداد متغيرات البيئة للاتصال بمزود LLM أو خدمات أخرى: + + 1. يمكنك إضافة المتغيرات فردياً أو بشكل جماعي + 2. أدخل متغيرات البيئة بتنسيق `KEY=VALUE` (واحد لكل سطر) + + + ![تعيين متغيرات البيئة](/images/enterprise/set-env-variables.png) + + + + تستخدم حزم Python خاصة؟ ستحتاج لإضافة بيانات اعتماد السجل هنا أيضاً. + راجع [سجلات الحزم الخاصة](/ar/enterprise/guides/private-package-registry) للمتغيرات المطلوبة. + + + + + + + 1. انقر على زر "Deploy" لبدء عملية النشر + 2. يمكنك مراقبة التقدم عبر شريط التقدم + 3. يستغرق النشر الأول عادة حوالي دقيقة واحدة + + + ![تقدم النشر](/images/enterprise/deploy-progress.png) + + + بمجرد اكتمال النشر، سترى: + - رابط طاقمك الفريد + - رمز Bearer لحماية API طاقمك + - زر "Delete" إذا كنت تحتاج لإزالة النشر + + + + + +## الخيار 3: إعادة النشر باستخدام API (تكامل CI/CD) + +لعمليات النشر الآلية في خطوط أنابيب CI/CD، يمكنك استخدام CrewAI API لتشغيل إعادة نشر الطواقم الحالية. هذا مفيد بشكل خاص لـ GitHub Actions وJenkins أو سير عمل الأتمتة الأخرى. + + + + + انتقل إلى إعدادات حساب CrewAI AMP لإنشاء رمز API: + + 1. انتقل إلى [app.crewai.com](https://app.crewai.com) + 2. انقر على **Settings** → **Account** → **Personal Access Token** + 3. أنشئ رمزاً جديداً وانسخه بأمان + 4. خزّن هذا الرمز كسر في نظام CI/CD + + + + + + حدد موقع المعرّف الفريد لطاقمك المنشور: + + 1. انتقل إلى **Automations** في لوحة تحكم CrewAI AMP + 2. اختر الأتمتة/الطاقم الحالي + 3. انقر على **Additional Details** + 4. انسخ **UUID** — يحدد هذا نشر طاقمك المحدد + + + + + + استخدم نقطة نهاية Deploy API لتشغيل إعادة النشر: + + ```bash + curl -i -X POST \ + -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \ + https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy + + # HTTP/2 200 + # content-type: application/json + # + # { + # "uuid": "your-automation-uuid", + # "status": "Deploy Enqueued", + # "public_url": "https://your-crew-deployment.crewai.com", + # "token": "your-bearer-token" + # } + ``` + + + إذا تم إنشاء أتمتتك متصلة بـ Git أولاً، سيسحب API تلقائياً أحدث التغييرات من مستودعك قبل إعادة النشر. + + + + + + + إليك سير عمل GitHub Actions مع مشغلات نشر أكثر تعقيداً: + + ```yaml + name: Deploy CrewAI Automation + + on: + push: + branches: [ main ] + pull_request: + types: [ labeled ] + release: + types: [ published ] + + jobs: + deploy: + runs-on: ubuntu-latest + if: | + (github.event_name == 'push' && github.ref == 'refs/heads/main') || + (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) || + (github.event_name == 'release') + steps: + - name: Trigger CrewAI Redeployment + run: | + curl -X POST \ + -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \ + https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy + ``` + + + أضف `CREWAI_PAT` و`CREWAI_AUTOMATION_UUID` كأسرار مستودع. لعمليات نشر PR، أضف تسمية "deploy" لتشغيل سير العمل. + + + + + + +## التفاعل مع أتمتتك المنشورة + +بمجرد اكتمال النشر، يمكنك الوصول إلى طاقمك عبر: + +1. **REST API**: تنشئ المنصة نقطة نهاية HTTPS فريدة بهذه المسارات الرئيسية: + + - `/inputs`: يعرض معاملات الإدخال المطلوبة + - `/kickoff`: يبدأ التنفيذ بالمدخلات المقدمة + - `/status/{kickoff_id}`: يتحقق من حالة التنفيذ + +2. **واجهة الويب**: زر [app.crewai.com](https://app.crewai.com) للوصول إلى: + - **علامة تبويب Status**: عرض معلومات النشر وتفاصيل نقطة نهاية API ورمز المصادقة + - **علامة تبويب Run**: تمثيل مرئي لبنية طاقمك + - **علامة تبويب Executions**: سجل جميع عمليات التنفيذ + - **علامة تبويب Metrics**: تحليلات الأداء + - **علامة تبويب Traces**: رؤى التنفيذ المفصلة + +### تشغيل عملية تنفيذ + +من لوحة تحكم Enterprise، يمكنك: + +1. النقر على اسم طاقمك لفتح تفاصيله +2. اختيار "Trigger Crew" من واجهة الإدارة +3. إدخال المدخلات المطلوبة في النافذة المنبثقة +4. مراقبة التقدم أثناء مرور التنفيذ عبر خط الأنابيب + +### المراقبة والتحليلات + +توفر منصة Enterprise ميزات مراقبة شاملة: + +- **إدارة التنفيذ**: تتبع عمليات التشغيل النشطة والمكتملة +- **التتبعات**: تحليلات مفصلة لكل عملية تنفيذ +- **المقاييس**: استخدام الرموز وأوقات التنفيذ والتكاليف +- **عرض الجدول الزمني**: تمثيل مرئي لتسلسل المهام + +### ميزات متقدمة + +تقدم منصة Enterprise أيضاً: + +- **إدارة متغيرات البيئة**: تخزين وإدارة مفاتيح API بأمان +- **اتصالات LLM**: تهيئة التكاملات مع مزودي LLM المختلفين +- **مستودع الأدوات المخصصة**: إنشاء ومشاركة وتثبيت الأدوات +- **Crew Studio**: بناء الطواقم عبر واجهة محادثة دون كتابة كود + +## استكشاف أخطاء النشر وإصلاحها + +إذا فشل النشر، تحقق من هذه المشكلات الشائعة: + +### فشل البناء + +#### ملف uv.lock مفقود + +**العرض**: فشل البناء مبكراً مع أخطاء حل الاعتماديات + +**الحل**: أنشئ ملف القفل وارفعه: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + + + ملف `uv.lock` مطلوب لجميع عمليات النشر. بدونه، لا يمكن للمنصة + تثبيت اعتمادياتك بشكل موثوق. + + +#### بنية المشروع الخاطئة + +**العرض**: أخطاء "Could not find entry point" أو "Module not found" + +**الحل**: تحقق من أن مشروعك يتطابق مع البنية المتوقعة: + +- **JSON-first Crews**: أبقِ `crew.jsonc` أو `crew.json` و `agents/` في جذر المشروع +- **Crews كلاسيكية**: استخدم `src/project_name/main.py` مع دالة دخول `run()` +- **Flows**: استخدم `src/project_name/main.py` مع دالة دخول `kickoff()` + +راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment) لمخططات البنية المفصلة. + +#### مُزخرف CrewBase مفقود في crew كلاسيكية + +**العرض**: أخطاء "Crew not found" أو "Config not found" أو أخطاء تهيئة الوكيل/المهمة + +**الحل**: في crews الكلاسيكية Python/YAML، تأكد من أن جميع فئات الـ crew تستخدم مُزخرف `@CrewBase`. لا تحتاج crews بنمط JSON-first إلى هذا المزخرف. + +```python +from crewai.project import CrewBase, agent, crew, task + +@CrewBase # This decorator is REQUIRED +class YourCrew(): + """Your crew description""" + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + # ... rest of crew definition +``` + + + ينطبق هذا على فئات crew الكلاسيكية المكتوبة في Python، بما في ذلك crews الكلاسيكية المضمنة داخل مشاريع Flow. + يتم التحقق من crews بنمط JSON-first من `crew.jsonc` و `agents/` بدلاً من ذلك. + + +#### نوع pyproject.toml غير صحيح + +**العرض**: نجاح البناء لكن فشل وقت التشغيل، أو سلوك غير متوقع + +**الحل**: تحقق من أن قسم `[tool.crewai]` يتطابق مع نوع مشروعك: + +```toml +# For Crew projects: +[tool.crewai] +type = "crew" + +# For Flow projects: +[tool.crewai] +type = "flow" +``` + +### فشل وقت التشغيل + +#### فشل اتصال LLM + +**العرض**: أخطاء مفتاح API، "model not found"، أو فشل المصادقة + +**الحل**: +1. تحقق من صحة تعيين مفتاح API لمزود LLM في متغيرات البيئة +2. تأكد من تطابق أسماء متغيرات البيئة مع ما يتوقعه الكود +3. اختبر محلياً بنفس متغيرات البيئة بالضبط قبل النشر + +#### أخطاء تنفيذ الطاقم + +**العرض**: يبدأ الطاقم لكن يفشل أثناء التنفيذ + +**الحل**: +1. تحقق من سجلات التنفيذ في لوحة تحكم AMP (علامة تبويب Traces) +2. تحقق من أن جميع الأدوات لديها مفاتيح API المطلوبة مُهيأة +3. في crews بنمط JSON-first، تحقق من `crew.jsonc` والملفات المشار إليها داخل `agents/` +4. في crews الكلاسيكية، تأكد من صحة `agents.yaml` و `tasks.yaml` + + + تواصل مع فريق الدعم للمساعدة في مشاكل النشر أو أسئلة حول + منصة AMP. + diff --git a/docs/v1.15.1/ar/enterprise/guides/enable-crew-studio.mdx b/docs/v1.15.1/ar/enterprise/guides/enable-crew-studio.mdx new file mode 100644 index 000000000..2393a5412 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/enable-crew-studio.mdx @@ -0,0 +1,179 @@ +--- +title: "تفعيل Crew Studio" +description: "تفعيل Crew Studio على CrewAI AMP" +icon: "comments" +mode: "wide" +--- + + + Crew Studio هو أداة قوية **بدون كود/منخفضة الكود** تتيح لك بسرعة + بناء أو هيكلة الطواقم عبر واجهة محادثة. + + +## ما هو Crew Studio؟ + +Crew Studio هو طريقة مبتكرة لإنشاء طواقم وكلاء الذكاء الاصطناعي بدون كتابة كود. + + + ![واجهة Crew Studio](/images/enterprise/crew-studio-interface.png) + + +مع Crew Studio، يمكنك: + +- الدردشة مع مساعد الطاقم لوصف مشكلتك +- إنشاء الوكلاء والمهام تلقائياً +- اختيار الأدوات المناسبة +- تهيئة المدخلات الضرورية +- إنشاء كود قابل للتنزيل للتخصيص +- النشر مباشرة على منصة CrewAI AMP + +## خطوات التهيئة + +قبل البدء باستخدام Crew Studio، تحتاج لتهيئة اتصالات LLM: + + + + انتقل إلى علامة تبويب **LLM Connections** في لوحة تحكم CrewAI AMP وأنشئ اتصال LLM جديداً. + + + يمكنك استخدام أي مزود LLM تريده ويدعمه CrewAI. + + + هيّئ اتصال LLM: + + - أدخل `Connection Name` (مثل `OpenAI`) + - اختر مزود النموذج: `openai` أو `azure` + - اختر النماذج التي تريد استخدامها في طواقم Studio + - نوصي بـ `gpt-4o` و`o1-mini` و`gpt-4o-mini` على الأقل + - أضف مفتاح API كمتغير بيئة: + - لـ OpenAI: أضف `OPENAI_API_KEY` مع مفتاح API + - لـ Azure OpenAI: راجع [هذه المقالة](https://blog.crewai.com/configuring-azure-openai-with-crewai-a-comprehensive-guide/) لتفاصيل التهيئة + - انقر على `Add Connection` لحفظ التهيئة + + + ![تهيئة اتصال LLM](/images/enterprise/llm-connection-config.png) + + + + + + بمجرد إتمام الإعداد، سترى الاتصال الجديد مُضافاً إلى قائمة الاتصالات المتاحة. + + + ![تم إضافة الاتصال](/images/enterprise/connection-added.png) + + + + + + في القائمة الرئيسية، انتقل إلى **Settings → Defaults** وهيّئ إعدادات LLM الافتراضية: + + - اختر النماذج الافتراضية للوكلاء والمكونات الأخرى + - عيّن التهيئات الافتراضية لـ Crew Studio + + انقر على `Save Settings` لتطبيق تغييراتك. + + + ![تهيئة إعدادات LLM الافتراضية](/images/enterprise/llm-defaults.png) + + + + + +## استخدام Crew Studio + +الآن بعد تهيئة اتصال LLM والإعدادات الافتراضية، أنت جاهز لبدء استخدام Crew Studio! + + + + انتقل إلى قسم **Studio** في لوحة تحكم CrewAI AMP. + + + + ابدأ محادثة مع مساعد الطاقم بوصف المشكلة التي تريد حلها: + + ```md + I need a crew that can research the latest AI developments and create a summary report. + ``` + + سيطرح مساعد الطاقم أسئلة توضيحية لفهم متطلباتك بشكل أفضل. + + + + + راجع تهيئة الطاقم المُنشأ، بما في ذلك: + + - الوكلاء وأدوارهم + - المهام المطلوب تنفيذها + - المدخلات المطلوبة + - الأدوات المستخدمة + + هذه فرصتك لتنقيح التهيئة قبل المتابعة. + + + + + بمجرد رضاك عن التهيئة، يمكنك: + + - تنزيل الكود المُنشأ للتخصيص المحلي + - نشر الطاقم مباشرة على منصة CrewAI AMP + - تعديل التهيئة وإعادة إنشاء الطاقم + + + + + بعد النشر، اختبر طاقمك بمدخلات نموذجية للتأكد من أنه يعمل كما هو متوقع. + + + + + للحصول على أفضل النتائج، قدم أوصافاً واضحة ومفصلة لما تريد أن + يحققه طاقمك. ضمّن مدخلات ومخرجات محددة متوقعة في + وصفك. + + +## مثال على سير العمل + +إليك سير عمل نموذجي لإنشاء طاقم مع Crew Studio: + + + + ابدأ بوصف مشكلتك: + + ```md + I need a crew that can analyze financial news and provide investment recommendations + ``` + + + + + أجب على أسئلة التوضيح من مساعد الطاقم لتنقيح + متطلباتك. + + + + راجع خطة الطاقم المُنشأة، التي قد تتضمن: + + - وكيل بحث لجمع الأخبار المالية + - وكيل تحليل لتفسير البيانات + - وكيل توصيات لتقديم نصائح استثمارية + + + + + وافق على الخطة أو اطلب تغييرات إذا لزم الأمر. + + + + نزّل الكود للتخصيص أو انشر مباشرة على المنصة. + + + + اختبر طاقمك بمدخلات نموذجية ونقّح حسب الحاجة. + + + + + تواصل مع فريق الدعم للمساعدة في Crew Studio أو أي ميزات أخرى في CrewAI + AMP. + diff --git a/docs/v1.15.1/ar/enterprise/guides/gmail-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/gmail-trigger.mdx new file mode 100644 index 000000000..5423109c0 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/gmail-trigger.mdx @@ -0,0 +1,97 @@ +--- +title: "مشغل Gmail" +description: "تشغيل الأتمتات عند حدوث أحداث Gmail (مثل رسائل بريد إلكتروني جديدة، تسميات)." +icon: "envelope" +mode: "wide" +--- + +## نظرة عامة + +استخدم مشغل Gmail لتشغيل طواقمك المنشورة عند حدوث أحداث Gmail في الحسابات المتصلة، مثل استلام رسالة بريد إلكتروني جديدة أو رسائل تطابق تسمية/فلتر. + + + تأكد من ربط Gmail في Tools & Integrations وتفعيل المشغل + لعملية النشر. + + +## تفعيل مشغل Gmail + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Gmail** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: معالجة الرسائل الجديدة + +عند وصول رسالة بريد إلكتروني جديدة، سيرسل مشغل Gmail الحمولة إلى طاقمك أو تدفقك. فيما يلي مثال على طاقم يحلل ويعالج حمولة المشغل. + +```python +@CrewBase +class GmailProcessingCrew: + @agent + def parser(self) -> Agent: + return Agent( + config=self.agents_config['parser'], + ) + + @task + def parse_gmail_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_gmail_payload'], + agent=self.parser(), + ) + + @task + def act_on_email(self) -> Task: + return Task( + config=self.tasks_config['act_on_email'], + agent=self.parser(), + ) +``` + +ستكون حمولة Gmail متاحة عبر آليات السياق القياسية. + +### الاختبار المحلي + +اختبر تكامل مشغل Gmail محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Gmail بحمولة واقعية +crewai triggers run gmail/new_email_received +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Gmail كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run gmail/new_email_received` (وليس `crewai run`) لمحاكاة + تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## مراقبة عمليات التنفيذ + +تتبع سجل وأداء عمليات التشغيل المُشغّلة: + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من ربط Gmail في Tools & Integrations +- تحقق من تفعيل مشغل Gmail في علامة تبويب Triggers +- اختبر محلياً بـ `crewai triggers run gmail/new_email_received` لرؤية هيكل الحمولة بالضبط +- تحقق من سجلات التنفيذ وتأكد من تمرير الحمولة كـ `crewai_trigger_payload` +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/v1.15.1/ar/enterprise/guides/google-calendar-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/google-calendar-trigger.mdx new file mode 100644 index 000000000..542df5b18 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/google-calendar-trigger.mdx @@ -0,0 +1,83 @@ +--- +title: "مشغل Google Calendar" +description: "تشغيل الطواقم عند إنشاء أو تحديث أو إلغاء أحداث Google Calendar" +icon: "calendar" +mode: "wide" +--- + +## نظرة عامة + +استخدم مشغل Google Calendar لإطلاق الأتمتات كلما تغيرت أحداث التقويم. تشمل حالات الاستخدام الشائعة إحاطة الفريق قبل اجتماع، وإخطار أصحاب المصلحة عند إلغاء حدث هام، أو تلخيص الجداول اليومية. + + + تأكد من ربط Google Calendar في **Tools & Integrations** وتفعيله + لعملية النشر التي تريد أتمتتها. + + +## تفعيل مشغل Google Calendar + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Google Calendar** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص تفاصيل الاجتماع + +المقتطف أدناه يعكس مثال `calendar-event-crew.py` في مستودع المشغلات. يحلل الحمولة، ويحلل الحاضرين والتوقيت، وينتج ملخصاً للاجتماع للأدوات اللاحقة. + +```python +from calendar_event_crew import GoogleCalendarEventTrigger + +crew = GoogleCalendarEventTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": calendar_payload, +}) +print(result.raw) +``` + +استخدم `crewai_trigger_payload` تماماً كما يتم تسليمه من المشغل حتى يتمكن الطاقم من استخراج الحقول المناسبة. + +## الاختبار المحلي + +اختبر تكامل مشغل Google Calendar محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Google Calendar بحمولة واقعية +crewai triggers run google_calendar/event_changed +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Calendar كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run google_calendar/event_changed` (وليس `crewai run`) لمحاكاة + تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## مراقبة عمليات التنفيذ + +تتبع قائمة **Executions** في لوحة تحكم النشر كل عملية تشغيل مُشغّلة وتعرض بيانات الحمولة الوصفية وملخصات المخرجات والأخطاء. + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من ربط حساب Google الصحيح وتفعيل المشغل +- اختبر محلياً بـ `crewai triggers run google_calendar/event_changed` لرؤية هيكل الحمولة بالضبط +- تأكد من أن سير عملك يتعامل مع أحداث اليوم الكامل (الحمولات تستخدم `start.date` و`end.date` بدلاً من الطوابع الزمنية) +- تحقق من سجلات التنفيذ إذا كانت التذكيرات أو مصفوفات الحاضرين مفقودة — قد تحد صلاحيات التقويم من الحقول في الحمولة +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/v1.15.1/ar/enterprise/guides/google-drive-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/google-drive-trigger.mdx new file mode 100644 index 000000000..0f4c05ec4 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/google-drive-trigger.mdx @@ -0,0 +1,80 @@ +--- +title: "مشغل Google Drive" +description: "الاستجابة لأحداث ملفات Google Drive بطواقم آلية" +icon: "folder" +mode: "wide" +--- + +## نظرة عامة + +شغّل أتمتاتك عند إنشاء أو تحديث أو حذف ملفات في Google Drive. تشمل سير العمل النموذجية تلخيص المحتوى المُحمّل حديثاً، وتطبيق سياسات المشاركة، أو إخطار المالكين عند تغيير ملفات هامة. + + + اربط Google Drive في **Tools & Integrations** وتأكد من تفعيل المشغل + للأتمتة التي تريد مراقبتها. + + +## تفعيل مشغل Google Drive + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Google Drive** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص نشاط الملفات + +تحلل طواقم Drive النموذجية الحمولة لاستخراج بيانات الملف الوصفية وتقييم الصلاحيات ونشر ملخص. + +```python +from drive_file_crew import GoogleDriveFileTrigger + +crew = GoogleDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": drive_payload, +}) +``` + +## الاختبار المحلي + +اختبر تكامل مشغل Google Drive محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Google Drive بحمولة واقعية +crewai triggers run google_drive/file_changed +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Drive كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run google_drive/file_changed` (وليس `crewai run`) لمحاكاة + تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## مراقبة عمليات التنفيذ + +تتبع سجل وأداء عمليات التشغيل المُشغّلة عبر قائمة **Executions** في لوحة تحكم النشر. + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## استكشاف الأخطاء وإصلاحها + +- تحقق من ربط Google Drive وتفعيل مفتاح التبديل للمشغل +- اختبر محلياً بـ `crewai triggers run google_drive/file_changed` لرؤية هيكل الحمولة بالضبط +- إذا كانت الحمولة تفتقد بيانات الصلاحيات، تأكد من أن الحساب المتصل لديه صلاحية الوصول إلى الملف أو المجلد +- يرسل المشغل معرّفات الملفات فقط؛ استخدم Drive API إذا كنت تحتاج جلب المحتوى الثنائي أثناء تشغيل الطاقم +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/v1.15.1/ar/enterprise/guides/hubspot-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/hubspot-trigger.mdx new file mode 100644 index 000000000..20c31aef6 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/hubspot-trigger.mdx @@ -0,0 +1,61 @@ +--- +title: "مشغل HubSpot" +description: "تشغيل طواقم CrewAI مباشرة من سير عمل HubSpot" +icon: "hubspot" +mode: "wide" +--- + +يقدم هذا الدليل عملية خطوة بخطوة لإعداد مشغلات HubSpot لـ CrewAI AMP، مما يتيح لك بدء الطواقم مباشرة من سير عمل HubSpot. + +## المتطلبات المسبقة + +- حساب CrewAI AMP +- حساب HubSpot مع ميزة [HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows) + +## خطوات الإعداد + + + + - سجّل الدخول إلى `حساب CrewAI AMP > Triggers` - اختر `HubSpot` من + قائمة المشغلات المتاحة - اختر حساب HubSpot الذي تريد ربطه + بـ CrewAI AMP - اتبع التعليمات على الشاشة لتفويض وصول CrewAI AMP + إلى حساب HubSpot - ستظهر رسالة تأكيد بمجرد + ربط HubSpot بنجاح مع CrewAI AMP + + + - سجّل الدخول إلى `حساب HubSpot > Automations > Workflows > New workflow` + - اختر نوع سير العمل المناسب لاحتياجاتك (مثل Start from scratch) - + في منشئ سير العمل، انقر على أيقونة Plus (+) لإضافة إجراء جديد. - + اختر `Integrated apps > CrewAI > Kickoff a Crew`. - اختر الطاقم الذي + تريد تشغيله. - انقر على `Save` لإضافة الإجراء إلى سير عملك + + سير عمل HubSpot 1 + + + + - بعد خطوة Kickoff a Crew، انقر على أيقونة Plus (+) لإضافة + إجراء جديد. - على سبيل المثال، لإرسال إشعار بريد إلكتروني داخلي، اختر + `Communications > Send internal email notification` - في حقل Body، + انقر على `Insert data`، اختر `View properties or action outputs from > Action + outputs > Crew Result` لتضمين بيانات الطاقم في البريد الإلكتروني + + سير عمل HubSpot 2 + + - هيّئ أي إجراءات إضافية حسب الحاجة - راجع خطوات + سير عملك للتأكد من إعداد كل شيء بشكل صحيح - فعّل سير العمل + + سير عمل HubSpot 3 + + + + +لمزيد من المعلومات المفصلة حول الإجراءات المتاحة وخيارات التخصيص، راجع [وثائق HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows). diff --git a/docs/v1.15.1/ar/enterprise/guides/human-in-the-loop.mdx b/docs/v1.15.1/ar/enterprise/guides/human-in-the-loop.mdx new file mode 100644 index 000000000..468f69e2e --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/human-in-the-loop.mdx @@ -0,0 +1,157 @@ +--- +title: "سير عمل HITL" +description: "تعلم كيفية تنفيذ سير عمل Human-In-The-Loop في CrewAI لتعزيز اتخاذ القرار" +icon: "user-check" +mode: "wide" +--- + +Human-In-The-Loop (HITL) هو نهج قوي يجمع بين الذكاء الاصطناعي والخبرة البشرية لتعزيز اتخاذ القرار وتحسين نتائج المهام. يوضح هذا الدليل كيفية تنفيذ HITL داخل CrewAI Enterprise. + +## نهجا HITL في CrewAI + +يقدم CrewAI نهجين لتنفيذ سير عمل Human-In-The-Loop: + +| النهج | الأفضل لـ | الإصدار | +|-------|-----------|---------| +| **قائم على التدفق** (مُزخرف `@human_feedback`) | الإنتاج مع واجهة Enterprise، سير عمل البريد الإلكتروني أولاً، ميزات المنصة الكاملة | **1.8.0+** | +| **قائم على Webhook** | التكاملات المخصصة، الأنظمة الخارجية (Slack، Teams، إلخ.)، الإعدادات القديمة | جميع الإصدارات | + +## HITL القائم على التدفق مع منصة Enterprise + + +يتطلب مُزخرف `@human_feedback` **إصدار CrewAI 1.8.0 أو أعلى**. + + +عند استخدام مُزخرف `@human_feedback` في تدفقاتك، يوفر CrewAI Enterprise **نظام HITL يعتمد على البريد الإلكتروني أولاً** يمكّن أي شخص لديه عنوان بريد إلكتروني من الاستجابة لطلبات المراجعة: + + + + يتلقى المستجيبون إشعارات بريد إلكتروني ويمكنهم الرد مباشرة — لا حاجة لتسجيل الدخول. + + + راجع واستجب لطلبات HITL في لوحة تحكم Enterprise عند التفضيل. + + + وجّه الطلبات إلى عناوين بريد محددة بناءً على أنماط الدوال أو استخراجها من حالة التدفق. + + + هيّئ استجابات احتياطية تلقائية عندما لا يرد أي شخص خلال المهلة الزمنية. + + + +### الفوائد الرئيسية + +- **مستجيبون خارجيون**: أي شخص لديه بريد إلكتروني يمكنه الاستجابة، حتى غير مستخدمي المنصة +- **تعيين ديناميكي**: استخراج بريد المُعيَّن من حالة التدفق (مثل `account_owner_email`) +- **تهيئة بسيطة**: التوجيه عبر البريد الإلكتروني أسهل في الإعداد من إدارة المستخدمين/الأدوار +- **احتياطي منشئ النشر**: إذا لم تتطابق قاعدة توجيه، يتم إخطار منشئ النشر + + +لتفاصيل التنفيذ حول مُزخرف `@human_feedback`، راجع دليل [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows). + + +## إعداد سير عمل HITL القائم على Webhook + +للتكاملات المخصصة مع الأنظمة الخارجية مثل Slack وMicrosoft Teams أو تطبيقاتك الخاصة، يمكنك استخدام النهج القائم على Webhook: + + + + هيّئ مهمتك مع تفعيل الإدخال البشري: + + إدخال بشري للطاقم + + + + + عند تشغيل طاقمك، أضف رابط webhook للإدخال البشري: + + رابط Webhook للطاقم + + + + + بمجرد إتمام الطاقم للمهمة التي تتطلب إدخالاً بشرياً، ستتلقى إشعار webhook يحتوي على: + - **معرّف التنفيذ** + - **معرّف المهمة** + - **مخرجات المهمة** + + + + سيتوقف النظام في حالة `Pending Human Input`. راجع مخرجات المهمة بعناية. + + + + استدعِ نقطة نهاية الاستئناف لطاقمك بالمعلومات التالية: + + نقطة نهاية استئناف الطاقم + + + + **هام: يجب تقديم روابط Webhook مرة أخرى**: + **يجب** تقديم نفس روابط webhook (`taskWebhookUrl`، `stepWebhookUrl`، `crewWebhookUrl`) في استدعاء الاستئناف التي استخدمتها في استدعاء التشغيل. لا تُنقل تهيئات Webhook تلقائياً من التشغيل — يجب تضمينها صراحة في طلب الاستئناف لمواصلة تلقي الإشعارات لاكتمال المهام وخطوات الوكيل واكتمال الطاقم. + + + مثال على استدعاء الاستئناف مع webhooks: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "Great work! Please add more details.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **تأثير التغذية الراجعة على تنفيذ المهمة**: + من الضروري توخي الحذر عند تقديم التغذية الراجعة، حيث سيتم دمج محتوى التغذية الراجعة بالكامل كسياق إضافي لعمليات تنفيذ المهام اللاحقة. + + وهذا يعني: + - جميع المعلومات في تغذيتك الراجعة تصبح جزءاً من سياق المهمة. + - التفاصيل غير ذات الصلة قد تؤثر سلباً عليها. + - التغذية الراجعة الموجزة وذات الصلة تساعد في الحفاظ على تركيز وكفاءة المهمة. + - راجع دائماً تغذيتك الراجعة بعناية قبل الإرسال للتأكد من أنها تحتوي فقط على معلومات ذات صلة توجه تنفيذ المهمة بشكل إيجابي. + + + إذا قدمت تغذية راجعة سلبية: + - سيعيد الطاقم محاولة المهمة مع سياق إضافي من تغذيتك الراجعة. + - ستتلقى إشعار webhook آخر لمزيد من المراجعة. + - كرر الخطوات 4-6 حتى ترضى. + + + + عندما ترسل تغذية راجعة إيجابية، سيستمر التنفيذ إلى الخطوات التالية. + + + +## أفضل الممارسات + +- **كن محدداً**: قدم تغذية راجعة واضحة وقابلة للتنفيذ تعالج المهمة مباشرة +- **كن ذا صلة**: ضمّن فقط المعلومات التي ستساعد في تحسين تنفيذ المهمة +- **كن سريعاً**: استجب لمطالبات HITL بسرعة لتجنب تأخير سير العمل +- **راجع بعناية**: تحقق من تغذيتك الراجعة قبل الإرسال لضمان الدقة + +## حالات الاستخدام الشائعة + +سير عمل HITL ذو قيمة خاصة لـ: +- ضمان الجودة والتحقق +- سيناريوهات اتخاذ القرار المعقدة +- العمليات الحساسة أو عالية المخاطر +- المهام الإبداعية التي تتطلب حكماً بشرياً +- مراجعات الامتثال والتنظيم + +## اعرف المزيد + + + + استكشف قدرات منصة Enterprise الكاملة لـ Flow HITL بما في ذلك إشعارات البريد الإلكتروني وقواعد التوجيه والاستجابة التلقائية والتحليلات. + + + دليل التنفيذ لمُزخرف `@human_feedback` في تدفقاتك. + + diff --git a/docs/v1.15.1/ar/enterprise/guides/kickoff-crew.mdx b/docs/v1.15.1/ar/enterprise/guides/kickoff-crew.mdx new file mode 100644 index 000000000..f1e477065 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/kickoff-crew.mdx @@ -0,0 +1,178 @@ +--- +title: "تشغيل الطاقم" +description: "تشغيل طاقم على CrewAI AMP" +icon: "flag-checkered" +mode: "wide" +--- + +## نظرة عامة + +بمجرد نشر طاقمك على منصة CrewAI AMP، يمكنك بدء عمليات التنفيذ عبر واجهة الويب أو API. يغطي هذا الدليل كلا النهجين. + +## الطريقة 1: استخدام واجهة الويب + +### الخطوة 1: الانتقال إلى طاقمك المنشور + +1. سجّل الدخول إلى [CrewAI AMP](https://app.crewai.com) +2. انقر على اسم الطاقم من قائمة مشاريعك +3. ستنتقل إلى صفحة تفاصيل الطاقم + +![لوحة تحكم الطاقم](/images/enterprise/crew-dashboard.png) + +### الخطوة 2: بدء التنفيذ + +من صفحة تفاصيل طاقمك، لديك خياران لبدء التنفيذ: + +#### الخيار أ: التشغيل السريع + +1. انقر على رابط `Kickoff` في قسم Test Endpoints +2. أدخل معاملات الإدخال المطلوبة لطاقمك في محرر JSON +3. انقر على زر `Send Request` + +![نقطة نهاية التشغيل](/images/enterprise/kickoff-endpoint.png) + +#### الخيار ب: استخدام الواجهة المرئية + +1. انقر على علامة تبويب `Run` في صفحة تفاصيل الطاقم +2. أدخل المدخلات المطلوبة في حقول النموذج +3. انقر على زر `Run Crew` + +![تشغيل الطاقم](/images/enterprise/run-crew.png) + +### الخطوة 3: مراقبة تقدم التنفيذ + +بعد بدء التنفيذ: + +1. ستتلقى استجابة تحتوي على `kickoff_id` - **انسخ هذا المعرّف** +2. هذا المعرّف ضروري لتتبع تنفيذك + +![نسخ معرّف المهمة](/images/enterprise/copy-task-id.png) + +### الخطوة 4: التحقق من حالة التنفيذ + +لمراقبة تقدم تنفيذك: + +1. انقر على نقطة نهاية "Status" في قسم Test Endpoints +2. الصق `kickoff_id` في الحقل المخصص +3. انقر على زر "Get Status" + +![الحصول على الحالة](/images/enterprise/get-status.png) + +ستعرض استجابة الحالة: + +- حالة التنفيذ الحالية (`running`، `completed`، إلخ.) +- تفاصيل حول المهام الجارية +- أي مخرجات أُنتجت حتى الآن + +### الخطوة 5: عرض النتائج النهائية + +بمجرد اكتمال التنفيذ: + +1. ستتغير الحالة إلى `completed` +2. يمكنك عرض نتائج ومخرجات التنفيذ الكاملة +3. لعرض أكثر تفصيلاً، تحقق من علامة تبويب `Executions` في صفحة تفاصيل الطاقم + +## الطريقة 2: استخدام API + +يمكنك أيضاً تشغيل الطواقم برمجياً باستخدام REST API لـ CrewAI AMP. + +### المصادقة + +جميع طلبات API تتطلب رمز حامل للمصادقة: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +رمز الحامل متاح في علامة تبويب Status في صفحة تفاصيل طاقمك. + +### التحقق من صحة الطاقم + +قبل تنفيذ العمليات، يمكنك التحقق من أن طاقمك يعمل بشكل صحيح: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +ستعيد الاستجابة الناجحة رسالة تشير إلى أن الطاقم يعمل: + +``` +Healthy% +``` + +### الخطوة 1: استرداد المدخلات المطلوبة + +أولاً، حدد المدخلات التي يتطلبها طاقمك: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +ستكون الاستجابة كائن JSON يحتوي على مصفوفة من معاملات الإدخال المطلوبة، على سبيل المثال: + +```json +{ "inputs": ["topic", "current_year"] } +``` + +يوضح هذا المثال أن هذا الطاقم المحدد يتطلب مدخلين: `topic` و`current_year`. + +### الخطوة 2: بدء التنفيذ + +ابدأ التنفيذ بتقديم المدخلات المطلوبة: + +```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 +``` + +ستتضمن الاستجابة `kickoff_id` الذي ستحتاجه للتتبع: + +```json +{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" } +``` + +### الخطوة 3: التحقق من حالة التنفيذ + +راقب تقدم التنفيذ باستخدام kickoff_id: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv +``` + +## التعامل مع عمليات التنفيذ + +### عمليات التنفيذ طويلة المدة + +لعمليات التنفيذ التي قد تستغرق وقتاً طويلاً: + +1. فكّر في تنفيذ آلية استعلام دوري للتحقق من الحالة بشكل دوري +2. استخدم webhooks (إذا كانت متاحة) للإشعار عند اكتمال التنفيذ +3. نفّذ معالجة الأخطاء للمهلات الزمنية المحتملة + +### سياق التنفيذ + +يتضمن سياق التنفيذ: + +- المدخلات المقدمة عند التشغيل +- متغيرات البيئة المُهيأة أثناء النشر +- أي حالة محفوظة بين المهام + +### تصحيح أخطاء عمليات التنفيذ الفاشلة + +إذا فشل التنفيذ: + +1. تحقق من علامة تبويب "Executions" للسجلات المفصلة +2. راجع علامة تبويب "Traces" لتفاصيل التنفيذ خطوة بخطوة +3. ابحث عن استجابات LLM واستخدام الأدوات في تفاصيل التتبع + + + تواصل مع فريق الدعم للمساعدة في مشاكل التنفيذ أو أسئلة حول + منصة Enterprise. + diff --git a/docs/v1.15.1/ar/enterprise/guides/microsoft-teams-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/microsoft-teams-trigger.mdx new file mode 100644 index 000000000..5ac319d6a --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/microsoft-teams-trigger.mdx @@ -0,0 +1,70 @@ +--- +title: "مشغل Microsoft Teams" +description: "تشغيل الطواقم من نشاط محادثات Microsoft Teams" +icon: "microsoft" +mode: "wide" +--- + +## نظرة عامة + +استخدم مشغل Microsoft Teams لبدء الأتمتات كلما أُنشئت محادثة جديدة. تشمل الأنماط الشائعة تلخيص الطلبات الواردة وتوجيه الرسائل العاجلة لفرق الدعم أو إنشاء مهام متابعة في أنظمة أخرى. + + + تأكد من ربط Microsoft Teams تحت **Tools & Integrations** و + تفعيله في علامة تبويب **Triggers** لعملية النشر. + + +## تفعيل مشغل Microsoft Teams + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Microsoft Teams** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص سلسلة محادثة جديدة + +```python +from teams_chat_created_crew import MicrosoftTeamsChatTrigger + +crew = MicrosoftTeamsChatTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": teams_payload, +}) +print(result.raw) +``` + +يحلل الطاقم بيانات المحادثة الوصفية (الموضوع، وقت الإنشاء، قائمة الأعضاء) وينشئ خطة عمل للفريق المستقبل. + +## الاختبار المحلي + +اختبر تكامل مشغل Microsoft Teams محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Microsoft Teams بحمولة واقعية +crewai triggers run microsoft_teams/teams_message_created +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Teams كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run microsoft_teams/teams_message_created` (وليس `crewai + run`) لمحاكاة تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى + طاقمك حمولة المشغل تلقائياً. + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من أن اتصال Teams نشط؛ يجب تحديثه إذا سحب المستأجر الصلاحيات +- اختبر محلياً بـ `crewai triggers run microsoft_teams/teams_message_created` لرؤية هيكل الحمولة بالضبط +- تأكد من أن اشتراك webhook في Microsoft 365 لا يزال صالحاً إذا توقفت الحمولات عن الوصول +- راجع سجلات التنفيذ لعدم تطابق شكل الحمولة — قد تحذف إشعارات Graph حقولاً عندما تكون المحادثة خاصة أو مقيدة +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/v1.15.1/ar/enterprise/guides/monorepo-deployments.mdx b/docs/v1.15.1/ar/enterprise/guides/monorepo-deployments.mdx new file mode 100644 index 000000000..d86f18e92 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/monorepo-deployments.mdx @@ -0,0 +1,224 @@ +--- +title: "النشر من Monorepo" +description: "انشر Crew أو Flow من مجلد فرعي داخل مستودع أكبر" +icon: "folder-tree" +mode: "wide" +--- + + + استخدم دليل عمل عندما يكون Crew أو Flow داخل مستودع أكبر. يتحقق CrewAI AMP + من الأتمتة ويبنيها ويشغلها من ذلك المجلد الفرعي بدلاً من جذر المستودع. + + +## متى تستخدم ذلك + +يكون النشر من monorepo مفيداً عندما يحتوي مستودع واحد على عدة أتمتات أو حزم +مشتركة أو كود تطبيقات آخر: + +```text +company-ai/ +|-- uv.lock +|-- packages/ +| `-- shared_tools/ +`-- crews/ + |-- support_agent/ + | |-- pyproject.toml + | |-- crew.jsonc + | `-- agents/ + | `-- support_agent.jsonc + `-- research_flow/ + |-- pyproject.toml + `-- src/ + `-- research_flow/ + `-- main.py +``` + +لنشر `support_agent`، اضبط دليل العمل على: + +```text +crews/support_agent +``` + +لا يزال AMP يجلب المستودع كاملاً أو يرفعه، لكنه يتعامل مع المجلد المحدد كجذر +مشروع الأتمتة. + +## ما الذي يتحكم به دليل العمل + +عند تعيين دليل عمل، يستخدم AMP ذلك المجلد من أجل: + +- التحقق من المشروع، بما في ذلك `pyproject.toml` وملفات crew JSON وأي نقطة دخول كلاسيكية لـ Crew أو Flow +- تثبيت الاعتماديات باستخدام `uv` +- دليل العمل للعملية قيد التشغيل +- متغير البيئة `CREW_ROOT_DIR` + +ترك الحقل فارغاً يحافظ على السلوك الحالي ويستخدم جذر المستودع. + +## المصادر المدعومة + +يمكنك تعيين دليل عمل عند إنشاء نشر من: + +- مستودع GitHub متصل +- مستودع Git مكوّن في AMP +- رفع ملف ZIP + + + اضبط أدلة العمل من واجهة AMP على الويب. لا يطلب تدفق CLI + `crewai deploy create` هذا الحقل. + + +يمكنك أيضاً إضافة دليل العمل أو تغييره في نشر موجود من صفحة **Settings** الخاصة +بالنشر. يسري التغيير في النشر التالي. + + + لا يمكن استخدام أدلة العمل وauto-deploy معاً. إذا كان للنشر دليل عمل، يتم + تعطيل auto-deploy لذلك النشر. أوقف auto-deploy قبل تعيين دليل عمل. + + +## إعداد نشر جديد + + + + في CrewAI AMP، أنشئ نشراً جديداً واختر المصدر: GitHub أو Git Repository أو + رفع ZIP. + + + + اختر المستودع والفرع اللذين يحتويان على monorepo، أو ارفع ملف ZIP يحتوي + جذره على محتويات monorepo. + + + + وسّع قسم **Advanced** في نموذج النشر. + + + + أدخل المسار من جذر المستودع إلى مشروع Crew أو Flow: + + ```text + crews/support_agent + ``` + + لا تضف شرطة مائلة في البداية. + + + + أضف أي متغيرات بيئة مطلوبة، ثم ابدأ النشر. + + + +## إعداد نشر موجود + + + + انتقل إلى الأتمتة في AMP وافتح **Settings**. + + + + إذا كان auto-deploy مفعلاً، أوقفه أولاً. لا يكون حقل دليل العمل متاحاً + أثناء تشغيل auto-deploy. + + + + في **Basic settings**، أدخل مسار المجلد الفرعي، مثل: + + ```text + crews/support_agent + ``` + + + + احفظ الإعداد وأعد نشر الأتمتة. سيتم استخدام دليل العمل الجديد في النشر + التالي. + + + +## قواعد المسار + +يجب أن يكون دليل العمل مساراً نسبياً داخل جذر المستودع أو ZIP. + +| القاعدة | المثال | +|---------|--------| +| استخدم مساراً نسبياً | `crews/support_agent` | +| لا تبدأ بـ `/` | `/crews/support_agent` غير صالح | +| لا تستخدم مقاطع المسار `.` أو `..` | `crews/../support_agent` غير صالح | +| استخدم الأحرف والأرقام والشرطات والشرطات السفلية والنقاط والشرطات المائلة فقط | `crews/support agent` غير صالح | +| اجعل المسار 255 حرفاً أو أقل | يتم رفض المسارات الأطول | + +يزيل AMP المسافات البيضاء في البداية والنهاية، ويضغط الشرطات المائلة المتكررة، +ويزيل الشرطة المائلة النهائية. تستخدم القيمة الفارغة جذر المستودع. + +## ملفات القفل وUV Workspaces + +يجب أن يحتوي المجلد المحدد على `pyproject.toml` وملفات المشروع المناسبة لنوع +الأتمتة: + +- crew بنمط JSON-first: ملف `crew.jsonc` أو `crew.json` مع مجلد `agents/` +- Crew كلاسيكي أو Flow: مجلد `src/` مع نقطة دخول Python المتوقعة + +يمكن أن يوجد ملف `uv.lock` أو `poetry.lock` إما في المجلد المحدد أو في جذر +المستودع. + +يدعم هذا تخطيطي ملفات القفل الشائعين: + + + + ```text + company-ai/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- uv.lock + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + ```text + company-ai/ + |-- uv.lock + |-- packages/ + | `-- shared_tools/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + + إذا كانت الأتمتة تستورد حزماً مشتركة من مكان آخر في monorepo، فصرّح بهذه + الحزم في `pyproject.toml` باستخدام إعدادات UV workspace أو path أو source. + يشغل AMP الأتمتة من المجلد المحدد، لذلك يجب تثبيت الكود المشترك كاعتمادية + بدلاً من الاعتماد على وجود جذر المستودع في Python path. + + +## استكشاف الأخطاء وإصلاحها + +### لم يتم العثور على دليل العمل + +تحقق من أن المسار نسبي إلى جذر المستودع أو ZIP. بالنسبة لرفع ZIP، يجب أن +تتضمن محتويات ZIP مسار دليل العمل تماماً كما أدخلته. + +### pyproject.toml مفقود + +يجب أن يشير دليل العمل إلى مجلد مشروع Crew أو Flow، وليس فقط إلى مجلد أب +يحتوي على عدة مشاريع. + +### uv.lock أو poetry.lock مفقود + +اعمل commit لملف قفل إما في مجلد المشروع المحدد أو في جذر المستودع. بالنسبة +إلى UV workspaces، يتم دعم إبقاء `uv.lock` في جذر workspace. + +### Auto-Deploy غير متاح + +يتم تعطيل auto-deploy أثناء تعيين دليل عمل. استخدم إعادة النشر اليدوية أو شغّل +إعادة النشر من CI/CD باستخدام AMP API. + + + تابع دليل النشر بعد اختيار دليل عمل monorepo. + diff --git a/docs/v1.15.1/ar/enterprise/guides/onedrive-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/onedrive-trigger.mdx new file mode 100644 index 000000000..ef9fd0c40 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/onedrive-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "مشغل OneDrive" +description: "أتمتة الاستجابات لنشاط ملفات OneDrive" +icon: "cloud" +mode: "wide" +--- + +## نظرة عامة + +ابدأ الأتمتات عند تغيير الملفات داخل OneDrive. يمكنك إنشاء ملخصات تدقيق وإخطار فرق الأمان بشأن المشاركة الخارجية أو تحديث أنظمة الأعمال اللاحقة ببيانات المستندات الوصفية الجديدة. + + + اربط OneDrive في **Tools & Integrations** وبدّل المشغل لعملية + النشر. + + +## تفعيل مشغل OneDrive + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **OneDrive** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تدقيق صلاحيات الملفات + +```python +from onedrive_file_crew import OneDriveFileTrigger + +crew = OneDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": onedrive_payload, +}) +``` + +يفحص الطاقم بيانات الملف الوصفية ونشاط المستخدم وتغييرات الصلاحيات لإنتاج ملخص متوافق مع متطلبات الامتثال. + +## الاختبار المحلي + +اختبر تكامل مشغل OneDrive محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل OneDrive بحمولة واقعية +crewai triggers run microsoft_onedrive/file_changed +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة OneDrive كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run microsoft_onedrive/file_changed` (وليس `crewai run`) + لمحاكاة تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من أن الحساب المتصل لديه صلاحية قراءة بيانات الملف الوصفية المضمنة في webhook +- اختبر محلياً بـ `crewai triggers run microsoft_onedrive/file_changed` لرؤية هيكل الحمولة بالضبط +- إذا كان المشغل يعمل لكن الحمولة تفتقد `permissions`، تأكد من أن إعدادات المشاركة على مستوى الموقع تسمح لـ Graph بإرجاع هذا الحقل +- للمستأجرين الكبار، صفّ الإشعارات مسبقاً حتى يعمل الطاقم فقط على المجلدات ذات الصلة +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/v1.15.1/ar/enterprise/guides/outlook-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/outlook-trigger.mdx new file mode 100644 index 000000000..9fa320bc9 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/outlook-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "مشغل Outlook" +description: "إطلاق الأتمتات من رسائل Outlook وتحديثات التقويم" +icon: "microsoft" +mode: "wide" +--- + +## نظرة عامة + +أتمت الاستجابات عندما يسلّم Outlook رسالة جديدة أو عند إزالة حدث من التقويم. تقوم الفرق عادة بتوجيه التصعيدات وإنشاء تذاكر أو تنبيه الحاضرين بالإلغاءات. + + + اربط Outlook في **Tools & Integrations** وتأكد من تفعيل المشغل + لعملية النشر. + + +## تفعيل مشغل Outlook + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Outlook** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص رسالة بريد إلكتروني جديدة + +```python +from outlook_message_crew import OutlookMessageTrigger + +crew = OutlookMessageTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": outlook_payload, +}) +``` + +يستخرج الطاقم تفاصيل المرسل والموضوع ومعاينة النص والمرفقات قبل إنشاء استجابة منظمة. + +## الاختبار المحلي + +اختبر تكامل مشغل Outlook محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Outlook بحمولة واقعية +crewai triggers run microsoft_outlook/email_received +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Outlook كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run microsoft_outlook/email_received` (وليس `crewai run`) + لمحاكاة تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## استكشاف الأخطاء وإصلاحها + +- تحقق من أن موصل Outlook لا يزال مفوّضاً؛ يجب تجديد الاشتراك دورياً +- اختبر محلياً بـ `crewai triggers run microsoft_outlook/email_received` لرؤية هيكل الحمولة بالضبط +- إذا كانت المرفقات مفقودة، تأكد من أن اشتراك webhook يتضمن علامة `includeResourceData` +- راجع سجلات التنفيذ عندما تفشل الأحداث في المطابقة — حمولات الإلغاء تفتقد قوائم الحاضرين حسب التصميم ويجب أن يأخذ الطاقم ذلك في الاعتبار +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/v1.15.1/ar/enterprise/guides/prepare-for-deployment.mdx b/docs/v1.15.1/ar/enterprise/guides/prepare-for-deployment.mdx new file mode 100644 index 000000000..d12eff408 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/prepare-for-deployment.mdx @@ -0,0 +1,343 @@ +--- +title: "التحضير للنشر" +description: "تأكد من جاهزية طاقمك أو تدفقك للنشر على CrewAI AMP" +icon: "clipboard-check" +mode: "wide" +--- + + + قبل النشر على CrewAI AMP، من الضروري التحقق من صحة بنية مشروعك. + يمكن نشر كل من الطواقم والتدفقات كـ "أتمتات"، لكن لهما بنى مشاريع + ومتطلبات مختلفة يجب استيفاؤها لنجاح النشر. + + +## فهم الأتمتات + +في CrewAI AMP، **الأتمتات** هو المصطلح الشامل لمشاريع الذكاء الاصطناعي الوكيل القابلة للنشر. يمكن أن تكون الأتمتة إما: + +- **طاقم**: فريق مستقل من وكلاء الذكاء الاصطناعي يعملون معاً على المهام +- **تدفق**: سير عمل مُنسّق يمكنه الجمع بين طواقم متعددة واستدعاءات LLM المباشرة والمنطق الإجرائي + +فهم النوع الذي تنشره ضروري لأن لهما بنى مشاريع ونقاط دخول مختلفة. + +## الطواقم مقابل التدفقات: الفروقات الرئيسية + + + + فرق وكلاء ذكاء اصطناعي مستقلة. الـ crews الجديدة تستخدم بنية JSON-first مع `crew.jsonc` و `agents/`؛ ويمكن للـ crews الكلاسيكية الاستمرار في استخدام `crew.py`. + + + سير عمل مُنسّق مع طواقم مضمنة في مجلد `crews/`. الأفضل للعمليات المعقدة متعددة المراحل. + + + +| الجانب | الطاقم | التدفق | +|--------|--------|--------| +| **بنية المشروع** | جذر المشروع مع `crew.jsonc` و `agents/` | `src/project_name/` مع مجلد `crews/` | +| **موقع المنطق الرئيسي** | `crew.jsonc` (كلاسيكي: `src/project_name/crew.py`) | `src/project_name/main.py` (فئة Flow) | +| **دالة نقطة الدخول** | تُحمّل من `crew.jsonc` (كلاسيكي: `run()` في `main.py`) | `kickoff()` في `main.py` | +| **نوع pyproject.toml** | `type = "crew"` | `type = "flow"` | +| **أمر CLI للإنشاء** | `crewai create crew name` | `crewai create flow name` | +| **موقع التهيئة** | `crew.jsonc` و `agents/` و `tools/` اختياريًا | `src/project_name/crews/crew_name/config/` أو مجلدات crew JSON مضمنة | +| **يمكن أن يحتوي طواقم أخرى** | لا | نعم (في مجلد `crews/`) | + +## مرجع بنية المشروع + +### بنية مشروع الطاقم + +عند تشغيل `crewai create crew my_crew`، تحصل على بنية JSON-first: + +``` +my_crew/ +├── .gitignore +├── pyproject.toml # Must have type = "crew" +├── README.md +├── .env +├── uv.lock # REQUIRED for deployment +├── crew.jsonc # إعدادات الـ crew والمهام والعملية والمدخلات +├── agents/ +│ └── researcher.jsonc # تعريفات الـ Agents +├── tools/ # أدوات custom: اختيارية +├── knowledge/ +└── skills/ +``` + + + في crews بنمط JSON-first، أبقِ `crew.jsonc` و `agents/` و `tools/` و `knowledge/` و `skills/` + في جذر المشروع. وضعها داخل `src/` يمنع `crewai run` والتحقق قبل النشر من العثور على تعريف الـ crew. + + + + المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew my_crew --classic` تستخدم البنية القديمة + `src/project_name/crew.py` و `src/project_name/config/agents.yaml` و + `src/project_name/config/tasks.yaml`. تظل هذه البنية مدعومة للـ crews المكتوبة في Python مع decorators. + + +### بنية مشروع التدفق + +عند تشغيل `crewai create flow my_flow`، تحصل على هذه البنية: + +``` +my_flow/ +├── .gitignore +├── pyproject.toml # Must have type = "flow" +├── README.md +├── .env +├── uv.lock # REQUIRED for deployment +└── src/ + └── my_flow/ + ├── __init__.py + ├── main.py # Entry point with kickoff() function + Flow class + ├── crews/ # Embedded crews folder + │ └── poem_crew/ + │ ├── __init__.py + │ ├── poem_crew.py # Crew with @CrewBase decorator + │ └── config/ + │ ├── agents.yaml + │ └── tasks.yaml + └── tools/ + ├── __init__.py + └── custom_tool.py +``` + + + الـ crews المستقلة بنمط JSON-first تستخدم ملفات JSON في جذر المشروع. أما Flows فتظل تستخدم + `src/project_name/` ويمكن أن تحتوي crews مضمنة كلاسيكية أو مجلدات crew JSON يتم تحميلها عبر + `crewai.project.load_crew`. + + +## قائمة فحص ما قبل النشر + +استخدم هذه القائمة للتحقق من جاهزية مشروعك للنشر. + +### 1. التحقق من تهيئة pyproject.toml + +يجب أن يتضمن `pyproject.toml` قسم `[tool.crewai]` الصحيح: + + + + ```toml + [tool.crewai] + type = "crew" + ``` + + + ```toml + [tool.crewai] + type = "flow" + ``` + + + + + إذا لم يتطابق `type` مع بنية مشروعك، سيفشل البناء أو + لن تعمل الأتمتة بشكل صحيح. + + +### 2. التأكد من وجود ملف uv.lock + +يستخدم CrewAI `uv` لإدارة الاعتماديات. يضمن ملف `uv.lock` بناءً قابلاً للتكرار وهو **مطلوب** للنشر. + +```bash +# إنشاء أو تحديث ملف القفل +uv lock + +# التحقق من وجوده +ls -la uv.lock +``` + +إذا لم يكن الملف موجوداً، شغّل `uv lock` وارفعه إلى مستودعك: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + +### 3. التحقق من تعريف الـ Crew + + + + يجب أن تحتوي crews بنمط JSON-first على `crew.jsonc` أو `crew.json` في جذر المشروع. + يجب أن يشير مصفوفة `agents` إلى ملفات داخل `agents/`، ويجب أن تشير كل task إلى اسم Agent صحيح. + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "Research {topic}.", + "expected_output": "A concise report.", + "agent": "researcher" + } + ], + "inputs": { + "topic": "AI Agents" + } + } + ``` + + تُشار الأدوات المخصصة بصيغة `"custom:"` ويجب تنفيذها في + `tools/.py` كصنف يرث من `BaseTool`. + + + يجب أن تستخدم الـ crews الكلاسيكية وPython crews المضمنة داخل Flows مزخرف `@CrewBase`. + + ```python + from crewai import Agent, Crew, Process, Task + from crewai.project import CrewBase, agent, crew, task + from crewai.agents.agent_builder.base_agent import BaseAgent + from typing import List + + @CrewBase + class MyCrew(): + """My crew description""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + @task + def my_task(self) -> Task: + return Task( + config=self.tasks_config['my_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) + ``` + + + +### 4. التحقق من نقاط دخول المشروع + +لا تحتاج crews المستقلة بنمط JSON-first إلى ملف `src/project_name/main.py` مكتوب يدويًا؛ +يقوم `crewai run` وتغليف النشر بتحميل `crew.jsonc` مباشرة. تستخدم crews الكلاسيكية وFlows نقاط دخول Python: + + + + شغّل محليًا من جذر المشروع: + + ```bash + crewai run + ``` + + + تستخدم نقطة الدخول دالة `run()`: + + ```python + # src/my_crew/main.py + from my_crew.crew import MyCrew + + def run(): + """Run the crew.""" + inputs = {'topic': 'AI in Healthcare'} + result = MyCrew().crew().kickoff(inputs=inputs) + return result + + if __name__ == "__main__": + run() + ``` + + + تستخدم نقطة الدخول دالة `kickoff()` مع فئة Flow: + + ```python + # src/my_flow/main.py + from crewai.flow import Flow, listen, start + from my_flow.crews.poem_crew.poem_crew import PoemCrew + + class MyFlow(Flow): + @start() + def begin(self): + # Flow logic here + result = PoemCrew().crew().kickoff(inputs={...}) + return result + + def kickoff(): + """Run the flow.""" + MyFlow().kickoff() + + if __name__ == "__main__": + kickoff() + ``` + + + +### 5. تحضير متغيرات البيئة + +قبل النشر، تأكد من أن لديك: + +1. **مفاتيح API لـ LLM** جاهزة (OpenAI، Anthropic، Google، إلخ.) +2. **مفاتيح API للأدوات** إذا كنت تستخدم أدوات خارجية (Serper، إلخ.) + + + إذا كان مشروعك يعتمد على حزم من **سجل PyPI خاص**، ستحتاج أيضاً لتهيئة + بيانات اعتماد مصادقة السجل كمتغيرات بيئة. راجع + دليل [سجلات الحزم الخاصة](/ar/enterprise/guides/private-package-registry) للتفاصيل. + + + + اختبر مشروعك محلياً بنفس متغيرات البيئة قبل النشر + لاكتشاف مشاكل التهيئة مبكراً. + + +## أوامر التحقق السريع + +شغّل هذه الأوامر من جذر مشروعك للتحقق السريع من إعدادك: + +```bash +# 1. Check project type in pyproject.toml +grep -A2 "\[tool.crewai\]" pyproject.toml + +# 2. Verify uv.lock exists +ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'" + +# 3. For JSON-first crews, verify crew.jsonc and agents/ +([ -f crew.jsonc ] || [ -f crew.json ]) || echo "No crew.jsonc or crew.json found" +test -d agents || echo "No agents/ directory found" + +# 4. For classic Crews - verify crew.py exists +ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)" + +# 5. For Flows - verify crews/ folder exists +ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)" + +# 6. For classic Python crews - check for CrewBase usage +grep -r "@CrewBase" . --include="*.py" +``` + +## أخطاء الإعداد الشائعة + +| الخطأ | العرض | الإصلاح | +|-------|-------|---------| +| `uv.lock` مفقود | فشل البناء أثناء حل الاعتماديات | شغّل `uv lock` وارفعه | +| `type` خاطئ في pyproject.toml | نجاح البناء لكن فشل وقت التشغيل | غيّر إلى النوع الصحيح | +| `crew.jsonc` أو `agents/` مفقود في crew بنمط JSON-first | لا يمكن العثور على تعريف الـ crew | أبقِ `crew.jsonc` و `agents/` في جذر المشروع | +| مُزخرف `@CrewBase` مفقود في crew كلاسيكية | أخطاء "Config not found" | أضف المُزخرف لجميع فئات الـ crew الكلاسيكية | +| ملفات كلاسيكية في الجذر بدل `src/` | نقطة الدخول غير موجودة | انقل ملفات Python الكلاسيكية إلى `src/project_name/` | +| `run()` أو `kickoff()` مفقودة | لا يمكن بدء الأتمتة | أضف دالة الدخول الصحيحة | + +## الخطوات التالية + +بمجرد اجتياز مشروعك لجميع عناصر القائمة، أنت جاهز للنشر: + + + اتبع دليل النشر لنشر طاقمك أو تدفقك على CrewAI AMP باستخدام + CLI أو واجهة الويب أو تكامل CI/CD. + diff --git a/docs/v1.15.1/ar/enterprise/guides/private-package-registry.mdx b/docs/v1.15.1/ar/enterprise/guides/private-package-registry.mdx new file mode 100644 index 000000000..d9633ff0c --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/private-package-registry.mdx @@ -0,0 +1,263 @@ +--- +title: "سجلات الحزم الخاصة" +description: "تثبيت حزم Python الخاصة من سجلات PyPI المصادق عليها في CrewAI AMP" +icon: "lock" +mode: "wide" +--- + + + يغطي هذا الدليل كيفية تهيئة مشروع CrewAI لتثبيت حزم Python + من سجلات PyPI الخاصة (Azure DevOps Artifacts، GitHub Packages، GitLab، AWS CodeArtifact، إلخ.) + عند النشر على CrewAI AMP. + + +## متى تحتاج هذا + +إذا كان مشروعك يعتمد على حزم Python داخلية أو خاصة مستضافة على سجل خاص +بدلاً من PyPI العام، ستحتاج إلى: + +1. إخبار UV **أين** يجد الحزمة (رابط فهرس) +2. إخبار UV **أي** حزم تأتي من ذلك الفهرس (تعيين مصدر) +3. تقديم **بيانات اعتماد** حتى يتمكن UV من المصادقة أثناء التثبيت + +يستخدم CrewAI AMP [UV](https://docs.astral.sh/uv/) لحل وتثبيت الاعتماديات. +يدعم UV السجلات الخاصة المصادق عليها عبر تهيئة `pyproject.toml` مع +متغيرات بيئة لبيانات الاعتماد. + +## الخطوة 1: تهيئة pyproject.toml + +ثلاثة أجزاء تعمل معاً في `pyproject.toml`: + +### 1أ. التصريح بالاعتمادية + +أضف الحزمة الخاصة إلى `[project.dependencies]` كأي اعتمادية أخرى: + +```toml +[project] +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] +``` + +### 1ب. تعريف الفهرس + +سجّل سجلك الخاص كفهرس مسمّى تحت `[[tool.uv.index]]`: + +```toml +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true +``` + + + حقل `name` مهم — يستخدمه UV لبناء أسماء متغيرات البيئة + للمصادقة (راجع [الخطوة 2](#step-2-set-authentication-credentials) أدناه). + + تعيين `explicit = true` يعني أن UV لن يبحث في هذا الفهرس عن كل حزمة — فقط + الحزم التي تعيّنها صراحة له في `[tool.uv.sources]`. يتجنب ذلك الاستعلامات غير الضرورية + ضد سجلك الخاص ويحمي من هجمات ارتباك الاعتماديات. + + +### 1ج. تعيين الحزمة للفهرس + +أخبر UV أي حزم يجب حلها من فهرسك الخاص باستخدام `[tool.uv.sources]`: + +```toml +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +### مثال كامل + +```toml +[project] +name = "my-crew-project" +version = "0.1.0" +requires-python = ">=3.10,<=3.13" +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] + +[tool.crewai] +type = "crew" + +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true + +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +بعد تحديث `pyproject.toml`، أعد إنشاء ملف القفل: + +```bash +uv lock +``` + + + ارفع دائماً `uv.lock` المُحدّث مع تغييرات `pyproject.toml`. + ملف القفل مطلوب للنشر — راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment). + + +## الخطوة 2: تعيين بيانات اعتماد المصادقة + +يصادق UV ضد الفهارس الخاصة باستخدام متغيرات بيئة تتبع اصطلاح تسمية +بناءً على اسم الفهرس الذي حددته في `pyproject.toml`: + +``` +UV_INDEX_{UPPER_NAME}_USERNAME +UV_INDEX_{UPPER_NAME}_PASSWORD +``` + +حيث `{UPPER_NAME}` هو اسم فهرسك محوّلاً إلى **أحرف كبيرة** مع **استبدال الشرطات بشرطات سفلية**. + +على سبيل المثال، فهرس باسم `my-private-registry` يستخدم: + +| المتغير | القيمة | +|---------|--------| +| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | اسم مستخدم السجل أو اسم الرمز | +| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | كلمة مرور السجل أو الرمز/PAT | + + + هذه المتغيرات **يجب** إضافتها عبر إعدادات **Environment Variables** في CrewAI AMP — + إما عالمياً أو على مستوى النشر. لا يمكن تعيينها في ملفات `.env` أو ترميزها في مشروعك. + + راجع [تعيين متغيرات البيئة في AMP](#setting-environment-variables-in-amp) أدناه. + + +## مرجع مزودي السجلات + +يوضح الجدول أدناه تنسيق رابط الفهرس وقيم بيانات الاعتماد لمزودي السجلات الشائعين. +استبدل القيم المؤقتة بتفاصيل مؤسستك وخلاصتك الفعلية. + +| المزود | رابط الفهرس | اسم المستخدم | كلمة المرور | +|--------|-------------|--------------|-------------| +| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | أي نص غير فارغ (مثل `token`) | Personal Access Token (PAT) بنطاق Packaging Read | +| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | اسم مستخدم GitHub | Personal Access Token (classic) بنطاق `read:packages` | +| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project أو Personal Access Token بنطاق `read_api` | +| **AWS CodeArtifact** | استخدم الرابط من `aws codeartifact get-repository-endpoint` | `aws` | رمز من `aws codeartifact get-authorization-token` | +| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | مفتاح حساب الخدمة بتشفير Base64 | +| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | اسم المستخدم أو البريد الإلكتروني | مفتاح API أو رمز الهوية | +| **مستضاف ذاتياً (devpi، Nexus، إلخ.)** | رابط Simple API لسجلك | اسم مستخدم السجل | كلمة مرور السجل | + + + لـ **AWS CodeArtifact**، تنتهي صلاحية رمز التفويض دورياً. + ستحتاج لتحديث قيمة `UV_INDEX_*_PASSWORD` عند انتهاء صلاحيتها. + فكّر في أتمتة هذا في خط أنابيب CI/CD. + + +## تعيين متغيرات البيئة في AMP + +يجب تهيئة بيانات اعتماد السجل الخاص كمتغيرات بيئة في CrewAI AMP. +لديك خياران: + + + + 1. سجّل الدخول إلى [CrewAI AMP](https://app.crewai.com) + 2. انتقل إلى أتمتتك + 3. افتح علامة تبويب **Environment Variables** + 4. أضف كل متغير (`UV_INDEX_*_USERNAME` و`UV_INDEX_*_PASSWORD`) مع قيمته + + راجع خطوة [النشر على AMP — تعيين متغيرات البيئة](/ar/enterprise/guides/deploy-to-amp#set-environment-variables) للتفاصيل. + + + أضف المتغيرات إلى ملف `.env` المحلي قبل تشغيل `crewai deploy create`. + سينقلها CLI بأمان إلى المنصة: + + ```bash + # .env + OPENAI_API_KEY=sk-... + UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token + UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here + ``` + + ```bash + crewai deploy create + ``` + + + + + **لا ترفع** أبداً بيانات الاعتماد إلى مستودعك. استخدم متغيرات بيئة AMP لجميع الأسرار. + يجب إدراج ملف `.env` في `.gitignore`. + + +لتحديث بيانات الاعتماد في نشر حالي، راجع [تحديث طاقمك — متغيرات البيئة](/ar/enterprise/guides/update-crew). + +## كيف يعمل الكل معاً + +عندما يبني CrewAI AMP أتمتتك، يعمل تدفق الحل هكذا: + + + + يسحب AMP مستودعك ويقرأ `pyproject.toml` و`uv.lock`. + + + يقرأ UV `[tool.uv.sources]` لتحديد أي فهرس يجب أن تأتي منه كل حزمة. + + + لكل فهرس خاص، يبحث UV عن `UV_INDEX_{NAME}_USERNAME` و`UV_INDEX_{NAME}_PASSWORD` + من متغيرات البيئة التي هيأتها في AMP. + + + يحمّل UV ويثبّت جميع الحزم — العامة (من PyPI) والخاصة (من سجلك). + + + يبدأ طاقمك أو تدفقك مع توفر جميع الاعتماديات. + + + +## استكشاف الأخطاء وإصلاحها + +### أخطاء المصادقة أثناء البناء + +**العرض**: فشل البناء بـ `401 Unauthorized` أو `403 Forbidden` عند حل حزمة خاصة. + +**تحقق من**: +- أسماء متغيرات البيئة `UV_INDEX_*` تتطابق مع اسم فهرسك بالضبط (أحرف كبيرة، شرطات → شرطات سفلية) +- بيانات الاعتماد معيّنة في متغيرات بيئة AMP، وليس فقط في `.env` محلي +- الرمز/PAT لديه صلاحيات القراءة المطلوبة لخلاصة الحزم +- الرمز لم تنتهِ صلاحيته (ذو صلة خاصة لـ AWS CodeArtifact) + +### الحزمة غير موجودة + +**العرض**: `No matching distribution found for my-private-package`. + +**تحقق من**: +- رابط الفهرس في `pyproject.toml` ينتهي بـ `/simple/` +- إدخال `[tool.uv.sources]` يعيّن اسم الحزمة الصحيح لاسم الفهرس الصحيح +- الحزمة منشورة فعلاً في سجلك الخاص +- شغّل `uv lock` محلياً بنفس بيانات الاعتماد للتحقق من عمل الحل + +### تعارضات ملف القفل + +**العرض**: فشل `uv lock` أو نتائج غير متوقعة بعد إضافة فهرس خاص. + +**الحل**: عيّن بيانات الاعتماد محلياً وأعد الإنشاء: + +```bash +export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token +export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat +uv lock +``` + +ثم ارفع `uv.lock` المُحدّث. + +## أدلة ذات صلة + + + + تحقق من بنية المشروع والاعتماديات قبل النشر. + + + انشر طاقمك أو تدفقك وهيّئ متغيرات البيئة. + + + حدّث متغيرات البيئة وادفع التغييرات إلى نشر قائم. + + diff --git a/docs/v1.15.1/ar/enterprise/guides/react-component-export.mdx b/docs/v1.15.1/ar/enterprise/guides/react-component-export.mdx new file mode 100644 index 000000000..d1ec9d362 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/react-component-export.mdx @@ -0,0 +1,112 @@ +--- +title: "تصدير مكون React" +description: "تعلم كيفية تصدير ودمج مكونات React من CrewAI AMP في تطبيقاتك" +icon: "react" +mode: "wide" +--- + +يشرح هذا الدليل كيفية تصدير طواقم CrewAI AMP كمكونات React ودمجها في تطبيقاتك. + +## تصدير مكون React + + + + انقر على القائمة (ثلاث نقاط على يمين طاقمك المنشور) واختر خيار التصدير واحفظ الملف محلياً. سنستخدم `CrewLead.jsx` في مثالنا. + + + تصدير مكون React + + + + + +## إعداد بيئة React + +لتشغيل مكون React هذا محلياً، ستحتاج لإعداد بيئة تطوير React ودمج هذا المكون في مشروع React. + + + + - حمّل وثبّت Node.js من الموقع الرسمي: https://nodejs.org/ + - اختر إصدار LTS (الدعم طويل المدى) للاستقرار. + + + + - افتح Command Prompt أو PowerShell + - انتقل إلى المجلد الذي تريد إنشاء مشروعك فيه + - شغّل الأمر التالي لإنشاء مشروع React جديد: + + ```bash + npx create-react-app my-crew-app + ``` + - انتقل إلى مجلد المشروع: + + ```bash + cd my-crew-app + ``` + + + + ```bash + npm install react-dom + ``` + + + + - انقل الملف المُحمّل `CrewLead.jsx` إلى مجلد `src` في مشروعك. + + + + - افتح `src/App.js` + - استبدل محتوياته بشيء مثل هذا: + + ```jsx + import React from 'react'; + import CrewLead from './CrewLead'; + + function App() { + return ( +
+ +
+ ); + } + + export default App; + ``` + - استبدل `YOUR_API_BASE_URL` و`YOUR_BEARER_TOKEN` بالقيم الفعلية لـ API. + + + + - في مجلد مشروعك، شغّل: + + ```bash + npm start + ``` + - سيبدأ خادم التطوير، ويجب أن يفتح متصفح الويب الافتراضي تلقائياً على `http://localhost:3000`، حيث سترى تطبيق React يعمل. + + + + +## التخصيص + +يمكنك بعد ذلك تخصيص `CrewLead.jsx` لإضافة اللون والعنوان وغيرها. + + + تخصيص مكون React + + + تخصيص مكون React + + +## الخطوات التالية + +- خصّص تنسيق المكون ليتوافق مع تصميم تطبيقك +- أضف خصائص إضافية للتهيئة +- ادمج مع إدارة حالة تطبيقك +- أضف معالجة الأخطاء وحالات التحميل diff --git a/docs/v1.15.1/ar/enterprise/guides/salesforce-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/salesforce-trigger.mdx new file mode 100644 index 000000000..8cd16c026 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/salesforce-trigger.mdx @@ -0,0 +1,50 @@ +--- +title: "مشغل Salesforce" +description: "تشغيل طواقم CrewAI من سير عمل Salesforce لأتمتة CRM" +icon: "salesforce" +mode: "wide" +--- + +يمكن تشغيل CrewAI AMP من Salesforce لأتمتة سير عمل إدارة علاقات العملاء وتعزيز عمليات المبيعات. + +## نظرة عامة + +Salesforce هي منصة رائدة لإدارة علاقات العملاء (CRM) تساعد الشركات على تبسيط عمليات المبيعات والخدمة والتسويق. من خلال إعداد مشغلات CrewAI من Salesforce، يمكنك: + +- أتمتة تسجيل وتأهيل العملاء المحتملين +- إنشاء مواد مبيعات مخصصة +- تعزيز خدمة العملاء بردود مدعومة بالذكاء الاصطناعي +- تبسيط تحليل البيانات وإعداد التقارير + +## عرض توضيحي + + + +## البدء + +لإعداد مشغلات Salesforce: + +1. **تواصل مع الدعم**: تواصل مع دعم CrewAI AMP للمساعدة في إعداد مشغل Salesforce +2. **مراجعة المتطلبات**: تأكد من أن لديك صلاحيات Salesforce اللازمة والوصول إلى API +3. **تهيئة الاتصال**: اعمل مع فريق الدعم لإنشاء الاتصال بين CrewAI ومثيل Salesforce الخاص بك +4. **اختبار المشغلات**: تحقق من عمل المشغلات بشكل صحيح مع حالات الاستخدام المحددة + +## حالات الاستخدام + +سيناريوهات Salesforce + CrewAI الشائعة تشمل: + +- **معالجة العملاء المحتملين**: تحليل وتسجيل العملاء المحتملين الوافدين تلقائياً +- **إنشاء العروض**: إنشاء عروض مخصصة بناءً على بيانات الفرص +- **رؤى العملاء**: إنشاء تقارير تحليلية من سجل تفاعلات العملاء +- **أتمتة المتابعة**: إنشاء رسائل متابعة وتوصيات مخصصة + +## الخطوات التالية + +للحصول على تعليمات الإعداد المفصلة وخيارات التهيئة المتقدمة، يرجى التواصل مع دعم CrewAI AMP الذي يمكنه تقديم إرشادات مخصصة لبيئة Salesforce واحتياجات عملك المحددة. diff --git a/docs/v1.15.1/ar/enterprise/guides/slack-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/slack-trigger.mdx new file mode 100644 index 000000000..28aed7b6e --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/slack-trigger.mdx @@ -0,0 +1,62 @@ +--- +title: "مشغل Slack" +description: "تشغيل طواقم CrewAI مباشرة من Slack باستخدام أوامر الشرطة المائلة" +icon: "slack" +mode: "wide" +--- + +يشرح هذا الدليل كيفية بدء طاقم مباشرة من Slack باستخدام مشغلات CrewAI. + +## المتطلبات المسبقة + +- مشغل CrewAI لـ Slack مُثبّت ومتصل بمساحة عمل Slack +- طاقم واحد على الأقل مُهيأ في CrewAI + +## خطوات الإعداد + + + + في لوحة تحكم CrewAI، انتقل إلى قسم **Triggers**. + + + تكامل CrewAI مع Slack + + + تحقق من أن Slack مدرج ومتصل. + + + - انتقل إلى القناة التي تريد تشغيل الطاقم منها. + - اكتب أمر الشرطة المائلة "**/kickoff**" لبدء عملية تشغيل الطاقم. + - يجب أن ترى "**Kickoff crew**" تظهر أثناء الكتابة: + + تشغيل الطاقم + + - اضغط Enter أو اختر خيار "**Kickoff crew**". سيظهر مربع حوار بعنوان "**Kickoff an AI Crew**". + + + - في القائمة المنسدلة "**Select of the crews online:**"، اختر الطاقم الذي تريد بدءه. + - في المثال أدناه، تم اختيار "**prep-for-meeting**": + + القائمة المنسدلة لتشغيل الطاقم + + - إذا كان طاقمك يتطلب أي مدخلات، انقر على زر "**Add Inputs**" لتقديمها. + + زر "**Add Inputs**" معروض في المثال أعلاه لكن لم يُنقر عليه بعد. + + + + - بمجرد اختيار الطاقم وإضافة أي مدخلات ضرورية، انقر على "**Kickoff**" لبدء الطاقم. + + تشغيل الطاقم + + - سيبدأ الطاقم بالتنفيذ وسترى النتائج في قناة Slack. + + نتائج تشغيل الطاقم + + + + +## نصائح + +- تأكد من أن لديك الصلاحيات اللازمة لاستخدام أمر `/kickoff` في مساحة عمل Slack. +- إذا لم تر الطاقم المطلوب في القائمة المنسدلة، تأكد من أنه مُهيأ بشكل صحيح ومتصل في CrewAI. diff --git a/docs/v1.15.1/ar/enterprise/guides/team-management.mdx b/docs/v1.15.1/ar/enterprise/guides/team-management.mdx new file mode 100644 index 000000000..7381958e4 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/team-management.mdx @@ -0,0 +1,91 @@ +--- +title: "إدارة الفريق" +description: "تعلم كيفية دعوة وإدارة أعضاء الفريق في مؤسسة CrewAI AMP" +icon: "users" +mode: "wide" +--- + +بصفتك مسؤولاً عن حساب CrewAI AMP، يمكنك بسهولة دعوة أعضاء جدد للانضمام إلى مؤسستك. يرشدك هذا الدليل خلال العملية خطوة بخطوة. + +## دعوة أعضاء الفريق + + + + - سجّل الدخول إلى حساب CrewAI AMP - ابحث عن أيقونة الترس في + الزاوية العلوية اليمنى من لوحة التحكم - انقر على أيقونة الترس للوصول إلى + صفحة **Settings**: + + صفحة الإعدادات + + + + - في صفحة الإعدادات، سترى علامة تبويب `Members` - انقر على علامة تبويب `Members` + للوصول إلى صفحة **Members**: + + علامة تبويب الأعضاء + + + + - في قسم الأعضاء، سترى قائمة بالأعضاء الحاليين (بما فيهم + أنت) - حدد موقع حقل إدخال `Email` - أدخل عنوان البريد الإلكتروني للشخص + الذي تريد دعوته - انقر على زر `Invite` لإرسال الدعوة + + + - يمكنك تكرار هذه العملية لدعوة أعضاء فريق متعددين - سيتلقى كل عضو + مدعو دعوة عبر البريد الإلكتروني للانضمام إلى مؤسستك + + + +## إضافة الأدوار + +يمكنك إضافة أدوار لأعضاء فريقك للتحكم في وصولهم إلى أجزاء مختلفة من المنصة. + + + + - سجّل الدخول إلى حساب CrewAI AMP - ابحث عن أيقونة الترس في + الزاوية العلوية اليمنى من لوحة التحكم - انقر على أيقونة الترس للوصول إلى + صفحة **Settings**: + + صفحة الإعدادات + + + + - في صفحة الإعدادات، سترى علامة تبويب `Roles` - انقر على علامة تبويب `Roles` + للوصول إلى صفحة **Roles**. + + علامة تبويب الأدوار + + - انقر على زر `Add Role` لإضافة دور جديد. - أدخل + تفاصيل وصلاحيات الدور وانقر على زر `Create Role` لإنشاء + الدور. + + نافذة إضافة الدور + + + + - في قسم الأعضاء، سترى قائمة بالأعضاء الحاليين (بما فيهم + أنت) + + العضو قبل الدعوة + + - بمجرد قبول العضو للدعوة، يمكنك إضافة دور + له. - عد إلى علامة تبويب `Roles` - انتقل إلى العضو الذي تريد إضافة + دور له وتحت عمود `Role`، انقر على القائمة المنسدلة - اختر الدور + الذي تريد إضافته للعضو - انقر على زر `Update` لحفظ الدور + + إضافة دور للعضو + + + + +## ملاحظات مهمة + +- **صلاحيات المسؤول**: فقط المستخدمون ذوو الصلاحيات الإدارية يمكنهم دعوة أعضاء جدد +- **دقة البريد الإلكتروني**: تأكد من صحة عناوين البريد الإلكتروني لأعضاء فريقك +- **قبول الدعوة**: سيحتاج الأعضاء المدعوون لقبول الدعوة للانضمام إلى مؤسستك +- **إشعارات البريد الإلكتروني**: قد ترغب في إعلام أعضاء فريقك بالتحقق من بريدهم الإلكتروني (بما في ذلك مجلدات البريد غير المرغوب) للدعوة + +باتباع هذه الخطوات، يمكنك بسهولة توسيع فريقك والتعاون بشكل أكثر فعالية داخل مؤسسة CrewAI AMP. diff --git a/docs/v1.15.1/ar/enterprise/guides/tool-repository.mdx b/docs/v1.15.1/ar/enterprise/guides/tool-repository.mdx new file mode 100644 index 000000000..9ff6b35b0 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/tool-repository.mdx @@ -0,0 +1,154 @@ +--- +title: مستودع الأدوات +description: "استخدام مستودع الأدوات لإدارة أدواتك" +icon: "toolbox" +mode: "wide" +--- + +## نظرة عامة + +مستودع الأدوات هو مدير حزم لأدوات CrewAI. يتيح للمستخدمين نشر وتثبيت وإدارة الأدوات التي تتكامل مع طواقم وتدفقات CrewAI. + +يمكن أن تكون الأدوات: + +- **خاصة**: متاحة فقط داخل مؤسستك (افتراضي) +- **عامة**: متاحة لجميع مستخدمي CrewAI إذا نُشرت بعلامة `--public` + +المستودع ليس نظام تحكم في الإصدارات. استخدم Git لتتبع تغييرات الكود وتمكين التعاون. + +## المتطلبات المسبقة + +قبل استخدام مستودع الأدوات، تأكد من أن لديك: + +- حساب [CrewAI AMP](https://app.crewai.com) +- [CrewAI CLI](/ar/concepts/cli#cli) مُثبّت +- uv>=0.5.0 مُثبّت. راجع [كيفية الترقية](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv) +- [Git](https://git-scm.com) مُثبّت ومُهيأ +- صلاحيات الوصول للنشر أو التثبيت في مؤسسة CrewAI AMP + +## تثبيت الأدوات + +لتثبيت أداة: + +```bash +crewai tool install +``` + +يثبّت هذا الأداة ويضيفها إلى `pyproject.toml`. + +يمكنك استخدام الأداة باستيرادها وإضافتها إلى وكلائك: + +```python +from your_tool.tool import YourTool + +custom_tool = YourTool() + +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=[custom_tool], + verbose=True +) +``` + +## إضافة حزم أخرى بعد تثبيت أداة + +بعد تثبيت أداة من مستودع أدوات CrewAI AMP، تحتاج لاستخدام أمر `crewai uv` لإضافة حزم أخرى لمشروعك. +استخدام أوامر `uv` المباشرة سيفشل لأن المصادقة لمستودع الأدوات يتم التعامل معها عبر CLI. باستخدام أمر `crewai uv`، يمكنك إضافة حزم أخرى لمشروعك دون القلق بشأن المصادقة. +يمكن استخدام أي أمر `uv` مع أمر `crewai uv`، مما يجعله أداة قوية لإدارة اعتماديات مشروعك دون عناء إدارة المصادقة عبر متغيرات البيئة أو طرق أخرى. + +لنفرض أنك ثبّت أداة مخصصة من مستودع أدوات CrewAI AMP تسمى "my-tool": + +```bash +crewai tool install my-tool +``` + +والآن تريد إضافة حزمة أخرى لمشروعك، يمكنك استخدام الأمر التالي: + +```bash +crewai uv add requests +``` + +أوامر أخرى مثل `uv sync` أو `uv remove` يمكن أيضاً استخدامها مع أمر `crewai uv`: + +```bash +crewai uv sync +``` + +```bash +crewai uv remove requests +``` + +سيضيف هذا الحزمة لمشروعك ويحدّث `pyproject.toml` وفقاً لذلك. + +## إنشاء ونشر الأدوات + +لإنشاء مشروع أداة جديد: + +```bash +crewai tool create +``` + +يولّد هذا مشروع أداة مُهيكل محلياً. + +بعد إجراء التغييرات، أنشئ مستودع Git وارفع الكود: + +```bash +git init +git add . +git commit -m "Initial version" +``` + +لنشر الأداة: + +```bash +crewai tool publish +``` + +افتراضياً، تُنشر الأدوات كخاصة. لجعل الأداة عامة: + +```bash +crewai tool publish --public +``` + +لمزيد من التفاصيل حول بناء الأدوات، راجع [إنشاء أدواتك الخاصة](/ar/concepts/tools#creating-your-own-tools). + +## تحديث الأدوات + +لتحديث أداة منشورة: + +1. عدّل الأداة محلياً +2. حدّث الإصدار في `pyproject.toml` (مثل من `0.1.0` إلى `0.1.1`) +3. ارفع التغييرات وانشر + +```bash +git commit -m "Update version to 0.1.1" +crewai tool publish +``` + +## حذف الأدوات + +لحذف أداة: + +1. انتقل إلى [CrewAI AMP](https://app.crewai.com) +2. انتقل إلى **Tools** +3. اختر الأداة +4. انقر على **Delete** + + + الحذف نهائي. لا يمكن استعادة أو إعادة تثبيت الأدوات المحذوفة. + + +## فحوصات الأمان + +كل إصدار منشور يخضع لفحوصات أمان آلية، ولا يكون متاحاً للتثبيت إلا بعد اجتيازها. + +يمكنك التحقق من حالة فحص الأمان للأداة في: + +`CrewAI AMP > Tools > Your Tool > Versions` + + + تواصل مع فريق الدعم للمساعدة في تكامل API أو + استكشاف الأخطاء. + diff --git a/docs/v1.15.1/ar/enterprise/guides/training-crews.mdx b/docs/v1.15.1/ar/enterprise/guides/training-crews.mdx new file mode 100644 index 000000000..77f9bb7bf --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/training-crews.mdx @@ -0,0 +1,132 @@ +--- +title: "تدريب الطواقم" +description: "قم بتدريب طواقمك المنشورة مباشرة من منصة CrewAI AMP لتحسين أداء الوكلاء بمرور الوقت" +icon: "dumbbell" +mode: "wide" +--- + +يتيح لك التدريب تحسين أداء الطاقم من خلال تشغيل جلسات تدريب تكرارية مباشرة من علامة تبويب **Training** في CrewAI AMP. تستخدم المنصة **وضع التدريب التلقائي** — حيث تتولى العملية التكرارية تلقائياً، على عكس تدريب CLI الذي يتطلب ملاحظات بشرية تفاعلية لكل تكرار. + +بعد اكتمال التدريب، يقوم CrewAI بتقييم مخرجات الوكلاء ودمج الملاحظات في اقتراحات قابلة للتنفيذ لكل وكيل. يتم بعد ذلك تطبيق هذه الاقتراحات على تشغيلات الطاقم المستقبلية لتحسين جودة المخرجات. + + + للحصول على تفاصيل حول كيفية عمل تدريب CrewAI، راجع صفحة [مفاهيم التدريب](/ar/concepts/training). + + +## المتطلبات الأساسية + + + + تحتاج إلى حساب CrewAI AMP مع نشر نشط في حالة **Ready** (نوع Crew). + + + يجب أن يكون لحسابك صلاحية تشغيل للنشر الذي تريد تدريبه. + + + +## كيفية تدريب طاقم + + + + انتقل إلى **Deployments**، انقر على نشرك، ثم اختر علامة تبويب **Training**. + + + + قدم **Training Name** — سيصبح هذا اسم ملف `.pkl` المستخدم لتخزين نتائج التدريب. على سبيل المثال، "Expert Mode Training" ينتج `expert_mode_training.pkl`. + + + + أدخل حقول إدخال الطاقم. هذه هي نفس المدخلات التي ستقدمها للتشغيل العادي — يتم تحميلها ديناميكياً بناءً على تكوين طاقمك. + + + + انقر على **Train Crew**. يتغير الزر إلى "Training..." مع مؤشر دوران أثناء تشغيل العملية. + + خلف الكواليس: + - يتم إنشاء سجل تدريب للنشر الخاص بك + - تستدعي المنصة نقطة نهاية التدريب التلقائي للنشر + - يقوم الطاقم بتشغيل تكراراته تلقائياً — لا حاجة لملاحظات يدوية + + + + تعرض لوحة **Current Training Status**: + - **Status** — الحالة الحالية لجلسة التدريب + - **Nº Iterations** — عدد تكرارات التدريب المُهيأة + - **Filename** — ملف `.pkl` الذي يتم إنشاؤه + - **Started At** — وقت بدء التدريب + - **Training Inputs** — المدخلات التي قدمتها + + + +## فهم نتائج التدريب + +بمجرد اكتمال التدريب، سترى بطاقات نتائج لكل وكيل تحتوي على المعلومات التالية: + +- **Agent Role** — اسم/دور الوكيل في طاقمك +- **Final Quality** — درجة من 0 إلى 10 تقيّم جودة مخرجات الوكيل +- **Final Summary** — ملخص لأداء الوكيل أثناء التدريب +- **Suggestions** — توصيات قابلة للتنفيذ لتحسين سلوك الوكيل + +### تحرير الاقتراحات + +يمكنك تحسين الاقتراحات لأي وكيل: + + + + في بطاقة نتائج أي وكيل، انقر على زر **Edit** بجوار الاقتراحات. + + + + حدّث نص الاقتراحات ليعكس التحسينات التي تريدها بشكل أفضل. + + + + انقر على **Save**. تتم مزامنة الاقتراحات المُعدّلة مع النشر وتُستخدم في جميع التشغيلات المستقبلية. + + + +## استخدام بيانات التدريب + +لتطبيق نتائج التدريب على طاقمك: + +1. لاحظ **Training Filename** (ملف `.pkl`) من جلسة التدريب المكتملة. +2. حدد اسم الملف هذا في تكوين kickoff أو التشغيل الخاص بنشرك. +3. يقوم الطاقم تلقائياً بتحميل ملف التدريب وتطبيق الاقتراحات المخزنة على كل وكيل. + +هذا يعني أن الوكلاء يستفيدون من الملاحظات المُنشأة أثناء التدريب في كل تشغيل لاحق. + +## التدريبات السابقة + +يعرض الجزء السفلي من علامة تبويب Training **سجل جميع جلسات التدريب السابقة** للنشر. استخدم هذا لمراجعة التدريبات السابقة، ومقارنة النتائج، أو اختيار ملف تدريب مختلف للاستخدام. + +## معالجة الأخطاء + +إذا فشل تشغيل التدريب، تعرض لوحة الحالة حالة خطأ مع رسالة تصف ما حدث خطأ. + +الأسباب الشائعة لفشل التدريب: +- **لم يتم تحديث وقت تشغيل النشر** — تأكد من أن نشرك يعمل بأحدث إصدار +- **أخطاء تنفيذ الطاقم** — مشاكل في منطق مهام الطاقم أو تكوين الوكيل +- **مشاكل الشبكة** — مشاكل الاتصال بين المنصة والنشر + +## القيود + + + ضع هذه القيود في الاعتبار عند التخطيط لسير عمل التدريب الخاص بك: + - **تدريب نشط واحد في كل مرة** لكل نشر — انتظر حتى ينتهي التشغيل الحالي قبل بدء آخر + - **وضع التدريب التلقائي فقط** — لا تدعم المنصة الملاحظات التفاعلية لكل تكرار مثل CLI + - **بيانات التدريب خاصة بالنشر** — ترتبط نتائج التدريب بمثيل وإصدار النشر المحدد + + +## الموارد ذات الصلة + + + + تعلم كيف يعمل تدريب CrewAI. + + + قم بتشغيل طاقمك المنشور من منصة AMP. + + + انشر طاقمك واجعله جاهزاً للتدريب. + + diff --git a/docs/v1.15.1/ar/enterprise/guides/update-crew.mdx b/docs/v1.15.1/ar/enterprise/guides/update-crew.mdx new file mode 100644 index 000000000..1bb9ec82f --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/update-crew.mdx @@ -0,0 +1,91 @@ +--- +title: "تحديث الطاقم" +description: "تحديث طاقم على CrewAI AMP" +icon: "pencil" +mode: "wide" +--- + + + بعد نشر طاقمك على CrewAI AMP، قد تحتاج لإجراء تحديثات على + الكود أو إعدادات الأمان أو التهيئة. يشرح هذا الدليل كيفية تنفيذ + عمليات التحديث الشائعة. + + +## لماذا تحديث طاقمك؟ + +لن يلتقط CrewAI تحديثات GitHub تلقائياً بشكل افتراضي، لذا ستحتاج لتشغيل التحديثات يدوياً، ما لم تكن قد حددت خيار `Auto-update` عند نشر طاقمك. + +هناك عدة أسباب قد تدفعك لتحديث نشر طاقمك: + +- تريد تحديث الكود بأحدث إيداع دفعته إلى GitHub +- تريد إعادة تعيين رمز الحامل لأسباب أمنية +- تريد تحديث متغيرات البيئة + +## 1. تحديث كود طاقمك لأحدث إيداع + +عندما تدفع إيداعات جديدة إلى مستودع GitHub وتريد تحديث نشرك: + +1. انتقل إلى طاقمك في منصة CrewAI AMP +2. انقر على زر `Re-deploy` في صفحة تفاصيل طاقمك + +![زر إعادة النشر](/images/enterprise/redeploy-button.png) + +سيؤدي ذلك إلى تشغيل تحديث يمكنك تتبعه عبر شريط التقدم. سيسحب النظام أحدث كود من مستودعك ويعيد بناء نشرك. + +## 2. إعادة تعيين رمز الحامل + +إذا كنت تحتاج لإنشاء رمز حامل جديد (مثلاً، إذا كنت تشتبه في أن الرمز الحالي ربما تم اختراقه): + +1. انتقل إلى طاقمك في منصة CrewAI AMP +2. ابحث عن قسم `Bearer Token` +3. انقر على زر `Reset` بجانب رمزك الحالي + +![إعادة تعيين الرمز](/images/enterprise/reset-token.png) + + + إعادة تعيين رمز الحامل ستبطل الرمز السابق فوراً. + تأكد من تحديث أي تطبيقات أو نصوص برمجية تستخدم الرمز القديم. + + +## 3. تحديث متغيرات البيئة + +لتحديث متغيرات البيئة لطاقمك: + +1. أولاً ادخل صفحة النشر بالنقر على اسم طاقمك + + + ![زر متغيرات البيئة](/images/enterprise/env-vars-button.png) + + +2. حدد موقع قسم `Environment Variables` (ستحتاج للنقر على أيقونة `Settings` للوصول إليه) +3. عدّل المتغيرات الحالية أو أضف جديدة في الحقول المتوفرة +4. انقر على زر `Update` بجانب كل متغير تعدّله + + + ![تحديث متغيرات البيئة](/images/enterprise/update-env-vars.png) + + +5. أخيراً، انقر على زر `Update Deployment` في أسفل الصفحة لتطبيق التغييرات + + + تحديث متغيرات البيئة سيشغّل نشراً جديداً، لكن هذا سيحدّث + فقط تهيئة البيئة وليس الكود نفسه. + + +## بعد التحديث + +بعد إجراء أي تحديث: + +1. سيعيد النظام بناء وإعادة نشر طاقمك +2. يمكنك مراقبة تقدم النشر في الوقت الفعلي +3. بمجرد الاكتمال، اختبر طاقمك للتأكد من أن التغييرات تعمل كما هو متوقع + + + إذا واجهت أي مشاكل بعد التحديث، يمكنك عرض سجلات النشر في + المنصة أو التواصل مع الدعم للمساعدة. + + + + تواصل مع فريق الدعم للمساعدة في تحديث طاقمك أو + استكشاف أخطاء النشر. + diff --git a/docs/v1.15.1/ar/enterprise/guides/webhook-automation.mdx b/docs/v1.15.1/ar/enterprise/guides/webhook-automation.mdx new file mode 100644 index 000000000..86d4ffe86 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/webhook-automation.mdx @@ -0,0 +1,157 @@ +--- +title: "أتمتة Webhook" +description: "أتمتة سير عمل CrewAI AMP باستخدام webhooks مع منصات مثل ActivePieces وZapier وMake.com" +icon: "webhook" +mode: "wide" +--- + +يتيح لك CrewAI AMP أتمتة سير عملك باستخدام webhooks. ستوجهك هذه المقالة خلال عملية إعداد واستخدام webhooks لبدء تنفيذ طاقمك، مع التركيز على التكامل مع ActivePieces، وهي منصة أتمتة سير العمل مشابهة لـ Zapier وMake.com. + +## إعداد Webhooks + + + + - انتقل إلى لوحة تحكم CrewAI AMP + - ابحث عن قسم `/kickoff`، الذي يُستخدم لبدء تنفيذ الطاقم + + واجهة البدء + + + + + في قسم محتوى JSON، ستحتاج إلى تقديم المعلومات التالية: + + - **inputs**: كائن JSON يحتوي على: + - `company`: اسم الشركة (مثال: "tesla") + - `product_name`: اسم المنتج (مثال: "crewai") + - `form_response`: نوع الاستجابة (مثال: "financial") + - `icp_description`: وصف موجز لملف العميل المثالي + - `product_description`: وصف قصير للمنتج + - `taskWebhookUrl`، `stepWebhookUrl`، `crewWebhookUrl`: عناوين URL لنقاط نهاية webhook المختلفة (ActivePieces أو Zapier أو Make.com أو منصة أخرى متوافقة) + + + + في هذا المثال سنستخدم ActivePieces. يمكنك استخدام منصات أخرى مثل Zapier وMake.com + + للتكامل مع ActivePieces: + + 1. أنشئ تدفقًا جديدًا في ActivePieces + 2. أضف مشغلًا (مثال: جدول `Every Day`) + + مشغل ActivePieces + + + 3. أضف خطوة إجراء HTTP + - عيّن الإجراء إلى `Send HTTP request` + - استخدم `POST` كطريقة + - عيّن عنوان URL إلى نقطة نهاية بدء CrewAI AMP + - أضف الترويسات اللازمة (مثال: `Bearer Token`) + + ترويسات ActivePieces + + + - في النص، ضمّن محتوى JSON كما تم تكوينه في الخطوة 2 + + نص ActivePieces + + + - سيبدأ الطاقم بعد ذلك في الوقت المحدد مسبقًا. + + + + 1. أنشئ تدفقًا جديدًا في ActivePieces وسمّه + + تدفق ActivePieces + + + 2. أضف خطوة webhook كمشغل: + - اختر `Catch Webhook` كنوع المشغل + - سيولّد هذا عنوان URL فريدًا سيستقبل طلبات HTTP ويشغل تدفقك + + Webhook ActivePieces + + + - كوّن البريد الإلكتروني لاستخدام نص جسم webhook الخاص بالطاقم + + بريد ActivePieces الإلكتروني + + + + + +## أمثلة مخرجات Webhook + +**ملاحظة:** أي كائن `meta` مُقدم في طلب البدء الخاص بك سيتم تضمينه في جميع حمولات webhook، مما يتيح لك تتبع الطلبات والحفاظ على السياق عبر دورة حياة تنفيذ الطاقم بالكامل. + + + + `stepWebhookUrl` - رد نداء يتم تنفيذه عند كل فكرة داخلية للوكيل + + ```json + { + "prompt": "Research the financial industry for potential AI solutions", + "thought": "I need to conduct preliminary research on the financial industry", + "tool": "research_tool", + "tool_input": "financial industry AI solutions", + "result": "**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.", + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + `taskWebhookUrl` - رد نداء يتم تنفيذه عند انتهاء كل مهمة + + ```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.", + "name": "Industry Research Task", + "expected_output": "Detailed research report on the financial industry", + "summary": "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.", + "agent": "Research Agent", + "output": "**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.", + "output_json": { + "industry": "financial", + "key_opportunities": ["digital customer engagement", "risk management", "regulatory compliance"] + }, + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + `crewWebhookUrl` - رد نداء يتم تنفيذه عند انتهاء تنفيذ الطاقم + + ```json + { + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "result": "**Final Analysis Report**\n\nLead Score: Customer service enhancement and compliance are particularly relevant.\n\nTalking Points:\n- Highlight how crewai's AI solutions can transform customer service\n- Discuss crewai's potential for sustainability goals\n- Emphasize compliance capabilities\n- Stress adaptability for various operation scales", + "result_json": { + "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." + ] + }, + "token_usage": { + "total_tokens": 1250, + "prompt_tokens": 800, + "completion_tokens": 450 + }, + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + diff --git a/docs/v1.15.1/ar/enterprise/guides/zapier-trigger.mdx b/docs/v1.15.1/ar/enterprise/guides/zapier-trigger.mdx new file mode 100644 index 000000000..ebeb1c863 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/guides/zapier-trigger.mdx @@ -0,0 +1,105 @@ +--- +title: "مشغل Zapier" +description: "تشغيل أطقم CrewAI من سير عمل Zapier لأتمتة سير العمل عبر التطبيقات" +icon: "bolt" +mode: "wide" +--- + +سيرشدك هذا الدليل خلال عملية إعداد مشغلات Zapier لـ CrewAI AMP، مما يتيح لك أتمتة سير العمل بين CrewAI AMP والتطبيقات الأخرى. + +## المتطلبات الأساسية + +- حساب CrewAI AMP +- حساب Zapier +- حساب Slack (لهذا المثال المحدد) + +## الإعداد خطوة بخطوة + + + + - في Zapier، أنشئ Zap جديدًا. + + + Zapier 1 + + + + + + Zapier 2 + + - اختر `New Pushed Message` كحدث المشغل. + - اربط حساب Slack الخاص بك إذا لم تفعل ذلك بالفعل. + + + + - أضف خطوة إجراء جديدة إلى Zap الخاص بك. + - اختر CrewAI+ كتطبيق الإجراء وKickoff كحدث الإجراء + + + Zapier 5 + + + + + - اربط حساب CrewAI AMP الخاص بك. + - اختر الطاقم المناسب لسير عملك. + + + Zapier 6 + + - كوّن مدخلات الطاقم باستخدام البيانات من رسالة Slack. + + + + - أضف خطوة إجراء أخرى لتنسيق مخرجات النص من CrewAI AMP. + - استخدم أدوات التنسيق في Zapier لتحويل مخرجات Markdown إلى HTML. + + + Zapier 8 + + + Zapier 9 + + + + + - أضف خطوة إجراء نهائية لإرسال المخرجات المنسقة عبر البريد الإلكتروني. + - اختر خدمة البريد الإلكتروني المفضلة لديك (مثال: Gmail، Outlook). + - كوّن تفاصيل البريد الإلكتروني، بما في ذلك المستلم والموضوع والنص. + - أدرج مخرجات CrewAI AMP المنسقة في نص البريد الإلكتروني. + + + Zapier 7 + + + + + - أدخل النص في قناة Slack الخاصة بك + + + Zapier 10 + + + - اختر زر النقاط الثلاث ثم اختر Push to Zapier + + + Zapier 11 + + + + + + Zapier 12 + + + + + +## نصائح للنجاح + +- تأكد من أن مدخلات CrewAI AMP مربوطة بشكل صحيح من رسالة Slack. +- اختبر Zap الخاص بك جيدًا قبل تفعيله لاكتشاف أي مشاكل محتملة. +- فكر في إضافة خطوات معالجة الأخطاء لإدارة حالات الفشل المحتملة في سير العمل. + +باتباع هذه الخطوات، ستكون قد أعددت بنجاح مشغلات Zapier لـ CrewAI AMP، مما يتيح سير عمل آلي يتم تشغيله بواسطة رسائل Slack وينتج عنه إشعارات بالبريد الإلكتروني مع مخرجات CrewAI AMP. diff --git a/docs/v1.15.1/ar/enterprise/integrations/asana.mdx b/docs/v1.15.1/ar/enterprise/integrations/asana.mdx new file mode 100644 index 000000000..394d2193b --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/asana.mdx @@ -0,0 +1,271 @@ +--- +title: تكامل Asana +description: "تنسيق مهام الفريق والمشاريع مع تكامل Asana لـ CrewAI." +icon: "circle" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المهام والمشاريع وتنسيق الفريق عبر Asana. أنشئ المهام وحدّث حالة المشروع وأدر التعيينات وبسّط سير عمل فريقك مع الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Asana، تأكد من أن لديك: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك نشط +- حساب Asana مع الأذونات المناسبة +- ربط حساب Asana الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Asana + +### 1. ربط حساب Asana الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Asana** في قسم تكاملات المصادقة +3. انقر على **ربط** وأكمل تدفق OAuth +4. امنح الأذونات اللازمة لإدارة المهام والمشاريع +5. انسخ رمز Enterprise الخاص بك من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز Enterprise الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء تعليق في Asana. + + **المعاملات:** + - `task` (string, مطلوب): معرف المهمة - معرف المهمة التي سيُضاف إليها التعليق. سيُنسب التعليق للمستخدم المصادق عليه حاليًا. + - `text` (string, مطلوب): النص (مثال: "This is a comment."). + + + + + **الوصف:** إنشاء مشروع في Asana. + + **المعاملات:** + - `name` (string, مطلوب): الاسم (مثال: "Stuff to buy"). + - `workspace` (string, مطلوب): مساحة العمل - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار مساحة العمل لإنشاء المشاريع فيها. الافتراضي هو أول مساحة عمل للمستخدم إذا تُرك فارغًا. + - `team` (string, اختياري): الفريق - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار الفريق لمشاركة هذا المشروع معه. الافتراضي هو أول فريق للمستخدم إذا تُرك فارغًا. + - `notes` (string, اختياري): ملاحظات (مثال: "These are things we need to purchase."). + + + + + **الوصف:** الحصول على قائمة المشاريع في Asana. + + **المعاملات:** + - `archived` (string, اختياري): مؤرشف - اختر "true" لعرض المشاريع المؤرشفة، "false" لعرض المشاريع النشطة فقط، أو "default" لعرض كليهما. + - الخيارات: `default`, `true`, `false` + + + + + **الوصف:** الحصول على مشروع بواسطة المعرف في Asana. + + **المعاملات:** + - `projectFilterId` (string, مطلوب): معرف المشروع. + + + + + **الوصف:** إنشاء مهمة في Asana. + + **المعاملات:** + - `name` (string, مطلوب): الاسم (مثال: "Task Name"). + - `workspace` (string, اختياري): مساحة العمل - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار مساحة العمل لإنشاء المهام فيها. الافتراضي هو أول مساحة عمل للمستخدم إذا تُرك فارغًا. + - `project` (string, اختياري): المشروع - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار المشروع لإنشاء هذه المهمة فيه. + - `notes` (string, اختياري): ملاحظات. + - `dueOnDate` (string, اختياري): تاريخ الاستحقاق - التاريخ الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due At. (مثال: "YYYY-MM-DD"). + - `dueAtDate` (string, اختياري): الاستحقاق في - التاريخ والوقت (طابع زمني ISO) الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due On. (مثال: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, اختياري): المُكلف - معرف مستخدم Asana الذي سيتم تعيين هذه المهمة له. استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار المُكلف. + - `gid` (string, اختياري): معرف خارجي - معرف من تطبيقك لربط هذه المهمة به. يمكنك استخدام هذا المعرف لمزامنة التحديثات لهذه المهمة لاحقًا. + + + + + **الوصف:** تحديث مهمة في Asana. + + **المعاملات:** + - `taskId` (string, مطلوب): معرف المهمة - معرف المهمة التي سيتم تحديثها. + - `completeStatus` (string, اختياري): حالة الإكمال. + - الخيارات: `true`, `false` + - `name` (string, اختياري): الاسم (مثال: "Task Name"). + - `notes` (string, اختياري): ملاحظات. + - `dueOnDate` (string, اختياري): تاريخ الاستحقاق - التاريخ الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due At. (مثال: "YYYY-MM-DD"). + - `dueAtDate` (string, اختياري): الاستحقاق في - التاريخ والوقت (طابع زمني ISO) الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due On. (مثال: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, اختياري): المُكلف - معرف مستخدم Asana الذي سيتم تعيين هذه المهمة له. + - `gid` (string, اختياري): معرف خارجي - معرف من تطبيقك لربط هذه المهمة به. + + + + + **الوصف:** الحصول على قائمة المهام في Asana. + + **المعاملات:** + - `workspace` (string, اختياري): مساحة العمل - معرف مساحة العمل لتصفية المهام عليها. + - `project` (string, اختياري): المشروع - معرف المشروع لتصفية المهام عليه. + - `assignee` (string, اختياري): المُكلف - معرف المُكلف لتصفية المهام عليه. + - `completedSince` (string, اختياري): مكتملة منذ - إرجاع المهام غير المكتملة فقط أو التي اكتملت منذ هذا الوقت (طابع زمني ISO أو Unix). (مثال: "2014-04-25T16:15:47-04:00"). + + + + + **الوصف:** الحصول على قائمة المهام بواسطة المعرف في Asana. + + **المعاملات:** + - `taskId` (string, مطلوب): معرف المهمة. + + + + + **الوصف:** الحصول على مهمة بواسطة المعرف الخارجي في Asana. + + **المعاملات:** + - `gid` (string, مطلوب): المعرف الخارجي - المعرف الذي ترتبط أو تتزامن به هذه المهمة، من تطبيقك. + + + + + **الوصف:** إضافة مهمة إلى قسم في Asana. + + **المعاملات:** + - `sectionId` (string, مطلوب): معرف القسم - معرف القسم لإضافة هذه المهمة إليه. + - `taskId` (string, مطلوب): معرف المهمة - معرف المهمة. (مثال: "1204619611402340"). + - `beforeTaskId` (string, اختياري): معرف المهمة السابقة - معرف مهمة في هذا القسم سيتم إدراج هذه المهمة قبلها. لا يمكن استخدامه مع After Task ID. (مثال: "1204619611402340"). + - `afterTaskId` (string, اختياري): معرف المهمة التالية - معرف مهمة في هذا القسم سيتم إدراج هذه المهمة بعدها. لا يمكن استخدامه مع Before Task ID. (مثال: "1204619611402340"). + + + + + **الوصف:** الحصول على قائمة الفرق في Asana. + + **المعاملات:** + - `workspace` (string, مطلوب): مساحة العمل - إرجاع الفرق في مساحة العمل هذه المرئية للمستخدم المصرح له. + + + + + **الوصف:** الحصول على قائمة مساحات العمل في Asana. + + **المعاملات:** لا توجد معاملات مطلوبة. + + + + +## أمثلة الاستخدام + +### إعداد وكيل Asana الأساسي + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Asana capabilities +asana_agent = Agent( + role="Project Manager", + goal="Manage tasks and projects in Asana efficiently", + backstory="An AI assistant specialized in project management and task coordination.", + apps=['asana'] # All Asana actions will be available +) + +# 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() +``` + +### تصفية أدوات Asana محددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Asana actions only +task_manager_agent = Agent( + role="Task Manager", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and management.", + apps=[ + 'asana/create_task', + 'asana/update_task', + 'asana/get_tasks' + ] # Specific Asana actions +) + +# 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() +``` + +### إدارة المشاريع المتقدمة + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate project activities and track progress", + backstory="An experienced project coordinator who ensures projects run smoothly.", + apps=['asana'] +) + +# Complex task involving multiple Asana operations +coordination_task = Task( + description=""" + 1. Get all active projects in the workspace + 2. For each project, get the list of incomplete tasks + 3. Create a summary report task in the 'Management Reports' project + 4. Add comments to overdue tasks to request status updates + """, + agent=project_coordinator, + expected_output="Summary report created and status update requests sent for overdue tasks" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ar/enterprise/integrations/box.mdx b/docs/v1.15.1/ar/enterprise/integrations/box.mdx new file mode 100644 index 000000000..08186175f --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/box.mdx @@ -0,0 +1,280 @@ +--- +title: تكامل Box +description: "تخزين الملفات وإدارة المستندات مع تكامل Box لـ CrewAI." +icon: "box" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة الملفات والمجلدات والمستندات عبر Box. ارفع الملفات، ونظّم هياكل المجلدات، وابحث في المحتوى، وبسّط إدارة مستندات فريقك باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Box، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Box بالصلاحيات المناسبة +- ربط حساب Box الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Box + +### 1. ربط حساب Box الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Box** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة الملفات والمجلدات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** حفظ ملف من عنوان URL في Box. + + **المعاملات:** + - `fileAttributes` (object, مطلوب): السمات - بيانات وصفية للملف تشمل الاسم والمجلد الأصلي والطوابع الزمنية. + ```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, مطلوب): عنوان URL للملف - يجب أن يكون حجم الملفات أقل من 50 ميجابايت. (مثال: "https://picsum.photos/200/300"). + + + + + **الوصف:** حفظ ملف في Box. + + **المعاملات:** + - `file` (string, مطلوب): الملف - يقبل كائن ملف يحتوي على بيانات الملف. يجب أن يكون حجم الملفات أقل من 50 ميجابايت. + - `fileName` (string, مطلوب): اسم الملف (مثال: "qwerty.png"). + - `folder` (string, اختياري): المجلد - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار وجهة مجلد الملف. يستخدم المجلد الجذري افتراضياً إذا تُرك فارغاً. + + + + + **الوصف:** الحصول على ملف بواسطة المعرّف في Box. + + **المعاملات:** + - `fileId` (string, مطلوب): معرّف الملف - المعرّف الفريد الذي يمثل ملفاً. (مثال: "12345"). + + + + + **الوصف:** عرض قائمة الملفات في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "direction", + "operator": "$stringExactlyMatches", + "value": "ASC" + } + ] + } + ] + } + ``` + + + + + **الوصف:** إنشاء مجلد في Box. + + **المعاملات:** + - `folderName` (string, مطلوب): الاسم - اسم المجلد الجديد. (مثال: "New Folder"). + - `folderParent` (object, مطلوب): المجلد الأصلي - المجلد الأصلي الذي سيُنشأ فيه المجلد الجديد. + ```json + { + "id": "123456" + } + ``` + + + + + **الوصف:** نقل مجلد في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + - `folderName` (string, مطلوب): الاسم - اسم المجلد. (مثال: "New Folder"). + - `folderParent` (object, مطلوب): المجلد الأصلي - وجهة المجلد الأصلي الجديد. + ```json + { + "id": "123456" + } + ``` + + + + + **الوصف:** الحصول على مجلد بواسطة المعرّف في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + + + + + **الوصف:** البحث في المجلدات في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المجلد المراد البحث فيه. + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "sort", + "operator": "$stringExactlyMatches", + "value": "name" + } + ] + } + ] + } + ``` + + + + + **الوصف:** حذف مجلد في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + - `recursive` (boolean, اختياري): تكراري - حذف مجلد غير فارغ بحذف المجلد وجميع محتوياته تكرارياً. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Box + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Box capabilities +box_agent = Agent( + role="Document Manager", + goal="Manage files and folders in Box efficiently", + backstory="An AI assistant specialized in document management and file organization.", + apps=['box'] # All Box actions will be available +) + +# 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() +``` + +### تصفية أدوات Box محددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Box actions only +file_organizer_agent = Agent( + role="File Organizer", + goal="Organize and manage file storage efficiently", + backstory="An AI assistant that focuses on file organization and storage management.", + apps=['box/create_folder', 'box/save_file', 'box/list_files'] # Specific Box actions +) + +# 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() +``` + +### إدارة الملفات المتقدمة + +```python +from crewai import Agent, Task, Crew + +file_manager = Agent( + role="File Manager", + goal="Maintain organized file structure and manage document lifecycle", + backstory="An experienced file manager who ensures documents are properly organized and accessible.", + apps=['box'] +) + +# Complex task involving multiple Box operations +management_task = Task( + description=""" + 1. List all files in the root folder + 2. Create monthly archive folders for the current year + 3. Move old files to appropriate archive folders + 4. Generate a summary report of the file organization + """, + agent=file_manager, + expected_output="Files organized into archive structure with summary report" +) + +crew = Crew( + agents=[file_manager], + tasks=[management_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ar/enterprise/integrations/clickup.mdx b/docs/v1.15.1/ar/enterprise/integrations/clickup.mdx new file mode 100644 index 000000000..a8b75526c --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/clickup.mdx @@ -0,0 +1,301 @@ +--- +title: تكامل ClickUp +description: "إدارة المهام والإنتاجية مع تكامل ClickUp لـ CrewAI." +icon: "list-check" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المهام والمشاريع وسير عمل الإنتاجية عبر ClickUp. أنشئ المهام وحدّثها، ونظّم المشاريع، وأدر تعيينات الفريق، وبسّط إدارة إنتاجيتك باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل ClickUp، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب ClickUp بالصلاحيات المناسبة +- ربط حساب ClickUp الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل ClickUp + +### 1. ربط حساب ClickUp الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **ClickUp** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المهام والمشاريع +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** البحث عن المهام في ClickUp باستخدام فلاتر متقدمة. + + **المعاملات:** + - `taskFilterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "statuses%5B%5D", + "operator": "$stringExactlyMatches", + "value": "open" + } + ] + } + ] + } + ``` + الحقول المتاحة: `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` + + + + + **الوصف:** الحصول على المهام في قائمة محددة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): القائمة - اختر قائمة للحصول على المهام منها. استخدم إعدادات المستخدم في بوابة الاتصال للسماح للمستخدمين باختيار قائمة ClickUp. + - `taskFilterFormula` (string, اختياري): البحث عن المهام التي تطابق الفلاتر المحددة. مثال: name=task1. + + + + + **الوصف:** إنشاء مهمة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): القائمة - اختر قائمة لإنشاء هذه المهمة فيها. + - `name` (string, مطلوب): الاسم - اسم المهمة. + - `description` (string, اختياري): الوصف - وصف المهمة. + - `status` (string, اختياري): الحالة - اختر حالة لهذه المهمة. + - `assignees` (string, اختياري): المكلّفون - اختر عضواً (أو مصفوفة من معرّفات الأعضاء) ليتم تعيينهم لهذه المهمة. + - `dueDate` (string, اختياري): تاريخ الاستحقاق - حدد تاريخ استحقاق لهذه المهمة. + - `additionalFields` (string, اختياري): حقول إضافية - حدد حقولاً إضافية لتضمينها في هذه المهمة بصيغة JSON. + + + + + **الوصف:** تحديث مهمة في ClickUp. + + **المعاملات:** + - `taskId` (string, مطلوب): معرّف المهمة - معرّف المهمة المراد تحديثها. + - `listId` (string, مطلوب): القائمة - اختر قائمة لإنشاء هذه المهمة فيها. + - `name` (string, اختياري): الاسم - اسم المهمة. + - `description` (string, اختياري): الوصف - وصف المهمة. + - `status` (string, اختياري): الحالة - اختر حالة لهذه المهمة. + - `assignees` (string, اختياري): المكلّفون - اختر عضواً (أو مصفوفة من معرّفات الأعضاء) ليتم تعيينهم لهذه المهمة. + - `dueDate` (string, اختياري): تاريخ الاستحقاق - حدد تاريخ استحقاق لهذه المهمة. + - `additionalFields` (string, اختياري): حقول إضافية - حدد حقولاً إضافية لتضمينها في هذه المهمة بصيغة JSON. + + + + + **الوصف:** حذف مهمة في ClickUp. + + **المعاملات:** + - `taskId` (string, مطلوب): معرّف المهمة - معرّف المهمة المراد حذفها. + + + + + **الوصف:** الحصول على معلومات القائمة في ClickUp. + + **المعاملات:** + - `spaceId` (string, مطلوب): معرّف المساحة - معرّف المساحة التي تحتوي على القوائم. + + + + + **الوصف:** الحصول على الحقول المخصصة في قائمة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): معرّف القائمة - معرّف القائمة للحصول على الحقول المخصصة منها. + + + + + **الوصف:** الحصول على جميع الحقول في قائمة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): معرّف القائمة - معرّف القائمة للحصول على جميع الحقول منها. + + + + + **الوصف:** الحصول على معلومات المساحة في ClickUp. + + **المعاملات:** + - `spaceId` (string, اختياري): معرّف المساحة - معرّف المساحة المراد استرجاعها. + + + + + **الوصف:** الحصول على المجلدات في ClickUp. + + **المعاملات:** + - `spaceId` (string, مطلوب): معرّف المساحة - معرّف المساحة التي تحتوي على المجلدات. + + + + + **الوصف:** الحصول على معلومات العضو في ClickUp. + + **المعاملات:** لا توجد معاملات مطلوبة. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ ClickUp + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Clickup capabilities +clickup_agent = Agent( + role="Task Manager", + goal="Manage tasks and projects in ClickUp efficiently", + backstory="An AI assistant specialized in task management and productivity coordination.", + apps=['clickup'] # All Clickup actions will be available +) + +# 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() +``` + +### تصفية أدوات ClickUp محددة + +```python + +task_coordinator = Agent( + role="Task Coordinator", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and status management.", + apps=['clickup/create_task'] +) + +# 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() +``` + +### إدارة المشاريع المتقدمة + +```python +from crewai import Agent, Task, Crew + +project_manager = Agent( + role="Project Manager", + goal="Coordinate project activities and track team productivity", + backstory="An experienced project manager who ensures projects are delivered on time.", + apps=['clickup'] +) + +# Complex task involving multiple ClickUp operations +project_coordination = Task( + description=""" + 1. Get all open tasks in the current space + 2. Identify overdue tasks and update their status + 3. Create a weekly report task summarizing project progress + 4. Assign the report task to the team lead + """, + agent=project_manager, + expected_output="Project status updated and weekly report task created and assigned" +) + +crew = Crew( + agents=[project_manager], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### البحث في المهام وإدارتها + +```python +from crewai import Agent, Task, Crew + +task_analyst = Agent( + role="Task Analyst", + goal="Analyze task patterns and optimize team productivity", + backstory="An AI assistant that analyzes task data to improve team efficiency.", + apps=['clickup'] +) + +# Task to analyze and optimize task distribution +task_analysis = Task( + description=""" + Search for all tasks assigned to team members in the last 30 days, + analyze completion patterns, and create optimization recommendations + """, + agent=task_analyst, + expected_output="Task analysis report with optimization recommendations" +) + +crew = Crew( + agents=[task_analyst], + tasks=[task_analysis] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل ClickUp أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/databricks.mdx b/docs/v1.15.1/ar/enterprise/integrations/databricks.mdx new file mode 100644 index 000000000..270f95e5e --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/databricks.mdx @@ -0,0 +1,123 @@ +--- +title: تكامل Databricks +description: "اربط وكلاء CrewAI بـ Databricks Genie وSQL وUnity Catalog Functions وVector Search عبر خوادم MCP المُدارة من Databricks." +icon: "layer-group" +mode: "wide" +--- + +## نظرة عامة + +اربط وكلاء CrewAI مباشرةً بمساحة عمل Databricks الخاصة بك عبر [خوادم MCP المُدارة من Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). يتيح تكامل Databricks لوكلائك طرح أسئلة بلغة طبيعية باستخدام **Genie**، وتنفيذ **SQL** خاضع للحوكمة، واستدعاء **Unity Catalog Functions**، واسترجاع المستندات باستخدام **Vector Search** — كل ذلك دون كتابة أو استضافة أي كود موصِّل، مع تطبيق أذونات Unity Catalog في كل استدعاء. + +في الخلفية، يُعدّ تكامل Databricks غلافًا مُدارًا حول دعم [خوادم MCP المخصصة](/ar/enterprise/guides/custom-mcp-server) في CrewAI. تكشف Databricks عن كل قدرة كنقطة نهاية [Model Context Protocol](https://modelcontextprotocol.io/) خاصة بها، ويتصل بها CrewAI بأمان نيابةً عنك. ولأن كل خادم يُضاف بشكل منفصل، يمكنك تفعيل القدرات التي تحتاجها فرقك (crews) بالضبط. + +## القدرات الرئيسية + + + + اطرح أسئلة بلغة طبيعية واحصل على إجابات مستندة إلى بياناتك باستخدام [Genie](https://docs.databricks.com/aws/en/genie/)، الذي يستعلم من Genie Spaces وUnity Catalog ويوفّر روابط تعود إلى واجهة Databricks. + + + نفّذ SQL خاضعًا للحوكمة على مستودعات Databricks لديك للاستعلام عن البيانات وتحويلها وإنشاء خطوط أنابيب البيانات مباشرةً من وكلائك. + + + استدعِ [دوال Unity Catalog](https://docs.databricks.com/aws/en/udf/unity-catalog) لتنفيذ SQL مُعرّف مسبقًا ومنطق أعمال مخصّص كأدوات قابلة لإعادة الاستخدام وخاضعة للحوكمة. + + + استرجع المستندات ذات الصلة لسير عمل RAG والمعرفة من فهارس [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) باستخدام التشابه الدلالي. + + + +تعمل جميع الخوادم خلف Unity AI Gateway وتطبّق ضوابط الوصول في Unity Catalog، بحيث لا يرى وكلاؤك سوى البيانات والأدوات المصرَّح لهم باستخدامها. + +## المتطلبات المسبقة + +قبل استخدام تكامل Databricks، تأكّد من توفّر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) باشتراك نشط +- مساحة عمل Databricks تحتوي على القدرات التي تريد كشفها (Genie Spaces، مستودعات SQL، دوال Unity Catalog، أو فهارس Vector Search) +- [امتيازات Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog) المناسبة على الكائنات الأساسية +- اسم مضيف مساحة عمل Databricks الخاص بك (مثال: `your-workspace.cloud.databricks.com`) + +## خوادم MCP المُدارة من Databricks + +تنشر Databricks خادم MCP مُدارًا منفصلًا لكل قدرة. يكشف CrewAI عنها كاتصالات فردية، يُهيَّأ كل منها باستخدام مضيف مساحة العمل ومعرّفات Unity Catalog ذات الصلة. تتبع نقاط النهاية الأنماط التالية: + +| الخادم | الوظيفة | نمط عنوان MCP | +|--------|---------|---------------| +| **Genie** | أسئلة وأجوبة بلغة طبيعية على Genie Space | `https:///api/2.0/mcp/genie/{genie_space_id}` | +| **Databricks SQL** | تنفيذ SQL على مستودعاتك | `https:///api/2.0/mcp/sql` | +| **Unity Catalog Functions** | تشغيل دوال UC المسجّلة | `https:///api/2.0/mcp/functions/{catalog}/{schema}` | +| **Vector Search** | الاستعلام من فهرس Vector Search | `https:///api/2.0/mcp/vector-search/{catalog}/{schema}` | + + +لا حاجة لإنشاء عناوين URL هذه يدويًا — يُنشئ CrewAI كل نقطة نهاية من مضيف مساحة العمل والمعرّفات (Genie Space ID، أو catalog/schema) التي تقدّمها عند تهيئة الاتصال. للاطّلاع على المواصفات الكاملة وأحدث تفاصيل نقاط النهاية، راجع [وثائق MCP المُدارة من Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). + + +## ربط Databricks في CrewAI AMP + + + تهيئة خادم MCP مُدار من Databricks في CrewAI AMP + + +تظهر كل قدرة من قدرات Databricks — **Databricks Genie** و**Databricks SQL** و**Databricks Unity Catalog Functions** و**Databricks Vector Search** — كخادم MCP خاص بها ضمن مجموعة Databricks في صفحة **Tools & Integrations**. هيّئ ما تحتاجه: + + + + انتقل إلى **Tools & Integrations** في الشريط الجانبي الأيسر في CrewAI AMP وحدِّد مجموعة **Databricks** في قائمة Connections. سترى خوادم Genie وSQL وUnity Catalog Functions وVector Search مُدرجة أسفلها. + + + + انقر على **Configure** بجوار القدرة التي تريد تفعيلها وقدّم تفاصيل الاتصال الخاصة بها: + + - **Workspace Host** — اسم مضيف مساحة عمل Databricks الخاص بك (مثال: `my-workspace.cloud.databricks.com`). + - **Genie** — **Genie Space ID** المراد الاستعلام عنه. + - **Unity Catalog Functions** — الـ **catalog** والـ **schema** اللذان يحتويان على دوالك. + - **Vector Search** — الـ **catalog** والـ **schema** اللذان يحتويان على الفهرس. + - **Databricks SQL** — لا توجد معرّفات إضافية؛ تُنفَّذ الاستعلامات على مستودعات SQL في مساحة عملك. + + + + اختر كيف يصادق CrewAI على Databricks. يُوصى باستخدام **OAuth**. + + - **Use OAuth** — اتصل بأمان باستخدام OAuth 2.0. يصادق كل مستخدم على حدة، وتُصدر Databricks رموزًا (tokens) محدّدة النطاق للقدرة (`genie` أو `sql` أو `unity-catalog` أو `vector-search`). يتولّى CrewAI تدفّق التفويض ويُجدّد الرموز تلقائيًا. + - **Use personal access token** — صادِق باستخدام [رمز وصول شخصي من Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/pat). استخدم هوية بأقل الامتيازات للحدّ من التعرّض. + + + + أكمل المصادقة. بمجرد الاتصال، تصبح أدوات الخادم متاحة لفرقك. كرّر العملية لأي قدرات Databricks أخرى تريد تفعيلها. + + + + +لأن كل قدرة هي اتصال منفصل، يمكنك المزج والمطابقة — على سبيل المثال، فعّل Genie وVector Search لفريق بحث، مع حجز SQL وUnity Catalog Functions لفريق هندسة البيانات. تتيح لك إعدادات الرؤية (Visibility) التحكّم في أعضاء الفريق الذين يمكنهم استخدام كل منها. + + +## استخدام أدوات Databricks في فرقك + +بمجرد الاتصال، تظهر الأدوات التي يكشفها كل خادم MCP جنبًا إلى جنب مع الاتصالات المدمجة في صفحة **Tools & Integrations**. يمكنك: + +- **إسناد الأدوات إلى الوكلاء** في فرقك تمامًا مثل أي أداة أخرى في CrewAI. +- **إدارة الرؤية** للتحكّم في أعضاء الفريق الذين يمكنهم استخدام كل اتصال. +- **تعديل أو إزالة** أي اتصال في أي وقت من قائمة Connections. + +يمكن لوكلائك الآن طلب إجابات مستندة من Genie، وتنفيذ SQL على مستودعاتك، واستدعاء دوال Unity Catalog، والبحث في فهارس Vector Search — مع تدفّق النتائج تلقائيًا إلى استدلالهم. + + +تطبّق Databricks الحوكمة عبر Unity Catalog وUnity AI Gateway: لا يمكن للمستخدم اكتشاف الأدوات واستدعاؤها إلا تلك المصرَّح بها لهوية مساحة عمله. إذا فشل استدعاء أداة، فتأكّد من أن المستخدم المتصل (أو هوية الرمز) يمتلك امتيازات Unity Catalog المطلوبة على Genie Space أو المستودع أو الدالة أو الفهرس. تُنفَّذ بعض استعلامات Genie وSQL بشكل غير متزامن وقد تستغرق لحظة لإرجاع النتائج. + + +## مزيد من المعلومات + + + + وثائق Databricks الرسمية لخوادم MCP المُدارة Genie وSQL وUnity Catalog Functions وVector Search. + + + تعرّف على كيفية اتصال CrewAI بأي خادم MCP، وهو الأساس الذي يُبنى عليه تكامل Databricks. + + + + + تواصل مع فريق الدعم للحصول على المساعدة في تهيئة تكامل Databricks أو في حل المشكلات. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/github.mdx b/docs/v1.15.1/ar/enterprise/integrations/github.mdx new file mode 100644 index 000000000..7737e6c3c --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/github.mdx @@ -0,0 +1,330 @@ +--- +title: تكامل GitHub +description: "إدارة المستودعات والمشكلات مع تكامل GitHub لـ CrewAI." +icon: "github" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المستودعات والمشكلات والإصدارات عبر GitHub. أنشئ المشكلات وحدّثها، وأدر الإصدارات، وتتبع تطور المشاريع، وبسّط سير عمل تطوير البرمجيات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل GitHub، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب GitHub بصلاحيات المستودع المناسبة +- ربط حساب GitHub الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل GitHub + +### 1. ربط حساب GitHub الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **GitHub** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المستودعات والمشكلات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مشكلة في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `title` (string, مطلوب): عنوان المشكلة - حدد عنوان المشكلة المراد إنشاؤها. + - `body` (string, اختياري): محتوى المشكلة - حدد محتوى نص المشكلة المراد إنشاؤها. + - `assignees` (string, اختياري): المكلّفون - حدد اسم (أسماء) تسجيل الدخول في GitHub للمكلّفين كمصفوفة من السلاسل النصية لهذه المشكلة. (مثال: `["octocat"]`). + + + + + **الوصف:** تحديث مشكلة في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `issue_number` (string, مطلوب): رقم المشكلة - حدد رقم المشكلة المراد تحديثها. + - `title` (string, مطلوب): عنوان المشكلة - حدد عنوان المشكلة المراد تحديثها. + - `body` (string, اختياري): محتوى المشكلة - حدد محتوى نص المشكلة المراد تحديثها. + - `assignees` (string, اختياري): المكلّفون - حدد اسم (أسماء) تسجيل الدخول في GitHub للمكلّفين كمصفوفة من السلاسل النصية لهذه المشكلة. (مثال: `["octocat"]`). + - `state` (string, اختياري): الحالة - حدد الحالة المحدّثة للمشكلة. + - الخيارات: `open`, `closed` + + + + + **الوصف:** الحصول على مشكلة بواسطة الرقم في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `issue_number` (string, مطلوب): رقم المشكلة - حدد رقم المشكلة المراد جلبها. + + + + + **الوصف:** قفل مشكلة في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `issue_number` (string, مطلوب): رقم المشكلة - حدد رقم المشكلة المراد قفلها. + - `lock_reason` (string, مطلوب): سبب القفل - حدد سبب قفل محادثة المشكلة أو طلب السحب. + - الخيارات: `off-topic`, `too heated`, `resolved`, `spam` + + + + + **الوصف:** البحث عن المشكلات في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `filter` (object, مطلوب): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "assignee", + "operator": "$stringExactlyMatches", + "value": "octocat" + } + ] + } + ] + } + ``` + الحقول المتاحة: `assignee`, `creator`, `mentioned`, `labels` + + + + + **الوصف:** إنشاء إصدار في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `tag_name` (string, مطلوب): الاسم - حدد اسم وسم الإصدار المراد إنشاؤه. (مثال: "v1.0.0"). + - `target_commitish` (string, اختياري): الهدف - حدد هدف الإصدار. يمكن أن يكون اسم فرع أو SHA لعملية إيداع. الافتراضي هو الفرع الرئيسي. (مثال: "master"). + - `body` (string, اختياري): المحتوى - حدد وصفاً لهذا الإصدار. + - `draft` (string, اختياري): مسودة - حدد ما إذا كان الإصدار المُنشأ يجب أن يكون مسودة (غير منشور). + - الخيارات: `true`, `false` + - `prerelease` (string, اختياري): إصدار تجريبي - حدد ما إذا كان الإصدار المُنشأ يجب أن يكون إصداراً تجريبياً. + - الخيارات: `true`, `false` + - `discussion_category_name` (string, اختياري): اسم فئة المناقشة - إذا حُدد، يتم إنشاء مناقشة من الفئة المحددة وربطها بالإصدار. + - `generate_release_notes` (string, اختياري): ملاحظات الإصدار - حدد ما إذا كان يجب إنشاء ملاحظات الإصدار تلقائياً. + - الخيارات: `true`, `false` + + + + + **الوصف:** تحديث إصدار في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `id` (string, مطلوب): معرّف الإصدار - حدد معرّف الإصدار المراد تحديثه. + - `tag_name` (string, اختياري): الاسم - حدد اسم وسم الإصدار المراد تحديثه. (مثال: "v1.0.0"). + - `target_commitish` (string, اختياري): الهدف - حدد هدف الإصدار. يمكن أن يكون اسم فرع أو SHA لعملية إيداع. الافتراضي هو الفرع الرئيسي. (مثال: "master"). + - `body` (string, اختياري): المحتوى - حدد وصفاً لهذا الإصدار. + - `draft` (string, اختياري): مسودة - حدد ما إذا كان الإصدار يجب أن يكون مسودة (غير منشور). + - الخيارات: `true`, `false` + - `prerelease` (string, اختياري): إصدار تجريبي - حدد ما إذا كان الإصدار يجب أن يكون إصداراً تجريبياً. + - الخيارات: `true`, `false` + - `discussion_category_name` (string, اختياري): اسم فئة المناقشة - إذا حُدد، يتم إنشاء مناقشة من الفئة المحددة وربطها بالإصدار. + - `generate_release_notes` (string, اختياري): ملاحظات الإصدار - حدد ما إذا كان يجب إنشاء ملاحظات الإصدار تلقائياً. + - الخيارات: `true`, `false` + + + + + **الوصف:** الحصول على إصدار بواسطة المعرّف في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `id` (string, مطلوب): معرّف الإصدار - حدد معرّف الإصدار المراد جلبه. + + + + + **الوصف:** الحصول على إصدار بواسطة اسم الوسم في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `tag_name` (string, مطلوب): الاسم - حدد وسم الإصدار المراد جلبه. (مثال: "v1.0.0"). + + + + + **الوصف:** حذف إصدار في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `id` (string, مطلوب): معرّف الإصدار - حدد معرّف الإصدار المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ GitHub + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Github capabilities +github_agent = Agent( + role="Repository Manager", + goal="Manage GitHub repositories, issues, and releases efficiently", + backstory="An AI assistant specialized in repository management and issue tracking.", + apps=['github'] # All Github actions will be available +) + +# 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() +``` + +### تصفية أدوات GitHub محددة + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage GitHub issues efficiently", + backstory="An AI assistant that focuses on issue tracking and management.", + apps=['github/create_issue'] +) + +# 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() +``` + +### إدارة الإصدارات + +```python +from crewai import Agent, Task, Crew + +release_manager = Agent( + role="Release Manager", + goal="Manage software releases and versioning", + backstory="An experienced release manager who handles version control and release processes.", + apps=['github'] +) + +# Task to create a new release +release_task = Task( + description=""" + Create a new release v2.1.0 for the project with: + - Auto-generated release notes + - Target the main branch + - Include a description of new features and bug fixes + """, + agent=release_manager, + expected_output="Release v2.1.0 created successfully with release notes" +) + +crew = Crew( + agents=[release_manager], + tasks=[release_task] +) + +crew.kickoff() +``` + +### تتبع المشكلات وإدارتها + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Track and coordinate project issues and development progress", + backstory="An AI assistant that helps coordinate development work and track project progress.", + apps=['github'] +) + +# Complex task involving multiple GitHub operations +coordination_task = Task( + description=""" + 1. Search for all open issues assigned to the current milestone + 2. Identify overdue issues and update their priority labels + 3. Create a weekly progress report issue + 4. Lock resolved issues that have been inactive for 30 days + """, + agent=project_coordinator, + expected_output="Project coordination completed with progress report and issue management" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل GitHub أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/gmail.mdx b/docs/v1.15.1/ar/enterprise/integrations/gmail.mdx new file mode 100644 index 000000000..3b4db3fff --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/gmail.mdx @@ -0,0 +1,302 @@ +--- +title: تكامل Gmail +description: "إدارة البريد الإلكتروني وجهات الاتصال مع تكامل Gmail لـ CrewAI." +icon: "envelope" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة رسائل البريد الإلكتروني وجهات الاتصال والمسودات عبر Gmail. أرسل رسائل البريد الإلكتروني، وابحث في الرسائل، وأدر جهات الاتصال، وأنشئ المسودات، وبسّط اتصالات البريد الإلكتروني باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Gmail، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Gmail بالصلاحيات المناسبة +- ربط حساب Gmail الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Gmail + +### 1. ربط حساب Gmail الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Gmail** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة البريد الإلكتروني وجهات الاتصال +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** استرجاع قائمة بالرسائل. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `q` (string, اختياري): استعلام بحث لتصفية الرسائل (مثال: 'from:someone@example.com is:unread'). + - `maxResults` (integer, اختياري): الحد الأقصى لعدد الرسائل المُرجعة (1-500). (الافتراضي: 100) + - `pageToken` (string, اختياري): رمز الصفحة لاسترجاع صفحة محددة من النتائج. + - `labelIds` (array, اختياري): إرجاع الرسائل ذات التصنيفات التي تطابق جميع معرّفات التصنيف المحددة فقط. + - `includeSpamTrash` (boolean, اختياري): تضمين رسائل البريد العشوائي والمحذوفات في النتائج. (الافتراضي: false) + + + + + **الوصف:** إرسال بريد إلكتروني. + + **المعاملات:** + - `to` (string, مطلوب): عنوان البريد الإلكتروني للمستلم. + - `subject` (string, مطلوب): سطر موضوع البريد الإلكتروني. + - `body` (string, مطلوب): محتوى رسالة البريد الإلكتروني. + - `userId` (string, اختياري): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `cc` (string, اختياري): عناوين نسخة كربونية (مفصولة بفواصل). + - `bcc` (string, اختياري): عناوين نسخة كربونية مخفية (مفصولة بفواصل). + - `from` (string, اختياري): عنوان المرسل (إذا كان مختلفاً عن المستخدم المصادق عليه). + - `replyTo` (string, اختياري): عنوان الرد. + - `threadId` (string, اختياري): معرّف السلسلة إذا كان الرد على محادثة موجودة. + + + + + **الوصف:** حذف بريد إلكتروني بواسطة المعرّف. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. + - `id` (string, مطلوب): معرّف الرسالة المراد حذفها. + + + + + **الوصف:** إنشاء مسودة بريد إلكتروني جديدة. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. + - `message` (object, مطلوب): كائن الرسالة الذي يحتوي على محتوى المسودة. + - `raw` (string, مطلوب): رسالة البريد الإلكتروني بترميز base64url. + + + + + **الوصف:** استرجاع رسالة محددة بواسطة المعرّف. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف الرسالة المراد استرجاعها. + - `format` (string, اختياري): صيغة إرجاع الرسالة. الخيارات: "full", "metadata", "minimal", "raw". (الافتراضي: "full") + - `metadataHeaders` (array, اختياري): عند التحديد وكانت الصيغة METADATA، يتم تضمين الترويسات المحددة فقط. + + + + + **الوصف:** استرجاع مرفق رسالة. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `messageId` (string, مطلوب): معرّف الرسالة التي تحتوي على المرفق. + - `id` (string, مطلوب): معرّف المرفق المراد استرجاعه. + + + + + **الوصف:** استرجاع سلسلة بريد إلكتروني محددة بواسطة المعرّف. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد استرجاعها. + - `format` (string, اختياري): صيغة إرجاع الرسائل. الخيارات: "full", "metadata", "minimal". (الافتراضي: "full") + - `metadataHeaders` (array, اختياري): عند التحديد وكانت الصيغة METADATA، يتم تضمين الترويسات المحددة فقط. + + + + + **الوصف:** تعديل التصنيفات المُطبقة على سلسلة. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد تعديلها. + - `addLabelIds` (array, اختياري): قائمة بمعرّفات التصنيفات المراد إضافتها لهذه السلسلة. + - `removeLabelIds` (array, اختياري): قائمة بمعرّفات التصنيفات المراد إزالتها من هذه السلسلة. + + + + + **الوصف:** نقل سلسلة إلى سلة المحذوفات. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد حذفها. + + + + + **الوصف:** إزالة سلسلة من سلة المحذوفات. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد استعادتها. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Gmail + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +gmail_agent = Agent( + role="Email Manager", + goal="Manage email communications and messages efficiently", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail'] # All Gmail actions will be available +) + +# 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() +``` + +### تصفية أدوات Gmail محددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Gmail actions only +email_coordinator = Agent( + role="Email Coordinator", + goal="Coordinate email communications and manage drafts", + backstory="An AI assistant that focuses on email coordination and draft management.", + apps=[ + 'gmail/send_email', + 'gmail/fetch_emails', + 'gmail/create_draft' + ] +) + +# 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() +``` + +### البحث في البريد الإلكتروني وتحليله + +```python +from crewai import Agent, Task, Crew + +# Create agent with Gmail search and analysis capabilities +email_analyst = Agent( + role="Email Analyst", + goal="Analyze email patterns and provide insights", + backstory="An AI assistant that analyzes email data to provide actionable insights.", + apps=['gmail/fetch_emails', 'gmail/get_message'] # Specific actions for email analysis +) + +# 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() +``` + +### إدارة السلاسل + +```python +from crewai import Agent, Task, Crew + +# Create agent with Gmail thread management capabilities +thread_manager = Agent( + role="Thread Manager", + goal="Organize and manage email threads efficiently", + backstory="An AI assistant that specializes in email thread organization and management.", + apps=[ + 'gmail/fetch_thread', + 'gmail/modify_thread', + 'gmail/trash_thread' + ] +) + +# Task to organize email threads +thread_task = Task( + description=""" + 1. Fetch all threads from the last month + 2. Apply appropriate labels to organize threads by project + 3. Archive or trash threads that are no longer relevant + """, + agent=thread_manager, + expected_output="Email threads organized with appropriate labels and cleanup completed" +) + +crew = Crew( + agents=[thread_manager], + tasks=[thread_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Gmail أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/google_calendar.mdx b/docs/v1.15.1/ar/enterprise/integrations/google_calendar.mdx new file mode 100644 index 000000000..f82b6cb18 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/google_calendar.mdx @@ -0,0 +1,366 @@ +--- +title: تكامل Google Calendar +description: "إدارة الأحداث والجداول الزمنية مع تكامل Google Calendar لـ CrewAI." +icon: "calendar" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة أحداث التقويم والجداول الزمنية والتوفر عبر Google Calendar. أنشئ الأحداث وحدّثها، وأدر الحضور، وتحقق من التوفر، وبسّط سير عمل الجدولة باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Calendar، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Calendar +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Calendar + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Calendar** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى التقويم +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على توفر التقويم (معلومات مشغول/متاح). + + **المعاملات:** + - `timeMin` (string, مطلوب): وقت البداية (بصيغة RFC3339) + - `timeMax` (string, مطلوب): وقت النهاية (بصيغة RFC3339) + - `items` (array, مطلوب): معرّفات التقاويم المراد التحقق منها + ```json + [ + { + "id": "calendar_id" + } + ] + ``` + - `timeZone` (string, اختياري): المنطقة الزمنية المستخدمة في الاستجابة. الافتراضي هو UTC. + - `groupExpansionMax` (integer, اختياري): الحد الأقصى لعدد معرّفات التقاويم لمجموعة واحدة. الحد الأقصى: 100 + - `calendarExpansionMax` (integer, اختياري): الحد الأقصى لعدد التقاويم لتقديم معلومات التوفر. الحد الأقصى: 50 + + + + + **الوصف:** إنشاء حدث جديد في التقويم المحدد. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم (استخدم 'primary' للتقويم الرئيسي) + - `summary` (string, مطلوب): عنوان/ملخص الحدث + - `start_dateTime` (string, مطلوب): وقت البداية بصيغة RFC3339 (مثال: 2024-01-20T10:00:00-07:00) + - `end_dateTime` (string, مطلوب): وقت النهاية بصيغة RFC3339 + - `description` (string, اختياري): وصف الحدث + - `timeZone` (string, اختياري): المنطقة الزمنية (مثال: America/Los_Angeles) + - `location` (string, اختياري): الموقع الجغرافي للحدث كنص حر. + - `attendees` (array, اختياري): قائمة الحضور للحدث. + ```json + [ + { + "email": "attendee@example.com", + "displayName": "Attendee Name", + "optional": false + } + ] + ``` + - `reminders` (object, اختياري): معلومات حول تذكيرات الحدث. + ```json + { + "useDefault": true, + "overrides": [ + { + "method": "email", + "minutes": 15 + } + ] + } + ``` + - `conferenceData` (object, اختياري): المعلومات المتعلقة بالمؤتمر، مثل تفاصيل مؤتمر Google Meet. + ```json + { + "createRequest": { + "requestId": "unique-request-id", + "conferenceSolutionKey": { + "type": "hangoutsMeet" + } + } + } + ``` + - `visibility` (string, اختياري): ظهور الحدث. الخيارات: default, public, private, confidential. الافتراضي: default + - `transparency` (string, اختياري): ما إذا كان الحدث يحجب الوقت في التقويم. الخيارات: opaque, transparent. الافتراضي: opaque + + + + + **الوصف:** استرجاع الأحداث للتقويم المحدد. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم (استخدم 'primary' للتقويم الرئيسي) + - `timeMin` (string, اختياري): الحد الأدنى للأحداث (بصيغة RFC3339) + - `timeMax` (string, اختياري): الحد الأعلى للأحداث (بصيغة RFC3339) + - `maxResults` (integer, اختياري): الحد الأقصى لعدد الأحداث (الافتراضي 10). الحد الأدنى: 1، الحد الأقصى: 2500 + - `orderBy` (string, اختياري): ترتيب الأحداث في النتيجة. الخيارات: startTime, updated. الافتراضي: startTime + - `singleEvents` (boolean, اختياري): ما إذا كان يجب توسيع الأحداث المتكررة إلى نُسخ فردية. الافتراضي: true + - `showDeleted` (boolean, اختياري): ما إذا كان يجب تضمين الأحداث المحذوفة. الافتراضي: false + - `showHiddenInvitations` (boolean, اختياري): ما إذا كان يجب تضمين الدعوات المخفية. الافتراضي: false + - `q` (string, اختياري): مصطلحات بحث نصية حرة للعثور على الأحداث المطابقة في أي حقل. + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `timeZone` (string, اختياري): المنطقة الزمنية المستخدمة في الاستجابة. + - `updatedMin` (string, اختياري): الحد الأدنى لوقت آخر تعديل للحدث (بصيغة RFC3339) للتصفية. + - `iCalUID` (string, اختياري): يحدد معرّف حدث بصيغة iCalendar ليتم تقديمه في الاستجابة. + + + + + **الوصف:** تحديث حدث موجود. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم + - `eventId` (string, مطلوب): معرّف الحدث المراد تحديثه + - `summary` (string, اختياري): عنوان الحدث المحدّث + - `description` (string, اختياري): وصف الحدث المحدّث + - `start_dateTime` (string, اختياري): وقت البداية المحدّث + - `end_dateTime` (string, اختياري): وقت النهاية المحدّث + + + + + **الوصف:** حذف حدث محدد. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم + - `eventId` (string, مطلوب): معرّف الحدث المراد حذفه + + + + + **الوصف:** استرجاع قائمة تقاويم المستخدم. + + **المعاملات:** + - `maxResults` (integer, اختياري): الحد الأقصى لعدد الإدخالات في صفحة نتائج واحدة. الحد الأدنى: 1 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `showDeleted` (boolean, اختياري): ما إذا كان يجب تضمين إدخالات قائمة التقويم المحذوفة. الافتراضي: false + - `showHidden` (boolean, اختياري): ما إذا كان يجب عرض الإدخالات المخفية. الافتراضي: false + - `minAccessRole` (string, اختياري): الحد الأدنى لدور الوصول للمستخدم. الخيارات: freeBusyReader, owner, reader, writer + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي للتقويم + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Calendar capabilities +calendar_agent = Agent( + role="Schedule Manager", + goal="Manage calendar events and scheduling efficiently", + backstory="An AI assistant specialized in calendar management and scheduling coordination.", + apps=['google_calendar'] # All Google Calendar actions will be available +) + +# Task to create a meeting +create_meeting_task = Task( + description="Create a team standup meeting for tomorrow at 9 AM with the development team", + agent=calendar_agent, + expected_output="Meeting created successfully with Google Meet link" +) + +# Run the task +crew = Crew( + agents=[calendar_agent], + tasks=[create_meeting_task] +) + +crew.kickoff() +``` + +### تصفية أدوات التقويم المحددة + +```python +meeting_coordinator = Agent( + role="Meeting Coordinator", + goal="Coordinate meetings and check availability", + backstory="An AI assistant that focuses on meeting scheduling and availability management.", + apps=['google_calendar/create_event', 'google_calendar/get_availability'] +) + +# Task to schedule a meeting with availability check +schedule_meeting = Task( + description="Check availability for next week and schedule a project review meeting with stakeholders", + agent=meeting_coordinator, + expected_output="Meeting scheduled after checking availability of all participants" +) + +crew = Crew( + agents=[meeting_coordinator], + tasks=[schedule_meeting] +) + +crew.kickoff() +``` + +### إدارة الأحداث وتحديثاتها + +```python +from crewai import Agent, Task, Crew + +event_manager = Agent( + role="Event Manager", + goal="Manage and update calendar events efficiently", + backstory="An experienced event manager who handles event logistics and updates.", + apps=['google_calendar'] +) + +# Task to manage event updates +event_management = Task( + description=""" + 1. List all events for this week + 2. Update any events that need location changes to include video conference links + 3. Check availability for upcoming meetings + """, + agent=event_manager, + expected_output="Weekly events updated with proper locations and availability checked" +) + +crew = Crew( + agents=[event_manager], + tasks=[event_management] +) + +crew.kickoff() +``` + +### التوفر وإدارة التقويم + +```python +from crewai import Agent, Task, Crew + +availability_coordinator = Agent( + role="Availability Coordinator", + goal="Coordinate availability and manage calendars for scheduling", + backstory="An AI assistant that specializes in availability management and calendar coordination.", + apps=['google_calendar'] +) + +# Task to coordinate availability +availability_task = Task( + description=""" + 1. Get the list of available calendars + 2. Check availability for all calendars next Friday afternoon + 3. Create a team meeting for the first available 2-hour slot + 4. Include Google Meet link and send invitations + """, + agent=availability_coordinator, + expected_output="Team meeting scheduled based on availability with all team members invited" +) + +crew = Crew( + agents=[availability_coordinator], + tasks=[availability_task] +) + +crew.kickoff() +``` + +### سير عمل الجدولة الآلية + +```python +from crewai import Agent, Task, Crew + +scheduling_automator = Agent( + role="Scheduling Automator", + goal="Automate scheduling workflows and calendar management", + backstory="An AI assistant that automates complex scheduling scenarios and calendar workflows.", + apps=['google_calendar'] +) + +# Complex scheduling automation task +automation_task = Task( + description=""" + 1. List all upcoming events for the next two weeks + 2. Identify any scheduling conflicts or back-to-back meetings + 3. Suggest optimal meeting times by checking availability + 4. Create buffer time between meetings where needed + 5. Update event descriptions with agenda items and meeting links + """, + agent=scheduling_automator, + expected_output="Calendar optimized with resolved conflicts, buffer times, and updated meeting details" +) + +crew = Crew( + agents=[scheduling_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات اللازمة للوصول إلى التقويم +- تحقق من أن اتصال OAuth يتضمن جميع النطاقات المطلوبة لـ Google Calendar API +- تحقق مما إذا كانت إعدادات مشاركة التقويم تسمح بمستوى الوصول المطلوب + +**مشاكل إنشاء الأحداث** + +- تحقق من صحة صيغ الوقت (صيغة RFC3339) +- تأكد من صحة صيغة عناوين البريد الإلكتروني للحضور +- تحقق من وجود التقويم المستهدف وإمكانية الوصول إليه +- تحقق من صحة تحديد المناطق الزمنية + +**التوفر وتعارضات الوقت** + +- استخدم صيغة RFC3339 المناسبة لنطاقات الوقت عند التحقق من التوفر +- تأكد من اتساق المناطق الزمنية عبر جميع العمليات +- تحقق من صحة معرّفات التقاويم عند التحقق من تقاويم متعددة + +**تحديث الأحداث وحذفها** + +- تحقق من صحة معرّفات الأحداث ووجودها +- تأكد من أن لديك صلاحيات التحرير للأحداث +- تحقق من أن ملكية التقويم تسمح بالتعديلات + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Calendar + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/google_contacts.mdx b/docs/v1.15.1/ar/enterprise/integrations/google_contacts.mdx new file mode 100644 index 000000000..d3627ec83 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/google_contacts.mdx @@ -0,0 +1,493 @@ +--- +title: تكامل Google Contacts +description: "إدارة جهات الاتصال والدليل مع تكامل Google Contacts لـ CrewAI." +icon: "address-book" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة جهات الاتصال ومعلومات الدليل عبر Google Contacts. يمكنك الوصول إلى جهات الاتصال الشخصية، والبحث في أشخاص الدليل، وإنشاء معلومات الاتصال وتحديثها، وإدارة مجموعات جهات الاتصال باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Contacts، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Contacts +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Contacts + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Contacts** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى جهات الاتصال والدليل +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** استرجاع جهات اتصال المستخدم من Google Contacts. + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد جهات الاتصال المراد إرجاعها (الحد الأقصى 1000). الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز الصفحة المراد استرجاعها. + - `personFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'names,emailAddresses,phoneNumbers'). الافتراضي: names,emailAddresses,phoneNumbers + - `requestSyncToken` (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false + - `sortOrder` (string, اختياري): ترتيب الفرز للاتصالات. الخيارات: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING + + + + + **الوصف:** البحث عن جهات اتصال باستخدام سلسلة استعلام. + + **المعاملات:** + - `query` (string, مطلوب): سلسلة استعلام البحث + - `readMask` (string, مطلوب): الحقول المراد قراءتها (مثال: 'names,emailAddresses,phoneNumbers') + - `pageSize` (integer, اختياري): عدد النتائج المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 30 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `sources` (array, اختياري): المصادر المراد البحث فيها. الخيارات: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. الافتراضي: READ_SOURCE_TYPE_CONTACT + + + + + **الوصف:** عرض قائمة الأشخاص في دليل المستخدم المصادق عليه. + + **المعاملات:** + - `sources` (array, مطلوب): مصادر الدليل المراد البحث فيها. الخيارات: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. الافتراضي: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE + - `pageSize` (integer, اختياري): عدد الأشخاص المراد إرجاعهم. الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `readMask` (string, اختياري): الحقول المراد قراءتها (مثال: 'names,emailAddresses') + - `requestSyncToken` (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false + - `mergeSources` (array, اختياري): بيانات إضافية لدمجها في استجابات أشخاص الدليل. الخيارات: CONTACT + + + + + **الوصف:** البحث عن أشخاص في الدليل. + + **المعاملات:** + - `query` (string, مطلوب): استعلام البحث + - `sources` (string, مطلوب): مصادر الدليل (استخدم 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE') + - `pageSize` (integer, اختياري): عدد النتائج المراد إرجاعها + - `readMask` (string, اختياري): الحقول المراد قراءتها + + + + + **الوصف:** عرض جهات الاتصال الأخرى (غير الموجودة في جهات الاتصال الشخصية). + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `readMask` (string, اختياري): الحقول المراد قراءتها + - `requestSyncToken` (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false + + + + + **الوصف:** البحث في جهات الاتصال الأخرى. + + **المعاملات:** + - `query` (string, مطلوب): استعلام البحث + - `readMask` (string, مطلوب): الحقول المراد قراءتها (مثال: 'names,emailAddresses') + - `pageSize` (integer, اختياري): عدد النتائج + + + + + **الوصف:** الحصول على معلومات الاتصال لشخص واحد بواسطة اسم المورد. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد للشخص المراد الحصول عليه (مثال: 'people/c123456789') + - `personFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'names,emailAddresses,phoneNumbers'). الافتراضي: names,emailAddresses,phoneNumbers + + + + + **الوصف:** إنشاء جهة اتصال جديدة في دفتر عناوين المستخدم. + + **المعاملات:** + - `names` (array, اختياري): أسماء الشخص + ```json + [ + { + "givenName": "John", + "familyName": "Doe", + "displayName": "John Doe" + } + ] + ``` + - `emailAddresses` (array, اختياري): عناوين البريد الإلكتروني + ```json + [ + { + "value": "john.doe@example.com", + "type": "work" + } + ] + ``` + - `phoneNumbers` (array, اختياري): أرقام الهاتف + ```json + [ + { + "value": "+1234567890", + "type": "mobile" + } + ] + ``` + - `addresses` (array, اختياري): العناوين البريدية + ```json + [ + { + "formattedValue": "123 Main St, City, State 12345", + "type": "home" + } + ] + ``` + - `organizations` (array, اختياري): المؤسسات/الشركات + ```json + [ + { + "name": "Company Name", + "title": "Job Title", + "type": "work" + } + ] + ``` + + + + + **الوصف:** تحديث معلومات جهة اتصال موجودة. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد للشخص المراد تحديثه (مثال: 'people/c123456789') + - `updatePersonFields` (string, مطلوب): الحقول المراد تحديثها (مثال: 'names,emailAddresses,phoneNumbers') + - `names` (array, اختياري): أسماء الشخص + - `emailAddresses` (array, اختياري): عناوين البريد الإلكتروني + - `phoneNumbers` (array, اختياري): أرقام الهاتف + + + + + **الوصف:** حذف جهة اتصال من دفتر عناوين المستخدم. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد للشخص المراد حذفه (مثال: 'people/c123456789') + + + + + **الوصف:** الحصول على معلومات عن عدة أشخاص في طلب واحد. + + **المعاملات:** + - `resourceNames` (array, مطلوب): أسماء موارد الأشخاص المراد الحصول عليهم. الحد الأقصى: 200 عنصر + - `personFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'names,emailAddresses,phoneNumbers'). الافتراضي: names,emailAddresses,phoneNumbers + + + + + **الوصف:** عرض مجموعات جهات اتصال المستخدم (التصنيفات). + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد مجموعات جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `groupFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'name,memberCount,clientData'). الافتراضي: name,memberCount + + + + + **الوصف:** الحصول على مجموعة جهات اتصال محددة بواسطة اسم المورد. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: 'contactGroups/myContactGroup') + - `maxMembers` (integer, اختياري): الحد الأقصى لعدد الأعضاء المراد تضمينهم. الحد الأدنى: 0، الحد الأقصى: 20000 + - `groupFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'name,memberCount,clientData'). الافتراضي: name,memberCount + + + + + **الوصف:** إنشاء مجموعة جهات اتصال جديدة (تصنيف). + + **المعاملات:** + - `name` (string, مطلوب): اسم مجموعة جهات الاتصال + - `clientData` (array, اختياري): بيانات خاصة بالعميل + ```json + [ + { + "key": "data_key", + "value": "data_value" + } + ] + ``` + + + + + **الوصف:** تحديث معلومات مجموعة جهات اتصال. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: 'contactGroups/myContactGroup') + - `name` (string, مطلوب): اسم مجموعة جهات الاتصال + - `clientData` (array, اختياري): بيانات خاصة بالعميل + ```json + [ + { + "key": "data_key", + "value": "data_value" + } + ] + ``` + + + + + **الوصف:** حذف مجموعة جهات اتصال. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد لمجموعة جهات الاتصال المراد حذفها (مثال: 'contactGroups/myContactGroup') + - `deleteContacts` (boolean, اختياري): ما إذا كان يجب حذف جهات الاتصال في المجموعة أيضاً. الافتراضي: false + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Contacts + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Contacts capabilities +contacts_agent = Agent( + role="Contact Manager", + goal="Manage contacts and directory information efficiently", + backstory="An AI assistant specialized in contact management and directory operations.", + apps=['google_contacts'] # All Google Contacts actions will be available +) + +# Task to retrieve and organize contacts +contact_management_task = Task( + description="Retrieve all contacts and organize them by company affiliation", + agent=contacts_agent, + expected_output="Contacts retrieved and organized by company with summary report" +) + +# Run the task +crew = Crew( + agents=[contacts_agent], + tasks=[contact_management_task] +) + +crew.kickoff() +``` + +### البحث في الدليل وإدارته + +```python +from crewai import Agent, Task, Crew + +directory_manager = Agent( + role="Directory Manager", + goal="Search and manage directory people and contacts", + backstory="An AI assistant that specializes in directory management and people search.", + apps=[ + 'google_contacts/search_directory_people', + 'google_contacts/list_directory_people', + 'google_contacts/search_contacts' + ] +) + +# Task to search and manage directory +directory_task = Task( + description="Search for team members in the company directory and create a team contact list", + agent=directory_manager, + expected_output="Team directory compiled with contact information" +) + +crew = Crew( + agents=[directory_manager], + tasks=[directory_task] +) + +crew.kickoff() +``` + +### إنشاء جهات الاتصال وتحديثاتها + +```python +from crewai import Agent, Task, Crew + +contact_curator = Agent( + role="Contact Curator", + goal="Create and update contact information systematically", + backstory="An AI assistant that maintains accurate and up-to-date contact information.", + apps=['google_contacts'] +) + +# Task to create and update contacts +curation_task = Task( + description=""" + 1. Search for existing contacts related to new business partners + 2. Create new contacts for partners not in the system + 3. Update existing contact information with latest details + 4. Organize contacts into appropriate groups + """, + agent=contact_curator, + expected_output="Contact database updated with new partners and organized groups" +) + +crew = Crew( + agents=[contact_curator], + tasks=[curation_task] +) + +crew.kickoff() +``` + +### إدارة مجموعات جهات الاتصال + +```python +from crewai import Agent, Task, Crew + +group_organizer = Agent( + role="Contact Group Organizer", + goal="Organize contacts into meaningful groups and categories", + backstory="An AI assistant that specializes in contact organization and group management.", + apps=['google_contacts'] +) + +# Task to organize contact groups +organization_task = Task( + description=""" + 1. List all existing contact groups + 2. Analyze contact distribution across groups + 3. Create new groups for better organization + 4. Move contacts to appropriate groups based on their information + """, + agent=group_organizer, + expected_output="Contacts organized into logical groups with improved structure" +) + +crew = Crew( + agents=[group_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### إدارة جهات الاتصال الشاملة + +```python +from crewai import Agent, Task, Crew + +contact_specialist = Agent( + role="Contact Management Specialist", + goal="Provide comprehensive contact management across all sources", + backstory="An AI assistant that handles all aspects of contact management including personal, directory, and other contacts.", + apps=['google_contacts'] +) + +# Complex contact management task +comprehensive_task = Task( + description=""" + 1. Retrieve contacts from all sources (personal, directory, other) + 2. Search for duplicate contacts and merge information + 3. Update outdated contact information + 4. Create missing contacts for important stakeholders + 5. Organize contacts into meaningful groups + 6. Generate a comprehensive contact report + """, + agent=contact_specialist, + expected_output="Complete contact management performed with unified contact database and detailed report" +) + +crew = Crew( + agents=[contact_specialist], + tasks=[comprehensive_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات المناسبة للوصول إلى جهات الاتصال +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Google Contacts API +- تحقق من منح صلاحيات الوصول للدليل لجهات اتصال المؤسسة + +**مشاكل صيغة اسم المورد** + +- تأكد من أن أسماء الموارد تتبع الصيغة الصحيحة (مثال: 'people/c123456789' لجهات الاتصال) +- تحقق من أن أسماء موارد مجموعات جهات الاتصال تستخدم الصيغة 'contactGroups/groupId' +- تأكد من وجود أسماء الموارد وإمكانية الوصول إليها + +**مشاكل البحث والاستعلام** + +- تأكد من صحة صيغة استعلامات البحث وعدم كونها فارغة +- استخدم حقول readMask المناسبة للبيانات التي تحتاجها +- تحقق من صحة تحديد مصادر البحث (جهات اتصال مقابل ملفات تعريف) + +**إنشاء جهات الاتصال وتحديثاتها** + +- تأكد من توفير الحقول المطلوبة عند إنشاء جهات الاتصال +- تحقق من صحة صيغة عناوين البريد الإلكتروني وأرقام الهاتف +- تأكد من أن معامل updatePersonFields يتضمن جميع الحقول التي يتم تحديثها + +**مشاكل الوصول إلى الدليل** + +- تأكد من أن لديك الصلاحيات المناسبة للوصول إلى دليل المؤسسة +- تحقق من صحة تحديد مصادر الدليل +- تأكد من أن مؤسستك تسمح بالوصول عبر API إلى معلومات الدليل + +**الترقيم والحدود** + +- انتبه لحدود حجم الصفحة (تختلف حسب نقطة النهاية) +- استخدم pageToken للترقيم عبر مجموعات النتائج الكبيرة +- احترم حدود معدل API وطبّق تأخيرات مناسبة + +**مجموعات جهات الاتصال والتنظيم** + +- تأكد من أن أسماء مجموعات جهات الاتصال فريدة عند إنشاء مجموعات جديدة +- تحقق من وجود جهات الاتصال قبل إضافتها إلى المجموعات +- تأكد من أن لديك صلاحيات تعديل مجموعات جهات الاتصال + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Contacts + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/google_docs.mdx b/docs/v1.15.1/ar/enterprise/integrations/google_docs.mdx new file mode 100644 index 000000000..ea1cc4caf --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/google_docs.mdx @@ -0,0 +1,550 @@ +--- +title: تكامل Google Docs +description: "إنشاء المستندات وتحريرها مع تكامل Google Docs لـ CrewAI." +icon: "file-lines" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وتحرير وإدارة مستندات Google Docs مع معالجة النصوص والتنسيق. أتمت إنشاء المستندات، وأدرج النصوص واستبدلها، وأدر نطاقات المحتوى، وبسّط سير عمل المستندات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Docs، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Docs +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Docs + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Docs** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى المستندات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مستند Google جديد. + + **المعاملات:** + - `title` (string, اختياري): عنوان المستند الجديد. + + + + + **الوصف:** الحصول على محتويات وبيانات وصفية لمستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد استرجاعه. + - `includeTabsContent` (boolean, اختياري): ما إذا كان يجب تضمين محتوى علامات التبويب. الافتراضي هو `false`. + - `suggestionsViewMode` (string, اختياري): وضع عرض الاقتراحات المراد تطبيقه. القيم: `DEFAULT_FOR_CURRENT_ACCESS`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. الافتراضي: `DEFAULT_FOR_CURRENT_ACCESS`. + + + + + **الوصف:** تطبيق تحديث واحد أو أكثر على مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `requests` (array, مطلوب): قائمة بالتحديثات المراد تطبيقها على المستند. + - `writeControl` (object, اختياري): يوفر التحكم في كيفية تنفيذ طلبات الكتابة. + + + + + **الوصف:** إدراج نص في مستند Google في موقع محدد. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `text` (string, مطلوب): النص المراد إدراجه. + - `index` (integer, اختياري): الفهرس القائم على الصفر حيث يتم إدراج النص. الافتراضي هو `1`. + + + + + **الوصف:** استبدال جميع نُسخ النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `containsText` (string, مطلوب): النص المراد البحث عنه واستبداله. + - `replaceText` (string, مطلوب): النص البديل. + - `matchCase` (boolean, اختياري): ما إذا كان البحث يجب أن يراعي حالة الأحرف. الافتراضي هو `false`. + + + + + **الوصف:** حذف المحتوى من نطاق محدد في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `startIndex` (integer, مطلوب): فهرس بداية النطاق المراد حذفه. + - `endIndex` (integer, مطلوب): فهرس نهاية النطاق المراد حذفه. + + + + + **الوصف:** إدراج فاصل صفحة في موقع محدد في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `index` (integer, اختياري): الفهرس القائم على الصفر حيث يتم إدراج فاصل الصفحة. الافتراضي هو `1`. + + + + + **الوصف:** إنشاء نطاق مسمّى في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `name` (string, مطلوب): اسم النطاق المسمّى. + - `startIndex` (integer, مطلوب): فهرس بداية النطاق. + - `endIndex` (integer, مطلوب): فهرس نهاية النطاق. + + + + + **الوصف:** إنشاء مستند Google جديد مع محتوى في إجراء واحد. + + **المعاملات:** + - `title` (string, مطلوب): عنوان المستند الجديد. + - `content` (string, اختياري): المحتوى النصي المراد إدراجه في المستند. استخدم `\n` لفقرات جديدة. + + + + + **الوصف:** إلحاق نص بنهاية مستند Google. يُدرج تلقائياً في نهاية المستند دون الحاجة لتحديد فهرس. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `text` (string, مطلوب): النص المراد إلحاقه بنهاية المستند. استخدم `\n` لفقرات جديدة. + + + + + **الوصف:** جعل النص غامقاً أو إزالة التنسيق الغامق في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `bold` (boolean, مطلوب): عيّن `true` لجعله غامقاً، `false` لإزالة الغامق. + + + + + **الوصف:** جعل النص مائلاً أو إزالة التنسيق المائل في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `italic` (boolean, مطلوب): عيّن `true` لجعله مائلاً، `false` لإزالة المائل. + + + + + **الوصف:** إضافة أو إزالة تنسيق التسطير من النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `underline` (boolean, مطلوب): عيّن `true` للتسطير، `false` لإزالة التسطير. + + + + + **الوصف:** إضافة أو إزالة تنسيق يتوسطه خط من النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `strikethrough` (boolean, مطلوب): عيّن `true` لإضافة يتوسطه خط، `false` للإزالة. + + + + + **الوصف:** تغيير حجم خط النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `fontSize` (number, مطلوب): حجم الخط بالنقاط. الأحجام الشائعة: 10, 11, 12, 14, 16, 18, 24, 36. + + + + + **الوصف:** تغيير لون النص باستخدام قيم RGB (مقياس 0-1) في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `red` (number, مطلوب): مكوّن الأحمر (0-1). مثال: `1` للأحمر الكامل. + - `green` (number, مطلوب): مكوّن الأخضر (0-1). مثال: `0.5` لنصف الأخضر. + - `blue` (number, مطلوب): مكوّن الأزرق (0-1). مثال: `0` لعدم وجود أزرق. + + + + + **الوصف:** تحويل نص موجود إلى رابط قابل للنقر في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تحويله إلى رابط. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تحويله إلى رابط (حصري). + - `url` (string, مطلوب): عنوان URL الذي يجب أن يشير إليه الرابط. مثال: `"https://example.com"`. + + + + + **الوصف:** تطبيق نمط عنوان أو فقرة على نطاق نصي في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرة (الفقرات) المراد تنسيقها. + - `endIndex` (integer, مطلوب): موضع نهاية الفقرة (الفقرات) المراد تنسيقها. + - `style` (string, مطلوب): النمط المراد تطبيقه. القيم: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`. + + + + + **الوصف:** تعيين محاذاة النص للفقرات في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرة (الفقرات) المراد محاذاتها. + - `endIndex` (integer, مطلوب): موضع نهاية الفقرة (الفقرات) المراد محاذاتها. + - `alignment` (string, مطلوب): محاذاة النص. القيم: `START` (يسار), `CENTER`, `END` (يمين), `JUSTIFIED`. + + + + + **الوصف:** تعيين تباعد الأسطر للفقرات في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرة (الفقرات). + - `endIndex` (integer, مطلوب): موضع نهاية الفقرة (الفقرات). + - `lineSpacing` (number, مطلوب): تباعد الأسطر كنسبة مئوية. `100` = مفرد، `115` = 1.15x، `150` = 1.5x، `200` = مزدوج. + + + + + **الوصف:** تحويل الفقرات إلى قائمة نقطية أو مرقمة في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرات المراد تحويلها إلى قائمة. + - `endIndex` (integer, مطلوب): موضع نهاية الفقرات المراد تحويلها إلى قائمة. + - `bulletPreset` (string, مطلوب): نمط النقاط/الترقيم. القيم: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`. + + + + + **الوصف:** إزالة النقاط أو الترقيم من الفقرات في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية فقرات القائمة. + - `endIndex` (integer, مطلوب): موضع نهاية فقرات القائمة. + + + + + **الوصف:** إدراج جدول مع محتوى في مستند Google في إجراء واحد. قدم المحتوى كمصفوفة ثنائية الأبعاد. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `rows` (integer, مطلوب): عدد الصفوف في الجدول. + - `columns` (integer, مطلوب): عدد الأعمدة في الجدول. + - `index` (integer, اختياري): الموضع لإدراج الجدول. إذا لم يُحدد، يُدرج الجدول في نهاية المستند. + - `content` (array, مطلوب): محتوى الجدول كمصفوفة ثنائية الأبعاد. كل مصفوفة داخلية هي صف. مثال: `[["Year", "Revenue"], ["2023", "$43B"], ["2024", "$45B"]]`. + + + + + **الوصف:** إدراج صف جديد فوق أو أسفل خلية مرجعية في جدول موجود. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف (قائم على الصفر) للخلية المرجعية. + - `columnIndex` (integer, اختياري): فهرس العمود (قائم على الصفر) للخلية المرجعية. الافتراضي هو `0`. + - `insertBelow` (boolean, اختياري): إذا `true`، يُدرج أسفل الصف المرجعي. إذا `false`، يُدرج فوقه. الافتراضي هو `true`. + + + + + **الوصف:** إدراج عمود جديد يساراً أو يميناً لخلية مرجعية في جدول موجود. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, اختياري): فهرس الصف (قائم على الصفر) للخلية المرجعية. الافتراضي هو `0`. + - `columnIndex` (integer, مطلوب): فهرس العمود (قائم على الصفر) للخلية المرجعية. + - `insertRight` (boolean, اختياري): إذا `true`، يُدرج إلى اليمين. إذا `false`، يُدرج إلى اليسار. الافتراضي هو `true`. + + + + + **الوصف:** حذف صف من جدول موجود في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف (قائم على الصفر) المراد حذفه. + - `columnIndex` (integer, اختياري): فهرس العمود (قائم على الصفر) لأي خلية في الصف. الافتراضي هو `0`. + + + + + **الوصف:** حذف عمود من جدول موجود في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, اختياري): فهرس الصف (قائم على الصفر) لأي خلية في العمود. الافتراضي هو `0`. + - `columnIndex` (integer, مطلوب): فهرس العمود (قائم على الصفر) المراد حذفه. + + + + + **الوصف:** دمج نطاق من خلايا الجدول في خلية واحدة. يتم الاحتفاظ بمحتوى جميع الخلايا. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف البادئ (قائم على الصفر) للدمج. + - `columnIndex` (integer, مطلوب): فهرس العمود البادئ (قائم على الصفر) للدمج. + - `rowSpan` (integer, مطلوب): عدد الصفوف المراد دمجها. + - `columnSpan` (integer, مطلوب): عدد الأعمدة المراد دمجها. + + + + + **الوصف:** إلغاء دمج خلايا جدول مدمجة سابقاً وإعادتها إلى خلايا فردية. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف (قائم على الصفر) للخلية المدمجة. + - `columnIndex` (integer, مطلوب): فهرس العمود (قائم على الصفر) للخلية المدمجة. + - `rowSpan` (integer, مطلوب): عدد الصفوف التي تمتد عليها الخلية المدمجة. + - `columnSpan` (integer, مطلوب): عدد الأعمدة التي تمتد عليها الخلية المدمجة. + + + + + **الوصف:** إدراج صورة من عنوان URL عام في مستند Google. يجب أن تكون الصورة متاحة للعموم، وأقل من 50 ميجابايت، وبصيغة PNG/JPEG/GIF. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `uri` (string, مطلوب): عنوان URL العام للصورة. يجب أن يكون متاحاً بدون مصادقة. + - `index` (integer, اختياري): الموضع لإدراج الصورة. إذا لم يُحدد، تُدرج الصورة في نهاية المستند. الافتراضي هو `1`. + + + + + **الوصف:** إدراج فاصل قسم لإنشاء أقسام مستند بتنسيقات مختلفة. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `index` (integer, مطلوب): الموضع لإدراج فاصل القسم. + - `sectionType` (string, مطلوب): نوع فاصل القسم. القيم: `CONTINUOUS` (يبقى في نفس الصفحة), `NEXT_PAGE` (يبدأ صفحة جديدة). + + + + + **الوصف:** إنشاء ترويسة للمستند. يُرجع headerId يمكن استخدامه مع insert_text لإضافة محتوى الترويسة. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `type` (string, اختياري): نوع الترويسة. القيم: `DEFAULT`. الافتراضي هو `DEFAULT`. + + + + + **الوصف:** إنشاء تذييل للمستند. يُرجع footerId يمكن استخدامه مع insert_text لإضافة محتوى التذييل. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `type` (string, اختياري): نوع التذييل. القيم: `DEFAULT`. الافتراضي هو `DEFAULT`. + + + + + **الوصف:** حذف ترويسة من المستند. استخدم get_document للعثور على headerId. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `headerId` (string, مطلوب): معرّف الترويسة المراد حذفها. + + + + + **الوصف:** حذف تذييل من المستند. استخدم get_document للعثور على footerId. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `footerId` (string, مطلوب): معرّف التذييل المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Docs + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Docs capabilities +docs_agent = Agent( + role="Document Creator", + goal="Create and manage Google Docs documents efficiently", + backstory="An AI assistant specialized in Google Docs document creation and editing.", + apps=['google_docs'] # All Google Docs actions will be available +) + +# Task to create a new document +create_doc_task = Task( + description="Create a new Google Document titled 'Project Status Report'", + agent=docs_agent, + expected_output="New Google Document 'Project Status Report' created successfully" +) + +# Run the task +crew = Crew( + agents=[docs_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +### تحرير النصوص وإدارة المحتوى + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on text editing +text_editor = Agent( + role="Document Editor", + goal="Edit and update content in Google Docs documents", + backstory="An AI assistant skilled in precise text editing and content management.", + apps=['google_docs/insert_text', 'google_docs/replace_text', 'google_docs/delete_content_range'] +) + +# Task to edit document content +edit_content_task = Task( + description="In document 'your_document_id', insert the text 'Executive Summary: ' at the beginning, then replace all instances of 'TODO' with 'COMPLETED'.", + agent=text_editor, + expected_output="Document updated with new text inserted and TODO items replaced." +) + +crew = Crew( + agents=[text_editor], + tasks=[edit_content_task] +) + +crew.kickoff() +``` + +### عمليات المستندات المتقدمة + +```python +from crewai import Agent, Task, Crew + +# Create an agent for advanced document operations +document_formatter = Agent( + role="Document Formatter", + goal="Apply advanced formatting and structure to Google Docs", + backstory="An AI assistant that handles complex document formatting and organization.", + apps=['google_docs/batch_update', 'google_docs/insert_page_break', 'google_docs/create_named_range'] +) + +# Task to format document +format_doc_task = Task( + description="In document 'your_document_id', insert a page break at position 100, create a named range called 'Introduction' for characters 1-50, and apply batch formatting updates.", + agent=document_formatter, + expected_output="Document formatted with page break, named range, and styling applied." +) + +crew = Crew( + agents=[document_formatter], + tasks=[format_doc_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات اللازمة للوصول إلى Google Docs. +- تحقق من أن اتصال OAuth يتضمن جميع النطاقات المطلوبة (`https://www.googleapis.com/auth/documents`). + +**مشاكل معرّف المستند** + +- تحقق جيداً من صحة معرّفات المستندات. +- تأكد من وجود المستند وإمكانية الوصول إليه من حسابك. +- يمكن العثور على معرّفات المستندات في عنوان URL لـ Google Docs. + +**عمليات إدراج النص والنطاقات** + +- عند استخدام `insert_text` أو `delete_content_range`، تأكد من صحة مواضع الفهرس. +- تذكر أن Google Docs يستخدم فهرسة قائمة على الصفر. +- يجب أن يحتوي المستند على محتوى في مواضع الفهرس المحددة. + +**تنسيق طلبات التحديث الدفعي** + +- عند استخدام `batch_update`، تأكد من صحة تنسيق مصفوفة `requests` وفقاً لتوثيق Google Docs API. +- تتطلب التحديثات المعقدة هياكل JSON محددة لكل نوع طلب. + +**عمليات استبدال النص** + +- لـ `replace_text`، تأكد من مطابقة معامل `containsText` تماماً للنص المراد استبداله. +- استخدم معامل `matchCase` للتحكم في حساسية حالة الأحرف. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Docs أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/google_drive.mdx b/docs/v1.15.1/ar/enterprise/integrations/google_drive.mdx new file mode 100644 index 000000000..18b8a3371 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/google_drive.mdx @@ -0,0 +1,238 @@ +--- +title: تكامل Google Drive +description: "تخزين الملفات وإدارتها مع تكامل Google Drive لـ CrewAI." +icon: "google" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة الملفات والمجلدات عبر Google Drive. ارفع الملفات وحمّلها ونظّمها وشاركها، وأنشئ المجلدات، وبسّط سير عمل إدارة المستندات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Drive، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Drive +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Drive + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Drive** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة الملفات والمجلدات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على ملف بواسطة المعرّف من Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد استرجاعه. + + + + + **الوصف:** عرض قائمة الملفات في Google Drive. + + **المعاملات:** + - `q` (string, اختياري): سلسلة استعلام لتصفية الملفات (مثال: "name contains 'report'"). + - `page_size` (integer, اختياري): الحد الأقصى لعدد الملفات المُرجعة (الافتراضي: 100، الحد الأقصى: 1000). + - `page_token` (string, اختياري): رمز لاسترجاع الصفحة التالية من النتائج. + - `order_by` (string, اختياري): ترتيب الفرز (مثال: "name", "createdTime desc", "modifiedTime"). + - `spaces` (string, اختياري): قائمة مفصولة بفواصل للمساحات المراد الاستعلام عنها (drive, appDataFolder, photos). + + + + + **الوصف:** رفع ملف إلى Google Drive. + + **المعاملات:** + - `name` (string, مطلوب): اسم الملف المراد إنشاؤه. + - `content` (string, مطلوب): محتوى الملف المراد رفعه. + - `mime_type` (string, اختياري): نوع MIME للملف (مثال: "text/plain", "application/pdf"). + - `parent_folder_id` (string, اختياري): معرّف المجلد الأصلي حيث يجب إنشاء الملف. + - `description` (string, اختياري): وصف الملف. + + + + + **الوصف:** تحميل ملف من Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد تحميله. + - `mime_type` (string, اختياري): نوع MIME للتصدير (مطلوب لمستندات Google Workspace). + + + + + **الوصف:** إنشاء مجلد جديد في Google Drive. + + **المعاملات:** + - `name` (string, مطلوب): اسم المجلد المراد إنشاؤه. + - `parent_folder_id` (string, اختياري): معرّف المجلد الأصلي حيث يجب إنشاء المجلد الجديد. + - `description` (string, اختياري): وصف المجلد. + + + + + **الوصف:** حذف ملف من Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد حذفه. + + + + + **الوصف:** مشاركة ملف في Google Drive مع مستخدمين محددين أو جعله عاماً. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد مشاركته. + - `role` (string, مطلوب): الدور الممنوح بهذا الإذن (reader, writer, commenter, owner). + - `type` (string, مطلوب): نوع المستفيد (user, group, domain, anyone). + - `email_address` (string, اختياري): عنوان البريد الإلكتروني للمستخدم أو المجموعة المراد المشاركة معهم (مطلوب لأنواع user/group). + - `domain` (string, اختياري): النطاق المراد المشاركة معه (مطلوب لنوع domain). + - `send_notification_email` (boolean, اختياري): ما إذا كان يجب إرسال بريد إلكتروني إشعاري (الافتراضي: true). + - `email_message` (string, اختياري): رسالة نصية مخصصة لتضمينها في البريد الإلكتروني الإشعاري. + + + + + **الوصف:** تحديث ملف موجود في Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد تحديثه. + - `name` (string, اختياري): الاسم الجديد للملف. + - `content` (string, اختياري): المحتوى الجديد للملف. + - `mime_type` (string, اختياري): نوع MIME الجديد للملف. + - `description` (string, اختياري): الوصف الجديد للملف. + - `add_parents` (string, اختياري): قائمة مفصولة بفواصل لمعرّفات المجلدات الأصلية المراد إضافتها. + - `remove_parents` (string, اختياري): قائمة مفصولة بفواصل لمعرّفات المجلدات الأصلية المراد إزالتها. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Drive + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Drive capabilities +drive_agent = Agent( + role="File Manager", + goal="Manage files and folders in Google Drive efficiently", + backstory="An AI assistant specialized in document and file management.", + apps=['google_drive'] # All Google Drive actions will be available +) + +# Task to organize files +organize_files_task = Task( + description="List all files in the root directory and organize them into appropriate folders", + agent=drive_agent, + expected_output="Summary of files organized with folder structure" +) + +# Run the task +crew = Crew( + agents=[drive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Google Drive المحددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Google Drive actions only +file_manager_agent = Agent( + role="Document Manager", + goal="Upload and manage documents efficiently", + backstory="An AI assistant that focuses on document upload and organization.", + apps=[ + 'google_drive/upload_file', + 'google_drive/create_folder', + 'google_drive/share_file' + ] # Specific Google Drive actions +) + +# Task to upload and share documents +document_task = Task( + description="Upload the quarterly report and share it with the finance team", + agent=file_manager_agent, + expected_output="Document uploaded and sharing permissions configured" +) + +crew = Crew( + agents=[file_manager_agent], + tasks=[document_task] +) + +crew.kickoff() +``` + +### إدارة الملفات المتقدمة + +```python +from crewai import Agent, Task, Crew + +file_organizer = Agent( + role="File Organizer", + goal="Maintain organized file structure and manage permissions", + backstory="An experienced file manager who ensures proper organization and access control.", + apps=['google_drive'] +) + +# Complex task involving multiple Google Drive operations +organization_task = Task( + description=""" + 1. List all files in the shared folder + 2. Create folders for different document types (Reports, Presentations, Spreadsheets) + 3. Move files to appropriate folders based on their type + 4. Set appropriate sharing permissions for each folder + 5. Create a summary document of the organization changes + """, + agent=file_organizer, + expected_output="Files organized into categorized folders with proper permissions and summary report" +) + +crew = Crew( + agents=[file_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ar/enterprise/integrations/google_sheets.mdx b/docs/v1.15.1/ar/enterprise/integrations/google_sheets.mdx new file mode 100644 index 000000000..5651ef83d --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/google_sheets.mdx @@ -0,0 +1,254 @@ +--- +title: تكامل Google Sheets +description: "مزامنة بيانات جداول البيانات مع تكامل Google Sheets لـ CrewAI." +icon: "google" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة بيانات جداول البيانات عبر Google Sheets. اقرأ الصفوف، وأنشئ إدخالات جديدة، وحدّث البيانات الموجودة، وبسّط سير عمل إدارة البيانات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. مثالي لتتبع البيانات وإعداد التقارير وإدارة البيانات التعاونية. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Sheets، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Sheets +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) +- جداول بيانات بترويسات أعمدة مناسبة لعمليات البيانات + +## إعداد تكامل Google Sheets + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Sheets** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى جداول البيانات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** استرجاع خصائص وبيانات جدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد استرجاعه. + - `ranges` (array, اختياري): النطاقات المراد استرجاعها من جدول البيانات. + - `includeGridData` (boolean, اختياري): true إذا كان يجب إرجاع بيانات الشبكة. الافتراضي: false + - `fields` (string, اختياري): الحقول المراد تضمينها في الاستجابة. + + + + + **الوصف:** إرجاع نطاق من القيم من جدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد استرجاع البيانات منه. + - `range` (string, مطلوب): ترميز A1 أو R1C1 للنطاق المراد استرجاع القيم منه. + - `valueRenderOption` (string, اختياري): كيفية تمثيل القيم في الإخراج. الخيارات: FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA. الافتراضي: FORMATTED_VALUE + - `dateTimeRenderOption` (string, اختياري): كيفية تمثيل التواريخ والأوقات في الإخراج. الخيارات: SERIAL_NUMBER, FORMATTED_STRING. الافتراضي: SERIAL_NUMBER + - `majorDimension` (string, اختياري): البُعد الرئيسي للنتائج. الخيارات: ROWS, COLUMNS. الافتراضي: ROWS + + + + + **الوصف:** تعيين القيم في نطاق من جدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد تحديثه. + - `range` (string, مطلوب): ترميز A1 للنطاق المراد تحديثه. + - `values` (array, مطلوب): البيانات المراد كتابتها. كل مصفوفة تمثل صفاً. + ```json + [ + ["Value1", "Value2", "Value3"], + ["Value4", "Value5", "Value6"] + ] + ``` + - `valueInputOption` (string, اختياري): كيفية تفسير بيانات الإدخال. الخيارات: RAW, USER_ENTERED. الافتراضي: USER_ENTERED + + + + + **الوصف:** إلحاق قيم بجدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد تحديثه. + - `range` (string, مطلوب): ترميز A1 لنطاق البحث عن جدول بيانات منطقي. + - `values` (array, مطلوب): البيانات المراد إلحاقها. كل مصفوفة تمثل صفاً. + ```json + [ + ["Value1", "Value2", "Value3"], + ["Value4", "Value5", "Value6"] + ] + ``` + - `valueInputOption` (string, اختياري): كيفية تفسير بيانات الإدخال. الخيارات: RAW, USER_ENTERED. الافتراضي: USER_ENTERED + - `insertDataOption` (string, اختياري): كيفية إدراج بيانات الإدخال. الخيارات: OVERWRITE, INSERT_ROWS. الافتراضي: INSERT_ROWS + + + + + **الوصف:** إنشاء جدول بيانات جديد. + + **المعاملات:** + - `title` (string, مطلوب): عنوان جدول البيانات الجديد. + - `sheets` (array, اختياري): الأوراق التي تشكل جزءاً من جدول البيانات. + ```json + [ + { + "properties": { + "title": "Sheet1" + } + } + ] + ``` + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Sheets + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Sheets capabilities +sheets_agent = Agent( + role="Data Manager", + goal="Manage spreadsheet data and track information efficiently", + backstory="An AI assistant specialized in data management and spreadsheet operations.", + apps=['google_sheets'] +) + +# Task to add new data to a spreadsheet +data_entry_task = Task( + description="Add a new customer record to the customer database spreadsheet with name, email, and signup date", + agent=sheets_agent, + expected_output="New customer record added successfully to the spreadsheet" +) + +# Run the task +crew = Crew( + agents=[sheets_agent], + tasks=[data_entry_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Google Sheets المحددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Google Sheets actions only +data_collector = Agent( + role="Data Collector", + goal="Collect and organize data in spreadsheets", + backstory="An AI assistant that focuses on data collection and organization.", + apps=[ + 'google_sheets/get_values', + 'google_sheets/update_values' + ] +) + +# Task to collect and organize data +data_collection = Task( + description="Retrieve current inventory data and add new product entries to the inventory spreadsheet", + agent=data_collector, + expected_output="Inventory data retrieved and new products added successfully" +) + +crew = Crew( + agents=[data_collector], + tasks=[data_collection] +) + +crew.kickoff() +``` + +### تحليل البيانات وإعداد التقارير + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Data Analyst", + goal="Analyze spreadsheet data and generate insights", + backstory="An experienced data analyst who extracts insights from spreadsheet data.", + apps=['google_sheets'] +) + +# Task to analyze data and create reports +analysis_task = Task( + description=""" + 1. Retrieve all sales data from the current month's spreadsheet + 2. Analyze the data for trends and patterns + 3. Create a summary report in a new row with key metrics + """, + agent=data_analyst, + expected_output="Sales data analyzed and summary report created with key insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Google الخاص بك لديه صلاحية التحرير على جداول البيانات المستهدفة +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Google Sheets API +- تأكد من مشاركة جداول البيانات مع الحساب المصادق عليه + +**مشاكل هيكل جدول البيانات** + +- تأكد من أن أوراق العمل تحتوي على ترويسات أعمدة مناسبة قبل إنشاء الصفوف أو تحديثها +- تحقق من صحة ترميز النطاق (صيغة A1) للخلايا المستهدفة +- تأكد من وجود معرّف جدول البيانات المحدد وإمكانية الوصول إليه + +**مشاكل نوع البيانات والصيغة** + +- تأكد من تطابق قيم البيانات مع الصيغة المتوقعة لكل عمود +- استخدم صيغ التاريخ المناسبة لأعمدة التاريخ (يُنصح بصيغة ISO) +- تحقق من صحة تنسيق القيم الرقمية لأعمدة الأرقام + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Sheets + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/google_slides.mdx b/docs/v1.15.1/ar/enterprise/integrations/google_slides.mdx new file mode 100644 index 000000000..77029f244 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/google_slides.mdx @@ -0,0 +1,382 @@ +--- +title: تكامل Google Slides +description: "إنشاء العروض التقديمية وإدارتها مع تكامل Google Slides لـ CrewAI." +icon: "chart-bar" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وتحرير وإدارة عروض Google Slides التقديمية. أنشئ العروض التقديمية، وحدّث المحتوى، واستورد البيانات من Google Sheets، وأدر الصفحات والصور المصغرة، وبسّط سير عمل العروض التقديمية باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Slides، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Slides +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Slides + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Slides** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى العروض التقديمية وجداول البيانات وDrive +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء عرض تقديمي فارغ بدون محتوى. + + **المعاملات:** + - `title` (string, مطلوب): عنوان العرض التقديمي. + + + + + **الوصف:** الحصول على بيانات وصفية خفيفة حول العرض التقديمي (العنوان، عدد الشرائح، معرّفات الشرائح). + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد استرجاعه. + + + + + **الوصف:** استخراج جميع المحتوى النصي من العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + + + + + **الوصف:** استرجاع عرض تقديمي بواسطة المعرّف. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد استرجاعه. + - `fields` (string, اختياري): الحقول المراد تضمينها في الاستجابة. + + + + + **الوصف:** تطبيق التحديثات أو إضافة المحتوى أو إزالته من العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد تحديثه. + - `requests` (array, مطلوب): قائمة بالتحديثات المراد تطبيقها. + ```json + [ + { + "insertText": { + "objectId": "slide_id", + "text": "Your text content here" + } + } + ] + ``` + - `writeControl` (object, اختياري): يوفر التحكم في كيفية تنفيذ طلبات الكتابة. + + + + + **الوصف:** استخراج المحتوى النصي من شريحة واحدة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `pageObjectId` (string, مطلوب): معرّف الشريحة/الصفحة. + + + + + **الوصف:** استرجاع صفحة محددة بواسطة معرّفها. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `pageObjectId` (string, مطلوب): معرّف الصفحة المراد استرجاعها. + + + + + **الوصف:** إنشاء صورة مصغرة للصفحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `pageObjectId` (string, مطلوب): معرّف الصفحة لإنشاء الصورة المصغرة. + + + + + **الوصف:** إضافة شريحة فارغة إضافية للعرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `insertionIndex` (integer, اختياري): مكان إدراج الشريحة (قائم على الصفر). إذا حُذف، تُضاف في النهاية. + + + + + **الوصف:** إنشاء شريحة بتخطيط محدد مسبقاً يحتوي على مناطق عناصر نائبة للعنوان والمحتوى وغيرها. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `layout` (string, مطلوب): نوع التخطيط. أحد: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. + - `insertionIndex` (integer, اختياري): مكان الإدراج (قائم على الصفر). حُذف للإضافة في النهاية. + + + + + **الوصف:** إنشاء مربع نص على شريحة مع محتوى. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة مربع النص إليها. + - `text` (string, مطلوب): المحتوى النصي لمربع النص. + - `x` (integer, اختياري): موضع X بوحدة EMU (914400 = 1 بوصة). الافتراضي: 914400. + - `y` (integer, اختياري): موضع Y بوحدة EMU. الافتراضي: 914400. + - `width` (integer, اختياري): العرض بوحدة EMU. الافتراضي: 7315200. + - `height` (integer, اختياري): الارتفاع بوحدة EMU. الافتراضي: 914400. + + + + + **الوصف:** إزالة شريحة من العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة المراد حذفها. + + + + + **الوصف:** إنشاء نسخة من شريحة موجودة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة المراد تكرارها. + + + + + **الوصف:** إعادة ترتيب الشرائح بنقلها إلى موضع جديد. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideIds` (array of strings, مطلوب): مصفوفة من معرّفات الشرائح المراد نقلها. + - `insertionIndex` (integer, مطلوب): الموضع المستهدف (قائم على الصفر). + + + + + **الوصف:** تضمين فيديو YouTube على شريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الفيديو إليها. + - `videoId` (string, مطلوب): معرّف فيديو YouTube (القيمة بعد v= في عنوان URL). + + + + + **الوصف:** تضمين فيديو من Google Drive على شريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الفيديو إليها. + - `fileId` (string, مطلوب): معرّف ملف Google Drive للفيديو. + + + + + **الوصف:** تعيين صورة خلفية لشريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لتعيين الخلفية لها. + - `imageUrl` (string, مطلوب): عنوان URL المتاح للعموم للصورة المراد استخدامها كخلفية. + + + + + **الوصف:** إنشاء جدول فارغ على شريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الجدول إليها. + - `rows` (integer, مطلوب): عدد الصفوف في الجدول. + - `columns` (integer, مطلوب): عدد الأعمدة في الجدول. + + + + + **الوصف:** إنشاء جدول مع محتوى في إجراء واحد. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الجدول إليها. + - `rows` (integer, مطلوب): عدد الصفوف في الجدول. + - `columns` (integer, مطلوب): عدد الأعمدة في الجدول. + - `content` (array, مطلوب): محتوى الجدول كمصفوفة ثنائية الأبعاد. مثال: [["Year", "Revenue"], ["2023", "$10M"]]. + + + + + **الوصف:** استيراد البيانات من Google Sheet إلى العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `sheetId` (string, مطلوب): معرّف Google Sheet المراد الاستيراد منه. + - `dataRange` (string, مطلوب): نطاق البيانات المراد استيرادها من الورقة. + + + + + **الوصف:** رفع ملف إلى Google Drive المرتبط بالعرض التقديمي. + + **المعاملات:** + - `file` (string, مطلوب): بيانات الملف المراد رفعها. + - `presentationId` (string, مطلوب): معرّف العرض التقديمي لربط الملف المرفوع. + + + + + **الوصف:** ربط ملف في Google Drive بالعرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `fileId` (string, مطلوب): معرّف الملف المراد ربطه. + + + + + **الوصف:** عرض قائمة بجميع العروض التقديمية المتاحة للمستخدم. + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد العروض التقديمية المراد إرجاعها لكل صفحة. + - `pageToken` (string, اختياري): رمز للترقيم. + + + + + **الوصف:** حذف عرض تقديمي بواسطة المعرّف. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Slides + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Slides capabilities +slides_agent = Agent( + role="Presentation Manager", + goal="Create and manage presentations efficiently", + backstory="An AI assistant specialized in presentation creation and content management.", + apps=['google_slides'] # All Google Slides actions will be available +) + +# Task to create a presentation +create_presentation_task = Task( + description="Create a new presentation for the quarterly business review with key slides", + agent=slides_agent, + expected_output="Quarterly business review presentation created with structured content" +) + +# Run the task +crew = Crew( + agents=[slides_agent], + tasks=[create_presentation_task] +) + +crew.kickoff() +``` + +### إدارة محتوى العروض التقديمية + +```python +from crewai import Agent, Task, Crew + +content_manager = Agent( + role="Content Manager", + goal="Manage presentation content and updates", + backstory="An AI assistant that focuses on content creation and presentation updates.", + apps=[ + 'google_slides/create_blank_presentation', + 'google_slides/batch_update_presentation', + 'google_slides/get_presentation' + ] +) + +# Task to create and update presentations +content_task = Task( + description="Create a new presentation and add content slides with charts and text", + agent=content_manager, + expected_output="Presentation created with updated content and visual elements" +) + +crew = Crew( + agents=[content_manager], + tasks=[content_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات المناسبة لـ Google Slides +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة للعروض التقديمية وجداول البيانات وDrive + +**مشاكل معرّف العرض التقديمي** + +- تحقق من صحة معرّفات العروض التقديمية ووجودها +- تأكد من أن لديك صلاحيات الوصول للعروض التقديمية التي تحاول تعديلها + +**مشاكل تحديث المحتوى** + +- تأكد من صحة تنسيق طلبات التحديث الدفعي وفقاً لمواصفات Google Slides API +- تحقق من وجود معرّفات الكائنات للشرائح والعناصر في العرض التقديمي + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Slides + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/hubspot.mdx b/docs/v1.15.1/ar/enterprise/integrations/hubspot.mdx new file mode 100644 index 000000000..b328cebb7 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/hubspot.mdx @@ -0,0 +1,360 @@ +--- +title: تكامل HubSpot +description: "إدارة الشركات وجهات الاتصال في HubSpot مع CrewAI." +icon: "briefcase" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة الشركات وجهات الاتصال داخل HubSpot. أنشئ سجلات جديدة وبسّط عمليات CRM باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل HubSpot، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال. +- حساب HubSpot بالصلاحيات المناسبة. +- ربط حساب HubSpot الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors). + +## إعداد تكامل HubSpot + +### 1. ربط حساب HubSpot الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors). +2. ابحث عن **HubSpot** في قسم تكاملات المصادقة. +3. انقر على **Connect** وأكمل عملية OAuth. +4. امنح الصلاحيات اللازمة لإدارة الشركات وجهات الاتصال. +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء سجل شركة جديد في HubSpot. + + **المعاملات:** + - `name` (string, مطلوب): اسم الشركة. + - `domain` (string, اختياري): اسم نطاق الشركة. + - `industry` (string, اختياري): القطاع. + - `phone` (string, اختياري): رقم الهاتف. + - `hubspot_owner_id` (string, اختياري): معرّف مالك الشركة. + - `type` (string, اختياري): نوع الشركة. القيم المتاحة: `PROSPECT`, `PARTNER`, `RESELLER`, `VENDOR`, `OTHER`. + - `city` (string, اختياري): المدينة. + - `state` (string, اختياري): الولاية/المنطقة. + - `zip` (string, اختياري): الرمز البريدي. + - `numberofemployees` (number, اختياري): عدد الموظفين. + - `annualrevenue` (number, اختياري): الإيرادات السنوية. + - `description` (string, اختياري): الوصف. + - `website` (string, اختياري): عنوان URL للموقع الإلكتروني. + + + + + **الوصف:** إنشاء سجل جهة اتصال جديد في HubSpot. + + **المعاملات:** + - `email` (string, مطلوب): عنوان البريد الإلكتروني لجهة الاتصال. + - `firstname` (string, اختياري): الاسم الأول. + - `lastname` (string, اختياري): اسم العائلة. + - `phone` (string, اختياري): رقم الهاتف. + - `hubspot_owner_id` (string, اختياري): مالك جهة الاتصال. + - `lifecyclestage` (string, اختياري): مرحلة دورة الحياة. القيم المتاحة: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`. + - `company` (string, اختياري): اسم الشركة. + - `jobtitle` (string, اختياري): المسمى الوظيفي. + + + + + **الوصف:** إنشاء سجل صفقة جديد في HubSpot. + + **المعاملات:** + - `dealname` (string, مطلوب): اسم الصفقة. + - `amount` (number, اختياري): قيمة الصفقة. + - `dealstage` (string, اختياري): مرحلة مسار الصفقة. + - `pipeline` (string, اختياري): مسار المبيعات الذي تنتمي إليه الصفقة. + - `closedate` (string, اختياري): التاريخ المتوقع لإغلاق الصفقة. + - `hubspot_owner_id` (string, اختياري): مالك الصفقة. + - `dealtype` (string, اختياري): نوع الصفقة. القيم المتاحة: `newbusiness`, `existingbusiness`. + - `description` (string, اختياري): وصف الصفقة. + - `hs_priority` (string, اختياري): أولوية الصفقة. القيم المتاحة: `low`, `medium`, `high`. + + + + + **الوصف:** إنشاء تفاعل جديد (مثل ملاحظة، بريد إلكتروني، مكالمة، اجتماع، مهمة) في HubSpot. + + **المعاملات:** + - `engagementType` (string, مطلوب): نوع التفاعل. القيم المتاحة: `NOTE`, `EMAIL`, `CALL`, `MEETING`, `TASK`. + - `hubspot_owner_id` (string, اختياري): المستخدم المعيّن للنشاط. + - `hs_timestamp` (string, اختياري): تاريخ ووقت النشاط. + - `hs_note_body` (string, اختياري): نص الملاحظة. (يُستخدم لـ `NOTE`) + - `hs_task_subject` (string, اختياري): عنوان المهمة. (يُستخدم لـ `TASK`) + - `hs_meeting_title` (string, اختياري): عنوان الاجتماع. (يُستخدم لـ `MEETING`) + + + + + **الوصف:** تحديث سجل شركة موجود في HubSpot. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الشركة المراد تحديثها. + - `name` (string, اختياري): اسم الشركة. + - `domain` (string, اختياري): اسم نطاق الشركة. + - `industry` (string, اختياري): القطاع. + - `phone` (string, اختياري): رقم الهاتف. + - `description` (string, اختياري): الوصف. + + + + + **الوصف:** تحديث سجل جهة اتصال موجود في HubSpot. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف جهة الاتصال المراد تحديثها. + - `firstname` (string, اختياري): الاسم الأول. + - `lastname` (string, اختياري): اسم العائلة. + - `email` (string, اختياري): عنوان البريد الإلكتروني. + - `phone` (string, اختياري): رقم الهاتف. + - `company` (string, اختياري): اسم الشركة. + - `jobtitle` (string, اختياري): المسمى الوظيفي. + + + + + **الوصف:** تحديث سجل صفقة موجود في HubSpot. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الصفقة المراد تحديثها. + - `dealname` (string, اختياري): اسم الصفقة. + - `amount` (number, اختياري): قيمة الصفقة. + - `dealstage` (string, اختياري): مرحلة مسار الصفقة. + - `closedate` (string, اختياري): تاريخ الإغلاق المتوقع. + + + + + **الوصف:** الحصول على قائمة بسجلات الشركات من HubSpot. + + **المعاملات:** + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** الحصول على قائمة بسجلات جهات الاتصال من HubSpot. + + **المعاملات:** + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** الحصول على قائمة بسجلات الصفقات من HubSpot. + + **المعاملات:** + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** الحصول على سجل شركة واحد بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الشركة المراد استرجاعها. + + + + + **الوصف:** الحصول على سجل جهة اتصال واحد بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف جهة الاتصال المراد استرجاعها. + + + + + **الوصف:** الحصول على سجل صفقة واحد بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الصفقة المراد استرجاعها. + + + + + **الوصف:** البحث عن سجلات الشركات في HubSpot باستخدام صيغة فلتر. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل (OR لمجموعات AND). + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** البحث عن سجلات جهات الاتصال في HubSpot باستخدام صيغة فلتر. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل (OR لمجموعات AND). + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** البحث عن سجلات الصفقات في HubSpot باستخدام صيغة فلتر. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل (OR لمجموعات AND). + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** حذف سجل شركة بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الشركة المراد حذفها. + + + + + **الوصف:** حذف سجل جهة اتصال بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف جهة الاتصال المراد حذفها. + + + + + **الوصف:** حذف سجل صفقة بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الصفقة المراد حذفها. + + + + + **الوصف:** الحصول على المخطط المتوقع لنوع كائن وعملية معينة. + + **المعاملات:** + - `recordType` (string, مطلوب): معرّف نوع الكائن (مثال: 'companies'). + - `operation` (string, مطلوب): نوع العملية (مثال: 'CREATE_RECORD'). + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ HubSpot + +```python +from crewai import Agent, Task, Crew + +# Create an agent with HubSpot capabilities +hubspot_agent = Agent( + role="CRM Manager", + goal="Manage company and contact records in HubSpot", + backstory="An AI assistant specialized in CRM management.", + apps=['hubspot'] # All HubSpot actions will be available +) + +# Task to create a new company +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" +) + +# Run the task +crew = Crew( + agents=[hubspot_agent], + tasks=[create_company_task] +) + +crew.kickoff() +``` + +### تصفية أدوات HubSpot المحددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific HubSpot actions only +contact_creator = Agent( + role="Contact Creator", + goal="Create new contacts in HubSpot", + backstory="An AI assistant that focuses on creating new contact entries in the CRM.", + apps=['hubspot/create_contact'] # Only contact creation action +) + +# Task to create a contact +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() +``` + +### إدارة جهات الاتصال + +```python +from crewai import Agent, Task, Crew + +# Create agent with HubSpot contact management capabilities +crm_manager = Agent( + role="CRM Manager", + goal="Manage and organize HubSpot contacts efficiently.", + backstory="An experienced CRM manager who maintains an organized contact database.", + apps=['hubspot'] # All HubSpot actions including contact management +) + +# Task to manage contacts +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() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل HubSpot أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/jira.mdx b/docs/v1.15.1/ar/enterprise/integrations/jira.mdx new file mode 100644 index 000000000..87fdea8a1 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/jira.mdx @@ -0,0 +1,248 @@ +--- +title: تكامل Jira +description: "تتبع المشكلات وإدارة المشاريع مع تكامل Jira لـ CrewAI." +icon: "bug" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المشكلات والمشاريع وسير العمل عبر Jira. أنشئ المشكلات وحدّثها، وتتبع تقدم المشاريع، وأدر التعيينات، وبسّط إدارة مشاريعك باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Jira، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Jira بصلاحيات المشروع المناسبة +- ربط حساب Jira الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Jira + +### 1. ربط حساب Jira الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Jira** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المشكلات والمشاريع +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مشكلة في Jira. + + **المعاملات:** + - `summary` (string, مطلوب): الملخص - ملخص موجز من سطر واحد للمشكلة. (مثال: "The printer stopped working"). + - `project` (string, اختياري): المشروع - المشروع الذي تنتمي إليه المشكلة. + - `issueType` (string, اختياري): نوع المشكلة - الافتراضي هو Task. + - `jiraIssueStatus` (string, اختياري): الحالة - الافتراضي هو أول حالة في المشروع. + - `assignee` (string, اختياري): المكلّف - الافتراضي هو المستخدم المصادق عليه. + - `description` (string, اختياري): الوصف - وصف تفصيلي للمشكلة. + - `additionalFields` (string, اختياري): حقول إضافية - حدد أي حقول أخرى بصيغة JSON. + + + + + **الوصف:** تحديث مشكلة في Jira. + + **المعاملات:** + - `issueKey` (string, مطلوب): مفتاح المشكلة (مثال: "TEST-1234"). + - `summary` (string, اختياري): الملخص. + - `issueType` (string, اختياري): نوع المشكلة. + - `jiraIssueStatus` (string, اختياري): الحالة. + - `assignee` (string, اختياري): المكلّف. + - `description` (string, اختياري): الوصف. + - `additionalFields` (string, اختياري): حقول إضافية بصيغة JSON. + + + + + **الوصف:** الحصول على مشكلة بواسطة المفتاح في Jira. + + **المعاملات:** + - `issueKey` (string, مطلوب): مفتاح المشكلة (مثال: "TEST-1234"). + + + + + **الوصف:** البحث عن المشكلات في Jira باستخدام الفلاتر. + + **المعاملات:** + - `jqlQuery` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل. + - `limit` (string, اختياري): حدود النتائج - الافتراضي 10. + + + + + **الوصف:** البحث عن المشكلات بواسطة JQL في Jira. + + **المعاملات:** + - `jqlQuery` (string, مطلوب): استعلام JQL (مثال: "project = PROJECT"). + - `paginationParameters` (object, اختياري): معاملات الترقيم. + + + + + **الوصف:** الحصول على المخطط المتوقع لنوع مشكلة. + + **المعاملات:** + - `issueTypeId` (string, مطلوب): معرّف نوع المشكلة. + - `projectKey` (string, مطلوب): مفتاح المشروع. + - `operation` (string, مطلوب): نوع العملية، مثال CREATE_ISSUE أو UPDATE_ISSUE. + + + + + **الوصف:** الحصول على المشاريع في Jira. + + **المعاملات:** + - `paginationParameters` (object, اختياري): معاملات الترقيم. + + + + + **الوصف:** الحصول على أنواع المشكلات بواسطة المشروع في Jira. + + **المعاملات:** + - `project` (string, مطلوب): مفتاح المشروع. + + + + + **الوصف:** الحصول على جميع أنواع المشكلات في Jira. + + **المعاملات:** لا توجد معاملات مطلوبة. + + + + + **الوصف:** الحصول على حالات المشكلات لمشروع معين. + + **المعاملات:** + - `project` (string, مطلوب): مفتاح المشروع. + + + + + **الوصف:** الحصول على المكلّفين لمشروع معين. + + **المعاملات:** + - `project` (string, مطلوب): مفتاح المشروع. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Jira + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Jira capabilities +jira_agent = Agent( + role="Issue Manager", + goal="Manage Jira issues and track project progress efficiently", + backstory="An AI assistant specialized in issue tracking and project management.", + apps=['jira'] # All Jira actions will be available +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a bug report for the login functionality with high priority and assign it to the development team", + agent=jira_agent, + expected_output="Bug report created successfully with issue key" +) + +# Run the task +crew = Crew( + agents=[jira_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### تحليل المشاريع وإعداد التقارير + +```python +from crewai import Agent, Task, Crew + +project_analyst = Agent( + role="Project Analyst", + goal="Analyze project data and generate insights from Jira", + backstory="An experienced project analyst who extracts insights from project management data.", + apps=['jira'] +) + +# Task to analyze project status +analysis_task = Task( + description=""" + 1. Get all projects and their issue types + 2. Search for all open issues across projects + 3. Analyze issue distribution by status and assignee + 4. Create a summary report issue with findings + """, + agent=project_analyst, + expected_output="Project analysis completed with summary report created" +) + +crew = Crew( + agents=[project_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Jira الخاص بك لديه الصلاحيات اللازمة للمشاريع المستهدفة +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Jira API + +**مفاتيح المشاريع أو المشكلات غير الصالحة** + +- تحقق جيداً من مفاتيح المشاريع ومفاتيح المشكلات للتأكد من صحة الصيغة (مثال: "PROJ-123") +- تأكد من وجود المشاريع وإمكانية الوصول إليها من حسابك + +**مشاكل استعلام JQL** + +- اختبر استعلامات JQL في بحث مشكلات Jira قبل استخدامها في استدعاءات API +- تأكد من صحة إملاء أسماء الحقول في JQL ووجودها في مثيل Jira الخاص بك + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Jira أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/linear.mdx b/docs/v1.15.1/ar/enterprise/integrations/linear.mdx new file mode 100644 index 000000000..c2eb34f84 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/linear.mdx @@ -0,0 +1,261 @@ +--- +title: تكامل Linear +description: "إدارة المشاريع البرمجية وتتبع الأخطاء مع تكامل Linear لـ CrewAI." +icon: "list-check" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المشكلات والمشاريع وسير عمل التطوير عبر Linear. أنشئ المشكلات وحدّثها، وأدر جداول المشاريع الزمنية، ونظّم الفرق، وبسّط عملية تطوير البرمجيات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Linear، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Linear بصلاحيات مساحة العمل المناسبة +- ربط حساب Linear الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Linear + +### 1. ربط حساب Linear الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Linear** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المشكلات والمشاريع +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مشكلة جديدة في Linear. + + **المعاملات:** + - `teamId` (string, مطلوب): معرّف الفريق للمشكلة الجديدة. + - `title` (string, مطلوب): العنوان. + - `description` (string, اختياري): الوصف. + - `statusId` (string, اختياري): الحالة. + - `priority` (string, اختياري): الأولوية كعدد صحيح. + - `dueDate` (string, اختياري): تاريخ الاستحقاق بصيغة ISO 8601. + - `cycleId` (string, اختياري): معرّف الدورة المرتبطة. + - `additionalFields` (object, اختياري): حقول إضافية. + + + + + **الوصف:** تحديث مشكلة في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد تحديثها. + - `title` (string, اختياري): العنوان. + - `description` (string, اختياري): الوصف. + - `statusId` (string, اختياري): الحالة. + - `priority` (string, اختياري): الأولوية. + - `dueDate` (string, اختياري): تاريخ الاستحقاق. + + + + + **الوصف:** الحصول على مشكلة بواسطة المعرّف في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد جلبها. + + + + + **الوصف:** البحث عن المشكلات في Linear. + + **المعاملات:** + - `queryTerm` (string, مطلوب): مصطلح البحث. + - `issueFilterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل. + + + + + **الوصف:** حذف مشكلة في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد حذفها. + + + + + **الوصف:** أرشفة مشكلة في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد أرشفتها. + + + + + **الوصف:** إنشاء مشكلة فرعية في Linear. + + **المعاملات:** + - `parentId` (string, مطلوب): معرّف المشكلة الأصلية. + - `teamId` (string, مطلوب): معرّف الفريق. + - `title` (string, مطلوب): العنوان. + - `description` (string, اختياري): الوصف. + + + + + **الوصف:** إنشاء مشروع جديد في Linear. + + **المعاملات:** + - `teamIds` (object, مطلوب): معرّف (معرّفات) الفريق المرتبطة بالمشروع. + - `projectName` (string, مطلوب): اسم المشروع. + - `description` (string, اختياري): وصف المشروع. + + + + + **الوصف:** تحديث مشروع في Linear. + + **المعاملات:** + - `projectId` (string, مطلوب): معرّف المشروع المراد تحديثه. + - `projectName` (string, اختياري): اسم المشروع. + - `description` (string, اختياري): وصف المشروع. + + + + + **الوصف:** الحصول على مشروع بواسطة المعرّف في Linear. + + **المعاملات:** + - `projectId` (string, مطلوب): معرّف المشروع المراد جلبه. + + + + + **الوصف:** حذف مشروع في Linear. + + **المعاملات:** + - `projectId` (string, مطلوب): معرّف المشروع المراد حذفه. + + + + + **الوصف:** البحث عن الفرق في Linear. + + **المعاملات:** + - `teamFilterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Linear + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Linear capabilities +linear_agent = Agent( + role="Development Manager", + goal="Manage Linear issues and track development progress efficiently", + backstory="An AI assistant specialized in software development project management.", + apps=['linear'] # All Linear actions will be available +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a high-priority bug report for the authentication system and assign it to the backend team", + agent=linear_agent, + expected_output="Bug report created successfully with issue ID" +) + +# Run the task +crew = Crew( + agents=[linear_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### إدارة المشاريع والفرق + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate projects and teams in Linear efficiently", + backstory="An experienced project coordinator who manages development cycles and team workflows.", + apps=['linear'] +) + +# Task to coordinate project setup +project_coordination = Task( + description=""" + 1. Search for engineering teams in Linear + 2. Create a new project for Q2 feature development + 3. Associate the project with relevant teams + 4. Create initial project milestones as issues + """, + agent=project_coordinator, + expected_output="Q2 project created with teams assigned and initial milestones established" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Linear الخاص بك لديه الصلاحيات اللازمة لمساحة العمل المستهدفة +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Linear API + +**معرّفات ومراجع غير صالحة** + +- تحقق جيداً من معرّفات الفرق والمشكلات والمشاريع للتأكد من صحة صيغة UUID +- تأكد من وجود الكيانات المشار إليها وإمكانية الوصول إليها + +**مشاكل التاريخ والوقت** + +- استخدم صيغة ISO 8601 لتواريخ الاستحقاق والطوابع الزمنية +- تأكد من معالجة المناطق الزمنية بشكل صحيح + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Linear أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/microsoft_excel.mdx b/docs/v1.15.1/ar/enterprise/integrations/microsoft_excel.mdx new file mode 100644 index 000000000..0ce049695 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/microsoft_excel.mdx @@ -0,0 +1,269 @@ +--- +title: تكامل Microsoft Excel +description: "إدارة المصنفات والبيانات مع تكامل Microsoft Excel لـ CrewAI." +icon: "table" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وإدارة مصنفات Excel وأوراق العمل والجداول والرسوم البيانية في OneDrive أو SharePoint. تعامل مع نطاقات البيانات، وأنشئ المرئيات، وأدر الجداول، وبسّط سير عمل جداول البيانات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Excel، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft 365 مع إمكانية الوصول إلى Excel وOneDrive/SharePoint +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Excel + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Excel** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى الملفات ومصنفات Excel +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مصنف Excel جديد في OneDrive أو SharePoint. + + **المعاملات:** + - `file_path` (string, مطلوب): المسار حيث يتم إنشاء المصنف (مثال: 'MyWorkbook.xlsx') + - `worksheets` (array, اختياري): أوراق العمل الأولية المراد إنشاؤها + + + + + **الوصف:** الحصول على جميع مصنفات Excel من OneDrive أو SharePoint. + + **المعاملات:** + - `select` (string, اختياري): اختيار خصائص محددة للإرجاع + - `filter` (string, اختياري): تصفية النتائج باستخدام صيغة OData + - `top` (integer, اختياري): عدد العناصر المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 999 + + + + + **الوصف:** الحصول على جميع أوراق العمل في مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + + + + + **الوصف:** إنشاء ورقة عمل جديدة في مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `name` (string, مطلوب): اسم ورقة العمل الجديدة + + + + + **الوصف:** الحصول على البيانات من نطاق محدد في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `range` (string, مطلوب): عنوان النطاق (مثال: 'A1:C10') + + + + + **الوصف:** تحديث البيانات في نطاق محدد في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `range` (string, مطلوب): عنوان النطاق (مثال: 'A1:C10') + - `values` (array, مطلوب): مصفوفة ثنائية الأبعاد من القيم لتعيينها في النطاق + + + + + **الوصف:** إنشاء جدول في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `range` (string, مطلوب): النطاق للجدول (مثال: 'A1:D10') + - `has_headers` (boolean, اختياري): ما إذا كان الصف الأول يحتوي على ترويسات. الافتراضي: true + + + + + **الوصف:** إضافة صف جديد إلى جدول Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `table_name` (string, مطلوب): اسم الجدول + - `values` (array, مطلوب): مصفوفة من القيم للصف الجديد + + + + + **الوصف:** إنشاء رسم بياني في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `chart_type` (string, مطلوب): نوع الرسم البياني (مثال: 'ColumnClustered', 'Line', 'Pie') + - `source_data` (string, مطلوب): نطاق البيانات للرسم البياني (مثال: 'A1:B10') + - `series_by` (string, اختياري): كيفية تفسير البيانات ('Auto', 'Columns', 'Rows'). الافتراضي: Auto + + + + + **الوصف:** الحصول على قيمة خلية واحدة في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `row` (integer, مطلوب): رقم الصف (قائم على الصفر) + - `column` (integer, مطلوب): رقم العمود (قائم على الصفر) + + + + + **الوصف:** الحصول على النطاق المستخدم لورقة عمل Excel (يحتوي على جميع البيانات). + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + + + + + **الوصف:** الحصول على جميع الجداول في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + + + + + **الوصف:** الحصول على البيانات من جدول محدد في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `table_name` (string, مطلوب): اسم الجدول + + + + + **الوصف:** حذف ورقة عمل من مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل المراد حذفها + + + + + **الوصف:** حذف جدول من ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `table_name` (string, مطلوب): اسم الجدول المراد حذفه + + + + + **الوصف:** الحصول على جميع النطاقات المسماة في مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Excel + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Excel capabilities +excel_agent = Agent( + role="Excel Data Manager", + goal="Manage Excel workbooks and data efficiently", + backstory="An AI assistant specialized in Excel data management and analysis.", + apps=['microsoft_excel'] # All Excel actions will be available +) + +# Task to create and populate a workbook +data_management_task = Task( + description="Create a new sales report workbook with data analysis and charts", + agent=excel_agent, + expected_output="Excel workbook created with sales data, analysis, and visualizations" +) + +# Run the task +crew = Crew( + agents=[excel_agent], + tasks=[data_management_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات المناسبة لـ Excel وOneDrive/SharePoint +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة (Files.Read.All, Files.ReadWrite.All) + +**مشاكل النطاق وورقة العمل** + +- تحقق من وجود أسماء أوراق العمل في المصنف المحدد +- تأكد من صحة تنسيق عناوين النطاقات (مثال: 'A1:C10') + +**مشاكل الرسوم البيانية** + +- تحقق من دعم أنواع الرسوم البيانية (ColumnClustered, Line, Pie، إلخ.) +- تأكد من أن نطاقات بيانات المصدر تحتوي على بيانات مناسبة لنوع الرسم البياني + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Excel + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/microsoft_onedrive.mdx b/docs/v1.15.1/ar/enterprise/integrations/microsoft_onedrive.mdx new file mode 100644 index 000000000..7ce92c1c0 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/microsoft_onedrive.mdx @@ -0,0 +1,218 @@ +--- +title: تكامل Microsoft OneDrive +description: "إدارة الملفات والمجلدات مع تكامل Microsoft OneDrive لـ CrewAI." +icon: "cloud" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من رفع وتحميل وإدارة الملفات والمجلدات في Microsoft OneDrive. أتمت عمليات الملفات، ونظّم المحتوى، وأنشئ روابط المشاركة، وبسّط سير عمل التخزين السحابي باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft OneDrive، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى OneDrive +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft OneDrive + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft OneDrive** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى الملفات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** عرض الملفات والمجلدات في OneDrive. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد استرجاعها (الحد الأقصى 1000). الافتراضي: `50`. + - `orderby` (string, اختياري): الترتيب حسب حقل (مثال: "name asc", "lastModifiedDateTime desc"). الافتراضي: "name asc". + - `filter` (string, اختياري): تعبير فلتر OData. + + + + + **الوصف:** الحصول على معلومات حول ملف أو مجلد محدد. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد. + + + + + **الوصف:** تحميل ملف من OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف المراد تحميله. + + + + + **الوصف:** رفع ملف إلى OneDrive. + + **المعاملات:** + - `file_name` (string, مطلوب): اسم الملف المراد رفعه. + - `content` (string, مطلوب): محتوى الملف بترميز Base64. + + + + + **الوصف:** إنشاء مجلد جديد في OneDrive. + + **المعاملات:** + - `folder_name` (string, مطلوب): اسم المجلد المراد إنشاؤه. + + + + + **الوصف:** حذف ملف أو مجلد من OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد حذفه. + + + + + **الوصف:** نسخ ملف أو مجلد في OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد نسخه. + - `parent_id` (string, اختياري): معرّف مجلد الوجهة (اختياري، الافتراضي هو الجذر). + - `new_name` (string, اختياري): الاسم الجديد للعنصر المنسوخ (اختياري). + + + + + **الوصف:** نقل ملف أو مجلد في OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد نقله. + - `parent_id` (string, مطلوب): معرّف مجلد الوجهة. + - `new_name` (string, اختياري): الاسم الجديد للعنصر (اختياري). + + + + + **الوصف:** البحث عن الملفات والمجلدات في OneDrive. + + **المعاملات:** + - `query` (string, مطلوب): سلسلة استعلام البحث. + - `top` (integer, اختياري): عدد النتائج المراد إرجاعها (الحد الأقصى 1000). الافتراضي: `50`. + + + + + **الوصف:** إنشاء رابط مشاركة لملف أو مجلد. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد مشاركته. + - `type` (string, اختياري): نوع رابط المشاركة. القيم: `view`, `edit`, `embed`. الافتراضي: `view`. + - `scope` (string, اختياري): نطاق رابط المشاركة. القيم: `anonymous`, `organization`. الافتراضي: `anonymous`. + + + + + **الوصف:** الحصول على الملفات التي تم الوصول إليها مؤخراً من OneDrive. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد استرجاعها (الحد الأقصى 200). الافتراضي: `25`. + + + + + **الوصف:** الحصول على الملفات والمجلدات المشاركة مع المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد استرجاعها (الحد الأقصى 200). الافتراضي: `50`. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft OneDrive + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft OneDrive capabilities +onedrive_agent = Agent( + role="File Manager", + goal="Manage files and folders in OneDrive efficiently", + backstory="An AI assistant specialized in Microsoft OneDrive file operations and organization.", + apps=['microsoft_onedrive'] # All OneDrive actions will be available +) + +# Task to list files and create a folder +organize_files_task = Task( + description="List all files in my OneDrive root directory and create a new folder called 'Project Documents'.", + agent=onedrive_agent, + expected_output="List of files displayed and new folder 'Project Documents' created." +) + +# Run the task +crew = Crew( + agents=[onedrive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى الملفات (مثال: `Files.Read`, `Files.ReadWrite`). +- تحقق من أن اتصال OAuth يتضمن جميع النطاقات المطلوبة. + +**مشاكل رفع الملفات** + +- تأكد من توفير `file_name` و`content` لعمليات رفع الملفات. +- يجب أن يكون المحتوى بترميز Base64 للملفات الثنائية. + +**عمليات الملفات (النسخ/النقل)** + +- لـ `move_item`، تأكد من توفير كل من `item_id` و`parent_id`. +- تحقق من وجود مجلدات الوجهة وإمكانية الوصول إليها. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft OneDrive + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/microsoft_outlook.mdx b/docs/v1.15.1/ar/enterprise/integrations/microsoft_outlook.mdx new file mode 100644 index 000000000..f1a6cd99e --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/microsoft_outlook.mdx @@ -0,0 +1,227 @@ +--- +title: تكامل Microsoft Outlook +description: "إدارة البريد الإلكتروني والتقويم وجهات الاتصال مع تكامل Microsoft Outlook لـ CrewAI." +icon: "envelope" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من الوصول إلى رسائل Outlook الإلكترونية وأحداث التقويم وجهات الاتصال وإدارتها. أرسل رسائل البريد الإلكتروني، واسترجع الرسائل، وأدر أحداث التقويم، ونظّم جهات الاتصال باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Outlook، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى Outlook +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Outlook + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Outlook** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى البريد والتقويم وجهات الاتصال +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على رسائل البريد الإلكتروني من صندوق بريد المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد الرسائل (الحد الأقصى 1000). الافتراضي: `10`. + - `filter` (string, اختياري): تعبير فلتر OData (مثال: "isRead eq false"). + - `search` (string, اختياري): سلسلة استعلام البحث. + - `orderby` (string, اختياري): الترتيب (مثال: "receivedDateTime desc"). الافتراضي: "receivedDateTime desc". + + + + + **الوصف:** إرسال رسالة بريد إلكتروني. + + **المعاملات:** + - `to_recipients` (array, مطلوب): مصفوفة عناوين المستلمين. + - `subject` (string, مطلوب): موضوع البريد الإلكتروني. + - `body` (string, مطلوب): محتوى البريد الإلكتروني. + - `body_type` (string, اختياري): نوع المحتوى. القيم: `Text`, `HTML`. الافتراضي: `HTML`. + - `importance` (string, اختياري): مستوى الأهمية. القيم: `low`, `normal`, `high`. الافتراضي: `normal`. + - `cc_recipients` (array, اختياري): مصفوفة عناوين النسخة الكربونية. + + + + + **الوصف:** الحصول على أحداث التقويم من تقويم المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد الأحداث (الحد الأقصى 1000). الافتراضي: `10`. + - `filter` (string, اختياري): تعبير فلتر OData. + - `orderby` (string, اختياري): الترتيب. الافتراضي: "start/dateTime asc". + + + + + **الوصف:** إنشاء حدث تقويم جديد. + + **المعاملات:** + - `subject` (string, مطلوب): موضوع/عنوان الحدث. + - `start_datetime` (string, مطلوب): وقت البداية بصيغة ISO 8601. + - `end_datetime` (string, مطلوب): وقت النهاية بصيغة ISO 8601. + - `timezone` (string, اختياري): المنطقة الزمنية. الافتراضي: `UTC`. + - `location` (string, اختياري): موقع الحدث. + - `attendees` (array, اختياري): مصفوفة عناوين الحضور. + + + + + **الوصف:** الحصول على جهات الاتصال من دفتر عناوين المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد جهات الاتصال (الحد الأقصى 1000). الافتراضي: `10`. + - `filter` (string, اختياري): تعبير فلتر OData. + + + + + **الوصف:** إنشاء جهة اتصال جديدة في دفتر عناوين المستخدم. + + **المعاملات:** + - `displayName` (string, مطلوب): اسم العرض لجهة الاتصال. + - `givenName` (string, اختياري): الاسم الأول. + - `surname` (string, اختياري): اسم العائلة. + - `emailAddresses` (array, اختياري): مصفوفة عناوين البريد الإلكتروني. + - `jobTitle` (string, اختياري): المسمى الوظيفي. + - `companyName` (string, اختياري): اسم الشركة. + + + + + **الوصف:** الرد على رسالة بريد إلكتروني. + + **المعاملات:** + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد الرد عليها. + - `comment` (string, مطلوب): محتوى الرد. + + + + + **الوصف:** إعادة توجيه رسالة بريد إلكتروني. + + **المعاملات:** + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد إعادة توجيهها. + - `to_recipients` (array, مطلوب): مصفوفة عناوين المستلمين. + - `comment` (string, اختياري): رسالة اختيارية لتضمينها فوق المحتوى المُعاد توجيهه. + + + + + **الوصف:** حذف رسالة بريد إلكتروني. + + **المعاملات:** + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد حذفها. + + + + + **الوصف:** تحديث حدث تقويم موجود. + + **المعاملات:** + - `event_id` (string, مطلوب): المعرّف الفريد للحدث. + - `subject` (string, اختياري): الموضوع/العنوان الجديد. + - `start_time` (string, اختياري): وقت البداية الجديد بصيغة ISO 8601. + - `location` (string, اختياري): الموقع الجديد. + + + + + **الوصف:** حذف حدث تقويم. + + **المعاملات:** + - `event_id` (string, مطلوب): المعرّف الفريد للحدث المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft Outlook + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Outlook capabilities +outlook_agent = Agent( + role="Email Assistant", + goal="Manage emails, calendar events, and contacts efficiently", + backstory="An AI assistant specialized in Microsoft Outlook operations and communication management.", + apps=['microsoft_outlook'] # All Outlook actions will be available +) + +# Task to send an email +send_email_task = Task( + description="Send an email to 'colleague@example.com' with subject 'Project Update' and body 'Hi, here is the latest project update. Best regards.'", + agent=outlook_agent, + expected_output="Email sent successfully to colleague@example.com" +) + +# Run the task +crew = Crew( + agents=[outlook_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى البريد والتقويم وجهات الاتصال. +- النطاقات المطلوبة تشمل: `Mail.Read`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.ReadWrite`. + +**مشاكل إرسال البريد الإلكتروني** + +- تأكد من توفير `to_recipients` و`subject` و`body` لـ `send_email`. +- تحقق من صحة صيغة عناوين البريد الإلكتروني. + +**إنشاء أحداث التقويم** + +- تأكد من توفير `subject` و`start_datetime` و`end_datetime`. +- استخدم صيغة ISO 8601 المناسبة لحقول التاريخ والوقت. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Outlook + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/microsoft_sharepoint.mdx b/docs/v1.15.1/ar/enterprise/integrations/microsoft_sharepoint.mdx new file mode 100644 index 000000000..56b88708d --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/microsoft_sharepoint.mdx @@ -0,0 +1,270 @@ +--- +title: تكامل Microsoft SharePoint +description: "إدارة المواقع والقوائم والمستندات مع تكامل Microsoft SharePoint لـ CrewAI." +icon: "folder-tree" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من الوصول إلى مواقع SharePoint والقوائم ومكتبات المستندات وإدارتها. استرجع معلومات المواقع، وأدر عناصر القوائم، وارفع الملفات ونظّمها، وبسّط سير عمل SharePoint باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft SharePoint، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft 365 مع إمكانية الوصول إلى SharePoint +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft SharePoint + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft SharePoint** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى مواقع SharePoint ومحتوياتها +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على جميع مواقع SharePoint التي يمكن للمستخدم الوصول إليها. + + **المعاملات:** + - `search` (string, اختياري): استعلام بحث لتصفية المواقع + - `top` (integer, اختياري): عدد العناصر المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 999 + + + + + **الوصف:** الحصول على معلومات حول موقع SharePoint محدد. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + + + + + **الوصف:** عرض جميع مكتبات المستندات (drives) في موقع SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + + + + + **الوصف:** الحصول على جميع القوائم في موقع SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + + + + + **الوصف:** الحصول على عناصر من قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `expand` (string, اختياري): توسيع البيانات المرتبطة (مثال: 'fields') + + + + + **الوصف:** إنشاء عنصر جديد في قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `fields` (object, مطلوب): قيم الحقول للعنصر الجديد + + + + + **الوصف:** تحديث عنصر في قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `item_id` (string, مطلوب): معرّف العنصر المراد تحديثه + - `fields` (object, مطلوب): قيم الحقول المراد تحديثها + + + + + **الوصف:** حذف عنصر من قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `item_id` (string, مطلوب): معرّف العنصر المراد حذفه + + + + + **الوصف:** رفع ملف إلى مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `file_path` (string, مطلوب): المسار حيث يتم رفع الملف + - `content` (string, مطلوب): محتوى الملف المراد رفعه + + + + + **الوصف:** استرجاع الملفات والمجلدات من مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `folder_id` (string, اختياري): معرّف المجلد. الافتراضي: 'root' + - `top` (integer, اختياري): الحد الأقصى لعدد العناصر. الافتراضي: 50 + + + + + **الوصف:** البحث عن الملفات والمجلدات في مكتبة مستندات SharePoint بالكلمات المفتاحية. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `query` (string, مطلوب): كلمات البحث المفتاحية + + + + + **الوصف:** حذف ملف أو مجلد من مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف أو المجلد المراد حذفه + + + + + **الوصف:** إنشاء مجلد جديد في مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `folder_name` (string, مطلوب): اسم المجلد الجديد + - `parent_id` (string, اختياري): معرّف المجلد الأصلي. الافتراضي: 'root' + + + + + **الوصف:** تحميل محتوى ملف خام من مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف المراد تحميله + + + + + **الوصف:** نسخ ملف أو مجلد إلى موقع جديد داخل SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف أو المجلد المراد نسخه + - `destination_folder_id` (string, مطلوب): معرّف مجلد الوجهة + + + + + **الوصف:** نقل ملف أو مجلد إلى موقع جديد داخل SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف أو المجلد المراد نقله + - `destination_folder_id` (string, مطلوب): معرّف مجلد الوجهة + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ SharePoint + +```python +from crewai import Agent, Task, Crew + +# Create an agent with SharePoint capabilities +sharepoint_agent = Agent( + role="SharePoint Manager", + goal="Manage SharePoint sites, lists, and documents efficiently", + backstory="An AI assistant specialized in SharePoint content management and collaboration.", + apps=['microsoft_sharepoint'] # All SharePoint actions will be available +) + +# Task to organize SharePoint content +content_organization_task = Task( + description="List all accessible SharePoint sites and organize content by department", + agent=sharepoint_agent, + expected_output="SharePoint sites listed and content organized by department" +) + +# Run the task +crew = Crew( + agents=[sharepoint_agent], + tasks=[content_organization_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات المناسبة لمواقع SharePoint +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة (Sites.Read.All, Sites.ReadWrite.All) + +**مشاكل معرّفات المواقع والقوائم** + +- تحقق من صحة معرّفات المواقع والقوائم وصيغتها الصحيحة +- استخدم إجراءات get_sites وget_site_lists لاكتشاف المعرّفات الصالحة + +**مشاكل الحقول والمخطط** + +- تأكد من تطابق أسماء الحقول تماماً مع مخطط قائمة SharePoint +- تحقق من تضمين الحقول المطلوبة عند إنشاء أو تحديث عناصر القوائم + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft SharePoint + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/microsoft_teams.mdx b/docs/v1.15.1/ar/enterprise/integrations/microsoft_teams.mdx new file mode 100644 index 000000000..9714fa580 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/microsoft_teams.mdx @@ -0,0 +1,205 @@ +--- +title: تكامل Microsoft Teams +description: "التعاون الجماعي والتواصل مع تكامل Microsoft Teams لـ CrewAI." +icon: "users" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من الوصول إلى بيانات Teams وإرسال الرسائل وإنشاء الاجتماعات وإدارة القنوات. أتمت التواصل الجماعي، وجدوِل الاجتماعات، واسترجع الرسائل، وبسّط سير عمل التعاون باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Teams، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى Teams +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Teams + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Teams** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى Teams +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على جميع الفرق التي ينتمي إليها المستخدم. + + **المعاملات:** + - لا توجد معاملات مطلوبة. + + + + + **الوصف:** الحصول على القنوات في فريق محدد. + + **المعاملات:** + - `team_id` (string, مطلوب): معرّف الفريق. + + + + + **الوصف:** إرسال رسالة إلى قناة Teams. + + **المعاملات:** + - `team_id` (string, مطلوب): معرّف الفريق. + - `channel_id` (string, مطلوب): معرّف القناة. + - `message` (string, مطلوب): محتوى الرسالة. + - `content_type` (string, اختياري): نوع المحتوى (html أو text). الافتراضي: `text`. + + + + + **الوصف:** الحصول على الرسائل من قناة Teams. + + **المعاملات:** + - `team_id` (string, مطلوب): معرّف الفريق. + - `channel_id` (string, مطلوب): معرّف القناة. + - `top` (integer, اختياري): عدد الرسائل (الحد الأقصى 50). الافتراضي: `20`. + + + + + **الوصف:** إنشاء اجتماع Teams. + + **المعاملات:** + - `subject` (string, مطلوب): موضوع/عنوان الاجتماع. + - `startDateTime` (string, مطلوب): وقت بداية الاجتماع (صيغة ISO 8601 مع المنطقة الزمنية). + - `endDateTime` (string, مطلوب): وقت نهاية الاجتماع (صيغة ISO 8601 مع المنطقة الزمنية). + + + + + **الوصف:** الحصول على أعضاء فريق محدد. + + **المعاملات:** + - `team_id` (string, مطلوب): المعرّف الفريد للفريق. + - `top` (integer, اختياري): الحد الأقصى لعدد الأعضاء (1-999). الافتراضي: `100`. + + + + + **الوصف:** إنشاء قناة جديدة في فريق. + + **المعاملات:** + - `team_id` (string, مطلوب): المعرّف الفريد للفريق. + - `display_name` (string, مطلوب): اسم القناة. الحد الأقصى 50 حرفاً. + - `description` (string, اختياري): وصف اختياري يشرح غرض القناة. + - `membership_type` (string, اختياري): ظهور القناة. القيم: `standard`, `private`. الافتراضي: `standard`. + + + + + **الوصف:** الرد على رسالة في قناة Teams. + + **المعاملات:** + - `team_id` (string, مطلوب): المعرّف الفريد للفريق. + - `channel_id` (string, مطلوب): المعرّف الفريد للقناة. + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد الرد عليها. + - `message` (string, مطلوب): محتوى الرد. + - `content_type` (string, اختياري): صيغة المحتوى. القيم: `html`, `text`. الافتراضي: `text`. + + + + + **الوصف:** تحديث اجتماع عبر الإنترنت موجود. + + **المعاملات:** + - `meeting_id` (string, مطلوب): المعرّف الفريد للاجتماع. + - `subject` (string, اختياري): عنوان الاجتماع الجديد. + - `startDateTime` (string, اختياري): وقت البداية الجديد بصيغة ISO 8601. + - `endDateTime` (string, اختياري): وقت النهاية الجديد بصيغة ISO 8601. + + + + + **الوصف:** حذف اجتماع عبر الإنترنت. + + **المعاملات:** + - `meeting_id` (string, مطلوب): المعرّف الفريد للاجتماع المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft Teams + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Teams capabilities +teams_agent = Agent( + role="Teams Coordinator", + goal="Manage Teams communication and meetings efficiently", + backstory="An AI assistant specialized in Microsoft Teams operations and team collaboration.", + apps=['microsoft_teams'] # All Teams actions will be available +) + +# Task to list teams and channels +explore_teams_task = Task( + description="List all teams I'm a member of and then get the channels for the first team.", + agent=teams_agent, + expected_output="List of teams and channels displayed." +) + +# Run the task +crew = Crew( + agents=[teams_agent], + tasks=[explore_teams_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى Teams. +- النطاقات المطلوبة تشمل: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `OnlineMeetings.ReadWrite`. + +**إنشاء الاجتماعات** + +- تأكد من توفير `subject` و`startDateTime` و`endDateTime`. +- استخدم صيغة ISO 8601 مع المنطقة الزمنية لحقول التاريخ والوقت. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Teams + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/microsoft_word.mdx b/docs/v1.15.1/ar/enterprise/integrations/microsoft_word.mdx new file mode 100644 index 000000000..32ab4eb5b --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/microsoft_word.mdx @@ -0,0 +1,168 @@ +--- +title: تكامل Microsoft Word +description: "إنشاء المستندات وإدارتها مع تكامل Microsoft Word لـ CrewAI." +icon: "file-word" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وقراءة وإدارة مستندات Word والملفات النصية في OneDrive أو SharePoint. أتمت إنشاء المستندات، واسترجع المحتوى، وأدر خصائص المستندات، وبسّط سير عمل المستندات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Word، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى Word وOneDrive/SharePoint +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Word + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Word** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى الملفات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على جميع مستندات Word من OneDrive أو SharePoint. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد إرجاعها (الحد الأدنى 1، الحد الأقصى 999). + - `filter` (string, اختياري): تصفية النتائج باستخدام صيغة OData. + + + + + **الوصف:** إنشاء مستند نصي (.txt) مع محتوى. يُنصح به لإنشاء المحتوى برمجياً. + + **المعاملات:** + - `file_name` (string, مطلوب): اسم المستند النصي (يجب أن ينتهي بـ .txt). + - `content` (string, اختياري): المحتوى النصي للمستند. + + + + + **الوصف:** الحصول على محتوى مستند (يعمل بشكل أفضل مع الملفات النصية). + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند. + + + + + **الوصف:** الحصول على خصائص وبيانات وصفية لمستند. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند. + + + + + **الوصف:** حذف مستند. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند المراد حذفه. + + + + + **الوصف:** نسخ مستند إلى موقع جديد في OneDrive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند المراد نسخه + - `name` (string, اختياري): الاسم الجديد للمستند المنسوخ + - `parent_id` (string, اختياري): معرّف مجلد الوجهة (الافتراضي هو الجذر) + + + + + **الوصف:** نقل مستند إلى موقع جديد في OneDrive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند المراد نقله + - `parent_id` (string, مطلوب): معرّف مجلد الوجهة + - `name` (string, اختياري): الاسم الجديد للمستند المنقول + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft Word + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Word capabilities +word_agent = Agent( + role="Document Manager", + goal="Manage Word documents and text files efficiently", + backstory="An AI assistant specialized in Microsoft Word document operations and content management.", + apps=['microsoft_word'] # All Word actions will be available +) + +# Task to create a new text document +create_doc_task = Task( + description="Create a new text document named 'meeting_notes.txt' with content 'Meeting Notes from January 2024: Key discussion points and action items.'", + agent=word_agent, + expected_output="New text document 'meeting_notes.txt' created successfully." +) + +# Run the task +crew = Crew( + agents=[word_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى الملفات (`Files.Read.All`, `Files.ReadWrite.All`). + +**مشاكل إنشاء الملفات** + +- عند إنشاء مستندات نصية، تأكد من أن `file_name` ينتهي بامتداد `.txt`. +- تحقق من أن لديك صلاحيات الكتابة للموقع المستهدف. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Word + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/notion.mdx b/docs/v1.15.1/ar/enterprise/integrations/notion.mdx new file mode 100644 index 000000000..ef7849009 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/notion.mdx @@ -0,0 +1,149 @@ +--- +title: تكامل Notion +description: "إدارة المستخدمين والتعليقات مع تكامل Notion لـ CrewAI." +icon: "book" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المستخدمين وإنشاء التعليقات عبر Notion. يمكنك الوصول إلى معلومات مستخدمي مساحة العمل وإنشاء تعليقات على الصفحات والمناقشات، مما يبسّط سير عمل التعاون باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Notion، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Notion بصلاحيات مساحة العمل المناسبة +- ربط حساب Notion الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Notion + +### 1. ربط حساب Notion الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Notion** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى المستخدمين وإنشاء التعليقات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** عرض جميع المستخدمين في مساحة العمل. + + **المعاملات:** + - `page_size` (integer, اختياري): عدد العناصر في الاستجابة. الحد الأدنى: 1، الحد الأقصى: 100، الافتراضي: 100 + - `start_cursor` (string, اختياري): مؤشر للترقيم. + + + + + **الوصف:** استرجاع مستخدم محدد بواسطة المعرّف. + + **المعاملات:** + - `user_id` (string, مطلوب): معرّف المستخدم المراد استرجاعه. + + + + + **الوصف:** إنشاء تعليق على صفحة أو مناقشة. + + **المعاملات:** + - `parent` (object, مطلوب): الصفحة الأصلية أو المناقشة للتعليق عليها. + ```json + { + "type": "page_id", + "page_id": "PAGE_ID_HERE" + } + ``` + - `rich_text` (array, مطلوب): المحتوى النصي الغني للتعليق. + ```json + [ + { + "type": "text", + "text": { + "content": "This is my comment text" + } + } + ] + ``` + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Notion + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Notion capabilities +notion_agent = Agent( + role="Workspace Manager", + goal="Manage workspace users and facilitate collaboration through comments", + backstory="An AI assistant specialized in user management and team collaboration.", + apps=['notion'] # All Notion actions will be available +) + +# Task to list workspace users +user_management_task = Task( + description="List all users in the workspace and provide a summary of team members", + agent=notion_agent, + expected_output="Complete list of workspace users with their details" +) + +# Run the task +crew = Crew( + agents=[notion_agent], + tasks=[user_management_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Notion الخاص بك لديه الصلاحيات المناسبة لقراءة معلومات المستخدمين +- تحقق من أن لديك صلاحيات التعليق على الصفحات أو المناقشات المستهدفة + +**مشاكل إنشاء التعليقات** + +- تحقق من صحة معرّفات الصفحات أو المناقشات وإمكانية الوصول إليها +- تأكد من اتباع محتوى النص الغني لمواصفات صيغة Notion API + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Notion أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/salesforce.mdx b/docs/v1.15.1/ar/enterprise/integrations/salesforce.mdx new file mode 100644 index 000000000..3807a27ea --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/salesforce.mdx @@ -0,0 +1,378 @@ +--- +title: تكامل Salesforce +description: "أتمتة CRM والمبيعات مع تكامل Salesforce لـ CrewAI." +icon: "salesforce" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة علاقات العملاء وعمليات المبيعات والبيانات عبر Salesforce. أنشئ السجلات وحدّثها، وأدر العملاء المحتملين والفرص، ونفّذ استعلامات SOQL، وبسّط سير عمل CRM باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Salesforce، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Salesforce بالصلاحيات المناسبة +- ربط حساب Salesforce الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + + + يتطلب Salesforce **تثبيتًا واحدًا يقوم به مسؤول النظام (admin)** لحزمة + CrewAI في مؤسستك قبل أن يتمكن أي مستخدم من الاتصال. هذا متطلب من منصة + Salesforce لجميع التكاملات المعتمدة على ExternalClientApp اعتبارًا من + إصدار Spring '26 — وليس خطوة خاصة بـ CrewAI. تدليلك خطوة Connect + Salesforce في CrewAI AMP خلال هذه العملية عند المحاولة الأولى. + + +## إعداد تكامل Salesforce + +### 1. ربط حساب Salesforce الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/unified_tools). +2. ابحث عن **Salesforce** في قسم تكاملات المصادقة. +3. انقر على **Connect**. + +ما يحدث بعد ذلك يعتمد على ما إذا كان مسؤول Salesforce في مؤسستك قد ثبّت +حزمة CrewAI بالفعل: + +- **الحزمة مثبتة بالفعل:** سيتم نقلك مباشرة إلى شاشة موافقة OAuth في + Salesforce — اعتمدها وسيكتمل الاتصال. +- **الحزمة غير مثبتة بعد:** سترى صفحة **Install CrewAI in Salesforce**. + اتبع خطوات التثبيت لمرة واحدة أدناه، ثم عُد إلى CrewAI AMP وانقر على + **Connect** مرة أخرى. + +4. امنح الصلاحيات اللازمة لإدارة CRM والمبيعات. +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations). + +#### تثبيت لمرة واحدة بواسطة المسؤول (مسؤول Salesforce فقط) + +عند أول نقرة على **Connect Salesforce** من أي مستخدم في مؤسستك، تقوم CrewAI +بإعادة توجيهك إلى صفحة تثبيت تُشير إلى حزمة CrewAI المُدارة. يحتاج مسؤول +Salesforce إلى تثبيتها مرة واحدة فقط لكامل المؤسسة. + +1. في صفحة التثبيت داخل CrewAI، انقر على **Install in Salesforce**. (يمكنك + أيضًا مشاركة عنوان URL لتلك الصفحة مع المسؤول — رابط التثبيت يعمل لأي + شخص يفتحه.) +2. سجّل الدخول إلى Salesforce بصلاحيات مسؤول. لبيئات Sandbox، استبدل + `login.salesforce.com` بـ `test.salesforce.com` في الرابط قبل فتحه. +3. اختر **Install for All Users**، ووافق على إشعار تطبيقات الجهات + الخارجية، ثم انقر **Install**. +4. من Setup في Salesforce، ابحث عن **External Client App Manager** ← + **CrewAI App** ← افتح علامة التبويب **Policies** ← **Edit**، واضبط + القيم التالية: + - **Permitted Users:** All users may self-authorize + - **IP Relaxation:** Relax IP restrictions + - **Refresh Token Policy:** Refresh token is valid until revoked +5. احفظ التغييرات. +6. عُد إلى CrewAI AMP وانقر على **Connect Salesforce** مرة أخرى. سيكتمل + OAuth هذه المرة. + + + **لست مسؤول Salesforce؟** أعِد توجيه عنوان URL لصفحة التثبيت (أو رابط + التثبيت نفسه) إلى مسؤول Salesforce لديكم واطلب منه إكمال الخطوات أعلاه. + بمجرد انتهائه، عُد إلى CrewAI AMP وانقر على **Connect** مرة أخرى. + + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة السجلات** + + + + **الوصف:** إنشاء سجل جهة اتصال جديد في Salesforce. + + **المعاملات:** + - `LastName` (string, مطلوب): اسم العائلة - هذا الحقل مطلوب + - `FirstName` (string, اختياري): الاسم الأول + - `Email` (string, اختياري): عنوان البريد الإلكتروني + - `accountId` (string, اختياري): معرّف الحساب المرتبط + - `Title` (string, اختياري): المسمى الوظيفي + + + + + **الوصف:** إنشاء سجل عميل محتمل جديد في Salesforce. + + **المعاملات:** + - `LastName` (string, مطلوب): اسم العائلة - هذا الحقل مطلوب + - `Company` (string, مطلوب): الشركة - هذا الحقل مطلوب + - `FirstName` (string, اختياري): الاسم الأول + - `Email` (string, اختياري): عنوان البريد الإلكتروني + - `Status` (string, اختياري): حالة العميل المحتمل + + + + + **الوصف:** إنشاء سجل فرصة جديد في Salesforce. + + **المعاملات:** + - `Name` (string, مطلوب): اسم الفرصة - هذا الحقل مطلوب + - `StageName` (string, اختياري): مرحلة الفرصة + - `CloseDate` (string, اختياري): تاريخ الإغلاق بصيغة YYYY-MM-DD + - `Amount` (string, اختياري): المبلغ المقدر للبيع + + + + + **الوصف:** إنشاء سجل حساب جديد في Salesforce. + + **المعاملات:** + - `Name` (string, مطلوب): اسم الحساب - هذا الحقل مطلوب + - `Website` (string, اختياري): عنوان URL للموقع الإلكتروني + - `Phone` (string, اختياري): رقم الهاتف + - `Description` (string, اختياري): وصف الحساب + + + + + **الوصف:** إنشاء سجل مهمة جديد في Salesforce. + + **المعاملات:** + - `subject` (string, مطلوب): موضوع المهمة + - `taskSubtype` (string, مطلوب): النوع الفرعي للمهمة - الخيارات: task, email, listEmail, call + - `whatId` (string, اختياري): معرّف الحساب أو الفرصة المرتبطة + - `Status` (string, اختياري): الحالة - الخيارات: Not Started, In Progress, Completed + + + + +### **تحديث السجلات** + + + + **الوصف:** تحديث سجل جهة اتصال موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `FirstName` (string, اختياري): الاسم الأول + - `LastName` (string, اختياري): اسم العائلة + - `Email` (string, اختياري): عنوان البريد الإلكتروني + + + + + **الوصف:** تحديث سجل عميل محتمل موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `LastName` (string, اختياري): اسم العائلة + - `Company` (string, اختياري): اسم الشركة + - `Status` (string, اختياري): حالة العميل المحتمل + + + + + **الوصف:** تحديث سجل فرصة موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `Name` (string, اختياري): اسم الفرصة + - `StageName` (string, اختياري): مرحلة الفرصة + - `Amount` (string, اختياري): المبلغ المقدر + + + + + **الوصف:** تحديث سجل حساب موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `Name` (string, اختياري): اسم الحساب + - `Website` (string, اختياري): عنوان URL للموقع الإلكتروني + + + + +### **استرجاع السجلات** + + + + **الوصف:** الحصول على سجل جهة اتصال بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل جهة الاتصال + + + + + **الوصف:** الحصول على سجل عميل محتمل بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل العميل المحتمل + + + + + **الوصف:** الحصول على سجل فرصة بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل الفرصة + + + + + **الوصف:** الحصول على سجل حساب بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل الحساب + + + + +### **البحث في السجلات** + + + + **الوصف:** البحث عن سجلات جهات الاتصال بتصفية متقدمة. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر متقدم بصيغة التعبير العادي المنفصل + - `sortBy` (string, اختياري): حقل الفرز + - `sortDirection` (string, اختياري): اتجاه الفرز - الخيارات: ASC, DESC + + + + + **الوصف:** البحث عن سجلات العملاء المحتملين بتصفية متقدمة. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر متقدم + - `sortBy` (string, اختياري): حقل الفرز + + + + + **الوصف:** البحث عن سجلات الفرص بتصفية متقدمة. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر متقدم + - `sortBy` (string, اختياري): حقل الفرز + + + + +### **العمليات المتقدمة** + + + + **الوصف:** تنفيذ استعلامات SOQL مخصصة على بيانات Salesforce. + + **المعاملات:** + - `query` (string, مطلوب): استعلام SOQL (مثال: "SELECT Id, Name FROM Account WHERE Name = 'Example'") + + + + + **الوصف:** نشر كائن مخصص جديد في Salesforce. + + **المعاملات:** + - `label` (string, مطلوب): تسمية الكائن + - `pluralLabel` (string, مطلوب): التسمية الجمعية + - `recordName` (string, مطلوب): اسم السجل + + + + + **الوصف:** الحصول على المخطط المتوقع لعمليات على أنواع كائنات محددة. + + **المعاملات:** + - `recordType` (string, مطلوب): نوع السجل المراد وصفه + - `operation` (string, مطلوب): نوع العملية (مثال: "CREATE_RECORD" أو "UPDATE_RECORD") + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Salesforce + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Salesforce capabilities +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.", + apps=['salesforce'] # All Salesforce actions will be available +) + +# 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() +``` + +### استعلامات SOQL المتقدمة وإعداد التقارير + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['salesforce'] +) + +# 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() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Salesforce أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/shopify.mdx b/docs/v1.15.1/ar/enterprise/integrations/shopify.mdx new file mode 100644 index 000000000..fdd790a44 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/shopify.mdx @@ -0,0 +1,196 @@ +--- +title: تكامل Shopify +description: "إدارة التجارة الإلكترونية والمتجر الإلكتروني مع تكامل Shopify لـ CrewAI." +icon: "shopify" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة عمليات التجارة الإلكترونية عبر Shopify. تعامل مع العملاء والطلبات والمنتجات والمخزون وتحليلات المتجر لتبسيط أعمالك التجارية عبر الإنترنت باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Shopify، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- متجر Shopify بصلاحيات المسؤول المناسبة +- ربط متجر Shopify الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Shopify + +### 1. ربط متجر Shopify الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Shopify** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المتجر والمنتجات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة العملاء** + + + + **الوصف:** استرجاع قائمة العملاء من متجر Shopify. + + **المعاملات:** + - `customerIds` (string, اختياري): قائمة معرّفات العملاء مفصولة بفواصل + - `limit` (string, اختياري): الحد الأقصى لعدد العملاء (الافتراضي: 250) + + + + + **الوصف:** إنشاء عميل جديد في متجر Shopify. + + **المعاملات:** + - `firstName` (string, مطلوب): الاسم الأول للعميل + - `lastName` (string, مطلوب): اسم العائلة للعميل + - `email` (string, مطلوب): عنوان البريد الإلكتروني للعميل + - `phone` (string, اختياري): رقم الهاتف + - `tags` (string, اختياري): الوسوم كمصفوفة أو قائمة مفصولة بفواصل + + + + + **الوصف:** تحديث عميل موجود في متجر Shopify. + + **المعاملات:** + - `customerId` (string, مطلوب): معرّف العميل المراد تحديثه + - `firstName` (string, اختياري): الاسم الأول + - `lastName` (string, اختياري): اسم العائلة + - `email` (string, اختياري): عنوان البريد الإلكتروني + + + + +### **إدارة الطلبات** + + + + **الوصف:** استرجاع قائمة الطلبات من متجر Shopify. + + **المعاملات:** + - `orderIds` (string, اختياري): قائمة معرّفات الطلبات مفصولة بفواصل + - `limit` (string, اختياري): الحد الأقصى لعدد الطلبات (الافتراضي: 250) + + + + + **الوصف:** إنشاء طلب جديد في متجر Shopify. + + **المعاملات:** + - `email` (string, مطلوب): عنوان البريد الإلكتروني للعميل + - `lineItems` (object, مطلوب): عناصر سطر الطلب بصيغة JSON + - `fulfillmentStatus` (string, اختياري): حالة التنفيذ - الخيارات: fulfilled, null, partial, restocked + + + + + **الوصف:** استرجاع سلال التسوق المهجورة من متجر Shopify. + + **المعاملات:** + - `status` (string, اختياري): عرض عمليات الدفع بالحالة المحددة - الخيارات: open, closed (الافتراضي: open) + - `limit` (string, اختياري): الحد الأقصى لعدد السلال (الافتراضي: 250) + + + + +### **إدارة المنتجات** + + + + **الوصف:** استرجاع قائمة المنتجات من متجر Shopify. + + **المعاملات:** + - `title` (string, اختياري): تصفية حسب عنوان المنتج + - `status` (string, اختياري): تصفية حسب الحالة - الخيارات: active, archived, draft + - `limit` (string, اختياري): الحد الأقصى لعدد المنتجات (الافتراضي: 250) + + + + + **الوصف:** إنشاء منتج جديد في متجر Shopify. + + **المعاملات:** + - `title` (string, مطلوب): عنوان المنتج + - `productType` (string, مطلوب): نوع/فئة المنتج + - `vendor` (string, مطلوب): مورد المنتج + - `productDescription` (string, اختياري): وصف المنتج + - `price` (string, اختياري): سعر المنتج + + + + + **الوصف:** تحديث منتج موجود في متجر Shopify. + + **المعاملات:** + - `productId` (string, مطلوب): معرّف المنتج المراد تحديثه + - `title` (string, اختياري): عنوان المنتج + - `price` (string, اختياري): سعر المنتج + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Shopify + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# 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.", + apps=['shopify'] # All Shopify actions will be available +) + +# 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() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Shopify أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/slack.mdx b/docs/v1.15.1/ar/enterprise/integrations/slack.mdx new file mode 100644 index 000000000..bc3835c6e --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/slack.mdx @@ -0,0 +1,170 @@ +--- +title: تكامل Slack +description: "التواصل الجماعي والتعاون مع تكامل Slack لـ CrewAI." +icon: "slack" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة التواصل الجماعي عبر Slack. أرسل الرسائل، وابحث في المحادثات، وأدر القنوات، ونسّق أنشطة الفريق لتبسيط سير عمل التعاون باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Slack، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- مساحة عمل Slack بالصلاحيات المناسبة +- ربط مساحة عمل Slack الخاصة بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Slack + +### 1. ربط مساحة عمل Slack الخاصة بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Slack** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للتواصل الجماعي +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة المستخدمين** + + + + **الوصف:** عرض جميع الأعضاء في قناة Slack. + + **المعاملات:** + - لا توجد معاملات مطلوبة + + + + + **الوصف:** البحث عن مستخدم في مساحة عمل Slack بواسطة عنوان بريده الإلكتروني. + + **المعاملات:** + - `email` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم في مساحة العمل + + + + + **الوصف:** البحث عن المستخدمين بواسطة اسمهم أو اسم العرض. + + **المعاملات:** + - `name` (string, مطلوب): الاسم الحقيقي للمستخدم للبحث عنه + - `displayName` (string, مطلوب): اسم عرض المستخدم للبحث عنه + + + + +### **إدارة القنوات** + + + + **الوصف:** عرض جميع القنوات في مساحة عمل Slack. + + **المعاملات:** + - لا توجد معاملات مطلوبة + + + + +### **المراسلة** + + + + **الوصف:** إرسال رسالة إلى قناة Slack. + + **المعاملات:** + - `channel` (string, مطلوب): اسم القناة أو معرّفها + - `message` (string, مطلوب): نص الرسالة المراد إرسالها + - `botName` (string, مطلوب): اسم البوت الذي يرسل هذه الرسالة + - `botIcon` (string, مطلوب): أيقونة البوت - يمكن أن تكون عنوان URL لصورة أو رمز تعبيري + + + + + **الوصف:** إرسال رسالة مباشرة إلى مستخدم محدد في Slack. + + **المعاملات:** + - `memberId` (string, مطلوب): معرّف المستخدم المستلم + - `message` (string, مطلوب): نص الرسالة المراد إرسالها + - `botName` (string, مطلوب): اسم البوت الذي يرسل هذه الرسالة + - `botIcon` (string, مطلوب): أيقونة البوت + + + + +### **البحث والاكتشاف** + + + + **الوصف:** البحث عن الرسائل عبر مساحة عمل Slack. + + **المعاملات:** + - `query` (string, مطلوب): استعلام بحث باستخدام صيغة بحث Slack للعثور على الرسائل المطابقة + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Slack + +```python +from crewai import Agent, Task, Crew + +# 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.", + apps=['slack'] # All Slack actions will be available +) + +# 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() +``` + +## التواصل مع الدعم + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Slack أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/snowflake.mdx b/docs/v1.15.1/ar/enterprise/integrations/snowflake.mdx new file mode 100644 index 000000000..be78d05da --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/snowflake.mdx @@ -0,0 +1,134 @@ +--- +title: تكامل Snowflake +description: "ربط وكلاء CrewAI بـ Snowflake Cortex Analyst و Cortex Search وتنفيذ SQL من خلال خادم MCP المُدار من Snowflake." +icon: "snowflake" +mode: "wide" +--- + +## نظرة عامة + +اربط وكلاء CrewAI مباشرة ببيانات Snowflake الخاصة بك من خلال [خادم MCP المُدار من Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). يتيح تكامل Snowflake لوكلائك الاستعلام عن البيانات المنظمة باستخدام **Cortex Analyst**، والبحث في البيانات غير المنظمة باستخدام **Cortex Search**، وتنفيذ SQL مُدار على مستودعات البيانات الخاصة بك — كل ذلك دون كتابة أو استضافة أي كود للموصّل. + +داخلياً، تكامل Snowflake هو غلاف مُدار حول دعم [Custom MCP Server](/ar/enterprise/guides/custom-mcp-server) في CrewAI. يكشف Snowflake عن قدرات Cortex AI الخاصة به من خلال نقطة نهاية [Model Context Protocol](https://modelcontextprotocol.io/)، ويتصل CrewAI بها بشكل آمن نيابةً عنك. أي أداة تكشفها على جانب Snowflake — Cortex Analyst أو Cortex Search أو تنفيذ SQL أو Cortex Agents أو أدواتك المخصصة — تصبح متاحة لطواقمك. + +## القدرات الرئيسية + + + + اطرح أسئلة بلغة طبيعية ودع [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) يولّد وينفذ SQL على بياناتك **المنظمة** باستخدام نماذج دلالية غنية. + + + استرجع البيانات **غير المنظمة** ذات الصلة لسير عمل RAG والمعرفة باستخدام [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview)، خدمة البحث المُدارة بالكامل من Snowflake. + + + نفّذ استعلامات SQL مُدارة مباشرة على مستودعات Snowflake الخاصة بك، مع وضع القراءة فقط القابل للتكوين، والمهلات الزمنية، واختيار المستودع. + + + +نظراً لأن التكامل يكشف عن أي أدوات ينشرها خادم MCP الخاص بك، يمكنك أيضاً كشف **Cortex Agents** و**الأدوات المخصصة** (الدوال المعرّفة من المستخدم والإجراءات المخزّنة) لوكلاء CrewAI. + +## المتطلبات الأساسية + +قبل استخدام تكامل Snowflake، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Snowflake مع إمكانية الوصول إلى ميزات Cortex AI +- [خادم MCP مُدار من Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) مُكوّن بالأدوات التي تريد كشفها +- صلاحيات Snowflake المناسبة (USAGE/SELECT) على خادم MCP والكائنات الأساسية + +## إعداد خادم Snowflake MCP + +يعمل خادم MCP المُدار من Snowflake داخل حساب Snowflake الخاص بك ويحدد الأدوات المتاحة للعملاء الخارجيين مثل CrewAI. أنشئ واحداً باستخدام أمر [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server)، مع سرد خدمات Cortex Search وعروض Cortex Analyst الدلالية وأدوات SQL التي تريد كشفها. + +```sql +CREATE MCP SERVER my_mcp_server + FROM SPECIFICATION $$ + tools: + - name: "sales_analyst" + type: "CORTEX_ANALYST" + identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view" + description: "Answer questions about sales metrics" + - name: "docs_search" + type: "CORTEX_SEARCH_SERVICE_QUERY" + identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search" + description: "Search internal support documentation" + - name: "run_sql" + type: "SQL_EXECUTION" + description: "Execute read-only SQL queries" + $$; +``` + + +تتبع نقطة نهاية MCP التنسيق `https:///api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}`. يبني CrewAI هذا العنوان تلقائياً من **عنوان URL للحساب** و**قاعدة البيانات** و**المخطط** و**اسم خادم MCP** الذي تقدمه عند تكوين التكامل. + + +للمواصفات الكاملة — بما في ذلك Cortex Agents والأدوات المخصصة وحدود حجم الاستجابة وخيارات الحوكمة — راجع [وثائق خادم MCP المُدار من Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). + +## ربط Snowflake في CrewAI AMP + + + تكوين تكامل Snowflake في CrewAI AMP + + + + + انتقل إلى **الأدوات والتكاملات** في الشريط الجانبي الأيسر لـ CrewAI AMP، وابحث عن **Snowflake** في قائمة التطبيقات، وافتح لوحة التكوين الخاصة به. + + + + املأ حقول الاتصال التي يستخدمها CrewAI للوصول إلى خادم Snowflake MCP الخاص بك: + + | الحقل | مطلوب | الوصف | + |-------|-------|-------| + | **الاسم** | نعم | اسم وصفي لهذا الاتصال (القيمة الافتراضية `Snowflake`). | + | **الوصف** | لا | ملخص اختياري لما يوفره هذا الاتصال. | + | **عنوان URL للحساب** | نعم | عنوان URL لحساب Snowflake الخاص بك، مثل `xy12345.us-east-1.snowflakecomputing.com`. | + | **قاعدة البيانات** | نعم | قاعدة البيانات التي تحتوي على خادم MCP الخاص بك (مثل `MY_DATABASE`). | + | **المخطط** | نعم | المخطط الذي يحتوي على خادم MCP الخاص بك (مثل `MY_SCHEMA`). | + | **اسم خادم MCP** | نعم | اسم كائن خادم MCP الذي أنشأته في Snowflake (مثل `MY_MCP_SERVER`). | + + + + اختر كيفية مصادقة CrewAI مع Snowflake. يُوصى باستخدام **OAuth**. + + - **استخدام OAuth** — اتصل بشكل آمن باستخدام OAuth 2.0 للمصادقة القائمة على الرموز دون مشاركة بيانات الاعتماد الخاصة بك. يتعامل CrewAI مع تدفق التفويض الكامل ويجدد الرموز تلقائياً. انسخ **عنوان URI لإعادة التوجيه** المعروض في النموذج (`https://oauth.crewai.com/oauth/add`) وسجّله كعنوان URI لإعادة التوجيه المعتمد في [تكامل أمان OAuth](https://docs.snowflake.com/en/user-guide/oauth-custom) في Snowflake. + - **استخدام رمز وصول شخصي** — المصادقة باستخدام [رمز وصول برمجي](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) مُنشأ من إعدادات حساب Snowflake الخاص بك. قم بتعيين دور بأقل صلاحيات للرمز للحد من التعرض. + + + + انقر على **المصادقة**. بالنسبة لـ OAuth، ستتم إعادة توجيهك إلى Snowflake لتفويض الوصول. بمجرد المصادقة، يظهر خادم Snowflake في قائمة الاتصالات وتصبح أدواته متاحة لطواقمك. + + + + +مع OAuth، يتم مصادقة كل مستخدم بشكل فردي وتُنفّذ الاستعلامات بدور `DEFAULT_ROLE` الخاص به في Snowflake. تأكد من أن المستخدمين المتصلين لديهم دور ومستودع افتراضي محدد (`ALTER USER SET DEFAULT_ROLE = '' DEFAULT_WAREHOUSE = ''`) حتى تتوفر موارد الحوسبة لأدوات Cortex Analyst و SQL. + + +## استخدام أدوات Snowflake في طواقمك + +بمجرد الاتصال، تظهر الأدوات التي يكشفها خادم MCP الخاص بك إلى جانب الاتصالات المدمجة في صفحة **الأدوات والتكاملات**. يمكنك: + +- **تعيين الأدوات للوكلاء** في طواقمك تماماً مثل أي أداة CrewAI أخرى. +- **إدارة الرؤية** للتحكم في أعضاء الفريق الذين يمكنهم استخدام الاتصال. +- **تعديل أو إزالة** الاتصال في أي وقت من قائمة الاتصالات. + +يمكن لوكلائك الآن سؤال Cortex Analyst عن المقاييس، وتشغيل Cortex Search على مستنداتك، وتنفيذ SQL — مع تدفق النتائج تلقائياً إلى استدلالهم. + + +يفرض Snowflake الحوكمة على خادم MCP: يحدد التحكم في الوصول القائم على الأدوار الأدوات التي يمكن للمستخدم اكتشافها واستدعاؤها، وتنطبق حدود على حجم الاستجابة وعدد الأدوات (بحد أقصى 50 لكل خادم) وعمق التكرار. إذا فشل استدعاء أداة، تأكد من أن دور المستخدم المتصل لديه الصلاحيات المطلوبة على خادم MCP والكائنات الأساسية. + + +## معرفة المزيد + + + + الوثائق الرسمية من Snowflake لإنشاء وإدارة خادم MCP. + + + تعرّف على كيفية اتصال CrewAI بأي خادم MCP، الأساس الذي يبني عليه تكامل Snowflake. + + + + + تواصل مع فريق الدعم للحصول على المساعدة في تكامل Snowflake أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/v1.15.1/ar/enterprise/integrations/stripe.mdx b/docs/v1.15.1/ar/enterprise/integrations/stripe.mdx new file mode 100644 index 000000000..26252a4ef --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/stripe.mdx @@ -0,0 +1,202 @@ +--- +title: تكامل Stripe +description: "معالجة المدفوعات وإدارة الاشتراكات مع تكامل Stripe لـ CrewAI." +icon: "stripe" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المدفوعات والاشتراكات وفواتير العملاء عبر Stripe. تعامل مع بيانات العملاء، ومعالجة الاشتراكات، وإدارة المنتجات، وتتبع المعاملات المالية لتبسيط سير عمل المدفوعات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Stripe، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Stripe بصلاحيات API المناسبة +- ربط حساب Stripe الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Stripe + +### 1. ربط حساب Stripe الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Stripe** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لمعالجة المدفوعات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة العملاء** + + + + **الوصف:** إنشاء عميل جديد في حساب Stripe. + + **المعاملات:** + - `emailCreateCustomer` (string, مطلوب): عنوان البريد الإلكتروني للعميل + - `name` (string, اختياري): الاسم الكامل للعميل + - `description` (string, اختياري): وصف العميل للمرجع الداخلي + + + + + **الوصف:** استرجاع عميل محدد بواسطة معرّف عميل Stripe. + + **المعاملات:** + - `idGetCustomer` (string, مطلوب): معرّف عميل Stripe المراد استرجاعه + + + + + **الوصف:** استرجاع قائمة العملاء مع تصفية اختيارية. + + **المعاملات:** + - `emailGetCustomers` (string, اختياري): تصفية العملاء حسب البريد الإلكتروني + - `limitGetCustomers` (string, اختياري): الحد الأقصى لعدد العملاء (الافتراضي: 10) + + + + + **الوصف:** تحديث معلومات عميل موجود. + + **المعاملات:** + - `customerId` (string, مطلوب): معرّف العميل المراد تحديثه + - `emailUpdateCustomer` (string, اختياري): عنوان البريد الإلكتروني المحدّث + - `name` (string, اختياري): اسم العميل المحدّث + + + + +### **إدارة الاشتراكات** + + + + **الوصف:** إنشاء اشتراك جديد لعميل. + + **المعاملات:** + - `customerIdCreateSubscription` (string, مطلوب): معرّف العميل الذي سيُنشأ له الاشتراك + - `plan` (string, مطلوب): معرّف خطة الاشتراك + + + + + **الوصف:** استرجاع الاشتراكات مع تصفية اختيارية. + + **المعاملات:** + - `customerIdGetSubscriptions` (string, اختياري): تصفية الاشتراكات حسب معرّف العميل + - `subscriptionStatus` (string, اختياري): تصفية حسب حالة الاشتراك - الخيارات: incomplete, trialing, active, past_due, canceled, unpaid + + + + +### **إدارة المنتجات** + + + + **الوصف:** إنشاء منتج جديد في كتالوج Stripe. + + **المعاملات:** + - `productName` (string, مطلوب): اسم المنتج + - `description` (string, اختياري): وصف المنتج + + + + + **الوصف:** استرجاع قائمة المنتجات مع تصفية اختيارية. + + **المعاملات:** + - `limitGetProducts` (string, اختياري): الحد الأقصى لعدد المنتجات (الافتراضي: 10) + + + + +### **العمليات المالية** + + + + **الوصف:** استرجاع معاملات الرصيد من حساب Stripe. + + **المعاملات:** + - `balanceTransactionType` (string, اختياري): تصفية حسب نوع المعاملة - الخيارات: charge, refund, payment, payment_refund + + + + + **الوصف:** استرجاع خطط الاشتراك من حساب Stripe. + + **المعاملات:** + - `isPlanActive` (boolean, اختياري): تصفية حسب حالة الخطة + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Stripe + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# 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.", + apps=['stripe'] # All Stripe actions will be available +) + +# 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() +``` + +## مرجع حالات الاشتراك + +فهم حالات الاشتراك: + +- **incomplete** - الاشتراك يتطلب طريقة دفع أو تأكيد الدفع +- **trialing** - الاشتراك في فترة تجريبية +- **active** - الاشتراك نشط وحالي +- **past_due** - فشل الدفع لكن الاشتراك لا يزال نشطاً +- **canceled** - تم إلغاء الاشتراك +- **unpaid** - فشل الدفع والاشتراك لم يعد نشطاً + +يمكّن هذا التكامل أتمتة شاملة لإدارة المدفوعات والاشتراكات، مما يسمح لوكلاء الذكاء الاصطناعي بالتعامل مع عمليات الفوترة بسلاسة ضمن نظام Stripe البيئي. diff --git a/docs/v1.15.1/ar/enterprise/integrations/zendesk.mdx b/docs/v1.15.1/ar/enterprise/integrations/zendesk.mdx new file mode 100644 index 000000000..000a6e4c4 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/integrations/zendesk.mdx @@ -0,0 +1,262 @@ +--- +title: تكامل Zendesk +description: "دعم العملاء وإدارة مكتب المساعدة مع تكامل Zendesk لـ CrewAI." +icon: "headset" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة عمليات دعم العملاء عبر Zendesk. أنشئ التذاكر وحدّثها، وأدر المستخدمين، وتتبع مقاييس الدعم، وبسّط سير عمل خدمة العملاء باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Zendesk، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Zendesk بصلاحيات API المناسبة +- ربط حساب Zendesk الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Zendesk + +### 1. ربط حساب Zendesk الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Zendesk** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة التذاكر والمستخدمين +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة التذاكر** + + + + **الوصف:** إنشاء تذكرة دعم جديدة في Zendesk. + + **المعاملات:** + - `ticketSubject` (string, مطلوب): سطر موضوع التذكرة + - `ticketDescription` (string, مطلوب): أول تعليق يظهر على التذكرة + - `requesterName` (string, مطلوب): اسم المستخدم الذي يطلب الدعم + - `requesterEmail` (string, مطلوب): بريد المستخدم الذي يطلب الدعم + - `ticketType` (string, اختياري): نوع التذكرة - الخيارات: problem, incident, question, task + - `ticketPriority` (string, اختياري): مستوى الأولوية - الخيارات: urgent, high, normal, low + - `ticketStatus` (string, اختياري): حالة التذكرة - الخيارات: new, open, pending, hold, solved, closed + + + + + **الوصف:** تحديث تذكرة دعم موجودة في Zendesk. + + **المعاملات:** + - `ticketId` (string, مطلوب): معرّف التذكرة المراد تحديثها + - `requesterName` (string, مطلوب): اسم المستخدم الذي طلب هذه التذكرة + - `requesterEmail` (string, مطلوب): بريد المستخدم الذي طلب هذه التذكرة + - `ticketSubject` (string, اختياري): موضوع التذكرة المحدّث + - `ticketPriority` (string, اختياري): الأولوية المحدّثة + - `ticketStatus` (string, اختياري): الحالة المحدّثة + + + + + **الوصف:** استرجاع تذكرة محددة بواسطة معرّفها. + + **المعاملات:** + - `ticketId` (string, مطلوب): معرّف التذكرة المراد استرجاعها + + + + + **الوصف:** إضافة تعليق أو ملاحظة داخلية إلى تذكرة موجودة. + + **المعاملات:** + - `ticketId` (string, مطلوب): معرّف التذكرة لإضافة التعليق إليها + - `commentBody` (string, مطلوب): رسالة التعليق + - `isInternalNote` (boolean, اختياري): عيّن إلى true للملاحظات الداخلية بدلاً من الردود العامة + + + + + **الوصف:** البحث عن التذاكر باستخدام فلاتر ومعايير مختلفة. + + **المعاملات:** + - `ticketSubject` (string, اختياري): تصفية حسب النص في موضوع التذكرة + - `ticketStatus` (string, اختياري): تصفية حسب الحالة + - `ticketPriority` (string, اختياري): تصفية حسب الأولوية + - `sort_by` (string, اختياري): حقل الفرز - الخيارات: created_at, updated_at, priority, status + - `sort_order` (string, اختياري): اتجاه الفرز - الخيارات: asc, desc + + + + +### **إدارة المستخدمين** + + + + **الوصف:** إنشاء مستخدم جديد في Zendesk. + + **المعاملات:** + - `name` (string, مطلوب): الاسم الكامل للمستخدم + - `email` (string, اختياري): عنوان البريد الإلكتروني + - `phone` (string, اختياري): رقم الهاتف + - `role` (string, اختياري): دور المستخدم - الخيارات: admin, agent, end-user + + + + + **الوصف:** تحديث معلومات مستخدم موجود. + + **المعاملات:** + - `userId` (string, مطلوب): معرّف المستخدم المراد تحديثه + - `name` (string, اختياري): اسم المستخدم المحدّث + - `email` (string, اختياري): البريد الإلكتروني المحدّث + - `role` (string, اختياري): الدور المحدّث + + + + + **الوصف:** استرجاع مستخدم محدد بواسطة معرّفه. + + **المعاملات:** + - `userId` (string, مطلوب): معرّف المستخدم المراد استرجاعه + + + + + **الوصف:** البحث عن المستخدمين باستخدام معايير مختلفة. + + **المعاملات:** + - `name` (string, اختياري): تصفية حسب اسم المستخدم + - `email` (string, اختياري): تصفية حسب البريد الإلكتروني + - `role` (string, اختياري): تصفية حسب الدور + + + + +### **أدوات إدارية** + + + + **الوصف:** استرجاع جميع الحقول القياسية والمخصصة المتاحة للتذاكر. + + **المعاملات:** + - `paginationParameters` (object, اختياري): إعدادات الترقيم + + + + + **الوصف:** الحصول على سجلات التدقيق (السجل للقراءة فقط) للتذاكر. + + **المعاملات:** + - `ticketId` (string, اختياري): الحصول على سجلات التدقيق لتذكرة محددة + + + + +## مستويات أولوية التذاكر + +فهم مستويات الأولوية: + +- **urgent** - مشاكل حرجة تتطلب اهتماماً فورياً +- **high** - مشاكل مهمة يجب معالجتها بسرعة +- **normal** - أولوية قياسية لمعظم التذاكر +- **low** - مشاكل ثانوية يمكن معالجتها عند الإمكان + +## سير عمل حالة التذكرة + +تقدم حالة التذكرة القياسي: + +- **new** - أُنشئت حديثاً، لم تُعيّن بعد +- **open** - يتم العمل عليها بنشاط +- **pending** - في انتظار رد العميل أو إجراء خارجي +- **hold** - متوقفة مؤقتاً +- **solved** - تم حل المشكلة، في انتظار تأكيد العميل +- **closed** - اكتملت التذكرة وأُغلقت + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Zendesk + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Zendesk capabilities +zendesk_agent = Agent( + role="Support Manager", + goal="Manage customer support tickets and provide excellent customer service", + backstory="An AI assistant specialized in customer support operations and ticket management.", + apps=['zendesk'] # All Zendesk actions will be available +) + +# Task to create a new support ticket +create_ticket_task = Task( + description="Create a high-priority support ticket for John Smith who is unable to access his account after password reset", + agent=zendesk_agent, + expected_output="Support ticket created successfully with ticket ID" +) + +# Run the task +crew = Crew( + agents=[zendesk_agent], + tasks=[create_ticket_task] +) + +crew.kickoff() +``` + +### إدارة التذاكر المتقدمة + +```python +from crewai import Agent, Task, Crew + +ticket_manager = Agent( + role="Ticket Manager", + goal="Manage support ticket workflows and ensure timely resolution", + backstory="An AI assistant that specializes in support ticket triage and workflow optimization.", + apps=['zendesk'] +) + +# Task to manage ticket lifecycle +ticket_workflow = Task( + description=""" + 1. Create a new support ticket for account access issues + 2. Add internal notes with troubleshooting steps + 3. Update ticket priority based on customer tier + 4. Add resolution comments and close the ticket + """, + agent=ticket_manager, + expected_output="Complete ticket lifecycle managed from creation to resolution" +) + +crew = Crew( + agents=[ticket_manager], + tasks=[ticket_workflow] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ar/enterprise/introduction.mdx b/docs/v1.15.1/ar/enterprise/introduction.mdx new file mode 100644 index 000000000..1d0b15c76 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/introduction.mdx @@ -0,0 +1,99 @@ +--- +title: "CrewAI AMP" +description: "نشر ومراقبة وتوسيع سير عمل وكلاء الذكاء الاصطناعي" +icon: "globe" +mode: "wide" +--- + +## مقدمة + +توفر منصة CrewAI AMP (منصة إدارة الوكلاء) بيئة لنشر ومراقبة وتوسيع أطقمك ووكلائك في بيئة إنتاجية. + + + لوحة تحكم CrewAI AMP + + +تعمل منصة CrewAI AMP على توسيع قوة إطار العمل مفتوح المصدر بميزات مصممة لعمليات النشر الإنتاجية والتعاون وقابلية التوسع. انشر أطقمك على بنية تحتية مُدارة وراقب تنفيذها في الوقت الفعلي. + +## الميزات الرئيسية + + + + انشر أطقمك على بنية تحتية مُدارة بنقرات قليلة + + + الوصول إلى أطقمك المنشورة عبر REST API للتكامل مع الأنظمة الحالية + + + راقب أطقمك مع تتبع تفصيلي للتنفيذ والسجلات + + + انشر وثبّت الأدوات لتعزيز قدرات أطقمك + + + بث الأحداث والتحديثات في الوقت الفعلي إلى أنظمتك + + + أنشئ وخصص الأطقم باستخدام واجهة بدون كود/منخفضة الكود + + + +## خيارات النشر + + + + اتصل مباشرة بمستودعات GitHub الخاصة بك لنشر الكود + + + انشر الأطقم المنشأة عبر واجهة استوديو الأطقم بدون كود + + + استخدم واجهة سطر أوامر CrewAI لسير عمل نشر أكثر تقدمًا + + + +## البدء + + + + أنشئ حسابك على [app.crewai.com](https://app.crewai.com) + + التسجيل + + + + استخدم الكود أو استوديو الأطقم لبناء طاقمك + + بناء طاقم + + + + انشر طاقمك على منصة Enterprise + + نشر طاقم + + + + تكامل مع طاقمك عبر نقاط نهاية API المُنشأة + + استخدام API الطاقم + + + + +للحصول على تعليمات مفصلة، اطلع على [دليل النشر](/ar/enterprise/guides/deploy-to-amp) أو انقر على الزر أدناه للبدء. diff --git a/docs/v1.15.1/ar/enterprise/resources/frequently-asked-questions.mdx b/docs/v1.15.1/ar/enterprise/resources/frequently-asked-questions.mdx new file mode 100644 index 000000000..65cc02c80 --- /dev/null +++ b/docs/v1.15.1/ar/enterprise/resources/frequently-asked-questions.mdx @@ -0,0 +1,152 @@ +--- +title: الأسئلة الشائعة +description: "الأسئلة المتكررة حول CrewAI AMP" +icon: "circle-question" +mode: "wide" +--- + + + + في العملية الهرمية، يتم إنشاء وكيل مدير تلقائيًا ينسق سير العمل، ويفوض المهام ويتحقق من النتائج لتنفيذ مبسط وفعال. يستخدم وكيل المدير الأدوات لتسهيل تفويض المهام وتنفيذها بواسطة الوكلاء تحت إشراف المدير. يُعد نموذج اللغة الخاص بالمدير (LLM) أساسيًا للعملية الهرمية ويجب إعداده بشكل صحيح لضمان العمل السليم. + + + + يتوفر أحدث توثيق لـ CrewAI على موقع التوثيق الرسمي: https://docs.crewai.com/ + توثيق CrewAI + + + + #### العملية الهرمية: + - يتم تفويض المهام وتنفيذها بناءً على سلسلة قيادة منظمة + - يجب تحديد نموذج لغة المدير (`manager_llm`) لوكيل المدير + - يشرف وكيل المدير على تنفيذ المهام والتخطيط والتفويض والتحقق + - لا يتم تعيين المهام مسبقًا؛ يقوم المدير بتخصيص المهام للوكلاء بناءً على قدراتهم + + #### العملية التسلسلية: + - يتم تنفيذ المهام واحدة تلو الأخرى، مما يضمن إكمال المهام بتقدم منظم + - يُستخدم مخرج مهمة واحدة كسياق للمهمة التالية + - يتبع تنفيذ المهام الترتيب المحدد مسبقًا في قائمة المهام + + #### أي عملية أفضل للمشاريع المعقدة؟ + العملية الهرمية أنسب للمشاريع المعقدة لأنها تسمح بـ: + - **تخصيص وتفويض ديناميكي للمهام**: يمكن لوكيل المدير تعيين المهام بناءً على قدرات الوكلاء + - **التحقق والإشراف المنظم**: يراجع وكيل المدير مخرجات المهام ويضمن إكمالها + - **إدارة المهام المعقدة**: تحكم دقيق في توفر الأدوات على مستوى الوكيل + + + + - **التعلم التكيفي**: تصبح الأطقم أكثر كفاءة بمرور الوقت، حيث تتكيف مع المعلومات الجديدة وتحسن نهجها في المهام + - **التخصيص المحسن**: تمكّن الذاكرة الوكلاء من تذكر تفضيلات المستخدم والتفاعلات السابقة، مما يؤدي إلى تجارب مخصصة + - **تحسين حل المشكلات**: يساعد الوصول إلى مخزن ذاكرة غني الوكلاء في اتخاذ قرارات أكثر استنارة، بالاعتماد على الدروس المستفادة والرؤى السياقية + + + + يمنع تعيين حد أقصى لعدد الطلبات في الدقيقة للوكيل من إجراء عدد كبير جدًا من الطلبات إلى الخدمات الخارجية، مما يساعد في تجنب حدود المعدل وتحسين الأداء. + + + + يتيح المدخل البشري للوكلاء طلب معلومات إضافية أو توضيحات عند الحاجة. هذه الميزة ضرورية في عمليات صنع القرار المعقدة أو عندما يحتاج الوكلاء إلى مزيد من التفاصيل لإكمال مهمة بفعالية. + + لدمج المدخل البشري في تنفيذ الوكيل، عيّن علامة `human_input` في تعريف المهمة. عند التفعيل، يطلب الوكيل من المستخدم إدخالًا قبل تقديم إجابته النهائية. يمكن أن يوفر هذا الإدخال سياقًا إضافيًا أو يوضح الغموض أو يتحقق من مخرجات الوكيل. + + للحصول على إرشادات تنفيذ مفصلة، راجع [دليل الإنسان في الحلقة](/ar/enterprise/guides/human-in-the-loop). + + + + يوفر CrewAI مجموعة من خيارات التخصيص المتقدمة: + + - **تخصيص نموذج اللغة**: يمكن تخصيص الوكلاء بنماذج لغوية محددة (`llm`) ونماذج لغوية لاستدعاء الدوال (`function_calling_llm`) + - **إعدادات الأداء والتصحيح**: ضبط أداء الوكيل ومراقبة عملياته + - **الوضع المفصل**: يتيح تسجيلًا مفصلًا لإجراءات الوكيل، مفيد للتصحيح والتحسين + - **حد RPM**: يحدد العدد الأقصى للطلبات في الدقيقة (`max_rpm`) + - **الحد الأقصى للتكرارات**: تسمح خاصية `max_iter` للمستخدمين بتحديد العدد الأقصى للتكرارات التي يمكن للوكيل تنفيذها لمهمة واحدة + - **التفويض والاستقلالية**: التحكم في قدرة الوكيل على التفويض أو طرح الأسئلة عبر خاصية `allow_delegation` (الافتراضي: True) + - **دمج المدخل البشري**: يمكن للوكلاء طلب معلومات إضافية أو توضيحات عند الحاجة + + + + يكون المدخل البشري مفيدًا بشكل خاص عندما: + - **يحتاج الوكلاء إلى معلومات إضافية أو توضيحات**: عندما يواجه الوكلاء غموضًا أو بيانات غير مكتملة + - **يحتاج الوكلاء إلى اتخاذ قرارات معقدة أو حساسة**: يمكن للمدخل البشري المساعدة في صنع القرارات الأخلاقية أو الدقيقة + - **الإشراف والتحقق من مخرجات الوكيل**: يمكن للمدخل البشري المساعدة في التحقق من النتائج ومنع الأخطاء + - **تخصيص سلوك الوكيل**: يمكن للمدخل البشري توفير ملاحظات لتحسين استجابات الوكيل بمرور الوقت + - **تحديد وحل الأخطاء أو القيود**: يساعد المدخل البشري في معالجة فجوات قدرات الوكيل + + + + أنواع الذاكرة المختلفة المتاحة في CrewAI هي: + - **الذاكرة قصيرة المدى**: تخزين مؤقت للسياق الفوري + - **الذاكرة طويلة المدى**: تخزين دائم للأنماط والمعلومات المكتسبة + - **ذاكرة الكيانات**: تخزين مركز على كيانات محددة وخصائصها + - **الذاكرة السياقية**: ذاكرة تحافظ على السياق عبر التفاعلات + + تعرف على المزيد حول أنواع الذاكرة المختلفة: + ذاكرة CrewAI + + + + لاستخدام Output Pydantic في مهمة، تحتاج إلى تعريف المخرج المتوقع للمهمة كنموذج Pydantic. إليك مثال سريع: + + + + ```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 + ) + ``` + + + + إليك درسًا تعليميًا حول كيفية الحصول على مخرجات منظمة بشكل متسق من وكلائك: + + + + + يمكنك إنشاء أدوات مخصصة عن طريق إنشاء فئة فرعية من فئة `BaseTool` المقدمة من CrewAI أو باستخدام مُزخرف الأداة (tool decorator). ينطوي إنشاء الفئة الفرعية على تعريف فئة جديدة ترث من `BaseTool`، مع تحديد الاسم والوصف وطريقة `_run` للمنطق التشغيلي. يتيح لك مُزخرف الأداة إنشاء كائن `Tool` مباشرة مع الخصائص المطلوبة والمنطق الوظيفي. + + دليل أدوات CrewAI + + + + تحدد خاصية `max_rpm` العدد الأقصى للطلبات في الدقيقة التي يمكن للطاقم تنفيذها لتجنب حدود المعدل، وستتجاوز إعدادات `max_rpm` الفردية للوكلاء إذا قمت بتعيينها. + + + diff --git a/docs/v1.15.1/ar/examples/cookbooks.mdx b/docs/v1.15.1/ar/examples/cookbooks.mdx new file mode 100644 index 000000000..49280d73c --- /dev/null +++ b/docs/v1.15.1/ar/examples/cookbooks.mdx @@ -0,0 +1,49 @@ +--- +title: كتب وصفات CrewAI +description: بدايات سريعة ودفاتر ملاحظات مركّزة على الميزات لتعلم الأنماط بسرعة. +icon: book +mode: "wide" +--- + +## بدايات سريعة وعروض توضيحية + + + + تنسيق عدة Agents على مهام مشتركة. يتضمن دفتر ملاحظات بنمط تعاون شامل. + + + + تعليم الـ Agents التفكير في خطط متعددة المراحل قبل التنفيذ باستخدام أدوات التخطيط. + + + + استكشاف حلقات التأمل الذاتي، ومطالبات النقد، وأنماط التفكير المنظم. + + + + + + تطبيق حواجز حماية على مستوى المهام مع إعادة المحاولة ودوال التحقق والبدائل الآمنة. + + + + ربط CrewAI بـ Gemini مع تأريض البحث للحصول على مخرجات واقعية غنية بالاستشهادات. + + + + إنشاء ملخصات فيديو باستخدام نموذج Gemini متعدد الوسائط وتنسيق CrewAI. + + + + + + عرض جميع دفاتر الملاحظات والعروض التوضيحية التي تستعرض إمكانيات CrewAI المحددة. + + + هل يفتقد نمط معين؟ أرسل طلبًا في منتدى المجتمع وسنوسّع المكتبة. + + + + +استخدم كتب الوصفات لتعلم نمط بسرعة، ثم انتقل إلى الأمثلة الكاملة للتطبيقات الجاهزة للإنتاج. + diff --git a/docs/v1.15.1/ar/examples/example.mdx b/docs/v1.15.1/ar/examples/example.mdx new file mode 100644 index 000000000..0987e8dff --- /dev/null +++ b/docs/v1.15.1/ar/examples/example.mdx @@ -0,0 +1,86 @@ +--- +title: أمثلة CrewAI +description: استكشف أمثلة منسّقة مرتبة حسب Crews وFlows والتكاملات ودفاتر الملاحظات. +icon: rocket-launch +mode: "wide" +--- + +## Crews + + + + تخطيط حملات تسويقية متعددة الـ Agents. + + + تخطيط رحلات مفاجئة مخصصة. + + + مطابقة السيرة الذاتية بالوظائف باستخدام البحث المتجهي. + + + إنشاء أوصاف وظيفية آلية. + + + فريق متعدد الـ Agents يصمم ويبني ألعاب Python. + + + استقطاب المرشحين وتقييمهم. + + + عرض القائمة الكاملة لأمثلة الـ Crews. + + + +## Flows + + + + إنشاء محتوى متعدد الـ Crews مع التوجيه. + + + مراقبة البريد الإلكتروني والرد الآلي. + + + تأهيل العملاء المحتملين مع تدخل بشري. + + + معالجة الملاحظات مع التكاملات. + + + سير عمل التحسين الذاتي التكراري. + + + إنشاء الفصول بالتوازي. + + + عرض القائمة الكاملة لأمثلة الـ Flows. + + + +## التكاملات + + + + التكامل مع إطار عمل LangGraph. + + + استخدام CrewAI مع Azure OpenAI. + + + تكاملات منظومة NVIDIA. + + + عرض جميع أمثلة التكاملات. + + + +## دفاتر الملاحظات + + + + Simple QA Crew + Flow. + + + أمثلة تفاعلية للتعلم والتجريب. + + diff --git a/docs/v1.15.1/ar/guides/advanced/customizing-prompts.mdx b/docs/v1.15.1/ar/guides/advanced/customizing-prompts.mdx new file mode 100644 index 000000000..b16c3b0b0 --- /dev/null +++ b/docs/v1.15.1/ar/guides/advanced/customizing-prompts.mdx @@ -0,0 +1,331 @@ +--- +title: تخصيص المطالبات +description: تعمّق في تخصيص المطالبات على المستوى المنخفض في CrewAI، مما يتيح حالات استخدام مخصصة ومعقدة لنماذج ولغات مختلفة. +icon: message-pen +mode: "wide" +--- + +## لماذا نخصص المطالبات؟ + +على الرغم من أن مطالبات CrewAI الافتراضية تعمل بشكل جيد في كثير من السيناريوهات، إلا أن التخصيص على المستوى المنخفض يفتح الباب أمام سلوك أكثر مرونة وقوة للـ Agent. إليك لماذا قد ترغب في الاستفادة من هذا التحكم العميق: + +1. **التحسين لنماذج LLM محددة** – تزدهر النماذج المختلفة (مثل GPT-4 وClaude وLlama) مع تنسيقات مطالبات مصممة لبنيتها الفريدة. +2. **تغيير اللغة** – بناء Agents تعمل حصريًا بلغات غير الإنجليزية مع التعامل مع الفروق الدقيقة بدقة. +3. **التخصص في مجالات معقدة** – تكييف المطالبات لصناعات متخصصة للغاية مثل الرعاية الصحية والمالية والقانون. +4. **ضبط النبرة والأسلوب** – جعل الـ Agents أكثر رسمية أو عفوية أو إبداعية أو تحليلية. +5. **دعم حالات استخدام مخصصة للغاية** – استخدام هياكل وتنسيقات مطالبات متقدمة لتلبية متطلبات معقدة خاصة بالمشروع. + +يستكشف هذا الدليل كيفية الوصول إلى مطالبات CrewAI على مستوى أعمق، مما يمنحك تحكمًا دقيقًا في كيفية تفكير الـ Agents وتفاعلها. + +## فهم نظام المطالبات في CrewAI + +تحت الغطاء، يستخدم CrewAI نظام مطالبات معياري يمكنك تخصيصه على نطاق واسع: + +- **قوالب الـ Agent** – تحكم في نهج كل Agent تجاه دوره المعيّن. +- **شرائح المطالبات** – تتحكم في السلوكيات المتخصصة مثل المهام واستخدام الأدوات وهيكل المخرجات. +- **معالجة الأخطاء** – توجيه كيفية استجابة الـ Agents للإخفاقات والاستثناءات وحالات انتهاء المهلة. +- **مطالبات خاصة بالأدوات** – تعريف تعليمات مفصلة لكيفية استدعاء الأدوات أو استخدامها. + +اطلع على [قوالب المطالبات الأصلية في مستودع CrewAI](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) لمعرفة كيفية تنظيم هذه العناصر. من هناك، يمكنك تجاوزها أو تكييفها حسب الحاجة لفتح سلوكيات متقدمة. + +## فهم تعليمات النظام الافتراضية + + +**مشكلة شفافية الإنتاج**: يحقن CrewAI تلقائيًا تعليمات افتراضية في مطالباتك قد لا تكون على علم بها. يشرح هذا القسم ما يحدث تحت الغطاء وكيفية الحصول على تحكم كامل. + + +عندما تعرّف Agent بـ `role` و`goal` و`backstory`، يضيف CrewAI تلقائيًا تعليمات نظام إضافية تتحكم في التنسيق والسلوك. فهم هذه الحقن الافتراضية أمر بالغ الأهمية لأنظمة الإنتاج التي تحتاج شفافية كاملة في المطالبات. + +### ما يحقنه CrewAI تلقائيًا + +بناءً على تهيئة الـ Agent، يضيف CrewAI تعليمات افتراضية مختلفة: + +#### للـ Agents بدون أدوات +```text +"I MUST use these formats, my job depends on it!" +``` + +#### للـ Agents مع أدوات +```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... +``` + +#### للمخرجات المنظمة (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." +``` + +### عرض مطالبة النظام الكاملة + +لمعرفة المطالبة المرسلة بالضبط إلى LLM، يمكنك فحص المطالبة المولّدة: + +```python +from crewai import Agent, Crew, Task +from crewai.utilities.prompts import Prompts + +# Create your agent +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 +) + +# Create a sample task +task = Task( + description="Analyze the sales data and identify trends", + expected_output="A detailed analysis with key insights and trends", + agent=agent +) + +# Create the prompt generator +prompt_generator = Prompts( + agent=agent, + has_tools=len(agent.tools) > 0, + use_system_prompt=agent.use_system_prompt +) + +# Generate and inspect the actual prompt +generated_prompt = prompt_generator.task_execution() + +# Print the complete system prompt that will be sent to the 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"]) + +# You can also see how the task description gets formatted +print("\n=== TASK CONTEXT ===") +print(f"Task Description: {task.description}") +print(f"Expected Output: {task.expected_output}") +``` + +### تجاوز التعليمات الافتراضية + +لديك عدة خيارات للحصول على تحكم كامل في المطالبات: + +#### الخيار 1: القوالب المخصصة (مُوصى به) +```python +from crewai import Agent + +# Define your own system template without default instructions +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 separate system/user messages +) +``` + +#### الخيار 2: ملف مطالبات مخصص +أنشئ ملف `custom_prompts.json` لتجاوز شرائح مطالبات محددة: + +```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}" + } +} +``` + +ثم استخدمه في Crew: + +```python +crew = Crew( + agents=[agent], + tasks=[task], + prompt_file="custom_prompts.json", + verbose=True +) +``` + + +يُحتفظ بـ `agent.i18n` للتوافق مع الإصدارات السابقة فقط، وقد تم إهماله. لتخصيص المطالبات أثناء التشغيل، مرّر `prompt_file` إلى `Crew`. وللوصول البرمجي المباشر إلى شرائح المطالبات، استخدم أداة i18n مباشرة: + + +```python +from crewai.utilities.i18n import get_i18n + +i18n = get_i18n("custom_prompts.json") +format_slice = i18n.slice("format") +tool_prompt = i18n.tools("ask_question") +``` + +#### الخيار 3: تعطيل مطالبات النظام لنماذج o1 +```python +agent = Agent( + role="Analyst", + goal="Analyze data", + backstory="Expert analyst", + use_system_prompt=False # Disables system prompt separation +) +``` + +### التصحيح باستخدام أدوات المراقبة + +لشفافية الإنتاج، استخدم منصات المراقبة لمتابعة جميع المطالبات وتفاعلات LLM. يتيح لك ذلك رؤية المطالبات المرسلة بالضبط (بما في ذلك التعليمات الافتراضية) إلى نماذج LLM. + +راجع [توثيق المراقبة](/ar/observability/overview) للحصول على أدلة تكامل مفصلة مع منصات متعددة بما في ذلك Langfuse وMLflow وWeights & Biases وحلول التسجيل المخصصة. + +### أفضل الممارسات للإنتاج + +1. **افحص المطالبات المولّدة دائمًا** قبل النشر في الإنتاج +2. **استخدم قوالب مخصصة** عندما تحتاج تحكمًا كاملاً في محتوى المطالبات +3. **دمج أدوات المراقبة** للمتابعة المستمرة للمطالبات (راجع [توثيق المراقبة](/ar/observability/overview)) +4. **اختبر مع نماذج LLM مختلفة** حيث قد تعمل التعليمات الافتراضية بشكل مختلف عبر النماذج +5. **وثّق تخصيصات المطالبات** لشفافية الفريق + + +التعليمات الافتراضية موجودة لضمان سلوك Agent متسق، لكنها قد تتعارض مع المتطلبات الخاصة بالمجال. استخدم خيارات التخصيص أعلاه للحفاظ على تحكم كامل في سلوك Agent في أنظمة الإنتاج. + + +## أفضل الممارسات لإدارة ملفات المطالبات + +عند الانخراط في تخصيص المطالبات على المستوى المنخفض، اتبع هذه الإرشادات للحفاظ على التنظيم وسهولة الصيانة: + +1. **احتفظ بالملفات منفصلة** – خزّن المطالبات المخصصة في ملفات JSON مخصصة خارج قاعدة الكود الرئيسية. +2. **التحكم في الإصدارات** – تتبع التغييرات داخل المستودع مع ضمان توثيق واضح لتعديلات المطالبات بمرور الوقت. +3. **التنظيم حسب النموذج أو اللغة** – استخدم تسميات مثل `prompts_llama.json` أو `prompts_es.json` لتحديد التهيئات المتخصصة بسرعة. +4. **توثيق التغييرات** – قدم تعليقات أو حافظ على ملف يوضح غرض ونطاق تخصيصاتك. +5. **قلل التعديلات** – تجاوز فقط الشرائح المحددة التي تحتاج حقًا لتعديلها مع الحفاظ على الوظائف الافتراضية لكل شيء آخر. + +## أبسط طريقة لتخصيص المطالبات + +إحدى الطرق المباشرة هي إنشاء ملف JSON للمطالبات التي تريد تجاوزها ثم توجيه Crew إلى ذلك الملف: + +1. أنشئ ملف JSON بشرائح المطالبات المحدّثة. +2. أشر إلى ذلك الملف عبر معامل `prompt_file` في Crew. + +يدمج CrewAI بعد ذلك تخصيصاتك مع الإعدادات الافتراضية، فلا تحتاج لإعادة تعريف كل مطالبة. إليك الطريقة: + +بالنسبة للكود الذي يحتاج إلى قراءة شرائح المطالبات مباشرة، استخدم `crewai.utilities.i18n.get_i18n()` مع ملف المطالبات نفسه بدلًا من قراءة `agent.i18n`. + +### مثال: تخصيص أساسي للمطالبات + +أنشئ ملف `custom_prompts.json` بالمطالبات التي تريد تعديلها. تأكد من إدراج جميع المطالبات عالية المستوى التي يجب أن يحتويها، وليس فقط تغييراتك: + +```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" + } +} +``` + +ثم ادمجه هكذا: + +```python +from crewai import Agent, Crew, Task, Process + +# Create agents and tasks as normal +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 +) + +# Create a crew with your custom prompt file +crew = Crew( + agents=[researcher], + tasks=[research_task], + prompt_file="path/to/custom_prompts.json", + verbose=True +) + +# Run the crew +result = crew.kickoff() +``` + +بهذه التعديلات البسيطة، تحصل على تحكم منخفض المستوى في كيفية تواصل الـ Agents وحل المهام. + +## التحسين لنماذج محددة + +تزدهر النماذج المختلفة مع مطالبات منظمة بطرق مختلفة. إجراء تعديلات أعمق يمكن أن يعزز الأداء بشكل كبير من خلال مواءمة مطالباتك مع خصائص النموذج. + +### مثال: قالب مطالبات Llama 3.3 + +على سبيل المثال، عند التعامل مع Llama 3.3 من Meta، قد يعكس التخصيص على المستوى الأعمق الهيكل الموصى به الموضح في: +https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template + +إليك مثالاً يوضح كيف يمكنك ضبط Agent للاستفادة من Llama 3.3 في الكود: + +```python +from crewai import Agent, Crew, Task, Process +from crewai_tools import DirectoryReadTool, FileReadTool + +# Define templates for system, user (prompt), and assistant (response) messages +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|>""" + +# Create an Agent using Llama-specific layouts +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", # Using the Llama 3 model + system_template=system_template, + prompt_template=prompt_template, + response_template=response_template, + tools=[DirectoryReadTool(), FileReadTool()] +) + +# Define a sample task +engineering_task = Task( + description="Review AI implementation files for potential improvements", + expected_output="A summary of key findings and recommendations", + agent=principal_engineer +) + +# Create a Crew for the task +llama_crew = Crew( + agents=[principal_engineer], + tasks=[engineering_task], + process=Process.sequential, + verbose=True +) + +# Execute the crew +result = llama_crew.kickoff() +print(result.raw) +``` + +من خلال هذه التهيئة العميقة، يمكنك ممارسة تحكم شامل منخفض المستوى في سير العمل القائمة على Llama دون الحاجة إلى ملف JSON منفصل. + +## الخلاصة + +يفتح تخصيص المطالبات على المستوى المنخفض في CrewAI الباب أمام حالات استخدام مخصصة ومعقدة للغاية. من خلال إنشاء ملفات مطالبات منظمة (أو قوالب مضمّنة مباشرة)، يمكنك استيعاب نماذج ولغات ومجالات متخصصة متنوعة. يضمن هذا المستوى من المرونة أنك تستطيع صياغة سلوك الذكاء الاصطناعي الذي تحتاجه بالضبط، مع العلم أن CrewAI لا يزال يوفر إعدادات افتراضية موثوقة عندما لا تتجاوزها. + + +لديك الآن الأساس لتخصيصات المطالبات المتقدمة في CrewAI. سواء كنت تتكيف مع هياكل خاصة بالنموذج أو قيود خاصة بالمجال، يتيح لك هذا النهج المنخفض المستوى تشكيل تفاعلات الـ Agent بطرق متخصصة للغاية. + diff --git a/docs/v1.15.1/ar/guides/advanced/fingerprinting.mdx b/docs/v1.15.1/ar/guides/advanced/fingerprinting.mdx new file mode 100644 index 000000000..12599a88f --- /dev/null +++ b/docs/v1.15.1/ar/guides/advanced/fingerprinting.mdx @@ -0,0 +1,134 @@ +--- +title: البصمات الرقمية +description: تعلم كيفية استخدام نظام البصمات الرقمية في CrewAI لتحديد وتتبع المكونات بشكل فريد طوال دورة حياتها. +icon: fingerprint +mode: "wide" +--- + +## نظرة عامة + +توفر البصمات الرقمية في CrewAI طريقة لتحديد وتتبع المكونات بشكل فريد طوال دورة حياتها. يتلقى كل `Agent` و`Crew` و`Task` بصمة رقمية فريدة تلقائيًا عند الإنشاء، ولا يمكن تجاوزها يدويًا. + +يمكن استخدام هذه البصمات لـ: +- تدقيق وتتبع استخدام المكونات +- ضمان سلامة هوية المكونات +- إرفاق بيانات وصفية بالمكونات +- إنشاء سلسلة عمليات قابلة للتتبع + +## كيف تعمل البصمات الرقمية + +البصمة الرقمية هي نسخة من فئة `Fingerprint` من وحدة `crewai.security`. تحتوي كل بصمة على: + +- سلسلة UUID: معرّف فريد للمكون يتم إنشاؤه تلقائيًا ولا يمكن تعيينه يدويًا +- طابع زمني للإنشاء: متى تم إنشاء البصمة، يُعيَّن تلقائيًا ولا يمكن تعديله يدويًا +- بيانات وصفية: قاموس معلومات إضافية يمكن تخصيصه + +تُنشأ البصمات الرقمية وتُعيَّن تلقائيًا عند إنشاء المكون. يكشف كل مكون بصمته من خلال خاصية للقراءة فقط. + +## الاستخدام الأساسي + +### الوصول إلى البصمات الرقمية + +```python +from crewai import Agent, Crew, Task + +# Create components - fingerprints are automatically generated +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 +) + +# Access the fingerprints +agent_fingerprint = agent.fingerprint +crew_fingerprint = crew.fingerprint +task_fingerprint = task.fingerprint + +# Print the UUID strings +print(f"Agent fingerprint: {agent_fingerprint.uuid_str}") +print(f"Crew fingerprint: {crew_fingerprint.uuid_str}") +print(f"Task fingerprint: {task_fingerprint.uuid_str}") +``` + +### العمل مع البيانات الوصفية للبصمة + +يمكنك إضافة بيانات وصفية إلى البصمات لسياق إضافي: + +```python +# Add metadata to the agent's fingerprint +agent.security_config.fingerprint.metadata = { + "version": "1.0", + "department": "Data Science", + "project": "Customer Analysis" +} + +# Access the metadata +print(f"Agent metadata: {agent.fingerprint.metadata}") +``` + +## استمرارية البصمة + +صُممت البصمات لتبقى ثابتة دون تغيير طوال دورة حياة المكون. إذا عدّلت مكونًا، تظل البصمة كما هي: + +```python +original_fingerprint = agent.fingerprint.uuid_str + +# Modify the agent +agent.goal = "New goal for analysis" + +# The fingerprint remains unchanged +assert agent.fingerprint.uuid_str == original_fingerprint +``` + +## البصمات الحتمية + +بينما لا يمكنك تعيين UUID والطابع الزمني مباشرة، يمكنك إنشاء بصمات حتمية باستخدام طريقة `generate` مع بذرة: + +```python +from crewai.security import Fingerprint + +# Create a deterministic fingerprint using a seed string +deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id") + +# The same seed always produces the same fingerprint +same_fingerprint = Fingerprint.generate(seed="my-agent-id") +assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str + +# You can also set metadata +custom_fingerprint = Fingerprint.generate( + seed="my-agent-id", + metadata={"version": "1.0"} +) +``` + +## الاستخدام المتقدم + +### هيكل البصمة + +لكل بصمة الهيكل التالي: + +```python +from crewai.security import Fingerprint + +fingerprint = agent.fingerprint + +# UUID string - the unique identifier (auto-generated) +uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000" + +# Creation timestamp (auto-generated) +created_at = fingerprint.created_at # A datetime object + +# Metadata - for additional information (can be customized) +metadata = fingerprint.metadata # A dictionary, defaults to {} +``` diff --git a/docs/v1.15.1/ar/guides/agents/crafting-effective-agents.mdx b/docs/v1.15.1/ar/guides/agents/crafting-effective-agents.mdx new file mode 100644 index 000000000..c1c6b1db3 --- /dev/null +++ b/docs/v1.15.1/ar/guides/agents/crafting-effective-agents.mdx @@ -0,0 +1,453 @@ +--- +title: صياغة Agents فعّالة +description: تعلم أفضل الممارسات لتصميم Agents ذكاء اصطناعي قوية ومتخصصة تتعاون بفعالية لحل المشكلات المعقدة. +icon: robot +mode: "wide" +--- + +## فن وعلم تصميم الـ Agent + +في قلب CrewAI يكمن الـ Agent - كيان ذكاء اصطناعي متخصص مصمم لأداء أدوار محددة ضمن إطار تعاوني. بينما إنشاء Agents أساسية أمر بسيط، فإن صياغة Agents فعّالة حقًا تنتج نتائج استثنائية يتطلب فهم مبادئ التصميم الأساسية وأفضل الممارسات. + +سيساعدك هذا الدليل على إتقان فن تصميم الـ Agent، مما يمكّنك من إنشاء شخصيات AI متخصصة تتعاون بفعالية وتفكر بشكل نقدي وتنتج مخرجات عالية الجودة مصممة لاحتياجاتك المحددة. + +### لماذا يهم تصميم الـ Agent + +الطريقة التي تعرّف بها الـ Agents تؤثر بشكل كبير على: + +1. **جودة المخرجات**: الـ Agents المصممة جيدًا تنتج نتائج أكثر صلة وجودة +2. **فعالية التعاون**: الـ Agents ذات المهارات المكملة تعمل معًا بكفاءة أكبر +3. **أداء المهام**: الـ Agents ذات الأدوار والأهداف الواضحة تنفذ المهام بفعالية أكبر +4. **قابلية التوسع**: الـ Agents المصممة بعناية يمكن إعادة استخدامها عبر Crews وسياقات متعددة + +لنستكشف أفضل الممارسات لإنشاء Agents تتفوق في هذه الأبعاد. + +## قاعدة 80/20: ركّز على المهام أكثر من الـ Agents + +عند بناء أنظمة AI فعّالة، تذكر هذا المبدأ الحاسم: **80% من جهدك يجب أن يذهب لتصميم المهام، و20% فقط لتعريف الـ Agents**. + +لماذا؟ لأن حتى أفضل Agent معرّف سيفشل مع مهام مصممة بشكل سيئ، لكن المهام المصممة جيدًا يمكنها رفع مستوى حتى Agent بسيط. هذا يعني: + +- اقضِ معظم وقتك في كتابة تعليمات مهام واضحة +- حدد المدخلات والمخرجات المتوقعة بالتفصيل +- أضف أمثلة وسياقًا لتوجيه التنفيذ +- خصص الوقت المتبقي لدور Agent وهدفه وخلفيته + +هذا لا يعني أن تصميم الـ Agent ليس مهمًا - بل هو مهم بالتأكيد. لكن تصميم المهام هو حيث تحدث معظم إخفاقات التنفيذ، لذا رتّب أولوياتك وفقًا لذلك. + +## المبادئ الأساسية لتصميم Agent فعّال + +### 1. إطار الدور-الهدف-الخلفية + +أقوى الـ Agents في CrewAI مبنية على أساس قوي من ثلاثة عناصر رئيسية: + +#### الدور: الوظيفة المتخصصة للـ Agent + +يحدد الدور ما يفعله الـ Agent ومجال خبرته. عند صياغة الأدوار: + +- **كن محددًا ومتخصصًا**: بدلاً من "كاتب"، استخدم "متخصص في التوثيق التقني" أو "راوي قصص إبداعي" +- **تماشَ مع المهن الواقعية**: ابنِ الأدوار على نماذج مهنية معروفة +- **تضمين خبرة المجال**: حدد مجال معرفة الـ Agent (مثل "محلل مالي متخصص في اتجاهات السوق") + +**أمثلة على أدوار فعّالة:** +```yaml +role: "Senior UX Researcher specializing in user interview analysis" +role: "Full-Stack Software Architect with expertise in distributed systems" +role: "Corporate Communications Director specializing in crisis management" +``` + +#### الهدف: غرض الـ Agent ودافعه + +يوجه الهدف جهود الـ Agent ويشكّل عملية صنع القرار. الأهداف الفعّالة يجب أن: + +- **تكون واضحة ومركّزة على النتائج**: حدد ما يحاول الـ Agent تحقيقه +- **تؤكد على معايير الجودة**: تضمين توقعات حول جودة العمل +- **تتضمن معايير النجاح**: ساعد الـ Agent على فهم ما يعنيه "الجيد" + +**أمثلة على أهداف فعّالة:** +```yaml +goal: "Uncover actionable user insights by analyzing interview data and identifying recurring patterns, unmet needs, and improvement opportunities" +goal: "Design robust, scalable system architectures that balance performance, maintainability, and cost-effectiveness" +goal: "Craft clear, empathetic crisis communications that address stakeholder concerns while protecting organizational reputation" +``` + +#### الخلفية: تجربة الـ Agent ومنظوره + +تمنح الخلفية عمقًا لشخصية الـ Agent، مؤثرة في كيفية تعامله مع المشكلات وتفاعله مع الآخرين. الخلفيات الجيدة: + +- **تؤسس الخبرة والتجربة**: تشرح كيف اكتسب الـ Agent مهاراته +- **تحدد أسلوب العمل والقيم**: تصف كيف يتعامل الـ Agent مع عمله +- **تنشئ شخصية متماسكة**: تضمن أن جميع عناصر الخلفية تتماشى مع الدور والهدف + +**أمثلة على خلفيات فعّالة:** +```yaml +backstory: "You have spent 15 years conducting and analyzing user research for top tech companies. You have a talent for reading between the lines and identifying patterns that others miss. You believe that good UX is invisible and that the best insights come from listening to what users don't say as much as what they do say." + +backstory: "With 20+ years of experience building distributed systems at scale, you've developed a pragmatic approach to software architecture. You've seen both successful and failed systems and have learned valuable lessons from each. You balance theoretical best practices with practical constraints and always consider the maintenance and operational aspects of your designs." + +backstory: "As a seasoned communications professional who has guided multiple organizations through high-profile crises, you understand the importance of transparency, speed, and empathy in crisis response. You have a methodical approach to crafting messages that address concerns while maintaining organizational credibility." +``` + +### 2. المتخصصون أفضل من العموميين + +يؤدي الـ Agents أداءً أفضل بشكل ملحوظ عند منحهم أدوارًا متخصصة بدلاً من عامة. الـ Agent المركّز بشدة ينتج مخرجات أكثر دقة وصلة: + +**عام (أقل فعالية):** +```yaml +role: "Writer" +``` + +**متخصص (أكثر فعالية):** +```yaml +role: "Technical Blog Writer specializing in explaining complex AI concepts to non-technical audiences" +``` + +**فوائد التخصص:** +- فهم أوضح للمخرجات المتوقعة +- أداء أكثر اتساقًا +- توافق أفضل مع المهام المحددة +- قدرة محسّنة على إصدار أحكام خاصة بالمجال + +### 3. التوازن بين التخصص والمرونة + +الـ Agents الفعّالة تحقق التوازن الصحيح بين التخصص (القيام بشيء واحد بشكل ممتاز) والمرونة (التكيف مع مواقف متنوعة): + +- **تخصص في الدور، مرونة في التطبيق**: أنشئ Agents بمهارات متخصصة يمكن تطبيقها عبر سياقات متعددة +- **تجنب التعريفات الضيقة جدًا**: تأكد من أن الـ Agents يمكنها التعامل مع التنوعات ضمن مجال خبرتها +- **ضع في الاعتبار السياق التعاوني**: صمم Agents تكمّل تخصصاتها الـ Agents الأخرى التي ستعمل معها + +### 4. تعيين مستويات الخبرة المناسبة + +مستوى الخبرة الذي تعيّنه للـ Agent يشكّل كيفية تعامله مع المهام: + +- **Agents مبتدئة**: جيدة للمهام المباشرة والعصف الذهني والمسودات الأولية +- **Agents متوسطة**: مناسبة لمعظم المهام القياسية مع تنفيذ موثوق +- **Agents خبيرة**: الأفضل للمهام المعقدة والمتخصصة التي تتطلب عمقًا ودقة +- **Agents على مستوى عالمي**: محجوزة للمهام الحرجة حيث الجودة الاستثنائية مطلوبة + +اختر مستوى الخبرة المناسب بناءً على تعقيد المهمة ومتطلبات الجودة. لمعظم Crews التعاونية، غالبًا ما يعمل مزيج من مستويات الخبرة بشكل أفضل، مع تعيين خبرة أعلى للوظائف المتخصصة الأساسية. + +## أمثلة عملية: قبل وبعد + +لنلقِ نظرة على بعض أمثلة تعريفات الـ Agent قبل وبعد تطبيق أفضل الممارسات: + +### مثال 1: Agent إنشاء المحتوى + +**قبل:** +```yaml +role: "Writer" +goal: "Write good content" +backstory: "You are a writer who creates content for websites." +``` + +**بعد:** +```yaml +role: "B2B Technology Content Strategist" +goal: "Create compelling, technically accurate content that explains complex topics in accessible language while driving reader engagement and supporting business objectives" +backstory: "You have spent a decade creating content for leading technology companies, specializing in translating technical concepts for business audiences. You excel at research, interviewing subject matter experts, and structuring information for maximum clarity and impact. You believe that the best B2B content educates first and sells second, building trust through genuine expertise rather than marketing hype." +``` + +### مثال 2: Agent البحث + +**قبل:** +```yaml +role: "Researcher" +goal: "Find information" +backstory: "You are good at finding information online." +``` + +**بعد:** +```yaml +role: "Academic Research Specialist in Emerging Technologies" +goal: "Discover and synthesize cutting-edge research, identifying key trends, methodologies, and findings while evaluating the quality and reliability of sources" +backstory: "With a background in both computer science and library science, you've mastered the art of digital research. You've worked with research teams at prestigious universities and know how to navigate academic databases, evaluate research quality, and synthesize findings across disciplines. You're methodical in your approach, always cross-referencing information and tracing claims to primary sources before drawing conclusions." +``` + +## صياغة مهام فعّالة للـ Agents + +بينما تصميم الـ Agent مهم، تصميم المهام حاسم للتنفيذ الناجح. إليك أفضل الممارسات لتصميم مهام تهيئ الـ Agents للنجاح: + +### تشريح المهمة الفعّالة + +المهمة المصممة جيدًا لها مكونان رئيسيان يخدمان أغراضًا مختلفة: + +#### وصف المهمة: العملية +يجب أن يركز الوصف على ماذا تفعل وكيف تفعله، بما في ذلك: +- تعليمات مفصلة للتنفيذ +- سياق ومعلومات خلفية +- النطاق والقيود +- خطوات العملية المتبعة + +#### المخرجات المتوقعة: التسليم +يجب أن تحدد المخرجات المتوقعة شكل النتيجة النهائية: +- مواصفات التنسيق (markdown، JSON، إلخ) +- متطلبات الهيكل +- معايير الجودة +- أمثلة على مخرجات جيدة (عند الإمكان) + +### أفضل ممارسات تصميم المهام + +#### 1. غرض واحد، مخرج واحد +تؤدي المهام أفضل أداء عند التركيز على هدف واضح واحد: + +**مثال سيئ (واسع جدًا):** +```yaml +task_description: "Research market trends, analyze the data, and create a visualization." +``` + +**مثال جيد (مركّز):** +```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. كن صريحًا بشأن المدخلات والمخرجات +حدد دائمًا بوضوح ما المدخلات التي ستستخدمها المهمة وكيف يجب أن تبدو المخرجات: + +**مثال:** +```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. تضمين الغرض والسياق +اشرح لماذا تهم المهمة وكيف تتناسب مع سير العمل الأكبر: + +**مثال:** +```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. استخدام أدوات المخرجات المنظمة +للمخرجات القابلة للقراءة آليًا، حدد التنسيق بوضوح: + +**مثال:** +```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." +``` + +## أخطاء شائعة يجب تجنبها + +بناءً على الدروس المستفادة من التطبيقات الواقعية، إليك أكثر المزالق شيوعًا في تصميم الـ Agent والمهام: + +### 1. تعليمات مهام غير واضحة + +**المشكلة:** تفتقر المهام لتفاصيل كافية مما يصعّب على الـ Agents تنفيذها بفعالية. + +**مثال تصميم سيئ:** +```yaml +research_task: + description: "Research AI trends." + expected_output: "A report on AI trends." +``` + +**نسخة محسّنة:** +```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. "مهام إلهية" تحاول فعل الكثير + +**المشكلة:** مهام تجمع عمليات معقدة متعددة في مجموعة تعليمات واحدة. + +**مثال تصميم سيئ:** +```yaml +comprehensive_task: + description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline." +``` + +**نسخة محسّنة:** +قسّمها إلى مهام متسلسلة ومركّزة: +```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. عدم توافق الوصف والمخرجات المتوقعة + +**المشكلة:** وصف المهمة يطلب شيئًا بينما المخرجات المتوقعة تحدد شيئًا مختلفًا. + +**مثال تصميم سيئ:** +```yaml +analysis_task: + description: "Analyze customer feedback to find areas of improvement." + expected_output: "A marketing plan for the next quarter." +``` + +**نسخة محسّنة:** +```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. عدم فهم العملية بنفسك + +**المشكلة:** مطالبة الـ Agents بتنفيذ مهام لا تفهمها أنت بالكامل. + +**الحل:** +1. حاول تنفيذ المهمة يدويًا أولاً +2. وثّق عمليتك ونقاط القرار ومصادر المعلومات +3. استخدم هذا التوثيق كأساس لوصف مهمتك + +### 5. الاستخدام المبكر للهياكل الهرمية + +**المشكلة:** إنشاء هرميات Agents معقدة بلا داعٍ حيث تعمل العمليات المتسلسلة بشكل أفضل. + +**الحل:** ابدأ بالعمليات المتسلسلة وانتقل إلى النماذج الهرمية فقط عندما يتطلب تعقيد سير العمل ذلك حقًا. + +### 6. تعريفات Agent غامضة أو عامة + +**المشكلة:** تعريفات Agent العامة تؤدي لمخرجات عامة. + +**مثال تصميم سيئ:** +```yaml +agent: + role: "Business Analyst" + goal: "Analyze business data" + backstory: "You are good at business analysis." +``` + +**نسخة محسّنة:** +```yaml +agent: + role: "SaaS Metrics Specialist focusing on growth-stage startups" + goal: "Identify actionable insights from business data that can directly impact customer retention and revenue growth" + backstory: "With 10+ years analyzing SaaS business models, you've developed a keen eye for the metrics that truly matter for sustainable growth. You've helped numerous companies identify the leverage points that turned around their business trajectory. You believe in connecting data to specific, actionable recommendations rather than general observations." +``` + +## استراتيجيات متقدمة لتصميم الـ Agent + +### التصميم للتعاون + +عند إنشاء Agents ستعمل معًا في Crew، ضع في اعتبارك: + +- **مهارات مكملة**: صمم Agents بقدرات مميزة ومكملة +- **نقاط التسليم**: حدد واجهات واضحة لكيفية انتقال العمل بين الـ Agents +- **توتر بنّاء**: أحيانًا، إنشاء Agents بمنظورات مختلفة قليلاً يمكن أن يؤدي لنتائج أفضل من خلال حوار منتج + +على سبيل المثال، قد يتضمن Crew إنشاء محتوى: + +```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..." +``` + +### إنشاء مستخدمي أدوات متخصصين + +يمكن تصميم بعض الـ Agents خصيصًا للاستفادة من أدوات معينة بفعالية: + +```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] +``` + +### تكييف الـ Agents مع قدرات LLM + +للنماذج المختلفة نقاط قوة مختلفة. صمم الـ Agents مع وضع هذه القدرات في الاعتبار: + +```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 +``` + +## اختبار تصميم الـ Agent والتكرار عليه + +تصميم الـ Agent غالبًا عملية تكرارية. إليك نهجًا عمليًا: + +1. **ابدأ بنموذج أولي**: أنشئ تعريف Agent أولي +2. **اختبر مع مهام نموذجية**: قيّم الأداء على مهام تمثيلية +3. **حلل المخرجات**: حدد نقاط القوة والضعف +4. **صقل التعريف**: اضبط الدور والهدف والخلفية بناءً على الملاحظات +5. **اختبر في بيئة تعاونية**: قيّم كيف يعمل الـ Agent في إعداد Crew + +## الخلاصة + +صياغة Agents فعّالة هي فن وعلم في آن واحد. من خلال تعريف الأدوار والأهداف والخلفيات بعناية بما يتماشى مع احتياجاتك المحددة، ودمجها مع مهام مصممة جيدًا، يمكنك إنشاء متعاونين AI متخصصين ينتجون نتائج استثنائية. + +تذكر أن تصميم الـ Agent والمهام عملية تكرارية. ابدأ بأفضل الممارسات هذه، وراقب الـ Agents أثناء العمل، وصقل نهجك بناءً على ما تتعلمه. وتذكر دائمًا قاعدة 80/20 - ركّز معظم جهدك على إنشاء مهام واضحة ومركّزة للحصول على أفضل النتائج من الـ Agents. + + +تهانينا! أنت الآن تفهم مبادئ وممارسات تصميم Agent الفعّال. طبّق هذه التقنيات لإنشاء Agents قوية ومتخصصة تعمل معًا بسلاسة لإنجاز مهام معقدة. + + +## الخطوات التالية + +- جرّب تهيئات Agent مختلفة لحالة استخدامك المحددة +- تعلم عن [بناء أول Crew](/ar/guides/crews/first-crew) لمعرفة كيف تعمل الـ Agents معًا +- استكشف [CrewAI Flows](/ar/guides/flows/first-flow) لتنسيق أكثر تقدمًا diff --git a/docs/v1.15.1/ar/guides/coding-tools/agents-md.mdx b/docs/v1.15.1/ar/guides/coding-tools/agents-md.mdx new file mode 100644 index 000000000..e118b72eb --- /dev/null +++ b/docs/v1.15.1/ar/guides/coding-tools/agents-md.mdx @@ -0,0 +1,61 @@ +--- +title: أدوات البرمجة +description: استخدم AGENTS.md لتوجيه أدوات البرمجة وبيئات التطوير عبر مشاريع CrewAI. +icon: terminal +mode: "wide" +--- + +## لماذا AGENTS.md + +`AGENTS.md` هو ملف تعليمات خفيف محلي للمستودع يمنح أدوات البرمجة توجيهات متسقة خاصة بالمشروع. ضعه في جذر المشروع واعتبره المصدر الموثوق لكيفية عمل المساعدين: الاصطلاحات والأوامر وملاحظات البنية والحدود. + +## إنشاء مشروع باستخدام CLI + +استخدم CLI الخاص بـ CrewAI لإنشاء هيكل مشروع، وسيُضاف `AGENTS.md` تلقائيًا في الجذر. + +```bash +# Crew +crewai create crew my_crew + +# Flow +crewai create flow my_flow + +# Tool repository +crewai tool create my_tool +``` + +## إعداد الأدوات: توجيه المساعدين إلى AGENTS.md + +### Codex + +يمكن توجيه Codex بملفات `AGENTS.md` الموضوعة في مستودعك. استخدمها لتوفير سياق مشروع مستمر مثل الاصطلاحات والأوامر وتوقعات سير العمل. + +### Claude Code + +يخزّن Claude Code ذاكرة المشروع في `CLAUDE.md`. يمكنك تهيئته بـ `/init` وتحريره باستخدام `/memory`. يدعم Claude Code أيضًا الاستيرادات داخل `CLAUDE.md`، فيمكنك إضافة سطر واحد مثل `@AGENTS.md` لسحب التعليمات المشتركة دون تكرارها. + +يمكنك ببساطة استخدام: + +```bash +mv AGENTS.md CLAUDE.md +``` + +### Gemini CLI وGoogle Antigravity + +يقوم Gemini CLI وAntigravity بتحميل ملف سياق المشروع (الافتراضي: `GEMINI.md`) من جذر المستودع والمجلدات الأصلية. يمكنك تهيئته لقراءة `AGENTS.md` بدلاً من ذلك (أو بالإضافة إليه) بتعيين `context.fileName` في إعدادات Gemini CLI. على سبيل المثال، عيّنه إلى `AGENTS.md` فقط، أو أدرج كلاً من `AGENTS.md` و`GEMINI.md` إذا أردت الاحتفاظ بتنسيق كل أداة. + +يمكنك ببساطة استخدام: + +```bash +mv AGENTS.md GEMINI.md +``` + +### Cursor + +يدعم Cursor ملف `AGENTS.md` كملف تعليمات مشروع. ضعه في جذر المشروع لتوفير توجيهات لمساعد البرمجة في Cursor. + +### Windsurf + +يوفر Claude Code تكاملاً رسميًا مع Windsurf. إذا كنت تستخدم Claude Code داخل Windsurf، اتبع توجيهات Claude Code أعلاه واستورد `AGENTS.md` من `CLAUDE.md`. + +إذا كنت تستخدم مساعد Windsurf الأصلي، هيّئ ميزة قواعد أو تعليمات المشروع (إذا كانت متاحة) لقراءة `AGENTS.md` أو الصق المحتويات مباشرة. diff --git a/docs/v1.15.1/ar/guides/coding-tools/build-with-ai.mdx b/docs/v1.15.1/ar/guides/coding-tools/build-with-ai.mdx new file mode 100644 index 000000000..fa459655d --- /dev/null +++ b/docs/v1.15.1/ar/guides/coding-tools/build-with-ai.mdx @@ -0,0 +1,214 @@ +--- +title: "البناء باستخدام الذكاء الاصطناعي" +description: "كل ما يحتاجه وكلاء البرمجة بالذكاء الاصطناعي للبناء والنشر والتوسع مع CrewAI — المهارات، وثائق مقروءة آلياً، النشر، وميزات المؤسسات." +icon: robot +mode: "wide" +--- + +# البناء باستخدام الذكاء الاصطناعي + +CrewAI مُصمَّم أصلاً للعمل مع الذكاء الاصطناعي. تجمع هذه الصفحة ما يحتاجه وكيل البرمجة بالذكاء الاصطناعي للبناء مع CrewAI — سواءً كان Claude Code أو Codex أو Cursor أو Gemini CLI أو أي مساعد آخر يساعد المطوّر على إيصال الـ crews والـ flows. + +### وكلاء البرمجة المدعومون + + + + + + + + + + + صُممت هذه الصفحة للبشر وللمساعدين الذكيين على حدٍّ سواء. إذا كنت وكيل برمجة، ابدأ بـ **Skills** للحصول على سياق CrewAI، ثم استخدم **llms.txt** للوصول الكامل إلى الوثائق. + + +--- + +## 1. Skills — علِّم وكيلك CrewAI + +**Skills** حزم تعليمات تمنح وكلاء البرمجة معرفة عميقة بـ CrewAI — كيفية إنشاء هيكل Flows، وضبط Crews، استخدام الأدوات، واتباع اتفاقيات الإطار. + + + + Anthropic + مهارات CrewAI متاحة في **سوق إضافات Claude Code** — نفس قناة التوزيع التي تستخدمها شركات رائدة في مجال الذكاء الاصطناعي: + ```shell + /plugin marketplace add crewAIInc/skills + /plugin install crewai-skills@crewai-plugins + /reload-plugins + ``` + + تُفعَّل أربع مهارات تلقائياً عند طرح أسئلة متعلقة بـ CrewAI: + + | المهارة | متى تُستخدم | + |---------|-------------| + | `getting-started` | مشاريع جديدة، الاختيار بين `LLM.call()` / `Agent` / `Crew` / `Flow`، ربط `crew.jsonc` / `main.py` | + | `design-agent` | ضبط الوكلاء — الدور، الهدف، الخلفية، الأدوات، نماذج اللغة، الذاكرة، الحدود الآمنة | + | `design-task` | وصف المهام، التبعيات، المخرجات المنظمة (`output_pydantic`، `output_json`)، المراجعة البشرية | + | `ask-docs` | الاستعلام من [خادم CrewAI docs MCP](https://docs.crewai.com/mcp) للحصول على تفاصيل واجهة البرمجة الحالية | + + + يعمل مع Claude Code أو Codex أو Cursor أو Gemini CLI أو أي وكيل برمجة: + ```shell + npx skills add crewaiinc/skills + ``` + يُجلب من [سجل skills.sh](https://skills.sh/crewaiinc/skills). + + + + + + استخدم إحدى الطريقتين أعلاه — سوق إضافات Claude Code أو `npx skills add`. كلاهما يثبّت الحزمة الرسمية [crewAIInc/skills](https://github.com/crewAIInc/skills). + + + تعلّم الحزمة وكيلك: + - **Flows** — تطبيقات ذات حالة، خطوات، وتشغيل crews + - **Crews والوكلاء** — أنماط JSON-first (`crew.jsonc` و `agents/*.jsonc`)، الأدوار، المهام، التفويض + - **الأدوات والتكاملات** — البحث، واجهات API، خوادم MCP، وأدوات CrewAI الشائعة + - **هيكل المشروع** — هياكل CLI واتفاقيات المستودع + - **أنماط محدثة** — يتماشى مع وثائق CrewAI الحالية وأفضل الممارسات + + + يمكن لوكيلك الآن إنشاء هيكل وبناء مشاريع CrewAI دون أن تعيد شرح الإطار في كل جلسة. + + + + + + كيف تعمل المهارات في وكلاء CrewAI — الحقن، التفعيل، والأنماط. + + + نظرة على حزمة crewAIInc/skills وما تتضمنه. + + + إعداد AGENTS.md لـ Claude Code وCodex وCursor وGemini CLI. + + + القائمة الرسمية — المهارات، إحصاءات التثبيت، والتدقيق. + + + +--- + +## 2. llms.txt — وثائق مقروءة آلياً + +ينشر CrewAI ملف `llms.txt` يمنح المساعدين الذكيين وصولاً مباشراً إلى الوثائق الكاملة بصيغة مقروءة آلياً. + +``` +https://docs.crewai.com/llms.txt +``` + + + + [`llms.txt`](https://llmstxt.org/) معيار ناشئ لجعل الوثائق قابلة للاستهلاك من قبل نماذج اللغة الكبيرة. بدلاً من استخراج HTML، يمكن لوكيلك جلب ملف نصي واحد منظم بكل المحتوى المطلوب. + + ملف `llms.txt` الخاص بـ CrewAI **متاح فعلياً** — يمكن لوكيلك استخدامه الآن. + + + وجِّه وكيل البرمجة إلى عنوان URL عندما يحتاج إلى مرجع CrewAI: + + ``` + Fetch https://docs.crewai.com/llms.txt for CrewAI documentation. + ``` + + يمكن للعديد من وكلاء البرمجة (Claude Code، Cursor، وغيرهما) جلب عناوين URL مباشرة. يحتوي الملف على وثائق منظمة تغطي مفاهيم CrewAI وواجهات البرمجة والأدلة. + + + - **دون استخراج ويب** — محتوى نظيف ومنظم في طلب واحد + - **دائماً محدث** — يُقدَّم مباشرة من docs.crewai.com + - **محسّن لنماذج اللغة** — مُنسَّق لنوافذ السياق لا للمتصفحات + - **يُكمّل Skills** — المهارات تعلّم الأنماط، وllms.txt يوفّر المرجع + + + +--- + +## 3. النشر للمؤسسات + +انتقل من crew محلي إلى الإنتاج على **CrewAI AMP** (منصة إدارة الوكلاء) في دقائق. + + + + أنشئ الهيكل واختبر crew أو flow: + ```bash + crewai create crew my_crew + cd my_crew + crewai run + ``` + + + تأكد أن هيكل مشروعك جاهز: + ```bash + crewai deploy --prepare + ``` + راجع [دليل التحضير](/ar/enterprise/guides/prepare-for-deployment) لتفاصيل الهيكل والمتطلبات. + + + ادفع إلى منصة CrewAI AMP: + ```bash + crewai deploy + ``` + يمكنك أيضاً النشر عبر [تكامل GitHub](/ar/enterprise/guides/deploy-to-amp) أو [Crew Studio](/ar/enterprise/guides/enable-crew-studio). + + + يحصل الـ crew المنشور على نقطة نهاية REST. دمجه في أي تطبيق: + ```bash + curl -X POST https://app.crewai.com/api/v1/crews//kickoff \ + -H "Authorization: Bearer $CREWAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"inputs": {"topic": "AI agents"}}' + ``` + + + + + + دليل النشر الكامل — CLI وGitHub وCrew Studio. + + + نظرة على المنصة — ما يوفّره AMP لـ crews في الإنتاج. + + + +--- + +## 4. ميزات المؤسسات + +CrewAI AMP مُصمَّم لفرق الإنتاج. إليك ما تحصل عليه بعد النشر. + + + + مسارات تنفيذ مفصّلة، وسجلات، ومقاييس أداء لكل تشغيل crew. راقب قرارات الوكلاء، استدعاءات الأدوات، وإكمال المهام في الوقت الفعلي. + + + واجهة منخفضة/بدون كود لإنشاء crews وتخصيصها ونشرها بصرياً — ثم التصدير إلى الشيفرة أو النشر مباشرة. + + + بث أحداث فورية من تنفيذات الـ crews إلى أنظمتك. تكامل مع Slack أو Zapier أو أي مستهلك ويبهوك. + + + SSO وRBAC وضوابط على مستوى المؤسسة. أدر من يمكنه إنشاء crews ونشرها والوصول إليها. + + + انشر وشارك أدواتاً مخصصة عبر مؤسستك. ثبّت أدوات المجتمع من السجل. + + + شغّل CrewAI AMP على بنيتك التحتية. قدرات المنصة كاملة مع ضوابط إقامة البيانات والامتثال. + + + + + + لفرق تحتاج نقل سير عمل وكلاء الذكاء الاصطناعي من النماذج الأولية إلى الإنتاج — مع المراقبة وضوابط الوصول والبنية التحتية القابلة للتوسع. سواءً كنت ناشئاً أو مؤسسة كبيرة، يتولى AMP التعقيد التشغيلي لتتفرغ لبناء الوكلاء. + + + - **السحابة (app.crewai.com)** — تُدار من CrewAI، أسرع طريق إلى الإنتاج + - **Factory (استضافة ذاتية)** — على بنيتك التحتية لسيطرة كاملة على البيانات + - **هجين** — دمج السحابة والاستضافة الذاتية حسب حساسية البيانات + + + + + سجّل وانشر أول crew لك في الإنتاج. + diff --git a/docs/v1.15.1/ar/guides/concepts/evaluating-use-cases.mdx b/docs/v1.15.1/ar/guides/concepts/evaluating-use-cases.mdx new file mode 100644 index 000000000..a0a3d5f42 --- /dev/null +++ b/docs/v1.15.1/ar/guides/concepts/evaluating-use-cases.mdx @@ -0,0 +1,485 @@ +--- +title: تقييم حالات الاستخدام لـ CrewAI +description: تعلم كيفية تقييم احتياجات تطبيقات الذكاء الاصطناعي واختيار النهج الصحيح بين Crews وFlows بناءً على متطلبات التعقيد والدقة. +icon: scale-balanced +mode: "wide" +--- + +## فهم إطار القرار + +عند بناء تطبيقات ذكاء اصطناعي مع CrewAI، أحد أهم القرارات التي ستتخذها هو اختيار النهج الصحيح لحالة الاستخدام المحددة. هل يجب استخدام Crew؟ أم Flow؟ أم مزيج من كليهما؟ سيساعدك هذا الدليل على تقييم متطلباتك واتخاذ قرارات معمارية مدروسة. + +في جوهر هذا القرار فهم العلاقة بين **التعقيد** و**الدقة** في تطبيقك: + + + مصفوفة التعقيد مقابل الدقة + + +تساعد هذه المصفوفة في تصور كيف تتوافق النهج المختلفة مع متطلبات متفاوتة للتعقيد والدقة. لنستكشف ما يعنيه كل ربع وكيف يوجه خياراتك المعمارية. + +## شرح مصفوفة التعقيد-الدقة + +### ما هو التعقيد؟ + +في سياق تطبيقات CrewAI، يشير **التعقيد** إلى: + +- عدد الخطوات أو العمليات المميزة المطلوبة +- تنوع المهام التي يجب تنفيذها +- التبعيات المتبادلة بين المكونات المختلفة +- الحاجة للمنطق الشرطي والتفرع +- تطور سير العمل الكلي + +### ما هي الدقة؟ + +**الدقة** في هذا السياق تشير إلى: + +- الدقة المطلوبة في المخرجات النهائية +- الحاجة لنتائج منظمة وقابلة للتنبؤ +- أهمية إمكانية التكرار +- مستوى التحكم المطلوب في كل خطوة +- تحمّل التباين في المخرجات + +### الأرباع الأربعة + +#### 1. تعقيد منخفض، دقة منخفضة + +**الخصائص:** +- مهام بسيطة ومباشرة +- تحمّل بعض التباين في المخرجات +- عدد محدود من الخطوات +- تطبيقات إبداعية أو استكشافية + +**النهج الموصى به:** Crews بسيطة مع عدد قليل من الـ Agents + +**أمثلة على حالات الاستخدام:** +- إنشاء محتوى أساسي +- العصف الذهني +- مهام التلخيص البسيطة +- مساعدة الكتابة الإبداعية + +#### 2. تعقيد منخفض، دقة عالية + +**الخصائص:** +- سير عمل بسيطة تتطلب مخرجات دقيقة ومنظمة +- حاجة لنتائج قابلة للتكرار +- خطوات محدودة مع متطلبات دقة عالية +- غالبًا تتضمن معالجة أو تحويل بيانات + +**النهج الموصى به:** Flows مع استدعاءات LLM مباشرة أو Crews بسيطة مع مخرجات منظمة + +**أمثلة على حالات الاستخدام:** +- استخراج البيانات وتحويلها +- ملء النماذج والتحقق منها +- إنشاء محتوى منظم (JSON، XML) +- مهام التصنيف البسيطة + +#### 3. تعقيد عالٍ، دقة منخفضة + +**الخصائص:** +- عمليات متعددة المراحل بخطوات كثيرة +- مخرجات إبداعية أو استكشافية +- تفاعلات معقدة بين المكونات +- تحمّل التباين في النتائج النهائية + +**النهج الموصى به:** Crews معقدة مع عدة Agents متخصصة + +**أمثلة على حالات الاستخدام:** +- البحث والتحليل +- خطوط إنتاج المحتوى +- تحليل البيانات الاستكشافي +- حل المشكلات الإبداعي + +#### 4. تعقيد عالٍ، دقة عالية + +**الخصائص:** +- سير عمل معقدة تتطلب مخرجات منظمة +- خطوات مترابطة متعددة مع متطلبات دقة صارمة +- حاجة لمعالجة متطورة ونتائج دقيقة معًا +- غالبًا تطبيقات حرجة المهمة + +**النهج الموصى به:** Flows تنسّق عدة Crews مع خطوات تحقق + +**أمثلة على حالات الاستخدام:** +- أنظمة دعم القرار المؤسسية +- خطوط معالجة بيانات معقدة +- معالجة مستندات متعددة المراحل +- تطبيقات الصناعات المنظمة + +## الاختيار بين Crews وFlows + +### متى تختار Crews + +الـ Crews مثالية عندما: + +1. **تحتاج ذكاء تعاوني** - عدة Agents بتخصصات مختلفة تحتاج للعمل معًا +2. **المشكلة تتطلب تفكيرًا ناشئًا** - الحل يستفيد من منظورات ونُهج مختلفة +3. **المهمة إبداعية أو تحليلية بالأساس** - العمل يتضمن بحثًا أو إنشاء محتوى أو تحليل +4. **تقدّر القدرة على التكيف على الهيكل الصارم** - سير العمل يمكن أن يستفيد من استقلالية الـ Agent +5. **تنسيق المخرجات يمكن أن يكون مرنًا نوعًا ما** - بعض التباين في هيكل المخرجات مقبول + +```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() +``` + +### متى تختار Flows + +الـ Flows مثالية عندما: + +1. **تحتاج تحكمًا دقيقًا في التنفيذ** - سير العمل يتطلب تسلسلًا دقيقًا وإدارة حالة +2. **التطبيق له متطلبات حالة معقدة** - تحتاج لصيانة وتحويل الحالة عبر خطوات متعددة +3. **تحتاج مخرجات منظمة وقابلة للتنبؤ** - التطبيق يتطلب نتائج متسقة ومنسّقة +4. **سير العمل يتضمن منطقًا شرطيًا** - مسارات مختلفة يجب اتخاذها بناءً على نتائج وسيطة +5. **تحتاج الجمع بين AI وكود إجرائي** - الحل يتطلب قدرات AI وبرمجة تقليدية معًا + +```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): + 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, _): + 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): + return category.lower().replace(" ", "_") + + @listen("billing") + def handle_billing_issue(self): + self.state.priority = "high" + return "Billing issue handled" + + @listen("account_access") + def handle_access_issue(self): + self.state.priority = "high" + return "Access issue handled" + + @listen("billing", "account_access", "technical_issue", "feature_request", "other") + def resolve_ticket(self, resolution_info): + self.state.resolution = f"Issue resolved: {resolution_info}" + return self.state.resolution + +# Run the flow +support_flow = CustomerSupportFlow() +result = support_flow.kickoff() +``` + +### متى تجمع بين Crews وFlows + +أكثر التطبيقات تطورًا غالبًا تستفيد من الجمع بين Crews وFlows: + +1. **عمليات معقدة متعددة المراحل** - استخدم Flows لتنسيق العملية الكلية وCrews للمهام الفرعية المعقدة +2. **تطبيقات تتطلب إبداعًا وهيكلاً معًا** - استخدم Crews للمهام الإبداعية وFlows للمعالجة المنظمة +3. **تطبيقات AI مؤسسية** - استخدم Flows لإدارة الحالة وتدفق العمليات مع الاستفادة من Crews للعمل المتخصص + +```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): + 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, _): + 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 + ) + + result = outline_crew.kickoff() + + import json + try: + self.state.outline = json.loads(result.raw) + except: + self.state.outline = {"sections": result.raw} + + return "Outline created" + + @listen(create_outline) + def write_content(self, _): + 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 + ) + + result = writing_crew.kickoff() + self.state.final_content = result.raw + + return "Content created" + + @listen(write_content) + def optimize_for_seo(self, _): + 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) + + 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() +``` + +## إطار التقييم العملي + +لتحديد النهج الصحيح لحالة استخدامك المحددة، اتبع إطار التقييم التدريجي هذا: + +### الخطوة 1: تقييم التعقيد + +قيّم تعقيد تطبيقك على مقياس من 1-10 من خلال النظر في: + +1. **عدد الخطوات**: كم عدد العمليات المميزة المطلوبة؟ + - 1-3 خطوات: تعقيد منخفض (1-3) + - 4-7 خطوات: تعقيد متوسط (4-7) + - 8+ خطوات: تعقيد عالٍ (8-10) + +2. **التبعيات المتبادلة**: ما مدى ترابط الأجزاء المختلفة؟ + - تبعيات قليلة: تعقيد منخفض (1-3) + - بعض التبعيات: تعقيد متوسط (4-7) + - تبعيات معقدة كثيرة: تعقيد عالٍ (8-10) + +3. **المنطق الشرطي**: ما مقدار التفرع وصنع القرار المطلوب؟ + - عملية خطية: تعقيد منخفض (1-3) + - بعض التفرع: تعقيد متوسط (4-7) + - أشجار قرار معقدة: تعقيد عالٍ (8-10) + +4. **المعرفة التخصصية**: ما مدى تخصص المعرفة المطلوبة؟ + - معرفة عامة: تعقيد منخفض (1-3) + - بعض المعرفة المتخصصة: تعقيد متوسط (4-7) + - خبرة عميقة في مجالات متعددة: تعقيد عالٍ (8-10) + +احسب متوسط درجتك لتحديد التعقيد الكلي. + +### الخطوة 2: تقييم متطلبات الدقة + +قيّم متطلبات الدقة على مقياس من 1-10 من خلال النظر في: + +1. **هيكل المخرجات**: ما مدى التنظيم المطلوب في المخرجات؟ + - نص حر: دقة منخفضة (1-3) + - شبه منظم: دقة متوسطة (4-7) + - منسّق بشكل صارم (JSON، XML): دقة عالية (8-10) + +2. **احتياجات الدقة**: ما أهمية الدقة الواقعية؟ + - محتوى إبداعي: دقة منخفضة (1-3) + - محتوى معلوماتي: دقة متوسطة (4-7) + - معلومات حرجة: دقة عالية (8-10) + +3. **إمكانية التكرار**: ما مدى اتساق النتائج عبر التشغيلات؟ + - التباين مقبول: دقة منخفضة (1-3) + - بعض الاتساق مطلوب: دقة متوسطة (4-7) + - تكرار دقيق مطلوب: دقة عالية (8-10) + +4. **تحمّل الأخطاء**: ما تأثير الأخطاء؟ + - تأثير منخفض: دقة منخفضة (1-3) + - تأثير معتدل: دقة متوسطة (4-7) + - تأثير عالٍ: دقة عالية (8-10) + +احسب متوسط درجتك لتحديد متطلبات الدقة الكلية. + +### الخطوة 3: التعيين على المصفوفة + +ارسم درجات التعقيد والدقة على المصفوفة: + +- **تعقيد منخفض (1-4)، دقة منخفضة (1-4)**: Crews بسيطة +- **تعقيد منخفض (1-4)، دقة عالية (5-10)**: Flows مع استدعاءات LLM مباشرة +- **تعقيد عالٍ (5-10)، دقة منخفضة (1-4)**: Crews معقدة +- **تعقيد عالٍ (5-10)، دقة عالية (5-10)**: Flows تنسّق Crews + +### الخطوة 4: مراعاة عوامل إضافية + +بالإضافة إلى التعقيد والدقة، ضع في اعتبارك: + +1. **وقت التطوير**: غالبًا ما تكون Crews أسرع في النماذج الأولية +2. **احتياجات الصيانة**: توفر Flows قابلية صيانة أفضل على المدى الطويل +3. **خبرة الفريق**: ضع في اعتبارك ألفة فريقك مع النُهج المختلفة +4. **متطلبات التوسع**: عادةً ما تتوسع Flows بشكل أفضل للتطبيقات المعقدة +5. **احتياجات التكامل**: ضع في اعتبارك كيف سيتكامل الحل مع الأنظمة الحالية + +## الخلاصة + +الاختيار بين Crews وFlows — أو الجمع بينهما — قرار معماري حاسم يؤثر على فعالية وقابلية صيانة وتوسع تطبيق CrewAI. من خلال تقييم حالة الاستخدام على أبعاد التعقيد والدقة، يمكنك اتخاذ قرارات مدروسة تتماشى مع متطلباتك المحددة. + +تذكر أن أفضل نهج غالبًا يتطور مع نضج تطبيقك. ابدأ بأبسط حل يلبي احتياجاتك، وكن مستعدًا لصقل بنيتك مع اكتساب الخبرة ووضوح المتطلبات. + + +لديك الآن إطار لتقييم حالات استخدام CrewAI واختيار النهج الصحيح بناءً على متطلبات التعقيد والدقة. سيساعدك هذا في بناء تطبيقات AI أكثر فعالية وقابلية للصيانة والتوسع. + + +## الخطوات التالية + +- تعلم المزيد عن [صياغة Agents فعّالة](/ar/guides/agents/crafting-effective-agents) +- استكشف [بناء أول Crew](/ar/guides/crews/first-crew) +- تعمّق في [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state) +- اطلع على [المفاهيم الأساسية](/ar/concepts/agents) لفهم أعمق diff --git a/docs/v1.15.1/ar/guides/crews/first-crew.mdx b/docs/v1.15.1/ar/guides/crews/first-crew.mdx new file mode 100644 index 000000000..db07c6ff9 --- /dev/null +++ b/docs/v1.15.1/ar/guides/crews/first-crew.mdx @@ -0,0 +1,140 @@ +--- +title: ابنِ أول Crew +description: دليل خطوة بخطوة لإنشاء فريق AI تعاوني باستخدام تهيئة JSON-first. +icon: users-gear +mode: "wide" +--- + +## بناء Crew للبحث + +في هذا الدليل ستنشئ crew من Agentين: واحد للبحث وآخر لكتابة تقرير markdown. مشاريع الـ crew الجديدة هي JSON-first: تُعرّف الـ Agents في `agents/*.jsonc`، وتُعرّف المهام وإعدادات الـ crew في `crew.jsonc`، ويحمّل `crewai run` هذا التعريف مباشرة. + +### المتطلبات + +1. تثبيت CrewAI من [دليل التثبيت](/ar/installation) +2. إعداد مفتاح LLM من [دليل LLMs](/ar/concepts/llms#setting-up-your-llm) +3. مفتاح [Serper.dev](https://serper.dev/) إذا أردت استخدام البحث على الويب + +## الخطوة 1: إنشاء Crew جديدة + +```bash +crewai create crew research_crew +cd research_crew +``` + +البنية الناتجة: + +```text +research_crew/ +├── .gitignore +├── .env +├── agents/ +│ └── researcher.jsonc +├── crew.jsonc +├── knowledge/ +├── pyproject.toml +├── README.md +├── skills/ +└── tools/ +``` + + +إذا احتجت إلى البنية القديمة التي تحتوي على `crew.py` و `config/agents.yaml` و `config/tasks.yaml`، استخدم `crewai create crew research_crew --classic`. + + +## الخطوة 2: تعريف الـ Agents + +عدّل ملف `agents/researcher.jsonc` الذي أنشأه القالب، ثم أضف `agents/analyst.jsonc`. يجب أن تطابق أسماء الملفات الأسماء المشار إليها في `crew.jsonc`. + +```jsonc agents/researcher.jsonc +{ + "role": "Senior Research Specialist for {topic}", + "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.", + "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.", + // استبدله بالنموذج الذي تستخدمه، مثل "openai/gpt-4o". + "llm": "provider/model-id", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +```jsonc agents/analyst.jsonc +{ + "role": "Report Analyst for {topic}", + "goal": "Turn research findings into a clear, well-structured report.", + "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.", + // استبدله بالنموذج الذي تستخدمه، مثل "openai/gpt-4o". + "llm": "provider/model-id", + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +استبدل `provider/model-id` بالنموذج الذي تستخدمه، مثل `openai/gpt-4o` أو `anthropic/claude-sonnet-4-6` أو `gemini/gemini-2.0-flash-001`. + +## الخطوة 3: تعريف المهام وإعدادات الـ Crew + +استبدل `crew.jsonc` بما يلي: + +```jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.", + "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis_task", + "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.", + "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.", + "agent": "analyst", + "context": ["research_task"], + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "Artificial Intelligence in Healthcare" + } +} +``` + +يشير `context` إلى أسماء مهام سابقة، لذلك يحصل analyst على مخرجات مهمة البحث. يوفر `inputs` قيمة افتراضية لـ `{topic}`. إذا حذفت القيمة الافتراضية، سيطلبها `crewai run`. + +## الخطوة 4: متغيرات البيئة + +عدّل `.env`: + +```sh +SERPER_API_KEY=your_serper_api_key +# أضف مفتاح مزود النموذج أيضًا. +``` + +## الخطوة 5: التثبيت والتشغيل + +```bash +crewai install +crewai run +``` + +بعد انتهاء التشغيل، افتح `output/report.md`. + + +شغّل مشاريع JSON crew من مصادر تثق بها فقط. أدوات `custom:` ومراجع `{"python": "module.attribute"}` تنفذ Python محليًا عند تحميل الـ crew. + + + +أصبحت لديك crew تعمل بأسلوب JSON-first تبحث في موضوع وتكتب تقريرًا. + diff --git a/docs/v1.15.1/ar/guides/flows/conversational-flows.mdx b/docs/v1.15.1/ar/guides/flows/conversational-flows.mdx new file mode 100644 index 000000000..371de79be --- /dev/null +++ b/docs/v1.15.1/ar/guides/flows/conversational-flows.mdx @@ -0,0 +1,473 @@ +--- +title: تدفقات المحادثة +description: أنشئ تطبيقات دردشة متعددة الجولات مع kickoff لكل جولة وسجل الرسائل وتوجيه النية والتتبع وجسور WebSocket. +icon: comments +mode: "wide" +--- + +## نظرة عامة + +تعامل التطبيقات المحادثية مع كل سطر من المستخدم كـ **تشغيل flow جديد** بنفس **معرّف الجلسة**. توفر CrewAI مساعدات لسجل الرسائل وتصنيف النية الاختياري وتأجيل التتبع وجسور الواجهة، إضافة إلى REPL محلي `flow.chat()` للتدفقات المحادثية. + +| المفهوم | التنفيذ | +|---------|---------| +| معرّف الجلسة | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` | +| سطر المستخدم | `handle_turn(message)` يضيف الرسالة إلى `state.messages` قبل تشغيل الرسم | +| اكتمال الجولة | `FlowFinished` لهذا **التشغيل** فقط؛ تستمر المحادثة في `handle_turn` التالي | +| تتبع الجلسة | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` | + +## واجهات الجولات + +استخدم **`flow.handle_turn(message, session_id=...)`** لكل رسالة مستخدم من REST أو WebSocket أو الاختبارات أو الواجهات المخصصة. استخدم **`flow.chat()`** عندما تريد حلقة دردشة محلية في الطرفية لـ `Flow` محادثي. + +لا يقبل `Flow.kickoff()` الوسيطين `user_message=` أو `session_id=`. في التدفقات المحادثية، يخزن `handle_turn()` الرسالة المعلقة ويستدعي داخلياً `kickoff(inputs={"id": session_id})`. + +| API | الاستخدام | +|-----|-----------| +| `handle_turn(message, session_id=...)` | غلاف مريح لجولة واحدة في `Flow` محادثي | +| `chat()` | REPL محلي في الطرفية لـ `Flow` محادثي | +| `kickoff(inputs={...})` | تشغيل متقدم للـ flow بدون معالجة جولة محادثية | +| `ask()` | مطالبة حاجزة **داخل** خطوة واحدة | +| `@human_feedback` | الموافقة/الرفض على **مخرجات خطوة** — وليس السطر التالي | +| `ChatSession.handle_turn(...)` | طبقة نقل فوق `handle_turn` | + +## بداية سريعة + +```python +from uuid import uuid4 + +from crewai import Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, +) + + +@ConversationConfig(defer_trace_finalization=True) +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context): + message = (self.state.current_user_message or "").lower() + if "طلب" in message or "order" in message: + return "order" + if "وداع" in message or "goodbye" in message: + return "goodbye" + return "help" + + @listen("order") + def handle_order(self): + reply = "طلبك في الطريق." + self.append_assistant_message(reply) + return reply + + @listen("help") + def handle_help(self): + reply = "كيف يمكنني المساعدة؟" + self.append_assistant_message(reply) + return reply + + @listen("goodbye") + def handle_goodbye(self): + reply = "وداعاً!" + self.append_assistant_message(reply) + return reply + + +session_id = str(uuid4()) +flow = SupportFlow() + +try: + flow.handle_turn("أين طلبي؟", session_id=session_id) + flow.handle_turn("وماذا عن الإرجاع؟", session_id=session_id) +finally: + flow.finalize_session_traces() +``` + +## دورة حياة الجولة + +كل `handle_turn` يشغّل: + +1. **`_configure_conversational_kickoff`** — دمج `session_id` / `user_message` في `inputs` وتطبيق `ConversationalConfig`. +2. **استعادة الحالة** — عند وجود `inputs["id"]` و`@persist`. +3. **`FlowStarted`** — في أول جولة للجلسة المؤجلة فقط. +4. **`prepare_conversational_turn`** — إضافة رسالة المستخدم و`last_user_message` وتصنيف اختياري. +5. **تنفيذ الرسم** — `@start` → `@router` → معالجات `@listen`. +6. **نهاية التشغيل** — يُتخطى `flow_finished` والتتبع لكل جولة عند التأجيل؛ `Agent.kickoff()` / crews لا تغلق دفعة الأب. + +استدعِ **`append_assistant_message(reply)`** في المعالجات. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى. + +## `ConversationalConfig` (افتراضيات على مستوى الصنف) + +عيّن على صنف `Flow` كـ `conversational_config: ClassVar[ConversationalConfig | None]`. + +| الحقل | الافتراضي | الغرض | +|-------|-----------|--------| +| `default_intents` | `None` | تسميات outcome للتصنيف التلقائي قبل kickoff | +| `intent_llm` | `None` | نموذج التصنيف (مطلوب عند وجود intents) | +| `interactive_prompt` | `"You: "` | مطالبة `kickoff(interactive=True)` | +| `interactive_timeout` | `None` | مهلة لكل سطر في الوضع التفاعلي | +| `exit_commands` | `exit`, `quit` | كلمات إنهاء الوضع التفاعلي | +| `defer_trace_finalization` | `True` | إبقاء دفعة trace واحدة مفتوحة بين الجولات | + +يمكن التجاوز لكل kickoff عبر `intents=` و`intent_llm=`. + +## `ChatState` (شكل الحالة الموصى به للحفظ) + +```python +from crewai.flow import ChatState + + +class MyChatState(ChatState): + # موروث: id, messages, last_user_message, last_intent, session_ready + research_turn_count: int = 0 + custom_flag: bool = False +``` + +| الحقل | الدور | +|-------|------| +| `id` | UUID الجلسة (مثل `session_id` / `inputs["id"]`) | +| `messages` | قائمة `{role, content}` لسجل LLM | +| `last_user_message` | آخر سطر مستخدم في هذه الجولة | +| `last_intent` | تسمية المسار بعد التصنيف (إن وُجد) | +| `session_ready` | علم bootstrap لمرة واحدة | + +`ConversationalInputs` هو `TypedDict` لـ `kickoff(inputs={...})`: `id`, `user_message`, `last_intent`. + +## API المحادثة على `Flow` + +### معاملات `kickoff` / `kickoff_async` + +| المعامل | الغرض | +|---------|--------| +| `user_message` | نص هذه الجولة (أو `{"role": "user", "content": "..."}`) | +| `session_id` | UUID المحادثة → `inputs["id"]` / `state.id` | +| `intents` | تسميات outcome لـ `classify_intent` قبل kickoff | +| `intent_llm` | LLM للتصنيف (مطلوب مع `intents`) | +| `interactive` | حلقة CLI عبر `ask()` (للعروض المحلية فقط) | +| `interactive_prompt` | مطالبة الوضع التفاعلي | +| `interactive_timeout` | مهلة `ask()` لكل سطر | +| `exit_commands` | كلمات إنهاء الوضع التفاعلي | +| `inputs` | حقول حالة إضافية | +| `restore_from_state_id` | استنساخ من flow محفوظ آخر | + +### سمات المثيل + +| السمة | الغرض | +|-------|--------| +| `conversational_config` | افتراضيات `ConversationalConfig` على مستوى الصنف | +| `defer_trace_finalization` | علم المثيل؛ يُضبط تلقائياً من config عند kickoff | +| `suppress_flow_events` | يخفي لوحات console؛ **التتبع يُسجّل** | +| `stream` | بث؛ مع `ChatSession.handle_turn(..., stream=True)` | + +### طرق وخصائص + +| الاسم | الوصف | +|------|--------| +| `append_message(role, content, **extra)` | إضافة إلى `state.messages` | +| `conversation_messages` | سجل للقراءة فقط لاستدعاءات LLM | +| `classify_intent(text, outcomes, *, llm, context=None)` | تعيين outcome | +| `receive_user_message(text, *, outcomes=None, llm=None)` | إضافة رسالة مستخدم؛ `last_intent` اختياري | +| `finalize_session_traces()` | إصدار `flow_finished` المؤجل وإنهاء دفعة trace | +| `_should_defer_trace_finalization()` | هل يُؤجل إنهاء trace لكل جولة | +| `input_history` | سجل تدقيق مطالبات وردود `ask()` | + +### مساعدات الوحدة (`crewai.flow.conversation`) + +| الدالة | الوصف | +|--------|--------| +| `normalize_kickoff_inputs(...)` | دمج kwargs المحادثة في `inputs` | +| `get_conversation_messages(flow)` | قراءة الرسائل من الحالة أو المخزن | +| `append_message(flow, ...)` | مثل طريقة المثيل | +| `prepare_conversational_turn(flow, ...)` | تهيئة الجولة (عادةً kickoff يستدعيها) | +| `receive_user_message(flow, ...)` | مثل طريقة المثيل | +| `set_state_field(flow, name, value)` | تعيين حقل dict أو Pydantic | +| `get_conversational_config(flow)` | قراءة `conversational_config` | +| `input_history_to_messages(entries)` | تحويل `input_history` لصيغة رسائل LLM | + +## أنماط توجيه النية + +### أ. تصنيف مسبق عبر `ConversationalConfig` (الأبسط) + +عيّن `default_intents` و`intent_llm`. كل kickoff يصنّف قبل `@router`؛ اقرأ `self.state.last_intent` في `route()`. + +### ب. تصنيف داخل `@router` (مطالبات أغنى) + +عيّن `default_intents=None` ليضيف kickoff الرسالة فقط. في `route()` استدعِ `classify_intent`: + +```python +@router(bootstrap) +def route(self): + intent = self.classify_intent( + self._routing_prompt(self.state.last_user_message), + ("GREETING", "ORDER", "RESEARCH", "GOODBYE"), + llm=self.conversational_config.intent_llm or "gpt-4o-mini", + ) + self.state.last_intent = intent + return intent +``` + +للبحث على الويب أو أدوات متعددة الخطوات استخدم **`@listen("RESEARCH")`** مع `Agent.kickoff()` وأدوات — وليس `LLM.call()` فقط. + +## عندما ينتهي الـ flow ويستمر المستخدم + +`FlowFinished` يعني أن **تنفيذ الرسم هذا** اكتمل. تستمر المحادثة بـ `kickoff` آخر ونفس `session_id`. `@persist` يستعيد `messages` والأعلام والسياق. + +**نمط الحفظ:** يُفضّل `@persist` على **خطوة نهائية واحدة** (مثل `finalize`) وليس على صنف `Flow` بالكامل. الحفظ على مستوى الصنف بعد كل method قد يفقد تحديثات المعالجات في نفس الجولة. + +لا تستخدم `@human_feedback` لأسطر المتابعة في الدردشة إلا عند الحاجة لموافقة بشرية على مخرجات خطوة محددة. + +## `Flow` المحادثاتي (تجريبي) + + + **ميزة تجريبية.** سطح `Flow` المحادثاتي (`conversational = True`، + `handle_turn`، `ConversationConfig`، `RouterConfig`، + `ConversationState`، الرسم البياني المدمج والمساعدات) يقع تحت + `crewai.experimental` وقد يتغير شكله قبل التخرج. ثبّت إصدار CrewAI إذا + كنت تعتمد على سلوك محدد، وراقب changelog للتحديثات الكاسرة. الملاحظات + والمشاكل مرحب بها. + + +فعّل الرسم المحادثاتي بتعيين `conversational = True` على صنف فرعي من `Flow`. عندئذٍ يُظهر `Flow` الأساسي رسم `@start` / `@router` / `converse_turn` / `end_conversation` مدمجاً، ويدير `state.messages`، ويُشغّل LLM التوجيه، ويبقي دفعة trace مفتوحة عبر الجولات. أنت تكتب **المسارات المخصصة** فقط؛ والإطار يتولى الباقي. + +استخدمه عندما تريد دردشة متعددة الجولات مع موجّه قائم على LLM ومعالجات لكل مسار دون توصيل دورة الحياة يدوياً. استخدم `Flow[ChatState]` (النمط الأدنى مستوى في الأعلى) عندما تحتاج تحكماً كاملاً. + +### مثال سريع + +```python +from crewai import LLM, Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, + RouterConfig, +) + + +ROUTER_LLM = LLM(model="gpt-4o-mini") + + +@ConversationConfig( + system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.", + llm=ROUTER_LLM, + router=RouterConfig(), # المسارات + الأوصاف تُكتشف تلقائياً من معالجات @listen +) +class SupportFlow(Flow[ConversationState]): + conversational = True + + @listen("INTERNET_SEARCH") + def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... + self.append_assistant_message(reply) + return reply + + @listen("CREWAI_DOCS") + def handle_crewai_docs(self) -> str: + """Look up the CrewAI documentation for framework/API questions.""" + ... + self.append_assistant_message(reply) + return reply + + +flow = SupportFlow() +try: + flow.handle_turn("ماذا يمكنك أن تفعل؟") # يوجَّه إلى converse (مدمج) + flow.handle_turn("ابحث في الويب عن أخبار الذكاء الاصطناعي.") # يوجَّه إلى INTERNET_SEARCH + flow.handle_turn("لخص النتيجة الأولى.") # يعود إلى converse +finally: + flow.finalize_session_traces() +``` + +للدردشة المحلية في الطرفية، استخدم `chat()`: + +```python +def kickoff() -> None: + SupportFlow().chat() +``` + +يلف `chat()` استدعاءات `handle_turn()` داخل REPL، ويخرج عند `exit` / `quit`، ويتجاهل الأسطر الفارغة افتراضياً، ويستدعي `finalize_session_traces()` عند انتهاء الجلسة. + +### `ConversationConfig` + +مزخرف صنف يُلحق افتراضيات الدردشة على مستوى الصنف. + +| الحقل | الافتراضي | الغرض | +|-------|-----------|-------| +| `system_prompt` | `slices.conversational_system_prompt` من i18n | رسالة system يستخدمها `converse_turn` المدمج. مرر `""` للتعطيل التام. | +| `llm` | `None` | LLM المحادثة (يستخدمه `converse_turn` وكاحتياطي للموجّه). | +| `router` | `None` | `RouterConfig` للتوجيه عبر LLM. بدونه، يسقط الـ flow دائماً إلى `converse`. | +| `answer_from_history_prompt` | افتراضي الإطار | رسالة system للمسار الاختياري `answer_from_history`. | +| `answer_from_history_llm` | `None` | يُفعّل الاختصار `answer_from_history` عند تعيينه. | +| `intent_llm` | `None` | LLM لمسار التصنيف المسبق القديم `intents=`/`default_intents`. | +| `default_intents` | `None` | تسميات النتائج للتصنيف المسبق القديم. | +| `visible_agent_outputs` | `None` | `"all"` أو قائمة بأسماء الـ agents الذين تُرفع مخرجاتهم من `append_agent_result()` إلى رسائل عامة. | +| `defer_trace_finalization` | `True` | يبقي دفعة trace واحدة مفتوحة عبر استدعاءات `handle_turn()`. | + +### `RouterConfig` وفهرس المسارات المُولَّد تلقائياً + +```python +RouterConfig( + prompt="تأطير اختياري للنطاق (سياسة، صوت، شخصية).", + response_format=MyRoute, # اختياري؛ يُولَّد تلقائياً عند الإغفال + llm=ROUTER_LLM, # يسقط إلى ConversationConfig.llm + routes=["INTERNET_SEARCH", "CREWAI_DOCS"], # اختياري؛ يُستنتج من المستمعين + route_descriptions={ + "INTERNET_SEARCH": "تجاوز الـ docstring لهذا المسار فقط.", + }, + default_intent="converse", # يُستخدم عند فشل LLM أو غيابه + fallback_intent="converse", # يُستخدم عندما يعيد LLM مساراً غير صالح + intent_field="intent", +) +``` + +تُبنى رسالة الموجّه إلى LLM تلقائياً. لكل مسار يختار الإطار وصفاً بهذا الترتيب من الأولوية: + +1. `RouterConfig.route_descriptions[label]` — تجاوز صريح. +2. `Flow.builtin_route_descriptions[label]` — نص جاهز من الإطار لـ `converse` و`end` و`answer_from_history` (مصاغ لـ LLM التوجيه). +3. أول سطر غير فارغ من docstring معالج `@listen(label)`. +4. فارغ (المسار يظهر في الفهرس بلا وصف). + +عملياً، **إضافة مسار جديد = `@listen("X")` + docstring من سطر واحد**: + +```python +@listen("INTERNET_SEARCH") +def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... +``` + +…وسيرى LLM التوجيه: + +``` +Routes: +- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions. +- INTERNET_SEARCH: Fresh web research, current news, real-time lookups. +- converse: Ordinary chat, follow-ups, summaries, clarifications… +- end: User signals the conversation is finished (goodbye, exit, done). +``` + +`RouterConfig.prompt` مخصص لـ **تأطير النطاق** (شخصية المساعد، قواعد العمل، النبرة). فهرس المسارات يُبنى تلقائياً — لا تُدرج المسارات في `prompt`؛ سيختل التزامن لحظة إضافة معالج جديد. + +### المسارات المدمجة + +| المسار | المعالج | الغرض | +|--------|---------|-------| +| `converse` | `converse_turn` | معالج الدردشة الافتراضي. يستدعي `ConversationConfig.llm` بـ system prompt + التاريخ القانوني للرسائل. | +| `end` | `end_conversation` | يضبط `state.ended = True` ويُصدر رد إنهاء. | +| `answer_from_history` | `answer_from_history_turn` | اختياري. يُوجَّه إليه عندما يكون `ConversationConfig.answer_from_history_llm` مُعيَّناً ويمكن الإجابة على الرسالة من التاريخ فقط. | + +يمكنك تجاوز أي من هذه بتعريف معالج بنفس الاسم في الصنف الفرعي. + +### دلالات `handle_turn()` + +`flow.handle_turn(message)` يُشغّل جولة واحدة: + +1. يعيد ضبط تعقّب التنفيذ لكل جولة (`_completed_methods`, `_method_outputs`) ليُعاد تشغيل الرسم — بدون ذلك، استدعاءات `kickoff` المتكررة على نفس النسخة ستُحدث دائرة قصر من الجولة الثانية لأن `Flow.kickoff_async` يعتبر `inputs={"id": ...}` استعادة من نقطة تفتيش. +2. يُلحق رسالة المستخدم بـ `state.messages` ويضبط `current_user_message` / `last_user_message`. يُحافَظ على `last_intent` **من الجولة السابقة** كي يستخدمها LLM التوجيه كإشارة. +3. يُشغّل `conversation_start` → `route_conversation` → معالج `@listen` المختار. +4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية). +5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك. + +استدعِ `handle_turn()` لرسائل الدردشة. استدعاء `kickoff(inputs={"id": ...})` مباشرةً يشغل الرسم بدون غلاف الجولة المحادثية. + +### `chat()` للـ REPL المحلي + +`flow.chat()` هو غلاف الطرفية الجاهز فوق `handle_turn()`: + +```python +flow = SupportFlow() +flow.chat() +``` + +يتولى الحلقة المحلية الشائعة: + +1. يطلب رسالة من المستخدم. +2. يتوقف عند `exit` / `quit` أو `EOFError` أو `KeyboardInterrupt`. +3. يستدعي `handle_turn(message, session_id=...)`. +4. يطبع نتيجة المساعد. +5. ينهي traces الجلسة المؤجلة داخل كتلة `finally`. + +خصص سلوك الطرفية عبر I/O قابل للحقن: + +```python +flow.chat( + session_id="demo-session", + prompt="You: ", + assistant_prefix="Assistant: ", + exit_commands=("exit", "quit", "bye"), +) +``` + +لتطبيقات الويب والـ workers الخلفية والاختبارات ووسائط النقل المخصصة، استمر في استخدام `handle_turn()` مباشرةً. + +### سلوك موجّه مخصص + +لتشغيل آثار جانبية (إعداد ناقل أحداث، قياس عن بُعد) في كل قرار توجيه، تجاوز `route_turn`: + +```python +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context: dict[str, Any]) -> str | None: + self.event_bus = MyBus(self) + return super().route_turn(context) +``` + +لتجاوز موجّه LLM واختيار مسار برمجياً، أعد سلسلة نصية من `route_turn`؛ إعادة `None` تسقط إلى `_route_with_config(...)`. + +### `append_assistant_message` و`append_agent_result` + +داخل معالج `@listen(label)`، اختر: + +- `self.append_assistant_message(text)` — يضيف جولة مساعد مرئية للمستخدم إلى `state.messages`. سيراها `converse_turn` في الجولة التالية. +- `self.append_agent_result(agent_name, result, visibility="private")` — يسجّل حدثاً منظماً في `state.events` وموضوعاً في `state.agent_threads[agent_name]`. الرؤية العامة تستدعي `append_assistant_message` أيضاً. استخدم النتائج الخاصة للعمل الجانبي الذي يجب ألا يلوث التاريخ القانوني. + +يمكن لـ `ConversationConfig.visible_agent_outputs` رفع النتائج الخاصة لـ agents محددين إلى عامة عالمياً (`"all"` أو قائمة بالأسماء). + +## التتبع عبر الجولات + +مع `defer_trace_finalization=True` (افتراضي في `ConversationalConfig`): + +- **دفعة trace واحدة** لجلسة الدردشة. +- **`flow_started`** في الجولة الأولى فقط؛ **`flow_finished`** مرة في `finalize_session_traces()`. +- **`kickoff` لكل جولة** لا يطبع "Trace batch finalized". +- **العمل المتداخل** (`Agent.kickoff()`, crews, Exa) يُلحق بدفعة **الأب**؛ flow داخلي من `AgentExecutor` لا يغلق دفعة الجلسة مبكراً. + +```python +flow.chat(session_id=session_id) +``` + +`flow.chat()` يستدعي `finalize_session_traces()` نيابةً عنك. عندما تملك الحلقة عبر `handle_turn()` أو `kickoff(...)`، استدعِ `finalize_session_traces()` عند انتهاء الجلسة. + +`suppress_flow_events=True` يخفي لوحات Rich فقط؛ أحداث trace والـ methods تُصدر. + +### دورة حياة trace لـ `Flow` المحادثاتي + +يستخدم [`Flow` المحادثاتي](#flow-المحادثاتي-تجريبي) التجريبي نفس دورة حياة tracing: `defer_trace_finalization` افتراضياً `True`، فيبقي كل `handle_turn()` أثر الجلسة مفتوحاً. أنهِ دوماً عند نهاية الجلسة — لُف حلقتك بـ `try/finally` واستدعِ `flow.finalize_session_traces()` عند الخروج. بدون ذلك، تبقى الدفعة مفتوحة وقد لا تُصدَّر آخر محادثة أبداً. + +## البث + +اضبط `stream = True` على صنف `Flow`. عندئذٍ يُصدر `kickoff(...)` أحداث `assistant_delta` (وما يرتبط بها) عبر ناقل الأحداث القياسي. + +## الاستيراد + +```python +from crewai.flow import ( + ChatState, + ConversationalConfig, + ConversationalInputs, + Flow, + listen, + persist, + router, + start, +) +``` + +## مراجع + +- [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state) +- [أنشئ أول Flow](/ar/guides/flows/first-flow) +- Demo: `lib/crewai/runner_conversational_flow_simple.py` — REPL بسيط مع `RESEARCH` ووكيل Exa diff --git a/docs/v1.15.1/ar/guides/flows/first-flow.mdx b/docs/v1.15.1/ar/guides/flows/first-flow.mdx new file mode 100644 index 000000000..322e71c2a --- /dev/null +++ b/docs/v1.15.1/ar/guides/flows/first-flow.mdx @@ -0,0 +1,222 @@ +--- +title: ابنِ أول Flow لك +description: تعلم كيفية إنشاء سير عمل منظمة قائمة على الأحداث مع تحكم دقيق في التنفيذ. +icon: diagram-project +mode: "wide" +--- + +## التحكم في سير عمل AI مع Flows + +تمثل CrewAI Flows المستوى التالي في تنسيق AI - الجمع بين القوة التعاونية لفرق Agents AI مع دقة ومرونة البرمجة الإجرائية. بينما تتفوق Crews في تعاون الـ Agents، تمنحك Flows تحكمًا دقيقًا في كيفية ووقت تفاعل المكونات المختلفة لنظام AI. + +في هذا الدليل، سنمشي عبر إنشاء CrewAI Flow قوي ينشئ دليلًا تعليميًا شاملاً حول أي موضوع. + +### ما يجعل Flows قوية + +تمكّنك Flows من: + +1. **الجمع بين أنماط تفاعل AI مختلفة** - استخدام Crews للمهام التعاونية المعقدة واستدعاءات LLM المباشرة للعمليات الأبسط والكود العادي للمنطق الإجرائي +2. **بناء أنظمة قائمة على الأحداث** - تحديد كيفية استجابة المكونات لأحداث وتغييرات بيانات محددة +3. **الحفاظ على الحالة عبر المكونات** - مشاركة وتحويل البيانات بين أجزاء مختلفة من تطبيقك +4. **التكامل مع الأنظمة الخارجية** - ربط سير عمل AI بسلاسة مع قواعد البيانات وواجهات API وواجهات المستخدم +5. **إنشاء مسارات تنفيذ معقدة** - تصميم فروع شرطية ومعالجة متوازية وسير عمل ديناميكية + +### المتطلبات المسبقة + +قبل البدء، تأكد من: + +1. تثبيت CrewAI باتباع [دليل التثبيت](/ar/installation) +2. إعداد مفتاح API لنموذج LLM في بيئتك، باتباع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) +3. فهم أساسي لـ Python + +## الخطوة 1: إنشاء مشروع CrewAI Flow جديد + +```bash +crewai create flow guide_creator_flow +cd guide_creator_flow +``` + + + نظرة عامة على إطار عمل CrewAI + + +## الخطوة 2: فهم هيكل المشروع + +يستخدم الـ crew المبدئي المضمّن في مشروع Flow بنية Python/YAML الكلاسيكية. لاستخدام crew بنمط JSON-first داخل Flow، أنشئ `crew.jsonc` و `agents/*.jsonc` داخل مجلد الـ crew وحمّله عبر `crewai.project.load_crew` كما في [Flows](/ar/concepts/flows#building-your-crews). + +``` +guide_creator_flow/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +└── src/ + └── guide_creator_flow/ + ├── __init__.py + ├── main.py + ├── crews/ + │ └── poem_crew/ + │ ├── config/ + │ │ ├── agents.yaml + │ │ └── tasks.yaml + │ └── poem_crew.py + └── tools/ + └── custom_tool.py +``` + +يوفر هذا الهيكل فصلاً واضحًا بين مكونات Flow المختلفة. سنعدّل هذا الهيكل لإنشاء Flow منشئ الدليل. + +## الخطوة 3: إضافة Crew كتابة المحتوى + +```bash +crewai flow add-crew content-crew +``` + +## الخطوة 4: تهيئة Crew كتابة المحتوى + +سنهيئ crew كتابة المحتوى باستخدام JSONC. سنعرّف Agent للكتابة وAgent للمراجعة، ثم نحمّل `crew.jsonc` من خطوة Flow. + +1. أنشئ `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`: + +```jsonc +{ + "role": "Educational Content Writer", + "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.", + "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +2. أنشئ `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`: + +```jsonc +{ + "role": "Educational Content Reviewer and Editor", + "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.", + "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +استبدل `provider/model-id` بالنموذج الذي تستخدمه، مثل `openai/gpt-4o` أو `gemini/gemini-2.0-flash-001` أو `anthropic/claude-sonnet-4-6`. + +3. أنشئ `src/guide_creator_flow/crews/content_crew/crew.jsonc`: + +```jsonc +{ + "name": "Content Crew", + "agents": ["content_writer", "content_reviewer"], + "tasks": [ + { + "name": "write_section_task", + "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}", + "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.", + "agent": "content_writer", + "markdown": true + }, + { + "name": "review_section_task", + "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.", + "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.", + "agent": "content_reviewer", + "context": ["write_section_task"], + "markdown": true + } + ], + "process": "sequential", + "verbose": true +} +``` + +4. استبدل `src/guide_creator_flow/crews/content_crew/content_crew.py` بمحمل صغير: + +```python +from pathlib import Path + +from crewai.project import load_crew + + +def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) +``` + +## الخطوة 5: إنشاء Flow + +الآن الجزء المثير - إنشاء Flow الذي سينسّق عملية إنشاء الدليل بالكامل. راجع الملف الإنجليزي الأصلي للكود الكامل لـ `main.py` حيث أن الكود يبقى كما هو. + +## الخطوة 6: إعداد متغيرات البيئة + +أنشئ ملف `.env` في جذر مشروعك بمفاتيح API. راجع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) لتفاصيل تهيئة المزود. + +```sh .env +OPENAI_API_KEY=your_openai_api_key +# or +GEMINI_API_KEY=your_gemini_api_key +# or +ANTHROPIC_API_KEY=your_anthropic_api_key +``` + +## الخطوة 7: تثبيت التبعيات + +```bash +crewai install +``` + +## الخطوة 8: تشغيل Flow + +```bash +crewai run +``` + +عند تشغيل هذا الأمر، ستشاهد Flow يعمل: +1. سيطلب منك موضوعًا ومستوى الجمهور +2. سينشئ مخططًا منظمًا لدليلك +3. سيعالج كل قسم مع تعاون الكاتب والمراجع +4. أخيرًا سيجمع كل شيء في دليل شامل + +## الخطوة 9: تصوير Flow + +```bash +crewai flow plot +``` + +سينشئ ملف HTML يوضح هيكل Flow بما في ذلك العلاقات بين الخطوات المختلفة. + +## الخطوة 10: مراجعة المخرجات + +بمجرد اكتمال Flow، ستجد ملفين في مجلد `output`: + +1. `guide_outline.json`: يحتوي على المخطط المنظم للدليل +2. `complete_guide.md`: الدليل الشامل بجميع الأقسام + +## الميزات الرئيسية الموضّحة + +يوضح Flow منشئ الدليل عدة ميزات قوية لـ CrewAI: + +1. **تفاعل المستخدم**: يجمع Flow مدخلات مباشرة من المستخدم +2. **استدعاءات LLM المباشرة**: يستخدم فئة LLM لتفاعلات AI فعّالة وأحادية الغرض +3. **بيانات منظمة مع Pydantic**: يستخدم نماذج Pydantic لضمان سلامة الأنواع +4. **معالجة تسلسلية مع سياق**: يكتب الأقسام بالترتيب ويوفر الأقسام السابقة كسياق +5. **Crews متعددة الـ Agents**: يستفيد من Agents متخصصة (كاتب ومراجع) لإنشاء المحتوى +6. **إدارة الحالة**: يحافظ على الحالة عبر خطوات العملية المختلفة +7. **بنية قائمة على الأحداث**: يستخدم مزخرف `@listen` للاستجابة للأحداث + +## الخطوات التالية + +1. جرّب هياكل Flow أكثر تعقيدًا وأنماطًا +2. جرّب استخدام `@router()` لإنشاء فروع شرطية +3. استكشف دوال `and_` و`or_` لتنفيذ متوازٍ أكثر تعقيدًا +4. اربط Flow بواجهات API خارجية وقواعد بيانات وواجهات مستخدم +5. ادمج عدة Crews متخصصة في Flow واحد +6. أنشئ تطبيقات دردشة متعددة الجولات مع [تدفقات المحادثة](/ar/guides/flows/conversational-flows) (`kickoff` لكل رسالة، `ChatSession`، تأجيل التتبع) + + +تهانينا! لقد بنيت بنجاح أول CrewAI Flow يجمع بين الكود العادي واستدعاءات LLM المباشرة ومعالجة Crew لإنشاء دليل شامل. هذه المهارات الأساسية تمكّنك من إنشاء تطبيقات AI متطورة بشكل متزايد. + diff --git a/docs/v1.15.1/ar/guides/flows/inputs-id-deprecation.mdx b/docs/v1.15.1/ar/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..3e29b2baf --- /dev/null +++ b/docs/v1.15.1/ar/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,102 @@ +--- +title: "الانتقال من inputs.id إلى restore_from_state_id" +description: "نقل تدفقات @persist من ترطيب inputs.id المهجور إلى حقل restore_from_state_id المدعوم" +icon: "arrow-right-arrow-left" +--- + + + تمرير `id` داخل `inputs` لترطيب تدفق `@persist` هو **مهجور** ومقرر إزالته في إصدار مستقبلي. البديل، `restore_from_state_id`، متاح في CrewAI **v1.14.5 وما بعده** — الخطوات أدناه تنطبق بمجرد أن تقوم بالتحديث. + + +## نظرة عامة + +الطريقة الموثقة لترطيب تدفق `@persist` من تنفيذ سابق هي تمرير UUID لذلك التنفيذ كـ `inputs.id`. الآن، تكشف CrewAI عن حقل مخصص، `restore_from_state_id`، الذي يقوم بنفس الترطيب دون تحميل حمولة `inputs` — ودون ربط مفتاح الترطيب بهوية التنفيذ الجديد. + +## الانتقال + +إذا كنت حالياً تبدأ تدفق `@persist` باستخدام `inputs={"id": ...}`: + +```python +# مهجور +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +انتقل إلى `restore_from_state_id`: + +```python +# مدعوم +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +تتمتع الوضعيتان بمعاني سلالة مختلفة: + +- `inputs={"id": }` (مهجور) — **استئناف**: تكتب الكتابات تحت المعرف المقدم، مما يمدد نفس تاريخ `flow_uuid`. +- `restore_from_state_id=` — **تفرع**: يترطب الحالة من اللقطة، ثم يكتب تحت `state.id` جديدة. يتم الحفاظ على تاريخ التدفق المصدر. + +لأغلب سيناريوهات الإنتاج — إعادة تشغيل تدفق تم تهيئته من حالة سابقة — فإن التفرع هو ما تريده. راجع [إتقان حالة التدفق](/ar/guides/flows/mastering-flow-state) للحصول على النموذج الذهني الكامل. + +إذا كنت تبدأ تدفقك عبر واجهة برمجة تطبيقات CrewAI AMP REST، راجع [AMP](#amp) أدناه لهجرة الحمولة المعادلة. + +## لماذا نقوم بإهمال `inputs.id` لـ `@persist` + +`inputs.id` هو حالياً الطريقة الموثقة لاستئناف تدفق `@persist` من تنفيذ سابق. المشكلة هي أن نفس UUID يقوم بوظيفتين في وقت واحد: + +1. **يحدد أي لقطة يترطب منها `@persist`** — تحميل الحالة المحفوظة تحت ذلك UUID. +2. **يصبح معرف تنفيذ التدفق الجديد** (`state.id` في SDK؛ يظهر كـ `flow_id` في بعض السياقات) — كل كتابة `@persist` من هذه البداية أيضاً تقع تحت نفس UUID. + +هذه الوظيفة المزدوجة هي السبب الجذري للمشاكل التي يصفها هذا الدليل. لأن UUID المقدم هو أيضاً معرف التنفيذ الجديد، فإن بدايتين تمرران نفس `inputs.id` ليست تنفيذين متميزين — إنهما تشتركان في معرف، وتشاركان في سجل الاستمرارية، و(على AMP) تشتركان في صف في قائمة التنفيذات. لا توجد طريقة للقول "ترطب من هذه اللقطة، ولكن سجل هذا التشغيل بشكل منفصل" دون تقسيم المسؤوليتين. + +`restore_from_state_id` هو هذا الانقسام. إنه يخبر `@persist` من أي لقطة يترطب، بينما يترك التنفيذ الجديد حراً لاستلام `state.id` جديدة. لم يعد مصدر الترطيب والتشغيل المسجل نفس UUID — وهو ما تريده معظم سيناريوهات الإنتاج فعلياً. + +## جدول إزالة + +من المقرر إزالة `inputs.id` لترطيب `@persist` في إصدار مستقبلي من CrewAI. لا يوجد قطع صارم فوري — تظل التدفقات الحالية تعمل — ولكن بمجرد أن تقوم بالتحديث إلى v1.14.5 أو ما بعده، يجب أن يستخدم الكود الجديد `restore_from_state_id`، ويجب أن تهاجر التدفقات الحالية في الفرصة المناسبة التالية. + +## AMP + +إذا كنت تنشر تدفقك إلى CrewAI AMP، فإن الهجرة تمتد إلى الحمولة التي تبدأ بها المرسلة إلى طاقمك المنشور، وتظهر الأعراض المرئية لإعادة استخدام `inputs.id` على لوحة معلومات النشر. تغطي القسمان الفرعيان أدناه كلاهما. + +### هجرة حمولة البداية + +إذا كنت حالياً تبدأ تدفقاً منشوراً عن طريق تضمين `id` في `inputs`: + +```bash +# مهجور +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +نقل UUID إلى حقل `restoreFromStateId` في المستوى الأعلى: + +```bash +# مدعوم +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{ + "inputs": {"topic": "AI Agent Frameworks"}, + "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv" + }' \ + https://your-crew-url.crewai.com/kickoff +``` + +يجلس `restoreFromStateId` بجانب `inputs` في حمولة البداية، وليس داخلها. الآن، يحمل كائن `inputs` فقط القيم التي تستهلكها تدفقك فعلياً. + +### ماذا يحدث عند إعادة استخدام `inputs.id` + +عندما تتلقى AMP بداية لتدفق يتطابق `inputs.id` الخاص به مع تنفيذ موجود، فإنه يحل إلى السجل الموجود بدلاً من إنشاء سجل جديد. من لوحة معلومات النشر سترى: + +- **حالة التنفيذ** — حالة التشغيل الجديد تحل محل حالة التشغيل السابق. يمكن أن تعود تنفيذات مكتملة إلى `جارية`، أو يمكن أن تتحول تشغيلات `مكتملة` إلى `خطأ` إذا فشلت البداية الجديدة — في كلتا الحالتين، لم تعد لوحة المعلومات تعكس التشغيل الأصلي. +- **التتبع** — تتراكم تتبعات OTel عبر البدايات لأنها تشترك في نفس معرف التنفيذ؛ تتبعات التشغيل السابق إما تُستبدل بـ، أو تُخلط مع، تشغيل الجديد. لم يعد إعادة التشغيل خطوة بخطوة يتوافق مع تنفيذ واحد. +- **قائمة التنفيذات** — البدايات التي يجب أن تظهر كصفوف منفصلة تتقلص إلى إدخال واحد، مما يخفي التاريخ. + +تساعد الهجرة إلى `restoreFromStateId` في الحفاظ على كل بداية كتنفيذ خاص بها — مع حالتها الخاصة، وتتبعها، وصفها في القائمة — بينما لا تزال ترطب الحالة من تشغيل سابق. + + + اتصل بفريق الدعم لدينا إذا لم تكن متأكداً من أي وضع يحتاجه تدفقك أو واجهت مشاكل أثناء الهجرة. + \ No newline at end of file diff --git a/docs/v1.15.1/ar/guides/flows/mastering-flow-state.mdx b/docs/v1.15.1/ar/guides/flows/mastering-flow-state.mdx new file mode 100644 index 000000000..2311a4462 --- /dev/null +++ b/docs/v1.15.1/ar/guides/flows/mastering-flow-state.mdx @@ -0,0 +1,228 @@ +--- +title: إتقان إدارة حالة Flow +description: دليل شامل لإدارة الحالة وحفظها والاستفادة منها في CrewAI Flows لبناء تطبيقات AI قوية. +icon: diagram-project +mode: "wide" +--- + +## فهم قوة الحالة في Flows + +إدارة الحالة هي العمود الفقري لأي سير عمل AI متطور. في CrewAI Flows، يتيح لك نظام الحالة الحفاظ على السياق ومشاركة البيانات بين الخطوات وبناء منطق تطبيق معقد. إتقان إدارة الحالة ضروري لإنشاء تطبيقات AI موثوقة وقابلة للصيانة وقوية. + +### لماذا تهم إدارة الحالة + +تمكّنك إدارة الحالة الفعّالة من: + +1. **الحفاظ على السياق عبر خطوات التنفيذ** - تمرير المعلومات بسلاسة بين مراحل سير العمل المختلفة +2. **بناء منطق شرطي معقد** - اتخاذ قرارات بناءً على البيانات المتراكمة +3. **إنشاء تطبيقات مستمرة** - حفظ واستعادة تقدم سير العمل +4. **معالجة الأخطاء بلطف** - تنفيذ أنماط استرداد لتطبيقات أكثر قوة +5. **توسيع تطبيقاتك** - دعم سير العمل المعقدة بتنظيم بيانات مناسب +6. **تمكين التطبيقات الحوارية** - تخزين والوصول إلى سجل المحادثات للتفاعلات الواعية بالسياق + +للدردشة متعددة الجولات (`kickoff` لكل سطر مستخدم، `ChatState`، توجيه النية، تأجيل التتبع، و`ChatSession`)، راجع [تدفقات المحادثة](/ar/guides/flows/conversational-flows). + +## أساسيات إدارة الحالة + +### نهجان لإدارة الحالة + +يوفر CrewAI طريقتين لإدارة الحالة في Flows: + +1. **الحالة غير المنظمة** - استخدام كائنات شبيهة بالقاموس للمرونة +2. **الحالة المنظمة** - استخدام نماذج Pydantic لسلامة الأنواع والتحقق + +### مثال الحالة غير المنظمة + +```python +from crewai.flow.flow import Flow, listen, start + +class UnstructuredStateFlow(Flow): + @start() + def initialize_data(self): + self.state["user_name"] = "Alex" + self.state["preferences"] = {"theme": "dark", "language": "English"} + self.state["items"] = [] + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + user = self.state["user_name"] + self.state["items"].append("item1") + self.state["processed"] = True + return "Processed" + +flow = UnstructuredStateFlow() +result = flow.kickoff() +``` + +### مثال الحالة المنظمة + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel, Field +from typing import List, Dict, Optional + +class AppState(BaseModel): + user_name: str = "" + items: List[str] = [] + processed: bool = False + completion_percentage: float = 0.0 + +class StructuredStateFlow(Flow[AppState]): + @start() + def initialize_data(self): + self.state.user_name = "Taylor" + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + self.state.items.append("item1") + self.state.processed = True + self.state.completion_percentage = 50.0 + return "Processed" + +flow = StructuredStateFlow() +result = flow.kickoff() +``` + +### فوائد الحالة المنظمة + +1. **سلامة الأنواع** - اكتشاف أخطاء الأنواع في وقت التطوير +2. **توثيق ذاتي** - نموذج الحالة يوثّق بوضوح البيانات المتاحة +3. **التحقق** - التحقق التلقائي من أنواع البيانات والقيود +4. **دعم IDE** - إكمال تلقائي وتوثيق مضمّن +5. **قيم افتراضية** - تعريف بدائل سهلة للبيانات المفقودة + +## حفظ حالة Flow + +يوفر مزخرف `@persist()` حفظ حالة تلقائي عند نقاط رئيسية في التنفيذ. + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + value: int = 0 + +@persist() +class PersistentCounterFlow(Flow[CounterState]): + @start() + def increment(self): + self.state.value += 1 + return self.state.value + + @listen(increment) + def double(self, value): + self.state.value = value * 2 + return self.state.value +``` + +#### تفرع الحالة المستمرة + +يدعم `@persist` نمطين متميزين للترطيب في `kickoff` / `kickoff_async`. استخدم **استئناف** (`inputs["id"]`) لمواصلة نفس النسب؛ استخدم **تفرع** (`restore_from_state_id`) لبدء نسبٍ جديد من لقطة: + +| | `state.id` بعد kickoff | كتابات `@persist` تذهب إلى | +|---|---|---| +| `inputs["id"]` (استئناف) | المعرّف المقدم | المعرّف المقدم (يمد التاريخ) | +| `restore_from_state_id` (تفرع) | معرّف جديد، أو `inputs["id"]` إذا ثُبّت | المعرّف الجديد (المصدر محفوظ) | + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + +# التشغيل 1: حالة جديدة، العداد 0 -> 1 +flow_1 = CounterFlow() +flow_1.kickoff() + +# التفرع: الترطيب من أحدث لقطة لـ flow_1، لكن الكتابة تحت state.id جديد +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# يبدأ flow_2 بـ counter=1 (مرطّب)، ثم تزيده step() إلى 2. +# تاريخ flow_uuid لـ flow_1 لم يتغيّر. +``` + +ملاحظات السلوك: + +- `restore_from_state_id` غير موجود في الاستمرارية → يعود kickoff بصمت إلى السلوك الافتراضي (يعكس سلوك `inputs["id"]` عند عدم العثور عليه). لا يُطلق أي استثناء. +- الجمع بين `restore_from_state_id` و `from_checkpoint` يطلق `ValueError` — يستهدفان نظامي حالة مختلفين (`@persist` مقابل Checkpointing) ولا يمكن الجمع بينهما. +- `restore_from_state_id=None` (افتراضي) متطابق بايت ببايت مع kickoff بدون المعامل. +- تثبيت `inputs["id"]` أثناء التفرع يعني أن التشغيل الجديد يشارك مفتاح الاستمرارية مع تدفق آخر — عادةً ما تريد فقط `restore_from_state_id`. + +## أنماط حالة متقدمة + +### المنطق الشرطي المبني على الحالة + +```python +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class PaymentState(BaseModel): + amount: float = 0.0 + is_approved: bool = False + retry_count: int = 0 + +class PaymentFlow(Flow[PaymentState]): + @start() + def process_payment(self): + self.state.amount = 100.0 + self.state.is_approved = self.state.amount < 1000 + return "Payment processed" + + @router(process_payment) + def check_approval(self, previous_result): + if self.state.is_approved: + return "approved" + elif self.state.retry_count < 3: + return "retry" + else: + return "rejected" + + @listen("approved") + def handle_approval(self): + return f"Payment of ${self.state.amount} approved!" + + @listen("retry") + def handle_retry(self): + self.state.retry_count += 1 + return "Retry initiated" + + @listen("rejected") + def handle_rejection(self): + return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries." +``` + +## أفضل الممارسات لإدارة الحالة + +1. **اجعل الحالة مركّزة** - صمم الحالة لتحتوي فقط على ما هو ضروري +2. **استخدم الحالة المنظمة للـ Flows المعقدة** - مع نمو التعقيد تصبح الحالة المنظمة أكثر قيمة +3. **وثّق انتقالات الحالة** - للـ Flows المعقدة، وثّق كيف تتغير الحالة عبر التنفيذ +4. **عالج أخطاء الحالة بلطف** - طبّق معالجة أخطاء للوصول إلى الحالة +5. **استخدم الحالة لتتبع التقدم** - استفد من الحالة لتتبع التقدم في Flows طويلة التشغيل +6. **استخدم العمليات غير المتغيرة عند الإمكان** - خاصة مع الحالة المنظمة + +## الخلاصة + +إتقان إدارة الحالة في CrewAI Flows يمنحك القدرة على بناء تطبيقات AI متطورة وقوية تحافظ على السياق وتتخذ قرارات معقدة وتقدم نتائج متسقة. + + +لقد أتقنت الآن مفاهيم وممارسات إدارة الحالة في CrewAI Flows! بهذه المعرفة، يمكنك إنشاء سير عمل AI قوية تحافظ على السياق بفعالية وتشارك البيانات بين الخطوات وتبني منطق تطبيق متطور. + + +## الخطوات التالية + +- جرّب الحالة المنظمة وغير المنظمة في Flows +- جرّب تطبيق حفظ الحالة لسير العمل طويلة التشغيل +- استكشف [بناء أول Crew](/ar/guides/crews/first-crew) لمعرفة كيف تعمل Crews وFlows معًا +- اطلع على [توثيق مرجع Flow](/ar/concepts/flows) لمزيد من الميزات المتقدمة diff --git a/docs/v1.15.1/ar/guides/migration/migrating-from-langgraph.mdx b/docs/v1.15.1/ar/guides/migration/migrating-from-langgraph.mdx new file mode 100644 index 000000000..913854ae8 --- /dev/null +++ b/docs/v1.15.1/ar/guides/migration/migrating-from-langgraph.mdx @@ -0,0 +1,103 @@ +--- +title: "الانتقال من LangGraph إلى CrewAI: دليل عملي للمهندسين" +description: إذا كنت قد بنيت بالفعل مع LangGraph، تعلم كيفية نقل مشاريعك بسرعة إلى CrewAI +icon: switch +mode: "wide" +--- + +لقد بنيت Agents مع LangGraph. لقد تعاملت مع `StateGraph`، وربطت الحواف الشرطية، وصححت أخطاء قواميس الحالة في الثانية صباحًا. إنه يعمل — لكن في مرحلة ما، بدأت تتساءل عما إذا كان هناك مسار أفضل نحو الإنتاج. + +هناك بالفعل. **CrewAI Flows** يمنحك نفس القوة — تنسيق قائم على الأحداث، توجيه شرطي، حالة مشتركة — مع نموذج كود أبسط بشكل كبير ونموذج ذهني يتماشى مع طريقة تفكيرك الفعلية في سير عمل AI متعدد الخطوات. + +تمشي هذه المقالة عبر المفاهيم الأساسية جنبًا إلى جنب، وتعرض مقارنات كود حقيقية، وتوضح لماذا CrewAI Flows هو إطار العمل الذي ستريد الوصول إليه بعد ذلك. + +--- + +## تحول النموذج الذهني + +LangGraph يطلب منك التفكير في **رسوم بيانية**: عقد وحواف وقواميس حالة. كل سير عمل هو رسم بياني موجّه تربط فيه الانتقالات صراحةً بين خطوات الحساب. + +CrewAI Flows يطلب منك التفكير في **أحداث**: طرق تبدأ الأشياء، وطرق تستمع للنتائج، وطرق توجّه التنفيذ. طوبولوجيا سير العمل تنبثق من تعليقات المزخرفات بدلاً من بناء رسم بياني صريح. + +إليك الخريطة الأساسية: + +| مفهوم LangGraph | المكافئ في CrewAI Flows | +| --- | --- | +| `StateGraph` class | `Flow` class | +| `add_node()` | طرق مزخرفة بـ `@start`، `@listen` | +| `add_edge()` / `add_conditional_edges()` | مزخرفات `@listen()` / `@router()` | +| `TypedDict` state | حالة Pydantic `BaseModel` | +| `START` / `END` constants | مزخرف `@start()` / إرجاع طبيعي للطريقة | +| `graph.compile()` | `flow.kickoff()` | +| Checkpointer / persistence | ذاكرة مدمجة (مدعومة بـ LanceDB) | + +--- + +## العرض 1: خط أنابيب تسلسلي بسيط + +تخيل أنك تبني خط أنابيب يأخذ موضوعًا، ويبحث فيه، ويكتب ملخصًا، وينسّق المخرجات. راجع الملف الإنجليزي الأصلي لأمثلة الكود الكاملة لكلا النهجين. + +الفرق الرئيسي: لا بناء رسم بياني، لا ربط حواف، لا خطوة ترجمة. ترتيب التنفيذ مُعلَن مباشرة حيث يوجد المنطق. `@start()` يحدد نقطة الدخول، و`@listen(method_name)` يربط الخطوات. + +--- + +## العرض 2: التوجيه الشرطي + +مزخرف `@router()` يحوّل طريقة إلى نقطة قرار. يعيد سلسلة تطابق مستمعًا — بلا قواميس تعيين، بلا دوال توجيه منفصلة. منطق التفرع يُقرأ كتعبير `if` في Python لأنه كذلك فعلاً. + +--- + +## العرض 3: دمج فرق Agents AI في Flows + +هنا تتجلى القوة الحقيقية لـ CrewAI. الـ Flows لا تقتصر على ربط استدعاءات LLM — بل تنسّق **Crews** كاملة من Agents مستقلة. + +الفكرة الرئيسية: **الـ Flows توفر طبقة التنسيق، والـ Crews توفر طبقة الذكاء.** كل خطوة في Flow يمكنها تشغيل فريق كامل من Agents متعاونة. + +--- + +## العرض 4: التنفيذ المتوازي والمزامنة + +المشغّل `and_()` على مزخرف `@listen` يضمن أن الطريقة تُنفَّذ فقط بعد اكتمال *جميع* الطرق السابقة. هناك أيضًا `or_()` للمتابعة بمجرد اكتمال *أي* مهمة سابقة. + +--- + +## لماذا CrewAI Flows للإنتاج + +- **حفظ حالة مدمج.** حالة Flow مدعومة بـ LanceDB. +- **إدارة حالة آمنة الأنواع.** نماذج Pydantic توفر التحقق والتسلسل ودعم IDE. +- **تنسيق Agents أصلي.** الـ Crews بنية أساسية أصلية. +- **نموذج ذهني أبسط.** المزخرفات تعلن عن النية. +- **تكامل CLI.** شغّل Flows بـ `crewai run`. + +--- + +## ورقة الغش للترحيل + +1. **عيّن حالتك.** حوّل `TypedDict` إلى Pydantic `BaseModel`. +2. **حوّل العقد إلى طرق.** كل دالة `add_node` تصبح طريقة على فئة `Flow` الفرعية. +3. **استبدل الحواف بمزخرفات.** `add_edge(START, "first_node")` يصبح `@start()`. `add_edge("a", "b")` يصبح `@listen(a)`. +4. **استبدل الحواف الشرطية بـ `@router`.** دالة التوجيه و`add_conditional_edges()` تصبح طريقة `@router()` واحدة. +5. **استبدل compile + invoke بـ kickoff.** احذف `graph.compile()`. استدعِ `flow.kickoff()` بدلاً منه. +6. **فكّر أين تناسب الـ Crews.** أي عقدة بها منطق Agent معقد متعدد الخطوات هي مرشحة لاستخراجها في Crew. + +--- + +## البدء + +```bash +pip install crewai +crewai create flow my_first_flow +cd my_first_flow +``` + +```bash +crewai run +``` + +--- + +## أفكار أخيرة + +LangGraph علّم المنظومة أن سير عمل AI تحتاج هيكلاً. كان ذلك درسًا مهمًا. لكن CrewAI Flows يأخذ ذلك الدرس ويقدمه في شكل أسرع في الكتابة وأسهل في القراءة وأقوى في الإنتاج — خاصة عندما تتضمن سير عملك عدة Agents متعاونة. + +ابدأ بـ `crewai create flow`. لن تنظر للخلف. diff --git a/docs/v1.15.1/ar/guides/migration/upgrading-crewai.mdx b/docs/v1.15.1/ar/guides/migration/upgrading-crewai.mdx new file mode 100644 index 000000000..372689335 --- /dev/null +++ b/docs/v1.15.1/ar/guides/migration/upgrading-crewai.mdx @@ -0,0 +1,190 @@ +--- +title: "ترقية CrewAI" +description: "كيفية ترقية CrewAI في مشروعك والتكيّف مع التغييرات الجذرية بين الإصدارات." +icon: "arrow-up-circle" +--- + +## نظرة عامة + +تجلب إصدارات CrewAI قدرات جديدة بانتظام. يرشدك هذا الدليل خلال الخطوات العملية للحفاظ على تثبيتك محدّثًا — سواء أداة سطر الأوامر أو البيئة الافتراضية لمشروعك. + +إذا كنت تبدأ من الصفر، راجع [التثبيت](/ar/installation). إذا كنت قادمًا من إطار عمل آخر، راجع [الترحيل من LangGraph](/ar/guides/migration/migrating-from-langgraph). + +--- + +## الشيئان اللذان قد ترغب في ترقيتهما + +يوجد CrewAI في مكانين على جهازك، ويتم ترقيتهما بشكل مستقل: + +| ماذا | كيف يُثبَّت | كيف تتم الترقية | +|---|---|---| +| **أداة سطر الأوامر العامة `crewai`** | `uv tool install crewai` | `uv tool install crewai --upgrade` | +| **بيئة venv للمشروع** (حيث يعمل الكود) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` ثم `crewai install` | + +يمكن لهما — وغالبًا ما يحدث — أن يخرجا عن التزامن. تشغيل `crewai --version` يُظهر إصدار سطر الأوامر. تشغيل `uv pip show crewai` داخل مشروعك يُظهر إصدار venv. إذا اختلفا، فهذا طبيعي؛ ما يهم بالنسبة للكود قيد التشغيل هو إصدار venv. + +## لماذا لا يقوم `crewai install` وحده بالترقية + +`crewai install` هو غلاف رفيع حول `uv sync`. يُثبّت بالضبط ما يقوله ملف `uv.lock` الحالي — وهو **لا** يرفع أي قيود إصدار. + +إذا كان `pyproject.toml` يقول `crewai>=1.11.1` وقد قام ملف القفل بحلّه إلى `1.11.1`، فإن تشغيل `crewai install` سيُبقيك على `1.11.1` للأبد، حتى وإن كان الإصدار `1.14.4` متاحًا. + +للترقية فعلًا، عليك: + +1. تحديث قيد الإصدار في `pyproject.toml` +2. إعادة حلّ ملف القفل +3. مزامنة venv + +`uv add` يقوم بالثلاثة في خطوة واحدة. + +## كيفية ترقية مشروعك + +```bash +# يرفع القيد ويعيد القفل في أمر واحد +uv add "crewai[tools]>=1.14.4" + +# يزامن venv (crewai install يستدعي uv sync تحت الغطاء) +crewai install + +# تحقّق +uv pip show crewai +# → Version: 1.14.4 +``` + +استبدل `[tools]` بأي إضافات يستخدمها مشروعك (مثلًا `[tools,anthropic]`). تحقّق من قائمة `dependencies` في `pyproject.toml` إن لم تكن متأكدًا. + + + يحدّث `uv add` كلا من `pyproject.toml` **و** `uv.lock` بشكل ذرّي. إذا قمت بتحرير `pyproject.toml` يدويًا، فإنك لا تزال بحاجة إلى تشغيل `uv lock --upgrade-package crewai` لإعادة حلّ ملف القفل قبل أن يلتقط `crewai install` الإصدار الجديد. + + +## ترقية أداة سطر الأوامر العامة + +أداة سطر الأوامر العامة منفصلة عن مشروعك. قم بترقيتها عبر: + +```bash +uv tool install crewai --upgrade +``` + +إذا حذّرك الـ shell بشأن `PATH` بعد الترقية، قم بتحديثه: + +```bash +uv tool update-shell +``` + +هذا **لا** يمسّ بيئة venv الخاصة بمشروعك — لا تزال بحاجة إلى `uv add` + `crewai install` داخل المشروع. + +## التحقق من تزامن الاثنين + +```bash +# إصدار سطر الأوامر العام +crewai --version + +# إصدار venv للمشروع +uv pip show crewai | grep Version +``` + +ليس من الضروري أن يتطابقا — لكن إصدار venv للمشروع هو ما يهم لسلوك التشغيل. + + + يتطلب CrewAI `Python >=3.10, <3.14`. إذا كان `uv` مثبَّتًا مقابل مفسّر أقدم، فأعد إنشاء venv للمشروع باستخدام إصدار Python مدعوم قبل تشغيل `crewai install`. + + +--- + +## التغييرات الجذرية وملاحظات الترحيل + +تتطلب معظم الترقيات تعديلات صغيرة فقط. المناطق أدناه هي تلك التي تنكسر بصمت أو بتتبعات مكدّس مربكة. + +### مسارات الاستيراد: tools و`BaseTool` + +الموقع الرسمي لاستيراد الـ tools هو `crewai.tools`. لا تزال المسارات القديمة تظهر في الدروس لكن يجب تحديثها. + +```python +# قبل +from crewai_tools import BaseTool +from crewai.agents.tools import tool + +# بعد +from crewai.tools import BaseTool, tool +``` + +كلٌ من المُزخرف `@tool` والفئة الفرعية `BaseTool` يقعان في `crewai.tools`. `AgentFinish` والرموز الأخرى الداخلية للوكيل لم تعد جزءًا من السطح العام — إذا كنت تستوردها، فانتقل إلى event listeners أو callbacks الـ `Task` بدلًا منها. + +### تغييرات معاملات `Agent` + +```python +from crewai import Agent + +agent = Agent( + role="Researcher", + goal="Find authoritative sources on {topic}", + backstory="You are a careful, source-driven researcher.", + llm="gpt-4o-mini", # اسم نموذج كسلسلة نصية أو كائن LLM + verbose=True, # bool وليس مستوى عددي صحيح + max_iter=15, # تغيّر الافتراضي بين الإصدارات — حدّده بشكل صريح + allow_delegation=False, +) +``` + +- يقبل `llm` إما اسم نموذج كسلسلة نصية (يُحلَّ عبر المزوّد المهيّأ) أو كائن `LLM` للتحكم الدقيق. +- `verbose` هو `bool` بسيط. تمرير عدد صحيح لم يعد يبدّل مستويات السجل. +- تغيّرت افتراضات `max_iter` بين الإصدارات. إذا توقف وكيلك بصمت عن التكرار بعد أول استدعاء tool، فحدّد `max_iter` صراحةً. + +### معاملات `Crew` + +```python +from crewai import Crew, Process + +crew = Crew( + agents=[...], + tasks=[...], + process=Process.sequential, # أو Process.hierarchical + memory=True, + cache=True, + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}}, +) +``` + +- يتطلب `process=Process.hierarchical` إما `manager_llm=` أو `manager_agent=`. بدون أحدهما، يرفع kickoff خطأً عند التحقّق. +- `memory=True` مع مزوّد embedding غير افتراضي يحتاج إلى قاموس `embedder` — راجع [إعداد الذاكرة وembedder](#memory-embedder-config) أدناه. + +### الإخراج المُهيكل لـ `Task` + +استخدم `output_pydantic` أو `output_json` أو `output_file` لإلزام نتيجة المهمة بشكل مكتوب الأنواع: + +```python +from pydantic import BaseModel +from crewai import Task + +class Article(BaseModel): + title: str + body: str + +write = Task( + description="Write an article about {topic}", + expected_output="A short article with a title and body", + agent=writer, + output_pydantic=Article, # الفئة، وليس مثيلًا منها + output_file="output/article.md", +) +``` + +`output_pydantic` يأخذ **الفئة** نفسها. تمرير `Article(title="", body="")` خطأ شائع ويفشل بخطأ تحقّق مربك. + +### إعداد الذاكرة وembedder {#memory-embedder-config} + +إذا كان `memory=True` وأنت لا تستخدم embeddings الافتراضية الخاصة بـ OpenAI، فيجب أن تمرّر `embedder`: + +```python +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={ + "provider": "ollama", + "config": {"model": "nomic-embed-text"}, + }, +) +``` + +ضع بيانات اعتماد المزوّد المعنيّة (`OPENAI_API_KEY`, `OLLAMA_HOST`, إلخ) في ملف `.env`. مسارات تخزين الذاكرة محلية بالنسبة للمشروع افتراضيًا — احذف مجلد ذاكرة المشروع إذا غيّرت embedders، لأن الأبعاد لا تختلط. diff --git a/docs/v1.15.1/ar/guides/tools/publish-custom-tools.mdx b/docs/v1.15.1/ar/guides/tools/publish-custom-tools.mdx new file mode 100644 index 000000000..f181e0e25 --- /dev/null +++ b/docs/v1.15.1/ar/guides/tools/publish-custom-tools.mdx @@ -0,0 +1,96 @@ +--- +title: نشر أدوات مخصصة +description: كيفية بناء وتعبئة ونشر أدواتك الخاصة المتوافقة مع CrewAI على PyPI ليتمكن أي مستخدم CrewAI من تثبيتها واستخدامها. +icon: box-open +mode: "wide" +--- + +## نظرة عامة + +نظام الأدوات في CrewAI مصمم للتوسيع. إذا بنيت أداة يمكن أن تفيد الآخرين، يمكنك تعبئتها كمكتبة Python مستقلة ونشرها على PyPI وإتاحتها لأي مستخدم CrewAI — دون الحاجة لطلب سحب إلى مستودع CrewAI. + +يمشي هذا الدليل عبر العملية الكاملة: تنفيذ عقد الأدوات، وهيكلة حزمتك، والنشر على PyPI. + + +إذا كنت تحتاج فقط أداة مخصصة لمشروعك، راجع دليل [إنشاء أدوات مخصصة](/ar/learn/create-custom-tools) بدلاً من ذلك. + + +## عقد الأدوات + +كل أداة CrewAI يجب أن تستوفي إحدى الواجهتين: + +### الخيار 1: وراثة `BaseTool` + +ورث من `crewai.tools.BaseTool` وطبّق طريقة `_run`. عرّف `name` و`description` واختياريًا `args_schema` للتحقق من المدخلات. + +```python +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + + +class GeolocateInput(BaseModel): + """Input schema for GeolocateTool.""" + address: str = Field(..., description="The street address to geolocate.") + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + args_schema: type[BaseModel] = GeolocateInput + + def _run(self, address: str) -> str: + return f"40.7128, -74.0060" +``` + +### الخيار 2: استخدام مزخرف `@tool` + +للأدوات الأبسط، يحوّل مزخرف `@tool` دالة إلى أداة CrewAI. يجب أن تحتوي الدالة على سلسلة توثيق (تُستخدم كوصف الأداة) وتعليقات أنواع. + +```python +from crewai.tools import tool + + +@tool("Geolocate") +def geolocate(address: str) -> str: + """Converts a street address into latitude/longitude coordinates.""" + return "40.7128, -74.0060" +``` + +### المتطلبات الأساسية + +بغض النظر عن النهج الذي تستخدمه، يجب أن تحتوي أداتك على: + +- **`name`** — معرّف قصير ووصفي. +- **`description`** — يخبر الـ Agent متى وكيف يستخدم الأداة. +- **`_run`** (BaseTool) أو **جسم الدالة** (@tool) — منطق التنفيذ المتزامن. +- **تعليقات أنواع** على جميع المعاملات وقيم الإرجاع. +- إرجاع نتيجة **نصية** (أو شيء يمكن تحويله لنص). + +## هيكل الحزمة + +``` +crewai-geolocate/ +├── pyproject.toml +├── LICENSE +├── README.md +└── src/ + └── crewai_geolocate/ + ├── __init__.py + └── tools.py +``` + +## النشر على PyPI + +```bash +# Build the package +uv build + +# Publish to PyPI +uv publish +``` + +بعد النشر، يمكن للمستخدمين تثبيت أداتك بـ: + +```bash +uv add crewai-geolocate +``` diff --git a/docs/v1.15.1/ar/index.mdx b/docs/v1.15.1/ar/index.mdx new file mode 100644 index 000000000..d74de8278 --- /dev/null +++ b/docs/v1.15.1/ar/index.mdx @@ -0,0 +1,105 @@ +--- +title: "توثيق CrewAI" +description: "ابنِ Agents ذكاء اصطناعي تعاونية وCrews وFlows — جاهزة للإنتاج من اليوم الأول." +icon: "house" +mode: "wide" +--- + +
+ CrewAI +
+

أطلق أنظمة متعددة الـ Agents بثقة

+

+ صمم Agents، ونسّق Crews، وأتمت Flows مع حواجز حماية وذاكرة ومعرفة ومراقبة مدمجة. +

+
+ + + +
+ +
+ +## ابدأ + + + + نظرة عامة على مفاهيم CrewAI وبنيته المعمارية وما يمكنك بناؤه باستخدام Agents وCrews وFlows. + + + التثبيت عبر `uv`، وإعداد مفاتيح API، وتهيئة CLI للتطوير المحلي. + + + أنشئ أول Crew لك في دقائق. تعلم بيئة التشغيل الأساسية وهيكل المشروع ودورة التطوير. + + + +## ابنِ الأساسيات + + + + أنشئ Agents بأدوات وذاكرة ومعرفة ومخرجات منظمة باستخدام Pydantic. يتضمن قوالب وأفضل الممارسات. + + + نسّق خطوات start/listen/router، وأدر الحالة، واحفظ التنفيذ، واستأنف سير العمل الطويل. + + + حدد عمليات متسلسلة أو هرمية أو مختلطة مع حواجز حماية واستدعاءات راجعة ومحفزات تدخل بشري. + + + +## رحلة المؤسسات + + + + إدارة البيئات وإعادة النشر بأمان ومراقبة التشغيل المباشر من لوحة تحكم المؤسسات. + + + ربط Gmail وSlack وSalesforce والمزيد. تمرير بيانات المحفزات إلى Crews وFlows تلقائيًا. + + + دعوة أعضاء الفريق وتهيئة التحكم في الوصول المبني على الأدوار وإدارة الوصول إلى أتمتة الإنتاج. + + + +## ما الجديد + + + + نظرة شاملة موحدة على Gmail وDrive وOutlook وTeams وOneDrive وHubSpot والمزيد — الآن مع نماذج بيانات وCrews. + + + استدعاء أتمتة CrewAI الحالية أو Amazon Bedrock Agents مباشرة من Crews باستخدام مجموعة أدوات التكامل المحدّثة. + + + + + تصفح الأمثلة وكتب الوصفات للحصول على تطبيقات مرجعية شاملة عبر Agents وFlows وأتمتة المؤسسات. + + +## ابقَ على تواصل + + + + إذا ساعدك CrewAI في الإطلاق بشكل أسرع، امنحنا نجمة وشارك مشاريعك مع المجتمع. + + + اطرح أسئلة واعرض سير العمل واطلب ميزات جديدة جنبًا إلى جنب مع المطورين الآخرين. + + diff --git a/docs/v1.15.1/ar/installation.mdx b/docs/v1.15.1/ar/installation.mdx new file mode 100644 index 000000000..1b6df571c --- /dev/null +++ b/docs/v1.15.1/ar/installation.mdx @@ -0,0 +1,216 @@ +--- +title: التثبيت +description: ابدأ مع CrewAI - التثبيت والتهيئة وبناء أول فريق AI +icon: wrench +mode: "wide" +--- + +### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills + +قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI. + +يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills` + + + +## فيديو تعليمي + +شاهد هذا الفيديو التعليمي لعرض تفصيلي لعملية التثبيت: + + + +## دليل نصي + + + **متطلبات إصدار Python** + +يتطلب CrewAI إصدار `Python >=3.10 and <3.14`. إليك كيفية التحقق من إصدارك: + +```bash +python3 --version +``` + +إذا كنت بحاجة لتحديث Python، قم بزيارة [python.org/downloads](https://python.org/downloads) + + + + + **متطلبات OpenAI SDK** + +يتطلب CrewAI 0.175.0 إصدار `openai >= 1.13.3`. إذا كنت تدير التبعيات بنفسك، تأكد من أن بيئتك تستوفي هذا الشرط لتجنب مشاكل الاستيراد/التشغيل. + + + +يستخدم CrewAI أداة `uv` لإدارة التبعيات والحزم. وهي تبسّط إعداد المشروع وتنفيذه وتوفر تجربة سلسة. + +إذا لم تكن قد ثبّتت `uv` بعد، اتبع **الخطوة 1** لإعدادها بسرعة على نظامك، وإلا يمكنك الانتقال إلى **الخطوة 2**. + + + + - **على macOS/Linux:** + + استخدم `curl` لتحميل السكريبت وتنفيذه عبر `sh`: + + ```shell + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + إذا لم يكن `curl` متاحًا على نظامك، يمكنك استخدام `wget`: + + ```shell + wget -qO- https://astral.sh/uv/install.sh | sh + ``` + + - **على Windows:** + + استخدم `irm` لتحميل السكريبت و`iex` لتنفيذه: + + ```shell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + إذا واجهت أي مشاكل، راجع [دليل تثبيت UV](https://docs.astral.sh/uv/getting-started/installation/) لمزيد من المعلومات. + + + + - شغّل الأمر التالي لتثبيت واجهة سطر أوامر `crewai`: + ```shell + uv tool install crewai + ``` + + إذا ظهر تحذير بشأن `PATH`، شغّل هذا الأمر لتحديث الصدفة: + ```shell + uv tool update-shell + ``` + + + + إذا واجهت خطأ بناء `chroma-hnswlib==0.7.6` (`fatal error C1083: Cannot open include file: 'float.h'`) على Windows، ثبّت [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) مع خيار *Desktop development with C++*. + + + - للتحقق من تثبيت `crewai`، شغّل: + ```shell + uv tool list + ``` + - يجب أن ترى شيئًا مثل: + ```shell + crewai v0.102.0 + - crewai + ``` + - إذا كنت بحاجة لتحديث `crewai`، شغّل: + ```shell + uv tool install crewai --upgrade + ``` + تم التثبيت بنجاح! أنت جاهز لإنشاء أول Crew! + + + + +# إنشاء مشروع CrewAI + +يقوم `crewai create crew` الآن بإنشاء مشروع crew بأسلوب JSON-first. توضع الـ Agents في `agents/*.jsonc`، وتوضع المهام وإعدادات الـ crew في `crew.jsonc`، ويحمّل `crewai run` هذا التعريف مباشرة. + + + + - شغّل أمر `crewai` عبر CLI: + ```shell + crewai create crew + ``` + + - سينشئ هذا مشروعًا جديدًا بالهيكل التالي: + ``` + my_project/ + ├── .gitignore + ├── .env + ├── agents/ + │ └── researcher.jsonc + ├── crew.jsonc + ├── knowledge/ + ├── pyproject.toml + ├── README.md + ├── skills/ + └── tools/ + ``` + + - إذا احتجت إلى البنية القديمة Python/YAML التي تحتوي على `crew.py` و `config/agents.yaml` و `config/tasks.yaml`، شغّل: + ```shell + crewai create crew --classic + ``` + + + + + - سيحتوي مشروعك على هذه الملفات الأساسية: + | الملف | الغرض | + | --- | --- | + | `crew.jsonc` | إعداد الـ crew وترتيب المهام والعملية وقيم الإدخال الافتراضية | + | `agents/*.jsonc` | تعريف دور كل Agent وهدفه و backstory والـ LLM والأدوات والسلوك | + | `.env` | تخزين مفاتيح API ومتغيرات البيئة | + | `tools/` | ملفات Python اختيارية لأدوات `custom:` | + | `knowledge/` | ملفات معرفة اختيارية للـ Agents | + | `skills/` | ملفات skills اختيارية تطبق على الـ crew | + + - ابدأ بتحرير `crew.jsonc` والملفات داخل `agents/` لتعريف سلوك الـ crew. + - استخدم قيم `{placeholder}` في نصوص الـ Agents والمهام، ثم ضع القيم الافتراضية في `inputs` داخل `crew.jsonc`. عند تشغيل `crewai run` ستطلب CLI أي قيم ناقصة. + - احتفظ بالمعلومات الحساسة مثل مفاتيح API في `.env`. + + + + + - قبل تشغيل الـ Crew، تأكد من تنفيذ: + ```bash + crewai install + ``` + - إذا كنت بحاجة لتثبيت حزم إضافية، استخدم: + ```shell + uv add + ``` + - لتشغيل الـ Crew، نفّذ الأمر التالي في جذر مشروعك: + ```bash + crewai run + ``` + + + +## خيارات التثبيت للمؤسسات + + +للفرق والمؤسسات، يوفر CrewAI خيارات نشر مؤسسية تزيل تعقيد الإعداد: + +### CrewAI AMP (SaaS) + +- لا يتطلب أي تثبيت - فقط سجّل مجانًا على [app.crewai.com](https://app.crewai.com) +- تحديثات وصيانة تلقائية +- بنية تحتية مُدارة وقابلة للتوسع +- بناء Crews بدون كتابة كود + +### CrewAI Factory (استضافة ذاتية) + +- نشر بالحاويات على بنيتك التحتية +- يدعم أي مزود سحابي بما في ذلك النشر المحلي +- تكامل مع أنظمة الأمان الحالية + + + تعرّف على عروض CrewAI للمؤسسات وجدول عرضًا توضيحيًا + + + +## الخطوات التالية + + + + اتبع البداية السريعة لإنشاء Flow وتشغيل طاقم بوكيل واحد وإنتاج تقرير. + + + تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI. + + diff --git a/docs/v1.15.1/ar/introduction.mdx b/docs/v1.15.1/ar/introduction.mdx new file mode 100644 index 000000000..58d441c6e --- /dev/null +++ b/docs/v1.15.1/ar/introduction.mdx @@ -0,0 +1,152 @@ +--- +title: مقدمة +description: ابنِ فرق Agents ذكاء اصطناعي تعمل معًا لمعالجة المهام المعقدة +icon: handshake +mode: "wide" +--- + +# ما هو CrewAI؟ + +**CrewAI هو إطار العمل مفتوح المصدر الرائد لتنسيق Agents الذكاء الاصطناعي المستقلة وبناء سير العمل المعقدة.** + +يمكّن المطورين من بناء أنظمة متعددة الـ Agents جاهزة للإنتاج من خلال الجمع بين الذكاء التعاوني لـ **Crews** والتحكم الدقيق لـ **Flows**. + +- **[CrewAI Flows](/ar/guides/flows/first-flow)**: العمود الفقري لتطبيق الذكاء الاصطناعي. تتيح لك Flows إنشاء سير عمل منظمة قائمة على الأحداث تدير الحالة وتتحكم في التنفيذ. وهي توفر البنية الأساسية التي تعمل ضمنها Agents الذكاء الاصطناعي. +- **[CrewAI Crews](/ar/guides/crews/first-crew)**: وحدات العمل ضمن Flow. الـ Crews هي فرق من Agents مستقلة تتعاون لحل مهام محددة يفوضها إليها Flow. + +مع أكثر من 100,000 مطور معتمد عبر دوراتنا المجتمعية، يُعد CrewAI المعيار لأتمتة الذكاء الاصطناعي الجاهزة للمؤسسات. + +### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills + +قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI. + +يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills` + + + +## بنية CrewAI المعمارية + +صُممت بنية CrewAI لتحقيق التوازن بين الاستقلالية والتحكم. + +### 1. Flows: العمود الفقري + + + فكّر في Flow كـ "المدير" أو "تعريف العملية" لتطبيقك. يحدد الخطوات والمنطق وكيفية تدفق البيانات عبر نظامك. + + + + نظرة عامة على إطار عمل CrewAI + + +توفر Flows: +- **إدارة الحالة**: حفظ البيانات عبر الخطوات والتنفيذات. +- **تنفيذ قائم على الأحداث**: تشغيل إجراءات بناءً على أحداث أو مدخلات خارجية. +- **التحكم في التدفق**: استخدام المنطق الشرطي والحلقات والتفرع. + +### 2. Crews: الذكاء + + + الـ Crews هي "الفرق" التي تقوم بالعمل الثقيل. ضمن Flow، يمكنك تشغيل Crew لمعالجة مشكلة معقدة تتطلب إبداعًا وتعاونًا. + + + + نظرة عامة على إطار عمل CrewAI + + +توفر Crews: +- **Agents بأدوار محددة**: Agents متخصصة بأهداف وأدوات محددة. +- **تعاون مستقل**: تعمل الـ Agents معًا لحل المهام. +- **تفويض المهام**: يتم تعيين المهام وتنفيذها بناءً على قدرات الـ Agent. + +## كيف يعمل الكل معًا + +1. يبدأ **Flow** حدثًا أو يشغّل عملية. +2. يدير **Flow** الحالة ويقرر ما يجب فعله بعد ذلك. +3. يفوّض **Flow** مهمة معقدة إلى **Crew**. +4. تتعاون Agents الـ **Crew** لإكمال المهمة. +5. يعيد **Crew** النتيجة إلى **Flow**. +6. يستمر **Flow** في التنفيذ بناءً على النتيجة. + +## الميزات الرئيسية + + + + ابنِ سير عمل موثوقة وذات حالة يمكنها التعامل مع العمليات طويلة التشغيل والمنطق المعقد. + + + انشر فرقًا من الـ Agents يمكنها التخطيط والتنفيذ والتعاون لتحقيق أهداف عالية المستوى. + + + اربط Agents بأي API أو قاعدة بيانات أو أداة محلية. + + + مصمم مع مراعاة الأمان والامتثال لعمليات نشر المؤسسات. + + + +## متى تستخدم Crews مقابل Flows + +**الإجابة المختصرة: استخدم كليهما.** + +لأي تطبيق جاهز للإنتاج، **ابدأ بـ Flow**. + +- **استخدم Flow** لتعريف الهيكل العام والحالة والمنطق لتطبيقك. +- **استخدم Crew** ضمن خطوة Flow عندما تحتاج فريقًا من الـ Agents لأداء مهمة معقدة محددة تتطلب استقلالية. + +| حالة الاستخدام | البنية المعمارية | +| :--- | :--- | +| **أتمتة بسيطة** | Flow واحد مع مهام Python | +| **بحث معقد** | Flow يدير الحالة -> Crew يجري البحث | +| **واجهة تطبيق خلفية** | Flow يعالج طلبات API -> Crew ينشئ المحتوى -> Flow يحفظ في قاعدة البيانات | + +## لماذا تختار CrewAI؟ + +- **تشغيل مستقل**: تتخذ الـ Agents قرارات ذكية بناءً على أدوارها وأدواتها المتاحة +- **تفاعل طبيعي**: تتواصل الـ Agents وتتعاون كأعضاء فريق بشري +- **تصميم قابل للتوسيع**: سهولة إضافة أدوات وأدوار وقدرات جديدة +- **جاهز للإنتاج**: مبني للموثوقية والتوسع في التطبيقات الواقعية +- **موجّه نحو الأمان**: مصمم مع مراعاة متطلبات أمان المؤسسات +- **كفاءة التكلفة**: محسّن لتقليل استخدام الرموز المميزة واستدعاءات API + +## هل أنت مستعد للبدء في البناء؟ + + + + تعلم كيفية إنشاء سير عمل منظمة قائمة على الأحداث مع تحكم دقيق في التنفيذ. + + + دليل تفصيلي لإنشاء فريق AI تعاوني يعمل معًا لحل المشكلات المعقدة. + + + + + + ابدأ مع CrewAI في بيئة التطوير الخاصة بك. + + + أنشئ Flow وشغّل طاقمًا بوكيل واحد وأنشئ تقريرًا من البداية للنهاية. + + + تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI. + + diff --git a/docs/v1.15.1/ar/learn/a2a-agent-delegation.mdx b/docs/v1.15.1/ar/learn/a2a-agent-delegation.mdx new file mode 100644 index 000000000..d743d98fb --- /dev/null +++ b/docs/v1.15.1/ar/learn/a2a-agent-delegation.mdx @@ -0,0 +1,87 @@ +--- +title: بروتوكول Agent-to-Agent (A2A) +description: الـ Agents تفوّض المهام إلى Agents A2A بعيدة و/أو تعمل كـ Agents خادم متوافقة مع A2A. +icon: network-wired +mode: "wide" +--- + +## تفويض Agent A2A + +يعامل CrewAI [بروتوكول A2A](https://a2a-protocol.org/latest/) كبنية تفويض أساسية، مما يمكّن الـ Agents من تفويض المهام وطلب المعلومات والتعاون مع Agents بعيدة، وكذلك العمل كـ Agents خادم متوافقة مع A2A. في وضع العميل، تختار الـ Agents تلقائيًا بين التنفيذ المحلي والتفويض البعيد بناءً على متطلبات المهمة. + +## كيف يعمل + +عندما يُهيَّأ Agent بقدرات A2A: + +1. يحلل الـ Agent كل مهمة +2. يقرر إما: + - معالجة المهمة مباشرة باستخدام قدراته الخاصة + - التفويض إلى Agent A2A بعيد للمعالجة المتخصصة +3. إذا فوّض، يتواصل الـ Agent مع Agent A2A البعيد عبر البروتوكول +4. تُعاد النتائج إلى سير عمل CrewAI + + + تفويض A2A يتطلب حزمة `a2a-sdk`. ثبّتها بـ: `uv add 'crewai[a2a]'` أو `pip install 'crewai[a2a]'` + + +## التهيئة الأساسية + + + `crewai.a2a.config.A2AConfig` مهمل وسيُزال في v2.0.0. استخدم `A2AClientConfig` للاتصال بـ Agents بعيدة و/أو `A2AServerConfig` لعرض الـ Agents كخوادم. + + +```python Code +from crewai import Agent, Crew, Task +from crewai.a2a import A2AClientConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks efficiently", + backstory="Expert at delegating to specialized research agents", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://example.com/.well-known/agent-card.json", + timeout=120, + max_turns=10 + ) +) + +task = Task( + description="Research the latest developments in quantum computing", + expected_output="A comprehensive research report", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task], verbose=True) +result = crew.kickoff() +``` + +## خيارات تهيئة العميل + +راجع الملف الإنجليزي الأصلي للحصول على القائمة الكاملة لمعاملات `A2AClientConfig` وخيارات المصادقة وآليات التحديث وتهيئة الخادم. + +## أفضل الممارسات + + + + هيّئ المهلات بناءً على أوقات استجابة Agent A2A المتوقعة. + + + + استخدم `max_turns` لمنع التبادل المفرط. + + + + عيّن `fail_fast=False` لبيئات الإنتاج مع عدة Agents. + + + + خزّن رموز المصادقة وبيانات الاعتماد كمتغيرات بيئة، ليس في الكود. + + + +## تعلم المزيد + +- [توثيق بروتوكول A2A](https://a2a-protocol.org) +- [تطبيقات A2A النموذجية](https://github.com/a2aproject/a2a-samples) +- [A2A Python SDK](https://github.com/a2aproject/a2a-python) diff --git a/docs/v1.15.1/ar/learn/before-and-after-kickoff-hooks.mdx b/docs/v1.15.1/ar/learn/before-and-after-kickoff-hooks.mdx new file mode 100644 index 000000000..0766a0f0d --- /dev/null +++ b/docs/v1.15.1/ar/learn/before-and-after-kickoff-hooks.mdx @@ -0,0 +1,47 @@ +--- +title: خطافات قبل وبعد الانطلاق +description: تعلم كيفية استخدام خطافات قبل وبعد الانطلاق في CrewAI +mode: "wide" +--- + +يوفر CrewAI خطافات تتيح لك تنفيذ كود قبل وبعد انطلاق Crew. هذه الخطافات مفيدة لمعالجة المدخلات مسبقًا أو معالجة النتائج لاحقًا. + +## خطاف قبل الانطلاق + +يُنفَّذ خطاف قبل الانطلاق قبل أن يبدأ Crew مهامه. يتلقى قاموس المدخلات ويمكنه تعديله قبل تمريره إلى Crew. يمكنك استخدام هذا الخطاف لإعداد بيئتك أو تحميل البيانات اللازمة أو معالجة المدخلات مسبقًا. + +```python +from crewai import CrewBase +from crewai.project import before_kickoff + +@CrewBase +class MyCrew: + @before_kickoff + def prepare_data(self, inputs): + inputs['processed'] = True + return inputs +``` + +## خطاف بعد الانطلاق + +يُنفَّذ خطاف بعد الانطلاق بعد إتمام Crew مهامه. يتلقى كائن النتيجة الذي يحتوي على مخرجات تنفيذ Crew. هذا الخطاف مثالي لمعالجة النتائج لاحقًا مثل التسجيل أو تحويل البيانات أو التحليل الإضافي. + +```python +from crewai import CrewBase +from crewai.project import after_kickoff + +@CrewBase +class MyCrew: + @after_kickoff + def log_results(self, result): + print("Crew execution completed with result:", result) + return result +``` + +## استخدام كلا الخطافين + +يمكن استخدام كلا الخطافين معًا لتوفير عملية إعداد وتفكيك شاملة لتنفيذ Crew. وهما مفيدان بشكل خاص في الحفاظ على بنية كود نظيفة من خلال فصل المسؤوليات وتعزيز نمطية تنفيذات CrewAI. + +## الخلاصة + +توفر خطافات قبل وبعد الانطلاق في CrewAI طرقًا قوية للتفاعل مع دورة حياة تنفيذ Crew. من خلال فهم واستخدام هذه الخطافات، يمكنك تعزيز متانة ومرونة Agents الذكاء الاصطناعي بشكل كبير. diff --git a/docs/v1.15.1/ar/learn/bring-your-own-agent.mdx b/docs/v1.15.1/ar/learn/bring-your-own-agent.mdx new file mode 100644 index 000000000..d3b76446d --- /dev/null +++ b/docs/v1.15.1/ar/learn/bring-your-own-agent.mdx @@ -0,0 +1,41 @@ +--- +title: أحضر Agent الخاص بك +description: تعلم كيفية إحضار Agents خاصة بك تعمل ضمن Crew. +icon: robots +mode: "wide" +--- + +قابلية التشغيل البيني مفهوم أساسي في CrewAI. يوضح هذا الدليل كيفية إحضار Agents خاصة بك تعمل ضمن Crew. + +## دليل المحوّلات لإحضار Agents الخاصة (Agents من LangGraph وOpenAI وغيرها...) + +نتطلب 3 محوّلات لتحويل أي Agent من أطر عمل مختلفة للعمل ضمن Crew. + +1. BaseAgentAdapter +2. BaseToolAdapter +3. BaseConverter + +## BaseAgentAdapter + +تعرّف هذه الفئة المجردة الواجهة المشتركة والوظائف التي يجب أن تنفذها جميع محوّلات الـ Agent. تمتد BaseAgent للحفاظ على التوافق مع إطار عمل CrewAI مع إضافة متطلبات خاصة بالمحوّل. + +الطرق المطلوبة: + +1. `def configure_tools` +2. `def configure_structured_output` + +## إنشاء محوّل خاص بك + +لدمج Agent من إطار عمل مختلف في CrewAI، تحتاج لإنشاء محوّل مخصص بوراثة `BaseAgentAdapter`. يعمل هذا المحوّل كطبقة توافق تترجم بين واجهات CrewAI والمتطلبات المحددة للـ Agent الخارجي. + +راجع الملف الإنجليزي الأصلي لأمثلة الكود التفصيلية لتنفيذ BaseAgentAdapter وBaseToolAdapter وBaseConverter. + +## محوّلات جاهزة للاستخدام + +نوفر محوّلات جاهزة للأطر التالية: +1. LangGraph +2. OpenAI Agents + +## تشغيل Crew مع Agents محوّلة: + +راجع الملف الإنجليزي الأصلي للحصول على مثال الكود الكامل الذي يوضح استخدام CrewAI Agent وOpenAI Agent Adapter وLangGraph Agent Adapter معًا في Crew واحد. diff --git a/docs/v1.15.1/ar/learn/coding-agents.mdx b/docs/v1.15.1/ar/learn/coding-agents.mdx new file mode 100644 index 000000000..f5f2f18d9 --- /dev/null +++ b/docs/v1.15.1/ar/learn/coding-agents.mdx @@ -0,0 +1,80 @@ +--- +title: Agents البرمجة +description: تعلم كيفية تمكين Agents CrewAI من كتابة وتنفيذ الكود، واستكشف الميزات المتقدمة لوظائف محسّنة. +icon: rectangle-code +mode: "wide" +--- + +## مقدمة + +أصبح لدى CrewAI Agents القدرة القوية على كتابة وتنفيذ الكود، مما يعزز قدراتها في حل المشكلات بشكل كبير. هذه الميزة مفيدة بشكل خاص للمهام التي تتطلب حلولاً حسابية أو برمجية. + +## تمكين تنفيذ الكود + +لتمكين تنفيذ الكود لـ Agent، عيّن معامل `allow_code_execution` إلى `True` عند إنشاء الـ Agent. + +```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 +) +``` + + +لاحظ أن معامل `allow_code_execution` يكون `False` افتراضيًا. + + +## اعتبارات مهمة + +1. **اختيار النموذج**: يُوصى بشدة باستخدام نماذج أكثر قدرة مثل Claude 3.5 Sonnet وGPT-4 عند تمكين تنفيذ الكود. + +2. **معالجة الأخطاء**: تتضمن ميزة تنفيذ الكود معالجة أخطاء. إذا أثار الكود المُنفَّذ استثناءً، سيتلقى الـ Agent رسالة الخطأ ويمكنه محاولة تصحيح الكود. يتحكم معامل `max_retry_limit` (الافتراضي 2) في الحد الأقصى لعدد المحاولات. + +3. **التبعيات**: لاستخدام ميزة تنفيذ الكود، تحتاج لتثبيت حزمة `crewai_tools`. + +## عملية تنفيذ الكود + + + + يحلل الـ Agent المهمة ويحدد أن تنفيذ الكود ضروري. + + + يصيغ كود Python اللازم لحل المشكلة. + + + يُرسَل الكود إلى أداة تنفيذ الكود الداخلية (`CodeInterpreterTool`). + + + يفسر الـ Agent النتيجة ويدمجها في استجابته أو يستخدمها لمزيد من حل المشكلات. + + + +## مثال استخدام + +```python Code +from crewai import Agent, Task, Crew + +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 +) + +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants.", + agent=coding_agent +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +result = analysis_crew.kickoff() +print(result) +``` diff --git a/docs/v1.15.1/ar/learn/conditional-tasks.mdx b/docs/v1.15.1/ar/learn/conditional-tasks.mdx new file mode 100644 index 000000000..818d72aac --- /dev/null +++ b/docs/v1.15.1/ar/learn/conditional-tasks.mdx @@ -0,0 +1,14 @@ +--- +title: المهام الشرطية +description: تعلم كيفية استخدام المهام الشرطية في انطلاق crewAI +icon: diagram-subtask +mode: "wide" +--- + +## مقدمة + +تتيح المهام الشرطية في crewAI التكيف الديناميكي لسير العمل بناءً على نتائج المهام السابقة. تمكّن هذه الميزة القوية الـ Crews من اتخاذ قرارات وتنفيذ المهام بشكل انتقائي، مما يعزز مرونة وكفاءة عملياتك المدفوعة بالذكاء الاصطناعي. + +## مثال استخدام + +راجع الملف الإنجليزي الأصلي للحصول على مثال الكود الكامل الذي يوضح استخدام `ConditionalTask` مع دالة شرط `is_data_missing` للتحكم في تنفيذ المهام بناءً على مخرجات المهام السابقة. diff --git a/docs/v1.15.1/ar/learn/create-custom-tools.mdx b/docs/v1.15.1/ar/learn/create-custom-tools.mdx new file mode 100644 index 000000000..da82f5b45 --- /dev/null +++ b/docs/v1.15.1/ar/learn/create-custom-tools.mdx @@ -0,0 +1,77 @@ +--- +title: إنشاء أدوات مخصصة +description: دليل شامل لصياغة واستخدام وإدارة الأدوات المخصصة ضمن إطار عمل CrewAI، بما في ذلك الوظائف الجديدة ومعالجة الأخطاء. +icon: hammer +mode: "wide" +--- + +## إنشاء واستخدام الأدوات في CrewAI + +يقدم هذا الدليل تعليمات مفصلة لإنشاء أدوات مخصصة لإطار عمل CrewAI وكيفية إدارة واستخدام هذه الأدوات بكفاءة، مع دمج أحدث الوظائف مثل تفويض الأدوات ومعالجة الأخطاء واستدعاء الأدوات الديناميكي. + + + **هل تريد نشر أداتك للمجتمع؟** إذا كنت تبني أداة يمكن أن تفيد الآخرين، اطلع على دليل [نشر أدوات مخصصة](/ar/guides/tools/publish-custom-tools) لتعلم كيفية تعبئة وتوزيع أداتك على PyPI. + + +### وراثة `BaseTool` + +لإنشاء أداة مخصصة، ورث من `BaseTool` وعرّف السمات الضرورية بما في ذلك `args_schema` للتحقق من المدخلات وطريقة `_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: + return "Tool's result" +``` + +### استخدام مزخرف `tool` + +```python Code +from crewai.tools import tool + +@tool("Tool Name") +def my_simple_tool(question: str) -> str: + """Tool description for clarity.""" + return "Tool output" +``` + +### تعريف دالة تخزين مؤقت للأداة + +```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: + return True if some_condition else False + +cached_tool.cache_function = my_cache_strategy +``` + +### إنشاء أدوات غير متزامنة + +يدعم CrewAI الأدوات غير المتزامنة لعمليات I/O غير المحجوبة. + +```python Code +import aiohttp +from crewai.tools import tool + +@tool("Async Web Fetcher") +async def fetch_webpage(url: str) -> str: + """Fetch content from a webpage asynchronously.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` diff --git a/docs/v1.15.1/ar/learn/custom-llm.mdx b/docs/v1.15.1/ar/learn/custom-llm.mdx new file mode 100644 index 000000000..a02222356 --- /dev/null +++ b/docs/v1.15.1/ar/learn/custom-llm.mdx @@ -0,0 +1,55 @@ +--- +title: تنفيذ LLM مخصص +description: تعلم كيفية إنشاء تنفيذات LLM مخصصة في CrewAI. +icon: code +mode: "wide" +--- + +## نظرة عامة + +يدعم CrewAI تنفيذات LLM المخصصة من خلال فئة `BaseLLM` المجردة. يتيح لك ذلك دمج أي مزود LLM لا يحظى بدعم مدمج في LiteLLM، أو تنفيذ آليات مصادقة مخصصة. + +## بداية سريعة + +راجع الملف الإنجليزي الأصلي للحصول على تنفيذ LLM مخصص كامل يوضح طريقة `call()` المطلوبة والطرق الاختيارية مثل `supports_function_calling()` و`get_context_window_size()`. + +## استخدام LLM المخصص + +```python +from crewai import Agent, Task, Crew + +custom_llm = CustomLLM( + model="my-custom-model", + api_key="your-api-key", + endpoint="https://api.example.com/v1/chat/completions", + temperature=0.7 +) + +agent = Agent( + role="Research Assistant", + goal="Find and analyze information", + backstory="You are a research assistant.", + llm=custom_llm +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A comprehensive summary", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## الطرق المطلوبة + +### البنّاء: `__init__()` + +**مهم**: يجب استدعاء `super().__init__(model, temperature)` مع المعاملات المطلوبة. + +### الطريقة المجردة: `call()` + +طريقة `call()` هي قلب تنفيذ LLM. يجب أن تقبل الرسائل وتعيد استجابة نصية وتعالج الأدوات واستدعاء الدوال إذا كانت مدعومة. + +يغطي هذا الدليل أساسيات تنفيذ LLM مخصصة في CrewAI. diff --git a/docs/v1.15.1/ar/learn/custom-manager-agent.mdx b/docs/v1.15.1/ar/learn/custom-manager-agent.mdx new file mode 100644 index 000000000..c20f8a272 --- /dev/null +++ b/docs/v1.15.1/ar/learn/custom-manager-agent.mdx @@ -0,0 +1,81 @@ +--- +title: Agent مدير مخصص +description: تعلم كيفية تعيين Agent مخصص كمدير في CrewAI، مما يوفر مزيدًا من التحكم في إدارة المهام والتنسيق. +icon: user-shield +mode: "wide" +--- + +# تعيين Agent محدد كمدير في CrewAI + +يتيح CrewAI للمستخدمين تعيين Agent محدد كمدير للـ Crew، مما يوفر مزيدًا من التحكم في إدارة المهام وتنسيقها. + +## استخدام سمة `manager_agent` + +تتيح لك سمة `manager_agent` تعريف Agent مخصص لإدارة الـ Crew. سيشرف هذا الـ Agent على العملية بأكملها لضمان إتمام المهام بكفاءة وبأعلى المعايير. + +```python Code +import os +from crewai import Agent, Task, Crew, Process + +researcher = Agent( + role="Researcher", + goal="Conduct thorough research and analysis on AI and AI agents", + backstory="You're an expert researcher...", + allow_delegation=False, +) + +writer = Agent( + role="Senior Writer", + goal="Create compelling content about AI and AI agents", + backstory="You're a senior writer...", + allow_delegation=False, +) + +task = Task( + description="Generate a list of 5 interesting ideas for an article...", + expected_output="5 bullet points, each with a paragraph and accompanying notes.", +) + +manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager...", + allow_delegation=True, +) + +crew = Crew( + agents=[researcher, writer], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, +) + +result = crew.kickoff() +``` + +## فوائد Agent المدير المخصص + +- **تحكم محسّن**: تخصيص نهج الإدارة ليناسب الاحتياجات المحددة لمشروعك. +- **تنسيق محسّن**: ضمان تنسيق المهام وإدارتها بكفاءة من قبل Agent ذي خبرة. +- **إدارة قابلة للتخصيص**: تعريف أدوار ومسؤوليات إدارية تتماشى مع أهداف مشروعك. + +## تعيين LLM للمدير + +إذا كنت تستخدم العملية الهرمية ولا تريد تعيين Agent مدير مخصص، يمكنك تحديد نموذج اللغة للمدير: + +```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 +) +``` + + +يجب تعيين إما `manager_agent` أو `manager_llm` عند استخدام العملية الهرمية. + diff --git a/docs/v1.15.1/ar/learn/customizing-agents.mdx b/docs/v1.15.1/ar/learn/customizing-agents.mdx new file mode 100644 index 000000000..54ce5977c --- /dev/null +++ b/docs/v1.15.1/ar/learn/customizing-agents.mdx @@ -0,0 +1,67 @@ +--- +title: تخصيص الـ Agents +description: دليل شامل لتخصيص الـ Agents لأدوار ومهام محددة وتخصيصات متقدمة ضمن إطار عمل CrewAI. +icon: user-pen +mode: "wide" +--- + +## السمات القابلة للتخصيص + +يعتمد بناء فريق CrewAI فعّال على القدرة على تخصيص Agents الذكاء الاصطناعي ديناميكيًا لتلبية المتطلبات الفريدة لأي مشروع. يغطي هذا القسم السمات الأساسية التي يمكنك تخصيصها. + +### السمات الرئيسية للتخصيص + +| السمة | الوصف | +|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Role** | يحدد وظيفة الـ Agent ضمن Crew، مثل 'محلل' أو 'ممثل خدمة عملاء'. | +| **Goal** | يعرّف أهداف الـ Agent، متوافقة مع دوره ومهمة Crew الشاملة. | +| **Backstory** | يوفر عمقًا لشخصية الـ Agent، معززًا الدوافع والتفاعلات ضمن Crew. | +| **Tools** *(اختياري)* | يمثل القدرات أو الطرق التي يستخدمها الـ Agent للمهام. | +| **Cache** *(اختياري)* | يحدد ما إذا كان الـ Agent يجب أن يستخدم ذاكرة مؤقتة لاستخدام الأدوات. | +| **Max RPM** | يعيّن الحد الأقصى للطلبات في الدقيقة (`max_rpm`). | +| **Verbose** *(اختياري)* | يمكّن التسجيل التفصيلي للتصحيح والتحسين. | +| **Allow Delegation** *(اختياري)* | يتحكم في تفويض المهام لـ Agents أخرى، الافتراضي `False`. | +| **Max Iter** *(اختياري)* | يحد الحد الأقصى لعدد التكرارات (`max_iter`) لمهمة، الافتراضي 25. | + +## خيارات تخصيص متقدمة + +### تخصيص نموذج اللغة + +يمكن تخصيص الـ Agents بنماذج لغة محددة (`llm`) ونماذج لغة لاستدعاء الدوال (`function_calling_llm`)، مما يوفر تحكمًا متقدمًا في قدرات المعالجة وصنع القرار. + +## إعدادات الأداء والتصحيح + +- **وضع التفصيل**: يمكّن التسجيل التفصيلي لإجراءات الـ Agent. +- **حد RPM**: يعيّن الحد الأقصى للطلبات في الدقيقة. + +### مثال: تعيين أدوات لـ Agent + +```python Code +import os +from crewai import Agent +from crewai_tools import SerperDevTool + +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" + +search_tool = SerperDevTool() + +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, + verbose=True, + max_rpm=None, + max_iter=25, +) +``` + +## التفويض والاستقلالية + +التحكم في قدرة الـ Agent على تفويض المهام أو طرح الأسئلة أمر حيوي لتخصيص استقلاليته وديناميكيات التعاون. افتراضيًا، سمة `allow_delegation` معيّنة على `False`. + +## الخلاصة + +تخصيص الـ Agents في CrewAI من خلال تعيين أدوارهم وأهدافهم وخلفياتهم وأدواتهم، إلى جانب خيارات متقدمة مثل تخصيص نموذج اللغة والذاكرة وإعدادات الأداء وتفضيلات التفويض، يجهّز فريق AI دقيق وقادر جاهز للتحديات المعقدة. diff --git a/docs/v1.15.1/ar/learn/dalle-image-generation.mdx b/docs/v1.15.1/ar/learn/dalle-image-generation.mdx new file mode 100644 index 000000000..0ab1c3754 --- /dev/null +++ b/docs/v1.15.1/ar/learn/dalle-image-generation.mdx @@ -0,0 +1,52 @@ +--- +title: "إنشاء الصور باستخدام DALL-E" +description: "تعلم كيفية استخدام DALL-E لإنشاء صور مدعومة بالذكاء الاصطناعي في مشاريع CrewAI" +icon: "image" +mode: "wide" +--- + +يدعم CrewAI التكامل مع DALL-E من OpenAI، مما يتيح لـ Agents الذكاء الاصطناعي إنشاء صور كجزء من مهامهم. سيرشدك هذا الدليل عبر كيفية إعداد واستخدام أداة DALL-E في مشاريع CrewAI. + +## المتطلبات المسبقة + +- crewAI مثبّت (أحدث إصدار) +- مفتاح OpenAI API مع وصول إلى DALL-E + +## إعداد أداة DALL-E + + + + ```python + from crewai_tools import DallETool + ``` + + + + ```python + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + tools=[SerperDevTool(), DallETool()], + allow_delegation=False, + verbose=True + ) + ``` + + + +## استخدام أداة DALL-E + +بمجرد إضافة أداة DALL-E إلى Agent، يمكنه إنشاء صور بناءً على مطالبات نصية. ستعيد الأداة رابط URL للصورة المُنشأة. + +## أفضل الممارسات + +1. **كن محددًا في مطالبات إنشاء الصور** للحصول على أفضل النتائج. +2. **ضع في اعتبارك وقت الإنشاء** - قد يستغرق إنشاء الصور بعض الوقت. +3. **اتبع سياسات الاستخدام** - التزم دائمًا بسياسات استخدام OpenAI عند إنشاء الصور. + +## استكشاف الأخطاء + +1. **تحقق من وصول API** - تأكد من أن مفتاح OpenAI API لديه وصول إلى DALL-E. +2. **توافق الإصدارات** - تأكد من استخدام أحدث إصدار من crewAI وcrewai-tools. +3. **تهيئة الأداة** - تحقق من إضافة أداة DALL-E بشكل صحيح لقائمة أدوات الـ Agent. diff --git a/docs/v1.15.1/ar/learn/execution-hooks.mdx b/docs/v1.15.1/ar/learn/execution-hooks.mdx new file mode 100644 index 000000000..1444eb58d --- /dev/null +++ b/docs/v1.15.1/ar/learn/execution-hooks.mdx @@ -0,0 +1,86 @@ +--- +title: نظرة عامة على خطافات التنفيذ +description: فهم واستخدام خطافات التنفيذ في CrewAI للتحكم الدقيق في عمليات الـ Agent +mode: "wide" +--- + +توفر خطافات التنفيذ تحكمًا دقيقًا في سلوك وقت تشغيل Agents CrewAI. على عكس خطافات الانطلاق التي تعمل قبل وبعد تنفيذ Crew، تعترض خطافات التنفيذ عمليات محددة أثناء تنفيذ الـ Agent، مما يتيح لك تعديل السلوك وتنفيذ فحوصات أمان وإضافة مراقبة شاملة. + +## أنواع خطافات التنفيذ + +### 1. [خطافات استدعاء LLM](/learn/llm-hooks) + +التحكم ومراقبة تفاعلات نموذج اللغة: +- **قبل استدعاء LLM**: تعديل المطالبات، التحقق من المدخلات، بوابات الموافقة +- **بعد استدعاء LLM**: تحويل الاستجابات، تنقية المخرجات، تحديث سجل المحادثة + +### 2. [خطافات استدعاء الأدوات](/learn/tool-hooks) + +التحكم ومراقبة تنفيذ الأدوات: +- **قبل استدعاء الأداة**: تعديل المدخلات، التحقق من المعاملات، حظر العمليات الخطرة +- **بعد استدعاء الأداة**: تحويل النتائج، تنقية المخرجات، تسجيل تفاصيل التنفيذ + +## طرق تسجيل الخطافات + +### 1. خطافات بالمزخرفات (مُوصى بها) + +```python +from crewai.hooks import before_llm_call, after_llm_call, before_tool_call, after_tool_call + +@before_llm_call +def limit_iterations(context): + if context.iterations > 10: + return False + return None + +@after_llm_call +def sanitize_response(context): + if "API_KEY" in context.response: + return context.response.replace("API_KEY", "[REDACTED]") + return None + +@before_tool_call +def block_dangerous_tools(context): + if context.tool_name == "delete_database": + return False + return None +``` + +### 2. خطافات نطاق Crew + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + print(f"LLM call in {self.__class__.__name__}") + return None + + @after_tool_call_crew + def log_results(self, context): + print(f"Tool result: {context.tool_result[:50]}...") + return None +``` + +## أفضل الممارسات + +1. **اجعل الخطافات مركّزة** - كل خطاف يجب أن يكون له مسؤولية واحدة واضحة +2. **عالج الأخطاء بلطف** +3. **عدّل السياق في مكانه** +4. **استخدم تلميحات الأنواع** +5. **نظّف في الاختبارات** + +## التوثيق ذو الصلة + +- [خطافات استدعاء LLM](/learn/llm-hooks) +- [خطافات استدعاء الأدوات](/learn/tool-hooks) +- [خطافات قبل وبعد الانطلاق](/learn/before-and-after-kickoff-hooks) +- [التدخل البشري](/learn/human-in-the-loop) + +## الخلاصة + +توفر خطافات التنفيذ تحكمًا قويًا في سلوك وقت تشغيل الـ Agent. استخدمها لتنفيذ حواجز أمان وسير عمل موافقة ومراقبة شاملة ومنطق أعمال مخصص. diff --git a/docs/v1.15.1/ar/learn/force-tool-output-as-result.mdx b/docs/v1.15.1/ar/learn/force-tool-output-as-result.mdx new file mode 100644 index 000000000..8551e7680 --- /dev/null +++ b/docs/v1.15.1/ar/learn/force-tool-output-as-result.mdx @@ -0,0 +1,45 @@ +--- +title: فرض مخرجات الأداة كنتيجة +description: تعلم كيفية فرض مخرجات الأداة كنتيجة لمهمة Agent في CrewAI. +icon: wrench-simple +mode: "wide" +--- + +## مقدمة + +في CrewAI، يمكنك فرض مخرجات أداة كنتيجة لمهمة Agent. هذه الميزة مفيدة عندما تريد التأكد من التقاط مخرجات الأداة وإعادتها كنتيجة للمهمة، متجنبًا أي تعديل من قبل الـ Agent أثناء تنفيذ المهمة. + +## فرض مخرجات الأداة كنتيجة + +لفرض مخرجات الأداة كنتيجة لمهمة Agent، تحتاج لتعيين معامل `result_as_answer` إلى `True` عند إضافة أداة إلى الـ Agent. + +```python Code +from crewai.agent import Agent +from my_tool import MyCustomTool + +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)], + ) + +task_result = coding_agent.execute_task(task) +``` + +## سير العمل أثناء التنفيذ + + + + ينفذ الـ Agent المهمة باستخدام الأداة المقدمة. + + + تولّد الأداة المخرجات التي تُلتقط كنتيجة للمهمة. + + + قد يتأمل الـ Agent ويستخلص دروسًا من الأداة لكن لا يعدّل المخرجات. + + + تُعاد مخرجات الأداة كنتيجة للمهمة دون أي تعديلات. + + diff --git a/docs/v1.15.1/ar/learn/hierarchical-process.mdx b/docs/v1.15.1/ar/learn/hierarchical-process.mdx new file mode 100644 index 000000000..af783bdcd --- /dev/null +++ b/docs/v1.15.1/ar/learn/hierarchical-process.mdx @@ -0,0 +1,76 @@ +--- +title: العملية الهرمية +description: دليل شامل لفهم وتطبيق العملية الهرمية ضمن مشاريع CrewAI. +icon: sitemap +mode: "wide" +--- + +## مقدمة + +تقدم العملية الهرمية في CrewAI نهجًا منظمًا لإدارة المهام، محاكاةً للتسلسلات الهرمية التنظيمية التقليدية للتفويض والتنفيذ الفعّال للمهام. + + + صُممت العملية الهرمية للاستفادة من نماذج متقدمة مثل GPT-4، مما يحسّن استخدام الرموز المميزة مع التعامل مع المهام المعقدة بكفاءة أكبر. + + +## نظرة عامة على العملية الهرمية + +افتراضيًا، تُدار المهام في CrewAI من خلال عملية متسلسلة. لكن اعتماد نهج هرمي يتيح تسلسلاً واضحًا في إدارة المهام، حيث يقوم Agent 'مدير' بتنسيق سير العمل وتفويض المهام والتحقق من النتائج. + +### الميزات الرئيسية + +- **تفويض المهام**: Agent مدير يوزّع المهام بين أعضاء Crew بناءً على أدوارهم وقدراتهم. +- **التحقق من النتائج**: يقيّم المدير النتائج لضمان استيفائها للمعايير المطلوبة. +- **سير عمل فعّال**: يحاكي الهياكل المؤسسية مقدمًا نهجًا منظمًا لإدارة المهام. + +## تنفيذ العملية الهرمية + +```python Code +from crewai import Crew, Process, Agent + +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.', +) + +project_crew = Crew( + tasks=[...], + agents=[researcher, writer], + manager_llm="gpt-4o", + process=Process.hierarchical, + planning=True, +) +``` + +### استخدام Agent مدير مخصص + +```python +manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager...", + allow_delegation=True, +) + +project_crew = Crew( + tasks=[...], + agents=[researcher, writer], + manager_agent=manager, + process=Process.hierarchical, + planning=True, +) +``` + + + لمزيد من التفاصيل حول إنشاء وتخصيص Agent مدير، اطلع على [توثيق Agent المدير المخصص](/ar/learn/custom-manager-agent). + + +## الخلاصة + +اعتماد العملية الهرمية في CrewAI مع التهيئات الصحيحة وفهم قدرات النظام يسهّل نهجًا منظمًا وفعّالاً لإدارة المشاريع. استفد من الميزات المتقدمة والتخصيصات لتكييف سير العمل لاحتياجاتك المحددة. diff --git a/docs/v1.15.1/ar/learn/human-feedback-in-flows.mdx b/docs/v1.15.1/ar/learn/human-feedback-in-flows.mdx new file mode 100644 index 000000000..11aeffcf6 --- /dev/null +++ b/docs/v1.15.1/ar/learn/human-feedback-in-flows.mdx @@ -0,0 +1,98 @@ +--- +title: التغذية الراجعة البشرية في Flows +description: تعلم كيفية دمج التغذية الراجعة البشرية مباشرة في CrewAI Flows باستخدام مزخرف @human_feedback +icon: user-check +mode: "wide" +--- + +## نظرة عامة + + +يتطلب مزخرف `@human_feedback` إصدار **CrewAI 1.8.0 أو أحدث**. تأكد من تحديث تثبيتك قبل استخدام هذه الميزة. + + +يمكّن مزخرف `@human_feedback` سير العمل البشري في الحلقة (HITL) مباشرة ضمن CrewAI Flows. يتيح لك إيقاف تنفيذ Flow مؤقتًا وعرض المخرجات لإنسان للمراجعة وجمع تعليقاته واختياريًا التوجيه إلى مستمعين مختلفين بناءً على نتيجة التعليقات. + +هذا مفيد بشكل خاص لـ: + +- **ضمان الجودة**: مراجعة المحتوى المُنشأ بالذكاء الاصطناعي قبل استخدامه +- **بوابات القرار**: السماح للبشر باتخاذ قرارات حرجة في سير العمل الآلي +- **سير عمل الموافقة**: تنفيذ أنماط الموافقة/الرفض/المراجعة +- **التحسين التفاعلي**: جمع التعليقات لتحسين المخرجات تكراريًا + +## بداية سريعة + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback + +class SimpleReviewFlow(Flow): + @start() + @human_feedback(message="Please review this content:") + def generate_content(self): + return "This is AI-generated content that needs review." + + @listen(generate_content) + def process_feedback(self, result): + print(f"Content: {result.output}") + print(f"Human said: {result.feedback}") + +flow = SimpleReviewFlow() +flow.kickoff() +``` + +## التوجيه مع emit + +عند تحديد `emit`، يصبح المزخرف موجّهًا. يُفسَّر التعليق البشري الحر بواسطة LLM ويُختزل إلى إحدى النتائج المحددة: + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback + +class ReviewFlow(Flow): + @start() + def generate_content(self): + return "Draft blog post content here..." + + @human_feedback( + message="Do you approve this content for publication?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Draft blog post content here..." + + @listen("approved") + def publish(self, result): + print(f"Publishing! User said: {result.feedback}") + + @listen("rejected") + def discard(self, result): + print(f"Discarding. Reason: {result.feedback}") +``` + +## التعلم من التغذية الراجعة + +معامل `learn=True` يمكّن حلقة تغذية راجعة بين المراجعين البشريين ونظام الذاكرة. عند تمكينه، يحسّن النظام مخرجاته تدريجيًا بالتعلم من التصحيحات البشرية السابقة. + +## أفضل الممارسات + +1. **اكتب رسائل طلب واضحة** +2. **اختر نتائج ذات معنى** +3. **وفّر دائمًا نتيجة افتراضية** +4. **استخدم سجل التعليقات لمسارات التدقيق** + +## التغذية الراجعة البشرية غير المتزامنة (غير محجوبة) + +استخدم معامل `provider` لتحديد استراتيجية جمع تعليقات مخصصة تتكامل مع أنظمة خارجية مثل Slack والبريد الإلكتروني وWebhooks وواجهات API. + +## التوثيق ذو الصلة + +- [نظرة عامة على Flows](/ar/concepts/flows) +- [إدارة حالة Flow](/ar/guides/flows/mastering-flow-state) +- [حفظ Flow](/ar/concepts/flows#persistence) +- [التوجيه مع @router](/ar/concepts/flows#router) +- [إدخال بشري عند التنفيذ](/ar/learn/human-input-on-execution) +- [الذاكرة](/ar/concepts/memory) diff --git a/docs/v1.15.1/ar/learn/human-in-the-loop.mdx b/docs/v1.15.1/ar/learn/human-in-the-loop.mdx new file mode 100644 index 000000000..69c5ea8a7 --- /dev/null +++ b/docs/v1.15.1/ar/learn/human-in-the-loop.mdx @@ -0,0 +1,80 @@ +--- +title: "سير عمل التدخل البشري (HITL)" +description: "تعلم كيفية تنفيذ سير عمل التدخل البشري في CrewAI لتعزيز صنع القرار" +icon: "user-check" +mode: "wide" +--- + +التدخل البشري (HITL) هو نهج قوي يجمع بين الذكاء الاصطناعي والخبرة البشرية لتعزيز صنع القرار وتحسين نتائج المهام. يوفر CrewAI طرقًا متعددة لتنفيذ HITL حسب احتياجاتك. + +## اختيار نهج HITL + +يوفر CrewAI نهجين رئيسيين لتنفيذ سير عمل التدخل البشري: + +| النهج | الأنسب لـ | التكامل | الإصدار | +|----------|----------|-------------|---------| +| **قائم على Flow** (مزخرف `@human_feedback`) | التطوير المحلي، المراجعة عبر وحدة التحكم، سير العمل المتزامن | [التغذية الراجعة البشرية في Flows](/ar/learn/human-feedback-in-flows) | **1.8.0+** | +| **قائم على Webhook** (المؤسسات) | نشر الإنتاج، سير العمل غير المتزامن، التكاملات الخارجية (Slack، Teams، إلخ) | هذا الدليل | - | + + +إذا كنت تبني Flows وتريد إضافة خطوات مراجعة بشرية مع توجيه بناءً على التعليقات، اطلع على دليل [التغذية الراجعة البشرية في Flows](/ar/learn/human-feedback-in-flows) لمزخرف `@human_feedback`. + + +## إعداد سير عمل HITL القائم على Webhook + + + + أعدّ مهمتك مع تمكين إدخال بشري. + + + + عند تشغيل Crew، أدرج عنوان Webhook URL لإدخال بشري. + + + + بمجرد إتمام Crew المهمة التي تتطلب إدخالاً بشريًا، ستتلقى إشعار Webhook. + + + + سيتوقف النظام في حالة `Pending Human Input`. راجع مخرجات المهمة بعناية. + + + + استدعِ نقطة نهاية الاستئناف لـ Crew. + + + **مهم: يجب توفير عناوين Webhook URL مرة أخرى**: + يجب توفير نفس عناوين Webhook URL في استدعاء الاستئناف التي استخدمتها في استدعاء الانطلاق. + + + + + إذا قدمت تعليقات سلبية، سيعيد Crew محاولة المهمة مع سياق إضافي من تعليقاتك. + + + + عند إرسال تعليقات إيجابية، سيستمر التنفيذ إلى الخطوات التالية. + + + +## أفضل الممارسات + +- **كن محددًا**: قدم تعليقات واضحة وقابلة للتنفيذ +- **ابقَ ذا صلة**: أدرج فقط معلومات تساعد في تحسين تنفيذ المهمة +- **كن في الوقت المناسب**: استجب لمطالبات HITL بسرعة لتجنب تأخير سير العمل +- **راجع بعناية**: تحقق من تعليقاتك قبل الإرسال لضمان الدقة + +## حالات الاستخدام الشائعة + +سير عمل HITL مفيدة بشكل خاص لـ: +- ضمان الجودة والتحقق +- سيناريوهات صنع القرار المعقدة +- العمليات الحساسة أو عالية المخاطر +- المهام الإبداعية التي تتطلب حكمًا بشريًا +- مراجعات الامتثال والتنظيم + +## ميزات المؤسسات + + + يوفر CrewAI Enterprise نظام إدارة HITL شامل لـ Flows مع مراجعة داخل المنصة وتعيين المستجيبين والأذونات وسياسات التصعيد وإدارة SLA والتوجيه الديناميكي والتحليلات الكاملة. [تعلم المزيد](/ar/enterprise/features/flow-hitl-management) + diff --git a/docs/v1.15.1/ar/learn/human-input-on-execution.mdx b/docs/v1.15.1/ar/learn/human-input-on-execution.mdx new file mode 100644 index 000000000..756f170a0 --- /dev/null +++ b/docs/v1.15.1/ar/learn/human-input-on-execution.mdx @@ -0,0 +1,99 @@ +--- +title: الإدخال البشري أثناء التنفيذ +description: دمج CrewAI مع الإدخال البشري أثناء التنفيذ في عمليات اتخاذ القرارات المعقدة والاستفادة الكاملة من إمكانيات خصائص وأدوات الوكيل. +icon: user-plus +mode: "wide" +--- + +## الإدخال البشري في تنفيذ الوكيل + +يُعد الإدخال البشري أمراً بالغ الأهمية في العديد من سيناريوهات تنفيذ الوكلاء، حيث يسمح للوكلاء بطلب معلومات إضافية أو توضيحات عند الضرورة. +هذه الميزة مفيدة بشكل خاص في عمليات اتخاذ القرارات المعقدة أو عندما يحتاج الوكلاء إلى مزيد من التفاصيل لإكمال مهمة بفعالية. + +## استخدام الإدخال البشري مع CrewAI + +لدمج الإدخال البشري في تنفيذ الوكيل، قم بتعيين علامة `human_input` في تعريف المهمة. عند تفعيلها، يطلب الوكيل من المستخدم إدخالاً قبل تقديم إجابته النهائية. +يمكن أن يوفر هذا الإدخال سياقاً إضافياً، أو يوضح الغموض، أو يتحقق من مخرجات الوكيل. + +### مثال: + +```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) +``` diff --git a/docs/v1.15.1/ar/learn/kickoff-async.mdx b/docs/v1.15.1/ar/learn/kickoff-async.mdx new file mode 100644 index 000000000..dfe446ba0 --- /dev/null +++ b/docs/v1.15.1/ar/learn/kickoff-async.mdx @@ -0,0 +1,306 @@ +--- +title: تشغيل الطاقم بشكل غير متزامن +description: تشغيل الطاقم بشكل غير متزامن +icon: rocket-launch +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على تشغيل طاقم بشكل غير متزامن، مما يتيح لك بدء تنفيذ الطاقم بطريقة غير حاجبة. +هذه الميزة مفيدة بشكل خاص عندما تريد تشغيل عدة أطقم بشكل متزامن أو عندما تحتاج إلى أداء مهام أخرى أثناء تنفيذ الطاقم. + +يقدم CrewAI نهجين للتنفيذ غير المتزامن: + +| الطريقة | النوع | الوصف | +|--------|------|-------------| +| `akickoff()` | غير متزامن أصلي | async/await أصلي عبر سلسلة التنفيذ بالكامل | +| `kickoff_async()` | قائم على الخيوط | يغلف التنفيذ المتزامن في `asyncio.to_thread` | + + +لأحمال العمل عالية التزامن، يُوصى باستخدام `akickoff()` لأنه يستخدم async أصلي لتنفيذ المهام وعمليات الذاكرة واسترجاع المعرفة. + + +## التنفيذ غير المتزامن الأصلي مع `akickoff()` + +توفر طريقة `akickoff()` تنفيذاً غير متزامن أصلياً حقيقياً، باستخدام async/await عبر سلسلة التنفيذ بالكامل بما في ذلك تنفيذ المهام وعمليات الذاكرة واستعلامات المعرفة. + +### توقيع الطريقة + +```python Code +async def akickoff(self, inputs: dict) -> CrewOutput: +``` + +### المعاملات + +- `inputs` (dict): قاموس يحتوي على بيانات الإدخال المطلوبة للمهام. + +### القيمة المُرجعة + +- `CrewOutput`: كائن يمثل نتيجة تنفيذ الطاقم. + +### مثال: تنفيذ طاقم غير متزامن أصلي + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# Create an agent +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 +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 +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# Native async execution +async def main(): + result = await analysis_crew.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(main()) +``` + +### مثال: عدة أطقم غير متزامنة أصلية + +تشغيل عدة أطقم بشكل متزامن باستخدام `asyncio.gather()` مع async أصلي: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +task_1 = Task( + description="Analyze the first dataset and calculate the average age. 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. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def main(): + results = await asyncio.gather( + crew_1.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}), + crew_2.akickoff(inputs={"ages": [20, 22, 24, 28, 30]}) + ) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(main()) +``` + +### مثال: async أصلي لمدخلات متعددة + +استخدم `akickoff_for_each()` لتنفيذ طاقمك على مدخلات متعددة بشكل متزامن مع async أصلي: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +data_analysis_task = Task( + description="Analyze the dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def main(): + datasets = [ + {"ages": [25, 30, 35, 40, 45]}, + {"ages": [20, 22, 24, 28, 30]}, + {"ages": [30, 35, 40, 45, 50]} + ] + + results = await analysis_crew.akickoff_for_each(datasets) + + for i, result in enumerate(results, 1): + print(f"Dataset {i} Result:", result) + +asyncio.run(main()) +``` + +## التنفيذ غير المتزامن القائم على الخيوط مع `kickoff_async()` + +توفر طريقة `kickoff_async()` تنفيذاً غير متزامن عن طريق تغليف `kickoff()` المتزامن في خيط. هذا مفيد للتكامل البسيط مع async أو للتوافق مع الإصدارات السابقة. + +### توقيع الطريقة + +```python Code +async def kickoff_async(self, inputs: dict) -> CrewOutput: +``` + +### المعاملات + +- `inputs` (dict): قاموس يحتوي على بيانات الإدخال المطلوبة للمهام. + +### القيمة المُرجعة + +- `CrewOutput`: كائن يمثل نتيجة تنفيذ الطاقم. + +### مثال: تنفيذ غير متزامن قائم على الخيوط + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(async_crew_execution()) +``` + +### مثال: عدة أطقم غير متزامنة قائمة على الخيوط + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def async_multiple_crews(): + 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]}) + + results = await asyncio.gather(result_1, result_2) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(async_multiple_crews()) +``` + +## البث غير المتزامن + +تدعم كلتا الطريقتين غير المتزامنتين البث عند تعيين `stream=True` على الطاقم: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +agent = Agent( + role="Researcher", + goal="Research and summarize topics", + backstory="You are an expert researcher." +) + +task = Task( + description="Research the topic: {topic}", + agent=agent, + expected_output="A comprehensive summary of the topic." +) + +crew = Crew( + agents=[agent], + tasks=[task], + stream=True # Enable streaming +) + +async def main(): + streaming_output = await crew.akickoff(inputs={"topic": "AI trends in 2024"}) + + # Async iteration over streaming chunks + async for chunk in streaming_output: + print(f"Chunk: {chunk.content}") + + # Access final result after streaming completes + result = streaming_output.result + print(f"Final result: {result.raw}") + +asyncio.run(main()) +``` + +## حالات الاستخدام المحتملة + +- **توليد المحتوى بالتوازي**: تشغيل عدة أطقم مستقلة بشكل غير متزامن، كل منها مسؤول عن توليد محتوى حول مواضيع مختلفة. على سبيل المثال، قد يبحث طاقم ويصوغ مقالاً عن اتجاهات الذكاء الاصطناعي، بينما يولد طاقم آخر منشورات وسائل التواصل الاجتماعي حول إطلاق منتج جديد. + +- **مهام أبحاث السوق المتزامنة**: إطلاق عدة أطقم بشكل غير متزامن لإجراء أبحاث السوق بالتوازي. قد يحلل طاقم اتجاهات الصناعة، بينما يفحص آخر استراتيجيات المنافسين، ويقيّم ثالث مشاعر المستهلكين. + +- **وحدات تخطيط السفر المستقلة**: تنفيذ أطقم منفصلة للتخطيط المستقل لجوانب مختلفة من رحلة. قد يتعامل طاقم مع خيارات الرحلات الجوية، وآخر مع الإقامة، وثالث يخطط للأنشطة. + +## الاختيار بين `akickoff()` و `kickoff_async()` + +| الميزة | `akickoff()` | `kickoff_async()` | +|---------|--------------|-------------------| +| نموذج التنفيذ | async/await أصلي | غلاف قائم على الخيوط | +| تنفيذ المهام | غير متزامن مع `aexecute_sync()` | متزامن في مجمع الخيوط | +| عمليات الذاكرة | غير متزامنة | متزامنة في مجمع الخيوط | +| استرجاع المعرفة | غير متزامن | متزامن في مجمع الخيوط | +| الأفضل لـ | أحمال العمل عالية التزامن والمرتبطة بالإدخال/الإخراج | التكامل البسيط مع async | +| دعم البث | نعم | نعم | diff --git a/docs/v1.15.1/ar/learn/kickoff-for-each.mdx b/docs/v1.15.1/ar/learn/kickoff-for-each.mdx new file mode 100644 index 000000000..a827799b0 --- /dev/null +++ b/docs/v1.15.1/ar/learn/kickoff-for-each.mdx @@ -0,0 +1,54 @@ +--- +title: تشغيل الطاقم لكل عنصر +description: تشغيل الطاقم لكل عنصر في قائمة +icon: at +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على تشغيل طاقم لكل عنصر في قائمة، مما يتيح لك تنفيذ الطاقم لكل عنصر في القائمة. +هذه الميزة مفيدة بشكل خاص عندما تحتاج إلى تنفيذ نفس مجموعة المهام لعناصر متعددة. + +## تشغيل طاقم لكل عنصر + +لتشغيل طاقم لكل عنصر في قائمة، استخدم طريقة `kickoff_for_each()`. +تنفذ هذه الطريقة الطاقم لكل عنصر في القائمة، مما يتيح لك معالجة عناصر متعددة بكفاءة. + +إليك مثالاً على كيفية تشغيل طاقم لكل عنصر في قائمة: + +```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) +``` diff --git a/docs/v1.15.1/ar/learn/litellm-removal-guide.mdx b/docs/v1.15.1/ar/learn/litellm-removal-guide.mdx new file mode 100644 index 000000000..b0e81d919 --- /dev/null +++ b/docs/v1.15.1/ar/learn/litellm-removal-guide.mdx @@ -0,0 +1,358 @@ +--- +title: استخدام CrewAI بدون LiteLLM +description: كيفية استخدام CrewAI مع التكاملات الأصلية للمزودين وإزالة اعتمادية LiteLLM من مشروعك. +icon: shield-check +mode: "wide" +--- + +## نظرة عامة + +يدعم CrewAI مسارين للاتصال بمزودي LLM: + +1. **التكاملات الأصلية** — اتصالات SDK مباشرة مع OpenAI وAnthropic وGoogle Gemini وAzure OpenAI وAWS Bedrock +2. **LiteLLM كاحتياط** — طبقة ترجمة تدعم أكثر من 100 مزود إضافي + +يشرح هذا الدليل كيفية استخدام CrewAI حصرياً مع التكاملات الأصلية للمزودين، مع إزالة أي اعتمادية على LiteLLM. + + + تم عزل حزمة `litellm` على PyPI بسبب حادث أمني/موثوقية. إذا كنت تعتمد على مزودين يحتاجون LiteLLM، يجب عليك الانتقال إلى التكاملات الأصلية. توفر لك تكاملات CrewAI الأصلية الوظائف الكاملة بدون LiteLLM. + + +## لماذا إزالة LiteLLM؟ + +- **تقليل سطح الاعتماديات** — حزم أقل تعني مخاطر أقل محتملة في سلسلة التوريد +- **أداء أفضل** — تتواصل حزم SDK الأصلية مباشرة مع واجهات برمجة تطبيقات المزودين، مما يلغي طبقة الترجمة +- **تصحيح أخطاء أبسط** — طبقة تجريد واحدة أقل بين كودك والمزود +- **حجم تثبيت أصغر** — يجلب LiteLLM العديد من الاعتماديات العابرة + +## المزودون الأصليون (لا يحتاجون LiteLLM) + +هؤلاء المزودون يستخدمون حزم SDK الخاصة بهم ويعملون بدون تثبيت LiteLLM: + + + + GPT-4o، GPT-4o-mini، o1، o3-mini، والمزيد. + ```bash + uv add "crewai[openai]" + ``` + + + Claude Sonnet، Claude Haiku، والمزيد. + ```bash + uv add "crewai[anthropic]" + ``` + + + Gemini 2.0 Flash، Gemini 2.0 Pro، والمزيد. + ```bash + uv add "crewai[gemini]" + ``` + + + نماذج OpenAI المستضافة على Azure. + ```bash + uv add "crewai[azure]" + ``` + + + Claude، Llama، Titan، والمزيد عبر AWS. + ```bash + uv add "crewai[bedrock]" + ``` + + + + + إذا كنت تستخدم المزودين الأصليين فقط، فلن تحتاج **أبداً** لتثبيت `crewai[litellm]`. حزمة `crewai` الأساسية بالإضافة إلى الإضافة الخاصة بالمزود الذي اخترته هي كل ما تحتاجه. + + +## كيفية التحقق مما إذا كنت تستخدم LiteLLM + +### تحقق من سلاسل النماذج الخاصة بك + +إذا كان كودك يستخدم بادئات النماذج هذه، فأنت تمرر عبر LiteLLM: + +| البادئة | المزود | يستخدم LiteLLM؟ | +|--------|----------|---------------| +| `ollama/` | Ollama | ✅ نعم | +| `groq/` | Groq | ✅ نعم | +| `together_ai/` | Together AI | ✅ نعم | +| `mistral/` | Mistral | ✅ نعم | +| `cohere/` | Cohere | ✅ نعم | +| `huggingface/` | Hugging Face | ✅ نعم | +| `openai/` | OpenAI | ❌ أصلي | +| `anthropic/` | Anthropic | ❌ أصلي | +| `gemini/` | Google Gemini | ❌ أصلي | +| `azure/` | Azure OpenAI | ❌ أصلي | +| `bedrock/` | AWS Bedrock | ❌ أصلي | + +### تحقق مما إذا كان LiteLLM مثبتاً + +```bash +# Using pip +pip show litellm + +# Using uv +uv pip show litellm +``` + +إذا أرجع الأمر معلومات الحزمة، فإن LiteLLM مثبت في بيئتك. + +### تحقق من اعتمادياتك + +انظر إلى ملف `pyproject.toml` الخاص بك بحثاً عن `crewai[litellm]`: + +```toml +# If you see this, you have LiteLLM as a dependency +dependencies = [ + "crewai[litellm]>=0.100.0", # ← Uses LiteLLM +] + +# Change to a native provider extra instead +dependencies = [ + "crewai[openai]>=0.100.0", # ← Native, no LiteLLM +] +``` + +## دليل الانتقال + +### الخطوة 1: حدد مزودك الحالي + +ابحث عن جميع استدعاءات `LLM()` وسلاسل النماذج في كودك: + +```bash +# Search your codebase for LLM model strings +grep -r "LLM(" --include="*.py" . +grep -r "llm=" --include="*.yaml" . +grep -r "llm:" --include="*.yaml" . +``` + +### الخطوة 2: انتقل إلى مزود أصلي + + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="groq/llama-3.1-70b") + + # After (Native): + llm = LLM(model="openai/gpt-4o") + ``` + + ```bash + # Install + uv add "crewai[openai]" + + # Set your API key + export OPENAI_API_KEY="sk-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") + + # After (Native): + llm = LLM(model="anthropic/claude-sonnet-4-20250514") + ``` + + ```bash + # Install + uv add "crewai[anthropic]" + + # Set your API key + export ANTHROPIC_API_KEY="sk-ant-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="mistral/mistral-large-latest") + + # After (Native): + llm = LLM(model="gemini/gemini-2.0-flash") + ``` + + ```bash + # Install + uv add "crewai[gemini]" + + # Set your API key + export GEMINI_API_KEY="..." + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="azure/your-deployment-name", + api_key="your-azure-api-key", + base_url="https://your-resource.openai.azure.com", + api_version="2024-06-01" + ) + ``` + + ```bash + # Install + uv add "crewai[azure]" + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_region_name="us-east-1" + ) + ``` + + ```bash + # Install + uv add "crewai[bedrock]" + + # Configure AWS credentials + export AWS_ACCESS_KEY_ID="..." + export AWS_SECRET_ACCESS_KEY="..." + export AWS_DEFAULT_REGION="us-east-1" + ``` + + + +### الخطوة 3: الاحتفاظ بـ Ollama بدون LiteLLM + +إذا كنت تستخدم Ollama وتريد الاستمرار في استخدامه، يمكنك الاتصال عبر واجهة برمجة تطبيقات Ollama المتوافقة مع OpenAI: + +```python +from crewai import LLM + +# Before (LiteLLM): +# llm = LLM(model="ollama/llama3") + +# After (OpenAI-compatible mode, no LiteLLM needed): +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" # Ollama doesn't require a real API key +) +``` + + + العديد من خوادم الاستدلال المحلية (Ollama، vLLM، LM Studio، llama.cpp) توفر واجهة برمجة تطبيقات متوافقة مع OpenAI. يمكنك استخدام بادئة `openai/` مع `base_url` مخصص للاتصال بأي منها بشكل أصلي. + + +### الخطوة 4: تحديث إعدادات YAML + +```yaml +# Before (LiteLLM providers): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: groq/llama-3.1-70b # ← LiteLLM + +# After (Native provider): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: openai/gpt-4o # ← Native +``` + +### الخطوة 5: إزالة LiteLLM + +بمجرد انتقال جميع مراجع النماذج الخاصة بك: + +```bash +# Remove litellm from your project +uv remove litellm + +# Or if using pip +pip uninstall litellm + +# Update your pyproject.toml: change crewai[litellm] to your provider extra +# e.g., crewai[openai], crewai[anthropic], crewai[gemini] +``` + +### الخطوة 6: التحقق + +شغّل مشروعك وتأكد من أن كل شيء يعمل: + +```bash +# Run your crew +crewai run + +# Or run your tests +uv run pytest +``` + +## مرجع سريع: خريطة سلاسل النماذج + +فيما يلي مسارات الانتقال الشائعة من المزودين المعتمدين على LiteLLM إلى المزودين الأصليين: + +```python +from crewai import LLM + +# ─── LiteLLM providers → Native alternatives ──────────────────── + +# Groq → OpenAI or Anthropic +# llm = LLM(model="groq/llama-3.1-70b") +llm = LLM(model="openai/gpt-4o-mini") # Fast & affordable +llm = LLM(model="anthropic/claude-haiku-3-5") # Fast & affordable + +# Together AI → OpenAI or Gemini +# llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") +llm = LLM(model="openai/gpt-4o") # High quality +llm = LLM(model="gemini/gemini-2.0-flash") # Fast & capable + +# Mistral → Anthropic or OpenAI +# llm = LLM(model="mistral/mistral-large-latest") +llm = LLM(model="anthropic/claude-sonnet-4-20250514") # High quality + +# Ollama → OpenAI-compatible (keep using local models) +# llm = LLM(model="ollama/llama3") +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" +) +``` + +## الأسئلة الشائعة + + + + لا، إذا كنت تستخدم أحد المزودين الخمسة المدعومين أصلياً (OpenAI، Anthropic، Gemini، Azure، Bedrock). تدعم هذه التكاملات الأصلية جميع ميزات CrewAI بما في ذلك البث واستدعاء الأدوات والمخرجات المنظمة والمزيد. ستفقد فقط الوصول إلى المزودين المتاحين حصرياً عبر LiteLLM (مثل Groq وTogether AI وMistral كمزودين من الدرجة الأولى). + + + نعم. ثبّت إضافات متعددة واستخدم مزودين مختلفين لوكلاء مختلفين: + ```bash + uv add "crewai[openai,anthropic,gemini]" + ``` + ```python + researcher = Agent(llm="openai/gpt-4o", ...) + writer = Agent(llm="anthropic/claude-sonnet-4-20250514", ...) + ``` + + + بغض النظر عن حالة العزل، فإن تقليل سطح اعتمادياتك يُعد ممارسة أمنية جيدة. إذا كنت تحتاج فقط مزودين يدعمهم CrewAI أصلياً، فلا يوجد سبب لإبقاء LiteLLM مثبتاً. + + + يستخدم المزودون الأصليون نفس متغيرات البيئة التي اعتدت عليها. لا حاجة لتغييرات على `OPENAI_API_KEY` أو `ANTHROPIC_API_KEY` أو `GEMINI_API_KEY` وغيرها. + + + +## موارد ذات صلة + +- [اتصالات LLM](/ar/learn/llm-connections) — الدليل الكامل لربط CrewAI مع أي LLM +- [مفاهيم LLM](/ar/concepts/llms) — فهم نماذج اللغة الكبيرة في CrewAI +- [دليل اختيار LLM](/ar/learn/llm-selection-guide) — اختيار النموذج المناسب لحالة استخدامك diff --git a/docs/v1.15.1/ar/learn/llm-connections.mdx b/docs/v1.15.1/ar/learn/llm-connections.mdx new file mode 100644 index 000000000..d748d115e --- /dev/null +++ b/docs/v1.15.1/ar/learn/llm-connections.mdx @@ -0,0 +1,214 @@ +--- +title: الاتصال بأي LLM +description: دليل شامل لدمج CrewAI مع نماذج اللغة الكبيرة المختلفة (LLMs) باستخدام LiteLLM، بما في ذلك المزودون المدعومون وخيارات الإعداد. +icon: brain-circuit +mode: "wide" +--- + +## ربط CrewAI بنماذج اللغة الكبيرة + +يتصل CrewAI بنماذج اللغة الكبيرة من خلال تكاملات SDK الأصلية لأكثر المزودين شيوعاً (OpenAI وAnthropic وGoogle Gemini وAzure وAWS Bedrock)، ويستخدم LiteLLM كاحتياط مرن لجميع المزودين الآخرين. + + + افتراضياً، يستخدم CrewAI نموذج `gpt-4o-mini`. يتم تحديد ذلك بواسطة متغير البيئة `OPENAI_MODEL_NAME`، الذي يكون قيمته الافتراضية "gpt-4o-mini" إذا لم يتم تعيينه. + يمكنك بسهولة إعداد وكلائك لاستخدام نموذج أو مزود مختلف كما هو موضح في هذا الدليل. + + +## المزودون المدعومون + +يدعم LiteLLM مجموعة واسعة من المزودين، بما في ذلك على سبيل المثال لا الحصر: + +- 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 +- Nebius AI Studio +- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1) +- والمزيد! + +للحصول على قائمة كاملة ومحدثة بالمزودين المدعومين، يرجى الرجوع إلى [وثائق مزودي LiteLLM](https://docs.litellm.ai/docs/providers). + + + لاستخدام أي مزود غير مغطى بتكامل أصلي، أضف LiteLLM كاعتمادية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + يستخدم المزودون الأصليون (OpenAI، Anthropic، Google Gemini، Azure، AWS Bedrock) إضافات SDK الخاصة بهم — راجع [أمثلة إعداد المزودين](/ar/concepts/llms#provider-configuration-examples). + + +## تغيير نموذج اللغة الكبير + +لاستخدام LLM مختلف مع وكلاء CrewAI، لديك عدة خيارات: + + + + مرر اسم النموذج كسلسلة نصية عند تهيئة الوكيل: + + ```python Code + from crewai import Agent + + # Using OpenAI's GPT-4 + 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' + ) + + # Using Anthropic's Claude + claude_agent = Agent( + role='Anthropic Expert', + goal='Analyze data using Claude', + backstory="An AI assistant leveraging Anthropic's language model.", + llm='claude-2' + ) + ``` + + + + لمزيد من الإعداد التفصيلي، استخدم فئة 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 + ) + ``` + + + + +## خيارات الإعداد + +عند إعداد LLM لوكيلك، يمكنك الوصول إلى مجموعة واسعة من المعاملات: + +| المعامل | النوع | الوصف | +|:----------|:-----:|:-------------| +| **model** | `str` | اسم النموذج المراد استخدامه (مثل "gpt-4"، "claude-2") | +| **temperature** | `float` | يتحكم في العشوائية في المخرجات (0.0 إلى 1.0) | +| **max_tokens** | `int` | الحد الأقصى لعدد الرموز المولدة | +| **top_p** | `float` | يتحكم في تنوع المخرجات (0.0 إلى 1.0) | +| **frequency_penalty** | `float` | يعاقب الرموز الجديدة بناءً على تكرارها في النص حتى الآن | +| **presence_penalty** | `float` | يعاقب الرموز الجديدة بناءً على وجودها في النص حتى الآن | +| **stop** | `str`, `List[str]` | تسلسل(ات) لإيقاف التوليد | +| **base_url** | `str` | عنوان URL الأساسي لنقطة نهاية API | +| **api_key** | `str` | مفتاح API الخاص بك للمصادقة | + +للحصول على قائمة كاملة بالمعاملات وأوصافها، راجع وثائق فئة LLM. + +## الاتصال بنماذج LLM المتوافقة مع OpenAI + +يمكنك الاتصال بنماذج LLM المتوافقة مع OpenAI باستخدام متغيرات البيئة أو عن طريق تعيين خصائص محددة في فئة 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 + + # Example using Gemini's OpenAI-compatible API. + os.environ["OPENAI_API_KEY"] = "your-gemini-key" # Should start with AIza... + os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/" + os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Add your Gemini model here, under 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 + # Example using Gemini's OpenAI-compatible API + llm = LLM( + model="openai/gemini-2.0-flash", + base_url="https://generativelanguage.googleapis.com/v1beta/openai/", + api_key="your-gemini-key", # Should start with AIza... + ) + agent = Agent(llm=llm, ...) + ``` + + + + +## استخدام النماذج المحلية مع Ollama + +للنماذج المحلية مثل تلك التي يوفرها Ollama: + + + + [انقر هنا لتحميل وتثبيت Ollama](https://ollama.com/download) + + + على سبيل المثال، شغّل `ollama pull llama3.2` لتحميل النموذج. + + + + ```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") + ) + ``` + + + + +## تغيير عنوان URL الأساسي لـ API + +يمكنك تغيير عنوان URL الأساسي لـ API لأي مزود LLM عن طريق تعيين معامل `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, ...) +``` + +هذا مفيد بشكل خاص عند العمل مع واجهات برمجة تطبيقات متوافقة مع OpenAI أو عندما تحتاج إلى تحديد نقطة نهاية مختلفة للمزود الذي اخترته. + +## الخاتمة + +من خلال الاستفادة من LiteLLM، يوفر CrewAI تكاملاً سلساً مع مجموعة واسعة من نماذج اللغة الكبيرة. تتيح لك هذه المرونة اختيار النموذج الأنسب لاحتياجاتك المحددة، سواء كنت تعطي الأولوية للأداء أو كفاءة التكلفة أو النشر المحلي. تذكر الرجوع إلى [وثائق LiteLLM](https://docs.litellm.ai/docs/) للحصول على أحدث المعلومات حول النماذج المدعومة وخيارات الإعداد. diff --git a/docs/v1.15.1/ar/learn/llm-hooks.mdx b/docs/v1.15.1/ar/learn/llm-hooks.mdx new file mode 100644 index 000000000..445f99349 --- /dev/null +++ b/docs/v1.15.1/ar/learn/llm-hooks.mdx @@ -0,0 +1,427 @@ +--- +title: خطافات استدعاء LLM +description: تعلم كيفية استخدام خطافات استدعاء LLM لاعتراض وتعديل والتحكم في تفاعلات نماذج اللغة في CrewAI +mode: "wide" +--- + +توفر خطافات استدعاء LLM تحكماً دقيقاً في تفاعلات نماذج اللغة أثناء تنفيذ الوكيل. تتيح لك هذه الخطافات اعتراض استدعاءات LLM وتعديل المطالبات وتحويل الاستجابات وتنفيذ بوابات الموافقة وإضافة تسجيل أو مراقبة مخصصة. + +## نظرة عامة + +تُنفذ خطافات LLM في نقطتين حرجتين: +- **قبل استدعاء LLM**: تعديل الرسائل، التحقق من المدخلات، أو حظر التنفيذ +- **بعد استدعاء LLM**: تحويل الاستجابات، تنقية المخرجات، أو تعديل سجل المحادثة + +## أنواع الخطافات + +### خطافات ما قبل استدعاء LLM + +تُنفذ قبل كل استدعاء LLM، ويمكن لهذه الخطافات: +- فحص وتعديل الرسائل المرسلة إلى LLM +- حظر تنفيذ LLM بناءً على شروط +- تنفيذ تحديد معدل أو بوابات موافقة +- إضافة سياق أو رسائل نظام +- تسجيل تفاصيل الطلب + +**التوقيع:** +```python +def before_hook(context: LLMCallHookContext) -> bool | None: + # Return False to block execution + # Return True or None to allow execution + ... +``` + +### خطافات ما بعد استدعاء LLM + +تُنفذ بعد كل استدعاء LLM، ويمكن لهذه الخطافات: +- تعديل أو تنقية استجابات LLM +- إضافة بيانات وصفية أو تنسيق +- تسجيل تفاصيل الاستجابة +- تحديث سجل المحادثة +- تنفيذ تصفية المحتوى + +**التوقيع:** +```python +def after_hook(context: LLMCallHookContext) -> str | None: + # Return modified response string + # Return None to keep original response + ... +``` + +## سياق خطاف LLM + +يوفر كائن `LLMCallHookContext` وصولاً شاملاً لحالة التنفيذ: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # Full executor reference + messages: list # Mutable message list + agent: Agent # Current agent + task: Task # Current task + crew: Crew # Crew instance + llm: BaseLLM # LLM instance + iterations: int # Current iteration count + response: str | None # LLM response (after hooks only) +``` + +### تعديل الرسائل + +**مهم:** قم دائماً بتعديل الرسائل في مكانها: + +```python +# ✅ Correct - modify in-place +def add_context(context: LLMCallHookContext) -> None: + context.messages.append({"role": "system", "content": "Be concise"}) + +# ❌ Wrong - replaces list reference +def wrong_approach(context: LLMCallHookContext) -> None: + context.messages = [{"role": "system", "content": "Be concise"}] +``` + +## طرق التسجيل + +### 1. تسجيل الخطافات العامة + +تسجيل خطافات تنطبق على جميع استدعاءات LLM عبر جميع الأطقم: + +```python +from crewai.hooks import register_before_llm_call_hook, register_after_llm_call_hook + +def log_llm_call(context): + print(f"LLM call by {context.agent.role} at iteration {context.iterations}") + return None # Allow execution + +register_before_llm_call_hook(log_llm_call) +``` + +### 2. التسجيل باستخدام المزخرفات + +استخدم المزخرفات لصياغة أنظف: + +```python +from crewai.hooks import before_llm_call, after_llm_call + +@before_llm_call +def validate_iteration_count(context): + if context.iterations > 10: + print("⚠️ Exceeded maximum iterations") + return False # Block execution + return None + +@after_llm_call +def sanitize_response(context): + if context.response and "API_KEY" in context.response: + return context.response.replace("API_KEY", "[REDACTED]") + return None +``` + +### 3. خطافات نطاق الطاقم + +تسجيل خطافات لمثيل طاقم محدد: + +```python +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # Only applies to this crew + if context.iterations == 0: + print(f"Starting task: {context.task.description}") + return None + + @after_llm_call_crew + def log_responses(self, context): + # Crew-specific response logging + print(f"Response length: {len(context.response)}") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## حالات الاستخدام الشائعة + +### 1. تحديد التكرارات + +```python +@before_llm_call +def limit_iterations(context: LLMCallHookContext) -> bool | None: + max_iterations = 15 + if context.iterations > max_iterations: + print(f"⛔ Blocked: Exceeded {max_iterations} iterations") + return False # Block execution + return None +``` + +### 2. بوابة الموافقة البشرية + +```python +@before_llm_call +def require_approval(context: LLMCallHookContext) -> bool | None: + if context.iterations > 5: + response = context.request_human_input( + prompt=f"Iteration {context.iterations}: Approve LLM call?", + default_message="Press Enter to approve, or type 'no' to block:" + ) + if response.lower() == "no": + print("🚫 LLM call blocked by user") + return False + return None +``` + +### 3. إضافة سياق النظام + +```python +@before_llm_call +def add_guardrails(context: LLMCallHookContext) -> None: + # Add safety guidelines to every LLM call + context.messages.append({ + "role": "system", + "content": "Ensure responses are factual and cite sources when possible." + }) + return None +``` + +### 4. تنقية الاستجابات + +```python +@after_llm_call +def sanitize_sensitive_data(context: LLMCallHookContext) -> str | None: + if not context.response: + return None + + # Remove sensitive patterns + import re + sanitized = context.response + sanitized = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[SSN-REDACTED]', sanitized) + sanitized = re.sub(r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', '[CARD-REDACTED]', sanitized) + + return sanitized +``` + +### 5. تتبع التكاليف + +```python +import tiktoken + +@before_llm_call +def track_token_usage(context: LLMCallHookContext) -> None: + encoding = tiktoken.get_encoding("cl100k_base") + total_tokens = sum( + len(encoding.encode(msg.get("content", ""))) + for msg in context.messages + ) + print(f"📊 Input tokens: ~{total_tokens}") + return None + +@after_llm_call +def track_response_tokens(context: LLMCallHookContext) -> None: + if context.response: + encoding = tiktoken.get_encoding("cl100k_base") + tokens = len(encoding.encode(context.response)) + print(f"📊 Response tokens: ~{tokens}") + return None +``` + +### 6. تسجيل التصحيح + +```python +@before_llm_call +def debug_request(context: LLMCallHookContext) -> None: + print(f""" + 🔍 LLM Call Debug: + - Agent: {context.agent.role} + - Task: {context.task.description[:50]}... + - Iteration: {context.iterations} + - Message Count: {len(context.messages)} + - Last Message: {context.messages[-1] if context.messages else 'None'} + """) + return None + +@after_llm_call +def debug_response(context: LLMCallHookContext) -> None: + if context.response: + print(f"✅ Response Preview: {context.response[:100]}...") + return None +``` + +## إدارة الخطافات + +### إلغاء تسجيل الخطافات + +```python +from crewai.hooks import ( + unregister_before_llm_call_hook, + unregister_after_llm_call_hook +) + +# Unregister specific hook +def my_hook(context): + ... + +register_before_llm_call_hook(my_hook) +# Later... +unregister_before_llm_call_hook(my_hook) # Returns True if found +``` + +### مسح الخطافات + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_all_llm_call_hooks +) + +# Clear specific hook type +count = clear_before_llm_call_hooks() +print(f"Cleared {count} before hooks") + +# Clear all LLM hooks +before_count, after_count = clear_all_llm_call_hooks() +print(f"Cleared {before_count} before and {after_count} after hooks") +``` + +### عرض الخطافات المسجلة + +```python +from crewai.hooks import ( + get_before_llm_call_hooks, + get_after_llm_call_hooks +) + +# Get current hooks +before_hooks = get_before_llm_call_hooks() +after_hooks = get_after_llm_call_hooks() + +print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after") +``` + +## أنماط متقدمة + +### تنفيذ خطاف مشروط + +```python +@before_llm_call +def conditional_blocking(context: LLMCallHookContext) -> bool | None: + # Only block for specific agents + if context.agent.role == "researcher" and context.iterations > 10: + return False + + # Only block for specific tasks + if "sensitive" in context.task.description.lower() and context.iterations > 5: + return False + + return None +``` + +### تعديلات واعية بالسياق + +```python +@before_llm_call +def adaptive_prompting(context: LLMCallHookContext) -> None: + # Add different context based on iteration + if context.iterations == 0: + context.messages.append({ + "role": "system", + "content": "Start with a high-level overview." + }) + elif context.iterations > 3: + context.messages.append({ + "role": "system", + "content": "Focus on specific details and provide examples." + }) + return None +``` + +### ربط الخطافات + +```python +# Multiple hooks execute in registration order + +@before_llm_call +def first_hook(context): + print("1. First hook executed") + return None + +@before_llm_call +def second_hook(context): + print("2. Second hook executed") + return None + +@before_llm_call +def blocking_hook(context): + if context.iterations > 10: + print("3. Blocking hook - execution stopped") + return False # Subsequent hooks won't execute + print("3. Blocking hook - execution allowed") + return None +``` + +## أفضل الممارسات + +1. **اجعل الخطافات مركزة**: يجب أن يكون لكل خطاف مسؤولية واحدة +2. **تجنب الحسابات الثقيلة**: تُنفذ الخطافات في كل استدعاء LLM +3. **تعامل مع الأخطاء بأناقة**: استخدم try-except لمنع فشل الخطافات من كسر التنفيذ +4. **استخدم تلميحات الأنواع**: استفد من `LLMCallHookContext` لدعم أفضل في بيئة التطوير +5. **وثّق سلوك الخطاف**: خاصة لشروط الحظر +6. **اختبر الخطافات بشكل مستقل**: اختبر الخطافات وحدوياً قبل الاستخدام في الإنتاج +7. **امسح الخطافات في الاختبارات**: استخدم `clear_all_llm_call_hooks()` بين تشغيلات الاختبار +8. **عدّل في المكان**: قم دائماً بتعديل `context.messages` في مكانها، ولا تستبدلها + +## معالجة الأخطاء + +```python +@before_llm_call +def safe_hook(context: LLMCallHookContext) -> bool | None: + try: + # Your hook logic + if some_condition: + return False + except Exception as e: + print(f"⚠️ Hook error: {e}") + # Decide: allow or block on error + return None # Allow execution despite error +``` + +## أمان الأنواع + +```python +from crewai.hooks import LLMCallHookContext, BeforeLLMCallHookType, AfterLLMCallHookType + +# Explicit type annotations +def my_before_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_after_hook(context: LLMCallHookContext) -> str | None: + return None + +# Type-safe registration +register_before_llm_call_hook(my_before_hook) +register_after_llm_call_hook(my_after_hook) +``` + +## استكشاف الأخطاء وإصلاحها + +### الخطاف لا يُنفذ +- تحقق من أن الخطاف مسجل قبل تنفيذ الطاقم +- تحقق مما إذا كان خطاف سابق أرجع `False` (يحظر الخطافات اللاحقة) +- تأكد من أن توقيع الخطاف يطابق النوع المتوقع + +### تعديلات الرسائل لا تستمر +- استخدم التعديلات في المكان: `context.messages.append()` +- لا تستبدل القائمة: `context.messages = []` + +### تعديلات الاستجابة لا تعمل +- أرجع السلسلة النصية المعدلة من خطافات ما بعد +- إرجاع `None` يحتفظ بالاستجابة الأصلية + +## الخاتمة + +توفر خطافات استدعاء LLM إمكانيات قوية للتحكم في تفاعلات نماذج اللغة ومراقبتها في CrewAI. استخدمها لتنفيذ حواجز الأمان وبوابات الموافقة والتسجيل وتتبع التكاليف وتنقية الاستجابات. مع معالجة الأخطاء المناسبة وأمان الأنواع، تُمكّن الخطافات أنظمة وكلاء قوية وجاهزة للإنتاج. diff --git a/docs/v1.15.1/ar/learn/llm-selection-guide.mdx b/docs/v1.15.1/ar/learn/llm-selection-guide.mdx new file mode 100644 index 000000000..f71865192 --- /dev/null +++ b/docs/v1.15.1/ar/learn/llm-selection-guide.mdx @@ -0,0 +1,821 @@ +--- +title: "دليل اختيار LLM الاستراتيجي" +description: "إطار عمل استراتيجي لاختيار نموذج اللغة الكبير المناسب لوكلاء الذكاء الاصطناعي في CrewAI وكتابة تعريفات فعالة للمهام والوكلاء" +icon: "brain-circuit" +mode: "wide" +--- + +## نهج CrewAI في اختيار LLM + +بدلاً من توصيات نماذج محددة، ندعو إلى **إطار تفكير** يساعدك على اتخاذ قرارات مستنيرة بناءً على حالة استخدامك المحددة وقيودك ومتطلباتك. يتطور مشهد LLM بسرعة، مع ظهور نماذج جديدة بانتظام وتحديث النماذج الحالية بشكل متكرر. الأهم هو تطوير نهج منظم للتقييم يبقى ذا صلة بغض النظر عن النماذج المتاحة تحديداً. + + + يركز هذا الدليل على التفكير الاستراتيجي بدلاً من توصيات نماذج محددة، + حيث يتطور مشهد LLM بسرعة. + + +## إطار القرار السريع + + + + ابدأ بفهم عميق لما تتطلبه مهامك فعلاً. ضع في الاعتبار التعقيد المعرفي + المطلوب وعمق الاستدلال اللازم وتنسيق المخرجات المتوقعة وحجم السياق الذي + سيحتاج النموذج لمعالجته. سيوجه هذا التحليل الأساسي كل قرار لاحق. + + + بمجرد فهم متطلباتك، اربطها بنقاط قوة النماذج. تتفوق عائلات النماذج + المختلفة في أنواع مختلفة من العمل؛ بعضها محسّن للاستدلال والتحليل وبعضها + للإبداع وتوليد المحتوى وبعضها للسرعة والكفاءة. + + + ضع في حسبانك قيودك التشغيلية الواقعية بما في ذلك قيود الميزانية ومتطلبات + زمن الاستجابة واحتياجات خصوصية البيانات وقدرات البنية التحتية. قد لا يكون + النموذج الأفضل نظرياً هو الخيار الأفضل عملياً لوضعك. + + + ابدأ بنماذج موثوقة ومفهومة جيداً وحسّن بناءً على الأداء الفعلي في حالة + استخدامك المحددة. غالباً ما تختلف النتائج الواقعية عن المعايير النظرية، لذا + فإن الاختبار التجريبي ضروري. + + + +## Core Selection Framework + +### a. Task-First Thinking + +The most critical step in LLM selection is understanding what your task actually demands. Too often, teams select models based on general reputation or benchmark scores without carefully analyzing their specific requirements. This approach leads to either over-engineering simple tasks with expensive, complex models, or under-powering sophisticated work with models that lack the necessary capabilities. + + + + - **Simple Tasks** represent the majority of everyday AI work and include basic instruction following, straightforward data processing, and simple formatting operations. These tasks typically have clear inputs and outputs with minimal ambiguity. The cognitive load is low, and the model primarily needs to follow explicit instructions rather than engage in complex reasoning. + + - **Complex Tasks** require multi-step reasoning, strategic thinking, and the ability to handle ambiguous or incomplete information. These might involve analyzing multiple data sources, developing comprehensive strategies, or solving problems that require breaking down into smaller components. The model needs to maintain context across multiple reasoning steps and often must make inferences that aren't explicitly stated. + + - **Creative Tasks** demand a different type of cognitive capability focused on generating novel, engaging, and contextually appropriate content. This includes storytelling, marketing copy creation, and creative problem-solving. The model needs to understand nuance, tone, and audience while producing content that feels authentic and engaging rather than formulaic. + + + + + - **Structured Data** tasks require precision and consistency in format adherence. When working with JSON, XML, or database formats, the model must reliably produce syntactically correct output that can be programmatically processed. These tasks often have strict validation requirements and little tolerance for format errors, making reliability more important than creativity. + + - **Creative Content** outputs demand a balance of technical competence and creative flair. The model needs to understand audience, tone, and brand voice while producing content that engages readers and achieves specific communication goals. Quality here is often subjective and requires models that can adapt their writing style to different contexts and purposes. + + - **Technical Content** sits between structured data and creative content, requiring both precision and clarity. Documentation, code generation, and technical analysis need to be accurate and comprehensive while remaining accessible to the intended audience. The model must understand complex technical concepts and communicate them effectively. + + + + + - **Short Context** scenarios involve focused, immediate tasks where the model needs to process limited information quickly. These are often transactional interactions where speed and efficiency matter more than deep understanding. The model doesn't need to maintain extensive conversation history or process large documents. + + - **Long Context** requirements emerge when working with substantial documents, extended conversations, or complex multi-part tasks. The model needs to maintain coherence across thousands of tokens while referencing earlier information accurately. This capability becomes crucial for document analysis, comprehensive research, and sophisticated dialogue systems. + + - **Very Long Context** scenarios push the boundaries of what's currently possible, involving massive document processing, extensive research synthesis, or complex multi-session interactions. These use cases require models specifically designed for extended context handling and often involve trade-offs between context length and processing speed. + + + + +### b. Model Capability Mapping + +Understanding model capabilities requires looking beyond marketing claims and benchmark scores to understand the fundamental strengths and limitations of different model architectures and training approaches. + + + + Reasoning models represent a specialized category designed specifically for complex, multi-step thinking tasks. These models excel when problems require careful analysis, strategic planning, or systematic problem decomposition. They typically employ techniques like chain-of-thought reasoning or tree-of-thought processing to work through complex problems step by step. + + The strength of reasoning models lies in their ability to maintain logical consistency across extended reasoning chains and to break down complex problems into manageable components. They're particularly valuable for strategic planning, complex analysis, and situations where the quality of reasoning matters more than speed of response. + + However, reasoning models often come with trade-offs in terms of speed and cost. They may also be less suitable for creative tasks or simple operations where their sophisticated reasoning capabilities aren't needed. Consider these models when your tasks involve genuine complexity that benefits from systematic, step-by-step analysis. + + + + + General purpose models offer the most balanced approach to LLM selection, providing solid performance across a wide range of tasks without extreme specialization in any particular area. These models are trained on diverse datasets and optimized for versatility rather than peak performance in specific domains. + + The primary advantage of general purpose models is their reliability and predictability across different types of work. They handle most standard business tasks competently, from research and analysis to content creation and data processing. This makes them excellent choices for teams that need consistent performance across varied workflows. + + While general purpose models may not achieve the peak performance of specialized alternatives in specific domains, they offer operational simplicity and reduced complexity in model management. They're often the best starting point for new projects, allowing teams to understand their specific needs before potentially optimizing with more specialized models. + + + + + Fast and efficient models prioritize speed, cost-effectiveness, and resource efficiency over sophisticated reasoning capabilities. These models are optimized for high-throughput scenarios where quick responses and low operational costs are more important than nuanced understanding or complex reasoning. + + These models excel in scenarios involving routine operations, simple data processing, function calling, and high-volume tasks where the cognitive requirements are relatively straightforward. They're particularly valuable for applications that need to process many requests quickly or operate within tight budget constraints. + + The key consideration with efficient models is ensuring that their capabilities align with your task requirements. While they can handle many routine operations effectively, they may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. They're best used for well-defined, routine operations where speed and cost matter more than sophistication. + + + + + Creative models are specifically optimized for content generation, writing quality, and creative thinking tasks. These models typically excel at understanding nuance, tone, and style while producing engaging, contextually appropriate content that feels natural and authentic. + + The strength of creative models lies in their ability to adapt writing style to different audiences, maintain consistent voice and tone, and generate content that engages readers effectively. They often perform better on tasks involving storytelling, marketing copy, brand communications, and other content where creativity and engagement are primary goals. + + When selecting creative models, consider not just their ability to generate text, but their understanding of audience, context, and purpose. The best creative models can adapt their output to match specific brand voices, target different audience segments, and maintain consistency across extended content pieces. + + + + + Open source models offer unique advantages in terms of cost control, customization potential, data privacy, and deployment flexibility. These models can be run locally or on private infrastructure, providing complete control over data handling and model behavior. + + The primary benefits of open source models include elimination of per-token costs, ability to fine-tune for specific use cases, complete data privacy, and independence from external API providers. They're particularly valuable for organizations with strict data privacy requirements, budget constraints, or specific customization needs. + + However, open source models require more technical expertise to deploy and maintain effectively. Teams need to consider infrastructure costs, model management complexity, and the ongoing effort required to keep models updated and optimized. The total cost of ownership may be higher than cloud-based alternatives when factoring in technical overhead. + + + + +## Strategic Configuration Patterns + +### a. Multi-Model Approach + + + Use different models for different purposes within the same crew to optimize + both performance and cost. + + +The most sophisticated CrewAI implementations often employ multiple models strategically, assigning different models to different agents based on their specific roles and requirements. This approach allows teams to optimize for both performance and cost by using the most appropriate model for each type of work. + +Planning agents benefit from reasoning models that can handle complex strategic thinking and multi-step analysis. These agents often serve as the "brain" of the operation, developing strategies and coordinating other agents' work. Content agents, on the other hand, perform best with creative models that excel at writing quality and audience engagement. Processing agents handling routine operations can use efficient models that prioritize speed and cost-effectiveness. + +**Example: Research and Analysis Crew** + +```python +from crewai import Agent, Task, Crew, LLM + +# High-capability reasoning model for strategic planning +manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1) + +# Creative model for content generation +content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7) + +# Efficient model for data processing +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, # High-capability model for complex reasoning + 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, # Creative model for engaging content + 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, # Fast, cost-effective model for routine tasks + verbose=True +) + +crew = Crew( + agents=[research_manager, content_writer, data_processor], + tasks=[...], # Your specific tasks + manager_llm=manager_llm, # Manager uses the reasoning model + verbose=True +) +``` + +The key to successful multi-model implementation is understanding how different agents interact and ensuring that model capabilities align with agent responsibilities. This requires careful planning but can result in significant improvements in both output quality and operational efficiency. + +### b. Component-Specific Selection + + + + The manager LLM plays a crucial role in hierarchical CrewAI processes, serving as the coordination point for multiple agents and tasks. This model needs to excel at delegation, task prioritization, and maintaining context across multiple concurrent operations. + + Effective manager LLMs require strong reasoning capabilities to make good delegation decisions, consistent performance to ensure predictable coordination, and excellent context management to track the state of multiple agents simultaneously. The model needs to understand the capabilities and limitations of different agents while optimizing task allocation for efficiency and quality. + + Cost considerations are particularly important for manager LLMs since they're involved in every operation. The model needs to provide sufficient capability for effective coordination while remaining cost-effective for frequent use. This often means finding models that offer good reasoning capabilities without the premium pricing of the most sophisticated options. + + + + + Function calling LLMs handle tool usage across all agents, making them critical for crews that rely heavily on external tools and APIs. These models need to excel at understanding tool capabilities, extracting parameters accurately, and handling tool responses effectively. + + The most important characteristics for function calling LLMs are precision and reliability rather than creativity or sophisticated reasoning. The model needs to consistently extract the correct parameters from natural language requests and handle tool responses appropriately. Speed is also important since tool usage often involves multiple round trips that can impact overall performance. + + Many teams find that specialized function calling models or general purpose models with strong tool support work better than creative or reasoning-focused models for this role. The key is ensuring that the model can reliably bridge the gap between natural language instructions and structured tool calls. + + + + + Individual agents can override crew-level LLM settings when their specific needs differ significantly from the general crew requirements. This capability allows for fine-tuned optimization while maintaining operational simplicity for most agents. + + Consider agent-specific overrides when an agent's role requires capabilities that differ substantially from other crew members. For example, a creative writing agent might benefit from a model optimized for content generation, while a data analysis agent might perform better with a reasoning-focused model. + + The challenge with agent-specific overrides is balancing optimization with operational complexity. Each additional model adds complexity to deployment, monitoring, and cost management. Teams should focus overrides on agents where the performance improvement justifies the additional complexity. + + + + +## Task Definition Framework + +### a. Focus on Clarity Over Complexity + +Effective task definition is often more important than model selection in determining the quality of CrewAI outputs. Well-defined tasks provide clear direction and context that enable even modest models to perform well, while poorly defined tasks can cause even sophisticated models to produce unsatisfactory results. + + + + The best task descriptions strike a balance between providing sufficient detail and maintaining clarity. They should define the specific objective clearly enough that there's no ambiguity about what success looks like, while explaining the approach or methodology in enough detail that the agent understands how to proceed. + + Effective task descriptions include relevant context and constraints that help the agent understand the broader purpose and any limitations they need to work within. They break complex work into focused steps that can be executed systematically, rather than presenting overwhelming, multi-faceted objectives that are difficult to approach systematically. + + Common mistakes include being too vague about objectives, failing to provide necessary context, setting unclear success criteria, or combining multiple unrelated tasks into a single description. The goal is to provide enough information for the agent to succeed while maintaining focus on a single, clear objective. + + + + + Expected output guidelines serve as a contract between the task definition and the agent, clearly specifying what the deliverable should look like and how it will be evaluated. These guidelines should describe both the format and structure needed, as well as the key elements that must be included for the output to be considered complete. + + The best output guidelines provide concrete examples of quality indicators and define completion criteria clearly enough that both the agent and human reviewers can assess whether the task has been completed successfully. This reduces ambiguity and helps ensure consistent results across multiple task executions. + + Avoid generic output descriptions that could apply to any task, missing format specifications that leave agents guessing about structure, unclear quality standards that make evaluation difficult, or failing to provide examples or templates that help agents understand expectations. + + + + +### b. Task Sequencing Strategy + + + + Sequential task dependencies are essential when tasks build upon previous outputs, information flows from one task to another, or quality depends on the completion of prerequisite work. This approach ensures that each task has access to the information and context it needs to succeed. + + Implementing sequential dependencies effectively requires using the context parameter to chain related tasks, building complexity gradually through task progression, and ensuring that each task produces outputs that serve as meaningful inputs for subsequent tasks. The goal is to maintain logical flow between dependent tasks while avoiding unnecessary bottlenecks. + + Sequential dependencies work best when there's a clear logical progression from one task to another and when the output of one task genuinely improves the quality or feasibility of subsequent tasks. However, they can create bottlenecks if not managed carefully, so it's important to identify which dependencies are truly necessary versus those that are merely convenient. + + + + + Parallel execution becomes valuable when tasks are independent of each other, time efficiency is important, or different expertise areas are involved that don't require coordination. This approach can significantly reduce overall execution time while allowing specialized agents to work on their areas of strength simultaneously. + + Successful parallel execution requires identifying tasks that can truly run independently, grouping related but separate work streams effectively, and planning for result integration when parallel tasks need to be combined into a final deliverable. The key is ensuring that parallel tasks don't create conflicts or redundancies that reduce overall quality. + + Consider parallel execution when you have multiple independent research streams, different types of analysis that don't depend on each other, or content creation tasks that can be developed simultaneously. However, be mindful of resource allocation and ensure that parallel execution doesn't overwhelm your available model capacity or budget. + + + + +## Optimizing Agent Configuration for LLM Performance + +### a. Role-Driven LLM Selection + + + Generic agent roles make it impossible to select the right LLM. Specific roles + enable targeted model optimization. + + +The specificity of your agent roles directly determines which LLM capabilities matter most for optimal performance. This creates a strategic opportunity to match precise model strengths with agent responsibilities. + +**Generic vs. Specific Role Impact on LLM Choice:** + +When defining roles, think about the specific domain knowledge, working style, and decision-making frameworks that would be most valuable for the tasks the agent will handle. The more specific and contextual the role definition, the better the model can embody that role effectively. + +```python +# ✅ Specific role - clear LLM requirements +specific_agent = Agent( + role="SaaS Revenue Operations Analyst", # Clear domain expertise needed + 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") # Reasoning model justified for complex analysis +) +``` + +**Role-to-Model Mapping Strategy:** + +- **"Research Analyst"** → Reasoning model (GPT-4o, Claude Sonnet) for complex analysis +- **"Content Editor"** → Creative model (Claude, GPT-4o) for writing quality +- **"Data Processor"** → Efficient model (GPT-4o-mini, Gemini Flash) for structured tasks +- **"API Coordinator"** → Function-calling optimized model (GPT-4o, Claude) for tool usage + +### b. Backstory as Model Context Amplifier + + + Strategic backstories multiply your chosen LLM's effectiveness by providing + domain-specific context that generic prompting cannot achieve. + + +A well-crafted backstory transforms your LLM choice from generic capability to specialized expertise. This is especially crucial for cost optimization - a well-contextualized efficient model can outperform a premium model without proper context. + +**Context-Driven Performance Example:** + +```python +# Context amplifies model effectiveness +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) # Balanced creativity with domain knowledge +) + +# This context enables Claude to perform like a domain expert +# Without it, even it would produce generic marketing advice +``` + +**Backstory Elements That Enhance LLM Performance:** + +- **Domain Experience**: "10+ years in enterprise SaaS sales" +- **Specific Expertise**: "Specializes in technical due diligence for Series B+ rounds" +- **Working Style**: "Prefers data-driven decisions with clear documentation" +- **Quality Standards**: "Insists on citing sources and showing analytical work" + +### c. Holistic Agent-LLM Optimization + +The most effective agent configurations create synergy between role specificity, backstory depth, and LLM selection. Each element reinforces the others to maximize model performance. + +**Optimization Framework:** + +```python +# Example: Technical Documentation Agent +tech_writer = Agent( + role="API Documentation Specialist", # Specific role for clear LLM requirements + 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", # Excellent for technical writing + temperature=0.1 # Low temperature for accuracy + ), + tools=[code_analyzer_tool, api_scanner_tool], + verbose=True +) +``` + +**Alignment Checklist:** + +- ✅ **Role Specificity**: Clear domain and responsibilities +- ✅ **LLM Match**: Model strengths align with role requirements +- ✅ **Backstory Depth**: Provides domain context the LLM can leverage +- ✅ **Tool Integration**: Tools support the agent's specialized function +- ✅ **Parameter Tuning**: Temperature and settings optimize for role needs + +The key is creating agents where every configuration choice reinforces your LLM selection strategy, maximizing performance while optimizing costs. + +## Practical Implementation Checklist + +Rather than repeating the strategic framework, here's a tactical checklist for implementing your LLM selection decisions in CrewAI: + + + + **What to Review:** + - Are all agents using the same LLM by default? + - Which agents handle the most complex reasoning tasks? + - Which agents primarily do data processing or formatting? + - Are any agents heavily tool-dependent? + + **Action**: Document current agent roles and identify optimization opportunities. + + + + + **Set Your Baseline:** + ```python + # Start with a reliable default for the crew + default_crew_llm = LLM(model="gpt-4o-mini") # Cost-effective baseline + + crew = Crew( + agents=[...], + tasks=[...], + memory=True + ) + ``` + + **Action**: Establish your crew's default LLM before optimizing individual agents. + + + + + **Identify and Upgrade Key Agents:** + ```python + # Manager or coordination agents + manager_agent = Agent( + role="Project Manager", + llm=LLM(model="gemini-2.5-flash-preview-05-20"), # Premium for coordination + # ... rest of config + ) + + # Creative or customer-facing agents + content_agent = Agent( + role="Content Creator", + llm=LLM(model="claude-3-5-sonnet"), # Best for writing + # ... rest of config + ) + ``` + + **Action**: Upgrade 20% of your agents that handle 80% of the complexity. + + + + + **Once you deploy your agents to production:** + - Use [CrewAI AMP platform](https://app.crewai.com) to A/B test your model selections + - Run multiple iterations with real inputs to measure consistency and performance + - Compare cost vs. performance across your optimized setup + - Share results with your team for collaborative decision-making + + **Action**: Replace guesswork with data-driven validation using the testing platform. + + + + +### When to Use Different Model Types + + + + Reasoning models become essential when tasks require genuine multi-step logical thinking, strategic planning, or high-level decision making that benefits from systematic analysis. These models excel when problems need to be broken down into components and analyzed systematically rather than handled through pattern matching or simple instruction following. + + Consider reasoning models for business strategy development, complex data analysis that requires drawing insights from multiple sources, multi-step problem solving where each step depends on previous analysis, and strategic planning tasks that require considering multiple variables and their interactions. + + However, reasoning models often come with higher costs and slower response times, so they're best reserved for tasks where their sophisticated capabilities provide genuine value rather than being used for simple operations that don't require complex reasoning. + + + + + Creative models become valuable when content generation is the primary output and the quality, style, and engagement level of that content directly impact success. These models excel when writing quality and style matter significantly, creative ideation or brainstorming is needed, or brand voice and tone are important considerations. + + Use creative models for blog post writing and article creation, marketing copy that needs to engage and persuade, creative storytelling and narrative development, and brand communications where voice and tone are crucial. These models often understand nuance and context better than general purpose alternatives. + + Creative models may be less suitable for technical or analytical tasks where precision and factual accuracy are more important than engagement and style. They're best used when the creative and communicative aspects of the output are primary success factors. + + + + + Efficient models are ideal for high-frequency, routine operations where speed and cost optimization are priorities. These models work best when tasks have clear, well-defined parameters and don't require sophisticated reasoning or creative capabilities. + + Consider efficient models for data processing and transformation tasks, simple formatting and organization operations, function calling and tool usage where precision matters more than sophistication, and high-volume operations where cost per operation is a significant factor. + + The key with efficient models is ensuring that their capabilities align with task requirements. They can handle many routine operations effectively but may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. + + + + + Open source models become attractive when budget constraints are significant, data privacy requirements exist, customization needs are important, or local deployment is required for operational or compliance reasons. + + Consider open source models for internal company tools where data privacy is paramount, privacy-sensitive applications that can't use external APIs, cost-optimized deployments where per-token pricing is prohibitive, and situations requiring custom model modifications or fine-tuning. + + However, open source models require more technical expertise to deploy and maintain effectively. Consider the total cost of ownership including infrastructure, technical overhead, and ongoing maintenance when evaluating open source options. + + + + +## Common CrewAI Model Selection Pitfalls + + + + **The Problem**: Using the same LLM for all agents in a crew, regardless of their specific roles and responsibilities. This is often the default approach but rarely optimal. + + **Real Example**: Using GPT-4o for both a strategic planning manager and a data extraction agent. The manager needs reasoning capabilities worth the premium cost, but the data extractor could perform just as well with GPT-4o-mini at a fraction of the price. + + **CrewAI Solution**: Leverage agent-specific LLM configuration to match model capabilities with agent roles: + ```python + # Strategic agent gets premium model + manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o")) + + # Processing agent gets efficient model + processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini")) + ``` + + + + + **The Problem**: Not understanding how CrewAI's LLM hierarchy works - crew LLM, manager LLM, and agent LLM settings can conflict or be poorly coordinated. + + **Real Example**: Setting a crew to use Claude, but having agents configured with GPT models, creating inconsistent behavior and unnecessary model switching overhead. + + **CrewAI Solution**: Plan your LLM hierarchy strategically: + ```python + crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + manager_llm=LLM(model="gpt-4o"), # For crew coordination + process=Process.hierarchical # When using manager_llm + ) + + # Agents inherit crew LLM unless specifically overridden + agent1 = Agent(llm=LLM(model="claude-3-5-sonnet")) # Override for specific needs + ``` + + + + + **The Problem**: Choosing models based on general capabilities while ignoring function calling performance for tool-heavy CrewAI workflows. + + **Real Example**: Selecting a creative-focused model for an agent that primarily needs to call APIs, search tools, or process structured data. The agent struggles with tool parameter extraction and reliable function calls. + + **CrewAI Solution**: Prioritize function calling capabilities for tool-heavy agents: + ```python + # For agents that use many tools + tool_agent = Agent( + role="API Integration Specialist", + tools=[search_tool, api_tool, data_tool], + llm=LLM(model="gpt-4o"), # Excellent function calling + # OR + llm=LLM(model="claude-3-5-sonnet") # Also strong with tools + ) + ``` + + + + + **The Problem**: Making complex model selection decisions based on theoretical performance without validating with actual CrewAI workflows and tasks. + + **Real Example**: Implementing elaborate model switching logic based on task types without testing if the performance gains justify the operational complexity. + + **CrewAI Solution**: Start simple, then optimize based on real performance data: + ```python + # Start with this + crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini")) + + # Test performance, then optimize specific agents as needed + # Use Enterprise platform testing to validate improvements + ``` + + + + + **The Problem**: Not considering how model context windows interact with CrewAI's memory and context sharing between agents. + + **Real Example**: Using a short-context model for agents that need to maintain conversation history across multiple task iterations, or in crews with extensive agent-to-agent communication. + + **CrewAI Solution**: Match context capabilities to crew communication patterns. + + + + +## Testing and Iteration Strategy + + + + Begin with reliable, general-purpose models that are well-understood and + widely supported. This provides a stable foundation for understanding your + specific requirements and performance expectations before optimizing for + specialized needs. + + + Develop metrics that align with your specific use case and business + requirements rather than relying solely on general benchmarks. Focus on + measuring outcomes that directly impact your success rather than theoretical + performance indicators. + + + Make model changes based on observed performance in your specific context + rather than theoretical considerations or general recommendations. + Real-world performance often differs significantly from benchmark results or + general reputation. + + + Evaluate the complete cost of ownership including model costs, development + time, maintenance overhead, and operational complexity. The cheapest model + per token may not be the most cost-effective choice when considering all + factors. + + + + + Focus on understanding your requirements first, then select models that best + match those needs. The best LLM choice is the one that consistently delivers + the results you need within your operational constraints. + + +### Enterprise-Grade Model Validation + +For teams serious about optimizing their LLM selection, the **CrewAI AMP platform** provides sophisticated testing capabilities that go far beyond basic CLI testing. The platform enables comprehensive model evaluation that helps you make data-driven decisions about your LLM strategy. + + + ![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png) + + +**Advanced Testing Features:** + +- **Multi-Model Comparison**: Test multiple LLMs simultaneously across the same tasks and inputs. Compare performance between GPT-4o, Claude, Llama, Groq, Cerebras, and other leading models in parallel to identify the best fit for your specific use case. + +- **Statistical Rigor**: Configure multiple iterations with consistent inputs to measure reliability and performance variance. This helps identify models that not only perform well but do so consistently across runs. + +- **Real-World Validation**: Use your actual crew inputs and scenarios rather than synthetic benchmarks. The platform allows you to test with your specific industry context, company information, and real use cases for more accurate evaluation. + +- **Comprehensive Analytics**: Access detailed performance metrics, execution times, and cost analysis across all tested models. This enables data-driven decision making rather than relying on general model reputation or theoretical capabilities. + +- **Team Collaboration**: Share testing results and model performance data across your team, enabling collaborative decision-making and consistent model selection strategies across projects. + +Go to [app.crewai.com](https://app.crewai.com) to get started! + + + The Enterprise platform transforms model selection from guesswork into a + data-driven process, enabling you to validate the principles in this guide + with your actual use cases and requirements. + + +## Key Principles Summary + + + + Choose models based on what the task actually requires, not theoretical capabilities or general reputation. + + +{" "} + + Align model strengths with agent roles and responsibilities for optimal + performance. + + +{" "} + + Maintain coherent model selection strategy across related components and + workflows. + + +{" "} + + Validate choices through real-world usage rather than benchmarks alone. + + +{" "} + + Start simple and optimize based on actual performance and needs. + + + + Balance performance requirements with cost and complexity constraints. + + + + + Remember: The best LLM choice is the one that consistently delivers the + results you need within your operational constraints. Focus on understanding + your requirements first, then select models that best match those needs. + + +## Current Model Landscape (June 2025) + + + **Snapshot in Time**: The following model rankings represent current + leaderboard standings as of June 2025, compiled from [LMSys + Arena](https://arena.lmsys.org/), [Artificial + Analysis](https://artificialanalysis.ai/), and other leading benchmarks. LLM + performance, availability, and pricing change rapidly. Always conduct your own + evaluations with your specific use cases and data. + + +### Leading Models by Category + +The tables below show a representative sample of current top-performing models across different categories, with guidance on their suitability for CrewAI agents: + + + These tables/metrics showcase selected leading models in each category and are + not exhaustive. Many excellent models exist beyond those listed here. The goal + is to illustrate the types of capabilities to look for rather than provide a + complete catalog. + + + + + **Best for Manager LLMs and Complex Analysis** + + | Model | Intelligence Score | Cost ($/M tokens) | Speed | Best Use in CrewAI | + |:------|:------------------|:------------------|:------|:------------------| + | **o3** | 70 | $17.50 | Fast | Manager LLM for complex multi-agent coordination | + | **Gemini 2.5 Pro** | 69 | $3.44 | Fast | Strategic planning agents, research coordination | + | **DeepSeek R1** | 68 | $0.96 | Moderate | Cost-effective reasoning for budget-conscious crews | + | **Claude 4 Sonnet** | 53 | $6.00 | Fast | Analysis agents requiring nuanced understanding | + | **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderate | Open-source alternative for reasoning tasks | + + These models excel at multi-step reasoning and are ideal for agents that need to develop strategies, coordinate other agents, or analyze complex information. + + + + + **Best for Development and Tool-Heavy Workflows** + + | Model | Coding Performance | Tool Use Score | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:------------------|:---------------|:------------------|:------------------| + | **Claude 4 Sonnet** | Excellent | 72.7% | $6.00 | Primary coding agent, technical documentation | + | **Claude 4 Opus** | Excellent | 72.5% | $30.00 | Complex software architecture, code review | + | **DeepSeek V3** | Very Good | High | $0.48 | Cost-effective coding for routine development | + | **Qwen2.5 Coder 32B** | Very Good | Medium | $0.15 | Budget-friendly coding agent | + | **Llama 3.1 405B** | Good | 81.1% | $3.50 | Function calling LLM for tool-heavy workflows | + + These models are optimized for code generation, debugging, and technical problem-solving, making them ideal for development-focused crews. + + + + + **Best for High-Throughput and Real-Time Applications** + + | Model | Speed (tokens/s) | Latency (TTFT) | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:-----------------|:---------------|:------------------|:------------------| + | **Llama 4 Scout** | 2,600 | 0.33s | $0.27 | High-volume processing agents | + | **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Real-time response agents | + | **DeepSeek R1 Distill** | 383 | Variable | $0.04 | Cost-optimized high-speed processing | + | **Llama 3.3 70B** | 2,500 | 0.52s | $0.60 | Balanced speed and capability | + | **Nova Micro** | High | 0.30s | $0.04 | Simple, fast task execution | + + These models prioritize speed and efficiency, perfect for agents handling routine operations or requiring quick responses. **Pro tip**: Pairing these models with fast inference providers like Groq can achieve even better performance, especially for open-source models like Llama. + + + + + **Best All-Around Models for General Crews** + + | Model | Overall Score | Versatility | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:--------------|:------------|:------------------|:------------------| + | **GPT-4.1** | 53 | Excellent | $3.50 | General-purpose crew LLM | + | **Claude 3.7 Sonnet** | 48 | Very Good | $6.00 | Balanced reasoning and creativity | + | **Gemini 2.0 Flash** | 48 | Good | $0.17 | Cost-effective general use | + | **Llama 4 Maverick** | 51 | Good | $0.37 | Open-source general purpose | + | **Qwen3 32B** | 44 | Good | $1.23 | Budget-friendly versatility | + + These models offer good performance across multiple dimensions, suitable for crews with diverse task requirements. + + + + +### Selection Framework for Current Models + + + + **When performance is the priority**: Use top-tier models like **o3**, **Gemini 2.5 Pro**, or **Claude 4 Sonnet** for manager LLMs and critical agents. These models excel at complex reasoning and coordination but come with higher costs. + + **Strategy**: Implement a multi-model approach where premium models handle strategic thinking while efficient models handle routine operations. + + + + + **When budget is a primary constraint**: Focus on models like **DeepSeek R1**, **Llama 4 Scout**, or **Gemini 2.0 Flash**. These provide strong performance at significantly lower costs. + + **Strategy**: Use cost-effective models for most agents, reserving premium models only for the most critical decision-making roles. + + + + + **For specific domain expertise**: Choose models optimized for your primary use case. **Claude 4** series for coding, **Gemini 2.5 Pro** for research, **Llama 405B** for function calling. + + **Strategy**: Select models based on your crew's primary function, ensuring the core capability aligns with model strengths. + + + + + **For data-sensitive operations**: Consider open-source models like **Llama 4** series, **DeepSeek V3**, or **Qwen3** that can be deployed locally while maintaining competitive performance. + + **Strategy**: Deploy open-source models on private infrastructure, accepting potential performance trade-offs for data control. + + + + +### Key Considerations for Model Selection + +- **Performance Trends**: The current landscape shows strong competition between reasoning-focused models (o3, Gemini 2.5 Pro) and balanced models (Claude 4, GPT-4.1). Specialized models like DeepSeek R1 offer excellent cost-performance ratios. + +- **Speed vs. Intelligence Trade-offs**: Models like Llama 4 Scout prioritize speed (2,600 tokens/s) while maintaining reasonable intelligence, whereas models like o3 maximize reasoning capability at the cost of speed and price. + +- **Open Source Viability**: The gap between open-source and proprietary models continues to narrow, with models like Llama 4 Maverick and DeepSeek V3 offering competitive performance at attractive price points. Fast inference providers particularly shine with open-source models, often delivering better speed-to-cost ratios than proprietary alternatives. + + + **Testing is Essential**: Leaderboard rankings provide general guidance, but + your specific use case, prompting style, and evaluation criteria may produce + different results. Always test candidate models with your actual tasks and + data before making final decisions. + + +### Practical Implementation Strategy + + + + Begin with well-established models like **GPT-4.1**, **Claude 3.7 Sonnet**, or **Gemini 2.0 Flash** that offer good performance across multiple dimensions and have extensive real-world validation. + + + + Determine if your crew has specific requirements (coding, reasoning, speed) + that would benefit from specialized models like **Claude 4 Sonnet** for + development or **o3** for complex analysis. For speed-critical applications, + consider fast inference providers like **Groq** alongside model selection. + + + + Use different models for different agents based on their roles. + High-capability models for managers and complex tasks, efficient models for + routine operations. + + + + Track performance metrics relevant to your use case and be prepared to adjust model selections as new models are released or pricing changes. + + diff --git a/docs/v1.15.1/ar/learn/multimodal-agents.mdx b/docs/v1.15.1/ar/learn/multimodal-agents.mdx new file mode 100644 index 000000000..9c80f969c --- /dev/null +++ b/docs/v1.15.1/ar/learn/multimodal-agents.mdx @@ -0,0 +1,141 @@ +--- +title: استخدام الوكلاء متعددي الوسائط +description: تعلم كيفية تفعيل واستخدام القدرات متعددة الوسائط في وكلائك لمعالجة الصور والمحتوى غير النصي ضمن إطار عمل CrewAI. +icon: video +mode: "wide" +--- + +## استخدام الوكلاء متعددي الوسائط + +يدعم CrewAI الوكلاء متعددي الوسائط القادرين على معالجة المحتوى النصي وغير النصي مثل الصور. سيوضح لك هذا الدليل كيفية تفعيل واستخدام القدرات متعددة الوسائط في وكلائك. + +### تفعيل القدرات متعددة الوسائط + +لإنشاء وكيل متعدد الوسائط، ما عليك سوى تعيين معامل `multimodal` إلى `True` عند تهيئة وكيلك: + +```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 +) +``` + +عند تعيين `multimodal=True`، يتم إعداد الوكيل تلقائياً بالأدوات اللازمة للتعامل مع المحتوى غير النصي، بما في ذلك `AddImageTool`. + +### العمل مع الصور + +يأتي الوكيل متعدد الوسائط مُعداً مسبقاً بأداة `AddImageTool`، التي تتيح له معالجة الصور. لا تحتاج إلى إضافة هذه الأداة يدوياً — فهي مضمنة تلقائياً عند تفعيل القدرات متعددة الوسائط. + +إليك مثالاً كاملاً يوضح كيفية استخدام وكيل متعدد الوسائط لتحليل صورة: + +```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() +``` + +### الاستخدام المتقدم مع السياق + +يمكنك تقديم سياق إضافي أو أسئلة محددة حول الصورة عند إنشاء مهام للوكلاء متعددي الوسائط. يمكن أن يتضمن وصف المهمة جوانب محددة تريد أن يركز عليها الوكيل: + +```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() +``` + +### تفاصيل الأداة + +عند العمل مع الوكلاء متعددي الوسائط، يتم إعداد `AddImageTool` تلقائياً بالمخطط التالي: + +```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 +``` + +سيتعامل الوكيل متعدد الوسائط تلقائياً مع معالجة الصور من خلال أدواته المدمجة، مما يتيح له: +- الوصول إلى الصور عبر عناوين URL أو مسارات الملفات المحلية +- معالجة محتوى الصورة مع سياق اختياري أو أسئلة محددة +- تقديم تحليلات ورؤى بناءً على المعلومات البصرية ومتطلبات المهمة + +### أفضل الممارسات + +عند العمل مع الوكلاء متعددي الوسائط، ضع هذه الممارسات في الاعتبار: + +1. **الوصول إلى الصور** + - تأكد من أن صورك قابلة للوصول عبر عناوين URL التي يمكن للوكيل الوصول إليها + - للصور المحلية، فكر في استضافتها مؤقتاً أو استخدام مسارات ملفات مطلقة + - تحقق من أن عناوين URL للصور صالحة وقابلة للوصول قبل تشغيل المهام + +2. **وصف المهمة** + - كن محدداً حول الجوانب التي تريد من الوكيل تحليلها في الصورة + - قم بتضمين أسئلة أو متطلبات واضحة في وصف المهمة + - فكر في استخدام معامل `action` الاختياري للتحليل المركز + +3. **إدارة الموارد** + - قد تتطلب معالجة الصور موارد حسابية أكثر من المهام النصية فقط + - قد تتطلب بعض نماذج اللغة ترميز base64 لبيانات الصورة + - فكر في المعالجة الدفعية لصور متعددة لتحسين الأداء + +4. **إعداد البيئة** + - تحقق من أن بيئتك تحتوي على الاعتماديات اللازمة لمعالجة الصور + - تأكد من أن نموذج اللغة الخاص بك يدعم القدرات متعددة الوسائط + - اختبر بصور صغيرة أولاً للتحقق من إعدادك + +5. **معالجة الأخطاء** + - نفّذ معالجة أخطاء مناسبة لحالات فشل تحميل الصور + - ضع استراتيجيات احتياطية لحالات فشل معالجة الصور + - راقب وسجل عمليات معالجة الصور لأغراض التصحيح diff --git a/docs/v1.15.1/ar/learn/overview.mdx b/docs/v1.15.1/ar/learn/overview.mdx new file mode 100644 index 000000000..b09a944fd --- /dev/null +++ b/docs/v1.15.1/ar/learn/overview.mdx @@ -0,0 +1,159 @@ +--- +title: "نظرة عامة" +description: "تعلم كيفية بناء وتخصيص وتحسين تطبيقات CrewAI الخاصة بك مع أدلة وبرامج تعليمية شاملة" +icon: "face-smile" +mode: "wide" +--- + +## تعلم CrewAI + +يوفر هذا القسم أدلة وبرامج تعليمية شاملة لمساعدتك في إتقان CrewAI، من المفاهيم الأساسية إلى التقنيات المتقدمة. سواء كنت قد بدأت للتو أو تبحث عن تحسين تطبيقاتك الحالية، ستوجهك هذه الموارد عبر كل جانب من جوانب بناء سير عمل وكلاء الذكاء الاصطناعي القوية. + +## أدلة البدء + +### المفاهيم الأساسية + + + تعلم كيفية تنفيذ المهام بترتيب تسلسلي لسير عمل منظم. + + + + تنفيذ تنفيذ المهام الهرمي مع وكلاء مديرين يشرفون على سير العمل. + + + + إنشاء سير عمل ديناميكي مع تنفيذ مهام شرطي بناءً على النتائج. + + + + تنفيذ الأطقم بشكل غير متزامن لأداء وتزامن محسّن. + + + +### تطوير الوكلاء + + + تعلم كيفية تخصيص سلوك الوكلاء وأدوارهم وقدراتهم. + + + + بناء وكلاء يمكنهم كتابة وتنفيذ وتصحيح الكود تلقائياً. + + + + إنشاء وكلاء يمكنهم معالجة النصوص والصور وأنواع الوسائط الأخرى. + + + + تنفيذ وكلاء مديرين مخصصين لسير العمل الهرمي المعقد. + + + +## الميزات المتقدمة + +### التحكم في سير العمل + + + دمج الإشراف البشري والتدخل في سير عمل الوكلاء. + + + + السماح بالإدخال البشري أثناء تنفيذ المهام لاتخاذ قرارات ديناميكية. + + + + إعادة تشغيل واستئناف المهام من عمليات تنفيذ الطاقم السابقة. + + + + تنفيذ الأطقم عدة مرات بمدخلات مختلفة بكفاءة. + + + +### التخصيص والتكامل + + + دمج نماذج لغة ومزودين مخصصين مع CrewAI. + + + + إعداد وإدارة الاتصالات بمزودي LLM المختلفين. + + + + بناء أدوات مخصصة لتوسيع قدرات الوكلاء. + + + + استخدام تعليقات Python التوضيحية لكود أنظف وأسهل في الصيانة. + + + +## التطبيقات المتخصصة + +### المحتوى والوسائط + + + توليد الصور باستخدام تكامل DALL-E مع وكلائك. + + + + دمج الوكلاء والنماذج الموجودة في سير عمل CrewAI. + + + +### إدارة الأدوات + + + إعداد الأدوات لإرجاع مخرجاتها مباشرة كنتائج للمهام. + + + +## توصيات مسار التعلم + +### للمبتدئين +1. ابدأ بـ **العملية التسلسلية** لفهم تنفيذ سير العمل الأساسي +2. تعلم **تخصيص الوكلاء** لإنشاء إعدادات وكلاء فعالة +3. استكشف **إنشاء أدوات مخصصة** لتوسيع الوظائف +4. جرب **الإنسان في الحلقة** لسير العمل التفاعلي + +### للمستخدمين المتوسطين +1. أتقن **العملية الهرمية** لأنظمة الوكلاء المتعددة المعقدة +2. نفّذ **المهام الشرطية** لسير العمل الديناميكي +3. استخدم **التشغيل غير المتزامن** لتحسين الأداء +4. ادمج **LLM مخصص** للنماذج المتخصصة + +### للمستخدمين المتقدمين +1. ابنِ **وكلاء متعددي الوسائط** لمعالجة الوسائط المعقدة +2. أنشئ **وكلاء مديرين مخصصين** للتنسيق المتطور +3. نفّذ **أحضر وكيلك الخاص** للأنظمة الهجينة +4. استخدم **إعادة تشغيل المهام** لاسترداد الأخطاء بشكل متين + +## أفضل الممارسات + +### التطوير +- **ابدأ بالبساطة**: ابدأ بسير العمل التسلسلي الأساسي قبل إضافة التعقيد +- **اختبر تدريجياً**: اختبر كل مكون قبل دمجه في أنظمة أكبر +- **استخدم التعليقات التوضيحية**: استفد من تعليقات Python التوضيحية لكود أنظف وأسهل في الصيانة +- **أدوات مخصصة**: ابنِ أدوات قابلة لإعادة الاستخدام يمكن مشاركتها عبر وكلاء مختلفين + +### الإنتاج +- **معالجة الأخطاء**: نفّذ معالجة أخطاء وآليات استرداد قوية +- **الأداء**: استخدم التنفيذ غير المتزامن وحسّن استدعاءات LLM لأداء أفضل +- **المراقبة**: ادمج أدوات المراقبة لتتبع أداء الوكلاء +- **الإشراف البشري**: ضمّن نقاط تفتيش بشرية للقرارات الحرجة + +### التحسين +- **إدارة الموارد**: راقب وحسّن استخدام الرموز وتكاليف API +- **تصميم سير العمل**: صمم سير عمل يقلل من استدعاءات LLM غير الضرورية +- **كفاءة الأدوات**: أنشئ أدوات فعالة توفر أقصى قيمة بأقل حمل +- **التحسين التكراري**: استخدم التغذية الراجعة والمقاييس لتحسين أداء الوكلاء باستمرار + +## الحصول على المساعدة + +- **التوثيق**: يتضمن كل دليل أمثلة وشروحات مفصلة +- **المجتمع**: انضم إلى [منتدى CrewAI](https://community.crewai.com) للمناقشات والدعم +- **الأمثلة**: تحقق من قسم الأمثلة للتطبيقات العاملة الكاملة +- **الدعم**: تواصل مع [support@crewai.com](mailto:support@crewai.com) للمساعدة التقنية + +ابدأ بالأدلة التي تتوافق مع احتياجاتك الحالية واستكشف تدريجياً المواضيع الأكثر تقدماً مع إتقانك للأساسيات. diff --git a/docs/v1.15.1/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/v1.15.1/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx new file mode 100644 index 000000000..069e25c31 --- /dev/null +++ b/docs/v1.15.1/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx @@ -0,0 +1,79 @@ +--- +title: إعادة تشغيل المهام من آخر تنفيذ للطاقم +description: إعادة تشغيل المهام من آخر crew.kickoff(...) +icon: arrow-right +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على إعادة التشغيل من مهمة محددة من آخر تشغيل للطاقم. هذه الميزة مفيدة بشكل خاص عندما تكون قد أنهيت تشغيلاً وقد ترغب في إعادة محاولة مهام معينة أو لا تحتاج إلى إعادة جلب البيانات ووكلاؤك لديهم بالفعل السياق المحفوظ من تنفيذ التشغيل، لذا تحتاج فقط إلى إعادة تشغيل المهام التي تريدها. + + + يجب عليك تشغيل `crew.kickoff()` قبل أن تتمكن من إعادة تشغيل مهمة. + حالياً، يُدعم فقط آخر تشغيل، لذا إذا استخدمت `kickoff_for_each`، فسيسمح لك فقط بإعادة التشغيل من أحدث تشغيل للطاقم. + + +إليك مثالاً على كيفية إعادة التشغيل من مهمة: + +### إعادة التشغيل من مهمة محددة باستخدام CLI + +لاستخدام ميزة إعادة التشغيل، اتبع هذه الخطوات: + + + + + + لعرض معرفات المهام من آخر تشغيل، استخدم: + + ```shell + crewai log-tasks-outputs + ``` + + بمجرد حصولك على `task_id` لإعادة التشغيل، استخدم: + + ```shell + crewai replay -t + ``` + + + + + تأكد من أن `crewai` مثبت ومُعد بشكل صحيح في بيئة التطوير الخاصة بك. + + +### إعادة التشغيل من مهمة برمجياً + +لإعادة التشغيل من مهمة برمجياً، استخدم الخطوات التالية: + + + + حدد `task_id` ومعاملات الإدخال لعملية إعادة التشغيل. + + + نفّذ أمر إعادة التشغيل ضمن كتلة try-except للتعامل مع الأخطاء المحتملة. + + ```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}") + ``` + + + + +## الخاتمة + +مع التحسينات المذكورة أعلاه والوظائف المفصلة، أصبحت إعادة تشغيل مهام محددة في CrewAI أكثر كفاءة ومتانة. +تأكد من اتباع الأوامر والخطوات بدقة لتحقيق أقصى استفادة من هذه الميزات. diff --git a/docs/v1.15.1/ar/learn/sequential-process.mdx b/docs/v1.15.1/ar/learn/sequential-process.mdx new file mode 100644 index 000000000..7ef2d66bf --- /dev/null +++ b/docs/v1.15.1/ar/learn/sequential-process.mdx @@ -0,0 +1,128 @@ +--- +title: العمليات التسلسلية +description: دليل شامل لاستخدام العمليات التسلسلية لتنفيذ المهام في مشاريع CrewAI. +icon: forward +mode: "wide" +--- + +## مقدمة + +يقدم CrewAI إطار عمل مرن لتنفيذ المهام بطريقة منظمة، يدعم كلاً من العمليات التسلسلية والهرمية. +يوضح هذا الدليل كيفية تنفيذ هذه العمليات بفعالية لضمان تنفيذ المهام بكفاءة وإكمال المشروع. + +## نظرة عامة على العملية التسلسلية + +تضمن العملية التسلسلية تنفيذ المهام واحدة تلو الأخرى، باتباع تقدم خطي. +هذا النهج مثالي للمشاريع التي تتطلب إكمال المهام بترتيب محدد. + +### الميزات الرئيسية + +- **تدفق مهام خطي**: يضمن تقدماً منظماً من خلال التعامل مع المهام بتسلسل محدد مسبقاً. +- **البساطة**: الأنسب للمشاريع ذات المهام الواضحة خطوة بخطوة. +- **سهولة المراقبة**: يسهل التتبع السهل لإكمال المهام وتقدم المشروع. + +## تنفيذ العملية التسلسلية + +لاستخدام العملية التسلسلية، قم بتجميع طاقمك وتعريف المهام بالترتيب الذي تحتاج إلى تنفيذها به. + +```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 +``` + +### ملاحظة: + +يجب أن يكون لكل مهمة في عملية تسلسلية وكيل مُعيّن. تأكد من أن كل `Task` تتضمن معامل `agent`. + +### سير العمل أثناء التنفيذ + +1. **المهمة الأولى**: في العملية التسلسلية، يكمل الوكيل الأول مهمته ويشير إلى الإكمال. +2. **المهام اللاحقة**: يلتقط الوكلاء مهامهم بناءً على نوع العملية، مع نتائج المهام السابقة أو التوجيهات التي تقود تنفيذهم. +3. **الإكمال**: تنتهي العملية بمجرد تنفيذ المهمة النهائية، مما يؤدي إلى إكمال المشروع. + +## الميزات المتقدمة + +### تفويض المهام + +في العمليات التسلسلية، إذا كان الوكيل لديه `allow_delegation` مُعيّن إلى `True`، يمكنه تفويض المهام إلى وكلاء آخرين في الطاقم. +يتم إعداد هذه الميزة تلقائياً عندما يكون هناك عدة وكلاء في الطاقم. + +### التنفيذ غير المتزامن + +يمكن تنفيذ المهام بشكل غير متزامن، مما يسمح بالمعالجة المتوازية عند الاقتضاء. +لإنشاء مهمة غير متزامنة، عيّن `async_execution=True` عند تعريف المهمة. + +### الذاكرة والتخزين المؤقت + +يدعم CrewAI كلاً من ميزتي الذاكرة والتخزين المؤقت: + +- **الذاكرة**: فعّلها بتعيين `memory=True` عند إنشاء الطاقم. يتيح هذا للوكلاء الاحتفاظ بالمعلومات عبر المهام. +- **التخزين المؤقت**: افتراضياً، التخزين المؤقت مفعّل. عيّن `cache=False` لتعطيله. + +### دوال الاستدعاء الراجع + +يمكنك تعيين دوال استدعاء راجع على مستوى المهمة والخطوة: + +- `task_callback`: يُنفذ بعد إكمال كل مهمة. +- `step_callback`: يُنفذ بعد كل خطوة في تنفيذ الوكيل. + +### مقاييس الاستخدام + +يتتبع CrewAI استخدام الرموز عبر جميع المهام والوكلاء. يمكنك الوصول إلى هذه المقاييس بعد التنفيذ. + +## أفضل الممارسات للعمليات التسلسلية + +1. **الترتيب مهم**: رتّب المهام بتسلسل منطقي حيث تبني كل مهمة على سابقتها. +2. **أوصاف مهام واضحة**: قدم أوصافاً مفصلة لكل مهمة لتوجيه الوكلاء بفعالية. +3. **اختيار الوكيل المناسب**: طابق مهارات وأدوار الوكلاء مع متطلبات كل مهمة. +4. **استخدم السياق**: استفد من سياق المهام السابقة لإبلاغ المهام اللاحقة. + +يضمن هذا التوثيق المحدث أن التفاصيل تعكس بدقة أحدث التغييرات في قاعدة الكود وتصف بوضوح كيفية الاستفادة من الميزات والإعدادات الجديدة. +تم الحفاظ على بساطة المحتوى ومباشرته لضمان سهولة الفهم. diff --git a/docs/v1.15.1/ar/learn/streaming-crew-execution.mdx b/docs/v1.15.1/ar/learn/streaming-crew-execution.mdx new file mode 100644 index 000000000..4dfe1859f --- /dev/null +++ b/docs/v1.15.1/ar/learn/streaming-crew-execution.mdx @@ -0,0 +1,384 @@ +--- +title: بث تنفيذ الطاقم +description: بث المخرجات في الوقت الفعلي من تنفيذ طاقم CrewAI الخاص بك +icon: wave-pulse +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على بث المخرجات في الوقت الفعلي أثناء تنفيذ الطاقم، مما يتيح لك عرض النتائج فور توليدها بدلاً من انتظار اكتمال العملية بالكامل. هذه الميزة مفيدة بشكل خاص لبناء التطبيقات التفاعلية وتقديم تغذية راجعة للمستخدم ومراقبة العمليات طويلة التشغيل. + +## كيف يعمل البث + +عند تفعيل البث، يلتقط CrewAI استجابات LLM واستدعاءات الأدوات فور حدوثها، ويحزمها في أجزاء منظمة تتضمن سياقاً حول المهمة والوكيل المنفذ. يمكنك التكرار على هذه الأجزاء في الوقت الفعلي والوصول إلى النتيجة النهائية بمجرد اكتمال التنفيذ. + +## تفعيل البث + +لتفعيل البث، عيّن معامل `stream` إلى `True` عند إنشاء طاقمك: + +```python Code +from crewai import Agent, Crew, Task + +# Create your agents and tasks +researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information on topics", + backstory="You are an experienced researcher with excellent analytical skills.", +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A detailed report on recent AI advancements", + agent=researcher, +) + +# Enable streaming +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True # Enable streaming output +) +``` + +## البث المتزامن + +عند استدعاء `kickoff()` على طاقم مع تفعيل البث، يُرجع كائن `CrewStreamingOutput` يمكنك التكرار عليه لاستلام الأجزاء فور وصولها: + +```python Code +# Start streaming execution +streaming = crew.kickoff(inputs={"topic": "artificial intelligence"}) + +# Iterate over chunks as they arrive +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access the final result after streaming completes +result = streaming.result +print(f"\n\nFinal output: {result.raw}") +``` + +### معلومات جزء البث + +يوفر كل جزء سياقاً غنياً حول التنفيذ: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +for chunk in streaming: + print(f"Task: {chunk.task_name} (index {chunk.task_index})") + print(f"Agent: {chunk.agent_role}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT or TOOL_CALL + if chunk.tool_call: + print(f"Tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +### الوصول إلى نتائج البث + +يوفر كائن `CrewStreamingOutput` عدة خصائص مفيدة: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +# Iterate and collect chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# After iteration completes +print(f"\nCompleted: {streaming.is_completed}") +print(f"Full text: {streaming.get_full_text()}") +print(f"All chunks: {len(streaming.chunks)}") +print(f"Final result: {streaming.result.raw}") +``` + +## البث غير المتزامن + +للتطبيقات غير المتزامنة، يمكنك استخدام إما `akickoff()` (async أصلي) أو `kickoff_async()` (قائم على الخيوط) مع التكرار غير المتزامن: + +### async أصلي مع `akickoff()` + +توفر طريقة `akickoff()` تنفيذاً غير متزامن أصلياً حقيقياً عبر السلسلة بالكامل: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Start native async streaming + streaming = await crew.akickoff(inputs={"topic": "AI"}) + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result.raw}") + +asyncio.run(stream_crew()) +``` + +### async قائم على الخيوط مع `kickoff_async()` + +للتكامل البسيط مع async أو التوافق مع الإصدارات السابقة: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Start thread-based async streaming + streaming = await crew.kickoff_async(inputs={"topic": "AI"}) + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result.raw}") + +asyncio.run(stream_crew()) +``` + + +لأحمال العمل عالية التزامن، يُوصى باستخدام `akickoff()` لأنه يستخدم async أصلي لتنفيذ المهام وعمليات الذاكرة واسترجاع المعرفة. راجع دليل [تشغيل الطاقم بشكل غير متزامن](/ar/learn/kickoff-async) لمزيد من التفاصيل. + + +## البث مع kickoff_for_each + +عند تنفيذ طاقم لمدخلات متعددة مع `kickoff_for_each()`، يعمل البث بشكل مختلف حسب ما إذا كنت تستخدم المتزامن أو غير المتزامن: + +### kickoff_for_each المتزامن + +مع `kickoff_for_each()` المتزامن، تحصل على قائمة كائنات `CrewStreamingOutput`، واحد لكل مدخل: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} +] + +# Returns list of streaming outputs +streaming_outputs = crew.kickoff_for_each(inputs=inputs_list) + +# Iterate over each streaming output +for i, streaming in enumerate(streaming_outputs): + print(f"\n=== Input {i + 1} ===") + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\n\nResult {i + 1}: {result.raw}") +``` + +### kickoff_for_each_async غير المتزامن + +مع `kickoff_for_each_async()` غير المتزامن، تحصل على `CrewStreamingOutput` واحد يُخرج أجزاء من جميع الأطقم فور وصولها بشكل متزامن: + +```python Code +import asyncio + +async def stream_multiple_crews(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} + ] + + # Returns single streaming output for all crews + streaming = await crew.kickoff_for_each_async(inputs=inputs_list) + + # Chunks from all crews arrive as they're generated + async for chunk in streaming: + print(f"[{chunk.task_name}] {chunk.content}", end="", flush=True) + + # Access all results + results = streaming.results # List of CrewOutput objects + for i, result in enumerate(results): + print(f"\n\nResult {i + 1}: {result.raw}") + +asyncio.run(stream_multiple_crews()) +``` + +## أنواع أجزاء البث + +يمكن أن تكون الأجزاء من أنواع مختلفة، يُشار إليها بحقل `chunk_type`: + +### أجزاء TEXT + +محتوى نصي قياسي من استجابات LLM: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### أجزاء TOOL_CALL + +معلومات حول استدعاءات الأدوات الجارية: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL: + print(f"\nCalling tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +## مثال عملي: بناء واجهة مستخدم مع البث + +إليك مثالاً كاملاً يوضح كيفية بناء تطبيق تفاعلي مع البث: + +```python Code +import asyncio +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +async def interactive_research(): + # Create crew with streaming enabled + researcher = Agent( + role="Research Analyst", + goal="Provide detailed analysis on any topic", + backstory="You are an expert researcher with broad knowledge.", + ) + + task = Task( + description="Research and analyze: {topic}", + expected_output="A comprehensive analysis with key insights", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True, + verbose=False + ) + + # Get user input + topic = input("Enter a topic to research: ") + + print(f"\n{'='*60}") + print(f"Researching: {topic}") + print(f"{'='*60}\n") + + # Start streaming execution + streaming = await crew.kickoff_async(inputs={"topic": topic}) + + current_task = "" + async for chunk in streaming: + # Show task transitions + if chunk.task_name != current_task: + current_task = chunk.task_name + print(f"\n[{chunk.agent_role}] Working on: {chunk.task_name}") + print("-" * 60) + + # Display text chunks + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Display tool calls + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Using tool: {chunk.tool_call.tool_name}") + + # Show final result + result = streaming.result + print(f"\n\n{'='*60}") + print("Analysis Complete!") + print(f"{'='*60}") + print(f"\nToken Usage: {result.token_usage}") + +asyncio.run(interactive_research()) +``` + +## حالات الاستخدام + +البث ذو قيمة خاصة لـ: + +- **التطبيقات التفاعلية**: تقديم تغذية راجعة فورية للمستخدمين أثناء عمل الوكلاء +- **المهام طويلة التشغيل**: عرض التقدم للبحث والتحليل أو توليد المحتوى +- **التصحيح والمراقبة**: مراقبة سلوك الوكلاء واتخاذ القرارات في الوقت الفعلي +- **تجربة المستخدم**: تقليل زمن الاستجابة المتصور بعرض نتائج تدريجية +- **لوحات المعلومات الحية**: بناء واجهات مراقبة تعرض حالة تنفيذ الطاقم + +## الإلغاء وتنظيف الموارد + +يدعم `CrewStreamingOutput` الإلغاء السلس بحيث يتوقف العمل الجاري فوراً عند انقطاع اتصال المستهلك. + +### مدير السياق غير المتزامن + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### الإلغاء الصريح + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # غير متزامن + # streaming.close() # المكافئ المتزامن +``` + +بعد الإلغاء، يكون كل من `streaming.is_cancelled` و `streaming.is_completed` بقيمة `True`. كل من `aclose()` و `close()` متساويان القوة. + +## ملاحظات مهمة + +- يفعّل البث تلقائياً بث LLM لجميع الوكلاء في الطاقم +- يجب التكرار عبر جميع الأجزاء قبل الوصول إلى خاصية `.result` +- لـ `kickoff_for_each_async()` مع البث، استخدم `.results` (بصيغة الجمع) للحصول على جميع المخرجات +- يضيف البث حملاً ضئيلاً ويمكن أن يحسن الأداء المتصور فعلياً +- يتضمن كل جزء سياقاً كاملاً (المهمة، الوكيل، نوع الجزء) لواجهات مستخدم غنية + +## معالجة الأخطاء + +التعامل مع الأخطاء أثناء تنفيذ البث: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSuccess: {result.raw}") + +except Exception as e: + print(f"\nError during streaming: {e}") + if streaming.is_completed: + print("Streaming completed but an error occurred") +``` + +من خلال الاستفادة من البث، يمكنك بناء تطبيقات أكثر استجابة وتفاعلية مع CrewAI، مما يوفر للمستخدمين رؤية فورية لتنفيذ الوكلاء والنتائج. diff --git a/docs/v1.15.1/ar/learn/streaming-flow-execution.mdx b/docs/v1.15.1/ar/learn/streaming-flow-execution.mdx new file mode 100644 index 000000000..de4575b1c --- /dev/null +++ b/docs/v1.15.1/ar/learn/streaming-flow-execution.mdx @@ -0,0 +1,478 @@ +--- +title: بث تنفيذ التدفق +description: بث المخرجات في الوقت الفعلي من تنفيذ تدفق CrewAI الخاص بك +icon: wave-pulse +mode: "wide" +--- + +## مقدمة + +تدعم تدفقات CrewAI بث المخرجات، مما يتيح لك استلام تحديثات فورية أثناء تنفيذ تدفقك. تمكّنك هذه الميزة من بناء تطبيقات متجاوبة تعرض النتائج تدريجياً وتوفر تحديثات تقدم حية وتخلق تجربة مستخدم أفضل لسير العمل طويلة التشغيل. + +## كيف يعمل بث التدفق + +عند تفعيل البث في تدفق، يلتقط CrewAI ويبث المخرجات من أي أطقم أو استدعاءات LLM داخل التدفق. يقدم البث أجزاء منظمة تحتوي على المحتوى وسياق المهمة ومعلومات الوكيل مع تقدم التنفيذ. + +## تفعيل البث + +لتفعيل البث، عيّن خاصية `stream` إلى `True` في فئة التدفق الخاصة بك: + +```python Code +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task + +class ResearchFlow(Flow): + stream = True # Enable streaming for the entire flow + + @start() + def initialize(self): + return {"topic": "AI trends"} + + @listen(initialize) + def research_topic(self, data): + researcher = Agent( + role="Research Analyst", + goal="Research topics thoroughly", + backstory="Expert researcher with analytical skills", + ) + + task = Task( + description="Research {topic} and provide insights", + expected_output="Detailed research findings", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + ) + + return crew.kickoff(inputs=data) +``` + +## البث المتزامن + +عند استدعاء `kickoff()` على تدفق مع تفعيل البث، يُرجع كائن `FlowStreamingOutput` يمكنك التكرار عليه: + +```python Code +flow = ResearchFlow() + +# Start streaming execution +streaming = flow.kickoff() + +# Iterate over chunks as they arrive +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access the final result after streaming completes +result = streaming.result +print(f"\n\nFinal output: {result}") +``` + +### معلومات جزء البث + +يوفر كل جزء سياقاً حول مصدره في التدفق: + +```python Code +streaming = flow.kickoff() + +for chunk in streaming: + print(f"Agent: {chunk.agent_role}") + print(f"Task: {chunk.task_name}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT or TOOL_CALL +``` + +### الوصول إلى خصائص البث + +يوفر كائن `FlowStreamingOutput` خصائص وطرق مفيدة: + +```python Code +streaming = flow.kickoff() + +# Iterate and collect chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# After iteration completes +print(f"\nCompleted: {streaming.is_completed}") +print(f"Full text: {streaming.get_full_text()}") +print(f"Total chunks: {len(streaming.chunks)}") +print(f"Final result: {streaming.result}") +``` + +## البث غير المتزامن + +للتطبيقات غير المتزامنة، استخدم `kickoff_async()` مع التكرار غير المتزامن: + +```python Code +import asyncio + +async def stream_flow(): + flow = ResearchFlow() + + # Start async streaming + streaming = await flow.kickoff_async() + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result}") + +asyncio.run(stream_flow()) +``` + +## البث مع التدفقات متعددة الخطوات + +يعمل البث بسلاسة عبر خطوات تدفق متعددة، بما في ذلك التدفقات التي تنفذ أطقم متعددة: + +```python Code +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task + +class MultiStepFlow(Flow): + stream = True + + @start() + def research_phase(self): + """First crew: Research the topic.""" + researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information", + backstory="Expert at finding relevant information", + ) + + task = Task( + description="Research AI developments in healthcare", + expected_output="Research findings on AI in healthcare", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + + self.state["research"] = result.raw + return result.raw + + @listen(research_phase) + def analysis_phase(self, research_data): + """Second crew: Analyze the research.""" + analyst = Agent( + role="Data Analyst", + goal="Analyze information and extract insights", + backstory="Expert at identifying patterns and trends", + ) + + task = Task( + description="Analyze this research: {research}", + expected_output="Key insights and trends", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + return crew.kickoff(inputs={"research": research_data}) + + +# Stream across both phases +flow = MultiStepFlow() +streaming = flow.kickoff() + +current_step = "" +for chunk in streaming: + # Track which flow step is executing + if chunk.task_name != current_step: + current_step = chunk.task_name + print(f"\n\n=== {chunk.task_name} ===\n") + + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\n\nFinal analysis: {result}") +``` + +## مثال عملي: لوحة معلومات التقدم + +إليك مثالاً كاملاً يوضح كيفية بناء لوحة معلومات تقدم مع البث: + +```python Code +import asyncio +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +class ResearchPipeline(Flow): + stream = True + + @start() + def gather_data(self): + researcher = Agent( + role="Data Gatherer", + goal="Collect relevant information", + backstory="Skilled at finding quality sources", + ) + + task = Task( + description="Gather data on renewable energy trends", + expected_output="Collection of relevant data points", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + self.state["data"] = result.raw + return result.raw + + @listen(gather_data) + def analyze_data(self, data): + analyst = Agent( + role="Data Analyst", + goal="Extract meaningful insights", + backstory="Expert at data analysis", + ) + + task = Task( + description="Analyze: {data}", + expected_output="Key insights and trends", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + return crew.kickoff(inputs={"data": data}) + + +async def run_with_dashboard(): + flow = ResearchPipeline() + + print("="*60) + print("RESEARCH PIPELINE DASHBOARD") + print("="*60) + + streaming = await flow.kickoff_async() + + current_agent = "" + current_task = "" + chunk_count = 0 + + async for chunk in streaming: + chunk_count += 1 + + # Display phase transitions + if chunk.task_name != current_task: + current_task = chunk.task_name + current_agent = chunk.agent_role + print(f"\n\n📋 Phase: {current_task}") + print(f"👤 Agent: {current_agent}") + print("-" * 60) + + # Display text output + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Display tool usage + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Tool: {chunk.tool_call.tool_name}") + + # Show completion summary + result = streaming.result + print(f"\n\n{'='*60}") + print("PIPELINE COMPLETE") + print(f"{'='*60}") + print(f"Total chunks: {chunk_count}") + print(f"Final output length: {len(str(result))} characters") + +asyncio.run(run_with_dashboard()) +``` + +## البث مع إدارة الحالة + +يعمل البث بشكل طبيعي مع إدارة حالة التدفق: + +```python Code +from pydantic import BaseModel + +class AnalysisState(BaseModel): + topic: str = "" + research: str = "" + insights: str = "" + +class StatefulStreamingFlow(Flow[AnalysisState]): + stream = True + + @start() + def research(self): + # State is available during streaming + topic = self.state.topic + print(f"Researching: {topic}") + + researcher = Agent( + role="Researcher", + goal="Research topics thoroughly", + backstory="Expert researcher", + ) + + task = Task( + description=f"Research {topic}", + expected_output="Research findings", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + + self.state.research = result.raw + return result.raw + + @listen(research) + def analyze(self, research): + # Access updated state + print(f"Analyzing {len(self.state.research)} chars of research") + + analyst = Agent( + role="Analyst", + goal="Extract insights", + backstory="Expert analyst", + ) + + task = Task( + description="Analyze: {research}", + expected_output="Key insights", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + result = crew.kickoff(inputs={"research": research}) + + self.state.insights = result.raw + return result.raw + + +# Run with streaming +flow = StatefulStreamingFlow() +streaming = flow.kickoff(inputs={"topic": "quantum computing"}) + +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\n\nFinal state:") +print(f"Topic: {flow.state.topic}") +print(f"Research length: {len(flow.state.research)}") +print(f"Insights length: {len(flow.state.insights)}") +``` + +## حالات الاستخدام + +بث التدفق ذو قيمة خاصة لـ: + +- **سير العمل متعددة المراحل**: عرض التقدم عبر مراحل البحث والتحليل والتوليف +- **خطوط الأنابيب المعقدة**: توفير رؤية لتدفقات معالجة البيانات طويلة التشغيل +- **التطبيقات التفاعلية**: بناء واجهات مستخدم متجاوبة تعرض النتائج الوسيطة +- **المراقبة والتصحيح**: مراقبة تنفيذ التدفق وتفاعلات الأطقم في الوقت الفعلي +- **تتبع التقدم**: إظهار المرحلة الحالية من سير العمل للمستخدمين +- **لوحات المعلومات الحية**: إنشاء واجهات مراقبة لتدفقات الإنتاج + +## أنواع أجزاء البث + +مثل بث الطاقم، يمكن أن تكون أجزاء التدفق من أنواع مختلفة: + +### أجزاء TEXT + +محتوى نصي قياسي من استجابات LLM: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### أجزاء TOOL_CALL + +معلومات حول استدعاءات الأدوات داخل التدفق: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\nTool: {chunk.tool_call.tool_name}") + print(f"Args: {chunk.tool_call.arguments}") +``` + +## معالجة الأخطاء + +التعامل مع الأخطاء بأناقة أثناء البث: + +```python Code +flow = ResearchFlow() +streaming = flow.kickoff() + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSuccess! Result: {result}") + +except Exception as e: + print(f"\nError during flow execution: {e}") + if streaming.is_completed: + print("Streaming completed but flow encountered an error") +``` + +## الإلغاء وتنظيف الموارد + +يدعم `FlowStreamingOutput` الإلغاء السلس بحيث يتوقف العمل الجاري فوراً عند انقطاع اتصال المستهلك. + +### مدير السياق غير المتزامن + +```python Code +streaming = await flow.kickoff_async() + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### الإلغاء الصريح + +```python Code +streaming = await flow.kickoff_async() +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # غير متزامن + # streaming.close() # المكافئ المتزامن +``` + +بعد الإلغاء، يكون كل من `streaming.is_cancelled` و `streaming.is_completed` بقيمة `True`. كل من `aclose()` و `close()` متساويان القوة. + +## ملاحظات مهمة + +- يفعّل البث تلقائياً بث LLM لأي أطقم مستخدمة داخل التدفق +- يجب التكرار عبر جميع الأجزاء قبل الوصول إلى خاصية `.result` +- يعمل البث مع كل من حالة التدفق المنظمة وغير المنظمة +- يلتقط بث التدفق المخرجات من جميع الأطقم واستدعاءات LLM في التدفق +- يتضمن كل جزء سياقاً حول الوكيل والمهمة التي ولدته +- يضيف البث حملاً ضئيلاً لتنفيذ التدفق + +## الدمج مع تصور التدفق + +يمكنك دمج البث مع تصور التدفق لتوفير صورة كاملة: + +```python Code +# Generate flow visualization +flow = ResearchFlow() +flow.plot("research_flow") # Creates HTML visualization + +# Run with streaming +streaming = flow.kickoff() +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\nFlow complete! View structure at: research_flow.html") +``` + +من خلال الاستفادة من بث التدفق، يمكنك بناء تطبيقات متطورة ومتجاوبة توفر للمستخدمين رؤية فورية لسير العمل المعقدة متعددة المراحل، مما يجعل أتمتة الذكاء الاصطناعي الخاصة بك أكثر شفافية وجاذبية. diff --git a/docs/v1.15.1/ar/learn/tool-hooks.mdx b/docs/v1.15.1/ar/learn/tool-hooks.mdx new file mode 100644 index 000000000..372db5924 --- /dev/null +++ b/docs/v1.15.1/ar/learn/tool-hooks.mdx @@ -0,0 +1,480 @@ +--- +title: خطافات استدعاء الأدوات +description: تعلم كيفية استخدام خطافات استدعاء الأدوات لاعتراض وتعديل والتحكم في تنفيذ الأدوات في CrewAI +mode: "wide" +--- + +توفر خطافات استدعاء الأدوات تحكماً دقيقاً في تنفيذ الأدوات أثناء عمليات الوكيل. تتيح لك هذه الخطافات اعتراض استدعاءات الأدوات وتعديل المدخلات وتحويل المخرجات وتنفيذ فحوصات السلامة وإضافة تسجيل أو مراقبة شاملة. + +## نظرة عامة + +تُنفذ خطافات الأدوات في نقطتين حرجتين: +- **قبل استدعاء الأداة**: تعديل المدخلات، التحقق من المعاملات، أو حظر التنفيذ +- **بعد استدعاء الأداة**: تحويل النتائج، تنقية المخرجات، أو تسجيل تفاصيل التنفيذ + +## أنواع الخطافات + +### خطافات ما قبل استدعاء الأداة + +تُنفذ قبل كل تنفيذ أداة، ويمكن لهذه الخطافات: +- فحص وتعديل مدخلات الأداة +- حظر تنفيذ الأداة بناءً على شروط +- تنفيذ بوابات موافقة للعمليات الخطرة +- التحقق من المعاملات +- تسجيل استدعاءات الأدوات + +**التوقيع:** +```python +def before_hook(context: ToolCallHookContext) -> bool | None: + # Return False to block execution + # Return True or None to allow execution + ... +``` + +### خطافات ما بعد استدعاء الأداة + +تُنفذ بعد كل تنفيذ أداة، ويمكن لهذه الخطافات: +- تعديل أو تنقية نتائج الأداة +- إضافة بيانات وصفية أو تنسيق +- تسجيل نتائج التنفيذ +- تنفيذ التحقق من النتائج +- تحويل تنسيقات المخرجات + +**التوقيع:** +```python +def after_hook(context: ToolCallHookContext) -> str | None: + # Return modified result string + # Return None to keep original result + ... +``` + +## سياق خطاف الأداة + +يوفر كائن `ToolCallHookContext` وصولاً شاملاً لحالة تنفيذ الأداة: + +```python +class ToolCallHookContext: + tool_name: str # Name of the tool being called + tool_input: dict[str, Any] # Mutable tool input parameters + tool: CrewStructuredTool # Tool instance reference + agent: Agent | BaseAgent | None # Agent executing the tool + task: Task | None # Current task + crew: Crew | None # Crew instance + tool_result: str | None # Tool result (after hooks only) +``` + +### تعديل مدخلات الأداة + +**مهم:** قم دائماً بتعديل مدخلات الأداة في مكانها: + +```python +# ✅ Correct - modify in-place +def sanitize_input(context: ToolCallHookContext) -> None: + context.tool_input['query'] = context.tool_input['query'].lower() + +# ❌ Wrong - replaces dict reference +def wrong_approach(context: ToolCallHookContext) -> None: + context.tool_input = {'query': 'new query'} +``` + +## طرق التسجيل + +### 1. تسجيل الخطافات العامة + +تسجيل خطافات تنطبق على جميع استدعاءات الأدوات عبر جميع الأطقم: + +```python +from crewai.hooks import register_before_tool_call_hook, register_after_tool_call_hook + +def log_tool_call(context): + print(f"Tool: {context.tool_name}") + print(f"Input: {context.tool_input}") + return None # Allow execution + +register_before_tool_call_hook(log_tool_call) +``` + +### 2. التسجيل باستخدام المزخرفات + +استخدم المزخرفات لصياغة أنظف: + +```python +from crewai.hooks import before_tool_call, after_tool_call + +@before_tool_call +def block_dangerous_tools(context): + dangerous_tools = ['delete_database', 'drop_table', 'rm_rf'] + if context.tool_name in dangerous_tools: + print(f"⛔ Blocked dangerous tool: {context.tool_name}") + return False # Block execution + return None + +@after_tool_call +def sanitize_results(context): + if context.tool_result and "password" in context.tool_result.lower(): + return context.tool_result.replace("password", "[REDACTED]") + return None +``` + +### 3. خطافات نطاق الطاقم + +تسجيل خطافات لمثيل طاقم محدد: + +```python +@CrewBase +class MyProjCrew: + @before_tool_call_crew + def validate_tool_inputs(self, context): + # Only applies to this crew + if context.tool_name == "web_search": + if not context.tool_input.get('query'): + print("❌ Invalid search query") + return False + return None + + @after_tool_call_crew + def log_tool_results(self, context): + # Crew-specific tool logging + print(f"✅ {context.tool_name} completed") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## حالات الاستخدام الشائعة + +### 1. حواجز السلامة + +```python +@before_tool_call +def safety_check(context: ToolCallHookContext) -> bool | None: + destructive_tools = [ + 'delete_file', + 'drop_table', + 'remove_user', + 'system_shutdown' + ] + + if context.tool_name in destructive_tools: + print(f"🛑 Blocked destructive tool: {context.tool_name}") + return False + + sensitive_tools = ['send_email', 'post_to_social_media', 'charge_payment'] + if context.tool_name in sensitive_tools: + print(f"⚠️ Executing sensitive tool: {context.tool_name}") + + return None +``` + +### 2. بوابة الموافقة البشرية + +```python +@before_tool_call +def require_approval_for_actions(context: ToolCallHookContext) -> bool | None: + approval_required = [ + 'send_email', + 'make_purchase', + 'delete_file', + 'post_message' + ] + + if context.tool_name in approval_required: + response = context.request_human_input( + prompt=f"Approve {context.tool_name}?", + default_message=f"Input: {context.tool_input}\nType 'yes' to approve:" + ) + + if response.lower() != 'yes': + print(f"❌ Tool execution denied: {context.tool_name}") + return False + + return None +``` + +### 3. التحقق من المدخلات وتنقيتها + +```python +@before_tool_call +def validate_and_sanitize_inputs(context: ToolCallHookContext) -> bool | None: + if context.tool_name == 'web_search': + query = context.tool_input.get('query', '') + if len(query) < 3: + print("❌ Search query too short") + return False + context.tool_input['query'] = query.strip().lower() + + if context.tool_name == 'read_file': + path = context.tool_input.get('path', '') + if '..' in path or path.startswith('/'): + print("❌ Invalid file path") + return False + + return None +``` + +### 4. تنقية النتائج + +```python +@after_tool_call +def sanitize_sensitive_data(context: ToolCallHookContext) -> str | None: + if not context.tool_result: + return None + + import re + result = context.tool_result + + result = re.sub( + r'(api[_-]?key|token)["\']?\s*[:=]\s*["\']?[\w-]+', + r'\1: [REDACTED]', + result, + flags=re.IGNORECASE + ) + + result = re.sub( + r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '[EMAIL-REDACTED]', + result + ) + + result = re.sub( + r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', + '[CARD-REDACTED]', + result + ) + + return result +``` + +### 5. تحليلات استخدام الأدوات + +```python +import time +from collections import defaultdict + +tool_stats = defaultdict(lambda: {'count': 0, 'total_time': 0, 'failures': 0}) + +@before_tool_call +def start_timer(context: ToolCallHookContext) -> None: + context.tool_input['_start_time'] = time.time() + return None + +@after_tool_call +def track_tool_usage(context: ToolCallHookContext) -> None: + start_time = context.tool_input.get('_start_time', time.time()) + duration = time.time() - start_time + + tool_stats[context.tool_name]['count'] += 1 + tool_stats[context.tool_name]['total_time'] += duration + + if not context.tool_result or 'error' in context.tool_result.lower(): + tool_stats[context.tool_name]['failures'] += 1 + + print(f""" + 📊 Tool Stats for {context.tool_name}: + - Executions: {tool_stats[context.tool_name]['count']} + - Avg Time: {tool_stats[context.tool_name]['total_time'] / tool_stats[context.tool_name]['count']:.2f}s + - Failures: {tool_stats[context.tool_name]['failures']} + """) + + return None +``` + +### 6. تحديد المعدل + +```python +from collections import defaultdict +from datetime import datetime, timedelta + +tool_call_history = defaultdict(list) + +@before_tool_call +def rate_limit_tools(context: ToolCallHookContext) -> bool | None: + tool_name = context.tool_name + now = datetime.now() + + tool_call_history[tool_name] = [ + call_time for call_time in tool_call_history[tool_name] + if now - call_time < timedelta(minutes=1) + ] + + if len(tool_call_history[tool_name]) >= 10: + print(f"🚫 Rate limit exceeded for {tool_name}") + return False + + tool_call_history[tool_name].append(now) + return None +``` + +### 7. تخزين نتائج الأدوات مؤقتاً + +```python +import hashlib +import json + +tool_cache = {} + +def cache_key(tool_name: str, tool_input: dict) -> str: + """Generate cache key from tool name and input.""" + input_str = json.dumps(tool_input, sort_keys=True) + return hashlib.md5(f"{tool_name}:{input_str}".encode()).hexdigest() + +@before_tool_call +def check_cache(context: ToolCallHookContext) -> bool | None: + key = cache_key(context.tool_name, context.tool_input) + if key in tool_cache: + print(f"💾 Cache hit for {context.tool_name}") + return None + +@after_tool_call +def cache_result(context: ToolCallHookContext) -> None: + if context.tool_result: + key = cache_key(context.tool_name, context.tool_input) + tool_cache[key] = context.tool_result + print(f"💾 Cached result for {context.tool_name}") + return None +``` + +### 8. تسجيل التصحيح + +```python +@before_tool_call +def debug_tool_call(context: ToolCallHookContext) -> None: + print(f""" + 🔍 Tool Call Debug: + - Tool: {context.tool_name} + - Agent: {context.agent.role if context.agent else 'Unknown'} + - Task: {context.task.description[:50] if context.task else 'Unknown'}... + - Input: {context.tool_input} + """) + return None + +@after_tool_call +def debug_tool_result(context: ToolCallHookContext) -> None: + if context.tool_result: + result_preview = context.tool_result[:200] + print(f"✅ Result Preview: {result_preview}...") + else: + print("⚠️ No result returned") + return None +``` + +## إدارة الخطافات + +### إلغاء تسجيل الخطافات + +```python +from crewai.hooks import ( + unregister_before_tool_call_hook, + unregister_after_tool_call_hook +) + +def my_hook(context): + ... + +register_before_tool_call_hook(my_hook) +success = unregister_before_tool_call_hook(my_hook) +print(f"Unregistered: {success}") +``` + +### مسح الخطافات + +```python +from crewai.hooks import ( + clear_before_tool_call_hooks, + clear_after_tool_call_hooks, + clear_all_tool_call_hooks +) + +count = clear_before_tool_call_hooks() +print(f"Cleared {count} before hooks") + +before_count, after_count = clear_all_tool_call_hooks() +print(f"Cleared {before_count} before and {after_count} after hooks") +``` + +### عرض الخطافات المسجلة + +```python +from crewai.hooks import ( + get_before_tool_call_hooks, + get_after_tool_call_hooks +) + +before_hooks = get_before_tool_call_hooks() +after_hooks = get_after_tool_call_hooks() + +print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after") +``` + +## أفضل الممارسات + +1. **اجعل الخطافات مركزة**: يجب أن يكون لكل خطاف مسؤولية واحدة +2. **تجنب الحسابات الثقيلة**: تُنفذ الخطافات في كل استدعاء أداة +3. **تعامل مع الأخطاء بأناقة**: استخدم try-except لمنع فشل الخطافات +4. **استخدم تلميحات الأنواع**: استفد من `ToolCallHookContext` لدعم أفضل في بيئة التطوير +5. **وثّق شروط الحظر**: وضّح متى ولماذا تُحظر الأدوات +6. **اختبر الخطافات بشكل مستقل**: اختبر الخطافات وحدوياً قبل الاستخدام في الإنتاج +7. **امسح الخطافات في الاختبارات**: استخدم `clear_all_tool_call_hooks()` بين تشغيلات الاختبار +8. **عدّل في المكان**: قم دائماً بتعديل `context.tool_input` في مكانه، ولا تستبدله +9. **سجّل القرارات المهمة**: خاصة عند حظر تنفيذ الأدوات +10. **راعِ الأداء**: خزّن عمليات التحقق المكلفة مؤقتاً عند الإمكان + +## معالجة الأخطاء + +```python +@before_tool_call +def safe_validation(context: ToolCallHookContext) -> bool | None: + try: + if not validate_input(context.tool_input): + return False + except Exception as e: + print(f"⚠️ Hook error: {e}") + return None # Allow execution despite error +``` + +## أمان الأنواع + +```python +from crewai.hooks import ToolCallHookContext, BeforeToolCallHookType, AfterToolCallHookType + +def my_before_hook(context: ToolCallHookContext) -> bool | None: + return None + +def my_after_hook(context: ToolCallHookContext) -> str | None: + return None + +register_before_tool_call_hook(my_before_hook) +register_after_tool_call_hook(my_after_hook) +``` + +## استكشاف الأخطاء وإصلاحها + +### الخطاف لا يُنفذ +- تحقق من أن الخطاف مسجل قبل تنفيذ الطاقم +- تحقق مما إذا كان خطاف سابق أرجع `False` (يحظر التنفيذ والخطافات اللاحقة) +- تأكد من أن توقيع الخطاف يطابق النوع المتوقع + +### تعديلات المدخلات لا تعمل +- استخدم التعديلات في المكان: `context.tool_input['key'] = value` +- لا تستبدل القاموس: `context.tool_input = {}` + +### تعديلات النتائج لا تعمل +- أرجع السلسلة النصية المعدلة من خطافات ما بعد +- إرجاع `None` يحتفظ بالنتيجة الأصلية +- تأكد من أن الأداة أرجعت نتيجة فعلاً + +### أداة محظورة بشكل غير متوقع +- تحقق من جميع خطافات ما قبل بحثاً عن شروط حظر +- تحقق من ترتيب تنفيذ الخطافات +- أضف تسجيل تصحيح لتحديد الخطاف الذي يحظر + +## الخاتمة + +توفر خطافات استدعاء الأدوات إمكانيات قوية للتحكم في تنفيذ الأدوات ومراقبتها في CrewAI. استخدمها لتنفيذ حواجز السلامة وبوابات الموافقة والتحقق من المدخلات وتنقية النتائج والتسجيل والتحليلات. مع معالجة الأخطاء المناسبة وأمان الأنواع، تُمكّن الخطافات أنظمة وكلاء آمنة وجاهزة للإنتاج مع مراقبة شاملة. diff --git a/docs/v1.15.1/ar/learn/using-annotations.mdx b/docs/v1.15.1/ar/learn/using-annotations.mdx new file mode 100644 index 000000000..4bea3eb9f --- /dev/null +++ b/docs/v1.15.1/ar/learn/using-annotations.mdx @@ -0,0 +1,155 @@ +--- +title: "استخدام التعليقات التوضيحية في crew.py" +description: "تعلم كيفية استخدام التعليقات التوضيحية لتنظيم الوكلاء والمهام والمكونات بشكل صحيح في CrewAI" +icon: "at" +mode: "wide" +--- + +يشرح هذا الدليل كيفية استخدام التعليقات التوضيحية للإشارة بشكل صحيح إلى **الوكلاء** و**المهام** والمكونات الأخرى في ملف `crew.py` كلاسيكي. + + +المشاريع الجديدة التي تُنشأ عبر `crewai create crew ` هي JSON-first وتستخدم `crew.jsonc` مع `agents/*.jsonc`. استخدم هذا الدليل عند العمل في مشروع كلاسيكي أُنشئ عبر `crewai create crew --classic`، أو عند ترحيل مشروع Python/YAML موجود، أو عندما تحتاج تحكمًا عبر decorators في Python. + + +## مقدمة + +تُستخدم التعليقات التوضيحية في إطار عمل CrewAI لتزيين الفئات والطرق، مما يوفر بيانات وصفية ووظائف للمكونات المختلفة في طاقمك. في مشاريع Python/YAML الكلاسيكية، تنظم الكود الذي يحمّل `config/agents.yaml` و `config/tasks.yaml` ويعيد كائن `Crew`. + +## التعليقات التوضيحية المتاحة + +يوفر إطار عمل CrewAI التعليقات التوضيحية التالية: + +- `@CrewBase`: تُستخدم لتزيين فئة الطاقم الرئيسية. +- `@agent`: تزين الطرق التي تعرّف وتُرجع كائنات Agent. +- `@task`: تزين الطرق التي تعرّف وتُرجع كائنات Task. +- `@crew`: تزين الطريقة التي تنشئ وتُرجع كائن Crew. +- `@llm`: تزين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة. +- `@tool`: تزين الطرق التي تهيئ وتُرجع كائنات الأدوات. +- `@callback`: تُستخدم لتعريف طرق الاستدعاء الراجع. +- `@output_json`: تُستخدم للطرق التي تُخرج بيانات JSON. +- `@output_pydantic`: تُستخدم للطرق التي تُخرج نماذج Pydantic. +- `@cache_handler`: تُستخدم لتعريف طرق معالجة التخزين المؤقت. + +## أمثلة الاستخدام + +لنمر عبر أمثلة لكيفية استخدام هذه التعليقات التوضيحية: + +### 1. فئة الطاقم الأساسية + +```python +@CrewBase +class LinkedinProfileCrew(): + """LinkedinProfile crew""" + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' +``` + +تُستخدم التعليقة التوضيحية `@CrewBase` لتزيين فئة الطاقم الرئيسية. تحتوي هذه الفئة عادةً على الإعدادات والطرق لإنشاء الوكلاء والمهام والطاقم نفسه. + + +`@CrewBase` تفعل أكثر من مجرد تسجيل الفئة: + +- **تمهيد الإعدادات:** تبحث عن `agents_config` و `tasks_config` (القيمة الافتراضية `config/agents.yaml` و `config/tasks.yaml`) بجانب ملف الفئة، وتحملها عند الإنشاء، وتتراجع بأمان إلى قواميس فارغة إذا كانت الملفات مفقودة. +- **تنسيق المزخرفات:** تحتفظ بمراجع محفوظة لكل طريقة مُعلّمة بـ `@agent` أو `@task` أو `@before_kickoff` أو `@after_kickoff` بحيث يتم إنشاؤها مرة واحدة لكل طاقم وتُنفذ بترتيب الإعلان. +- **ربط الخطافات:** تربط تلقائياً خطافات التشغيل المحفوظة بكائن `Crew` المُرجع من طريقة `@crew`، مما يجعلها تعمل قبل وبعد `.kickoff()`. +- **تكامل MCP:** عندما تعرّف الفئة `mcp_server_params`، ينشئ `get_mcp_tools()` بكسل محول MCP server، ويملأ الأدوات المُعلنة، ويوقف خطاف ما بعد التشغيل الداخلي المحول. راجع [نظرة عامة على MCP](/ar/mcp/overview) لتفاصيل إعداد المحول. + + +### 2. تعريف الأداة + +```python +@tool +def myLinkedInProfileTool(self): + return LinkedInProfileTool() +``` + +تُستخدم التعليقة التوضيحية `@tool` لتزيين الطرق التي تُرجع كائنات أدوات. يمكن للوكلاء استخدام هذه الأدوات لأداء مهام محددة. + +### 3. تعريف 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") +``` + +تُستخدم التعليقة التوضيحية `@llm` لتزيين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة. تستخدم هذه النماذج من قبل الوكلاء لمهام معالجة اللغة الطبيعية. + +### 4. تعريف الوكيل + +```python +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'] + ) +``` + +تُستخدم التعليقة التوضيحية `@agent` لتزيين الطرق التي تعرّف وتُرجع كائنات Agent. + +### 5. تعريف المهمة + +```python +@task +def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_linkedin_task'], + agent=self.researcher() + ) +``` + +تُستخدم التعليقة التوضيحية `@task` لتزيين الطرق التي تعرّف وتُرجع كائنات Task. تحدد هذه الطرق إعداد المهمة والوكيل المسؤول عنها. + +### 6. إنشاء الطاقم + +```python +@crew +def crew(self) -> Crew: + """Creates the LinkedinProfile crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +تُستخدم التعليقة التوضيحية `@crew` لتزيين الطريقة التي تنشئ وتُرجع كائن `Crew`. تجمع هذه الطريقة جميع المكونات (الوكلاء والمهام) في طاقم وظيفي. + +## إعداد YAML الكلاسيكي + +في المشاريع الكلاسيكية، تُخزن إعدادات الوكلاء عادةً في ملف YAML. إليك مثالاً على كيفية ظهور ملف `agents.yaml` لوكيل الباحث: + +```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 +``` + +يتوافق إعداد YAML هذا مع وكيل الباحث المُعرّف في فئة `LinkedinProfileCrew`. يحدد الإعداد دور الوكيل وهدفه وخلفيته وخصائص أخرى مثل LLM والأدوات التي يستخدمها. + +لاحظ كيف يتوافق `llm` و `tools` في ملف YAML مع الطرق المزينة بـ `@llm` و `@tool` في فئة Python. + +## أفضل الممارسات + +- **تسمية متسقة**: استخدم اصطلاحات تسمية واضحة ومتسقة لطرقك. على سبيل المثال، يمكن تسمية طرق الوكلاء بأسماء أدوارهم (مثل researcher، reporting_analyst). +- **متغيرات البيئة**: استخدم متغيرات البيئة للمعلومات الحساسة مثل مفاتيح API. +- **المرونة**: صمم طاقمك ليكون مرناً بالسماح بإضافة أو إزالة الوكلاء والمهام بسهولة. +- **توافق YAML-الكود**: في المشاريع الكلاسيكية، تأكد من أن الأسماء والهياكل في ملفات YAML تتوافق بشكل صحيح مع الطرق المزينة في كود Python الخاص بك. + +باتباع هذه الإرشادات واستخدام التعليقات التوضيحية بشكل صحيح، يمكنك الحفاظ على أطقم كلاسيكية منظمة وسهلة الصيانة. للـ crews الجديدة، استخدم بنية JSON-first في [Crews](/ar/concepts/crews). diff --git a/docs/v1.15.1/ar/mcp/dsl-integration.mdx b/docs/v1.15.1/ar/mcp/dsl-integration.mdx new file mode 100644 index 000000000..392570e1f --- /dev/null +++ b/docs/v1.15.1/ar/mcp/dsl-integration.mdx @@ -0,0 +1,349 @@ +--- +title: تكامل MCP DSL +description: تعلم كيفية استخدام صياغة DSL البسيطة في CrewAI لدمج خوادم MCP مباشرة مع وكلائك باستخدام حقل mcps. +icon: code +mode: "wide" +--- + +## نظرة عامة + +يوفر تكامل MCP DSL (لغة المجال المحددة) في CrewAI **الطريقة الأبسط** لربط وكلائك بخوادم MCP (بروتوكول سياق النموذج). ما عليك سوى إضافة حقل `mcps` إلى وكيلك وسيتعامل CrewAI مع كل التعقيدات تلقائياً. + + + هذا هو **النهج الموصى به** لمعظم حالات استخدام MCP. للسيناريوهات المتقدمة + التي تتطلب إدارة اتصال يدوية، راجع + [MCPServerAdapter](/ar/mcp/overview#advanced-mcpserveradapter). + + +## الاستخدام الأساسي + +أضف خوادم MCP إلى وكيلك باستخدام حقل `mcps`: + +```python +from crewai import Agent + +agent = Agent( + role="Research Assistant", + goal="Help with research and analysis tasks", + backstory="Expert assistant with access to advanced research tools", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=research" + ] +) + +# MCP tools are now automatically available! +# No need for manual connection management or tool configuration +``` + +## تنسيقات المراجع المدعومة + +### خوادم MCP البعيدة الخارجية + +```python +# Basic HTTPS server +"https://api.example.com/mcp" + +# Server with authentication +"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" + +# Server with custom path +"https://services.company.com/api/v1/mcp" +``` + +### اختيار أدوات محددة + +استخدم صياغة `#` لاختيار أدوات محددة من خادم: + +```python +# Get only the forecast tool from weather server +"https://weather.api.com/mcp#get_forecast" + +# Get only the search tool from Exa +"https://mcp.exa.ai/mcp?api_key=your_key#web_search_exa" +``` + +### تكاملات MCP المتصلة + +اربط خوادم MCP من كتالوج CrewAI أو أحضر خوادمك الخاصة. بمجرد الاتصال في حسابك، أشر إليها بالمعرف المختصر: + +```python +# Connected MCP with all tools +"snowflake" + +# Specific tool from a connected MCP +"stripe#list_invoices" + +# Multiple connected MCPs +mcps=[ + "snowflake", + "stripe", + "github" +] +``` + +## مثال كامل + +إليك مثالاً كاملاً يستخدم خوادم MCP متعددة: + +```python +from crewai import Agent, Task, Crew, Process + +# Create agent with multiple MCP sources +multi_source_agent = Agent( + role="Multi-Source Research Analyst", + goal="Conduct comprehensive research using multiple data sources", + backstory="""Expert researcher with access to web search, weather data, + financial information, and academic research tools""", + mcps=[ + # External MCP servers + "https://mcp.exa.ai/mcp?api_key=your_exa_key&profile=research", + "https://weather.api.com/mcp#get_current_conditions", + + # Connected MCPs from catalog + "snowflake", + "stripe#list_invoices", + "github#search_repositories" + ] +) + +# Create comprehensive research task +research_task = Task( + description="""Research the impact of AI agents on business productivity. + Include current weather impacts on remote work, financial market trends, + and recent academic publications on AI agent frameworks.""", + expected_output="""Comprehensive report covering: + 1. AI agent business impact analysis + 2. Weather considerations for remote work + 3. Financial market trends related to AI + 4. Academic research citations and insights + 5. Competitive landscape analysis""", + agent=multi_source_agent +) + +# Create and execute crew +research_crew = Crew( + agents=[multi_source_agent], + tasks=[research_task], + process=Process.sequential, + verbose=True +) + +result = research_crew.kickoff() +print(f"Research completed with {len(multi_source_agent.mcps)} MCP data sources") +``` + +## تسمية الأدوات والتنظيم + +يتعامل CrewAI تلقائياً مع تسمية الأدوات لمنع التعارضات: + +```python +# Original MCP server has tools: "search", "analyze" +# CrewAI creates tools: "mcp_exa_ai_search", "mcp_exa_ai_analyze" + +agent = Agent( + role="Tool Organization Demo", + goal="Show how tool naming works", + backstory="Demonstrates automatic tool organization", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=key", # Tools: mcp_exa_ai_* + "https://weather.service.com/mcp", # Tools: weather_service_com_* + "snowflake" # Tools: snowflake_* + ] +) + +# Each server's tools get unique prefixes based on the server name +# This prevents naming conflicts between different MCP servers +``` + +## معالجة الأخطاء والمرونة + +صُمم MCP DSL ليكون متيناً وسهل الاستخدام: + +### التعامل الأنيق مع فشل الخادم + +```python +agent = Agent( + role="Resilient Researcher", + goal="Research despite server issues", + backstory="Experienced researcher who adapts to available tools", + mcps=[ + "https://primary-server.com/mcp", # Primary data source + "https://backup-server.com/mcp", # Backup if primary fails + "https://unreachable-server.com/mcp", # Will be skipped with warning + "snowflake" # Connected MCP from catalog + ] +) + +# Agent will: +# 1. Successfully connect to working servers +# 2. Log warnings for failing servers +# 3. Continue with available tools +# 4. Not crash or hang on server failures +``` + +### حماية المهلة الزمنية + +جميع عمليات MCP لها مهلات زمنية مدمجة: + +- **مهلة الاتصال**: 10 ثوانٍ +- **مهلة تنفيذ الأداة**: 30 ثانية +- **مهلة الاكتشاف**: 15 ثانية + +```python +# These servers will timeout gracefully if unresponsive +mcps=[ + "https://slow-server.com/mcp", # Will timeout after 10s if unresponsive + "https://overloaded-api.com/mcp" # Will timeout if discovery takes > 15s +] +``` + +## ميزات الأداء + +### التخزين المؤقت التلقائي + +تُخزن مخططات الأدوات مؤقتاً لمدة 5 دقائق لتحسين الأداء: + +```python +# First agent creation - discovers tools from server +agent1 = Agent(role="First", goal="Test", backstory="Test", + mcps=["https://api.example.com/mcp"]) + +# Second agent creation (within 5 minutes) - uses cached tool schemas +agent2 = Agent(role="Second", goal="Test", backstory="Test", + mcps=["https://api.example.com/mcp"]) # Much faster! +``` + +### الاتصالات حسب الطلب + +تُنشأ اتصالات الأدوات فقط عند استخدام الأدوات فعلياً: + +```python +# Agent creation is fast - no MCP connections made yet +agent = Agent( + role="On-Demand Agent", + goal="Use tools efficiently", + backstory="Efficient agent that connects only when needed", + mcps=["https://api.example.com/mcp"] +) + +# MCP connection is made only when a tool is actually executed +# This minimizes connection overhead and improves startup performance +``` + +## التكامل مع الميزات الموجودة + +تعمل أدوات MCP بسلاسة مع ميزات CrewAI الأخرى: + +```python +from crewai.tools import BaseTool + +class CustomTool(BaseTool): + name: str = "custom_analysis" + description: str = "Custom analysis tool" + + def _run(self, **kwargs): + return "Custom analysis result" + +agent = Agent( + role="Full-Featured Agent", + goal="Use all available tool types", + backstory="Agent with comprehensive tool access", + + # All tool types work together + tools=[CustomTool()], # Custom tools + apps=["gmail", "slack"], # Platform integrations + mcps=[ # MCP servers + "https://mcp.exa.ai/mcp?api_key=key", + "snowflake" + ], + + verbose=True, + max_iter=15 +) +``` + +## أفضل الممارسات + +### 1. استخدم أدوات محددة عند الإمكان + +```python +# Good - only get the tools you need +mcps=["https://weather.api.com/mcp#get_forecast"] + +# Less efficient - gets all tools from server +mcps=["https://weather.api.com/mcp"] +``` + +### 2. تعامل مع المصادقة بأمان + +```python +import os + +# Store API keys in environment variables +exa_key = os.getenv("EXA_API_KEY") +exa_profile = os.getenv("EXA_PROFILE") + +agent = Agent( + role="Secure Agent", + goal="Use MCP tools securely", + backstory="Security-conscious agent", + mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"] +) +``` + +### 3. خطط لفشل الخادم + +```python +# Always include backup options +mcps=[ + "https://primary-api.com/mcp", # Primary choice + "https://backup-api.com/mcp", # Backup option + "snowflake" # Connected MCP fallback +] +``` + +### 4. استخدم أدواراً وصفية للوكلاء + +```python +agent = Agent( + role="Weather-Enhanced Market Analyst", + goal="Analyze markets considering weather impacts", + backstory="Financial analyst with access to weather data for agricultural market insights", + mcps=[ + "https://weather.service.com/mcp#get_forecast", + "stripe#list_invoices" + ] +) +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**لم يتم اكتشاف أدوات:** + +```python +# Check your MCP server URL and authentication +# Verify the server is running and accessible +mcps=["https://mcp.example.com/mcp?api_key=valid_key"] +``` + +**انتهاء مهلة الاتصال:** + +```python +# Server may be slow or overloaded +# CrewAI will log warnings and continue with other servers +# Check server status or try backup servers +``` + +**فشل المصادقة:** + +```python +# Verify API keys and credentials +# Check server documentation for required parameters +# Ensure query parameters are properly URL encoded +``` + +## متقدم: MCPServerAdapter + +للسيناريوهات المعقدة التي تتطلب إدارة اتصال يدوية، استخدم فئة `MCPServerAdapter` من `crewai-tools`. استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به لأنه يتعامل تلقائياً مع بدء وإيقاف الاتصال بخادم MCP. diff --git a/docs/v1.15.1/ar/mcp/multiple-servers.mdx b/docs/v1.15.1/ar/mcp/multiple-servers.mdx new file mode 100644 index 000000000..14e2d4681 --- /dev/null +++ b/docs/v1.15.1/ar/mcp/multiple-servers.mdx @@ -0,0 +1,65 @@ +--- +title: الاتصال بخوادم MCP متعددة +description: تعلم كيفية استخدام MCPServerAdapter في CrewAI للاتصال بخوادم MCP متعددة بشكل متزامن وتجميع أدواتها. +icon: layer-group +mode: "wide" +--- + +## نظرة عامة + +يتيح لك `MCPServerAdapter` في `crewai-tools` الاتصال بخوادم MCP متعددة بشكل متزامن. هذا مفيد عندما يحتاج وكلاؤك للوصول إلى أدوات موزعة عبر خدمات أو بيئات مختلفة. يجمع المحول الأدوات من جميع الخوادم المحددة، مما يجعلها متاحة لوكلاء CrewAI. + +## الإعداد + +للاتصال بخوادم متعددة، توفر قائمة من قواميس معاملات الخادم لـ `MCPServerAdapter`. يجب أن يعرّف كل قاموس في القائمة معاملات خادم MCP واحد. + +تتضمن أنواع النقل المدعومة لكل خادم في القائمة `stdio` و `sse` و `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.") + +``` + +## إدارة الاتصال + +عند استخدام مدير السياق (تعليمة `with`)، يتعامل `MCPServerAdapter` مع دورة حياة جميع الاتصالات بخوادم MCP المُعدة (البدء والإيقاف). هذا يبسط إدارة الموارد ويضمن إغلاق جميع الاتصالات بشكل صحيح عند الخروج من السياق. diff --git a/docs/v1.15.1/ar/mcp/overview.mdx b/docs/v1.15.1/ar/mcp/overview.mdx new file mode 100644 index 000000000..ecb1204ee --- /dev/null +++ b/docs/v1.15.1/ar/mcp/overview.mdx @@ -0,0 +1,690 @@ +--- +title: "خوادم MCP كأدوات في CrewAI" +description: "تعلم كيفية دمج خوادم MCP كأدوات في وكلاء CrewAI باستخدام مكتبة `crewai-tools`." +icon: plug +mode: "wide" +--- + +## نظرة عامة + +يوفر [بروتوكول سياق النموذج](https://modelcontextprotocol.io/introduction) (MCP) طريقة موحدة لوكلاء الذكاء الاصطناعي لتوفير سياق لنماذج اللغة الكبيرة من خلال التواصل مع خدمات خارجية تُعرف بخوادم MCP. + +يقدم CrewAI **نهجين** لتكامل MCP: + +### تكامل DSL البسيط (الموصى به) + +استخدم حقل `mcps` مباشرة على الوكلاء لتكامل سلس مع أدوات MCP. يدعم DSL كلاً من **المراجع النصية** (للإعداد السريع) و**الإعدادات المنظمة** (للتحكم الكامل). + +#### المراجع النصية (إعداد سريع) + +مثالية لخوادم HTTPS البعيدة وتكاملات MCP المتصلة من كتالوج CrewAI: + +```python +from crewai import Agent + +agent = Agent( + role="Research Analyst", + goal="Research and analyze information", + backstory="Expert researcher with access to external tools", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key", # External MCP server + "https://api.weather.com/mcp#get_forecast", # Specific tool from server + "snowflake", # Connected MCP from catalog + "stripe#list_invoices" # Specific tool from connected MCP + ] +) +# MCP tools are now automatically available to your agent! +``` + +#### الإعدادات المنظمة (تحكم كامل) + +للتحكم الكامل في إعدادات الاتصال وتصفية الأدوات وجميع أنواع النقل: + +```python +from crewai import Agent +from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE +from crewai.mcp.filters import create_static_tool_filter + +agent = Agent( + role="Advanced Research Analyst", + goal="Research with full control over MCP connections", + backstory="Expert researcher with advanced tool access", + mcps=[ + # Stdio transport for local servers + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + env={"API_KEY": "your_key"}, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "list_directory"] + ), + cache_tools_list=True, + ), + # HTTP/Streamable HTTP transport for remote servers + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=True, + cache_tools_list=True, + ), + # SSE transport for real-time streaming + MCPServerSSE( + url="https://stream.example.com/mcp/sse", + headers={"Authorization": "Bearer your_token"}, + ), + ] +) +``` + +### متقدم: MCPServerAdapter (للسيناريوهات المعقدة) + +لحالات الاستخدام المتقدمة التي تتطلب إدارة اتصال يدوية، توفر مكتبة `crewai-tools` فئة `MCPServerAdapter`. + +ندعم حالياً آليات النقل التالية: + +- **Stdio**: للخوادم المحلية (التواصل عبر الإدخال/الإخراج القياسي بين العمليات على نفس الجهاز) +- **Server-Sent Events (SSE)**: للخوادم البعيدة (بث بيانات أحادي الاتجاه في الوقت الفعلي من الخادم إلى العميل عبر HTTP) +- **Streamable HTTPS**: للخوادم البعيدة (اتصال مرن، ربما ثنائي الاتجاه عبر HTTPS، يستخدم غالباً SSE للتدفقات من الخادم إلى العميل) + +## فيديو تعليمي + +شاهد هذا الفيديو التعليمي للحصول على دليل شامل حول تكامل MCP مع CrewAI: + + + +## التثبيت + +يتطلب تكامل CrewAI MCP مكتبة `mcp`: + +```shell +# For Simple DSL Integration (Recommended) +uv add mcp + +# For Advanced MCPServerAdapter usage +uv pip install 'crewai-tools[mcp]' +``` + +## البدء السريع: تكامل DSL البسيط + +أسهل طريقة لدمج خوادم MCP هي استخدام حقل `mcps` على وكلائك. يمكنك استخدام مراجع نصية أو إعدادات منظمة. + +### البدء السريع مع المراجع النصية + +```python +from crewai import Agent, Task, Crew + +# Create agent with MCP tools using string references +research_agent = Agent( + role="Research Analyst", + goal="Find and analyze information using advanced search tools", + backstory="Expert researcher with access to multiple data sources", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile", + "snowflake#run_query" + ] +) + +# Create task +research_task = Task( + description="Research the latest developments in AI agent frameworks", + expected_output="Comprehensive research report with citations", + agent=research_agent +) + +# Create and run crew +crew = Crew(agents=[research_agent], tasks=[research_task]) +result = crew.kickoff() +``` + +### البدء السريع مع الإعدادات المنظمة + +```python +from crewai import Agent, Task, Crew +from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE + +# Create agent with structured MCP configurations +research_agent = Agent( + role="Research Analyst", + goal="Find and analyze information using advanced search tools", + backstory="Expert researcher with access to multiple data sources", + mcps=[ + # Local stdio server + MCPServerStdio( + command="python", + args=["local_server.py"], + env={"API_KEY": "your_key"}, + ), + # Remote HTTP server + MCPServerHTTP( + url="https://api.research.com/mcp", + headers={"Authorization": "Bearer your_token"}, + ), + ] +) + +# Create task +research_task = Task( + description="Research the latest developments in AI agent frameworks", + expected_output="Comprehensive research report with citations", + agent=research_agent +) + +# Create and run crew +crew = Crew(agents=[research_agent], tasks=[research_task]) +result = crew.kickoff() +``` + +هذا كل شيء! يتم اكتشاف أدوات MCP تلقائياً وإتاحتها لوكيلك. + +## تنسيقات مراجع MCP + +يدعم حقل `mcps` كلاً من **المراجع النصية** (للإعداد السريع) و**الإعدادات المنظمة** (للتحكم الكامل). يمكنك مزج كلا التنسيقين في نفس القائمة. + +### المراجع النصية + +#### خوادم MCP الخارجية + +```python +mcps=[ + # Full server - get all available tools + "https://mcp.example.com/api", + + # Specific tool from server using # syntax + "https://api.weather.com/mcp#get_current_weather", + + # Server with authentication parameters + "https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" +] +``` + +#### تكاملات MCP المتصلة + +اربط خوادم MCP من كتالوج CrewAI أو أحضر خوادمك الخاصة. بمجرد الاتصال في حسابك، أشر إليها بالمعرف المختصر: + +```python +mcps=[ + # Connected MCP - get all available tools + "snowflake", + + # Specific tool from a connected MCP using # syntax + "stripe#list_invoices", + + # Multiple connected MCPs + "snowflake", + "stripe", + "github" +] +``` + +### الإعدادات المنظمة + +#### نقل Stdio (خوادم محلية) + +مثالي لخوادم MCP المحلية التي تعمل كعمليات: + +```python +from crewai.mcp import MCPServerStdio +from crewai.mcp.filters import create_static_tool_filter + +mcps=[ + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + env={"API_KEY": "your_key"}, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"] + ), + cache_tools_list=True, + ), + # Python-based server + MCPServerStdio( + command="python", + args=["path/to/server.py"], + env={"UV_PYTHON": "3.12", "API_KEY": "your_key"}, + ), +] +``` + +#### نقل HTTP/Streamable HTTP (خوادم بعيدة) + +لخوادم MCP البعيدة عبر HTTP/HTTPS: + +```python +from crewai.mcp import MCPServerHTTP + +mcps=[ + # Streamable HTTP (default) + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=True, + cache_tools_list=True, + ), + # Standard HTTP + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=False, + ), +] +``` + +#### نقل SSE (البث في الوقت الفعلي) + +للخوادم البعيدة التي تستخدم Server-Sent Events: + +```python +from crewai.mcp import MCPServerSSE + +mcps=[ + MCPServerSSE( + url="https://stream.example.com/mcp/sse", + headers={"Authorization": "Bearer your_token"}, + cache_tools_list=True, + ), +] +``` + +### مراجع مختلطة + +يمكنك دمج المراجع النصية والإعدادات المنظمة: + +```python +from crewai.mcp import MCPServerStdio, MCPServerHTTP + +mcps=[ + # String references + "https://external-api.com/mcp", # External server + "snowflake", # Connected MCP from catalog + + # Structured configurations + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + ), + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer token"}, + ), +] +``` + +### تصفية الأدوات + +تدعم الإعدادات المنظمة تصفية أدوات متقدمة: + +```python +from crewai.mcp import MCPServerStdio +from crewai.mcp.filters import create_static_tool_filter, create_dynamic_tool_filter, ToolFilterContext + +# Static filtering (allow/block lists) +static_filter = create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"], + blocked_tool_names=["delete_file"], +) + +# Dynamic filtering (context-aware) +def dynamic_filter(context: ToolFilterContext, tool: dict) -> bool: + # Block dangerous tools for certain agent roles + if context.agent.role == "Code Reviewer": + if "delete" in tool.get("name", "").lower(): + return False + return True + +mcps=[ + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + tool_filter=static_filter, # or dynamic_filter + ), +] +``` + +## معاملات الإعداد + +يدعم كل نوع نقل خيارات إعداد محددة: + +### معاملات MCPServerStdio + +- **`command`** (مطلوب): الأمر المراد تنفيذه (مثل `"python"` أو `"node"` أو `"npx"` أو `"uvx"`) +- **`args`** (اختياري): قائمة وسيطات الأمر (مثل `["server.py"]` أو `["-y", "@mcp/server"]`) +- **`env`** (اختياري): قاموس متغيرات البيئة لتمريرها إلى العملية +- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة +- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً لوصول أسرع لاحقاً (الافتراضي: `False`) + +### معاملات MCPServerHTTP + +- **`url`** (مطلوب): عنوان URL الخادم (مثل `"https://api.example.com/mcp"`) +- **`headers`** (اختياري): قاموس رؤوس HTTP للمصادقة أو أغراض أخرى +- **`streamable`** (اختياري): ما إذا كان يجب استخدام نقل HTTP القابل للبث (الافتراضي: `True`) +- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة +- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً (الافتراضي: `False`) + +### معاملات MCPServerSSE + +- **`url`** (مطلوب): عنوان URL الخادم (مثل `"https://api.example.com/mcp/sse"`) +- **`headers`** (اختياري): قاموس رؤوس HTTP للمصادقة أو أغراض أخرى +- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة +- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً (الافتراضي: `False`) + +### المعاملات المشتركة + +تدعم جميع أنواع النقل: + +- **`tool_filter`**: دالة تصفية للتحكم في الأدوات المتاحة. يمكن أن تكون: + - `None` (الافتراضي): جميع الأدوات متاحة + - تصفية ثابتة: تُنشأ باستخدام `create_static_tool_filter()` لقوائم السماح/الحظر + - تصفية ديناميكية: تُنشأ باستخدام `create_dynamic_tool_filter()` للتصفية الواعية بالسياق +- **`cache_tools_list`**: عند `True`، تخزن قائمة الأدوات مؤقتاً بعد أول اكتشاف لتحسين الأداء في الاتصالات اللاحقة + +## الميزات الرئيسية + +- **اكتشاف تلقائي للأدوات**: يتم اكتشاف الأدوات ودمجها تلقائياً +- **منع تعارض الأسماء**: تُضاف بادئات أسماء الخوادم لأسماء الأدوات +- **محسّن للأداء**: اتصالات حسب الطلب مع تخزين مؤقت للمخططات +- **مرونة في الأخطاء**: تعامل أنيق مع الخوادم غير المتاحة +- **حماية المهلة الزمنية**: مهلات زمنية مدمجة تمنع تعليق الاتصالات +- **تكامل شفاف**: يعمل بسلاسة مع ميزات CrewAI الموجودة +- **دعم نقل كامل**: أنواع نقل Stdio وHTTP/Streamable HTTP وSSE +- **تصفية متقدمة**: قدرات تصفية أدوات ثابتة وديناميكية +- **مصادقة مرنة**: دعم للرؤوس ومتغيرات البيئة ومعاملات الاستعلام + +## معالجة الأخطاء + +صُمم تكامل MCP DSL ليكون مرناً ويتعامل مع الفشل بأناقة: + +```python +from crewai import Agent +from crewai.mcp import MCPServerStdio, MCPServerHTTP + +agent = Agent( + role="Resilient Agent", + goal="Continue working despite server issues", + backstory="Agent that handles failures gracefully", + mcps=[ + # String references + "https://reliable-server.com/mcp", # Will work + "https://unreachable-server.com/mcp", # Will be skipped gracefully + "snowflake", # Connected MCP from catalog + + # Structured configs + MCPServerStdio( + command="python", + args=["reliable_server.py"], # Will work + ), + MCPServerHTTP( + url="https://slow-server.com/mcp", # Will timeout gracefully + ), + ] +) +# Agent will use tools from working servers and log warnings for failing ones +``` + +جميع أخطاء الاتصال تُعالج بأناقة: + +- **فشل الاتصال**: تُسجل كتحذيرات، ويستمر الوكيل مع الأدوات المتاحة +- **أخطاء المهلة الزمنية**: تنتهي الاتصالات بعد 30 ثانية (قابلة للتعديل) +- **أخطاء المصادقة**: تُسجل بوضوح للتصحيح +- **إعدادات غير صالحة**: تُرفع أخطاء التحقق عند إنشاء الوكيل + +## متقدم: MCPServerAdapter + +للسيناريوهات المعقدة التي تتطلب إدارة اتصال يدوية، استخدم فئة `MCPServerAdapter` من `crewai-tools`. استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به لأنه يتعامل تلقائياً مع بدء وإيقاف الاتصال بخادم MCP. + +## إعداد الاتصال + +يدعم `MCPServerAdapter` عدة خيارات إعداد لتخصيص سلوك الاتصال: + +- **`connect_timeout`** (اختياري): الحد الأقصى للوقت بالثواني لانتظار إنشاء اتصال بخادم MCP. القيمة الافتراضية 30 ثانية إذا لم تُحدد. هذا مفيد بشكل خاص للخوادم البعيدة التي قد يكون لها أوقات استجابة متغيرة. + +```python +# Example with custom connection timeout +with MCPServerAdapter(server_params, connect_timeout=60) as tools: + # Connection will timeout after 60 seconds if not established + pass +``` + +```python +from crewai import Agent +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # For Stdio Server + +# Example server_params (choose one based on your server type): +# 1. Stdio Server: +server_params=StdioServerParameters( + command="python3", + args=["servers/your_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +# 2. SSE Server: +server_params = { + "url": "http://localhost:8000/sse", + "transport": "sse" +} + +# 3. Streamable HTTP Server: +server_params = { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" +} + +# Example usage (uncomment and adapt once server_params is set): +with MCPServerAdapter(server_params, connect_timeout=60) 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, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +يوضح هذا النمط العام كيفية دمج الأدوات. للحصول على أمثلة محددة مصممة لكل نوع نقل، راجع الأدلة التفصيلية أدناه. + +## تصفية الأدوات + +هناك طريقتان لتصفية الأدوات: + +1. الوصول إلى أداة محددة باستخدام فهرسة نمط القاموس. +2. تمرير قائمة أسماء الأدوات إلى منشئ `MCPServerAdapter`. + +### الوصول إلى أداة محددة باستخدام فهرسة نمط القاموس. + +```python +with MCPServerAdapter(server_params, connect_timeout=60) 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"]], # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +### تمرير قائمة أسماء الأدوات إلى منشئ `MCPServerAdapter`. + +```python +with MCPServerAdapter(server_params, "tool_name", connect_timeout=60) 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, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +## الاستخدام مع CrewBase + +لاستخدام أدوات MCPServer ضمن فئة CrewBase، استخدم طريقة `get_mcp_tools`. يجب توفير إعدادات الخادم عبر خاصية `mcp_server_params`. يمكنك تمرير إعداد واحد أو قائمة من إعدادات خوادم متعددة. + +```python +@CrewBase +class CrewWithMCP: + # ... define your agents and tasks config file ... + + mcp_server_params = [ + # 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}, + ) + ] + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # get all available tools + + # ... rest of your crew setup ... +``` + + +عندما تكون فئة الطاقم مزينة بـ `@CrewBase`، تُدار دورة حياة المحول نيابة عنك: + +- أول استدعاء لـ `get_mcp_tools()` ينشئ بكسل `MCPServerAdapter` مشتركاً يُعاد استخدامه من قبل كل وكيل في الطاقم. +- يُغلق المحول تلقائياً بعد اكتمال `.kickoff()` بفضل خطاف ما بعد التشغيل الضمني المحقون من `@CrewBase`، لذا لا حاجة للتنظيف اليدوي. +- إذا لم يتم تعريف `mcp_server_params`، يُرجع `get_mcp_tools()` ببساطة قائمة فارغة، مما يسمح لنفس مسارات الكود بالعمل مع أو بدون إعداد MCP. + +هذا يجعل من الآمن استدعاء `get_mcp_tools()` من طرق وكلاء متعددة أو تفعيل MCP بشكل انتقائي لكل بيئة. + + +### إعداد مهلة الاتصال + +يمكنك إعداد مهلة الاتصال لخوادم MCP عن طريق تعيين خاصية فئة `mcp_connect_timeout`. إذا لم تُحدد مهلة، تكون القيمة الافتراضية 30 ثانية. + +```python +@CrewBase +class CrewWithMCP: + mcp_server_params = [...] + mcp_connect_timeout = 60 # 60 seconds timeout for all MCP connections + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +### تصفية الأدوات + +يمكنك تصفية الأدوات المتاحة لوكيلك عن طريق تمرير قائمة أسماء الأدوات إلى طريقة `get_mcp_tools`. + +```python +@agent +def another_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # get specific tools + ) +``` + +## استكشاف تكاملات MCP + + + + **الموصى به**: استخدم صياغة حقل `mcps=[]` البسيطة لتكامل MCP بلا جهد. + + + الاتصال بخوادم MCP المحلية عبر الإدخال/الإخراج القياسي. مثالي للنصوص البرمجية والملفات التنفيذية المحلية. + + + التكامل مع خوادم MCP البعيدة باستخدام Server-Sent Events لبث البيانات في الوقت الفعلي. + + + استخدام Streamable HTTP المرن للاتصال القوي مع خوادم MCP البعيدة. + + + تجميع الأدوات من عدة خوادم MCP بشكل متزامن باستخدام محول واحد. + + + مراجعة أفضل ممارسات الأمان المهمة لتكامل MCP للحفاظ على سلامة وكلائك. + + + +تحقق من هذا المستودع للحصول على عروض وأمثلة كاملة لتكامل MCP مع CrewAI! + + + CrewAI MCP Demo + + +## البقاء آمناً مع MCP + +تأكد دائماً من أنك تثق بخادم MCP قبل استخدامه. + +#### تحذير أمني: هجمات إعادة ربط DNS + +يمكن أن تكون عمليات نقل SSE عرضة لهجمات إعادة ربط DNS إذا لم تكن مؤمنة بشكل صحيح. +لمنع ذلك: + +1. **تحقق دائماً من رؤوس Origin** على اتصالات SSE الواردة للتأكد من أنها تأتي من مصادر متوقعة +2. **تجنب ربط الخوادم بجميع واجهات الشبكة** (0.0.0.0) عند التشغيل محلياً - اربط فقط بـ localhost (127.0.0.1) بدلاً من ذلك +3. **نفّذ مصادقة مناسبة** لجميع اتصالات SSE + +بدون هذه الحمايات، يمكن للمهاجمين استخدام إعادة ربط DNS للتفاعل مع خوادم MCP المحلية من مواقع ويب بعيدة. + +لمزيد من التفاصيل، راجع [وثائق أمان نقل MCP من Anthropic](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). + +### القيود + +- **الأوليات المدعومة**: حالياً، يدعم `MCPServerAdapter` بشكل أساسي تكييف `أدوات` MCP. + لا يتم دمج أوليات MCP الأخرى مثل `prompts` أو `resources` مباشرة كمكونات CrewAI من خلال هذا المحول في هذا الوقت. +- **معالجة المخرجات**: يعالج المحول عادةً المخرجات النصية الرئيسية من أداة MCP (مثل `.content[0].text`). قد تتطلب المخرجات المعقدة أو متعددة الوسائط معالجة مخصصة إذا لم تتناسب مع هذا النمط. diff --git a/docs/v1.15.1/ar/mcp/security.mdx b/docs/v1.15.1/ar/mcp/security.mdx new file mode 100644 index 000000000..e968ff9f5 --- /dev/null +++ b/docs/v1.15.1/ar/mcp/security.mdx @@ -0,0 +1,149 @@ +--- +title: اعتبارات أمان MCP +description: تعرف على أفضل ممارسات الأمان المهمة عند دمج خوادم MCP مع وكلاء CrewAI. +icon: lock +mode: "wide" +--- + +## نظرة عامة + + +الجانب الأكثر أهمية في أمان MCP هو **الثقة**. يجب أن تتصل فقط بخوادم MCP التي تثق بها **بالكامل**. + + +عند دمج خدمات خارجية مثل خوادم MCP (بروتوكول سياق النموذج) في وكلاء CrewAI، يكون الأمان أمراً بالغ الأهمية. +يمكن لخوادم MCP تنفيذ التعليمات البرمجية والوصول إلى البيانات أو التفاعل مع أنظمة أخرى بناءً على الأدوات التي تكشفها. +من الضروري فهم الآثار واتباع أفضل الممارسات لحماية تطبيقاتك وبياناتك. + +### المخاطر + +- تنفيذ تعليمات برمجية عشوائية على الجهاز الذي يعمل عليه الوكيل (خاصة مع نقل `Stdio` إذا كان الخادم يمكنه التحكم في الأمر المُنفذ). +- كشف بيانات حساسة من وكيلك أو بيئته. +- التلاعب بسلوك وكيلك بطرق غير مقصودة، بما في ذلك إجراء استدعاءات API غير مصرح بها نيابة عنك. +- اختطاف عملية استدلال وكيلك من خلال تقنيات حقن المطالبات المتطورة (انظر أدناه). + +### 1. الثقة بخوادم MCP + + +**اتصل فقط بخوادم MCP التي تثق بها.** + + +قبل إعداد `MCPServerAdapter` للاتصال بخادم MCP، تأكد من معرفة: +- **من يشغل الخادم؟** هل هو خدمة معروفة وذات سمعة جيدة، أم خادم داخلي تحت سيطرتك؟ +- **ما الأدوات التي يكشفها؟** افهم قدرات الأدوات. هل يمكن إساءة استخدامها إذا سيطر مهاجم أو إذا كان الخادم نفسه خبيثاً؟ +- **ما البيانات التي يصل إليها أو يعالجها؟** كن على دراية بأي معلومات حساسة قد تُرسل إلى خادم MCP أو يتعامل معها. + +تجنب الاتصال بخوادم MCP غير معروفة أو غير موثقة، خاصة إذا كان وكلاؤك يتعاملون مع مهام أو بيانات حساسة. + +### 2. حقن المطالبات الآمن عبر بيانات الأداة الوصفية: خطر "بروتوكول التحكم بالنموذج" + +خطر كبير وخفي هو إمكانية حقن المطالبات عبر البيانات الوصفية للأداة. إليك كيف يعمل: + +1. عندما يتصل وكيل CrewAI بخادم MCP، يطلب عادةً قائمة الأدوات المتاحة. +2. يستجيب خادم MCP ببيانات وصفية لكل أداة، بما في ذلك اسمها ووصفها وأوصاف معاملاتها. +3. يستخدم نموذج اللغة (LLM) الأساسي لوكيلك هذه البيانات الوصفية لفهم كيف ومتى يستخدم الأدوات. +4. يمكن لخادم MCP خبيث صياغة بياناته الوصفية للأدوات لتتضمن تعليمات مخفية أو صريحة تعمل كحقن مطالبات. + +**الأهم، يمكن أن يحدث هذا الهجوم بمجرد الاتصال بخادم خبيث وسرد أدواته، حتى لو لم يقرر وكيلك *استخدام* أي من تلك الأدوات.** مجرد التعرض للبيانات الوصفية الخبيثة يمكن أن يكون كافياً لاختراق سلوك الوكيل. + +**التخفيف:** + +* **الحذر الشديد مع الخوادم غير الموثوقة:** نكرر: *لا تتصل بخوادم MCP لا تثق بها بالكامل.* يجعل خطر حقن البيانات الوصفية هذا أمراً بالغ الأهمية. + +### أمان نقل Stdio + +عادةً ما يُستخدم نقل Stdio (الإدخال/الإخراج القياسي) لخوادم MCP المحلية التي تعمل على نفس الجهاز مثل تطبيق CrewAI. + +- **عزل العملية**: على الرغم من أنه أكثر أماناً بشكل عام لأنه لا يتضمن تعرض شبكي افتراضياً، تأكد من أن النص البرمجي أو الأمر الذي يُشغله `StdioServerParameters` من مصدر موثوق ولديه أذونات نظام ملفات مناسبة. +- **تنقية المدخلات**: إذا كان نص Stdio البرمجي يأخذ مدخلات معقدة مشتقة من تفاعلات الوكيل، تأكد من أن النص ينقي هذه المدخلات لمنع حقن الأوامر أو الثغرات الأخرى. +- **حدود الموارد**: كن على دراية بأن عملية خادم Stdio المحلية تستهلك موارد محلية (CPU، الذاكرة). تأكد من أنها تعمل بشكل جيد ولن تستنفد موارد النظام. + +### هجمات الوكيل المرتبك + +[مشكلة الوكيل المرتبك](https://en.wikipedia.org/wiki/Confused_deputy_problem) هي ثغرة أمنية كلاسيكية يمكن أن تظهر في تكاملات MCP، خاصة عندما يعمل خادم MCP كوسيط لخدمات طرف ثالث (مثل Google Calendar وGitHub) التي تستخدم OAuth 2.0 للترخيص. + +**السيناريو:** + +1. خادم MCP (نسميه `MCP-Proxy`) يسمح لوكيلك بالتفاعل مع `ThirdPartyAPI`. +2. يستخدم `MCP-Proxy` `client_id` ثابتاً واحداً خاصاً به عند التحدث مع خادم ترخيص `ThirdPartyAPI`. +3. أنت، كمستخدم، تصرح بشكل شرعي لـ `MCP-Proxy` بالوصول إلى `ThirdPartyAPI` نيابة عنك. +4. يصنع مهاجم رابطاً خبيثاً يبدأ تدفق OAuth مع `MCP-Proxy`، لكنه مصمم لخداع خادم ترخيص `ThirdPartyAPI`. +5. إذا نقرت على هذا الرابط، وشاهد خادم ترخيص `ThirdPartyAPI` ملف تعريف ارتباط الموافقة الموجود لـ `client_id` الخاص بـ `MCP-Proxy`، فقد *يتخطى* طلب موافقتك مرة أخرى. +6. قد يُخدع `MCP-Proxy` بعد ذلك لتمرير رمز ترخيص إلى المهاجم. + +**التخفيف (بشكل أساسي لمطوري خوادم MCP):** + +* يجب على خوادم MCP الوسيطة التي تستخدم معرفات عميل ثابتة للخدمات النهائية الحصول على **موافقة صريحة من المستخدم** لكل تطبيق عميل أو وكيل يتصل بها قبل بدء تدفق OAuth. + +**تداعيات مستخدم CrewAI:** + +* كن حذراً إذا أعاد خادم MCP توجيهك لمصادقات OAuth متعددة، خاصة إذا بدت غير متوقعة أو كانت الأذونات المطلوبة واسعة جداً. + +### أمان النقل البعيد (SSE و Streamable HTTP) + +عند الاتصال بخوادم MCP البعيدة عبر SSE أو Streamable HTTP، فإن ممارسات أمان الويب القياسية ضرورية. + +### اعتبارات أمان SSE + +### أ. هجمات إعادة ربط DNS (خاصة لـ SSE) + + +**احمِ ضد هجمات إعادة ربط DNS.** + + +تسمح إعادة ربط DNS لموقع ويب يتحكم فيه مهاجم بتجاوز سياسة نفس الأصل وإجراء طلبات لخوادم على شبكة المستخدم المحلية. + +**استراتيجيات التخفيف لمنفذي خوادم MCP:** +- **تحقق من رؤوس `Origin` و `Host`**: يجب على خوادم MCP (خاصة SSE) التحقق من رؤوس HTTP لضمان أن الطلبات تأتي من نطاقات/عملاء متوقعين. +- **اربط بـ `localhost` (127.0.0.1)**: عند تشغيل خوادم MCP محلياً للتطوير، اربطها بـ `127.0.0.1` بدلاً من `0.0.0.0`. +- **المصادقة**: اطلب مصادقة لجميع الاتصالات بخادم MCP. + +### ب. استخدم HTTPS + +- **تشفير البيانات أثناء النقل**: استخدم دائماً HTTPS لعناوين URL خوادم MCP البعيدة لتشفير الاتصال. + +### ج. تمرير الرمز (نمط مضاد) + +هذا يتعلق بشكل أساسي بمطوري خوادم MCP لكن فهمه يساعد في اختيار خوادم آمنة. + +"تمرير الرمز" هو عندما يقبل خادم MCP رمز وصول من وكيل CrewAI ويمرره ببساطة إلى API آخر بدون تحقق مناسب. + +**المخاطر:** +* يتجاوز ضوابط الأمان على خادم MCP أو API النهائي. +* يكسر مسارات التدقيق والمساءلة. +* يسمح بإساءة استخدام الرموز المسروقة. + +### د. التحقق من المدخلات وتنقيتها + +- **التحقق من المدخلات أمر بالغ الأهمية**: يجب على خوادم MCP التحقق بصرامة من جميع المدخلات المستلمة من الوكلاء *قبل* معالجتها أو تمريرها إلى الأدوات. هذا دفاع أساسي ضد العديد من الثغرات الشائعة: + - **حقن الأوامر:** إذا كانت أداة تبني أوامر shell أو استعلامات SQL بناءً على المدخلات، يجب على الخادم تنقية هذه المدخلات بدقة. + - **اجتياز المسار:** إذا وصلت أداة إلى ملفات بناءً على معاملات المدخلات، يجب على الخادم التحقق من هذه المسارات وتنقيتها. + - **فحوصات نوع البيانات والنطاق:** يجب أن تضمن الخوادم توافق البيانات مع الأنواع والنطاقات المتوقعة. + +### هـ. تحديد المعدل وإدارة الموارد + +- **منع الإساءة**: يجب أن تنفذ خوادم MCP تحديد المعدل لمنع الإساءة. +- **إعادة المحاولة من جانب العميل**: نفّذ منطق إعادة محاولة معقول في مهام CrewAI. + +## 4. نصائح لتنفيذ خادم MCP آمن (للمطورين) + +إذا كنت تطور خادم MCP قد تتصل به وكلاء CrewAI، ضع في الاعتبار أفضل الممارسات التالية: + +- **اتبع ممارسات البرمجة الآمنة**: التزم بمبادئ البرمجة الآمنة القياسية (مثل OWASP Top 10). +- **مبدأ الحد الأدنى من الصلاحيات**: تأكد من أن العملية التي تشغل خادم MCP لديها فقط الأذونات اللازمة. +- **إدارة الاعتماديات**: حافظ على تحديث جميع الاعتماديات لتصحيح الثغرات المعروفة. +- **الإعدادات الافتراضية الآمنة**: صمم خادمك وأدواته لتكون آمنة افتراضياً. +- **التحكم في الوصول للأدوات**: نفّذ آليات قوية للتحكم في الوكلاء أو المستخدمين المصرح لهم بالوصول إلى أدوات محددة. +- **معالجة أخطاء آمنة**: يجب ألا تكشف الخوادم رسائل خطأ داخلية مفصلة أو تتبعات المكدس للعميل. +- **التسجيل والمراقبة الشاملة**: نفّذ تسجيلاً مفصلاً للأحداث المتعلقة بالأمان. +- **الالتزام بمواصفات ترخيص MCP**: إذا كنت تنفذ المصادقة والترخيص، اتبع بدقة [مواصفات ترخيص MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization). +- **تدقيقات أمنية منتظمة**: إذا كان خادم MCP يتعامل مع بيانات حساسة، فكر في إجراء تدقيقات أمنية دورية. + +## 5. قراءة إضافية + +لمزيد من المعلومات التفصيلية حول أمان MCP، راجع التوثيق الرسمي: +- **[أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)** + +من خلال فهم اعتبارات الأمان هذه وتنفيذ أفضل الممارسات، يمكنك الاستفادة بأمان من قوة خوادم MCP في مشاريع CrewAI. +هذه ليست شاملة بأي حال، لكنها تغطي المخاوف الأمنية الأكثر شيوعاً وأهمية. +ستستمر التهديدات في التطور، لذا من المهم البقاء على اطلاع وتكييف إجراءات الأمان وفقاً لذلك. diff --git a/docs/v1.15.1/ar/mcp/sse.mdx b/docs/v1.15.1/ar/mcp/sse.mdx new file mode 100644 index 000000000..3e5e35246 --- /dev/null +++ b/docs/v1.15.1/ar/mcp/sse.mdx @@ -0,0 +1,151 @@ +--- +title: نقل SSE +description: تعلم كيفية ربط CrewAI بخوادم MCP البعيدة باستخدام Server-Sent Events (SSE) للاتصال في الوقت الفعلي. +icon: wifi +mode: "wide" +--- + +## نظرة عامة + +توفر Server-Sent Events (SSE) طريقة قياسية لخادم الويب لإرسال تحديثات إلى العميل عبر اتصال HTTP واحد طويل الأمد. في سياق MCP، تُستخدم SSE للخوادم البعيدة لبث البيانات (مثل استجابات الأدوات) إلى تطبيق CrewAI في الوقت الفعلي. + +## المفاهيم الرئيسية + +- **خوادم بعيدة**: SSE مناسب لخوادم MCP المستضافة عن بُعد. +- **بث أحادي الاتجاه**: عادةً ما يكون SSE قناة اتصال أحادية الاتجاه من الخادم إلى العميل. +- **إعداد `MCPServerAdapter`**: لـ SSE، ستوفر عنوان URL الخادم وتحدد نوع النقل. + +## الاتصال عبر SSE + +يمكنك الاتصال بخادم MCP المبني على SSE باستخدام نهجين رئيسيين لإدارة دورة حياة الاتصال: + +### 1. اتصال مُدار بالكامل (الموصى به) + +استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به. يتعامل تلقائياً مع إنشاء وإغلاق الاتصال بخادم 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.") + +``` + + +استبدل `"http://localhost:8000/sse"` بعنوان URL الفعلي لخادم MCP SSE الخاص بك. + + +### 2. دورة حياة اتصال يدوية + +إذا كنت بحاجة إلى تحكم أدق، يمكنك إدارة دورة حياة اتصال `MCPServerAdapter` يدوياً. + + +**يجب** عليك استدعاء `mcp_server_adapter.stop()` لضمان إغلاق الاتصال وتحرير الموارد. يُوصى بشدة باستخدام كتلة `try...finally`. + + +```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.") + +``` + +## اعتبارات أمان SSE + + +**هجمات إعادة ربط DNS**: يمكن أن تكون عمليات نقل SSE عرضة لهجمات إعادة ربط DNS إذا لم يكن خادم MCP مؤمناً بشكل صحيح. قد يسمح هذا لمواقع ويب خبيثة بالتفاعل مع خوادم MCP المحلية أو على الشبكة الداخلية. + + +للتخفيف من هذا الخطر: +- يجب أن تتحقق تطبيقات خادم MCP من **رؤوس `Origin`** على اتصالات SSE الواردة. +- عند تشغيل خوادم MCP SSE محلية للتطوير، **اربط فقط بـ `localhost` (`127.0.0.1`)** بدلاً من جميع واجهات الشبكة (`0.0.0.0`). +- نفّذ **مصادقة مناسبة** لجميع اتصالات SSE إذا كشفت أدوات أو بيانات حساسة. + +للحصول على نظرة شاملة على أفضل ممارسات الأمان، يرجى الرجوع إلى صفحة [اعتبارات الأمان](./security.mdx) ووثائق [أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) الرسمية. diff --git a/docs/v1.15.1/ar/mcp/stdio.mdx b/docs/v1.15.1/ar/mcp/stdio.mdx new file mode 100644 index 000000000..cf1b20e49 --- /dev/null +++ b/docs/v1.15.1/ar/mcp/stdio.mdx @@ -0,0 +1,134 @@ +--- +title: نقل Stdio +description: تعلم كيفية ربط CrewAI بخوادم MCP المحلية باستخدام آلية نقل Stdio (الإدخال/الإخراج القياسي). +icon: server +mode: "wide" +--- + +## نظرة عامة + +صُمم نقل Stdio (الإدخال/الإخراج القياسي) لربط `MCPServerAdapter` بخوادم MCP المحلية التي تتواصل عبر تدفقات الإدخال والإخراج القياسية. يُستخدم هذا عادةً عندما يكون خادم MCP نصاً برمجياً أو ملفاً تنفيذياً يعمل على نفس الجهاز مثل تطبيق CrewAI. + +## المفاهيم الرئيسية + +- **التنفيذ المحلي**: يدير نقل Stdio عملية تعمل محلياً لخادم MCP. +- **`StdioServerParameters`**: تُستخدم هذه الفئة من مكتبة `mcp` لإعداد الأمر والوسيطات ومتغيرات البيئة لتشغيل خادم Stdio. + +## الاتصال عبر Stdio + +يمكنك الاتصال بخادم MCP المبني على Stdio باستخدام نهجين رئيسيين لإدارة دورة حياة الاتصال: + +### 1. اتصال مُدار بالكامل (الموصى به) + +استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به. يتعامل تلقائياً مع بدء عملية خادم MCP وإيقافها عند الخروج من السياق. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +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]}") + + # Example: Using the tools from the Stdio MCP server in a CrewAI Agent + 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. دورة حياة اتصال يدوية + +إذا كنت بحاجة إلى تحكم أدق في وقت بدء وإيقاف عملية خادم MCP Stdio، يمكنك إدارة دورة حياة `MCPServerAdapter` يدوياً. + + +**يجب** عليك استدعاء `mcp_server_adapter.stop()` لضمان إنهاء عملية الخادم وتحرير الموارد. يُوصى بشدة باستخدام كتلة `try...finally`. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +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() # Manually start the connection and server process + tools = mcp_server_adapter.tools + print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}") + + # Example: Using the tools with your Agent, Task, Crew setup + 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() # Actual inputs depend on your tool + 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: # Check if connected before stopping + print("Stopping Stdio MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: # If adapter exists but not connected (e.g. start failed) + print("Stdio MCP server adapter was not connected. No stop needed or start failed.") + +``` + +تذكر استبدال المسارات والأوامر النائبة بتفاصيل خادم Stdio الفعلية. يمكن استخدام معامل `env` في `StdioServerParameters` لتعيين متغيرات البيئة لعملية الخادم، وهو مفيد لإعداد سلوكها أو توفير المسارات اللازمة (مثل `PYTHONPATH`). diff --git a/docs/v1.15.1/ar/mcp/streamable-http.mdx b/docs/v1.15.1/ar/mcp/streamable-http.mdx new file mode 100644 index 000000000..a4567ea74 --- /dev/null +++ b/docs/v1.15.1/ar/mcp/streamable-http.mdx @@ -0,0 +1,136 @@ +--- +title: نقل Streamable HTTP +description: تعلم كيفية ربط CrewAI بخوادم MCP البعيدة باستخدام نقل Streamable HTTP المرن. +icon: globe +mode: "wide" +--- + +## نظرة عامة + +يوفر نقل Streamable HTTP طريقة مرنة للاتصال بخوادم MCP البعيدة. يُبنى عادةً على HTTP ويمكنه دعم أنماط اتصال متنوعة، بما في ذلك الطلب والاستجابة والبث، وأحياناً يستخدم Server-Sent Events (SSE) لتدفقات من الخادم إلى العميل ضمن تفاعل HTTP أوسع. + +## المفاهيم الرئيسية + +- **خوادم بعيدة**: مصمم لخوادم MCP المستضافة عن بُعد. +- **المرونة**: يمكنه دعم أنماط تفاعل أكثر تعقيداً من SSE العادي، بما في ذلك الاتصال ثنائي الاتجاه المحتمل إذا نفذه الخادم. +- **إعداد `MCPServerAdapter`**: ستحتاج إلى توفير عنوان URL الأساسي للخادم للاتصال MCP وتحديد `"streamable-http"` كنوع النقل. + +## الاتصال عبر Streamable HTTP + +لديك طريقتان رئيسيتان لإدارة دورة حياة الاتصال مع خادم MCP Streamable HTTP: + +### 1. اتصال مُدار بالكامل (الموصى به) + +النهج الموصى به هو استخدام مدير سياق Python (تعليمة `with`)، الذي يتعامل مع إعداد الاتصال وإنهائه تلقائياً. + +```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.") + +``` +**ملاحظة:** استبدل `"http://localhost:8001/mcp"` بعنوان URL الفعلي لخادم MCP Streamable HTTP الخاص بك. + +### 2. دورة حياة اتصال يدوية + +للسيناريوهات التي تتطلب تحكماً أكثر صراحة، يمكنك إدارة اتصال `MCPServerAdapter` يدوياً. + + +من **الضروري** استدعاء `mcp_server_adapter.stop()` عند الانتهاء لإغلاق الاتصال وتحرير الموارد. كتلة `try...finally` هي الطريقة الأكثر أماناً لضمان ذلك. + + +```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.") +``` + +## اعتبارات الأمان + +عند استخدام نقل Streamable HTTP، فإن أفضل ممارسات أمان الويب العامة ضرورية: +- **استخدم HTTPS**: فضّل دائماً HTTPS لعناوين URL خوادم MCP لتشفير البيانات أثناء النقل. +- **المصادقة**: نفّذ آليات مصادقة قوية إذا كان خادم MCP يكشف أدوات أو بيانات حساسة. +- **التحقق من المدخلات**: تأكد من أن خادم MCP يتحقق من جميع الطلبات والمعاملات الواردة. + +للحصول على دليل شامل حول تأمين تكاملات MCP، يرجى الرجوع إلى صفحة [اعتبارات الأمان](./security.mdx) ووثائق [أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) الرسمية. diff --git a/docs/v1.15.1/ar/observability/arize-phoenix.mdx b/docs/v1.15.1/ar/observability/arize-phoenix.mdx new file mode 100644 index 000000000..239cced3e --- /dev/null +++ b/docs/v1.15.1/ar/observability/arize-phoenix.mdx @@ -0,0 +1,150 @@ +--- +title: Arize Phoenix +description: تكامل Arize Phoenix مع CrewAI باستخدام OpenTelemetry و OpenInference +icon: magnifying-glass-chart +mode: "wide" +--- + +# تكامل Arize Phoenix + +يوضح هذا الدليل كيفية دمج **Arize Phoenix** مع **CrewAI** باستخدام OpenTelemetry عبر حزمة [OpenInference](https://github.com/openinference/openinference) SDK. بنهاية هذا الدليل، ستتمكن من تتبع وكلاء CrewAI وتصحيح أخطاء وكلائك بسهولة. + +> **ما هو Arize Phoenix؟** [Arize Phoenix](https://phoenix.arize.com) هو منصة مراقبة LLM توفر التتبع والتقييم لتطبيقات الذكاء الاصطناعي. + +[![شاهد عرض فيديو لتكاملنا مع Phoenix](https://storage.googleapis.com/arize-assets/fixtures/setup_crewai.png)](https://www.youtube.com/watch?v=Yc5q3l6F7Ww) + +## البدء + +سنمر عبر مثال بسيط لاستخدام CrewAI ودمجه مع Arize Phoenix عبر OpenTelemetry باستخدام OpenInference. + +يمكنك أيضاً الوصول إلى هذا الدليل على [Google Colab](https://colab.research.google.com/github/Arize-ai/phoenix/blob/main/tutorials/tracing/crewai_tracing_tutorial.ipynb). + +### الخطوة 1: تثبيت الاعتماديات + +```bash +pip install openinference-instrumentation-crewai crewai crewai-tools arize-phoenix-otel +``` + +### الخطوة 2: إعداد متغيرات البيئة + +قم بإعداد مفاتيح API لـ Phoenix Cloud وإعداد OpenTelemetry لإرسال التتبعات إلى Phoenix. Phoenix Cloud هو إصدار مستضاف من Arize Phoenix، لكنه ليس مطلوباً لاستخدام هذا التكامل. + +يمكنك الحصول على مفتاح Serper API المجاني [هنا](https://serper.dev/). + +```python +import os +from getpass import getpass + +# Get your Phoenix Cloud credentials +PHOENIX_API_KEY = getpass("🔑 Enter your Phoenix Cloud API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") +SERPER_API_KEY = getpass("🔑 Enter your Serper API key: ") + +# Set environment variables +os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={PHOENIX_API_KEY}" +os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com" # Phoenix Cloud, change this to your own endpoint if you are using a self-hosted instance +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +os.environ["SERPER_API_KEY"] = SERPER_API_KEY +``` + +### الخطوة 3: تهيئة OpenTelemetry مع Phoenix + +قم بتهيئة OpenInference OpenTelemetry instrumentation SDK لبدء التقاط التتبعات وإرسالها إلى Phoenix. + +```python +from phoenix.otel import register + +tracer_provider = register( + project_name="crewai-tracing-demo", + auto_instrument=True, +) +``` + +### الخطوة 4: إنشاء تطبيق CrewAI + +سننشئ تطبيق CrewAI حيث يتعاون وكيلان للبحث وكتابة مقال مدونة حول تطورات الذكاء الاصطناعي. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool +from openinference.instrumentation.crewai import CrewAIInstrumentor +from phoenix.otel import register + +# setup monitoring for your crew +tracer_provider = register( + endpoint="http://localhost:6006/v1/traces") +CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider) +search_tool = SerperDevTool() + +# Define your agents with roles and goals +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, + 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, +) + +# Create tasks for your agents +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, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[researcher, writer], tasks=[task1, task2], verbose=1, process=Process.sequential +) + +# Get your crew to work! +result = crew.kickoff() + +print("######################") +print(result) +``` + +### الخطوة 5: عرض التتبعات في Phoenix + +بعد تشغيل الوكيل، يمكنك عرض التتبعات المولدة من تطبيق CrewAI في Phoenix. سترى خطوات مفصلة لتفاعلات الوكلاء واستدعاءات LLM، مما يساعدك في التصحيح والتحسين. + +سجل الدخول إلى حساب Phoenix Cloud الخاص بك وانتقل إلى المشروع الذي حددته في معامل `project_name`. سترى عرض زمني للتتبع مع جميع تفاعلات الوكلاء واستخدامات الأدوات واستدعاءات LLM. + +![مثال تتبع في Phoenix يوضح تفاعلات الوكلاء](https://storage.googleapis.com/arize-assets/fixtures/crewai_traces.png) + + +### معلومات التوافق +- Python 3.8+ +- CrewAI >= 0.86.0 +- Arize Phoenix >= 7.0.1 +- OpenTelemetry SDK >= 1.31.0 + + +### المراجع +- [وثائق Phoenix](https://docs.arize.com/phoenix/) - نظرة عامة على منصة Phoenix. +- [وثائق CrewAI](https://docs.crewai.com/) - نظرة عامة على إطار عمل CrewAI. +- [وثائق OpenTelemetry](https://opentelemetry.io/docs/) - دليل OpenTelemetry +- [OpenInference GitHub](https://github.com/openinference/openinference) - الكود المصدري لـ OpenInference SDK. diff --git a/docs/v1.15.1/ar/observability/braintrust.mdx b/docs/v1.15.1/ar/observability/braintrust.mdx new file mode 100644 index 000000000..7f52d9e92 --- /dev/null +++ b/docs/v1.15.1/ar/observability/braintrust.mdx @@ -0,0 +1,232 @@ +--- +title: Braintrust +description: تكامل Braintrust مع CrewAI باستخدام تتبع وتقييم OpenTelemetry +icon: magnifying-glass-chart +mode: "wide" +--- + +# تكامل Braintrust + +يوضح هذا الدليل كيفية دمج **Braintrust** مع **CrewAI** باستخدام OpenTelemetry للتتبع والتقييم الشامل. بنهاية هذا الدليل، ستتمكن من تتبع وكلاء CrewAI ومراقبة أدائهم وتقييم مخرجاتهم باستخدام منصة المراقبة القوية من Braintrust. + +> **ما هو Braintrust؟** [Braintrust](https://www.braintrust.dev) هو منصة تقييم ومراقبة للذكاء الاصطناعي توفر تتبعاً شاملاً وتقييماً ومراقبة لتطبيقات الذكاء الاصطناعي مع تتبع تجارب مدمج وتحليلات أداء. + +## البدء + +سنمر عبر مثال بسيط لاستخدام CrewAI ودمجه مع Braintrust عبر OpenTelemetry للمراقبة والتقييم الشامل. + +### الخطوة 1: تثبيت الاعتماديات + +```bash +uv add braintrust[otel] crewai crewai-tools opentelemetry-instrumentation-openai opentelemetry-instrumentation-crewai python-dotenv +``` + +### الخطوة 2: إعداد متغيرات البيئة + +قم بإعداد مفاتيح API لـ Braintrust وإعداد OpenTelemetry لإرسال التتبعات إلى Braintrust. ستحتاج إلى مفتاح API من Braintrust ومفتاح API من OpenAI. + +```python +import os +from getpass import getpass + +# Get your Braintrust credentials +BRAINTRUST_API_KEY = getpass("🔑 Enter your Braintrust API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") + +# Set environment variables +os.environ["BRAINTRUST_API_KEY"] = BRAINTRUST_API_KEY +os.environ["BRAINTRUST_PARENT"] = "project_name:crewai-demo" +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +``` + +### الخطوة 3: تهيئة OpenTelemetry مع Braintrust + +قم بتهيئة أداة Braintrust OpenTelemetry لبدء التقاط التتبعات وإرسالها إلى Braintrust. + +```python +import os +from typing import Any, Dict + +from braintrust.otel import BraintrustSpanProcessor +from crewai import Agent, Crew, Task +from crewai.llm import LLM +from opentelemetry import trace +from opentelemetry.instrumentation.crewai import CrewAIInstrumentor +from opentelemetry.instrumentation.openai import OpenAIInstrumentor +from opentelemetry.sdk.trace import TracerProvider + +def setup_tracing() -> None: + """Setup OpenTelemetry tracing with Braintrust.""" + current_provider = trace.get_tracer_provider() + if isinstance(current_provider, TracerProvider): + provider = current_provider + else: + provider = TracerProvider() + trace.set_tracer_provider(provider) + + provider.add_span_processor(BraintrustSpanProcessor()) + CrewAIInstrumentor().instrument(tracer_provider=provider) + OpenAIInstrumentor().instrument(tracer_provider=provider) + + +setup_tracing() +``` + +### الخطوة 4: إنشاء تطبيق CrewAI + +سننشئ تطبيق CrewAI حيث يتعاون وكيلان للبحث وكتابة مقال مدونة حول تطورات الذكاء الاصطناعي، مع تفعيل التتبع الشامل. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +def create_crew() -> Crew: + """Create a crew with multiple agents for comprehensive tracing.""" + llm = LLM(model="gpt-4o-mini") + search_tool = SerperDevTool() + + 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, + llm=llm, + 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, + llm=llm, + ) + + research_task = Task( + description="""Conduct a comprehensive analysis of the latest advancements in {topic}. + Identify key trends, breakthrough technologies, and potential industry impacts.""", + expected_output="Full analysis report in bullet points", + agent=researcher, + ) + + writing_task = Task( + description="""Using the insights provided, develop an engaging blog + post that highlights the most significant {topic} 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, + context=[research_task], + ) + + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential + ) + + return crew + +def run_crew(): + """Run the crew and return results.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": "AI developments"}) + return result + +if __name__ == "__main__": + result = run_crew() + print(result) +``` + +### الخطوة 5: عرض التتبعات في Braintrust + +بعد تشغيل طاقمك، يمكنك عرض تتبعات شاملة في Braintrust من خلال وجهات نظر مختلفة: + + + + + عرض تتبع Braintrust + + + + + + عرض الجدول الزمني Braintrust + + + + + + عرض المحادثة Braintrust + + + + +### الخطوة 6: التقييم عبر SDK (التجارب) + +يمكنك أيضاً تشغيل التقييمات باستخدام Braintrust Eval SDK. هذا مفيد لمقارنة الإصدارات أو تسجيل المخرجات. فيما يلي مثال Python باستخدام فئة `Eval`: + +```python +# eval_crew.py +from braintrust import Eval +from autoevals import Levenshtein + +def evaluate_crew_task(input_data): + """Task function that wraps our crew for evaluation.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": input_data["topic"]}) + return str(result) + +Eval( + "AI Research Crew", + { + "data": lambda: [ + {"topic": "artificial intelligence trends 2024"}, + {"topic": "machine learning breakthroughs"}, + {"topic": "AI ethics and governance"}, + ], + "task": evaluate_crew_task, + "scores": [Levenshtein], + }, +) +``` + +قم بإعداد مفتاح API الخاص بك وشغّل: + +```bash +export BRAINTRUST_API_KEY="YOUR_API_KEY" +braintrust eval eval_crew.py +``` + +راجع [دليل Braintrust Eval SDK](https://www.braintrust.dev/docs/start/eval-sdk) لمزيد من التفاصيل. + +### الميزات الرئيسية لتكامل Braintrust + +- **تتبع شامل**: تتبع جميع تفاعلات الوكلاء واستخدام الأدوات واستدعاءات LLM +- **مراقبة الأداء**: مراقبة أوقات التنفيذ واستخدام الرموز ومعدلات النجاح +- **تتبع التجارب**: مقارنة إعدادات الطاقم والنماذج المختلفة +- **التقييم الآلي**: إعداد مقاييس تقييم مخصصة لمخرجات الطاقم +- **تتبع الأخطاء**: مراقبة وتصحيح حالات الفشل عبر عمليات تنفيذ الطاقم +- **تحليل التكاليف**: تتبع استخدام الرموز والتكاليف المرتبطة + +### معلومات التوافق +- Python 3.8+ +- CrewAI >= 0.86.0 +- Braintrust >= 0.1.0 +- OpenTelemetry SDK >= 1.31.0 + +### المراجع +- [وثائق Braintrust](https://www.braintrust.dev/docs) - نظرة عامة على منصة Braintrust +- [تكامل Braintrust CrewAI](https://www.braintrust.dev/docs/integrations/crew-ai) - دليل التكامل الرسمي مع CrewAI +- [Braintrust Eval SDK](https://www.braintrust.dev/docs/start/eval-sdk) - تشغيل التجارب عبر SDK +- [وثائق CrewAI](https://docs.crewai.com/) - نظرة عامة على إطار عمل CrewAI +- [وثائق OpenTelemetry](https://opentelemetry.io/docs/) - دليل OpenTelemetry +- [Braintrust GitHub](https://github.com/braintrustdata/braintrust) - الكود المصدري لـ Braintrust SDK diff --git a/docs/v1.15.1/ar/observability/datadog.mdx b/docs/v1.15.1/ar/observability/datadog.mdx new file mode 100644 index 000000000..0d6ebebe9 --- /dev/null +++ b/docs/v1.15.1/ar/observability/datadog.mdx @@ -0,0 +1,109 @@ +--- +title: تكامل Datadog +description: تعلم كيفية دمج Datadog مع CrewAI لإرسال تتبعات مراقبة LLM إلى Datadog. +icon: dog +mode: "wide" +--- + +# دمج Datadog مع CrewAI + +سيوضح هذا الدليل كيفية دمج **[Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/)** مع **CrewAI** باستخدام [أداة Datadog للتجهيز التلقائي](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python). بنهاية هذا الدليل، ستتمكن من إرسال تتبعات مراقبة LLM إلى Datadog وعرض تشغيلات وكلاء CrewAI في [عرض التنفيذ الوكيلي](https://docs.datadoghq.com/llm_observability/monitoring/agent_monitoring) من Datadog LLM Observability. + +## ما هو Datadog LLM Observability؟ + +[Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) يساعد مهندسي الذكاء الاصطناعي وعلماء البيانات ومطوري التطبيقات على تطوير وتقييم ومراقبة تطبيقات LLM بسرعة. حسّن جودة المخرجات والأداء والتكاليف والمخاطر الإجمالية بثقة مع تجارب منظمة وتتبع شامل عبر وكلاء الذكاء الاصطناعي والتقييمات. + +## البدء + +### تثبيت الاعتماديات + +```shell +pip install ddtrace crewai crewai-tools +``` + +### تعيين متغيرات البيئة + +إذا لم يكن لديك مفتاح API من Datadog، يمكنك [إنشاء حساب](https://www.datadoghq.com/) و[الحصول على مفتاح API](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + +ستحتاج أيضاً إلى تحديد اسم تطبيق ML في متغيرات البيئة التالية. تطبيق ML هو تجميع لتتبعات LLM Observability المرتبطة بتطبيق محدد قائم على LLM. + +```shell +export DD_API_KEY= +export DD_SITE= +export DD_LLMOBS_ENABLED=true +export DD_LLMOBS_ML_APP= +export DD_LLMOBS_AGENTLESS_ENABLED=true +export DD_APM_TRACING_ENABLED=false +``` + +بالإضافة إلى ذلك، قم بإعداد مفاتيح API لمزودي LLM + +```shell +export OPENAI_API_KEY= +export ANTHROPIC_API_KEY= +export GEMINI_API_KEY= +... +``` + +### إنشاء تطبيق وكيل CrewAI + +```python +# crewai_agent.py +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], +) + +task = Task( + description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer +) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) + +output = crew.kickoff(dict(multiplication="2 * 2")) +``` + +### تشغيل التطبيق مع التجهيز التلقائي من Datadog + +مع تعيين [متغيرات البيئة](#تعيين-متغيرات-البيئة)، يمكنك الآن تشغيل التطبيق مع التجهيز التلقائي من Datadog. + +```shell +ddtrace-run python crewai_agent.py +``` + +### عرض التتبعات في Datadog + +بعد تشغيل التطبيق، يمكنك عرض التتبعات في [عرض تتبعات Datadog LLM Observability](https://app.datadoghq.com/llm/traces)، باختيار اسم تطبيق ML الذي اخترته من القائمة المنسدلة أعلى اليسار. + +النقر على تتبع سيعرض لك تفاصيل التتبع، بما في ذلك إجمالي الرموز المستخدمة وعدد استدعاءات LLM والنماذج المستخدمة والتكلفة المقدرة. + + +عرض تتبع Datadog LLM Observability + + +بالإضافة إلى ذلك، يمكنك عرض رسم بياني لتنفيذ التتبع، الذي يوضح تدفق التحكم والبيانات للتتبع. + + +عرض تدفق تنفيذ وكيل Datadog LLM Observability + + +## المراجع + +- [Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) +- [التجهيز التلقائي لـ CrewAI من Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python#crew-ai) diff --git a/docs/v1.15.1/ar/observability/galileo.mdx b/docs/v1.15.1/ar/observability/galileo.mdx new file mode 100644 index 000000000..9c51f2306 --- /dev/null +++ b/docs/v1.15.1/ar/observability/galileo.mdx @@ -0,0 +1,86 @@ +--- +title: Galileo +description: تكامل Galileo مع CrewAI للتتبع والتقييم +icon: telescope +mode: "wide" +--- + +## نظرة عامة + +يوضح هذا الدليل كيفية دمج **Galileo** مع **CrewAI** للتتبع الشامل وهندسة التقييم. بنهاية هذا الدليل، ستتمكن من تتبع وكلاء CrewAI ومراقبة أدائهم وتقييم سلوكهم باستخدام منصة المراقبة القوية من Galileo. + +> **ما هو Galileo؟** [Galileo](https://galileo.ai) هو منصة تقييم ومراقبة للذكاء الاصطناعي توفر تتبعاً شاملاً وتقييماً ومراقبة لتطبيقات الذكاء الاصطناعي. تمكّن الفرق من التقاط البيانات الحقيقية وإنشاء حواجز قوية وتشغيل تجارب منهجية مع تتبع تجارب مدمج وتحليلات أداء. + +## البدء + +يتبع هذا البرنامج التعليمي [البدء السريع مع CrewAI](/ar/quickstart) ويوضح كيفية إضافة [CrewAIEventListener](https://v2docs.galileo.ai/sdk-api/python/reference/handlers/crewai/handler) من Galileo كمعالج أحداث. + +> **ملاحظة** يفترض هذا البرنامج التعليمي أنك أكملت [البدء السريع مع CrewAI](/ar/quickstart). + +### الخطوة 1: تثبيت الاعتماديات + +ثبّت الاعتماديات المطلوبة لتطبيقك: + +```bash +uv add galileo +``` + +### الخطوة 2: أضف إلى ملف .env من [البدء السريع مع CrewAI](/ar/quickstart) + +```bash +# Your Galileo API key +GALILEO_API_KEY="your-galileo-api-key" + +# Your Galileo project name +GALILEO_PROJECT="your-galileo-project-name" + +# The name of the Log stream you want to use for logging +GALILEO_LOG_STREAM="your-galileo-log-stream " +``` + +### الخطوة 3: إضافة مستمع أحداث Galileo + +لتفعيل التسجيل مع Galileo، تحتاج إلى إنشاء مثيل من `CrewAIEventListener`. استورد حزمة معالج CrewAI من Galileo بإضافة الكود التالي في أعلى ملف main.py: + +```python +from galileo.handlers.crewai.handler import CrewAIEventListener +``` + +في بداية دالة التشغيل، أنشئ مستمع الأحداث: + +```python +def run(): + # Create the event listener + CrewAIEventListener() + # The rest of your existing code goes here +``` + +عند إنشاء مثيل المستمع، يتم تسجيله تلقائياً مع CrewAI. + +### الخطوة 4: شغّل طاقمك + +شغّل طاقمك باستخدام CrewAI CLI: + +```bash +crewai run +``` + +### الخطوة 5: عرض التتبعات في Galileo + +بمجرد انتهاء طاقمك، سيتم تفريغ التتبعات وستظهر في Galileo. + +![عرض تتبع Galileo](/images/galileo-trace-veiw.png) + +## فهم تكامل Galileo + +يتكامل Galileo مع CrewAI عن طريق تسجيل مستمع أحداث يلتقط أحداث تنفيذ الطاقم (مثل إجراءات الوكلاء واستدعاءات الأدوات واستجابات النماذج) ويعيد توجيهها إلى Galileo للمراقبة والتقييم. + +### فهم مستمع الأحداث + +إنشاء مثيل `CrewAIEventListener()` هو كل ما يلزم لتفعيل Galileo لتشغيل CrewAI. عند الإنشاء، يقوم المستمع بـ: + +- التسجيل تلقائياً مع CrewAI +- قراءة إعدادات Galileo من متغيرات البيئة +- تسجيل جميع بيانات التشغيل في مشروع Galileo وتدفق السجل المحدد بواسطة `GALILEO_PROJECT` و `GALILEO_LOG_STREAM` + +لا يلزم أي إعداد إضافي أو تغييرات في الكود. diff --git a/docs/v1.15.1/ar/observability/langdb.mdx b/docs/v1.15.1/ar/observability/langdb.mdx new file mode 100644 index 000000000..42726faaa --- /dev/null +++ b/docs/v1.15.1/ar/observability/langdb.mdx @@ -0,0 +1,167 @@ +--- +title: تكامل LangDB +description: إدارة وتأمين وتحسين سير عمل CrewAI مع بوابة LangDB AI — الوصول إلى أكثر من 350 نموذجاً وتوجيه تلقائي وتحسين التكاليف ومراقبة كاملة. +icon: database +mode: "wide" +--- + +# مقدمة + +توفر [بوابة LangDB AI](https://langdb.ai) واجهات API متوافقة مع OpenAI للاتصال بنماذج لغة كبيرة متعددة وتعمل كمنصة مراقبة تجعل تتبع سير عمل CrewAI شاملاً وسهلاً مع توفير الوصول إلى أكثر من 350 نموذج لغة. مع استدعاء `init()` واحد، يتم التقاط جميع تفاعلات الوكلاء وتنفيذ المهام واستدعاءات LLM، مما يوفر مراقبة شاملة وبنية تحتية جاهزة للإنتاج لتطبيقاتك. + + + مثال تتبع LangDB CrewAI + + +**تحقق من:** [عرض مثال التتبع المباشر](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22) + +## الميزات + +### قدرات بوابة AI +- **الوصول إلى أكثر من 350 LLM**: الاتصال بجميع نماذج اللغة الرئيسية من خلال تكامل واحد +- **النماذج الافتراضية**: إنشاء إعدادات نماذج مخصصة مع معاملات وقواعد توجيه محددة +- **MCP الافتراضي**: تفعيل التوافق والتكامل مع أنظمة MCP لتعزيز اتصال الوكلاء +- **حواجز الحماية**: تنفيذ تدابير السلامة وضوابط الامتثال لسلوك الوكلاء + +### المراقبة والتتبع +- **تتبع تلقائي**: استدعاء `init()` واحد يلتقط جميع تفاعلات CrewAI +- **رؤية شاملة**: مراقبة سير عمل الوكلاء من البداية إلى النهاية +- **تتبع استخدام الأدوات**: تتبع الأدوات التي يستخدمها الوكلاء ونتائجها +- **مراقبة استدعاءات النماذج**: رؤى مفصلة لتفاعلات LLM +- **تحليلات الأداء**: مراقبة زمن الاستجابة واستخدام الرموز والتكاليف +- **دعم التصحيح**: تنفيذ خطوة بخطوة لاستكشاف الأخطاء +- **المراقبة في الوقت الفعلي**: لوحة معلومات التتبعات والمقاييس الحية + +## تعليمات الإعداد + + + + ثبّت عميل LangDB مع علامة ميزة CrewAI: + ```bash + pip install 'pylangdb[crewai]' + ``` + + + قم بإعداد بيانات اعتماد LangDB: + ```bash + export LANGDB_API_KEY="" + export LANGDB_PROJECT_ID="" + export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + ``` + + + استورد وهيّئ LangDB قبل إعداد كود CrewAI: + ```python + from pylangdb.crewai import init + # Initialize LangDB + init() + ``` + + + قم بإعداد LLM مع رؤوس LangDB: + ```python + from crewai import Agent, Task, Crew, LLM + import os + + # Configure LLM with LangDB headers + llm = LLM( + model="openai/gpt-4o", + api_key=os.getenv("LANGDB_API_KEY"), + base_url=os.getenv("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.getenv("LANGDB_PROJECT_ID")} + ) + ``` + + + +## مثال سريع للبدء + +```python +import os +from pylangdb.crewai import init +from crewai import Agent, Task, Crew, LLM + +init() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +researcher = Agent( + role="Research Specialist", + goal="Research topics thoroughly", + backstory="Expert researcher with skills in finding information", + llm=create_llm("openai/gpt-4o"), + verbose=True +) + +task = Task( + description="Research the given topic and provide a comprehensive summary", + agent=researcher, + expected_output="Detailed research summary with key findings" +) + +crew = Crew(agents=[researcher], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## عرض التتبعات في LangDB + +بعد تشغيل تطبيق CrewAI، يمكنك عرض تتبعات مفصلة في لوحة معلومات LangDB: + + + لوحة معلومات تتبع LangDB تعرض سير عمل CrewAI + + +### ما ستراه + +- **تفاعلات الوكلاء**: التدفق الكامل لمحادثات الوكلاء وتسليم المهام +- **استخدام الأدوات**: الأدوات التي تم استدعاؤها ومدخلاتها ومخرجاتها +- **استدعاءات النماذج**: تفاعلات LLM المفصلة مع المطالبات والاستجابات +- **مقاييس الأداء**: تتبع زمن الاستجابة واستخدام الرموز والتكاليف +- **الجدول الزمني للتنفيذ**: عرض خطوة بخطوة لسير العمل بالكامل + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +- **عدم ظهور تتبعات**: تأكد من استدعاء `init()` قبل أي استيرادات CrewAI +- **أخطاء المصادقة**: تحقق من مفتاح API ومعرف المشروع في LangDB + +## الموارد + + + + الوثائق والأدلة الرسمية لـ LangDB + + + برامج تعليمية خطوة بخطوة لبناء وكلاء AI + + + أمثلة تكامل CrewAI الكاملة + + + الوصول إلى تتبعاتك وتحليلاتك + + + تصفح أكثر من 350 نموذج لغة متاح + + + خيارات الاستضافة الذاتية وقدرات المؤسسات + + + +## الخطوات التالية + +غطى هذا الدليل أساسيات دمج بوابة LangDB AI مع CrewAI. لتعزيز سير عمل الذكاء الاصطناعي بشكل أكبر، استكشف: + +- **النماذج الافتراضية**: إنشاء إعدادات نماذج مخصصة مع استراتيجيات توجيه +- **حواجز الحماية والسلامة**: تنفيذ تصفية المحتوى وضوابط الامتثال +- **النشر في الإنتاج**: إعداد خطط احتياطية وإعادة المحاولة وتوازن الأحمال + +لمزيد من الميزات المتقدمة وحالات الاستخدام، زُر [وثائق LangDB](https://docs.langdb.ai) أو استكشف [كتالوج النماذج](https://app.langdb.ai/models) لاكتشاف جميع النماذج المتاحة. diff --git a/docs/v1.15.1/ar/observability/langfuse.mdx b/docs/v1.15.1/ar/observability/langfuse.mdx new file mode 100644 index 000000000..e62d2e657 --- /dev/null +++ b/docs/v1.15.1/ar/observability/langfuse.mdx @@ -0,0 +1,109 @@ +--- +title: تكامل Langfuse +description: تعلم كيفية دمج Langfuse مع CrewAI عبر OpenTelemetry باستخدام OpenLit +icon: vials +mode: "wide" +--- + +# دمج Langfuse مع CrewAI + +يوضح هذا الدفتر كيفية دمج **Langfuse** مع **CrewAI** باستخدام OpenTelemetry عبر حزمة **OpenLit** SDK. بنهاية هذا الدفتر، ستتمكن من تتبع تطبيقات CrewAI مع Langfuse لتحسين المراقبة والتصحيح. + +> **ما هو Langfuse؟** [Langfuse](https://langfuse.com) هو منصة هندسة LLM مفتوحة المصدر. توفر قدرات التتبع والمراقبة لتطبيقات LLM، مما يساعد المطورين على التصحيح والتحليل والتحسين. يتكامل Langfuse مع أدوات وأطر عمل متنوعة عبر تكاملات أصلية وOpenTelemetry وواجهات API/SDKs. + +[![فيديو نظرة عامة على Langfuse](https://github.com/user-attachments/assets/3926b288-ff61-4b95-8aa1-45d041c70866)](https://langfuse.com/watch-demo) + +## البدء + +سنمر عبر مثال بسيط لاستخدام CrewAI ودمجه مع Langfuse عبر OpenTelemetry باستخدام OpenLit. + +### الخطوة 1: تثبيت الاعتماديات + +```python +%pip install langfuse openlit crewai crewai_tools +``` + +### الخطوة 2: إعداد متغيرات البيئة + +عيّن مفاتيح API لـ Langfuse وإعدادات تصدير OpenTelemetry لإرسال التتبعات إلى Langfuse. يرجى الرجوع إلى [وثائق Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) لمزيد من المعلومات. + +```python +import os + +# Get keys for your project from the project settings page: 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" # 🇪🇺 EU region +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region + + +# Your OpenAI key +os.environ["OPENAI_API_KEY"] = "sk-proj-..." +``` + +مع تعيين متغيرات البيئة، يمكننا الآن تهيئة عميل Langfuse. تهيئ `get_client()` عميل Langfuse باستخدام بيانات الاعتماد المقدمة في متغيرات البيئة. + +```python +from langfuse import get_client + +langfuse = get_client() + +# Verify connection +if langfuse.auth_check(): + print("Langfuse client is authenticated and ready!") +else: + print("Authentication failed. Please check your credentials and host.") +``` + +### الخطوة 3: تهيئة OpenLit + +قم بتهيئة OpenLit OpenTelemetry instrumentation SDK لبدء التقاط تتبعات OpenTelemetry. + +```python +import openlit + +openlit.init() +``` + +### الخطوة 4: إنشاء تطبيق CrewAI بسيط + +سننشئ تطبيق CrewAI بسيط حيث يتعاون عدة وكلاء للإجابة على سؤال المستخدم. + +```python +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], + ) + +task = Task(description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) +``` + +### الخطوة 5: عرض التتبعات في Langfuse + +بعد تشغيل الوكيل، يمكنك عرض التتبعات المولدة من تطبيق CrewAI في [Langfuse](https://cloud.langfuse.com). سترى خطوات مفصلة لتفاعلات LLM، مما يساعدك في التصحيح والتحسين. + +![مثال تتبع CrewAI في Langfuse](https://langfuse.com/images/cookbook/integration_crewai/crewai-example-trace.png) + +_[مثال تتبع عام في Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/e2cf380ffc8d47d28da98f136140642b?timestamp=2025-02-05T15%3A12%3A02.717Z&observation=3b32338ee6a5d9af)_ + +## المراجع + +- [وثائق Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) diff --git a/docs/v1.15.1/ar/observability/langtrace.mdx b/docs/v1.15.1/ar/observability/langtrace.mdx new file mode 100644 index 000000000..d07f3f35e --- /dev/null +++ b/docs/v1.15.1/ar/observability/langtrace.mdx @@ -0,0 +1,73 @@ +--- +title: تكامل Langtrace +description: كيفية مراقبة التكلفة وزمن الاستجابة وأداء وكلاء CrewAI باستخدام Langtrace، أداة مراقبة خارجية. +icon: chart-line +mode: "wide" +--- + +# نظرة عامة على Langtrace + +Langtrace هو أداة مفتوحة المصدر خارجية تساعدك في إعداد المراقبة والتقييمات لنماذج اللغة الكبيرة (LLMs) وأطر عمل LLM وقواعد بيانات المتجهات. +على الرغم من أنها ليست مبنية مباشرة في CrewAI، يمكن استخدام Langtrace جنباً إلى جنب مع CrewAI للحصول على رؤية عميقة في التكلفة وزمن الاستجابة وأداء وكلاء CrewAI. +يتيح لك هذا التكامل تسجيل المعاملات الفائقة ومراقبة تراجعات الأداء وإنشاء عملية للتحسين المستمر لوكلائك. + +![نظرة عامة على سلسلة مختارة من جلسات تشغيل الوكلاء](/images/langtrace1.png) +![نظرة عامة على تتبعات الوكلاء](/images/langtrace2.png) +![نظرة عامة على تتبعات LLM بالتفصيل](/images/langtrace3.png) + +## تعليمات الإعداد + + + + سجّل بزيارة [https://langtrace.ai/signup](https://langtrace.ai/signup). + + + عيّن نوع المشروع إلى `CrewAI` وقم بتوليد مفتاح API. + + + استخدم الأمر التالي: + + ```bash + pip install langtrace-python-sdk + ``` + + + استورد وهيّئ Langtrace في بداية نصك البرمجي، قبل أي استيرادات CrewAI: + + ```python + from langtrace_python_sdk import langtrace + langtrace.init(api_key='') + + # Now import CrewAI modules + from crewai import Agent, Task, Crew + ``` + + + +### الميزات وتطبيقاتها على CrewAI + +1. **تتبع رموز LLM والتكاليف** + + - مراقبة استخدام الرموز والتكاليف المرتبطة لكل تفاعل وكيل CrewAI. + +2. **رسم بياني للتتبع لخطوات التنفيذ** + + - تصور تدفق تنفيذ مهام CrewAI، بما في ذلك زمن الاستجابة والسجلات. + - مفيد لتحديد الاختناقات في سير عمل الوكلاء. + +3. **تنظيم مجموعات البيانات مع التعليق اليدوي** + + - إنشاء مجموعات بيانات من مخرجات مهام CrewAI للتدريب أو التقييم المستقبلي. + +4. **إدارة إصدارات المطالبات** + + - تتبع الإصدارات المختلفة من المطالبات المستخدمة في وكلاء CrewAI. + - مفيد لاختبار A/B وتحسين أداء الوكلاء. + +5. **ساحة المطالبات مع مقارنات النماذج** + + - اختبار ومقارنة مطالبات ونماذج مختلفة لوكلاء CrewAI قبل النشر. + +6. **الاختبارات والتقييمات** + + - إعداد اختبارات آلية لوكلاء ومهام CrewAI. diff --git a/docs/v1.15.1/ar/observability/maxim.mdx b/docs/v1.15.1/ar/observability/maxim.mdx new file mode 100644 index 000000000..dd311643b --- /dev/null +++ b/docs/v1.15.1/ar/observability/maxim.mdx @@ -0,0 +1,221 @@ +--- +title: "تكامل Maxim" +description: "بدء مراقبة وتقييم ومراقبة الوكلاء" +icon: "infinity" +mode: "wide" +--- + +# نظرة عامة على Maxim + +يوفر Maxim AI مراقبة شاملة للوكلاء وتقييماً ومراقبة لتطبيقات CrewAI. مع تكامل Maxim بسطر واحد، يمكنك بسهولة تتبع وتحليل تفاعلات الوكلاء ومقاييس الأداء والمزيد. + +## الميزات + +### إدارة المطالبات + +تمكّنك قدرات إدارة المطالبات في Maxim من إنشاء وتنظيم وتحسين المطالبات لوكلاء CrewAI. بدلاً من ترميز التعليمات مباشرة، استفد من SDK الخاص بـ Maxim لاسترداد وتطبيق مطالبات مُدارة بالإصدارات ديناميكياً. + + + + أنشئ وصقل وجرّب وانشر مطالباتك عبر الساحة. نظّم مطالباتك باستخدام المجلدات والإصدارات، وجرّب مع حالات العالم الحقيقي عن طريق ربط الأدوات والسياق، وانشر بناءً على منطق مخصص. + + + + + مع بناء الفرق لتطبيقات الذكاء الاصطناعي، يُعد جزء كبير من التجريب هو التكرار على هيكل المطالبات. للتعاون بفعالية وتنظيم التغييرات بوضوح، يسمح Maxim بإصدارات المطالبات ومقارنة التشغيلات عبر الإصدارات. + + + + + التكرار على المطالبات أثناء تطوير تطبيق الذكاء الاصطناعي يحتاج تجارب عبر النماذج وهياكل المطالبات وغيرها. لمقارنة الإصدارات واتخاذ قرارات مستنيرة، تسمح ساحة المقارنة بعرض جنب إلى جنب للنتائج. + + ## **لماذا تستخدم مقارنة المطالبات؟** + + تجمع مقارنة المطالبات عدة مطالبات فردية في عرض واحد، مما يمكّن من نهج مبسط لسير عمل متنوع: + + 1. **مقارنة النماذج**: تقييم أداء نماذج مختلفة على نفس المطالبة. + 2. **تحسين المطالبات**: مقارنة إصدارات مختلفة لتحديد الصياغة الأكثر فعالية. + 3. **اتساق عبر النماذج**: ضمان مخرجات متسقة عبر نماذج مختلفة لنفس المطالبة. + 4. **قياس الأداء**: تحليل مقاييس مثل زمن الاستجابة والتكلفة وعدد الرموز عبر نماذج ومطالبات مختلفة. + + + +### المراقبة والتقييمات + +يوفر Maxim AI مراقبة وتقييماً شاملاً لوكلاء CrewAI، مما يساعدك في فهم ما يحدث بالضبط أثناء كل تنفيذ. + + + + تتبع دورة حياة وكيلك الكاملة، بما في ذلك استدعاءات الأدوات ومسارات الوكلاء وتدفقات القرار بسهولة. + + + + + شغّل تقييمات مفصلة على التتبعات الكاملة أو العقد الفردية مع دعم لـ: + + - التفاعلات متعددة الخطوات وتحليل التتبع الدقيق + - تقييمات على مستوى الجلسة + - محاكاة لاختبار العالم الحقيقي + + + + + +

+ تقييم السجلات الملتقطة تلقائياً من واجهة المستخدم بناءً على المرشحات والعينات +

+ + +

+ استخدام التقييم البشري أو التصنيف لتقييم جودة سجلاتك +

+ + +

+ تقييم أي مكون من تتبعك أو سجلك للحصول على رؤى حول سلوك وكيلك +

+ + + --- + + + عيّن حدوداً على **الأخطاء والتكلفة واستخدام الرموز وتغذية المستخدم الراجعة وزمن الاستجابة** واحصل على تنبيهات فورية عبر Slack أو PagerDuty. + + + + + تصور التتبعات عبر الزمن ومقاييس الاستخدام وزمن الاستجابة ومعدلات الأخطاء بسهولة. + + + + + +## البدء + +### المتطلبات الأساسية + +- إصدار Python >= 3.10 +- حساب Maxim ([سجّل هنا](https://getmaxim.ai/)) +- توليد مفتاح API من Maxim +- مشروع CrewAI + +### التثبيت + +ثبّت Maxim SDK عبر pip: + +```python +pip install maxim-py +``` + +أو أضفه إلى ملف `requirements.txt`: + +``` +maxim-py +``` + +### الإعداد الأساسي + +### 1. إعداد متغيرات البيئة + +```python +### Environment Variables Setup + +# Create a `.env` file in your project root: + +# Maxim API Configuration +MAXIM_API_KEY=your_api_key_here +MAXIM_LOG_REPO_ID=your_repo_id_here +``` + +### 2. استيراد الحزم المطلوبة + +```python +from crewai import Agent, Task, Crew, Process +from maxim import Maxim +from maxim.logger.crewai import instrument_crewai +``` + +### 3. تهيئة Maxim بمفتاح API + +```python {8} +# Instrument CrewAI with just one line +instrument_crewai(Maxim().logger()) +``` + +### 4. إنشاء وتشغيل تطبيق CrewAI كالمعتاد + +```python +# Create your agent +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 +) + +# Define the task +research_task = Task( + description="Research the latest AI advancements...", + expected_output="", + agent=researcher +) + +# Configure and run the crew +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True +) + +try: + result = crew.kickoff() +finally: + maxim.cleanup() # Ensure cleanup happens even if errors occur +``` + +هذا كل شيء! سيتم الآن تسجيل جميع تفاعلات وكلاء CrewAI وستكون متاحة في لوحة معلومات Maxim. + +تحقق من دفتر Google Colab هذا كمرجع سريع - [الدفتر](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing) + +## عرض تتبعاتك + +بعد تشغيل تطبيق CrewAI: + +1. سجل الدخول إلى [لوحة معلومات Maxim](https://app.getmaxim.ai/login) +2. انتقل إلى مستودعك +3. اعرض تتبعات الوكلاء المفصلة، بما في ذلك: + - محادثات الوكلاء + - أنماط استخدام الأدوات + - مقاييس الأداء + - تحليلات التكاليف + + + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +- **عدم ظهور تتبعات**: تأكد من صحة مفتاح API ومعرف المستودع +- تأكد من استدعاء **`instrument_crewai()`** **_قبل_** تشغيل طاقمك +- عيّن `debug=True` في استدعاء `instrument_crewai()` لإظهار أي أخطاء داخلية: + + ```python + instrument_crewai(logger, debug=True) + ``` +- أعدّ وكلاءك مع `verbose=True` لالتقاط سجلات مفصلة +- تحقق مرة أخرى من أن `instrument_crewai()` يُستدعى **قبل** إنشاء أو تنفيذ الوكلاء + +## الموارد + + + + وثائق CrewAI الرسمية + + + وثائق Maxim الرسمية + + + Maxim Github + + diff --git a/docs/v1.15.1/ar/observability/mlflow.mdx b/docs/v1.15.1/ar/observability/mlflow.mdx new file mode 100644 index 000000000..d8945f14d --- /dev/null +++ b/docs/v1.15.1/ar/observability/mlflow.mdx @@ -0,0 +1,206 @@ +--- +title: تكامل MLflow +description: ابدأ بسرعة في مراقبة وكلائك باستخدام MLflow. +icon: bars-staggered +mode: "wide" +--- + +# نظرة عامة على MLflow + +[MLflow](https://mlflow.org/) هو منصة مفتوحة المصدر لمساعدة ممارسي تعلم الآلة والفرق في التعامل مع تعقيدات عملية تعلم الآلة. + +يوفر ميزة التتبع التي تعزز قابلية مراقبة نماذج اللغة الكبيرة (LLM) في تطبيقات الذكاء الاصطناعي التوليدي الخاصة بك من خلال التقاط معلومات تفصيلية حول تنفيذ خدمات تطبيقك. +يوفر التتبع طريقة لتسجيل المدخلات والمخرجات والبيانات الوصفية المرتبطة بكل خطوة وسيطة في الطلب، مما يتيح لك تحديد مصدر الأخطاء والسلوكيات غير المتوقعة بسهولة. + +![نظرة عامة على استخدام تتبع crewAI مع MLflow](/images/mlflow-tracing.gif) + +### الميزات + +- **لوحة معلومات التتبع**: راقب أنشطة وكلاء crewAI الخاصين بك من خلال لوحات معلومات تفصيلية تتضمن المدخلات والمخرجات والبيانات الوصفية للنطاقات. +- **التتبع الآلي**: تكامل مؤتمت بالكامل مع crewAI، يمكن تفعيله عبر تشغيل `mlflow.crewai.autolog()`. +- **أدوات التتبع اليدوي بأقل مجهود**: خصّص أدوات التتبع من خلال واجهات برمجة التطبيقات عالية المستوى من MLflow مثل المزخرفات وأغلفة الدوال ومديري السياق. +- **التوافق مع OpenTelemetry**: يدعم تتبع MLflow تصدير التتبعات إلى جامع OpenTelemetry، الذي يمكن استخدامه بعد ذلك لتصدير التتبعات إلى خلفيات متنوعة مثل Jaeger وZipkin وAWS X-Ray. +- **تغليف ونشر الوكلاء**: قم بتغليف ونشر وكلاء crewAI الخاصين بك إلى خادم استدلال مع مجموعة متنوعة من أهداف النشر. +- **استضافة آمنة لنماذج LLM**: استضف نماذج LLM متعددة من مزودين مختلفين في نقطة نهاية موحدة من خلال بوابة MLflow. +- **التقييم**: قيّم وكلاء crewAI الخاصين بك باستخدام مجموعة واسعة من المقاييس عبر واجهة برمجة تطبيقات مريحة `mlflow.evaluate()`. + +## تعليمات الإعداد + + + + ```shell + # The crewAI integration is available in mlflow>=2.19.0 + pip install mlflow + ``` + + + ```shell + # This process is optional, but it is recommended to use MLflow tracking server for better visualization and broader features. + mlflow server + ``` + + + أضف السطرين التاليين إلى كود تطبيقك: + + ```python + import mlflow + + mlflow.crewai.autolog() + + # Optional: Set a tracking URI and an experiment name if you have a tracking server + mlflow.set_tracking_uri("http://localhost:5000") + mlflow.set_experiment("CrewAI") + ``` + + مثال على الاستخدام لتتبع وكلاء 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) + ``` + راجع [وثائق تتبع MLflow](https://mlflow.org/docs/latest/llms/tracing/index.html) لمزيد من الإعدادات وحالات الاستخدام. + + + الآن يتم التقاط تتبعات وكلاء crewAI الخاصين بك بواسطة MLflow. + لنقم بزيارة خادم تتبع MLflow لعرض التتبعات والحصول على رؤى حول وكلائك. + + افتح `127.0.0.1:5000` في متصفحك لزيارة خادم تتبع MLflow. + + MLflow tracing example with crewai + + + diff --git a/docs/v1.15.1/ar/observability/neatlogs.mdx b/docs/v1.15.1/ar/observability/neatlogs.mdx new file mode 100644 index 000000000..7fbc188ad --- /dev/null +++ b/docs/v1.15.1/ar/observability/neatlogs.mdx @@ -0,0 +1,134 @@ +--- +title: تكامل Neatlogs +description: افهم وأصلح وشارك عمليات تشغيل وكلاء CrewAI الخاصة بك +icon: magnifying-glass-chart +mode: "wide" +--- + +# مقدمة + +يساعدك Neatlogs على **رؤية ما فعله وكيلك**، و**لماذا**، و**مشاركته**. + +يلتقط كل خطوة: الأفكار، واستدعاءات الأدوات، والاستجابات، والتقييمات. لا سجلات خام. فقط تتبعات واضحة ومنظمة. ممتاز لتصحيح الأخطاء والتعاون. + +## لماذا تستخدم Neatlogs؟ + +يستخدم وكلاء CrewAI أدوات متعددة وخطوات تفكير. عندما يحدث خطأ ما، تحتاج إلى السياق - وليس فقط الأخطاء. + +يتيح لك Neatlogs: + +- تتبع مسار اتخاذ القرار بالكامل +- إضافة ملاحظات مباشرة على الخطوات +- الدردشة مع التتبع باستخدام مساعد الذكاء الاصطناعي +- مشاركة عمليات التشغيل علنياً للحصول على ملاحظات +- تحويل الرؤى إلى مهام + +كل ذلك في مكان واحد. + +إدارة تتبعاتك بسهولة + +![التتبعات](/images/neatlogs-1.png) +![استجابة التتبع](/images/neatlogs-2.png) + +أفضل تجربة مستخدم لعرض تتبع CrewAI. انشر التعليقات أينما تريد. استخدم الذكاء الاصطناعي لتصحيح الأخطاء. + +![تفاصيل التتبع](/images/neatlogs-3.png) +![روبوت الدردشة الذكي مع التتبع](/images/neatlogs-4.png) +![درج التعليقات](/images/neatlogs-5.png) + +## الميزات الأساسية + +- **عارض التتبع**: تتبع الأفكار والأدوات والقرارات بالتسلسل +- **التعليقات المضمنة**: أشر إلى زملاء الفريق على أي خطوة تتبع +- **الملاحظات والتقييم**: حدد المخرجات كصحيحة أو غير صحيحة +- **إبراز الأخطاء**: وسم تلقائي لأخطاء API/الأدوات +- **تحويل المهام**: حوّل التعليقات إلى مهام موكلة +- **اسأل التتبع (AI)**: تحدث مع تتبعك باستخدام روبوت Neatlogs الذكي +- **المشاركة العامة**: انشر روابط التتبع لمجتمعك + +## إعداد سريع مع CrewAI + + + + قم بزيارة [neatlogs.com](https://neatlogs.com/?utm_source=crewAI-docs)، وأنشئ مشروعاً، وانسخ مفتاح API. + + + ```bash + pip install neatlogs + ``` + (أحدث إصدار 0.8.0، Python 3.8+؛ رخصة MIT) + + + قبل بدء وكلاء Crew، أضف: + + ```python + import neatlogs + neatlogs.init("YOUR_PROJECT_API_KEY") + ``` + + يعمل الوكلاء كالمعتاد. يلتقط Neatlogs كل شيء تلقائياً. + + + + + + +## تحت الغطاء + +وفقاً لـ GitHub، فإن Neatlogs: + +- يلتقط الأفكار واستدعاءات الأدوات والاستجابات والأخطاء وإحصائيات الرموز المميزة +- يدعم توليد المهام بالذكاء الاصطناعي وسير عمل التقييم المتين + +كل ذلك بسطرين فقط من الكود. + + + +## شاهده وهو يعمل + +### عرض توضيحي كامل (4 دقائق) + + + +### تكامل CrewAI (30 ثانية) + + + + + +## الروابط والدعم + +- [وثائق Neatlogs](https://docs.neatlogs.com/) +- [لوحة التحكم ومفتاح API](https://app.neatlogs.com/) +- [تابعنا على Twitter](https://twitter.com/neatlogs) +- البريد الإلكتروني: hello@neatlogs.com +- [GitHub SDK](https://github.com/NeatLogs/neatlogs) + + + +## الخلاصة + +بمجرد: + +```bash +pip install neatlogs + +import neatlogs +neatlogs.init("YOUR_API_KEY") + +You can now capture, understand, share, and act on your CrewAI agent runs in seconds. +No setup overhead. Full trace transparency. Full team collaboration. +``` diff --git a/docs/v1.15.1/ar/observability/openlit.mdx b/docs/v1.15.1/ar/observability/openlit.mdx new file mode 100644 index 000000000..a0aa5533d --- /dev/null +++ b/docs/v1.15.1/ar/observability/openlit.mdx @@ -0,0 +1,181 @@ +--- +title: تكامل OpenLIT +description: ابدأ بسرعة في مراقبة وكلائك بسطر واحد فقط من الكود باستخدام OpenTelemetry. +icon: magnifying-glass-chart +mode: "wide" +--- + +# نظرة عامة على OpenLIT + +[OpenLIT](https://github.com/openlit/openlit?src=crewai-docs) هو أداة مفتوحة المصدر تجعل من السهل مراقبة أداء وكلاء الذكاء الاصطناعي ونماذج LLM وقواعد بيانات المتجهات ووحدات GPU بسطر **واحد** فقط من الكود. + +يوفر تتبعاً ومقاييس أصلية لـ OpenTelemetry لتتبع المعلمات المهمة مثل التكلفة وزمن الاستجابة والتفاعلات وتسلسل المهام. +يمكّنك هذا الإعداد من تتبع المعلمات الفائقة ومراقبة مشكلات الأداء، مما يساعدك في إيجاد طرق لتحسين وضبط وكلائك بمرور الوقت. + + + Overview Agent usage including cost and tokens + Overview of agent otel traces and metrics + Overview of agent traces in details + + +### الميزات + +- **لوحة معلومات التحليلات**: راقب صحة وأداء وكلائك من خلال لوحات معلومات تفصيلية تتتبع المقاييس والتكاليف وتفاعلات المستخدمين. +- **SDK مراقبة أصلي لـ OpenTelemetry**: حزم SDK محايدة للمورد لإرسال التتبعات والمقاييس إلى أدوات المراقبة الحالية مثل Grafana وDataDog وغيرها. +- **تتبع التكاليف للنماذج المخصصة والمعدّلة**: خصّص تقديرات التكلفة لنماذج محددة باستخدام ملفات تسعير مخصصة لوضع ميزانية دقيقة. +- **لوحة مراقبة الاستثناءات**: اكتشف وحل المشكلات بسرعة من خلال تتبع الاستثناءات والأخطاء الشائعة بلوحة مراقبة. +- **الامتثال والأمان**: اكتشف التهديدات المحتملة مثل الألفاظ البذيئة وتسريبات المعلومات الشخصية. +- **كشف حقن الموجهات**: حدد حقن الكود المحتمل وتسريبات الأسرار. +- **إدارة مفاتيح API والأسرار**: تعامل مع مفاتيح API لنماذج LLM وأسرارك مركزياً بأمان، مع تجنب الممارسات غير الآمنة. +- **إدارة الموجهات**: أدر وأصدر موجهات الوكلاء باستخدام PromptHub للوصول المتسق والسهل عبر الوكلاء. +- **ساحة تجربة النماذج**: اختبر وقارن نماذج مختلفة لوكلاء CrewAI قبل النشر. + +## تعليمات الإعداد + + + + + + ```shell + git clone git@github.com:openlit/openlit.git + ``` + + + من المجلد الجذري لـ [مستودع OpenLIT](https://github.com/openlit/openlit)، شغّل الأمر التالي: + ```shell + docker compose up -d + ``` + + + + + ```shell + pip install openlit + ``` + + + أضف السطرين التاليين إلى كود تطبيقك: + + + ```python + import openlit + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + ``` + + مثال على الاستخدام لمراقبة وكيل CrewAI: + + ```python + from crewai import Agent, Task, Crew, Process + import openlit + + openlit.init(disable_metrics=True) + # 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, + llm='command-r' + ) + + + # 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, + llm='command-r' + ) + + # Instantiate your crew with a custom manager + crew = Crew( + agents=[researcher], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, + ) + + # Start the crew's work + result = crew.kickoff() + + print(result) + ``` + + + + أضف السطرين التاليين إلى كود تطبيقك: + ```python + import openlit + + openlit.init() + ``` + + شغّل الأمر التالي لإعداد نقطة نهاية تصدير OTEL: + ```shell + export OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318" + ``` + + مثال على الاستخدام لمراقبة وكيل CrewAI غير متزامن: + + ```python + import asyncio + from crewai import Crew, Agent, Task + import openlit + + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + + # 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, + llm="command-r" + ) + + # 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="5 bullet points, each with a paragraph and accompanying notes.", + ) + + # 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()) + ``` + + + راجع [مستودع Python SDK الخاص بـ OpenLIT](https://github.com/openlit/openlit/tree/main/sdk/python) لمزيد من الإعدادات المتقدمة وحالات الاستخدام. + + + مع جمع بيانات مراقبة الوكلاء وإرسالها إلى OpenLIT، الخطوة التالية هي عرض وتحليل هذه البيانات للحصول على رؤى حول أداء وكيلك وسلوكه وتحديد مجالات التحسين. + + ما عليك سوى التوجه إلى OpenLIT على `127.0.0.1:3000` في متصفحك لبدء الاستكشاف. يمكنك تسجيل الدخول باستخدام بيانات الاعتماد الافتراضية + - **البريد الإلكتروني**: `user@openlit.io` + - **كلمة المرور**: `openlituser` + + + Overview Agent usage including cost and tokens + Overview of agent otel traces and metrics + + + + diff --git a/docs/v1.15.1/ar/observability/opik.mdx b/docs/v1.15.1/ar/observability/opik.mdx new file mode 100644 index 000000000..60442fe47 --- /dev/null +++ b/docs/v1.15.1/ar/observability/opik.mdx @@ -0,0 +1,130 @@ +--- +title: تكامل Opik +description: تعرّف على كيفية استخدام Comet Opik لتصحيح الأخطاء وتقييم ومراقبة تطبيقات CrewAI الخاصة بك مع تتبع شامل وتقييمات آلية ولوحات معلومات جاهزة للإنتاج. +icon: meteor +mode: "wide" +--- + +# نظرة عامة على Opik + +مع [Comet Opik](https://www.comet.com/docs/opik/)، يمكنك تصحيح الأخطاء وتقييم ومراقبة تطبيقات LLM وأنظمة RAG وسير العمل الوكيلي مع تتبع شامل وتقييمات آلية ولوحات معلومات جاهزة للإنتاج. + + + Opik agent monitoring example with CrewAI + + +يوفر Opik دعماً شاملاً لكل مرحلة من مراحل تطوير تطبيق CrewAI الخاص بك: + +- **تسجيل التتبعات والنطاقات**: تتبع تلقائي لاستدعاءات LLM ومنطق التطبيق لتصحيح الأخطاء وتحليل أنظمة التطوير والإنتاج. أضف التعليقات التوضيحية يدوياً أو برمجياً، واعرض وقارن الاستجابات عبر المشاريع. +- **تقييم أداء تطبيق LLM**: قيّم وفقاً لمجموعة اختبار مخصصة وشغّل مقاييس تقييم مدمجة أو حدد مقاييسك الخاصة في SDK أو واجهة المستخدم. +- **الاختبار ضمن خط أنابيب CI/CD**: أنشئ خطوط أساس أداء موثوقة مع اختبارات وحدة LLM من Opik، المبنية على PyTest. شغّل تقييمات عبر الإنترنت للمراقبة المستمرة في الإنتاج. +- **مراقبة وتحليل بيانات الإنتاج**: افهم أداء نماذجك على بيانات غير مرئية في الإنتاج وأنشئ مجموعات بيانات لتكرارات التطوير الجديدة. + +## الإعداد +يوفر Comet نسخة مستضافة من منصة Opik، أو يمكنك تشغيل المنصة محلياً. + +لاستخدام النسخة المستضافة، ما عليك سوى [إنشاء حساب Comet مجاني](https://www.comet.com/signup?utm_medium=github&utm_source=crewai_docs) والحصول على مفتاح API الخاص بك. + +لتشغيل منصة Opik محلياً، راجع [دليل التثبيت](https://www.comet.com/docs/opik/self-host/overview/) لمزيد من المعلومات. + +في هذا الدليل سنستخدم مثال البدء السريع الخاص بـ CrewAI. + + + + ```shell + pip install crewai crewai-tools opik --upgrade + ``` + + + ```python + import opik + opik.configure(use_local=False) + ``` + + + أولاً، نقوم بإعداد مفاتيح API لمزود LLM كمتغيرات بيئة: + + ```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: ") + ``` + + + الخطوة الأولى هي إنشاء مشروعنا. سنستخدم مثالاً من وثائق 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, + ) + + ``` + + الآن يمكننا استيراد متتبع Opik وتشغيل الطاقم: + + ```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) + ``` + بعد تشغيل تطبيق CrewAI، قم بزيارة تطبيق Opik لعرض: + - تتبعات LLM والنطاقات وبياناتها الوصفية + - تفاعلات الوكلاء وتدفق تنفيذ المهام + - مقاييس الأداء مثل زمن الاستجابة واستخدام الرموز المميزة + - مقاييس التقييم (مدمجة أو مخصصة) + + + +## الموارد + +- [وثائق 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/) diff --git a/docs/v1.15.1/ar/observability/overview.mdx b/docs/v1.15.1/ar/observability/overview.mdx new file mode 100644 index 000000000..9e6e239c7 --- /dev/null +++ b/docs/v1.15.1/ar/observability/overview.mdx @@ -0,0 +1,120 @@ +--- +title: "نظرة عامة" +description: "راقب وقيّم وحسّن وكلاء CrewAI الخاصين بك باستخدام أدوات مراقبة شاملة" +icon: "face-smile" +mode: "wide" +--- + +## المراقبة في CrewAI + +تعد المراقبة أمراً بالغ الأهمية لفهم كيفية أداء وكلاء CrewAI، وتحديد الاختناقات، وضمان التشغيل الموثوق في بيئات الإنتاج. يغطي هذا القسم مختلف الأدوات والمنصات التي توفر إمكانيات المراقبة والتقييم والتحسين لسير عمل وكلائك. + +## لماذا تعد المراقبة مهمة + +- **مراقبة الأداء**: تتبع أوقات تنفيذ الوكلاء واستخدام الرموز المميزة واستهلاك الموارد +- **ضمان الجودة**: تقييم جودة المخرجات واتساقها عبر سيناريوهات مختلفة +- **تصحيح الأخطاء**: تحديد وحل المشكلات في سلوك الوكلاء وتنفيذ المهام +- **إدارة التكاليف**: مراقبة استخدام API لنماذج LLM والتكاليف المرتبطة بها +- **التحسين المستمر**: جمع الرؤى لتحسين أداء الوكلاء بمرور الوقت + +## أدوات المراقبة المتاحة + +### منصات المراقبة والتتبع + + + + + تتبع شامل لسير عمل CrewAI مع التقاط تلقائي لتفاعلات الوكلاء. + + + + مراقبة أصلية لـ OpenTelemetry مع تتبع التكاليف وتحليلات الأداء. + + + + إدارة دورة حياة تعلم الآلة مع إمكانيات التتبع والتقييم. + + + + منصة هندسة LLM مع تتبع وتحليلات تفصيلية. + + + + مراقبة مفتوحة المصدر لنماذج LLM وأطر العمل الوكيلية. + + + + منصة مراقبة الذكاء الاصطناعي للمراقبة واستكشاف الأخطاء وإصلاحها. + + + + بوابة ذكاء اصطناعي مع مراقبة شاملة وميزات موثوقية. + + + + تصحيح الأخطاء وتقييم ومراقبة تطبيقات LLM مع تتبع شامل. + + + + منصة Weights & Biases لتتبع وتقييم تطبيقات الذكاء الاصطناعي. + + + +### التقييم وضمان الجودة + + + + منصة تقييم شاملة لمخرجات LLM وسلوكيات الوكلاء. + + + +## مقاييس المراقبة الرئيسية + +### مقاييس الأداء +- **وقت التنفيذ**: المدة التي يستغرقها الوكلاء لإكمال المهام +- **استخدام الرموز المميزة**: الرموز المدخلة/المخرجة المستهلكة من استدعاءات LLM +- **زمن استجابة API**: أوقات الاستجابة من الخدمات الخارجية +- **معدل النجاح**: نسبة المهام المكتملة بنجاح + +### مقاييس الجودة +- **دقة المخرجات**: صحة استجابات الوكلاء +- **الاتساق**: الموثوقية عبر مدخلات متشابهة +- **الصلة**: مدى تطابق المخرجات مع النتائج المتوقعة +- **السلامة**: الامتثال لسياسات المحتوى والإرشادات + +### مقاييس التكلفة +- **تكاليف API**: النفقات من استخدام مزودي LLM +- **استخدام الموارد**: استهلاك الحوسبة والذاكرة +- **التكلفة لكل مهمة**: الكفاءة الاقتصادية لعمليات الوكلاء +- **تتبع الميزانية**: المراقبة مقابل حدود الإنفاق + +## البدء + +1. **اختر أدواتك**: حدد منصات المراقبة التي تتوافق مع احتياجاتك +2. **أضف الأدوات لكودك**: أضف المراقبة لتطبيقات CrewAI الخاصة بك +3. **أعدّ لوحات المعلومات**: هيئ العروض المرئية للمقاييس الرئيسية +4. **حدد التنبيهات**: أنشئ إشعارات للأحداث المهمة +5. **أنشئ خطوط الأساس**: قس الأداء الأولي للمقارنة +6. **كرر وحسّن**: استخدم الرؤى لتحسين وكلائك + +## أفضل الممارسات + +### مرحلة التطوير +- استخدم التتبع التفصيلي لفهم سلوك الوكلاء +- طبّق مقاييس التقييم مبكراً في التطوير +- راقب استخدام الموارد أثناء الاختبار +- أعدّ فحوصات جودة آلية + +### مرحلة الإنتاج +- طبّق مراقبة وتنبيهات شاملة +- تتبع اتجاهات الأداء بمرور الوقت +- راقب الشذوذ والتدهور +- حافظ على رؤية التكاليف والتحكم بها + +### التحسين المستمر +- مراجعات أداء وتحسين منتظمة +- اختبار A/B لتكوينات وكلاء مختلفة +- حلقات تغذية راجعة لتحسين الجودة +- توثيق الدروس المستفادة + +اختر أدوات المراقبة التي تناسب حالة الاستخدام والبنية التحتية ومتطلبات المراقبة الخاصة بك لضمان أن وكلاء CrewAI يعملون بشكل موثوق وفعال. diff --git a/docs/v1.15.1/ar/observability/patronus-evaluation.mdx b/docs/v1.15.1/ar/observability/patronus-evaluation.mdx new file mode 100644 index 000000000..c6b522640 --- /dev/null +++ b/docs/v1.15.1/ar/observability/patronus-evaluation.mdx @@ -0,0 +1,206 @@ +--- +title: تقييم Patronus AI +description: راقب وقيّم أداء وكلاء CrewAI باستخدام منصة التقييم الشاملة من Patronus AI لمخرجات LLM وسلوكيات الوكلاء. +icon: shield-check +mode: "wide" +--- + +# تقييم Patronus AI + +## نظرة عامة + +يوفر [Patronus AI](https://patronus.ai) إمكانيات تقييم ومراقبة شاملة لوكلاء CrewAI، مما يمكّنك من تقييم مخرجات النماذج وسلوكيات الوكلاء والأداء العام للنظام. يتيح لك هذا التكامل تنفيذ سير عمل تقييم مستمر يساعد في الحفاظ على الجودة والموثوقية في بيئات الإنتاج. + +## الميزات الرئيسية + +- **التقييم الآلي**: تقييم فوري لمخرجات وسلوكيات الوكلاء +- **معايير مخصصة**: حدد معايير تقييم محددة مصممة لحالات الاستخدام الخاصة بك +- **مراقبة الأداء**: تتبع مقاييس أداء الوكلاء بمرور الوقت +- **ضمان الجودة**: ضمان جودة مخرجات متسقة عبر سيناريوهات مختلفة +- **السلامة والامتثال**: مراقبة المشكلات المحتملة وانتهاكات السياسات + +## أدوات التقييم + +يوفر Patronus ثلاث أدوات تقييم رئيسية لحالات استخدام مختلفة: + +1. **PatronusEvalTool**: يسمح للوكلاء باختيار المقيّم والمعايير الأنسب لمهمة التقييم. +2. **PatronusPredefinedCriteriaEvalTool**: يستخدم مقيّماً ومعايير محددة مسبقاً من قبل المستخدم. +3. **PatronusLocalEvaluatorTool**: يستخدم دوال تقييم مخصصة محددة من قبل المستخدم. + +## التثبيت + +لاستخدام هذه الأدوات، تحتاج إلى تثبيت حزمة Patronus: + +```shell +uv add patronus +``` + +ستحتاج أيضاً إلى إعداد مفتاح API الخاص بـ Patronus كمتغير بيئة: + +```shell +export PATRONUS_API_KEY="your_patronus_api_key" +``` + +## خطوات البدء + +لاستخدام أدوات تقييم Patronus بفعالية، اتبع الخطوات التالية: + +1. **تثبيت Patronus**: ثبّت حزمة Patronus باستخدام الأمر أعلاه. +2. **إعداد مفتاح API**: عيّن مفتاح API الخاص بـ Patronus كمتغير بيئة. +3. **اختيار الأداة المناسبة**: حدد أداة تقييم Patronus المناسبة بناءً على احتياجاتك. +4. **إعداد الأداة**: هيئ الأداة بالمعاملات اللازمة. + +## أمثلة + +### استخدام PatronusEvalTool + +يوضح المثال التالي كيفية استخدام `PatronusEvalTool`، التي تسمح للوكلاء باختيار المقيّم والمعايير الأنسب: + +```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() +``` + +### استخدام PatronusPredefinedCriteriaEvalTool + +يوضح المثال التالي كيفية استخدام `PatronusPredefinedCriteriaEvalTool`، التي تستخدم مقيّماً ومعايير محددة مسبقاً: + +```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() +``` + +### استخدام PatronusLocalEvaluatorTool + +يوضح المثال التالي كيفية استخدام `PatronusLocalEvaluatorTool`، التي تستخدم دوال تقييم مخصصة: + +```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() +``` + +## المعاملات + +### PatronusEvalTool + +لا تتطلب `PatronusEvalTool` أي معاملات أثناء التهيئة. تقوم تلقائياً بجلب المقيّمين والمعايير المتاحة من API الخاص بـ Patronus. + +### PatronusPredefinedCriteriaEvalTool + +تقبل `PatronusPredefinedCriteriaEvalTool` المعاملات التالية أثناء التهيئة: + +- **evaluators**: مطلوب. قائمة من القواميس تحتوي على المقيّم والمعايير المراد استخدامها. مثال: `[{"evaluator": "judge", "criteria": "contains-code"}]`. + +### PatronusLocalEvaluatorTool + +تقبل `PatronusLocalEvaluatorTool` المعاملات التالية أثناء التهيئة: + +- **patronus_client**: مطلوب. مثيل عميل Patronus. +- **evaluator**: اختياري. اسم المقيّم المحلي المسجل للاستخدام. القيمة الافتراضية هي سلسلة نصية فارغة. +- **evaluated_model_gold_answer**: اختياري. الإجابة المرجعية للاستخدام في التقييم. القيمة الافتراضية هي سلسلة نصية فارغة. + +## الاستخدام + +عند استخدام أدوات تقييم Patronus، تقدم مدخلات النموذج ومخرجاته وسياقه، وتعيد الأداة نتائج التقييم من API الخاص بـ Patronus. + +بالنسبة لـ `PatronusEvalTool` و`PatronusPredefinedCriteriaEvalTool`، المعاملات التالية مطلوبة عند استدعاء الأداة: + +- **evaluated_model_input**: وصف مهمة الوكيل بنص بسيط. +- **evaluated_model_output**: مخرجات الوكيل للمهمة. +- **evaluated_model_retrieved_context**: سياق الوكيل. + +بالنسبة لـ `PatronusLocalEvaluatorTool`، نفس المعاملات مطلوبة، لكن المقيّم والإجابة المرجعية يتم تحديدهما أثناء التهيئة. + +## الخلاصة + +توفر أدوات تقييم Patronus طريقة قوية لتقييم وتسجيل درجات مدخلات ومخرجات النماذج باستخدام منصة Patronus AI. من خلال تمكين الوكلاء من تقييم مخرجاتهم أو مخرجات وكلاء آخرين، يمكن لهذه الأدوات المساعدة في تحسين جودة وموثوقية سير عمل CrewAI. diff --git a/docs/v1.15.1/ar/observability/portkey.mdx b/docs/v1.15.1/ar/observability/portkey.mdx new file mode 100644 index 000000000..e676b7a35 --- /dev/null +++ b/docs/v1.15.1/ar/observability/portkey.mdx @@ -0,0 +1,823 @@ +--- +title: تكامل Portkey +description: كيفية استخدام Portkey مع CrewAI +icon: key +mode: "wide" +--- + +Portkey CrewAI Header Image + + + +## مقدمة + +يعزز Portkey إمكانيات CrewAI بميزات جاهزة للإنتاج، محولاً طواقم الوكلاء التجريبية إلى أنظمة متينة من خلال توفير: + +- **مراقبة كاملة** لكل خطوة وكيل واستخدام أداة وتفاعل +- **موثوقية مدمجة** مع آليات الاحتياط وإعادة المحاولة وموازنة الأحمال +- **تتبع التكاليف وتحسينها** لإدارة إنفاقك على الذكاء الاصطناعي +- **الوصول إلى أكثر من 200 نموذج LLM** من خلال تكامل واحد +- **حواجز الحماية** للحفاظ على سلوك الوكلاء آمناً ومتوافقاً +- **موجهات مُتحكم بإصداراتها** لأداء وكلاء متسق + + +### التثبيت والإعداد + + + +```bash +pip install -U crewai portkey-ai +``` + + + +أنشئ مفتاح API لـ Portkey مع حدود ميزانية/معدل اختيارية من [لوحة تحكم Portkey](https://app.portkey.ai/). يمكنك أيضاً إرفاق إعدادات للموثوقية والتخزين المؤقت والمزيد لهذا المفتاح. المزيد عن هذا لاحقاً. + + + +التكامل بسيط - ما عليك سوى تحديث إعداد LLM في تكوين CrewAI الخاص بك: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create an LLM instance with Portkey integration +gpt_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", # We are using a Virtual key, so this is a placeholder + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_LLM_VIRTUAL_KEY", + trace_id="unique-trace-id", # Optional, for request tracing + ) +) + +#Use them in your Crew Agents like this: + + @agent + def lead_market_analyst(self) -> Agent: + return Agent( + config=self.agents_config['lead_market_analyst'], + verbose=True, + memory=False, + llm=gpt_llm + ) + +``` + + +**ما هي المفاتيح الافتراضية؟** تخزّن المفاتيح الافتراضية في Portkey مفاتيح API لمزودي LLM (OpenAI وAnthropic وغيرها) بشكل آمن في خزنة مشفرة. تتيح تدوير المفاتيح وإدارة الميزانية بسهولة. [تعرّف على المزيد حول المفاتيح الافتراضية هنا](https://portkey.ai/docs/product/ai-gateway/virtual-keys). + + + + +## ميزات الإنتاج + +### 1. مراقبة محسّنة + +يوفر Portkey مراقبة شاملة لوكلاء CrewAI، مما يساعدك على فهم ما يحدث بالضبط أثناء كل عملية تنفيذ. + + + + + + + +توفر التتبعات عرضاً هرمياً لتنفيذ طاقمك، يظهر تسلسل استدعاءات LLM واستدعاءات الأدوات وانتقالات الحالة. + +```python +# Add trace_id to enable hierarchical tracing in 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" # Add unique trace ID + ) +) +``` + + + + + + + +يسجّل Portkey كل تفاعل مع نماذج LLM، بما في ذلك: + +- حمولات الطلب والاستجابة الكاملة +- مقاييس زمن الاستجابة واستخدام الرموز المميزة +- حسابات التكلفة +- استدعاءات الأدوات وتنفيذ الدوال + +يمكن تصفية جميع السجلات حسب البيانات الوصفية ومعرّفات التتبع والنماذج والمزيد، مما يسهّل تصحيح أخطاء عمليات تشغيل طاقم محددة. + + + + + + + +يوفر Portkey لوحات معلومات مدمجة تساعدك على: + +- تتبع التكلفة واستخدام الرموز المميزة عبر جميع عمليات تشغيل الطاقم +- تحليل مقاييس الأداء مثل زمن الاستجابة ومعدلات النجاح +- تحديد الاختناقات في سير عمل الوكلاء +- مقارنة تكوينات الطاقم ونماذج LLM المختلفة + +يمكنك تصفية وتقسيم جميع المقاييس حسب بيانات وصفية مخصصة لتحليل أنواع طواقم أو مجموعات مستخدمين أو حالات استخدام محددة. + + + + + Analytics with metadata filters + + +أضف بيانات وصفية مخصصة لتكوين LLM في CrewAI لتمكين تصفية وتقسيم قوية: + +```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", # Special _user field for user analytics + "request_source": "mobile_app" + } + ) +) +``` + +يمكن استخدام هذه البيانات الوصفية لتصفية السجلات والتتبعات والمقاييس في لوحة تحكم Portkey، مما يتيح لك تحليل عمليات تشغيل طاقم أو مستخدمين أو بيئات محددة. + + + +### 2. الموثوقية - حافظ على تشغيل طواقمك بسلاسة + +عند تشغيل الطواقم في الإنتاج، قد تحدث مشكلات - حدود معدل API أو مشكلات الشبكة أو انقطاعات المزود. تضمن ميزات الموثوقية في Portkey استمرار عمل وكلائك بسلاسة حتى عند حدوث مشكلات. + +من السهل تفعيل الاحتياط في إعداد CrewAI الخاص بك باستخدام تكوين Portkey: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with fallback configuration +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 this LLM configuration with your agents +``` + +سيحاول هذا التكوين تلقائياً استخدام Claude إذا فشل طلب GPT-4o، مما يضمن استمرار تشغيل طاقمك. + + + + يتعامل مع حالات الفشل المؤقتة تلقائياً. إذا فشل استدعاء LLM، سيعيد Portkey محاولة نفس الطلب لعدد محدد من المرات - مثالي لحدود المعدل أو انقطاعات الشبكة. + + + امنع وكلاءك من التعليق. عيّن مهلات لضمان حصولك على استجابات (أو الفشل بأمان) ضمن الأطر الزمنية المطلوبة. + + + أرسل طلبات مختلفة إلى مزودين مختلفين. وجّه التفكير المعقد إلى GPT-4 والمهام الإبداعية إلى Claude والاستجابات السريعة إلى Gemini بناءً على احتياجاتك. + + + استمر في العمل حتى لو فشل مزودك الأساسي. انتقل تلقائياً إلى مزودين احتياطيين للحفاظ على التوفر. + + + وزّع الطلبات عبر مفاتيح API أو مزودين متعددين. ممتاز لعمليات الطاقم عالية الحجم والبقاء ضمن حدود المعدل. + + + +### 3. إدارة الموجهات في CrewAI + +يساعدك استوديو هندسة الموجهات من Portkey في إنشاء وإدارة وتحسين الموجهات المستخدمة في وكلاء CrewAI. بدلاً من ترميز الموجهات أو التعليمات بشكل ثابت، استخدم API عرض الموجهات من Portkey لجلب وتطبيق موجهاتك المُصدَرة ديناميكياً. + + +![Prompt Playground Interface](https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/refs/heads/main/CrewAI%20Portkey%20Docs.webp) + + + + +ساحة تجربة الموجهات هي مكان لمقارنة واختبار ونشر الموجهات المثالية لتطبيق الذكاء الاصطناعي الخاص بك. هي المكان الذي تجرّب فيه نماذج مختلفة وتختبر المتغيرات وتقارن المخرجات وتحسّن استراتيجية هندسة الموجهات قبل النشر في الإنتاج. تتيح لك: + +1. تطوير الموجهات بشكل تكراري قبل استخدامها في وكلائك +2. اختبار الموجهات مع متغيرات ونماذج مختلفة +3. مقارنة المخرجات بين إصدارات موجهات مختلفة +4. التعاون مع أعضاء الفريق في تطوير الموجهات + +تجعل هذه البيئة المرئية من الأسهل صياغة موجهات فعالة لكل خطوة في سير عمل وكلاء CrewAI. + + + +يسترجع API عرض الموجهات قوالب الموجهات الخاصة بك مع جميع المعاملات المُعدّة: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL, Portkey + +# Initialize Portkey admin client +portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY") + +# Retrieve prompt using the 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"] + + +# Set up LLM with Portkey integration +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" + ) +) + +# Create agent using the rendered prompt +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory=backstory_agent, # Use the rendered prompt + verbose=True, + llm=portkey_llm +) +``` + + + +يمكنك: +- إنشاء إصدارات متعددة من نفس الموجه +- مقارنة الأداء بين الإصدارات +- الرجوع إلى إصدارات سابقة عند الحاجة +- تحديد الإصدار المراد استخدامه في كودك: + +```python +# Use a specific prompt version +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID@version_number", + variables={ + "agent_role": "Senior Research Scientist", + "agent_goal": "Discover groundbreaking insights" + } +) +``` + + + +تستخدم موجهات Portkey قوالب بنمط Mustache لاستبدال المتغيرات بسهولة: + +``` +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}}. +``` + +عند العرض، ما عليك سوى تمرير المتغيرات: + +```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" + } +) +``` + + + + + تعرّف على المزيد حول ميزات إدارة الموجهات في Portkey + + +### 4. حواجز الحماية لطواقم آمنة + +تضمن حواجز الحماية أن وكلاء CrewAI يعملون بأمان ويستجيبون بشكل مناسب في جميع الحالات. + +**لماذا تستخدم حواجز الحماية؟** + +قد يواجه وكلاء CrewAI أوضاع فشل مختلفة: +- توليد محتوى ضار أو غير مناسب +- تسريب معلومات حساسة مثل المعلومات الشخصية +- توهم معلومات غير صحيحة +- توليد مخرجات بتنسيقات غير صحيحة + +تضيف حواجز حماية Portkey حماية لكل من المدخلات والمخرجات. + +**تطبيق حواجز الحماية** + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with 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"] + } + ) +) + +# Create agent with guardrailed LLM +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 +) +``` + +يمكن لحواجز حماية Portkey: +- كشف وحذف المعلومات الشخصية في المدخلات والمخرجات +- تصفية المحتوى الضار أو غير المناسب +- التحقق من تنسيقات الاستجابة وفقاً للمخططات +- التحقق من التوهمات مقابل الحقائق المرجعية +- تطبيق منطق الأعمال والقواعد المخصصة + + + استكشف ميزات حواجز الحماية في Portkey لتعزيز سلامة الوكلاء + + +### 5. تتبع المستخدمين باستخدام البيانات الوصفية + +تتبع المستخدمين الفرديين عبر وكلاء CrewAI باستخدام نظام البيانات الوصفية في Portkey. + +**ما هي البيانات الوصفية في Portkey؟** + +تتيح لك البيانات الوصفية ربط بيانات مخصصة بكل طلب، مما يمكّن التصفية والتقسيم والتحليلات. الحقل الخاص `_user` مصمم خصيصاً لتتبع المستخدمين. + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with user tracking +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", # Special _user field for user analytics + "user_tier": "premium", + "user_company": "Acme Corp", + "session_id": "abc-123" + } + ) +) + +# Create agent with tracked LLM +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 +) +``` + +**تصفية التحليلات حسب المستخدم** + +مع وجود البيانات الوصفية، يمكنك تصفية التحليلات حسب المستخدم وتحليل مقاييس الأداء على أساس كل مستخدم: + + + + + +يمكّن هذا: +- تتبع التكاليف والميزانية لكل مستخدم +- تحليلات مستخدم مخصصة +- مقاييس على مستوى الفريق أو المؤسسة +- مراقبة خاصة بالبيئة (التجريب مقابل الإنتاج) + + + استكشف كيفية استخدام البيانات الوصفية المخصصة لتعزيز تحليلاتك + + +### 6. التخزين المؤقت لطواقم فعالة + +طبّق التخزين المؤقت لجعل وكلاء CrewAI أكثر كفاءة وفعالية من حيث التكلفة: + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with simple caching +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" + } + } + ) +) + +# Create agent with cached LLM +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 +) +``` + +يقوم التخزين المؤقت البسيط بمطابقة دقيقة لموجهات الإدخال، مع تخزين الطلبات المتطابقة لتجنب عمليات تنفيذ النموذج الزائدة. + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with semantic caching +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" + } + } + ) +) + +# Create agent with semantically cached LLM +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 +) +``` + +يأخذ التخزين المؤقت الدلالي في الاعتبار التشابه السياقي بين طلبات الإدخال، مع تخزين الاستجابات للمدخلات المتشابهة دلالياً. + + + +### 7. التوافق بين النماذج + +يدعم CrewAI مزودي LLM متعددين، ويوسّع Portkey هذه القدرة من خلال توفير الوصول إلى أكثر من 200 نموذج LLM عبر واجهة موحدة. يمكنك التبديل بسهولة بين نماذج مختلفة دون تغيير منطق الوكيل الأساسي: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Set up LLMs with different providers +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" + ) +) + +# Choose which LLM to use for each agent based on your needs +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 for Anthropic +) +``` + +يوفر Portkey الوصول إلى نماذج LLM من مزودين بما في ذلك: + +- OpenAI (GPT-4o، GPT-4 Turbo، إلخ) +- Anthropic (Claude 3.5 Sonnet، Claude 3 Opus، إلخ) +- Mistral AI (Mistral Large، Mistral Medium، إلخ) +- Google Vertex AI (Gemini 1.5 Pro، إلخ) +- Cohere (Command، Command-R، إلخ) +- AWS Bedrock (Claude، Titan، إلخ) +- النماذج المحلية/الخاصة + + + اطلع على القائمة الكاملة لمزودي LLM المدعومين من Portkey + + +## إعداد حوكمة المؤسسة لـ CrewAI + +**لماذا حوكمة المؤسسة؟** +إذا كنت تستخدم CrewAI داخل مؤسستك، فأنت بحاجة إلى مراعاة عدة جوانب حوكمة: +- **إدارة التكاليف**: التحكم في إنفاق الذكاء الاصطناعي وتتبعه عبر الفرق +- **التحكم في الوصول**: إدارة الفرق التي يمكنها استخدام نماذج محددة +- **تحليلات الاستخدام**: فهم كيفية استخدام الذكاء الاصطناعي عبر المؤسسة +- **الأمان والامتثال**: الحفاظ على معايير أمان المؤسسة +- **الموثوقية**: ضمان خدمة متسقة لجميع المستخدمين + +يضيف Portkey طبقة حوكمة شاملة لتلبية احتياجات المؤسسة هذه. لننفّذ هذه الضوابط خطوة بخطوة. + + + +المفاتيح الافتراضية هي طريقة Portkey الآمنة لإدارة مفاتيح API لمزودي LLM. توفر ضوابط أساسية مثل: +- حدود الميزانية لاستخدام API +- إمكانيات تحديد المعدل +- تخزين آمن لمفاتيح API + +لإنشاء مفتاح افتراضي: +انتقل إلى [المفاتيح الافتراضية](https://app.portkey.ai/virtual-keys) في تطبيق Portkey. احفظ وانسخ معرّف المفتاح الافتراضي + + + + + + +احفظ معرّف المفتاح الافتراضي - ستحتاجه في الخطوة التالية. + + + + +تحدد التكوينات في Portkey كيفية توجيه طلباتك، مع ميزات مثل التوجيه المتقدم والاحتياط وإعادة المحاولة. + +لإنشاء تكوينك: +1. انتقل إلى [التكوينات](https://app.portkey.ai/configs) في لوحة تحكم Portkey +2. أنشئ تكويناً جديداً بـ: + ```json + { + "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1", + "override_params": { + "model": "gpt-4o" // Your preferred model name + } + } + ``` +3. احفظ ولاحظ اسم التكوين للخطوة التالية + + + + + + + + +الآن أنشئ مفتاح API لـ Portkey وأرفق التكوين الذي أنشأته في الخطوة 2: + +1. انتقل إلى [مفاتيح API](https://app.portkey.ai/api-keys) في Portkey وأنشئ مفتاح API جديد +2. حدد تكوينك من `الخطوة 2` +3. أنشئ واحفظ مفتاح API الخاص بك + + + + + + + + +بعد إعداد مفتاح API لـ Portkey مع التكوين المرفق، اربطه بوكلاء CrewAI: + +```python +from crewai import Agent, LLM +from portkey_ai import PORTKEY_GATEWAY_URL + +# Configure LLM with your API key +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="YOUR_PORTKEY_API_KEY" +) + +# Create agent with Portkey-enabled LLM +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 +) +``` + + + + + +### الخطوة 1: تطبيق ضوابط الميزانية وحدود المعدل + +تمكّن المفاتيح الافتراضية التحكم الدقيق في الوصول إلى LLM على مستوى الفريق/القسم. يساعدك هذا على: +- إعداد [حدود الميزانية](https://portkey.ai/docs/product/ai-gateway/virtual-keys/budget-limits) +- منع الارتفاعات غير المتوقعة في الاستخدام باستخدام حدود المعدل +- تتبع إنفاق الأقسام + +#### إعداد ضوابط خاصة بالقسم: +1. انتقل إلى [المفاتيح الافتراضية](https://app.portkey.ai/virtual-keys) في لوحة تحكم Portkey +2. أنشئ مفتاحاً افتراضياً جديداً لكل قسم مع حدود ميزانية ومعدل +3. هيئ الحدود الخاصة بكل قسم + + + + + + + +### الخطوة 2: تحديد قواعد الوصول للنماذج + +مع توسع استخدام الذكاء الاصطناعي، يصبح التحكم في الفرق التي يمكنها الوصول إلى نماذج محددة أمراً بالغ الأهمية. توفر تكوينات Portkey طبقة التحكم هذه مع ميزات مثل: + +#### ميزات التحكم في الوصول: +- **قيود النماذج**: تقييد الوصول إلى نماذج محددة +- **حماية البيانات**: تطبيق حواجز حماية للبيانات الحساسة +- **ضوابط الموثوقية**: إضافة احتياط ومنطق إعادة المحاولة + +#### مثال على التكوين: +إليك تكويناً أساسياً لتوجيه الطلبات إلى OpenAI، تحديداً باستخدام GPT-4o: + +```json +{ + "strategy": { + "mode": "single" + }, + "targets": [ + { + "virtual_key": "YOUR_OPENAI_VIRTUAL_KEY", + "override_params": { + "model": "gpt-4o" + } + } + ] +} +``` + + أنشئ تكوينك في [صفحة التكوينات](https://app.portkey.ai/configs) في لوحة تحكم Portkey. + + + يمكن تحديث التكوينات في أي وقت لضبط الضوابط دون التأثير على التطبيقات قيد التشغيل. + + + + + ### الخطوة 3: تطبيق ضوابط الوصول + + أنشئ مفاتيح API خاصة بالمستخدم تقوم تلقائياً بـ: + - تتبع الاستخدام لكل مستخدم/فريق بمساعدة المفاتيح الافتراضية + - تطبيق التكوينات المناسبة لتوجيه الطلبات + - جمع البيانات الوصفية ذات الصلة لتصفية السجلات + - فرض أذونات الوصول + + أنشئ مفاتيح API من خلال [تطبيق Portkey](https://app.portkey.ai/) + + مثال باستخدام 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"] + ) + ``` + + للحصول على تعليمات تفصيلية لإدارة المفاتيح، راجع [وثائق Portkey](https://portkey.ai/docs). + + + + ### الخطوة 4: النشر والمراقبة + بعد توزيع مفاتيح API على أعضاء فريقك، يصبح إعداد CrewAI الجاهز للمؤسسة جاهزاً للعمل. يمكن لكل عضو في الفريق الآن استخدام مفاتيح API المخصصة له مع مستويات وصول وضوابط ميزانية مناسبة. + + راقب الاستخدام في لوحة تحكم Portkey: + - تتبع التكاليف حسب القسم + - أنماط استخدام النماذج + - حجم الطلبات + - معدلات الأخطاء + + + + + +### ميزات المؤسسة متاحة الآن +**تكامل CrewAI الخاص بك يتضمن الآن:** +- ضوابط ميزانية للأقسام +- حوكمة الوصول للنماذج +- تتبع الاستخدام والإسناد +- حواجز أمان +- ميزات الموثوقية + + +## الأسئلة الشائعة + + + + يضيف Portkey جاهزية الإنتاج لـ CrewAI من خلال مراقبة شاملة (تتبعات وسجلات ومقاييس) وميزات موثوقية (احتياط وإعادة محاولة وتخزين مؤقت) والوصول إلى أكثر من 200 نموذج LLM عبر واجهة موحدة. هذا يسهّل تصحيح الأخطاء وتحسين وتوسيع تطبيقات الوكلاء. + + + + نعم! يتكامل Portkey بسلاسة مع تطبيقات CrewAI الحالية. ما عليك سوى تحديث كود تكوين LLM بالنسخة المُمكّنة من Portkey. يبقى باقي كود الوكيل والطاقم دون تغيير. + + + + يدعم Portkey جميع ميزات CrewAI، بما في ذلك الوكلاء والأدوات وسير العمل مع تدخل بشري وجميع أنواع عمليات المهام (تسلسلي وهرمي وغيرها). يضيف المراقبة والموثوقية دون تقييد أي من وظائف الإطار. + + + + نعم، يتيح لك Portkey استخدام `trace_id` متسق عبر وكلاء متعددين في طاقم لتتبع سير العمل بالكامل. هذا مفيد بشكل خاص للطواقم المعقدة حيث تريد فهم مسار التنفيذ الكامل عبر وكلاء متعددين. + + + + يتيح لك Portkey إضافة بيانات وصفية مخصصة لتكوين LLM، والتي يمكنك استخدامها للتصفية. أضف حقولاً مثل `crew_name` أو `crew_type` أو `session_id` للعثور على عمليات تنفيذ طاقم محددة وتحليلها بسهولة. + + + + نعم! يستخدم Portkey مفاتيح API الخاصة بك لمزودي LLM المختلفين. يخزنها بشكل آمن كمفاتيح افتراضية، مما يتيح لك إدارة وتدوير المفاتيح بسهولة دون تغيير كودك. + + + + +## الموارد + + + +

وثائق CrewAI الرسمية

+ + +

احصل على إرشادات مخصصة لتنفيذ هذا التكامل

+ + diff --git a/docs/v1.15.1/ar/observability/tracing.mdx b/docs/v1.15.1/ar/observability/tracing.mdx new file mode 100644 index 000000000..234a62fcd --- /dev/null +++ b/docs/v1.15.1/ar/observability/tracing.mdx @@ -0,0 +1,214 @@ +--- +title: تتبع CrewAI +description: التتبع المدمج لطواقم وتدفقات CrewAI مع منصة CrewAI AMP +icon: magnifying-glass-chart +mode: "wide" +--- + +# التتبع المدمج في CrewAI + +يوفر CrewAI إمكانيات تتبع مدمجة تتيح لك مراقبة وتصحيح أخطاء الطواقم والتدفقات في الوقت الفعلي. يوضح هذا الدليل كيفية تفعيل التتبع لكل من **الطواقم** و**التدفقات** باستخدام منصة المراقبة المتكاملة في CrewAI. + +> **ما هو تتبع CrewAI؟** يوفر التتبع المدمج في CrewAI مراقبة شاملة لوكلاء الذكاء الاصطناعي، بما في ذلك قرارات الوكلاء وجداول تنفيذ المهام واستخدام الأدوات واستدعاءات LLM - كل ذلك متاح عبر [منصة CrewAI AMP](https://app.crewai.com). + +![واجهة تتبع CrewAI](/images/crewai-tracing.png) + +## المتطلبات الأساسية + +قبل أن تتمكن من استخدام تتبع CrewAI، تحتاج إلى: + +1. **حساب CrewAI AMP**: سجّل للحصول على حساب مجاني على [app.crewai.com](https://app.crewai.com) +2. **مصادقة CLI**: استخدم CLI الخاص بـ CrewAI لمصادقة بيئتك المحلية + +```bash +crewai login +``` + +## تعليمات الإعداد + +### الخطوة 1: إنشاء حساب CrewAI AMP + +قم بزيارة [app.crewai.com](https://app.crewai.com) وأنشئ حسابك المجاني. سيمنحك هذا الوصول إلى منصة CrewAI AMP حيث يمكنك عرض التتبعات والمقاييس وإدارة طواقمك. + +### الخطوة 2: تثبيت CLI الخاص بـ CrewAI والمصادقة + +إذا لم تكن قد فعلت ذلك بالفعل، ثبّت CrewAI مع أدوات CLI: + +```bash +uv add 'crewai[tools]' +``` + +ثم صادق على CLI مع حساب CrewAI AMP الخاص بك: + +```bash +crewai login +``` + +سيقوم هذا الأمر بـ: + +1. فتح متصفحك إلى صفحة المصادقة +2. طلب إدخال رمز الجهاز +3. مصادقة بيئتك المحلية مع حساب CrewAI AMP +4. تفعيل إمكانيات التتبع لتطويرك المحلي + +### الخطوة 3: تفعيل التتبع في طاقمك + +يمكنك تفعيل التتبع لطاقمك عبر تعيين معامل `tracing` إلى `True`: + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +# Define your agents +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, + tools=[SerperDevTool()], +) + +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, +) + +# Create tasks for your agents +research_task = 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, +) + +writing_task = 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.""", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Enable tracing in your crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + tracing=True, # Enable built-in tracing + verbose=True +) + +# Execute your crew +result = crew.kickoff() +``` + +### الخطوة 4: تفعيل التتبع في التدفق + +بالمثل، يمكنك تفعيل التتبع لتدفقات CrewAI: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class ExampleFlow(Flow[ExampleState]): + def __init__(self): + super().__init__(tracing=True) # Enable tracing for the flow + + @start() + def first_method(self): + print("Starting the flow") + self.state.counter = 1 + self.state.message = "Flow started" + return "continue" + + @listen("continue") + def second_method(self): + print("Continuing the flow") + self.state.counter += 1 + self.state.message = "Flow continued" + return "finish" + + @listen("finish") + def final_method(self): + print("Finishing the flow") + self.state.counter += 1 + self.state.message = "Flow completed" + +# Create and run the flow with tracing enabled +flow = ExampleFlow(tracing=True) +result = flow.kickoff() +``` + +### الخطوة 5: عرض التتبعات في لوحة تحكم CrewAI AMP + +بعد تشغيل الطاقم أو التدفق، يمكنك عرض التتبعات التي أنشأها تطبيق CrewAI في لوحة تحكم CrewAI AMP. يجب أن ترى خطوات تفصيلية لتفاعلات الوكلاء واستخدامات الأدوات واستدعاءات LLM. +ما عليك سوى النقر على الرابط أدناه لعرض التتبعات أو التوجه إلى علامة تبويب التتبعات في لوحة التحكم [هنا](https://app.crewai.com/crewai_plus/trace_batches) +![واجهة تتبع CrewAI](/images/view-traces.png) + +### البديل: إعداد متغير البيئة + +يمكنك أيضاً تفعيل التتبع عالمياً عبر تعيين متغير بيئة: + +```bash +export CREWAI_TRACING_ENABLED=true +``` + +أو إضافته إلى ملف `.env`: + +```env +CREWAI_TRACING_ENABLED=true +``` + +عند تعيين متغير البيئة هذا، ستُفعّل جميع الطواقم والتدفقات التتبع تلقائياً، حتى بدون تعيين `tracing=True` صراحةً. + +## عرض التتبعات + +### الوصول إلى لوحة تحكم CrewAI AMP + +1. قم بزيارة [app.crewai.com](https://app.crewai.com) وسجّل الدخول إلى حسابك +2. انتقل إلى لوحة تحكم مشروعك +3. انقر على علامة تبويب **التتبعات** لعرض تفاصيل التنفيذ + +### ما ستراه في التتبعات + +يوفر تتبع CrewAI رؤية شاملة لـ: + +- **قرارات الوكلاء**: شاهد كيف يفكر الوكلاء في المهام ويتخذون القرارات +- **جدول تنفيذ المهام**: تمثيل مرئي لتسلسلات المهام والتبعيات +- **استخدام الأدوات**: مراقبة الأدوات المستدعاة ونتائجها +- **استدعاءات LLM**: تتبع جميع تفاعلات نماذج اللغة، بما في ذلك الموجهات والاستجابات +- **مقاييس الأداء**: أوقات التنفيذ واستخدام الرموز المميزة والتكاليف +- **تتبع الأخطاء**: معلومات تفصيلية عن الأخطاء وتتبعات المكدس + +### ميزات التتبع + +- **جدول التنفيذ**: انقر عبر مراحل التنفيذ المختلفة +- **سجلات تفصيلية**: الوصول إلى سجلات شاملة لتصحيح الأخطاء +- **تحليلات الأداء**: حلّل أنماط التنفيذ وحسّن الأداء +- **إمكانيات التصدير**: حمّل التتبعات لمزيد من التحليل + +### مشكلات المصادقة + +إذا واجهت مشاكل في المصادقة: + +1. تأكد من تسجيل الدخول: `crewai login` +2. تحقق من اتصال الإنترنت +3. تحقق من حسابك على [app.crewai.com](https://app.crewai.com) + +### التتبعات لا تظهر + +إذا لم تظهر التتبعات في لوحة التحكم: + +1. تأكد من تعيين `tracing=True` في الطاقم/التدفق +2. تحقق من `CREWAI_TRACING_ENABLED=true` إذا كنت تستخدم متغيرات البيئة +3. تأكد من المصادقة عبر `crewai login` +4. تحقق من أن الطاقم/التدفق قيد التنفيذ فعلاً diff --git a/docs/v1.15.1/ar/observability/truefoundry.mdx b/docs/v1.15.1/ar/observability/truefoundry.mdx new file mode 100644 index 000000000..9260f43fc --- /dev/null +++ b/docs/v1.15.1/ar/observability/truefoundry.mdx @@ -0,0 +1,146 @@ +--- +title: تكامل TrueFoundry +icon: chart-line +mode: "wide" +--- + +توفر TrueFoundry [بوابة ذكاء اصطناعي](https://www.truefoundry.com/ai-gateway) جاهزة للمؤسسات يمكنها التكامل مع أطر العمل الوكيلية مثل CrewAI وتوفير الحوكمة والمراقبة لتطبيقات الذكاء الاصطناعي. تعمل بوابة TrueFoundry AI كواجهة موحدة للوصول إلى LLM، وتوفر: + +- **وصول موحد لـ API**: الاتصال بأكثر من 250 نموذج LLM (OpenAI وClaude وGemini وGroq وMistral) عبر API واحد +- **زمن استجابة منخفض**: زمن استجابة داخلي أقل من 3 مللي ثانية مع توجيه ذكي وموازنة أحمال +- **أمان المؤسسة**: امتثال SOC 2 وHIPAA وGDPR مع RBAC وتسجيل المراجعة +- **إدارة الحصص والتكاليف**: حصص قائمة على الرموز المميزة وتحديد المعدل وتتبع استخدام شامل +- **المراقبة**: تسجيل كامل للطلبات/الاستجابات ومقاييس وتتبعات مع احتفاظ قابل للتخصيص + +## كيف يتكامل TrueFoundry مع CrewAI + + +### التثبيت والإعداد + + + +```bash +pip install crewai +``` + + + +1. سجّل في [حساب TrueFoundry](https://www.truefoundry.com/register) +2. اتبع الخطوات هنا في [البدء السريع](https://docs.truefoundry.com/gateway/quick-start) + + + +![إعداد كود TrueFoundry](/images/new-code-snippet.png) + +```python +from crewai import LLM + +# Create an LLM instance with TrueFoundry AI Gateway +truefoundry_llm = LLM( + model="openai-main/gpt-4o", # Similarly, you can call any model from any provider + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Use in your CrewAI agents +from crewai import Agent + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + llm=truefoundry_llm, + verbose=True + ) +``` + + + +### مثال كامل على CrewAI + +```python +from crewai import Agent, Task, Crew, LLM + +# Configure LLM with TrueFoundry +llm = LLM( + model="openai-main/gpt-4o", + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Create agents +researcher = Agent( + role='Research Analyst', + goal='Conduct detailed market research', + backstory='Expert market analyst with attention to detail', + llm=llm, + verbose=True +) + +writer = Agent( + role='Content Writer', + goal='Create comprehensive reports', + backstory='Experienced technical writer', + llm=llm, + verbose=True +) + +# Create tasks +research_task = Task( + description='Research AI market trends for 2024', + agent=researcher, + expected_output='Comprehensive research summary' +) + +writing_task = Task( + description='Create a market research report', + agent=writer, + expected_output='Well-structured report with insights', + context=[research_task] +) + +# Create and execute crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +result = crew.kickoff() +``` + +### المراقبة والحوكمة + +راقب وكلاء CrewAI من خلال علامة تبويب المقاييس في TrueFoundry: +![مقاييس TrueFoundry](/images/gateway-metrics.png) + +مع بوابة الذكاء الاصطناعي من TrueFoundry، يمكنك مراقبة وتحليل: + +- **مقاييس الأداء**: تتبع مقاييس زمن الاستجابة الرئيسية مثل زمن استجابة الطلب ووقت أول رمز (TTFS) وزمن الاستجابة بين الرموز (ITL) بنسب مئوية P99 وP90 وP50 +- **التكلفة واستخدام الرموز المميزة**: احصل على رؤية لتكاليف تطبيقك مع تفاصيل دقيقة لرموز الإدخال/الإخراج والنفقات المرتبطة لكل نموذج +- **أنماط الاستخدام**: افهم كيف يُستخدم تطبيقك مع تحليلات تفصيلية لنشاط المستخدم وتوزيع النماذج والاستخدام حسب الفريق +- **تحديد المعدل وموازنة الأحمال**: يمكنك إعداد تحديد المعدل وموازنة الأحمال والاحتياط لنماذجك + +## التتبع + +لفهم أعمق حول التتبع، يرجى مراجعة [البدء بالتتبع](https://docs.truefoundry.com/docs/tracing/tracing-getting-started). للتتبع، يمكنك إضافة Traceloop SDK: + +```bash +pip install traceloop-sdk +``` + +```python +from traceloop.sdk import Traceloop + +# Initialize enhanced tracing +Traceloop.init( + api_endpoint="https://your-truefoundry-endpoint/api/tracing", + headers={ + "Authorization": f"Bearer {your_truefoundry_pat_token}", + "TFY-Tracing-Project": "your_project_name", + }, +) +``` + +يوفر هذا ارتباط تتبع إضافي عبر سير عمل CrewAI بالكامل. +![تتبع CrewAI مع TrueFoundry](/images/tracing_crewai.png) diff --git a/docs/v1.15.1/ar/observability/weave.mdx b/docs/v1.15.1/ar/observability/weave.mdx new file mode 100644 index 000000000..c2ded9a86 --- /dev/null +++ b/docs/v1.15.1/ar/observability/weave.mdx @@ -0,0 +1,125 @@ +--- +title: تكامل Weave +description: تعرّف على كيفية استخدام Weights & Biases (W&B) Weave لتتبع وتجربة وتقييم وتحسين تطبيقات CrewAI. +icon: radar +mode: "wide" +--- + +# نظرة عامة على Weave + +[Weights & Biases (W&B) Weave](https://weave-docs.wandb.ai/) هو إطار عمل لتتبع وتجربة وتقييم ونشر وتحسين التطبيقات المبنية على نماذج اللغة الكبيرة. + +![نظرة عامة على استخدام تتبع W&B Weave مع CrewAI](/images/weave-tracing.gif) + +يوفر Weave دعماً شاملاً لكل مرحلة من مراحل تطوير تطبيق CrewAI: + +- **التتبع والمراقبة**: تتبع تلقائي لاستدعاءات LLM ومنطق التطبيق لتصحيح الأخطاء وتحليل أنظمة الإنتاج +- **التكرار المنهجي**: تحسين والتكرار على الموجهات ومجموعات البيانات والنماذج +- **التقييم**: استخدام مقيّمين مخصصين أو مُعدّين مسبقاً لتقييم أداء الوكلاء وتحسينه بشكل منهجي +- **حواجز الحماية**: حماية وكلائك بحماية مسبقة ولاحقة للإشراف على المحتوى وسلامة الموجهات + +يلتقط Weave التتبعات تلقائياً لتطبيقات CrewAI، مما يمكّنك من مراقبة وتحليل أداء وكلائك وتفاعلاتهم وتدفق التنفيذ. يساعدك هذا في بناء مجموعات بيانات تقييم أفضل وتحسين سير عمل وكلائك. + +## تعليمات الإعداد + + + + ```shell + pip install crewai weave + ``` + + + سجّل في [حساب Weights & Biases](https://wandb.ai) إذا لم تكن قد فعلت ذلك بالفعل. ستحتاج إليه لعرض التتبعات والمقاييس. + + + أضف الكود التالي إلى تطبيقك: + + ```python + import weave + + # Initialize Weave with your project name + weave.init(project_name="crewai_demo") + ``` + + بعد التهيئة، سيوفر Weave عنوان URL حيث يمكنك عرض التتبعات والمقاييس. + + + ```python + from crewai import Agent, Task, Crew, LLM, Process + + # Create an LLM with a temperature of 0 to ensure deterministic outputs + llm = LLM(model="gpt-4o", temperature=0) + + # Create agents + 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, + ) + + # Create tasks + 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 + ) + + # Create a crew + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential, + ) + + # Run the crew + result = crew.kickoff(inputs={"topic": "AI in material science"}) + print(result) + ``` + + + بعد تشغيل تطبيق CrewAI، قم بزيارة عنوان URL الذي وفره Weave أثناء التهيئة لعرض: + - استدعاءات LLM وبياناتها الوصفية + - تفاعلات الوكلاء وتدفق تنفيذ المهام + - مقاييس الأداء مثل زمن الاستجابة واستخدام الرموز المميزة + - أي أخطاء أو مشكلات حدثت أثناء التنفيذ + + + Weave tracing example with CrewAI + + + + +## الميزات + +- يلتقط Weave تلقائياً جميع عمليات CrewAI: تفاعلات الوكلاء وتنفيذ المهام؛ استدعاءات LLM مع البيانات الوصفية واستخدام الرموز المميزة؛ استخدام الأدوات ونتائجها. +- يدعم التكامل جميع طرق تنفيذ CrewAI: `kickoff()` و`kickoff_for_each()` و`kickoff_async()` و`kickoff_for_each_async()`. +- تتبع تلقائي لجميع [أدوات crewAI](https://github.com/crewAIInc/crewAI-tools). +- دعم ميزة التدفق مع تصحيح المزخرفات (`@start` و`@listen` و`@router` و`@or_` و`@and_`). +- تتبع حواجز الحماية المخصصة المُمررة لمهام CrewAI `Task` باستخدام `@weave.op()`. + +لمعلومات تفصيلية حول ما هو مدعوم، قم بزيارة [وثائق Weave CrewAI](https://weave-docs.wandb.ai/guides/integrations/crewai/#getting-started-with-flow). + +## الموارد + +- [وثائق Weave](https://weave-docs.wandb.ai) +- [مثال على لوحة معلومات 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) diff --git a/docs/v1.15.1/ar/quickstart.mdx b/docs/v1.15.1/ar/quickstart.mdx new file mode 100644 index 000000000..339156423 --- /dev/null +++ b/docs/v1.15.1/ar/quickstart.mdx @@ -0,0 +1,257 @@ +--- +title: البدء السريع +description: ابنِ أول Flow في CrewAI خلال دقائق — التنسيق والحالة وفريقًا بوكيل واحد ينتج تقريرًا فعليًا. +icon: rocket +mode: "wide" +--- + +### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills + +قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI. + +يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills` + + + +في هذا الدليل ستُنشئ **Flow** يحدد موضوع بحث، ويشغّل **طاقمًا بوكيل واحد** (باحث يستخدم البحث على الويب)، وينتهي بتقرير **Markdown** على القرص. يُعد Flow الطريقة الموصى بها لتنظيم التطبيقات الإنتاجية: يمتلك **الحالة** و**ترتيب التنفيذ**، بينما **الوكلاء** ينفّذون العمل داخل خطوة الطاقم. + +إذا لم تُكمل تثبيت CrewAI بعد، اتبع [دليل التثبيت](/ar/installation) أولًا. + +## المتطلبات الأساسية + +- بيئة Python وواجهة سطر أوامر CrewAI (راجع [التثبيت](/ar/installation)) +- نموذج لغوي مهيأ بالمفاتيح الصحيحة — راجع [LLMs](/ar/concepts/llms#setting-up-your-llm) +- مفتاح API من [Serper.dev](https://serper.dev/) (`SERPER_API_KEY`) للبحث على الويب في هذا الدرس + +## ابنِ أول Flow لك + + + + من الطرفية، أنشئ مشروع Flow (اسم المجلد يستخدم شرطة سفلية، مثل `latest_ai_flow`): + + + ```shell Terminal + crewai create flow latest-ai-flow + cd latest_ai_flow + ``` + + + يُنشئ ذلك تطبيق Flow ضمن `src/latest_ai_flow/`، بما في ذلك طاقمًا أوليًا في `crews/content_crew/` ستستبدله بطاقم بحث **بوكيل واحد** في الخطوات التالية. + + + + أنشئ `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc` (أنشئ مجلد `agents/` إذا لزم). تُملأ المتغيرات مثل `{topic}` من `crew.kickoff(inputs=...)`. + + ```jsonc agents/researcher.jsonc + { + "role": "باحث بيانات أول في {topic}", + "goal": "اكتشاف أحدث التطورات في {topic}", + "backstory": "أنت باحث يجد المعلومات الأكثر صلة ويعرضها بوضوح.", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true + } + } + ``` + + + + + أنشئ `src/latest_ai_flow/crews/content_crew/crew.jsonc`: + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "أجرِ بحثًا معمقًا عن {topic}. استخدم البحث على الويب للعثور على معلومات حديثة وموثوقة.", + "expected_output": "تقرير بصيغة Markdown بأقسام واضحة: الاتجاهات الرئيسية، أدوات أو شركات بارزة، والآثار. بين 800 و1200 كلمة تقريبًا. دون إحاطة المستند بأكمله بكتل كود.", + "agent": "researcher", + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true + } + ``` + + + + + استبدل `content_crew.py` المُولّد بمحمل صغير يحول `crew.jsonc` إلى `Crew`. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py + from pathlib import Path + + from crewai.project import load_crew + + + def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) + ``` + + + + + اربط الطاقم بـ Flow: خطوة `@start()` تضبط الموضوع في **الحالة**، وخطوة `@listen` تشغّل الطاقم. يظل `output_file` للمهمة يكتب `output/report.md`. + + ```python main.py + # src/latest_ai_flow/main.py + from pydantic import BaseModel + + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"الموضوع: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = kickoff_content_crew(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("اكتمل طاقم البحث.") + + @listen(run_research) + def summarize(self): + print("مسار التقرير: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() + ``` + + + إذا كان اسم الحزمة ليس `latest_ai_flow`، عدّل استيراد `kickoff_content_crew` ليطابق مسار الوحدة في مشروعك. + + + + + في جذر المشروع، ضبط `.env`: + + - `SERPER_API_KEY` — من [Serper.dev](https://serper.dev/) + - مفاتيح مزوّد النموذج حسب الحاجة — راجع [إعداد LLM](/ar/concepts/llms#setting-up-your-llm) + + + + + ```shell Terminal + crewai install + crewai run + ``` + + + يُنفّذ `crewai run` نقطة دخول Flow المعرّفة في المشروع (نفس أمر الطواقم؛ نوع المشروع `"flow"` في `pyproject.toml`). + + + + يجب أن ترى سجلات من Flow والطاقم. افتح **`output/report.md`** للتقرير المُولَّد (مقتطف): + + + ```markdown output/report.md + # وكلاء الذكاء الاصطناعي: المشهد والاتجاهات الحديثة + + ## ملخص تنفيذي + … + + ## أبرز الاتجاهات + - **استخدام الأدوات والتنسيق** — … + - **التبني المؤسسي** — … + + ## الآثار + … + ``` + + + سيكون الملف الفعلي أطول ويعكس نتائج بحث مباشرة. + + + +## كيف يترابط هذا + +1. **Flow** — يشغّل `LatestAiFlow` أولًا `prepare_topic` ثم `run_research` ثم `summarize`. الحالة (`topic`، `report`) على Flow. +2. **الطاقم** — يحمّل `kickoff_content_crew` ملف `crew.jsonc` ويشغّل مهمة واحدة بوكيل واحد: الباحث يستخدم **Serper** للبحث على الويب ثم يكتب التقرير. +3. **المُخرَج** — يكتب `output_file` للمهمة التقرير في `output/report.md`. + +للتعمق في أنماط Flow (التوجيه، الاستمرارية، الإنسان في الحلقة)، راجع [ابنِ أول Flow](/ar/guides/flows/first-flow) و[Flows](/ar/concepts/flows). للطواقم دون Flow، راجع [Crews](/ar/concepts/crews). لوكيل `Agent` واحد و`kickoff()` بلا مهام، راجع [Agents](/ar/concepts/agents#direct-agent-interaction-with-kickoff). + + +أصبح لديك Flow كامل مع طاقم وكيل وتقرير محفوظ — قاعدة قوية لإضافة خطوات أو طواقم أو أدوات. + + +### اتساق التسمية + +يجب أن تطابق الأسماء في `crew.jsonc` الملفات والمراجع: + +- `agents: ["researcher"]` يحمّل `agents/researcher.jsonc` +- `tasks[].agent: "researcher"` يربط المهمة بذلك الـ agent + +## النشر + +ادفع Flow إلى **[CrewAI AMP](https://app.crewai.com)** بعد أن يعمل محليًا ويكون المشروع في مستودع **GitHub**. من جذر المشروع: + + +```bash المصادقة +crewai login +``` + +```bash إنشاء نشر +crewai deploy create +``` + +```bash الحالة والسجلات +crewai deploy status +crewai deploy logs +``` + +```bash إرسال التحديثات بعد تغيير الكود +crewai deploy push +``` + +```bash عرض النشرات أو حذفها +crewai deploy list +crewai deploy remove +``` + + + + غالبًا ما يستغرق **النشر الأول حوالي دقيقة**. المتطلبات الكاملة ومسار الواجهة الويب في [النشر على AMP](/ar/enterprise/guides/deploy-to-amp). + + + + + النشر على AMP خطوة بخطوة (CLI ولوحة التحكم). + + + ناقش الأفكار وشارك مشاريعك وتواصل مع مطوري CrewAI. + + diff --git a/docs/v1.15.1/ar/skills.mdx b/docs/v1.15.1/ar/skills.mdx new file mode 100644 index 000000000..57c189c96 --- /dev/null +++ b/docs/v1.15.1/ar/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: ثبّت crewaiinc/skills من السجل الرسمي على skills.sh—Flows وCrews ووكلاء مرتبطون بالوثائق لـ Claude Code وCursor وCodex وغيرها. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**امنح وكيل البرمجة سياق CrewAI في أمر واحد.** + +تُنشر **Skills** الخاصة بـ CrewAI على **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**—السجل الرسمي لـ `crewaiinc/skills`، بما في ذلك كل مهارة (مثل **design-agent** و**getting-started** و**design-task** و**ask-docs**) وإحصاءات التثبيت والتدقيقات. تعلّم وكلاء البرمجة—مثل Claude Code وCursor وCodex—هيكلة Flows وضبط Crews واستخدام الأدوات واتباع أنماط CrewAI. نفّذ الأمر أدناه (أو الصقه في الوكيل). + +```shell Terminal +npx skills add crewaiinc/skills +``` + +يضيف ذلك حزمة المهارات إلى سير عمل الوكيل لتطبيق اتفاقيات CrewAI دون إعادة شرح الإطار في كل جلسة. المصدر والقضايا على [GitHub](https://github.com/crewAIInc/skills). + +## ما يحصل عليه الوكيل + +- **Flows** — تطبيقات ذات حالة وخطوات وkickoffs للـ crew على نمط CrewAI +- **Crews والوكلاء** — أنماط JSON-first (`crew.jsonc` و `agents/*.jsonc`)، أدوار، مهام، وتفويض +- **الأدوات والتكاملات** — ربط الوكلاء بالبحث وواجهات API وأدوات CrewAI الشائعة +- **هيكل المشروع** — مواءمة مع قوالب CLI واتفاقيات المستودع +- **أنماط محدثة** — تتبع المهارات وثائق CrewAI والممارسات الموصى بها + +## تعرّف أكثر على هذا الموقع + + + + استخدام `AGENTS.md` وسير عمل وكلاء البرمجة مع CrewAI. + + + ابنِ أول Flow وcrew من البداية للنهاية. + + + ثبّت CrewAI CLI وحزمة Python. + + + القائمة الرسمية لـ `crewaiinc/skills`—المهارات والتثبيتات والتدقيقات. + + + مصدر الحزمة والتحديثات والقضايا. + + + +### فيديو: CrewAI مع مهارات وكلاء البرمجة + + + +### 11. Login + +Authenticate with CrewAI AMP using a secure device code flow (no email entry required). + +```shell Terminal +crewai login +``` + +What happens: + +- A verification URL and short code are displayed in your terminal +- Your browser opens to the verification URL +- Enter/confirm the code to complete authentication + +Notes: + +- The OAuth2 provider and domain are configured via `crewai config` (defaults use `login.crewai.com`) +- After successful login, the CLI also attempts to authenticate to the Tool Repository automatically +- If you reset your configuration, run `crewai login` again to re-authenticate + +### 12. API Keys + +When running the `crewai create crew` command, the CLI shows a list of available LLM providers, followed by model selection for your chosen provider. The selected model is saved in the generated `.env` file and each generated agent JSONC file can set its own `llm`. + +Once you've selected an LLM provider and model, you will be prompted for API keys. + +#### Available LLM Providers + +Here's a list of the most popular LLM providers suggested by the CLI: + +- OpenAI +- Groq +- Anthropic +- Google Gemini +- SambaNova + +When you select a provider, the CLI will then show you available models for that provider and prompt you to enter your API key. + +#### Other Options + +If you select "other", you will be able to select from a list of LiteLLM supported providers. + +When you select a provider, the CLI will prompt you to enter the Key name and the API key. + +See the following link for each provider's key name: + +- [LiteLLM Providers](https://docs.litellm.ai/docs/providers) + +### 13. Configuration Management + +Manage CLI configuration settings for CrewAI. + +```shell Terminal +crewai config [COMMAND] [OPTIONS] +``` + +#### Commands: + +- `list`: Display all CLI configuration parameters + +```shell Terminal +crewai config list +``` + +- `set`: Set a CLI configuration parameter + +```shell Terminal +crewai config set +``` + +- `reset`: Reset all CLI configuration parameters to default values + +```shell Terminal +crewai config reset +``` + +#### Available Configuration Parameters + +- `enterprise_base_url`: Base URL of the CrewAI AMP instance +- `oauth2_provider`: OAuth2 provider used for authentication (e.g., workos, okta, auth0) +- `oauth2_audience`: OAuth2 audience value, typically used to identify the target API or resource +- `oauth2_client_id`: OAuth2 client ID issued by the provider, used during authentication requests +- `oauth2_domain`: OAuth2 provider's domain (e.g., your-org.auth0.com) used for issuing tokens + +#### Examples + +Display current configuration: + +```shell Terminal +crewai config list +``` + +Example output: +| Setting | Value | Description | +| :------------------ | :----------------------- | :---------------------------------------------------------- | +| enterprise_base_url | https://app.crewai.com | Base URL of the CrewAI AMP instance | +| org_name | Not set | Name of the currently active organization | +| org_uuid | Not set | UUID of the currently active organization | +| oauth2_provider | workos | OAuth2 provider (e.g., workos, okta, auth0) | +| oauth2_audience | client_01YYY | Audience identifying the target API/resource | +| oauth2_client_id | client_01XXX | OAuth2 client ID issued by the provider | +| oauth2_domain | login.crewai.com | Provider domain (e.g., your-org.auth0.com) | + +Set the enterprise base URL: + +```shell Terminal +crewai config set enterprise_base_url https://my-enterprise.crewai.com +``` + +Set OAuth2 provider: + +```shell Terminal +crewai config set oauth2_provider auth0 +``` + +Set OAuth2 domain: + +```shell Terminal +crewai config set oauth2_domain my-company.auth0.com +``` + +Reset all configuration to defaults: + +```shell Terminal +crewai config reset +``` + + + After resetting configuration, re-run `crewai login` to authenticate again. + + +### 14. Trace Management + +Manage trace collection preferences for your Crew and Flow executions. + +```shell Terminal +crewai traces [COMMAND] +``` + +#### Commands: + +- `enable`: Enable trace collection for crew/flow executions + +```shell Terminal +crewai traces enable +``` + +- `disable`: Disable trace collection for crew/flow executions + +```shell Terminal +crewai traces disable +``` + +- `status`: Show current trace collection status + +```shell Terminal +crewai traces status +``` + +#### How Tracing Works + +Trace collection is controlled by checking three settings in priority order: + +1. **Explicit flag in code** (highest priority - can enable OR disable): + + ```python + crew = Crew(agents=[...], tasks=[...], tracing=True) # Always enable + crew = Crew(agents=[...], tasks=[...], tracing=False) # Always disable + crew = Crew(agents=[...], tasks=[...]) # Check lower priorities (default) + ``` + + - `tracing=True` will **always enable** tracing (overrides everything) + - `tracing=False` will **always disable** tracing (overrides everything) + - `tracing=None` or omitted will check lower priority settings + +2. **Environment variable** (second priority): + + ```env + CREWAI_TRACING_ENABLED=true + ``` + + - Checked only if `tracing` is not explicitly set to `True` or `False` in code + - Set to `true` or `1` to enable tracing + +3. **User preference** (lowest priority): + ```shell Terminal + crewai traces enable + ``` + - Checked only if `tracing` is not set in code and `CREWAI_TRACING_ENABLED` is not set to `true` + - Running `crewai traces enable` is sufficient to enable tracing by itself + + +**To enable tracing**, use any one of these methods: +- Set `tracing=True` in your Crew/Flow code, OR +- Add `CREWAI_TRACING_ENABLED=true` to your `.env` file, OR +- Run `crewai traces enable` + +**To disable tracing**, use any ONE of these methods: + +- Set `tracing=False` in your Crew/Flow code (overrides everything), OR +- Remove or set to `false` the `CREWAI_TRACING_ENABLED` env var, OR +- Run `crewai traces disable` + +Higher priority settings override lower ones. + + + + + For more information about tracing, see the [Tracing + documentation](/observability/tracing). + + + + CrewAI CLI handles authentication to the Tool Repository automatically when + adding packages to your project. Just append `crewai` before any `uv` command + to use it. E.g. `crewai uv add requests`. For more information, see [Tool + Repository](https://docs.crewai.com/enterprise/features/tool-repository) docs. + + + + Configuration settings are stored in `~/.config/crewai/settings.json`. Some + settings like organization name and UUID are read-only and managed through + authentication and organization commands. Tool repository related settings are + hidden and cannot be set directly by users. + diff --git a/docs/v1.15.1/en/concepts/collaboration.mdx b/docs/v1.15.1/en/concepts/collaboration.mdx new file mode 100644 index 000000000..867db5b33 --- /dev/null +++ b/docs/v1.15.1/en/concepts/collaboration.mdx @@ -0,0 +1,363 @@ +--- +title: Collaboration +description: How to enable agents to work together, delegate tasks, and communicate effectively within CrewAI teams. +icon: screen-users +mode: "wide" +--- + +## Overview + +Collaboration in CrewAI enables agents to work together as a team by delegating tasks and asking questions to leverage each other's expertise. When `allow_delegation=True`, agents automatically gain access to powerful collaboration tools. + +## Quick Start: Enable Collaboration + +```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 +) +``` + +## How Agent Collaboration Works + +When `allow_delegation=True`, CrewAI automatically provides agents with two powerful tools: + +### 1. **Delegate Work Tool** +Allows agents to assign tasks to teammates with specific expertise. + +```python +# Agent automatically gets this tool: +# Delegate work to coworker(task: str, context: str, coworker: str) +``` + +### 2. **Ask Question Tool** +Enables agents to ask specific questions to gather information from colleagues. + +```python +# Agent automatically gets this tool: +# Ask question to coworker(question: str, context: str, coworker: str) +``` + +## Collaboration in Action + +Here's a complete example showing agents collaborating on a content creation task: + +```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() +``` + +## Collaboration Patterns + +### Pattern 1: Research → Write → Edit +```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 +) +``` + +### Pattern 2: Collaborative Single Task +```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 +) +``` + +## Hierarchical Collaboration + +For complex projects, use a hierarchical process with a manager agent: + +```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 +) +``` + +## Best Practices for Collaboration + +### 1. **Clear Role Definition** +```python +# ✅ Good: Specific, complementary roles +researcher = Agent(role="Market Research Analyst", ...) +writer = Agent(role="Technical Content Writer", ...) + +# ❌ Avoid: Overlapping or vague roles +agent1 = Agent(role="General Assistant", ...) +agent2 = Agent(role="Helper", ...) +``` + +### 2. **Strategic Delegation Enabling** +```python +# ✅ Enable delegation for coordinators and generalists +lead_agent = Agent( + role="Content Lead", + allow_delegation=True, # Can delegate to specialists + ... +) + +# ✅ Disable for focused specialists (optional) +specialist_agent = Agent( + role="Data Analyst", + allow_delegation=False, # Focuses on core expertise + ... +) +``` + +### 3. **Context Sharing** +```python +# ✅ Use context parameter for task dependencies +writing_task = Task( + description="Write article based on research", + agent=writer, + context=[research_task], # Shares research results + ... +) +``` + +### 4. **Clear Task Descriptions** +```python +# ✅ Specific, actionable descriptions +Task( + description="""Research competitors in the AI chatbot space. + Focus on: pricing models, key features, target markets. + Provide data in a structured format.""", + ... +) + +# ❌ Vague descriptions that don't guide collaboration +Task(description="Do some research about chatbots", ...) +``` + +## Troubleshooting Collaboration + +### Issue: Agents Not Collaborating +**Symptoms:** Agents work in isolation, no delegation occurs +```python +# ✅ Solution: Ensure delegation is enabled +agent = Agent( + role="...", + allow_delegation=True, # This is required! + ... +) +``` + +### Issue: Too Much Back-and-Forth +**Symptoms:** Agents ask excessive questions, slow progress +```python +# ✅ Solution: Provide better context and specific roles +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.""", + ... +) +``` + +### Issue: Delegation Loops +**Symptoms:** Agents delegate back and forth indefinitely +```python +# ✅ Solution: Clear hierarchy and responsibilities +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) +``` + +## Advanced Collaboration Features + +### Custom Collaboration Rules +```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 +) +``` + +### Monitoring Collaboration +```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 +) +``` + +## Memory and Learning + +Enable agents to remember past collaborations: + +```python +agent = Agent( + role="Content Lead", + memory=True, # Remembers past interactions + allow_delegation=True, + verbose=True +) +``` + +With memory enabled, agents learn from previous collaborations and improve their delegation decisions over time. + +## Next Steps + +- **Try the examples**: Start with the basic collaboration example +- **Experiment with roles**: Test different agent role combinations +- **Monitor interactions**: Use `verbose=True` to see collaboration in action +- **Optimize task descriptions**: Clear tasks lead to better collaboration +- **Scale up**: Try hierarchical processes for complex projects + +Collaboration transforms individual AI agents into powerful teams that can tackle complex, multi-faceted challenges together. diff --git a/docs/v1.15.1/en/concepts/crews.mdx b/docs/v1.15.1/en/concepts/crews.mdx new file mode 100644 index 000000000..2c43b63c7 --- /dev/null +++ b/docs/v1.15.1/en/concepts/crews.mdx @@ -0,0 +1,458 @@ +--- +title: Crews +description: Understanding and utilizing crews in the crewAI framework with comprehensive attributes and functionalities. +icon: people-group +mode: "wide" +--- + +## Overview + +A crew in crewAI represents a collaborative group of agents working together to achieve a set of tasks. Each crew defines the strategy for task execution, agent collaboration, and the overall workflow. + +## Crew Attributes + +| Attribute | Parameters | Description | +| :------------------------------------ | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Tasks** | `tasks` | A list of tasks assigned to the crew. | +| **Agents** | `agents` | A list of agents that are part of the crew. | +| **Process** _(optional)_ | `process` | The process flow (e.g., sequential, hierarchical) the crew follows. Default is `sequential`. | +| **Verbose** _(optional)_ | `verbose` | The verbosity level for logging during execution. Defaults to `False`. | +| **Manager LLM** _(optional)_ | `manager_llm` | The language model used by the manager agent in a hierarchical process. **Required when using a hierarchical process.** | +| **Function Calling LLM** _(optional)_ | `function_calling_llm` | If passed, the crew will use this LLM to do function calling for tools for all agents in the crew. Each agent can have its own LLM, which overrides the crew's LLM for function calling. | +| **Config** _(optional)_ | `config` | Optional configuration settings for the crew, in `Json` or `Dict[str, Any]` format. | +| **Max RPM** _(optional)_ | `max_rpm` | Maximum requests per minute the crew adheres to during execution. Defaults to `None`. | +| **Memory** _(optional)_ | `memory` | Utilized for storing execution memories (short-term, long-term, entity memory). | | +| **Cache** _(optional)_ | `cache` | Specifies whether to use a cache for storing the results of tools' execution. Defaults to `True`. | +| **Embedder** _(optional)_ | `embedder` | Configuration for the embedder to be used by the crew. Mostly used by memory for now. Default is `{"provider": "openai"}`. | +| **Step Callback** _(optional)_ | `step_callback` | A function that is called after each step of every agent. This can be used to log the agent's actions or to perform other operations; it won't override the agent-specific `step_callback`. | +| **Task Callback** _(optional)_ | `task_callback` | A function that is called after the completion of each task. Useful for monitoring or additional operations post-task execution. | +| **Share Crew** _(optional)_ | `share_crew` | Whether you want to share the complete crew information and execution with the crewAI team to make the library better, and allow us to train models. | +| **Output Log File** _(optional)_ | `output_log_file` | Set to True to save logs as logs.txt in the current directory or provide a file path. Logs will be in JSON format if the filename ends in .json, otherwise .txt. Defaults to `None`. | +| **Manager Agent** _(optional)_ | `manager_agent` | `manager` sets a custom agent that will be used as a manager. | +| **Prompt File** _(optional)_ | `prompt_file` | Path to the prompt JSON file to be used for the crew. | +| **Planning** *(optional)* | `planning` | Adds planning ability to the Crew. When activated before each Crew iteration, all Crew data is sent to an AgentPlanner that will plan the tasks and this plan will be added to each task description. | +| **Planning LLM** *(optional)* | `planning_llm` | The language model used by the AgentPlanner in a planning process. | +| **Knowledge Sources** _(optional)_ | `knowledge_sources` | Knowledge sources available at the crew level, accessible to all the agents. | +| **Stream** _(optional)_ | `stream` | Enable streaming output to receive real-time updates during crew execution. Returns a `CrewStreamingOutput` object that can be iterated for chunks. Defaults to `False`. | +| **Chat LLM** _(optional)_ | `chat_llm` | The language model used to orchestrate `crewai chat` CLI interactions with the crew. Accepts a model name string or `LLM` instance. Defaults to `None`. | +| **Before Kickoff Callbacks** _(optional)_ | `before_kickoff_callbacks` | A list of callable functions executed **before** the crew starts. Each callback receives and can modify the inputs dict. Distinct from the `@before_kickoff` decorator. Defaults to `[]`. | +| **After Kickoff Callbacks** _(optional)_ | `after_kickoff_callbacks` | A list of callable functions executed **after** the crew finishes. Each callback receives and can modify the `CrewOutput`. Distinct from the `@after_kickoff` decorator. Defaults to `[]`. | +| **Tracing** _(optional)_ | `tracing` | Controls OpenTelemetry tracing for the crew. `True` = always enable, `False` = always disable, `None` = inherit from environment / user settings. Defaults to `None`. | +| **Skills** _(optional)_ | `skills` | A list of `Path` objects (skill search directories) or pre-loaded `Skill` objects applied to all agents in the crew. Defaults to `None`. | +| **Security Config** _(optional)_ | `security_config` | A `SecurityConfig` instance managing crew fingerprinting and identity. Defaults to `SecurityConfig()`. | +| **Checkpoint** _(optional)_ | `checkpoint` | Enables automatic checkpointing. Pass `True` for sensible defaults, a `CheckpointConfig` for full control, `False` to opt out, or `None` to inherit. See the [Checkpointing](#checkpointing) section below. Defaults to `None`. | + + +**Crew Max RPM**: 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. + + +## Creating Crews + +There are two common ways to create crews in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**. + +### JSONC Configuration (Recommended) + +New projects created with `crewai create crew ` use `crew.jsonc` for crew-level settings and tasks, plus one file per agent in `agents/`. + +`crewai run` automatically detects `crew.jsonc` or `crew.json`, loads the referenced agents, prompts for missing placeholders, and kicks off the crew. + +#### Example `crew.jsonc` + +```jsonc crew.jsonc +{ + "name": "Market Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research", + "description": "Research {topic} and collect the most relevant facts.", + "expected_output": "Structured research notes about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis", + "description": "Analyze the research and write a concise report.", + "expected_output": "A markdown report with findings and recommendations.", + "agent": "analyst", + "context": ["research"], + "output_file": "output/report.md" + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "AI Agents" + } +} +``` + +Each string in `agents` resolves to `agents/.jsonc` first, then `agents/.json`. + +```jsonc agents/researcher.jsonc +{ + "role": "{topic} Senior Researcher", + "goal": "Find accurate and current information about {topic}.", + "backstory": "You are a careful researcher who cites clear evidence.", + "llm": "openai/gpt-4o", + "tools": ["SerperDevTool"] +} +``` + + +Tasks run in the order they appear in `tasks` when `process` is `"sequential"`. + + +For hierarchical crews, set `"process": "hierarchical"` and provide either `manager_llm` or `manager_agent`. A `manager_agent` can reference an `agents/.jsonc` file that is not included in the top-level `agents` list. + +JSON crew definitions support crew-level fields such as `process`, `verbose`, `memory`, `cache`, `max_rpm`, `planning`, `planning_llm`, `manager_llm`, `manager_agent`, `function_calling_llm`, `output_log_file`, `stream`, `tracing`, `before_kickoff_callbacks`, and `after_kickoff_callbacks`. + +Python callbacks and custom classes use `{"python": "module.attribute"}`. Custom tools use `"custom:"` and load `tools/.py` at runtime. + + +Only run JSON crew projects from sources you trust. `custom:` tools and `{"python": "module.attribute"}` references execute local Python code when the crew loads. + + +### Classic Python/YAML Configuration + +Classic projects created with `crewai create crew --classic` use `crew.py`, `config/agents.yaml`, `config/tasks.yaml`, and the `@CrewBase`, `@agent`, `@task`, and `@crew` decorators. That pattern remains supported and is documented in [Using Annotations](/en/learn/using-annotations). + +### Direct Code Definition (Alternative) + +Alternatively, you can define the crew directly in code without using YAML configuration files. + +```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 + ) +``` +How to run the above code: + +```python code +YourCrewName().crew().kickoff(inputs={}) +``` + +In this example: + +- Agents and tasks are defined directly within the class without decorators. +- We manually create and manage the list of agents and tasks. +- This approach provides more control but can be less maintainable for larger projects. + +## Crew Output + +The output of a crew in the CrewAI framework is encapsulated within the `CrewOutput` class. +This class provides a structured way to access results of the crew's execution, including various formats such as raw strings, JSON, and Pydantic models. +The `CrewOutput` includes the results from the final task output, token usage, and individual task outputs. + +### Crew Output Attributes + +| Attribute | Parameters | Type | Description | +| :--------------- | :------------- | :------------------------- | :--------------------------------------------------------------------------------------------------- | +| **Raw** | `raw` | `str` | The raw output of the crew. This is the default format for the output. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | A Pydantic model object representing the structured output of the crew. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | A dictionary representing the JSON output of the crew. | +| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | A list of `TaskOutput` objects, each representing the output of a task in the crew. | +| **Token Usage** | `token_usage` | `Dict[str, Any]` | A summary of token usage, providing insights into the language model's performance during execution. | + +### Crew Output Methods and Properties + +| Method/Property | Description | +| :-------------- | :------------------------------------------------------------------------------------------------ | +| **json** | Returns the JSON string representation of the crew output if the output format is JSON. | +| **to_dict** | Converts the JSON and Pydantic outputs to a dictionary. | +| \***\*str\*\*** | Returns the string representation of the crew output, prioritizing Pydantic, then JSON, then raw. | + +### Accessing Crew Outputs + +Once a crew has been executed, its output can be accessed through the `output` attribute of the `Crew` object. The `CrewOutput` class provides various ways to interact with and present this output. + +#### Example + +```python Code +# Example crew execution +crew = Crew( + agents=[research_agent, writer_agent], + tasks=[research_task, write_article_task], + verbose=True +) + +crew_output = crew.kickoff() + +# Accessing the crew output +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}") +``` + +## Accessing Crew Logs + +You can see real time log of the crew execution, by setting `output_log_file` as a `True(Boolean)` or a `file_name(str)`. Supports logging of events as both `file_name.txt` and `file_name.json`. +In case of `True(Boolean)` will save as `logs.txt`. + +In case of `output_log_file` is set as `False(Boolean)` or `None`, the logs will not be populated. + +```python Code +# Save crew logs +crew = Crew(output_log_file = True) # Logs will be saved as logs.txt +crew = Crew(output_log_file = file_name) # Logs will be saved as file_name.txt +crew = Crew(output_log_file = file_name.txt) # Logs will be saved as file_name.txt +crew = Crew(output_log_file = file_name.json) # Logs will be saved as file_name.json +``` + + + +## Checkpointing + +Checkpointing lets a crew automatically save its state after key events (e.g. task completion) so that long-running or interrupted runs can be resumed exactly where they left off without re-executing completed tasks. + +### Quick Start + +Pass `checkpoint=True` to enable checkpointing with sensible defaults (saves to `.checkpoints/` after every task): + +```python Code +from crewai import Crew, Process + +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, write_task], + process=Process.sequential, + checkpoint=True, # saves to .checkpoints/ after every task +) + +crew.kickoff(inputs={"topic": "AI trends"}) +``` + +### Full Control with `CheckpointConfig` + +Use `CheckpointConfig` for fine-grained control over location, trigger events, storage backend, and retention: + +```python Code +from crewai import Crew, Process +from crewai.state.checkpoint_config import CheckpointConfig + +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, write_task], + process=Process.sequential, + checkpoint=CheckpointConfig( + location="./.checkpoints", # directory for JSON files (default) + on_events=["task_completed"], # trigger after each task (default) + max_checkpoints=5, # keep only the 5 most recent checkpoints + ), +) + +crew.kickoff(inputs={"topic": "AI trends"}) +``` + +### Resuming from a Checkpoint + +Use `Crew.from_checkpoint()` to restore a crew from a saved checkpoint file, then call `kickoff()` to resume: + +```python Code +# Resume from the most recent checkpoint +crew = Crew.from_checkpoint(".checkpoints/latest.json") +crew.kickoff() +``` + + +When restoring from a checkpoint, `checkpoint_inputs`, `checkpoint_train`, and `checkpoint_kickoff_event_id` are automatically reconstructed — you do not need to set these manually. + + +### `CheckpointConfig` Attributes + +| Attribute | Type | Default | Description | +| :----------------- | :------------------------------------- | :------------------- | :-------------------------------------------------------------------------------------------- | +| `location` | `str` | `"./.checkpoints"` | Storage destination. For `JsonProvider` this is a directory path; for `SqliteProvider` a database file path. | +| `on_events` | `list[str]` | `["task_completed"]` | Event types that trigger a checkpoint write. Use `["*"]` to checkpoint on every event. | +| `provider` | `JsonProvider \| SqliteProvider` | `JsonProvider()` | Storage backend. Defaults to `JsonProvider` (plain JSON files). | +| `max_checkpoints` | `int \| None` | `None` | Maximum checkpoints to keep. Oldest are pruned after each write. `None` keeps all. | + +## Memory Utilization + +Crews can utilize memory (short-term, long-term, and entity memory) to enhance their execution and learning over time. This feature allows crews to store and recall execution memories, aiding in decision-making and task execution strategies. + +## Cache Utilization + +Caches can be employed to store the results of tools' execution, making the process more efficient by reducing the need to re-execute identical tasks. + +## Crew Usage Metrics + +After the crew execution, you can access the `usage_metrics` attribute to view the language model (LLM) usage metrics for all tasks executed by the crew. This provides insights into operational efficiency and areas for improvement. + +```python Code +# Access the crew's usage metrics +crew = Crew(agents=[agent1, agent2], tasks=[task1, task2]) +crew.kickoff() +print(crew.usage_metrics) +``` + +## Crew Execution Process + +- **Sequential Process**: Tasks are executed one after another, allowing for a linear flow of work. +- **Hierarchical Process**: A manager agent coordinates the crew, delegating tasks and validating outcomes before proceeding. **Note**: A `manager_llm` or `manager_agent` is required for this process and it's essential for validating the process flow. + +### Kicking Off a Crew + +Once your crew is assembled, initiate the workflow with the `kickoff()` method. This starts the execution process according to the defined process flow. + +```python Code +# Start the crew's task execution +result = my_crew.kickoff() +print(result) +``` + +### Different Ways to Kick Off a Crew + +Once your crew is assembled, initiate the workflow with the appropriate kickoff method. CrewAI provides several methods for better control over the kickoff process. + +#### Synchronous Methods + +- `kickoff()`: Starts the execution process according to the defined process flow. +- `kickoff_for_each()`: Executes tasks sequentially for each provided input event or item in the collection. + +#### Asynchronous Methods + +CrewAI offers two approaches for async execution: + +| Method | Type | Description | +|--------|------|-------------| +| `akickoff()` | Native async | True async/await throughout the entire execution chain | +| `akickoff_for_each()` | Native async | Native async execution for each input in a list | +| `kickoff_async()` | Thread-based | Wraps synchronous execution in `asyncio.to_thread` | +| `kickoff_for_each_async()` | Thread-based | Thread-based async for each input in a list | + + +For high-concurrency workloads, `akickoff()` and `akickoff_for_each()` are recommended as they use native async for task execution, memory operations, and knowledge retrieval. + + +```python Code +# Start the crew's task execution +result = my_crew.kickoff() +print(result) + +# Example of using 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) + +# Example of using native async with akickoff +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.akickoff(inputs=inputs) +print(async_result) + +# Example of using native async with akickoff_for_each +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +async_results = await my_crew.akickoff_for_each(inputs=inputs_array) +for async_result in async_results: + print(async_result) + +# Example of using thread-based kickoff_async +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.kickoff_async(inputs=inputs) +print(async_result) + +# Example of using thread-based 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) +``` + +These methods provide flexibility in how you manage and execute tasks within your crew, allowing for both synchronous and asynchronous workflows tailored to your needs. For detailed async examples, see the [Kickoff Crew Asynchronously](/en/learn/kickoff-async) guide. + +### Streaming Crew Execution + +For real-time visibility into crew execution, you can enable streaming to receive output as it's generated: + +```python Code +# Enable streaming +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +# Iterate over streaming output +streaming = crew.kickoff(inputs={"topic": "AI"}) +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access final result +result = streaming.result +``` + +Learn more about streaming in the [Streaming Crew Execution](/en/learn/streaming-crew-execution) guide. + +### Replaying from a Specific Task + +You can now replay from a specific task using our CLI command `replay`. + +The replay feature in CrewAI allows you to replay from a specific task using the command-line interface (CLI). By running the command `crewai replay -t `, you can specify the `task_id` for the replay process. + +Kickoffs will now save the latest kickoffs returned task outputs locally for you to be able to replay from. + +### Replaying from a Specific Task Using the CLI + +To use the replay feature, follow these steps: + +1. Open your terminal or command prompt. +2. Navigate to the directory where your CrewAI project is located. +3. Run the following command: + +To view the latest kickoff task IDs, use: + +```shell +crewai log-tasks-outputs +``` + +Then, to replay from a specific task, use: + +```shell +crewai replay -t +``` + +These commands let you replay from your latest kickoff tasks, still retaining context from previously executed tasks. diff --git a/docs/v1.15.1/en/concepts/event-listener.mdx b/docs/v1.15.1/en/concepts/event-listener.mdx new file mode 100644 index 000000000..b3eb33e83 --- /dev/null +++ b/docs/v1.15.1/en/concepts/event-listener.mdx @@ -0,0 +1,414 @@ +--- +title: "Event Listeners" +description: "Tap into CrewAI events to build custom integrations and monitoring" +icon: spinner +mode: "wide" +--- + +## Overview + +CrewAI provides a powerful event system that allows you to listen for and react to various events that occur during the execution of your Crew. This feature enables you to build custom integrations, monitoring solutions, logging systems, or any other functionality that needs to be triggered based on CrewAI's internal events. + +## How It Works + +CrewAI uses an event bus architecture to emit events throughout the execution lifecycle. The event system is built on the following components: + +1. **CrewAIEventsBus**: A singleton event bus that manages event registration and emission +2. **BaseEvent**: Base class for all events in the system +3. **BaseEventListener**: Abstract base class for creating custom event listeners + +When specific actions occur in CrewAI (like a Crew starting execution, an Agent completing a task, or a tool being used), the system emits corresponding events. You can register handlers for these events to execute custom code when they occur. + + +CrewAI AMP provides a built-in Prompt Tracing feature that leverages the event system to track, store, and visualize all prompts, completions, and associated metadata. This provides powerful debugging capabilities and transparency into your agent operations. + +![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png) + +With Prompt Tracing you can: + +- View the complete history of all prompts sent to your LLM +- Track token usage and costs +- Debug agent reasoning failures +- Share prompt sequences with your team +- Compare different prompt strategies +- Export traces for compliance and auditing + + +## Creating a Custom Event Listener + +To create a custom event listener, you need to: + +1. Create a class that inherits from `BaseEventListener` +2. Implement the `setup_listeners` method +3. Register handlers for the events you're interested in +4. Create an instance of your listener in the appropriate file + +Here's a simple example of a custom event listener class: + +```python +from crewai.events import ( + CrewKickoffStartedEvent, + CrewKickoffCompletedEvent, + AgentExecutionCompletedEvent, +) +from crewai.events 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}") +``` + +## Properly Registering Your Listener + +Simply defining your listener class isn't enough. You need to create an instance of it and ensure it's imported in your application. This ensures that: + +1. The event handlers are registered with the event bus +2. The listener instance remains in memory (not garbage collected) +3. The listener is active when events are emitted + +### Option 1: Import and Instantiate in Your Crew or Flow Implementation + +The most important thing is to create an instance of your listener in the file where your Crew or Flow is defined and executed: + +#### For Crew-based Applications + +Create and import your listener at the top of your Crew implementation file: + +```python +# In your crew.py file +from crewai import Agent, Crew, Task +from my_listeners import MyCustomListener + +# Create an instance of your listener +my_listener = MyCustomListener() + +class MyCustomCrew: + # Your crew implementation... + + def crew(self): + return Crew( + agents=[...], + tasks=[...], + # ... + ) +``` + +#### For Flow-based Applications + +Create and import your listener at the top of your Flow implementation file: + +```python +# In your main.py or flow.py file +from crewai.flow import Flow, listen, start +from my_listeners import MyCustomListener + +# Create an instance of your listener +my_listener = MyCustomListener() + +class MyCustomFlow(Flow): + # Your flow implementation... + + @start() + def first_step(self): + # ... +``` + +This ensures that your listener is loaded and active when your Crew or Flow is executed. + +### Option 2: Create a Package for Your Listeners + +For a more structured approach, especially if you have multiple listeners: + +1. Create a package for your listeners: + +``` +my_project/ + ├── listeners/ + │ ├── __init__.py + │ ├── my_custom_listener.py + │ └── another_listener.py +``` + +2. In `my_custom_listener.py`, define your listener class and create an instance: + +```python +# my_custom_listener.py +from crewai.events import BaseEventListener +# ... import events ... + +class MyCustomListener(BaseEventListener): + # ... implementation ... + +# Create an instance of your listener +my_custom_listener = MyCustomListener() +``` + +3. In `__init__.py`, import the listener instances to ensure they're loaded: + +```python +# __init__.py +from .my_custom_listener import my_custom_listener +from .another_listener import another_listener + +# Optionally export them if you need to access them elsewhere +__all__ = ['my_custom_listener', 'another_listener'] +``` + +4. Import your listeners package in your Crew or Flow file: + +```python +# In your crew.py or flow.py file +import my_project.listeners # This loads all your listeners + +class MyCustomCrew: + # Your crew implementation... +``` + +This is how third-party event listeners are registered in the CrewAI codebase. + +## Available Event Types + +CrewAI provides a wide range of events that you can listen for: + +### Crew Events + +- **CrewKickoffStartedEvent**: Emitted when a Crew starts execution +- **CrewKickoffCompletedEvent**: Emitted when a Crew completes execution +- **CrewKickoffFailedEvent**: Emitted when a Crew fails to complete execution +- **CrewTestStartedEvent**: Emitted when a Crew starts testing +- **CrewTestCompletedEvent**: Emitted when a Crew completes testing +- **CrewTestFailedEvent**: Emitted when a Crew fails to complete testing +- **CrewTrainStartedEvent**: Emitted when a Crew starts training +- **CrewTrainCompletedEvent**: Emitted when a Crew completes training +- **CrewTrainFailedEvent**: Emitted when a Crew fails to complete training +- **CrewTestResultEvent**: Emitted when a Crew test result is available. Contains the quality score, execution duration, and model used. + +### Agent Events + +- **AgentExecutionStartedEvent**: Emitted when an Agent starts executing a task +- **AgentExecutionCompletedEvent**: Emitted when an Agent completes executing a task +- **AgentExecutionErrorEvent**: Emitted when an Agent encounters an error during execution +- **LiteAgentExecutionStartedEvent**: Emitted when a LiteAgent starts executing. Contains the agent info, tools, and messages. +- **LiteAgentExecutionCompletedEvent**: Emitted when a LiteAgent completes execution. Contains the agent info and output. +- **LiteAgentExecutionErrorEvent**: Emitted when a LiteAgent encounters an error during execution. Contains the agent info and error message. +- **AgentEvaluationStartedEvent**: Emitted when an agent evaluation starts. Contains the agent ID, agent role, optional task ID, and iteration number. +- **AgentEvaluationCompletedEvent**: Emitted when an agent evaluation completes. Contains the agent ID, agent role, optional task ID, iteration number, metric category, and score. +- **AgentEvaluationFailedEvent**: Emitted when an agent evaluation fails. Contains the agent ID, agent role, optional task ID, iteration number, and error message. + +### Task Events + +- **TaskStartedEvent**: Emitted when a Task starts execution +- **TaskCompletedEvent**: Emitted when a Task completes execution +- **TaskFailedEvent**: Emitted when a Task fails to complete execution +- **TaskEvaluationEvent**: Emitted when a Task is evaluated + +### Tool Usage Events + +- **ToolUsageStartedEvent**: Emitted when a tool execution is started +- **ToolUsageFinishedEvent**: Emitted when a tool execution is completed +- **ToolUsageErrorEvent**: Emitted when a tool execution encounters an error +- **ToolValidateInputErrorEvent**: Emitted when a tool input validation encounters an error +- **ToolExecutionErrorEvent**: Emitted when a tool execution encounters an error +- **ToolSelectionErrorEvent**: Emitted when there's an error selecting a tool + +### MCP Events + +- **MCPConnectionStartedEvent**: Emitted when starting to connect to an MCP server. Contains the server name, URL, transport type, connection timeout, and whether it's a reconnection attempt. +- **MCPConnectionCompletedEvent**: Emitted when successfully connected to an MCP server. Contains the server name, connection duration in milliseconds, and whether it was a reconnection. +- **MCPConnectionFailedEvent**: Emitted when connection to an MCP server fails. Contains the server name, error message, and error type (`timeout`, `authentication`, `network`, etc.). +- **MCPToolExecutionStartedEvent**: Emitted when starting to execute an MCP tool. Contains the server name, tool name, and tool arguments. +- **MCPToolExecutionCompletedEvent**: Emitted when MCP tool execution completes successfully. Contains the server name, tool name, result, and execution duration in milliseconds. +- **MCPToolExecutionFailedEvent**: Emitted when MCP tool execution fails. Contains the server name, tool name, error message, and error type (`timeout`, `validation`, `server_error`, etc.). +- **MCPConfigFetchFailedEvent**: Emitted when fetching an MCP server configuration fails (e.g., the MCP is not connected in your account, API error, or connection failure after config was fetched). Contains the slug, error message, and error type (`not_connected`, `api_error`, `connection_failed`). + +### Knowledge Events + +- **KnowledgeRetrievalStartedEvent**: Emitted when a knowledge retrieval is started +- **KnowledgeRetrievalCompletedEvent**: Emitted when a knowledge retrieval is completed +- **KnowledgeQueryStartedEvent**: Emitted when a knowledge query is started +- **KnowledgeQueryCompletedEvent**: Emitted when a knowledge query is completed +- **KnowledgeQueryFailedEvent**: Emitted when a knowledge query fails +- **KnowledgeSearchQueryFailedEvent**: Emitted when a knowledge search query fails + +### LLM Guardrail Events + +- **LLMGuardrailStartedEvent**: Emitted when a guardrail validation starts. Contains details about the guardrail being applied and retry count. +- **LLMGuardrailCompletedEvent**: Emitted when a guardrail validation completes. Contains details about validation success/failure, results, and error messages if any. +- **LLMGuardrailFailedEvent**: Emitted when a guardrail validation fails. Contains the error message and retry count. + +### Flow Events + +- **FlowCreatedEvent**: Emitted when a Flow is created +- **FlowStartedEvent**: Emitted when a Flow starts execution +- **FlowFinishedEvent**: Emitted when a Flow completes execution +- **FlowPausedEvent**: Emitted when a Flow is paused waiting for human feedback. Contains the flow name, flow ID, method name, current state, message shown when requesting feedback, and optional list of possible outcomes for routing. +- **FlowPlotEvent**: Emitted when a Flow is plotted +- **MethodExecutionStartedEvent**: Emitted when a Flow method starts execution +- **MethodExecutionFinishedEvent**: Emitted when a Flow method completes execution +- **MethodExecutionFailedEvent**: Emitted when a Flow method fails to complete execution +- **MethodExecutionPausedEvent**: Emitted when a Flow method is paused waiting for human feedback. Contains the flow name, method name, current state, flow ID, message shown when requesting feedback, and optional list of possible outcomes for routing. + +### Human In The Loop Events + +- **FlowInputRequestedEvent**: Emitted when a Flow requests user input via `Flow.ask()`. Contains the flow name, method name, the question or prompt being shown to the user, and optional metadata (e.g., user ID, channel, session context). +- **FlowInputReceivedEvent**: Emitted when user input is received after `Flow.ask()`. Contains the flow name, method name, the original question, the user's response (or `None` if timed out), optional request metadata, and optional response metadata from the provider (e.g., who responded, thread ID, timestamps). +- **HumanFeedbackRequestedEvent**: Emitted when a `@human_feedback` decorated method requires input from a human reviewer. Contains the flow name, method name, the method output shown to the human for review, the message displayed when requesting feedback, and optional list of possible outcomes for routing. +- **HumanFeedbackReceivedEvent**: Emitted when a human provides feedback in response to a `@human_feedback` decorated method. Contains the flow name, method name, the raw text feedback provided by the human, and the collapsed outcome string (if emit was specified). + +### LLM Events + +- **LLMCallStartedEvent**: Emitted when an LLM call starts +- **LLMCallCompletedEvent**: Emitted when an LLM call completes +- **LLMCallFailedEvent**: Emitted when an LLM call fails +- **LLMStreamChunkEvent**: Emitted for each chunk received during streaming LLM responses +- **LLMThinkingChunkEvent**: Emitted when a thinking/reasoning chunk is received from a thinking model. Contains the chunk text and optional response ID. + +### Memory Events + +- **MemoryQueryStartedEvent**: Emitted when a memory query is started. Contains the query, limit, and optional score threshold. +- **MemoryQueryCompletedEvent**: Emitted when a memory query is completed successfully. Contains the query, results, limit, score threshold, and query execution time. +- **MemoryQueryFailedEvent**: Emitted when a memory query fails. Contains the query, limit, score threshold, and error message. +- **MemorySaveStartedEvent**: Emitted when a memory save operation is started. Contains the value to be saved, metadata, and optional agent role. +- **MemorySaveCompletedEvent**: Emitted when a memory save operation is completed successfully. Contains the saved value, metadata, agent role, and save execution time. +- **MemorySaveFailedEvent**: Emitted when a memory save operation fails. Contains the value, metadata, agent role, and error message. +- **MemoryRetrievalStartedEvent**: Emitted when memory retrieval for a task prompt starts. Contains the optional task ID. +- **MemoryRetrievalCompletedEvent**: Emitted when memory retrieval for a task prompt completes successfully. Contains the task ID, memory content, and retrieval execution time. +- **MemoryRetrievalFailedEvent**: Emitted when memory retrieval for a task prompt fails. Contains the optional task ID and error message. + +### Reasoning Events + +- **AgentReasoningStartedEvent**: Emitted when an agent starts reasoning about a task. Contains the agent role, task ID, and attempt number. +- **AgentReasoningCompletedEvent**: Emitted when an agent finishes its reasoning process. Contains the agent role, task ID, the plan produced, and whether the agent is ready to proceed. +- **AgentReasoningFailedEvent**: Emitted when the reasoning process fails. Contains the agent role, task ID, and error message. + +### Observation Events + +- **StepObservationStartedEvent**: Emitted when the Planner begins observing a step's result. Fires after every step execution, before the observation LLM call. Contains the agent role, step number, and step description. +- **StepObservationCompletedEvent**: Emitted when the Planner finishes observing a step's result. Contains whether the step completed successfully, key information learned, whether the remaining plan is still valid, whether a full replan is needed, and suggested refinements. +- **StepObservationFailedEvent**: Emitted when the observation LLM call itself fails. The system defaults to continuing the plan. Contains the error message. +- **PlanRefinementEvent**: Emitted when the Planner refines upcoming step descriptions without a full replan. Contains the number of refined steps and the refinements applied. +- **PlanReplanTriggeredEvent**: Emitted when the Planner triggers a full replan because the remaining plan was deemed fundamentally wrong. Contains the replan reason, replan count, and number of completed steps preserved. +- **GoalAchievedEarlyEvent**: Emitted when the Planner detects the goal was achieved early and remaining steps will be skipped. Contains the number of steps remaining and steps completed. + +### A2A (Agent-to-Agent) Events + +#### Delegation Events + +- **A2ADelegationStartedEvent**: Emitted when A2A delegation starts. Contains the endpoint URL, task description, agent ID, context ID, whether it's multiturn, turn number, agent card metadata, protocol version, provider info, and optional skill ID. +- **A2ADelegationCompletedEvent**: Emitted when A2A delegation completes. Contains the completion status (`completed`, `input_required`, `failed`, etc.), result, error message, context ID, and agent card metadata. +- **A2AParallelDelegationStartedEvent**: Emitted when parallel delegation to multiple A2A agents begins. Contains the list of endpoints and the task description. +- **A2AParallelDelegationCompletedEvent**: Emitted when parallel delegation to multiple A2A agents completes. Contains the list of endpoints, success count, failure count, and results summary. + +#### Conversation Events + +- **A2AConversationStartedEvent**: Emitted once at the beginning of a multiturn A2A conversation, before the first message exchange. Contains the agent ID, endpoint, context ID, agent card metadata, protocol version, and provider info. +- **A2AMessageSentEvent**: Emitted when a message is sent to the A2A agent. Contains the message content, turn number, context ID, message ID, and whether it's multiturn. +- **A2AResponseReceivedEvent**: Emitted when a response is received from the A2A agent. Contains the response content, turn number, context ID, message ID, status, and whether it's the final response. +- **A2AConversationCompletedEvent**: Emitted once at the end of a multiturn A2A conversation. Contains the final status (`completed` or `failed`), final result, error message, context ID, and total number of turns. + +#### Streaming Events + +- **A2AStreamingStartedEvent**: Emitted when streaming mode begins for A2A delegation. Contains the task ID, context ID, endpoint, turn number, and whether it's multiturn. +- **A2AStreamingChunkEvent**: Emitted when a streaming chunk is received. Contains the chunk text, chunk index, whether it's the final chunk, task ID, context ID, and turn number. + +#### Polling & Push Notification Events + +- **A2APollingStartedEvent**: Emitted when polling mode begins for A2A delegation. Contains the task ID, context ID, polling interval in seconds, and endpoint. +- **A2APollingStatusEvent**: Emitted on each polling iteration. Contains the task ID, context ID, current task state, elapsed seconds, and poll count. +- **A2APushNotificationRegisteredEvent**: Emitted when a push notification callback is registered. Contains the task ID, context ID, callback URL, and endpoint. +- **A2APushNotificationReceivedEvent**: Emitted when a push notification is received from the remote A2A agent. Contains the task ID, context ID, and current state. +- **A2APushNotificationSentEvent**: Emitted when a push notification is sent to a callback URL. Contains the task ID, context ID, callback URL, state, whether delivery succeeded, and optional error message. +- **A2APushNotificationTimeoutEvent**: Emitted when push notification wait times out. Contains the task ID, context ID, and timeout duration in seconds. + +#### Connection & Authentication Events + +- **A2AAgentCardFetchedEvent**: Emitted when an agent card is successfully fetched. Contains the endpoint, agent name, agent card metadata, protocol version, provider info, whether it was cached, and fetch time in milliseconds. +- **A2AAuthenticationFailedEvent**: Emitted when authentication to an A2A agent fails. Contains the endpoint, auth type attempted (e.g., `bearer`, `oauth2`, `api_key`), error message, and HTTP status code. +- **A2AConnectionErrorEvent**: Emitted when a connection error occurs during A2A communication. Contains the endpoint, error message, error type (e.g., `timeout`, `connection_refused`, `dns_error`), HTTP status code, and the operation being attempted. +- **A2ATransportNegotiatedEvent**: Emitted when transport protocol is negotiated with an A2A agent. Contains the negotiated transport, negotiated URL, selection source (`client_preferred`, `server_preferred`, `fallback`), and client/server supported transports. +- **A2AContentTypeNegotiatedEvent**: Emitted when content types are negotiated with an A2A agent. Contains the client/server input/output modes, negotiated input/output modes, and whether negotiation succeeded. + +#### Artifact Events + +- **A2AArtifactReceivedEvent**: Emitted when an artifact is received from a remote A2A agent. Contains the task ID, artifact ID, artifact name, description, MIME type, size in bytes, and whether content should be appended. + +#### Server Task Events + +- **A2AServerTaskStartedEvent**: Emitted when an A2A server task execution starts. Contains the task ID and context ID. +- **A2AServerTaskCompletedEvent**: Emitted when an A2A server task execution completes. Contains the task ID, context ID, and result. +- **A2AServerTaskCanceledEvent**: Emitted when an A2A server task execution is canceled. Contains the task ID and context ID. +- **A2AServerTaskFailedEvent**: Emitted when an A2A server task execution fails. Contains the task ID, context ID, and error message. + +#### Context Lifecycle Events + +- **A2AContextCreatedEvent**: Emitted when an A2A context is created. Contexts group related tasks in a conversation or workflow. Contains the context ID and creation timestamp. +- **A2AContextExpiredEvent**: Emitted when an A2A context expires due to TTL. Contains the context ID, creation timestamp, age in seconds, and task count. +- **A2AContextIdleEvent**: Emitted when an A2A context becomes idle (no activity for the configured threshold). Contains the context ID, idle time in seconds, and task count. +- **A2AContextCompletedEvent**: Emitted when all tasks in an A2A context complete. Contains the context ID, total tasks, and duration in seconds. +- **A2AContextPrunedEvent**: Emitted when an A2A context is pruned (deleted). Contains the context ID, task count, and age in seconds. + +## Event Handler Structure + +Each event handler receives two parameters: + +1. **source**: The object that emitted the event +2. **event**: The event instance, containing event-specific data + +The structure of the event object depends on the event type, but all events inherit from `BaseEvent` and include: + +- **timestamp**: The time when the event was emitted +- **type**: A string identifier for the event type + +Additional fields vary by event type. For example, `CrewKickoffCompletedEvent` includes `crew_name` and `output` fields. + +## Advanced Usage: Scoped Handlers + +For temporary event handling (useful for testing or specific operations), you can use the `scoped_handlers` context manager: + +```python +from crewai.events import crewai_event_bus, CrewKickoffStartedEvent + +with crewai_event_bus.scoped_handlers(): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def temp_handler(source, event): + print("This handler only exists within this context") + + # Do something that emits events + +# Outside the context, the temporary handler is removed +``` + +## Use Cases + +Event listeners can be used for a variety of purposes: + +1. **Logging and Monitoring**: Track the execution of your Crew and log important events +2. **Analytics**: Collect data about your Crew's performance and behavior +3. **Debugging**: Set up temporary listeners to debug specific issues +4. **Integration**: Connect CrewAI with external systems like monitoring platforms, databases, or notification services +5. **Custom Behavior**: Trigger custom actions based on specific events + +## Best Practices + +1. **Keep Handlers Light**: Event handlers should be lightweight and avoid blocking operations +2. **Error Handling**: Include proper error handling in your event handlers to prevent exceptions from affecting the main execution +3. **Cleanup**: If your listener allocates resources, ensure they're properly cleaned up +4. **Selective Listening**: Only listen for events you actually need to handle +5. **Testing**: Test your event listeners in isolation to ensure they behave as expected + +By leveraging CrewAI's event system, you can extend its functionality and integrate it seamlessly with your existing infrastructure. diff --git a/docs/v1.15.1/en/concepts/files.mdx b/docs/v1.15.1/en/concepts/files.mdx new file mode 100644 index 000000000..af86baabe --- /dev/null +++ b/docs/v1.15.1/en/concepts/files.mdx @@ -0,0 +1,267 @@ +--- +title: Files +description: Pass images, PDFs, audio, video, and text files to your agents for multimodal processing. +icon: file-image +--- + +## Overview + +CrewAI supports native multimodal file inputs, allowing you to pass images, PDFs, audio, video, and text files directly to your agents. Files are automatically formatted for each LLM provider's API requirements. + + +File support requires the optional `crewai-files` package. Install it with: + +```bash +uv add 'crewai[file-processing]' +``` + + + +The file processing API is currently in early access. + + +## File Types + +CrewAI supports five specific file types plus a generic `File` class that auto-detects the type: + +| Type | Class | Use Cases | +|:-----|:------|:----------| +| **Image** | `ImageFile` | Photos, screenshots, diagrams, charts | +| **PDF** | `PDFFile` | Documents, reports, papers | +| **Audio** | `AudioFile` | Voice recordings, podcasts, meetings | +| **Video** | `VideoFile` | Screen recordings, presentations | +| **Text** | `TextFile` | Code files, logs, data files | +| **Generic** | `File` | Auto-detect type from content | + +```python +from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile + +image = ImageFile(source="screenshot.png") +pdf = PDFFile(source="report.pdf") +audio = AudioFile(source="meeting.mp3") +video = VideoFile(source="demo.mp4") +text = TextFile(source="data.csv") + +file = File(source="document.pdf") +``` + +## File Sources + +The `source` parameter accepts multiple input types and auto-detects the appropriate handler: + +### From Path + +```python +from crewai_files import ImageFile + +image = ImageFile(source="./images/chart.png") +``` + +### From URL + +```python +from crewai_files import ImageFile + +image = ImageFile(source="https://example.com/image.png") +``` + +### From Bytes + +```python +from crewai_files import ImageFile, FileBytes + +image_bytes = download_image_from_api() +image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png")) +image = ImageFile(source=image_bytes) +``` + +## Using Files + +Files can be passed at multiple levels, with more specific levels taking precedence. + +### With Crews + +Pass files when kicking off a crew: + +```python +from crewai import Crew +from crewai_files import ImageFile + +crew = Crew(agents=[analyst], tasks=[analysis_task]) + +result = crew.kickoff( + inputs={"topic": "Q4 Sales"}, + input_files={ + "chart": ImageFile(source="sales_chart.png"), + "report": PDFFile(source="quarterly_report.pdf"), + } +) +``` + +### With Tasks + +Attach files to specific tasks: + +```python +from crewai import Task +from crewai_files import ImageFile + +task = Task( + description="Analyze the sales chart and identify trends in {chart}", + expected_output="A summary of key trends", + input_files={ + "chart": ImageFile(source="sales_chart.png"), + } +) +``` + +### With Flows + +Pass files to flows, which automatically inherit to crews: + +```python +from crewai.flow.flow import Flow, start +from crewai_files import ImageFile + +class AnalysisFlow(Flow): + @start() + def analyze(self): + return self.analysis_crew.kickoff() + +flow = AnalysisFlow() +result = flow.kickoff( + input_files={"image": ImageFile(source="data.png")} +) +``` + +### With Standalone Agents + +Pass files directly to agent kickoff: + +```python +from crewai import Agent +from crewai_files import ImageFile + +agent = Agent( + role="Image Analyst", + goal="Analyze images", + backstory="Expert at visual analysis", + llm="gpt-4o", +) + +result = agent.kickoff( + messages="What's in this image?", + input_files={"photo": ImageFile(source="photo.jpg")}, +) +``` + +## File Precedence + +When files are passed at multiple levels, more specific levels override broader ones: + +``` +Flow input_files < Crew input_files < Task input_files +``` + +For example, if both Flow and Task define a file named `"chart"`, the Task's version is used. + +## Provider Support + +Different providers support different file types. CrewAI automatically formats files for each provider's API. + +| Provider | Image | PDF | Audio | Video | Text | +|:---------|:-----:|:---:|:-----:|:-----:|:----:| +| **OpenAI** (completions API) | ✓ | | | | | +| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | | +| **Anthropic** (claude-3.x) | ✓ | ✓ | | | | +| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ | +| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | | +| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | | + + +Google Gemini models support all file types including video (up to 1 hour, 2GB). Use Gemini when you need to process video content. + + + +If you pass a file type that the provider doesn't support (e.g., video to OpenAI), you'll receive an `UnsupportedFileTypeError`. Choose your provider based on the file types you need to process. + + +## How Files Are Sent + +CrewAI automatically chooses the optimal method to send files to each provider: + +| Method | Description | Used When | +|:-------|:------------|:----------| +| **Inline Base64** | File embedded directly in the request | Small files (< 5MB typically) | +| **File Upload API** | File uploaded separately, referenced by ID | Large files that exceed threshold | +| **URL Reference** | Direct URL passed to the model | File source is already a URL | + +### Provider Transmission Methods + +| Provider | Inline Base64 | File Upload API | URL References | +|:---------|:-------------:|:---------------:|:--------------:| +| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ | +| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ | +| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ | +| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) | +| **Azure OpenAI** | ✓ | | ✓ | + + +You don't need to manage this yourself. CrewAI automatically uses the most efficient method based on file size and provider capabilities. Providers without file upload APIs use inline base64 for all files. + + +## File Handling Modes + +Control how files are processed when they exceed provider limits: + +```python +from crewai_files import ImageFile, PDFFile + +image = ImageFile(source="large.png", mode="strict") +image = ImageFile(source="large.png", mode="auto") +image = ImageFile(source="large.png", mode="warn") +pdf = PDFFile(source="large.pdf", mode="chunk") +``` + +## Provider Constraints + +Each provider has specific limits for file sizes and dimensions: + +### OpenAI +- **Images**: Max 20 MB, up to 10 images per request +- **PDFs**: Max 32 MB, up to 100 pages +- **Audio**: Max 25 MB, up to 25 minutes + +### Anthropic +- **Images**: Max 5 MB, max 8000x8000 pixels, up to 100 images +- **PDFs**: Max 32 MB, up to 100 pages + +### Google Gemini +- **Images**: Max 100 MB +- **PDFs**: Max 50 MB +- **Audio**: Max 100 MB, up to 9.5 hours +- **Video**: Max 2 GB, up to 1 hour + +### AWS Bedrock +- **Images**: Max 4.5 MB, max 8000x8000 pixels +- **PDFs**: Max 3.75 MB, up to 100 pages + +## Referencing Files in Prompts + +Use the file's key name in your task descriptions to reference files: + +```python +task = Task( + description=""" + Analyze the provided materials: + 1. Review the chart in {sales_chart} + 2. Cross-reference with data in {quarterly_report} + 3. Summarize key findings + """, + expected_output="Analysis summary with key insights", + input_files={ + "sales_chart": ImageFile(source="chart.png"), + "quarterly_report": PDFFile(source="report.pdf"), + } +) +``` diff --git a/docs/v1.15.1/en/concepts/flows.mdx b/docs/v1.15.1/en/concepts/flows.mdx new file mode 100644 index 000000000..647512545 --- /dev/null +++ b/docs/v1.15.1/en/concepts/flows.mdx @@ -0,0 +1,1163 @@ +--- +title: Flows +description: Learn how to create and manage AI workflows using CrewAI Flows. +icon: arrow-progress +mode: "wide" +--- + +## Overview + +CrewAI Flows is a powerful feature designed to streamline the creation and management of AI workflows. Flows allow developers to combine and coordinate coding tasks and Crews efficiently, providing a robust framework for building sophisticated AI automations. + +Flows allow you to create structured, event-driven workflows. They provide a seamless way to connect multiple tasks, manage state, and control the flow of execution in your AI applications. With Flows, you can easily design and implement multi-step processes that leverage the full potential of CrewAI's capabilities. + +1. **Simplified Workflow Creation**: Easily chain together multiple Crews and tasks to create complex AI workflows. + +2. **State Management**: Flows make it super easy to manage and share state between different tasks in your workflow. + +3. **Event-Driven Architecture**: Built on an event-driven model, allowing for dynamic and responsive workflows. + +4. **Flexible Control Flow**: Implement conditional logic, loops, and branching within your workflows. + +## Getting Started + +Let's create a simple Flow where you will use OpenAI to generate a random city in one task and then use that city to generate a fun fact in another task. + +```python Code + +from crewai.flow.flow import Flow, listen, start +from dotenv import load_dotenv +from litellm import completion + +load_dotenv() + +class ExampleFlow(Flow): + model = "gpt-4o-mini" + + @start() + def generate_city(self): + print("Starting flow") + # Each flow state automatically gets a unique ID + print(f"Flow State ID: {self.state['id']}") + + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": "Return the name of a random city in the world.", + }, + ], + ) + + random_city = response["choices"][0]["message"]["content"] + # Store the city in our state + self.state["city"] = random_city + print(f"Random City: {random_city}") + + return random_city + + @listen(generate_city) + def generate_fun_fact(self, random_city): + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": f"Tell me a fun fact about {random_city}", + }, + ], + ) + + fun_fact = response["choices"][0]["message"]["content"] + # Store the fun fact in our state + self.state["fun_fact"] = fun_fact + return fun_fact + + + +flow = ExampleFlow() +flow.plot() +result = flow.kickoff() + +print(f"Generated fun fact: {result}") +``` +![Flow Visual image](/images/crewai-flow-1.png) +In the above example, we have created a simple Flow that generates a random city using OpenAI and then generates a fun fact about that city. The Flow consists of two tasks: `generate_city` and `generate_fun_fact`. The `generate_city` task is the starting point of the Flow, and the `generate_fun_fact` task listens for the output of the `generate_city` task. + +Each Flow instance automatically receives a unique identifier (UUID) in its state, which helps track and manage flow executions. The state can also store additional data (like the generated city and fun fact) that persists throughout the flow's execution. + +When you run the Flow, it will: +1. Generate a unique ID for the flow state +2. Generate a random city and store it in the state +3. Generate a fun fact about that city and store it in the state +4. Print the results to the console + +The state's unique ID and stored data can be useful for tracking flow executions and maintaining context between tasks. + +**Note:** Ensure you have set up your `.env` file to store your `OPENAI_API_KEY`. This key is necessary for authenticating requests to the OpenAI API. + +### @start() + +The `@start()` decorator marks entry points for a Flow. You can: + +- Declare multiple unconditional starts: `@start()` +- Gate a start on a prior method or router label: `@start("method_or_label")` +- Provide a callable condition to control when a start should fire + +All satisfied `@start()` methods will execute (often in parallel) when the Flow begins or resumes. + +### @listen() + +The `@listen()` decorator is used to mark a method as a listener for the output of another task in the Flow. The method decorated with `@listen()` will be executed when the specified task emits an output. The method can access the output of the task it is listening to as an argument. + +#### Usage + +The `@listen()` decorator can be used in several ways: + +1. **Listening to a Method by Name**: You can pass the name of the method you want to listen to as a string. When that method completes, the listener method will be triggered. + + ```python Code + @listen("generate_city") + def generate_fun_fact(self, random_city): + # Implementation + ``` + +2. **Listening to a Method Directly**: You can pass the method itself. When that method completes, the listener method will be triggered. + ```python Code + @listen(generate_city) + def generate_fun_fact(self, random_city): + # Implementation + ``` + +### Flow Output + +Accessing and handling the output of a Flow is essential for integrating your AI workflows into larger applications or systems. CrewAI Flows provide straightforward mechanisms to retrieve the final output, access intermediate results, and manage the overall state of your Flow. + +#### Retrieving the Final Output + +When you run a Flow, the final output is determined by the last method that completes. The `kickoff()` method returns the output of this final method. + +Here's how you can access the final output: + + +```python Code +from crewai.flow.flow import Flow, listen, start + +class OutputExampleFlow(Flow): + @start() + def first_method(self): + return "Output from first_method" + + @listen(first_method) + def second_method(self, first_output): + return f"Second method received: {first_output}" + + +flow = OutputExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() + +print("---- Final Output ----") +print(final_output) +``` + +```text Output +---- Final Output ---- +Second method received: Output from first_method +``` + + +![Flow Visual image](/images/crewai-flow-2.png) + +In this example, the `second_method` is the last method to complete, so its output will be the final output of the Flow. +The `kickoff()` method will return the final output, which is then printed to the console. The `plot()` method will generate the HTML file, which will help you understand the flow. + +#### Accessing and Updating State + +In addition to retrieving the final output, you can also access and update the state within your Flow. The state can be used to store and share data between different methods in the Flow. After the Flow has run, you can access the state to retrieve any information that was added or updated during the execution. + +Here's an example of how to update and access the state: + + + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class StateExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + self.state.message = "Hello from first_method" + self.state.counter += 1 + + @listen(first_method) + def second_method(self): + self.state.message += " - updated by second_method" + self.state.counter += 1 + return self.state.message + +flow = StateExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() +print(f"Final Output: {final_output}") +print("Final State:") +print(flow.state) +``` + +```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) + +In this example, the state is updated by both `first_method` and `second_method`. +After the Flow has run, you can access the final state to see the updates made by these methods. + +By ensuring that the final method's output is returned and providing access to the state, CrewAI Flows make it easy to integrate the results of your AI workflows into larger applications or systems, +while also maintaining and accessing the state throughout the Flow's execution. + +## Flow Usage Metrics + +After a Flow execution completes, you can access the `usage_metrics` property to view aggregated token usage across **every LLM call** made during the run — including calls from every Crew the Flow orchestrated, calls inside Agent tools, and bare `LLM.call(...)` invocations from Flow methods. This is the SDK-side equivalent of the totals shown in the CrewAI Enterprise UI. + +```python Code +from crewai import LLM +from crewai.flow.flow import Flow, listen, start + +class UsageMetricsFlow(Flow): + @start() + def run_first_crew(self): + self.state.first_result = FirstCrew().crew().kickoff() + + @listen(run_first_crew) + def call_llm_directly(self): + # Bare LLM call — still counted by flow.usage_metrics + llm = LLM(model="openai/gpt-4o-mini") + self.state.summary = llm.call("Summarize the key takeaways.") + + @listen(call_llm_directly) + def run_second_crew(self): + self.state.second_result = SecondCrew().crew().kickoff() + +flow = UsageMetricsFlow() +flow.kickoff() + +print(flow.usage_metrics) +# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369, +# cached_prompt_tokens=0, reasoning_tokens=0, +# cache_creation_tokens=0, successful_requests=5) +``` + + + `flow.usage_metrics` is **not** the same as `flow.kickoff().token_usage`. The + latter returns the `CrewOutput.token_usage` of the **last** `@listen` method + that returned a `CrewOutput`, which means it only reflects the final Crew and + ignores prior Crews and bare `LLM.call(...)` invocations entirely. Use + `flow.usage_metrics` whenever you need the **full** token rollup for the Flow + execution. + + +Each entry in the returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far. + +## Flow State Management + +Managing state effectively is crucial for building reliable and maintainable AI workflows. CrewAI Flows provides robust mechanisms for both unstructured and structured state management, +allowing developers to choose the approach that best fits their application's needs. + +### Unstructured State Management + +In unstructured state management, all state is stored in the `state` attribute of the `Flow` class. +This approach offers flexibility, enabling developers to add or modify state attributes on the fly without defining a strict schema. +Even with unstructured states, CrewAI Flows automatically generates and maintains a unique identifier (UUID) for each state instance. + +```python Code +from crewai.flow.flow import Flow, listen, start + +class UnstructuredExampleFlow(Flow): + + @start() + def first_method(self): + # The state automatically includes an 'id' field + print(f"State ID: {self.state['id']}") + self.state['counter'] = 0 + self.state['message'] = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated" + + @listen(second_method) + def third_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = UnstructuredExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**Note:** The `id` field is automatically generated and preserved throughout the flow's execution. You don't need to manage or set it manually, and it will be maintained even when updating the state with new data. + +**Key Points:** + +- **Flexibility:** You can dynamically add attributes to `self.state` without predefined constraints. +- **Simplicity:** Ideal for straightforward workflows where state structure is minimal or varies significantly. + +### Structured State Management + +Structured state management leverages predefined schemas to ensure consistency and type safety across the workflow. +By using models like Pydantic's `BaseModel`, developers can define the exact shape of the state, enabling better validation and auto-completion in development environments. + +Each state in CrewAI Flows automatically receives a unique identifier (UUID) to help track and manage state instances. This ID is automatically generated and managed by the Flow system. + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + + +class ExampleState(BaseModel): + # Note: 'id' field is automatically added to all states + counter: int = 0 + message: str = "" + + +class StructuredExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + # Access the auto-generated ID if needed + print(f"State ID: {self.state.id}") + self.state.message = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state.counter += 1 + self.state.message += " - updated" + + @listen(second_method) + def third_method(self): + self.state.counter += 1 + self.state.message += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = StructuredExampleFlow() +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**Key Points:** + +- **Defined Schema:** `ExampleState` clearly outlines the state structure, enhancing code readability and maintainability. +- **Type Safety:** Leveraging Pydantic ensures that state attributes adhere to the specified types, reducing runtime errors. +- **Auto-Completion:** IDEs can provide better auto-completion and error checking based on the defined state model. + +### Choosing Between Unstructured and Structured State Management + +- **Use Unstructured State Management when:** + + - The workflow's state is simple or highly dynamic. + - Flexibility is prioritized over strict state definitions. + - Rapid prototyping is required without the overhead of defining schemas. + +- **Use Structured State Management when:** + - The workflow requires a well-defined and consistent state structure. + - Type safety and validation are important for your application's reliability. + - You want to leverage IDE features like auto-completion and type checking for better developer experience. + +By providing both unstructured and structured state management options, CrewAI Flows empowers developers to build AI workflows that are both flexible and robust, catering to a wide range of application requirements. + +## Flow Persistence + +The @persist decorator enables automatic state persistence in CrewAI Flows, allowing you to maintain flow state across restarts or different workflow executions. This decorator can be applied at either the class level or method level, providing flexibility in how you manage state persistence. + +### Class-Level Persistence + +When applied at the class level, the @persist decorator automatically persists all flow method states: + +```python +@persist # Using SQLiteFlowPersistence by default +class MyFlow(Flow[MyState]): + @start() + def initialize_flow(self): + # This method will automatically have its state persisted + self.state.counter = 1 + print("Initialized flow. State ID:", self.state.id) + + @listen(initialize_flow) + def next_step(self): + # The state (including self.state.id) is automatically reloaded + self.state.counter += 1 + print("Flow state is persisted. Counter:", self.state.counter) +``` + +### Method-Level Persistence + +For more granular control, you can apply @persist to specific methods: + +```python +class AnotherFlow(Flow[dict]): + @persist # Persists only this method's state + @start() + def begin(self): + if "runs" not in self.state: + self.state["runs"] = 0 + self.state["runs"] += 1 + print("Method-level persisted runs:", self.state["runs"]) +``` + +### Forking Persisted State + +`@persist` supports two distinct hydration modes on `kickoff` / `kickoff_async`: + +- `kickoff(inputs={"id": })` — **resume**: load the latest snapshot for the supplied UUID and continue writing under the same `flow_uuid`. The history extends. +- `kickoff(restore_from_state_id=)` — **fork**: load the latest snapshot for the supplied UUID, hydrate the new run's state from it, and assign a fresh `state.id` (auto-generated, or `inputs["id"]` if pinned). The new run's `@persist` writes land under the new `state.id`; the source flow's history is preserved. + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + print(f"[id={self.state.id}] counter={self.state.counter}") + +# Run 1: fresh state, counter 0 -> 1, persisted under flow_1.state.id +flow_1 = CounterFlow() +flow_1.kickoff() + +# Fork: hydrate from flow_1's latest snapshot, but use a NEW state.id +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# flow_2.state.counter starts at 1 (hydrated), then step() bumps it to 2. +# flow_2.state.id != flow_1.state.id; flow_1's history is unchanged. +``` + +If the supplied `restore_from_state_id` does not match any persisted state, the kickoff falls back silently — same as the existing `inputs["id"]` resume not-found behavior. Combining `restore_from_state_id` with `from_checkpoint` raises a `ValueError`; pick one hydration source. Pinning `inputs["id"]` while forking shares a persistence key with another flow — usually you want only `restore_from_state_id`. + +### How It Works + +1. **Unique State Identification** + - Each flow state automatically receives a unique UUID + - The ID is preserved across state updates and method calls + - Supports both structured (Pydantic BaseModel) and unstructured (dictionary) states + +2. **Default SQLite Backend** + - SQLiteFlowPersistence is the default storage backend + - States are automatically saved to a local SQLite database + - Robust error handling ensures clear messages if database operations fail + +3. **Error Handling** + - Comprehensive error messages for database operations + - Automatic state validation during save and load + - Clear feedback when persistence operations encounter issues + +### Important Considerations + +- **State Types**: Both structured (Pydantic BaseModel) and unstructured (dictionary) states are supported +- **Automatic ID**: The `id` field is automatically added if not present +- **State Recovery**: Failed or restarted flows can automatically reload their previous state +- **Custom Implementation**: You can provide your own FlowPersistence implementation for specialized storage needs + +### Technical Advantages + +1. **Precise Control Through Low-Level Access** + - Direct access to persistence operations for advanced use cases + - Fine-grained control via method-level persistence decorators + - Built-in state inspection and debugging capabilities + - Full visibility into state changes and persistence operations + +2. **Enhanced Reliability** + - Automatic state recovery after system failures or restarts + - Transaction-based state updates for data integrity + - Comprehensive error handling with clear error messages + - Robust validation during state save and load operations + +3. **Extensible Architecture** + - Customizable persistence backend through FlowPersistence interface + - Support for specialized storage solutions beyond SQLite + - Compatible with both structured (Pydantic) and unstructured (dict) states + - Seamless integration with existing CrewAI flow patterns + +The persistence system's architecture emphasizes technical precision and customization options, allowing developers to maintain full control over state management while benefiting from built-in reliability features. + +## Flow Control + +### Conditional Logic: `or` + +The `or_` function in Flows allows you to listen to multiple methods and trigger the listener method when any of the specified methods emit an output. + + + +```python Code +from crewai.flow.flow import Flow, listen, or_, start + +class OrExampleFlow(Flow): + + @start() + def start_method(self): + return "Hello from the start method" + + @listen(start_method) + def second_method(self): + return "Hello from the second method" + + @listen(or_(start_method, second_method)) + def logger(self, result): + print(f"Logger: {result}") + + + +flow = OrExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Logger: Hello from the start method +Logger: Hello from the second method +``` + + + +![Flow Visual image](/images/crewai-flow-4.png) + +When you run this Flow, the `logger` method will be triggered by the output of either the `start_method` or the `second_method`. +The `or_` function is used to listen to multiple methods and trigger the listener method when any of the specified methods emit an output. + +### Conditional Logic: `and` + +The `and_` function in Flows allows you to listen to multiple methods and trigger the listener method only when all the specified methods emit an output. + + + +```python Code +from crewai.flow.flow import Flow, and_, listen, start + +class AndExampleFlow(Flow): + + @start() + def start_method(self): + self.state["greeting"] = "Hello from the start method" + + @listen(start_method) + def second_method(self): + self.state["joke"] = "What do computers eat? Microchips." + + @listen(and_(start_method, second_method)) + def logger(self): + print("---- Logger ----") + print(self.state) + +flow = AndExampleFlow() +flow.plot() +flow.kickoff() +``` + +```text Output +---- Logger ---- +{'greeting': 'Hello from the start method', 'joke': 'What do computers eat? Microchips.'} +``` + + + +![Flow Visual image](/images/crewai-flow-5.png) + +When you run this Flow, the `logger` method will be triggered only when both the `start_method` and the `second_method` emit an output. +The `and_` function is used to listen to multiple methods and trigger the listener method only when all the specified methods emit an output. + +### Router + +The `@router()` decorator in Flows allows you to define conditional routing logic based on the output of a method. +You can specify different routes based on the output of the method, allowing you to control the flow of execution dynamically. + + + +```python Code +import random +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + success_flag: bool = False + +class RouterFlow(Flow[ExampleState]): + + @start() + def start_method(self): + print("Starting the structured flow") + random_boolean = random.choice([True, False]) + self.state.success_flag = random_boolean + + @router(start_method) + def second_method(self): + if self.state.success_flag: + return "success" + else: + return "failed" + + @listen("success") + def third_method(self): + print("Third method running") + + @listen("failed") + def fourth_method(self): + print("Fourth method running") + + +flow = RouterFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Starting the structured flow +Third method running +Fourth method running +``` + + + +![Flow Visual image](/images/crewai-flow-6.png) + +In the above example, the `start_method` generates a random boolean value and sets it in the state. +The `second_method` uses the `@router()` decorator to define conditional routing logic based on the value of the boolean. +If the boolean is `True`, the method returns `"success"`, and if it is `False`, the method returns `"failed"`. +The `third_method` and `fourth_method` listen to the output of the `second_method` and execute based on the returned value. + +When you run this Flow, the output will change based on the random boolean value generated by the `start_method`. + +### Human in the Loop (human feedback) + + +The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**. + + +The `@human_feedback` decorator enables human-in-the-loop workflows by pausing flow execution to collect feedback from a human. This is useful for approval gates, quality review, and decision points that require human judgment. + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="Do you approve this content?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + def generate_content(self): + return "Content to be reviewed..." + + @listen("approved") + def on_approval(self, result: HumanFeedbackResult): + print(f"Approved! Feedback: {result.feedback}") + + @listen("rejected") + def on_rejection(self, result: HumanFeedbackResult): + print(f"Rejected. Reason: {result.feedback}") +``` + +When `emit` is specified, the human's free-form feedback is interpreted by an LLM and collapsed into one of the specified outcomes, which then triggers the corresponding `@listen` decorator. + +You can also use `@human_feedback` without routing to simply collect feedback: + +```python Code +@start() +@human_feedback(message="Any comments on this output?") +def my_method(self): + return "Output for review" + +@listen(my_method) +def next_step(self, result: HumanFeedbackResult): + # Access feedback via result.feedback + # Access original output via result.output + pass +``` + +Access all feedback collected during a flow via `self.last_human_feedback` (most recent) or `self.human_feedback_history` (all feedback as a list). + +For a complete guide on human feedback in flows, including **async/non-blocking feedback** with custom providers (Slack, webhooks, etc.), see [Human Feedback in Flows](/en/learn/human-feedback-in-flows). + +## Adding Agents to Flows + +Agents can be seamlessly integrated into your flows, providing a lightweight alternative to full Crews when you need simpler, focused task execution. Here's an example of how to use an Agent within a flow to perform market research: + +```python +import asyncio +from typing import Any, Dict, List + +from crewai_tools import SerperDevTool +from pydantic import BaseModel, Field + +from crewai.agent import Agent +from crewai.flow.flow import Flow, listen, start + + +# Define a structured output format +class MarketAnalysis(BaseModel): + key_trends: List[str] = Field(description="List of identified market trends") + market_size: str = Field(description="Estimated market size") + competitors: List[str] = Field(description="Major competitors in the space") + + +# Define flow state +class MarketResearchState(BaseModel): + product: str = "" + analysis: MarketAnalysis | None = None + + +# Create a flow class +class MarketResearchFlow(Flow[MarketResearchState]): + @start() + def initialize_research(self) -> Dict[str, Any]: + print(f"Starting market research for {self.state.product}") + return {"product": self.state.product} + + @listen(initialize_research) + async def analyze_market(self) -> Dict[str, Any]: + # Create an Agent for market research + analyst = Agent( + role="Market Research Analyst", + goal=f"Analyze the market for {self.state.product}", + backstory="You are an experienced market analyst with expertise in " + "identifying market trends and opportunities.", + tools=[SerperDevTool()], + verbose=True, + ) + + # Define the research query + query = f""" + Research the market for {self.state.product}. Include: + 1. Key market trends + 2. Market size + 3. Major competitors + + Format your response according to the specified structure. + """ + + # Execute the analysis with structured output format + result = await analyst.kickoff_async(query, response_format=MarketAnalysis) + if result.pydantic: + print("result", result.pydantic) + else: + print("result", result) + + # Return the analysis to update the state + return {"analysis": result.pydantic} + + @listen(analyze_market) + def present_results(self, analysis) -> None: + print("\nMarket Analysis Results") + print("=====================") + + if isinstance(analysis, dict): + # If we got a dict with 'analysis' key, extract the actual analysis object + market_analysis = analysis.get("analysis") + else: + market_analysis = analysis + + if market_analysis and isinstance(market_analysis, MarketAnalysis): + print("\nKey Market Trends:") + for trend in market_analysis.key_trends: + print(f"- {trend}") + + print(f"\nMarket Size: {market_analysis.market_size}") + + print("\nMajor Competitors:") + for competitor in market_analysis.competitors: + print(f"- {competitor}") + else: + print("No structured analysis data available.") + print("Raw analysis:", analysis) + + +# Usage example +async def run_flow(): + flow = MarketResearchFlow() + flow.plot("MarketResearchFlowPlot") + result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"}) + return result + + +# Run the flow +if __name__ == "__main__": + asyncio.run(run_flow()) +``` + +![Flow Visual image](/images/crewai-flow-7.png) + +This example demonstrates several key features of using Agents in flows: + +1. **Structured Output**: Using Pydantic models to define the expected output format (`MarketAnalysis`) ensures type safety and structured data throughout the flow. + +2. **State Management**: The flow state (`MarketResearchState`) maintains context between steps and stores both inputs and outputs. + +3. **Tool Integration**: Agents can use tools (like `WebsiteSearchTool`) to enhance their capabilities. + +## Adding Crews to Flows + +Creating a flow with multiple crews in CrewAI is straightforward. + +You can generate a new CrewAI project that includes all the scaffolding needed to create a flow with multiple crews by running the following command: + +```bash +crewai create flow name_of_flow +``` + +This command will generate a new CrewAI project with the necessary folder structure. The generated project includes a prebuilt crew called `poem_crew` that is already working. The starter embedded crew uses the classic Python/YAML layout; new standalone crews created with `crewai create crew` use the JSON-first layout. + +### Folder Structure + +After running the `crewai create flow name_of_flow` command, you will see a folder structure similar to the following: + +| Directory/File | Description | +| :--------------------- | :----------------------------------------------------------------- | +| `name_of_flow/` | Root directory for the flow. | +| ├── `crews/` | Contains directories for specific crews. | +| │ └── `poem_crew/` | Directory for the "poem_crew" with its configurations and scripts. | +| │ ├── `config/` | Configuration files directory for the "poem_crew". | +| │ │ ├── `agents.yaml` | YAML file defining the agents for "poem_crew". | +| │ │ └── `tasks.yaml` | YAML file defining the tasks for "poem_crew". | +| │ ├── `poem_crew.py` | Script for "poem_crew" functionality. | +| ├── `tools/` | Directory for additional tools used in the flow. | +| │ └── `custom_tool.py` | Custom tool implementation. | +| ├── `main.py` | Main script for running the flow. | +| ├── `README.md` | Project description and instructions. | +| ├── `pyproject.toml` | Configuration file for project dependencies and settings. | +| └── `.gitignore` | Specifies files and directories to ignore in version control. | + +### Building Your Crews + +In the `crews` folder, you can define multiple crews. The generated `poem_crew` uses the classic embedded-crew structure: + +- `config/agents.yaml`: Defines the agents for the crew. +- `config/tasks.yaml`: Defines the tasks for the crew. +- `poem_crew.py`: Contains the crew definition, including agents, tasks, and the crew itself. + +You can copy, paste, and edit the `poem_crew` to create other classic embedded crews. + +For JSON-first embedded crews, use a folder with `crew.jsonc` and `agents/*.jsonc` instead: + +```text +crews/ +└── research_crew/ + ├── agents/ + │ └── researcher.jsonc + └── crew.jsonc +``` + +Then load it from a Flow step: + +```python +from pathlib import Path +from crewai.project import load_crew + +crew, default_inputs = load_crew( + Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc" +) +result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"}) +``` + +### Connecting Crews in `main.py` + +The `main.py` file is where you create your flow and connect the crews together. You can define your flow by using the `Flow` class and the decorators `@start` and `@listen` to specify the flow of execution. + +Here's an example of how you can connect the `poem_crew` in the `main.py` file: + +```python Code +#!/usr/bin/env python +from random import randint + +from pydantic import BaseModel +from crewai.flow.flow import Flow, listen, start +from .crews.poem_crew.poem_crew import PoemCrew + +class PoemState(BaseModel): + sentence_count: int = 1 + poem: str = "" + +class PoemFlow(Flow[PoemState]): + + @start() + def generate_sentence_count(self): + print("Generating sentence count") + self.state.sentence_count = randint(1, 5) + + @listen(generate_sentence_count) + def generate_poem(self): + print("Generating poem") + result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count}) + + print("Poem generated", result.raw) + self.state.poem = result.raw + + @listen(generate_poem) + def save_poem(self): + print("Saving poem") + with open("poem.txt", "w") as f: + f.write(self.state.poem) + +def kickoff(): + poem_flow = PoemFlow() + poem_flow.kickoff() + + +def plot(): + poem_flow = PoemFlow() + poem_flow.plot("PoemFlowPlot") + +if __name__ == "__main__": + kickoff() + plot() +``` + +In this example, the `PoemFlow` class defines a flow that generates a sentence count, uses the `PoemCrew` to generate a poem, and then saves the poem to a file. The flow is kicked off by calling the `kickoff()` method. The PoemFlowPlot will be generated by `plot()` method. + +![Flow Visual image](/images/crewai-flow-8.png) + +### Running the Flow + +(Optional) Before running the flow, you can install the dependencies by running: + +```bash +crewai install +``` + +Once all of the dependencies are installed, you need to activate the virtual environment by running: + +```bash +source .venv/bin/activate +``` + +After activating the virtual environment, you can run the flow with the CrewAI CLI: + +```bash +crewai run +``` + +You can also run the project script directly: + +```bash +uv run kickoff +``` + +The flow will execute, and you should see the output in the console. + +## Plot Flows + +Visualizing your AI workflows can provide valuable insights into the structure and execution paths of your flows. CrewAI offers a powerful visualization tool that allows you to generate interactive plots of your flows, making it easier to understand and optimize your AI workflows. + +### What are Plots? + +Plots in CrewAI are graphical representations of your AI workflows. They display the various tasks, their connections, and the flow of data between them. This visualization helps in understanding the sequence of operations, identifying bottlenecks, and ensuring that the workflow logic aligns with your expectations. + +### How to Generate a Plot + +CrewAI provides two convenient methods to generate plots of your flows: + +#### Option 1: Using the `plot()` Method + +If you are working directly with a flow instance, you can generate a plot by calling the `plot()` method on your flow object. This method will create an HTML file containing the interactive plot of your flow. + +```python Code +# Assuming you have a flow instance +flow.plot("my_flow_plot") +``` + +This will generate a file named `my_flow_plot.html` in your current directory. You can open this file in a web browser to view the interactive plot. + +#### Option 2: Using the Command Line + +If you are working within a structured CrewAI project, you can generate a plot using the command line. This is particularly useful for larger projects where you want to visualize the entire flow setup. + +```bash +crewai flow plot +``` + +This command will generate an HTML file with the plot of your flow, similar to the `plot()` method. The file will be saved in your project directory, and you can open it in a web browser to explore the flow. + +### Understanding the Plot + +The generated plot will display nodes representing the tasks in your flow, with directed edges indicating the flow of execution. The plot is interactive, allowing you to zoom in and out, and hover over nodes to see additional details. + +By visualizing your flows, you can gain a clearer understanding of the workflow's structure, making it easier to debug, optimize, and communicate your AI processes to others. + +### Conclusion + +Plotting your flows is a powerful feature of CrewAI that enhances your ability to design and manage complex AI workflows. Whether you choose to use the `plot()` method or the command line, generating plots will provide you with a visual representation of your workflows, aiding in both development and presentation. + +## Next Steps + +If you're interested in exploring additional examples of flows, we have a variety of recommendations in our examples repository. Here are four specific flow examples, each showcasing unique use cases to help you match your current problem type to a specific example: + +1. **Email Auto Responder Flow**: This example demonstrates an infinite loop where a background job continually runs to automate email responses. It's a great use case for tasks that need to be performed repeatedly without manual intervention. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow) + +2. **Lead Score Flow**: This flow showcases adding human-in-the-loop feedback and handling different conditional branches using the router. It's an excellent example of how to incorporate dynamic decision-making and human oversight into your workflows. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow) + +3. **Write a Book Flow**: This example excels at chaining multiple crews together, where the output of one crew is used by another. Specifically, one crew outlines an entire book, and another crew generates chapters based on the outline. Eventually, everything is connected to produce a complete book. This flow is perfect for complex, multi-step processes that require coordination between different tasks. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows) + +4. **Meeting Assistant Flow**: This flow demonstrates how to broadcast one event to trigger multiple follow-up actions. For instance, after a meeting is completed, the flow can update a Trello board, send a Slack message, and save the results. It's a great example of handling multiple outcomes from a single event, making it ideal for comprehensive task management and notification systems. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow) + +By exploring these examples, you can gain insights into how to leverage CrewAI Flows for various use cases, from automating repetitive tasks to managing complex, multi-step processes with dynamic decision-making and human feedback. + +Also, check out our YouTube video on how to use flows in CrewAI below! + + + +## Running Flows + +There are two ways to run a flow: + +### Using the Flow API + +You can run a flow programmatically by creating an instance of your flow class and calling the `kickoff()` method: + +```python +flow = ExampleFlow() +result = flow.kickoff() +``` + +### Streaming Flow Execution + +For real-time visibility into flow execution, you can enable streaming to receive output as it's generated: + +```python +class StreamingFlow(Flow): + stream = True # Enable streaming + + @start() + def research(self): + # Your flow implementation + pass + +# Iterate over streaming output +flow = StreamingFlow() +streaming = flow.kickoff() +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access final result +result = streaming.result +``` + +Learn more about streaming in the [Streaming Flow Execution](/en/learn/streaming-flow-execution) guide. + +## Memory in Flows + +Every Flow automatically has access to CrewAI's unified [Memory](/concepts/memory) system. You can store, recall, and extract memories directly inside any flow method using three built-in convenience methods. + +### Built-in Methods + +| Method | Description | +| :--- | :--- | +| `self.remember(content, **kwargs)` | Store content in memory. Accepts optional `scope`, `categories`, `metadata`, `importance`. | +| `self.recall(query, **kwargs)` | Retrieve relevant memories. Accepts optional `scope`, `categories`, `limit`, `depth`. | +| `self.extract_memories(content)` | Break raw text into discrete, self-contained memory statements. | + +A default `Memory()` instance is created automatically when the Flow initializes. You can also pass a custom one: + +```python +from crewai.flow.flow import Flow +from crewai import Memory + +custom_memory = Memory( + recency_weight=0.5, + recency_half_life_days=7, + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) + +flow = MyFlow(memory=custom_memory) +``` + +### Example: Research and Analyze Flow + +```python +from crewai.flow.flow import Flow, listen, start + + +class ResearchAnalysisFlow(Flow): + @start() + def gather_data(self): + # Simulate research findings + findings = ( + "PostgreSQL handles 10k concurrent connections with connection pooling. " + "MySQL caps at around 5k. MongoDB scales horizontally but adds complexity." + ) + + # Extract atomic facts and remember each one + memories = self.extract_memories(findings) + for mem in memories: + self.remember(mem, scope="/research/databases") + + return findings + + @listen(gather_data) + def analyze(self, raw_findings): + # Recall relevant past research (from this run or previous runs) + past = self.recall("database performance and scaling", limit=10, depth="shallow") + + context_lines = [f"- {m.record.content}" for m in past] + context = "\n".join(context_lines) if context_lines else "No prior context." + + return { + "new_findings": raw_findings, + "prior_context": context, + "total_memories": len(past), + } + + +flow = ResearchAnalysisFlow() +result = flow.kickoff() +print(result) +``` + +Because memory persists across runs (backed by LanceDB on disk), the `analyze` step will recall findings from previous executions too -- enabling flows that learn and accumulate knowledge over time. + +See the [Memory documentation](/concepts/memory) for details on scopes, slices, composite scoring, embedder configuration, and more. + +### Using the CLI + +Starting from version 0.103.0, you can run flows using the `crewai run` command: + +```shell +crewai run +``` + +This command automatically detects if your project is a flow (based on the `type = "flow"` setting in your pyproject.toml) and runs it accordingly. This is the recommended way to run flows from the command line. + +The legacy `crewai flow kickoff` command is deprecated. Use `crewai run` for both crews and flows. diff --git a/docs/v1.15.1/en/concepts/knowledge.mdx b/docs/v1.15.1/en/concepts/knowledge.mdx new file mode 100644 index 000000000..937cca1fd --- /dev/null +++ b/docs/v1.15.1/en/concepts/knowledge.mdx @@ -0,0 +1,1097 @@ +--- +title: Knowledge +description: What is knowledge in CrewAI and how to use it. +icon: book +mode: "wide" +--- + +## Overview + +Knowledge in CrewAI is a powerful system that allows AI agents to access and utilize external information sources during their tasks. +Think of it as giving your agents a reference library they can consult while working. + + + Key benefits of using Knowledge: + - Enhance agents with domain-specific information + - Support decisions with real-world data + - Maintain context across conversations + - Ground responses in factual information + + +## Quickstart Examples + + +For file-based Knowledge Sources, make sure to place your files in a `knowledge` directory at the root of your project. +Also, use relative paths from the `knowledge` directory when creating the source. + + +### Vector store (RAG) client configuration + +CrewAI exposes a provider-neutral RAG client abstraction for vector stores. The default provider is ChromaDB, and Qdrant is supported as well. You can switch providers using configuration utilities. + +Supported today: +- ChromaDB (default) +- Qdrant + +```python Code +from crewai.rag.config.utils import set_rag_config, get_rag_client, clear_rag_config + +# ChromaDB (default) +from crewai.rag.chromadb.config import ChromaDBConfig +set_rag_config(ChromaDBConfig()) +chromadb_client = get_rag_client() + +# Qdrant +from crewai.rag.qdrant.config import QdrantConfig +set_rag_config(QdrantConfig()) +qdrant_client = get_rag_client() + +# Example operations (same API for any provider) +client = qdrant_client # or chromadb_client +client.create_collection(collection_name="docs") +client.add_documents( + collection_name="docs", + documents=[{"id": "1", "content": "CrewAI enables collaborative AI agents."}], +) +results = client.search(collection_name="docs", query="collaborative agents", limit=3) + +clear_rag_config() # optional reset +``` + +This RAG client is separate from Knowledge’s built-in storage. Use it when you need direct vector-store control or custom retrieval pipelines. + +### Basic String Knowledge Example + +```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?"}) +``` + +### Web Content Knowledge Example + + + You need to install `docling` for the following example to work: `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."} +) +``` + +## Supported Knowledge Sources + +CrewAI supports various types of knowledge sources out of the box: + + + + - Raw strings + - Text files (.txt) + - PDF documents + + + - CSV files + - Excel spreadsheets + - JSON documents + + + +### Text File Knowledge Source +```python +from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource + +text_source = TextFileKnowledgeSource( + file_paths=["document.txt", "another.txt"] +) +``` + +### PDF Knowledge Source +```python +from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource + +pdf_source = PDFKnowledgeSource( + file_paths=["document.pdf", "another.pdf"] +) +``` + +### CSV Knowledge Source +```python +from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource + +csv_source = CSVKnowledgeSource( + file_paths=["data.csv"] +) +``` + +### Excel Knowledge Source +```python +from crewai.knowledge.source.excel_knowledge_source import ExcelKnowledgeSource + +excel_source = ExcelKnowledgeSource( + file_paths=["spreadsheet.xlsx"] +) +``` + +### JSON Knowledge Source +```python +from crewai.knowledge.source.json_knowledge_source import JSONKnowledgeSource + +json_source = JSONKnowledgeSource( + file_paths=["data.json"] +) +``` + + + Please ensure that you create the ./knowledge folder. All source files (e.g., .txt, .pdf, .xlsx, .json) should be placed in this folder for centralized management. + + +## Agent vs Crew Knowledge: Complete Guide + + +**Understanding Knowledge Levels**: CrewAI supports knowledge at both agent and crew levels. This section clarifies exactly how each works, when they're initialized, and addresses common misconceptions about dependencies. + + +### How Knowledge Initialization Actually Works + +Here's exactly what happens when you use knowledge: + +#### Agent-Level Knowledge (Independent) +```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 +``` + +#### What Happens During `crew.kickoff()` + +When you call `crew.kickoff()`, here's the exact sequence: + +```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() +``` + +#### Storage Independence + +Each knowledge level uses independent storage collections: + +```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 +``` + +### Complete Working Examples + +#### Example 1: Agent-Only Knowledge +```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 +``` + +#### Example 2: Both Agent and Crew Knowledge +```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 +``` + +#### Example 3: Multiple Agents with Different Knowledge +```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-generativeai", + "config": {"model_name": "gemini-embedding-001"} + } +) + +# Each agent gets only their specific knowledge +# Each can use different embedding providers +``` + + +Unlike retrieval from a vector database using a tool, agents preloaded with knowledge will not need a retrieval persona or task. +Simply add the relevant knowledge sources your agent or crew needs to function. + +Knowledge sources can be added at the agent or crew level. +Crew level knowledge sources will be used by **all agents** in the crew. +Agent level knowledge sources will be used by the **specific agent** that is preloaded with the knowledge. + + +## Knowledge Configuration + +You can configure the knowledge configuration for the crew or agent. + +```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`: is the number of relevant documents to return. Default is 3. + `score_threshold`: is the minimum score for a document to be considered relevant. Default is 0.35. + + +## Supported Knowledge Parameters + + + List of knowledge sources that provide content to be stored and queried. Can include PDF, CSV, Excel, JSON, text files, or string content. + + + Name of the collection where the knowledge will be stored. Used to identify different sets of knowledge. Defaults to \"knowledge\" if not provided. + + +Custom storage configuration for managing how the knowledge is stored and retrieved. If not provided, a default storage will be created. + + +## Knowledge Storage Transparency + + +**Understanding Knowledge Storage**: CrewAI automatically stores knowledge sources in platform-specific directories using ChromaDB for vector storage. Understanding these locations and defaults helps with production deployments, debugging, and storage management. + + +### Where CrewAI Stores Knowledge Files + +By default, CrewAI uses the same storage system as memory, storing knowledge in platform-specific directories: + +#### Default Storage Locations by Platform + +**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}\ +``` + +### Finding Your Knowledge Storage Location + +To see exactly where CrewAI is storing your knowledge files: + +```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.") +``` + +### Controlling Knowledge Storage Locations + +#### Option 1: Environment Variable (Recommended) +```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=[...] +) +``` + +#### Option 2: Custom Knowledge Storage +```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 +``` + +#### Option 3: Project-Specific Knowledge Storage +```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 +``` + +### Default Embedding Provider Behavior + + +**Default Embedding Provider**: CrewAI defaults to OpenAI embeddings (`text-embedding-3-small`) for knowledge storage, even when using different LLM providers. You can easily customize this to match your setup. + + +#### Understanding Default Behavior +```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 +) +``` + +#### Customizing Knowledge Embedding Providers +```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-generativeai", + "config": { + "model_name": "gemini-embedding-001", + "api_key": "your-google-key" + } + } +) +``` + +#### Configuring Azure OpenAI Embeddings + +When using Azure OpenAI embeddings: +1. Make sure you deploy the embedding model in Azure platform first +2. Then you need to use the following configuration: + +```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" + } + } +) +``` + +## Advanced Features + +### Query Rewriting + +CrewAI implements an intelligent query rewriting mechanism to optimize knowledge retrieval. When an agent needs to search through knowledge sources, the raw task prompt is automatically transformed into a more effective search query. + +#### How Query Rewriting Works + +1. When an agent executes a task with knowledge sources available, the `_get_knowledge_search_query` method is triggered +2. The agent's LLM is used to transform the original task prompt into an optimized search query +3. This optimized query is then used to retrieve relevant information from knowledge sources + +#### Benefits of Query Rewriting + + + + By focusing on key concepts and removing irrelevant content, query rewriting helps retrieve more relevant information. + + + The rewritten queries are designed to be more specific and context-aware for vector database retrieval. + + + +#### Example + +```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?" +``` + +The rewritten query is more focused on the core information need and removes irrelevant instructions about output formatting. + + + This mechanism is fully automatic and requires no configuration from users. The agent's LLM is used to perform the query rewriting, so using a more capable LLM can improve the quality of rewritten queries. + + +### Knowledge Events + +CrewAI emits events during the knowledge retrieval process that you can listen for using the event system. These events allow you to monitor, debug, and analyze how knowledge is being retrieved and used by your agents. + +#### Available Knowledge Events + +- **KnowledgeRetrievalStartedEvent**: Emitted when an agent starts retrieving knowledge from sources +- **KnowledgeRetrievalCompletedEvent**: Emitted when knowledge retrieval is completed, including the query used and the retrieved content +- **KnowledgeQueryStartedEvent**: Emitted when a query to knowledge sources begins +- **KnowledgeQueryCompletedEvent**: Emitted when a query completes successfully +- **KnowledgeQueryFailedEvent**: Emitted when a query to knowledge sources fails +- **KnowledgeSearchQueryFailedEvent**: Emitted when a search query fails + +#### Example: Monitoring Knowledge Retrieval + +```python +from crewai.events import ( + KnowledgeRetrievalStartedEvent, + KnowledgeRetrievalCompletedEvent, + 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() +``` + +For more information on using events, see the [Event Listeners](/en/concepts/event-listener) documentation. + +### Custom Knowledge Sources + +CrewAI allows you to create custom knowledge sources for any type of data by extending the `BaseKnowledgeSource` class. Let's create a practical example that fetches and processes space news articles. + +#### Space News Knowledge Source Example + + + +```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/) +``` + + + +## Debugging and Troubleshooting + +### Debugging Knowledge Issues + +#### Check Agent Knowledge Initialization +```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)}") +``` + +#### Verify Knowledge Storage Locations +```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}") +``` + +#### Test Knowledge Retrieval +```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") +``` + +#### Inspect Knowledge Collections +```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") +``` + +#### Check Knowledge Processing +```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]}...") +``` + +### Common Knowledge Storage Issues + +**"File not found" errors:** +```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)}") +``` + +**"Embedding dimension mismatch" errors:** +```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"}} +) +``` + +**"ChromaDB permission denied" errors:** +```bash +# Fix storage permissions +chmod -R 755 ~/.local/share/CrewAI/ +``` + +**Knowledge not persisting between runs:** +```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")) +``` + +### Knowledge Reset Commands + +```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 +``` + +### Clearing Knowledge + +If you need to clear the knowledge stored in CrewAI, you can use the `crewai reset-memories` command with the `--knowledge` option. + +```bash Command +crewai reset-memories --knowledge +``` + +This is useful when you've updated your knowledge sources and want to ensure that the agents are using the most recent information. + +## Best Practices + + + + - Keep chunk sizes appropriate for your content type + - Consider content overlap for context preservation + - Organize related information into separate knowledge sources + + + + - Adjust chunk sizes based on content complexity + - Configure appropriate embedding models + - Consider using local embedding providers for faster processing + + + + - With the typical file structure provided by CrewAI, knowledge sources are embedded every time the kickoff is triggered. + - If the knowledge sources are large, this leads to inefficiency and increased latency, as the same data is embedded each time. + - To resolve this, directly initialize the knowledge parameter instead of the knowledge_sources parameter. + - Link to the issue to get complete idea [Github Issue](https://github.com/crewAIInc/crewAI/issues/2755) + + + + - Use agent-level knowledge for role-specific information + - Use crew-level knowledge for shared information all agents need + - Set embedders at agent level if you need different embedding strategies + - Use consistent collection naming by keeping agent roles descriptive + - Test knowledge initialization by checking agent.knowledge after kickoff + - Monitor storage locations to understand where knowledge is stored + - Reset knowledge appropriately using the correct command types + + + + - Set `CREWAI_STORAGE_DIR` to a known location in production + - Choose explicit embedding providers to match your LLM setup and avoid API key conflicts + - Monitor knowledge storage size as it grows with document additions + - Organize knowledge sources by domain or purpose using collection names + - Include knowledge directories in your backup and deployment strategies + - Set appropriate file permissions for knowledge files and storage directories + - Use environment variables for API keys and sensitive configuration + + + + diff --git a/docs/v1.15.1/en/concepts/llms.mdx b/docs/v1.15.1/en/concepts/llms.mdx new file mode 100644 index 000000000..85921b6ea --- /dev/null +++ b/docs/v1.15.1/en/concepts/llms.mdx @@ -0,0 +1,1635 @@ +--- +title: 'LLMs' +description: 'A comprehensive guide to configuring and using Large Language Models (LLMs) in your CrewAI projects' +icon: 'microchip-ai' +mode: "wide" +--- + +## Overview + +CrewAI integrates with multiple LLM providers through providers native sdks, giving you the flexibility to choose the right model for your specific use case. This guide will help you understand how to configure and use different LLM providers in your CrewAI projects. + + +## What are LLMs? + +Large Language Models (LLMs) are the core intelligence behind CrewAI agents. They enable agents to understand context, make decisions, and generate human-like responses. Here's what you need to know: + + + + Large Language Models are AI systems trained on vast amounts of text data. They power the intelligence of your CrewAI agents, enabling them to understand and generate human-like text. + + + The context window determines how much text an LLM can process at once. Larger windows (e.g., 128K tokens) allow for more context but may be more expensive and slower. + + + Temperature (0.0 to 1.0) controls response randomness. Lower values (e.g., 0.2) produce more focused, deterministic outputs, while higher values (e.g., 0.8) increase creativity and variability. + + + Each LLM provider (e.g., OpenAI, Anthropic, Google) offers different models with varying capabilities, pricing, and features. Choose based on your needs for accuracy, speed, and cost. + + + +## Setting up your LLM + +There are different places in CrewAI code where you can specify the model to use. Once you specify the model you are using, you will need to provide the configuration (like an API key) for each of the model providers you use. See the [provider configuration examples](#provider-configuration-examples) section for your provider. + + + + The simplest way to get started. Set the model in your environment directly, through an `.env` file or in your app code. If you used `crewai create` to bootstrap your project, it will be set already. + + ```bash .env + MODEL=model-id # e.g. gpt-4o, gemini-2.0-flash, claude-3-sonnet-... + + # Be sure to set your API keys here too. See the Provider + # section below. + ``` + + + Never commit API keys to version control. Use environment files (.env) or your system's secret management. + + + + Create a YAML file to define your agent configurations. This method is great for version control and team collaboration: + + ```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... + # (see provider configuration examples below for more) + ``` + + + The YAML configuration allows you to: + - Version control your agent settings + - Easily switch between different models + - Share configurations across team members + - Document model choices and their purposes + + + + For maximum flexibility, configure LLMs directly in your Python code: + + ```python {4,8} + from crewai import LLM + + # Basic configuration + llm = LLM(model="model-id-here") # gpt-4o, gemini-2.0-flash, anthropic/claude... + + # Advanced configuration with detailed parameters + llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + temperature=0.7, # Higher for more creative outputs + timeout=120, # Seconds to wait for response + max_tokens=4000, # Maximum length of response + top_p=0.9, # Nucleus sampling parameter + frequency_penalty=0.1 , # Reduce repetition + presence_penalty=0.1, # Encourage topic diversity + response_format={"type": "json"}, # For structured outputs + seed=42 # For reproducible results + ) + ``` + + + Parameter explanations: + - `temperature`: Controls randomness (0.0-1.0) + - `timeout`: Maximum wait time for response + - `max_tokens`: Limits response length + - `top_p`: Alternative to temperature for sampling + - `frequency_penalty`: Reduces word repetition + - `presence_penalty`: Encourages new topics + - `response_format`: Specifies output structure + - `seed`: Ensures consistent outputs + + + + + + CrewAI provides native SDK integrations for OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock, and Snowflake Cortex — no extra install needed beyond the provider-specific extras (e.g. `uv add "crewai[openai]"`). + + All other providers are powered by **LiteLLM**. If you plan to use any of them, add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + +## Provider Configuration Examples + +CrewAI supports a multitude of LLM providers, each offering unique features, authentication methods, and model capabilities. +In this section, you'll find detailed examples that help you select, configure, and optimize the LLM that best fits your project's needs. + + + + CrewAI provides native integration with OpenAI through the OpenAI Python SDK. + + ```toml Code + # Required + OPENAI_API_KEY=sk-... + + # Optional + OPENAI_BASE_URL= + ``` + + **Basic Usage:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4o", + api_key="your-api-key", # Or set OPENAI_API_KEY + temperature=0.7, + max_tokens=4000 + ) + ``` + + **Advanced Configuration:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4o", + api_key="your-api-key", + base_url="https://api.openai.com/v1", # Optional custom endpoint + organization="org-...", # Optional organization ID + project="proj_...", # Optional project ID + temperature=0.7, + max_tokens=4000, + max_completion_tokens=4000, # For newer models + top_p=0.9, + frequency_penalty=0.1, + presence_penalty=0.1, + stop=["END"], + seed=42, # For reproducible outputs + stream=True, # Enable streaming + timeout=60.0, # Request timeout in seconds + max_retries=3, # Maximum retry attempts + logprobs=True, # Return log probabilities + top_logprobs=5, # Number of most likely tokens + reasoning_effort="medium" # For o1 models: low, medium, high + ) + ``` + + **Structured Outputs:** + ```python Code + from pydantic import BaseModel + from crewai import LLM + + class ResponseFormat(BaseModel): + name: str + age: int + summary: str + + llm = LLM( + model="openai/gpt-4o", + ) + ``` + + **Supported Environment Variables:** + - `OPENAI_API_KEY`: Your OpenAI API key (required) + - `OPENAI_BASE_URL`: Custom base URL for OpenAI API (optional) + + **Features:** + - Native function calling support (except o1 models) + - Structured outputs with JSON schema + - Streaming support for real-time responses + - Token usage tracking + - Stop sequences support (except o1 models) + - Log probabilities for token-level insights + - Reasoning effort control for o1 models + + **Supported Models:** + + | Model | Context Window | Best For | + |---------------------|------------------|-----------------------------------------------| + | gpt-4.1 | 1M tokens | Latest model with enhanced capabilities | + | gpt-4.1-mini | 1M tokens | Efficient version with large context | + | gpt-4.1-nano | 1M tokens | Ultra-efficient variant | + | gpt-4o | 128,000 tokens | Optimized for speed and intelligence | + | gpt-4o-mini | 200,000 tokens | Cost-effective with large context | + | gpt-4-turbo | 128,000 tokens | Long-form content, document analysis | + | gpt-4 | 8,192 tokens | High-accuracy tasks, complex reasoning | + | o1 | 200,000 tokens | Advanced reasoning, complex problem-solving | + | o1-preview | 128,000 tokens | Preview of reasoning capabilities | + | o1-mini | 128,000 tokens | Efficient reasoning model | + | o3-mini | 200,000 tokens | Lightweight reasoning model | + | o4-mini | 200,000 tokens | Next-gen efficient reasoning | + + **Responses API:** + + OpenAI offers two APIs: Chat Completions (default) and the newer Responses API. The Responses API was designed from the ground up with native multimodal support—text, images, audio, and function calls are all first-class citizens. It provides better performance with reasoning models and supports additional features like auto-chaining and built-in tools. + + ```python Code + from crewai import LLM + + # Use the Responses API instead of Chat Completions + llm = LLM( + model="openai/gpt-4o", + api="responses", # Enable Responses API + store=True, # Store responses for multi-turn (optional) + auto_chain=True, # Auto-chain for reasoning models (optional) + ) + ``` + + **Responses API Parameters:** + - `api`: Set to `"responses"` to use the Responses API (default: `"completions"`) + - `instructions`: System-level instructions (Responses API only) + - `store`: Whether to store responses for multi-turn conversations + - `previous_response_id`: ID of previous response for multi-turn + - `include`: Additional data to include in response (e.g., `["reasoning.encrypted_content"]`) + - `builtin_tools`: List of OpenAI built-in tools: `"web_search"`, `"file_search"`, `"code_interpreter"`, `"computer_use"` + - `parse_tool_outputs`: Return structured `ResponsesAPIResult` with parsed built-in tool outputs + - `auto_chain`: Automatically track and use response IDs for multi-turn conversations + - `auto_chain_reasoning`: Track encrypted reasoning items for ZDR (Zero Data Retention) compliance + + + Use the Responses API for new projects, especially when working with reasoning models (o1, o3, o4) or when you need native multimodal support for [files](/en/concepts/files). + + + **Note:** To use OpenAI, install the required dependencies: + ```bash + uv add "crewai[openai]" + ``` + + + + Meta's Llama API provides access to Meta's family of large language models. + The API is available through the [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website). + Set the following environment variables in your `.env` file: + + ```toml Code + # Meta Llama API Key Configuration + LLAMA_API_KEY=LLM|your_api_key_here + ``` + + Example usage in your CrewAI project: + ```python Code + from crewai import LLM + + # Initialize Meta Llama LLM + llm = LLM( + model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8", + temperature=0.8, + stop=["END"], + seed=42 + ) + ``` + + All models listed here https://llama.developer.meta.com/docs/models/ are supported. + + | Model ID | Input context length | Output context length | Input Modalities | Output Modalities | + | --- | --- | --- | --- | --- | + | `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | Text, Image | Text | + | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | Text, Image | Text | + | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | Text | Text | + | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | Text | Text | + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + CrewAI provides native integration with the Snowflake Cortex REST API through its OpenAI-compatible Chat Completions endpoint. This avoids LiteLLM fallback for `snowflake/...` models. Snowflake Cortex currently supports Chat Completions only in CrewAI, so use the default `api` mode and do not set `api="responses"`. + + ```toml Code + # Required + SNOWFLAKE_PAT= + SNOWFLAKE_ACCOUNT_URL=https://.snowflakecomputing.com + + # Alternative account configuration + SNOWFLAKE_ACCOUNT= + ``` + + **Basic Usage:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/openai-gpt-4.1", + temperature=0.7, + max_completion_tokens=1024, + ) + ``` + + **Claude Models on Cortex:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/claude-sonnet-4-5", + max_completion_tokens=1024, + stream=True, + ) + ``` + + **Supported Environment Variables:** + - `SNOWFLAKE_PAT`, `SNOWFLAKE_TOKEN`, or `SNOWFLAKE_JWT`: token used as the Bearer credential + - `SNOWFLAKE_ACCOUNT_URL`: full Snowflake account URL + - `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_ACCOUNT_ID`, or `SNOWFLAKE_ACCOUNT_IDENTIFIER`: account identifier used to build the account URL + + Snowflake REST requests use the user's default Snowflake role. Make sure that role has `SNOWFLAKE.CORTEX_USER` or `SNOWFLAKE.CORTEX_REST_API_USER`. Database, schema, warehouse, and explicit role parameters are not required by the Cortex REST Chat Completions endpoint. + + **Features:** + - Native provider selection with `model="snowflake/"` + - Streaming and non-streaming Chat Completions only; `api="responses"` is not supported + - Token usage tracking + - Function calling for Snowflake-hosted OpenAI and Claude models + - Automatic removal of invalid trailing assistant prefill for Snowflake Claude models + + + + CrewAI provides native integration with Anthropic through the Anthropic Python SDK. + + ```toml Code + # Required + ANTHROPIC_API_KEY=sk-ant-... + ``` + + **Basic Usage:** + ```python Code + from crewai import LLM + + llm = LLM( + model="anthropic/claude-3-5-sonnet-20241022", + api_key="your-api-key", # Or set ANTHROPIC_API_KEY + max_tokens=4096 # Required for Anthropic + ) + ``` + + **Advanced Configuration:** + ```python Code + from crewai import LLM + + llm = LLM( + model="anthropic/claude-3-5-sonnet-20241022", + api_key="your-api-key", + base_url="https://api.anthropic.com", # Optional custom endpoint + temperature=0.7, + max_tokens=4096, # Required parameter + top_p=0.9, + stop_sequences=["END", "STOP"], # Anthropic uses stop_sequences + stream=True, # Enable streaming + timeout=60.0, # Request timeout in seconds + max_retries=3 # Maximum retry attempts + ) + ``` + + **Extended Thinking (Claude Sonnet 4 and Beyond):** + + CrewAI supports Anthropic's Extended Thinking feature, which allows Claude to think through problems in a more human-like way before responding. This is particularly useful for complex reasoning, analysis, and problem-solving tasks. + + ```python Code + from crewai import LLM + + # Enable extended thinking with default settings + llm = LLM( + model="anthropic/claude-sonnet-4", + thinking={"type": "enabled"}, + max_tokens=10000 + ) + + # Configure thinking with budget control + llm = LLM( + model="anthropic/claude-sonnet-4", + thinking={ + "type": "enabled", + "budget_tokens": 5000 # Limit thinking tokens + }, + max_tokens=10000 + ) + ``` + + **Thinking Configuration Options:** + - `type`: Set to `"enabled"` to activate extended thinking mode + - `budget_tokens` (optional): Maximum tokens to use for thinking (helps control costs) + + **Models Supporting Extended Thinking:** + - `claude-sonnet-4` and newer models + - `claude-3-7-sonnet` (with extended thinking capabilities) + + **When to Use Extended Thinking:** + - Complex reasoning and multi-step problem solving + - Mathematical calculations and proofs + - Code analysis and debugging + - Strategic planning and decision making + - Research and analytical tasks + + **Note:** Extended thinking consumes additional tokens but can significantly improve response quality for complex tasks. + + **Supported Environment Variables:** + - `ANTHROPIC_API_KEY`: Your Anthropic API key (required) + + **Features:** + - Native tool use support for Claude 3+ models + - Extended Thinking support for Claude Sonnet 4+ + - Streaming support for real-time responses + - Automatic system message handling + - Stop sequences for controlled output + - Token usage tracking + - Multi-turn tool use conversations + + **Important Notes:** + - `max_tokens` is a **required** parameter for all Anthropic models + - Claude uses `stop_sequences` instead of `stop` + - System messages are handled separately from conversation messages + - First message must be from the user (automatically handled) + - Messages must alternate between user and assistant + + **Supported Models:** + + | Model | Context Window | Best For | + |------------------------------|----------------|-----------------------------------------------| + | claude-sonnet-4 | 200,000 tokens | Latest with extended thinking capabilities | + | claude-3-7-sonnet | 200,000 tokens | Advanced reasoning and agentic tasks | + | claude-3-5-sonnet-20241022 | 200,000 tokens | Latest Sonnet with best performance | + | claude-3-5-haiku | 200,000 tokens | Fast, compact model for quick responses | + | claude-3-opus | 200,000 tokens | Most capable for complex tasks | + | claude-3-sonnet | 200,000 tokens | Balanced intelligence and speed | + | claude-3-haiku | 200,000 tokens | Fastest for simple tasks | + | claude-2.1 | 200,000 tokens | Extended context, reduced hallucinations | + | claude-2 | 100,000 tokens | Versatile model for various tasks | + | claude-instant | 100,000 tokens | Fast, cost-effective for everyday tasks | + + **Note:** To use Anthropic, install the required dependencies: + ```bash + uv add "crewai[anthropic]" + ``` + + + + CrewAI provides native integration with Google Gemini through the Google Gen AI Python SDK. + + Set your API key in your `.env` file. If you need a key, check [AI Studio](https://aistudio.google.com/apikey). + + ```toml .env + # Required (one of the following) + GOOGLE_API_KEY= + GEMINI_API_KEY= + + # For Vertex AI Express mode (API key authentication) + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + + # For Vertex AI with service account + GOOGLE_CLOUD_PROJECT= + GOOGLE_CLOUD_LOCATION= # Defaults to us-central1 + ``` + + **Basic Usage:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + api_key="your-api-key", # Or set GOOGLE_API_KEY/GEMINI_API_KEY + temperature=0.7 + ) + ``` + + **Advanced Configuration:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.5-flash", + api_key="your-api-key", + temperature=0.7, + top_p=0.9, + top_k=40, # Top-k sampling parameter + max_output_tokens=8192, + stop_sequences=["END", "STOP"], + stream=True, # Enable streaming + safety_settings={ + "HARM_CATEGORY_HARASSMENT": "BLOCK_NONE", + "HARM_CATEGORY_HATE_SPEECH": "BLOCK_NONE" + } + ) + ``` + + **Vertex AI Express Mode (API Key Authentication):** + + Vertex AI Express mode allows you to use Vertex AI with simple API key authentication instead of service account credentials. This is the quickest way to get started with Vertex AI. + + To enable Express mode, set both environment variables in your `.env` file: + ```toml .env + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + ``` + + Then use the LLM as usual: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7 + ) + ``` + + + To get an Express mode API key: + - New Google Cloud users: Get an [express mode API key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey) + - Existing Google Cloud users: Get a [Google Cloud API key bound to a service account](https://cloud.google.com/docs/authentication/api-keys) + + For more details, see the [Vertex AI Express mode documentation](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey). + + + **Vertex AI Configuration (Service Account):** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-1.5-pro", + project="your-gcp-project-id", + location="us-central1" # GCP region + ) + ``` + + **Supported Environment Variables:** + - `GOOGLE_API_KEY` or `GEMINI_API_KEY`: Your Google API key (required for Gemini API and Vertex AI Express mode) + - `GOOGLE_GENAI_USE_VERTEXAI`: Set to `true` to use Vertex AI (required for Express mode) + - `GOOGLE_CLOUD_PROJECT`: Google Cloud project ID (for Vertex AI with service account) + - `GOOGLE_CLOUD_LOCATION`: GCP location (defaults to `us-central1`) + + **Features:** + - Native function calling support for Gemini 1.5+ and 2.x models + - Streaming support for real-time responses + - Multimodal capabilities (text, images, video) + - Safety settings configuration + - Support for both Gemini API and Vertex AI + - Automatic system instruction handling + - Token usage tracking + + **Gemini Models:** + + Google offers a range of powerful models optimized for different use cases. + + | Model | Context Window | Best For | + |--------------------------------|----------------|-------------------------------------------------------------------| + | gemini-2.5-flash | 1M tokens | Adaptive thinking, cost efficiency | + | gemini-2.5-pro | 1M tokens | Enhanced thinking and reasoning, multimodal understanding | + | gemini-2.0-flash | 1M tokens | Next generation features, speed, thinking | + | gemini-2.0-flash-thinking | 32,768 tokens | Advanced reasoning with thinking process | + | gemini-2.0-flash-lite | 1M tokens | Cost efficiency and low latency | + | gemini-1.5-pro | 2M tokens | Best performing, logical reasoning, coding | + | gemini-1.5-flash | 1M tokens | Balanced multimodal model, good for most tasks | + | gemini-1.5-flash-8b | 1M tokens | Fastest, most cost-efficient | + | gemini-1.0-pro | 32,768 tokens | Earlier generation model | + + **Gemma Models:** + + The Gemini API also supports [Gemma models](https://ai.google.dev/gemma/docs) hosted on Google infrastructure. + + | Model | Context Window | Best For | + |----------------|----------------|------------------------------------| + | gemma-3-1b | 32,000 tokens | Ultra-lightweight tasks | + | gemma-3-4b | 128,000 tokens | Efficient general-purpose tasks | + | gemma-3-12b | 128,000 tokens | Balanced performance and efficiency| + | gemma-3-27b | 128,000 tokens | High-performance tasks | + + **Note:** To use Google Gemini, install the required dependencies: + ```bash + uv add "crewai[google-genai]" + ``` + + The full list of models is available in the [Gemini model docs](https://ai.google.dev/gemini-api/docs/models). + + + Get credentials from your Google Cloud Console and save it to a JSON file, then load it with the following code: + ```python Code + import json + + file_path = 'path/to/vertex_ai_service_account.json' + + # Load the JSON file + with open(file_path, 'r') as file: + vertex_credentials = json.load(file) + + # Convert the credentials to a JSON string + vertex_credentials_json = json.dumps(vertex_credentials) + ``` + + Example usage in your CrewAI project: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini-1.5-pro-latest", # or vertex_ai/gemini-1.5-pro-latest + temperature=0.7, + vertex_credentials=vertex_credentials_json + ) + ``` + + Google offers a range of powerful models optimized for different use cases: + + | Model | Context Window | Best For | + |--------------------------------|----------------|-------------------------------------------------------------------| + | gemini-2.5-flash-preview-04-17 | 1M tokens | Adaptive thinking, cost efficiency | + | gemini-2.5-pro-preview-05-06 | 1M tokens | Enhanced thinking and reasoning, multimodal understanding, advanced coding, and more | + | gemini-2.0-flash | 1M tokens | Next generation features, speed, thinking, and realtime streaming | + | gemini-2.0-flash-lite | 1M tokens | Cost efficiency and low latency | + | gemini-1.5-flash | 1M tokens | Balanced multimodal model, good for most tasks | + | gemini-1.5-flash-8B | 1M tokens | Fastest, most cost-efficient, good for high-frequency tasks | + | gemini-1.5-pro | 2M tokens | Best performing, wide variety of reasoning tasks including logical reasoning, coding, and creative collaboration | + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + CrewAI provides native integration with Azure AI Inference and Azure OpenAI through the Azure AI Inference Python SDK. + + ```toml Code + # Required + AZURE_API_KEY= + AZURE_ENDPOINT= + + # Optional + AZURE_API_VERSION= # Defaults to 2024-06-01 + ``` + + **Endpoint URL Formats:** + + For Azure OpenAI deployments: + ``` + https://.openai.azure.com/openai/deployments/ + ``` + + For Azure AI Inference endpoints: + ``` + https://.inference.azure.com + ``` + + **Basic Usage:** + ```python Code + llm = LLM( + model="azure/gpt-4", + api_key="", # Or set AZURE_API_KEY + endpoint="", + api_version="2024-06-01" + ) + ``` + + **Advanced Configuration:** + ```python Code + llm = LLM( + model="azure/gpt-4o", + temperature=0.7, + max_tokens=4000, + top_p=0.9, + frequency_penalty=0.0, + presence_penalty=0.0, + stop=["END"], + stream=True, + timeout=60.0, + max_retries=3 + ) + ``` + + **Supported Environment Variables:** + - `AZURE_API_KEY`: Your Azure API key (required) + - `AZURE_ENDPOINT`: Your Azure endpoint URL (required, also checks `AZURE_OPENAI_ENDPOINT` and `AZURE_API_BASE`) + - `AZURE_API_VERSION`: API version (optional, defaults to `2024-06-01`) + + **Features:** + - Native function calling support for Azure OpenAI models (gpt-4, gpt-4o, gpt-3.5-turbo, etc.) + - Streaming support for real-time responses + - Automatic endpoint URL validation and correction + - Comprehensive error handling with retry logic + - Token usage tracking + + **Note:** To use Azure AI Inference, install the required dependencies: + ```bash + uv add "crewai[azure-ai-inference]" + ``` + + + + CrewAI provides native integration with AWS Bedrock through the boto3 SDK using the Converse API. + + ```toml Code + # Required + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + + # Optional + AWS_SESSION_TOKEN= # For temporary credentials + AWS_DEFAULT_REGION= # Defaults to us-east-1 + AWS_REGION_NAME= # Alternative configuration for backwards compatibility with LiteLLM. Defaults to us-east-1 + ``` + + **Basic Usage:** + ```python Code + from crewai import LLM + + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + region_name="us-east-1" + ) + ``` + + **Advanced Configuration:** + ```python Code + from crewai import LLM + + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_access_key_id="your-access-key", # Or set AWS_ACCESS_KEY_ID + aws_secret_access_key="your-secret-key", # Or set AWS_SECRET_ACCESS_KEY + aws_session_token="your-session-token", # For temporary credentials + region_name="us-east-1", + temperature=0.7, + max_tokens=4096, + top_p=0.9, + top_k=250, # For Claude models + stop_sequences=["END", "STOP"], + stream=True, # Enable streaming + guardrail_config={ # Optional content filtering + "guardrailIdentifier": "your-guardrail-id", + "guardrailVersion": "1" + }, + additional_model_request_fields={ # Model-specific parameters + "top_k": 250 + } + ) + ``` + + **Supported Environment Variables:** + - `AWS_ACCESS_KEY_ID`: AWS access key (required) + - `AWS_SECRET_ACCESS_KEY`: AWS secret key (required) + - `AWS_SESSION_TOKEN`: AWS session token for temporary credentials (optional) + - `AWS_DEFAULT_REGION`: AWS region (defaults to `us-east-1`) + - `AWS_REGION_NAME`: AWS region (defaults to `us-east-1`). Alternative configuration for backwards compatibility with LiteLLM + + **Features:** + - Native tool calling support via Converse API + - Streaming and non-streaming responses + - Comprehensive error handling with retry logic + - Guardrail configuration for content filtering + - Model-specific parameters via `additional_model_request_fields` + - Token usage tracking and stop reason logging + - Support for all Bedrock foundation models + - Automatic conversation format handling + + **Important Notes:** + - Uses the modern Converse API for unified model access + - Automatic handling of model-specific conversation requirements + - System messages are handled separately from conversation + - First message must be from user (automatically handled) + - Some models (like Cohere) require conversation to end with user message + + [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) is a managed service that provides access to multiple foundation models from top AI companies through a unified API. + + | Model | Context Window | Best For | + |-------------------------|----------------------|-------------------------------------------------------------------| + | Amazon Nova Pro | Up to 300k tokens | High-performance, model balancing accuracy, speed, and cost-effectiveness across diverse tasks. | + | Amazon Nova Micro | Up to 128k tokens | High-performance, cost-effective text-only model optimized for lowest latency responses. | + | Amazon Nova Lite | Up to 300k tokens | High-performance, affordable multimodal processing for images, video, and text with real-time capabilities. | + | Claude 3.7 Sonnet | Up to 128k tokens | High-performance, best for complex reasoning, coding & AI agents | + | Claude 3.5 Sonnet v2 | Up to 200k tokens | State-of-the-art model specialized in software engineering, agentic capabilities, and computer interaction at optimized cost. | + | Claude 3.5 Sonnet | Up to 200k tokens | High-performance model delivering superior intelligence and reasoning across diverse tasks with optimal speed-cost balance. | + | Claude 3.5 Haiku | Up to 200k tokens | Fast, compact multimodal model optimized for quick responses and seamless human-like interactions | + | Claude 3 Sonnet | Up to 200k tokens | Multimodal model balancing intelligence and speed for high-volume deployments. | + | Claude 3 Haiku | Up to 200k tokens | Compact, high-speed multimodal model optimized for quick responses and natural conversational interactions | + | Claude 3 Opus | Up to 200k tokens | Most advanced multimodal model exceling at complex tasks with human-like reasoning and superior contextual understanding. | + | Claude 2.1 | Up to 200k tokens | Enhanced version with expanded context window, improved reliability, and reduced hallucinations for long-form and RAG applications | + | Claude | Up to 100k tokens | Versatile model excelling in sophisticated dialogue, creative content, and precise instruction following. | + | Claude Instant | Up to 100k tokens | Fast, cost-effective model for everyday tasks like dialogue, analysis, summarization, and document Q&A | + | Llama 3.1 405B Instruct | Up to 128k tokens | Advanced LLM for synthetic data generation, distillation, and inference for chatbots, coding, and domain-specific tasks. | + | Llama 3.1 70B Instruct | Up to 128k tokens | Powers complex conversations with superior contextual understanding, reasoning and text generation. | + | Llama 3.1 8B Instruct | Up to 128k tokens | Advanced state-of-the-art model with language understanding, superior reasoning, and text generation. | + | Llama 3 70B Instruct | Up to 8k tokens | Powers complex conversations with superior contextual understanding, reasoning and text generation. | + | Llama 3 8B Instruct | Up to 8k tokens | Advanced state-of-the-art LLM with language understanding, superior reasoning, and text generation. | + | Titan Text G1 - Lite | Up to 4k tokens | Lightweight, cost-effective model optimized for English tasks and fine-tuning with focus on summarization and content generation. | + | Titan Text G1 - Express | Up to 8k tokens | Versatile model for general language tasks, chat, and RAG applications with support for English and 100+ languages. | + | Cohere Command | Up to 4k tokens | Model specialized in following user commands and delivering practical enterprise solutions. | + | Jurassic-2 Mid | Up to 8,191 tokens | Cost-effective model balancing quality and affordability for diverse language tasks like Q&A, summarization, and content generation. | + | Jurassic-2 Ultra | Up to 8,191 tokens | Model for advanced text generation and comprehension, excelling in complex tasks like analysis and content creation. | + | Jamba-Instruct | Up to 256k tokens | Model with extended context window optimized for cost-effective text generation, summarization, and Q&A. | + | Mistral 7B Instruct | Up to 32k tokens | This LLM follows instructions, completes requests, and generates creative text. | + | Mistral 8x7B Instruct | Up to 32k tokens | An MOE LLM that follows instructions, completes requests, and generates creative text. | + | DeepSeek R1 | 32,768 tokens | Advanced reasoning model | + + **Note:** To use AWS Bedrock, install the required dependencies: + ```bash + uv add "crewai[bedrock]" + ``` + + + + ```toml Code + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_DEFAULT_REGION= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="sagemaker/" + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + MISTRAL_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="mistral/mistral-large-latest", + temperature=0.7 + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + NVIDIA_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="nvidia_nim/meta/llama3-70b-instruct", + temperature=0.7 + ) + ``` + + Nvidia NIM provides a comprehensive suite of models for various use cases, from general-purpose tasks to specialized applications. + + | Model | Context Window | Best For | + |-------------------------------------------------------------------------|----------------|-------------------------------------------------------------------| + | nvidia/mistral-nemo-minitron-8b-8k-instruct | 8,192 tokens | State-of-the-art small language model delivering superior accuracy for chatbot, virtual assistants, and content generation. | + | nvidia/nemotron-4-mini-hindi-4b-instruct | 4,096 tokens | A bilingual Hindi-English SLM for on-device inference, tailored specifically for Hindi Language. | + | nvidia/llama-3.1-nemotron-70b-instruct | 128k tokens | Customized for enhanced helpfulness in responses | + | nvidia/llama3-chatqa-1.5-8b | 128k tokens | Advanced LLM to generate high-quality, context-aware responses for chatbots and search engines. | + | nvidia/llama3-chatqa-1.5-70b | 128k tokens | Advanced LLM to generate high-quality, context-aware responses for chatbots and search engines. | + | nvidia/vila | 128k tokens | Multi-modal vision-language model that understands text/img/video and creates informative responses | + | nvidia/neva-22 | 4,096 tokens | Multi-modal vision-language model that understands text/images and generates informative responses | + | nvidia/nemotron-mini-4b-instruct | 8,192 tokens | General-purpose tasks | + | nvidia/usdcode-llama3-70b-instruct | 128k tokens | State-of-the-art LLM that answers OpenUSD knowledge queries and generates USD-Python code. | + | nvidia/nemotron-4-340b-instruct | 4,096 tokens | Creates diverse synthetic data that mimics the characteristics of real-world data. | + | meta/codellama-70b | 100k tokens | LLM capable of generating code from natural language and vice versa. | + | meta/llama2-70b | 4,096 tokens | Cutting-edge large language AI model capable of generating text and code in response to prompts. | + | meta/llama3-8b-instruct | 8,192 tokens | Advanced state-of-the-art LLM with language understanding, superior reasoning, and text generation. | + | meta/llama3-70b-instruct | 8,192 tokens | Powers complex conversations with superior contextual understanding, reasoning and text generation. | + | meta/llama-3.1-8b-instruct | 128k tokens | Advanced state-of-the-art model with language understanding, superior reasoning, and text generation. | + | meta/llama-3.1-70b-instruct | 128k tokens | Powers complex conversations with superior contextual understanding, reasoning and text generation. | + | meta/llama-3.1-405b-instruct | 128k tokens | Advanced LLM for synthetic data generation, distillation, and inference for chatbots, coding, and domain-specific tasks. | + | meta/llama-3.2-1b-instruct | 128k tokens | Advanced state-of-the-art small language model with language understanding, superior reasoning, and text generation. | + | meta/llama-3.2-3b-instruct | 128k tokens | Advanced state-of-the-art small language model with language understanding, superior reasoning, and text generation. | + | meta/llama-3.2-11b-vision-instruct | 128k tokens | Advanced state-of-the-art small language model with language understanding, superior reasoning, and text generation. | + | meta/llama-3.2-90b-vision-instruct | 128k tokens | Advanced state-of-the-art small language model with language understanding, superior reasoning, and text generation. | + | google/gemma-7b | 8,192 tokens | Cutting-edge text generation model text understanding, transformation, and code generation. | + | google/gemma-2b | 8,192 tokens | Cutting-edge text generation model text understanding, transformation, and code generation. | + | google/codegemma-7b | 8,192 tokens | Cutting-edge model built on Google's Gemma-7B specialized for code generation and code completion. | + | google/codegemma-1.1-7b | 8,192 tokens | Advanced programming model for code generation, completion, reasoning, and instruction following. | + | google/recurrentgemma-2b | 8,192 tokens | Novel recurrent architecture based language model for faster inference when generating long sequences. | + | google/gemma-2-9b-it | 8,192 tokens | Cutting-edge text generation model text understanding, transformation, and code generation. | + | google/gemma-2-27b-it | 8,192 tokens | Cutting-edge text generation model text understanding, transformation, and code generation. | + | google/gemma-2-2b-it | 8,192 tokens | Cutting-edge text generation model text understanding, transformation, and code generation. | + | google/deplot | 512 tokens | One-shot visual language understanding model that translates images of plots into tables. | + | google/paligemma | 8,192 tokens | Vision language model adept at comprehending text and visual inputs to produce informative responses. | + | mistralai/mistral-7b-instruct-v0.2 | 32k tokens | This LLM follows instructions, completes requests, and generates creative text. | + | mistralai/mixtral-8x7b-instruct-v0.1 | 8,192 tokens | An MOE LLM that follows instructions, completes requests, and generates creative text. | + | mistralai/mistral-large | 4,096 tokens | Creates diverse synthetic data that mimics the characteristics of real-world data. | + | mistralai/mixtral-8x22b-instruct-v0.1 | 8,192 tokens | Creates diverse synthetic data that mimics the characteristics of real-world data. | + | mistralai/mistral-7b-instruct-v0.3 | 32k tokens | This LLM follows instructions, completes requests, and generates creative text. | + | nv-mistralai/mistral-nemo-12b-instruct | 128k tokens | Most advanced language model for reasoning, code, multilingual tasks; runs on a single GPU. | + | mistralai/mamba-codestral-7b-v0.1 | 256k tokens | Model for writing and interacting with code across a wide range of programming languages and tasks. | + | microsoft/phi-3-mini-128k-instruct | 128K tokens | Lightweight, state-of-the-art open LLM with strong math and logical reasoning skills. | + | microsoft/phi-3-mini-4k-instruct | 4,096 tokens | Lightweight, state-of-the-art open LLM with strong math and logical reasoning skills. | + | microsoft/phi-3-small-8k-instruct | 8,192 tokens | Lightweight, state-of-the-art open LLM with strong math and logical reasoning skills. | + | microsoft/phi-3-small-128k-instruct | 128K tokens | Lightweight, state-of-the-art open LLM with strong math and logical reasoning skills. | + | microsoft/phi-3-medium-4k-instruct | 4,096 tokens | Lightweight, state-of-the-art open LLM with strong math and logical reasoning skills. | + | microsoft/phi-3-medium-128k-instruct | 128K tokens | Lightweight, state-of-the-art open LLM with strong math and logical reasoning skills. | + | microsoft/phi-3.5-mini-instruct | 128K tokens | Lightweight multilingual LLM powering AI applications in latency bound, memory/compute constrained environments | + | microsoft/phi-3.5-moe-instruct | 128K tokens | Advanced LLM based on Mixture of Experts architecture to deliver compute efficient content generation | + | microsoft/kosmos-2 | 1,024 tokens | Groundbreaking multimodal model designed to understand and reason about visual elements in images. | + | microsoft/phi-3-vision-128k-instruct | 128k tokens | Cutting-edge open multimodal model exceling in high-quality reasoning from images. | + | microsoft/phi-3.5-vision-instruct | 128k tokens | Cutting-edge open multimodal model exceling in high-quality reasoning from images. | + | databricks/dbrx-instruct | 12k tokens | A general-purpose LLM with state-of-the-art performance in language understanding, coding, and RAG. | + | snowflake/arctic | 1,024 tokens | Delivers high efficiency inference for enterprise applications focused on SQL generation and coding. | + | aisingapore/sea-lion-7b-instruct | 4,096 tokens | LLM to represent and serve the linguistic and cultural diversity of Southeast Asia | + | ibm/granite-8b-code-instruct | 4,096 tokens | Software programming LLM for code generation, completion, explanation, and multi-turn conversion. | + | ibm/granite-34b-code-instruct | 8,192 tokens | Software programming LLM for code generation, completion, explanation, and multi-turn conversion. | + | ibm/granite-3.0-8b-instruct | 4,096 tokens | Advanced Small Language Model supporting RAG, summarization, classification, code, and agentic AI | + | ibm/granite-3.0-3b-a800m-instruct | 4,096 tokens | Highly efficient Mixture of Experts model for RAG, summarization, entity extraction, and classification | + | mediatek/breeze-7b-instruct | 4,096 tokens | Creates diverse synthetic data that mimics the characteristics of real-world data. | + | upstage/solar-10.7b-instruct | 4,096 tokens | Excels in NLP tasks, particularly in instruction-following, reasoning, and mathematics. | + | writer/palmyra-med-70b-32k | 32k tokens | Leading LLM for accurate, contextually relevant responses in the medical domain. | + | writer/palmyra-med-70b | 32k tokens | Leading LLM for accurate, contextually relevant responses in the medical domain. | + | writer/palmyra-fin-70b-32k | 32k tokens | Specialized LLM for financial analysis, reporting, and data processing | + | 01-ai/yi-large | 32k tokens | Powerful model trained on English and Chinese for diverse tasks including chatbot and creative writing. | + | deepseek-ai/deepseek-coder-6.7b-instruct | 2k tokens | Powerful coding model offering advanced capabilities in code generation, completion, and infilling | + | rakuten/rakutenai-7b-instruct | 1,024 tokens | Advanced state-of-the-art LLM with language understanding, superior reasoning, and text generation. | + | rakuten/rakutenai-7b-chat | 1,024 tokens | Advanced state-of-the-art LLM with language understanding, superior reasoning, and text generation. | + | baichuan-inc/baichuan2-13b-chat | 4,096 tokens | Support Chinese and English chat, coding, math, instruction following, solving quizzes | + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + NVIDIA Nemotron models are designed for demanding agentic workloads, including complex reasoning, long-context analysis, tool use, multilingual tasks, and high-stakes RAG. + + The `NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4` model is a frontier-scale open-weight model from NVIDIA with 550B total parameters and 55B active parameters. It uses a LatentMoE architecture that combines Mamba-2, MoE, Attention, and Multi-Token Prediction (MTP), and supports context lengths up to 1M tokens. + + + `NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4` is a very large model. NVIDIA lists minimum serving requirements of 4x GB200, 4x B200, 4x GB300, 4x B300, or 8x H100 GPUs. For most CrewAI users, the recommended path is to use NVIDIA NIM or another OpenAI-compatible hosted endpoint rather than running it locally. + + + **Hosted NVIDIA NIM usage:** + ```toml Code + NVIDIA_API_KEY= + ``` + + ```python Code + from crewai import LLM + + llm = LLM( + model="nvidia_nim/nvidia/nvidia-nemotron-3-ultra-550b-a55b", + temperature=0.2, + max_tokens=4096, + ) + ``` + + **Self-hosted OpenAI-compatible endpoint:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/nvidia-nemotron-3-ultra-550b-a55b-nvfp4", + base_url="https://your-nemotron-endpoint.example.com/v1", + api_key="your-api-key", + temperature=0.2, + max_tokens=4096, + ) + ``` + + **Model details:** + + | Model | Context Window | Best For | + |-------|----------------|----------| + | `nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4` | Up to 1M tokens | Frontier reasoning, complex agentic workflows, long-context analysis, tool use, multilingual reasoning, and high-stakes RAG | + + **Supported languages:** English, French, Spanish, Italian, German, Japanese, Korean, Hindi, Brazilian Portuguese, and Chinese. + + **Reasoning mode:** Nemotron 3 Ultra supports configurable reasoning via its chat template using `enable_thinking=True` or `enable_thinking=False`. If you are using a hosted endpoint, check your provider's documentation for how that flag is exposed. + + For model details, license, and deployment guidance, see the [NVIDIA Nemotron 3 Ultra model card](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-NVFP4). + + **Note:** Hosted NVIDIA NIM usage uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + + NVIDIA NIM enables you to run powerful LLMs locally on your Windows machine using WSL2 (Windows Subsystem for Linux). + This approach allows you to leverage your NVIDIA GPU for private, secure, and cost-effective AI inference without relying on cloud services. + Perfect for development, testing, or production scenarios where data privacy or offline capabilities are required. + + Here is a step-by-step guide to setting up a local NVIDIA NIM model: + + 1. Follow installation instructions from [NVIDIA Website](https://docs.nvidia.com/nim/wsl2/latest/getting-started.html) + + 2. Install the local model. For Llama 3.1-8b follow [instructions](https://build.nvidia.com/meta/llama-3_1-8b-instruct/deploy) + + 3. Configure your crewai local models: + + ```python Code + from crewai.llm import LLM + + local_nvidia_nim_llm = LLM( + model="openai/meta/llama-3.1-8b-instruct", # it's an openai-api compatible model + base_url="http://localhost:8000/v1", + api_key="", # api_key is required, but you can use any text + ) + + # Then you can use it in your crew: + + @CrewBase + class MyCrew(): + # ... + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + llm=local_nvidia_nim_llm + ) + + # ... + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + + ```toml Code + GROQ_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="groq/llama-3.2-90b-text-preview", + temperature=0.7 + ) + ``` + | Model | Context Window | Best For | + |-------------------|------------------|--------------------------------------------| + | Llama 3.1 70B/8B | 131,072 tokens | High-performance, large context tasks | + | Llama 3.2 Series | 8,192 tokens | General-purpose tasks | + | Mixtral 8x7B | 32,768 tokens | Balanced performance and context | + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + # Required + WATSONX_URL= + WATSONX_APIKEY= + WATSONX_PROJECT_ID= + + # Optional + WATSONX_TOKEN= + WATSONX_DEPLOYMENT_SPACE_ID= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="watsonx/meta-llama/llama-3-1-70b-instruct", + base_url="https://api.watsonx.ai/v1" + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 1. Install Ollama: [ollama.ai](https://ollama.ai/) + 2. Run a model: `ollama run llama3` + 3. Configure: + + ```python Code + llm = LLM( + model="ollama/llama3:70b", + base_url="http://localhost:11434" + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + FIREWORKS_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct", + temperature=0.7 + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + PERPLEXITY_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="llama-3.1-sonar-large-128k-online", + base_url="https://api.perplexity.ai/" + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + HF_TOKEN= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct" + ) + ``` + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + + ```toml Code + SAMBANOVA_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="sambanova/Meta-Llama-3.1-8B-Instruct", + temperature=0.7 + ) + ``` + | Model | Context Window | Best For | + |--------------------|------------------------|----------------------------------------------| + | Llama 3.1 70B/8B | Up to 131,072 tokens | High-performance, large context tasks | + | Llama 3.1 405B | 8,192 tokens | High-performance and output quality | + | Llama 3.2 Series | 8,192 tokens | General-purpose, multimodal tasks | + | Llama 3.3 70B | Up to 131,072 tokens | High-performance and output quality | + | Qwen2 familly | 8,192 tokens | High-performance and output quality | + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + # Required + CEREBRAS_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="cerebras/llama3.1-70b", + temperature=0.7, + max_tokens=8192 + ) + ``` + + + Cerebras features: + - Fast inference speeds + - Competitive pricing + - Good balance of speed and quality + - Support for long context windows + + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + OPENROUTER_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="openrouter/deepseek/deepseek-r1", + base_url="https://openrouter.ai/api/v1", + api_key=OPENROUTER_API_KEY + ) + ``` + + + Open Router models: + - openrouter/deepseek/deepseek-r1 + - openrouter/deepseek/deepseek-chat + + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + + Set the following environment variables in your `.env` file: + ```toml Code + NEBIUS_API_KEY= + ``` + + Example usage in your CrewAI project: + ```python Code + llm = LLM( + model="nebius/Qwen/Qwen3-30B-A3B" + ) + ``` + + + Nebius AI Studio features: + - Large collection of open source models + - Higher rate limits + - Competitive pricing + - Good balance of speed and quality + + + **Note:** This provider uses LiteLLM. Add it as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + + + +## Streaming Responses + +CrewAI supports streaming responses from LLMs, allowing your application to receive and process outputs in real-time as they're generated. + + + + Enable streaming by setting the `stream` parameter to `True` when initializing your LLM: + + ```python + from crewai import LLM + + # Create an LLM with streaming enabled + llm = LLM( + model="openai/gpt-4o", + stream=True # Enable streaming + ) + ``` + + When streaming is enabled, responses are delivered in chunks as they're generated, creating a more responsive user experience. + + + + CrewAI emits events for each chunk received during streaming: + + ```python + from crewai.events import ( + LLMStreamChunkEvent + ) + from crewai.events 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): + # Process each chunk as it arrives + print(f"Received chunk: {event.chunk}") + + my_listener = MyCustomListener() + ``` + + + [Click here](/en/concepts/event-listener#event-listeners) for more details + + + + + All LLM events in CrewAI include agent and task information, allowing you to track and filter LLM interactions by specific agents or tasks: + + ```python + from crewai import LLM, Agent, Task, Crew + from crewai.events import LLMStreamChunkEvent + from crewai.events import BaseEventListener + + class MyCustomListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(LLMStreamChunkEvent) + def on_llm_stream_chunk(source, event): + if researcher.id == event.agent_id: + print("\n==============\n Got event:", event, "\n==============\n") + + + my_listener = MyCustomListener() + + llm = LLM(model="gpt-4o-mini", temperature=0, stream=True) + + researcher = Agent( + role="About User", + goal="You know everything about the user.", + backstory="""You are a master at understanding people and their preferences.""", + llm=llm, + ) + + search = Task( + description="Answer the following questions about the user: {question}", + expected_output="An answer to the question.", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[search]) + + result = crew.kickoff( + inputs={"question": "..."} + ) + ``` + + + This feature is particularly useful for: + - Debugging specific agent behaviors + - Logging LLM usage by task type + - Auditing which agents are making what types of LLM calls + - Performance monitoring of specific tasks + + + + +## Async LLM Calls + +CrewAI supports asynchronous LLM calls for improved performance and concurrency in your AI workflows. Async calls allow you to run multiple LLM requests concurrently without blocking, making them ideal for high-throughput applications and parallel agent operations. + + + + Use the `acall` method for asynchronous LLM requests: + + ```python + import asyncio + from crewai import LLM + + async def main(): + llm = LLM(model="openai/gpt-4o") + + # Single async call + response = await llm.acall("What is the capital of France?") + print(response) + + asyncio.run(main()) + ``` + + The `acall` method supports all the same parameters as the synchronous `call` method, including messages, tools, and callbacks. + + + + Combine async calls with streaming for real-time concurrent responses: + + ```python + import asyncio + from crewai import LLM + + async def stream_async(): + llm = LLM(model="openai/gpt-4o", stream=True) + + response = await llm.acall("Write a short story about AI") + + print(response) + + asyncio.run(stream_async()) + ``` + + + +## Structured LLM Calls + +CrewAI supports structured responses from LLM calls by allowing you to define a `response_format` using a Pydantic model. This enables the framework to automatically parse and validate the output, making it easier to integrate the response into your application without manual post-processing. + +For example, you can define a Pydantic model to represent the expected response structure and pass it as the `response_format` when instantiating the LLM. The model will then be used to convert the LLM output into a structured Python object. + +```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') +``` + +## Advanced Features and Optimization + +Learn how to get the most out of your LLM configuration: + + + + CrewAI includes smart context management features: + + ```python + from crewai import LLM + + # CrewAI automatically handles: + # 1. Token counting and tracking + # 2. Content summarization when needed + # 3. Task splitting for large contexts + + llm = LLM( + model="gpt-4", + max_tokens=4000, # Limit response length + ) + ``` + + + Best practices for context management: + 1. Choose models with appropriate context windows + 2. Pre-process long inputs when possible + 3. Use chunking for large documents + 4. Monitor token usage to optimize costs + + + + + + + Choose the right context window for your task: + - Small tasks (up to 4K tokens): Standard models + - Medium tasks (between 4K-32K): Enhanced models + - Large tasks (over 32K): Large context models + + ```python + # Configure model with appropriate settings + llm = LLM( + model="openai/gpt-4-turbo-preview", + temperature=0.7, # Adjust based on task + max_tokens=4096, # Set based on output needs + timeout=300 # Longer timeout for complex tasks + ) + ``` + + - Lower temperature (0.1 to 0.3) for factual responses + - Higher temperature (0.7 to 0.9) for creative tasks + + + + + 1. Monitor token usage + 2. Implement rate limiting + 3. Use caching when possible + 4. Set appropriate max_tokens limits + + + + + Remember to regularly monitor your token usage and adjust your configuration as needed to optimize costs and performance. + + + + + CrewAI internally uses native sdks for LLM calls, which allows you to drop additional parameters that are not needed for your specific use case. This can help simplify your code and reduce the complexity of your LLM configuration. + For example, if you don't need to send the stop parameter, you can simply omit it from your LLM call: + + ```python + from crewai import LLM + import os + + os.environ["OPENAI_API_KEY"] = "" + + o3_llm = LLM( + model="o3", + drop_params=True, + additional_drop_params=["stop"] + ) + ``` + + + + CrewAI provides message interceptors for several providers, allowing you to hook into request/response cycles at the transport layer. + + **Supported Providers:** + - ✅ OpenAI + - ✅ Anthropic + + **Basic Usage:** + ```python +import httpx +from crewai import LLM +from crewai.llms.hooks import BaseInterceptor + +class CustomInterceptor(BaseInterceptor[httpx.Request, httpx.Response]): + """Custom interceptor to modify requests and responses.""" + + def on_outbound(self, request: httpx.Request) -> httpx.Request: + """Print request before sending to the LLM provider.""" + print(request) + return request + + def on_inbound(self, response: httpx.Response) -> httpx.Response: + """Process response after receiving from the LLM provider.""" + print(f"Status: {response.status_code}") + print(f"Response time: {response.elapsed}") + return response + +# Use the interceptor with an LLM +llm = LLM( + model="openai/gpt-4o", + interceptor=CustomInterceptor() +) + ``` + + **Important Notes:** + - Both methods must return the received object or type of object. + - Modifying received objects may result in unexpected behavior or application crashes. + - Not all providers support interceptors - check the supported providers list above + + + Interceptors operate at the transport layer. This is particularly useful for: + - Message transformation and filtering + - Debugging API interactions + + + + +## Common Issues and Solutions + + + + + Most authentication issues can be resolved by checking API key format and environment variable names. + + + ```bash + # OpenAI + OPENAI_API_KEY=sk-... + + # Anthropic + ANTHROPIC_API_KEY=sk-ant-... + ``` + + + + Always include the provider prefix in model names + + + ```python + # Correct + llm = LLM(model="openai/gpt-4") + + # Incorrect + llm = LLM(model="gpt-4") + ``` + + + + Use larger context models for extensive tasks + + + ```python + # Large context model + llm = LLM(model="openai/gpt-4o") # 128K tokens + ``` + + diff --git a/docs/v1.15.1/en/concepts/memory.mdx b/docs/v1.15.1/en/concepts/memory.mdx new file mode 100644 index 000000000..349546d1c --- /dev/null +++ b/docs/v1.15.1/en/concepts/memory.mdx @@ -0,0 +1,885 @@ +--- +title: Memory +description: Leveraging the unified memory system in CrewAI to enhance agent capabilities. +icon: database +mode: "wide" +--- + +## Overview + +CrewAI provides a **unified memory system** -- a single `Memory` class that replaces separate short-term, long-term, entity, and external memory types with one intelligent API. Memory uses an LLM to analyze content when saving (inferring scope, categories, and importance) and supports adaptive-depth recall with composite scoring that blends semantic similarity, recency, and importance. + +You can use memory four ways: **standalone** (scripts, notebooks), **with Crews**, **with Agents**, or **inside Flows**. + +## Quick Start + +```python +from crewai import Memory + +memory = Memory() + +# Store -- the LLM infers scope, categories, and importance +memory.remember("We decided to use PostgreSQL for the user database.") + +# Retrieve -- results ranked by composite score (semantic + recency + importance) +matches = memory.recall("What database did we choose?") +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Tune scoring for a fast-moving project +memory = Memory(recency_weight=0.5, recency_half_life_days=7) + +# Forget +memory.forget(scope="/project/old") + +# Explore the self-organized scope tree +print(memory.tree()) +print(memory.info("/")) +``` + +## Four Ways to Use Memory + +### Standalone + +Use memory in scripts, notebooks, CLI tools, or as a standalone knowledge base -- no agents or crews required. + +```python +from crewai import Memory + +memory = Memory() + +# Build up knowledge +memory.remember("The API rate limit is 1000 requests per minute.") +memory.remember("Our staging environment uses port 8080.") +memory.remember("The team agreed to use feature flags for all new releases.") + +# Later, recall what you need +matches = memory.recall("What are our API limits?", limit=5) +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Extract atomic facts from a longer text +raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL +next quarter. The budget is $50k. Sarah will lead the migration.""" + +facts = memory.extract_memories(raw) +# ["Migration from MySQL to PostgreSQL planned for next quarter", +# "Database migration budget is $50k", +# "Sarah will lead the database migration"] + +for fact in facts: + memory.remember(fact) +``` + +### With Crews + +Pass `memory=True` for default settings, or pass a configured `Memory` instance for custom behavior. + +```python +from crewai import Crew, Agent, Task, Process, Memory + +# Option 1: Default memory +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + memory=True, + verbose=True, +) + +# Option 2: Custom memory with tuned scoring +memory = Memory( + recency_weight=0.4, + semantic_weight=0.4, + importance_weight=0.2, + recency_half_life_days=14, +) +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + memory=memory, +) +``` + +When `memory=True`, the crew creates a default `Memory()` and passes the crew's `embedder` configuration through automatically. All agents in the crew share the crew's memory unless an agent has its own. Without a custom `embedder`, memory uses OpenAI `text-embedding-3-large` embeddings. + +After each task, the crew automatically extracts discrete facts from the task output and stores them. Before each task, the agent recalls relevant context from memory and injects it into the task prompt. + +### With Agents + +Agents can use the crew's shared memory (default) or receive a scoped view for private context. + +```python +from crewai import Agent, Memory + +memory = Memory() + +# Researcher gets a private scope -- only sees /agent/researcher +researcher = Agent( + role="Researcher", + goal="Find and analyze information", + backstory="Expert researcher with attention to detail", + memory=memory.scope("/agent/researcher"), +) + +# Writer uses crew shared memory (no agent-level memory set) +writer = Agent( + role="Writer", + goal="Produce clear, well-structured content", + backstory="Experienced technical writer", + # memory not set -- uses crew._memory when crew has memory enabled +) +``` + +This pattern gives the researcher private findings while the writer reads from the shared crew memory. + +### With Flows + +Every Flow has built-in memory. Use `self.remember()`, `self.recall()`, and `self.extract_memories()` inside any flow method. + +```python +from crewai.flow.flow import Flow, listen, start + +class ResearchFlow(Flow): + @start() + def gather_data(self): + findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k." + self.remember(findings, scope="/research/databases") + return findings + + @listen(gather_data) + def write_report(self, findings): + # Recall past research to provide context + past = self.recall("database performance benchmarks") + context = "\n".join(f"- {m.record.content}" for m in past) + return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}" +``` + +See the [Flows documentation](/concepts/flows) for more on memory in Flows. + + +## Hierarchical Scopes + +### What Scopes Are + +Memories are organized into a hierarchical tree of scopes, similar to a filesystem. Each scope is a path like `/`, `/project/alpha`, or `/agent/researcher/findings`. + +``` +/ + /company + /company/engineering + /company/product + /project + /project/alpha + /project/beta + /agent + /agent/researcher + /agent/writer +``` + +Scopes provide **context-dependent memory** -- when you recall within a scope, you only search that branch of the tree, which improves both precision and performance. + +### How Scope Inference Works + +When you call `remember()` without specifying a scope, the LLM analyzes the content and the existing scope tree, then suggests the best placement. If no existing scope fits, it creates a new one. Over time, the scope tree grows organically from the content itself -- you don't need to design a schema upfront. + +```python +memory = Memory() + +# LLM infers scope from content +memory.remember("We chose PostgreSQL for the user database.") +# -> might be placed under /project/decisions or /engineering/database + +# You can also specify scope explicitly +memory.remember("Sprint velocity is 42 points", scope="/team/metrics") +``` + +### Visualizing the Scope Tree + +```python +print(memory.tree()) +# / (15 records) +# /project (8 records) +# /project/alpha (5 records) +# /project/beta (3 records) +# /agent (7 records) +# /agent/researcher (4 records) +# /agent/writer (3 records) + +print(memory.info("/project/alpha")) +# ScopeInfo(path='/project/alpha', record_count=5, +# categories=['architecture', 'database'], +# oldest_record=datetime(...), newest_record=datetime(...), +# child_scopes=[]) +``` + +### MemoryScope: Subtree Views + +A `MemoryScope` restricts all operations to a branch of the tree. The agent or code using it can only see and write within that subtree. + +```python +memory = Memory() + +# Create a scope for a specific agent +agent_memory = memory.scope("/agent/researcher") + +# Everything is relative to /agent/researcher +agent_memory.remember("Found three relevant papers on LLM memory.") +# -> stored under /agent/researcher + +agent_memory.recall("relevant papers") +# -> searches only under /agent/researcher + +# Narrow further with subscope +project_memory = agent_memory.subscope("project-alpha") +# -> /agent/researcher/project-alpha +``` + +### Best Practices for Scope Design + +- **Start flat, let the LLM organize.** Don't over-engineer your scope hierarchy upfront. Begin with `memory.remember(content)` and let the LLM's scope inference create structure as content accumulates. + +- **Use `/{entity_type}/{identifier}` patterns.** Natural hierarchies emerge from patterns like `/project/alpha`, `/agent/researcher`, `/company/engineering`, `/customer/acme-corp`. + +- **Scope by concern, not by data type.** Use `/project/alpha/decisions` rather than `/decisions/project/alpha`. This keeps related content together. + +- **Keep depth shallow (2-3 levels).** Deeply nested scopes become too sparse. `/project/alpha/architecture` is good; `/project/alpha/architecture/decisions/databases/postgresql` is too deep. + +- **Use explicit scopes when you know, let the LLM infer when you don't.** If you're storing a known project decision, pass `scope="/project/alpha/decisions"`. If you're storing freeform agent output, omit the scope and let the LLM figure it out. + +### Use Case Examples + +**Multi-project team:** +```python +memory = Memory() +# Each project gets its own branch +memory.remember("Using microservices architecture", scope="/project/alpha/architecture") +memory.remember("GraphQL API for client apps", scope="/project/beta/api") + +# Recall across all projects +memory.recall("API design decisions") + +# Or within a specific project +memory.recall("API design", scope="/project/beta") +``` + +**Per-agent private context with shared knowledge:** +```python +memory = Memory() + +# Researcher has private findings +researcher_memory = memory.scope("/agent/researcher") + +# Writer can read from both its own scope and shared company knowledge +writer_view = memory.slice( + scopes=["/agent/writer", "/company/knowledge"], + read_only=True, +) +``` + +**Customer support (per-customer context):** +```python +memory = Memory() + +# Each customer gets isolated context +memory.remember("Prefers email communication", scope="/customer/acme-corp") +memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp") + +# Shared product docs are accessible to all agents +memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs") +``` + + +## Memory Slices + +### What Slices Are + +A `MemorySlice` is a view across multiple, possibly disjoint scopes. Unlike a scope (which restricts to one subtree), a slice lets you recall from several branches simultaneously. + +### When to Use Slices vs Scopes + +- **Scope**: Use when an agent or code block should be restricted to a single subtree. Example: an agent that only sees `/agent/researcher`. +- **Slice**: Use when you need to combine context from multiple branches. Example: an agent that reads from its own scope plus shared company knowledge. + +### Read-Only Slices + +The most common pattern: give an agent read access to multiple branches without letting it write to shared areas. + +```python +memory = Memory() + +# Agent can recall from its own scope AND company knowledge, +# but cannot write to company knowledge +agent_view = memory.slice( + scopes=["/agent/researcher", "/company/knowledge"], + read_only=True, +) + +matches = agent_view.recall("company security policies", limit=5) +# Searches both /agent/researcher and /company/knowledge, merges and ranks results + +agent_view.remember("new finding") # Raises PermissionError (read-only) +``` + +### Read-Write Slices + +When read-only is disabled, you can write to any of the included scopes, but you must specify which scope explicitly. + +```python +view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False) + +# Must specify scope when writing +view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"]) +``` + + +## Composite Scoring + +Recall results are ranked by a weighted combination of three signals: + +``` +composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance +``` + +Where: +- **similarity** = `1 / (1 + distance)` from the vector index (0 to 1) +- **decay** = `0.5^(age_days / half_life_days)` -- exponential decay (1.0 for today, 0.5 at half-life) +- **importance** = the record's importance score (0 to 1), set at encoding time + +Configure these directly on the `Memory` constructor: + +```python +# Sprint retrospective: favor recent memories, short half-life +memory = Memory( + recency_weight=0.5, + semantic_weight=0.3, + importance_weight=0.2, + recency_half_life_days=7, +) + +# Architecture knowledge base: favor important memories, long half-life +memory = Memory( + recency_weight=0.1, + semantic_weight=0.5, + importance_weight=0.4, + recency_half_life_days=180, +) +``` + +Each `MemoryMatch` includes a `match_reasons` list so you can see why a result ranked where it did (e.g. `["semantic", "recency", "importance"]`). + + +## LLM Analysis Layer + +Memory uses the LLM in three ways: + +1. **On save** -- When you omit scope, categories, or importance, the LLM analyzes the content and suggests scope, categories, importance, and metadata (entities, dates, topics). +2. **On recall** -- For deep/auto recall, the LLM analyzes the query (keywords, time hints, suggested scopes, complexity) to guide retrieval. +3. **Extract memories** -- `extract_memories(content)` breaks raw text (e.g. task output) into discrete memory statements. Agents use this before calling `remember()` on each statement so that atomic facts are stored instead of one large blob. + +All analysis degrades gracefully on LLM failure -- see [Failure Behavior](#failure-behavior). + + +## Memory Consolidation + +When saving new content, the encoding pipeline automatically checks for similar existing records in storage. If the similarity is above `consolidation_threshold` (default 0.85), the LLM decides what to do: + +- **keep** -- The existing record is still accurate and not redundant. +- **update** -- The existing record should be updated with new information (LLM provides the merged content). +- **delete** -- The existing record is outdated, superseded, or contradicted. +- **insert_new** -- Whether the new content should also be inserted as a separate record. + +This prevents duplicates from accumulating. For example, if you save "CrewAI ensures reliable operation" three times, consolidation recognizes the duplicates and keeps only one record. + +### Intra-batch Dedup + +When using `remember_many()`, items within the same batch are compared against each other before hitting storage. If two items have cosine similarity >= `batch_dedup_threshold` (default 0.98), the later one is silently dropped. This catches exact or near-exact duplicates within a single batch without any LLM calls (pure vector math). + +```python +# Only 2 records are stored (the third is a near-duplicate of the first) +memory.remember_many([ + "CrewAI supports complex workflows.", + "Python is a great language.", + "CrewAI supports complex workflows.", # dropped by intra-batch dedup +]) +``` + + +## Non-blocking Saves + +`remember_many()` is **non-blocking** -- it submits the encoding pipeline to a background thread and returns immediately. This means the agent can continue to the next task while memories are being saved. + +```python +# Returns immediately -- save happens in background +memory.remember_many(["Fact A.", "Fact B.", "Fact C."]) + +# recall() automatically waits for pending saves before searching +matches = memory.recall("facts") # sees all 3 records +``` + +### Read Barrier + +Every `recall()` call automatically calls `drain_writes()` before searching, ensuring the query always sees the latest persisted records. This is transparent -- you never need to think about it. + +### Crew Shutdown + +When a crew finishes, `kickoff()` drains all pending memory saves in its `finally` block, so no saves are lost even if the crew completes while background saves are in flight. + +### Standalone Usage + +For scripts or notebooks where there's no crew lifecycle, call `drain_writes()` or `close()` explicitly: + +```python +memory = Memory() +memory.remember_many(["Fact A.", "Fact B."]) + +# Option 1: Wait for pending saves +memory.drain_writes() + +# Option 2: Drain and shut down the background pool +memory.close() +``` + + +## Source and Privacy + +Every memory record can carry a `source` tag for provenance tracking and a `private` flag for access control. + +### Source Tracking + +The `source` parameter identifies where a memory came from: + +```python +# Tag memories with their origin +memory.remember("User prefers dark mode", source="user:alice") +memory.remember("System config updated", source="admin") +memory.remember("Agent found a bug", source="agent:debugger") + +# Recall only memories from a specific source +matches = memory.recall("user preferences", source="user:alice") +``` + +### Private Memories + +Private memories are only visible to recall when the `source` matches: + +```python +# Store a private memory +memory.remember("Alice's API key is sk-...", source="user:alice", private=True) + +# This recall sees the private memory (source matches) +matches = memory.recall("API key", source="user:alice") + +# This recall does NOT see it (different source) +matches = memory.recall("API key", source="user:bob") + +# Admin access: see all private records regardless of source +matches = memory.recall("API key", include_private=True) +``` + +This is particularly useful in multi-user or enterprise deployments where different users' memories should be isolated. + + +## RecallFlow (Deep Recall) + +`recall()` supports two depths: + +- **`depth="shallow"`** -- Direct vector search with composite scoring. Fast (~200ms), no LLM calls. +- **`depth="deep"` (default)** -- Runs a multi-step RecallFlow: query analysis, scope selection, parallel vector search, confidence-based routing, and optional recursive exploration when confidence is low. + +**Smart LLM skip**: Queries shorter than `query_analysis_threshold` (default 200 characters) skip the LLM query analysis entirely, even in deep mode. Short queries like "What database do we use?" are already good search phrases -- the LLM analysis adds little value. This saves ~1-3s per recall for typical short queries. Only longer queries (e.g. full task descriptions) go through LLM distillation into targeted sub-queries. + +```python +# Shallow: pure vector search, no LLM +matches = memory.recall("What did we decide?", limit=10, depth="shallow") + +# Deep (default): intelligent retrieval with LLM analysis for long queries +matches = memory.recall( + "Summarize all architecture decisions from this quarter", + limit=10, + depth="deep", +) +``` + +The confidence thresholds that control the RecallFlow router are configurable: + +```python +memory = Memory( + confidence_threshold_high=0.9, # Only synthesize when very confident + confidence_threshold_low=0.4, # Explore deeper more aggressively + exploration_budget=2, # Allow up to 2 exploration rounds + query_analysis_threshold=200, # Skip LLM for queries shorter than this +) +``` + + +## Embedder Configuration + +Memory needs an embedding model to convert text into vectors for semantic search. By default, `Memory()` uses OpenAI `text-embedding-3-large` embeddings, which produce 3072-dimensional vectors. Set `OPENAI_API_KEY` for the default path, or configure a custom embedder in one of three ways. + + +Existing local memory stores created with 1536-dimensional embeddings, such as `text-embedding-3-small` or `text-embedding-ada-002`, may not be compatible with the `text-embedding-3-large` default. This applies to both the OpenAI and Azure OpenAI providers — Azure's default embedding model also changed from `text-embedding-ada-002` to `text-embedding-3-large`. If local testing fails with an embedding dimension mismatch, reset memory with `crewai reset-memories -m`, delete the local memory storage directory, or explicitly configure the older embedder model until you migrate. + + +### Passing to Memory Directly + +```python +from crewai import Memory + +# As a config dict +memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-large"}}) + +# As a pre-built callable +from crewai.rag.embeddings.factory import build_embedder +embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}) +memory = Memory(embedder=embedder) +``` + +### Via Crew Embedder Config + +When using `memory=True`, the crew's `embedder` config is passed through: + +```python +from crewai import Crew + +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-large"}}, +) +``` + +### Provider Examples + + + +```python +memory = Memory(embedder={ + "provider": "openai", + "config": { + "model_name": "text-embedding-3-large", + # "api_key": "sk-...", # or set OPENAI_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "ollama", + "config": { + "model_name": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "azure", + "config": { + "deployment_id": "your-embedding-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com", + "api_version": "2024-02-01", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-generativeai", + "config": { + "model_name": "gemini-embedding-001", + # "api_key": "...", # or set GOOGLE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-vertex", + "config": { + "model_name": "gemini-embedding-001", + "project_id": "your-gcp-project-id", + "location": "us-central1", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "cohere", + "config": { + "model_name": "embed-english-v3.0", + # "api_key": "...", # or set COHERE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "voyageai", + "config": { + "model": "voyage-3", + # "api_key": "...", # or set VOYAGE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "amazon-bedrock", + "config": { + "model_name": "amazon.titan-embed-text-v1", + # Uses default AWS credentials (boto3 session) + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "huggingface", + "config": { + "model_name": "sentence-transformers/all-MiniLM-L6-v2", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "jina", + "config": { + "model_name": "jina-embeddings-v2-base-en", + # "api_key": "...", # or set JINA_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "watsonx", + "config": { + "model_id": "ibm/slate-30m-english-rtrvr", + "api_key": "your-watsonx-api-key", + "project_id": "your-project-id", + "url": "https://us-south.ml.cloud.ibm.com", + }, +}) +``` + + + +```python +# Pass any callable that takes a list of strings and returns a list of vectors +def my_embedder(texts: list[str]) -> list[list[float]]: + # Your embedding logic here + return [[0.1, 0.2, ...] for _ in texts] + +memory = Memory(embedder=my_embedder) +``` + + + +### Provider Reference + +| Provider | Key | Typical Model | Notes | +| :--- | :--- | :--- | :--- | +| OpenAI | `openai` | `text-embedding-3-large` | Default. Set `OPENAI_API_KEY`. | +| Ollama | `ollama` | `mxbai-embed-large` | Local, no API key needed. | +| Azure OpenAI | `azure` | `text-embedding-3-large` | Default model. Requires `deployment_id`. | +| Google AI | `google-generativeai` | `gemini-embedding-001` | Set `GOOGLE_API_KEY`. | +| Google Vertex | `google-vertex` | `gemini-embedding-001` | Requires `project_id`. | +| Cohere | `cohere` | `embed-english-v3.0` | Strong multilingual support. | +| VoyageAI | `voyageai` | `voyage-3` | Optimized for retrieval. | +| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | Uses boto3 credentials. | +| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | Local sentence-transformers. | +| Jina | `jina` | `jina-embeddings-v2-base-en` | Set `JINA_API_KEY`. | +| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | Requires `project_id`. | +| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | Local, no API key. | +| Custom | `custom` | -- | Requires `embedding_callable`. | + + +## LLM Configuration + +Memory uses an LLM for save analysis (scope, categories, importance inference), consolidation decisions, and deep recall query analysis. You can configure which model to use. + +```python +from crewai import Memory, LLM + +# Default: gpt-4o-mini +memory = Memory() + +# Use a different OpenAI model +memory = Memory(llm="gpt-4o") + +# Use Anthropic +memory = Memory(llm="anthropic/claude-3-haiku-20240307") + +# Use Ollama for fully local/private analysis +memory = Memory(llm="ollama/llama3.2") + +# Use Google Gemini +memory = Memory(llm="gemini/gemini-2.0-flash") + +# Pass a pre-configured LLM instance with custom settings +llm = LLM(model="gpt-4o", temperature=0) +memory = Memory(llm=llm) +``` + +The LLM is initialized **lazily** -- it's only created when first needed. This means `Memory()` never fails at construction time, even if API keys aren't set. Errors only surface when the LLM is actually called (e.g. when saving without explicit scope/categories, or during deep recall). + +For fully offline/private operation, use a local model for both the LLM and embedder: + +```python +memory = Memory( + llm="ollama/llama3.2", + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) +``` + + +## Storage Backend + +- **Default**: LanceDB, stored under `./.crewai/memory` (or `$CREWAI_STORAGE_DIR/memory` if the env var is set, or the path you pass as `storage="path/to/dir"`). +- **Custom backend**: Implement the `StorageBackend` protocol (see `crewai.memory.storage.backend`) and pass an instance to `Memory(storage=your_backend)`. + + +## Discovery + +Inspect the scope hierarchy, categories, and records: + +```python +memory.tree() # Formatted tree of scopes and record counts +memory.tree("/project", max_depth=2) # Subtree view +memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest +memory.list_scopes("/") # Immediate child scopes +memory.list_categories() # Category names and counts +memory.list_records(scope="/project/alpha", limit=20) # Records in a scope, newest first +``` + + +## Failure Behavior + +If the LLM fails during analysis (network error, rate limit, invalid response), memory degrades gracefully: + +- **Save analysis** -- A warning is logged and the memory is still stored with default scope `/`, empty categories, and importance `0.5`. +- **Extract memories** -- The full content is stored as a single memory so nothing is dropped. +- **Query analysis** -- Recall falls back to simple scope selection and vector search so you still get results. + +No exception is raised for these analysis failures; only storage or embedder failures will raise. + + +## Privacy Note + +Memory content is sent to the configured LLM for analysis (scope/categories/importance on save, query analysis and optional deep recall). For sensitive data, use a local LLM (e.g. Ollama) or ensure your provider meets your compliance requirements. + + +## Memory Events + +All memory operations emit events with `source_type="unified_memory"`. You can listen for timing, errors, and content. + +| Event | Description | Key Properties | +| :---- | :---------- | :------------- | +| **MemoryQueryStartedEvent** | Query begins | `query`, `limit` | +| **MemoryQueryCompletedEvent** | Query succeeds | `query`, `results`, `query_time_ms` | +| **MemoryQueryFailedEvent** | Query fails | `query`, `error` | +| **MemorySaveStartedEvent** | Save begins | `value`, `metadata` | +| **MemorySaveCompletedEvent** | Save succeeds | `value`, `save_time_ms` | +| **MemorySaveFailedEvent** | Save fails | `value`, `error` | +| **MemoryRetrievalStartedEvent** | Agent retrieval starts | `task_id` | +| **MemoryRetrievalCompletedEvent** | Agent retrieval done | `task_id`, `memory_content`, `retrieval_time_ms` | + +Example: monitor query time: + +```python +from crewai.events import BaseEventListener, MemoryQueryCompletedEvent + +class MemoryMonitor(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(MemoryQueryCompletedEvent) + def on_done(source, event): + if getattr(event, "source_type", None) == "unified_memory": + print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms") +``` + + +## Troubleshooting + +**Memory not persisting?** +- Ensure the storage path is writable (default `./.crewai/memory`). Pass `storage="./your_path"` to use a different directory, or set the `CREWAI_STORAGE_DIR` environment variable. +- When using a crew, confirm `memory=True` or `memory=Memory(...)` is set. + +**Slow recall?** +- Use `depth="shallow"` for routine agent context. Reserve `depth="deep"` for complex queries. +- Increase `query_analysis_threshold` to skip LLM analysis for more queries. + +**LLM analysis errors in logs?** +- Memory still saves/recalls with safe defaults. Check API keys, rate limits, and model availability if you want full LLM analysis. + +**Background save errors in logs?** +- Memory saves run in a background thread. Errors are emitted as `MemorySaveFailedEvent` but don't crash the agent. Check logs for the root cause (usually LLM or embedder connection issues). + +**Embedding dimension mismatch?** +- Existing local memory stores may have been created with a different embedding model. The default OpenAI memory embedder is now `text-embedding-3-large` (3072 dimensions), while older stores commonly used 1536-dimensional embeddings. For local testing, run `crewai reset-memories -m`, delete the local memory storage directory, or configure the previous embedder model explicitly. + +**Concurrent write conflicts?** +- LanceDB operations are serialized with a shared lock and retried automatically on conflict. This handles multiple `Memory` instances pointing at the same database (e.g. agent memory + crew memory). No action needed. + +**Browse memory from the terminal:** +```bash +crewai memory # Opens the TUI browser +crewai memory --storage-path ./my_memory # Point to a specific directory +``` + +**Reset memory (e.g. for tests):** +```python +crew.reset_memories(command_type="memory") # Resets unified memory +# Or on a Memory instance: +memory.reset() # All scopes +memory.reset(scope="/project/old") # Only that subtree +``` + + +## Configuration Reference + +All configuration is passed as keyword arguments to `Memory(...)`. Every parameter has a sensible default. + +| Parameter | Default | Description | +| :--- | :--- | :--- | +| `llm` | `"gpt-4o-mini"` | LLM for analysis (model name or `BaseLLM` instance). | +| `storage` | `"lancedb"` | Storage backend (`"lancedb"`, a path string, or a `StorageBackend` instance). | +| `embedder` | `None` (OpenAI `text-embedding-3-large`) | Embedder (config dict, callable, or `None` for default OpenAI). | +| `recency_weight` | `0.3` | Weight for recency in composite score. | +| `semantic_weight` | `0.5` | Weight for semantic similarity in composite score. | +| `importance_weight` | `0.2` | Weight for importance in composite score. | +| `recency_half_life_days` | `30` | Days for recency score to halve (exponential decay). | +| `consolidation_threshold` | `0.85` | Similarity above which consolidation is triggered on save. Set to `1.0` to disable. | +| `consolidation_limit` | `5` | Max existing records to compare during consolidation. | +| `default_importance` | `0.5` | Importance assigned when not provided and LLM analysis is skipped. | +| `batch_dedup_threshold` | `0.98` | Cosine similarity for dropping near-duplicates within a `remember_many()` batch. | +| `confidence_threshold_high` | `0.8` | Recall confidence above which results are returned directly. | +| `confidence_threshold_low` | `0.5` | Recall confidence below which deeper exploration is triggered. | +| `complex_query_threshold` | `0.7` | For complex queries, explore deeper below this confidence. | +| `exploration_budget` | `1` | Number of LLM-driven exploration rounds during deep recall. | +| `query_analysis_threshold` | `200` | Queries shorter than this (in characters) skip LLM analysis during deep recall. | diff --git a/docs/v1.15.1/en/concepts/planning.mdx b/docs/v1.15.1/en/concepts/planning.mdx new file mode 100644 index 000000000..c1992718d --- /dev/null +++ b/docs/v1.15.1/en/concepts/planning.mdx @@ -0,0 +1,155 @@ +--- +title: Planning +description: Learn how to add planning to your CrewAI Crew and improve their performance. +icon: ruler-combined +mode: "wide" +--- + +## Overview + +The planning feature in CrewAI allows you to add planning capability to your crew. When enabled, before each Crew iteration, +all Crew information is sent to an AgentPlanner that will plan the tasks step by step, and this plan will be added to each task description. + +### Using the Planning Feature + +Getting started with the planning feature is very easy, the only step required is to add `planning=True` to your Crew: + + +```python Code +from crewai import Crew, Agent, Task, Process + +# Assemble your crew with planning capabilities +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, +) +``` + + +From this point on, your crew will have planning enabled, and the tasks will be planned before each iteration. + + +When planning is enabled, crewAI will use `gpt-4o-mini` as the default LLM for planning, which requires a valid OpenAI API key. Since your agents might be using different LLMs, this could cause confusion if you don't have an OpenAI API key configured or if you're experiencing unexpected behavior related to LLM API calls. + + +#### Planning LLM + +Now you can define the LLM that will be used to plan the tasks. + +When running the base case example, you will see something like the output below, which represents the output of the `AgentPlanner` +responsible for creating the step-by-step logic to add to the Agents' tasks. + + +```python Code +from crewai import Crew, Agent, Task, Process + +# Assemble your crew with planning capabilities and custom LLM +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, + planning_llm="gpt-4o" +) + +# Run the crew +my_crew.kickoff() +``` + +```markdown Result +[2024-07-15 16:49:11][INFO]: Planning the crew execution +**Step-by-Step Plan for Task Execution** + +**Task Number 1: Conduct a thorough research about AI LLMs** + +**Agent:** AI LLMs Senior Data Researcher + +**Agent Goal:** Uncover cutting-edge developments in AI LLMs + +**Task Expected Output:** A list with 10 bullet points of the most relevant information about AI LLMs + +**Task Tools:** None specified + +**Agent Tools:** None specified + +**Step-by-Step Plan:** + +1. **Define Research Scope:** + + - Determine the specific areas of AI LLMs to focus on, such as advancements in architecture, use cases, ethical considerations, and performance metrics. + +2. **Identify Reliable Sources:** + + - List reputable sources for AI research, including academic journals, industry reports, conferences (e.g., NeurIPS, ACL), AI research labs (e.g., OpenAI, Google AI), and online databases (e.g., IEEE Xplore, arXiv). + +3. **Collect Data:** + + - Search for the latest papers, articles, and reports published in 2024 and early 2025. + - Use keywords like "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025", etc. + +4. **Analyze Findings:** + + - Read and summarize the key points from each source. + - Highlight new techniques, models, and applications introduced in the past year. + +5. **Organize Information:** + + - Categorize the information into relevant topics (e.g., new architectures, ethical implications, real-world applications). + - Ensure each bullet point is concise but informative. + +6. **Create the List:** + + - Compile the 10 most relevant pieces of information into a bullet point list. + - Review the list to ensure clarity and relevance. + +**Expected Output:** + +A list with 10 bullet points of the most relevant information about AI LLMs. + +--- + +**Task Number 2: Review the context you got and expand each topic into a full section for a report** + +**Agent:** AI LLMs Reporting Analyst + +**Agent Goal:** Create detailed reports based on AI LLMs data analysis and research findings + +**Task Expected Output:** A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```' + +**Task Tools:** None specified + +**Agent Tools:** None specified + +**Step-by-Step Plan:** + +1. **Review the Bullet Points:** + - Carefully read through the list of 10 bullet points provided by the AI LLMs Senior Data Researcher. + +2. **Outline the Report:** + - Create an outline with each bullet point as a main section heading. + - Plan sub-sections under each main heading to cover different aspects of the topic. + +3. **Research Further Details:** + - For each bullet point, conduct additional research if necessary to gather more detailed information. + - Look for case studies, examples, and statistical data to support each section. + +4. **Write Detailed Sections:** + - Expand each bullet point into a comprehensive section. + - Ensure each section includes an introduction, detailed explanation, examples, and a conclusion. + - Use markdown formatting for headings, subheadings, lists, and emphasis. + +5. **Review and Edit:** + - Proofread the report for clarity, coherence, and correctness. + - Make sure the report flows logically from one section to the next. + - Format the report according to markdown standards. + +6. **Finalize the Report:** + - Ensure the report is complete with all sections expanded and detailed. + - Double-check formatting and make any necessary adjustments. + +**Expected Output:** +A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'. +``` + \ No newline at end of file diff --git a/docs/v1.15.1/en/concepts/processes.mdx b/docs/v1.15.1/en/concepts/processes.mdx new file mode 100644 index 000000000..a7411a560 --- /dev/null +++ b/docs/v1.15.1/en/concepts/processes.mdx @@ -0,0 +1,66 @@ +--- +title: Processes +description: Detailed guide on workflow management through processes in CrewAI, with updated implementation details. +icon: bars-staggered +mode: "wide" +--- + +## Overview + + + Processes orchestrate the execution of tasks by agents, akin to project management in human teams. + These processes ensure tasks are distributed and executed efficiently, in alignment with a predefined strategy. + + +## Process Implementations + +- **Sequential**: Executes tasks sequentially, ensuring tasks are completed in an orderly progression. +- **Hierarchical**: Organizes tasks in a managerial hierarchy, where tasks are delegated and executed based on a structured chain of command. A manager language model (`manager_llm`) or a custom manager agent (`manager_agent`) must be specified in the crew to enable the hierarchical process, facilitating the creation and management of tasks by the manager. + +## The Role of Processes in Teamwork +Processes enable individual agents to operate as a cohesive unit, streamlining their efforts to achieve common objectives with efficiency and coherence. + +## Assigning Processes to a Crew +To assign a process to a crew, specify the process type upon crew creation to set the execution strategy. For a hierarchical process, ensure to define `manager_llm` or `manager_agent` for the manager agent. + +```python +from crewai import Crew, Process + +# Example: Creating a crew with a sequential process +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.sequential +) + +# Example: Creating a crew with a hierarchical process +# Ensure to provide a manager_llm or manager_agent +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.hierarchical, + manager_llm="gpt-4o" + # or + # manager_agent=my_manager_agent +) +``` +**Note:** Ensure `my_agents` and `my_tasks` are defined prior to creating a `Crew` object, and for the hierarchical process, either `manager_llm` or `manager_agent` is also required. + +## Sequential Process + +This method mirrors dynamic team workflows, progressing through tasks in a thoughtful and systematic manner. Task execution follows the predefined order in the task list, with the output of one task serving as context for the next. + +To customize task context, utilize the `context` parameter in the `Task` class to specify outputs that should be used as context for subsequent tasks. + +## Hierarchical Process + +Emulates a corporate hierarchy, CrewAI allows specifying a custom manager agent or automatically creates one, requiring the specification of a manager language model (`manager_llm`). This agent oversees task execution, including planning, delegation, and validation. Tasks are not pre-assigned; the manager allocates tasks to agents based on their capabilities, reviews outputs, and assesses task completion. + +## Process Class: Detailed Overview + +The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`). + +## Conclusion + +The structured collaboration facilitated by processes within CrewAI is crucial for enabling systematic teamwork among agents. +This documentation has been updated to reflect the latest features and enhancements, ensuring users have access to the most current and comprehensive information. \ No newline at end of file diff --git a/docs/v1.15.1/en/concepts/production-architecture.mdx b/docs/v1.15.1/en/concepts/production-architecture.mdx new file mode 100644 index 000000000..82f873860 --- /dev/null +++ b/docs/v1.15.1/en/concepts/production-architecture.mdx @@ -0,0 +1,162 @@ +--- +title: Production Architecture +description: Best practices for building production-ready AI applications with CrewAI +icon: server +mode: "wide" +--- + +# The Flow-First Mindset + +When building production AI applications with CrewAI, **we recommend starting with a Flow**. + +While it's possible to run individual Crews or Agents, wrapping them in a Flow provides the necessary structure for a robust, scalable application. + +## Why Flows? + +1. **State Management**: Flows provide a built-in way to manage state across different steps of your application. This is crucial for passing data between Crews, maintaining context, and handling user inputs. +2. **Control**: Flows allow you to define precise execution paths, including loops, conditionals, and branching logic. This is essential for handling edge cases and ensuring your application behaves predictably. +3. **Observability**: Flows provide a clear structure that makes it easier to trace execution, debug issues, and monitor performance. We recommend using [CrewAI Tracing](/en/observability/tracing) for detailed insights. Simply run `crewai login` to enable free observability features. + +## The Architecture + +A typical production CrewAI application looks like this: + +```mermaid +graph TD + Start((Start)) --> Flow[Flow Orchestrator] + Flow --> State{State Management} + State --> Step1[Step 1: Data Gathering] + Step1 --> Crew1[Research Crew] + Crew1 --> State + State --> Step2{Condition Check} + Step2 -- "Valid" --> Step3[Step 3: Execution] + Step3 --> Crew2[Action Crew] + Step2 -- "Invalid" --> End((End)) + Crew2 --> End +``` + +### 1. The Flow Class +Your `Flow` class is the entry point. It defines the state schema and the methods that execute your logic. + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class AppState(BaseModel): + user_input: str = "" + research_results: str = "" + final_report: str = "" + +class ProductionFlow(Flow[AppState]): + @start() + def gather_input(self): + # ... logic to get input ... + pass + + @listen(gather_input) + def run_research_crew(self): + # ... trigger a Crew ... + pass +``` + +### 2. State Management +Use Pydantic models to define your state. This ensures type safety and makes it clear what data is available at each step. + +- **Keep it minimal**: Store only what you need to persist between steps. +- **Use structured data**: Avoid unstructured dictionaries when possible. + +### 3. Crews as Units of Work +Delegate complex tasks to Crews. A Crew should be focused on a specific goal (e.g., "Research a topic", "Write a blog post"). + +- **Don't over-engineer Crews**: Keep them focused. +- **Pass state explicitly**: Pass the necessary data from the Flow state to the Crew inputs. + +```python + @listen(gather_input) + def run_research_crew(self): + crew = ResearchCrew() + result = crew.kickoff(inputs={"topic": self.state.user_input}) + self.state.research_results = result.raw +``` + +## Control Primitives + +Leverage CrewAI's control primitives to add robustness and control to your Crews. + +### 1. Task Guardrails +Use [Task Guardrails](/en/concepts/tasks#task-guardrails) to validate task outputs before they are accepted. This ensures that your agents produce high-quality results. + +```python +def validate_content(result: TaskOutput) -> Tuple[bool, Any]: + if len(result.raw) < 100: + return (False, "Content is too short. Please expand.") + return (True, result.raw) + +task = Task( + ..., + guardrail=validate_content +) +``` + +### 2. Structured Outputs +Always use structured outputs (`output_pydantic` or `output_json`) when passing data between tasks or to your application. This prevents parsing errors and ensures type safety. + +```python +class ResearchResult(BaseModel): + summary: str + sources: List[str] + +task = Task( + ..., + output_pydantic=ResearchResult +) +``` + +### 3. LLM Hooks +Use [LLM Hooks](/en/learn/llm-hooks) to inspect or modify messages before they are sent to the LLM, or to sanitize responses. + +```python +@before_llm_call +def log_request(context): + print(f"Agent {context.agent.role} is calling the LLM...") +``` + +## Deployment Patterns + +When deploying your Flow, consider the following: + +### CrewAI Enterprise +The easiest way to deploy your Flow is using CrewAI Enterprise. It handles the infrastructure, authentication, and monitoring for you. + +Check out the [Deployment Guide](/en/enterprise/guides/deploy-crew) to get started. + +```bash +crewai deploy create +``` + +### Async Execution +For long-running tasks, use `kickoff_async` to avoid blocking your API. + +### Persistence +Use the `@persist` decorator to save the state of your Flow to a database. This allows you to resume execution if the process crashes or if you need to wait for human input. + +```python +@persist +class ProductionFlow(Flow[AppState]): + # ... +``` + +By default, `@persist` resumes a flow when `kickoff(inputs={"id": })` is supplied, extending the same `flow_uuid` history. To **fork** a persisted flow into a new lineage — hydrate state from a previous run but write under a fresh `state.id` — pass `restore_from_state_id`: + +```python +flow.kickoff(restore_from_state_id="") +``` + +The new run gets a fresh `state.id` (auto-generated, or `inputs["id"]` if pinned) so its `@persist` writes don't extend the source's history. Combining with `from_checkpoint` raises a `ValueError`; pick one hydration source. + +## Summary + +- **Start with a Flow.** +- **Define a clear State.** +- **Use Crews for complex tasks.** +- **Deploy with an API and persistence.** diff --git a/docs/v1.15.1/en/concepts/reasoning.mdx b/docs/v1.15.1/en/concepts/reasoning.mdx new file mode 100644 index 000000000..d37017f57 --- /dev/null +++ b/docs/v1.15.1/en/concepts/reasoning.mdx @@ -0,0 +1,148 @@ +--- +title: Reasoning +description: "Learn how to enable and use agent reasoning to improve task execution." +icon: brain +mode: "wide" +--- + +## Overview + +Agent reasoning is a feature that allows agents to reflect on a task and create a plan before execution. This helps agents approach tasks more methodically and ensures they're ready to perform the assigned work. + +## Usage + +To enable reasoning for an agent, simply set `reasoning=True` when creating the agent: + +```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 +) +``` + +## How It Works + +When reasoning is enabled, before executing a task, the agent will: + +1. Reflect on the task and create a detailed plan +2. Evaluate whether it's ready to execute the task +3. Refine the plan as necessary until it's ready or max_reasoning_attempts is reached +4. Inject the reasoning plan into the task description before execution + +This process helps the agent break down complex tasks into manageable steps and identify potential challenges before starting. + +## Configuration Options + + + Enable or disable reasoning + + + + Maximum number of attempts to refine the plan before proceeding with execution. If None (default), the agent will continue refining until it's ready. + + +## Example + +Here's a complete example: + +```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) +``` + +## Error Handling + +The reasoning process is designed to be robust, with error handling built in. If an error occurs during reasoning, the agent will proceed with executing the task without the reasoning plan. This ensures that tasks can still be executed even if the reasoning process fails. + +Here's how to handle potential errors in your code: + +```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) +``` + +## Example Reasoning Output + +Here's an example of what a reasoning plan might look like for a data analysis task: + +``` +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. +``` + +This reasoning plan helps the agent organize its approach to the task, consider potential challenges, and ensure it delivers the expected output. diff --git a/docs/v1.15.1/en/concepts/skills.mdx b/docs/v1.15.1/en/concepts/skills.mdx new file mode 100644 index 000000000..d88602b84 --- /dev/null +++ b/docs/v1.15.1/en/concepts/skills.mdx @@ -0,0 +1,306 @@ +--- +title: Skills +description: Filesystem-based skill packages that inject domain expertise and instructions into agent prompts. +icon: bolt +mode: "wide" +--- + +## Overview + +Skills are self-contained directories that provide agents with **domain-specific instructions, guidelines, and reference material**. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body. + +When activated, a skill's instructions are injected directly into the agent's task prompt — giving the agent expertise without requiring any code changes. + + +**Skills are NOT tools.** This is the most common point of confusion. + +- **Skills** inject *instructions and context* into the agent's prompt. They tell the agent *how to think* about a problem. +- **Tools** give the agent *callable functions* to take action (search, read files, call APIs). + +You often need **both**: skills for expertise, tools for action. They are configured independently and complement each other. + + +--- + +## Quick Start + +### 1. Create a Skill Directory + +``` +skills/ +└── code-review/ + ├── SKILL.md # Required — instructions + ├── references/ # Optional — reference docs + │ └── style-guide.md + └── scripts/ # Optional — executable scripts +``` + +### 2. Write Your SKILL.md + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## Code Review Guidelines + +When reviewing code, follow this checklist: + +1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure +2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls +3. **Readability**: Ensure clear naming, appropriate comments, and consistent style +4. **Testing**: Verify adequate test coverage for new functionality + +### Severity Levels +- **Critical**: Security vulnerabilities, data loss risks → block merge +- **Major**: Performance issues, logic errors → request changes +- **Minor**: Style issues, naming suggestions → approve with comments +``` + +### 3. Attach to an Agent + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # Injects review guidelines + tools=[GithubSearchTool(), FileReadTool()], # Lets agent read code +) +``` + +The agent now has both **expertise** (from the skill) and **capabilities** (from the tools). + +--- + +## Skills + Tools: Working Together + +Here are common patterns showing how skills and tools complement each other: + +### Pattern 1: Skills Only (Domain Expertise, No Actions Needed) + +Use when the agent needs specific instructions but doesn't need to call external services: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # Writing guidelines and templates + # No tools needed — agent writes based on provided context +) +``` + +### Pattern 2: Tools Only (Actions, No Special Expertise) + +Use when the agent needs to take action but doesn't need domain-specific instructions: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # Can search and scrape + # No skills needed — general research doesn't need special guidelines +) +``` + +### Pattern 3: Skills + Tools (Expertise AND Actions) + +The most common real-world pattern. The skill provides *how* to approach the work; tools provide *what* the agent can do: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # Audit methodology and checklists + tools=[ + SerperDevTool(), # Research known vulnerabilities + FileReadTool(), # Read config files + CodeInterpreterTool(), # Run analysis scripts + ], +) +``` + +### Pattern 4: Skills + MCPs + +Skills work alongside MCP servers the same way they work with tools: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # Analysis methodology + mcps=["https://data-warehouse.example.com/sse"], # Remote data access +) +``` + +### Pattern 5: Skills + Apps + +Skills can guide how an agent uses platform integrations: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # Response templates and escalation rules + apps=["gmail", "zendesk"], # Can send emails and update tickets +) +``` + +--- + +## Crew-Level Skills + +Skills can be set on a crew to apply to **all agents**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # All agents get these skills +) +``` + +Agent-level skills take priority — if the same skill is discovered at both levels, the agent's version is used. + +--- + +## SKILL.md Format + +```markdown +--- +name: my-skill +description: Short description of what this skill does and when to use it. +license: Apache-2.0 # optional +compatibility: crewai>=0.1.0 # optional +metadata: # optional + author: your-name + version: "1.0" +allowed-tools: web-search file-read # optional, experimental +--- + +Instructions for the agent go here. This markdown body is injected +into the agent's prompt when the skill is activated. +``` + +### Frontmatter Fields + +| Field | Required | Description | +| :-------------- | :------- | :----------------------------------------------------------------------- | +| `name` | Yes | 1–64 chars. Lowercase alphanumeric and hyphens. Must match directory name. | +| `description` | Yes | 1–1024 chars. Describes what the skill does and when to use it. | +| `license` | No | License name or reference to a bundled license file. | +| `compatibility` | No | Max 500 chars. Environment requirements (products, packages, network). | +| `metadata` | No | Arbitrary string key-value mapping. | +| `allowed-tools` | No | Space-delimited list of pre-approved tools. Experimental. | + +--- + +## Directory Structure + +``` +my-skill/ +├── SKILL.md # Required — frontmatter + instructions +├── scripts/ # Optional — executable scripts +├── references/ # Optional — reference documents +└── assets/ # Optional — static files (configs, data) +``` + +The directory name must match the `name` field in `SKILL.md`. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly. + +--- + +## Pre-loading Skills + +For more control, you can discover and activate skills programmatically: + +```python +from pathlib import Path +from crewai.skills import discover_skills, activate_skill + +# Discover all skills in a directory +skills = discover_skills(Path("./skills")) + +# Activate them (loads full SKILL.md body) +activated = [activate_skill(s) for s in skills] + +# Pass to an agent +agent = Agent( + role="Researcher", + goal="Find relevant information", + backstory="An expert researcher.", + skills=activated, +) +``` + +--- + +## How Skills Are Loaded + +Skills use **progressive disclosure** — only loading what's needed at each stage: + +| Stage | What's loaded | When | +| :--------- | :------------------------------------ | :------------------ | +| Discovery | Name, description, frontmatter fields | `discover_skills()` | +| Activation | Full SKILL.md body text | `activate_skill()` | + +During normal agent execution (passing directory paths via `skills=["./skills"]`), skills are automatically discovered and activated. The progressive loading only matters when using the programmatic API. + +--- + +## Skills vs Knowledge + +Both skills and knowledge modify the agent's prompt, but they serve different purposes: + +| Aspect | Skills | Knowledge | +| :--- | :--- | :--- | +| **What it provides** | Instructions, procedures, guidelines | Facts, data, information | +| **How it's stored** | Markdown files (SKILL.md) | Embedded in vector store (ChromaDB) | +| **How it's retrieved** | Entire body injected into prompt | Semantic search finds relevant chunks | +| **Best for** | Methodology, checklists, style guides | Company docs, product info, reference data | +| **Set via** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**Rule of thumb:** If the agent needs to follow a *process*, use a skill. If the agent needs to reference *data*, use knowledge. + +--- + +## Common Questions + + + + It depends on your use case. Skills and tools are **independent** — you can use either, both, or neither. + + - **Skills alone**: When the agent needs expertise but no external actions (e.g., writing with style guidelines) + - **Tools alone**: When the agent needs actions but no special methodology (e.g., simple web search) + - **Both**: When the agent needs expertise AND actions (e.g., security audit with specific checklists AND ability to scan code) + + + + **No.** The `allowed-tools` field in SKILL.md is experimental metadata only — it does not provision or inject any tools. You must always set tools separately via `tools=[]`, `mcps=[]`, or `apps=[]`. + + + + The agent-level skill takes priority. Skills are deduplicated by name — the agent's skills are processed first, so if the same skill name appears at both levels, the agent's version is used. + + + + There's a soft warning at 50,000 characters, but no hard limit. Keep skills focused and concise for best results — large prompt injections can dilute the agent's attention. + + diff --git a/docs/v1.15.1/en/concepts/tasks.mdx b/docs/v1.15.1/en/concepts/tasks.mdx new file mode 100644 index 000000000..6a11465b5 --- /dev/null +++ b/docs/v1.15.1/en/concepts/tasks.mdx @@ -0,0 +1,1036 @@ +--- +title: Tasks +description: Detailed guide on managing and creating tasks within the CrewAI framework. +icon: list-check +mode: "wide" +--- + +## Overview + +In the CrewAI framework, a `Task` is a specific assignment completed by an `Agent`. + +Tasks provide all necessary details for execution, such as a description, the agent responsible, required tools, and more, facilitating a wide range of action complexities. + +Tasks within CrewAI can be collaborative, requiring multiple agents to work together. This is managed through the task properties and orchestrated by the Crew's process, enhancing teamwork and efficiency. + + +CrewAI AMP includes a Visual Task Builder in Crew Studio that simplifies complex task creation and chaining. Design your task flows visually and test them in real-time without writing code. + +![Task Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +The Visual Task Builder enables: + +- Drag-and-drop task creation +- Visual task dependencies and flow +- Real-time testing and validation +- Easy sharing and collaboration + + +### Task Execution Flow + +Tasks can be executed in two ways: + +- **Sequential**: Tasks are executed in the order they are defined +- **Hierarchical**: Tasks are assigned to agents based on their roles and expertise + +The execution flow is defined when creating the crew: + +```python Code +crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + process=Process.sequential # or Process.hierarchical +) +``` + +## Task Attributes + +| Attribute | Parameters | Type | Description | +| :------------------------------------- | :---------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------- | +| **Description** | `description` | `str` | A clear, concise statement of what the task entails. | +| **Expected Output** | `expected_output` | `str` | A detailed description of what the task's completion looks like. | +| **Name** _(optional)_ | `name` | `Optional[str]` | A name identifier for the task. | +| **Agent** _(optional)_ | `agent` | `Optional[BaseAgent]` | The agent responsible for executing the task. | +| **Tools** _(optional)_ | `tools` | `List[BaseTool]` | The tools/resources the agent is limited to use for this task. | +| **Context** _(optional)_ | `context` | `Optional[List["Task"]]` | Other tasks whose outputs will be used as context for this task. | +| **Async Execution** _(optional)_ | `async_execution` | `Optional[bool]` | Whether the task should be executed asynchronously. Defaults to False. | +| **Human Input** _(optional)_ | `human_input` | `Optional[bool]` | Whether the task should have a human review the final answer of the agent. Defaults to False. | +| **Markdown** _(optional)_ | `markdown` | `Optional[bool]` | Whether the task should instruct the agent to return the final answer formatted in Markdown. Defaults to False. | +| **Config** _(optional)_ | `config` | `Optional[Dict[str, Any]]` | Task-specific configuration parameters. | +| **Output File** _(optional)_ | `output_file` | `Optional[str]` | File path for storing the task output. | +| **Create Directory** _(optional)_ | `create_directory` | `Optional[bool]` | Whether to create the directory for output_file if it doesn't exist. Defaults to True. | +| **Output JSON** _(optional)_ | `output_json` | `Optional[Type[BaseModel]]` | A Pydantic model to structure the JSON output. | +| **Output Pydantic** _(optional)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | A Pydantic model for task output. | +| **Callback** _(optional)_ | `callback` | `Optional[Any]` | Function/object to be executed after task completion. | +| **Guardrail** _(optional)_ | `guardrail` | `Optional[Callable]` | Function to validate task output before proceeding to next task. | +| **Guardrails** _(optional)_ | `guardrails` | `Optional[List[Callable]]` | List of guardrails to validate task output before proceeding to next task. | +| **Guardrail Max Retries** _(optional)_ | `guardrail_max_retries` | `Optional[int]` | Maximum number of retries when guardrail validation fails. Defaults to 3. | + + + The task attribute `max_retries` is deprecated and will be removed in v1.0.0. + Use `guardrail_max_retries` instead to control retry attempts when a guardrail + fails. + + +## Creating Tasks + +There are two common ways to create tasks in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**. + +### JSONC Configuration (Recommended) + +New projects created with `crewai create crew ` define tasks in `crew.jsonc`. The `agents` array points to files in `agents/`, and the `tasks` array defines the ordered work the crew should run. + +After creating your CrewAI project as outlined in the [Installation](/en/installation) section, edit the generated `crew.jsonc`. + + +Use `{placeholder}` values in task `description`, `expected_output`, and `output_file`. Put defaults in the top-level `inputs` object; `crewai run` prompts for any missing values. + + +Here's an example `crew.jsonc` with two ordered tasks: + +````jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "reporting_analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research about {topic}. Include current and relevant information.", + "expected_output": "A list of the most relevant information about {topic}.", + "agent": "researcher" + }, + { + "name": "reporting_task", + "description": "Review the research and expand it into a detailed report.", + "expected_output": "A polished markdown report without fenced code blocks.", + "agent": "reporting_analyst", + "context": ["research_task"], + "markdown": true, + "output_file": "report.md" + } + ], + "inputs": { + "topic": "AI Agents" + } +} +```` + +Each task must include `description` and `expected_output`. The `agent` value should match an agent name listed in `agents`. `context` is a list of prior task names; forward references are rejected so sequential context stays explicit. + +Task entries support any public `Task` field. Common fields include `name`, `agent`, `context`, `output_file`, `tools`, `human_input`, `async_execution`, `guardrail`, `guardrails`, `guardrail_max_retries`, `markdown`, `input_files`, `output_json`, `output_pydantic`, `response_model`, and `converter_cls`. Use `"type": "ConditionalTask"` with a `condition` field for conditional tasks. + +### Classic YAML Configuration + +Classic projects created with `crewai create crew --classic` use `config/tasks.yaml` and a `@CrewBase` class in `crew.py`. This remains supported for existing YAML projects or teams that prefer decorator-based Python wiring. + +### Direct Code Definition (Alternative) + +Alternatively, you can define tasks directly in your code without using YAML configuration: + +```python task.py +from crewai import Task + +research_task = Task( + description=""" + Conduct a thorough research about AI Agents. + 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 AI Agents + """, + agent=researcher +) + +reporting_task = 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. + """, + agent=reporting_analyst, + markdown=True, # Enable markdown formatting for the final output + output_file="report.md" +) +``` + + + Directly specify an `agent` for assignment or let the `hierarchical` CrewAI's + process decide based on roles, availability, etc. + + +## Task Output + +Understanding task outputs is crucial for building effective AI workflows. CrewAI provides a structured way to handle task results through the `TaskOutput` class, which supports multiple output formats and can be easily passed between tasks. + +The output of a task in CrewAI framework is encapsulated within the `TaskOutput` class. This class provides a structured way to access results of a task, including various formats such as raw output, JSON, and Pydantic models. + +By default, the `TaskOutput` will only include the `raw` output. A `TaskOutput` will only include the `pydantic` or `json_dict` output if the original `Task` object was configured with `output_pydantic` or `output_json`, respectively. + +### Task Output Attributes + +| Attribute | Parameters | Type | Description | +| :---------------- | :-------------- | :------------------------- | :------------------------------------------------------------------------------------------------- | +| **Description** | `description` | `str` | Description of the task. | +| **Summary** | `summary` | `Optional[str]` | Summary of the task, auto-generated from the first 10 words of the description. | +| **Raw** | `raw` | `str` | The raw output of the task. This is the default format for the output. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | A Pydantic model object representing the structured output of the task. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | A dictionary representing the JSON output of the task. | +| **Agent** | `agent` | `str` | The agent that executed the task. | +| **Output Format** | `output_format` | `OutputFormat` | The format of the task output, with options including RAW, JSON, and Pydantic. The default is RAW. | +| **Messages** | `messages` | `list[LLMMessage]` | The messages from the last task execution. | + +### Task Methods and Properties + +| Method/Property | Description | +| :-------------- | :------------------------------------------------------------------------------------------------ | +| **json** | Returns the JSON string representation of the task output if the output format is JSON. | +| **to_dict** | Converts the JSON and Pydantic outputs to a dictionary. | +| **str** | Returns the string representation of the task output, prioritizing Pydantic, then JSON, then raw. | + +### Accessing Task Outputs + +Once a task has been executed, its output can be accessed through the `output` attribute of the `Task` object. The `TaskOutput` class provides various ways to interact with and present this output. + +#### Example + +```python Code +# Example task +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +# Execute the crew +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() + +# Accessing the task output +task_output = task.output + +print(f"Task Description: {task_output.description}") +print(f"Task Summary: {task_output.summary}") +print(f"Raw Output: {task_output.raw}") +if task_output.json_dict: + print(f"JSON Output: {json.dumps(task_output.json_dict, indent=2)}") +if task_output.pydantic: + print(f"Pydantic Output: {task_output.pydantic}") +``` + +## Markdown Output Formatting + +The `markdown` parameter enables automatic markdown formatting for task outputs. When set to `True`, the task will instruct the agent to format the final answer using proper Markdown syntax. + +### Using Markdown Formatting + +```python Code +# Example task with markdown formatting enabled +formatted_task = Task( + description="Create a comprehensive report on AI trends", + expected_output="A well-structured report with headers, sections, and bullet points", + agent=reporter_agent, + markdown=True # Enable automatic markdown formatting +) +``` + +When `markdown=True`, the agent will receive additional instructions to format the output using: + +- `#` for headers +- `**text**` for bold text +- `*text*` for italic text +- `-` or `*` for bullet points +- `` `code` `` for inline code +- ` `language ``` for code blocks + +### YAML Configuration with Markdown + +```yaml tasks.yaml +analysis_task: + description: > + Analyze the market data and create a detailed report + expected_output: > + A comprehensive analysis with charts and key findings + agent: analyst + markdown: true # Enable markdown formatting + output_file: analysis.md +``` + +### Benefits of Markdown Output + +- **Consistent Formatting**: Ensures all outputs follow proper markdown conventions +- **Better Readability**: Structured content with headers, lists, and emphasis +- **Documentation Ready**: Output can be directly used in documentation systems +- **Cross-Platform Compatibility**: Markdown is universally supported + + + The markdown formatting instructions are automatically added to the task + prompt when `markdown=True`, so you don't need to specify formatting + requirements in your task description. + + +## Task Dependencies and Context + +Tasks can depend on the output of other tasks using the `context` attribute. For example: + +```python Code +research_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + agent=researcher +) + +analysis_task = Task( + description="Analyze the research findings and identify key trends", + expected_output="Analysis report of AI trends", + agent=analyst, + context=[research_task] # This task will wait for research_task to complete +) +``` + +## Task Guardrails + +Task guardrails provide a way to validate and transform task outputs before they +are passed to the next task. This feature helps ensure data quality and provides +feedback to agents when their output doesn't meet specific criteria. + +CrewAI supports two types of guardrails: + +1. **Function-based guardrails**: Python functions with custom validation logic, giving you complete control over the validation process and ensuring reliable, deterministic results. + +2. **LLM-based guardrails**: String descriptions that use the agent's LLM to validate outputs based on natural language criteria. These are ideal for complex or subjective validation requirements. + +### Function-Based Guardrails + +To add a function-based guardrail to a task, provide a validation function through the `guardrail` parameter: + +```python Code +from typing import Tuple, Union, Dict, Any +from crewai import TaskOutput + +def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]: + """Validate blog content meets requirements.""" + try: + # Check word count + word_count = len(result.raw.split()) + if word_count > 200: + return (False, "Blog content exceeds 200 words") + + # Additional validation logic here + return (True, result.raw.strip()) + except Exception as e: + return (False, "Unexpected error during validation") + +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail=validate_blog_content # Add the guardrail function +) +``` + +### LLM-Based Guardrails (String Descriptions) + +Instead of writing custom validation functions, you can use string descriptions that leverage LLM-based validation. When you provide a string to the `guardrail` or `guardrails` parameter, CrewAI automatically creates an `LLMGuardrail` that uses the agent's LLM to validate the output based on your description. + +**Requirements**: + +- The task must have an `agent` assigned (the guardrail uses the agent's LLM) +- Provide a clear, descriptive string explaining the validation criteria + +```python Code +from crewai import Task + +# Single LLM-based guardrail +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail="The blog post must be under 200 words and contain no technical jargon" +) +``` + +LLM-based guardrails are particularly useful for: + +- **Complex validation logic** that's difficult to express programmatically +- **Subjective criteria** like tone, style, or quality assessments +- **Natural language requirements** that are easier to describe than code + +The LLM guardrail will: + +1. Analyze the task output against your description +2. Return `(True, output)` if the output complies with the criteria +3. Return `(False, feedback)` with specific feedback if validation fails + +**Example with detailed validation criteria**: + +```python Code +research_task = Task( + description="Research the latest developments in quantum computing", + expected_output="A comprehensive research report", + agent=researcher_agent, + guardrail=""" + The research report must: + - Be at least 1000 words long + - Include at least 5 credible sources + - Cover both technical and practical applications + - Be written in a professional, academic tone + - Avoid speculation or unverified claims + """ +) +``` + +### Multiple Guardrails + +You can apply multiple guardrails to a task using the `guardrails` parameter. Multiple guardrails are executed sequentially, with each guardrail receiving the output from the previous one. This allows you to chain validation and transformation steps. + +The `guardrails` parameter accepts: + +- A list of guardrail functions or string descriptions +- A single guardrail function or string (same as `guardrail`) + +**Note**: If `guardrails` is provided, it takes precedence over `guardrail`. The `guardrail` parameter will be ignored when `guardrails` is set. + +```python Code +from typing import Tuple, Any +from crewai import TaskOutput, Task + +def validate_word_count(result: TaskOutput) -> Tuple[bool, Any]: + """Validate word count is within limits.""" + word_count = len(result.raw.split()) + if word_count < 100: + return (False, f"Content too short: {word_count} words. Need at least 100 words.") + if word_count > 500: + return (False, f"Content too long: {word_count} words. Maximum is 500 words.") + return (True, result.raw) + +def validate_no_profanity(result: TaskOutput) -> Tuple[bool, Any]: + """Check for inappropriate language.""" + profanity_words = ["badword1", "badword2"] # Example list + content_lower = result.raw.lower() + for word in profanity_words: + if word in content_lower: + return (False, f"Inappropriate language detected: {word}") + return (True, result.raw) + +def format_output(result: TaskOutput) -> Tuple[bool, Any]: + """Format and clean the output.""" + formatted = result.raw.strip() + # Capitalize first letter + formatted = formatted[0].upper() + formatted[1:] if formatted else formatted + return (True, formatted) + +# Apply multiple guardrails sequentially +blog_task = Task( + description="Write a blog post about AI", + expected_output="A well-formatted blog post between 100-500 words", + agent=blog_agent, + guardrails=[ + validate_word_count, # First: validate length + validate_no_profanity, # Second: check content + format_output # Third: format the result + ], + guardrail_max_retries=3 +) +``` + +In this example, the guardrails execute in order: + +1. `validate_word_count` checks the word count +2. `validate_no_profanity` checks for inappropriate language (using the output from step 1) +3. `format_output` formats the final result (using the output from step 2) + +If any guardrail fails, the error is sent back to the agent, and the task is retried up to `guardrail_max_retries` times. + +**Mixing function-based and LLM-based guardrails**: + +You can combine both function-based and string-based guardrails in the same list: + +```python Code +from typing import Tuple, Any +from crewai import TaskOutput, Task + +def validate_word_count(result: TaskOutput) -> Tuple[bool, Any]: + """Validate word count is within limits.""" + word_count = len(result.raw.split()) + if word_count < 100: + return (False, f"Content too short: {word_count} words. Need at least 100 words.") + if word_count > 500: + return (False, f"Content too long: {word_count} words. Maximum is 500 words.") + return (True, result.raw) + +# Mix function-based and LLM-based guardrails +blog_task = Task( + description="Write a blog post about AI", + expected_output="A well-formatted blog post between 100-500 words", + agent=blog_agent, + guardrails=[ + validate_word_count, # Function-based: precise word count check + "The content must be engaging and suitable for a general audience", # LLM-based: subjective quality check + "The writing style should be clear, concise, and free of technical jargon" # LLM-based: style validation + ], + guardrail_max_retries=3 +) +``` + +This approach combines the precision of programmatic validation with the flexibility of LLM-based assessment for subjective criteria. + +### Guardrail Function Requirements + +1. **Function Signature**: + + - Must accept exactly one parameter (the task output) + - Should return a tuple of `(bool, Any)` + - Type hints are recommended but optional + +2. **Return Values**: + - On success: it returns a tuple of `(bool, Any)`. For example: `(True, validated_result)` + - On Failure: it returns a tuple of `(bool, str)`. For example: `(False, "Error message explain the failure")` + +### Error Handling Best Practices + +1. **Structured Error Responses**: + +```python Code +from crewai import TaskOutput, LLMGuardrail + +def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]: + try: + # Main validation logic + 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. **Error Categories**: + + - Use specific error codes + - Include relevant context + - Provide actionable feedback + +3. **Validation Chain**: + +```python Code +from typing import Any, Dict, List, Tuple, Union +from crewai import TaskOutput + +def complex_validation(result: TaskOutput) -> Tuple[bool, Any]: + """Chain multiple validation steps.""" + # Step 1: Basic validation + if not result: + return (False, "Empty result") + + # Step 2: Content validation + try: + validated = validate_content(result) + if not validated: + return (False, "Invalid content") + + # Step 3: Format validation + formatted = format_output(validated) + return (True, formatted) + except Exception as e: + return (False, str(e)) +``` + +### Handling Guardrail Results + +When a guardrail returns `(False, error)`: + +1. The error is sent back to the agent +2. The agent attempts to fix the issue +3. The process repeats until: + - The guardrail returns `(True, result)` + - Maximum retries are reached (`guardrail_max_retries`) + +Example with retry handling: + +```python Code +from typing import Optional, Tuple, Union +from crewai import TaskOutput, Task + +def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]: + """Validate and parse JSON output.""" + try: + # Try to parse as JSON + data = json.loads(result) + return (True, data) + except json.JSONDecodeError as e: + return (False, "Invalid JSON format") + +task = Task( + description="Generate a JSON report", + expected_output="A valid JSON object", + agent=analyst, + guardrail=validate_json_output, + guardrail_max_retries=3 # Limit retry attempts +) +``` + +## Getting Structured Consistent Outputs from Tasks + + + It's also important to note that the output of the final task of a crew + becomes the final output of the actual crew itself. + + +### Using `output_pydantic` + +The `output_pydantic` property allows you to define a Pydantic model that the task output should conform to. This ensures that the output is not only structured but also validated according to the Pydantic model. + +Here's an example demonstrating how to use 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="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A compelling blog title and well-written content.", + agent=blog_agent, + output_pydantic=Blog, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Accessing Properties Directly from the Pydantic Model +print("Accessing Properties - Option 2") +title = result.pydantic.title +content = result.pydantic.content +print("Title:", title) +print("Content:", content) + +# Option 3: Accessing Properties Using the to_dict() Method +print("Accessing Properties - Option 3") +output_dict = result.to_dict() +title = output_dict["title"] +content = output_dict["content"] +print("Title:", title) +print("Content:", content) + +# Option 4: Printing the Entire Blog Object +print("Accessing Properties - Option 5") +print("Blog:", result) + +``` + +In this example: + +- A Pydantic model Blog is defined with title and content fields. +- The task task1 uses the output_pydantic property to specify that its output should conform to the Blog model. +- After executing the crew, you can access the structured output in multiple ways as shown. + +#### Explanation of Accessing the Output + +1. Dictionary-Style Indexing: You can directly access the fields using result["field_name"]. This works because the CrewOutput class implements the **getitem** method. +2. Directly from Pydantic Model: Access the attributes directly from the result.pydantic object. +3. Using to_dict() Method: Convert the output to a dictionary and access the fields. +4. Printing the Entire Object: Simply print the result object to see the structured output. + +### Using `output_json` + +The `output_json` property allows you to define the expected output in JSON format. This ensures that the task's output is a valid JSON structure that can be easily parsed and used in your application. + +Here's an example demonstrating how to use `output_json`: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +# Define the Pydantic model for the blog +class Blog(BaseModel): + title: str + content: str + + +# Define the agent +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +# Define the task with output_json set to the Blog model +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A JSON object with 'title' and 'content' fields.", + agent=blog_agent, + output_json=Blog, +) + +# Instantiate the crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +# Kickoff the crew to execute the task +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Printing the Entire Blog Object +print("Accessing Properties - Option 2") +print("Blog:", result) +``` + +In this example: + +- A Pydantic model Blog is defined with title and content fields, which is used to specify the structure of the JSON output. +- The task task1 uses the output_json property to indicate that it expects a JSON output conforming to the Blog model. +- After executing the crew, you can access the structured JSON output in two ways as shown. + +#### Explanation of Accessing the Output + +1. Accessing Properties Using Dictionary-Style Indexing: You can access the fields directly using result["field_name"]. This is possible because the CrewOutput class implements the **getitem** method, allowing you to treat the output like a dictionary. In this option, we're retrieving the title and content from the result. +2. Printing the Entire Blog Object: By printing result, you get the string representation of the CrewOutput object. Since the **str** method is implemented to return the JSON output, this will display the entire output as a formatted string representing the Blog object. + +--- + +By using output_pydantic or output_json, you ensure that your tasks produce outputs in a consistent and structured format, making it easier to process and utilize the data within your application or across multiple tasks. + +## Integrating Tools with Tasks + +Leverage tools from the [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) and [LangChain Tools](https://python.langchain.com/docs/integrations/tools) for enhanced task performance and agent interaction. + +## Creating a Task with Tools + +```python Code +import os +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key + +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +research_agent = Agent( + role='Researcher', + goal='Find and summarize the latest AI news', + backstory="""You're a researcher at a large company. + You're responsible for analyzing data and providing insights + to the business.""", + verbose=True +) + +# to perform a semantic search for a specified query from a text's content across the internet +search_tool = SerperDevTool() + +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() +print(result) +``` + +This demonstrates how tasks with specific tools can override an agent's default set for tailored task execution. + +## Referring to Other Tasks + +In CrewAI, the output of one task is automatically relayed into the next one, but you can specifically define what tasks' output, including multiple, should be used as context for another task. + +This is useful when you have a task that depends on the output of another task that is not performed immediately after it. This is done through the `context` attribute of the task: + +```python Code +# ... + +research_ai_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +research_ops_task = Task( + description="Research the latest developments in AI Ops", + expected_output="A list of recent AI Ops developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +write_blog_task = Task( + description="Write a full blog post about the importance of AI and its latest news", + expected_output="Full blog post that is 4 paragraphs long", + agent=writer_agent, + context=[research_ai_task, research_ops_task] +) + +#... +``` + +## Asynchronous Execution + +You can define a task to be executed asynchronously. This means that the crew will not wait for it to be completed to continue with the next task. This is useful for tasks that take a long time to be completed, or that are not crucial for the next tasks to be performed. + +You can then use the `context` attribute to define in a future task that it should wait for the output of the asynchronous task to be completed. + +```python Code +#... + +list_ideas = Task( + description="List of 5 interesting ideas to explore for an article about AI.", + expected_output="Bullet point list of 5 ideas for an article.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +list_important_history = Task( + description="Research the history of AI and give me the 5 most important events.", + expected_output="Bullet point list of 5 important events.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +write_article = Task( + description="Write an article about AI, its history, and interesting ideas.", + expected_output="A 4 paragraph article about AI.", + agent=writer, + context=[list_ideas, list_important_history] # Will wait for the output of the two tasks to be completed +) + +#... +``` + +## Callback Mechanism + +The callback function is executed after the task is completed, allowing for actions or notifications to be triggered based on the task's outcome. + +```python Code +# ... + +def callback_function(output: TaskOutput): + # Do something after the task is completed + # Example: Send an email to the manager + print(f""" + Task completed! + Task: {output.description} + Output: {output.raw} + """) + +research_task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool], + callback=callback_function +) + +#... +``` + +## Accessing a Specific Task Output + +Once a crew finishes running, you can access the output of a specific task by using the `output` attribute of the task object: + +```python Code +# ... +task1 = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +#... + +crew = Crew( + agents=[research_agent], + tasks=[task1, task2, task3], + verbose=True +) + +result = crew.kickoff() + +# Returns a TaskOutput object with the description and results of the task +print(f""" + Task completed! + Task: {task1.output.description} + Output: {task1.output.raw} +""") +``` + +## Tool Override Mechanism + +Specifying tools in a task allows for dynamic adaptation of agent capabilities, emphasizing CrewAI's flexibility. + +## Error Handling and Validation Mechanisms + +While creating and executing tasks, certain validation mechanisms are in place to ensure the robustness and reliability of task attributes. These include but are not limited to: + +- Ensuring only one output type is set per task to maintain clear output expectations. +- Preventing the manual assignment of the `id` attribute to uphold the integrity of the unique identifier system. + +These validations help in maintaining the consistency and reliability of task executions within the crewAI framework. + +## Creating Directories when Saving Files + +The `create_directory` parameter controls whether CrewAI should automatically create directories when saving task outputs to files. This feature is particularly useful for organizing outputs and ensuring that file paths are correctly structured, especially when working with complex project hierarchies. + +### Default Behavior + +By default, `create_directory=True`, which means CrewAI will automatically create any missing directories in the output file path: + +```python Code +# Default behavior - directories are created automatically +report_task = Task( + description='Generate a comprehensive market analysis report', + expected_output='A detailed market analysis with charts and insights', + agent=analyst_agent, + output_file='reports/2025/market_analysis.md', # Creates 'reports/2025/' if it doesn't exist + markdown=True +) +``` + +### Disabling Directory Creation + +If you want to prevent automatic directory creation and ensure that the directory already exists, set `create_directory=False`: + +```python Code +# Strict mode - directory must already exist +strict_output_task = Task( + description='Save critical data that requires existing infrastructure', + expected_output='Data saved to pre-configured location', + agent=data_agent, + output_file='secure/vault/critical_data.json', + create_directory=False # Will raise RuntimeError if 'secure/vault/' doesn't exist +) +``` + +### YAML Configuration + +You can also configure this behavior in your YAML task definitions: + +```yaml tasks.yaml +analysis_task: + description: > + Generate quarterly financial analysis + expected_output: > + A comprehensive financial report with quarterly insights + agent: financial_analyst + output_file: reports/quarterly/q4_2024_analysis.pdf + create_directory: true # Automatically create 'reports/quarterly/' directory + +audit_task: + description: > + Perform compliance audit and save to existing audit directory + expected_output: > + A compliance audit report + agent: auditor + output_file: audit/compliance_report.md + create_directory: false # Directory must already exist +``` + +### Use Cases + +**Automatic Directory Creation (`create_directory=True`):** + +- Development and prototyping environments +- Dynamic report generation with date-based folders +- Automated workflows where directory structure may vary +- Multi-tenant applications with user-specific folders + +**Manual Directory Management (`create_directory=False`):** + +- Production environments with strict file system controls +- Security-sensitive applications where directories must be pre-configured +- Systems with specific permission requirements +- Compliance environments where directory creation is audited + +### Error Handling + +When `create_directory=False` and the directory doesn't exist, CrewAI will raise a `RuntimeError`: + +```python Code +try: + result = crew.kickoff() +except RuntimeError as e: + # Handle missing directory error + print(f"Directory creation failed: {e}") + # Create directory manually or use fallback location +``` + +Check out the video below to see how to use structured outputs in CrewAI: + + + +## Conclusion + +Tasks are the driving force behind the actions of agents in CrewAI. +By properly defining tasks and their outcomes, you set the stage for your AI agents to work effectively, either independently or as a collaborative unit. +Equipping tasks with appropriate tools, understanding the execution process, and following robust validation practices are crucial for maximizing CrewAI's potential, +ensuring agents are effectively prepared for their assignments and that tasks are executed as intended. diff --git a/docs/v1.15.1/en/concepts/testing.mdx b/docs/v1.15.1/en/concepts/testing.mdx new file mode 100644 index 000000000..dbac110b4 --- /dev/null +++ b/docs/v1.15.1/en/concepts/testing.mdx @@ -0,0 +1,49 @@ +--- +title: Testing +description: Learn how to test your CrewAI Crew and evaluate their performance. +icon: vial +mode: "wide" +--- + +## Overview + +Testing is a crucial part of the development process, and it is essential to ensure that your crew is performing as expected. With crewAI, you can easily test your crew and evaluate its performance using the built-in testing capabilities. + +### Using the Testing Feature + +We added the CLI command `crewai test` to make it easy to test your crew. This command will run your crew for a specified number of iterations and provide detailed performance metrics. The parameters are `n_iterations` and `model`, which are optional and default to 2 and `gpt-4o-mini` respectively. For now, the only provider available is OpenAI. + +```bash +crewai test +``` + +If you want to run more iterations or use a different model, you can specify the parameters like this: + +```bash +crewai test --n_iterations 5 --model gpt-4o +``` + +or using the short forms: + +```bash +crewai test -n 5 -m gpt-4o +``` + +When you run the `crewai test` command, the crew will be executed for the specified number of iterations, and the performance metrics will be displayed at the end of the run. + +A table of scores at the end will show the performance of the crew in terms of the following metrics: + +
**Tasks Scores (1-10 Higher is better)**
+ +| Tasks/Crew/Agents | Run 1 | Run 2 | Avg. Total | Agents | Additional Info | +|:------------------|:-----:|:-----:|:----------:|:------------------------------:|:---------------------------------| +| Task 1 | 9.0 | 9.5 | **9.2** | Professional Insights | | +| | | | | Researcher | | +| Task 2 | 9.0 | 10.0 | **9.5** | Company Profile Investigator | | +| Task 3 | 9.0 | 9.0 | **9.0** | Automation Insights | | +| | | | | Specialist | | +| Task 4 | 9.0 | 9.0 | **9.0** | Final Report Compiler | Automation Insights Specialist | +| Crew | 9.00 | 9.38 | **9.2** | | | +| Execution Time (s) | 126 | 145 | **135** | | | + +The example above shows the test results for two runs of the crew with two tasks, with the average total score for each task and the crew as a whole. diff --git a/docs/v1.15.1/en/concepts/tools.mdx b/docs/v1.15.1/en/concepts/tools.mdx new file mode 100644 index 000000000..da41da3b1 --- /dev/null +++ b/docs/v1.15.1/en/concepts/tools.mdx @@ -0,0 +1,341 @@ +--- +title: Tools +description: Understanding and leveraging tools within the CrewAI framework for agent collaboration and task execution. +icon: screwdriver-wrench +mode: "wide" +--- + +## Overview + +CrewAI tools empower agents with capabilities ranging from web searching and data analysis to collaboration and delegating tasks among coworkers. +This documentation outlines how to create, integrate, and leverage these tools within the CrewAI framework, including a new focus on collaboration tools. + + + Tools give agents **callable functions** to take action. They work alongside [MCPs](/en/mcp/overview) (remote tool servers), [Apps](/en/concepts/agent-capabilities) (platform integrations), [Skills](/en/concepts/skills) (domain expertise), and [Knowledge](/en/concepts/knowledge) (retrieved facts). See the [Agent Capabilities](/en/concepts/agent-capabilities) overview to understand when to use each. + + +## What is a Tool? + +A tool in CrewAI is a skill or function that agents can utilize to perform various actions. +This includes tools from the [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) and [LangChain Tools](https://python.langchain.com/docs/integrations/tools), +enabling everything from simple searches to complex interactions and effective teamwork among agents. + + +CrewAI AMP provides a comprehensive Tools Repository with pre-built integrations for common business systems and APIs. Deploy agents with enterprise tools in minutes instead of days. + +The Enterprise Tools Repository includes: + +- Pre-built connectors for popular enterprise systems +- Custom tool creation interface +- Version control and sharing capabilities +- Security and compliance features + + +## Key Characteristics of Tools + +- **Utility**: Crafted for tasks such as web searching, data analysis, content generation, and agent collaboration. +- **Integration**: Boosts agent capabilities by seamlessly integrating tools into their workflow. +- **Customizability**: Provides the flexibility to develop custom tools or utilize existing ones, catering to the specific needs of agents. +- **Error Handling**: Incorporates robust error handling mechanisms to ensure smooth operation. +- **Caching Mechanism**: Features intelligent caching to optimize performance and reduce redundant operations. +- **Asynchronous Support**: Handles both synchronous and asynchronous tools, enabling non-blocking operations. +- **Typed Outputs**: Uses optional Pydantic models to give agents clear JSON fields while direct Python calls still receive the tool's normal return value. + +## Using CrewAI Tools + +To enhance your agents' capabilities with crewAI tools, begin by installing our extra tools package: + +```bash +pip install 'crewai[tools]' +``` + +Here's an example demonstrating their use: + +```python Code +import os +from crewai import Agent, Task, Crew +# Importing crewAI tools +from crewai_tools import ( + DirectoryReadTool, + FileReadTool, + SerperDevTool, + WebsiteSearchTool +) + +# Set up API keys +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key +os.environ["OPENAI_API_KEY"] = "Your Key" + +# Instantiate tools +docs_tool = DirectoryReadTool(directory='./blog-posts') +file_tool = FileReadTool() +search_tool = SerperDevTool() +web_rag_tool = WebsiteSearchTool() + +# Create agents +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 +) + +# Define tasks +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' # The final blog post will be saved here +) + +# Assemble a crew with planning enabled +crew = Crew( + agents=[researcher, writer], + tasks=[research, write], + verbose=True, + planning=True, # Enable planning feature +) + +# Execute tasks +crew.kickoff() +``` + +## Available CrewAI Tools + +- **Error Handling**: All tools are built with error handling capabilities, allowing agents to gracefully manage exceptions and continue their tasks. +- **Caching Mechanism**: All tools support caching, enabling agents to efficiently reuse previously obtained results, reducing the load on external resources and speeding up the execution time. You can also define finer control over the caching mechanism using the `cache_function` attribute on the tool. + +Here is a list of the available tools and their descriptions: + +| Tool | Description | +| :------------------------------- | :--------------------------------------------------------------------------------------------- | +| **ApifyActorsTool** | A tool that integrates Apify Actors with your workflows for web scraping and automation tasks. | +| **BrowserbaseLoadTool** | A tool for interacting with and extracting data from web browsers. | +| **CodeDocsSearchTool** | A RAG tool optimized for searching through code documentation and related technical documents. | +| **CodeInterpreterTool** | A tool for interpreting python code. | +| **ComposioTool** | Enables use of Composio tools. | +| **CSVSearchTool** | A RAG tool designed for searching within CSV files, tailored to handle structured data. | +| **DALL-E Tool** | A tool for generating images using the DALL-E API. | +| **DirectorySearchTool** | A RAG tool for searching within directories, useful for navigating through file systems. | +| **DOCXSearchTool** | A RAG tool aimed at searching within DOCX documents, ideal for processing Word files. | +| **DirectoryReadTool** | Facilitates reading and processing of directory structures and their contents. | +| **ExaSearchTool** | Search the web with Exa, the fastest and most accurate web search API. Supports token-efficient highlights and full page content. | +| **FileReadTool** | Enables reading and extracting data from files, supporting various file formats. | +| **FirecrawlSearchTool** | A tool to search webpages using Firecrawl and return the results. | +| **FirecrawlCrawlWebsiteTool** | A tool for crawling webpages using Firecrawl. | +| **FirecrawlScrapeWebsiteTool** | A tool for scraping webpages URL using Firecrawl and returning its contents. | +| **GithubSearchTool** | A RAG tool for searching within GitHub repositories, useful for code and documentation search. | +| **SerperDevTool** | A specialized tool for development purposes, with specific functionalities under development. | +| **TXTSearchTool** | A RAG tool focused on searching within text (.txt) files, suitable for unstructured data. | +| **JSONSearchTool** | A RAG tool designed for searching within JSON files, catering to structured data handling. | +| **LlamaIndexTool** | Enables the use of LlamaIndex tools. | +| **MDXSearchTool** | A RAG tool tailored for searching within Markdown (MDX) files, useful for documentation. | +| **PDFSearchTool** | A RAG tool aimed at searching within PDF documents, ideal for processing scanned documents. | +| **PGSearchTool** | A RAG tool optimized for searching within PostgreSQL databases, suitable for database queries. | +| **Vision Tool** | A tool for generating images using the DALL-E API. | +| **RagTool** | A general-purpose RAG tool capable of handling various data sources and types. | +| **ScrapeElementFromWebsiteTool** | Enables scraping specific elements from websites, useful for targeted data extraction. | +| **ScrapeWebsiteTool** | Facilitates scraping entire websites, ideal for comprehensive data collection. | +| **WebsiteSearchTool** | A RAG tool for searching website content, optimized for web data extraction. | +| **XMLSearchTool** | A RAG tool designed for searching within XML files, suitable for structured data formats. | +| **YoutubeChannelSearchTool** | A RAG tool for searching within YouTube channels, useful for video content analysis. | +| **YoutubeVideoSearchTool** | A RAG tool aimed at searching within YouTube videos, ideal for video data extraction. | + +## Creating your own Tools + + + Developers can craft `custom tools` tailored for their agent's needs or + utilize pre-built options. + + +There are two main ways for one to create a CrewAI tool: + +### Subclassing `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: + # Your tool's logic here + return "Tool's result" +``` + +### Typed Tool Outputs + +When a tool returns structured data, define a Pydantic output model. This gives the agent field names it can trust, such as `sku`, `quantity`, or `needs_reorder`. + +Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent a JSON string based on the output model. + +```python Code +from crewai.tools import BaseTool +from pydantic import BaseModel + +class InventoryResult(BaseModel): + sku: str + quantity: int + needs_reorder: bool + +class InventoryTool(BaseTool): + name: str = "Inventory Check" + description: str = "Checks current stock for a product SKU." + + def _run(self, sku: str) -> InventoryResult: + quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0) + return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5) + +tool = InventoryTool() + +# Direct calls receive the raw Pydantic object. +result = tool.run(sku="SKU-123") +print(result.quantity) +``` + +To send Markdown or another short text format to the agent, override `format_output_for_agent`. Direct calls to `tool.run(...)` still return the normal Python value. + +```python Code +class InventoryTool(BaseTool): + name: str = "Inventory Check" + description: str = "Checks current stock for a product SKU." + + def _run(self, sku: str) -> InventoryResult: + quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0) + return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5) + + def format_output_for_agent(self, raw_result: object) -> str: + result = InventoryResult.model_validate(raw_result) + status = "reorder needed" if result.needs_reorder else "stock is healthy" + return f"{result.sku}: {result.quantity} units. {status}." +``` + +If you do not override `format_output_for_agent`, typed outputs are sent to the agent as JSON. Plain string results work as before. + +## Asynchronous Tool Support + +CrewAI supports asynchronous tools, allowing you to implement tools that perform non-blocking operations like network requests, file I/O, or other async operations without blocking the main execution thread. + +### Creating Async Tools + +You can create async tools in two ways: + +#### 1. Using the `tool` Decorator with Async Functions + +```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. Implementing Async Methods in Custom Tool Classes + +```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""" + # Your async implementation here + await asyncio.sleep(1) + return f"Processed {query} asynchronously" +``` + +### Using Async Tools + +Async tools work seamlessly in both standard Crew workflows and Flow-based workflows: + +```python Code +# In standard Crew +agent = Agent(role="researcher", tools=[async_custom_tool]) + +# In Flow +class MyFlow(Flow): + @start() + async def begin(self): + crew = Crew(agents=[agent]) + result = await crew.kickoff_async() + return result +``` + +The CrewAI framework automatically handles the execution of both synchronous and asynchronous tools, so you don't need to worry about how to call them differently. + +### Utilizing the `tool` Decorator + +```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.""" + # Function logic here + return "Result from your custom tool" +``` + +### Custom Caching Mechanism + + + Tools can optionally implement a `cache_function` to fine-tune caching + behavior. This function determines when to cache results based on specific + conditions, offering granular control over caching logic. + + +```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): + # In this case, we only cache the result if it's a multiple of 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, + ) + #... +``` + +## Conclusion + +Tools are pivotal in extending the capabilities of CrewAI agents, enabling them to undertake a broad spectrum of tasks and collaborate effectively. +When building solutions with CrewAI, leverage both custom and existing tools to empower your agents and enhance the AI ecosystem. Consider utilizing error handling, +caching mechanisms, and the flexibility of tool arguments to optimize your agents' performance and capabilities. diff --git a/docs/v1.15.1/en/concepts/training.mdx b/docs/v1.15.1/en/concepts/training.mdx new file mode 100644 index 000000000..468e1acef --- /dev/null +++ b/docs/v1.15.1/en/concepts/training.mdx @@ -0,0 +1,197 @@ +--- +title: Training +description: Learn how to train your CrewAI agents by giving them feedback early on and get consistent results. +icon: dumbbell +mode: "wide" +--- + +## Overview + +The training feature in CrewAI allows you to train your AI agents using the command-line interface (CLI). +By running the command `crewai train -n `, you can specify the number of iterations for the training process. + +During training, CrewAI utilizes techniques to optimize the performance of your agents along with human feedback. +This helps the agents improve their understanding, decision-making, and problem-solving abilities. + +### Training Your Crew Using the CLI + +To use the training feature, follow these steps: + +1. Open your terminal or command prompt. +2. Navigate to the directory where your CrewAI project is located. +3. Run the following command: + +```shell +crewai train -n -f +``` + + Replace `` with the desired number of training iterations and `` with the appropriate filename ending with `.pkl`. + + + + If you omit `-f`, the output defaults to `trained_agents_data.pkl` in the current working directory. You can pass an absolute path to control where the file is written. + + +### Training your Crew programmatically + +To train your crew programmatically, use the following steps: + +1. Define the number of iterations for training. +2. Specify the input parameters for the training process. +3. Execute the training command within a try-except block to handle potential errors. + +```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}") +``` + +## How trained data is used by agents + +CrewAI uses the training artifacts in two ways: during training to incorporate your human feedback, and after training to guide agents with consolidated suggestions. + +### Training data flow + +```mermaid +flowchart TD + A["Start training
CLI: crewai train -n -f
or Python: crew.train(...)"] --> B["Setup training mode
- task.human_input = true
- disable delegation
- init training_data.pkl + trained file"] + + subgraph "Iterations" + direction LR + C["Iteration i
initial_output"] --> D["User human_feedback"] + D --> E["improved_output"] + E --> F["Append to training_data.pkl
by agent_id and iteration"] + end + + B --> C + F --> G{"More iterations?"} + G -- "Yes" --> C + G -- "No" --> H["Evaluate per agent
aggregate iterations"] + + H --> I["Consolidate
suggestions[] + quality + final_summary"] + I --> J["Save by agent role to trained file
(default: trained_agents_data.pkl)"] + + J --> K["Normal (non-training) runs"] + K --> L["Auto-load suggestions
from trained_agents_data.pkl"] + L --> M["Append to prompt
for consistent improvements"] +``` + +### During training runs + +- On each iteration, the system records for every agent: + - `initial_output`: the agent’s first answer + - `human_feedback`: your inline feedback when prompted + - `improved_output`: the agent’s follow-up answer after feedback +- This data is stored in a working file named `training_data.pkl` keyed by the agent’s internal ID and iteration. +- While training is active, the agent automatically appends your prior human feedback to its prompt to enforce those instructions on subsequent attempts within the training session. + Training is interactive: tasks set `human_input = true`, so running in a non-interactive environment will block on user input. + +### After training completes + +- When `train(...)` finishes, CrewAI evaluates the collected training data per agent and produces a consolidated result containing: + - `suggestions`: clear, actionable instructions distilled from your feedback and the difference between initial/improved outputs + - `quality`: a 0–10 score capturing improvement + - `final_summary`: a step-by-step set of action items for future tasks +- These consolidated results are saved to the filename you pass to `train(...)` (default via CLI is `trained_agents_data.pkl`). Entries are keyed by the agent’s `role` so they can be applied across sessions. +- During normal (non-training) execution, each agent automatically loads its consolidated `suggestions` and appends them to the task prompt as mandatory instructions. This gives you consistent improvements without changing your agent definitions. + +### File summary + +- `training_data.pkl` (ephemeral, per-session): + - Structure: `agent_id -> { iteration_number: { initial_output, human_feedback, improved_output } }` + - Purpose: capture raw data and human feedback during training + - Location: saved in the current working directory (CWD) +- `trained_agents_data.pkl` (or your custom filename): + - Structure: `agent_role -> { suggestions: string[], quality: number, final_summary: string }` + - Purpose: persist consolidated guidance for future runs + - Location: written to the CWD by default; use `-f` to set a custom (including absolute) path + +## Small Language Model Considerations + + + When using smaller language models (≤7B parameters) for training data evaluation, be aware that they may face challenges with generating structured outputs and following complex instructions. + + +### Limitations of Small Models in Training Evaluation + + + + Smaller models often struggle with producing valid JSON responses needed for structured training evaluations, leading to parsing errors and incomplete data. + + + Models under 7B parameters may provide less nuanced evaluations with limited reasoning depth compared to larger models. + + + Complex training evaluation criteria may not be fully followed or considered by smaller models. + + + Evaluations across multiple training iterations may lack consistency with smaller models. + + + +### Recommendations for Training + + + + For optimal training quality and reliable evaluations, we strongly recommend using models with at least 7B parameters or larger: + + ```python + from crewai import Agent, Crew, Task, LLM + + # Recommended minimum for training evaluation + llm = LLM(model="mistral/open-mistral-7b") + + # Better options for reliable training evaluation + llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0") + llm = LLM(model="gpt-4o") + + # Use this LLM with your agents + agent = Agent( + role="Training Evaluator", + goal="Provide accurate training feedback", + llm=llm + ) + ``` + + + More powerful models provide higher quality feedback with better reasoning, leading to more effective training iterations. + + + + If you must use smaller models for training evaluation, be aware of these constraints: + + ```python + # Using a smaller model (expect some limitations) + llm = LLM(model="huggingface/microsoft/Phi-3-mini-4k-instruct") + ``` + + + While CrewAI includes optimizations for small models, expect less reliable and less nuanced evaluation results that may require more human intervention during training. + + + + +### Key Points to Note + +- **Positive Integer Requirement:** Ensure that the number of iterations (`n_iterations`) is a positive integer. The code will raise a `ValueError` if this condition is not met. +- **Filename Requirement:** Ensure that the filename ends with `.pkl`. The code will raise a `ValueError` if this condition is not met. +- **Error Handling:** The code handles subprocess errors and unexpected exceptions, providing error messages to the user. +- Trained guidance is applied at prompt time; it does not modify your Python/YAML agent configuration. +- Agents automatically load trained suggestions from a file named `trained_agents_data.pkl` located in the current working directory. If you trained to a different filename, pass that path with `Crew(trained_agents_file="my_custom_trained.pkl")`, set `CREWAI_TRAINED_AGENTS_FILE`, or use `crewai run -f my_custom_trained.pkl`. +- You can change the output filename when calling `crewai train` with `-f/--filename`. Absolute paths are supported if you want to save outside the CWD. + +It is important to note that the training process may take some time, depending on the complexity of your agents and will also require your feedback on each iteration. + +Once the training is complete, your agents will be equipped with enhanced capabilities and knowledge, ready to tackle complex tasks and provide more consistent and valuable insights. + +Remember to regularly update and retrain your agents to ensure they stay up-to-date with the latest information and advancements in the field. diff --git a/docs/v1.15.1/en/enterprise/features/a2a.mdx b/docs/v1.15.1/en/enterprise/features/a2a.mdx new file mode 100644 index 000000000..e66cbe340 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/a2a.mdx @@ -0,0 +1,227 @@ +--- +title: A2A on AMP +description: Production-grade Agent-to-Agent communication with distributed state and multi-scheme authentication +icon: "network-wired" +mode: "wide" +--- + + +A2A server agents on AMP are in early release. APIs may change in future versions. + + +## Overview + +CrewAI AMP extends the open-source [A2A protocol implementation](/en/learn/a2a-agent-delegation) with production infrastructure for deploying distributed agents at scale. AMP supports A2A protocol versions 0.2 and 0.3. When you deploy a crew or agent with A2A server configuration to AMP, the platform automatically provisions distributed state management, authentication, multi-transport endpoints, and lifecycle management. + + + For A2A protocol fundamentals, client/server configuration, and authentication schemes, see the [A2A Agent Delegation](/en/learn/a2a-agent-delegation) documentation. This page covers what AMP adds on top of the open-source implementation. + + +### Usage + +Add `A2AServerConfig` to any agent in your crew and deploy to AMP. The platform detects agents with server configuration and automatically registers A2A endpoints, generates agent cards, and provisions the infrastructure described below. + +```python +from crewai import Agent, Crew, Task +from crewai.a2a import A2AServerConfig +from crewai.a2a.auth import EnterpriseTokenAuth + +agent = Agent( + role="Data Analyst", + goal="Analyze datasets and provide insights", + backstory="Expert data scientist with statistical analysis skills", + llm="gpt-4o", + a2a=A2AServerConfig( + auth=EnterpriseTokenAuth() + ) +) + +task = Task( + description="Analyze the provided dataset", + expected_output="Statistical summary with key insights", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task]) +``` + +After [deploying to AMP](/en/enterprise/guides/deploy-to-amp), the platform registers two levels of A2A endpoints: + +- **Crew-level**: an aggregate agent card at `/.well-known/agent-card.json` where each agent with `A2AServerConfig` is listed as a skill, with a JSON-RPC endpoint at `/a2a` +- **Per-agent**: isolated agent cards and JSON-RPC endpoints mounted at `/a2a/agents/{role}/`, each with its own tenancy + +Clients can interact with the crew as a whole or target a specific agent directly. To route a request to a specific agent through the crew-level endpoint, include `"target_agent"` in the message metadata with the agent's slugified role name (e.g., `"data-analyst"` for an agent with role `"Data Analyst"`). If no `target_agent` is provided, the request is handled by the first agent in the crew. + +See [A2A Agent Delegation](/en/learn/a2a-agent-delegation#server-configuration-options) for the full list of `A2AServerConfig` options. + + + Per the A2A protocol, agent cards are publicly accessible to enable discovery. This includes both the crew-level card at `/.well-known/agent-card.json` and per-agent cards at `/a2a/agents/{role}/.well-known/agent-card.json`. Do not include sensitive information in agent names, descriptions, or skill definitions. + + +### File Inputs and Structured Output + +A2A on AMP supports passing files and requesting structured output in both directions. Clients can send files as `FilePart`s and request structured responses by embedding a JSON schema in the message. Server agents receive files as `input_files` on the task, and return structured data as `DataPart`s when a schema is provided. See [File Inputs and Structured Output](/en/learn/a2a-agent-delegation#file-inputs-and-structured-output) for details. + +### What AMP Adds + + + + Persistent task, context, and result storage + + + OIDC, OAuth2, mTLS, and Enterprise token validation beyond simple bearer tokens + + + Full gRPC server with TLS and authentication + + + Automatic idle detection, expiration, and cleanup of long-running conversations + + + HMAC-SHA256 signed push notifications with replay protection + + + REST, JSON-RPC, and gRPC endpoints served simultaneously from a single deployment + + + +--- + +## Distributed State Management + +In the open-source implementation, task and context state lives in memory on a single process. AMP replaces this with persistent, distributed stores. + +### Storage Layers + +| Store | Purpose | +|---|---| +| **Task Store** | Persists A2A task state and metadata | +| **Context Store** | Tracks conversation context, creation time, last activity, and associated tasks | +| **Result Store** | Caches task results for retrieval | +| **Push Config Store** | Manages webhook subscriptions per task | + +Multiple A2A deployments are automatically isolated from each other, preventing data collisions when sharing infrastructure. + +--- + +## Enterprise Authentication + +AMP supports six authentication schemes for incoming A2A requests, configurable per deployment. Authentication works across both HTTP and gRPC transports. + +| Scheme | Description | Use Case | +|---|---|---| +| **SimpleTokenAuth** | Static bearer token from `AUTH_TOKEN` env var | Development, simple deployments | +| **EnterpriseTokenAuth** | Token verification via CrewAI PlusAPI with integration token claims | AMP-to-AMP agent communication | +| **OIDCAuth** | OpenID Connect JWT validation with JWKS endpoint caching | Enterprise SSO integration | +| **OAuth2ServerAuth** | OAuth2 with configurable scopes | Fine-grained access control | +| **APIKeyServerAuth** | API key validation via header or query parameter | Third-party integrations | +| **MTLSServerAuth** | Mutual TLS certificate-based authentication | Zero-trust environments | + +The configured auth scheme automatically populates the agent card's `securitySchemes` and `security` fields. Clients discover authentication requirements by fetching the agent card before making requests. + +--- + +## Extended Agent Cards + +AMP supports role-based skill visibility through extended agent cards. Unauthenticated users see the standard agent card with public skills. Authenticated users receive an extended card with additional capabilities. + +This enables patterns like: +- Public agents that expose basic skills to anyone, with advanced skills available to authenticated clients +- Internal agents that advertise different capabilities based on the caller's identity + +--- + +## gRPC Transport + +If enabled, AMP provides full gRPC support alongside the default JSON-RPC transport. + +- **TLS termination** with configurable certificate and key paths +- **gRPC reflection** for debugging with tools like `grpcurl` +- **Authentication** using the same schemes available for HTTP +- **Extension validation** ensuring clients support required protocol extensions +- **Version negotiation** across A2A protocol versions 0.2 and 0.3 + +For deployments exposing multiple agents, AMP automatically allocates per-agent gRPC ports and coordinates TLS, startup, and shutdown across all servers. + +--- + +## Context Lifecycle Management + +AMP tracks the lifecycle of A2A conversation contexts and automatically manages cleanup. + +### Lifecycle States + +| State | Condition | Action | +|---|---|---| +| **Active** | Context has recent activity | None | +| **Idle** | No activity for a configured period | Marked idle, event emitted | +| **Expired** | Context exceeds its maximum lifetime | Marked expired, associated tasks cleaned up, event emitted | + +A background cleanup task runs hourly to scan for idle and expired contexts. All state transitions emit CrewAI events that integrate with the platform's observability features. + +--- + +## Signed Push Notifications + +When an A2A agent sends push notifications to a client webhook, AMP signs each request with HMAC-SHA256 to ensure integrity and prevent tampering. + +### Signature Headers + +| Header | Purpose | +|---|---| +| `X-A2A-Signature` | HMAC-SHA256 signature in `sha256={hex_digest}` format | +| `X-A2A-Signature-Timestamp` | Unix timestamp bound to the signature | +| `X-A2A-Notification-Token` | Optional notification auth token | + +### Security Properties + +- **Integrity**: payload cannot be modified without invalidating the signature +- **Replay protection**: signatures are timestamp-bound with a configurable tolerance window +- **Retry with backoff**: failed deliveries retry with exponential backoff + +--- + +## Distributed Event Streaming + +In the open-source implementation, SSE streaming works within a single process. AMP propagates SSE events across instances so that clients receive updates even when the instance holding the streaming connection differs from the instance executing the task. + +--- + +## Multi-Transport Endpoints + +AMP serves REST and JSON-RPC by default. gRPC is available as an additional transport if enabled. + +| Transport | Path Convention | Description | +|---|---|---| +| **REST** | `/v1/message:send`, `/v1/message:stream`, `/v1/tasks` | Google API conventions | +| **JSON-RPC** | Standard A2A JSON-RPC endpoint | Default A2A protocol transport | +| **gRPC** | Per-agent port allocation | Optional, high-performance binary protocol | + +All active transports share the same authentication, version negotiation, and extension validation. Agent cards are generated from agent and crew metadata — roles, goals, and tools become skills and descriptions — and automatically include interfaces for each active transport. They can also be manually configured via `A2AServerConfig`. + +--- + +## Version and Extension Negotiation + +AMP validates A2A protocol versions and extensions at the transport layer. + +### Version Negotiation + +- Clients send the `A2A-Version` header with their preferred version +- AMP validates against supported versions (0.2, 0.3) and falls back to 0.3 if unspecified +- The negotiated version is returned in the response headers + +### Extension Validation + +- Clients declare supported extensions via the `X-A2A-Extensions` header +- AMP validates that clients support all extensions the agent requires +- Requests from clients missing required extensions receive an `UnsupportedExtensionError` + +--- + +## Next Steps + +- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — A2A protocol fundamentals and configuration +- [A2UI](/en/learn/a2ui) — Interactive UI rendering over A2A +- [Deploy to AMP](/en/enterprise/guides/deploy-to-amp) — General deployment guide +- [Webhook Streaming](/en/enterprise/features/webhook-streaming) — Event streaming for deployed automations diff --git a/docs/v1.15.1/en/enterprise/features/agent-control-plane/monitoring.mdx b/docs/v1.15.1/en/enterprise/features/agent-control-plane/monitoring.mdx new file mode 100644 index 000000000..ef94d1895 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/agent-control-plane/monitoring.mdx @@ -0,0 +1,112 @@ +--- +title: "Watch your Automations" +description: "Watch fleet health, LLM consumption, and per-automation behavior from the Automations tab." +sidebarTitle: "Monitoring" +icon: "gauge" +mode: "wide" +--- + + + **ACP (Beta) Docs Navigation** + + - [Overview](/en/enterprise/features/agent-control-plane/overview) + - **Monitoring** *(you are here)* + - [Rules](/en/enterprise/features/agent-control-plane/rules) + + +## Overview + +The **Automations** tab is the read-only operations view of the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview). It combines two metric cards, an interactive sankey, and two sub-tables — **Automations** and **Consumption** — that you can search, filter, and sort. + + + ![Agent Control Plane overview](/images/enterprise/acp-overview-automations-sankey.png) + + +All charts and tables respect the **Last 24 hours / Last Week / Last 30 days** selector at the top right. Deltas compare the selected window against the previous one of the same length. + + + Rows only show data for deployments on **crewAI v1.13 or higher** — older deployments appear in the *"We've detected N other automations that we can't display"* banner under the sankey and contribute zero metrics until they're updated and re-deployed. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements). + + +## Dashboard + +The header of the page has two metric cards and an interactive sankey. Clicking either card switches the sankey between two modes: + +- **Health mode** — `Total Automations → status buckets (Critical / Warning / Healthy)`. Click a bucket to filter the Automations table to just those deployments. +- **Consumption mode** — `Model Providers → Automations → Total Cost`. Click a provider to filter the Consumption table to that provider. + +| Card | What it shows | +|------|---------------| +| **Automations** | `active` automations (and total count), total `errors` in the window, currently `active executions` (and total in the window), with a delta vs the previous period. | +| **Consumption** | Total `cost` and `tokens used`, with a cost delta vs the previous period. | + + + ![Overview with consumption sankey](/images/enterprise/acp-overview-consumption-sankey.png) + + +## Automations table + +The **Automations** sub-tab is the per-deployment breakdown of fleet health. Each row is one deployed crew or flow. + + + ![Automations table with health status breakdown](/images/enterprise/acp-automations-table.png) + + +| Column | What it shows | +|--------|---------------| +| **Automation** | Deployment name and any tags assigned to it (e.g. `production`, `financial`). | +| **Last execution** | Time since the most recent run. | +| **Health Status Breakdown** | Stacked bar of `Critical` / `Warning` / `Healthy` percentages for executions in the window. | +| **Executions with Errors** | Total failed executions in the window. | +| **PII detection applied** | `Yes` if a per-deployment PII config or a matching [PII rule](/en/enterprise/features/agent-control-plane/rules) is active. | +| **Executions** | Total executions in the window. | +| **Last updated** | When the deployment was last re-deployed. | +| **Crew Version** | The `crewai` version reported by the deployment. An info icon next to versions below `1.13` flags rows that can't contribute metrics. | + +Search by name, filter by `Status` (`Healthy` / `Warning` / `Critical`), and sort by any column header. Click a deployment name to open the **Automation panel** (see below). + +## Consumption table + +The **Consumption** sub-tab is the per-deployment breakdown of LLM spend and token usage. + + + ![Consumption table broken down by LLM provider](/images/enterprise/acp-consumption-table.png) + + +| Column | What it shows | +|--------|---------------| +| **Automation** | Deployment name. | +| **Last execution** | Time since the most recent run. | +| **Tokens used** | One row per LLM provider used by this automation, with the delta vs the previous period. | +| **Cost** | Cost per LLM provider, with the delta vs the previous period. | +| **Total cost** | Sum across all providers, with the delta. | +| **Executions** | Total executions in the window. | +| **Last updated** | When the deployment was last re-deployed. | +| **Crew Version** | The `crewai` version reported by the deployment. | + +Filter by **LLM provider** and sort by `Cost`, `Executions`, or `Last run`. + + + **Empty cells (`—` or `$0.00`) usually mean the deployment is below crewAI v1.13.** In the screenshot above, *Automation F* (`1.7.0`) and *Automation I* (`1.12.2`) show blanks for tokens and cost — their executions still run, but they don't emit the provider-level telemetry that powers this table. Update and re-deploy these crews to start collecting consumption data. + + +## Related + + + + What ACP is, requirements, plan tiers, and RBAC. + + + Apply organization-wide PII Redaction rules across many automations. + + + Drill into a single execution to see agent reasoning, tool calls, and token usage. + + + Deploy a crew on a crewAI version that supports the Agent Control Plane. + + + + + Contact our support team for help interpreting metrics in the Agent Control Plane. + diff --git a/docs/v1.15.1/en/enterprise/features/agent-control-plane/overview.mdx b/docs/v1.15.1/en/enterprise/features/agent-control-plane/overview.mdx new file mode 100644 index 000000000..1e3d4de8b --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/agent-control-plane/overview.mdx @@ -0,0 +1,82 @@ +--- +title: Agent Control Plane Overview +description: "Single operations hub for live automations — fleet health, LLM consumption, and organization-wide policies in one place." +sidebarTitle: Overview +icon: "book-open" +--- + + + **ACP (Beta) Docs Navigation** + + - **Overview** *(you are here)* + - [Monitoring](/en/enterprise/features/agent-control-plane/monitoring) + - [Rules](/en/enterprise/features/agent-control-plane/rules) + + +## Overview + +The **Agent Control Plane** (ACP) is the operations hub for everything you have running on CrewAI AMP. It is a single screen — split into **Automations** and **Rules** tabs — that lets your team: + +- Monitor the **health** of every live automation (crew or flow), with `Critical` / `Warning` / `Healthy` breakdowns and execution counts. +- Track **LLM consumption** — tokens and cost — per automation, per provider, and per model, with a delta vs the previous period. +- Drill into any single automation or model provider for time-series charts and per-provider breakdowns. +- Apply organization-wide **Rules** (today: PII Redaction) across many automations at once instead of editing each deployment individually. + + + ![Agent Control Plane overview](/images/enterprise/acp-overview-automations-sankey.png) + + + + The Agent Control Plane is currently labeled **Beta** in CrewAI Platform. + + +The two tabs answer two different questions: + +- **Automations** — *"How is my fleet behaving right now, and what is it costing me?"* See [Monitoring](/en/enterprise/features/agent-control-plane/monitoring). +- **Rules** — *"How do I enforce a policy (e.g. PII redaction) across many deployments without re-deploying each one?"* See [Rules](/en/enterprise/features/agent-control-plane/rules). + +## Requirements + + + **crewAI v1.13 or higher** is required for an automation to populate any data on this page — health, executions, errors, tokens, and cost all flow through telemetry that lit up in `crewai==1.13`. Older deployments appear in the *"We've detected N other automations that we can't display"* banner and contribute zero rows until they are updated and re-deployed. + + + + **Enterprise Plan or Ultra Plan** is required to create or edit [Rules](/en/enterprise/features/agent-control-plane/rules). Lower-tier organizations can open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* Monitoring (the Automations tab) is available on all plans where the feature is enabled. + + +- The **Agent Control Plane** feature must be enabled for your organization. If you don't see it in the sidebar, ask your account owner to request enablement. +- Inside ACP, [RBAC](/en/enterprise/features/rbac) governs access: `read` to view the dashboard and rules, `manage` to create, edit, toggle, or delete rules. +- All charts and tables can be scoped to the **Last 24 hours**, **Last Week**, or **Last 30 days** using the time selector at the top right. Deltas (`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday`, etc.) compare the selected window against the previous one of the same length. + +## What you can do here + + + + Watch fleet health and LLM spend with metric cards, an interactive sankey, per-automation tables, and drill-down side panels for any automation or provider. + + + Apply organization-wide PII Redaction policies scoped by tools and tags. Changes take effect on the next execution — no re-deploy required. + + + +## Related + + + + Drill into a single execution to see agent reasoning, tool calls, and token usage. + + + Manage who can read the Agent Control Plane and who can edit rules. + + + Entity catalog and per-deployment PII configuration referenced by Rules. + + + Deploy a crew on a crewAI version that supports the Agent Control Plane. + + + + + Contact our support team for help interpreting metrics or designing rules. + diff --git a/docs/v1.15.1/en/enterprise/features/agent-control-plane/rules.mdx b/docs/v1.15.1/en/enterprise/features/agent-control-plane/rules.mdx new file mode 100644 index 000000000..755afbcc4 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/agent-control-plane/rules.mdx @@ -0,0 +1,122 @@ +--- +title: "Set up the Rules" +description: "Apply organization-wide policies across many automations from a single place." +sidebarTitle: "Rules" +icon: "shield-check" +mode: "wide" +--- + + + **ACP (Beta) Docs Navigation** + + - [Overview](/en/enterprise/features/agent-control-plane/overview) + - [Monitoring](/en/enterprise/features/agent-control-plane/monitoring) + - **Rules** *(you are here)* + + +## Overview + +Rules let you apply policies — today: **PII Redaction** — across many automations at once, instead of configuring each deployment individually. Open the **Rules** tab in the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview) to manage them. + + + ![Rules list](/images/enterprise/acp-rules-list.png) + + +Each rule card shows the name, description, the **scope** the rule applies to (selected tools and tags), and a count of **engaged automations** — deployments that currently match the scope. The toggle on the right enables or disables the rule without deleting it. + +## Requirements + + + **Enterprise Plan or Ultra Plan** is required to create or edit PII Redaction rules. Lower-tier organizations can still open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* — contact your account owner or sales to upgrade. + + +- The **Agent Control Plane** feature must be enabled for your organization. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements). +- The `manage` [RBAC permission](/en/enterprise/features/rbac) on Agent Control Plane is required to create, edit, toggle, or delete rules. The `read` permission is enough to view them. +- All rule changes are versioned for auditing. + +## Available rule types + +| Type | What it does | +|------|---------------| +| **PII Redaction** | Applies PII redaction to executions of every matching automation, using the same entity catalog and custom recognizers documented in [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions). | + +More rule types will be added over time. + +## Creating a rule + + + Rule edit side panel with conditions and PII mask type + + + + + Click **+ Create new** at the top-right of the Rules tab, or **View Details** on an existing rule card. + + + + Give the rule a clear name (e.g. *Mask PII (CC)*) and a description explaining when it applies. Both show up on the rule card and in the Engaged Automations modal. + + + + Today only **PII Redaction** is available. + + + + Conditions decide which automations the rule engages with. Both are optional and use **set-equality** semantics: + + - **Tools** — only automations whose tool set **exactly matches** the selected tools will engage. Picks from Studio apps, MCPs, OSS tools, and Tool Repository registry tools. + - **Automations** — only automations whose tag set **exactly matches** the selected tags will engage. + + Leaving a picker empty means "no filter on this dimension". Leaving both empty means the rule applies to **every** automation in the organization. + + + + Check each entity type you want covered and choose **Mask** (replaces with the entity label, e.g. ``) or **Redact** (removes the matched text entirely). See [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions) for the full entity catalog and how to add organization-level custom recognizers. + + + + The rule applies to **future** executions of every engaged automation as soon as you save. No re-deploy is needed. + + + +## Engaged automations + +Click **Engaged N automations** on any rule card to see exactly which deployments the rule is currently matching, along with each one's last execution. + + + ![Engaged automations modal](/images/enterprise/acp-rules-engaged-modal.png) + + +This is the fastest way to sanity-check a rule's scope before enabling it — for example, to confirm that a rule scoped to the `production` tag isn't accidentally matching a staging deployment. + +## Org-wide rules vs per-deployment settings + +PII Redaction can be configured in two places: + +- **Per-deployment** — under **Settings → PII Protection** on each individual deployment ([guide](/en/enterprise/features/pii-trace-redactions)) +- **Org-wide** — as a Rule on this page + +When an enabled org-wide rule's scope matches a deployment, the rule's entity configuration **overrides** the deployment-owned PII settings for that deployment's executions — the rule becomes the single source of truth while it's attached. Disable or detach the rule (or change its scope so it no longer matches) and the deployment falls back to its own PII Protection settings. + +Prefer org-wide rules when you want to enforce a consistent policy across many deployments; reserve per-deployment configuration for one-off exceptions. + +## Related + + + + What ACP is, requirements, plan tiers, and RBAC. + + + Monitor automations and LLM consumption across your fleet. + + + Entity catalog, custom recognizers, and per-deployment configuration. + + + Manage who can create or edit rules. + + + + + Contact our support team for help designing rules for your organization. + diff --git a/docs/v1.15.1/en/enterprise/features/agent-repositories.mdx b/docs/v1.15.1/en/enterprise/features/agent-repositories.mdx new file mode 100644 index 000000000..879d39045 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/agent-repositories.mdx @@ -0,0 +1,155 @@ +--- +title: 'Agent Repositories' +description: 'Learn how to use Agent Repositories to share and reuse your agents across teams and projects' +icon: 'people-group' +mode: "wide" +--- + +Agent Repositories allow enterprise users to store, share, and reuse agent definitions across teams and projects. This feature enables organizations to maintain a centralized library of standardized agents, promoting consistency and reducing duplication of effort. + + + ![Agent Repositories](/images/enterprise/agent-repositories.png) + + +## Benefits of Agent Repositories + +- **Standardization**: Maintain consistent agent definitions across your organization +- **Reusability**: Create an agent once and use it in multiple crews and projects +- **Governance**: Implement organization-wide policies for agent configurations +- **Collaboration**: Enable teams to share and build upon each other's work + +## Creating and Use Agent Repositories + +1. You must have an account at CrewAI, try the [free plan](https://app.crewai.com). +2. Create agents with specific roles and goals for your workflows. +3. Configure tools and capabilities for each specialized assistant. +4. Deploy agents across projects via visual interface or API integration. + + + ![Agent Repositories](/images/enterprise/create-agent-repository.png) + + + +### Loading Agents from Repositories + +You can load agents from repositories in your code using the `from_repository` parameter to run locally: + +```python +from crewai import Agent + +# Create an agent by loading it from a repository +# The agent is loaded with all its predefined configurations +researcher = Agent( + from_repository="market-research-agent" +) +``` + +### Overriding Repository Settings + +You can override specific settings from the repository by providing them in the configuration: + +```python +researcher = Agent( + from_repository="market-research-agent", + goal="Research the latest trends in AI development", # Override the repository goal + verbose=True # Add a setting not in the repository +) +``` + +### Example: Creating a Crew with Repository Agents + +```python +from crewai import Crew, Agent, Task + +# Load agents from repositories +researcher = Agent( + from_repository="market-research-agent" +) + +writer = Agent( + from_repository="content-writer-agent" +) + +# Create tasks +research_task = Task( + description="Research the latest trends in AI", + agent=researcher +) + +writing_task = Task( + description="Write a comprehensive report based on the research", + agent=writer +) + +# Create the crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +# Run the crew +result = crew.kickoff() +``` + +### Example: Using `kickoff()` with Repository Agents + +You can also use repository agents directly with the `kickoff()` method for simpler interactions: + +```python +from crewai import Agent +from pydantic import BaseModel +from typing import List + +# Define a structured output format +class MarketAnalysis(BaseModel): + key_trends: List[str] + opportunities: List[str] + recommendation: str + +# Load an agent from repository +analyst = Agent( + from_repository="market-analyst-agent", + verbose=True +) + +# Get a free-form response +result = analyst.kickoff("Analyze the AI market in 2025") +print(result.raw) # Access the raw response + +# Get structured output +structured_result = analyst.kickoff( + "Provide a structured analysis of the AI market in 2025", + response_format=MarketAnalysis +) + +# Access structured data +print(f"Key Trends: {structured_result.pydantic.key_trends}") +print(f"Recommendation: {structured_result.pydantic.recommendation}") +``` + +## Best Practices + +1. **Naming Convention**: Use clear, descriptive names for your repository agents +2. **Documentation**: Include comprehensive descriptions for each agent +3. **Tool Management**: Ensure that tools referenced by repository agents are available in your environment +4. **Access Control**: Manage permissions to ensure only authorized team members can modify repository agents + +## Organization Management + +To switch between organizations or see your current organization, use the CrewAI CLI: + +```bash +# View current organization +crewai org current + +# Switch to a different organization +crewai org switch + +# List all available organizations +crewai org list +``` + + +When loading agents from repositories, you must be authenticated and switched to the correct organization. If you receive errors, check your authentication status and organization settings using the CLI commands above. + diff --git a/docs/v1.15.1/en/enterprise/features/automations.mdx b/docs/v1.15.1/en/enterprise/features/automations.mdx new file mode 100644 index 000000000..675977e01 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/automations.mdx @@ -0,0 +1,104 @@ +--- +title: Automations +description: "Manage, deploy, and monitor your live crews (automations) in one place." +icon: "rocket" +mode: "wide" +--- + +## Overview + +Automations is the live operations hub for your deployed crews. Use it to deploy from GitHub or a ZIP file, manage environment variables, re‑deploy when needed, and monitor the status of each automation. + + + ![Automations Overview](/images/enterprise/automations-overview.png) + + + +## Deployment Methods + +### Deploy from GitHub + +Use this for version‑controlled projects and continuous deployment. + + + + Click Configure GitHub and authorize access. + + + Choose the Repository and Branch you want to deploy from. + + + Turn on Automatically deploy new commits to ship updates on every push. + + + Add secrets individually or use Bulk View for multiple variables. + + + Click Deploy to create your live automation. + + + + + ![GitHub Deployment](/images/enterprise/deploy-from-github.png) + + +### Deploy from ZIP + +Ship quickly without Git—upload a compressed package of your project. + + + + Select the ZIP archive from your computer. + + + Provide any required variables or keys. + + + Click Deploy to create your live automation. + + + + + ![ZIP Deployment](/images/enterprise/deploy-from-zip.png) + + +## Automations Dashboard + +The table lists all live automations with key details: + +- **CREW**: Automation name +- **STATUS**: Online / Failed / In Progress +- **URL**: Endpoint for kickoff/status +- **TOKEN**: Automation token +- **ACTIONS**: Re‑deploy, delete, and more + +Use the top‑right controls to filter and search: + +- Search by name +- Filter by Status +- Filter by Source (GitHub / Studio / ZIP) + +Once deployed, you can view the automation details and have the **Options** dropdown menu to `chat with this crew`, `Export React Component` and `Export as MCP`. + + + ![Automations Table](/images/enterprise/automations-table.png) + + +## Best Practices + +- Prefer GitHub deployments for version control and CI/CD +- Use re‑deploy to roll forward after code or config updates or set it to auto-deploy on every push + +## Related + + + + Deploy a Crew from GitHub or ZIP file. + + + Trigger automations via webhooks or API. + + + Stream real-time events and updates to your systems. + + diff --git a/docs/v1.15.1/en/enterprise/features/crew-studio.mdx b/docs/v1.15.1/en/enterprise/features/crew-studio.mdx new file mode 100644 index 000000000..b4ea0b238 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/crew-studio.mdx @@ -0,0 +1,88 @@ +--- +title: Crew Studio +description: "Build new automations with AI assistance, a visual editor, and integrated testing." +icon: "pencil" +mode: "wide" +--- + +## Overview + +Crew Studio is an interactive, AI‑assisted workspace for creating new automations from scratch using natural language and a visual workflow editor. + + + ![Crew Studio Overview](/images/enterprise/crew-studio-overview.png) + + +## Prompt‑based Creation + +- Describe the automation you want; the AI generates agents, tasks, and tools. +- Use voice input via the microphone icon if preferred. +- Start from built‑in prompts for common use cases. + + + ![Prompt Builder](/images/enterprise/crew-studio-prompt.png) + + +## Visual Editor + +The canvas reflects the workflow as nodes and edges with three supporting panels that allow you to configure the workflow easily without writing code; a.k.a. "**vibe coding AI Agents**". + +You can use the drag-and-drop functionality to add agents, tasks, and tools to the canvas or you can use the chat section to build the agents. Both approaches share state and can be used interchangeably. + +- **AI Thoughts (left)**: streaming reasoning as the workflow is designed +- **Canvas (center)**: agents and tasks as connected nodes +- **Resources (right)**: drag‑and‑drop components (agents, tasks, tools) + + + ![Visual Canvas](/images/enterprise/crew-studio-canvas.png) + + +## Execution & Debugging + +Switch to the Execution view to run and observe the workflow: + +- Event timeline +- Detailed logs (Details, Messages, Raw Data) +- Local test runs before publishing + + + ![Execution View](/images/enterprise/crew-studio-execution.png) + + +## Publish & Export + +- Publish to deploy a live automation +- Download source as a ZIP for local development or customization + + + ![Publish & Download](/images/enterprise/crew-studio-publish.png) + + +Once published, you can view the automation details and have the **Options** dropdown menu to `chat with this crew`, `Export React Component` and `Export as MCP`. + + + ![Published Automation](/images/enterprise/crew-studio-published.png) + + +## Best Practices + +- Iterate quickly in Studio; publish only when stable +- Keep tools constrained to minimum permissions needed +- Use Traces to validate behavior and performance + +## Related + + + + Enable Crew Studio. + + + Build a Crew. + + + Deploy a Crew from GitHub or ZIP file. + + + Export a React Component. + + diff --git a/docs/v1.15.1/en/enterprise/features/flow-hitl-management.mdx b/docs/v1.15.1/en/enterprise/features/flow-hitl-management.mdx new file mode 100644 index 000000000..36eb4325c --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/flow-hitl-management.mdx @@ -0,0 +1,558 @@ +--- +title: "Flow HITL Management" +description: "Enterprise-grade human review for Flows with email-first notifications, routing rules, and auto-response capabilities" +icon: "users-gear" +mode: "wide" +--- + + +Flow HITL Management features require the `@human_feedback` decorator, available in **CrewAI version 1.8.0 or higher**. These features apply specifically to **Flows**, not Crews. + + +CrewAI Enterprise provides a comprehensive Human-in-the-Loop (HITL) management system for Flows that transforms AI workflows into collaborative human-AI processes. The platform uses an **email-first architecture** that enables anyone with an email address to respond to review requests—no platform account required. + +## Overview + + + + Responders can reply directly to notification emails to provide feedback + + + Route requests to specific emails based on method patterns or flow state + + + Configure automatic fallback responses when no human replies in time + + + +### Key Benefits + +- **Simple mental model**: Email addresses are universal; no need to manage platform users or roles +- **External responders**: Anyone with an email can respond, even non-platform users +- **Dynamic assignment**: Pull assignee email directly from flow state (e.g., `sales_rep_email`) +- **Reduced configuration**: Fewer settings to configure, faster time to value +- **Email as primary channel**: Most users prefer responding via email over logging into a dashboard + +## Setting Up Human Review Points in Flows + +Configure human review checkpoints within your Flows using the `@human_feedback` decorator. When execution reaches a review point, the system pauses, notifies the assignee via email, and waits for a response. + +```python +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ContentApprovalFlow(Flow): + @start() + def generate_content(self): + return "Generated marketing copy for Q1 campaign..." + + @human_feedback( + message="Please review this content for brand compliance:", + emit=["approved", "rejected", "needs_revision"], + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Marketing copy for review..." + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + print(f"Publishing approved content. Reviewer notes: {result.feedback}") + + @listen("rejected") + def archive_content(self, result: HumanFeedbackResult): + print(f"Content rejected. Reason: {result.feedback}") +``` + +For complete implementation details, see the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide. + +### Decorator Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `message` | `str` | The message displayed to the human reviewer | +| `emit` | `list[str]` | Valid response options (displayed as buttons in UI) | + +## Platform Configuration + +Access HITL configuration from: **Deployment → Settings → Human in the Loop Configuration** + + + HITL Configuration Settings + + +### Email Notifications + +Toggle to enable or disable email notifications for HITL requests. + +| Setting | Default | Description | +|---------|---------|-------------| +| Email Notifications | Enabled | Send emails when feedback is requested | + + +When disabled, responders must use the dashboard UI or you must configure webhooks for custom notification systems. + + +### SLA Target + +Set a target response time for tracking and metrics purposes. + +| Setting | Description | +|---------|-------------| +| SLA Target (minutes) | Target response time. Used for dashboard metrics and SLA tracking | + +Leave empty to disable SLA tracking. + +## Email Notifications & Responses + +The HITL system uses an email-first architecture where responders can reply directly to notification emails. + +### How Email Responses Work + + + + When a HITL request is created, an email is sent to the assigned responder with the review content and context. + + + The email includes a special reply-to address with a signed token for authentication. + + + The responder simply replies to the email with their feedback—no login required. + + + The platform receives the reply, verifies the signed token, and matches the sender email. + + + The feedback is recorded and the flow continues with the human's input. + + + +### Response Format + +Responders can reply with: + +- **Emit option**: If the reply matches an `emit` option (e.g., "approved"), it's used directly +- **Free-form text**: Any text response is passed to the flow as feedback +- **Plain text**: The first line of the reply body is used as feedback + +### Confirmation Emails + +After processing a reply, the responder receives a confirmation email indicating whether the feedback was successfully submitted or if an error occurred. + +### Email Token Security + +- Tokens are cryptographically signed for security +- Tokens expire after 7 days +- Sender email must match the token's authorized email +- Confirmation/error emails are sent after processing + +## Routing Rules + +Route HITL requests to specific email addresses based on method patterns. + + + HITL Routing Rules Configuration + + +### Rule Structure + +```json +{ + "name": "Approvals to Finance", + "match": { + "method_name": "approve_*" + }, + "assign_to_email": "finance@company.com", + "assign_from_input": "manager_email" +} +``` + +### Matching Patterns + +| Pattern | Description | Example Match | +|---------|-------------|---------------| +| `approve_*` | Wildcard (any chars) | `approve_payment`, `approve_vendor` | +| `review_?` | Single char | `review_a`, `review_1` | +| `validate_payment` | Exact match | `validate_payment` only | + +### Assignment Priority + +1. **Dynamic assignment** (`assign_from_input`): If configured, pulls email from flow state +2. **Static email** (`assign_to_email`): Falls back to configured email +3. **Deployment creator**: If no rule matches, the deployment creator's email is used + +### Dynamic Assignment Example + +If your flow state contains `{"sales_rep_email": "alice@company.com"}`, configure: + +```json +{ + "name": "Route to Sales Rep", + "match": { + "method_name": "review_*" + }, + "assign_from_input": "sales_rep_email" +} +``` + +The request will be assigned to `alice@company.com` automatically. + + +**Use Case**: Pull the assignee from your CRM, database, or previous flow step to dynamically route reviews to the right person. + + +## Auto-Response + +Automatically respond to HITL requests if no human responds within a timeout. This ensures flows don't hang indefinitely. + +### Configuration + +| Setting | Description | +|---------|-------------| +| Enabled | Toggle to enable auto-response | +| Timeout (minutes) | Time to wait before auto-responding | +| Default Outcome | The response value (must match an `emit` option) | + + + HITL Auto-Response Configuration + + +### Use Cases + +- **SLA compliance**: Ensure flows don't hang indefinitely +- **Default approval**: Auto-approve low-risk requests after timeout +- **Graceful degradation**: Continue with a safe default when reviewers are unavailable + + +Use auto-response carefully. Only enable it for non-critical reviews where a default response is acceptable. + + +## Review Process + +### Dashboard Interface + +The HITL review interface provides a clean, focused experience for reviewers: + +- **Markdown Rendering**: Rich formatting for review content with syntax highlighting +- **Context Panel**: View flow state, execution history, and related information +- **Feedback Input**: Provide detailed feedback and comments with your decision +- **Quick Actions**: One-click emit option buttons with optional comments + + + HITL Pending Requests List + + +### Response Methods + +Reviewers can respond via three channels: + +| Method | Description | +|--------|-------------| +| **Email Reply** | Reply directly to the notification email | +| **Dashboard** | Use the Enterprise dashboard UI | +| **API/Webhook** | Programmatic response via API | + +### History & Audit Trail + +Every HITL interaction is tracked with a complete timeline: + +- Decision history (approve/reject/revise) +- Reviewer identity and timestamp +- Feedback and comments provided +- Response method (email/dashboard/API) +- Response time metrics + +## Analytics & Monitoring + +Track HITL performance with comprehensive analytics. + +### Performance Dashboard + + + HITL Metrics Dashboard + + + + + Monitor average and median response times by reviewer or flow. + + + Analyze review volume patterns to optimize team capacity. + + + View approval/rejection rates across different review types. + + + Track percentage of reviews completed within SLA targets. + + + +### Audit & Compliance + +Enterprise-ready audit capabilities for regulatory requirements: + +- Complete decision history with timestamps +- Reviewer identity verification +- Immutable audit logs +- Export capabilities for compliance reporting + +## Common Use Cases + + + + **Use Case**: Internal security questionnaire automation with human validation + + - AI generates responses to security questionnaires + - Security team reviews and validates accuracy via email + - Approved responses are compiled into final submission + - Full audit trail for compliance + + + + **Use Case**: Marketing content requiring legal/brand review + + - AI generates marketing copy or social media content + - Route to brand team email for voice/tone review + - Automatic publishing upon approval + + + + **Use Case**: Expense reports, contract terms, budget allocations + + - AI pre-processes and categorizes financial requests + - Route based on amount thresholds using dynamic assignment + - Maintain complete audit trail for financial compliance + + + + **Use Case**: Route reviews to account owners from your CRM + + - Flow fetches account owner email from CRM + - Store email in flow state (e.g., `account_owner_email`) + - Use `assign_from_input` to route to the right person automatically + + + + **Use Case**: AI output validation before customer delivery + + - AI generates customer-facing content or responses + - QA team reviews via email notification + - Feedback loops improve AI performance over time + + + +## Webhooks API + +When your Flows pause for human feedback, you can configure webhooks to send request data to your own application. This enables: + +- Building custom approval UIs +- Integrating with internal tools (Jira, ServiceNow, custom dashboards) +- Routing approvals to third-party systems +- Mobile app notifications +- Automated decision systems + + + HITL Webhook Configuration + + +### Configuring Webhooks + + + + Go to your **Deployment** → **Settings** → **Human in the Loop** + + + Click to expand the **Webhooks** configuration + + + Enter your webhook URL (must be HTTPS in production) + + + Click **Save Configuration** to activate + + + +You can configure multiple webhooks. Each active webhook receives all HITL events. + +### Webhook Events + +Your endpoint will receive HTTP POST requests for these events: + +| Event Type | When Triggered | +|------------|----------------| +| `new_request` | A flow pauses and requests human feedback | + +### Webhook Payload + +All webhooks receive a JSON payload with this structure: + +```json +{ + "event": "new_request", + "request": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "flow_id": "flow_abc123", + "method_name": "review_article", + "message": "Please review this article for publication.", + "emit_options": ["approved", "rejected", "request_changes"], + "state": { + "article_id": 12345, + "author": "john@example.com", + "category": "technology" + }, + "metadata": {}, + "created_at": "2026-01-14T12:00:00Z" + }, + "deployment": { + "id": 456, + "name": "Content Review Flow", + "organization_id": 789 + }, + "callback_url": "https://api.crewai.com/...", + "assigned_to_email": "reviewer@company.com" +} +``` + +### Responding to Requests + +To submit feedback, **POST to the `callback_url`** included in the webhook payload. + +```http +POST {callback_url} +Content-Type: application/json + +{ + "feedback": "Approved. Great article!", + "source": "my_custom_app" +} +``` + +### Security + + +All webhook requests are cryptographically signed using HMAC-SHA256 to ensure authenticity and prevent tampering. + + +#### Webhook Security + +- **HMAC-SHA256 signatures**: Every webhook includes a cryptographic signature +- **Per-webhook secrets**: Each webhook has its own unique signing secret +- **Encrypted at rest**: Signing secrets are encrypted in our database +- **Timestamp verification**: Prevents replay attacks + +#### Signature Headers + +Each webhook request includes these headers: + +| Header | Description | +|--------|-------------| +| `X-Signature` | HMAC-SHA256 signature: `sha256=` | +| `X-Timestamp` | Unix timestamp when the request was signed | + +#### Verification + +Verify by computing: + +```python +import hmac +import hashlib + +expected = hmac.new( + signing_secret.encode(), + f"{timestamp}.{payload}".encode(), + hashlib.sha256 +).hexdigest() + +if hmac.compare_digest(expected, signature): + # Valid signature +``` + +### Error Handling + +Your webhook endpoint should return a 2xx status code to acknowledge receipt: + +| Your Response | Our Behavior | +|---------------|--------------| +| 2xx | Webhook delivered successfully | +| 4xx/5xx | Logged as failed, no retry | +| Timeout (30s) | Logged as failed, no retry | + +## Security & RBAC + +### Dashboard Access + +HITL access is controlled at the deployment level: + +| Permission | Capability | +|------------|------------| +| `manage_human_feedback` | Configure HITL settings, view all requests | +| `respond_to_human_feedback` | Respond to requests, view assigned requests | + +### Email Response Authorization + +For email replies: +1. The reply-to token encodes the authorized email +2. Sender email must match the token's email +3. Token must not be expired (7-day default) +4. Request must still be pending + +### Audit Trail + +All HITL actions are logged: +- Request creation +- Assignment changes +- Response submission (with source: dashboard/email/API) +- Flow resume status + +## Troubleshooting + +### Emails Not Sending + +1. Check "Email Notifications" is enabled in configuration +2. Verify routing rules match the method name +3. Verify assignee email is valid +4. Check deployment creator fallback if no routing rules match + +### Email Replies Not Processing + +1. Check token hasn't expired (7-day default) +2. Verify sender email matches assigned email +3. Ensure request is still pending (not already responded) + +### Flow Not Resuming + +1. Check request status in dashboard +2. Verify callback URL is accessible +3. Ensure deployment is still running + +## Best Practices + + +**Start Simple**: Begin with email notifications to deployment creator, then add routing rules as your workflows mature. + + +1. **Use Dynamic Assignment**: Pull assignee emails from your flow state for flexible routing. + +2. **Configure Auto-Response**: Set up a fallback for non-critical reviews to prevent flows from hanging. + +3. **Monitor Response Times**: Use analytics to identify bottlenecks and optimize your review process. + +4. **Keep Review Messages Clear**: Write clear, actionable messages in the `@human_feedback` decorator. + +5. **Test Email Flow**: Send test requests to verify email delivery before going to production. + +## Related Resources + + + + Implementation guide for the `@human_feedback` decorator + + + Step-by-step guide for setting up HITL workflows + + + Configure role-based access control for your organization + + + Set up real-time event notifications + + diff --git a/docs/v1.15.1/en/enterprise/features/hallucination-guardrail.mdx b/docs/v1.15.1/en/enterprise/features/hallucination-guardrail.mdx new file mode 100644 index 000000000..db11956d8 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/hallucination-guardrail.mdx @@ -0,0 +1,251 @@ +--- +title: Hallucination Guardrail +description: "Prevent and detect AI hallucinations in your CrewAI tasks" +icon: "shield-check" +mode: "wide" +--- + +## Overview + +The Hallucination Guardrail is an enterprise feature that validates AI-generated content to ensure it's grounded in facts and doesn't contain hallucinations. It analyzes task outputs against reference context and provides detailed feedback when potentially hallucinated content is detected. + +## What are Hallucinations? + +AI hallucinations occur when language models generate content that appears plausible but is factually incorrect or not supported by the provided context. The Hallucination Guardrail helps prevent these issues by: + +- Comparing outputs against reference context +- Evaluating faithfulness to source material +- Providing detailed feedback on problematic content +- Supporting custom thresholds for validation strictness + +## Basic Usage + +### Setting Up the Guardrail + +```python +from crewai.tasks.hallucination_guardrail import HallucinationGuardrail +from crewai import LLM + +# Basic usage - will use task's expected_output as context +guardrail = HallucinationGuardrail( + llm=LLM(model="gpt-4o-mini") +) + +# With explicit reference context +context_guardrail = HallucinationGuardrail( + context="AI helps with various tasks including analysis and generation.", + llm=LLM(model="gpt-4o-mini") +) +``` + +### Adding to Tasks + +```python +from crewai import Task + +# Create your task with the guardrail +task = Task( + description="Write a summary about AI capabilities", + expected_output="A factual summary based on the provided context", + agent=my_agent, + guardrail=guardrail # Add the guardrail to validate output +) +``` + +## Advanced Configuration + +### Custom Threshold Validation + +For stricter validation, you can set a custom faithfulness threshold (0-10 scale): + +```python +# Strict guardrail requiring high faithfulness score +strict_guardrail = HallucinationGuardrail( + context="Quantum computing uses qubits that exist in superposition states.", + llm=LLM(model="gpt-4o-mini"), + threshold=8.0 # Requires score >= 8 to pass validation +) +``` + +### Including Tool Response Context + +When your task uses tools, you can include tool responses for more accurate validation: + +```python +# Guardrail with tool response context +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" +) +``` + +## How It Works + +### Validation Process + +1. **Context Analysis**: The guardrail compares task output against the provided reference context +2. **Faithfulness Scoring**: Uses an internal evaluator to assign a faithfulness score (0-10) +3. **Verdict Determination**: Determines if content is faithful or contains hallucinations +4. **Threshold Checking**: If a custom threshold is set, validates against that score +5. **Feedback Generation**: Provides detailed reasons when validation fails + +### Validation Logic + +- **Default Mode**: Uses verdict-based validation (FAITHFUL vs HALLUCINATED) +- **Threshold Mode**: Requires faithfulness score to meet or exceed the specified threshold +- **Error Handling**: Gracefully handles evaluation errors and provides informative feedback + +## Guardrail Results + +The guardrail returns structured results indicating validation status: + +```python +# Example of guardrail result structure +{ + "valid": False, + "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context." +} +``` + +### Result Properties + +- **valid**: Boolean indicating whether the output passed validation +- **feedback**: Detailed explanation when validation fails, including: + - Faithfulness score + - Verdict classification + - Specific reasons for failure + +## Integration with Task System + +### Automatic Validation + +When a guardrail is added to a task, it automatically validates the output before the task is marked as complete: + +```python +# Task output validation flow +task_output = agent.execute_task(task) +validation_result = guardrail(task_output) + +if validation_result.valid: + # Task completes successfully + return task_output +else: + # Task fails with validation feedback + raise ValidationError(validation_result.feedback) +``` + +### Event Tracking + +The guardrail integrates with CrewAI's event system to provide observability: + +- **Validation Started**: When guardrail evaluation begins +- **Validation Completed**: When evaluation finishes with results +- **Validation Failed**: When technical errors occur during evaluation + +## Best Practices + +### Context Guidelines + + + + Include all relevant factual information that the AI should base its output on: + + ```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. + """ + ``` + + + + Only include information directly related to the task to avoid confusion: + + ```python + # Good: Focused context + context = "The current weather in New York is 18°C with light rain." + + # Avoid: Unrelated information + context = "The weather is 18°C. The city has 8 million people. Traffic is heavy." + ``` + + + + Ensure your reference context reflects current, accurate information. + + + +### Threshold Selection + + + + Begin without custom thresholds to understand baseline performance. + + + + - **High-stakes content**: Use threshold 8-10 for maximum accuracy + - **General content**: Use threshold 6-7 for balanced validation + - **Creative content**: Use threshold 4-5 or default verdict-based validation + + + + Track validation results and adjust thresholds based on false positives/negatives. + + + +## Performance Considerations + +### Impact on Execution Time + +- **Validation Overhead**: Each guardrail adds ~1-3 seconds per task +- **LLM Efficiency**: Choose efficient models for evaluation (e.g., gpt-4o-mini) + +### Cost Optimization + +- **Model Selection**: Use smaller, efficient models for guardrail evaluation +- **Context Size**: Keep reference context concise but comprehensive +- **Caching**: Consider caching validation results for repeated content + +## Troubleshooting + + + **Possible Causes:** + - Context is too restrictive or unrelated to task output + - Threshold is set too high for the content type + - Reference context contains outdated information + + **Solutions:** + - Review and update context to match task requirements + - Lower threshold or use default verdict-based validation + - Ensure context is current and accurate + + + + **Possible Causes:** + - Threshold too high for creative or interpretive tasks + - Context doesn't cover all valid aspects of the output + - Evaluation model being overly conservative + + **Solutions:** + - Lower threshold or use default validation + - Expand context to include broader acceptable content + - Test with different evaluation models + + + + **Possible Causes:** + - Network connectivity issues + - LLM model unavailable or rate limited + - Malformed task output or context + + **Solutions:** + - Check network connectivity and LLM service status + - Implement retry logic for transient failures + - Validate task output format before guardrail evaluation + + + + Contact our support team for assistance with hallucination guardrail configuration or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/features/marketplace.mdx b/docs/v1.15.1/en/enterprise/features/marketplace.mdx new file mode 100644 index 000000000..8e5c1ee85 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/marketplace.mdx @@ -0,0 +1,46 @@ +--- +title: Marketplace +description: "Discover, install, and govern reusable assets for your enterprise crews." +icon: "store" +mode: "wide" +--- + +## Overview + +The Marketplace provides a curated surface for discovering integrations, internal tools, and reusable assets that accelerate crew development. + + + ![Marketplace Overview](/images/enterprise/marketplace-overview.png) + + +## Discoverability + +- Browse by category and capability +- Search for assets by name or keyword + +## Install & Enable + +- One‑click install for approved assets +- Enable or disable per crew as needed +- Configure required environment variables and scopes + + + ![Install & Configure](/images/enterprise/marketplace-install.png) + + +You can also download the templates directly from the marketplace by clicking on the `Download` button so +you can use them locally or refine them to your needs. + +## Related + + + + Connect external apps and manage internal tools your agents can use. + + + Publish and install tools to enhance your crews' capabilities. + + + Store, share, and reuse agent definitions across teams and projects. + + diff --git a/docs/v1.15.1/en/enterprise/features/merged-step-card.mdx b/docs/v1.15.1/en/enterprise/features/merged-step-card.mdx new file mode 100644 index 000000000..f0a3be647 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/merged-step-card.mdx @@ -0,0 +1,82 @@ +--- +title: One Card per Step +description: "Each step on the Studio canvas is a single card that combines the task and the agent that performs it." +icon: "layer-group" +mode: "wide" +--- + +## Overview + +On the Studio canvas, each step of work is represented by a **single card**. The card combines two things that used to live in separate nodes: + +- **The task** — what to do (name, description, expected output, and response format). +- **The agent** — who does it (the assigned agent, its model, and its tools). + +An agent isn't an independent participant in your workflow — it's an attribute of the task: *which agent performs this work.* Putting the task and its agent on one card makes that relationship explicit and turns your automation into a single, left-to-right chain of work units that's easier to read at a glance. + + + ![Merged step cards on the canvas](/images/enterprise/merged-step-card-canvas.png) + + +## On the canvas + +Each collapsed card shows: + +- The **task name and description** at the top. +- A **footer summarizing the assigned agent** — avatar, name, model, and tools. + +There's no separate agent node and no vertical agent → task edge. Your steps connect directly to one another in the order they run. + +## In the editor + +Open a card to edit it. The expanded view is the same card in a detailed state — not a different screen — organized into two clearly labeled sections. + + + ![Expanded step editor](/images/enterprise/merged-step-card-editor.png) + + +### The task — what to do + +Open by default, since this is what you usually edit: + +- **Name** +- **Description** +- **Expected Output** +- **Response Format** — surfaced here because it controls exactly what downstream steps (such as routing) read from this step. + +### The agent — who does it + +The assigned agent is shown as a summary — **name, model, and tools inline**. Its deeper configuration is preserved behind two disclosures: + +- **Role, goal & backstory** +- **Agent settings** — reasoning, max reasoning attempts, allow delegation, max iterations, and LLM settings. + + + An agent's full configuration — Role, Goal, Backstory, Model, Tools, LLM Settings, and the complete Agent Settings block — lives behind the **Role, goal & backstory** and **Agent settings** disclosures, organized by how often you edit it. + + +## Swapping vs. editing the agent + +There are two distinct ways to work with the agent on a card, and they do different things: + +- **Swap** reassigns *which* agent performs this task. Use the **Swap** control to pick a different agent from this project, choose one from your Agent Repository, or create a new agent. This is scoped to the task. +- **Editing** the agent — opening **Role, goal & backstory** or **Agent settings** — changes the agent *itself*. + + + ![Swap agent panel](/images/enterprise/merged-step-card-swap-agent.png) + + + + **Agents are reusable and shared.** The same agent can perform more than one task across your project. Editing an agent's role, backstory, or settings updates that agent **everywhere it's used** — not just on the card you opened. If you want a change to apply to only one step, **Swap** in a different agent instead of editing the shared one. + + +## Related + + + + Build automations with AI assistance and a visual editor. + + + Manage and reuse agents across your automations. + + diff --git a/docs/v1.15.1/en/enterprise/features/pii-trace-redactions.mdx b/docs/v1.15.1/en/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..75b6073aa --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: PII Redaction for Traces +description: "Automatically redact sensitive data from crew and flow execution traces" +icon: "lock" +mode: "wide" +--- + +## Overview + +PII Redaction is a CrewAI AMP feature that automatically detects and masks Personally Identifiable Information (PII) in your crew and flow execution traces. This ensures sensitive data like credit card numbers, social security numbers, email addresses, and names are not exposed in your CrewAI AMP traces. You can also create custom recognizers to protect organization-specific data. + + + + PII Redaction is available on the Enterprise plan. + Deployment must be version 1.8.0 or higher. + + + + + ![PII Redaction Overview](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## Why PII Redaction Matters + +When running AI agents in production, sensitive information often flows through your crews: + +- Customer data from CRM integrations +- Financial information from payment processors +- Personal details from form submissions +- Internal employee data + +Without proper redaction, this data appears in traces, making compliance with regulations like GDPR, HIPAA, and PCI-DSS challenging. PII Redaction solves this by automatically masking sensitive data before it's stored in traces. + +## How It Works + +1. **Detect** - Scan trace event data for known PII patterns +2. **Classify** - Identify the type of sensitive data (credit card, SSN, email, etc.) +3. **Mask/Redact** - Replace the sensitive data with masked values based on your configuration + +``` +Original: "Contact john.doe@company.com or call 555-123-4567" +Redacted: "Contact or call " +``` + +## Enabling PII Redaction + + + You must be on the Enterprise plan and your deployment must be version 1.8.0 or higher to use this feature. + + + + + In the CrewAI AMP dashboard, select your deployed crew and go to one of your deployments/automations, then navigate to **Settings** → **PII Protection**. + + + + Toggle on **PII Redaction for Traces**. This will enable automatic scanning and redaction of trace data. + + + You need to manually enable PII Redaction for each deployment. + + + + ![Enable PII Redaction](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + Select which types of PII to detect and redact. Each entity can be individually enabled or disabled. + + + ![Configure Entities](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + Save your configuration. PII redaction will be active on all subsequent crew executions, no redeployment is needed. + + + +## Supported Entity Types + +CrewAI supports the following PII entity types, organized by category. + +### Global Entities + +| Entity | Description | Example | +|--------|-------------|---------| +| `CREDIT_CARD` | Credit/debit card numbers | "4111-1111-1111-1111" | +| `CRYPTO` | Cryptocurrency wallet addresses | "bc1qxy2kgd..." | +| `DATE_TIME` | Dates and times | "January 15, 2024" | +| `EMAIL_ADDRESS` | Email addresses | "john@example.com" | +| `IBAN_CODE` | International bank account numbers | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | IPv4 and IPv6 addresses | "192.168.1.1" | +| `LOCATION` | Geographic locations | "New York City" | +| `MEDICAL_LICENSE` | Medical license numbers | "MD12345" | +| `NRP` | Nationalities, religious, or political groups | - | +| `PERSON` | Personal names | "John Doe" | +| `PHONE_NUMBER` | Phone numbers in various formats | "+1 (555) 123-4567" | +| `URL` | Web URLs | "https://example.com" | + +### US-Specific Entities + +| Entity | Description | Example | +|--------|-------------|---------| +| `US_BANK_NUMBER` | US Bank account numbers | "1234567890" | +| `US_DRIVER_LICENSE` | US Driver's license numbers | "D1234567" | +| `US_ITIN` | Individual Taxpayer ID | "900-70-0000" | +| `US_PASSPORT` | US Passport numbers | "123456789" | +| `US_SSN` | Social Security Numbers | "123-45-6789" | + +## Redaction Actions + +For each enabled entity, you can configure how the data is redacted: + +| Action | Description | Example Output | +|--------|-------------|----------------| +| `mask` | Replace with the entity type label | `` | +| `redact` | Completely remove the text | *(empty)* | + +## Custom Recognizers + +In addition to built-in entities, you can create **custom recognizers** to detect organization-specific PII patterns. + + + ![Custom Recognizers](/images/enterprise/pii_mask_recognizer.png) + + +### Recognizer Types + +You have two options for custom recognizers: + +| Type | Best For | Example Use Case | +|------|----------|------------------| +| **Pattern-based (Regex)** | Structured data with predictable formats | Salary amounts, employee IDs, project codes | +| **Deny-list** | Exact string matches | Company names, internal codenames, specific terms | + +### Creating a Custom Recognizer + + + + Go to your Organization **Settings** → **Organization** → **Add Recognizer**. + + + + + ![Configure Recognizer](/images/enterprise/pii_mask_recognizer_create.png) + + + Configure the following fields: + - **Name**: A descriptive name for the recognizer + - **Entity Type**: The entity label that will appear in redacted output (e.g., `EMPLOYEE_ID`, `SALARY`) + - **Type**: Choose between Regex Pattern or Deny List + - **Pattern/Values**: Regex pattern or list of strings to match + - **Confidence Threshold**: Minimum score (0.0-1.0) required for a match to trigger redaction. Higher values (e.g., 0.8) reduce false positives but may miss some matches. Lower values (e.g., 0.5) catch more matches but may over-redact. Default is 0.8. + - **Context Words** (optional): Words that increase detection confidence when found nearby + + + + Save the recognizer. It will be available to enable on your deployments. + + + +### Understanding Entity Types + +The **Entity Type** determines how matched content appears in redacted traces: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +Input: "Employee salary: $50,000" +Output: "Employee " +``` + +### Using Context Words + +Context words improve accuracy by increasing confidence when specific terms appear near the matched pattern: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +When "project" or "code" appears near "PRJ-1234", the recognizer has higher confidence it's a true match, reducing false positives. + + +## Viewing Redacted Traces + +Once PII redaction is enabled, your traces will show redacted values in place of sensitive data: + +``` +Task Output: "Customer placed order #12345. +Contact email: , phone: . +Payment processed for card ending in ." +``` + +Redacted values are clearly marked with angle brackets and the entity type label (e.g., ``), making it easy to understand what data was protected while still allowing you to debug and monitor crew behavior. + + + +## Best Practices + +### Performance Considerations + + + + Each enabled entity adds processing overhead. Only enable entities relevant to your data. + + + + For custom recognizers, use specific patterns to reduce false positives and improve performance. Regex patterns are best when identifying specific patterns in the traces such as salary, employee id, project code, etc. Deny-list recognizers are best when identifying exact strings in the traces such as company names, internal codenames, etc. + + + + Context words improve accuracy by only triggering detection when surrounding text matches. + + + +## Troubleshooting + + + **Possible Causes:** + - Entity type not enabled in configuration + - Pattern doesn't match the data format + - Custom recognizer has syntax errors + + **Solutions:** + - Verify entity is enabled in Settings → Security + - Test regex patterns with sample data + - Check logs for configuration errors + + + + **Possible Causes:** + - Overly broad entity types enabled (e.g., `DATE_TIME` catches dates everywhere) + - Custom recognizer patterns are too general + + **Solutions:** + - Disable entities that cause false positives + - Make custom patterns more specific + - Add context words to improve accuracy + + + + **Possible Causes:** + - Too many entities enabled + - NLP-based entities (`PERSON`, `LOCATION`, `NRP`) are computationally expensive as they use machine learning models + + **Solutions:** + - Only enable entities you actually need + - Consider using pattern-based alternatives where possible + - Monitor trace processing times in the dashboard + + +--- + +## Practical Example: Salary Pattern Matching + +This example demonstrates how to create a custom recognizer to detect and mask salary information in your traces. + +### Use Case + +Your crew processes employee or financial data that includes salary information in formats like: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +You want to automatically mask these values to protect sensitive compensation data. + +### Configuration + + + ![Salary Recognizer Configuration](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| Field | Value | +|-------|-------| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### Regex Pattern Breakdown + +| Pattern Component | Meaning | +|-------------------|---------| +| `salary:` | Matches the literal text "salary:" | +| `\s*` | Matches zero or more whitespace characters | +| `\$` | Matches the dollar sign (escaped) | +| `\s*` | Matches zero or more whitespace characters after $ | +| `\d{1,3}` | Matches 1-3 digits (e.g., "1", "50", "125") | +| `(,\d{3})*` | Matches comma-separated thousands (e.g., ",000", ",500,000") | +| `(\.\d{2})?` | Optionally matches cents (e.g., ".00", ".50") | + +### Example Results + +``` +Original: "Employee record shows salary: $125,000.00 annually" +Redacted: "Employee record shows annually" + +Original: "Base salary:$50,000 with bonus potential" +Redacted: "Base with bonus potential" +``` + + + Adding context words like "salary", "compensation", "pay", "wage", and "income" helps increase detection confidence when these terms appear near the matched pattern, reducing false positives. + + +### Enable the Recognizer for Your Deployments + + + Creating a custom recognizer at the organization level does not automatically enable it for your deployments. You must manually enable each recognizer for every deployment where you want it applied. + + +After creating your custom recognizer, enable it for each deployment: + + + + Go to your deployment/automation and open **Settings** → **PII Protection**. + + + + Under **Mask Recognizers**, you'll see your organization-defined recognizers. Check the box next to the recognizers you want to enable. + + + ![Enable Custom Recognizer](/images/enterprise/pii_mask_recognizers_options.png) + + + + + Save your changes. The recognizer will be active on all subsequent executions for this deployment. + + + + + Repeat this process for each deployment where you need the custom recognizer. This gives you granular control over which recognizers are active in different environments (e.g., development vs. production). + diff --git a/docs/v1.15.1/en/enterprise/features/rbac.mdx b/docs/v1.15.1/en/enterprise/features/rbac.mdx new file mode 100644 index 000000000..ad4ed77d7 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/rbac.mdx @@ -0,0 +1,256 @@ +--- +title: "Role-Based Access Control (RBAC)" +description: "Control access to crews, tools, and data with roles, scopes, and granular permissions." +icon: "shield" +mode: "wide" +--- + +## Overview + +RBAC in CrewAI AMP enables secure, scalable access management through two layers: + +1. **Feature permissions** — control what each role can do across the platform (manage, read, or no access) +2. **Entity-level permissions** — fine-grained access on individual automations, environment variables, LLM connections, and Git repositories + + + RBAC overview in CrewAI AMP + + +## Users and Roles + +Each member in your CrewAI workspace is assigned a role, which determines their access across various features. + +You can: + +- Use predefined roles (Owner, Member) +- Create custom roles tailored to specific permissions +- Assign roles at any time through the settings panel + +You can configure users and roles in Settings → Roles. + + + + Go to Settings → Roles in CrewAI AMP. + + + Use a predefined role (Owner, Member) or click{" "} + Create role to define a custom one. + + + Select users and assign the role. You can change this anytime. + + + +### Predefined Roles + +| Role | Description | +| :--------- | :-------------------------------------------------------------------------- | +| **Owner** | Full access to all features and settings. Cannot be restricted. | +| **Member** | Read access to most features, manage access to environment variables, LLM connections, and Studio projects. Cannot modify organization or default settings. | + +### Configuration summary + +| Area | Where to configure | Options | +| :-------------------- | :--------------------------------- | :-------------------------------------- | +| Users & Roles | Settings → Roles | Predefined: Owner, Member; Custom roles | +| Automation visibility | Automation → Settings → Visibility | Private; Whitelist users/roles | + +--- + +## Feature Permissions Matrix + +Every role has a permission level for each feature area. The three levels are: + +- **Manage** — full read/write access (create, edit, delete) +- **Read** — view-only access +- **No access** — feature is hidden/inaccessible + +| Feature | Owner | Member (default) | Available levels | Description | +| :------------------------ | :------ | :--------------- | :------------------------ | :-------------------------------------------------------------- | +| `usage_dashboards` | Manage | Read | Manage / Read / No access | View usage metrics and analytics | +| `crews_dashboards` | Manage | Read | Manage / Read / No access | View deployment dashboards, access automation details | +| `invitations` | Manage | Read | Manage / Read / No access | Invite new members to the organization | +| `training_ui` | Manage | Read | Manage / Read / No access | Access training/fine-tuning interfaces | +| `tools` | Manage | Read | Manage / Read / No access | Create and manage tools | +| `agents` | Manage | Read | Manage / Read / No access | Create and manage agents | +| `environment_variables` | Manage | Manage | Manage / No access | Create and manage environment variables | +| `llm_connections` | Manage | Manage | Manage / No access | Configure LLM provider connections | +| `default_settings` | Manage | No access | Manage / No access | Modify organization-wide default settings | +| `organization_settings` | Manage | No access | Manage / No access | Manage billing, plans, and organization configuration | +| `studio_projects` | Manage | Manage | Manage / No access | Create and edit projects in Studio | + + + When creating a custom role, most features can be set to **Manage**, **Read**, or **No access**. However, `environment_variables`, `llm_connections`, `default_settings`, `organization_settings`, and `studio_projects` only support **Manage** or **No access** — there is no read-only option for these features. + + +--- + +## Deploying from GitHub or Zip + +One of the most common RBAC questions is: _"What permissions does a team member need to deploy?"_ + +### Deploy from GitHub + +To deploy an automation from a GitHub repository, a user needs: + +1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard where deployments are created +2. **Git repository access** (if entity-level RBAC for Git repositories is enabled): the user's role must be granted access to the specific Git repository via entity-level permissions +3. **`studio_projects`: `Manage`** — if building the crew in Studio before deploying + +### Deploy from Zip + +To deploy an automation from a Zip file upload, a user needs: + +1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard +2. **Zip deployments enabled**: the organization must not have disabled zip deployments in organization settings + +### Quick Reference: Minimum Permissions for Deployment + +| Action | Required feature permissions | Additional requirements | +| :------------------- | :------------------------------------ | :----------------------------------------------- | +| Deploy from GitHub | `crews_dashboards: Read` | Git repo entity access (if Git RBAC is enabled) | +| Deploy from Zip | `crews_dashboards: Read` | Zip deployments must be enabled at the org level | +| Build in Studio | `studio_projects: Manage` | — | +| Configure LLM keys | `llm_connections: Manage` | — | +| Set environment vars | `environment_variables: Manage` | Entity-level access (if entity RBAC is enabled) | + +--- + +## Automation‑level Access Control (Entity Permissions) + +In addition to organization‑wide roles, CrewAI supports fine‑grained entity-level permissions that restrict access to individual resources. + +### Automation Visibility + +Automations support visibility settings that restrict access by user or role. This is useful for: + +- Keeping sensitive or experimental automations private +- Managing visibility across large teams or external collaborators +- Testing automations in isolated contexts + +Deployments can be configured as private, meaning only whitelisted users and roles will be able to interact with them. + +You can configure automation‑level access control in Automation → Settings → Visibility tab. + + + + Navigate to Automation → Settings → Visibility. + + + Choose Private to restrict access. The organization owner always + retains access. + + + Add specific users and roles allowed to view, run, and access + logs/metrics/settings. + + + Save changes, then confirm that non‑whitelisted users cannot view or run the + automation. + + + +### Private visibility: access outcomes + +| Action | Owner | Whitelisted user/role | Not whitelisted | +| :--------------------------- | :---- | :-------------------- | :-------------- | +| View automation | ✓ | ✓ | ✗ | +| Run automation/API | ✓ | ✓ | ✗ | +| Access logs/metrics/settings | ✓ | ✓ | ✗ | + + + The organization owner always has access. In private mode, only whitelisted + users and roles can view, run, and access logs/metrics/settings. + + + + Automation Visibility settings in CrewAI AMP + + +### Deployment Permission Types + +When granting entity-level access to a specific automation, you can assign these permission types: + +| Permission | What it allows | +| :------------------- | :-------------------------------------------------- | +| `run` | Execute the automation and use its API | +| `traces` | View execution traces and logs | +| `manage_settings` | Edit, redeploy, rollback, or delete the automation | +| `human_in_the_loop` | Respond to human-in-the-loop (HITL) requests | +| `full_access` | All of the above | + +### Entity-level RBAC for Other Resources + +When entity-level RBAC is enabled, access to these resources can also be controlled per user or role: + +| Resource | Controlled by | Description | +| :--------------------- | :------------------------------- | :---------------------------------------------------- | +| Environment variables | Entity RBAC feature flag | Restrict which roles/users can view or manage specific env vars | +| LLM connections | Entity RBAC feature flag | Restrict access to specific LLM provider configurations | +| Git repositories | Git repositories RBAC org setting | Restrict which roles/users can access specific connected repos | + +--- + +## Common Role Patterns + +While CrewAI ships with Owner and Member roles, most teams benefit from creating custom roles. Here are common patterns: + +### Developer Role + +A role for team members who build and deploy automations but don't manage organization settings. + +| Feature | Permission | +| :------------------------ | :--------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Manage | +| `invitations` | Read | +| `training_ui` | Read | +| `tools` | Manage | +| `agents` | Manage | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | Manage | + +### Viewer / Stakeholder Role + +A role for non-technical stakeholders who need to monitor automations and view results. + +| Feature | Permission | +| :------------------------ | :--------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Read | +| `invitations` | No access | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | No access | +| `llm_connections` | No access | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | No access | + +### Ops / Platform Admin Role + +A role for platform operators who manage infrastructure settings but may not build agents. + +| Feature | Permission | +| :------------------------ | :--------- | +| `usage_dashboards` | Manage | +| `crews_dashboards` | Manage | +| `invitations` | Manage | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | Manage | +| `organization_settings` | Read | +| `studio_projects` | No access | + +--- + + + Contact our support team for assistance with RBAC questions. + diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/aws-workload-identity.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/aws-workload-identity.mdx new file mode 100644 index 000000000..f9ba0e8c0 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/aws-workload-identity.mdx @@ -0,0 +1,321 @@ +--- +title: AWS Workload Identity (OIDC Federation) +description: Configure AWS Secrets Manager via Workload Identity for rotation-aware, credential-free secret access +sidebarTitle: With Workload Identity +icon: "id-badge" +--- + +## Overview + +This guide configures AWS Secrets Manager as a secret provider using **Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for AWS credentials via STS, and reads your secrets — without a long-lived AWS access key being stored anywhere. + + +**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials and don't care about rotation propagation, see the simpler [AWS — static keys / AssumeRole](/en/enterprise/features/secrets-manager/aws) guide. + + +### How it works at runtime + +1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform. +2. The worker calls `sts:AssumeRoleWithWebIdentity` on the IAM role you set up below, presenting the JWT. +3. AWS STS validates the JWT against CrewAI Platform's public OIDC issuer (so your platform installation must be reachable from AWS), then returns short-lived AWS credentials. +4. The worker uses those credentials to call `secretsmanager:GetSecretValue`. +5. The fetched value is injected as the environment variable's value for that automation kickoff. + +OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware. + +## Prerequisites + + +Before starting, make sure you have: + +- The automation pod image must include CrewAI runtime version `1.14.5` or later. +- An AWS account with permission to create IAM OIDC providers, IAM roles, and IAM policies. +- The AWS region where your secrets live (or will live), e.g. `us-east-1`. +- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac). +- **Your CrewAI organization UUID.** Find it on the organization's settings page in CrewAI Platform — the trust policy in Step 3 binds the IAM role to this specific organization. +- **Your CrewAI Platform installation must be reachable from AWS over HTTPS** so that AWS STS can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible (or that AWS has network reach to it via VPC peering / equivalent). + + +## Step 1 — Find Your CrewAI Platform OIDC Issuer URL + +Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https:///.well-known/openid-configuration`. The `issuer` field in that document is the URL AWS will register as a trusted OIDC provider. + +Open the URL in a browser (replacing `` with your actual hostname, e.g. `app.crewai.com`): + +``` +https:///.well-known/openid-configuration +``` + +You should see JSON containing: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +Note the exact value of `issuer` — you'll use it in Step 3. + + +If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration. + + +## Step 2 — Register CrewAI Platform as an IAM OIDC Identity Provider + +Open the [IAM → Identity providers console](https://console.aws.amazon.com/iam/home#/identity_providers) and click **Add provider**. + +- **Provider type:** OpenID Connect. +- **Provider URL:** the `issuer` value from Step 1 (e.g. `https://app.crewai.com`). +- **Audience:** `sts.amazonaws.com` + +Click **Add provider**. + +Or via CLI: + +```bash +aws iam create-open-id-connect-provider \ + --url "https://" \ + --client-id-list "sts.amazonaws.com" \ + --thumbprint-list "$(echo | openssl s_client -servername -connect :443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')" +``` + +Copy the **OpenIDConnectProviderArn** from the output (or the provider's ARN from the console). You'll use it in Step 3. + + +AWS does not actually validate the thumbprint for STS WebIdentity calls — it always re-fetches the JWKS at validation time — but the API requires the field to be present. + + +{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */} +{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */} + +## Step 3 — Create the IAM Role + +Save as `trust-policy.json`, replacing ``, `` (the issuer host **without** `https://` or `http://`, e.g. `app.crewai.com`), and `` (from the Prerequisites): + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":aud": "sts.amazonaws.com", + ":sub": "organization:" + } + } + } + ] +} +``` + +Create the role: + +```bash +aws iam create-role \ + --role-name crewai-secrets-reader \ + --assume-role-policy-document file://trust-policy.json +``` + +Copy the **Role Arn** from the output — that's your `aws_role_arn`. You'll paste it into CrewAI Platform in Step 6. + + +The two conditions scope the trust precisely: `aud` restricts assumption to tokens with the AWS STS audience, and `sub` scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted. CrewAI Platform always sets both claims on AWS workload identity tokens. + + +{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */} + +## Step 4 — Create and attach the IAM policy for Secrets Manager + KMS access + +Save as `secrets-policy.json`, replacing the placeholders with your account ID, region, secret-name prefix, and the KMS key ARN(s) that encrypt those secrets: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerListForUI", + "Effect": "Allow", + "Action": "secretsmanager:ListSecrets", + "Resource": "*" + }, + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:GetSecretValue" + ], + "Resource": "arn:aws:secretsmanager:::secret:-*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:Decrypt" + ], + "Resource": "arn:aws:kms:::key/" + } + ] +} +``` + +`SecretsManagerListForUI` powers the **Secret Name autocomplete** in the Environment Variables form and the **Test Connection** button on the credential. `secretsmanager:ListSecrets` only accepts `Resource: "*"` — it is account-scoped at the IAM layer. + +Attach the policy to the role using either the CLI (inline policy, simplest) or the console UI; for environments that reuse the same permissions across many roles, use the **Managed policy** tab for a reusable, named policy. + + + + ```bash + aws iam put-role-policy \ + --role-name crewai-secrets-reader \ + --policy-name SecretsManagerRead \ + --policy-document file://secrets-policy.json + ``` + + This attaches the policy **inline** to the role. Inline policies are tied to the role and cannot be reused on other roles. + + + + ```bash + POLICY_ARN=$(aws iam create-policy \ + --policy-name CrewAISecretsReader \ + --policy-document file://secrets-policy.json \ + --query 'Policy.Arn' --output text) + + aws iam attach-role-policy \ + --role-name crewai-secrets-reader \ + --policy-arn "$POLICY_ARN" + ``` + + A managed policy is a standalone IAM resource you can attach to multiple roles. + + + + 1. Open the [IAM → Roles console](https://console.aws.amazon.com/iam/home#/roles) and select **crewai-secrets-reader**. + 2. On the **Permissions** tab, click **Add permissions** → **Create inline policy**. + 3. Switch to the **JSON** editor and paste the contents of `secrets-policy.json`. + 4. Click **Next**, give the policy a name (e.g. `SecretsManagerRead`), and click **Create policy**. + + To create a reusable managed policy instead, use **IAM → Policies → Create policy** and then attach it to the role from the role's **Permissions** tab. + + {/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */} + + + +## Step 5 — Create at Least One Secret in AWS + +If you don't already have a secret to test against, create one now: + +```bash +aws secretsmanager create-secret \ + --region \ + --name crewai-test-keyword \ + --secret-string "hello from aws" +``` + +Or via the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**. + +{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */} + +## Step 6 — Add a Workload Identity Configuration in CrewAI Platform + +In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**. + +{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */} +{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */} + +Fill the form: + +- **Name:** A descriptive name, e.g. `aws-prod`. +- **Cloud Provider:** `AWS`. +- **AWS Role ARN:** the **Role Arn** from Step 3. +- **AWS Region:** the region where your secrets live, e.g. `us-east-1`. +- (Optional) Check **Set as default for AWS** if you'd like this WI config to be the default selected when creating an AWS-backed secret credential. + +Click **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */} +{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */} + +## Step 7 — Add a Secret Provider Credential Bound to the WI Config + +Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**. + +Fill the form: + +- **Name:** A descriptive name, e.g. `aws-prod-wi`. +- **Provider:** `AWS Secrets Manager`. +- **Authentication Method:** `Workload Identity` (instead of static keys / AssumeRole). +- **Workload Identity Configuration:** select the config you created in Step 6 (e.g. `aws-prod`). +- (Optional) Check **Set as default credential for this provider**. + +The form will only ask for **AWS Region** under Workload Identity — the static-credential fields (Access Key ID, Secret Access Key, Role ARN, External ID) are intentionally hidden because they don't apply to this path; the role ARN comes from the linked WI config. + +Click **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */} + +## Step 8 — Test the Connection + +After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT, exchanges it with AWS STS via `sts:AssumeRoleWithWebIdentity`, and confirms the resulting credentials can call `sts:GetCallerIdentity` against the assumed role. A green result means the federation binding is healthy. + +A successful Test Connection proves the trust policy, OIDC provider registration, and audience condition are all wired correctly. It does **not** prove per-secret IAM is correct — `secretsmanager:GetSecretValue` on a specific secret ARN is exercised separately when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes. + +## Step 9 — Reference the Secret in an Environment Variable + +Now reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior. + +The only difference between WI-backed and static-keys-backed env vars is **when** the secret is read: + +- **WI-backed:** secret value is read fresh on every automation kickoff. +- **Static-keys-backed:** secret value is read at deploy time and baked into the deployment image. + +## Step 10 — Verify Rotation + +After the deployment is running, rotate the secret in AWS: + +```bash +aws secretsmanager update-secret \ + --region \ + --secret-id crewai-test-keyword \ + --secret-string "rotated value" +``` + +Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no waiting on a TTL. + +To confirm in logs (if you have access to the worker), look for: + +``` +Workload identity config '' (aws): N secret(s) resolved +``` + +This line appears for every kickoff and indicates a fresh `GetSecretValue` call against AWS. + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| Test Connection fails with a handshake error | The `sts:AssumeRoleWithWebIdentity` call was rejected. Verify the trust policy's federated principal ARN references `oidc-provider/` (host **without** `https://` or `http://`, no trailing slash), the audience condition is exactly `sts.amazonaws.com`, the `sub` condition matches your CrewAI organization UUID, and the platform's OIDC discovery URL is reachable from AWS over the public internet. | +| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | AWS STS can't reach your CrewAI Platform host to fetch JWKS. Confirm the host is internet-accessible from AWS, the OIDC discovery URL returns 200, and the JWKS endpoint is reachable. | +| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | Trust policy mismatch. Re-check Step 3: the federated principal ARN must include `oidc-provider/` (host **without** `https://` or `http://`, no trailing slash), the audience condition must be exactly `sts.amazonaws.com`, and the `sub` condition must equal `organization:`. | +| Secret Name autocomplete shows `AccessDenied: secretsmanager:ListSecrets` | The role is missing `secretsmanager:ListSecrets` with `Resource: "*"`. Add the `SecretsManagerListForUI` statement from Step 4. | +| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but resource-scoped IAM is missing on the failing secret. Audit the role's `secretsmanager:GetSecretValue` and `kms:Decrypt` permissions for that specific secret's ARN and KMS key. | +| `RegionDisabledException` / no secrets found | The region in the Workload Identity Config doesn't match where the secret lives. Re-check Step 6. | +| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. | + +### Reference Links + +- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) +- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html) +- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) + +## Next Steps + +- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage) +- For multi-cloud, see also [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) and [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity). diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/aws.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/aws.mdx new file mode 100644 index 000000000..11eecac8f --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/aws.mdx @@ -0,0 +1,295 @@ +--- +title: AWS Secrets Manager (Static Credentials) +description: Configure AWS Secrets Manager as a secret provider for CrewAI Platform using static access keys or AssumeRole +sidebarTitle: With Static Credentials +icon: "key" +--- + +## Overview + +This guide walks you through configuring AWS Secrets Manager as a secret provider for your CrewAI Platform organization, using **static credentials** (access keys, optionally with AssumeRole). By the end, CrewAI Platform will be able to read secrets stored in your AWS account and inject them as environment variable values at runtime. + + +This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff (no re-deploy), see [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity). + + + +This guide covers the AWS-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage). + + +## Prerequisites + + +Before starting, make sure you have: + +- An AWS account with permission to create IAM users, customer-managed policies, and (optionally) IAM roles. +- The AWS region where your secrets live (or will live), for example `us-east-1`. +- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## Choose an Authentication Method + +CrewAI Platform supports two ways for the platform to authenticate with AWS Secrets Manager. Pick one before you begin — the steps below differ depending on which you choose. + +| Method | When to use | Trade-offs | +|---|---|---| +| **Static access keys** | Getting started, single-account deployments | Simplest setup; access keys must be rotated manually | +| **AssumeRole** | Cross-account, production hardening | Short-lived credentials; supports External ID; requires extra IAM role | + +The rest of this guide uses tabs in Steps 3–5 so you can follow the path that matches your choice. + +## Step 1 — Create an IAM User + +Open the [IAM console](https://console.aws.amazon.com/iam/), navigate to **Users**, then click **Create user**. + +- Suggested name: `crewai-secrets-reader`. +- Leave **Provide user access to the AWS Management Console** unchecked — this principal is used programmatically by CrewAI Platform, not by humans. +- Click **Next**. + +On the **Set permissions** page, leave the default selection. You will attach the policy in Step 3. + +Click **Next**, review, and click **Create user**. + +For full details, see the AWS documentation: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). + +{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */} + +## Step 2 — Create the IAM Policy + +CrewAI Platform needs read-only access to AWS Secrets Manager and permission to decrypt secrets via KMS. Create a customer-managed policy with the following JSON. + +In the IAM console, navigate to **Policies**, then click **Create policy**. + +Choose the **JSON** tab and replace the contents with: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:ListSecrets", + "secretsmanager:GetSecretValue", + "secretsmanager:DescribeSecret" + ], + "Resource": "*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:DescribeKey", + "kms:Decrypt" + ], + "Resource": "*" + } + ] +} +``` + +Click **Next**, then on the **Review and create** page: + +- **Policy name:** `CrewAISecretsManagerRead` +- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform` + +Click **Create policy**. + + +The policy above grants `*` on `Resource` for simplicity. In production, scope the `Resource` down to the ARNs of the specific secrets CrewAI Platform should access, and scope `kms:Decrypt` to the specific KMS key ARNs that encrypt those secrets. See the [AWS guidance on least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html). + + +{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */} +{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */} + +## Step 3 — Attach the Policy + + + + 1. In the IAM console, navigate to **Users** and click the user you created in Step 1. + 2. On the **Permissions** tab, click **Add permissions** → **Attach policies directly**. + 3. Search for `CrewAISecretsManagerRead`, select it, and click **Next**. + 4. Click **Add permissions**. + + {/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */} + + + + With AssumeRole, the policy is attached to a separate IAM **role** (not directly to the user). The user from Step 1 only needs permission to call `sts:AssumeRole` on that role. + + **Create the role:** + + 1. In the IAM console, navigate to **Roles** and click **Create role**. + 2. **Trusted entity type:** AWS account. Choose **This account** (or **Another AWS account** for cross-account setups, then enter the AWS account ID hosting the IAM user from Step 1). + 3. (Recommended) Check **Require external ID** and enter a value you generate yourself — this is a shared secret you will paste into CrewAI Platform in Step 5. + 4. Click **Next**. + 5. Attach the `CrewAISecretsManagerRead` policy. + 6. Click **Next**, name the role `CrewAISecretsManagerRole`, and click **Create role**. + + **Allow the IAM user to assume the role:** + + 1. Open the role you just created and copy its **ARN**. + 2. In the IAM console, navigate to **Users**, click the user from Step 1, and on the **Permissions** tab click **Add permissions** → **Create inline policy**. + 3. On the **JSON** tab, paste the following (replace `ROLE_ARN_FROM_ABOVE`): + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "ROLE_ARN_FROM_ABOVE" + } + ] + } + ``` + + 4. Name the policy `CrewAIAssumeSecretsRole` and click **Create policy**. + + {/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */} + {/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */} + + + +## Step 4 — Get Credentials + + + + 1. In the IAM console, open the user from Step 1. + 2. Click the **Security credentials** tab. + 3. Under **Access keys**, click **Create access key**. + 4. Select **Application running outside AWS** (or **Other**) as the use case. Click **Next**. + 5. (Optional) Add a description tag. Click **Create access key**. + 6. Click **Show** to reveal the secret access key, then copy both the **Access key ID** and the **Secret access key**, or click **Download .csv file**. + + + The secret access key is shown only once. If you close this page without copying it, you will need to delete the key and create a new one. + + + For full details, see the AWS documentation: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). + + {/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */} + {/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */} + + + + Even with AssumeRole, CrewAI Platform still needs an access key for the IAM user — it uses those keys as the calling identity to perform the `sts:AssumeRole` call. + + 1. Create an access key for the user exactly as described in the **Static access keys** tab above. + 2. Open the role you created in Step 3 and copy: + - The **Role ARN** (from the role summary). + - The **External ID** you configured (if any) — you set this yourself in Step 3, so make sure you have it on hand. + + {/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */} + + + +## Step 5 — Add the Credential in CrewAI Platform + +In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} +{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */} + + + + Fill the form: + + - **Name:** A descriptive name, e.g. `aws-prod`. + - **Provider:** `AWS Secrets Manager`. + - **Region:** The AWS region where your secrets live, e.g. `us-east-1`. This must match the region of the secrets you want to read. + - **Access Key ID:** The value from Step 4. + - **Secret Access Key:** The value from Step 4. + - (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference AWS secrets without specifying a credential explicitly. + + Leave **Role ARN** and **External ID** blank. + + Click **Create**. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */} + + + + Fill the form: + + - **Name:** A descriptive name, e.g. `aws-prod-assumerole`. + - **Provider:** `AWS Secrets Manager`. + - **Region:** The AWS region where your secrets live. + - **Access Key ID:** The IAM user's access key from Step 4 (used to call STS). + - **Secret Access Key:** The IAM user's secret access key from Step 4. + - **Role ARN:** The Role ARN you copied in Step 4. + - **External ID:** The External ID you set on the role's trust policy (omit if none). + - (Optional) Check **Set as default credential for this provider**. + + Click **Create**. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */} + + + + +**How the two modes behave at runtime:** + +- With **static access keys** only, CrewAI Platform calls AWS Secrets Manager directly using the keys you supplied. +- When a **Role ARN** is set, CrewAI Platform first calls `sts:AssumeRole` with the supplied access keys (and External ID if configured), then uses the short-lived credentials returned by STS to read your secrets. + + +{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */} + +## Step 6 — Create at Least One Secret in AWS + +If you do not already have secrets in AWS Secrets Manager, create one now so you can verify the connection in Step 7. + +In the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/), click **Store a new secret**. + +- **Secret type:** Choose **Other type of secret**. +- **Key/value pairs** — either: + - Enter one or more key/value pairs (recommended for structured secrets), or + - Use the **Plaintext** tab for a single string value. +- **Encryption key:** Use `aws/secretsmanager` (the AWS-managed key) unless you have a specific KMS key requirement. + +Click **Next**, then enter: + +- **Secret name:** A unique name, e.g. `crewai/openai-api-key`. +- **Description (optional):** A short note about what the secret is for. + +Click **Next** through the rotation and review steps, then click **Store**. + + +**JSON-key reference syntax.** If you store a secret with multiple key/value pairs (a JSON object), CrewAI Platform can extract a specific field using the `secret-name#json_key` syntax in environment variable references. For example, a secret named `database-credentials` with `{"username": "...", "password": "..."}` can be referenced as `database-credentials#password`. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details. + + +For full details, see the AWS documentation: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + +{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */} +{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */} + +## Step 7 — Test the Connection + +Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**. + +A success toast confirms that CrewAI Platform can authenticate to AWS and read secrets from your account. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */} + +If the test fails, check the most common causes: + +| Symptom | Likely cause | +|---|---| +| `AccessDenied` on `secretsmanager:ListSecrets` | Policy not attached, or wrong user. Re-check Step 3. | +| `AccessDenied` on `kms:Decrypt` | Missing the `KMSDecrypt` statement, or your secrets use a customer-managed KMS key not covered by `Resource: "*"`. | +| `InvalidClientTokenId` / `SignatureDoesNotMatch` | Wrong access key ID or secret access key. Re-check Step 4 and Step 5. | +| `RegionDisabledException` / no secrets found | The credential's **Region** does not match where your secrets actually live. | +| `AccessDenied` on `sts:AssumeRole` (AssumeRole only) | Inline `sts:AssumeRole` policy missing on the IAM user, or the role's trust policy does not allow this principal, or the External ID does not match. | +| Test passes immediately after creating the IAM user, but fails next time | IAM credentials sometimes take a minute or two to propagate globally. Retry. | + +## Next Steps + +Now that AWS is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to: + +- Grant org members the right permissions to use (or manage) Secrets Manager. +- Reference your AWS secrets from CrewAI Platform environment variables. + +If you want **rotation-aware** secrets that propagate without re-deploying, switch to [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff. diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/azure-workload-identity.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/azure-workload-identity.mdx new file mode 100644 index 000000000..091410322 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/azure-workload-identity.mdx @@ -0,0 +1,275 @@ +--- +title: Azure Workload Identity Federation +description: Configure Azure Key Vault via Microsoft Entra Workload Identity Federation for rotation-aware, credential-free secret access +sidebarTitle: With Workload Identity +icon: "id-badge" +--- + +## Overview + +This guide configures Azure Key Vault as a secret provider using **Microsoft Entra Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for an Entra access token via the Microsoft identity platform, and reads your secrets — without any client secret being stored anywhere. + + +**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials, see the simpler [Azure Key Vault — client secret](/en/enterprise/features/secrets-manager/azure) guide. + + +### How it works at runtime + +1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform. +2. The worker presents the JWT to Microsoft Entra at `https://login.microsoftonline.com//oauth2/v2.0/token` as a `client_assertion` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`), referencing the App Registration whose **Federated Identity Credential** matches the JWT's issuer + subject. +3. Entra validates the JWT against your platform's OIDC discovery document and JWKS, then returns a short-lived access token scoped to `https://vault.azure.net/.default`. +4. The worker calls Azure Key Vault to read the secret. +5. The fetched value is injected as the environment variable's value for that automation kickoff. + +OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware. + +## Prerequisites + + +Before starting, make sure you have: + +- The automation pod image must include CrewAI runtime version `1.14.5` or later. +- An Azure subscription and a Microsoft Entra tenant you can manage. +- Permission in the tenant to create App Registrations and add Federated Identity Credentials. +- A Key Vault using **Azure RBAC** for authorization (not the legacy access-policy model). +- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac). +- **Your CrewAI Platform installation must be reachable from Microsoft Entra over HTTPS** so that Entra can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible. + + +## Step 1 — Find Your CrewAI Platform OIDC Issuer URL + +Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https:///.well-known/openid-configuration`. The `issuer` field there is the URL Microsoft Entra will register as a trusted federation issuer. + +Open the URL in a browser: + +``` +https:///.well-known/openid-configuration +``` + +You should see JSON containing: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +Note the exact value of `issuer` — you'll use it in Step 3. + + +If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration. + + +## Step 2 — Create an App Registration + +In the [Microsoft Entra portal](https://entra.microsoft.com), navigate to **App registrations** and click **New registration**. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- Leave **Redirect URI** blank. + +Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** on the App's overview blade — you'll use them in Step 6. + +{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */} + +## Step 3 — Add a Federated Identity Credential + +The Federated Identity Credential tells Microsoft Entra: *trust JWTs minted by this issuer, with this subject, when they're presented as a client assertion for this App Registration.* + +On the App Registration, navigate to **Certificates & secrets** → **Federated credentials** → **Add credential**. + +- **Federated credential scenario:** `Other issuer`. +- **Issuer:** the CrewAI Platform issuer URL from Step 1, e.g. `https://`. +- **Subject identifier:** `organization:` — exactly the value of the JWT's `sub` claim. Find your org UUID in CrewAI Platform's organization settings. This scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted. +- **Name:** any descriptive label, e.g. `crewai-org-prod`. +- **Audience:** `api://AzureADTokenExchange`. This is the fixed audience Microsoft Entra requires for federated credentials and is what CrewAI Platform sets in the JWT's `aud` claim. + +Click **Add**. + + +**Per-org isolation.** The subject identifier (`organization:`) restricts the federated credential to a specific CrewAI organization's tokens. If multiple CrewAI organizations should share one App Registration, add one Federated Identity Credential per organization (each with the org's UUID). + + +For full details, see the Microsoft documentation: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust). + +{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */} + +## Step 4 — Grant the App Registration Access to Key Vault + +Grant the App Registration **Key Vault Secrets User** on the target vault — the same role you'd use for the static-credentials path. Use either vault-wide (simpler) or per-secret (least privilege). + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + Vault-wide scope grants the `secrets/list` permission that the **Secret Name autocomplete** in CrewAI Platform's env-var form depends on. Choose this tab if you want autocomplete to work. + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */} + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + Per-secret bindings disable the **Secret Name autocomplete** in CrewAI Platform's env-var form (autocomplete requires `secrets/list`, which is vault-scoped only). Type the full secret name instead. + + {/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */} + + + + For a **vault-wide** assignment: + + 1. Open your Key Vault in the Azure portal. + 2. Click **Access control (IAM)** → **Add** → **Add role assignment**. + 3. Select role **Key Vault Secrets User** → **Next**. + 4. Click **Select members**, search for the App Registration `crewai-secrets-reader`, click **Select**. + 5. Click **Review + assign**. + + For a **per-secret** assignment, use the same flow but start from **Objects** → **Secrets** → select the secret → its own **Access control (IAM)** panel. Per-secret bindings disable autocomplete (see the Per-secret tab above). + + + +## Step 5 — Create at Least One Secret in Key Vault + +If you don't already have a secret to test against, create one via the Azure CLI: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + +Or via the Azure portal: + +1. Open your Key Vault and navigate to **Objects** → **Secrets**. +2. Click **Generate/Import**. +3. **Upload options:** `Manual`. **Name:** the secret name (e.g. `openai-api-key`). **Secret value:** paste the value. +4. Click **Create**. + + +**Secret name conventions.** Azure Key Vault secret names cannot contain underscores. CrewAI Platform automatically converts underscores to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`), so you can keep underscore-style env-var names — but the underlying secret in Key Vault must use hyphens. + + +## Step 6 — Add a Workload Identity Configuration in CrewAI Platform + +In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**. + +Fill the form: + +- **Name:** A descriptive name, e.g. `azure-prod`. +- **Cloud Provider:** `Azure`. +- **Tenant ID:** your Microsoft Entra **Directory (tenant) ID** from Step 2. +- **Client ID:** your App Registration's **Application (client) ID** from Step 2. +- (Optional) Check **Set as default for Azure** if you'd like this to be the default WI config selected when creating an Azure-backed secret credential. + +The **Audience** is fixed at `api://AzureADTokenExchange` — Microsoft Entra requires this exact audience for federated credentials, so no Audience field is shown on the form. + +Click **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */} +{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */} + +## Step 7 — Add a Secret Provider Credential Bound to the WI Config + +Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**. + +Fill the form: + +- **Name:** A descriptive name, e.g. `azure-prod-wi`. +- **Provider:** `Azure Key Vault`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** select the config you created in Step 6. +- **Key Vault URL:** the vault's DNS hostname, e.g. `https://my-vault.vault.azure.net`. +- (Optional) Check **Set as default credential for this provider**. + +The form will only ask for **Key Vault URL** under Workload Identity — the static-credential fields (Tenant ID, Client ID, Client Secret) are intentionally hidden because they don't apply to this path; tenant + client come from the linked WI config. + +Click **Create**. + + +**One App Registration, many vaults.** The Key Vault URL lives on the credential, not the WI config. So one App Registration (and one WI config) can serve multiple Key Vaults — just create one Secret Provider Credential per vault, all linked to the same WI config. + + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */} + +## Step 8 — Test the Connection + +After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT, presents it to Microsoft Entra as a federated `client_assertion`, and confirms Entra returns a vault-scoped access token. A green result means the federation binding is healthy. + +A successful Test Connection proves the Federated Identity Credential's issuer, subject, and audience all match, and that the App Registration is reachable. It does **not** prove per-secret Key Vault RBAC is correct — `getSecret` against a specific secret is exercised separately when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes. + +## Step 9 — Reference the Secret in an Environment Variable + +Reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior. + +## Step 10 — Verify Rotation + +After the deployment is running, rotate the secret in Key Vault: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "rotated value" +``` + +Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no TTL wait. + +To confirm in worker logs, look for: + +``` +Workload identity config '' (azure): N secret(s) resolved +``` + +This line appears for every kickoff and indicates a fresh `getSecret` call against Azure Key Vault. + +For an end-to-end fingerprint-based verification, see [Verify Rotation End-to-End](/en/enterprise/features/secrets-manager/verify-rotation). + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| Test Connection fails with a handshake error | The federated `client_assertion` was rejected by Microsoft Entra. Verify the Federated Identity Credential's **Issuer** matches the platform's `issuer` value exactly, **Subject** is `organization:` (matching the JWT's `sub` claim), **Audience** is `api://AzureADTokenExchange`, and the platform's OIDC discovery URL is reachable from Entra over the public internet. | +| `AADSTS70021: No matching federated identity record found for presented assertion` | The Federated Identity Credential's **Issuer** + **Subject** + **Audience** don't all match the JWT exactly. Re-check Step 3: subject must be `organization:` (matching the JWT's `sub` claim), audience must be `api://AzureADTokenExchange`. | +| `AADSTS700024: Client assertion is not within its valid time range` | The CrewAI Platform host's clock is significantly skewed from real time. Check NTP on the host. | +| `AADSTS50013: Assertion failed signature validation` | Microsoft Entra couldn't verify the JWT's signature. Confirm `https:///oauth2/jwks` is reachable from the public internet and serves a valid JWKS. | +| Secret Name autocomplete shows `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` | The App Registration's **Key Vault Secrets User** role is scoped to a single secret. Grant the role at the vault scope so the `list` data-plane action is allowed. See Step 4. | +| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but per-secret Key Vault RBAC is missing on the failing secret. Audit **Key Vault Secrets User** on that specific secret (or extend the role assignment to the vault scope). | +| `Forbidden — request was not authorized` (vault using legacy access policies) | The vault hasn't been switched to Azure RBAC. Under the vault's **Access configuration**, set permission model to **Azure role-based access control** and re-grant the role from Step 4. | +| `azure_vault_url is required for Azure secret resolution` (worker logs) | The Secret Provider Credential is missing **Key Vault URL**. Re-check Step 7. | +| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. | + +### Reference Links + +- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) +- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust) +- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) + +## Next Steps + +- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage) +- For multi-cloud, the AWS-equivalent setup is at [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) and the GCP-equivalent at [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity). + +## Screenshot Reference + +The placeholders above map to: + +- `01-register-app.png` — Azure portal "Register an application" form filled with `crewai-secrets-reader`. +- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, with **Other issuer**, the platform issuer URL, subject `organization:`, audience `api://AzureADTokenExchange`. +- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, with **Key Vault Secrets User** and the App Registration selected. +- `04-per-secret-rbac.png` — Same form but at a single secret's IAM scope (alternative least-privilege path). +- `05-amp-add-wi-config-azure.png` — CrewAI Platform "Add Workload Identity Config" form with Cloud Provider = Azure, Tenant ID, Client ID populated. +- `06-amp-wi-list-with-azure.png` — Workload Identity list page after creation, showing rows for AWS, GCP, and the new Azure config. +- `07-amp-add-credential-azure-wi.png` — "Add Secret Provider Credential" form with Provider = Azure Key Vault, Auth = Workload Identity, the WI config picked, and Key Vault URL populated. diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/azure.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/azure.mdx new file mode 100644 index 000000000..2c39e6fee --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/azure.mdx @@ -0,0 +1,196 @@ +--- +title: Azure Key Vault +description: Configure Azure Key Vault as a secret provider for CrewAI Platform, end-to-end +sidebarTitle: With Static Credentials +icon: "key" +--- + +## Overview + +This guide walks you through configuring Azure Key Vault as a secret provider for your CrewAI Platform organization, using a **Microsoft Entra App Registration with a client secret**. By the end, CrewAI Platform will be able to read secrets stored in your Azure Key Vault and inject them as environment variable values at runtime. + + +This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff, see [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity). + + + +This guide covers the Azure-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage). + + +## Prerequisites + + +Before starting, make sure you have: + +- An Azure subscription with permission to create App Registrations in Microsoft Entra and to grant role assignments on Key Vault resources. +- A Key Vault using **Azure RBAC** for authorization (not the legacy access-policy model). If your vault still uses access policies, switch it to RBAC under the vault's **Access configuration** blade. +- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## Step 1 — Create an App Registration + +The App Registration is the Microsoft Entra-side identity CrewAI Platform will authenticate as. + +In the [Microsoft Entra portal](https://entra.microsoft.com), navigate to **App registrations** and click **New registration**. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- Leave **Redirect URI** blank. + +Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** on the App's overview blade — you'll paste both into CrewAI Platform in Step 4. + +For full details, see the Microsoft documentation: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). + +{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */} + +## Step 2 — Create a Client Secret + +On the App Registration, navigate to **Certificates & secrets** → **Client secrets** → **New client secret**. + +- **Description:** `crewai-platform` +- **Expires:** pick a duration that matches your rotation policy (Microsoft caps this at 24 months). + +Click **Add**. Copy the **Value** column immediately — it can never be re-displayed once you leave the page. + + +Client secrets are long-lived static credentials. Store the value securely (in a password manager or your own secret store) and rotate it before expiry. To eliminate static credentials entirely, use [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) instead. + + +{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */} + +## Step 3 — Grant the App Registration Access to Key Vault + +CrewAI Platform needs read access to secrets in your Key Vault. Use one of two scopes — **vault-wide** for simplicity, or **per-secret** for least privilege. + + + + In the [Key Vault console](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults), open the target vault, then navigate to **Access control (IAM)** → **Add** → **Add role assignment**. + + - **Role:** **Key Vault Secrets User** + - **Assign access to:** User, group, or service principal + - **Members:** search for and select your App Registration (`crewai-secrets-reader`). + + Click **Review + assign**. + + Or via the Azure CLI: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */} + + + + Grant the role at the level of an individual secret. Repeat for each secret CrewAI Platform should access: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */} + + + + +The **Key Vault Secrets User** role allows reading secret values but not listing all secrets in the vault. CrewAI Platform's secret-name autocomplete also calls `list` — that permission is included by the role at the vault scope, but **not** at the per-secret scope. With per-secret bindings, autocomplete won't suggest secrets; type the full secret name instead. + + +## Step 4 — Add the Credential in CrewAI Platform + +In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +Fill the form: + +- **Name:** A descriptive name, e.g. `azure-prod`. +- **Provider:** `Azure Key Vault`. +- **Key Vault URL:** the vault's DNS hostname, e.g. `https://my-vault.vault.azure.net`. +- **Tenant ID:** your Microsoft Entra **Directory (tenant) ID** from Step 1. +- **Client ID:** your App Registration's **Application (client) ID** from Step 1. +- **Client Secret:** the **Value** you copied in Step 2. +- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference Azure secrets without specifying a credential explicitly. + +Click **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */} + +## Step 5 — Create at Least One Secret in Azure Key Vault + +If you don't already have secrets in Key Vault, create one now so you can verify the connection in Step 6. + +In the Key Vault console, navigate to **Objects** → **Secrets** → **Generate/Import**. + +- **Upload options:** `Manual` +- **Name:** e.g. `openai-api-key` +- **Secret value:** paste your secret value +- Leave the rest at defaults. + +Click **Create**. + +Or via the Azure CLI: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + + +**Secret name conventions.** Azure Key Vault secret names cannot contain underscores. CrewAI Platform automatically converts underscores to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`), so you can keep underscore-style env-var names — but the underlying secret in Key Vault must use hyphens. + + + +**JSON-key reference syntax.** Key Vault treats secret values as opaque strings. If your secret value happens to be a JSON object, CrewAI Platform can extract a single field using the `secret-name#json_key` syntax (e.g. `database-credentials#password`). See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details. + + +For full details, see the Microsoft documentation: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli). + +{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */} + +## Step 6 — Test the Connection + +Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**. + +A success toast confirms that CrewAI Platform can authenticate to Microsoft Entra and read secrets from your vault. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */} + +If the test fails, check the most common causes: + +| Symptom | Likely cause | +|---|---| +| `AADSTS7000215: Invalid client secret provided` | The pasted **Client Secret** is wrong or expired. Re-create the secret (Step 2) and update the credential. | +| `AADSTS700016: Application not found in the directory` | The **Tenant ID** or **Client ID** doesn't match the App Registration. Re-check Step 4. | +| `Forbidden — caller does not have permission` | The App Registration is missing the **Key Vault Secrets User** role on the vault (or per-secret). Re-check Step 3. | +| `Vault not found` / DNS errors | The **Key Vault URL** is wrong, or your vault has private endpoints that block public access. Confirm the host responds to `curl https://.vault.azure.net/secrets?api-version=7.4`. | +| `Forbidden — request was not authorized` (vault using legacy access policies) | The vault hasn't been switched to Azure RBAC. Under the vault's **Access configuration**, set permission model to **Azure role-based access control** and re-grant the role from Step 3. | + +## Next Steps + +Now that Azure Key Vault is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to: + +- Grant org members the right permissions to use (or manage) Secrets Manager. +- Reference your Azure secrets from CrewAI Platform environment variables. + +If you want **rotation-aware** secrets that propagate without re-deploying, switch to [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) — same vault, no client secret to rotate, secrets are fetched per kickoff. + +## Screenshot Reference + +The placeholders above map to: + +- `01-register-app.png` — Azure portal "Register an application" form filled with `crewai-secrets-reader`. +- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, with the freshly-created secret row visible (Value column highlighted before it gets masked). +- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, with **Key Vault Secrets User** picked and the App Registration selected as a member. +- `04-per-secret-rbac.png` — Same panel but scoped to a single secret resource (alternative least-privilege path). +- `05-amp-add-credential-form-azure.png` — CrewAI Platform "Add Secret Provider Credential" form: Provider = Azure Key Vault, all five fields populated. +- `06-create-secret.png` — Azure Key Vault "Create a secret" panel with `openai-api-key` and a pasted value. +- `07-test-connection-success.png` — CrewAI Platform success toast / row state after clicking **Test Connection** on the credential. diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/gcp-workload-identity.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/gcp-workload-identity.mdx new file mode 100644 index 000000000..7c594d643 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/gcp-workload-identity.mdx @@ -0,0 +1,273 @@ +--- +title: GCP Workload Identity Federation +description: Configure Google Cloud Secret Manager via Workload Identity Federation for rotation-aware, credential-free secret access +sidebarTitle: With Workload Identity +icon: "id-badge" +--- + +## Overview + +This guide configures Google Cloud Secret Manager as a secret provider using **Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for Google Cloud credentials via the Security Token Service, and reads your secrets — without a long-lived service account key being stored anywhere. + + +**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials, see the simpler [GCP — service account key](/en/enterprise/features/secrets-manager/gcp) guide. + + +### How it works at runtime + +1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform. +2. The worker exchanges the JWT for a federated Google credential via the [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest), referencing the Workload Identity Pool Provider you set up below. +3. The worker calls `secretmanager.googleapis.com:accessSecretVersion` to read the secret, using the federated credential directly (the federated principal holds `roles/secretmanager.secretAccessor` — see Step 4). +4. The fetched value is injected as the environment variable's value for that automation kickoff. + +OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware. + +## Prerequisites + + +Before starting, make sure you have: + +- The automation pod image must include CrewAI runtime version `1.14.5` or later. +- A Google Cloud project with the **Secret Manager API**, **Security Token Service API**, and **IAM Credentials API** enabled. Enable them via the console or: + + ```bash + gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \ + --project= + ``` + +- Permission in the project to create Workload Identity Pools, IAM roles, service accounts, and (if needed) secrets. +- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac). +- **Your CrewAI Platform installation must be reachable from Google Cloud over HTTPS** so that GCP STS can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible. + + +## Step 1 — Find Your CrewAI Platform OIDC Issuer URL + +Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https:///.well-known/openid-configuration`. The `issuer` field there is the URL Google will register as a trusted OIDC provider. + +Open the URL in a browser: + +``` +https:///.well-known/openid-configuration +``` + +You should see JSON containing: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +Note the exact value of `issuer` — you'll use it in Step 3. + + +If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration. + + +## Step 2 — Create a Workload Identity Pool + +A Workload Identity Pool is a Google Cloud-side container for trusted external identities. You'll register CrewAI Platform as a provider inside this pool. + +```bash +gcloud iam workload-identity-pools create crewai-pool \ + --project= \ + --location=global \ + --display-name="CrewAI Platform" +``` + +Or in the [Workload Identity Pools console](https://console.cloud.google.com/iam-admin/workload-identity-pools), click **Create Pool**. + +{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */} + +## Step 3 — Add CrewAI Platform as an OIDC Provider in the Pool + +```bash +gcloud iam workload-identity-pools providers create-oidc crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --display-name="CrewAI Platform OIDC" \ + --issuer-uri="https://" \ + --attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \ + --attribute-condition="assertion.organization_id != ''" +``` + +The `--attribute-mapping` tells Google how to map JWT claims into Google attributes: +- `google.subject` is the principal identifier — we map it to the JWT's `sub` claim, which CrewAI Platform sets to `organization:`. +- `attribute.organization` is a custom attribute — we map it to the JWT's `organization_id` claim so you can reference it in IAM bindings later. + +The `--attribute-condition` is a defense-in-depth check that rejects tokens missing an `organization_id` claim. + +Get the **provider resource name** (you'll need it for the audience and IAM bindings): + +```bash +gcloud iam workload-identity-pools providers describe crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --format="value(name)" +``` + +Output looks like: + +``` +projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider +``` + +This is your **Workload Identity Provider** value for CrewAI Platform in Step 6. CrewAI Platform automatically computes the OIDC audience as `//iam.googleapis.com/` when issuing tokens. + +{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */} + +## Step 4 — Grant Secret Manager Access to the Federated Principal + +Bind both Secret Manager roles at project scope to the federated principal — one role enables the Secret Name autocomplete in the env-var form, the other allows reading secret values at automation kickoff. Both are required for the feature to work end-to-end. + +```bash +PRINCIPAL_SET="principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools/crewai-pool/attribute.organization/" + +# Required for the Secret Name autocomplete (calls secretmanager.secrets.list) +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.viewer" + +# Required to read secret values at kickoff +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" +``` + +Replace `` with the numeric project number (`gcloud projects describe --format='value(projectNumber)'`) and `` with the UUID of the CrewAI Platform organization that should be allowed to read your secrets. You can find the org UUID in the platform UI on the organization's settings page, or via the API. This scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted. + +Or via the Google Cloud console: + +1. Open **IAM & Admin** → **IAM** for your project. +2. Click **GRANT ACCESS**. +3. **New principals:** paste the full `principalSet://...attribute.organization/` string. +4. Assign role **Secret Manager Viewer** (`roles/secretmanager.viewer`). +5. Click **SAVE**. +6. Click **GRANT ACCESS** again and repeat with role **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + +**Per-org isolation.** The `principalSet://...attribute.organization/` pattern restricts access to a specific organization's tokens. If you have multiple CrewAI organizations sharing one Google Cloud project, repeat both bindings per-org with the correct UUID — or use a less restrictive attribute condition if isolation isn't needed. + + + +**Scoping `secretAccessor` per-secret (optional).** If you'd rather not grant `roles/secretmanager.secretAccessor` project-wide, omit the second binding above and bind per-secret instead: + +```bash +gcloud secrets add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" \ + --project= +``` + +Keep `roles/secretmanager.viewer` at the project scope either way — `secretmanager.secrets.list` (which the autocomplete relies on) cannot be granted per-secret. + + +## Step 5 — Create at Least One Secret in GCP + +If you don't already have a secret to test against, create one via the `gcloud` CLI: + +```bash +echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \ + --data-file=- \ + --project= \ + --replication-policy=automatic +``` + +Or via the [Secret Manager console](https://console.cloud.google.com/security/secret-manager): + +1. Open **Secret Manager** in your GCP project. +2. Click **+ CREATE SECRET**. +3. **Name:** `crewai-test-keyword`. **Secret value:** paste your value. +4. Click **CREATE SECRET**. + +## Step 6 — Add a Workload Identity Configuration in CrewAI Platform + +In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**. + +Fill the form: + +- **Name:** A descriptive name, e.g. `gcp-prod`. +- **Cloud Provider:** `GCP`. +- **Workload Identity Provider:** the provider resource name from Step 3, e.g. `projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`. +- (Optional) Toggle **Default Configuration** if you'd like this to be the default WI config selected when creating a GCP-backed secret credential. + +Click **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */} +{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */} + +## Step 7 — Add a Secret Provider Credential Bound to the WI Config + +Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**. + +Fill the form: + +- **Name:** A descriptive name, e.g. `gcp-prod-wi`. +- **Provider:** `Google Cloud Secret Manager`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** select the config you created in Step 6. +- **Project ID:** your GCP project ID (the same project that owns the secrets). +- (Optional) Check **Set as default credential for this provider**. + +The form will only ask for **Project ID** under Workload Identity — the **Service Account JSON** field is intentionally hidden because it doesn't apply to this path; the federated identity comes from the linked WI config. + +Click **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */} + +## Step 8 — Test the Connection + +After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT and exchanges it via the Security Token Service for a federated Google access token. A green result means the federation binding is healthy. + +A successful Test Connection proves the Workload Identity Pool, OIDC provider, attribute mapping, and attribute condition are all wired correctly. It does **not** prove Secret Manager IAM is correct — `secretmanager.secrets.list` and `secretmanager.versions.access` are exercised separately when the Secret Name autocomplete loads or when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes. + +## Step 9 — Reference the Secret in an Environment Variable + +Reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior. + +## Step 10 — Verify Rotation + +After the deployment is running, rotate the secret in GCP by adding a new version (Secret Manager always reads the latest enabled version by default): + +```bash +echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \ + --data-file=- \ + --project= +``` + +Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no TTL wait. + +To confirm in worker logs, look for: + +``` +Workload identity config '' (gcp): N secret(s) resolved +``` + +This line appears for every kickoff and indicates a fresh `accessSecretVersion` call against GCP. + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| Test Connection fails with a handshake error | The STS token exchange was rejected. Verify the Workload Identity Pool exists, the OIDC provider's issuer matches the platform's `issuer` value, and the attribute condition accepts the JWT's claims. Confirm the platform's OIDC discovery URL is reachable from GCP over the public internet. | +| `Could not refresh access token: invalid_target` | The audience claim doesn't match the Workload Identity Provider's expected audience. CrewAI Platform sets the audience automatically; if you customized it, ensure it matches `//iam.googleapis.com/`. | +| `Failed to fetch JWKS from issuer` | GCP STS can't reach your CrewAI Platform host. Confirm the host is internet-accessible and `/.well-known/openid-configuration` returns 200. | +| `Attribute condition rejected token` | The OIDC provider's attribute condition (Step 3) requires `organization_id`. CrewAI Platform always sets this claim, so this usually means a misconfigured pool/provider. Re-check the provider's attribute condition. | +| Secret Name autocomplete shows `PERMISSION_DENIED: secretmanager.secrets.list` | The federated principal is missing `roles/secretmanager.viewer` at project scope. The `secretmanager.secrets.list` permission is project-scoped only and cannot be granted per-secret. See Step 4. | +| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but `secretmanager.versions.access` is missing on the failing secret. Audit `roles/secretmanager.secretAccessor` (project-scoped, or per-secret if you scoped it that way in Step 4). | +| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. | + +### Reference Links + +- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation) +- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) +- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control) + +## Next Steps + +- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage) +- For multi-cloud, see also [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) and [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity). diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/gcp.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/gcp.mdx new file mode 100644 index 000000000..6283105e8 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/gcp.mdx @@ -0,0 +1,189 @@ +--- +title: Google Cloud Secret Manager +description: Configure Google Cloud Secret Manager as a secret provider for CrewAI Platform, end-to-end +sidebarTitle: With Static Credentials +icon: "key" +--- + +## Overview + +This guide walks you through configuring Google Cloud Secret Manager as a secret provider for your CrewAI Platform organization, using **service account credentials**. By the end, CrewAI Platform will be able to read secrets stored in your Google Cloud project and inject them as environment variable values at runtime. + + +This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff, see [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity). + + + +This guide covers the GCP-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage). + + +## Prerequisites + + +Before starting, make sure you have: + +- A Google Cloud project with the **Secret Manager API** enabled. Enable it in the [APIs & Services console](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com) or via `gcloud`: + + ```bash + gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID + ``` + +- Permission in the project to create service accounts, grant IAM roles, and (if needed) create secrets. +- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## Step 1 — Create a Service Account + +A service account is the GCP-side identity CrewAI Platform will authenticate as. + +In the [IAM & Admin → Service Accounts console](https://console.cloud.google.com/iam-admin/serviceaccounts), click **Create Service Account**. + +- **Service account name:** `crewai-secrets-reader` +- **Service account ID:** auto-fills from the name (e.g. `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`) +- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform" + +Click **Create and Continue**. Skip the optional grants on this screen — you'll attach the role in Step 2. Click **Done**. + +For full details, see the GCP documentation: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create). + +{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */} + +## Step 2 — Grant Secret Manager Access + +CrewAI Platform needs permission to list and read secrets in your project. Use one of two scopes — **project-wide** for simplicity, or **per-secret** for least privilege. + + + + In the [IAM console](https://console.cloud.google.com/iam-admin/iam), click **Grant Access** and: + + - **New principals:** the service account's email from Step 1. + - **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + Click **Save**. + + Or via `gcloud`: + + ```bash + gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" + ``` + + {/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */} + + + + Grant the role only on the specific secrets CrewAI Platform should access. Repeat for each secret: + + ```bash + gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" \ + --project=YOUR_PROJECT_ID + ``` + + Or in the console: open each secret in [Secret Manager](https://console.cloud.google.com/security/secret-manager), click **Permissions** in the right panel, and grant **Secret Manager Secret Accessor** to the service account. + + {/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */} + + + + +The `roles/secretmanager.secretAccessor` role grants read-only access to secret values. CrewAI Platform also calls `secretmanager.secrets.list` for the autocomplete experience in the env-var form — that permission is included in the role at the project scope, but **not** at the per-secret scope. With per-secret bindings, autocomplete won't suggest secrets; you'll need to type the full secret name. + + +## Step 3 — Create a Service Account Key + +Open the service account from Step 1 in the [IAM & Admin → Service Accounts console](https://console.cloud.google.com/iam-admin/serviceaccounts). + +- Click the **Keys** tab. +- Click **Add Key** → **Create new key**. +- **Key type:** JSON. +- Click **Create**. The browser downloads a JSON file — keep it secure; it cannot be re-downloaded. + +Or via `gcloud`: + +```bash +gcloud iam service-accounts keys create ./crewai-secrets-reader.json \ + --iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com +``` + + +The service account key is a long-lived static credential. Store it securely (in a password manager or your own secret store) and rotate it on a regular cadence. To eliminate static credentials entirely, use [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) instead. + + +{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */} + +## Step 4 — Add the Credential in CrewAI Platform + +In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +Fill the form: + +- **Name:** A descriptive name, e.g. `gcp-prod`. +- **Provider:** `Google Cloud Secret Manager`. +- **Project ID:** Your GCP project ID (e.g. `my-crewai-prod`). +- **Service Account JSON:** Paste the entire contents of the JSON file you downloaded in Step 3. +- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference GCP secrets without specifying a credential explicitly. + +Click **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */} + +## Step 5 — Create at Least One Secret in GCP + +If you don't already have secrets in GCP Secret Manager, create one now so you can verify the connection in Step 6. + +In the [Secret Manager console](https://console.cloud.google.com/security/secret-manager), click **Create secret**. + +- **Name:** A unique name, e.g. `openai-api-key`. +- **Secret value:** Either paste a raw value or upload a file. +- Leave the rotation, replication, and other settings at their defaults unless you have a specific requirement. + +Click **Create secret**. + +Or via `gcloud`: + +```bash +echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \ + --data-file=- \ + --project=YOUR_PROJECT_ID \ + --replication-policy=automatic +``` + + +**JSON-key reference syntax.** GCP Secret Manager treats secret values as opaque blobs. If your secret value happens to be a JSON string, CrewAI Platform can extract a single field using the `secret-name#json_key` syntax (e.g. `database-credentials#password`). See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details. + + +For full details, see the GCP documentation: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart). + +{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */} + +## Step 6 — Test the Connection + +Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**. + +A success toast confirms that CrewAI Platform can authenticate to GCP and read secrets from your project. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */} + +If the test fails, check the most common causes: + +| Symptom | Likely cause | +|---|---| +| `PERMISSION_DENIED` on listing secrets | Service account is missing `roles/secretmanager.secretAccessor`, or you scoped it per-secret (`list` is not granted). Re-check Step 2. | +| `PERMISSION_DENIED` on `secretmanager.secrets.access` | Same as above, but for a specific secret. Confirm the service account has accessor role on the secret in question. | +| `unauthorized_client` / `invalid_grant` | The pasted Service Account JSON is invalid, expired, or for a deleted service account. Re-create the key (Step 3) and re-paste. | +| `Project ID does not match` | The Project ID field in CrewAI Platform doesn't match the project that owns the service account / secrets. Re-check Step 4. | +| `API not enabled` | Secret Manager API isn't enabled on the project. See Prerequisites. | + +## Next Steps + +Now that GCP is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to: + +- Grant org members the right permissions to use (or manage) Secrets Manager. +- Reference your GCP secrets from CrewAI Platform environment variables. + +If you want **rotation-aware** secrets that propagate without re-deploying, switch to [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff. diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/overview.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/overview.mdx new file mode 100644 index 000000000..8de3b8e34 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/overview.mdx @@ -0,0 +1,96 @@ +--- +title: Secrets Manager Overview +description: Connect external secret stores to CrewAI Platform and reference managed secrets from environment variables +sidebarTitle: Overview +icon: "book-open" +--- + +## Overview + +The Secrets Manager feature lets your organization connect an external secret store — AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault — and reference those secrets directly from environment variables on your automations and crews. Instead of pasting plaintext values into the platform, you store one set of credentials per provider and refer to secrets by name. + +This gives you: + +- **Centralized storage** — manage secrets in your provider rather than editing CrewAI Platform configuration. CrewAI Platform keeps no plaintext copy of the secret value. +- **Reduced exposure** — sensitive values never live in plaintext in your CrewAI Platform configuration. +- **Cloud-native auditability** — your provider's audit log records every secret read. + + +Secrets Manager (both the static-credentials and Workload Identity paths) requires CrewAI runtime version `1.14.5` or later in the automation pod image. + + +## Two Paths: Static Credentials vs Workload Identity + +There are two ways to wire CrewAI Platform up to your cloud's secret store. **They differ significantly in rotation behavior**, so choose based on how often your secrets rotate and how strict your security posture is. + +| Aspect | Static Credentials | Workload Identity (OIDC Federation) | +|---|---|---| +| **Authentication** | Long-lived access keys / service account JSON stored in CrewAI Platform | Short-lived tokens minted per worker process; no static credentials stored anywhere | +| **Rotation propagation** | Resolved at deploy time and **baked into the deployment's container image** — rotated values require a re-deploy | Resolved at **automation execution time** — rotated values propagate to the next kickoff with no re-deploy | +| **Setup effort** | Lower — paste keys / upload service account JSON | Higher — register CrewAI Platform as an OIDC provider in your cloud, configure trust policies | +| **Best for** | Getting started, infrequently-rotated secrets, single-account deployments | Production, frequently-rotated secrets, compliance-driven environments that prohibit long-lived credentials | + + +**Both paths use the same UI flow** to reference secrets in environment variables (see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage)). The difference is entirely in how the platform authenticates to your cloud and when it reads the secret value. + + +### Choose your setup guide + +| Provider | Static Credentials | Workload Identity | +|---|---|---| +| AWS Secrets Manager | [AWS — static keys / AssumeRole](/en/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/en/enterprise/features/secrets-manager/aws-workload-identity) | +| Google Cloud Secret Manager | [GCP — service account key](/en/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) | +| Azure Key Vault | [Azure — client secret](/en/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) | + + +The Secrets Manager and Workload Identity UIs are currently labeled **Beta** in CrewAI Platform. + + +## How It Fits Together + +Setting up Secrets Manager is a three-step flow that involves both your cloud provider and CrewAI Platform: + +1. **An admin configures a provider credential.** This is the cloud-side work — and the work differs depending on which path (static credentials or Workload Identity) you choose. Provider-specific guides cover this end to end. +2. **An admin (or a permitted member) references a secret in an environment variable.** From the Environment Variables page, the user picks a provider credential and selects the secret name. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables). +3. **The automation receives the resolved value at runtime.** When a crew or automation runs, CrewAI Platform fetches the secret from your provider and injects it as the environment variable's value. With Workload Identity, this fetch happens on every kickoff (rotation-aware). With static credentials, this fetch happens at deploy time and the value is baked into the deployment image. + +## Visibility & Scope + + +WI-backed environment variables follow the same assignment model as plaintext environment variables: an automation resolves only the WI-backed variables explicitly assigned to it. Assign a WI-backed variable to an automation from the Environment Variables page on that automation; variables defined at the organization level or in a Studio project are not resolved at kickoff until you assign them. + + + +The secret-fetch stage runs on every kickoff but only does work when WI-backed environment variables are assigned to the deployment. For each assigned variable, the runtime resolves the value from your cloud provider on every crew, flow, training, test, or checkpoint-restore kickoff and writes it into the process environment. With nothing assigned, the stage is a no-op. Otherwise, cost is proportional to the number of assigned variables: a small added latency per kickoff plus one cloud-side audit-log entry per variable. + + + +At the Workload Identity *configuration* level, scope is still organization-wide today. Every automation in the organization is bootstrapped against every Workload Identity configuration the org has registered, and you cannot today bind a specific Workload Identity configuration to a specific automation. Per-automation Workload Identity scoping is on the roadmap. Until then, only register Workload Identity configurations every automation in your organization is allowed to use. + + +## Permissions + +Two CrewAI Platform features control access to Secrets Manager: + +- `secret_providers` — controls who can view or manage provider credentials. +- `environment_variables` — controls who can create and edit environment variables (including those that reference secrets). + +A third feature controls Workload Identity setup: + +- `workload_identity_configs` — controls who can view or manage Workload Identity configurations. Required only if you're using the Workload Identity path. + +Owners always have full access. Members do **not** receive access to `secret_providers` or `workload_identity_configs` by default and must be granted permission via a custom role. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac) for the full matrix and step-by-step instructions. + +## Next Steps + +Pick your path: + +- **Static credentials** (simpler, requires re-deploy on rotation): + - [Configure AWS Secrets Manager](/en/enterprise/features/secrets-manager/aws) + - [Configure Google Cloud Secret Manager](/en/enterprise/features/secrets-manager/gcp) + - [Configure Azure Key Vault](/en/enterprise/features/secrets-manager/azure) +- **Workload Identity** (rotation-aware, no re-deploy): + - [Configure AWS Workload Identity](/en/enterprise/features/secrets-manager/aws-workload-identity) + - [Configure GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) + - [Configure Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) +- Then: [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage) diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/usage.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/usage.mdx new file mode 100644 index 000000000..4dd72dba3 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/usage.mdx @@ -0,0 +1,137 @@ +--- +title: Using the Secrets Manager +description: Manage permissions and reference managed secrets from environment variables in CrewAI Platform +sidebarTitle: Usage & Permissions +icon: "list-check" +--- + +## Overview + +This guide is provider-agnostic. It assumes you (or another admin) have already configured at least one Secret Provider Credential. Pick your setup guide based on the path you want: + +- Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp) +- Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity) + +Use this guide to: + +- Grant the right permissions to org members. +- Reference secrets from environment variables on your automations. +- Verify everything resolves correctly at runtime. + +## Permissions (RBAC) + +Three CrewAI Platform features are relevant when working with Secrets Manager: + +- `secret_providers` — controls access to the **Secret Provider Credentials** page. +- `workload_identity_configs` — controls access to the **Workload Identity** page (only relevant if you use the WI path). +- `environment_variables` — controls who can create or edit environment variables. + +Each feature has two action levels: `read` and `manage`. Granting `manage` automatically implies `read`. + +### What to Grant + +| Goal | `secret_providers` | `workload_identity_configs` | `environment_variables` | +|---|---|---|---| +| Use existing static credentials in environment variables (no provider edits) | `read` | — | `manage` | +| Create, edit, or delete static credentials | `manage` | — | `manage` | +| Use existing Workload Identity-backed credentials in env vars | `read` | — | `manage` | +| Create, edit, or delete Workload Identity configs (and credentials referencing them) | `manage` | `manage` | `manage` | + + +**Owners** automatically have full access to every feature. The default **Member** role intentionally excludes `secret_providers` and `workload_identity_configs` — admins must explicitly opt members in via a custom role. + + +### How to Assign + +1. In CrewAI Platform, navigate to **Settings** → **Roles**. From this page you can create new roles, edit each role's permissions, and assign roles to existing members of the organization. + + {/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */} + {/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */} + +2. Click **Create Role** to make a new role, or open an existing role to edit its permissions. + +3. In the role's permission editor, toggle the relevant features per the table above: + + - `secret_providers`: choose **read** if this role only needs to use existing credentials, or **manage** if it should also be able to create, edit, and delete credentials. + - `environment_variables`: choose **manage** so the role can create environment variables that reference secrets. + + {/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */} + {/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */} + +4. Save the role. + +5. Assign the role to the relevant members from the same Roles page (or the org Members list). + + {/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */} + +## Referencing Secrets in Environment Variables + +Once a provider credential exists and your role has the right permissions, you can reference managed secrets from any environment variable. + +In CrewAI Platform, navigate to **Environment Variables** and click **Add Environment Variables**. + +{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */} + +Fill the form: + +- **Key** — the name of the environment variable. Must start with a letter or underscore and contain only letters, numbers, and underscores. Conventionally uppercase, e.g. `OPENAI_API_KEY`. + +- **Value Source** — choose where the value comes from: + - **Direct Value** — a plaintext value you type in. Use this when you do not want to involve a provider. + - **Use AWS default** (or the equivalent for your provider) — uses the credential currently marked as the default for that provider type. + - **A specific named credential** — select the credential by name. Use this if you have multiple credentials for the same provider (for example, `aws-prod` and `aws-staging`) and want to pick one explicitly. + + {/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */} + +- **Secret Name** — the name of the secret in your provider. Once a credential is selected, this field offers autocomplete: start typing and CrewAI Platform queries your provider for matching secret names. + + Use the `secret-name#json_key` syntax to extract a single field from a structured (JSON) secret. For example, given a secret `database-credentials` with value `{"username": "...", "password": "..."}`, reference `database-credentials#password` to inject just the password. + + {/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */} + + + **Azure Key Vault note:** Azure secret names cannot contain underscores. CrewAI Platform automatically converts underscores in your `Secret Name` field to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`). + + +Click **Create** to save the variable. + +{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */} + + +When editing an existing environment variable, leaving the **Value** field blank preserves the current value. This is intentional — it lets you change other fields (like the secret name or credential) without re-entering the value. + + +## Verifying It Works + +To verify end-to-end: + +1. Reference the environment variable on an automation, crew, or deployment exactly as you would any other environment variable. +2. Deploy the automation. +3. Trigger a run and confirm it completes successfully. + +### Rotation behavior depends on the credential path + +| Credential path | When the secret is read | What rotation requires | +|---|---|---| +| **Static credentials** (AWS access keys, GCP service account JSON) | At **deploy time** — value is baked into the deployment image | Re-deploy the automation after rotating the secret | +| **Workload Identity** (OIDC federation, AWS or GCP) | At **every automation kickoff** — value is fetched fresh from your cloud | Nothing — the next kickoff after rotation sees the new value | + + +**If you need rotation-aware secrets** (no re-deploy on rotation), use the Workload Identity path: [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity). The trade-off is more setup effort up front (registering CrewAI Platform as an OIDC provider in your cloud) but simpler operations long-term. + + +If the deploy or run fails with an error related to your secret, check the most common causes: + +| Symptom | Likely cause | +|---|---| +| `no credential found` | The environment variable references a provider but no specific credential was selected, and there is no default credential set for that provider type. Either select a credential explicitly on the variable, or mark a credential as default on the **Secret Provider Credentials** page. | +| `secret not found` | Typo in the **Secret Name**, or the secret does not exist in the provider account/region the credential points to. Re-check both. | +| Automation runs with the old value after rotating (static-credentials path) | The previous value is baked into the deployment's container image. Re-deploy the automation to pick up the rotated value. To avoid this entirely, switch the credential to the Workload Identity path. | +| Automation runs with the old value after rotating (Workload Identity path) | Confirm the env var references a WI-backed credential (not a static-keys one). With WI, the next kickoff after rotation should see the new value. If it doesn't, check that the secret was actually updated in your cloud (e.g., `aws secretsmanager get-secret-value`). | +| `JSON key not found` | When using `secret-name#json_key`, the underlying secret must be a valid JSON object containing that key. Verify by reading the secret directly in your provider. | + +## Next Steps + +- [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview) +- Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp) +- Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity) diff --git a/docs/v1.15.1/en/enterprise/features/secrets-manager/verify-rotation.mdx b/docs/v1.15.1/en/enterprise/features/secrets-manager/verify-rotation.mdx new file mode 100644 index 000000000..67bea00fb --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/secrets-manager/verify-rotation.mdx @@ -0,0 +1,261 @@ +--- +title: Verify Rotation +description: A self-contained example crew that proves secret rotation propagates to running deployments without re-deploy. +sidebarTitle: Verify Rotation +icon: "arrows-rotate" +--- + +## Overview + +This guide shows you how to verify that **a secret rotated in your cloud provider is picked up on the very next automation kickoff** — no re-deploy, no worker restart. It's only relevant when you've configured a Workload Identity-backed credential ([AWS](/en/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/en/enterprise/features/secrets-manager/azure-workload-identity)). Static-credential deployments require a re-deploy after rotation; nothing to verify here. + +The recipe below uses a tiny, self-contained crew with one tool, one agent, one task. The crew prompt never references the secret value — instead, a tool reads it from `os.environ` and reports a SHA-256 fingerprint of what it sees. Rotate the secret in your cloud provider, kickoff again, and the fingerprint changes. + + +Why a fingerprint, not the raw value? Putting raw secrets into LLM output and trace logs is a leak vector. The fingerprint is enough to confirm "the value changed" without writing the actual value anywhere observable. + + +## Prerequisites + +Before running this verification: + +- A WI-backed Secret Provider Credential is configured ([AWS](/en/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/en/enterprise/features/secrets-manager/azure-workload-identity)). +- An environment variable on your deployment with `Secret = true`, key `API_KEY` (or whatever name you prefer — adjust the tool below to match), referencing a secret in your cloud provider. +- A way to update the secret value in your cloud provider (CLI access or the cloud console). +- A way to kickoff the deployment via HTTP (curl, Postman, or the **Run** tab in CrewAI Platform). + +## Step 1 — Scaffold a Verification Crew + +Create a classic crew project because this example wires a Python tool through `crew.py`: + +```bash +crewai create crew rotation_verifier --classic --skip_provider +cd rotation_verifier +``` + +## Step 2 — Add the Credential Echo Tool + +Replace `src/rotation_verifier/tools/custom_tool.py` with a tool that reads the secret-backed env var and returns a fingerprint: + +```python src/rotation_verifier/tools/credential_echo_tool.py +"""Tool that verifies a runtime-injected secret without leaking the value. + +Reads the secret-backed env var (populated by the workload-identity +secrets manager at kickoff time) and returns a stable fingerprint. Never +echo raw credential values into LLM output or logs in production code — +the fingerprint alone is sufficient to confirm rotation worked. +""" + +from __future__ import annotations + +import hashlib +import os + +from crewai.tools import BaseTool + + +# Match the deployment environment variable's `key` field. +ENV_VAR_NAME = "API_KEY" + + +class CredentialEchoTool(BaseTool): + name: str = "credential_echo" + description: str = ( + "Read the API credential from the worker's environment and return a " + "fingerprint summary. Use this exactly once when asked to verify the " + "current credential. Takes no arguments." + ) + + def _run(self) -> str: + value = os.environ.get(ENV_VAR_NAME) + if not value: + return ( + f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-" + "identity secret fetch did not run, or the deployment is " + "missing the secret-backed env var." + ) + fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12] + return f"Authenticated. credential.fingerprint=sha256:{fingerprint}" +``` + +## Step 3 — Replace the Default Agent and Task Configs + +The crew has one agent and one task — both with descriptions that **never** mention the secret value, so task keys stay stable across rotations. + +```yaml src/rotation_verifier/config/agents.yaml +credential_checker: + role: > + Credential Verifier + goal: > + Confirm that the workload-identity-backed secret reached this worker + process and report a fingerprint of the current value. + backstory: > + You are a no-nonsense reliability engineer responsible for verifying + that secrets fetched at runtime via workload identity are present + and fresh. You always use the credential_echo tool exactly once and + report the result verbatim — you never make up values. +``` + +```yaml src/rotation_verifier/config/tasks.yaml +verify_credential_task: + description: > + Use the credential_echo tool to read the runtime-injected credential + and produce a one-line confirmation. The current year is {current_year} + (use it only in the timestamp; do not transform the credential output). + expected_output: > + A single line in the form: + "[{current_year}] " + agent: credential_checker +``` + +## Step 4 — Wire the Crew Class + +```python src/rotation_verifier/crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent + +from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool + + +@CrewBase +class RotationVerifierCrew(): + """Single-task crew that verifies a workload-identity-backed secret + was successfully fetched at runtime. + + Rotate the underlying secret in the cloud provider, kickoff again, and + the credential fingerprint in the agent's report changes — without any + re-deploy, worker restart, or input change. The crew prompt itself + never references the secret value. + """ + + agents: list[BaseAgent] + tasks: list[Task] + + @agent + def credential_checker(self) -> Agent: + return Agent( + config=self.agents_config["credential_checker"], + tools=[CredentialEchoTool()], + verbose=True, + ) + + @task + def verify_credential_task(self) -> Task: + return Task(config=self.tasks_config["verify_credential_task"]) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +## Step 5 — Deploy and Configure the Secret Env Var + +Deploy this crew to CrewAI Platform exactly as you would any other crew. Then on the deployment's **Environment Variables** page: + +- **Key:** `API_KEY` (must match `ENV_VAR_NAME` in the tool) +- **Value Source:** the WI-backed credential you set up in [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity) +- **Secret Name:** the name of the secret in your cloud provider's Secret Manager + +{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */} + +## Step 6 — Run the First Kickoff + +Replace `` and `` with values from your deployment's **Run** tab. + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +When the kickoff completes (a few seconds), check the agent's output. You'll see: + +``` +[2026] Authenticated. credential.fingerprint=sha256:004421b993c9 +``` + +Note the fingerprint. That hash is uniquely tied to whatever secret value is currently in your cloud provider. + +## Step 7 — Rotate the Secret in Your Cloud Provider + + + + ```bash + aws secretsmanager update-secret \ + --region \ + --secret-id \ + --secret-string "rotated value" + ``` + + + + Add a new version (Secret Manager always reads `latest`): + + ```bash + echo -n "rotated value" | gcloud secrets versions add \ + --data-file=- \ + --project= + ``` + + + + ```bash + az keyvault secret set \ + --vault-name \ + --name \ + --value "rotated value" + ``` + + + +## Step 8 — Run a Second Kickoff and Compare + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +The agent's output now shows a **different fingerprint**: + +``` +[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72 +``` + +This proves the rotation was picked up by the running deployment with no re-deploy, worker restart, or other operator action. + +## What This Verifies — and What It Doesn't + +**Verifies:** +- WI OIDC token minting from CrewAI Platform works. +- Cloud-side trust (IAM OIDC provider for AWS, Workload Identity Pool for GCP, Federated Identity Credential for Azure) accepts the token. +- The cloud-side identity (IAM Role / GCP service account / Entra App Registration) has access to read the secret. +- The secret value reaches `os.environ` of the worker process at kickoff time. +- Subsequent rotations propagate to the next kickoff. + +**Does not verify:** +- That your real production crews handle the rotation gracefully — e.g., long-running tasks that read the env var once at startup will keep using the old value until the task ends. Plan accordingly: read secrets at the point of use, not at module import. + +## Why Not Reference the Secret Directly in the Prompt? + +A simpler-looking demo would put the secret value directly into a task description (e.g., "Research about `{api_key}`") and inspect the prompt. **Don't do that.** Two reasons: + +1. **It leaks the secret into LLM call traces and provider-side logs.** Anyone with trace access can read it. +2. **It changes the task's description at every kickoff.** CrewAI Platform identifies tasks by an MD5 hash of the description; a rotating value means the hash changes per kickoff, which breaks the deploy-time → runtime task mapping. Symptom: the task records show as `pending_run` indefinitely, or only some of a multi-task crew's tasks register. + +The tool-based pattern in this guide sidesteps both issues: the prompt is static, the tool reads the env var at runtime, and only a fingerprint of the value reaches the LLM. + +## Next Steps + +- [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview) +- Once verified, drop the verification crew. Real crews should follow the same pattern: secrets accessed via `os.environ` inside a tool, never substituted into prompts. diff --git a/docs/v1.15.1/en/enterprise/features/sso.mdx b/docs/v1.15.1/en/enterprise/features/sso.mdx new file mode 100644 index 000000000..3384d3d79 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/sso.mdx @@ -0,0 +1,550 @@ +--- +title: Single Sign-On (SSO) +icon: "key" +description: Configure enterprise SSO authentication for CrewAI Platform — SaaS and Factory +--- + +## Overview + +CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP)** and **Factory (self-hosted)** deployments. SSO enables your team to authenticate using your organization's existing identity provider, enforcing centralized access control, MFA policies, and user lifecycle management. + +### Supported Providers + +| Provider | SaaS | Factory | Protocol | CLI Support | +|---|---|---|---|---| +| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC | ✅ | +| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 | ✅ | +| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ | +| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ | +| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC | ✅ | + +### Key Capabilities + +- **SAML 2.0 and OAuth 2.0 / OIDC** protocol support +- **Device Authorization Grant** flow for CLI authentication +- **Role-Based Access Control (RBAC)** with custom roles and per-resource permissions +- **MFA enforcement** delegated to your identity provider +- **User provisioning** through IdP assignment (users/groups) + +--- + +## SaaS SSO + +### Default Authentication + +CrewAI's managed SaaS platform (AMP) uses **WorkOS** as the default authentication provider. When you sign up at [app.crewai.com](https://app.crewai.com), authentication is handled through `login.crewai.com` — no additional SSO configuration is required. + +### Enterprise Custom SSO + +Enterprise SaaS customers can configure SSO with their own identity provider (Entra ID, Okta, Auth0). Contact your CrewAI account team to enable custom SSO for your organization. Once configured: + +1. Your team members authenticate through your organization's IdP +2. Access control and MFA policies are enforced by your IdP +3. The CrewAI CLI automatically detects your SSO configuration via `crewai enterprise configure` + +### CLI Defaults (SaaS) + +| Setting | Default Value | +|---|---| +| `enterprise_base_url` | `https://app.crewai.com` | +| `oauth2_provider` | `workos` | +| `oauth2_domain` | `login.crewai.com` | + +--- + +## Factory SSO Setup + +Factory (self-hosted) deployments require you to configure SSO by setting environment variables in your Helm `values.yaml` and registering an application in your identity provider. + +### Microsoft Entra ID (Azure AD) + + + + 1. Go to [portal.azure.com](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations** → **New registration** + 2. Configure: + - **Name:** `CrewAI` (or your preferred name) + - **Supported account types:** Accounts in this organizational directory only + - **Redirect URI:** Select **Web**, enter `https:///auth/entra_id/callback` + 3. Click **Register** + + + + From the app overview page, copy: + - **Application (client) ID** → `ENTRA_ID_CLIENT_ID` + - **Directory (tenant) ID** → `ENTRA_ID_TENANT_ID` + + + + 1. Navigate to **Certificates & Secrets** → **New client secret** + 2. Add a description and select expiration period + 3. Copy the secret value immediately (it won't be shown again) → `ENTRA_ID_CLIENT_SECRET` + + + + 1. Go to **Enterprise applications** → select your app + 2. Under **Security** → **Permissions**, click **Grant admin consent** + 3. Ensure **Microsoft Graph → User.Read** is granted + + + + Under **App registrations** → your app → **App roles**, create: + + | Display Name | Value | Allowed Member Types | + |---|---|---| + | Member | `member` | Users/Groups | + | Factory Admin | `factory-admin` | Users/Groups | + + + The `member` role grants login access. The `factory-admin` role grants admin panel access. Roles are included in the JWT automatically. + + + + + 1. Under **Properties**, set **Assignment required?** to **Yes** + 2. Under **Users and groups**, assign users/groups with the appropriate role + + + + ```yaml + envVars: + AUTH_PROVIDER: "entra_id" + + secrets: + ENTRA_ID_CLIENT_ID: "" + ENTRA_ID_CLIENT_SECRET: "" + ENTRA_ID_TENANT_ID: "" + ``` + + + + To allow `crewai login` via Device Authorization Grant: + + 1. Under **Authentication** → **Advanced settings**, enable **Allow public client flows** + 2. Under **Expose an API**, add an Application ID URI (e.g., `api://crewai-cli`) + 3. Add a scope (e.g., `read`) with **Admins and users** consent + 4. Under **Manifest**, set `accessTokenAcceptedVersion` to `2` + 5. Add environment variables: + + ```yaml + secrets: + ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID: "" + ENTRA_ID_CUSTOM_OPENID_SCOPE: "" + ``` + + + +--- + +### Okta + + + + 1. Open Okta Admin Console → **Applications** → **Create App Integration** + 2. Select **OIDC - OpenID Connect** → **Web Application** → **Next** + 3. Configure: + - **App integration name:** `CrewAI SSO` + - **Sign-in redirect URI:** `https:///auth/okta/callback` + - **Sign-out redirect URI:** `https://` + - **Assignments:** Choose who can access (everyone or specific groups) + 4. Click **Save** + + + + From the app details page: + - **Client ID** → `OKTA_CLIENT_ID` + - **Client Secret** → `OKTA_CLIENT_SECRET` + - **Okta URL** (top-right corner, under your username) → `OKTA_SITE` + + + + 1. Navigate to **Security** → **API** + 2. Select your authorization server (default: `default`) + 3. Under **Access Policies**, add a policy and rule: + - In the rule, under **Scopes requested**, select **The following scopes** → **OIDC default scopes** + 4. Note the **Name** and **Audience** of the authorization server + + + The authorization server name and audience must match `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` exactly. Mismatches cause `401 Unauthorized` or `Invalid token: Signature verification failed` errors. + + + + + ```yaml + envVars: + AUTH_PROVIDER: "okta" + + secrets: + OKTA_CLIENT_ID: "" + OKTA_CLIENT_SECRET: "" + OKTA_SITE: "https://your-domain.okta.com" + OKTA_AUTHORIZATION_SERVER: "default" + OKTA_AUDIENCE: "api://default" + ``` + + + + 1. Create a **new** app integration: **OIDC** → **Native Application** + 2. Enable **Device Authorization** and **Refresh Token** grant types + 3. Allow everyone in your organization to access + 4. Add environment variable: + + ```yaml + secrets: + OKTA_DEVICE_AUTHORIZATION_CLIENT_ID: "" + ``` + + + Device Authorization requires a **Native Application** — it cannot use the Web Application created for browser-based SSO. + + + + +--- + +### Keycloak + + + + 1. Open Keycloak Admin Console → navigate to your realm + 2. **Clients** → **Create client**: + - **Client type:** OpenID Connect + - **Client ID:** `crewai-factory` (suggested) + 3. Capability config: + - **Client authentication:** On + - **Standard flow:** Checked + 4. Login settings: + - **Root URL:** `https://` + - **Valid redirect URIs:** `https:///auth/keycloak/callback` + - **Valid post logout redirect URIs:** `https://` + 5. Click **Save** + + + + - **Client ID** → `KEYCLOAK_CLIENT_ID` + - Under **Credentials** tab: **Client secret** → `KEYCLOAK_CLIENT_SECRET` + - **Realm name** → `KEYCLOAK_REALM` + - **Keycloak server URL** → `KEYCLOAK_SITE` + + + + ```yaml + envVars: + AUTH_PROVIDER: "keycloak" + + secrets: + KEYCLOAK_CLIENT_ID: "" + KEYCLOAK_CLIENT_SECRET: "" + KEYCLOAK_SITE: "https://keycloak.yourdomain.com" + KEYCLOAK_REALM: "" + KEYCLOAK_AUDIENCE: "account" + # Only set if using a custom base path (pre-v17 migrations): + # KEYCLOAK_BASE_URL: "/auth" + ``` + + + Keycloak includes `account` as the default audience in access tokens. For most installations, `KEYCLOAK_AUDIENCE=account` works without additional configuration. See [Keycloak audience documentation](https://www.keycloak.org/docs/latest/authorization_services/index.html) if you need a custom audience. + + + + + 1. Create a **second** client: + - **Client type:** OpenID Connect + - **Client ID:** `crewai-factory-cli` (suggested) + - **Client authentication:** Off (Device Authorization requires a public client) + - **Authentication flow:** Check **only** OAuth 2.0 Device Authorization Grant + 2. Add environment variable: + + ```yaml + secrets: + KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID: "" + ``` + + + +--- + +### WorkOS + + + + 1. Create an application in the [WorkOS Dashboard](https://dashboard.workos.com) + 2. Configure the redirect URI: `https:///auth/workos/callback` + 3. Note the **Client ID** and **AuthKit domain** + 4. Set up organizations in the WorkOS dashboard + + + + ```yaml + envVars: + AUTH_PROVIDER: "workos" + + secrets: + WORKOS_CLIENT_ID: "" + WORKOS_AUTHKIT_DOMAIN: "" + ``` + + + +--- + +### Auth0 + + + + 1. In the [Auth0 Dashboard](https://manage.auth0.com), create a new **Regular Web Application** + 2. Configure: + - **Allowed Callback URLs:** `https:///auth/auth0/callback` + - **Allowed Logout URLs:** `https://` + 3. Note the **Domain**, **Client ID**, and **Client Secret** + + + + ```yaml + envVars: + AUTH_PROVIDER: "auth0" + + secrets: + AUTH0_CLIENT_ID: "" + AUTH0_CLIENT_SECRET: "" + AUTH0_DOMAIN: "" + ``` + + + + 1. Create a **Native** application in Auth0 for Device Authorization + 2. Enable the **Device Authorization** grant type under application settings + 3. Configure the CLI with the appropriate audience and client ID + + + +--- + +## CLI Authentication + +The CrewAI CLI supports SSO authentication via the **Device Authorization Grant** flow. This allows developers to authenticate from their terminal without exposing credentials. + +### Quick Setup + +For Factory installations, the CLI can auto-configure all OAuth2 settings: + +```bash +crewai enterprise configure https://your-factory-url.app +``` + +This command fetches the SSO configuration from your Factory instance and sets all required CLI parameters automatically. + +Then authenticate: + +```bash +crewai login +``` + + + Requires CrewAI CLI version **1.6.0** or higher for Entra ID, **0.159.0** or higher for Okta, and **1.9.0** or higher for Keycloak. + + +### Manual CLI Configuration + +If you need to configure the CLI manually, use `crewai config set`: + +```bash +# Set the provider +crewai config set oauth2_provider okta + +# Set provider-specific values +crewai config set oauth2_domain your-domain.okta.com +crewai config set oauth2_client_id your-client-id +crewai config set oauth2_audience api://default + +# Set the enterprise base URL +crewai config set enterprise_base_url https://your-factory-url.app +``` + +### CLI Configuration Reference + +| Setting | Description | Example | +|---|---|---| +| `enterprise_base_url` | Your CrewAI instance URL | `https://crewai.yourcompany.com` | +| `oauth2_provider` | Provider name | `workos`, `okta`, `auth0`, `entra_id`, `keycloak` | +| `oauth2_domain` | Provider domain | `your-domain.okta.com` | +| `oauth2_client_id` | OAuth2 client ID | `0oaqnwji7pGW7VT6T697` | +| `oauth2_audience` | API audience identifier | `api://default` | + +View current configuration: + +```bash +crewai config list +``` + +### How Device Authorization Works + +1. Run `crewai login` — the CLI requests a device code from your IdP +2. A verification URL and code are displayed in your terminal +3. Your browser opens to the verification URL +4. Enter the code and authenticate with your IdP credentials +5. The CLI receives an access token and stores it locally + +--- + +## Role-Based Access Control (RBAC) + +CrewAI Platform provides granular RBAC that integrates with your SSO provider. + +### Permission Model + +| Permission | Description | +|---|---| +| **Read** | View resources (dashboards, automations, logs) | +| **Write** | Create and modify resources | +| **Manage** | Full control including deletion and configuration | + +### Resources + +Permissions can be scoped to individual resources: + +- **Usage Dashboard** — Platform usage metrics and analytics +- **Automations Dashboard** — Crew and flow management +- **Environment Variables** — Secret and configuration management +- **Individual Automations** — Per-automation access control + +### Roles + +- **Predefined roles** come out of the box with standard permission sets +- **Custom roles** can be created with any combination of permissions +- **Per-resource assignment** — limit specific automations to individual users or roles + +### Factory Admin Access + +For Factory deployments using Entra ID, admin access is controlled via App Roles: + +- Assign the `factory-admin` role to users who need admin panel access +- Assign the `member` role for standard platform access +- Roles are communicated via JWT claims — no additional configuration needed after IdP setup + +--- + +## Troubleshooting + +### Invalid Redirect URI + +**Symptom:** Authentication fails with a redirect URI mismatch error. + +**Fix:** Ensure the redirect URI in your IdP exactly matches the expected callback URL: + +| Provider | Callback URL | +|---|---| +| Entra ID | `https:///auth/entra_id/callback` | +| Okta | `https:///auth/okta/callback` | +| Keycloak | `https:///auth/keycloak/callback` | +| WorkOS | `https:///auth/workos/callback` | +| Auth0 | `https:///auth/auth0/callback` | + +### CLI Login Fails (Device Authorization) + +**Symptom:** `crewai login` returns an error or times out. + +**Fix:** +- Verify that Device Authorization Grant is enabled in your IdP +- For Okta: ensure you have a **Native Application** (not Web) with Device Authorization grant +- For Entra ID: ensure **Allow public client flows** is enabled +- For Keycloak: ensure the CLI client has **Client authentication: Off** and only Device Authorization Grant enabled +- Check that `*_DEVICE_AUTHORIZATION_CLIENT_ID` environment variable is set on the server + +### Token Validation Errors + +**Symptom:** `Invalid token: Signature verification failed` or `401 Unauthorized` after login. + +**Fix:** +- **Okta:** Verify `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` match the authorization server's Name and Audience exactly +- **Entra ID:** Ensure `accessTokenAcceptedVersion` is set to `2` in the app manifest +- **Keycloak:** Verify `KEYCLOAK_AUDIENCE` matches the audience in your access tokens (default: `account`) + +### Admin Consent Not Granted (Entra ID) + +**Symptom:** Users can't log in, see "needs admin approval" message. + +**Fix:** Go to **Enterprise applications** → your app → **Permissions** → **Grant admin consent**. Ensure `User.Read` is granted for Microsoft Graph. + +### 403 Forbidden After Login + +**Symptom:** User authenticates successfully but gets 403 errors. + +**Fix:** +- Check that the user is assigned to the application in your IdP +- For Entra ID with **Assignment required = Yes**: ensure the user has a role assignment (Member or Factory Admin) +- For Okta: verify the user or their group is assigned under the app's **Assignments** tab + +### CLI Can't Reach Factory Instance + +**Symptom:** `crewai enterprise configure` fails to connect. + +**Fix:** +- Verify the Factory URL is reachable from your machine +- Check that `enterprise_base_url` is set correctly: `crewai config list` +- Ensure TLS certificates are valid and trusted + +--- + +## Environment Variables Reference + +### Common + +| Variable | Description | +|---|---| +| `AUTH_PROVIDER` | Authentication provider: `entra_id`, `okta`, `workos`, `auth0`, `keycloak`, `local` | + +### Microsoft Entra ID + +| Variable | Required | Description | +|---|---|---| +| `ENTRA_ID_CLIENT_ID` | ✅ | Application (client) ID from Azure | +| `ENTRA_ID_CLIENT_SECRET` | ✅ | Client secret from Azure | +| `ENTRA_ID_TENANT_ID` | ✅ | Directory (tenant) ID from Azure | +| `ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Client ID for Device Authorization Grant | +| `ENTRA_ID_CUSTOM_OPENID_SCOPE` | CLI only | Custom scope from "Expose an API" (e.g., `api://crewai-cli/read`) | + +### Okta + +| Variable | Required | Description | +|---|---|---| +| `OKTA_CLIENT_ID` | ✅ | Okta application client ID | +| `OKTA_CLIENT_SECRET` | ✅ | Okta client secret | +| `OKTA_SITE` | ✅ | Okta organization URL (e.g., `https://your-domain.okta.com`) | +| `OKTA_AUTHORIZATION_SERVER` | ✅ | Authorization server name (e.g., `default`) | +| `OKTA_AUDIENCE` | ✅ | Authorization server audience (e.g., `api://default`) | +| `OKTA_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Native app client ID for Device Authorization | + +### WorkOS + +| Variable | Required | Description | +|---|---|---| +| `WORKOS_CLIENT_ID` | ✅ | WorkOS application client ID | +| `WORKOS_AUTHKIT_DOMAIN` | ✅ | AuthKit domain (e.g., `your-domain.authkit.com`) | + +### Auth0 + +| Variable | Required | Description | +|---|---|---| +| `AUTH0_CLIENT_ID` | ✅ | Auth0 application client ID | +| `AUTH0_CLIENT_SECRET` | ✅ | Auth0 client secret | +| `AUTH0_DOMAIN` | ✅ | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) | + +### Keycloak + +| Variable | Required | Description | +|---|---|---| +| `KEYCLOAK_CLIENT_ID` | ✅ | Keycloak client ID | +| `KEYCLOAK_CLIENT_SECRET` | ✅ | Keycloak client secret | +| `KEYCLOAK_SITE` | ✅ | Keycloak server URL | +| `KEYCLOAK_REALM` | ✅ | Keycloak realm name | +| `KEYCLOAK_AUDIENCE` | ✅ | Token audience (default: `account`) | +| `KEYCLOAK_BASE_URL` | Optional | Base URL path (e.g., `/auth` for pre-v17 migrations) | +| `KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Public client ID for Device Authorization | + +--- + +## Next Steps + +- [Installation Guide](/installation) — Get started with CrewAI +- [Quickstart](/quickstart) — Build your first crew +- [RBAC Setup](/enterprise/features/rbac) — Detailed role and permission management diff --git a/docs/v1.15.1/en/enterprise/features/tools-and-integrations.mdx b/docs/v1.15.1/en/enterprise/features/tools-and-integrations.mdx new file mode 100644 index 000000000..682f231c5 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/tools-and-integrations.mdx @@ -0,0 +1,262 @@ +--- +title: Tools & Integrations +description: "Connect external apps and manage internal tools your agents can use." +icon: "wrench" +mode: "wide" +--- + +## Overview + +Tools & Integrations is the central hub for connecting third‑party apps and managing internal tools that your agents can use at runtime. + + + ![Tools & Integrations Overview](/images/enterprise/crew_connectors.png) + + +## Explore + + + + +## Agent Apps (Integrations) + +Connect enterprise‑grade applications (e.g., Gmail, Google Drive, HubSpot, Slack) via OAuth to enable agent actions. + +{" "} + + + Click Connect on an app and complete OAuth. + + + Optionally adjust scopes, triggers, and action availability. + + + Connected services become available as tools for your agents. + + + +{" "} +![Integrations Grid](/images/enterprise/agent-apps.png) + +### Connect your Account + +1. Go to Integrations +2. Click Connect on the desired service +3. Complete the OAuth flow and grant scopes +4. Copy your Enterprise Token from Integration Settings + +{" "} + + ![Enterprise Token](/images/enterprise/enterprise_action_auth_token.png) + + +### Install Integration Tools + +To use the integrations locally, you need to install the latest `crewai-tools` package. + +```bash +uv add crewai-tools +``` + +### Environment Variable Setup + +{" "} + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +### Usage Example + +{" "} + + Use the new streamlined approach to integrate enterprise apps. Simply specify + the app and its actions directly in the Agent configuration. + + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +email_agent = Agent( + role="Email Manager", + goal="Manage and organize email communications", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail', 'gmail/send_email'] # Using canonical name 'gmail' +) + +# Task to send an email +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" +) + +# Run the task +crew = Crew( + agents=[email_agent], + tasks=[email_task] +) + +# Run the crew +crew.kickoff() +``` + +### Filtering Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Gmail actions only +gmail_agent = Agent( + role="Gmail Manager", + goal="Manage gmail communications and notifications", + backstory="An AI assistant that helps coordinate gmail communications.", + apps=['gmail/fetch_emails'] # Using canonical name with specific action +) + +notification_task = Task( + description="Find the email from john@example.com", + agent=gmail_agent, + expected_output="Email found from john@example.com" +) + +crew = Crew( + agents=[gmail_agent], + tasks=[notification_task] +) +``` + +On a deployed crew, you can specify which actions are available for each integration from the service settings page. + +{" "} + + ![Filter Actions](/images/enterprise/filtering_enterprise_action_tools.png) + + +### Scoped Deployments (multi‑user orgs) + +You can scope each integration to a specific user. For example, a crew that connects to Google can use a specific user’s Gmail account. + +{" "} +Useful when different teams/users must keep data access separated. + +Use the `user_bearer_token` to scope authentication to the requesting user. If the user isn’t logged in, the crew won’t use connected integrations. Otherwise it falls back to the default bearer token configured for the deployment. + +{" "} +![User Bearer Token](/images/enterprise/user_bearer_token.png) + +{" "} +
+### Catalog + +#### Communication & Collaboration + +- Gmail — Manage emails and drafts +- Slack — Workspace notifications and alerts +- Microsoft — Office 365 and Teams integration + +#### Project Management + +- Jira — Issue tracking and project management +- ClickUp — Task and productivity management +- Asana — Team task and project coordination +- Notion — Page and database management +- Linear — Software project and bug tracking +- GitHub — Repository and issue management + +#### Customer Relationship Management + +- Salesforce — CRM account and opportunity management +- HubSpot — Sales pipeline and contact management +- Zendesk — Customer support ticket management + +#### Business & Finance + +- Stripe — Payment processing and customer management +- Shopify — E‑commerce store and product management + +#### Productivity & Storage + +- Google Sheets — Spreadsheet data synchronization +- Google Calendar — Event and schedule management +- Box — File storage and document management + +…and more to come! + + + + +## Internal Tools + +Create custom tools locally, publish them on CrewAI AMP Tool Repository and use them in your agents. + +{" "} + + Before running the commands below, make sure you log in to your CrewAI AMP + account by running this command: ```bash crewai login ``` + + +{" "} + + ![Internal Tool Detail](/images/enterprise/tools-integrations-internal.png) + + +{" "} + + + Create a new tool locally. ```bash crewai tool create your-tool ``` + + + Publish the tool to the CrewAI AMP Tool Repository. ```bash crewai tool + publish ``` + + + Install the tool from the CrewAI AMP Tool Repository. ```bash crewai tool + install your-tool ``` + + + +Manage: + +- Name and description +- Visibility (Private / Public) +- Required environment variables +- Version history and downloads +- Team and role access + +{" "} +![Internal Tool Detail](/images/enterprise/tool-configs.png) + + + + +## Related + + + + Create, publish, and version custom tools for your organization. + + + Automate workflows and integrate with external platforms and services. + + diff --git a/docs/v1.15.1/en/enterprise/features/traces.mdx b/docs/v1.15.1/en/enterprise/features/traces.mdx new file mode 100644 index 000000000..4f2d4cf50 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/traces.mdx @@ -0,0 +1,148 @@ +--- +title: Traces +description: "Using Traces to monitor your Crews" +icon: "timeline" +mode: "wide" +--- + +## Overview + +Traces provide comprehensive visibility into your crew executions, helping you monitor performance, debug issues, and optimize your AI agent workflows. + +## What are Traces? + +Traces in CrewAI AMP are detailed execution records that capture every aspect of your crew's operation, from initial inputs to final outputs. They record: + +- Agent thoughts and reasoning +- Task execution details +- Tool usage and outputs +- Token consumption metrics +- Execution times +- Cost estimates + +![Traces Overview](/images/enterprise/traces-overview.png) + +## Accessing Traces + + + + Once in your CrewAI AMP dashboard, click on the **Traces** to view all execution records. + + + + You'll see a list of all crew executions, sorted by date. Click on any execution to view its detailed trace. + + + +## Understanding the Trace Interface + +The trace interface is divided into several sections, each providing different insights into your crew's execution: + +### 1. Execution Summary + +The top section displays high-level metrics about the execution: + +- **Total Tokens**: Number of tokens consumed across all tasks +- **Prompt Tokens**: Tokens used in prompts to the LLM +- **Completion Tokens**: Tokens generated in LLM responses +- **Requests**: Number of API calls made +- **Execution Time**: Total duration of the crew run +- **Estimated Cost**: Approximate cost based on token usage + +![Execution Summary](/images/enterprise/trace-summary.png) + +### 2. Tasks & Agents + +This section shows all tasks and agents that were part of the crew execution: + +- Task name and agent assignment +- Agents and LLMs used for each task +- Status (completed/failed) +- Individual execution time of the task + +![Task List](/images/enterprise/trace-tasks.png) + +### 3. Final Output + +Displays the final result produced by the crew after all tasks are completed. + +![Final Output](/images/enterprise/final-output.png) + +### 4. Execution Timeline + +A visual representation of when each task started and ended, helping you identify bottlenecks or parallel execution patterns. + +![Execution Timeline](/images/enterprise/trace-timeline.png) + +### 5. Detailed Task View + +When you click on a specific task in the timeline or task list, you'll see: + +![Detailed Task View](/images/enterprise/trace-detailed-task.png) + +- **Task Key**: Unique identifier for the task +- **Task ID**: Technical identifier in the system +- **Status**: Current state (completed/running/failed) +- **Agent**: Which agent performed the task +- **LLM**: Language model used for this task +- **Start/End Time**: When the task began and completed +- **Execution Time**: Duration of this specific task +- **Task Description**: What the agent was instructed to do +- **Expected Output**: What output format was requested +- **Input**: Any input provided to this task from previous tasks +- **Output**: The actual result produced by the agent + +## Using Traces for Debugging + +Traces are invaluable for troubleshooting issues with your crews: + + + + When a crew execution doesn't produce the expected results, examine the trace to find where things went wrong. Look for: + + - Failed tasks + - Unexpected agent decisions + - Tool usage errors + - Misinterpreted instructions + + + ![Failure Points](/images/enterprise/failure.png) + + + + + + Use execution metrics to identify performance bottlenecks: + + - Tasks that took longer than expected + - Excessive token usage + - Redundant tool operations + - Unnecessary API calls + + + + + Analyze token usage and cost estimates to optimize your crew's efficiency: + + - Consider using smaller models for simpler tasks + - Refine prompts to be more concise + - Cache frequently accessed information + - Structure tasks to minimize redundant operations + + + + +## Performance and batching + +CrewAI batches trace uploads to reduce overhead on high-volume runs: + +- A TraceBatchManager buffers events and sends them in batches via the Plus API client +- Reduces network chatter and improves reliability on flaky connections +- Automatically enabled in the default trace listener; no configuration needed + +This yields more stable tracing under load while preserving detailed task/agent telemetry. + + + Contact our support team for assistance with trace analysis or any other + CrewAI AMP features. + diff --git a/docs/v1.15.1/en/enterprise/features/webhook-streaming.mdx b/docs/v1.15.1/en/enterprise/features/webhook-streaming.mdx new file mode 100644 index 000000000..4abb4d41d --- /dev/null +++ b/docs/v1.15.1/en/enterprise/features/webhook-streaming.mdx @@ -0,0 +1,173 @@ +--- +title: Webhook Streaming +description: "Using Webhook Streaming to stream events to your webhook" +icon: "webhook" +mode: "wide" +--- + +## Overview + +Enterprise Event Streaming lets you receive real-time webhook updates about your crews and flows deployed to +CrewAI AMP, such as model calls, tool usage, and flow steps. + +## Usage + +When using the Kickoff API, include a `webhooks` object to your request, for example: + +```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" + } + } +} +``` + +If `realtime` is set to `true`, each event is delivered individually and immediately, at the cost of crew/flow performance. + +## Webhook Format + +Each webhook sends a list of events: + +```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." } + ] + } + } + ] +} +``` + +The `data` object structure varies by event type. Refer to the [event list](https://github.com/crewAIInc/crewAI/tree/main/lib/crewai/src/crewai/events/types) on GitHub. + +As requests are sent over HTTP, the order of events can't be guaranteed. If you need ordering, use the `timestamp` field. + +## Supported Events + +CrewAI supports both system events and custom events in Enterprise Event Streaming. These events are sent to your configured webhook endpoint during crew and flow execution. + +### Flow Events: + +- `flow_created` +- `flow_started` +- `flow_finished` +- `flow_plot` +- `method_execution_started` +- `method_execution_finished` +- `method_execution_failed` + +### Agent Events: + +- `agent_execution_started` +- `agent_execution_completed` +- `agent_execution_error` +- `lite_agent_execution_started` +- `lite_agent_execution_completed` +- `lite_agent_execution_error` +- `agent_logs_started` +- `agent_logs_execution` +- `agent_evaluation_started` +- `agent_evaluation_completed` +- `agent_evaluation_failed` + +### Crew Events: + +- `crew_kickoff_started` +- `crew_kickoff_completed` +- `crew_kickoff_failed` +- `crew_train_started` +- `crew_train_completed` +- `crew_train_failed` +- `crew_test_started` +- `crew_test_completed` +- `crew_test_failed` +- `crew_test_result` + +### Task Events: + +- `task_started` +- `task_completed` +- `task_failed` +- `task_evaluation` + +### Tool Usage Events: + +- `tool_usage_started` +- `tool_usage_finished` +- `tool_usage_error` +- `tool_validate_input_error` +- `tool_selection_error` +- `tool_execution_error` + +### LLM Events: + +- `llm_call_started` +- `llm_call_completed` +- `llm_call_failed` +- `llm_stream_chunk` + +### LLM Guardrail Events: + +- `llm_guardrail_started` +- `llm_guardrail_completed` + +### Memory Events: + +- `memory_query_started` +- `memory_query_completed` +- `memory_query_failed` +- `memory_save_started` +- `memory_save_completed` +- `memory_save_failed` +- `memory_retrieval_started` +- `memory_retrieval_completed` + +### Knowledge Events: + +- `knowledge_search_query_started` +- `knowledge_search_query_completed` +- `knowledge_search_query_failed` +- `knowledge_query_started` +- `knowledge_query_completed` +- `knowledge_query_failed` + +### Reasoning Events: + +- `agent_reasoning_started` +- `agent_reasoning_completed` +- `agent_reasoning_failed` + +Event names match the internal event bus. See GitHub for the full list of events. + +You can emit your own custom events, and they will be delivered through the webhook stream alongside system events. + + + + Full list of events + + + Contact our support team for assistance with webhook integration or + troubleshooting. + + diff --git a/docs/v1.15.1/en/enterprise/guides/automation-triggers.mdx b/docs/v1.15.1/en/enterprise/guides/automation-triggers.mdx new file mode 100644 index 000000000..395d8f74d --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/automation-triggers.mdx @@ -0,0 +1,322 @@ +--- +title: "Triggers Overview" +description: "Understand how CrewAI AMP triggers work, how to manage them, and where to find integration-specific playbooks" +icon: "face-smile" +mode: "wide" +--- + +CrewAI AMP triggers connect your automations to real-time events across the tools your teams already use. Instead of polling systems or relying on manual kickoffs, triggers listen for changes—new emails, calendar updates, CRM status changes—and immediately launch the crew or flow you specify. + + + ![Automation Triggers Overview](/images/enterprise/crew_connectors.png) + + +### Integration Playbooks + +Deep-dive guides walk through setup and sample workflows for each integration: + + + + Enable crews when emails arrive or threads update. + + +{" "} + + + React to calendar events as they are created, updated, or cancelled. + + + +{" "} + + + Handle Drive file uploads, edits, and deletions. + + + +{" "} + + + Automate responses to new Outlook messages and calendar updates. + + + +{" "} + + + Audit file activity and sharing changes in OneDrive. + + + +{" "} + + + Kick off workflows when new Teams chats start. + + + +{" "} + + + Launch automations from HubSpot workflows and lifecycle events. + + + +{" "} + + + Connect Salesforce processes to CrewAI for CRM automation. + + + +{" "} + + + Start crews directly from Slack slash commands. + + + + + Bridge CrewAI with thousands of Zapier-supported apps. + + + +## Trigger Capabilities + +With triggers, you can: + +- **Respond to real-time events** - Automatically execute workflows when specific conditions are met +- **Integrate with external systems** - Connect with platforms like Gmail, Outlook, OneDrive, JIRA, Slack, Stripe and more +- **Scale your automation** - Handle high-volume events without manual intervention +- **Maintain context** - Access trigger data within your crews and flows + +## Managing Triggers + +### Viewing Available Triggers + +To access and manage your automation triggers: + +1. Navigate to your deployment in the CrewAI dashboard +2. Click on the **Triggers** tab to view all available trigger integrations + + + List of available automation triggers + + +This view shows all the trigger integrations available for your deployment, along with their current connection status. + +### Enabling and Disabling Triggers + +Each trigger can be easily enabled or disabled using the toggle switch: + + + Enable or disable triggers with toggle + + +- **Enabled (blue toggle)**: The trigger is active and will automatically execute your deployment when the specified events occur +- **Disabled (gray toggle)**: The trigger is inactive and will not respond to events + +Simply click the toggle to change the trigger state. Changes take effect immediately. + +### Monitoring Trigger Executions + +Track the performance and history of your triggered executions: + + + List of executions triggered by automation + + +## Building Trigger-Driven Automations + +Before building your automation, it's helpful to understand the structure of trigger payloads that your crews and flows will receive. + +### Trigger Setup Checklist + +Before wiring a trigger into production, make sure you: + +- Connect the integration under **Tools & Integrations** and complete any OAuth or API key steps +- Enable the trigger toggle on the deployment that should respond to events +- Provide any required environment variables (API tokens, tenant IDs, shared secrets) +- Create or update tasks that can parse the incoming payload within the first crew task or flow step +- Decide whether to pass trigger context automatically using `allow_crewai_trigger_context` +- Set up monitoring—webhook logs, CrewAI execution history, and optional external alerting + +### Testing Triggers Locally with CLI + +The CrewAI CLI provides powerful commands to help you develop and test trigger-driven automations without deploying to production. + +#### List Available Triggers + +View all available triggers for your connected integrations: + +```bash +crewai triggers list +``` + +This command displays all triggers available based on your connected integrations, showing: + +- Integration name and connection status +- Available trigger types +- Trigger names and descriptions + +#### Simulate Trigger Execution + +Test your crew with realistic trigger payloads before deployment: + +```bash +crewai triggers run +``` + +For example: + +```bash +crewai triggers run microsoft_onedrive/file_changed +``` + +This command: + +- Executes your crew locally +- Passes a complete, realistic trigger payload +- Simulates exactly how your crew will be called in production + + + **Important Development Notes:** + - Use `crewai triggers run ` to simulate trigger execution during development + - Using `crewai run` will NOT simulate trigger calls and won't pass the trigger payload + - After deployment, your crew will be executed with the actual trigger payload + - If your crew expects parameters that aren't in the trigger payload, execution may fail + + +### Triggers with Crew + +Your existing crew definitions work seamlessly with triggers, you just need to have a task to parse the received payload: + +```python +@CrewBase +class MyAutomatedCrew: + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + ) + + @task + def parse_trigger_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_trigger_payload'], + agent=self.researcher(), + ) + + @task + def analyze_trigger_content(self) -> Task: + return Task( + config=self.tasks_config['analyze_trigger_data'], + agent=self.researcher(), + ) +``` + +The crew will automatically receive and can access the trigger payload through the standard CrewAI context mechanisms. + + + Crew and Flow inputs can include `crewai_trigger_payload`. CrewAI + automatically injects this payload: - Tasks: appended to the first task's + description by default ("Trigger Payload: {crewai_trigger_payload}") - Control + via `allow_crewai_trigger_context`: set `True` to always inject, `False` to + never inject - Flows: any `@start()` method that accepts a + `crewai_trigger_payload` parameter will receive it + + +### Integration with Flows + +For flows, you have more control over how trigger data is handled: + +#### Accessing Trigger Payload + +All `@start()` methods in your flows will accept an additional parameter called `crewai_trigger_payload`: + +```python +from crewai.flow import Flow, start, listen + +class MyAutomatedFlow(Flow): + @start() + def handle_trigger(self, crewai_trigger_payload: dict = None): + """ + This start method can receive trigger data + """ + if crewai_trigger_payload: + # Process the trigger data + trigger_id = crewai_trigger_payload.get('id') + event_data = crewai_trigger_payload.get('payload', {}) + + # Store in flow state for use by other methods + self.state.trigger_id = trigger_id + self.state.trigger_type = event_data + + return event_data + + # Handle manual execution + return None + + @listen(handle_trigger) + def process_data(self, trigger_data): + """ + Process the data from the trigger + """ + # ... process the trigger +``` + +#### Triggering Crews from Flows + +When kicking off a crew within a flow that was triggered, pass the trigger payload as it: + +```python +@start() +def delegate_to_crew(self, crewai_trigger_payload: dict = None): + """ + Delegate processing to a specialized crew + """ + crew = MySpecializedCrew() + + # Pass the trigger payload to the crew + result = crew.crew().kickoff( + inputs={ + 'a_custom_parameter': "custom_value", + 'crewai_trigger_payload': crewai_trigger_payload + }, + ) + + return result +``` + +## Troubleshooting + +**Trigger not firing:** + +- Verify the trigger is enabled in your deployment's Triggers tab +- Check integration connection status under Tools & Integrations +- Ensure all required environment variables are properly configured + +**Execution failures:** + +- Check the execution logs for error details +- Use `crewai triggers run ` to test locally and see the exact payload structure +- Verify your crew can handle the `crewai_trigger_payload` parameter +- Ensure your crew doesn't expect parameters that aren't included in the trigger payload + +**Development issues:** + +- Always test with `crewai triggers run ` before deploying to see the complete payload +- Remember that `crewai run` does NOT simulate trigger calls—use `crewai triggers run` instead +- Use `crewai triggers list` to verify which triggers are available for your connected integrations +- After deployment, your crew will receive the actual trigger payload, so test thoroughly locally first + +Automation triggers transform your CrewAI deployments into responsive, event-driven systems that can seamlessly integrate with your existing business processes and tools. diff --git a/docs/v1.15.1/en/enterprise/guides/azure-openai-setup.mdx b/docs/v1.15.1/en/enterprise/guides/azure-openai-setup.mdx new file mode 100644 index 000000000..3d0be69d9 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/azure-openai-setup.mdx @@ -0,0 +1,54 @@ +--- +title: "Azure OpenAI Setup" +description: "Configure Azure OpenAI with Crew Studio for enterprise LLM connections" +icon: "microsoft" +mode: "wide" +--- + +This guide walks you through connecting Azure OpenAI with Crew Studio for seamless enterprise AI operations. + +## Setup Process + + + + 1. In Azure, go to [Azure AI Foundry](https://ai.azure.com/) > select your Azure OpenAI deployment. + 2. On the left menu, click `Deployments`. If you don't have one, create a deployment with your desired model. + 3. Once created, select your deployment and locate the `Target URI` and `Key` on the right side of the page. Keep this page open, as you'll need this information. + + Azure AI Foundry + + + + + 4. In another tab, open `CrewAI AMP > LLM Connections`. Name your LLM Connection, select Azure as the provider, and choose the same model you selected in Azure. + 5. On the same page, add environment variables from step 3: + - One named `AZURE_DEPLOYMENT_TARGET_URL` (using the Target URI). The URL should look like this: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview + - Another named `AZURE_API_KEY` (using the Key). + 6. Click `Add Connection` to save your LLM Connection. + + + + 7. In `CrewAI AMP > Settings > Defaults > Crew Studio LLM Settings`, set the new LLM Connection and model as defaults. + + + + 8. Ensure network access settings: + - In Azure, go to `Azure OpenAI > select your deployment`. + - Navigate to `Resource Management > Networking`. + - Ensure that `Allow access from all networks` is enabled. If this setting is restricted, CrewAI may be blocked from accessing your Azure OpenAI endpoint. + + + + +## Verification + +You're all set! Crew Studio will now use your Azure OpenAI connection. Test the connection by creating a simple crew or task to ensure everything is working properly. + +## Troubleshooting + +If you encounter issues: + +- Verify the Target URI format matches the expected pattern +- Check that the API key is correct and has proper permissions +- Ensure network access is configured to allow CrewAI connections +- Confirm the deployment model matches what you've configured in CrewAI diff --git a/docs/v1.15.1/en/enterprise/guides/build-crew.mdx b/docs/v1.15.1/en/enterprise/guides/build-crew.mdx new file mode 100644 index 000000000..de2a63088 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/build-crew.mdx @@ -0,0 +1,48 @@ +--- +title: "Build Crew" +description: "A Crew is a group of agents that work together to complete a task." +icon: "people-arrows" +mode: "wide" +--- + +## Overview + +[CrewAI AMP](https://app.crewai.com) streamlines the process of **creating**, **deploying**, and **managing** your AI agents in production environments. + +## Getting Started + + + +### Installation and Setup + + + Follow our standard installation guide to set up CrewAI CLI and create your + first project. + + +### Building Your Crew + + + Follow our quickstart guide to create your first agent crew using YAML + configuration. + + +## Support and Resources + +For Enterprise-specific support or questions, contact our dedicated support team at [support@crewai.com](mailto:support@crewai.com). + + + Book time with our team to learn more about Enterprise features and how they + can benefit your organization. + diff --git a/docs/v1.15.1/en/enterprise/guides/capture_telemetry_logs.mdx b/docs/v1.15.1/en/enterprise/guides/capture_telemetry_logs.mdx new file mode 100644 index 000000000..b751031f1 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/capture_telemetry_logs.mdx @@ -0,0 +1,57 @@ +--- +title: "OpenTelemetry Export" +description: "Export traces and logs from your CrewAI AMP deployments to your own OpenTelemetry collector" +icon: "magnifying-glass-chart" +mode: "wide" +--- + +CrewAI AMP can export OpenTelemetry **traces** and **logs** from your deployments directly to your own collector. This lets you monitor agent performance, track LLM calls, and debug issues using your existing observability stack. + +Telemetry data follows the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus additional CrewAI-specific attributes. + + +OpenTelemetry is the **recommended observability path** — vendor-neutral, works with any OTLP-compatible backend (Grafana, Honeycomb, NewRelic, your own collector). If you specifically use Datadog, see the dedicated [Datadog Integration](./datadog) guide which covers both the Datadog Agent path and Datadog's OTLP intake. + + +## Prerequisites + + + + Your organization must have an active CrewAI AMP account. + + + You need an OpenTelemetry-compatible collector endpoint (e.g., your own OTel Collector, Datadog, Grafana, or any OTLP-compatible backend). + + + +## Setting up a collector + +1. In CrewAI AMP, go to **Settings** > **OpenTelemetry Collectors**. +2. Click **Add Collector**. +3. Select an integration: + - **OpenTelemetry Traces** and **OpenTelemetry Logs** — export to any OTLP-compatible collector or backend. + - **Datadog** — send traces straight to Datadog's OTLP intake, no separate collector or Datadog Agent required. +4. Configure the connection. The fields depend on the integration you selected: + + + + **OpenTelemetry Traces** and **OpenTelemetry Logs** are separate integrations that share the same fields — pick the one matching the signal you want to export. + + - **Endpoint** — Your collector's OTLP endpoint (e.g., `https://otel-collector.example.com:4317`). + - **Service Name** — A name to identify this service in your observability platform. + - **Custom Headers** *(optional)* — Add authentication or routing headers as key-value pairs. + - **Certificate** *(optional)* — Provide a TLS certificate if your collector requires one. + + ![OpenTelemetry collector configuration](/images/crewai-otel-collector-opentelemetry.png) + + + For Datadog setup, see the dedicated [Datadog Integration](./datadog) guide — it covers both the Datadog Agent path (recommended, cheaper for log volume) and Datadog's OTLP intake with full collector configuration steps. + + + +5. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. +6. Click **Save**. + + + You can add multiple collectors — for example, one for traces and another for logs, or send to different backends for different purposes. + diff --git a/docs/v1.15.1/en/enterprise/guides/custom-mcp-server.mdx b/docs/v1.15.1/en/enterprise/guides/custom-mcp-server.mdx new file mode 100644 index 000000000..342028bb3 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/custom-mcp-server.mdx @@ -0,0 +1,136 @@ +--- +title: "Custom MCP Servers" +description: "Connect your own MCP servers to CrewAI AMP with public access, API key authentication, or OAuth 2.0" +icon: "plug" +mode: "wide" +--- + +CrewAI AMP supports connecting to any MCP server that implements the [Model Context Protocol](https://modelcontextprotocol.io/). You can bring public servers that require no authentication, servers protected by an API key or bearer token, and servers that use OAuth 2.0 for secure delegated access. + +## Prerequisites + + + + You need an active [CrewAI AMP](https://app.crewai.com) account. + + + The URL of the MCP server you want to connect. The server must be accessible from the internet and support Streamable HTTP transport. + + + +## Adding a Custom MCP Server + + + + Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP, then select the **Connections** tab. + + + + Click the **Add Custom MCP Server** button. A dialog will appear with the configuration form. + + + + - **Name** (required): A descriptive name for your MCP server (e.g., "My Internal Tools Server"). + - **Description**: An optional summary of what this MCP server provides. + - **Server URL** (required): The full URL to your MCP server endpoint (e.g., `https://my-server.example.com/mcp`). + + + + Select one of the three available authentication methods based on how your MCP server is secured. See the sections below for details on each method. + + + + If your MCP server requires additional headers on every request (e.g., tenant identifiers or routing headers), click **+ Add Header** and provide the header name and value. You can add multiple custom headers. + + + + Click **Create MCP Server** to save the connection. Your custom MCP server will now appear in the Connections list and its tools will be available for use in your crews. + + + +## Authentication Methods + +### No Authentication + +Choose this option when your MCP server is publicly accessible and does not require any credentials. This is common for open-source or internal servers running behind a VPN. + +### Authentication Token + +Use this method when your MCP server is protected by an API key or bearer token. + + + Custom MCP Server with Authentication Token + + +| Field | Required | Description | +|-------|----------|-------------| +| **Header Name** | Yes | The name of the HTTP header that carries the token (e.g., `X-API-Key`, `Authorization`). | +| **Value** | Yes | Your API key or bearer token. | +| **Add to** | No | Where to attach the credential — **Header** (default) or **Query parameter**. | + + +If your server expects a `Bearer` token in the `Authorization` header, set the Header Name to `Authorization` and the Value to `Bearer `. + + +### OAuth 2.0 + +Use this method for MCP servers that require OAuth 2.0 authorization. CrewAI will handle the full OAuth flow, including token refresh. + + + Custom MCP Server with OAuth 2.0 + + +| Field | Required | Description | +|-------|----------|-------------| +| **Redirect URI** | — | Pre-filled and read-only. Copy this URI and register it as an authorized redirect URI in your OAuth provider. | +| **Authorization Endpoint** | Yes | The URL where users are sent to authorize access (e.g., `https://auth.example.com/oauth/authorize`). | +| **Token Endpoint** | Yes | The URL used to exchange the authorization code for an access token (e.g., `https://auth.example.com/oauth/token`). | +| **Client ID** | Yes | The OAuth client ID issued by your provider. | +| **Client Secret** | No | The OAuth client secret. Not required for public clients using PKCE. | +| **Scopes** | No | Space-separated list of scopes to request (e.g., `read write`). | +| **Token Auth Method** | No | How the client credentials are sent when exchanging tokens — **Standard (POST body)** or **Basic Auth (header)**. Defaults to Standard. | +| **PKCE Supported** | No | Enable if your OAuth provider supports Proof Key for Code Exchange. Recommended for improved security. | + + +**Discover OAuth Config**: If your OAuth provider supports OpenID Connect Discovery, click the **Discover OAuth Config** link to auto-populate the authorization and token endpoints from the provider's `/.well-known/openid-configuration` URL. + + +#### Setting Up OAuth 2.0 Step by Step + + + + Copy the **Redirect URI** shown in the form and add it as an authorized redirect URI in your OAuth provider's application settings. + + + + Fill in the **Authorization Endpoint**, **Token Endpoint**, **Client ID**, and optionally the **Client Secret** and **Scopes**. + + + + Select the appropriate **Token Auth Method**. Most providers use the default **Standard (POST body)**. Some older providers require **Basic Auth (header)**. + + + + Check **PKCE Supported** if your provider supports it. PKCE adds an extra layer of security to the authorization code flow and is recommended for all new integrations. + + + + Click **Create MCP Server**. You will be redirected to your OAuth provider to authorize access. Once authorized, CrewAI will store the tokens and automatically refresh them as needed. + + + +## Using Your Custom MCP Server + +Once connected, your custom MCP server's tools appear alongside built-in connections on the **Tools & Integrations** page. You can: + +- **Assign tools to agents** in your crews just like any other CrewAI tool. +- **Manage visibility** to control which team members can use the server. +- **Edit or remove** the connection at any time from the Connections list. + + +If your MCP server becomes unreachable or the credentials expire, tool calls using that server will fail. Make sure the server URL is stable and credentials are kept up to date. + + + + Contact our support team for assistance with custom MCP server configuration or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/guides/datadog.mdx b/docs/v1.15.1/en/enterprise/guides/datadog.mdx new file mode 100644 index 000000000..1db2eae88 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/datadog.mdx @@ -0,0 +1,291 @@ +--- +title: "Datadog Integration" +description: "Monitor self-hosted CrewAI AMP deployments in Datadog via the Datadog Agent or Datadog's OTLP intake — either path lands the same structured facets so you can import the ready-made operations dashboard." +icon: "dog" +mode: "wide" +--- + +CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes. + + +For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs). + + +## Choose a path + +CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure. + + + + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + + **Setup:** + 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). + 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. + 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + + **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. + + + CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend. + + **Setup:** + 1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**. + 2. Configure the connection: + - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/): + - `otlp.datadoghq.com` (US1) + - `otlp.us3.datadoghq.com` (US3) + - `otlp.us5.datadoghq.com` (US5) + - `otlp.datadoghq.eu` (EU1) + - `otlp.ap1.datadoghq.com` (AP1) + - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + 3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list. + 4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step. + + ![Datadog collector configuration](/images/crewai-otel-collector-datadog.png) + + **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup. + + + +Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice. + +## Log schema reference + + +This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). + + +When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. + +### Why JSON output + + + + Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field. + + + Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration. + + + Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces. + + + The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed. + + + +### Enabling JSON output + +`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. + +```shell +CREWAI_LOG_FORMAT=json +``` + +Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. + + + The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. + + +### Example events + +A single info-level log inside an active automation kickoff: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:23.482914Z", + "level": "INFO", + "logger": "crewai_enterprise.utilities.pii_redaction", + "crewai_version": "1.14.7", + "msg": "PII tracking state reset (engines preserved)", + "automation_id": "12", + "task_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow" +} +``` + +An error with a Python exception is collapsed into a single event with the traceback as a string: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:31.218450Z", + "level": "ERROR", + "logger": "api.tasks.flow_run_task", + "crewai_version": "1.14.7", + "msg": "Flow execution failed", + "automation_id": "12", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow", + "exception": { + "type": "ValueError", + "message": "Topic cannot be empty", + "stacktrace": "Traceback (most recent call last):\n File \"/app/flow.py\", line 42, in summarize\n ...\nValueError: Topic cannot be empty\n" + } +} +``` + +The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. + +### Schema v1 fields + +Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded. + +| Field | Type | Always present | Source | +|-------|------|----------------|--------| +| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. | +| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. | +| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. | +| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. | +| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. | +| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). | +| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). | +| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. | +| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. | +| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. | +| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. | +| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. | +| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. | +| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. | + + + Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable. + + +### Stability promise + +The `schema` field declares the contract. Within `v1`, CrewAI commits to: + +- **Never removing a field** that customers may have built queries or dashboards against. +- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle. +- **Adding new fields** at any time. Consumers should ignore unknown top-level keys. + +When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate. + +## Prerequisite: promote facets + +Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account. + + + + Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event. + + + Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**. + + - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id` + - `crewai_version`, `model_id` + - `exception.type`, `exception.message` + + Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard. + + + +## Import the dashboard + + + + Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine. + + + Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**. + + + Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**. + + Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range. + + + + + Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI. + + +## What you get + +The dashboard is organized into four sections plus a placeholder for a custom drill-down widget: + +| Section | Widgets | Useful for | +|---------|---------|------------| +| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). | +| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. | +| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. | +| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. | +| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. | + +Three template variables at the top of the dashboard re-scope every widget at once: + +- **`$automation`** — filter to a single automation by name. +- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior). +- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account). + +## Verify ingestion + +Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path: + + + + Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. + + If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + + + Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). + + If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved. + + + +## Customize + +The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing. + +### Add a Recent Errors log stream + +The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures: + +1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group. +2. Drag in a **Log Stream** widget. +3. Set the filter query to `status:error $automation $version $service`. +4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`. +5. Sort by most recent, limit to 25 entries. + +Clicking any row jumps to Logs Explorer with the same filter pre-applied. + +### Add p95 latency + +Logs don't include execution duration by default. Two ways to add a latency widget: + +- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration. +- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM. + +### Re-scope to multiple deployments + +The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +|---------|--------------|-----| +| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | +| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | +| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | + +## Next steps + + + + Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends. + + + Reference for customizing widget queries against the structured facets above. + + diff --git a/docs/v1.15.1/en/enterprise/guides/datadog_dashboard.json b/docs/v1.15.1/en/enterprise/guides/datadog_dashboard.json new file mode 100644 index 000000000..447be8c30 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/datadog_dashboard.json @@ -0,0 +1,582 @@ +{ + "title": "crewAI -- Operations", + "description": "Monitoring dashboard for self-hosted crewAI deployments running structured JSON logs. Tracks executions, errors, token usage, and automation health.", + "widgets": [ + { + "id": 8810001, + "definition": { + "title": "Header", + "background_color": "vivid_blue", + "show_title": true, + "type": "group", + "layout_type": "ordered", + "widgets": [ + { + "id": 9910001, + "definition": { + "title": "Total Executions", + "time": { + "live_span": "1h" + }, + "type": "query_value", + "requests": [ + { + "response_format": "scalar", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "cardinality", + "metric": "@execution_id" + }, + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1" + } + ] + } + ], + "autoscale": true, + "precision": 0 + }, + "layout": { + "x": 0, + "y": 0, + "width": 3, + "height": 2 + } + }, + { + "id": 9910002, + "definition": { + "title": "Error Rate (%)", + "time": { + "live_span": "1h" + }, + "type": "query_value", + "requests": [ + { + "response_format": "scalar", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "status:error $automation $version $service" + }, + "compute": { + "aggregation": "count" + }, + "indexes": [ + "*" + ] + }, + { + "data_source": "logs", + "name": "query2", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "cardinality", + "metric": "@execution_id" + }, + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1 / query2 * 100" + } + ], + "conditional_formats": [ + { + "comparator": ">", + "value": 10, + "palette": "white_on_red" + }, + { + "comparator": ">", + "value": 5, + "palette": "white_on_yellow" + }, + { + "comparator": ">=", + "value": 0, + "palette": "white_on_green" + } + ] + } + ], + "autoscale": false, + "custom_unit": "%", + "precision": 2 + }, + "layout": { + "x": 3, + "y": 0, + "width": 3, + "height": 2 + } + }, + { + "id": 9910003, + "definition": { + "title": "Active Automations", + "time": { + "live_span": "1h" + }, + "type": "query_value", + "requests": [ + { + "response_format": "scalar", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "cardinality", + "metric": "@automation_id" + }, + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1" + } + ] + } + ], + "autoscale": true, + "precision": 0 + }, + "layout": { + "x": 6, + "y": 0, + "width": 3, + "height": 2 + } + }, + { + "id": 9910004, + "definition": { + "title": "CrewAI Versions in Use", + "time": { + "live_span": "1h" + }, + "type": "query_value", + "requests": [ + { + "response_format": "scalar", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "cardinality", + "metric": "@crewai_version" + }, + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1" + } + ] + } + ], + "autoscale": true, + "precision": 0 + }, + "layout": { + "x": 9, + "y": 0, + "width": 3, + "height": 2 + } + } + ] + }, + "layout": { + "x": 0, + "y": 0, + "width": 12, + "height": 3 + } + }, + { + "id": 8820001, + "definition": { + "title": "Throughput", + "background_color": "vivid_green", + "show_title": true, + "type": "group", + "layout_type": "ordered", + "widgets": [ + { + "id": 9920001, + "definition": { + "title": "Executions per Hour by Automation (top 10)", + "show_legend": false, + "type": "timeseries", + "requests": [ + { + "response_format": "timeseries", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "cardinality", + "metric": "@execution_id", + "interval": 3600000 + }, + "group_by": [ + { + "facet": "@automation_name", + "limit": 10, + "sort": { + "aggregation": "cardinality", + "metric": "@execution_id", + "order": "desc" + } + } + ], + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1" + } + ], + "style": { + "palette": "semantic" + }, + "display_type": "bars" + } + ] + }, + "layout": { + "x": 0, + "y": 0, + "width": 12, + "height": 3 + } + } + ] + }, + "layout": { + "x": 0, + "y": 3, + "width": 12, + "height": 4 + } + }, + { + "id": 8830001, + "definition": { + "title": "Errors", + "background_color": "vivid_orange", + "show_title": true, + "type": "group", + "layout_type": "ordered", + "widgets": [ + { + "id": 9930001, + "definition": { + "title": "Errors by Exception Type (top 5)", + "show_legend": false, + "type": "timeseries", + "requests": [ + { + "response_format": "timeseries", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "status:error $automation $version $service" + }, + "compute": { + "aggregation": "count" + }, + "group_by": [ + { + "facet": "@exception.type", + "limit": 5, + "sort": { + "aggregation": "count", + "order": "desc" + } + } + ], + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1" + } + ], + "style": { + "palette": "warm" + }, + "display_type": "bars" + } + ] + }, + "layout": { + "x": 0, + "y": 0, + "width": 6, + "height": 3 + } + }, + { + "id": 9930002, + "definition": { + "title": "Top Exception Types by Count", + "type": "toplist", + "requests": [ + { + "response_format": "scalar", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "status:error $automation $version $service" + }, + "compute": { + "aggregation": "count" + }, + "group_by": [ + { + "facet": "@exception.type", + "limit": 10, + "sort": { + "aggregation": "count", + "order": "desc" + } + } + ], + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1" + } + ], + "sort": { + "count": 10, + "order_by": [ + { + "type": "formula", + "index": 0, + "order": "desc" + } + ] + } + } + ], + "style": { + "palette": "datadog16" + } + }, + "layout": { + "x": 6, + "y": 0, + "width": 6, + "height": 3 + } + } + ] + }, + "layout": { + "x": 0, + "y": 7, + "width": 12, + "height": 4 + } + }, + { + "id": 8840001, + "definition": { + "title": "Cost", + "background_color": "vivid_purple", + "show_title": true, + "type": "group", + "layout_type": "ordered", + "widgets": [ + { + "id": 9940001, + "definition": { + "title": "Total Tokens per Hour by Model (input + output)", + "show_legend": false, + "type": "timeseries", + "requests": [ + { + "response_format": "timeseries", + "queries": [ + { + "data_source": "logs", + "name": "query1", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "sum", + "metric": "@gen_ai.usage.input_tokens", + "interval": 3600000 + }, + "group_by": [ + { + "facet": "@gen_ai.request.model", + "limit": 10, + "sort": { + "aggregation": "sum", + "metric": "@gen_ai.usage.input_tokens", + "order": "desc" + } + } + ], + "indexes": [ + "*" + ] + }, + { + "data_source": "logs", + "name": "query2", + "search": { + "query": "$automation $version $service" + }, + "compute": { + "aggregation": "sum", + "metric": "@gen_ai.usage.output_tokens", + "interval": 3600000 + }, + "group_by": [ + { + "facet": "@gen_ai.request.model", + "limit": 10, + "sort": { + "aggregation": "sum", + "metric": "@gen_ai.usage.output_tokens", + "order": "desc" + } + } + ], + "indexes": [ + "*" + ] + } + ], + "formulas": [ + { + "formula": "query1 + query2", + "alias": "Total Tokens" + } + ], + "style": { + "palette": "cool" + }, + "display_type": "area" + } + ] + }, + "layout": { + "x": 0, + "y": 0, + "width": 12, + "height": 3 + } + } + ] + }, + "layout": { + "x": 0, + "y": 11, + "width": 12, + "height": 4 + } + }, + { + "id": 8850002, + "definition": { + "title": "Drill-Down", + "background_color": "gray", + "show_title": true, + "type": "group", + "layout_type": "ordered", + "widgets": [] + }, + "layout": { + "x": 0, + "y": 15, + "width": 12, + "height": 1 + } + } + ], + "template_variables": [ + { + "name": "automation", + "prefix": "@automation_name", + "available_values": [], + "default": "*" + }, + { + "name": "version", + "prefix": "@crewai_version", + "available_values": [], + "default": "*" + }, + { + "name": "service", + "prefix": "service", + "available_values": [], + "default": "*" + } + ], + "layout_type": "ordered", + "notify_list": [], + "pause_auto_refresh": false, + "reflow_type": "fixed", + "tags": [ + "ai:created_with_ai" + ] +} diff --git a/docs/v1.15.1/en/enterprise/guides/deploy-to-amp.mdx b/docs/v1.15.1/en/enterprise/guides/deploy-to-amp.mdx new file mode 100644 index 000000000..cbc78d893 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/deploy-to-amp.mdx @@ -0,0 +1,451 @@ +--- +title: "Deploy to AMP" +description: "Deploy your Crew or Flow to CrewAI AMP" +icon: "rocket" +mode: "wide" +--- + + + After creating a Crew or Flow locally (or through Crew Studio), the next step is + deploying it to the CrewAI AMP platform. This guide covers multiple deployment + methods to help you choose the best approach for your workflow. + + +## Prerequisites + + + + You should have a working Crew or Flow that runs successfully locally. + Follow our [preparation guide](/en/enterprise/guides/prepare-for-deployment) to verify your project structure. + + + Your code should be in a GitHub repository (for GitHub integration + method) + + + + + **Crews vs Flows**: Both project types can be deployed as "automations" on CrewAI AMP. + The deployment process is the same, but they have different project structures. + See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for details. + + +## Option 1: Deploy Using CrewAI CLI + +The CLI provides the fastest way to deploy locally developed Crews or Flows to the AMP platform. +The CLI automatically detects your project type from `pyproject.toml` and builds accordingly. + + + + If you haven't already, install the CrewAI CLI: + + ```bash + pip install crewai[tools] + ``` + + + The CLI comes with the main CrewAI package, but the `[tools]` extra ensures you have all deployment dependencies. + + + + + + First, you need to authenticate your CLI with the CrewAI AMP platform: + + ```bash + # If you already have a CrewAI AMP account, or want to create one: + crewai login + ``` + + When you run either command, the CLI will: + 1. Display a URL and a unique device code + 2. Open your browser to the authentication page + 3. Prompt you to confirm the device + 4. Complete the authentication process + + Upon successful authentication, you'll see a confirmation message in your terminal! + + + + + + From your project directory, run: + + ```bash + crewai deploy create + ``` + + This command will: + 1. Detect your GitHub repository information + 2. Identify environment variables in your local `.env` file + 3. Securely transfer these variables to the Enterprise platform + 4. Create a new deployment with a unique identifier + + On successful creation, you'll see a message like: + ```shell + Deployment created successfully! + Name: your_project_name + Deployment ID: 01234567-89ab-cdef-0123-456789abcdef + Current Status: Deploy Enqueued + ``` + + + + + + Track the deployment status with: + + ```bash + crewai deploy status + ``` + + For detailed logs of the build process: + + ```bash + crewai deploy logs + ``` + + + The first deployment typically takes around 1 minute. + + + + + +## Additional CLI Commands + +The CrewAI CLI offers several commands to manage your deployments: + +```bash +# List all your deployments +crewai deploy list + +# Get the status of your deployment +crewai deploy status + +# View the logs of your deployment +crewai deploy logs + +# Push updates after code changes +crewai deploy push + +# Remove a deployment +crewai deploy remove +``` + +## Option 2: Deploy Directly via Web Interface + +You can also deploy your Crews or Flows directly through the CrewAI AMP web interface by connecting your GitHub account. This approach doesn't require using the CLI on your local machine. The platform automatically detects your project type and handles the build appropriately. + + + + + +You need to push your crew to a GitHub repository. If you haven't created a crew yet, you can [follow this tutorial](/en/quickstart). + + + + + + 1. Log in to [CrewAI AMP](https://app.crewai.com) + 2. Click on the button "Connect GitHub" + + + ![Connect GitHub Button](/images/enterprise/connect-github.png) + + + + + + + After connecting your GitHub account, you'll be able to select which repository to deploy: + + + ![Select Repository](/images/enterprise/select-repo.png) + + + + If your Crew or Flow is inside a monorepo subfolder, expand **Advanced** + and set a working directory before deploying. See + [Monorepo Deployments](/en/enterprise/guides/monorepo-deployments). + + + + + + + Before deploying, you'll need to set up your environment variables to connect to your LLM provider or other services: + + 1. You can add variables individually or in bulk + 2. Enter your environment variables in `KEY=VALUE` format (one per line) + + + ![Set Environment Variables](/images/enterprise/set-env-variables.png) + + + + Using private Python packages? You'll need to add your registry credentials here too. + See [Private Package Registries](/en/enterprise/guides/private-package-registry) for the required variables. + + + + + + + 1. Click the "Deploy" button to start the deployment process + 2. You can monitor the progress through the progress bar + 3. The first deployment typically takes around 1 minute + + + ![Deploy Progress](/images/enterprise/deploy-progress.png) + + + Once deployment is complete, you'll see: + - Your crew's unique URL + - A Bearer token to protect your crew API + - A "Delete" button if you need to remove the deployment + + + + + +## Option 3: Redeploy Using API (CI/CD Integration) + +For automated deployments in CI/CD pipelines, you can use the CrewAI API to trigger redeployments of existing crews. This is particularly useful for GitHub Actions, Jenkins, or other automation workflows. + + + + + Navigate to your CrewAI AMP account settings to generate an API token: + + 1. Go to [app.crewai.com](https://app.crewai.com) + 2. Click on **Settings** → **Account** → **Personal Access Token** + 3. Generate a new token and copy it securely + 4. Store this token as a secret in your CI/CD system + + + + + + Locate the unique identifier for your deployed crew: + + 1. Go to **Automations** in your CrewAI AMP dashboard + 2. Select your existing automation/crew + 3. Click on **Additional Details** + 4. Copy the **UUID** - this identifies your specific crew deployment + + + + + + Use the Deploy API endpoint to trigger a redeployment: + + ```bash + curl -i -X POST \ + -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \ + https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy + + # HTTP/2 200 + # content-type: application/json + # + # { + # "uuid": "your-automation-uuid", + # "status": "Deploy Enqueued", + # "public_url": "https://your-crew-deployment.crewai.com", + # "token": "your-bearer-token" + # } + ``` + + + If your automation was first created connected to Git, the API will automatically pull the latest changes from your repository before redeploying. + + + + + + + Here's a GitHub Actions workflow with more complex deployment triggers: + + ```yaml + name: Deploy CrewAI Automation + + on: + push: + branches: [ main ] + pull_request: + types: [ labeled ] + release: + types: [ published ] + + jobs: + deploy: + runs-on: ubuntu-latest + if: | + (github.event_name == 'push' && github.ref == 'refs/heads/main') || + (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) || + (github.event_name == 'release') + steps: + - name: Trigger CrewAI Redeployment + run: | + curl -X POST \ + -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \ + https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy + ``` + + + Add `CREWAI_PAT` and `CREWAI_AUTOMATION_UUID` as repository secrets. For PR deployments, add a "deploy" label to trigger the workflow. + + + + + + +## Interact with Your Deployed Automation + +Once deployment is complete, you can access your crew through: + +1. **REST API**: The platform generates a unique HTTPS endpoint with these key routes: + + - `/inputs`: Lists the required input parameters + - `/kickoff`: Initiates an execution with provided inputs + - `/status/{kickoff_id}`: Checks the execution status + +2. **Web Interface**: Visit [app.crewai.com](https://app.crewai.com) to access: + - **Status tab**: View deployment information, API endpoint details, and authentication token + - **Run tab**: Visual representation of your crew's structure + - **Executions tab**: History of all executions + - **Metrics tab**: Performance analytics + - **Traces tab**: Detailed execution insights + +### Trigger an Execution + +From the Enterprise dashboard, you can: + +1. Click on your crew's name to open its details +2. Select "Trigger Crew" from the management interface +3. Enter the required inputs in the modal that appears +4. Monitor progress as the execution moves through the pipeline + +### Monitoring and Analytics + +The Enterprise platform provides comprehensive observability features: + +- **Execution Management**: Track active and completed runs +- **Traces**: Detailed breakdowns of each execution +- **Metrics**: Token usage, execution times, and costs +- **Timeline View**: Visual representation of task sequences + +### Advanced Features + +The Enterprise platform also offers: + +- **Environment Variables Management**: Securely store and manage API keys +- **LLM Connections**: Configure integrations with various LLM providers +- **Custom Tools Repository**: Create, share, and install tools +- **Crew Studio**: Build crews through a chat interface without writing code + +## Troubleshooting Deployment Failures + +If your deployment fails, check these common issues: + +### Build Failures + +#### Missing uv.lock File + +**Symptom**: Build fails early with dependency resolution errors + +**Solution**: Generate and commit the lock file: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + + + The `uv.lock` file is required for all deployments. Without it, the platform + cannot reliably install your dependencies. + + +#### Wrong Project Structure + +**Symptom**: "Could not find entry point" or "Module not found" errors + +**Solution**: Verify your project matches the expected structure: + +- **JSON-first Crews**: Keep `crew.jsonc` or `crew.json` and `agents/` at the project root +- **Classic Crews**: Use `src/project_name/main.py` with a `run()` entry point +- **Flows**: Use `src/project_name/main.py` with a `kickoff()` entry point + +See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for detailed structure diagrams. + +#### Missing CrewBase Decorator in a Classic Crew + +**Symptom**: "Crew not found", "Config not found", or agent/task configuration errors + +**Solution**: For classic Python/YAML crews, ensure all crew classes use the `@CrewBase` decorator. JSON-first crews do not need this decorator. + +```python +from crewai.project import CrewBase, agent, crew, task + +@CrewBase # This decorator is REQUIRED +class YourCrew(): + """Your crew description""" + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + # ... rest of crew definition +``` + + + This applies to classic Python crew classes, including classic crews embedded inside Flow projects. + JSON-first crews are validated from `crew.jsonc` and `agents/` instead. + + +#### Incorrect pyproject.toml Type + +**Symptom**: Build succeeds but runtime fails, or unexpected behavior + +**Solution**: Verify the `[tool.crewai]` section matches your project type: + +```toml +# For Crew projects: +[tool.crewai] +type = "crew" + +# For Flow projects: +[tool.crewai] +type = "flow" +``` + +### Runtime Failures + +#### LLM Connection Failures + +**Symptom**: API key errors, "model not found", or authentication failures + +**Solution**: +1. Verify your LLM provider's API key is correctly set in environment variables +2. Ensure the environment variable names match what your code expects +3. Test locally with the exact same environment variables before deploying + +#### Crew Execution Errors + +**Symptom**: Crew starts but fails during execution + +**Solution**: +1. Check the execution logs in the AMP dashboard (Traces tab) +2. Verify all tools have required API keys configured +3. For JSON-first crews, validate `crew.jsonc` and the referenced files in `agents/` +4. For classic crews, ensure `agents.yaml` and `tasks.yaml` are valid + + + Contact our support team for assistance with deployment issues or questions + about the AMP platform. + diff --git a/docs/v1.15.1/en/enterprise/guides/enable-crew-studio.mdx b/docs/v1.15.1/en/enterprise/guides/enable-crew-studio.mdx new file mode 100644 index 000000000..d58805434 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/enable-crew-studio.mdx @@ -0,0 +1,179 @@ +--- +title: "Enable Crew Studio" +description: "Enabling Crew Studio on CrewAI AMP" +icon: "comments" +mode: "wide" +--- + + + Crew Studio is a powerful **no-code/low-code** tool that allows you to quickly + scaffold or build Crews through a conversational interface. + + +## What is Crew Studio? + +Crew Studio is an innovative way to create AI agent crews without writing code. + + + ![Crew Studio Interface](/images/enterprise/crew-studio-interface.png) + + +With Crew Studio, you can: + +- Chat with the Crew Assistant to describe your problem +- Automatically generate agents and tasks +- Select appropriate tools +- Configure necessary inputs +- Generate downloadable code for customization +- Deploy directly to the CrewAI AMP platform + +## Configuration Steps + +Before you can start using Crew Studio, you need to configure your LLM connections: + + + + Go to the **LLM Connections** tab in your CrewAI AMP dashboard and create a new LLM connection. + + + Feel free to use any LLM provider you want that is supported by CrewAI. + + + Configure your LLM connection: + + - Enter a `Connection Name` (e.g., `OpenAI`) + - Select your model provider: `openai` or `azure` + - Select models you'd like to use in your Studio-generated Crews + - We recommend at least `gpt-4o`, `o1-mini`, and `gpt-4o-mini` + - Add your API key as an environment variable: + - For OpenAI: Add `OPENAI_API_KEY` with your API key + - For Azure OpenAI: Refer to [this article](https://blog.crewai.com/configuring-azure-openai-with-crewai-a-comprehensive-guide/) for configuration details + - Click `Add Connection` to save your configuration + + + ![LLM Connection Configuration](/images/enterprise/llm-connection-config.png) + + + + + + Once you complete the setup, you'll see your new connection added to the list of available connections. + + + ![Connection Added](/images/enterprise/connection-added.png) + + + + + + In the main menu, go to **Settings → Defaults** and configure the LLM Defaults settings: + + - Select default models for agents and other components + - Set default configurations for Crew Studio + + Click `Save Settings` to apply your changes. + + + ![LLM Defaults Configuration](/images/enterprise/llm-defaults.png) + + + + + +## Using Crew Studio + +Now that you've configured your LLM connection and default settings, you're ready to start using Crew Studio! + + + + Navigate to the **Studio** section in your CrewAI AMP dashboard. + + + + Start a conversation with the Crew Assistant by describing the problem you want to solve: + + ```md + I need a crew that can research the latest AI developments and create a summary report. + ``` + + The Crew Assistant will ask clarifying questions to better understand your requirements. + + + + + Review the generated crew configuration, including: + + - Agents and their roles + - Tasks to be performed + - Required inputs + - Tools to be used + + This is your opportunity to refine the configuration before proceeding. + + + + + Once you're satisfied with the configuration, you can: + + - Download the generated code for local customization + - Deploy the crew directly to the CrewAI AMP platform + - Modify the configuration and regenerate the crew + + + + + After deployment, test your crew with sample inputs to ensure it performs as expected. + + + + + For best results, provide clear, detailed descriptions of what you want your + crew to accomplish. Include specific inputs and expected outputs in your + description. + + +## Example Workflow + +Here's a typical workflow for creating a crew with Crew Studio: + + + + Start by describing your problem: + + ```md + I need a crew that can analyze financial news and provide investment recommendations + ``` + + + + + Respond to clarifying questions from the Crew Assistant to refine your + requirements. + + + + Review the generated crew plan, which might include: + + - A Research Agent to gather financial news + - An Analysis Agent to interpret the data + - A Recommendations Agent to provide investment advice + + + + + Approve the plan or request changes if necessary. + + + + Download the code for customization or deploy directly to the platform. + + + + Test your crew with sample inputs and refine as needed. + + + + + Contact our support team for assistance with Crew Studio or any other CrewAI + AMP features. + diff --git a/docs/v1.15.1/en/enterprise/guides/gmail-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/gmail-trigger.mdx new file mode 100644 index 000000000..68c513aa1 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/gmail-trigger.mdx @@ -0,0 +1,97 @@ +--- +title: "Gmail Trigger" +description: "Trigger automations when Gmail events occur (e.g., new emails, labels)." +icon: "envelope" +mode: "wide" +--- + +## Overview + +Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter. + + + Make sure Gmail is connected in Tools & Integrations and the trigger is + enabled for your deployment. + + +## Enabling the Gmail Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Gmail** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Process new emails + +When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload. + +```python +@CrewBase +class GmailProcessingCrew: + @agent + def parser(self) -> Agent: + return Agent( + config=self.agents_config['parser'], + ) + + @task + def parse_gmail_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_gmail_payload'], + agent=self.parser(), + ) + + @task + def act_on_email(self) -> Task: + return Task( + config=self.tasks_config['act_on_email'], + agent=self.parser(), + ) +``` + +The Gmail payload will be available via the standard context mechanisms. + +### Testing Locally + +Test your Gmail trigger integration locally using the CrewAI CLI: + +```bash +# View all available triggers +crewai triggers list + +# Simulate a Gmail trigger with realistic payload +crewai triggers run gmail/new_email_received +``` + +The `crewai triggers run` command will execute your crew with a complete Gmail payload, allowing you to test your parsing logic before deployment. + + + Use `crewai triggers run gmail/new_email_received` (not `crewai run`) to + simulate trigger execution during development. After deployment, your crew + will automatically receive the trigger payload. + + +## Monitoring Executions + +Track history and performance of triggered runs: + + + List of executions triggered by automation + + +## Troubleshooting + +- Ensure Gmail is connected in Tools & Integrations +- Verify the Gmail Trigger is enabled on the Triggers tab +- Test locally with `crewai triggers run gmail/new_email_received` to see the exact payload structure +- Check the execution logs and confirm the payload is passed as `crewai_trigger_payload` +- Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution diff --git a/docs/v1.15.1/en/enterprise/guides/google-calendar-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/google-calendar-trigger.mdx new file mode 100644 index 000000000..5a5f66a2b --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/google-calendar-trigger.mdx @@ -0,0 +1,83 @@ +--- +title: "Google Calendar Trigger" +description: "Kick off crews when Google Calendar events are created, updated, or cancelled" +icon: "calendar" +mode: "wide" +--- + +## Overview + +Use the Google Calendar trigger to launch automations whenever calendar events change. Common use cases include briefing a team before a meeting, notifying stakeholders when a critical event is cancelled, or summarizing daily schedules. + + + Make sure Google Calendar is connected in **Tools & Integrations** and enabled + for the deployment you want to automate. + + +## Enabling the Google Calendar Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Google Calendar** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize meeting details + +The snippet below mirrors the `calendar-event-crew.py` example in the trigger repository. It parses the payload, analyses the attendees and timing, and produces a meeting brief for downstream tools. + +```python +from calendar_event_crew import GoogleCalendarEventTrigger + +crew = GoogleCalendarEventTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": calendar_payload, +}) +print(result.raw) +``` + +Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields. + +## Testing Locally + +Test your Google Calendar trigger integration locally using the CrewAI CLI: + +```bash +# View all available triggers +crewai triggers list + +# Simulate a Google Calendar trigger with realistic payload +crewai triggers run google_calendar/event_changed +``` + +The `crewai triggers run` command will execute your crew with a complete Calendar payload, allowing you to test your parsing logic before deployment. + + + Use `crewai triggers run google_calendar/event_changed` (not `crewai run`) to + simulate trigger execution during development. After deployment, your crew + will automatically receive the trigger payload. + + +## Monitoring Executions + +The **Executions** list in the deployment dashboard tracks every triggered run and surfaces payload metadata, output summaries, and errors. + + + List of executions triggered by automation + + +## Troubleshooting + +- Ensure the correct Google account is connected and the trigger is enabled +- Test locally with `crewai triggers run google_calendar/event_changed` to see the exact payload structure +- Confirm your workflow handles all-day events (payloads use `start.date` and `end.date` instead of timestamps) +- Check execution logs if reminders or attendee arrays are missing—calendar permissions can limit fields in the payload +- Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution diff --git a/docs/v1.15.1/en/enterprise/guides/google-drive-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/google-drive-trigger.mdx new file mode 100644 index 000000000..0baf1cae3 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/google-drive-trigger.mdx @@ -0,0 +1,80 @@ +--- +title: "Google Drive Trigger" +description: "Respond to Google Drive file events with automated crews" +icon: "folder" +mode: "wide" +--- + +## Overview + +Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change. + + + Connect Google Drive in **Tools & Integrations** and confirm the trigger is + enabled for the automation you want to monitor. + + +## Enabling the Google Drive Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Google Drive** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize file activity + +The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary. + +```python +from drive_file_crew import GoogleDriveFileTrigger + +crew = GoogleDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": drive_payload, +}) +``` + +## Testing Locally + +Test your Google Drive trigger integration locally using the CrewAI CLI: + +```bash +# View all available triggers +crewai triggers list + +# Simulate a Google Drive trigger with realistic payload +crewai triggers run google_drive/file_changed +``` + +The `crewai triggers run` command will execute your crew with a complete Drive payload, allowing you to test your parsing logic before deployment. + + + Use `crewai triggers run google_drive/file_changed` (not `crewai run`) to + simulate trigger execution during development. After deployment, your crew + will automatically receive the trigger payload. + + +## Monitoring Executions + +Track history and performance of triggered runs with the **Executions** list in the deployment dashboard. + + + List of executions triggered by automation + + +## Troubleshooting + +- Verify Google Drive is connected and the trigger toggle is enabled +- Test locally with `crewai triggers run google_drive/file_changed` to see the exact payload structure +- If a payload is missing permission data, ensure the connected account has access to the file or folder +- The trigger sends file IDs only; use the Drive API if you need to fetch binary content during the crew run +- Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution diff --git a/docs/v1.15.1/en/enterprise/guides/hubspot-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/hubspot-trigger.mdx new file mode 100644 index 000000000..9dfae4fba --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/hubspot-trigger.mdx @@ -0,0 +1,61 @@ +--- +title: "HubSpot Trigger" +description: "Trigger CrewAI crews directly from HubSpot Workflows" +icon: "hubspot" +mode: "wide" +--- + +This guide provides a step-by-step process to set up HubSpot triggers for CrewAI AMP, enabling you to initiate crews directly from HubSpot Workflows. + +## Prerequisites + +- A CrewAI AMP account +- A HubSpot account with the [HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows) feature + +## Setup Steps + + + + - Log in to your `CrewAI AMP account > Triggers` - Select `HubSpot` from the + list of available triggers - Choose the HubSpot account you want to connect + with CrewAI AMP - Follow the on-screen prompts to authorize CrewAI AMP + access to your HubSpot account - A confirmation message will appear once + HubSpot is successfully connected with CrewAI AMP + + + - Log in to your `HubSpot account > Automations > Workflows > New workflow` + - Select the workflow type that fits your needs (e.g., Start from scratch) - + In the workflow builder, click the Plus (+) icon to add a new action. - + Choose `Integrated apps > CrewAI > Kickoff a Crew`. - Select the Crew you + want to initiate. - Click `Save` to add the action to your workflow + + HubSpot Workflow 1 + + + + - After the Kickoff a Crew step, click the Plus (+) icon to add a new + action. - For example, to send an internal email notification, choose + `Communications > Send internal email notification` - In the Body field, + click `Insert data`, select `View properties or action outputs from > Action + outputs > Crew Result` to include Crew data in the email + + HubSpot Workflow 2 + + - Configure any additional actions as needed - Review your workflow + steps to ensure everything is set up correctly - Activate the workflow + + HubSpot Workflow 3 + + + + +For more detailed information on available actions and customization options, refer to the [HubSpot Workflows Documentation](https://knowledge.hubspot.com/workflows/create-workflows). diff --git a/docs/v1.15.1/en/enterprise/guides/human-in-the-loop.mdx b/docs/v1.15.1/en/enterprise/guides/human-in-the-loop.mdx new file mode 100644 index 000000000..7824555bc --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/human-in-the-loop.mdx @@ -0,0 +1,157 @@ +--- +title: "HITL Workflows" +description: "Learn how to implement Human-In-The-Loop workflows in CrewAI for enhanced decision-making" +icon: "user-check" +mode: "wide" +--- + +Human-In-The-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. This guide shows you how to implement HITL within CrewAI Enterprise. + +## HITL Approaches in CrewAI + +CrewAI offers two approaches for implementing human-in-the-loop workflows: + +| Approach | Best For | Version | +|----------|----------|---------| +| **Flow-based** (`@human_feedback` decorator) | Production with Enterprise UI, email-first workflows, full platform features | **1.8.0+** | +| **Webhook-based** | Custom integrations, external systems (Slack, Teams, etc.), legacy setups | All versions | + +## Flow-Based HITL with Enterprise Platform + + +The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**. + + +When using the `@human_feedback` decorator in your Flows, CrewAI Enterprise provides an **email-first HITL system** that enables anyone with an email address to respond to review requests: + + + + Responders receive email notifications and can reply directly—no login required. + + + Review and respond to HITL requests in the Enterprise dashboard when preferred. + + + Route requests to specific emails based on method patterns or pull from flow state. + + + Configure automatic fallback responses when no human replies within the timeout. + + + +### Key Benefits + +- **External responders**: Anyone with an email can respond, even non-platform users +- **Dynamic assignment**: Pull assignee email from flow state (e.g., `account_owner_email`) +- **Simple configuration**: Email-based routing is easier to set up than user/role management +- **Deployment creator fallback**: If no routing rule matches, the deployment creator is notified + + +For implementation details on the `@human_feedback` decorator, see the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide. + + +## Setting Up Webhook-Based HITL Workflows + +For custom integrations with external systems like Slack, Microsoft Teams, or your own applications, you can use the webhook-based approach: + + + + Set up your task with human input enabled: + + Crew Human Input + + + + + When kicking off your crew, include a webhook URL for human input: + + Crew Webhook URL + + + + + Once the crew completes the task requiring human input, you'll receive a webhook notification containing: + - **Execution ID** + - **Task ID** + - **Task output** + + + + The system will pause in the `Pending Human Input` state. Review the task output carefully. + + + + Call the resume endpoint of your crew with the following information: + + Crew Resume Endpoint + + + + **Critical: Webhook URLs Must Be Provided Again**: + You **must** provide the same webhook URLs (`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`) in the resume call that you used in the kickoff call. Webhook configurations are **NOT** automatically carried over from kickoff - they must be explicitly included in the resume request to continue receiving notifications for task completion, agent steps, and crew completion. + + + Example resume call with webhooks: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "Great work! Please add more details.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **Feedback Impact on Task Execution**: + It's crucial to exercise care when providing feedback, as the entire feedback content will be incorporated as additional context for further task executions. + + This means: + - All information in your feedback becomes part of the task's context. + - Irrelevant details may negatively influence it. + - Concise, relevant feedback helps maintain task focus and efficiency. + - Always review your feedback carefully before submission to ensure it contains only pertinent information that will positively guide the task's execution. + + + If you provide negative feedback: + - The crew will retry the task with added context from your feedback. + - You'll receive another webhook notification for further review. + - Repeat steps 4-6 until satisfied. + + + + When you submit positive feedback, the execution will proceed to the next steps. + + + +## Best Practices + +- **Be Specific**: Provide clear, actionable feedback that directly addresses the task at hand +- **Stay Relevant**: Only include information that will help improve the task execution +- **Be Timely**: Respond to HITL prompts promptly to avoid workflow delays +- **Review Carefully**: Double-check your feedback before submitting to ensure accuracy + +## Common Use Cases + +HITL workflows are particularly valuable for: +- Quality assurance and validation +- Complex decision-making scenarios +- Sensitive or high-stakes operations +- Creative tasks requiring human judgment +- Compliance and regulatory reviews + +## Learn More + + + + Explore the full Enterprise Flow HITL platform capabilities including email notifications, routing rules, auto-response, and analytics. + + + Implementation guide for the `@human_feedback` decorator in your Flows. + + diff --git a/docs/v1.15.1/en/enterprise/guides/kickoff-crew.mdx b/docs/v1.15.1/en/enterprise/guides/kickoff-crew.mdx new file mode 100644 index 000000000..ba2408333 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/kickoff-crew.mdx @@ -0,0 +1,178 @@ +--- +title: "Kickoff Crew" +description: "Kickoff a Crew on CrewAI AMP" +icon: "flag-checkered" +mode: "wide" +--- + +## Overview + +Once you've deployed your crew to the CrewAI AMP platform, you can kickoff executions through the web interface or the API. This guide covers both approaches. + +## Method 1: Using the Web Interface + +### Step 1: Navigate to Your Deployed Crew + +1. Log in to [CrewAI AMP](https://app.crewai.com) +2. Click on the crew name from your projects list +3. You'll be taken to the crew's detail page + +![Crew Dashboard](/images/enterprise/crew-dashboard.png) + +### Step 2: Initiate Execution + +From your crew's detail page, you have two options to kickoff an execution: + +#### Option A: Quick Kickoff + +1. Click the `Kickoff` link in the Test Endpoints section +2. Enter the required input parameters for your crew in the JSON editor +3. Click the `Send Request` button + +![Kickoff Endpoint](/images/enterprise/kickoff-endpoint.png) + +#### Option B: Using the Visual Interface + +1. Click the `Run` tab in the crew detail page +2. Enter the required inputs in the form fields +3. Click the `Run Crew` button + +![Run Crew](/images/enterprise/run-crew.png) + +### Step 3: Monitor Execution Progress + +After initiating the execution: + +1. You'll receive a response containing a `kickoff_id` - **copy this ID** +2. This ID is essential for tracking your execution + +![Copy Task ID](/images/enterprise/copy-task-id.png) + +### Step 4: Check Execution Status + +To monitor the progress of your execution: + +1. Click the "Status" endpoint in the Test Endpoints section +2. Paste the `kickoff_id` into the designated field +3. Click the "Get Status" button + +![Get Status](/images/enterprise/get-status.png) + +The status response will show: + +- Current execution state (`running`, `completed`, etc.) +- Details about which tasks are in progress +- Any outputs produced so far + +### Step 5: View Final Results + +Once execution is complete: + +1. The status will change to `completed` +2. You can view the full execution results and outputs +3. For a more detailed view, check the `Executions` tab in the crew detail page + +## Method 2: Using the API + +You can also kickoff crews programmatically using the CrewAI AMP REST API. + +### Authentication + +All API requests require a bearer token for authentication: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +Your bearer token is available on the Status tab of your crew's detail page. + +### Checking Crew Health + +Before executing operations, you can verify that your crew is running properly: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +A successful response will return a message indicating the crew is operational: + +``` +Healthy% +``` + +### Step 1: Retrieve Required Inputs + +First, determine what inputs your crew requires: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +The response will be a JSON object containing an array of required input parameters, for example: + +```json +{ "inputs": ["topic", "current_year"] } +``` + +This example shows that this particular crew requires two inputs: `topic` and `current_year`. + +### Step 2: Kickoff Execution + +Initiate execution by providing the required inputs: + +```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 +``` + +The response will include a `kickoff_id` that you'll need for tracking: + +```json +{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" } +``` + +### Step 3: Check Execution Status + +Monitor the execution progress using the kickoff_id: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv +``` + +## Handling Executions + +### Long-Running Executions + +For executions that may take a long time: + +1. Consider implementing a polling mechanism to check status periodically +2. Use webhooks (if available) for notification when execution completes +3. Implement error handling for potential timeouts + +### Execution Context + +The execution context includes: + +- Inputs provided at kickoff +- Environment variables configured during deployment +- Any state maintained between tasks + +### Debugging Failed Executions + +If an execution fails: + +1. Check the "Executions" tab for detailed logs +2. Review the "Traces" tab for step-by-step execution details +3. Look for LLM responses and tool usage in the trace details + + + Contact our support team for assistance with execution issues or questions + about the Enterprise platform. + diff --git a/docs/v1.15.1/en/enterprise/guides/microsoft-teams-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/microsoft-teams-trigger.mdx new file mode 100644 index 000000000..8b69c65b2 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/microsoft-teams-trigger.mdx @@ -0,0 +1,70 @@ +--- +title: "Microsoft Teams Trigger" +description: "Kick off crews from Microsoft Teams chat activity" +icon: "microsoft" +mode: "wide" +--- + +## Overview + +Use the Microsoft Teams trigger to start automations whenever a new chat is created. Common patterns include summarizing inbound requests, routing urgent messages to support teams, or creating follow-up tasks in other systems. + + + Confirm Microsoft Teams is connected under **Tools & Integrations** and + enabled in the **Triggers** tab for your deployment. + + +## Enabling the Microsoft Teams Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Microsoft Teams** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize a new chat thread + +```python +from teams_chat_created_crew import MicrosoftTeamsChatTrigger + +crew = MicrosoftTeamsChatTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": teams_payload, +}) +print(result.raw) +``` + +The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team. + +## Testing Locally + +Test your Microsoft Teams trigger integration locally using the CrewAI CLI: + +```bash +# View all available triggers +crewai triggers list + +# Simulate a Microsoft Teams trigger with realistic payload +crewai triggers run microsoft_teams/teams_message_created +``` + +The `crewai triggers run` command will execute your crew with a complete Teams payload, allowing you to test your parsing logic before deployment. + + + Use `crewai triggers run microsoft_teams/teams_message_created` (not `crewai + run`) to simulate trigger execution during development. After deployment, your + crew will automatically receive the trigger payload. + + +## Troubleshooting + +- Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions +- Test locally with `crewai triggers run microsoft_teams/teams_message_created` to see the exact payload structure +- Confirm the webhook subscription in Microsoft 365 is still valid if payloads stop arriving +- Review execution logs for payload shape mismatches—Graph notifications may omit fields when a chat is private or restricted +- Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution diff --git a/docs/v1.15.1/en/enterprise/guides/monorepo-deployments.mdx b/docs/v1.15.1/en/enterprise/guides/monorepo-deployments.mdx new file mode 100644 index 000000000..03e55ef6d --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/monorepo-deployments.mdx @@ -0,0 +1,229 @@ +--- +title: "Monorepo Deployments" +description: "Deploy a Crew or Flow from a subfolder in a larger repository" +icon: "folder-tree" +mode: "wide" +--- + + + Use a working directory when your Crew or Flow lives inside a larger + repository. CrewAI AMP validates, builds, tests, and runs the automation from + that subfolder instead of the repository root. + + +## When to Use This + +Monorepo deployments are useful when one repository contains multiple +automations, shared packages, or other application code: + +```text +company-ai/ +|-- uv.lock +|-- packages/ +| `-- shared_tools/ +`-- crews/ + |-- support_agent/ + | |-- pyproject.toml + | |-- crew.jsonc + | `-- agents/ + | `-- support_agent.jsonc + `-- research_flow/ + |-- pyproject.toml + `-- src/ + `-- research_flow/ + `-- main.py +``` + +To deploy `support_agent`, set the working directory to: + +```text +crews/support_agent +``` + +AMP still pulls or uploads the whole repository, but it treats the selected +folder as the automation project root. + +## What the Working Directory Controls + +When a working directory is set, AMP uses that folder for: + +- Project validation, including `pyproject.toml`, JSON crew files, and any classic Crew or Flow entry point +- Dependency installation with `uv` +- The running process working directory +- The `CREW_ROOT_DIR` environment variable + +Leaving the field empty keeps the existing behavior and uses the repository +root. + +## Supported Sources + +You can set a working directory when creating a deployment from: + +- A connected GitHub repository +- A Git repository configured in AMP +- A ZIP upload + + + Configure working directories in the AMP web interface. The + `crewai deploy create` CLI flow does not prompt for this field. + + +You can also add or change the working directory on an existing deployment from +the deployment's **Settings** page. The change takes effect on the next deploy. + + + Working directories and auto-deploy cannot be used together. If a deployment + has a working directory, auto-deploy is disabled for that deployment. Turn + auto-deploy off before setting a working directory. + + +## Configure a New Deployment + + + + In CrewAI AMP, create a new deployment and choose your source: GitHub, Git + Repository, or ZIP upload. + + + + Choose the repository and branch that contain your monorepo, or upload a ZIP + file whose root contains the monorepo contents. + + + + Expand the **Advanced** section in the deploy form. + + + + Enter the path from the repository root to the Crew or Flow project: + + ```text + crews/support_agent + ``` + + Do not include a leading slash. + + + + Add any required environment variables, then start the deployment. + + + +## Configure an Existing Deployment + + + + Go to your automation in AMP and open **Settings**. + + + + If auto-deploy is enabled, disable it first. The working directory field is + unavailable while auto-deploy is on. + + + + In **Basic settings**, enter the subfolder path, such as: + + ```text + crews/support_agent + ``` + + + + Save the setting and redeploy the automation. The new working directory is + used on the next deploy. + + + +## Path Rules + +The working directory must be a relative path inside the repository or ZIP root. + +| Rule | Example | +|------|---------| +| Use a relative path | `crews/support_agent` | +| Do not start with `/` | `/crews/support_agent` is invalid | +| Do not use `.` or `..` path segments | `crews/../support_agent` is invalid | +| Use only letters, numbers, dashes, underscores, dots, and forward slashes | `crews/support agent` is invalid | +| Keep the path at 255 characters or fewer | Longer paths are rejected | + +AMP trims leading and trailing whitespace, collapses repeated slashes, and +removes trailing slashes. A blank value uses the repository root. + +## Lock Files and UV Workspaces + +The selected folder must contain the automation's `pyproject.toml` and the +project files for its type: + +- JSON-first crew: `crew.jsonc` or `crew.json`, plus `agents/` +- Classic crew or Flow: `src/` with the expected Python entry point + +A `uv.lock` or `poetry.lock` file can live either in the selected folder or at +the repository root. + +This supports both common lock-file layouts: + + + + ```text + company-ai/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- uv.lock + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + ```text + company-ai/ + |-- uv.lock + |-- packages/ + | `-- shared_tools/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + + If your automation imports shared packages from elsewhere in the monorepo, + declare those packages in `pyproject.toml` using UV workspace, path, or source + configuration. AMP runs the automation from the selected folder, so shared + code should be installed as a dependency instead of relying on the repository + root being on the Python path. + + +## Troubleshooting + +### Working Directory Not Found + +Check that the path is relative to the repository or ZIP root. For ZIP uploads, +the ZIP contents must include the working directory path exactly as entered. + +### Missing pyproject.toml + +The working directory should point to the Crew or Flow project folder, not just +to a parent folder that contains several projects. + +### Missing uv.lock or poetry.lock + +Commit a lock file either in the selected project folder or in the repository +root. For UV workspaces, keeping `uv.lock` at the workspace root is supported. + +### Auto-Deploy Is Unavailable + +Auto-deploy is disabled while a working directory is set. Use manual redeploys +or trigger redeployments from CI/CD with the AMP API instead. + + + Continue with the deployment guide after choosing your monorepo working + directory. + diff --git a/docs/v1.15.1/en/enterprise/guides/onedrive-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/onedrive-trigger.mdx new file mode 100644 index 000000000..a9280f5b1 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/onedrive-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "OneDrive Trigger" +description: "Automate responses to OneDrive file activity" +icon: "cloud" +mode: "wide" +--- + +## Overview + +Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata. + + + Connect OneDrive in **Tools & Integrations** and toggle the trigger on for + your deployment. + + +## Enabling the OneDrive Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **OneDrive** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Audit file permissions + +```python +from onedrive_file_crew import OneDriveFileTrigger + +crew = OneDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": onedrive_payload, +}) +``` + +The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary. + +## Testing Locally + +Test your OneDrive trigger integration locally using the CrewAI CLI: + +```bash +# View all available triggers +crewai triggers list + +# Simulate a OneDrive trigger with realistic payload +crewai triggers run microsoft_onedrive/file_changed +``` + +The `crewai triggers run` command will execute your crew with a complete OneDrive payload, allowing you to test your parsing logic before deployment. + + + Use `crewai triggers run microsoft_onedrive/file_changed` (not `crewai run`) + to simulate trigger execution during development. After deployment, your crew + will automatically receive the trigger payload. + + +## Troubleshooting + +- Ensure the connected account has permission to read the file metadata included in the webhook +- Test locally with `crewai triggers run microsoft_onedrive/file_changed` to see the exact payload structure +- If the trigger fires but the payload is missing `permissions`, confirm the site-level sharing settings allow Graph to return this field +- For large tenants, filter notifications upstream so the crew only runs on relevant directories +- Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution diff --git a/docs/v1.15.1/en/enterprise/guides/outlook-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/outlook-trigger.mdx new file mode 100644 index 000000000..ce1bd30a0 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/outlook-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "Outlook Trigger" +description: "Launch automations from Outlook emails and calendar updates" +icon: "microsoft" +mode: "wide" +--- + +## Overview + +Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations. + + + Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled + for your deployment. + + +## Enabling the Outlook Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Outlook** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize a new email + +```python +from outlook_message_crew import OutlookMessageTrigger + +crew = OutlookMessageTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": outlook_payload, +}) +``` + +The crew extracts sender details, subject, body preview, and attachments before generating a structured response. + +## Testing Locally + +Test your Outlook trigger integration locally using the CrewAI CLI: + +```bash +# View all available triggers +crewai triggers list + +# Simulate an Outlook trigger with realistic payload +crewai triggers run microsoft_outlook/email_received +``` + +The `crewai triggers run` command will execute your crew with a complete Outlook payload, allowing you to test your parsing logic before deployment. + + + Use `crewai triggers run microsoft_outlook/email_received` (not `crewai run`) + to simulate trigger execution during development. After deployment, your crew + will automatically receive the trigger payload. + + +## Troubleshooting + +- Verify the Outlook connector is still authorized; the subscription must be renewed periodically +- Test locally with `crewai triggers run microsoft_outlook/email_received` to see the exact payload structure +- If attachments are missing, confirm the webhook subscription includes the `includeResourceData` flag +- Review execution logs when events fail to match—cancellation payloads lack attendee lists by design and the crew should account for that +- Remember: use `crewai triggers run` (not `crewai run`) to simulate trigger execution diff --git a/docs/v1.15.1/en/enterprise/guides/prepare-for-deployment.mdx b/docs/v1.15.1/en/enterprise/guides/prepare-for-deployment.mdx new file mode 100644 index 000000000..959dfac5a --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/prepare-for-deployment.mdx @@ -0,0 +1,347 @@ +--- +title: "Prepare for Deployment" +description: "Ensure your Crew or Flow is ready for deployment to CrewAI AMP" +icon: "clipboard-check" +mode: "wide" +--- + + + Before deploying to CrewAI AMP, it's crucial to verify your project is correctly structured. + Both Crews and Flows can be deployed as "automations," but they have different project structures + and requirements that must be met for successful deployment. + + +## Understanding Automations + +In CrewAI AMP, **automations** is the umbrella term for deployable Agentic AI projects. An automation can be either: + +- **A Crew**: A standalone team of AI agents working together on tasks +- **A Flow**: An orchestrated workflow that can combine multiple crews, direct LLM calls, and procedural logic + +Understanding which type you're deploying is essential because they have different project structures and entry points. + +## Crews vs Flows: Key Differences + + + + Standalone AI agent teams. New crews are JSON-first with `crew.jsonc` and `agents/`; classic crews can still use `crew.py`. + + + Orchestrated workflows with embedded crews in a `crews/` folder. Best for complex, multi-stage processes. + + + +| Aspect | Crew | Flow | +|--------|------|------| +| **Project structure** | Project root with `crew.jsonc` and `agents/` | `src/project_name/` with `crews/` folder | +| **Main logic location** | `crew.jsonc` (classic: `src/project_name/crew.py`) | `src/project_name/main.py` (Flow class) | +| **Entry point function** | Loaded from `crew.jsonc` (classic: `run()` in `main.py`) | `kickoff()` in `main.py` | +| **pyproject.toml type** | `type = "crew"` | `type = "flow"` | +| **CLI create command** | `crewai create crew name` | `crewai create flow name` | +| **Config location** | `crew.jsonc`, `agents/`, optional `tools/` | `src/project_name/crews/crew_name/config/` or embedded JSON crew folders | +| **Can contain other crews** | No | Yes (in `crews/` folder) | + +## Project Structure Reference + +### Crew Project Structure + +When you run `crewai create crew my_crew`, you get the JSON-first structure: + +``` +my_crew/ +├── .gitignore +├── pyproject.toml # Must have type = "crew" +├── README.md +├── .env +├── uv.lock # REQUIRED for deployment +├── crew.jsonc # Crew settings, tasks, process, inputs +├── agents/ +│ └── researcher.jsonc # Agent definitions +├── tools/ # Optional custom: tools +├── knowledge/ +└── skills/ +``` + + + For JSON-first crews, keep `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, and `skills/` + at the project root. Placing them under `src/` will prevent `crewai run` and deployment + validation from finding the crew definition. + + + + Classic projects created with `crewai create crew my_crew --classic` use the older + `src/project_name/crew.py`, `src/project_name/config/agents.yaml`, and + `src/project_name/config/tasks.yaml` layout. That layout remains supported for + decorator-based Python crews. + + +### Flow Project Structure + +When you run `crewai create flow my_flow`, you get this structure: + +``` +my_flow/ +├── .gitignore +├── pyproject.toml # Must have type = "flow" +├── README.md +├── .env +├── uv.lock # REQUIRED for deployment +└── src/ + └── my_flow/ + ├── __init__.py + ├── main.py # Entry point with kickoff() function + Flow class + ├── crews/ # Embedded crews folder + │ └── poem_crew/ + │ ├── __init__.py + │ ├── poem_crew.py # Crew with @CrewBase decorator + │ └── config/ + │ ├── agents.yaml + │ └── tasks.yaml + └── tools/ + ├── __init__.py + └── custom_tool.py +``` + + + JSON-first standalone crews use project-root JSON files. Flows still use + `src/project_name/` and can contain either classic embedded crews or embedded + JSON crew folders loaded with `crewai.project.load_crew`. + + +## Pre-Deployment Checklist + +Use this checklist to verify your project is ready for deployment. + +### 1. Verify pyproject.toml Configuration + +Your `pyproject.toml` must include the correct `[tool.crewai]` section: + + + + ```toml + [tool.crewai] + type = "crew" + ``` + + + ```toml + [tool.crewai] + type = "flow" + ``` + + + + + If the `type` doesn't match your project structure, the build will fail or + the automation won't run correctly. + + +### 2. Ensure uv.lock File Exists + +CrewAI uses `uv` for dependency management. The `uv.lock` file ensures reproducible builds and is **required** for deployment. + +```bash +# Generate or update the lock file +uv lock + +# Verify it exists +ls -la uv.lock +``` + +If the file doesn't exist, run `uv lock` and commit it to your repository: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + +### 3. Validate the Crew Definition + + + + JSON-first crews must have a `crew.jsonc` or `crew.json` file at the project root. + The `agents` array must reference files in `agents/`, and each task should reference + a valid agent name. + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "Research {topic}.", + "expected_output": "A concise report.", + "agent": "researcher" + } + ], + "inputs": { + "topic": "AI Agents" + } + } + ``` + + Custom tools are referenced as `"custom:"` and must be implemented in + `tools/.py` with a `BaseTool` subclass. + + + Classic crews and Python crews embedded in Flows must use the `@CrewBase` decorator. + + ```python + from crewai import Agent, Crew, Process, Task + from crewai.project import CrewBase, agent, crew, task + from crewai.agents.agent_builder.base_agent import BaseAgent + from typing import List + + @CrewBase + class MyCrew(): + """My crew description""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + @task + def my_task(self) -> Task: + return Task( + config=self.tasks_config['my_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) + ``` + + + +### 4. Check Project Entry Points + +JSON-first standalone crews do not need a hand-written `src/project_name/main.py`; `crewai run` +and deployment packaging load `crew.jsonc` directly. Classic crews and Flows use Python entry +points: + + + + Run locally from the project root: + + ```bash + crewai run + ``` + + + The entry point uses a `run()` function: + + ```python + # src/my_crew/main.py + from my_crew.crew import MyCrew + + def run(): + """Run the crew.""" + inputs = {'topic': 'AI in Healthcare'} + result = MyCrew().crew().kickoff(inputs=inputs) + return result + + if __name__ == "__main__": + run() + ``` + + + The entry point uses a `kickoff()` function with a Flow class: + + ```python + # src/my_flow/main.py + from crewai.flow import Flow, listen, start + from my_flow.crews.poem_crew.poem_crew import PoemCrew + + class MyFlow(Flow): + @start() + def begin(self): + # Flow logic here + result = PoemCrew().crew().kickoff(inputs={...}) + return result + + def kickoff(): + """Run the flow.""" + MyFlow().kickoff() + + if __name__ == "__main__": + kickoff() + ``` + + + +### 5. Prepare Environment Variables + +Before deployment, ensure you have: + +1. **LLM API keys** ready (OpenAI, Anthropic, Google, etc.) +2. **Tool API keys** if using external tools (Serper, etc.) + + + If your project depends on packages from a **private PyPI registry**, you'll also need to configure + registry authentication credentials as environment variables. See the + [Private Package Registries](/en/enterprise/guides/private-package-registry) guide for details. + + + + Test your project locally with the same environment variables before deploying + to catch configuration issues early. + + +## Quick Validation Commands + +Run these commands from your project root to quickly verify your setup: + +```bash +# 1. Check project type in pyproject.toml +grep -A2 "\[tool.crewai\]" pyproject.toml + +# 2. Verify uv.lock exists +ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'" + +# 3. For JSON-first crews, verify crew.jsonc and agents/ exist +([ -f crew.jsonc ] || [ -f crew.json ]) || echo "No crew.jsonc or crew.json found" +test -d agents || echo "No agents/ directory found" + +# 4. For classic Crews - verify crew.py exists +ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)" + +# 5. For Flows - verify crews/ folder exists +ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)" + +# 6. For classic Python crews - check for CrewBase usage +grep -r "@CrewBase" . --include="*.py" +``` + +## Common Setup Mistakes + +| Mistake | Symptom | Fix | +|---------|---------|-----| +| Missing `uv.lock` | Build fails during dependency resolution | Run `uv lock` and commit | +| Wrong `type` in pyproject.toml | Build succeeds but runtime fails | Change to correct type | +| Missing `crew.jsonc` or `agents/` in a JSON-first crew | Crew definition not found | Keep `crew.jsonc` and `agents/` at the project root | +| Missing `@CrewBase` decorator in a classic crew | "Config not found" errors | Add decorator to all classic crew classes | +| Classic files at root instead of `src/` | Entry point not found | Move classic Python files to `src/project_name/` | +| Missing `run()` or `kickoff()` | Cannot start automation | Add correct entry function | + +## Next Steps + +Once your project passes all checklist items, you're ready to deploy: + + + Follow the deployment guide to deploy your Crew or Flow to CrewAI AMP using + the CLI, web interface, or CI/CD integration. + diff --git a/docs/v1.15.1/en/enterprise/guides/private-package-registry.mdx b/docs/v1.15.1/en/enterprise/guides/private-package-registry.mdx new file mode 100644 index 000000000..feb521436 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/private-package-registry.mdx @@ -0,0 +1,263 @@ +--- +title: "Private Package Registries" +description: "Install private Python packages from authenticated PyPI registries in CrewAI AMP" +icon: "lock" +mode: "wide" +--- + + + This guide covers how to configure your CrewAI project to install Python packages + from private PyPI registries (Azure DevOps Artifacts, GitHub Packages, GitLab, AWS CodeArtifact, etc.) + when deploying to CrewAI AMP. + + +## When You Need This + +If your project depends on internal or proprietary Python packages hosted on a private registry +rather than the public PyPI, you'll need to: + +1. Tell UV **where** to find the package (an index URL) +2. Tell UV **which** packages come from that index (a source mapping) +3. Provide **credentials** so UV can authenticate during install + +CrewAI AMP uses [UV](https://docs.astral.sh/uv/) for dependency resolution and installation. +UV supports authenticated private registries through `pyproject.toml` configuration combined +with environment variables for credentials. + +## Step 1: Configure pyproject.toml + +Three pieces work together in your `pyproject.toml`: + +### 1a. Declare the dependency + +Add the private package to your `[project.dependencies]` like any other dependency: + +```toml +[project] +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] +``` + +### 1b. Define the index + +Register your private registry as a named index under `[[tool.uv.index]]`: + +```toml +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true +``` + + + The `name` field is important — UV uses it to construct the environment variable names + for authentication (see [Step 2](#step-2-set-authentication-credentials) below). + + Setting `explicit = true` means UV won't search this index for every package — only the + ones you explicitly map to it in `[tool.uv.sources]`. This avoids unnecessary queries + against your private registry and protects against dependency confusion attacks. + + +### 1c. Map the package to the index + +Tell UV which packages should be resolved from your private index using `[tool.uv.sources]`: + +```toml +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +### Complete example + +```toml +[project] +name = "my-crew-project" +version = "0.1.0" +requires-python = ">=3.10,<=3.13" +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] + +[tool.crewai] +type = "crew" + +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true + +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +After updating `pyproject.toml`, regenerate your lock file: + +```bash +uv lock +``` + + + Always commit the updated `uv.lock` along with your `pyproject.toml` changes. + The lock file is required for deployment — see [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment). + + +## Step 2: Set Authentication Credentials + +UV authenticates against private indexes using environment variables that follow a naming convention +based on the index name you defined in `pyproject.toml`: + +``` +UV_INDEX_{UPPER_NAME}_USERNAME +UV_INDEX_{UPPER_NAME}_PASSWORD +``` + +Where `{UPPER_NAME}` is your index name converted to **uppercase** with **hyphens replaced by underscores**. + +For example, an index named `my-private-registry` uses: + +| Variable | Value | +|----------|-------| +| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | Your registry username or token name | +| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | Your registry password or token/PAT | + + + These environment variables **must** be added via the CrewAI AMP **Environment Variables** settings — + either globally or at the deployment level. They cannot be set in `.env` files or hardcoded in your project. + + See [Setting Environment Variables in AMP](#setting-environment-variables-in-amp) below. + + +## Registry Provider Reference + +The table below shows the index URL format and credential values for common registry providers. +Replace placeholder values with your actual organization and feed details. + +| Provider | Index URL | Username | Password | +|----------|-----------|----------|----------| +| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | Any non-empty string (e.g. `token`) | Personal Access Token (PAT) with Packaging Read scope | +| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | GitHub username | Personal Access Token (classic) with `read:packages` scope | +| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project or Personal Access Token with `read_api` scope | +| **AWS CodeArtifact** | Use the URL from `aws codeartifact get-repository-endpoint` | `aws` | Token from `aws codeartifact get-authorization-token` | +| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Base64-encoded service account key | +| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | Username or email | API key or identity token | +| **Self-hosted (devpi, Nexus, etc.)** | Your registry's simple API URL | Registry username | Registry password | + + + For **AWS CodeArtifact**, the authorization token expires periodically. + You'll need to refresh the `UV_INDEX_*_PASSWORD` value when it expires. + Consider automating this in your CI/CD pipeline. + + +## Setting Environment Variables in AMP + +Private registry credentials must be configured as environment variables in CrewAI AMP. +You have two options: + + + + 1. Log in to [CrewAI AMP](https://app.crewai.com) + 2. Navigate to your automation + 3. Open the **Environment Variables** tab + 4. Add each variable (`UV_INDEX_*_USERNAME` and `UV_INDEX_*_PASSWORD`) with its value + + See the [Deploy to AMP — Set Environment Variables](/en/enterprise/guides/deploy-to-amp#set-environment-variables) step for details. + + + Add the variables to your local `.env` file before running `crewai deploy create`. + The CLI will securely transfer them to the platform: + + ```bash + # .env + OPENAI_API_KEY=sk-... + UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token + UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here + ``` + + ```bash + crewai deploy create + ``` + + + + + **Never** commit credentials to your repository. Use AMP environment variables for all secrets. + The `.env` file should be listed in `.gitignore`. + + +To update credentials on an existing deployment, see [Update Your Crew — Environment Variables](/en/enterprise/guides/update-crew). + +## How It All Fits Together + +When CrewAI AMP builds your automation, the resolution flow works like this: + + + + AMP pulls your repository and reads `pyproject.toml` and `uv.lock`. + + + UV reads `[tool.uv.sources]` to determine which index each package should come from. + + + For each private index, UV looks up `UV_INDEX_{NAME}_USERNAME` and `UV_INDEX_{NAME}_PASSWORD` + from the environment variables you configured in AMP. + + + UV downloads and installs all packages — both public (from PyPI) and private (from your registry). + + + Your crew or flow starts with all dependencies available. + + + +## Troubleshooting + +### Authentication Errors During Build + +**Symptom**: Build fails with `401 Unauthorized` or `403 Forbidden` when resolving a private package. + +**Check**: +- The `UV_INDEX_*` environment variable names match your index name exactly (uppercased, hyphens → underscores) +- Credentials are set in AMP environment variables, not just in a local `.env` +- Your token/PAT has the required read permissions for the package feed +- The token hasn't expired (especially relevant for AWS CodeArtifact) + +### Package Not Found + +**Symptom**: `No matching distribution found for my-private-package`. + +**Check**: +- The index URL in `pyproject.toml` ends with `/simple/` +- The `[tool.uv.sources]` entry maps the correct package name to the correct index name +- The package is actually published to your private registry +- Run `uv lock` locally with the same credentials to verify resolution works + +### Lock File Conflicts + +**Symptom**: `uv lock` fails or produces unexpected results after adding a private index. + +**Solution**: Set the credentials locally and regenerate: + +```bash +export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token +export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat +uv lock +``` + +Then commit the updated `uv.lock`. + +## Related Guides + + + + Verify project structure and dependencies before deploying. + + + Deploy your crew or flow and configure environment variables. + + + Update environment variables and push changes to a running deployment. + + diff --git a/docs/v1.15.1/en/enterprise/guides/react-component-export.mdx b/docs/v1.15.1/en/enterprise/guides/react-component-export.mdx new file mode 100644 index 000000000..47012db8d --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/react-component-export.mdx @@ -0,0 +1,112 @@ +--- +title: "React Component Export" +description: "Learn how to export and integrate CrewAI AMP React components into your applications" +icon: "react" +mode: "wide" +--- + +This guide explains how to export CrewAI AMP crews as React components and integrate them into your own applications. + +## Exporting a React Component + + + + Click on the ellipsis (three dots on the right of your deployed crew) and select the export option and save the file locally. We will be using `CrewLead.jsx` for our example. + + + Export React Component + + + + + +## Setting Up Your React Environment + +To run this React component locally, you'll need to set up a React development environment and integrate this component into a React project. + + + + - Download and install Node.js from the official website: https://nodejs.org/ + - Choose the LTS (Long Term Support) version for stability. + + + + - Open Command Prompt or PowerShell + - Navigate to the directory where you want to create your project + - Run the following command to create a new React project: + + ```bash + npx create-react-app my-crew-app + ``` + - Change into the project directory: + + ```bash + cd my-crew-app + ``` + + + + ```bash + npm install react-dom + ``` + + + + - Move the downloaded file `CrewLead.jsx` into the `src` folder of your project, + + + + - Open `src/App.js` + - Replace its contents with something like this: + + ```jsx + import React from 'react'; + import CrewLead from './CrewLead'; + + function App() { + return ( +
+ +
+ ); + } + + export default App; + ``` + - Replace `YOUR_API_BASE_URL` and `YOUR_BEARER_TOKEN` with the actual values for your API. + + + + - In your project directory, run: + + ```bash + npm start + ``` + - This will start the development server, and your default web browser should open automatically to http://localhost:3000, where you'll see your React app running. + + + + +## Customization + +You can then customise the `CrewLead.jsx` to add color, title etc + + + Customise React Component + + + Customise React Component + + +## Next Steps + +- Customize the component styling to match your application's design +- Add additional props for configuration +- Integrate with your application's state management +- Add error handling and loading states diff --git a/docs/v1.15.1/en/enterprise/guides/salesforce-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/salesforce-trigger.mdx new file mode 100644 index 000000000..4b0010edb --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/salesforce-trigger.mdx @@ -0,0 +1,50 @@ +--- +title: "Salesforce Trigger" +description: "Trigger CrewAI crews from Salesforce workflows for CRM automation" +icon: "salesforce" +mode: "wide" +--- + +CrewAI AMP can be triggered from Salesforce to automate customer relationship management workflows and enhance your sales operations. + +## Overview + +Salesforce is a leading customer relationship management (CRM) platform that helps businesses streamline their sales, service, and marketing operations. By setting up CrewAI triggers from Salesforce, you can: + +- Automate lead scoring and qualification +- Generate personalized sales materials +- Enhance customer service with AI-powered responses +- Streamline data analysis and reporting + +## Demo + + + +## Getting Started + +To set up Salesforce triggers: + +1. **Contact Support**: Reach out to CrewAI AMP support for assistance with Salesforce trigger setup +2. **Review Requirements**: Ensure you have the necessary Salesforce permissions and API access +3. **Configure Connection**: Work with the support team to establish the connection between CrewAI and your Salesforce instance +4. **Test Triggers**: Verify the triggers work correctly with your specific use cases + +## Use Cases + +Common Salesforce + CrewAI trigger scenarios include: + +- **Lead Processing**: Automatically analyze and score incoming leads +- **Proposal Generation**: Create customized proposals based on opportunity data +- **Customer Insights**: Generate analysis reports from customer interaction history +- **Follow-up Automation**: Create personalized follow-up messages and recommendations + +## Next Steps + +For detailed setup instructions and advanced configuration options, please contact CrewAI AMP support who can provide tailored guidance for your specific Salesforce environment and business needs. diff --git a/docs/v1.15.1/en/enterprise/guides/slack-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/slack-trigger.mdx new file mode 100644 index 000000000..8608c1a44 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/slack-trigger.mdx @@ -0,0 +1,62 @@ +--- +title: "Slack Trigger" +description: "Trigger CrewAI crews directly from Slack using slash commands" +icon: "slack" +mode: "wide" +--- + +This guide explains how to start a crew directly from Slack using CrewAI triggers. + +## Prerequisites + +- CrewAI Slack trigger installed and connected to your Slack workspace +- At least one crew configured in CrewAI + +## Setup Steps + + + + In the CrewAI dashboard, navigate to the **Triggers** section. + + + CrewAI Slack Integration + + + Verify that Slack is listed and is connected. + + + - Navigate to the channel where you want to kickoff the crew. + - Type the slash command "**/kickoff**" to initiate the crew kickoff process. + - You should see a "**Kickoff crew**" appear as you type: + + Kickoff crew + + - Press Enter or select the "**Kickoff crew**" option. A dialog box titled "**Kickoff an AI Crew**" will appear. + + + - In the dropdown menu labeled "**Select of the crews online:**", choose the crew you want to start. + - In the example below, "**prep-for-meeting**" is selected: + + Kickoff crew dropdown + + - If your crew requires any inputs, click the "**Add Inputs**" button to provide them. + + The "**Add Inputs**" button is shown in the example above but is not yet clicked. + + + + - Once you've selected the crew and added any necessary inputs, click "**Kickoff**" to start the crew. + + Kickoff crew + + - The crew will start executing and you will see the results in the Slack channel. + + Kickoff crew results + + + + +## Tips + +- Make sure you have the necessary permissions to use the `/kickoff` command in your Slack workspace. +- If you don't see your desired crew in the dropdown, ensure it's properly configured and online in CrewAI. \ No newline at end of file diff --git a/docs/v1.15.1/en/enterprise/guides/team-management.mdx b/docs/v1.15.1/en/enterprise/guides/team-management.mdx new file mode 100644 index 000000000..c9258cd4d --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/team-management.mdx @@ -0,0 +1,91 @@ +--- +title: "Team Management" +description: "Learn how to invite and manage team members in your CrewAI AMP organization" +icon: "users" +mode: "wide" +--- + +As an administrator of a CrewAI AMP account, you can easily invite new team members to join your organization. This guide will walk you through the process step-by-step. + +## Inviting Team Members + + + + - Log in to your CrewAI AMP account - Look for the gear icon (⚙️) in the top + right corner of the dashboard - Click on the gear icon to access the + **Settings** page: + + Settings Page + + + + - On the Settings page, you'll see a `Members` tab - Click on the `Members` + tab to access the **Members** page: + + Members Tab + + + + - In the Members section, you'll see a list of current members (including + yourself) - Locate the `Email` input field - Enter the email address of the + person you want to invite - Click the `Invite` button to send the invitation + + + - You can repeat this process to invite multiple team members - Each invited + member will receive an email invitation to join your organization + + + +## Adding Roles + +You can add roles to your team members to control their access to different parts of the platform. + + + + - Log in to your CrewAI AMP account - Look for the gear icon (⚙️) in the top + right corner of the dashboard - Click on the gear icon to access the + **Settings** page: + + Settings Page + + + + - On the Settings page, you'll see a `Roles` tab - Click on the `Roles` tab + to access the **Roles** page. + + Roles Tab + + - Click on the `Add Role` button to add a new role. - Enter the + details and permissions of the role and click the `Create Role` button to + create the role. + + Add Role Modal + + + + - In the Members section, you'll see a list of current members (including + yourself) + + Member Accepted Invitation + + - Once the member has accepted the invitation, you can add a role to + them. - Navigate back to `Roles` tab - Go to the member you want to add a + role to and under the `Role` column, click on the dropdown - Select the role + you want to add to the member - Click the `Update` button to save the role + + Add Role to Member + + + + +## Important Notes + +- **Admin Privileges**: Only users with administrative privileges can invite new members +- **Email Accuracy**: Ensure you have the correct email addresses for your team members +- **Invitation Acceptance**: Invited members will need to accept the invitation to join your organization +- **Email Notifications**: You may want to inform your team members to check their email (including spam folders) for the invitation + +By following these steps, you can easily expand your team and collaborate more effectively within your CrewAI AMP organization. diff --git a/docs/v1.15.1/en/enterprise/guides/tool-repository.mdx b/docs/v1.15.1/en/enterprise/guides/tool-repository.mdx new file mode 100644 index 000000000..850d4efe8 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/tool-repository.mdx @@ -0,0 +1,154 @@ +--- +title: Tool Repository +description: "Using the Tool Repository to manage your tools" +icon: "toolbox" +mode: "wide" +--- + +## Overview + +The Tool Repository is a package manager for CrewAI tools. It allows users to publish, install, and manage tools that integrate with CrewAI crews and flows. + +Tools can be: + +- **Private**: accessible only within your organization (default) +- **Public**: accessible to all CrewAI users if published with the `--public` flag + +The repository is not a version control system. Use Git to track code changes and enable collaboration. + +## Prerequisites + +Before using the Tool Repository, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account +- [CrewAI CLI](/en/concepts/cli#cli) installed +- uv>=0.5.0 installed. Check out [how to upgrade](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv) +- [Git](https://git-scm.com) installed and configured +- Access permissions to publish or install tools in your CrewAI AMP organization + +## Installing Tools + +To install a tool: + +```bash +crewai tool install +``` + +This installs the tool and adds it to `pyproject.toml`. + +You can use the tool by importing it and adding it to your agents: + +```python +from your_tool.tool import YourTool + +custom_tool = YourTool() + +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=[custom_tool], + verbose=True +) +``` + +## Adding other packages after installing a tool + +After installing a tool from the CrewAI AMP Tool Repository, you need to use the `crewai uv` command to add other packages to your project. +Using pure `uv` commands will fail due to authentication to tool repository being handled by the CLI. By using the `crewai uv` command, you can add other packages to your project without having to worry about authentication. +Any `uv` command can be used with the `crewai uv` command, making it a powerful tool for managing your project's dependencies without the hassle of managing authentication through environment variables or other methods. + +Say that you have installed a custom tool from the CrewAI AMP Tool Repository called "my-tool": + +```bash +crewai tool install my-tool +``` + +And now you want to add another package to your project, you can use the following command: + +```bash +crewai uv add requests +``` + +Other commands like `uv sync` or `uv remove` can also be used with the `crewai uv` command: + +```bash +crewai uv sync +``` + +```bash +crewai uv remove requests +``` + +This will add the package to your project and update `pyproject.toml` accordingly. + +## Creating and Publishing Tools + +To create a new tool project: + +```bash +crewai tool create +``` + +This generates a scaffolded tool project locally. + +After making changes, initialize a Git repository and commit the code: + +```bash +git init +git add . +git commit -m "Initial version" +``` + +To publish the tool: + +```bash +crewai tool publish +``` + +By default, tools are published as private. To make a tool public: + +```bash +crewai tool publish --public +``` + +For more details on how to build tools, see [Creating your own tools](/en/concepts/tools#creating-your-own-tools). + +## Updating Tools + +To update a published tool: + +1. Modify the tool locally +2. Update the version in `pyproject.toml` (e.g., from `0.1.0` to `0.1.1`) +3. Commit the changes and publish + +```bash +git commit -m "Update version to 0.1.1" +crewai tool publish +``` + +## Deleting Tools + +To delete a tool: + +1. Go to [CrewAI AMP](https://app.crewai.com) +2. Navigate to **Tools** +3. Select the tool +4. Click **Delete** + + + Deletion is permanent. Deleted tools cannot be restored or re-installed. + + +## Security Checks + +Every published version undergoes automated security checks, and are only available to install after they pass. + +You can check the security check status of a tool at: + +`CrewAI AMP > Tools > Your Tool > Versions` + + + Contact our support team for assistance with API integration or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/guides/training-crews.mdx b/docs/v1.15.1/en/enterprise/guides/training-crews.mdx new file mode 100644 index 000000000..8366ad641 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/training-crews.mdx @@ -0,0 +1,132 @@ +--- +title: "Training Crews" +description: "Train your deployed crews directly from the CrewAI AMP platform to improve agent performance over time" +icon: "dumbbell" +mode: "wide" +--- + +Training lets you improve crew performance by running iterative training sessions directly from the **Training** tab in CrewAI AMP. The platform uses **auto-train mode** — it handles the iterative process automatically, unlike CLI training which requires interactive human feedback per iteration. + +After training completes, CrewAI evaluates agent outputs and consolidates feedback into actionable suggestions for each agent. These suggestions are then applied to future crew runs to improve output quality. + + + For details on how CrewAI training works under the hood, see the [Training Concepts](/en/concepts/training) page. + + +## Prerequisites + + + + You need a CrewAI AMP account with an active deployment in **Ready** status (Crew type). + + + Your account must have run permission for the deployment you want to train. + + + +## How to train a crew + + + + Navigate to **Deployments**, click your deployment, then select the **Training** tab. + + + + Provide a **Training Name** — this becomes the `.pkl` filename used to store training results. For example, "Expert Mode Training" produces `expert_mode_training.pkl`. + + + + Enter the crew's input fields. These are the same inputs you'd provide for a normal kickoff — they're dynamically loaded based on your crew's configuration. + + + + Click **Train Crew**. The button changes to "Training..." with a spinner while the process runs. + + Behind the scenes: + - A training record is created for your deployment + - The platform calls the deployment's auto-train endpoint + - The crew runs its iterations automatically — no manual feedback required + + + + The **Current Training Status** panel displays: + - **Status** — Current state of the training run + - **Nº Iterations** — Number of training iterations configured + - **Filename** — The `.pkl` file being generated + - **Started At** — When training began + - **Training Inputs** — The inputs you provided + + + +## Understanding training results + +Once training completes, you'll see per-agent result cards with the following information: + +- **Agent Role** — The name/role of the agent in your crew +- **Final Quality** — A score from 0 to 10 evaluating the agent's output quality +- **Final Summary** — A summary of the agent's performance during training +- **Suggestions** — Actionable recommendations for improving the agent's behavior + +### Editing suggestions + +You can refine the suggestions for any agent: + + + + On any agent's result card, click the **Edit** button next to the suggestions. + + + + Update the suggestions text to better reflect the improvements you want. + + + + Click **Save**. The edited suggestions sync back to the deployment and are used in all future runs. + + + +## Using trained data + +To apply training results to your crew: + +1. Note the **Training Filename** (the `.pkl` file) from your completed training session. +2. Specify this filename in your deployment's kickoff or run configuration. +3. The crew automatically loads the training file and applies the stored suggestions to each agent. + +This means agents benefit from the feedback generated during training on every subsequent run. + +## Previous trainings + +The bottom of the Training tab displays a **history of all past training sessions** for the deployment. Use this to review previous training runs, compare results, or select a different training file to use. + +## Error handling + +If a training run fails, the status panel shows an error state along with a message describing what went wrong. + +Common causes of training failures: +- **Deployment runtime not updated** — Ensure your deployment is running the latest version +- **Crew execution errors** — Issues within the crew's task logic or agent configuration +- **Network issues** — Connectivity problems between the platform and the deployment + +## Limitations + + + Keep these constraints in mind when planning your training workflow: + - **One active training at a time** per deployment — wait for the current run to finish before starting another + - **Auto-train mode only** — the platform does not support interactive per-iteration feedback like the CLI does + - **Training data is deployment-specific** — training results are tied to the specific deployment instance and version + + +## Related resources + + + + Learn how CrewAI training works under the hood. + + + Run your deployed crew from the AMP platform. + + + Get your crew deployed and ready for training. + + diff --git a/docs/v1.15.1/en/enterprise/guides/update-crew.mdx b/docs/v1.15.1/en/enterprise/guides/update-crew.mdx new file mode 100644 index 000000000..991b3248a --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/update-crew.mdx @@ -0,0 +1,91 @@ +--- +title: "Update Crew" +description: "Updating a Crew on CrewAI AMP" +icon: "pencil" +mode: "wide" +--- + + + After deploying your crew to CrewAI AMP, you may need to make updates to the + code, security settings, or configuration. This guide explains how to perform + these common update operations. + + +## Why Update Your Crew? + +CrewAI won't automatically pick up GitHub updates by default, so you'll need to manually trigger updates, unless you checked the `Auto-update` option when deploying your crew. + +There are several reasons you might want to update your crew deployment: + +- You want to update the code with a latest commit you pushed to GitHub +- You want to reset the bearer token for security reasons +- You want to update environment variables + +## 1. Updating Your Crew Code for a Latest Commit + +When you've pushed new commits to your GitHub repository and want to update your deployment: + +1. Navigate to your crew in the CrewAI AMP platform +2. Click on the `Re-deploy` button on your crew details page + +![Re-deploy Button](/images/enterprise/redeploy-button.png) + +This will trigger an update that you can track using the progress bar. The system will pull the latest code from your repository and rebuild your deployment. + +## 2. Resetting Bearer Token + +If you need to generate a new bearer token (for example, if you suspect the current token might have been compromised): + +1. Navigate to your crew in the CrewAI AMP platform +2. Find the `Bearer Token` section +3. Click the `Reset` button next to your current token + +![Reset Token](/images/enterprise/reset-token.png) + + + Resetting your bearer token will invalidate the previous token immediately. + Make sure to update any applications or scripts that are using the old token. + + +## 3. Updating Environment Variables + +To update the environment variables for your crew: + +1. First access the deployment page by clicking on your crew's name + + + ![Environment Variables Button](/images/enterprise/env-vars-button.png) + + +2. Locate the `Environment Variables` section (you will need to click the `Settings` icon to access it) +3. Edit the existing variables or add new ones in the fields provided +4. Click the `Update` button next to each variable you modify + + + ![Update Environment Variables](/images/enterprise/update-env-vars.png) + + +5. Finally, click the `Update Deployment` button at the bottom of the page to apply the changes + + + Updating environment variables will trigger a new deployment, but this will + only update the environment configuration and not the code itself. + + +## After Updating + +After performing any update: + +1. The system will rebuild and redeploy your crew +2. You can monitor the deployment progress in real-time +3. Once complete, test your crew to ensure the changes are working as expected + + + If you encounter any issues after updating, you can view deployment logs in + the platform or contact support for assistance. + + + + Contact our support team for assistance with updating your crew or + troubleshooting deployment issues. + diff --git a/docs/v1.15.1/en/enterprise/guides/vertex-ai-workload-identity-setup.mdx b/docs/v1.15.1/en/enterprise/guides/vertex-ai-workload-identity-setup.mdx new file mode 100644 index 000000000..a13a73c17 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/vertex-ai-workload-identity-setup.mdx @@ -0,0 +1,295 @@ +--- +title: "Vertex AI with Workload Identity" +description: "Connect Google Vertex AI to CrewAI AMP with no service account keys — credentials are minted per-execution via OIDC workload identity federation." +icon: "google" +mode: "wide" +--- + + +Workload identity for LLM connections is currently available to enterprise SaaS customers on CrewAI AMP. Contact your CrewAI account team to enable it for your organization before starting this guide. + + +## Version requirements + +| Component | Required version | Notes | +|---|---|---| +| **CrewAI AMP** | Early access (per-organization feature flag) | Contact CrewAI support to enable **Workload Identity Configs** and **LLM workload identity** on your org. | +| **CrewAI Python SDK (`crewai`)** | **`1.14.3` or higher** | Crews built from this version (or later) include the OIDC token fetch and GCP credential setup needed for Vertex workload identity. | +| **LLM provider** | **Google Gen AI SDK** (`google/` model prefix) | Required. LiteLLM's `vertex_ai/*` provider is **not** supported with workload identity. Use the `google/` prefix on your LLM connection's model field — for example `google/gemini-2.5-pro`, `google/gemini-2.5-flash`, `google/gemini-2.0-flash`. | +| **Google Cloud APIs** | `iam.googleapis.com`, `iamcredentials.googleapis.com`, `sts.googleapis.com`, `aiplatform.googleapis.com` | All four must be enabled on the target project (see [Part 1, step 1](#part-1-gcp-setup)). | + + +**Use the `google/` model prefix, not `vertex_ai/`.** Workload identity requires the native Google Gen AI SDK route, which uses Application Default Credentials. The LiteLLM `vertex_ai/*` provider does not consume the ADC config the runtime writes, so calls will fail to authenticate. + + +## Overview + +CrewAI AMP can authenticate to Google Vertex AI using **GCP Workload Identity Federation** instead of long-lived service account keys. At kickoff, your crew execution fetches a short-lived OIDC token from AMP scoped to your organization and writes a Google **Application Default Credentials (ADC)** `external_account` configuration that points at it. The Google Gen AI SDK (invoked via CrewAI's `google/` model prefix) then transparently exchanges that OIDC token at GCP STS, optionally impersonates a service account, and calls Vertex AI — all in-process inside the running crew. + +The result: + +- **No Google credentials stored in CrewAI AMP** — no service account JSON keys, no API keys. AMP holds only the OIDC signing key it uses to mint tokens. +- **Trust is anchored in your GCP project.** You decide which CrewAI organization can impersonate which service account. +- **The STS exchange happens inside the crew execution**, not in AMP's control plane. AMP only mints OIDC tokens; the Google credentials returned by GCP are never seen or persisted by AMP — they live and die inside a single execution. +- **Access tokens are refreshed automatically**, and the underlying OIDC subject token is rotated before expiry — long-running crews are supported (with one edge case noted below). + +### How it works + +```mermaid +sequenceDiagram + participant Crew as Crew execution + participant AMP as CrewAI AMP + participant STS as GCP STS + participant IAM as IAM Credentials API + participant Vertex as Vertex AI + + Crew->>AMP: Request OIDC JWT (aud = WI provider) + AMP-->>Crew: OIDC JWT + Note over Crew: Write GOOGLE_APPLICATION_CREDENTIALS
external_account ADC file + Crew->>STS: Exchange JWT (via google-auth) + Note right of STS: Validate via JWKS
+ attribute condition + STS-->>Crew: Federated token + Crew->>IAM: generateAccessToken (impersonate SA) + IAM-->>Crew: SA access token + Crew->>Vertex: generateContent / predict +``` + +GCP fetches AMP's public signing keys from a standard OIDC discovery endpoint and validates each token before exchanging it. AMP never sees your GCP service account key, and the federated/SA tokens minted by GCP stay inside the crew execution that requested them — they are not returned to or persisted by AMP's control plane. + +--- + +## Prerequisites + +- A GCP project with Vertex AI enabled (`aiplatform.googleapis.com`). +- The `gcloud` CLI authenticated as a user with IAM admin on that project. See [Appendix: minimum IAM](#appendix-minimum-iam-for-setup) for the specific roles required. +- Your **CrewAI organization UUID**. Find it in CrewAI AMP at **Settings → Organization** (use the UUID, not the numeric ID). +- Workload identity for LLM connections enabled on your AMP organization — contact CrewAI support. + +The CrewAI AMP OIDC issuer URL is: + +``` +https://app.crewai.com +``` + +--- + +## Part 1 — GCP setup + + + + ```bash + gcloud services enable \ + iam.googleapis.com \ + iamcredentials.googleapis.com \ + sts.googleapis.com \ + aiplatform.googleapis.com \ + --project=PROJECT_ID + ``` + + + + ```bash + gcloud iam workload-identity-pools create crewai-amp \ + --project=PROJECT_ID \ + --location=global \ + --display-name="CrewAI AMP" + ``` + + + + The `attribute-condition` is the **critical security boundary** — it restricts which CrewAI organization can assume any identity from this pool. Replace `YOUR_ORG_UUID` with your AMP organization UUID. + + ```bash + gcloud iam workload-identity-pools providers create-oidc crewai-amp-oidc \ + --project=PROJECT_ID \ + --location=global \ + --workload-identity-pool=crewai-amp \ + --issuer-uri="https://app.crewai.com" \ + --attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \ + --attribute-condition="assertion.organization_id == 'YOUR_ORG_UUID'" + ``` + + + `YOUR_ORG_UUID` must be your organization **UUID** (the same value used by `attribute.organization` in the principalSet binding below). A wrong value here is the most common cause of `PERMISSION_DENIED` failures during STS exchange. + + + Record the full provider resource name — you'll need it in Part 2: + + ```bash + gcloud iam workload-identity-pools providers describe crewai-amp-oidc \ + --project=PROJECT_ID \ + --location=global \ + --workload-identity-pool=crewai-amp \ + --format="value(name)" + # projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/providers/crewai-amp-oidc + ``` + + + + `crewai-vertex` is an example name — pick anything that fits your naming conventions, but use the same value in the impersonation binding (next step) and on the LLM connection (Part 2). + + ```bash + gcloud iam service-accounts create crewai-vertex \ + --project=PROJECT_ID \ + --display-name="CrewAI AMP — Vertex AI" + + gcloud projects add-iam-policy-binding PROJECT_ID \ + --member="serviceAccount:crewai-vertex@PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/aiplatform.user" + ``` + + `roles/aiplatform.user` is the minimum role needed for `generateContent` and `predict`. Tighten further with custom roles if your security policy requires it. + + + + This is the second security boundary: only federated identities whose `organization` attribute matches your org UUID can impersonate this SA. + + ```bash + gcloud iam service-accounts add-iam-policy-binding \ + crewai-vertex@PROJECT_ID.iam.gserviceaccount.com \ + --project=PROJECT_ID \ + --role="roles/iam.workloadIdentityUser" \ + --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/attribute.organization/YOUR_ORG_UUID" + ``` + + + +--- + +## Part 2 — CrewAI AMP setup + + + + In AMP, go to **Settings → Workload Identity Configs → New** and fill in: + + | Field | Value | + |---|---| + | **Name** | A memorable label, e.g. `vertex-ai-prod` | + | **Cloud provider** | `GCP` | + | **GCP Workload Identity Provider** | The full resource name from Part 1, step 3 (`projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/providers/crewai-amp-oidc`) | + | **Default for GCP** | Optional — marks this as the default GCP config for new connections | + + Creating workload identity configs requires a role with **manage** access to LLM connections (see [RBAC](/en/enterprise/features/rbac)). + + + + Go to **LLM Connections → New** (or edit an existing one) and select: + + - **Provider:** `Vertex` + - **Workload Identity Config:** the config from the previous step + - **GCP Service Account Email:** the SA you created in Part 1 (e.g., `crewai-vertex@PROJECT_ID.iam.gserviceaccount.com`) + + No `GOOGLE_API_KEY` environment variable is required — leave that empty. For region, add a single connection-scoped env var: + + - `GOOGLE_CLOUD_LOCATION=global` — recommended default. Vertex's `global` endpoint provides higher availability and is supported by current Gemini 2.x and 3.x models. Set a specific region (e.g. `us-central1`, `europe-west4`) if you need data residency (the global endpoint does **not** guarantee in-region processing) or if you plan to use Vertex features that don't run on `global` (notably **tuning**, **batch prediction** for Anthropic / OpenMaaS models, and **RAG corpus management** — RAG *requests* still work on global). For chat/completion crews, `global` is the right choice. + + + Service account impersonation is configured per-connection (not per-config) so a single workload identity pool can be reused for multiple service accounts with different Vertex permissions. + + + + + Attach the LLM connection to a crew, Studio project, or deployment exactly as you would any other LLM connection. At kickoff, the running crew will request an OIDC token from AMP for this connection's workload identity provider and exchange it for Vertex credentials in-process — no Google credentials are stored or pushed by AMP. + + + +--- + +## Runtime behavior + +For Vertex connections backed by workload identity, the crew does **not** receive a `GOOGLE_API_KEY` or service account JSON as a static deploy-time env var. Instead, at kickoff, the running crew: + +1. Fetches an OIDC token from AMP, signed with AMP's private key and scoped to your organization (audience = your workload identity provider). +2. Writes the JWT to a temporary file in the execution environment. +3. Writes a Google **Application Default Credentials (ADC)** config of type `external_account` that references the JWT file, your STS audience, and (optionally) the service account impersonation URL. +4. Sets the following environment variables for the crew process: + + | Env var | Value | + |---|---| + | `GOOGLE_APPLICATION_CREDENTIALS` | Path to the temporary ADC `external_account` config file | + | `GOOGLE_CLOUD_PROJECT` | Your GCP project number, parsed from the workload identity provider resource name (Google Gen AI SDK accepts either the project ID or the project number) | + + No `GOOGLE_API_KEY` and no `GOOGLE_CLOUD_LOCATION` are set automatically. Configure `GOOGLE_CLOUD_LOCATION` on your LLM connection in AMP (recommended default: `global`). + +5. From this point on, **`google-auth`** (used by the Google Gen AI SDK) does the STS exchange and SA impersonation transparently on the first Vertex API call, and caches/refreshes the resulting access token automatically. + +The crew SDK reads these like any other env var — no code changes required, provided your crew was deployed against **`crewai>=1.14.3`** (see [Version requirements](#version-requirements)). + +### Long-running crews + +Access tokens are **automatically refreshed**: + +- **Vertex access tokens** (1-hour TTL) are refreshed by `google-auth` in-process, transparently to your crew code. +- **The underlying OIDC subject token** (also 1-hour TTL) is rotated before expiry on every kickoff entry point. The crew fetches a fresh OIDC JWT from AMP and rewrites the ADC token file; subsequent STS exchanges pick up the new JWT. + +In practice this means: + +- Crews that run for **less than 1 hour** never trigger a refresh — the initial token covers the whole execution. +- Crews that run for **multiple hours** continue to function as long as kickoff entry points (sync hops, agent steps, etc.) fire during the execution; the refresh buffer ensures the OIDC token is rotated before STS rejects it. +- If a single Vertex API call runs for more than 1 hour (very unusual — typical Gemini responses return in seconds), the OIDC token can expire mid-request and the call will fail. This is the one scenario where token refresh cannot help. + +--- + +## Verification + +Run a crew that uses the Vertex connection and tail the execution logs in AMP. A successful `generateContent` or `predict` call confirms the full chain — OIDC mint → STS exchange → SA impersonation → Vertex — is wired correctly. + +If the crew fails, see [Troubleshooting](#troubleshooting) below. Most issues trace back to the GCP-side configuration — the OIDC provider's `attribute-condition` or the service account's `principalSet` binding. + +### Inspecting on the GCP side + +You can confirm tokens are being exchanged by looking at **Cloud Audit Logs** in your GCP project: + +- Service: `sts.googleapis.com` → method `google.identity.sts.v1.SecurityTokenService.ExchangeToken` +- Service: `iamcredentials.googleapis.com` → method `GenerateAccessToken` + +A short crew execution produces one `ExchangeToken` and one `GenerateAccessToken` entry; longer executions produce additional entries each time the OIDC token is rotated. The `protoPayload.authenticationInfo` includes the `sub` and `organization_id` claims, useful for audit and incident response. + +--- + +## Troubleshooting + +| Symptom | Likely cause | +|---|---| +| AMP UI doesn't show **Workload Identity Configs** | Feature isn't enabled for your organization — contact CrewAI support. | +| AMP UI rejects attaching a config to an LLM connection | The connection's provider must be `Vertex` (GCP). | +| GCP STS returns `PERMISSION_DENIED: The given credential is rejected by the attribute condition` | Org UUID mismatch — typically the numeric org ID was used instead of the UUID, or the UUID in the attribute condition is wrong. | +| GCP STS returns `INVALID_ARGUMENT: Invalid JWT` | Issuer URL in the provider doesn't match `https://app.crewai.com`, or GCP's JWKS cache is stale (wait up to 1 hour, or recreate the provider). | +| `generateAccessToken` returns `PERMISSION_DENIED` | The pool member is missing `roles/iam.workloadIdentityUser` on the service account, or the `principalSet` in the binding uses the wrong attribute path. | +| Vertex returns `PERMISSION_DENIED` on `generateContent` | The service account is missing `roles/aiplatform.user` (or an equivalent custom role) on the project. | +| Crew fails immediately with `DefaultCredentialsError: File was not found` | The ADC token file was cleaned up — typically because the execution process was forked after credentials initialized. Re-kickoff the crew. If it persists, bump `crewai>=1.14.3` in your `pyproject.toml` and re-deploy. | +| Crew fails with `DefaultCredentialsError` and no `GOOGLE_APPLICATION_CREDENTIALS` is set in the execution env | Your crew was deployed against a pre-`1.14.3` `crewai`, so no ADC file was written and no API-key fallback exists for workload identity connections. Bump `crewai>=1.14.3` in your `pyproject.toml` and re-deploy. | +| Crew fails after ~1 hour with `invalid_grant` from STS | The OIDC subject token expired and refresh did not fire — typically because a single in-process call held the execution past the refresh buffer. If this reproduces, contact CrewAI support with the failing execution ID. | +| Vertex calls fail with `Unable to locate project` | `GOOGLE_CLOUD_PROJECT` was not parsed — your workload identity provider resource name in AMP doesn't match the `projects/PROJECT_NUMBER/...` format. Re-check the provider value copied from `gcloud iam workload-identity-pools providers describe`. | +| Vertex calls fail with `region`/`location` errors | `GOOGLE_CLOUD_LOCATION` isn't set on the LLM connection. Add it as a connection-scoped env var (`global` is the recommended default). | +| Vertex returns `model not found` or `not available in location` | The chosen region doesn't host the requested model. Switch the connection's `GOOGLE_CLOUD_LOCATION` to `global`, or pick a region known to host the model. | +| Vertex calls fail to authenticate despite a working WI config | The model identifier uses the `vertex_ai/` (LiteLLM) prefix instead of `google/`. Workload identity only works through the Google Gen AI SDK route — change the model to `google/`. | + +--- + +## Security notes + +- **The `organization_id` claim is your security boundary.** Your GCP attribute condition **must** restrict to your organization UUID. Without it, any CrewAI AMP organization could exchange a token through your pool. The `sub` claim contains the same UUID prefixed with `organization:` — either could be used, but `organization_id` matches the bare-UUID form used in the `attribute.organization` mapping and `principalSet` binding. +- **Service account impersonation is the second boundary.** The `principalSet` binding restricts impersonation to identities whose `organization` attribute matches your UUID. Use it even when the attribute condition is set — defense in depth. +- **Issuer trust is one-way.** GCP fetches AMP's public JWKS over HTTPS. AMP never receives any GCP credential. + +--- + +## Appendix: minimum IAM for setup + +The user running the `gcloud` commands above needs, on the target project: + +- `roles/iam.workloadIdentityPoolAdmin` — create pools and providers +- `roles/iam.serviceAccountAdmin` — create service accounts +- `roles/resourcemanager.projectIamAdmin` — bind project-level roles +- `roles/serviceusage.serviceUsageAdmin` — enable required APIs + +Or, equivalently, `roles/owner` on the project. + +--- + +## Related + +- [Single Sign-On (SSO)](/en/enterprise/features/sso) — Authentication for the AMP UI and CLI (separate system from LLM workload identity) +- [Azure OpenAI Setup](/en/enterprise/guides/azure-openai-setup) — Static-key alternative for Azure OpenAI +- [GCP: Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) — Google's reference docs diff --git a/docs/v1.15.1/en/enterprise/guides/webhook-automation.mdx b/docs/v1.15.1/en/enterprise/guides/webhook-automation.mdx new file mode 100644 index 000000000..399ce0728 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/webhook-automation.mdx @@ -0,0 +1,157 @@ +--- +title: "Webhook Automation" +description: "Automate CrewAI AMP workflows using webhooks with platforms like ActivePieces, Zapier, and Make.com" +icon: "webhook" +mode: "wide" +--- + +CrewAI AMP allows you to automate your workflow using webhooks. This article will guide you through the process of setting up and using webhooks to kickoff your crew execution, with a focus on integration with ActivePieces, a workflow automation platform similar to Zapier and Make.com. + +## Setting Up Webhooks + + + + - Navigate to the CrewAI AMP dashboard + - Look for the `/kickoff` section, which is used to start the crew execution + + Kickoff Interface + + + + + In the JSON Content section, you'll need to provide the following information: + + - **inputs**: A JSON object containing: + - `company`: The name of the company (e.g., "tesla") + - `product_name`: The name of the product (e.g., "crewai") + - `form_response`: The type of response (e.g., "financial") + - `icp_description`: A brief description of the Ideal Customer Profile + - `product_description`: A short description of the product + - `taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`: URLs for various webhook endpoints (ActivePieces, Zapier, Make.com or another compatible platform) + + + + In this example we will be using ActivePieces. You can use other platforms such as Zapier and Make.com + + To integrate with ActivePieces: + + 1. Set up a new flow in ActivePieces + 2. Add a trigger (e.g., `Every Day` schedule) + + ActivePieces Trigger + + + 3. Add an HTTP action step + - Set the action to `Send HTTP request` + - Use `POST` as the method + - Set the URL to your CrewAI AMP kickoff endpoint + - Add necessary headers (e.g., `Bearer Token`) + + ActivePieces Headers + + + - In the body, include the JSON content as configured in step 2 + + ActivePieces Body + + + - The crew will then kickoff at the pre-defined time. + + + + 1. Create a new flow in ActivePieces and name it + + ActivePieces Flow + + + 2. Add a webhook step as the trigger: + - Select `Catch Webhook` as the trigger type + - This will generate a unique URL that will receive HTTP requests and trigger your flow + + ActivePieces Webhook + + + - Configure the email to use crew webhook body text + + ActivePieces Email + + + + + +## Webhook Output Examples + +**Note:** Any `meta` object provided in your kickoff request will be included in all webhook payloads, allowing you to track requests and maintain context across the entire crew execution lifecycle. + + + + `stepWebhookUrl` - Callback that will be executed upon each agent inner thought + + ```json + { + "prompt": "Research the financial industry for potential AI solutions", + "thought": "I need to conduct preliminary research on the financial industry", + "tool": "research_tool", + "tool_input": "financial industry AI solutions", + "result": "**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.", + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + `taskWebhookUrl` - Callback that will be executed upon the end of each 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.", + "name": "Industry Research Task", + "expected_output": "Detailed research report on the financial industry", + "summary": "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.", + "agent": "Research Agent", + "output": "**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.", + "output_json": { + "industry": "financial", + "key_opportunities": ["digital customer engagement", "risk management", "regulatory compliance"] + }, + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + `crewWebhookUrl` - Callback that will be executed upon the end of the crew execution + + ```json + { + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "result": "**Final Analysis Report**\n\nLead Score: Customer service enhancement and compliance are particularly relevant.\n\nTalking Points:\n- Highlight how crewai's AI solutions can transform customer service\n- Discuss crewai's potential for sustainability goals\n- Emphasize compliance capabilities\n- Stress adaptability for various operation scales", + "result_json": { + "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." + ] + }, + "token_usage": { + "total_tokens": 1250, + "prompt_tokens": 800, + "completion_tokens": 450 + }, + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + diff --git a/docs/v1.15.1/en/enterprise/guides/zapier-trigger.mdx b/docs/v1.15.1/en/enterprise/guides/zapier-trigger.mdx new file mode 100644 index 000000000..74400b884 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/guides/zapier-trigger.mdx @@ -0,0 +1,105 @@ +--- +title: "Zapier Trigger" +description: "Trigger CrewAI crews from Zapier workflows to automate cross-app workflows" +icon: "bolt" +mode: "wide" +--- + +This guide will walk you through the process of setting up Zapier triggers for CrewAI AMP, allowing you to automate workflows between CrewAI AMP and other applications. + +## Prerequisites + +- A CrewAI AMP account +- A Zapier account +- A Slack account (for this specific example) + +## Step-by-Step Setup + + + + - In Zapier, create a new Zap. + + + Zapier 1 + + + + + + Zapier 2 + + - Select `New Pushed Message` as the Trigger Event. + - Connect your Slack account if you haven't already. + + + + - Add a new action step to your Zap. + - Choose CrewAI+ as your action app and Kickoff as the Action Event + + + Zapier 5 + + + + + - Connect your CrewAI AMP account. + - Select the appropriate Crew for your workflow. + + + Zapier 6 + + - Configure the inputs for the Crew using the data from the Slack message. + + + + - Add another action step to format the text output from CrewAI AMP. + - Use Zapier's formatting tools to convert the Markdown output to HTML. + + + Zapier 8 + + + Zapier 9 + + + + + - Add a final action step to send the formatted output via email. + - Choose your preferred email service (e.g., Gmail, Outlook). + - Configure the email details, including recipient, subject, and body. + - Insert the formatted CrewAI AMP output into the email body. + + + Zapier 7 + + + + + - Enter the text in your Slack channel + + + Zapier 10 + + + - Select the 3 ellipsis button and then chose Push to Zapier + + + Zapier 11 + + + + + + Zapier 12 + + + + + +## Tips for Success + +- Ensure that your CrewAI AMP inputs are correctly mapped from the Slack message. +- Test your Zap thoroughly before turning it on to catch any potential issues. +- Consider adding error handling steps to manage potential failures in the workflow. + +By following these steps, you'll have successfully set up Zapier triggers for CrewAI AMP, allowing for automated workflows triggered by Slack messages and resulting in email notifications with CrewAI AMP output. diff --git a/docs/v1.15.1/en/enterprise/integrations/asana.mdx b/docs/v1.15.1/en/enterprise/integrations/asana.mdx new file mode 100644 index 000000000..4b025b674 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/asana.mdx @@ -0,0 +1,272 @@ +--- +title: Asana Integration +description: "Team task and project coordination with Asana integration for CrewAI." +icon: "circle" +mode: "wide" +--- + +## Overview + +Enable your agents to manage tasks, projects, and team coordination through Asana. Create tasks, update project status, manage assignments, and streamline your team's workflow with AI-powered automation. + +## Prerequisites + +Before using the Asana integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- An Asana account with appropriate permissions +- Connected your Asana account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Asana Integration + +### 1. Connect Your Asana Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Asana** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for task and project management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create a comment in Asana. + + **Parameters:** + - `task` (string, required): Task ID - The ID of the Task the comment will be added to. The comment will be authored by the currently authenticated user. + - `text` (string, required): Text (example: "This is a comment."). + + + + + **Description:** Create a project in Asana. + + **Parameters:** + - `name` (string, required): Name (example: "Stuff to buy"). + - `workspace` (string, required): Workspace - Use Connect Portal Workflow Settings to allow users to select which Workspace to create Projects in. Defaults to the user's first Workspace if left blank. + - `team` (string, optional): Team - Use Connect Portal Workflow Settings to allow users to select which Team to share this Project with. Defaults to the user's first Team if left blank. + - `notes` (string, optional): Notes (example: "These are things we need to purchase."). + + + + + **Description:** Get a list of projects in Asana. + + **Parameters:** + - `archived` (string, optional): Archived - Choose "true" to show archived projects, "false" to display only active projects, or "default" to show both archived and active projects. + - Options: `default`, `true`, `false` + + + + + **Description:** Get a project by ID in Asana. + + **Parameters:** + - `projectFilterId` (string, required): Project ID. + + + + + **Description:** Create a task in Asana. + + **Parameters:** + - `name` (string, required): Name (example: "Task Name"). + - `workspace` (string, optional): Workspace - Use Connect Portal Workflow Settings to allow users to select which Workspace to create Tasks in. Defaults to the user's first Workspace if left blank.. + - `project` (string, optional): Project - Use Connect Portal Workflow Settings to allow users to select which Project to create this Task in. + - `notes` (string, optional): Notes. + - `dueOnDate` (string, optional): Due On - The date on which this task is due. Cannot be used together with Due At. (example: "YYYY-MM-DD"). + - `dueAtDate` (string, optional): Due At - The date and time (ISO timestamp) at which this task is due. Cannot be used together with Due On. (example: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, optional): Assignee - The ID of the Asana user this task will be assigned to. Use Connect Portal Workflow Settings to allow users to select an Assignee. + - `gid` (string, optional): External ID - An ID from your application to associate this task with. You can use this ID to sync updates to this task later. + + + + + **Description:** Update a task in Asana. + + **Parameters:** + - `taskId` (string, required): Task ID - The ID of the Task that will be updated. + - `completeStatus` (string, optional): Completed Status. + - Options: `true`, `false` + - `name` (string, optional): Name (example: "Task Name"). + - `notes` (string, optional): Notes. + - `dueOnDate` (string, optional): Due On - The date on which this task is due. Cannot be used together with Due At. (example: "YYYY-MM-DD"). + - `dueAtDate` (string, optional): Due At - The date and time (ISO timestamp) at which this task is due. Cannot be used together with Due On. (example: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, optional): Assignee - The ID of the Asana user this task will be assigned to. Use Connect Portal Workflow Settings to allow users to select an Assignee. + - `gid` (string, optional): External ID - An ID from your application to associate this task with. You can use this ID to sync updates to this task later. + + + + + **Description:** Get a list of tasks in Asana. + + **Parameters:** + - `workspace` (string, optional): Workspace - The ID of the Workspace to filter tasks on. Use Connect Portal Workflow Settings to allow users to select a Workspace. + - `project` (string, optional): Project - The ID of the Project to filter tasks on. Use Connect Portal Workflow Settings to allow users to select a Project. + - `assignee` (string, optional): Assignee - The ID of the assignee to filter tasks on. Use Connect Portal Workflow Settings to allow users to select an Assignee. + - `completedSince` (string, optional): Completed since - Only return tasks that are either incomplete or that have been completed since this time (ISO or Unix timestamp). (example: "2014-04-25T16:15:47-04:00"). + + + + + **Description:** Get a list of tasks by ID in Asana. + + **Parameters:** + - `taskId` (string, required): Task ID. + + + + + **Description:** Get a task by external ID in Asana. + + **Parameters:** + - `gid` (string, required): External ID - The ID that this task is associated or synced with, from your application. + + + + + **Description:** Add a task to a section in Asana. + + **Parameters:** + - `sectionId` (string, required): Section ID - The ID of the section to add this task to. + - `taskId` (string, required): Task ID - The ID of the task. (example: "1204619611402340"). + - `beforeTaskId` (string, optional): Before Task ID - The ID of a task in this section that this task will be inserted before. Cannot be used with After Task ID. (example: "1204619611402340"). + - `afterTaskId` (string, optional): After Task ID - The ID of a task in this section that this task will be inserted after. Cannot be used with Before Task ID. (example: "1204619611402340"). + + + + + **Description:** Get a list of teams in Asana. + + **Parameters:** + - `workspace` (string, required): Workspace - Returns the teams in this workspace visible to the authorized user. + + + + + **Description:** Get a list of workspaces in Asana. + + **Parameters:** None required. + + + + +## Usage Examples + +### Basic Asana Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Asana capabilities +asana_agent = Agent( + role="Project Manager", + goal="Manage tasks and projects in Asana efficiently", + backstory="An AI assistant specialized in project management and task coordination.", + apps=['asana'] # All Asana actions will be available +) + +# 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() +``` + +### Filtering Specific Asana Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Asana actions only +task_manager_agent = Agent( + role="Task Manager", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and management.", + apps=[ + 'asana/create_task', + 'asana/update_task', + 'asana/get_tasks' + ] # Specific Asana actions +) + +# 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() +``` + +### Advanced Project Management + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate project activities and track progress", + backstory="An experienced project coordinator who ensures projects run smoothly.", + apps=['asana'] +) + +# Complex task involving multiple Asana operations +coordination_task = Task( + description=""" + 1. Get all active projects in the workspace + 2. For each project, get the list of incomplete tasks + 3. Create a summary report task in the 'Management Reports' project + 4. Add comments to overdue tasks to request status updates + """, + agent=project_coordinator, + expected_output="Summary report created and status update requests sent for overdue tasks" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/en/enterprise/integrations/box.mdx b/docs/v1.15.1/en/enterprise/integrations/box.mdx new file mode 100644 index 000000000..d6e80898b --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/box.mdx @@ -0,0 +1,281 @@ +--- +title: Box Integration +description: "File storage and document management with Box integration for CrewAI." +icon: "box" +mode: "wide" +--- + +## Overview + +Enable your agents to manage files, folders, and documents through Box. Upload files, organize folder structures, search content, and streamline your team's document management with AI-powered automation. + +## Prerequisites + +Before using the Box integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Box account with appropriate permissions +- Connected your Box account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Box Integration + +### 1. Connect Your Box Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Box** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for file and folder management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Save a file from URL in Box. + + **Parameters:** + - `fileAttributes` (object, required): Attributes - File metadata including name, parent folder, and timestamps. + ```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, required): File URL - Files must be smaller than 50MB in size. (example: "https://picsum.photos/200/300"). + + + + + **Description:** Save a file in Box. + + **Parameters:** + - `file` (string, required): File - Accepts a File Object containing file data. Files must be smaller than 50MB in size. + - `fileName` (string, required): File Name (example: "qwerty.png"). + - `folder` (string, optional): Folder - Use Connect Portal Workflow Settings to allow users to select the File's Folder destination. Defaults to the user's root folder if left blank. + + + + + **Description:** Get a file by ID in Box. + + **Parameters:** + - `fileId` (string, required): File ID - The unique identifier that represents a file. (example: "12345"). + + + + + **Description:** List files in Box. + + **Parameters:** + - `folderId` (string, required): Folder ID - The unique identifier that represents a folder. (example: "0"). + - `filterFormula` (object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "direction", + "operator": "$stringExactlyMatches", + "value": "ASC" + } + ] + } + ] + } + ``` + + + + + **Description:** Create a folder in Box. + + **Parameters:** + - `folderName` (string, required): Name - The name for the new folder. (example: "New Folder"). + - `folderParent` (object, required): Parent Folder - The parent folder where the new folder will be created. + ```json + { + "id": "123456" + } + ``` + + + + + **Description:** Move a folder in Box. + + **Parameters:** + - `folderId` (string, required): Folder ID - The unique identifier that represents a folder. (example: "0"). + - `folderName` (string, required): Name - The name for the folder. (example: "New Folder"). + - `folderParent` (object, required): Parent Folder - The new parent folder destination. + ```json + { + "id": "123456" + } + ``` + + + + + **Description:** Get a folder by ID in Box. + + **Parameters:** + - `folderId` (string, required): Folder ID - The unique identifier that represents a folder. (example: "0"). + + + + + **Description:** Search folders in Box. + + **Parameters:** + - `folderId` (string, required): Folder ID - The folder to search within. + - `filterFormula` (object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "sort", + "operator": "$stringExactlyMatches", + "value": "name" + } + ] + } + ] + } + ``` + + + + + **Description:** Delete a folder in Box. + + **Parameters:** + - `folderId` (string, required): Folder ID - The unique identifier that represents a folder. (example: "0"). + - `recursive` (boolean, optional): Recursive - Delete a folder that is not empty by recursively deleting the folder and all of its content. + + + + +## Usage Examples + +### Basic Box Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Box capabilities +box_agent = Agent( + role="Document Manager", + goal="Manage files and folders in Box efficiently", + backstory="An AI assistant specialized in document management and file organization.", + apps=['box'] # All Box actions will be available +) + +# 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() +``` + +### Filtering Specific Box Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Box actions only +file_organizer_agent = Agent( + role="File Organizer", + goal="Organize and manage file storage efficiently", + backstory="An AI assistant that focuses on file organization and storage management.", + apps=['box/create_folder', 'box/save_file', 'box/list_files'] # Specific Box actions +) + +# 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() +``` + +### Advanced File Management + +```python +from crewai import Agent, Task, Crew + +file_manager = Agent( + role="File Manager", + goal="Maintain organized file structure and manage document lifecycle", + backstory="An experienced file manager who ensures documents are properly organized and accessible.", + apps=['box'] +) + +# Complex task involving multiple Box operations +management_task = Task( + description=""" + 1. List all files in the root folder + 2. Create monthly archive folders for the current year + 3. Move old files to appropriate archive folders + 4. Generate a summary report of the file organization + """, + agent=file_manager, + expected_output="Files organized into archive structure with summary report" +) + +crew = Crew( + agents=[file_manager], + tasks=[management_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/en/enterprise/integrations/clickup.mdx b/docs/v1.15.1/en/enterprise/integrations/clickup.mdx new file mode 100644 index 000000000..cc83388cb --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/clickup.mdx @@ -0,0 +1,302 @@ +--- +title: ClickUp Integration +description: "Task and productivity management with ClickUp integration for CrewAI." +icon: "list-check" +mode: "wide" +--- + +## Overview + +Enable your agents to manage tasks, projects, and productivity workflows through ClickUp. Create and update tasks, organize projects, manage team assignments, and streamline your productivity management with AI-powered automation. + +## Prerequisites + +Before using the ClickUp integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A ClickUp account with appropriate permissions +- Connected your ClickUp account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up ClickUp Integration + +### 1. Connect Your ClickUp Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **ClickUp** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for task and project management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Search for tasks in ClickUp using advanced filters. + + **Parameters:** + - `taskFilterFormula` (object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "statuses%5B%5D", + "operator": "$stringExactlyMatches", + "value": "open" + } + ] + } + ] + } + ``` + Available fields: `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` + + + + + **Description:** Get tasks in a specific list in ClickUp. + + **Parameters:** + - `listId` (string, required): List - Select a List to get tasks from. Use Connect Portal User Settings to allow users to select a ClickUp List. + - `taskFilterFormula` (string, optional): Search for tasks that match specified filters. For example: name=task1. + + + + + **Description:** Create a task in ClickUp. + + **Parameters:** + - `listId` (string, required): List - Select a List to create this task in. Use Connect Portal User Settings to allow users to select a ClickUp List. + - `name` (string, required): Name - The task name. + - `description` (string, optional): Description - Task description. + - `status` (string, optional): Status - Select a Status for this task. Use Connect Portal User Settings to allow users to select a ClickUp Status. + - `assignees` (string, optional): Assignees - Select a Member (or an array of member IDs) to be assigned to this task. Use Connect Portal User Settings to allow users to select a ClickUp Member. + - `dueDate` (string, optional): Due Date - Specify a date for this task to be due on. + - `additionalFields` (string, optional): Additional Fields - Specify additional fields to include on this task as JSON. + + + + + **Description:** Update a task in ClickUp. + + **Parameters:** + - `taskId` (string, required): Task ID - The ID of the task to update. + - `listId` (string, required): List - Select a List to create this task in. Use Connect Portal User Settings to allow users to select a ClickUp List. + - `name` (string, optional): Name - The task name. + - `description` (string, optional): Description - Task description. + - `status` (string, optional): Status - Select a Status for this task. Use Connect Portal User Settings to allow users to select a ClickUp Status. + - `assignees` (string, optional): Assignees - Select a Member (or an array of member IDs) to be assigned to this task. Use Connect Portal User Settings to allow users to select a ClickUp Member. + - `dueDate` (string, optional): Due Date - Specify a date for this task to be due on. + - `additionalFields` (string, optional): Additional Fields - Specify additional fields to include on this task as JSON. + + + + + **Description:** Delete a task in ClickUp. + + **Parameters:** + - `taskId` (string, required): Task ID - The ID of the task to delete. + + + + + **Description:** Get List information in ClickUp. + + **Parameters:** + - `spaceId` (string, required): Space ID - The ID of the space containing the lists. + + + + + **Description:** Get Custom Fields in a List in ClickUp. + + **Parameters:** + - `listId` (string, required): List ID - The ID of the list to get custom fields from. + + + + + **Description:** Get All Fields in a List in ClickUp. + + **Parameters:** + - `listId` (string, required): List ID - The ID of the list to get all fields from. + + + + + **Description:** Get Space information in ClickUp. + + **Parameters:** + - `spaceId` (string, optional): Space ID - The ID of the space to retrieve. + + + + + **Description:** Get Folders in ClickUp. + + **Parameters:** + - `spaceId` (string, required): Space ID - The ID of the space containing the folders. + + + + + **Description:** Get Member information in ClickUp. + + **Parameters:** None required. + + + + +## Usage Examples + +### Basic ClickUp Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Clickup capabilities +clickup_agent = Agent( + role="Task Manager", + goal="Manage tasks and projects in ClickUp efficiently", + backstory="An AI assistant specialized in task management and productivity coordination.", + apps=['clickup'] # All Clickup actions will be available +) + +# 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() +``` + +### Filtering Specific ClickUp Tools + +```python + +task_coordinator = Agent( + role="Task Coordinator", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and status management.", + apps=['clickup/create_task'] +) + +# 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() +``` + +### Advanced Project Management + +```python +from crewai import Agent, Task, Crew + +project_manager = Agent( + role="Project Manager", + goal="Coordinate project activities and track team productivity", + backstory="An experienced project manager who ensures projects are delivered on time.", + apps=['clickup'] +) + +# Complex task involving multiple ClickUp operations +project_coordination = Task( + description=""" + 1. Get all open tasks in the current space + 2. Identify overdue tasks and update their status + 3. Create a weekly report task summarizing project progress + 4. Assign the report task to the team lead + """, + agent=project_manager, + expected_output="Project status updated and weekly report task created and assigned" +) + +crew = Crew( + agents=[project_manager], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### Task Search and Management + +```python +from crewai import Agent, Task, Crew + +task_analyst = Agent( + role="Task Analyst", + goal="Analyze task patterns and optimize team productivity", + backstory="An AI assistant that analyzes task data to improve team efficiency.", + apps=['clickup'] +) + +# Task to analyze and optimize task distribution +task_analysis = Task( + description=""" + Search for all tasks assigned to team members in the last 30 days, + analyze completion patterns, and create optimization recommendations + """, + agent=task_analyst, + expected_output="Task analysis report with optimization recommendations" +) + +crew = Crew( + agents=[task_analyst], + tasks=[task_analysis] +) + +crew.kickoff() +``` + +### Getting Help + + + Contact our support team for assistance with ClickUp integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/databricks.mdx b/docs/v1.15.1/en/enterprise/integrations/databricks.mdx new file mode 100644 index 000000000..8216123a9 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/databricks.mdx @@ -0,0 +1,123 @@ +--- +title: Databricks Integration +description: "Connect CrewAI agents to Databricks Genie, SQL, Unity Catalog Functions, and Vector Search through Databricks managed MCP servers." +icon: "layer-group" +mode: "wide" +--- + +## Overview + +Connect your CrewAI agents directly to your Databricks workspace through [Databricks managed MCP servers](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). The Databricks integration lets your agents ask natural-language questions with **Genie**, run governed **SQL**, call **Unity Catalog Functions**, and retrieve documents with **Vector Search** — all without writing or hosting any connector code, and with Unity Catalog permissions enforced on every call. + +Under the hood, the Databricks integration is a managed wrapper around CrewAI's [Custom MCP Server](/en/enterprise/guides/custom-mcp-server) support. Databricks exposes each capability as its own [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, and CrewAI connects to them securely on your behalf. Because each server is added separately, you can enable exactly the capabilities your crews need. + +## Key Capabilities + + + + Ask questions in plain language and get grounded answers from your data with [Genie](https://docs.databricks.com/aws/en/genie/), which queries Genie Spaces and Unity Catalog and links back to the Databricks UI. + + + Run governed SQL against your Databricks warehouses to query, transform, and author data pipelines directly from your agents. + + + Invoke [Unity Catalog functions](https://docs.databricks.com/aws/en/udf/unity-catalog) to run predefined SQL and custom business logic as governed, reusable tools. + + + Retrieve relevant documents for RAG and knowledge workflows from [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) indexes using semantic similarity. + + + +Every server runs behind the Unity AI Gateway and enforces Unity Catalog access controls, so your agents only ever see the data and tools they're permitted to use. + +## Prerequisites + +Before using the Databricks integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Databricks workspace with the capabilities you want to expose (Genie Spaces, SQL warehouses, Unity Catalog functions, or Vector Search indexes) +- Appropriate [Unity Catalog privileges](https://docs.databricks.com/aws/en/data-governance/unity-catalog) on the underlying objects +- Your Databricks workspace hostname (e.g. `your-workspace.cloud.databricks.com`) + +## Databricks Managed MCP Servers + +Databricks publishes a separate managed MCP server for each capability. CrewAI exposes these as individual connections, each configured with your workspace host and the relevant Unity Catalog identifiers. The endpoints follow these patterns: + +| Server | What it does | MCP URL pattern | +|--------|--------------|-----------------| +| **Genie** | Natural-language Q&A over a Genie Space | `https:///api/2.0/mcp/genie/{genie_space_id}` | +| **Databricks SQL** | Execute SQL against your warehouses | `https:///api/2.0/mcp/sql` | +| **Unity Catalog Functions** | Run registered UC functions | `https:///api/2.0/mcp/functions/{catalog}/{schema}` | +| **Vector Search** | Query a Vector Search index | `https:///api/2.0/mcp/vector-search/{catalog}/{schema}` | + + +You don't construct these URLs by hand — CrewAI builds each endpoint from the workspace host and identifiers (Genie Space ID, or catalog/schema) you provide when configuring the connection. For the full specification and the latest endpoint details, see the [Databricks managed MCP documentation](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). + + +## Connecting Databricks in CrewAI AMP + + + Configure a Databricks managed MCP server in CrewAI AMP + + +Each Databricks capability — **Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions**, and **Databricks Vector Search** — appears as its own MCP server under the Databricks group on the **Tools & Integrations** page. Configure the ones you need: + + + + Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP and locate the **Databricks** group in the Connections list. You'll see the Genie, SQL, Unity Catalog Functions, and Vector Search servers listed beneath it. + + + + Click **Configure** next to the capability you want to enable and provide its connection details: + + - **Workspace Host** — your Databricks workspace hostname (e.g. `my-workspace.cloud.databricks.com`). + - **Genie** — the **Genie Space ID** to query. + - **Unity Catalog Functions** — the **catalog** and **schema** that contain your functions. + - **Vector Search** — the **catalog** and **schema** that contain your index. + - **Databricks SQL** — no additional identifiers; queries run against your workspace's SQL warehouses. + + + + Select how CrewAI authenticates to Databricks. **OAuth** is recommended. + + - **Use OAuth** — Connect securely using OAuth 2.0. Each user authenticates individually, and Databricks issues tokens scoped to the capability (`genie`, `sql`, `unity-catalog`, or `vector-search`). CrewAI handles the authorization flow and refreshes tokens automatically. + - **Use personal access token** — Authenticate with a [Databricks personal access token](https://docs.databricks.com/aws/en/dev-tools/auth/pat). Use a least-privileged identity to limit exposure. + + + + Complete authentication. Once connected, the server's tools become available to your crews. Repeat for any other Databricks capabilities you want to enable. + + + + +Because each capability is a separate connection, you can mix and match — for example, enable Genie and Vector Search for a research crew while reserving SQL and Unity Catalog Functions for a data-engineering crew. Visibility settings let you control which team members can use each one. + + +## Using Databricks Tools in Your Crews + +Once connected, the tools each MCP server exposes appear alongside built-in connections on the **Tools & Integrations** page. You can: + +- **Assign tools to agents** in your crews just like any other CrewAI tool. +- **Manage visibility** to control which team members can use each connection. +- **Edit or remove** any connection at any time from the Connections list. + +Your agents can now ask Genie for grounded answers, run SQL against your warehouses, call Unity Catalog functions, and search Vector Search indexes — with results flowing back into their reasoning automatically. + + +Databricks enforces governance through Unity Catalog and the Unity AI Gateway: a user can only discover and invoke tools their workspace identity is permitted to use. If a tool call fails, confirm the connecting user (or token identity) has the required Unity Catalog privileges on the Genie Space, warehouse, function, or index. Some Genie and SQL queries run asynchronously and may take a moment to return results. + + +## Learn More + + + + Official Databricks documentation for the managed Genie, SQL, Unity Catalog Functions, and Vector Search MCP servers. + + + Learn how CrewAI connects to any MCP server, the foundation the Databricks integration builds on. + + + + + Contact our support team for assistance with the Databricks integration or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/github.mdx b/docs/v1.15.1/en/enterprise/integrations/github.mdx new file mode 100644 index 000000000..1d4c9760f --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/github.mdx @@ -0,0 +1,331 @@ +--- +title: GitHub Integration +description: "Repository and issue management with GitHub integration for CrewAI." +icon: "github" +mode: "wide" +--- + +## Overview + +Enable your agents to manage repositories, issues, and releases through GitHub. Create and update issues, manage releases, track project development, and streamline your software development workflow with AI-powered automation. + +## Prerequisites + +Before using the GitHub integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A GitHub account with appropriate repository permissions +- Connected your GitHub account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up GitHub Integration + +### 1. Connect Your GitHub Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **GitHub** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for repository and issue management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create an issue in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Issue. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Issue. + - `title` (string, required): Issue Title - Specify the title of the issue to create. + - `body` (string, optional): Issue Body - Specify the body contents of the issue to create. + - `assignees` (string, optional): Assignees - Specify the assignee(s)' GitHub login as an array of strings for this issue. (example: `["octocat"]`). + + + + + **Description:** Update an issue in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Issue. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Issue. + - `issue_number` (string, required): Issue Number - Specify the number of the issue to update. + - `title` (string, required): Issue Title - Specify the title of the issue to update. + - `body` (string, optional): Issue Body - Specify the body contents of the issue to update. + - `assignees` (string, optional): Assignees - Specify the assignee(s)' GitHub login as an array of strings for this issue. (example: `["octocat"]`). + - `state` (string, optional): State - Specify the updated state of the issue. + - Options: `open`, `closed` + + + + + **Description:** Get an issue by number in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Issue. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Issue. + - `issue_number` (string, required): Issue Number - Specify the number of the issue to fetch. + + + + + **Description:** Lock an issue in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Issue. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Issue. + - `issue_number` (string, required): Issue Number - Specify the number of the issue to lock. + - `lock_reason` (string, required): Lock Reason - Specify a reason for locking the issue or pull request conversation. + - Options: `off-topic`, `too heated`, `resolved`, `spam` + + + + + **Description:** Search for issues in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Issue. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Issue. + - `filter` (object, required): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "assignee", + "operator": "$stringExactlyMatches", + "value": "octocat" + } + ] + } + ] + } + ``` + Available fields: `assignee`, `creator`, `mentioned`, `labels` + + + + + **Description:** Create a release in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Release. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Release. + - `tag_name` (string, required): Name - Specify the name of the release tag to be created. (example: "v1.0.0"). + - `target_commitish` (string, optional): Target - Specify the target of the release. This can either be a branch name or a commit SHA. Defaults to the main branch. (example: "master"). + - `body` (string, optional): Body - Specify a description for this release. + - `draft` (string, optional): Draft - Specify whether the created release should be a draft (unpublished) release. + - Options: `true`, `false` + - `prerelease` (string, optional): Prerelease - Specify whether the created release should be a prerelease. + - Options: `true`, `false` + - `discussion_category_name` (string, optional): Discussion Category Name - If specified, a discussion of the specified category is created and linked to the release. The value must be a category that already exists in the repository. + - `generate_release_notes` (string, optional): Release Notes - Specify whether the created release should automatically create release notes using the provided name and body specified. + - Options: `true`, `false` + + + + + **Description:** Update a release in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Release. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Release. + - `id` (string, required): Release ID - Specify the ID of the release to update. + - `tag_name` (string, optional): Name - Specify the name of the release tag to be updated. (example: "v1.0.0"). + - `target_commitish` (string, optional): Target - Specify the target of the release. This can either be a branch name or a commit SHA. Defaults to the main branch. (example: "master"). + - `body` (string, optional): Body - Specify a description for this release. + - `draft` (string, optional): Draft - Specify whether the created release should be a draft (unpublished) release. + - Options: `true`, `false` + - `prerelease` (string, optional): Prerelease - Specify whether the created release should be a prerelease. + - Options: `true`, `false` + - `discussion_category_name` (string, optional): Discussion Category Name - If specified, a discussion of the specified category is created and linked to the release. The value must be a category that already exists in the repository. + - `generate_release_notes` (string, optional): Release Notes - Specify whether the created release should automatically create release notes using the provided name and body specified. + - Options: `true`, `false` + + + + + **Description:** Get a release by ID in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Release. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Release. + - `id` (string, required): Release ID - Specify the release ID of the release to fetch. + + + + + **Description:** Get a release by tag name in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Release. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Release. + - `tag_name` (string, required): Name - Specify the tag of the release to fetch. (example: "v1.0.0"). + + + + + **Description:** Delete a release in GitHub. + + **Parameters:** + - `owner` (string, required): Owner - Specify the name of the account owner of the associated repository for this Release. (example: "abc"). + - `repo` (string, required): Repository - Specify the name of the associated repository for this Release. + - `id` (string, required): Release ID - Specify the ID of the release to delete. + + + + +## Usage Examples + +### Basic GitHub Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Github capabilities +github_agent = Agent( + role="Repository Manager", + goal="Manage GitHub repositories, issues, and releases efficiently", + backstory="An AI assistant specialized in repository management and issue tracking.", + apps=['github'] # All Github actions will be available +) + +# 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() +``` + +### Filtering Specific GitHub Tools + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage GitHub issues efficiently", + backstory="An AI assistant that focuses on issue tracking and management.", + apps=['github/create_issue'] +) + +# 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() +``` + +### Release Management + +```python +from crewai import Agent, Task, Crew + +release_manager = Agent( + role="Release Manager", + goal="Manage software releases and versioning", + backstory="An experienced release manager who handles version control and release processes.", + apps=['github'] +) + +# Task to create a new release +release_task = Task( + description=""" + Create a new release v2.1.0 for the project with: + - Auto-generated release notes + - Target the main branch + - Include a description of new features and bug fixes + """, + agent=release_manager, + expected_output="Release v2.1.0 created successfully with release notes" +) + +crew = Crew( + agents=[release_manager], + tasks=[release_task] +) + +crew.kickoff() +``` + +### Issue Tracking and Management + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Track and coordinate project issues and development progress", + backstory="An AI assistant that helps coordinate development work and track project progress.", + apps=['github'] +) + +# Complex task involving multiple GitHub operations +coordination_task = Task( + description=""" + 1. Search for all open issues assigned to the current milestone + 2. Identify overdue issues and update their priority labels + 3. Create a weekly progress report issue + 4. Lock resolved issues that have been inactive for 30 days + """, + agent=project_coordinator, + expected_output="Project coordination completed with progress report and issue management" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### Getting Help + + + Contact our support team for assistance with GitHub integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/gmail.mdx b/docs/v1.15.1/en/enterprise/integrations/gmail.mdx new file mode 100644 index 000000000..681b6c53c --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/gmail.mdx @@ -0,0 +1,303 @@ +--- +title: Gmail Integration +description: "Email and contact management with Gmail integration for CrewAI." +icon: "envelope" +mode: "wide" +--- + +## Overview + +Enable your agents to manage emails, contacts, and drafts through Gmail. Send emails, search messages, manage contacts, create drafts, and streamline your email communications with AI-powered automation. + +## Prerequisites + +Before using the Gmail integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Gmail account with appropriate permissions +- Connected your Gmail account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Gmail Integration + +### 1. Connect Your Gmail Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Gmail** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for email and contact management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Retrieve a list of messages. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `q` (string, optional): Search query to filter messages (e.g., 'from:someone@example.com is:unread'). + - `maxResults` (integer, optional): Maximum number of messages to return (1-500). (default: 100) + - `pageToken` (string, optional): Page token to retrieve a specific page of results. + - `labelIds` (array, optional): Only return messages with labels that match all of the specified label IDs. + - `includeSpamTrash` (boolean, optional): Include messages from SPAM and TRASH in the results. (default: false) + + + + + **Description:** Send an email. + + **Parameters:** + - `to` (string, required): Recipient email address. + - `subject` (string, required): Email subject line. + - `body` (string, required): Email message content. + - `userId` (string, optional): The user's email address or 'me' for the authenticated user. (default: "me") + - `cc` (string, optional): CC email addresses (comma-separated). + - `bcc` (string, optional): BCC email addresses (comma-separated). + - `from` (string, optional): Sender email address (if different from authenticated user). + - `replyTo` (string, optional): Reply-to email address. + - `threadId` (string, optional): Thread ID if replying to an existing conversation. + + + + + **Description:** Delete an email by ID. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. + - `id` (string, required): The ID of the message to delete. + + + + + **Description:** Create a new draft email. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. + - `message` (object, required): Message object containing the draft content. + - `raw` (string, required): Base64url encoded email message. + + + + + **Description:** Retrieve a specific message by ID. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `id` (string, required): The ID of the message to retrieve. + - `format` (string, optional): The format to return the message in. Options: "full", "metadata", "minimal", "raw". (default: "full") + - `metadataHeaders` (array, optional): When given and format is METADATA, only include headers specified. + + + + + **Description:** Retrieve a message attachment. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `messageId` (string, required): The ID of the message containing the attachment. + - `id` (string, required): The ID of the attachment to retrieve. + + + + + **Description:** Retrieve a specific email thread by ID. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `id` (string, required): The ID of the thread to retrieve. + - `format` (string, optional): The format to return the messages in. Options: "full", "metadata", "minimal". (default: "full") + - `metadataHeaders` (array, optional): When given and format is METADATA, only include headers specified. + + + + + **Description:** Modify the labels applied to a thread. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `id` (string, required): The ID of the thread to modify. + - `addLabelIds` (array, optional): A list of IDs of labels to add to this thread. + - `removeLabelIds` (array, optional): A list of IDs of labels to remove from this thread. + + + + + **Description:** Move a thread to the trash. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `id` (string, required): The ID of the thread to trash. + + + + + **Description:** Remove a thread from the trash. + + **Parameters:** + - `userId` (string, required): The user's email address or 'me' for the authenticated user. (default: "me") + - `id` (string, required): The ID of the thread to untrash. + + + + +## Usage Examples + +### Basic Gmail Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +gmail_agent = Agent( + role="Email Manager", + goal="Manage email communications and messages efficiently", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail'] # All Gmail actions will be available +) + +# 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() +``` + +### Filtering Specific Gmail Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Gmail actions only +email_coordinator = Agent( + role="Email Coordinator", + goal="Coordinate email communications and manage drafts", + backstory="An AI assistant that focuses on email coordination and draft management.", + apps=[ + 'gmail/send_email', + 'gmail/fetch_emails', + 'gmail/create_draft' + ] +) + +# 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() +``` + +### Email Search and Analysis + +```python +from crewai import Agent, Task, Crew + +# Create agent with Gmail search and analysis capabilities +email_analyst = Agent( + role="Email Analyst", + goal="Analyze email patterns and provide insights", + backstory="An AI assistant that analyzes email data to provide actionable insights.", + apps=['gmail/fetch_emails', 'gmail/get_message'] # Specific actions for email analysis +) + +# 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() +``` + +### Thread Management + +```python +from crewai import Agent, Task, Crew + +# Create agent with Gmail thread management capabilities +thread_manager = Agent( + role="Thread Manager", + goal="Organize and manage email threads efficiently", + backstory="An AI assistant that specializes in email thread organization and management.", + apps=[ + 'gmail/fetch_thread', + 'gmail/modify_thread', + 'gmail/trash_thread' + ] +) + +# Task to organize email threads +thread_task = Task( + description=""" + 1. Fetch all threads from the last month + 2. Apply appropriate labels to organize threads by project + 3. Archive or trash threads that are no longer relevant + """, + agent=thread_manager, + expected_output="Email threads organized with appropriate labels and cleanup completed" +) + +crew = Crew( + agents=[thread_manager], + tasks=[thread_task] +) + +crew.kickoff() +``` + +### Getting Help + + + Contact our support team for assistance with Gmail integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/google_calendar.mdx b/docs/v1.15.1/en/enterprise/integrations/google_calendar.mdx new file mode 100644 index 000000000..e3c35f2ef --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/google_calendar.mdx @@ -0,0 +1,367 @@ +--- +title: Google Calendar Integration +description: "Event and schedule management with Google Calendar integration for CrewAI." +icon: "calendar" +mode: "wide" +--- + +## Overview + +Enable your agents to manage calendar events, schedules, and availability through Google Calendar. Create and update events, manage attendees, check availability, and streamline your scheduling workflows with AI-powered automation. + +## Prerequisites + +Before using the Google Calendar integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Google account with Google Calendar access +- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Google Calendar Integration + +### 1. Connect Your Google Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Google Calendar** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for calendar access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Get calendar availability (free/busy information). + + **Parameters:** + - `timeMin` (string, required): Start time (RFC3339 format) + - `timeMax` (string, required): End time (RFC3339 format) + - `items` (array, required): Calendar IDs to check + ```json + [ + { + "id": "calendar_id" + } + ] + ``` + - `timeZone` (string, optional): Time zone used in the response. The default is UTC. + - `groupExpansionMax` (integer, optional): Maximal number of calendar identifiers to be provided for a single group. Maximum: 100 + - `calendarExpansionMax` (integer, optional): Maximal number of calendars for which FreeBusy information is to be provided. Maximum: 50 + + + + + **Description:** Create a new event in the specified calendar. + + **Parameters:** + - `calendarId` (string, required): Calendar ID (use 'primary' for main calendar) + - `summary` (string, required): Event title/summary + - `start_dateTime` (string, required): Start time in RFC3339 format (e.g., 2024-01-20T10:00:00-07:00) + - `end_dateTime` (string, required): End time in RFC3339 format + - `description` (string, optional): Event description + - `timeZone` (string, optional): Time zone (e.g., America/Los_Angeles) + - `location` (string, optional): Geographic location of the event as free-form text. + - `attendees` (array, optional): List of attendees for the event. + ```json + [ + { + "email": "attendee@example.com", + "displayName": "Attendee Name", + "optional": false + } + ] + ``` + - `reminders` (object, optional): Information about the event's reminders. + ```json + { + "useDefault": true, + "overrides": [ + { + "method": "email", + "minutes": 15 + } + ] + } + ``` + - `conferenceData` (object, optional): The conference-related information, such as details of a Google Meet conference. + ```json + { + "createRequest": { + "requestId": "unique-request-id", + "conferenceSolutionKey": { + "type": "hangoutsMeet" + } + } + } + ``` + - `visibility` (string, optional): Visibility of the event. Options: default, public, private, confidential. Default: default + - `transparency` (string, optional): Whether the event blocks time on the calendar. Options: opaque, transparent. Default: opaque + + + + + **Description:** Retrieve events for the specified calendar. + + **Parameters:** + - `calendarId` (string, required): Calendar ID (use 'primary' for main calendar) + - `timeMin` (string, optional): Lower bound for events (RFC3339) + - `timeMax` (string, optional): Upper bound for events (RFC3339) + - `maxResults` (integer, optional): Maximum number of events (default 10). Minimum: 1, Maximum: 2500 + - `orderBy` (string, optional): The order of the events returned in the result. Options: startTime, updated. Default: startTime + - `singleEvents` (boolean, optional): Whether to expand recurring events into instances and only return single one-off events and instances of recurring events. Default: true + - `showDeleted` (boolean, optional): Whether to include deleted events (with status equals cancelled) in the result. Default: false + - `showHiddenInvitations` (boolean, optional): Whether to include hidden invitations in the result. Default: false + - `q` (string, optional): Free text search terms to find events that match these terms in any field. + - `pageToken` (string, optional): Token specifying which result page to return. + - `timeZone` (string, optional): Time zone used in the response. + - `updatedMin` (string, optional): Lower bound for an event's last modification time (RFC3339) to filter by. + - `iCalUID` (string, optional): Specifies an event ID in the iCalendar format to be provided in the response. + + + + + **Description:** Update an existing event. + + **Parameters:** + - `calendarId` (string, required): Calendar ID + - `eventId` (string, required): Event ID to update + - `summary` (string, optional): Updated event title + - `description` (string, optional): Updated event description + - `start_dateTime` (string, optional): Updated start time + - `end_dateTime` (string, optional): Updated end time + + + + + **Description:** Delete a specified event. + + **Parameters:** + - `calendarId` (string, required): Calendar ID + - `eventId` (string, required): Event ID to delete + + + + + **Description:** Retrieve user's calendar list. + + **Parameters:** + - `maxResults` (integer, optional): Maximum number of entries returned on one result page. Minimum: 1 + - `pageToken` (string, optional): Token specifying which result page to return. + - `showDeleted` (boolean, optional): Whether to include deleted calendar list entries in the result. Default: false + - `showHidden` (boolean, optional): Whether to show hidden entries. Default: false + - `minAccessRole` (string, optional): The minimum access role for the user in the returned entries. Options: freeBusyReader, owner, reader, writer + + + + +## Usage Examples + +### Basic Calendar Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Calendar capabilities +calendar_agent = Agent( + role="Schedule Manager", + goal="Manage calendar events and scheduling efficiently", + backstory="An AI assistant specialized in calendar management and scheduling coordination.", + apps=['google_calendar'] # All Google Calendar actions will be available +) + +# Task to create a meeting +create_meeting_task = Task( + description="Create a team standup meeting for tomorrow at 9 AM with the development team", + agent=calendar_agent, + expected_output="Meeting created successfully with Google Meet link" +) + +# Run the task +crew = Crew( + agents=[calendar_agent], + tasks=[create_meeting_task] +) + +crew.kickoff() +``` + +### Filtering Specific Calendar Tools + +```python +meeting_coordinator = Agent( + role="Meeting Coordinator", + goal="Coordinate meetings and check availability", + backstory="An AI assistant that focuses on meeting scheduling and availability management.", + apps=['google_calendar/create_event', 'google_calendar/get_availability'] +) + +# Task to schedule a meeting with availability check +schedule_meeting = Task( + description="Check availability for next week and schedule a project review meeting with stakeholders", + agent=meeting_coordinator, + expected_output="Meeting scheduled after checking availability of all participants" +) + +crew = Crew( + agents=[meeting_coordinator], + tasks=[schedule_meeting] +) + +crew.kickoff() +``` + +### Event Management and Updates + +```python +from crewai import Agent, Task, Crew + +event_manager = Agent( + role="Event Manager", + goal="Manage and update calendar events efficiently", + backstory="An experienced event manager who handles event logistics and updates.", + apps=['google_calendar'] +) + +# Task to manage event updates +event_management = Task( + description=""" + 1. List all events for this week + 2. Update any events that need location changes to include video conference links + 3. Check availability for upcoming meetings + """, + agent=event_manager, + expected_output="Weekly events updated with proper locations and availability checked" +) + +crew = Crew( + agents=[event_manager], + tasks=[event_management] +) + +crew.kickoff() +``` + +### Availability and Calendar Management + +```python +from crewai import Agent, Task, Crew + +availability_coordinator = Agent( + role="Availability Coordinator", + goal="Coordinate availability and manage calendars for scheduling", + backstory="An AI assistant that specializes in availability management and calendar coordination.", + apps=['google_calendar'] +) + +# Task to coordinate availability +availability_task = Task( + description=""" + 1. Get the list of available calendars + 2. Check availability for all calendars next Friday afternoon + 3. Create a team meeting for the first available 2-hour slot + 4. Include Google Meet link and send invitations + """, + agent=availability_coordinator, + expected_output="Team meeting scheduled based on availability with all team members invited" +) + +crew = Crew( + agents=[availability_coordinator], + tasks=[availability_task] +) + +crew.kickoff() +``` + +### Automated Scheduling Workflows + +```python +from crewai import Agent, Task, Crew + +scheduling_automator = Agent( + role="Scheduling Automator", + goal="Automate scheduling workflows and calendar management", + backstory="An AI assistant that automates complex scheduling scenarios and calendar workflows.", + apps=['google_calendar'] +) + +# Complex scheduling automation task +automation_task = Task( + description=""" + 1. List all upcoming events for the next two weeks + 2. Identify any scheduling conflicts or back-to-back meetings + 3. Suggest optimal meeting times by checking availability + 4. Create buffer time between meetings where needed + 5. Update event descriptions with agenda items and meeting links + """, + agent=scheduling_automator, + expected_output="Calendar optimized with resolved conflicts, buffer times, and updated meeting details" +) + +crew = Crew( + agents=[scheduling_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Authentication Errors** + +- Ensure your Google account has the necessary permissions for calendar access +- Verify that the OAuth connection includes all required scopes for Google Calendar API +- Check if calendar sharing settings allow the required access level + +**Event Creation Issues** + +- Verify that time formats are correct (RFC3339 format) +- Ensure attendee email addresses are properly formatted +- Check that the target calendar exists and is accessible +- Verify time zones are correctly specified + +**Availability and Time Conflicts** + +- Use proper RFC3339 format for time ranges when checking availability +- Ensure time zones are consistent across all operations +- Verify that calendar IDs are correct when checking multiple calendars + +**Event Updates and Deletions** + +- Verify that event IDs are correct and events exist +- Ensure you have edit permissions for the events +- Check that calendar ownership allows modifications + +### Getting Help + + + Contact our support team for assistance with Google Calendar integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/google_contacts.mdx b/docs/v1.15.1/en/enterprise/integrations/google_contacts.mdx new file mode 100644 index 000000000..755c86b49 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/google_contacts.mdx @@ -0,0 +1,494 @@ +--- +title: Google Contacts Integration +description: "Contact and directory management with Google Contacts integration for CrewAI." +icon: "address-book" +mode: "wide" +--- + +## Overview + +Enable your agents to manage contacts and directory information through Google Contacts. Access personal contacts, search directory people, create and update contact information, and manage contact groups with AI-powered automation. + +## Prerequisites + +Before using the Google Contacts integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Google account with Google Contacts access +- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Google Contacts Integration + +### 1. Connect Your Google Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Google Contacts** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for contacts and directory access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Retrieve user's contacts from Google Contacts. + + **Parameters:** + - `pageSize` (integer, optional): Number of contacts to return (max 1000). Minimum: 1, Maximum: 1000 + - `pageToken` (string, optional): The token of the page to retrieve. + - `personFields` (string, optional): Fields to include (e.g., 'names,emailAddresses,phoneNumbers'). Default: names,emailAddresses,phoneNumbers + - `requestSyncToken` (boolean, optional): Whether the response should include a sync token. Default: false + - `sortOrder` (string, optional): The order in which the connections should be sorted. Options: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING + + + + + **Description:** Search for contacts using a query string. + + **Parameters:** + - `query` (string, required): Search query string + - `readMask` (string, required): Fields to read (e.g., 'names,emailAddresses,phoneNumbers') + - `pageSize` (integer, optional): Number of results to return. Minimum: 1, Maximum: 30 + - `pageToken` (string, optional): Token specifying which result page to return. + - `sources` (array, optional): The sources to search in. Options: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. Default: READ_SOURCE_TYPE_CONTACT + + + + + **Description:** List people in the authenticated user's directory. + + **Parameters:** + - `sources` (array, required): Directory sources to search within. Options: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. Default: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE + - `pageSize` (integer, optional): Number of people to return. Minimum: 1, Maximum: 1000 + - `pageToken` (string, optional): Token specifying which result page to return. + - `readMask` (string, optional): Fields to read (e.g., 'names,emailAddresses') + - `requestSyncToken` (boolean, optional): Whether the response should include a sync token. Default: false + - `mergeSources` (array, optional): Additional data to merge into the directory people responses. Options: CONTACT + + + + + **Description:** Search for people in the directory. + + **Parameters:** + - `query` (string, required): Search query + - `sources` (string, required): Directory sources (use 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE') + - `pageSize` (integer, optional): Number of results to return + - `readMask` (string, optional): Fields to read + + + + + **Description:** List other contacts (not in user's personal contacts). + + **Parameters:** + - `pageSize` (integer, optional): Number of contacts to return. Minimum: 1, Maximum: 1000 + - `pageToken` (string, optional): Token specifying which result page to return. + - `readMask` (string, optional): Fields to read + - `requestSyncToken` (boolean, optional): Whether the response should include a sync token. Default: false + + + + + **Description:** Search other contacts. + + **Parameters:** + - `query` (string, required): Search query + - `readMask` (string, required): Fields to read (e.g., 'names,emailAddresses') + - `pageSize` (integer, optional): Number of results + + + + + **Description:** Get a single person's contact information by resource name. + + **Parameters:** + - `resourceName` (string, required): The resource name of the person to get (e.g., 'people/c123456789') + - `personFields` (string, optional): Fields to include (e.g., 'names,emailAddresses,phoneNumbers'). Default: names,emailAddresses,phoneNumbers + + + + + **Description:** Create a new contact in the user's address book. + + **Parameters:** + - `names` (array, optional): Person's names + ```json + [ + { + "givenName": "John", + "familyName": "Doe", + "displayName": "John Doe" + } + ] + ``` + - `emailAddresses` (array, optional): Email addresses + ```json + [ + { + "value": "john.doe@example.com", + "type": "work" + } + ] + ``` + - `phoneNumbers` (array, optional): Phone numbers + ```json + [ + { + "value": "+1234567890", + "type": "mobile" + } + ] + ``` + - `addresses` (array, optional): Postal addresses + ```json + [ + { + "formattedValue": "123 Main St, City, State 12345", + "type": "home" + } + ] + ``` + - `organizations` (array, optional): Organizations/companies + ```json + [ + { + "name": "Company Name", + "title": "Job Title", + "type": "work" + } + ] + ``` + + + + + **Description:** Update an existing contact's information. + + **Parameters:** + - `resourceName` (string, required): The resource name of the person to update (e.g., 'people/c123456789') + - `updatePersonFields` (string, required): Fields to update (e.g., 'names,emailAddresses,phoneNumbers') + - `names` (array, optional): Person's names + - `emailAddresses` (array, optional): Email addresses + - `phoneNumbers` (array, optional): Phone numbers + + + + + **Description:** Delete a contact from the user's address book. + + **Parameters:** + - `resourceName` (string, required): The resource name of the person to delete (e.g., 'people/c123456789') + + + + + **Description:** Get information about multiple people in a single request. + + **Parameters:** + - `resourceNames` (array, required): Resource names of people to get. Maximum: 200 items + - `personFields` (string, optional): Fields to include (e.g., 'names,emailAddresses,phoneNumbers'). Default: names,emailAddresses,phoneNumbers + + + + + **Description:** List the user's contact groups (labels). + + **Parameters:** + - `pageSize` (integer, optional): Number of contact groups to return. Minimum: 1, Maximum: 1000 + - `pageToken` (string, optional): Token specifying which result page to return. + - `groupFields` (string, optional): Fields to include (e.g., 'name,memberCount,clientData'). Default: name,memberCount + + + + + **Description:** Get a specific contact group by resource name. + + **Parameters:** + - `resourceName` (string, required): The resource name of the contact group (e.g., 'contactGroups/myContactGroup') + - `maxMembers` (integer, optional): Maximum number of members to include. Minimum: 0, Maximum: 20000 + - `groupFields` (string, optional): Fields to include (e.g., 'name,memberCount,clientData'). Default: name,memberCount + + + + + **Description:** Create a new contact group (label). + + **Parameters:** + - `name` (string, required): The name of the contact group + - `clientData` (array, optional): Client-specific data + ```json + [ + { + "key": "data_key", + "value": "data_value" + } + ] + ``` + + + + + **Description:** Update a contact group's information. + + **Parameters:** + - `resourceName` (string, required): The resource name of the contact group (e.g., 'contactGroups/myContactGroup') + - `name` (string, required): The name of the contact group + - `clientData` (array, optional): Client-specific data + ```json + [ + { + "key": "data_key", + "value": "data_value" + } + ] + ``` + + + + + **Description:** Delete a contact group. + + **Parameters:** + - `resourceName` (string, required): The resource name of the contact group to delete (e.g., 'contactGroups/myContactGroup') + - `deleteContacts` (boolean, optional): Whether to delete contacts in the group as well. Default: false + + + + +## Usage Examples + +### Basic Google Contacts Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Contacts capabilities +contacts_agent = Agent( + role="Contact Manager", + goal="Manage contacts and directory information efficiently", + backstory="An AI assistant specialized in contact management and directory operations.", + apps=['google_contacts'] # All Google Contacts actions will be available +) + +# Task to retrieve and organize contacts +contact_management_task = Task( + description="Retrieve all contacts and organize them by company affiliation", + agent=contacts_agent, + expected_output="Contacts retrieved and organized by company with summary report" +) + +# Run the task +crew = Crew( + agents=[contacts_agent], + tasks=[contact_management_task] +) + +crew.kickoff() +``` + +### Directory Search and Management + +```python +from crewai import Agent, Task, Crew + +directory_manager = Agent( + role="Directory Manager", + goal="Search and manage directory people and contacts", + backstory="An AI assistant that specializes in directory management and people search.", + apps=[ + 'google_contacts/search_directory_people', + 'google_contacts/list_directory_people', + 'google_contacts/search_contacts' + ] +) + +# Task to search and manage directory +directory_task = Task( + description="Search for team members in the company directory and create a team contact list", + agent=directory_manager, + expected_output="Team directory compiled with contact information" +) + +crew = Crew( + agents=[directory_manager], + tasks=[directory_task] +) + +crew.kickoff() +``` + +### Contact Creation and Updates + +```python +from crewai import Agent, Task, Crew + +contact_curator = Agent( + role="Contact Curator", + goal="Create and update contact information systematically", + backstory="An AI assistant that maintains accurate and up-to-date contact information.", + apps=['google_contacts'] +) + +# Task to create and update contacts +curation_task = Task( + description=""" + 1. Search for existing contacts related to new business partners + 2. Create new contacts for partners not in the system + 3. Update existing contact information with latest details + 4. Organize contacts into appropriate groups + """, + agent=contact_curator, + expected_output="Contact database updated with new partners and organized groups" +) + +crew = Crew( + agents=[contact_curator], + tasks=[curation_task] +) + +crew.kickoff() +``` + +### Contact Group Management + +```python +from crewai import Agent, Task, Crew + +group_organizer = Agent( + role="Contact Group Organizer", + goal="Organize contacts into meaningful groups and categories", + backstory="An AI assistant that specializes in contact organization and group management.", + apps=['google_contacts'] +) + +# Task to organize contact groups +organization_task = Task( + description=""" + 1. List all existing contact groups + 2. Analyze contact distribution across groups + 3. Create new groups for better organization + 4. Move contacts to appropriate groups based on their information + """, + agent=group_organizer, + expected_output="Contacts organized into logical groups with improved structure" +) + +crew = Crew( + agents=[group_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### Comprehensive Contact Management + +```python +from crewai import Agent, Task, Crew + +contact_specialist = Agent( + role="Contact Management Specialist", + goal="Provide comprehensive contact management across all sources", + backstory="An AI assistant that handles all aspects of contact management including personal, directory, and other contacts.", + apps=['google_contacts'] +) + +# Complex contact management task +comprehensive_task = Task( + description=""" + 1. Retrieve contacts from all sources (personal, directory, other) + 2. Search for duplicate contacts and merge information + 3. Update outdated contact information + 4. Create missing contacts for important stakeholders + 5. Organize contacts into meaningful groups + 6. Generate a comprehensive contact report + """, + agent=contact_specialist, + expected_output="Complete contact management performed with unified contact database and detailed report" +) + +crew = Crew( + agents=[contact_specialist], + tasks=[comprehensive_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Google account has appropriate permissions for contacts access +- Verify that the OAuth connection includes required scopes for Google Contacts API +- Check that directory access permissions are granted for organization contacts + +**Resource Name Format Issues** + +- Ensure resource names follow the correct format (e.g., 'people/c123456789' for contacts) +- Verify that contact group resource names use the format 'contactGroups/groupId' +- Check that resource names exist and are accessible + +**Search and Query Issues** + +- Ensure search queries are properly formatted and not empty +- Use appropriate readMask fields for the data you need +- Verify that search sources are correctly specified (contacts vs profiles) + +**Contact Creation and Updates** + +- Ensure required fields are provided when creating contacts +- Verify that email addresses and phone numbers are properly formatted +- Check that updatePersonFields parameter includes all fields being updated + +**Directory Access Issues** + +- Ensure you have appropriate permissions to access organization directory +- Verify that directory sources are correctly specified +- Check that your organization allows API access to directory information + +**Pagination and Limits** + +- Be mindful of page size limits (varies by endpoint) +- Use pageToken for pagination through large result sets +- Respect API rate limits and implement appropriate delays + +**Contact Groups and Organization** + +- Ensure contact group names are unique when creating new groups +- Verify that contacts exist before adding them to groups +- Check that you have permissions to modify contact groups + +### Getting Help + + + Contact our support team for assistance with Google Contacts integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/google_docs.mdx b/docs/v1.15.1/en/enterprise/integrations/google_docs.mdx new file mode 100644 index 000000000..2cfc4fc51 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/google_docs.mdx @@ -0,0 +1,551 @@ +--- +title: Google Docs Integration +description: "Document creation and editing with Google Docs integration for CrewAI." +icon: "file-lines" +mode: "wide" +--- + +## Overview + +Enable your agents to create, edit, and manage Google Docs documents with text manipulation and formatting. Automate document creation, insert and replace text, manage content ranges, and streamline your document workflows with AI-powered automation. + +## Prerequisites + +Before using the Google Docs integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Google account with Google Docs access +- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Google Docs Integration + +### 1. Connect Your Google Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Google Docs** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for document access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create a new Google Document. + + **Parameters:** + - `title` (string, optional): The title for the new document. + + + + + **Description:** Get the contents and metadata of a Google Document. + + **Parameters:** + - `documentId` (string, required): The ID of the document to retrieve. + - `includeTabsContent` (boolean, optional): Whether to include tab content. Default is `false`. + - `suggestionsViewMode` (string, optional): The suggestions view mode to apply to the document. Enum: `DEFAULT_FOR_CURRENT_ACCESS`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. Default is `DEFAULT_FOR_CURRENT_ACCESS`. + + + + + **Description:** Apply one or more updates to a Google Document. + + **Parameters:** + - `documentId` (string, required): The ID of the document to update. + - `requests` (array, required): A list of updates to apply to the document. Each item is an object representing a request. + - `writeControl` (object, optional): Provides control over how write requests are executed. Contains `requiredRevisionId` (string) and `targetRevisionId` (string). + + + + + **Description:** Insert text into a Google Document at a specific location. + + **Parameters:** + - `documentId` (string, required): The ID of the document to update. + - `text` (string, required): The text to insert. + - `index` (integer, optional): The zero-based index where to insert the text. Default is `1`. + + + + + **Description:** Replace all instances of text in a Google Document. + + **Parameters:** + - `documentId` (string, required): The ID of the document to update. + - `containsText` (string, required): The text to find and replace. + - `replaceText` (string, required): The text to replace it with. + - `matchCase` (boolean, optional): Whether the search should respect case. Default is `false`. + + + + + **Description:** Delete content from a specific range in a Google Document. + + **Parameters:** + - `documentId` (string, required): The ID of the document to update. + - `startIndex` (integer, required): The start index of the range to delete. + - `endIndex` (integer, required): The end index of the range to delete. + + + + + **Description:** Insert a page break at a specific location in a Google Document. + + **Parameters:** + - `documentId` (string, required): The ID of the document to update. + - `index` (integer, optional): The zero-based index where to insert the page break. Default is `1`. + + + + + **Description:** Create a named range in a Google Document. + + **Parameters:** + - `documentId` (string, required): The ID of the document to update. + - `name` (string, required): The name for the named range. + - `startIndex` (integer, required): The start index of the range. + - `endIndex` (integer, required): The end index of the range. + + + + + **Description:** Create a new Google Document with content in one action. + + **Parameters:** + - `title` (string, required): The title for the new document. Appears at the top of the document and in Google Drive. + - `content` (string, optional): The text content to insert into the document. Use `\n` for new paragraphs. + + + + + **Description:** Append text to the end of a Google Document. Automatically inserts at the document end without needing to specify an index. + + **Parameters:** + - `documentId` (string, required): The document ID from create_document response or URL. + - `text` (string, required): Text to append at the end of the document. Use `\n` for new paragraphs. + + + + + **Description:** Make text bold or remove bold formatting in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to format. + - `endIndex` (integer, required): End position of text to format (exclusive). + - `bold` (boolean, required): Set `true` to make bold, `false` to remove bold. + + + + + **Description:** Make text italic or remove italic formatting in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to format. + - `endIndex` (integer, required): End position of text to format (exclusive). + - `italic` (boolean, required): Set `true` to make italic, `false` to remove italic. + + + + + **Description:** Add or remove underline formatting from text in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to format. + - `endIndex` (integer, required): End position of text to format (exclusive). + - `underline` (boolean, required): Set `true` to underline, `false` to remove underline. + + + + + **Description:** Add or remove strikethrough formatting from text in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to format. + - `endIndex` (integer, required): End position of text to format (exclusive). + - `strikethrough` (boolean, required): Set `true` to add strikethrough, `false` to remove. + + + + + **Description:** Change the font size of text in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to format. + - `endIndex` (integer, required): End position of text to format (exclusive). + - `fontSize` (number, required): Font size in points. Common sizes: 10, 11, 12, 14, 16, 18, 24, 36. + + + + + **Description:** Change the color of text using RGB values (0-1 scale) in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to format. + - `endIndex` (integer, required): End position of text to format (exclusive). + - `red` (number, required): Red component (0-1). Example: `1` for full red. + - `green` (number, required): Green component (0-1). Example: `0.5` for half green. + - `blue` (number, required): Blue component (0-1). Example: `0` for no blue. + + + + + **Description:** Turn existing text into a clickable hyperlink in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of text to make into a link. + - `endIndex` (integer, required): End position of text to make into a link (exclusive). + - `url` (string, required): The URL the link should point to. Example: `"https://example.com"`. + + + + + **Description:** Apply a heading or paragraph style to a text range in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of paragraph(s) to style. + - `endIndex` (integer, required): End position of paragraph(s) to style. + - `style` (string, required): The style to apply. Enum: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`. + + + + + **Description:** Set text alignment for paragraphs in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of paragraph(s) to align. + - `endIndex` (integer, required): End position of paragraph(s) to align. + - `alignment` (string, required): Text alignment. Enum: `START` (left), `CENTER`, `END` (right), `JUSTIFIED`. + + + + + **Description:** Set line spacing for paragraphs in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of paragraph(s). + - `endIndex` (integer, required): End position of paragraph(s). + - `lineSpacing` (number, required): Line spacing as percentage. `100` = single, `115` = 1.15x, `150` = 1.5x, `200` = double. + + + + + **Description:** Convert paragraphs to a bulleted or numbered list in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of paragraphs to convert to list. + - `endIndex` (integer, required): End position of paragraphs to convert to list. + - `bulletPreset` (string, required): Bullet/numbering style. Enum: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`. + + + + + **Description:** Remove bullets or numbering from paragraphs in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `startIndex` (integer, required): Start position of list paragraphs. + - `endIndex` (integer, required): End position of list paragraphs. + + + + + **Description:** Insert a table with content into a Google Document in one action. Provide content as a 2D array. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `rows` (integer, required): Number of rows in the table. + - `columns` (integer, required): Number of columns in the table. + - `index` (integer, optional): Position to insert the table. If not provided, the table is inserted at the end of the document. + - `content` (array, required): Table content as a 2D array. Each inner array is a row. Example: `[["Year", "Revenue"], ["2023", "$43B"], ["2024", "$45B"]]`. + + + + + **Description:** Insert a new row above or below a reference cell in an existing table. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `tableStartIndex` (integer, required): The start index of the table. Get from get_document. + - `rowIndex` (integer, required): Row index (0-based) of reference cell. + - `columnIndex` (integer, optional): Column index (0-based) of reference cell. Default is `0`. + - `insertBelow` (boolean, optional): If `true`, insert below the reference row. If `false`, insert above. Default is `true`. + + + + + **Description:** Insert a new column left or right of a reference cell in an existing table. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `tableStartIndex` (integer, required): The start index of the table. + - `rowIndex` (integer, optional): Row index (0-based) of reference cell. Default is `0`. + - `columnIndex` (integer, required): Column index (0-based) of reference cell. + - `insertRight` (boolean, optional): If `true`, insert to the right. If `false`, insert to the left. Default is `true`. + + + + + **Description:** Delete a row from an existing table in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `tableStartIndex` (integer, required): The start index of the table. + - `rowIndex` (integer, required): Row index (0-based) to delete. + - `columnIndex` (integer, optional): Column index (0-based) of any cell in the row. Default is `0`. + + + + + **Description:** Delete a column from an existing table in a Google Document. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `tableStartIndex` (integer, required): The start index of the table. + - `rowIndex` (integer, optional): Row index (0-based) of any cell in the column. Default is `0`. + - `columnIndex` (integer, required): Column index (0-based) to delete. + + + + + **Description:** Merge a range of table cells into a single cell. Content from all cells is preserved. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `tableStartIndex` (integer, required): The start index of the table. + - `rowIndex` (integer, required): Starting row index (0-based) for the merge. + - `columnIndex` (integer, required): Starting column index (0-based) for the merge. + - `rowSpan` (integer, required): Number of rows to merge. + - `columnSpan` (integer, required): Number of columns to merge. + + + + + **Description:** Unmerge previously merged table cells back into individual cells. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `tableStartIndex` (integer, required): The start index of the table. + - `rowIndex` (integer, required): Row index (0-based) of the merged cell. + - `columnIndex` (integer, required): Column index (0-based) of the merged cell. + - `rowSpan` (integer, required): Number of rows the merged cell spans. + - `columnSpan` (integer, required): Number of columns the merged cell spans. + + + + + **Description:** Insert an image from a public URL into a Google Document. The image must be publicly accessible, under 50MB, and in PNG/JPEG/GIF format. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `uri` (string, required): Public URL of the image. Must be accessible without authentication. + - `index` (integer, optional): Position to insert the image. If not provided, the image is inserted at the end of the document. Default is `1`. + + + + + **Description:** Insert a section break to create document sections with different formatting. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `index` (integer, required): Position to insert the section break. + - `sectionType` (string, required): The type of section break. Enum: `CONTINUOUS` (stays on same page), `NEXT_PAGE` (starts a new page). + + + + + **Description:** Create a header for the document. Returns a headerId which can be used with insert_text to add header content. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `type` (string, optional): Header type. Enum: `DEFAULT`. Default is `DEFAULT`. + + + + + **Description:** Create a footer for the document. Returns a footerId which can be used with insert_text to add footer content. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `type` (string, optional): Footer type. Enum: `DEFAULT`. Default is `DEFAULT`. + + + + + **Description:** Delete a header from the document. Use get_document to find the headerId. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `headerId` (string, required): The header ID to delete. Get from get_document response. + + + + + **Description:** Delete a footer from the document. Use get_document to find the footerId. + + **Parameters:** + - `documentId` (string, required): The document ID. + - `footerId` (string, required): The footer ID to delete. Get from get_document response. + + + + +## Usage Examples + +### Basic Google Docs Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Docs capabilities +docs_agent = Agent( + role="Document Creator", + goal="Create and manage Google Docs documents efficiently", + backstory="An AI assistant specialized in Google Docs document creation and editing.", + apps=['google_docs'] # All Google Docs actions will be available +) + +# Task to create a new document +create_doc_task = Task( + description="Create a new Google Document titled 'Project Status Report'", + agent=docs_agent, + expected_output="New Google Document 'Project Status Report' created successfully" +) + +# Run the task +crew = Crew( + agents=[docs_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +### Text Editing and Content Management + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on text editing +text_editor = Agent( + role="Document Editor", + goal="Edit and update content in Google Docs documents", + backstory="An AI assistant skilled in precise text editing and content management.", + apps=['google_docs/insert_text', 'google_docs/replace_text', 'google_docs/delete_content_range'] +) + +# Task to edit document content +edit_content_task = Task( + description="In document 'your_document_id', insert the text 'Executive Summary: ' at the beginning, then replace all instances of 'TODO' with 'COMPLETED'.", + agent=text_editor, + expected_output="Document updated with new text inserted and TODO items replaced." +) + +crew = Crew( + agents=[text_editor], + tasks=[edit_content_task] +) + +crew.kickoff() +``` + +### Advanced Document Operations + +```python +from crewai import Agent, Task, Crew + +# Create an agent for advanced document operations +document_formatter = Agent( + role="Document Formatter", + goal="Apply advanced formatting and structure to Google Docs", + backstory="An AI assistant that handles complex document formatting and organization.", + apps=['google_docs/batch_update', 'google_docs/insert_page_break', 'google_docs/create_named_range'] +) + +# Task to format document +format_doc_task = Task( + description="In document 'your_document_id', insert a page break at position 100, create a named range called 'Introduction' for characters 1-50, and apply batch formatting updates.", + agent=document_formatter, + expected_output="Document formatted with page break, named range, and styling applied." +) + +crew = Crew( + agents=[document_formatter], + tasks=[format_doc_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Authentication Errors** + +- Ensure your Google account has the necessary permissions for Google Docs access. +- Verify that the OAuth connection includes all required scopes (`https://www.googleapis.com/auth/documents`). + +**Document ID Issues** + +- Double-check document IDs for correctness. +- Ensure the document exists and is accessible to your account. +- Document IDs can be found in the Google Docs URL. + +**Text Insertion and Range Operations** + +- When using `insert_text` or `delete_content_range`, ensure index positions are valid. +- Remember that Google Docs uses zero-based indexing. +- The document must have content at the specified index positions. + +**Batch Update Request Formatting** + +- When using `batch_update`, ensure the `requests` array is correctly formatted according to the Google Docs API documentation. +- Complex updates require specific JSON structures for each request type. + +**Replace Text Operations** + +- For `replace_text`, ensure the `containsText` parameter exactly matches the text you want to replace. +- Use `matchCase` parameter to control case sensitivity. + +### Getting Help + + + Contact our support team for assistance with Google Docs integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/google_drive.mdx b/docs/v1.15.1/en/enterprise/integrations/google_drive.mdx new file mode 100644 index 000000000..977c4e729 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/google_drive.mdx @@ -0,0 +1,239 @@ +--- +title: Google Drive Integration +description: "File storage and management with Google Drive integration for CrewAI." +icon: "google" +mode: "wide" +--- + +## Overview + +Enable your agents to manage files and folders through Google Drive. Upload, download, organize, and share files, create folders, and streamline your document management workflows with AI-powered automation. + +## Prerequisites + +Before using the Google Drive integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Google account with Google Drive access +- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Google Drive Integration + +### 1. Connect Your Google Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Google Drive** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for file and folder management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Get a file by ID from Google Drive. + + **Parameters:** + - `file_id` (string, required): The ID of the file to retrieve. + + + + + **Description:** List files in Google Drive. + + **Parameters:** + - `q` (string, optional): Query string to filter files (example: "name contains 'report'"). + - `page_size` (integer, optional): Maximum number of files to return (default: 100, max: 1000). + - `page_token` (string, optional): Token for retrieving the next page of results. + - `order_by` (string, optional): Sort order (example: "name", "createdTime desc", "modifiedTime"). + - `spaces` (string, optional): Comma-separated list of spaces to query (drive, appDataFolder, photos). + + + + + **Description:** Upload a file to Google Drive. + + **Parameters:** + - `name` (string, required): Name of the file to create. + - `content` (string, required): Content of the file to upload. + - `mime_type` (string, optional): MIME type of the file (example: "text/plain", "application/pdf"). + - `parent_folder_id` (string, optional): ID of the parent folder where the file should be created. + - `description` (string, optional): Description of the file. + + + + + **Description:** Download a file from Google Drive. + + **Parameters:** + - `file_id` (string, required): The ID of the file to download. + - `mime_type` (string, optional): MIME type for export (required for Google Workspace documents). + + + + + **Description:** Create a new folder in Google Drive. + + **Parameters:** + - `name` (string, required): Name of the folder to create. + - `parent_folder_id` (string, optional): ID of the parent folder where the new folder should be created. + - `description` (string, optional): Description of the folder. + + + + + **Description:** Delete a file from Google Drive. + + **Parameters:** + - `file_id` (string, required): The ID of the file to delete. + + + + + **Description:** Share a file in Google Drive with specific users or make it public. + + **Parameters:** + - `file_id` (string, required): The ID of the file to share. + - `role` (string, required): The role granted by this permission (reader, writer, commenter, owner). + - `type` (string, required): The type of the grantee (user, group, domain, anyone). + - `email_address` (string, optional): The email address of the user or group to share with (required for user/group types). + - `domain` (string, optional): The domain to share with (required for domain type). + - `send_notification_email` (boolean, optional): Whether to send a notification email (default: true). + - `email_message` (string, optional): A plain text custom message to include in the notification email. + + + + + **Description:** Update an existing file in Google Drive. + + **Parameters:** + - `file_id` (string, required): The ID of the file to update. + - `name` (string, optional): New name for the file. + - `content` (string, optional): New content for the file. + - `mime_type` (string, optional): New MIME type for the file. + - `description` (string, optional): New description for the file. + - `add_parents` (string, optional): Comma-separated list of parent folder IDs to add. + - `remove_parents` (string, optional): Comma-separated list of parent folder IDs to remove. + + + + +## Usage Examples + +### Basic Google Drive Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Drive capabilities +drive_agent = Agent( + role="File Manager", + goal="Manage files and folders in Google Drive efficiently", + backstory="An AI assistant specialized in document and file management.", + apps=['google_drive'] # All Google Drive actions will be available +) + +# Task to organize files +organize_files_task = Task( + description="List all files in the root directory and organize them into appropriate folders", + agent=drive_agent, + expected_output="Summary of files organized with folder structure" +) + +# Run the task +crew = Crew( + agents=[drive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +### Filtering Specific Google Drive Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Google Drive actions only +file_manager_agent = Agent( + role="Document Manager", + goal="Upload and manage documents efficiently", + backstory="An AI assistant that focuses on document upload and organization.", + apps=[ + 'google_drive/upload_file', + 'google_drive/create_folder', + 'google_drive/share_file' + ] # Specific Google Drive actions +) + +# Task to upload and share documents +document_task = Task( + description="Upload the quarterly report and share it with the finance team", + agent=file_manager_agent, + expected_output="Document uploaded and sharing permissions configured" +) + +crew = Crew( + agents=[file_manager_agent], + tasks=[document_task] +) + +crew.kickoff() +``` + +### Advanced File Management + +```python +from crewai import Agent, Task, Crew + +file_organizer = Agent( + role="File Organizer", + goal="Maintain organized file structure and manage permissions", + backstory="An experienced file manager who ensures proper organization and access control.", + apps=['google_drive'] +) + +# Complex task involving multiple Google Drive operations +organization_task = Task( + description=""" + 1. List all files in the shared folder + 2. Create folders for different document types (Reports, Presentations, Spreadsheets) + 3. Move files to appropriate folders based on their type + 4. Set appropriate sharing permissions for each folder + 5. Create a summary document of the organization changes + """, + agent=file_organizer, + expected_output="Files organized into categorized folders with proper permissions and summary report" +) + +crew = Crew( + agents=[file_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/en/enterprise/integrations/google_sheets.mdx b/docs/v1.15.1/en/enterprise/integrations/google_sheets.mdx new file mode 100644 index 000000000..7d54d6532 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/google_sheets.mdx @@ -0,0 +1,369 @@ +--- +title: Google Sheets Integration +description: "Spreadsheet data synchronization with Google Sheets integration for CrewAI." +icon: "google" +mode: "wide" +--- + +## Overview + +Enable your agents to manage spreadsheet data through Google Sheets. Read rows, create new entries, update existing data, and streamline your data management workflows with AI-powered automation. Perfect for data tracking, reporting, and collaborative data management. + +## Prerequisites + +Before using the Google Sheets integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Google account with Google Sheets access +- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) +- Spreadsheets with proper column headers for data operations + +## Setting Up Google Sheets Integration + +### 1. Connect Your Google Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Google Sheets** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for spreadsheet access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Retrieve properties and data of a spreadsheet. + + **Parameters:** + - `spreadsheetId` (string, required): The ID of the spreadsheet to retrieve. + - `ranges` (array, optional): The ranges to retrieve from the spreadsheet. + - `includeGridData` (boolean, optional): True if grid data should be returned. Default: false + - `fields` (string, optional): The fields to include in the response. Use this to improve performance by only returning needed data. + + + + + **Description:** Returns a range of values from a spreadsheet. + + **Parameters:** + - `spreadsheetId` (string, required): The ID of the spreadsheet to retrieve data from. + - `range` (string, required): The A1 notation or R1C1 notation of the range to retrieve values from. + - `valueRenderOption` (string, optional): How values should be represented in the output. Options: FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA. Default: FORMATTED_VALUE + - `dateTimeRenderOption` (string, optional): How dates, times, and durations should be represented in the output. Options: SERIAL_NUMBER, FORMATTED_STRING. Default: SERIAL_NUMBER + - `majorDimension` (string, optional): The major dimension that results should use. Options: ROWS, COLUMNS. Default: ROWS + + + + + **Description:** Sets values in a range of a spreadsheet. + + **Parameters:** + - `spreadsheetId` (string, required): The ID of the spreadsheet to update. + - `range` (string, required): The A1 notation of the range to update. + - `values` (array, required): The data to be written. Each array represents a row. + ```json + [ + ["Value1", "Value2", "Value3"], + ["Value4", "Value5", "Value6"] + ] + ``` + - `valueInputOption` (string, optional): How the input data should be interpreted. Options: RAW, USER_ENTERED. Default: USER_ENTERED + + + + + **Description:** Appends values to a spreadsheet. + + **Parameters:** + - `spreadsheetId` (string, required): The ID of the spreadsheet to update. + - `range` (string, required): The A1 notation of a range to search for a logical table of data. + - `values` (array, required): The data to append. Each array represents a row. + ```json + [ + ["Value1", "Value2", "Value3"], + ["Value4", "Value5", "Value6"] + ] + ``` + - `valueInputOption` (string, optional): How the input data should be interpreted. Options: RAW, USER_ENTERED. Default: USER_ENTERED + - `insertDataOption` (string, optional): How the input data should be inserted. Options: OVERWRITE, INSERT_ROWS. Default: INSERT_ROWS + + + + + **Description:** Creates a new spreadsheet. + + **Parameters:** + - `title` (string, required): The title of the new spreadsheet. + - `sheets` (array, optional): The sheets that are part of the spreadsheet. + ```json + [ + { + "properties": { + "title": "Sheet1" + } + } + ] + ``` + + + + +## Usage Examples + +### Basic Google Sheets Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Sheets capabilities +sheets_agent = Agent( + role="Data Manager", + goal="Manage spreadsheet data and track information efficiently", + backstory="An AI assistant specialized in data management and spreadsheet operations.", + apps=['google_sheets'] +) + +# Task to add new data to a spreadsheet +data_entry_task = Task( + description="Add a new customer record to the customer database spreadsheet with name, email, and signup date", + agent=sheets_agent, + expected_output="New customer record added successfully to the spreadsheet" +) + +# Run the task +crew = Crew( + agents=[sheets_agent], + tasks=[data_entry_task] +) + +crew.kickoff() +``` + +### Filtering Specific Google Sheets Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Google Sheets actions only +data_collector = Agent( + role="Data Collector", + goal="Collect and organize data in spreadsheets", + backstory="An AI assistant that focuses on data collection and organization.", + apps=[ + 'google_sheets/get_values', + 'google_sheets/update_values' + ] +) + +# Task to collect and organize data +data_collection = Task( + description="Retrieve current inventory data and add new product entries to the inventory spreadsheet", + agent=data_collector, + expected_output="Inventory data retrieved and new products added successfully" +) + +crew = Crew( + agents=[data_collector], + tasks=[data_collection] +) + +crew.kickoff() +``` + +### Data Analysis and Reporting + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Data Analyst", + goal="Analyze spreadsheet data and generate insights", + backstory="An experienced data analyst who extracts insights from spreadsheet data.", + apps=['google_sheets'] +) + +# Task to analyze data and create reports +analysis_task = Task( + description=""" + 1. Retrieve all sales data from the current month's spreadsheet + 2. Analyze the data for trends and patterns + 3. Create a summary report in a new row with key metrics + """, + agent=data_analyst, + expected_output="Sales data analyzed and summary report created with key insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Spreadsheet Creation and Management + +```python +from crewai import Agent, Task, Crew + +spreadsheet_manager = Agent( + role="Spreadsheet Manager", + goal="Create and manage spreadsheets efficiently", + backstory="An AI assistant that specializes in creating and organizing spreadsheets.", + apps=['google_sheets'] +) + +# Task to create and set up new spreadsheets +setup_task = Task( + description=""" + 1. Create a new spreadsheet for quarterly reports + 2. Set up proper headers and structure + 3. Add initial data and formatting + """, + agent=spreadsheet_manager, + expected_output="New quarterly report spreadsheet created and properly structured" +) + +crew = Crew( + agents=[spreadsheet_manager], + tasks=[setup_task] +) + +crew.kickoff() +``` + +### Automated Data Updates + +```python +from crewai import Agent, Task, Crew + +data_updater = Agent( + role="Data Updater", + goal="Automatically update and maintain spreadsheet data", + backstory="An AI assistant that maintains data accuracy and updates records automatically.", + apps=['google_sheets'] +) + +# Task to update data based on conditions +update_task = Task( + description=""" + 1. Get spreadsheet properties and structure + 2. Read current data from specific ranges + 3. Update values in target ranges with new data + 4. Append new records to the bottom of the sheet + """, + agent=data_updater, + expected_output="Spreadsheet data updated successfully with new values and records" +) + +crew = Crew( + agents=[data_updater], + tasks=[update_task] +) + +crew.kickoff() +``` + +### Complex Data Management Workflow + +```python +from crewai import Agent, Task, Crew + +workflow_manager = Agent( + role="Data Workflow Manager", + goal="Manage complex data workflows across multiple spreadsheets", + backstory="An AI assistant that orchestrates complex data operations across multiple spreadsheets.", + apps=['google_sheets'] +) + +# Complex workflow task +workflow_task = Task( + description=""" + 1. Get all customer data from the main customer spreadsheet + 2. Create a new monthly summary spreadsheet + 3. Append summary data to the new spreadsheet + 4. Update customer status based on activity metrics + 5. Generate reports with proper formatting + """, + agent=workflow_manager, + expected_output="Monthly customer workflow completed with new spreadsheet and updated data" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Google account has edit access to the target spreadsheets +- Verify that the OAuth connection includes required scopes for Google Sheets API +- Check that spreadsheets are shared with the authenticated account + +**Spreadsheet Structure Issues** + +- Ensure worksheets have proper column headers before creating or updating rows +- Verify that range notation (A1 format) is correct for the target cells +- Check that the specified spreadsheet ID exists and is accessible + +**Data Type and Format Issues** + +- Ensure data values match the expected format for each column +- Use proper date formats for date columns (ISO format recommended) +- Verify that numeric values are properly formatted for number columns + +**Range and Cell Reference Issues** + +- Use proper A1 notation for ranges (e.g., "A1:C10", "Sheet1!A1:B5") +- Ensure range references don't exceed the actual spreadsheet dimensions +- Verify that sheet names in range references match actual sheet names + +**Value Input and Rendering Options** + +- Choose appropriate `valueInputOption` (RAW vs USER_ENTERED) for your data +- Select proper `valueRenderOption` based on how you want data formatted +- Consider `dateTimeRenderOption` for consistent date/time handling + +**Spreadsheet Creation Issues** + +- Ensure spreadsheet titles are unique and follow naming conventions +- Verify that sheet properties are properly structured when creating sheets +- Check that you have permissions to create new spreadsheets in your account + +### Getting Help + + + Contact our support team for assistance with Google Sheets integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/google_slides.mdx b/docs/v1.15.1/en/enterprise/integrations/google_slides.mdx new file mode 100644 index 000000000..20efe0a0a --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/google_slides.mdx @@ -0,0 +1,546 @@ +--- +title: Google Slides Integration +description: "Presentation creation and management with Google Slides integration for CrewAI." +icon: "chart-bar" +mode: "wide" +--- + +## Overview + +Enable your agents to create, edit, and manage Google Slides presentations. Create presentations, update content, import data from Google Sheets, manage pages and thumbnails, and streamline your presentation workflows with AI-powered automation. + +## Prerequisites + +Before using the Google Slides integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Google account with Google Slides access +- Connected your Google account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Google Slides Integration + +### 1. Connect Your Google Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Google Slides** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for presentations, spreadsheets, and drive access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Creates a blank presentation with no content. + + **Parameters:** + - `title` (string, required): The title of the presentation. + + + + + **Description:** Get lightweight metadata about a presentation (title, slide count, slide IDs). Use this first before fetching full content. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation to retrieve. + + + + + **Description:** Extract all text content from a presentation. Returns slide IDs and text from shapes and tables only (no formatting). + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + + + + + **Description:** Retrieves a presentation by ID. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation to retrieve. + - `fields` (string, optional): The fields to include in the response. Use this to improve performance by only returning needed data. + + + + + **Description:** Applies updates, add content, or remove content from a presentation. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation to update. + - `requests` (array, required): A list of updates to apply to the presentation. + ```json + [ + { + "insertText": { + "objectId": "slide_id", + "text": "Your text content here" + } + } + ] + ``` + - `writeControl` (object, optional): Provides control over how write requests are executed. + ```json + { + "requiredRevisionId": "revision_id_string" + } + ``` + + + + + **Description:** Extract text content from a single slide. Returns only text from shapes and tables (no formatting or styling). + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `pageObjectId` (string, required): The ID of the slide/page to get text from. + + + + + **Description:** Retrieves a specific page by its ID. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `pageObjectId` (string, required): The ID of the page to retrieve. + + + + + **Description:** Generates a page thumbnail. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `pageObjectId` (string, required): The ID of the page for thumbnail generation. + + + + + **Description:** Add an additional blank slide to a presentation. New presentations already have one blank slide - check get_presentation_metadata first. For slides with title/body areas, use create_slide_with_layout instead. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `insertionIndex` (integer, optional): Where to insert the slide (0-based). If omitted, adds at the end. + + + + + **Description:** Create a slide with a predefined layout containing placeholder areas for title, body, etc. This is better than create_slide for structured content. After creating, use get_page to find placeholder IDs, then insert text into them. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `layout` (string, required): Layout type. One of: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. TITLE_AND_BODY is best for title+description. TITLE for title-only slides. SECTION_HEADER for section dividers. + - `insertionIndex` (integer, optional): Where to insert (0-based). Omit to add at end. + + + + + **Description:** Create a text box on a slide with content. Use this for titles, descriptions, paragraphs - not tables. Optionally specify position (x, y) and size (width, height) in EMU units (914400 EMU = 1 inch). + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The ID of the slide to add the text box to. + - `text` (string, required): The text content for the text box. + - `x` (integer, optional): X position in EMU (914400 = 1 inch). Default: 914400 (1 inch from left). + - `y` (integer, optional): Y position in EMU (914400 = 1 inch). Default: 914400 (1 inch from top). + - `width` (integer, optional): Width in EMU. Default: 7315200 (~8 inches). + - `height` (integer, optional): Height in EMU. Default: 914400 (~1 inch). + + + + + **Description:** Remove a slide from the presentation. Use get_presentation first to find the slide ID. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The object ID of the slide to delete. Get from get_presentation. + + + + + **Description:** Create a copy of an existing slide. The duplicate is inserted immediately after the original. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The object ID of the slide to duplicate. Get from get_presentation. + + + + + **Description:** Reorder slides by moving them to a new position. Slide IDs must be in their current presentation order (no duplicates). + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideIds` (array of strings, required): Array of slide IDs to move. Must be in current presentation order. + - `insertionIndex` (integer, required): Target position (0-based). 0 = beginning, slide count = end. + + + + + **Description:** Embed a YouTube video on a slide. The video ID is the value after "v=" in YouTube URLs (e.g., for youtube.com/watch?v=abc123, use "abc123"). + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The ID of the slide to add the video to. Get from get_presentation. + - `videoId` (string, required): The YouTube video ID (the value after v= in the URL). + + + + + **Description:** Embed a video from Google Drive on a slide. The file ID can be found in the Drive file URL. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The ID of the slide to add the video to. Get from get_presentation. + - `fileId` (string, required): The Google Drive file ID of the video. + + + + + **Description:** Set a background image for a slide. The image URL must be publicly accessible. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The ID of the slide to set the background for. Get from get_presentation. + - `imageUrl` (string, required): Publicly accessible URL of the image to use as background. + + + + + **Description:** Create an empty table on a slide. To create a table with content, use create_table_with_content instead. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The ID of the slide to add the table to. Get from get_presentation. + - `rows` (integer, required): Number of rows in the table. + - `columns` (integer, required): Number of columns in the table. + + + + + **Description:** Create a table with content in one action. Provide content as a 2D array where each inner array is a row. Example: [["Header1", "Header2"], ["Row1Col1", "Row1Col2"]]. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `slideId` (string, required): The ID of the slide to add the table to. Get from get_presentation. + - `rows` (integer, required): Number of rows in the table. + - `columns` (integer, required): Number of columns in the table. + - `content` (array, required): Table content as 2D array. Each inner array is a row. Example: [["Year", "Revenue"], ["2023", "$10M"]]. + + + + + **Description:** Imports data from a Google Sheet into a presentation. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `sheetId` (string, required): The ID of the Google Sheet to import from. + - `dataRange` (string, required): The range of data to import from the sheet. + + + + + **Description:** Uploads a file to Google Drive associated with the presentation. + + **Parameters:** + - `file` (string, required): The file data to upload. + - `presentationId` (string, required): The ID of the presentation to link the uploaded file. + + + + + **Description:** Links a file in Google Drive to a presentation. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation. + - `fileId` (string, required): The ID of the file to link. + + + + + **Description:** Lists all presentations accessible to the user. + + **Parameters:** + - `pageSize` (integer, optional): The number of presentations to return per page. + - `pageToken` (string, optional): A token for pagination. + + + + + **Description:** Deletes a presentation by ID. + + **Parameters:** + - `presentationId` (string, required): The ID of the presentation to delete. + + + + +## Usage Examples + +### Basic Google Slides Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Slides capabilities +slides_agent = Agent( + role="Presentation Manager", + goal="Create and manage presentations efficiently", + backstory="An AI assistant specialized in presentation creation and content management.", + apps=['google_slides'] # All Google Slides actions will be available +) + +# Task to create a presentation +create_presentation_task = Task( + description="Create a new presentation for the quarterly business review with key slides", + agent=slides_agent, + expected_output="Quarterly business review presentation created with structured content" +) + +# Run the task +crew = Crew( + agents=[slides_agent], + tasks=[create_presentation_task] +) + +crew.kickoff() +``` + +### Presentation Content Management + +```python +from crewai import Agent, Task, Crew + +content_manager = Agent( + role="Content Manager", + goal="Manage presentation content and updates", + backstory="An AI assistant that focuses on content creation and presentation updates.", + apps=[ + 'google_slides/create_blank_presentation', + 'google_slides/batch_update_presentation', + 'google_slides/get_presentation' + ] +) + +# Task to create and update presentations +content_task = Task( + description="Create a new presentation and add content slides with charts and text", + agent=content_manager, + expected_output="Presentation created with updated content and visual elements" +) + +crew = Crew( + agents=[content_manager], + tasks=[content_task] +) + +crew.kickoff() +``` + +### Data Integration and Visualization + +```python +from crewai import Agent, Task, Crew + +data_visualizer = Agent( + role="Data Visualizer", + goal="Create presentations with data imported from spreadsheets", + backstory="An AI assistant that specializes in data visualization and presentation integration.", + apps=['google_slides'] +) + +# Task to create data-driven presentations +visualization_task = Task( + description=""" + 1. Create a new presentation for monthly sales report + 2. Import data from the sales spreadsheet + 3. Create charts and visualizations from the imported data + 4. Generate thumbnails for slide previews + """, + agent=data_visualizer, + expected_output="Data-driven presentation created with imported spreadsheet data and visualizations" +) + +crew = Crew( + agents=[data_visualizer], + tasks=[visualization_task] +) + +crew.kickoff() +``` + +### Presentation Library Management + +```python +from crewai import Agent, Task, Crew + +library_manager = Agent( + role="Presentation Library Manager", + goal="Manage and organize presentation libraries", + backstory="An AI assistant that manages presentation collections and file organization.", + apps=['google_slides'] +) + +# Task to manage presentation library +library_task = Task( + description=""" + 1. List all existing presentations + 2. Generate thumbnails for presentation previews + 3. Upload supporting files to Drive and link to presentations + 4. Organize presentations by topic and date + """, + agent=library_manager, + expected_output="Presentation library organized with thumbnails and linked supporting files" +) + +crew = Crew( + agents=[library_manager], + tasks=[library_task] +) + +crew.kickoff() +``` + +### Automated Presentation Workflows + +```python +from crewai import Agent, Task, Crew + +presentation_automator = Agent( + role="Presentation Automator", + goal="Automate presentation creation and management workflows", + backstory="An AI assistant that automates complex presentation workflows and content generation.", + apps=['google_slides'] +) + +# Complex presentation automation task +automation_task = Task( + description=""" + 1. Create multiple presentations for different departments + 2. Import relevant data from various spreadsheets + 3. Update existing presentations with new content + 4. Generate thumbnails for all presentations + 5. Link supporting documents from Drive + 6. Create a master index presentation with links to all others + """, + agent=presentation_automator, + expected_output="Automated presentation workflow completed with multiple presentations and organized structure" +) + +crew = Crew( + agents=[presentation_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### Template and Content Creation + +```python +from crewai import Agent, Task, Crew + +template_creator = Agent( + role="Template Creator", + goal="Create presentation templates and standardized content", + backstory="An AI assistant that creates consistent presentation templates and content standards.", + apps=['google_slides'] +) + +# Task to create templates +template_task = Task( + description=""" + 1. Create blank presentation templates for different use cases + 2. Add standard layouts and content placeholders + 3. Create sample presentations with best practices + 4. Generate thumbnails for template previews + 5. Upload template assets to Drive and link appropriately + """, + agent=template_creator, + expected_output="Presentation templates created with standardized layouts and linked assets" +) + +crew = Crew( + agents=[template_creator], + tasks=[template_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Google account has appropriate permissions for Google Slides +- Verify that the OAuth connection includes required scopes for presentations, spreadsheets, and drive access +- Check that presentations are shared with the authenticated account + +**Presentation ID Issues** + +- Verify that presentation IDs are correct and presentations exist +- Ensure you have access permissions to the presentations you're trying to modify +- Check that presentation IDs are properly formatted + +**Content Update Issues** + +- Ensure batch update requests are properly formatted according to Google Slides API specifications +- Verify that object IDs for slides and elements exist in the presentation +- Check that write control revision IDs are current if using optimistic concurrency + +**Data Import Issues** + +- Verify that Google Sheet IDs are correct and accessible +- Ensure data ranges are properly specified using A1 notation +- Check that you have read permissions for the source spreadsheets + +**File Upload and Linking Issues** + +- Ensure file data is properly encoded for upload +- Verify that Drive file IDs are correct when linking files +- Check that you have appropriate Drive permissions for file operations + +**Page and Thumbnail Operations** + +- Verify that page object IDs exist in the specified presentation +- Ensure presentations have content before attempting to generate thumbnails +- Check that page structure is valid for thumbnail generation + +**Pagination and Listing Issues** + +- Use appropriate page sizes for listing presentations +- Implement proper pagination using page tokens for large result sets +- Handle empty result sets gracefully + +### Getting Help + + + Contact our support team for assistance with Google Slides integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/hubspot.mdx b/docs/v1.15.1/en/enterprise/integrations/hubspot.mdx new file mode 100644 index 000000000..f5f4279c0 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/hubspot.mdx @@ -0,0 +1,616 @@ +--- +title: "HubSpot Integration" +description: "Manage companies and contacts in HubSpot with CrewAI." +icon: "briefcase" +mode: "wide" +--- + +## Overview + +Enable your agents to manage companies and contacts within HubSpot. Create new records and streamline your CRM processes with AI-powered automation. + +## Prerequisites + +Before using the HubSpot integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription. +- A HubSpot account with appropriate permissions. +- Connected your HubSpot account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors). + +## Setting Up HubSpot Integration + +### 1. Connect Your HubSpot Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors). +2. Find **HubSpot** in the Authentication Integrations section. +3. Click **Connect** and complete the OAuth flow. +4. Grant the necessary permissions for company and contact management. +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create a new company record in HubSpot. + + **Parameters:** + - `name` (string, required): Name of the company. + - `domain` (string, optional): Company Domain Name. + - `industry` (string, optional): Industry. Must be one of the predefined values from HubSpot. + - `phone` (string, optional): Phone Number. + - `hubspot_owner_id` (string, optional): Company owner ID. + - `type` (string, optional): Type of the company. Available values: `PROSPECT`, `PARTNER`, `RESELLER`, `VENDOR`, `OTHER`. + - `city` (string, optional): City. + - `state` (string, optional): State/Region. + - `zip` (string, optional): Postal Code. + - `numberofemployees` (number, optional): Number of Employees. + - `annualrevenue` (number, optional): Annual Revenue. + - `timezone` (string, optional): Time Zone. + - `description` (string, optional): Description. + - `linkedin_company_page` (string, optional): LinkedIn Company Page URL. + - `company_email` (string, optional): Company Email. + - `first_name` (string, optional): First Name of a contact at the company. + - `last_name` (string, optional): Last Name of a contact at the company. + - `about_us` (string, optional): About Us. + - `hs_csm_sentiment` (string, optional): CSM Sentiment. Available values: `at_risk`, `neutral`, `healthy`. + - `closedate` (string, optional): Close Date. + - `hs_keywords` (string, optional): Company Keywords. Must be one of the predefined values. + - `country` (string, optional): Country/Region. + - `hs_country_code` (string, optional): Country/Region Code. + - `hs_employee_range` (string, optional): Employee range. + - `facebook_company_page` (string, optional): Facebook Company Page URL. + - `facebookfans` (number, optional): Number of Facebook Fans. + - `hs_gps_coordinates` (string, optional): GPS Coordinates. + - `hs_gps_error` (string, optional): GPS Error. + - `googleplus_page` (string, optional): Google Plus Page URL. + - `owneremail` (string, optional): HubSpot Owner Email. + - `ownername` (string, optional): HubSpot Owner Name. + - `hs_ideal_customer_profile` (string, optional): Ideal Customer Profile Tier. Available values: `tier_1`, `tier_2`, `tier_3`. + - `hs_industry_group` (string, optional): Industry group. + - `is_public` (boolean, optional): Is Public. + - `hs_last_metered_enrichment_timestamp` (string, optional): Last Metered Enrichment Timestamp. + - `hs_lead_status` (string, optional): Lead Status. Available values: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`. + - `lifecyclestage` (string, optional): Lifecycle Stage. Available values: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`. + - `linkedinbio` (string, optional): LinkedIn Bio. + - `hs_linkedin_handle` (string, optional): LinkedIn handle. + - `hs_live_enrichment_deadline` (string, optional): Live enrichment deadline. + - `hs_logo_url` (string, optional): Logo URL. + - `hs_analytics_source` (string, optional): Original Traffic Source. + - `hs_pinned_engagement_id` (number, optional): Pinned Engagement ID. + - `hs_quick_context` (string, optional): Quick context. + - `hs_revenue_range` (string, optional): Revenue range. + - `hs_state_code` (string, optional): State/Region Code. + - `address` (string, optional): Street Address. + - `address2` (string, optional): Street Address 2. + - `hs_is_target_account` (boolean, optional): Target Account. + - `hs_target_account` (string, optional): Target Account Tier. Available values: `tier_1`, `tier_2`, `tier_3`. + - `hs_target_account_recommendation_snooze_time` (string, optional): Target Account Recommendation Snooze Time. + - `hs_target_account_recommendation_state` (string, optional): Target Account Recommendation State. Available values: `DISMISSED`, `NONE`, `SNOOZED`. + - `total_money_raised` (string, optional): Total Money Raised. + - `twitterbio` (string, optional): Twitter Bio. + - `twitterfollowers` (number, optional): Twitter Followers. + - `twitterhandle` (string, optional): Twitter Handle. + - `web_technologies` (string, optional): Web Technologies used. Must be one of the predefined values. + - `website` (string, optional): Website URL. + - `founded_year` (string, optional): Year Founded. + + + + + **Description:** Create a new contact record in HubSpot. + + **Parameters:** + - `email` (string, required): Email address of the contact. + - `firstname` (string, optional): First Name. + - `lastname` (string, optional): Last Name. + - `phone` (string, optional): Phone Number. + - `hubspot_owner_id` (string, optional): Contact owner. + - `lifecyclestage` (string, optional): Lifecycle Stage. Available values: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`. + - `hs_lead_status` (string, optional): Lead Status. Available values: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`. + - `annualrevenue` (string, optional): Annual Revenue. + - `hs_buying_role` (string, optional): Buying Role. + - `cc_emails` (string, optional): CC Emails. + - `ch_customer_id` (string, optional): Chargify Customer ID. + - `ch_customer_reference` (string, optional): Chargify Customer Reference. + - `chargify_sites` (string, optional): Chargify Site(s). + - `city` (string, optional): City. + - `hs_facebook_ad_clicked` (boolean, optional): Clicked Facebook ad. + - `hs_linkedin_ad_clicked` (string, optional): Clicked LinkedIn Ad. + - `hs_clicked_linkedin_ad` (string, optional): Clicked on a LinkedIn Ad. + - `closedate` (string, optional): Close Date. + - `company` (string, optional): Company Name. + - `company_size` (string, optional): Company size. + - `country` (string, optional): Country/Region. + - `hs_country_region_code` (string, optional): Country/Region Code. + - `date_of_birth` (string, optional): Date of birth. + - `degree` (string, optional): Degree. + - `hs_email_customer_quarantined_reason` (string, optional): Email address quarantine reason. + - `hs_role` (string, optional): Employment Role. Must be one of the predefined values. + - `hs_seniority` (string, optional): Employment Seniority. Must be one of the predefined values. + - `hs_sub_role` (string, optional): Employment Sub Role. Must be one of the predefined values. + - `hs_employment_change_detected_date` (string, optional): Employment change detected date. + - `hs_enriched_email_bounce_detected` (boolean, optional): Enriched Email Bounce Detected. + - `hs_facebookid` (string, optional): Facebook ID. + - `hs_facebook_click_id` (string, optional): Facebook click id. + - `fax` (string, optional): Fax Number. + - `field_of_study` (string, optional): Field of study. + - `followercount` (number, optional): Follower Count. + - `gender` (string, optional): Gender. + - `hs_google_click_id` (string, optional): Google ad click id. + - `graduation_date` (string, optional): Graduation date. + - `owneremail` (string, optional): HubSpot Owner Email (legacy). + - `ownername` (string, optional): HubSpot Owner Name (legacy). + - `industry` (string, optional): Industry. + - `hs_inferred_language_codes` (string, optional): Inferred Language Codes. Must be one of the predefined values. + - `jobtitle` (string, optional): Job Title. + - `hs_job_change_detected_date` (string, optional): Job change detected date. + - `job_function` (string, optional): Job function. + - `hs_journey_stage` (string, optional): Journey Stage. Must be one of the predefined values. + - `kloutscoregeneral` (number, optional): Klout Score. + - `hs_last_metered_enrichment_timestamp` (string, optional): Last Metered Enrichment Timestamp. + - `hs_latest_source` (string, optional): Latest Traffic Source. + - `hs_latest_source_timestamp` (string, optional): Latest Traffic Source Date. + - `hs_legal_basis` (string, optional): Legal basis for processing contact's data. + - `linkedinbio` (string, optional): LinkedIn Bio. + - `linkedinconnections` (number, optional): LinkedIn Connections. + - `hs_linkedin_url` (string, optional): LinkedIn URL. + - `hs_linkedinid` (string, optional): Linkedin ID. + - `hs_live_enrichment_deadline` (string, optional): Live enrichment deadline. + - `marital_status` (string, optional): Marital Status. + - `hs_content_membership_email` (string, optional): Member email. + - `hs_content_membership_notes` (string, optional): Membership Notes. + - `message` (string, optional): Message. + - `military_status` (string, optional): Military status. + - `mobilephone` (string, optional): Mobile Phone Number. + - `numemployees` (string, optional): Number of Employees. + - `hs_analytics_source` (string, optional): Original Traffic Source. + - `photo` (string, optional): Photo. + - `hs_pinned_engagement_id` (number, optional): Pinned engagement ID. + - `zip` (string, optional): Postal Code. + - `hs_language` (string, optional): Preferred language. Must be one of the predefined values. + - `associatedcompanyid` (number, optional): Primary Associated Company ID. + - `hs_email_optout_survey_reason` (string, optional): Reason for opting out of email. + - `relationship_status` (string, optional): Relationship Status. + - `hs_returning_to_office_detected_date` (string, optional): Returning to office detected date. + - `salutation` (string, optional): Salutation. + - `school` (string, optional): School. + - `seniority` (string, optional): Seniority. + - `hs_feedback_show_nps_web_survey` (boolean, optional): Should be shown an NPS web survey. + - `start_date` (string, optional): Start date. + - `state` (string, optional): State/Region. + - `hs_state_code` (string, optional): State/Region Code. + - `hs_content_membership_status` (string, optional): Status. + - `address` (string, optional): Street Address. + - `tax_exempt` (string, optional): Tax Exempt. + - `hs_timezone` (string, optional): Time Zone. Must be one of the predefined values. + - `twitterbio` (string, optional): Twitter Bio. + - `hs_twitterid` (string, optional): Twitter ID. + - `twitterprofilephoto` (string, optional): Twitter Profile Photo. + - `twitterhandle` (string, optional): Twitter Username. + - `vat_number` (string, optional): VAT Number. + - `ch_verified` (string, optional): Verified for ACH/eCheck Payments. + - `website` (string, optional): Website URL. + - `hs_whatsapp_phone_number` (string, optional): WhatsApp Phone Number. + - `work_email` (string, optional): Work email. + - `hs_googleplusid` (string, optional): googleplus ID. + + + + + **Description:** Create a new deal record in HubSpot. + + **Parameters:** + - `dealname` (string, required): Name of the deal. + - `amount` (number, optional): The value of the deal. + - `dealstage` (string, optional): The pipeline stage of the deal. + - `pipeline` (string, optional): The pipeline the deal belongs to. + - `closedate` (string, optional): The date the deal is expected to close. + - `hubspot_owner_id` (string, optional): The owner of the deal. + - `dealtype` (string, optional): The type of deal. Available values: `newbusiness`, `existingbusiness`. + - `description` (string, optional): A description of the deal. + - `hs_priority` (string, optional): The priority of the deal. Available values: `low`, `medium`, `high`. + + + + + **Description:** Create a new engagement (e.g., note, email, call, meeting, task) in HubSpot. + + **Parameters:** + - `engagementType` (string, required): The type of engagement. Available values: `NOTE`, `EMAIL`, `CALL`, `MEETING`, `TASK`. + - `hubspot_owner_id` (string, optional): The user the activity is assigned to. + - `hs_timestamp` (string, optional): The date and time of the activity. + - `hs_note_body` (string, optional): The body of the note. (Used for `NOTE`) + - `hs_task_subject` (string, optional): The title of the task. (Used for `TASK`) + - `hs_task_body` (string, optional): The notes for the task. (Used for `TASK`) + - `hs_task_status` (string, optional): The status of the task. (Used for `TASK`) + - `hs_meeting_title` (string, optional): The title of the meeting. (Used for `MEETING`) + - `hs_meeting_body` (string, optional): The description for the meeting. (Used for `MEETING`) + - `hs_meeting_start_time` (string, optional): The start time of the meeting. (Used for `MEETING`) + - `hs_meeting_end_time` (string, optional): The end time of the meeting. (Used for `MEETING`) + + + + + **Description:** Update an existing company record in HubSpot. + + **Parameters:** + - `recordId` (string, required): The ID of the company to update. + - `name` (string, optional): Name of the company. + - `domain` (string, optional): Company Domain Name. + - `industry` (string, optional): Industry. + - `phone` (string, optional): Phone Number. + - `city` (string, optional): City. + - `state` (string, optional): State/Region. + - `zip` (string, optional): Postal Code. + - `numberofemployees` (number, optional): Number of Employees. + - `annualrevenue` (number, optional): Annual Revenue. + - `description` (string, optional): Description. + + + + + **Description:** Create a record for a specified object type in HubSpot. + + **Parameters:** + - `recordType` (string, required): The object type ID of the custom object. + - Additional parameters depend on the custom object's schema. + + + + + **Description:** Update an existing contact record in HubSpot. + + **Parameters:** + - `recordId` (string, required): The ID of the contact to update. + - `firstname` (string, optional): First Name. + - `lastname` (string, optional): Last Name. + - `email` (string, optional): Email address. + - `phone` (string, optional): Phone Number. + - `company` (string, optional): Company Name. + - `jobtitle` (string, optional): Job Title. + - `lifecyclestage` (string, optional): Lifecycle Stage. + + + + + **Description:** Update an existing deal record in HubSpot. + + **Parameters:** + - `recordId` (string, required): The ID of the deal to update. + - `dealname` (string, optional): Name of the deal. + - `amount` (number, optional): The value of the deal. + - `dealstage` (string, optional): The pipeline stage of the deal. + - `pipeline` (string, optional): The pipeline the deal belongs to. + - `closedate` (string, optional): The date the deal is expected to close. + - `dealtype` (string, optional): The type of deal. + + + + + **Description:** Update an existing engagement in HubSpot. + + **Parameters:** + - `recordId` (string, required): The ID of the engagement to update. + - `hs_note_body` (string, optional): The body of the note. + - `hs_task_subject` (string, optional): The title of the task. + - `hs_task_body` (string, optional): The notes for the task. + - `hs_task_status` (string, optional): The status of the task. + + + + + **Description:** Update a record for a specified object type in HubSpot. + + **Parameters:** + - `recordId` (string, required): The ID of the record to update. + - `recordType` (string, required): The object type ID of the custom object. + - Additional parameters depend on the custom object's schema. + + + + + **Description:** Get a list of company records from HubSpot. + + **Parameters:** + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Get a list of contact records from HubSpot. + + **Parameters:** + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Get a list of deal records from HubSpot. + + **Parameters:** + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Get a list of engagement records from HubSpot. + + **Parameters:** + - `objectName` (string, required): The type of engagement to fetch (e.g., "notes"). + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Get a list of records for any specified object type in HubSpot. + + **Parameters:** + - `recordType` (string, required): The object type ID of the custom object. + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Get a single company record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the company to retrieve. + + + + + **Description:** Get a single contact record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the contact to retrieve. + + + + + **Description:** Get a single deal record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the deal to retrieve. + + + + + **Description:** Get a single engagement record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the engagement to retrieve. + + + + + **Description:** Get a single record of any specified object type by its ID. + + **Parameters:** + - `recordType` (string, required): The object type ID of the custom object. + - `recordId` (string, required): The ID of the record to retrieve. + + + + + **Description:** Search for company records in HubSpot using a filter formula. + + **Parameters:** + - `filterFormula` (object, optional): A filter in disjunctive normal form (OR of ANDs). + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Search for contact records in HubSpot using a filter formula. + + **Parameters:** + - `filterFormula` (object, optional): A filter in disjunctive normal form (OR of ANDs). + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Search for deal records in HubSpot using a filter formula. + + **Parameters:** + - `filterFormula` (object, optional): A filter in disjunctive normal form (OR of ANDs). + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Search for engagement records in HubSpot using a filter formula. + + **Parameters:** + - `engagementFilterFormula` (object, optional): A filter for engagements. + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Search for records of any specified object type in HubSpot. + + **Parameters:** + - `recordType` (string, required): The object type ID to search. + - `filterFormula` (string, optional): The filter formula to apply. + - `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages. + + + + + **Description:** Delete a company record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the company to delete. + + + + + **Description:** Delete a contact record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the contact to delete. + + + + + **Description:** Delete a deal record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the deal to delete. + + + + + **Description:** Delete an engagement record by its ID. + + **Parameters:** + - `recordId` (string, required): The ID of the engagement to delete. + + + + + **Description:** Delete a record of any specified object type by its ID. + + **Parameters:** + - `recordType` (string, required): The object type ID of the custom object. + - `recordId` (string, required): The ID of the record to delete. + + + + + **Description:** Get contacts from a specific list by its ID. + + **Parameters:** + - `listId` (string, required): The ID of the list to get contacts from. + - `paginationParameters` (object, optional): Use `pageCursor` for subsequent pages. + + + + + **Description:** Get the expected schema for a given object type and operation. + + **Parameters:** + - `recordType` (string, required): The object type ID (e.g., 'companies'). + - `operation` (string, required): The operation type (e.g., 'CREATE_RECORD'). + + + + +## Usage Examples + +### Basic HubSpot Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with HubSpot capabilities +hubspot_agent = Agent( + role="CRM Manager", + goal="Manage company and contact records in HubSpot", + backstory="An AI assistant specialized in CRM management.", + apps=['hubspot'] # All HubSpot actions will be available +) + +# Task to create a new company +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" +) + +# Run the task +crew = Crew( + agents=[hubspot_agent], + tasks=[create_company_task] +) + +crew.kickoff() +``` + +### Filtering Specific HubSpot Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific HubSpot actions only +contact_creator = Agent( + role="Contact Creator", + goal="Create new contacts in HubSpot", + backstory="An AI assistant that focuses on creating new contact entries in the CRM.", + apps=['hubspot/create_contact'] # Only contact creation action +) + +# Task to create a contact +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() +``` + +### Contact Management + +```python +from crewai import Agent, Task, Crew + +# Create agent with HubSpot contact management capabilities +crm_manager = Agent( + role="CRM Manager", + goal="Manage and organize HubSpot contacts efficiently.", + backstory="An experienced CRM manager who maintains an organized contact database.", + apps=['hubspot'] # All HubSpot actions including contact management +) + +# Task to manage contacts +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() +``` + +### Getting Help + + + Contact our support team for assistance with HubSpot integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/jira.mdx b/docs/v1.15.1/en/enterprise/integrations/jira.mdx new file mode 100644 index 000000000..0f9164014 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/jira.mdx @@ -0,0 +1,405 @@ +--- +title: Jira Integration +description: "Issue tracking and project management with Jira integration for CrewAI." +icon: "bug" +mode: "wide" +--- + +## Overview + +Enable your agents to manage issues, projects, and workflows through Jira. Create and update issues, track project progress, manage assignments, and streamline your project management with AI-powered automation. + +## Prerequisites + +Before using the Jira integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Jira account with appropriate project permissions +- Connected your Jira account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Jira Integration + +### 1. Connect Your Jira Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Jira** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for issue and project management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create an issue in Jira. + + **Parameters:** + - `summary` (string, required): Summary - A brief one-line summary of the issue. (example: "The printer stopped working"). + - `project` (string, optional): Project - The project which the issue belongs to. Defaults to the user's first project if not provided. Use Connect Portal Workflow Settings to allow users to select a Project. + - `issueType` (string, optional): Issue type - Defaults to Task if not provided. + - `jiraIssueStatus` (string, optional): Status - Defaults to the project's first status if not provided. + - `assignee` (string, optional): Assignee - Defaults to the authenticated user if not provided. + - `descriptionType` (string, optional): Description Type - Select the Description Type. + - Options: `description`, `descriptionJSON` + - `description` (string, optional): Description - A detailed description of the issue. This field appears only when 'descriptionType' = 'description'. + - `additionalFields` (string, optional): Additional Fields - Specify any other fields that should be included in JSON format. Use Connect Portal Workflow Settings to allow users to select which Issue Fields to update. + ```json + { + "customfield_10001": "value" + } + ``` + + + + + **Description:** Update an issue in Jira. + + **Parameters:** + - `issueKey` (string, required): Issue Key (example: "TEST-1234"). + - `summary` (string, optional): Summary - A brief one-line summary of the issue. (example: "The printer stopped working"). + - `issueType` (string, optional): Issue type - Use Connect Portal Workflow Settings to allow users to select an Issue Type. + - `jiraIssueStatus` (string, optional): Status - Use Connect Portal Workflow Settings to allow users to select a Status. + - `assignee` (string, optional): Assignee - Use Connect Portal Workflow Settings to allow users to select an Assignee. + - `descriptionType` (string, optional): Description Type - Select the Description Type. + - Options: `description`, `descriptionJSON` + - `description` (string, optional): Description - A detailed description of the issue. This field appears only when 'descriptionType' = 'description'. + - `additionalFields` (string, optional): Additional Fields - Specify any other fields that should be included in JSON format. + + + + + **Description:** Get an issue by key in Jira. + + **Parameters:** + - `issueKey` (string, required): Issue Key (example: "TEST-1234"). + + + + + **Description:** Search issues in Jira using filters. + + **Parameters:** + - `jqlQuery` (object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "status", + "operator": "$stringExactlyMatches", + "value": "Open" + } + ] + } + ] + } + ``` + Available operators: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan` + - `limit` (string, optional): Limit results - Limit the maximum number of issues to return. Defaults to 10 if left blank. + + + + + **Description:** Search issues by JQL in Jira. + + **Parameters:** + - `jqlQuery` (string, required): JQL Query (example: "project = PROJECT"). + - `paginationParameters` (object, optional): Pagination parameters for paginated results. + ```json + { + "pageCursor": "cursor_string" + } + ``` + + + + + **Description:** Update any issue in Jira. Use DESCRIBE_ACTION_SCHEMA to get properties schema for this function. + + **Parameters:** No specific parameters - use JIRA_DESCRIBE_ACTION_SCHEMA first to get the expected schema. + + + + + **Description:** Get the expected schema for an issue type. Use this function first if no other function matches the issue type you want to operate on. + + **Parameters:** + - `issueTypeId` (string, required): Issue Type ID. + - `projectKey` (string, required): Project key. + - `operation` (string, required): Operation Type value, for example CREATE_ISSUE or UPDATE_ISSUE. + + + + + **Description:** Get Projects in Jira. + + **Parameters:** + - `paginationParameters` (object, optional): Pagination Parameters. + ```json + { + "pageCursor": "cursor_string" + } + ``` + + + + + **Description:** Get Issue Types by project in Jira. + + **Parameters:** + - `project` (string, required): Project key. + + + + + **Description:** Get all Issue Types in Jira. + + **Parameters:** None required. + + + + + **Description:** Get issue statuses for a given project. + + **Parameters:** + - `project` (string, required): Project key. + + + + + **Description:** Get assignees for a given project. + + **Parameters:** + - `project` (string, required): Project key. + + + + +## Usage Examples + +### Basic Jira Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Jira capabilities +jira_agent = Agent( + role="Issue Manager", + goal="Manage Jira issues and track project progress efficiently", + backstory="An AI assistant specialized in issue tracking and project management.", + apps=['jira'] # All Jira actions will be available +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a bug report for the login functionality with high priority and assign it to the development team", + agent=jira_agent, + expected_output="Bug report created successfully with issue key" +) + +# Run the task +crew = Crew( + agents=[jira_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### Filtering Specific Jira Tools + +```python + +issue_coordinator = Agent( + role="Issue Coordinator", + goal="Create and manage Jira issues efficiently", + backstory="An AI assistant that focuses on issue creation and management.", + apps=['jira'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and update the status of related issues", + agent=issue_coordinator, + expected_output="Feature request created and related issues updated" +) + +crew = Crew( + agents=[issue_coordinator], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Project Analysis and Reporting + +```python +from crewai import Agent, Task, Crew + +project_analyst = Agent( + role="Project Analyst", + goal="Analyze project data and generate insights from Jira", + backstory="An experienced project analyst who extracts insights from project management data.", + apps=['jira'] +) + +# Task to analyze project status +analysis_task = Task( + description=""" + 1. Get all projects and their issue types + 2. Search for all open issues across projects + 3. Analyze issue distribution by status and assignee + 4. Create a summary report issue with findings + """, + agent=project_analyst, + expected_output="Project analysis completed with summary report created" +) + +crew = Crew( + agents=[project_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Automated Issue Management + +```python +from crewai import Agent, Task, Crew + +automation_manager = Agent( + role="Automation Manager", + goal="Automate issue management and workflow processes", + backstory="An AI assistant that automates repetitive issue management tasks.", + apps=['jira'] +) + +# Task to automate issue management +automation_task = Task( + description=""" + 1. Search for all unassigned issues using JQL + 2. Get available assignees for each project + 3. Automatically assign issues based on workload and expertise + 4. Update issue priorities based on age and type + 5. Create weekly sprint planning issues + """, + agent=automation_manager, + expected_output="Issues automatically assigned and sprint planning issues created" +) + +crew = Crew( + agents=[automation_manager], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### Advanced Schema-Based Operations + +```python +from crewai import Agent, Task, Crew + +schema_specialist = Agent( + role="Schema Specialist", + goal="Handle complex Jira operations using dynamic schemas", + backstory="An AI assistant that can work with dynamic Jira schemas and custom issue types.", + apps=['jira'] +) + +# Task using schema-based operations +schema_task = Task( + description=""" + 1. Get all projects and their custom issue types + 2. For each custom issue type, describe the action schema + 3. Create issues using the dynamic schema for complex custom fields + 4. Update issues with custom field values based on business rules + """, + agent=schema_specialist, + expected_output="Custom issues created and updated using dynamic schemas" +) + +crew = Crew( + agents=[schema_specialist], + tasks=[schema_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Jira account has necessary permissions for the target projects +- Verify that the OAuth connection includes required scopes for Jira API +- Check if you have create/edit permissions for issues in the specified projects + +**Invalid Project or Issue Keys** + +- Double-check project keys and issue keys for correct format (e.g., "PROJ-123") +- Ensure projects exist and are accessible to your account +- Verify that issue keys reference existing issues + +**Issue Type and Status Issues** + +- Use JIRA_GET_ISSUE_TYPES_BY_PROJECT to get valid issue types for a project +- Use JIRA_GET_ISSUE_STATUS_BY_PROJECT to get valid statuses +- Ensure issue types and statuses are available in the target project + +**JQL Query Problems** + +- Test JQL queries in Jira's issue search before using in API calls +- Ensure field names in JQL are spelled correctly and exist in your Jira instance +- Use proper JQL syntax for complex queries + +**Custom Fields and Schema Issues** + +- Use JIRA_DESCRIBE_ACTION_SCHEMA to get the correct schema for complex issue types +- Ensure custom field IDs are correct (e.g., "customfield_10001") +- Verify that custom fields are available in the target project and issue type + +**Filter Formula Issues** + +- Ensure filter formulas follow the correct JSON structure for disjunctive normal form +- Use valid field names that exist in your Jira configuration +- Test simple filters before building complex multi-condition queries + +### Getting Help + + + Contact our support team for assistance with Jira integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/linear.mdx b/docs/v1.15.1/en/enterprise/integrations/linear.mdx new file mode 100644 index 000000000..083c630ce --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/linear.mdx @@ -0,0 +1,466 @@ +--- +title: Linear Integration +description: "Software project and bug tracking with Linear integration for CrewAI." +icon: "list-check" +mode: "wide" +--- + +## Overview + +Enable your agents to manage issues, projects, and development workflows through Linear. Create and update issues, manage project timelines, organize teams, and streamline your software development process with AI-powered automation. + +## Prerequisites + +Before using the Linear integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Linear account with appropriate workspace permissions +- Connected your Linear account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Linear Integration + +### 1. Connect Your Linear Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Linear** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for issue and project management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create a new issue in Linear. + + **Parameters:** + - `teamId` (string, required): Team ID - Specify the Team ID of the parent for this new issue. Use Connect Portal Workflow Settings to allow users to select a Team ID. (example: "a70bdf0f-530a-4887-857d-46151b52b47c"). + - `title` (string, required): Title - Specify a title for this issue. + - `description` (string, optional): Description - Specify a description for this issue. + - `statusId` (string, optional): Status - Specify the state or status of this issue. + - `priority` (string, optional): Priority - Specify the priority of this issue as an integer. + - `dueDate` (string, optional): Due Date - Specify the due date of this issue in ISO 8601 format. + - `cycleId` (string, optional): Cycle ID - Specify the cycle associated with this issue. + - `additionalFields` (object, optional): Additional Fields. + ```json + { + "assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c", + "labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"] + } + ``` + + + + + **Description:** Update an issue in Linear. + + **Parameters:** + - `issueId` (string, required): Issue ID - Specify the Issue ID of the issue to update. (example: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + - `title` (string, optional): Title - Specify a title for this issue. + - `description` (string, optional): Description - Specify a description for this issue. + - `statusId` (string, optional): Status - Specify the state or status of this issue. + - `priority` (string, optional): Priority - Specify the priority of this issue as an integer. + - `dueDate` (string, optional): Due Date - Specify the due date of this issue in ISO 8601 format. + - `cycleId` (string, optional): Cycle ID - Specify the cycle associated with this issue. + - `additionalFields` (object, optional): Additional Fields. + ```json + { + "assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c", + "labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"] + } + ``` + + + + + **Description:** Get an issue by ID in Linear. + + **Parameters:** + - `issueId` (string, required): Issue ID - Specify the record ID of the issue to fetch. (example: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + + + + + **Description:** Get an issue by issue identifier in Linear. + + **Parameters:** + - `externalId` (string, required): External ID - Specify the human-readable Issue identifier of the issue to fetch. (example: "ABC-1"). + + + + + **Description:** Search issues in Linear. + + **Parameters:** + - `queryTerm` (string, required): Query Term - The search term to look for. + - `issueFilterFormula` (object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "title", + "operator": "$stringContains", + "value": "bug" + } + ] + } + ] + } + ``` + Available fields: `title`, `number`, `project`, `createdAt` + Available operators: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan`, `$numberGreaterThanOrEqualTo`, `$numberLessThanOrEqualTo`, `$numberGreaterThan`, `$numberLessThan`, `$dateTimeAfter`, `$dateTimeBefore` + + + + + **Description:** Delete an issue in Linear. + + **Parameters:** + - `issueId` (string, required): Issue ID - Specify the record ID of the issue to delete. (example: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + + + + + **Description:** Archive an issue in Linear. + + **Parameters:** + - `issueId` (string, required): Issue ID - Specify the record ID of the issue to archive. (example: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + + + + + **Description:** Create a sub-issue in Linear. + + **Parameters:** + - `parentId` (string, required): Parent ID - Specify the Issue ID for the parent of this new issue. + - `teamId` (string, required): Team ID - Specify the Team ID of the parent for this new sub-issue. Use Connect Portal Workflow Settings to allow users to select a Team ID. (example: "a70bdf0f-530a-4887-857d-46151b52b47c"). + - `title` (string, required): Title - Specify a title for this issue. + - `description` (string, optional): Description - Specify a description for this issue. + - `additionalFields` (object, optional): Additional Fields. + ```json + { + "lead": "linear_user_id" + } + ``` + + + + + **Description:** Create a new project in Linear. + + **Parameters:** + - `teamIds` (object, required): Team ID - Specify the team ID(s) this project is associated with as a string or a JSON array. Use Connect Portal User Settings to allow your user to select a Team ID. + ```json + [ + "a70bdf0f-530a-4887-857d-46151b52b47c", + "4ac7..." + ] + ``` + - `projectName` (string, required): Project Name - Specify the name of the project. (example: "My Linear Project"). + - `description` (string, optional): Project Description - Specify a description for this project. + - `additionalFields` (object, optional): Additional Fields. + ```json + { + "state": "planned", + "description": "" + } + ``` + + + + + **Description:** Update a project in Linear. + + **Parameters:** + - `projectId` (string, required): Project ID - Specify the ID of the project to update. (example: "a6634484-6061-4ac7-9739-7dc5e52c796b"). + - `projectName` (string, optional): Project Name - Specify the name of the project to update. (example: "My Linear Project"). + - `description` (string, optional): Project Description - Specify a description for this project. + - `additionalFields` (object, optional): Additional Fields. + ```json + { + "state": "planned", + "description": "" + } + ``` + + + + + **Description:** Get a project by ID in Linear. + + **Parameters:** + - `projectId` (string, required): Project ID - Specify the Project ID of the project to fetch. (example: "a6634484-6061-4ac7-9739-7dc5e52c796b"). + + + + + **Description:** Delete a project in Linear. + + **Parameters:** + - `projectId` (string, required): Project ID - Specify the Project ID of the project to delete. (example: "a6634484-6061-4ac7-9739-7dc5e52c796b"). + + + + + **Description:** Search teams in Linear. + + **Parameters:** + - `teamFilterFormula` (object, optional): A filter in disjunctive normal form - OR of AND groups of single conditions. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "name", + "operator": "$stringContains", + "value": "Engineering" + } + ] + } + ] + } + ``` + Available fields: `id`, `name` + + + + +## Usage Examples + +### Basic Linear Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Linear capabilities +linear_agent = Agent( + role="Development Manager", + goal="Manage Linear issues and track development progress efficiently", + backstory="An AI assistant specialized in software development project management.", + apps=['linear'] # All Linear actions will be available +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a high-priority bug report for the authentication system and assign it to the backend team", + agent=linear_agent, + expected_output="Bug report created successfully with issue ID" +) + +# Run the task +crew = Crew( + agents=[linear_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### Filtering Specific Linear Tools + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage Linear issues efficiently", + backstory="An AI assistant that focuses on issue creation and lifecycle management.", + apps=['linear/create_issue'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and update the status of related issues to reflect current progress", + agent=issue_manager, + expected_output="Feature request created and related issues updated" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Project and Team Management + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate projects and teams in Linear efficiently", + backstory="An experienced project coordinator who manages development cycles and team workflows.", + apps=['linear'] +) + +# Task to coordinate project setup +project_coordination = Task( + description=""" + 1. Search for engineering teams in Linear + 2. Create a new project for Q2 feature development + 3. Associate the project with relevant teams + 4. Create initial project milestones as issues + """, + agent=project_coordinator, + expected_output="Q2 project created with teams assigned and initial milestones established" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### Issue Hierarchy and Sub-task Management + +```python +from crewai import Agent, Task, Crew + +task_organizer = Agent( + role="Task Organizer", + goal="Organize complex issues into manageable sub-tasks", + backstory="An AI assistant that breaks down complex development work into organized sub-tasks.", + apps=['linear'] +) + +# Task to create issue hierarchy +hierarchy_task = Task( + description=""" + 1. Search for large feature issues that need to be broken down + 2. For each complex issue, create sub-issues for different components + 3. Update the parent issues with proper descriptions and links to sub-issues + 4. Assign sub-issues to appropriate team members based on expertise + """, + agent=task_organizer, + expected_output="Complex issues broken down into manageable sub-tasks with proper assignments" +) + +crew = Crew( + agents=[task_organizer], + tasks=[hierarchy_task] +) + +crew.kickoff() +``` + +### Automated Development Workflow + +```python +from crewai import Agent, Task, Crew + +workflow_automator = Agent( + role="Workflow Automator", + goal="Automate development workflow processes in Linear", + backstory="An AI assistant that automates repetitive development workflow tasks.", + apps=['linear'] +) + +# Complex workflow automation task +automation_task = Task( + description=""" + 1. Search for issues that have been in progress for more than 7 days + 2. Update their priorities based on due dates and project importance + 3. Create weekly sprint planning issues for each team + 4. Archive completed issues from the previous cycle + 5. Generate project status reports as new issues + """, + agent=workflow_automator, + expected_output="Development workflow automated with updated priorities, sprint planning, and status reports" +) + +crew = Crew( + agents=[workflow_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Linear account has necessary permissions for the target workspace +- Verify that the OAuth connection includes required scopes for Linear API +- Check if you have create/edit permissions for issues and projects in the workspace + +**Invalid IDs and References** + +- Double-check team IDs, issue IDs, and project IDs for correct UUID format +- Ensure referenced entities (teams, projects, cycles) exist and are accessible +- Verify that issue identifiers follow the correct format (e.g., "ABC-1") + +**Team and Project Association Issues** + +- Use LINEAR_SEARCH_TEAMS to get valid team IDs before creating issues or projects +- Ensure teams exist and are active in your workspace +- Verify that team IDs are properly formatted as UUIDs + +**Issue Status and Priority Problems** + +- Check that status IDs reference valid workflow states for the team +- Ensure priority values are within the valid range for your Linear configuration +- Verify that custom fields and labels exist before referencing them + +**Date and Time Format Issues** + +- Use ISO 8601 format for due dates and timestamps +- Ensure time zones are handled correctly for due date calculations +- Verify that date values are valid and in the future for due dates + +**Search and Filter Issues** + +- Ensure search queries are properly formatted and not empty +- Use valid field names in filter formulas: `title`, `number`, `project`, `createdAt` +- Test simple filters before building complex multi-condition queries +- Verify that operator types match the data types of the fields being filtered + +**Sub-issue Creation Problems** + +- Ensure parent issue IDs are valid and accessible +- Verify that the team ID for sub-issues matches or is compatible with the parent issue's team +- Check that parent issues are not already archived or deleted + +### Getting Help + + + Contact our support team for assistance with Linear integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/microsoft_excel.mdx b/docs/v1.15.1/en/enterprise/integrations/microsoft_excel.mdx new file mode 100644 index 000000000..d0fadb7c7 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/microsoft_excel.mdx @@ -0,0 +1,507 @@ +--- +title: Microsoft Excel Integration +description: "Workbook and data management with Microsoft Excel integration for CrewAI." +icon: "table" +mode: "wide" +--- + +## Overview + +Enable your agents to create and manage Excel workbooks, worksheets, tables, and charts in OneDrive or SharePoint. Manipulate data ranges, create visualizations, manage tables, and streamline your spreadsheet workflows with AI-powered automation. + +## Prerequisites + +Before using the Microsoft Excel integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Microsoft 365 account with Excel and OneDrive/SharePoint access +- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Microsoft Excel Integration + +### 1. Connect Your Microsoft Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Microsoft Excel** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for files and Excel workbook access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Create a new Excel workbook in OneDrive or SharePoint. + + **Parameters:** + - `file_path` (string, required): Path where to create the workbook (e.g., 'MyWorkbook.xlsx') + - `worksheets` (array, optional): Initial worksheets to create + ```json + [ + { + "name": "Sheet1" + }, + { + "name": "Data" + } + ] + ``` + + + + + **Description:** Get all Excel workbooks from OneDrive or SharePoint. + + **Parameters:** + - `select` (string, optional): Select specific properties to return + - `filter` (string, optional): Filter results using OData syntax + - `expand` (string, optional): Expand related resources inline + - `top` (integer, optional): Number of items to return. Minimum: 1, Maximum: 999 + - `orderby` (string, optional): Order results by specified properties + + + + + **Description:** Get all worksheets in an Excel workbook. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `select` (string, optional): Select specific properties to return (e.g., 'id,name,position') + - `filter` (string, optional): Filter results using OData syntax + - `expand` (string, optional): Expand related resources inline + - `top` (integer, optional): Number of items to return. Minimum: 1, Maximum: 999 + - `orderby` (string, optional): Order results by specified properties + + + + + **Description:** Create a new worksheet in an Excel workbook. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `name` (string, required): Name of the new worksheet + + + + + **Description:** Get data from a specific range in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `range` (string, required): Range address (e.g., 'A1:C10') + + + + + **Description:** Update data in a specific range in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `range` (string, required): Range address (e.g., 'A1:C10') + - `values` (array, required): 2D array of values to set in the range + ```json + [ + ["Name", "Age", "City"], + ["John", 30, "New York"], + ["Jane", 25, "Los Angeles"] + ] + ``` + + + + + **Description:** Create a table in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `range` (string, required): Range for the table (e.g., 'A1:D10') + - `has_headers` (boolean, optional): Whether the first row contains headers. Default: true + + + + + **Description:** Get all tables in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + + + + + **Description:** Add a new row to an Excel table. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `table_name` (string, required): Name of the table + - `values` (array, required): Array of values for the new row + ```json + ["John Doe", 35, "Manager", "Sales"] + ``` + + + + + **Description:** Get data from a specific table in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `table_name` (string, required): Name of the table + + + + + **Description:** Create a chart in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `chart_type` (string, required): Type of chart (e.g., 'ColumnClustered', 'Line', 'Pie') + - `source_data` (string, required): Range of data for the chart (e.g., 'A1:B10') + - `series_by` (string, optional): How to interpret the data ('Auto', 'Columns', or 'Rows'). Default: Auto + + + + + **Description:** Get the value of a single cell in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `row` (integer, required): Row number (0-based) + - `column` (integer, required): Column number (0-based) + + + + + **Description:** Get the used range of an Excel worksheet (contains all data). + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + + + + + **Description:** Get the used range metadata (dimensions only, no data) of an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + + + + + **Description:** Get all charts in an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + + + + + **Description:** Delete a worksheet from an Excel workbook. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet to delete + + + + + **Description:** Delete a table from an Excel worksheet. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + - `worksheet_name` (string, required): Name of the worksheet + - `table_name` (string, required): Name of the table to delete + + + + + **Description:** Get all named ranges in an Excel workbook. + + **Parameters:** + - `file_id` (string, required): The ID of the Excel file + + + + +## Usage Examples + +### Basic Excel Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Excel capabilities +excel_agent = Agent( + role="Excel Data Manager", + goal="Manage Excel workbooks and data efficiently", + backstory="An AI assistant specialized in Excel data management and analysis.", + apps=['microsoft_excel'] # All Excel actions will be available +) + +# Task to create and populate a workbook +data_management_task = Task( + description="Create a new sales report workbook with data analysis and charts", + agent=excel_agent, + expected_output="Excel workbook created with sales data, analysis, and visualizations" +) + +# Run the task +crew = Crew( + agents=[excel_agent], + tasks=[data_management_task] +) + +crew.kickoff() +``` + +### Data Analysis and Reporting + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Data Analyst", + goal="Analyze data in Excel and create comprehensive reports", + backstory="An AI assistant that specializes in data analysis and Excel reporting.", + apps=[ + 'microsoft_excel/get_workbooks', + 'microsoft_excel/get_range_data', + 'microsoft_excel/create_chart', + 'microsoft_excel/add_table' + ] +) + +# Task to analyze existing data +analysis_task = Task( + description="Analyze sales data in existing workbooks and create summary charts and tables", + agent=data_analyst, + expected_output="Data analyzed with summary charts and tables created" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Workbook Creation and Structure + +```python +from crewai import Agent, Task, Crew + +workbook_creator = Agent( + role="Workbook Creator", + goal="Create structured Excel workbooks with multiple worksheets and data organization", + backstory="An AI assistant that creates well-organized Excel workbooks for various business needs.", + apps=['microsoft_excel'] +) + +# Task to create structured workbooks +creation_task = Task( + description=""" + 1. Create a new quarterly report workbook + 2. Add multiple worksheets for different departments + 3. Create tables with headers for data organization + 4. Set up charts for key metrics visualization + """, + agent=workbook_creator, + expected_output="Structured workbook created with multiple worksheets, tables, and charts" +) + +crew = Crew( + agents=[workbook_creator], + tasks=[creation_task] +) + +crew.kickoff() +``` + +### Data Manipulation and Updates + +```python +from crewai import Agent, Task, Crew + +data_manipulator = Agent( + role="Data Manipulator", + goal="Update and manipulate data in Excel worksheets efficiently", + backstory="An AI assistant that handles data updates, table management, and range operations.", + apps=['microsoft_excel'] +) + +# Task to manipulate data +manipulation_task = Task( + description=""" + 1. Get data from existing worksheets + 2. Update specific ranges with new information + 3. Add new rows to existing tables + 4. Create additional charts based on updated data + 5. Organize data across multiple worksheets + """, + agent=data_manipulator, + expected_output="Data updated across worksheets with new charts and organized structure" +) + +crew = Crew( + agents=[data_manipulator], + tasks=[manipulation_task] +) + +crew.kickoff() +``` + +### Advanced Excel Automation + +```python +from crewai import Agent, Task, Crew + +excel_automator = Agent( + role="Excel Automator", + goal="Automate complex Excel workflows and data processing", + backstory="An AI assistant that automates sophisticated Excel operations and data workflows.", + apps=['microsoft_excel'] +) + +# Complex automation task +automation_task = Task( + description=""" + 1. Scan all Excel workbooks for specific data patterns + 2. Create consolidated reports from multiple workbooks + 3. Generate charts and tables for trend analysis + 4. Set up named ranges for easy data reference + 5. Create dashboard worksheets with key metrics + 6. Clean up unused worksheets and tables + """, + agent=excel_automator, + expected_output="Automated Excel workflow completed with consolidated reports and dashboards" +) + +crew = Crew( + agents=[excel_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### Financial Modeling and Analysis + +```python +from crewai import Agent, Task, Crew + +financial_modeler = Agent( + role="Financial Modeler", + goal="Create financial models and analysis in Excel", + backstory="An AI assistant specialized in financial modeling and analysis using Excel.", + apps=['microsoft_excel'] +) + +# Task for financial modeling +modeling_task = Task( + description=""" + 1. Create financial model workbooks with multiple scenarios + 2. Set up input tables for assumptions and variables + 3. Create calculation worksheets with formulas and logic + 4. Generate charts for financial projections and trends + 5. Add summary tables for key financial metrics + 6. Create sensitivity analysis tables + """, + agent=financial_modeler, + expected_output="Financial model created with scenarios, calculations, and analysis charts" +) + +crew = Crew( + agents=[financial_modeler], + tasks=[modeling_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Microsoft account has appropriate permissions for Excel and OneDrive/SharePoint +- Verify that the OAuth connection includes required scopes (Files.Read.All, Files.ReadWrite.All) +- Check that you have access to the specific workbooks you're trying to modify + +**File ID and Path Issues** + +- Verify that file IDs are correct and files exist in your OneDrive or SharePoint +- Ensure file paths are properly formatted when creating new workbooks +- Check that workbook files have the correct .xlsx extension + +**Worksheet and Range Issues** + +- Verify that worksheet names exist in the specified workbook +- Ensure range addresses are properly formatted (e.g., 'A1:C10') +- Check that ranges don't exceed worksheet boundaries + +**Data Format Issues** + +- Ensure data values are properly formatted for Excel (strings, numbers, integers) +- Verify that 2D arrays for ranges have consistent row and column counts +- Check that table data includes proper headers when has_headers is true + +**Chart Creation Issues** + +- Verify that chart types are supported (ColumnClustered, Line, Pie, etc.) +- Ensure source data ranges contain appropriate data for the chart type +- Check that the source data range exists and contains data + +**Table Management Issues** + +- Ensure table names are unique within worksheets +- Verify that table ranges don't overlap with existing tables +- Check that new row data matches the table's column structure + +**Cell and Range Operations** + +- Verify that row and column indices are 0-based for cell operations +- Ensure ranges contain data when using get_used_range +- Check that named ranges exist before referencing them + +### Getting Help + + + Contact our support team for assistance with Microsoft Excel integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/microsoft_onedrive.mdx b/docs/v1.15.1/en/enterprise/integrations/microsoft_onedrive.mdx new file mode 100644 index 000000000..30d8077e8 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/microsoft_onedrive.mdx @@ -0,0 +1,329 @@ +--- +title: Microsoft OneDrive Integration +description: "File and folder management with Microsoft OneDrive integration for CrewAI." +icon: "cloud" +mode: "wide" +--- + +## Overview + +Enable your agents to upload, download, and manage files and folders in Microsoft OneDrive. Automate file operations, organize content, create sharing links, and streamline your cloud storage workflows with AI-powered automation. + +## Prerequisites + +Before using the Microsoft OneDrive integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Microsoft account with OneDrive access +- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Microsoft OneDrive Integration + +### 1. Connect Your Microsoft Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Microsoft OneDrive** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for file access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** List files and folders in OneDrive. + + **Parameters:** + - `top` (integer, optional): Number of items to retrieve (max 1000). Default is `50`. + - `orderby` (string, optional): Order by field (e.g., "name asc", "lastModifiedDateTime desc"). Default is "name asc". + - `filter` (string, optional): OData filter expression. + + + + + **Description:** Get information about a specific file or folder. + + **Parameters:** + - `item_id` (string, required): The ID of the file or folder. + + + + + **Description:** Download a file from OneDrive. + + **Parameters:** + - `item_id` (string, required): The ID of the file to download. + + + + + **Description:** Upload a file to OneDrive. + + **Parameters:** + - `file_name` (string, required): Name of the file to upload. + - `content` (string, required): Base64 encoded file content. + + + + + **Description:** Create a new folder in OneDrive. + + **Parameters:** + - `folder_name` (string, required): Name of the folder to create. + + + + + **Description:** Delete a file or folder from OneDrive. + + **Parameters:** + - `item_id` (string, required): The ID of the file or folder to delete. + + + + + **Description:** Copy a file or folder in OneDrive. + + **Parameters:** + - `item_id` (string, required): The ID of the file or folder to copy. + - `parent_id` (string, optional): The ID of the destination folder (optional, defaults to root). + - `new_name` (string, optional): New name for the copied item (optional). + + + + + **Description:** Move a file or folder in OneDrive. + + **Parameters:** + - `item_id` (string, required): The ID of the file or folder to move. + - `parent_id` (string, required): The ID of the destination folder. + - `new_name` (string, optional): New name for the item (optional). + + + + + **Description:** Search for files and folders in OneDrive. + + **Parameters:** + - `query` (string, required): Search query string. + - `top` (integer, optional): Number of results to return (max 1000). Default is `50`. + + + + + **Description:** Create a sharing link for a file or folder. + + **Parameters:** + - `item_id` (string, required): The ID of the file or folder to share. + - `type` (string, optional): Type of sharing link. Enum: `view`, `edit`, `embed`. Default is `view`. + - `scope` (string, optional): Scope of the sharing link. Enum: `anonymous`, `organization`. Default is `anonymous`. + + + + + **Description:** Get thumbnails for a file. + + **Parameters:** + - `item_id` (string, required): The ID of the file. + + + + + **Description:** List files and folders in a specific OneDrive path. + + **Parameters:** + - `folder_path` (string, required): The folder path (e.g., 'Documents/Reports'). + - `top` (integer, optional): Number of items to retrieve (max 1000). Default is `50`. + - `orderby` (string, optional): Order by field (e.g., "name asc", "lastModifiedDateTime desc"). Default is "name asc". + + + + + **Description:** Get recently accessed files from OneDrive. + + **Parameters:** + - `top` (integer, optional): Number of items to retrieve (max 200). Default is `25`. + + + + + **Description:** Get files and folders shared with the user. + + **Parameters:** + - `top` (integer, optional): Number of items to retrieve (max 200). Default is `50`. + - `orderby` (string, optional): Order by field. Default is "name asc". + + + + + **Description:** Get information about a specific file or folder by path. + + **Parameters:** + - `file_path` (string, required): The file or folder path (e.g., 'Documents/report.docx'). + + + + + **Description:** Download a file from OneDrive by its path. + + **Parameters:** + - `file_path` (string, required): The file path (e.g., 'Documents/report.docx'). + + + + +## Usage Examples + +### Basic Microsoft OneDrive Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft OneDrive capabilities +onedrive_agent = Agent( + role="File Manager", + goal="Manage files and folders in OneDrive efficiently", + backstory="An AI assistant specialized in Microsoft OneDrive file operations and organization.", + apps=['microsoft_onedrive'] # All OneDrive actions will be available +) + +# Task to list files and create a folder +organize_files_task = Task( + description="List all files in my OneDrive root directory and create a new folder called 'Project Documents'.", + agent=onedrive_agent, + expected_output="List of files displayed and new folder 'Project Documents' created." +) + +# Run the task +crew = Crew( + agents=[onedrive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +### File Upload and Management + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on file operations +file_operator = Agent( + role="File Operator", + goal="Upload, download, and manage files with precision", + backstory="An AI assistant skilled in file handling and content management.", + apps=['microsoft_onedrive/upload_file', 'microsoft_onedrive/download_file', 'microsoft_onedrive/get_file_info'] +) + +# Task to upload and manage a file +file_management_task = Task( + description="Upload a text file named 'report.txt' with content 'This is a sample report for the project.' Then get information about the uploaded file.", + agent=file_operator, + expected_output="File uploaded successfully and file information retrieved." +) + +crew = Crew( + agents=[file_operator], + tasks=[file_management_task] +) + +crew.kickoff() +``` + +### File Organization and Sharing + +```python +from crewai import Agent, Task, Crew + +# Create an agent for file organization and sharing +file_organizer = Agent( + role="File Organizer", + goal="Organize files and create sharing links for collaboration", + backstory="An AI assistant that excels at organizing files and managing sharing permissions.", + apps=['microsoft_onedrive/search_files', 'microsoft_onedrive/move_item', 'microsoft_onedrive/share_item', 'microsoft_onedrive/create_folder'] +) + +# Task to organize and share files +organize_share_task = Task( + description="Search for files containing 'presentation' in the name, create a folder called 'Presentations', move the found files to this folder, and create a view-only sharing link for the folder.", + agent=file_organizer, + expected_output="Files organized into 'Presentations' folder and sharing link created." +) + +crew = Crew( + agents=[file_organizer], + tasks=[organize_share_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Authentication Errors** + +- Ensure your Microsoft account has the necessary permissions for file access (e.g., `Files.Read`, `Files.ReadWrite`). +- Verify that the OAuth connection includes all required scopes. + +**File Upload Issues** + +- Ensure `file_name` and `content` are provided for file uploads. +- Content must be Base64 encoded for binary files. +- Check that you have write permissions to OneDrive. + +**File/Folder ID Issues** + +- Double-check item IDs for correctness when accessing specific files or folders. +- Item IDs are returned by other operations like `list_files` or `search_files`. +- Ensure the referenced items exist and are accessible. + +**Search and Filter Operations** + +- Use appropriate search terms for `search_files` operations. +- For `filter` parameters, use proper OData syntax. + +**File Operations (Copy/Move)** + +- For `move_item`, ensure both `item_id` and `parent_id` are provided. +- For `copy_item`, only `item_id` is required; `parent_id` defaults to root if not specified. +- Verify that destination folders exist and are accessible. + +**Sharing Link Creation** + +- Ensure the item exists before creating sharing links. +- Choose appropriate `type` and `scope` based on your sharing requirements. +- `anonymous` scope allows access without sign-in; `organization` requires organizational account. + +### Getting Help + + + Contact our support team for assistance with Microsoft OneDrive integration + setup or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/microsoft_outlook.mdx b/docs/v1.15.1/en/enterprise/integrations/microsoft_outlook.mdx new file mode 100644 index 000000000..c25d18e82 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/microsoft_outlook.mdx @@ -0,0 +1,330 @@ +--- +title: Microsoft Outlook Integration +description: "Email, calendar, and contact management with Microsoft Outlook integration for CrewAI." +icon: "envelope" +mode: "wide" +--- + +## Overview + +Enable your agents to access and manage Outlook emails, calendar events, and contacts. Send emails, retrieve messages, manage calendar events, and organize contacts with AI-powered automation. + +## Prerequisites + +Before using the Microsoft Outlook integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Microsoft account with Outlook access +- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Microsoft Outlook Integration + +### 1. Connect Your Microsoft Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Microsoft Outlook** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for mail, calendar, and contact access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Get email messages from the user's mailbox. + + **Parameters:** + - `top` (integer, optional): Number of messages to retrieve (max 1000). Default is `10`. + - `filter` (string, optional): OData filter expression (e.g., "isRead eq false"). + - `search` (string, optional): Search query string. + - `orderby` (string, optional): Order by field (e.g., "receivedDateTime desc"). Default is "receivedDateTime desc". + - `select` (string, optional): Select specific properties to return. + - `expand` (string, optional): Expand related resources inline. + + + + + **Description:** Send an email message. + + **Parameters:** + - `to_recipients` (array, required): Array of recipient email addresses. + - `cc_recipients` (array, optional): Array of CC recipient email addresses. + - `bcc_recipients` (array, optional): Array of BCC recipient email addresses. + - `subject` (string, required): Email subject. + - `body` (string, required): Email body content. + - `body_type` (string, optional): Body content type. Enum: `Text`, `HTML`. Default is `HTML`. + - `importance` (string, optional): Message importance level. Enum: `low`, `normal`, `high`. Default is `normal`. + - `reply_to` (array, optional): Array of reply-to email addresses. + - `save_to_sent_items` (boolean, optional): Whether to save the message to Sent Items folder. Default is `true`. + + + + + **Description:** Get calendar events from the user's calendar. + + **Parameters:** + - `top` (integer, optional): Number of events to retrieve (max 1000). Default is `10`. + - `skip` (integer, optional): Number of events to skip. Default is `0`. + - `filter` (string, optional): OData filter expression (e.g., "start/dateTime ge '2024-01-01T00:00:00Z'"). + - `orderby` (string, optional): Order by field (e.g., "start/dateTime asc"). Default is "start/dateTime asc". + + + + + **Description:** Create a new calendar event. + + **Parameters:** + - `subject` (string, required): Event subject/title. + - `body` (string, optional): Event body/description. + - `start_datetime` (string, required): Start date and time in ISO 8601 format (e.g., '2024-01-20T10:00:00'). + - `end_datetime` (string, required): End date and time in ISO 8601 format. + - `timezone` (string, optional): Time zone (e.g., 'Pacific Standard Time'). Default is `UTC`. + - `location` (string, optional): Event location. + - `attendees` (array, optional): Array of attendee email addresses. + + + + + **Description:** Get contacts from the user's address book. + + **Parameters:** + - `top` (integer, optional): Number of contacts to retrieve (max 1000). Default is `10`. + - `skip` (integer, optional): Number of contacts to skip. Default is `0`. + - `filter` (string, optional): OData filter expression. + - `orderby` (string, optional): Order by field (e.g., "displayName asc"). Default is "displayName asc". + + + + + **Description:** Create a new contact in the user's address book. + + **Parameters:** + - `displayName` (string, required): Contact's display name. + - `givenName` (string, optional): Contact's first name. + - `surname` (string, optional): Contact's last name. + - `emailAddresses` (array, optional): Array of email addresses. Each item is an object with `address` (string) and `name` (string). + - `businessPhones` (array, optional): Array of business phone numbers. + - `homePhones` (array, optional): Array of home phone numbers. + - `jobTitle` (string, optional): Contact's job title. + - `companyName` (string, optional): Contact's company name. + + + + + **Description:** Get a specific email message by ID. + + **Parameters:** + - `message_id` (string, required): The unique identifier of the message. Obtain from get_messages action. + - `select` (string, optional): Comma-separated list of properties to return. Example: "id,subject,body,from,receivedDateTime". Default is "id,subject,body,from,toRecipients,receivedDateTime". + + + + + **Description:** Reply to an email message. + + **Parameters:** + - `message_id` (string, required): The unique identifier of the message to reply to. Obtain from get_messages action. + - `comment` (string, required): The reply message content. Can be plain text or HTML. The original message will be quoted below this content. + + + + + **Description:** Forward an email message. + + **Parameters:** + - `message_id` (string, required): The unique identifier of the message to forward. Obtain from get_messages action. + - `to_recipients` (array, required): Array of recipient email addresses to forward to. Example: ["john@example.com", "jane@example.com"]. + - `comment` (string, optional): Optional message to include above the forwarded content. Can be plain text or HTML. + + + + + **Description:** Mark a message as read or unread. + + **Parameters:** + - `message_id` (string, required): The unique identifier of the message. Obtain from get_messages action. + - `is_read` (boolean, required): Set to true to mark as read, false to mark as unread. + + + + + **Description:** Delete an email message. + + **Parameters:** + - `message_id` (string, required): The unique identifier of the message to delete. Obtain from get_messages action. + + + + + **Description:** Update an existing calendar event. + + **Parameters:** + - `event_id` (string, required): The unique identifier of the event. Obtain from get_calendar_events action. + - `subject` (string, optional): New subject/title for the event. + - `start_time` (string, optional): New start time in ISO 8601 format (e.g., "2024-01-20T10:00:00"). REQUIRED: Must also provide start_timezone when using this field. + - `start_timezone` (string, optional): Timezone for start time. REQUIRED when updating start_time. Examples: "Pacific Standard Time", "Eastern Standard Time", "UTC". + - `end_time` (string, optional): New end time in ISO 8601 format. REQUIRED: Must also provide end_timezone when using this field. + - `end_timezone` (string, optional): Timezone for end time. REQUIRED when updating end_time. Examples: "Pacific Standard Time", "Eastern Standard Time", "UTC". + - `location` (string, optional): New location for the event. + - `body` (string, optional): New body/description for the event. Supports HTML formatting. + + + + + **Description:** Delete a calendar event. + + **Parameters:** + - `event_id` (string, required): The unique identifier of the event to delete. Obtain from get_calendar_events action. + + + + +## Usage Examples + +### Basic Microsoft Outlook Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Outlook capabilities +outlook_agent = Agent( + role="Email Assistant", + goal="Manage emails, calendar events, and contacts efficiently", + backstory="An AI assistant specialized in Microsoft Outlook operations and communication management.", + apps=['microsoft_outlook'] # All Outlook actions will be available +) + +# Task to send an email +send_email_task = Task( + description="Send an email to 'colleague@example.com' with subject 'Project Update' and body 'Hi, here is the latest project update. Best regards.'", + agent=outlook_agent, + expected_output="Email sent successfully to colleague@example.com" +) + +# Run the task +crew = Crew( + agents=[outlook_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +### Email Management and Search + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on email management +email_manager = Agent( + role="Email Manager", + goal="Retrieve, search, and organize email messages", + backstory="An AI assistant skilled in email organization and management.", + apps=['microsoft_outlook/get_messages'] +) + +# Task to search and retrieve emails +search_emails_task = Task( + description="Get the latest 20 unread emails and provide a summary of the most important ones.", + agent=email_manager, + expected_output="Summary of the most important unread emails with key details." +) + +crew = Crew( + agents=[email_manager], + tasks=[search_emails_task] +) + +crew.kickoff() +``` + +### Calendar and Contact Management + +```python +from crewai import Agent, Task, Crew + +# Create an agent for calendar and contact management +scheduler = Agent( + role="Calendar and Contact Manager", + goal="Manage calendar events and maintain contact information", + backstory="An AI assistant that handles scheduling and contact organization.", + apps=['microsoft_outlook/create_calendar_event', 'microsoft_outlook/get_calendar_events', 'microsoft_outlook/create_contact'] +) + +# Task to create a meeting and add a contact +schedule_task = Task( + description="Create a calendar event for tomorrow at 2 PM titled 'Team Meeting' with location 'Conference Room A', and create a new contact for 'John Smith' with email 'john.smith@example.com' and job title 'Project Manager'.", + agent=scheduler, + expected_output="Calendar event created and new contact added successfully." +) + +crew = Crew( + agents=[scheduler], + tasks=[schedule_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Authentication Errors** + +- Ensure your Microsoft account has the necessary permissions for mail, calendar, and contact access. +- Required scopes include: `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`. +- Verify that the OAuth connection includes all required scopes. + +**Email Sending Issues** + +- Ensure `to_recipients`, `subject`, and `body` are provided for `send_email`. +- Check that email addresses are properly formatted. +- Verify that the account has `Mail.Send` permissions. + +**Calendar Event Creation** + +- Ensure `subject`, `start_datetime`, and `end_datetime` are provided. +- Use proper ISO 8601 format for datetime fields (e.g., '2024-01-20T10:00:00'). +- Verify timezone settings if events appear at incorrect times. + +**Contact Management** + +- For `create_contact`, ensure `displayName` is provided as it's required. +- When providing `emailAddresses`, use the proper object format with `address` and `name` properties. + +**Search and Filter Issues** + +- Use proper OData syntax for `filter` parameters. +- For date filters, use ISO 8601 format (e.g., "receivedDateTime ge '2024-01-01T00:00:00Z'"). + +### Getting Help + + + Contact our support team for assistance with Microsoft Outlook integration + setup or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/microsoft_sharepoint.mdx b/docs/v1.15.1/en/enterprise/integrations/microsoft_sharepoint.mdx new file mode 100644 index 000000000..ab5f310f3 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/microsoft_sharepoint.mdx @@ -0,0 +1,733 @@ +--- +title: Microsoft SharePoint Integration +description: "Site, list, and document management with Microsoft SharePoint integration for CrewAI." +icon: "folder-tree" +mode: "wide" +--- + +## Overview + +Enable your agents to access and manage SharePoint sites, lists, and document libraries. Retrieve site information, manage list items, upload and organize files, and streamline your SharePoint workflows with AI-powered automation. + +## Prerequisites + +Before using the Microsoft SharePoint integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Microsoft 365 account with SharePoint access +- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Microsoft SharePoint Integration + +### 1. Connect Your Microsoft Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Microsoft SharePoint** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for SharePoint sites and content access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Get all SharePoint sites the user has access to. + + **Parameters:** + - `search` (string, optional): Search query to filter sites + - `select` (string, optional): Select specific properties to return (e.g., 'displayName,id,webUrl') + - `filter` (string, optional): Filter results using OData syntax + - `expand` (string, optional): Expand related resources inline + - `top` (integer, optional): Number of items to return. Minimum: 1, Maximum: 999 + - `skip` (integer, optional): Number of items to skip. Minimum: 0 + - `orderby` (string, optional): Order results by specified properties (e.g., 'displayName desc') + + + + + **Description:** Get information about a specific SharePoint site. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `select` (string, optional): Select specific properties to return (e.g., 'displayName,id,webUrl,drives') + - `expand` (string, optional): Expand related resources inline (e.g., 'drives,lists') + + + + + **Description:** List all document libraries (drives) in a SharePoint site. Use this to discover available libraries before using file operations. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `top` (integer, optional): Maximum number of drives to return per page (1-999). Default is 100 + - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'id,name,webUrl,driveType') + + + + + **Description:** Get all lists in a SharePoint site. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + + + + + **Description:** Get information about a specific list. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `list_id` (string, required): The ID of the list + + + + + **Description:** Get items from a SharePoint list. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `list_id` (string, required): The ID of the list + - `expand` (string, optional): Expand related data (e.g., 'fields') + + + + + **Description:** Create a new item in a SharePoint list. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `list_id` (string, required): The ID of the list + - `fields` (object, required): The field values for the new item + ```json + { + "Title": "New Item Title", + "Description": "Item description", + "Status": "Active" + } + ``` + + + + + **Description:** Update an item in a SharePoint list. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `list_id` (string, required): The ID of the list + - `item_id` (string, required): The ID of the item to update + - `fields` (object, required): The field values to update + ```json + { + "Title": "Updated Title", + "Status": "Completed" + } + ``` + + + + + **Description:** Delete an item from a SharePoint list. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `list_id` (string, required): The ID of the list + - `item_id` (string, required): The ID of the item to delete + + + + + **Description:** Upload a file to a SharePoint document library. + + **Parameters:** + - `site_id` (string, required): The ID of the SharePoint site + - `file_path` (string, required): The path where to upload the file (e.g., 'folder/filename.txt') + - `content` (string, required): The file content to upload + + + + + **Description:** Retrieve files and folders from a SharePoint document library. By default lists the root folder, but you can navigate into subfolders by providing a folder_id. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `folder_id` (string, optional): The ID of the folder to list contents from. Use 'root' for the root folder, or provide a folder ID from a previous list_files call. Default is 'root' + - `top` (integer, optional): Maximum number of items to return per page (1-1000). Default is 50 + - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results + - `orderby` (string, optional): Sort order for results (e.g., 'name asc', 'size desc', 'lastModifiedDateTime desc'). Default is 'name asc' + - `filter` (string, optional): OData filter to narrow results (e.g., 'file ne null' for files only, 'folder ne null' for folders only) + - `select` (string, optional): Comma-separated list of fields to return (e.g., 'id,name,size,folder,file,webUrl,lastModifiedDateTime') + + + + + **Description:** Delete a file or folder from a SharePoint document library. For folders, all contents are deleted recursively. Items are moved to the site recycle bin. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the file or folder to delete. Obtain from list_files + + + + + **Description:** List files and folders in a SharePoint document library folder by its path. More efficient than multiple list_files calls for deep navigation. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `folder_path` (string, required): The full path to the folder without leading/trailing slashes (e.g., 'Documents', 'Reports/2024/Q1') + - `top` (integer, optional): Maximum number of items to return per page (1-1000). Default is 50 + - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results + - `orderby` (string, optional): Sort order for results (e.g., 'name asc', 'size desc'). Default is 'name asc' + - `select` (string, optional): Comma-separated list of fields to return (e.g., 'id,name,size,folder,file,webUrl,lastModifiedDateTime') + + + + + **Description:** Download raw file content from a SharePoint document library. Use only for plain text files (.txt, .csv, .json). For Excel files, use the Excel-specific actions. For Word files, use get_word_document_content. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the file to download. Obtain from list_files or list_files_by_path + + + + + **Description:** Retrieve detailed metadata for a specific file or folder in a SharePoint document library, including name, size, created/modified dates, and author information. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the file or folder. Obtain from list_files or list_files_by_path + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'id,name,size,createdDateTime,lastModifiedDateTime,webUrl,createdBy,lastModifiedBy') + + + + + **Description:** Create a new folder in a SharePoint document library. By default creates the folder in the root; use parent_id to create subfolders. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `folder_name` (string, required): Name for the new folder. Cannot contain: \ / : * ? " < > | + - `parent_id` (string, optional): The ID of the parent folder. Use 'root' for the document library root, or provide a folder ID from list_files. Default is 'root' + + + + + **Description:** Search for files and folders in a SharePoint document library by keywords. Searches file names, folder names, and file contents for Office documents. Do not use wildcards or special characters. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `query` (string, required): Search keywords (e.g., 'report', 'budget 2024'). Wildcards like *.txt are not supported + - `top` (integer, optional): Maximum number of results to return per page (1-1000). Default is 50 + - `skip_token` (string, optional): Pagination token from a previous response to fetch the next page of results + - `select` (string, optional): Comma-separated list of fields to return (e.g., 'id,name,size,folder,file,webUrl,lastModifiedDateTime') + + + + + **Description:** Copy a file or folder to a new location within SharePoint. The original item remains unchanged. The copy operation is asynchronous for large files. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the file or folder to copy. Obtain from list_files or search_files + - `destination_folder_id` (string, required): The ID of the destination folder. Use 'root' for the root folder, or a folder ID from list_files + - `new_name` (string, optional): New name for the copy. If not provided, the original name is used + + + + + **Description:** Move a file or folder to a new location within SharePoint. The item is removed from its original location. For folders, all contents are moved as well. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the file or folder to move. Obtain from list_files or search_files + - `destination_folder_id` (string, required): The ID of the destination folder. Use 'root' for the root folder, or a folder ID from list_files + - `new_name` (string, optional): New name for the moved item. If not provided, the original name is kept + + + + + **Description:** List all worksheets (tabs) in an Excel workbook stored in a SharePoint document library. Use the returned worksheet name with other Excel actions. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'id,name,position,visibility') + - `filter` (string, optional): OData filter expression (e.g., "visibility eq 'Visible'" to exclude hidden sheets) + - `top` (integer, optional): Maximum number of worksheets to return. Minimum: 1, Maximum: 999 + - `orderby` (string, optional): Sort order (e.g., 'position asc' to return sheets in tab order) + + + + + **Description:** Create a new worksheet (tab) in an Excel workbook stored in a SharePoint document library. The new sheet is added at the end of the tab list. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `name` (string, required): Name for the new worksheet. Maximum 31 characters. Cannot contain: \ / * ? : [ ]. Must be unique within the workbook + + + + + **Description:** Retrieve cell values from a specific range in an Excel worksheet stored in SharePoint. For reading all data without knowing dimensions, use get_excel_used_range instead. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet (tab) to read from. Obtain from get_excel_worksheets. Case-sensitive + - `range` (string, required): Cell range in A1 notation (e.g., 'A1:C10', 'A:C', '1:5', 'A1') + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text') + + + + + **Description:** Write values to a specific range in an Excel worksheet stored in SharePoint. Overwrites existing cell contents. The values array dimensions must match the range dimensions exactly. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet (tab) to update. Obtain from get_excel_worksheets. Case-sensitive + - `range` (string, required): Cell range in A1 notation where values will be written (e.g., 'A1:C3' for a 3x3 block) + - `values` (array, required): 2D array of values (rows containing cells). Example for A1:B2: [["Header1", "Header2"], ["Value1", "Value2"]]. Use null to clear a cell + + + + + **Description:** Return only the metadata (address and dimensions) of the used range in a worksheet, without the actual cell values. Ideal for large files to understand spreadsheet size before reading data in chunks. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet (tab) to read. Obtain from get_excel_worksheets. Case-sensitive + + + + + **Description:** Retrieve all cells containing data in a worksheet stored in SharePoint. Do not use for files larger than 2MB. For large files, use get_excel_used_range_metadata first, then get_excel_range_data to read in smaller chunks. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet (tab) to read. Obtain from get_excel_worksheets. Case-sensitive + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text,rowCount,columnCount') + + + + + **Description:** Retrieve the value of a single cell by row and column index from an Excel file in SharePoint. Indices are 0-based (row 0 = Excel row 1, column 0 = column A). + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet (tab). Obtain from get_excel_worksheets. Case-sensitive + - `row` (integer, required): 0-based row index (row 0 = Excel row 1). Valid range: 0-1048575 + - `column` (integer, required): 0-based column index (column 0 = A, column 1 = B). Valid range: 0-16383 + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text') + + + + + **Description:** Convert a cell range into a formatted Excel table with filtering, sorting, and structured data capabilities. Tables enable add_excel_table_row for appending data. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet containing the data range. Obtain from get_excel_worksheets + - `range` (string, required): Cell range to convert into a table, including headers and data (e.g., 'A1:D10' where A1:D1 contains column headers) + - `has_headers` (boolean, optional): Set to true if the first row contains column headers. Default is true + + + + + **Description:** List all tables in a specific Excel worksheet stored in SharePoint. Returns table properties including id, name, showHeaders, and showTotals. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet to get tables from. Obtain from get_excel_worksheets + + + + + **Description:** Append a new row to the end of an Excel table in a SharePoint file. The values array must have the same number of elements as the table has columns. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet containing the table. Obtain from get_excel_worksheets + - `table_name` (string, required): Name of the table to add the row to (e.g., 'Table1'). Obtain from get_excel_tables. Case-sensitive + - `values` (array, required): Array of cell values for the new row, one per column in table order (e.g., ["John Doe", "john@example.com", 25]) + + + + + **Description:** Get all rows from an Excel table in a SharePoint file as a data range. Easier than get_excel_range_data when working with structured tables since you don't need to know the exact range. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet containing the table. Obtain from get_excel_worksheets + - `table_name` (string, required): Name of the table to get data from (e.g., 'Table1'). Obtain from get_excel_tables. Case-sensitive + - `select` (string, optional): Comma-separated list of properties to return (e.g., 'address,values,formulas,numberFormat,text') + + + + + **Description:** Create a chart visualization in an Excel worksheet stored in SharePoint from a data range. The chart is embedded in the worksheet. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet where the chart will be created. Obtain from get_excel_worksheets + - `chart_type` (string, required): Chart type (e.g., 'ColumnClustered', 'ColumnStacked', 'Line', 'LineMarkers', 'Pie', 'Bar', 'BarClustered', 'Area', 'Scatter', 'Doughnut') + - `source_data` (string, required): Data range for the chart in A1 notation, including headers (e.g., 'A1:B10') + - `series_by` (string, optional): How data series are organized: 'Auto', 'Columns', or 'Rows'. Default is 'Auto' + + + + + **Description:** List all charts embedded in an Excel worksheet stored in SharePoint. Returns chart properties including id, name, chartType, height, width, and position. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet to list charts from. Obtain from get_excel_worksheets + + + + + **Description:** Permanently remove a worksheet (tab) and all its contents from an Excel workbook stored in SharePoint. Cannot be undone. A workbook must have at least one worksheet. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet to delete. Case-sensitive. All data, tables, and charts on this sheet will be permanently removed + + + + + **Description:** Remove a table from an Excel worksheet in SharePoint. This deletes the table structure (filtering, formatting, table features) but preserves the underlying cell data. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + - `worksheet_name` (string, required): Name of the worksheet containing the table. Obtain from get_excel_worksheets + - `table_name` (string, required): Name of the table to delete (e.g., 'Table1'). Obtain from get_excel_tables. The data in the cells will remain after table deletion + + + + + **Description:** Retrieve all named ranges defined in an Excel workbook stored in SharePoint. Named ranges are user-defined labels for cell ranges (e.g., 'SalesData' for A1:D100). + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Excel file in SharePoint. Obtain from list_files or search_files + + + + + **Description:** Download and extract text content from a Word document (.docx) stored in a SharePoint document library. This is the recommended way to read Word documents from SharePoint. + + **Parameters:** + - `site_id` (string, required): The full SharePoint site identifier from get_sites + - `drive_id` (string, required): The ID of the document library. Call get_drives first to get valid drive IDs + - `item_id` (string, required): The unique identifier of the Word document (.docx) in SharePoint. Obtain from list_files or search_files + + + + +## Usage Examples + +### Basic SharePoint Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with SharePoint capabilities +sharepoint_agent = Agent( + role="SharePoint Manager", + goal="Manage SharePoint sites, lists, and documents efficiently", + backstory="An AI assistant specialized in SharePoint content management and collaboration.", + apps=['microsoft_sharepoint'] # All SharePoint actions will be available +) + +# Task to organize SharePoint content +content_organization_task = Task( + description="List all accessible SharePoint sites and organize content by department", + agent=sharepoint_agent, + expected_output="SharePoint sites listed and content organized by department" +) + +# Run the task +crew = Crew( + agents=[sharepoint_agent], + tasks=[content_organization_task] +) + +crew.kickoff() +``` + +### List Management and Data Operations + +```python +from crewai import Agent, Task, Crew + +list_manager = Agent( + role="List Manager", + goal="Manage SharePoint lists and data efficiently", + backstory="An AI assistant that focuses on SharePoint list management and data operations.", + apps=[ + 'microsoft_sharepoint/get_site_lists', + 'microsoft_sharepoint/get_list_items', + 'microsoft_sharepoint/create_list_item', + 'microsoft_sharepoint/update_list_item' + ] +) + +# Task to manage list data +list_management_task = Task( + description="Get all lists from the project site, review items, and update status for completed tasks", + agent=list_manager, + expected_output="SharePoint lists reviewed and task statuses updated" +) + +crew = Crew( + agents=[list_manager], + tasks=[list_management_task] +) + +crew.kickoff() +``` + +### Document Library Management + +```python +from crewai import Agent, Task, Crew + +document_manager = Agent( + role="Document Manager", + goal="Manage SharePoint document libraries and files", + backstory="An AI assistant that specializes in document organization and file management.", + apps=['microsoft_sharepoint'] +) + +# Task to manage documents +document_task = Task( + description=""" + 1. Get all files from the main document library + 2. Upload new policy documents to the appropriate folders + 3. Organize files by department and date + 4. Remove outdated documents + """, + agent=document_manager, + expected_output="Document library organized with new files uploaded and outdated files removed" +) + +crew = Crew( + agents=[document_manager], + tasks=[document_task] +) + +crew.kickoff() +``` + +### Site Administration and Analysis + +```python +from crewai import Agent, Task, Crew + +site_administrator = Agent( + role="Site Administrator", + goal="Administer and analyze SharePoint sites", + backstory="An AI assistant that handles site administration and provides insights on site usage.", + apps=['microsoft_sharepoint'] +) + +# Task for site administration +admin_task = Task( + description=""" + 1. Get information about all accessible SharePoint sites + 2. Analyze site structure and content organization + 3. Identify sites with low activity or outdated content + 4. Generate recommendations for site optimization + """, + agent=site_administrator, + expected_output="Site analysis completed with optimization recommendations" +) + +crew = Crew( + agents=[site_administrator], + tasks=[admin_task] +) + +crew.kickoff() +``` + +### Automated Content Workflows + +```python +from crewai import Agent, Task, Crew + +workflow_automator = Agent( + role="Workflow Automator", + goal="Automate SharePoint content workflows and processes", + backstory="An AI assistant that automates complex SharePoint workflows and content management processes.", + apps=['microsoft_sharepoint'] +) + +# Complex workflow automation task +automation_task = Task( + description=""" + 1. Monitor project lists across multiple sites + 2. Create status reports based on list data + 3. Upload reports to designated document libraries + 4. Update project tracking lists with completion status + 5. Archive completed project documents + 6. Send notifications for overdue items + """, + agent=workflow_automator, + expected_output="Automated workflow completed with status reports generated and project tracking updated" +) + +crew = Crew( + agents=[workflow_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### Data Integration and Reporting + +```python +from crewai import Agent, Task, Crew + +data_integrator = Agent( + role="Data Integrator", + goal="Integrate and analyze data across SharePoint sites and lists", + backstory="An AI assistant that specializes in data integration and cross-site analysis.", + apps=['microsoft_sharepoint'] +) + +# Task for data integration +integration_task = Task( + description=""" + 1. Get data from multiple SharePoint lists across different sites + 2. Consolidate information into comprehensive reports + 3. Create new list items with aggregated data + 4. Upload analytical reports to executive document library + 5. Update dashboard lists with key metrics + """, + agent=data_integrator, + expected_output="Data integrated across sites with comprehensive reports and updated dashboards" +) + +crew = Crew( + agents=[data_integrator], + tasks=[integration_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Microsoft account has appropriate permissions for SharePoint sites +- Verify that the OAuth connection includes required scopes (Sites.Read.All, Sites.ReadWrite.All) +- Check that you have access to the specific sites and lists you're trying to access + +**Site and List ID Issues** + +- Verify that site IDs and list IDs are correct and properly formatted +- Ensure that sites and lists exist and are accessible to your account +- Use the get_sites and get_site_lists actions to discover valid IDs + +**Field and Schema Issues** + +- Ensure field names match exactly with the SharePoint list schema +- Verify that required fields are included when creating or updating list items +- Check that field types and values are compatible with the list column definitions + +**File Upload Issues** + +- Ensure file paths are properly formatted and don't contain invalid characters +- Verify that you have write permissions to the target document library +- Check that file content is properly encoded for upload + +**OData Query Issues** + +- Use proper OData syntax for filter, select, expand, and orderby parameters +- Verify that property names used in queries exist in the target resources +- Test simple queries before building complex filter expressions + +**Pagination and Performance** + +- Use top and skip parameters appropriately for large result sets +- Implement proper pagination for lists with many items +- Consider using select parameters to return only needed properties + +**Document Library Operations** + +- Ensure you have proper permissions for document library operations +- Verify that drive item IDs are correct when deleting files or folders +- Check that file paths don't conflict with existing content + +### Getting Help + + + Contact our support team for assistance with Microsoft SharePoint integration + setup or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/microsoft_teams.mdx b/docs/v1.15.1/en/enterprise/integrations/microsoft_teams.mdx new file mode 100644 index 000000000..1681bc4b4 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/microsoft_teams.mdx @@ -0,0 +1,323 @@ +--- +title: Microsoft Teams Integration +description: "Team collaboration and communication with Microsoft Teams integration for CrewAI." +icon: "users" +mode: "wide" +--- + +## Overview + +Enable your agents to access Teams data, send messages, create meetings, and manage channels. Automate team communication, schedule meetings, retrieve messages, and streamline your collaboration workflows with AI-powered automation. + +## Prerequisites + +Before using the Microsoft Teams integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Microsoft account with Teams access +- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Microsoft Teams Integration + +### 1. Connect Your Microsoft Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Microsoft Teams** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for Teams access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Get all teams the user is a member of. + + **Parameters:** + - No parameters required. + + + + + **Description:** Get channels in a specific team. + + **Parameters:** + - `team_id` (string, required): The ID of the team. + + + + + **Description:** Send a message to a Teams channel. + + **Parameters:** + - `team_id` (string, required): The ID of the team. + - `channel_id` (string, required): The ID of the channel. + - `message` (string, required): The message content. + - `content_type` (string, optional): Content type (html or text). Enum: `html`, `text`. Default is `text`. + + + + + **Description:** Get messages from a Teams channel. + + **Parameters:** + - `team_id` (string, required): The ID of the team. + - `channel_id` (string, required): The ID of the channel. + - `top` (integer, optional): Number of messages to retrieve (max 50). Default is `20`. + + + + + **Description:** Create a Teams meeting. + + **Parameters:** + - `subject` (string, required): Meeting subject/title. + - `startDateTime` (string, required): Meeting start time (ISO 8601 format with timezone). + - `endDateTime` (string, required): Meeting end time (ISO 8601 format with timezone). + + + + + **Description:** Search online meetings by Join Web URL. + + **Parameters:** + - `join_web_url` (string, required): The join web URL of the meeting to search for. + + + + + **Description:** Search online meetings by external Meeting ID. + + **Parameters:** + - `join_meeting_id` (string, required): The meeting ID (numeric code) that attendees use to join. This is the joinMeetingId shown in meeting invitations, not the Graph API meeting id. + + + + + **Description:** Get details of a specific online meeting. + + **Parameters:** + - `meeting_id` (string, required): The Graph API meeting ID (a long alphanumeric string). Obtain from create_meeting or search_online_meetings actions. Different from the numeric joinMeetingId. + + + + + **Description:** Get members of a specific team. + + **Parameters:** + - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action. + - `top` (integer, optional): Maximum number of members to retrieve per page (1-999). Default is `100`. + - `skip_token` (string, optional): Pagination token from a previous response. When the response includes @odata.nextLink, extract the $skiptoken parameter value and pass it here to get the next page of results. + + + + + **Description:** Create a new channel in a team. + + **Parameters:** + - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action. + - `display_name` (string, required): Name of the channel as displayed in Teams. Must be unique within the team. Max 50 characters. + - `description` (string, optional): Optional description explaining the channel's purpose. Visible in channel details. Max 1024 characters. + - `membership_type` (string, optional): Channel visibility. Enum: `standard`, `private`. "standard" = visible to all team members, "private" = visible only to specifically added members. Default is `standard`. + + + + + **Description:** Get replies to a specific message in a channel. + + **Parameters:** + - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action. + - `channel_id` (string, required): The unique identifier of the channel. Obtain from get_channels action. + - `message_id` (string, required): The unique identifier of the parent message. Obtain from get_messages action. + - `top` (integer, optional): Maximum number of replies to retrieve per page (1-50). Default is `50`. + - `skip_token` (string, optional): Pagination token from a previous response. When the response includes @odata.nextLink, extract the $skiptoken parameter value and pass it here to get the next page of results. + + + + + **Description:** Reply to a message in a Teams channel. + + **Parameters:** + - `team_id` (string, required): The unique identifier of the team. Obtain from get_teams action. + - `channel_id` (string, required): The unique identifier of the channel. Obtain from get_channels action. + - `message_id` (string, required): The unique identifier of the message to reply to. Obtain from get_messages action. + - `message` (string, required): The reply content. For HTML, include formatting tags. For text, plain text only. + - `content_type` (string, optional): Content format. Enum: `html`, `text`. "text" for plain text, "html" for rich text with formatting. Default is `text`. + + + + + **Description:** Update an existing online meeting. + + **Parameters:** + - `meeting_id` (string, required): The unique identifier of the meeting. Obtain from create_meeting or search_online_meetings actions. + - `subject` (string, optional): New meeting title. + - `startDateTime` (string, optional): New start time in ISO 8601 format with timezone. Example: "2024-01-20T10:00:00-08:00". + - `endDateTime` (string, optional): New end time in ISO 8601 format with timezone. + + + + + **Description:** Delete an online meeting. + + **Parameters:** + - `meeting_id` (string, required): The unique identifier of the meeting to delete. Obtain from create_meeting or search_online_meetings actions. + + + + +## Usage Examples + +### Basic Microsoft Teams Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Teams capabilities +teams_agent = Agent( + role="Teams Coordinator", + goal="Manage Teams communication and meetings efficiently", + backstory="An AI assistant specialized in Microsoft Teams operations and team collaboration.", + apps=['microsoft_teams'] # All Teams actions will be available +) + +# Task to list teams and channels +explore_teams_task = Task( + description="List all teams I'm a member of and then get the channels for the first team.", + agent=teams_agent, + expected_output="List of teams and channels displayed." +) + +# Run the task +crew = Crew( + agents=[teams_agent], + tasks=[explore_teams_task] +) + +crew.kickoff() +``` + +### Messaging and Communication + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on messaging +messenger = Agent( + role="Teams Messenger", + goal="Send and retrieve messages in Teams channels", + backstory="An AI assistant skilled in team communication and message management.", + apps=['microsoft_teams/send_message', 'microsoft_teams/get_messages'] +) + +# Task to send a message and retrieve recent messages +messaging_task = Task( + description="Send a message 'Hello team! This is an automated update from our AI assistant.' to the General channel of team 'your_team_id', then retrieve the last 10 messages from that channel.", + agent=messenger, + expected_output="Message sent successfully and recent messages retrieved." +) + +crew = Crew( + agents=[messenger], + tasks=[messaging_task] +) + +crew.kickoff() +``` + +### Meeting Management + +```python +from crewai import Agent, Task, Crew + +# Create an agent for meeting management +meeting_scheduler = Agent( + role="Meeting Scheduler", + goal="Create and manage Teams meetings", + backstory="An AI assistant that handles meeting scheduling and organization.", + apps=['microsoft_teams/create_meeting', 'microsoft_teams/search_online_meetings_by_join_url'] +) + +# Task to create a meeting +schedule_meeting_task = Task( + description="Create a Teams meeting titled 'Weekly Team Sync' scheduled for tomorrow at 10:00 AM lasting for 1 hour (use proper ISO 8601 format with timezone).", + agent=meeting_scheduler, + expected_output="Teams meeting created successfully with meeting details." +) + +crew = Crew( + agents=[meeting_scheduler], + tasks=[schedule_meeting_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Authentication Errors** + +- Ensure your Microsoft account has the necessary permissions for Teams access. +- Required scopes include: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `OnlineMeetings.ReadWrite`, `OnlineMeetings.Read`. +- Verify that the OAuth connection includes all required scopes. + +**Team and Channel Access** + +- Ensure you are a member of the teams you're trying to access. +- Double-check team IDs and channel IDs for correctness. +- Team and channel IDs can be obtained using the `get_teams` and `get_channels` actions. + +**Message Sending Issues** + +- Ensure `team_id`, `channel_id`, and `message` are provided for `send_message`. +- Verify that you have permissions to send messages to the specified channel. +- Choose appropriate `content_type` (text or html) based on your message format. + +**Meeting Creation** + +- Ensure `subject`, `startDateTime`, and `endDateTime` are provided. +- Use proper ISO 8601 format with timezone for datetime fields (e.g., '2024-01-20T10:00:00-08:00'). +- Verify that the meeting times are in the future. + +**Message Retrieval Limitations** + +- The `get_messages` action can retrieve a maximum of 50 messages per request. +- Messages are returned in reverse chronological order (newest first). + +**Meeting Search** + +- For `search_online_meetings_by_join_url`, ensure the join URL is exact and properly formatted. +- The URL should be the complete Teams meeting join URL. + +### Getting Help + + + Contact our support team for assistance with Microsoft Teams integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/microsoft_word.mdx b/docs/v1.15.1/en/enterprise/integrations/microsoft_word.mdx new file mode 100644 index 000000000..7b7675b2e --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/microsoft_word.mdx @@ -0,0 +1,240 @@ +--- +title: Microsoft Word Integration +description: "Document creation and management with Microsoft Word integration for CrewAI." +icon: "file-word" +mode: "wide" +--- + +## Overview + +Enable your agents to create, read, and manage Word documents and text files in OneDrive or SharePoint. Automate document creation, retrieve content, manage document properties, and streamline your document workflows with AI-powered automation. + +## Prerequisites + +Before using the Microsoft Word integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Microsoft account with Word and OneDrive/SharePoint access +- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Microsoft Word Integration + +### 1. Connect Your Microsoft Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Microsoft Word** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for file access +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** Get all Word documents from OneDrive or SharePoint. + + **Parameters:** + - `select` (string, optional): Select specific properties to return. + - `filter` (string, optional): Filter results using OData syntax. + - `expand` (string, optional): Expand related resources inline. + - `top` (integer, optional): Number of items to return (min 1, max 999). + - `orderby` (string, optional): Order results by specified properties. + + + + + **Description:** Create a text document (.txt) with content. RECOMMENDED for programmatic content creation that needs to be readable and editable. + + **Parameters:** + - `file_name` (string, required): Name of the text document (should end with .txt). + - `content` (string, optional): Text content for the document. Default is "This is a new text document created via API." + + + + + **Description:** Get the content of a document (works best with text files). + + **Parameters:** + - `file_id` (string, required): The ID of the document. + + + + + **Description:** Get properties and metadata of a document. + + **Parameters:** + - `file_id` (string, required): The ID of the document. + + + + + **Description:** Delete a document. + + **Parameters:** + - `file_id` (string, required): The ID of the document to delete. + + + + + **Description:** Copy a document to a new location in OneDrive. + + **Parameters:** + - `file_id` (string, required): The ID of the document to copy + - `name` (string, optional): New name for the copied document + - `parent_id` (string, optional): The ID of the destination folder (defaults to root) + + + + + **Description:** Move a document to a new location in OneDrive. + + **Parameters:** + - `file_id` (string, required): The ID of the document to move + - `parent_id` (string, required): The ID of the destination folder + - `name` (string, optional): New name for the moved document + + + + +## Usage Examples + +### Basic Microsoft Word Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Word capabilities +word_agent = Agent( + role="Document Manager", + goal="Manage Word documents and text files efficiently", + backstory="An AI assistant specialized in Microsoft Word document operations and content management.", + apps=['microsoft_word'] # All Word actions will be available +) + +# Task to create a new text document +create_doc_task = Task( + description="Create a new text document named 'meeting_notes.txt' with content 'Meeting Notes from January 2024: Key discussion points and action items.'", + agent=word_agent, + expected_output="New text document 'meeting_notes.txt' created successfully." +) + +# Run the task +crew = Crew( + agents=[word_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +### Reading and Managing Documents + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on document operations +document_reader = Agent( + role="Document Reader", + goal="Retrieve and analyze document content and properties", + backstory="An AI assistant skilled in reading and analyzing document content.", + apps=['microsoft_word/get_documents', 'microsoft_word/get_document_content', 'microsoft_word/get_document_properties'] +) + +# Task to list and read documents +read_docs_task = Task( + description="List all Word documents in my OneDrive, then get the content and properties of the first document found.", + agent=document_reader, + expected_output="List of documents with content and properties of the first document." +) + +crew = Crew( + agents=[document_reader], + tasks=[read_docs_task] +) + +crew.kickoff() +``` + +### Document Cleanup and Organization + +```python +from crewai import Agent, Task, Crew + +# Create an agent for document management +document_organizer = Agent( + role="Document Organizer", + goal="Organize and clean up document collections", + backstory="An AI assistant that helps maintain organized document libraries.", + apps=['microsoft_word/get_documents', 'microsoft_word/get_document_properties', 'microsoft_word/delete_document'] +) + +# Task to organize documents +organize_task = Task( + description="List all documents, check their properties, and identify any documents that might be duplicates or outdated for potential cleanup.", + agent=document_organizer, + expected_output="Analysis of document library with recommendations for organization." +) + +crew = Crew( + agents=[document_organizer], + tasks=[organize_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Authentication Errors** + +- Ensure your Microsoft account has the necessary permissions for file access (e.g., `Files.Read.All`, `Files.ReadWrite.All`). +- Verify that the OAuth connection includes all required scopes. + +**File Creation Issues** + +- When creating text documents, ensure the `file_name` ends with `.txt` extension. +- Verify that you have write permissions to the target location (OneDrive/SharePoint). + +**Document Access Issues** + +- Double-check document IDs for correctness when accessing specific documents. +- Ensure the referenced documents exist and are accessible. +- Note that this integration works best with text files (.txt) for content operations. + +**Content Retrieval Limitations** + +- The `get_document_content` action works best with text files (.txt). +- For complex Word documents (.docx), consider using the document properties action to get metadata. + +### Getting Help + + + Contact our support team for assistance with Microsoft Word integration setup + or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/notion.mdx b/docs/v1.15.1/en/enterprise/integrations/notion.mdx new file mode 100644 index 000000000..c094da071 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/notion.mdx @@ -0,0 +1,296 @@ +--- +title: Notion Integration +description: "User management and commenting with Notion integration for CrewAI." +icon: "book" +mode: "wide" +--- + +## Overview + +Enable your agents to manage users and create comments through Notion. Access workspace user information and create comments on pages and discussions, streamlining your collaboration workflows with AI-powered automation. + +## Prerequisites + +Before using the Notion integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Notion account with appropriate workspace permissions +- Connected your Notion account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors) + +## Setting Up Notion Integration + +### 1. Connect Your Notion Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Notion** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for user access and comment creation +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Actions + + + + **Description:** List all users in the workspace. + + **Parameters:** + - `page_size` (integer, optional): Number of items returned in the response. Minimum: 1, Maximum: 100, Default: 100 + - `start_cursor` (string, optional): Cursor for pagination. Return results after this cursor. + + + + + **Description:** Retrieve a specific user by ID. + + **Parameters:** + - `user_id` (string, required): The ID of the user to retrieve. + + + + + **Description:** Create a comment on a page or discussion. + + **Parameters:** + - `parent` (object, required): The parent page or discussion to comment on. + ```json + { + "type": "page_id", + "page_id": "PAGE_ID_HERE" + } + ``` + or + ```json + { + "type": "discussion_id", + "discussion_id": "DISCUSSION_ID_HERE" + } + ``` + - `rich_text` (array, required): The rich text content of the comment. + ```json + [ + { + "type": "text", + "text": { + "content": "This is my comment text" + } + } + ] + ``` + + + + +## Usage Examples + +### Basic Notion Agent Setup + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Notion capabilities +notion_agent = Agent( + role="Workspace Manager", + goal="Manage workspace users and facilitate collaboration through comments", + backstory="An AI assistant specialized in user management and team collaboration.", + apps=['notion'] # All Notion actions will be available +) + +# Task to list workspace users +user_management_task = Task( + description="List all users in the workspace and provide a summary of team members", + agent=notion_agent, + expected_output="Complete list of workspace users with their details" +) + +# Run the task +crew = Crew( + agents=[notion_agent], + tasks=[user_management_task] +) + +crew.kickoff() +``` + +### Filtering Specific Notion Tools + +```python +comment_manager = Agent( + role="Comment Manager", + goal="Create and manage comments on Notion pages", + backstory="An AI assistant that focuses on facilitating discussions through comments.", + apps=['notion/create_comment'] +) + +# Task to create comments on pages +comment_task = Task( + description="Create a summary comment on the project status page with key updates", + agent=comment_manager, + expected_output="Comment created successfully with project status updates" +) + +crew = Crew( + agents=[comment_manager], + tasks=[comment_task] +) + +crew.kickoff() +``` + +### User Information and Team Management + +```python +from crewai import Agent, Task, Crew + +team_coordinator = Agent( + role="Team Coordinator", + goal="Coordinate team activities and manage user information", + backstory="An AI assistant that helps coordinate team activities and manages user information.", + apps=['notion'] +) + +# Task to coordinate team activities +coordination_task = Task( + description=""" + 1. List all users in the workspace + 2. Get detailed information for specific team members + 3. Create comments on relevant pages to notify team members about updates + """, + agent=team_coordinator, + expected_output="Team coordination completed with user information gathered and notifications sent" +) + +crew = Crew( + agents=[team_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### Collaboration and Communication + +```python +from crewai import Agent, Task, Crew + +collaboration_facilitator = Agent( + role="Collaboration Facilitator", + goal="Facilitate team collaboration through comments and user management", + backstory="An AI assistant that specializes in team collaboration and communication.", + apps=['notion'] +) + +# Task to facilitate collaboration +collaboration_task = Task( + description=""" + 1. Identify active users in the workspace + 2. Create contextual comments on project pages to facilitate discussions + 3. Provide status updates and feedback through comments + """, + agent=collaboration_facilitator, + expected_output="Collaboration facilitated with comments created and team members notified" +) + +crew = Crew( + agents=[collaboration_facilitator], + tasks=[collaboration_task] +) + +crew.kickoff() +``` + +### Automated Team Communication + +```python +from crewai import Agent, Task, Crew + +communication_automator = Agent( + role="Communication Automator", + goal="Automate team communication and user management workflows", + backstory="An AI assistant that automates communication workflows and manages user interactions.", + apps=['notion'] +) + +# Complex communication automation task +automation_task = Task( + description=""" + 1. List all workspace users and identify team roles + 2. Get specific user information for project stakeholders + 3. Create automated status update comments on key project pages + 4. Facilitate team communication through targeted comments + """, + agent=communication_automator, + expected_output="Automated communication workflow completed with user management and comments" +) + +crew = Crew( + agents=[communication_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Troubleshooting + +### Common Issues + +**Permission Errors** + +- Ensure your Notion account has appropriate permissions to read user information +- Verify that the OAuth connection includes required scopes for user access and comment creation +- Check that you have permissions to comment on the target pages or discussions + +**User Access Issues** + +- Ensure you have workspace admin permissions to list all users +- Verify that user IDs are correct and users exist in the workspace +- Check that the workspace allows API access to user information + +**Comment Creation Issues** + +- Verify that page IDs or discussion IDs are correct and accessible +- Ensure that rich text content follows Notion's API format specifications +- Check that you have comment permissions on the target pages or discussions + +**API Rate Limits** + +- Be mindful of Notion's API rate limits when making multiple requests +- Implement appropriate delays between requests if needed +- Consider pagination for large user lists + +**Parent Object Specification** + +- Ensure parent object type is correctly specified (page_id or discussion_id) +- Verify that the parent page or discussion exists and is accessible +- Check that the parent object ID format is correct + +### Getting Help + + + Contact our support team for assistance with Notion integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/salesforce.mdx b/docs/v1.15.1/en/enterprise/integrations/salesforce.mdx new file mode 100644 index 000000000..5e4eb0e8b --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/salesforce.mdx @@ -0,0 +1,731 @@ +--- +title: Salesforce Integration +description: "CRM and sales automation with Salesforce integration for CrewAI." +icon: "salesforce" +mode: "wide" +--- + +## Overview + +Enable your agents to manage customer relationships, sales processes, and data through Salesforce. Create and update records, manage leads and opportunities, execute SOQL queries, and streamline your CRM workflows with AI-powered automation. + +## Prerequisites + +Before using the Salesforce integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Salesforce account with appropriate permissions +- Connected your Salesforce account through the [Integrations page](https://app.crewai.com/integrations) + + + Salesforce requires a **one-time admin install** of the CrewAI package in + your org before any user can connect. This is a Salesforce platform + requirement for all ExternalClientApp-based integrations as of the Spring + '26 release — not a CrewAI-specific step. The Connect Salesforce flow in + CrewAI AMP walks you through it the first time. + + +## Setting Up Salesforce Integration + +### 1. Connect Your Salesforce Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/unified_tools). +2. Find **Salesforce** in the Authentication Integrations section. +3. Click **Connect**. + +What happens next depends on whether a Salesforce admin in your org has +already installed the CrewAI package: + +- **Package already installed:** you're taken straight to the Salesforce + OAuth consent screen — approve it and you're connected. +- **Package not installed yet:** you'll see an **Install CrewAI in + Salesforce** page. Follow the one-time install steps below, then come + back to CrewAI AMP and click **Connect** again. + +4. Grant the necessary permissions for CRM and sales management. +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations). + +#### One-time admin install (Salesforce admin only) + +The first time anyone in your org clicks **Connect Salesforce**, CrewAI +redirects them to an install page that points at the CrewAI managed package. +A Salesforce admin needs to install it once for the whole org. + +1. On the install page in CrewAI, click **Install in Salesforce**. (You can + also share the page URL with your admin — the install link works for + anyone who opens it.) +2. Sign in to Salesforce as an admin. For sandboxes, swap `login.salesforce.com` + for `test.salesforce.com` in the URL before opening it. +3. Choose **Install for All Users**, acknowledge the third-party app prompt, + and click **Install**. +4. In Salesforce Setup, search **External Client App Manager** → **CrewAI + App** → open the **Policies** tab → **Edit** and set: + - **Permitted Users:** All users may self-authorize + - **IP Relaxation:** Relax IP restrictions + - **Refresh Token Policy:** Refresh token is valid until revoked +5. Save. +6. Return to CrewAI AMP and click **Connect Salesforce** again. OAuth will + complete this time. + + + **Not a Salesforce admin?** Forward the install page URL (or the install + link itself) to your Salesforce admin and ask them to complete the steps + above. Once they're done, return to CrewAI AMP and click **Connect** again. + + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Tools + +### **Record Management** + + + + **Description:** Create a new Contact record in Salesforce. + + **Parameters:** + - `FirstName` (string, optional): First Name + - `LastName` (string, required): Last Name - This field is required + - `accountId` (string, optional): Account ID - The Account that the Contact belongs to + - `Email` (string, optional): Email address + - `Title` (string, optional): Title of the contact, such as CEO or Vice President + - `Description` (string, optional): A description of the Contact + - `additionalFields` (object, optional): Additional fields in JSON format for custom Contact fields + + + + + **Description:** Create a new Lead record in Salesforce. + + **Parameters:** + - `FirstName` (string, optional): First Name + - `LastName` (string, required): Last Name - This field is required + - `Company` (string, required): Company - This field is required + - `Email` (string, optional): Email address + - `Phone` (string, optional): Phone number + - `Website` (string, optional): Website URL + - `Title` (string, optional): Title of the contact, such as CEO or Vice President + - `Status` (string, optional): Lead Status - Use Connect Portal Workflow Settings to select Lead Status + - `Description` (string, optional): A description of the Lead + - `additionalFields` (object, optional): Additional fields in JSON format for custom Lead fields + + + + + **Description:** Create a new Opportunity record in Salesforce. + + **Parameters:** + - `Name` (string, required): The Opportunity name - This field is required + - `StageName` (string, optional): Opportunity Stage - Use Connect Portal Workflow Settings to select stage + - `CloseDate` (string, optional): Close Date in YYYY-MM-DD format - Defaults to 30 days from current date + - `AccountId` (string, optional): The Account that the Opportunity belongs to + - `Amount` (string, optional): Estimated total sale amount + - `Description` (string, optional): A description of the Opportunity + - `OwnerId` (string, optional): The Salesforce user assigned to work on this Opportunity + - `NextStep` (string, optional): Description of next task in closing Opportunity + - `additionalFields` (object, optional): Additional fields in JSON format for custom Opportunity fields + + + + + **Description:** Create a new Task record in Salesforce. + + **Parameters:** + - `whatId` (string, optional): Related to ID - The ID of the Account or Opportunity this Task is related to + - `whoId` (string, optional): Name ID - The ID of the Contact or Lead this Task is related to + - `subject` (string, required): Subject of the task + - `activityDate` (string, optional): Activity Date in YYYY-MM-DD format + - `description` (string, optional): A description of the Task + - `taskSubtype` (string, required): Task Subtype - Options: task, email, listEmail, call + - `Status` (string, optional): Status - Options: Not Started, In Progress, Completed + - `ownerId` (string, optional): Assigned To ID - The Salesforce user assigned to this Task + - `callDurationInSeconds` (string, optional): Call Duration in seconds + - `isReminderSet` (boolean, optional): Whether reminder is set + - `reminderDateTime` (string, optional): Reminder Date/Time in ISO format + - `additionalFields` (object, optional): Additional fields in JSON format for custom Task fields + + + + + **Description:** Create a new Account record in Salesforce. + + **Parameters:** + - `Name` (string, required): The Account name - This field is required + - `OwnerId` (string, optional): The Salesforce user assigned to this Account + - `Website` (string, optional): Website URL + - `Phone` (string, optional): Phone number + - `Description` (string, optional): Account description + - `additionalFields` (object, optional): Additional fields in JSON format for custom Account fields + + + + + **Description:** Create a record of any object type in Salesforce. + + **Note:** This is a flexible tool for creating records of custom or unknown object types. + + + + +### **Record Updates** + + + + **Description:** Update an existing Contact record in Salesforce. + + **Parameters:** + - `recordId` (string, required): The ID of the record to update + - `FirstName` (string, optional): First Name + - `LastName` (string, optional): Last Name + - `accountId` (string, optional): Account ID - The Account that the Contact belongs to + - `Email` (string, optional): Email address + - `Title` (string, optional): Title of the contact + - `Description` (string, optional): A description of the Contact + - `additionalFields` (object, optional): Additional fields in JSON format for custom Contact fields + + + + + **Description:** Update an existing Lead record in Salesforce. + + **Parameters:** + - `recordId` (string, required): The ID of the record to update + - `FirstName` (string, optional): First Name + - `LastName` (string, optional): Last Name + - `Company` (string, optional): Company name + - `Email` (string, optional): Email address + - `Phone` (string, optional): Phone number + - `Website` (string, optional): Website URL + - `Title` (string, optional): Title of the contact + - `Status` (string, optional): Lead Status + - `Description` (string, optional): A description of the Lead + - `additionalFields` (object, optional): Additional fields in JSON format for custom Lead fields + + + + + **Description:** Update an existing Opportunity record in Salesforce. + + **Parameters:** + - `recordId` (string, required): The ID of the record to update + - `Name` (string, optional): The Opportunity name + - `StageName` (string, optional): Opportunity Stage + - `CloseDate` (string, optional): Close Date in YYYY-MM-DD format + - `AccountId` (string, optional): The Account that the Opportunity belongs to + - `Amount` (string, optional): Estimated total sale amount + - `Description` (string, optional): A description of the Opportunity + - `OwnerId` (string, optional): The Salesforce user assigned to work on this Opportunity + - `NextStep` (string, optional): Description of next task in closing Opportunity + - `additionalFields` (object, optional): Additional fields in JSON format for custom Opportunity fields + + + + + **Description:** Update an existing Task record in Salesforce. + + **Parameters:** + - `recordId` (string, required): The ID of the record to update + - `whatId` (string, optional): Related to ID - The ID of the Account or Opportunity this Task is related to + - `whoId` (string, optional): Name ID - The ID of the Contact or Lead this Task is related to + - `subject` (string, optional): Subject of the task + - `activityDate` (string, optional): Activity Date in YYYY-MM-DD format + - `description` (string, optional): A description of the Task + - `Status` (string, optional): Status - Options: Not Started, In Progress, Completed + - `ownerId` (string, optional): Assigned To ID - The Salesforce user assigned to this Task + - `callDurationInSeconds` (string, optional): Call Duration in seconds + - `isReminderSet` (boolean, optional): Whether reminder is set + - `reminderDateTime` (string, optional): Reminder Date/Time in ISO format + - `additionalFields` (object, optional): Additional fields in JSON format for custom Task fields + + + + + **Description:** Update an existing Account record in Salesforce. + + **Parameters:** + - `recordId` (string, required): The ID of the record to update + - `Name` (string, optional): The Account name + - `OwnerId` (string, optional): The Salesforce user assigned to this Account + - `Website` (string, optional): Website URL + - `Phone` (string, optional): Phone number + - `Description` (string, optional): Account description + - `additionalFields` (object, optional): Additional fields in JSON format for custom Account fields + + + + + **Description:** Update a record of any object type in Salesforce. + + **Note:** This is a flexible tool for updating records of custom or unknown object types. + + + + +### **Record Retrieval** + + + + **Description:** Get a Contact record by its ID. + + **Parameters:** + - `recordId` (string, required): Record ID of the Contact + + + + + **Description:** Get a Lead record by its ID. + + **Parameters:** + - `recordId` (string, required): Record ID of the Lead + + + + + **Description:** Get an Opportunity record by its ID. + + **Parameters:** + - `recordId` (string, required): Record ID of the Opportunity + + + + + **Description:** Get a Task record by its ID. + + **Parameters:** + - `recordId` (string, required): Record ID of the Task + + + + + **Description:** Get an Account record by its ID. + + **Parameters:** + - `recordId` (string, required): Record ID of the Account + + + + + **Description:** Get a record of any object type by its ID. + + **Parameters:** + - `recordType` (string, required): Record Type (e.g., "CustomObject__c") + - `recordId` (string, required): Record ID + + + + +### **Record Search** + + + + **Description:** Search for Contact records with advanced filtering. + + **Parameters:** + - `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators + - `sortBy` (string, optional): Sort field (e.g., "CreatedDate") + - `sortDirection` (string, optional): Sort direction - Options: ASC, DESC + - `includeAllFields` (boolean, optional): Include all fields in results + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Search for Lead records with advanced filtering. + + **Parameters:** + - `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators + - `sortBy` (string, optional): Sort field (e.g., "CreatedDate") + - `sortDirection` (string, optional): Sort direction - Options: ASC, DESC + - `includeAllFields` (boolean, optional): Include all fields in results + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Search for Opportunity records with advanced filtering. + + **Parameters:** + - `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators + - `sortBy` (string, optional): Sort field (e.g., "CreatedDate") + - `sortDirection` (string, optional): Sort direction - Options: ASC, DESC + - `includeAllFields` (boolean, optional): Include all fields in results + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Search for Task records with advanced filtering. + + **Parameters:** + - `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators + - `sortBy` (string, optional): Sort field (e.g., "CreatedDate") + - `sortDirection` (string, optional): Sort direction - Options: ASC, DESC + - `includeAllFields` (boolean, optional): Include all fields in results + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Search for Account records with advanced filtering. + + **Parameters:** + - `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators + - `sortBy` (string, optional): Sort field (e.g., "CreatedDate") + - `sortDirection` (string, optional): Sort direction - Options: ASC, DESC + - `includeAllFields` (boolean, optional): Include all fields in results + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Search for records of any object type. + + **Parameters:** + - `recordType` (string, required): Record Type to search + - `filterFormula` (string, optional): Filter search criteria + - `includeAllFields` (boolean, optional): Include all fields in results + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + +### **List View Retrieval** + + + + **Description:** Get Contact records from a specific List View. + + **Parameters:** + - `listViewId` (string, required): List View ID + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Get Lead records from a specific List View. + + **Parameters:** + - `listViewId` (string, required): List View ID + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Get Opportunity records from a specific List View. + + **Parameters:** + - `listViewId` (string, required): List View ID + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Get Task records from a specific List View. + + **Parameters:** + - `listViewId` (string, required): List View ID + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Get Account records from a specific List View. + + **Parameters:** + - `listViewId` (string, required): List View ID + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + + **Description:** Get records of any object type from a specific List View. + + **Parameters:** + - `recordType` (string, required): Record Type + - `listViewId` (string, required): List View ID + - `paginationParameters` (object, optional): Pagination settings with pageCursor + + + + +### **Custom Fields** + + + + **Description:** Deploy custom fields for Contact objects. + + **Parameters:** + - `label` (string, required): Field Label for displays and internal reference + - `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields + - `length` (string, required): Length for numeric/text fields + - `decimalPlace` (string, required): Decimal places for numeric fields + - `pickListValues` (string, required): Values for picklist fields (separated by new lines) + - `visibleLines` (string, required): Visible lines for multiselect/text area fields + - `description` (string, optional): Field description + - `helperText` (string, optional): Helper text shown on hover + - `defaultFieldValue` (string, optional): Default field value + + + + + **Description:** Deploy custom fields for Lead objects. + + **Parameters:** + - `label` (string, required): Field Label for displays and internal reference + - `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields + - `length` (string, required): Length for numeric/text fields + - `decimalPlace` (string, required): Decimal places for numeric fields + - `pickListValues` (string, required): Values for picklist fields (separated by new lines) + - `visibleLines` (string, required): Visible lines for multiselect/text area fields + - `description` (string, optional): Field description + - `helperText` (string, optional): Helper text shown on hover + - `defaultFieldValue` (string, optional): Default field value + + + + + **Description:** Deploy custom fields for Opportunity objects. + + **Parameters:** + - `label` (string, required): Field Label for displays and internal reference + - `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields + - `length` (string, required): Length for numeric/text fields + - `decimalPlace` (string, required): Decimal places for numeric fields + - `pickListValues` (string, required): Values for picklist fields (separated by new lines) + - `visibleLines` (string, required): Visible lines for multiselect/text area fields + - `description` (string, optional): Field description + - `helperText` (string, optional): Helper text shown on hover + - `defaultFieldValue` (string, optional): Default field value + + + + + **Description:** Deploy custom fields for Task objects. + + **Parameters:** + - `label` (string, required): Field Label for displays and internal reference + - `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, Time, Url + - `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields + - `length` (string, required): Length for numeric/text fields + - `decimalPlace` (string, required): Decimal places for numeric fields + - `pickListValues` (string, required): Values for picklist fields (separated by new lines) + - `visibleLines` (string, required): Visible lines for multiselect fields + - `description` (string, optional): Field description + - `helperText` (string, optional): Helper text shown on hover + - `defaultFieldValue` (string, optional): Default field value + + + + + **Description:** Deploy custom fields for Account objects. + + **Parameters:** + - `label` (string, required): Field Label for displays and internal reference + - `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields + - `length` (string, required): Length for numeric/text fields + - `decimalPlace` (string, required): Decimal places for numeric fields + - `pickListValues` (string, required): Values for picklist fields (separated by new lines) + - `visibleLines` (string, required): Visible lines for multiselect/text area fields + - `description` (string, optional): Field description + - `helperText` (string, optional): Helper text shown on hover + - `defaultFieldValue` (string, optional): Default field value + + + + + **Description:** Deploy custom fields for any object type. + + **Note:** This is a flexible tool for creating custom fields on custom or unknown object types. + + + + +### **Advanced Operations** + + + + **Description:** Execute custom SOQL queries against your Salesforce data. + + **Parameters:** + - `query` (string, required): SOQL Query (e.g., "SELECT Id, Name FROM Account WHERE Name = 'Example'") + + + + + **Description:** Deploy a new custom object in Salesforce. + + **Parameters:** + - `label` (string, required): Object Label for tabs, page layouts, and reports + - `pluralLabel` (string, required): Plural Label (e.g., "Accounts") + - `description` (string, optional): A description of the Custom Object + - `recordName` (string, required): Record Name that appears in layouts and searches (e.g., "Account Name") + + + + + **Description:** Get the expected schema for operations on specific object types. + + **Parameters:** + - `recordType` (string, required): Record Type to describe + - `operation` (string, required): Operation Type (e.g., "CREATE_RECORD" or "UPDATE_RECORD") + + **Note:** Use this function first when working with custom objects to understand their schema before performing operations. + + + + +## Usage Examples + +### Basic Salesforce Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Salesforce capabilities +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.", + apps=['salesforce'] # All Salesforce actions will be available +) + +# 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() +``` + +### Filtering Specific Salesforce Tools + +```python + +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.", + apps=['salesforce/create_record_lead'] +) + +# 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() +``` + +### Contact and Account Management + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['salesforce'] +) + +# 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() +``` + +### Advanced SOQL Queries and Reporting + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['salesforce'] +) + +# 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() +``` + +This comprehensive documentation covers all the Salesforce tools organized by functionality, making it easy for users to find the specific operations they need for their CRM automation tasks. + +### Getting Help + + + Contact our support team for assistance with Salesforce integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/shopify.mdx b/docs/v1.15.1/en/enterprise/integrations/shopify.mdx new file mode 100644 index 000000000..47e4cdf26 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/shopify.mdx @@ -0,0 +1,410 @@ +--- +title: Shopify Integration +description: "E-commerce and online store management with Shopify integration for CrewAI." +icon: "shopify" +mode: "wide" +--- + +## Overview + +Enable your agents to manage e-commerce operations through Shopify. Handle customers, orders, products, inventory, and store analytics to streamline your online business with AI-powered automation. + +## Prerequisites + +Before using the Shopify integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Shopify store with appropriate admin permissions +- Connected your Shopify store through the [Integrations page](https://app.crewai.com/integrations) + +## Setting Up Shopify Integration + +### 1. Connect Your Shopify Store + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Shopify** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for store and product management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Tools + +### **Customer Management** + + + + **Description:** Retrieve a list of customers from your Shopify store. + + **Parameters:** + - `customerIds` (string, optional): Comma-separated list of customer IDs to filter by (example: "207119551, 207119552") + - `createdAtMin` (string, optional): Only return customers created after this date (ISO or Unix timestamp) + - `createdAtMax` (string, optional): Only return customers created before this date (ISO or Unix timestamp) + - `updatedAtMin` (string, optional): Only return customers updated after this date (ISO or Unix timestamp) + - `updatedAtMax` (string, optional): Only return customers updated before this date (ISO or Unix timestamp) + - `limit` (string, optional): Maximum number of customers to return (defaults to 250) + + + + + **Description:** Search for customers using advanced filtering criteria. + + **Parameters:** + - `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators + - `limit` (string, optional): Maximum number of customers to return (defaults to 250) + + + + + **Description:** Create a new customer in your Shopify store. + + **Parameters:** + - `firstName` (string, required): Customer's first name + - `lastName` (string, required): Customer's last name + - `email` (string, required): Customer's email address + - `company` (string, optional): Company name + - `streetAddressLine1` (string, optional): Street address + - `streetAddressLine2` (string, optional): Street address line 2 + - `city` (string, optional): City + - `state` (string, optional): State or province code + - `country` (string, optional): Country + - `zipCode` (string, optional): Zip code + - `phone` (string, optional): Phone number + - `tags` (string, optional): Tags as array or comma-separated list + - `note` (string, optional): Customer note + - `sendEmailInvite` (boolean, optional): Whether to send email invitation + - `metafields` (object, optional): Additional metafields in JSON format + + + + + **Description:** Update an existing customer in your Shopify store. + + **Parameters:** + - `customerId` (string, required): The ID of the customer to update + - `firstName` (string, optional): Customer's first name + - `lastName` (string, optional): Customer's last name + - `email` (string, optional): Customer's email address + - `company` (string, optional): Company name + - `streetAddressLine1` (string, optional): Street address + - `streetAddressLine2` (string, optional): Street address line 2 + - `city` (string, optional): City + - `state` (string, optional): State or province code + - `country` (string, optional): Country + - `zipCode` (string, optional): Zip code + - `phone` (string, optional): Phone number + - `tags` (string, optional): Tags as array or comma-separated list + - `note` (string, optional): Customer note + - `sendEmailInvite` (boolean, optional): Whether to send email invitation + - `metafields` (object, optional): Additional metafields in JSON format + + + + +### **Order Management** + + + + **Description:** Retrieve a list of orders from your Shopify store. + + **Parameters:** + - `orderIds` (string, optional): Comma-separated list of order IDs to filter by (example: "450789469, 450789470") + - `createdAtMin` (string, optional): Only return orders created after this date (ISO or Unix timestamp) + - `createdAtMax` (string, optional): Only return orders created before this date (ISO or Unix timestamp) + - `updatedAtMin` (string, optional): Only return orders updated after this date (ISO or Unix timestamp) + - `updatedAtMax` (string, optional): Only return orders updated before this date (ISO or Unix timestamp) + - `limit` (string, optional): Maximum number of orders to return (defaults to 250) + + + + + **Description:** Create a new order in your Shopify store. + + **Parameters:** + - `email` (string, required): Customer email address + - `lineItems` (object, required): Order line items in JSON format with title, price, quantity, and variant_id + - `sendReceipt` (boolean, optional): Whether to send order receipt + - `fulfillmentStatus` (string, optional): Fulfillment status - Options: fulfilled, null, partial, restocked + - `financialStatus` (string, optional): Financial status - Options: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided + - `inventoryBehaviour` (string, optional): Inventory behavior - Options: bypass, decrement_ignoring_policy, decrement_obeying_policy + - `note` (string, optional): Order note + + + + + **Description:** Update an existing order in your Shopify store. + + **Parameters:** + - `orderId` (string, required): The ID of the order to update + - `email` (string, optional): Customer email address + - `lineItems` (object, optional): Updated order line items in JSON format + - `sendReceipt` (boolean, optional): Whether to send order receipt + - `fulfillmentStatus` (string, optional): Fulfillment status - Options: fulfilled, null, partial, restocked + - `financialStatus` (string, optional): Financial status - Options: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided + - `inventoryBehaviour` (string, optional): Inventory behavior - Options: bypass, decrement_ignoring_policy, decrement_obeying_policy + - `note` (string, optional): Order note + + + + + **Description:** Retrieve abandoned carts from your Shopify store. + + **Parameters:** + - `createdWithInLast` (string, optional): Restrict results to checkouts created within specified time + - `createdAfterId` (string, optional): Restrict results to after the specified ID + - `status` (string, optional): Show checkouts with given status - Options: open, closed (defaults to open) + - `createdAtMin` (string, optional): Only return carts created after this date (ISO or Unix timestamp) + - `createdAtMax` (string, optional): Only return carts created before this date (ISO or Unix timestamp) + - `limit` (string, optional): Maximum number of carts to return (defaults to 250) + + + + +### **Product Management (REST API)** + + + + **Description:** Retrieve a list of products from your Shopify store using REST API. + + **Parameters:** + - `productIds` (string, optional): Comma-separated list of product IDs to filter by (example: "632910392, 632910393") + - `title` (string, optional): Filter by product title + - `productType` (string, optional): Filter by product type + - `vendor` (string, optional): Filter by vendor + - `status` (string, optional): Filter by status - Options: active, archived, draft + - `createdAtMin` (string, optional): Only return products created after this date (ISO or Unix timestamp) + - `createdAtMax` (string, optional): Only return products created before this date (ISO or Unix timestamp) + - `updatedAtMin` (string, optional): Only return products updated after this date (ISO or Unix timestamp) + - `updatedAtMax` (string, optional): Only return products updated before this date (ISO or Unix timestamp) + - `limit` (string, optional): Maximum number of products to return (defaults to 250) + + + + + **Description:** Create a new product in your Shopify store using REST API. + + **Parameters:** + - `title` (string, required): Product title + - `productType` (string, required): Product type/category + - `vendor` (string, required): Product vendor + - `productDescription` (string, optional): Product description (accepts plain text or HTML) + - `tags` (string, optional): Product tags as array or comma-separated list + - `price` (string, optional): Product price + - `inventoryPolicy` (string, optional): Inventory policy - Options: deny, continue + - `imageUrl` (string, optional): Product image URL + - `isPublished` (boolean, optional): Whether product is published + - `publishToPointToSale` (boolean, optional): Whether to publish to point of sale + + + + + **Description:** Update an existing product in your Shopify store using REST API. + + **Parameters:** + - `productId` (string, required): The ID of the product to update + - `title` (string, optional): Product title + - `productType` (string, optional): Product type/category + - `vendor` (string, optional): Product vendor + - `productDescription` (string, optional): Product description (accepts plain text or HTML) + - `tags` (string, optional): Product tags as array or comma-separated list + - `price` (string, optional): Product price + - `inventoryPolicy` (string, optional): Inventory policy - Options: deny, continue + - `imageUrl` (string, optional): Product image URL + - `isPublished` (boolean, optional): Whether product is published + - `publishToPointToSale` (boolean, optional): Whether to publish to point of sale + + + + +### **Product Management (GraphQL)** + + + + **Description:** Retrieve products using advanced GraphQL filtering capabilities. + + **Parameters:** + - `productFilterFormula` (object, optional): Advanced filter in disjunctive normal form with support for fields like id, title, vendor, status, handle, tag, created_at, updated_at, published_at + + + + + **Description:** Create a new product using GraphQL API with enhanced media support. + + **Parameters:** + - `title` (string, required): Product title + - `productType` (string, required): Product type/category + - `vendor` (string, required): Product vendor + - `productDescription` (string, optional): Product description (accepts plain text or HTML) + - `tags` (string, optional): Product tags as array or comma-separated list + - `media` (object, optional): Media objects with alt text, content type, and source URL + - `additionalFields` (object, optional): Additional product fields like status, requiresSellingPlan, giftCard + + + + + **Description:** Update an existing product using GraphQL API with enhanced media support. + + **Parameters:** + - `productId` (string, required): The GraphQL ID of the product to update (e.g., "gid://shopify/Product/913144112") + - `title` (string, optional): Product title + - `productType` (string, optional): Product type/category + - `vendor` (string, optional): Product vendor + - `productDescription` (string, optional): Product description (accepts plain text or HTML) + - `tags` (string, optional): Product tags as array or comma-separated list + - `media` (object, optional): Updated media objects with alt text, content type, and source URL + - `additionalFields` (object, optional): Additional product fields like status, requiresSellingPlan, giftCard + + + + +## Usage Examples + +### Basic Shopify Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# 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.", + apps=['shopify'] # All Shopify actions will be available +) + +# 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() +``` + +### Filtering Specific Shopify Tools + +```python + +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.", + apps=['shopify/create_customer'] +) + +# 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() +``` + +### Product Management with GraphQL + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['shopify'] +) + +# 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() +``` + +### Order and Customer Analytics + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['shopify'] +) + +# 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() +``` + +### Getting Help + + + Contact our support team for assistance with Shopify integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/slack.mdx b/docs/v1.15.1/en/enterprise/integrations/slack.mdx new file mode 100644 index 000000000..a997f4d94 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/slack.mdx @@ -0,0 +1,327 @@ +--- +title: Slack Integration +description: "Team communication and collaboration with Slack integration for CrewAI." +icon: "slack" +mode: "wide" +--- + +## Overview + +Enable your agents to manage team communication through Slack. Send messages, search conversations, manage channels, and coordinate team activities to streamline your collaboration workflows with AI-powered automation. + +## Prerequisites + +Before using the Slack integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Slack workspace with appropriate permissions +- Connected your Slack workspace through the [Integrations page](https://app.crewai.com/integrations) + +## Setting Up Slack Integration + +### 1. Connect Your Slack Workspace + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Slack** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for team communication +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Tools + +### **User Management** + + + + **Description:** List all members in a Slack channel. + + **Parameters:** + - No parameters required - retrieves all channel members + + + + + **Description:** Find a user in your Slack workspace by their email address. + + **Parameters:** + - `email` (string, required): The email address of a user in the workspace + + + + + **Description:** Search for users by their name or display name. + + **Parameters:** + - `name` (string, required): User's real name to search for + - `displayName` (string, required): User's display name to search for + - `paginationParameters` (object, optional): Pagination settings + - `pageCursor` (string, optional): Page cursor for pagination + + + + +### **Channel Management** + + + + **Description:** List all channels in your Slack workspace. + + **Parameters:** + - No parameters required - retrieves all accessible channels + + + + +### **Messaging** + + + + **Description:** Send a message to a Slack channel. + + **Parameters:** + - `channel` (string, required): Channel name or ID - Use Connect Portal Workflow Settings to allow users to select a channel, or enter a channel name to create a new channel + - `message` (string, required): The message text to send + - `botName` (string, required): The name of the bot that sends this message + - `botIcon` (string, required): Bot icon - Can be either an image URL or an emoji (e.g., ":dog:") + - `blocks` (object, optional): Slack Block Kit JSON for rich message formatting with attachments and interactive elements + - `authenticatedUser` (boolean, optional): If true, message appears to come from your authenticated Slack user instead of the application (defaults to false) + + + + + **Description:** Send a direct message to a specific user in Slack. + + **Parameters:** + - `memberId` (string, required): Recipient user ID - Use Connect Portal Workflow Settings to allow users to select a workspace member + - `message` (string, required): The message text to send + - `botName` (string, required): The name of the bot that sends this message + - `botIcon` (string, required): Bot icon - Can be either an image URL or an emoji (e.g., ":dog:") + - `blocks` (object, optional): Slack Block Kit JSON for rich message formatting with attachments and interactive elements + - `authenticatedUser` (boolean, optional): If true, message appears to come from your authenticated Slack user instead of the application (defaults to false) + + + + +### **Search & Discovery** + + + + **Description:** Search for messages across your Slack workspace. + + **Parameters:** + - `query` (string, required): Search query using Slack search syntax to find messages that match specified criteria + + **Search Query Examples:** + - `"project update"` - Search for messages containing "project update" + - `from:@john in:#general` - Search for messages from John in the #general channel + - `has:link after:2023-01-01` - Search for messages with links after January 1, 2023 + - `in:@channel before:yesterday` - Search for messages in a specific channel before yesterday + + + + +## Block Kit Integration + +Slack's Block Kit allows you to create rich, interactive messages. Here are some examples of how to use the `blocks` parameter: + +### Simple Text with Attachment + +```json +[ + { + "text": "I am a test message", + "attachments": [ + { + "text": "And here's an attachment!" + } + ] + } +] +``` + +### Rich Formatting with Sections + +```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." + } + } +] +``` + +## Usage Examples + +### Basic Slack Agent Setup + +```python +from crewai import Agent, Task, Crew + +# 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.", + apps=['slack'] # All Slack actions will be available +) + +# 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() +``` + +### Filtering Specific Slack Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Slack actions only +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.", + apps=[ + 'slack/send_message', + 'slack/send_direct_message', + 'slack/search_messages' + ] # Using canonical action names from canonical_integrations.yml +) + +# 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() +``` + +### Advanced Messaging with Block Kit + +```python +from crewai import Agent, Task, Crew + +# Create agent with Slack messaging capabilities +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.", + apps=['slack/send_message'] # Specific action for sending messages +) + +# 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() +``` + +### Message Search and Analytics + +```python +from crewai import Agent, Task, Crew + +# Create agent with Slack search and user management capabilities +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.", + apps=[ + 'slack/search_messages', + 'slack/get_user_by_email', + 'slack/list_members' + ] # Using canonical action names from canonical_integrations.yml +) + +# 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() +``` + +## Contact Support + + + Contact our support team for assistance with Slack integration setup or + troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/snowflake.mdx b/docs/v1.15.1/en/enterprise/integrations/snowflake.mdx new file mode 100644 index 000000000..76724a5f1 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/snowflake.mdx @@ -0,0 +1,134 @@ +--- +title: Snowflake Integration +description: "Connect CrewAI agents to Snowflake Cortex Analyst, Cortex Search, and SQL execution through the Snowflake-managed MCP server." +icon: "snowflake" +mode: "wide" +--- + +## Overview + +Connect your CrewAI agents directly to your Snowflake data through the [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). The Snowflake integration lets your agents query structured data with **Cortex Analyst**, search unstructured data with **Cortex Search**, and run governed SQL against your warehouses — all without writing or hosting any connector code. + +Under the hood, the Snowflake integration is a managed wrapper around CrewAI's [Custom MCP Server](/en/enterprise/guides/custom-mcp-server) support. Snowflake exposes its Cortex AI capabilities through a [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, and CrewAI connects to it securely on your behalf. Any tool you expose on the Snowflake side — Cortex Analyst, Cortex Search, SQL execution, Cortex Agents, or your own custom tools — becomes available to your crews. + +## Key Capabilities + + + + Ask questions in natural language and let [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) generate and run SQL against your **structured** data using rich semantic models. + + + Retrieve relevant **unstructured** data for RAG and knowledge workflows with [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview), Snowflake's fully managed search service. + + + Run governed SQL queries directly against your Snowflake warehouses, with configurable read-only mode, timeouts, and warehouse selection. + + + +Because the integration surfaces whatever tools your MCP server publishes, you can also expose **Cortex Agents** and **custom tools** (user-defined functions and stored procedures) to your CrewAI agents. + +## Prerequisites + +Before using the Snowflake integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Snowflake account with access to Cortex AI features +- A [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) configured with the tools you want to expose +- Appropriate Snowflake privileges (USAGE/SELECT) on the MCP server and its underlying objects + +## Setting Up the Snowflake MCP Server + +The Snowflake-managed MCP server runs inside your Snowflake account and defines which tools are available to external clients like CrewAI. Create one with the [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server) command, listing the Cortex Search services, Cortex Analyst semantic views, and SQL tools you want to expose. + +```sql +CREATE MCP SERVER my_mcp_server + FROM SPECIFICATION $$ + tools: + - name: "sales_analyst" + type: "CORTEX_ANALYST" + identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view" + description: "Answer questions about sales metrics" + - name: "docs_search" + type: "CORTEX_SEARCH_SERVICE_QUERY" + identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search" + description: "Search internal support documentation" + - name: "run_sql" + type: "SQL_EXECUTION" + description: "Execute read-only SQL queries" + $$; +``` + + +The MCP endpoint follows the format `https:///api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}`. CrewAI builds this URL automatically from the **Account URL**, **Database**, **Schema**, and **MCP Server Name** you provide when configuring the integration. + + +For the complete specification — including Cortex Agents, custom tools, response-size limits, and governance options — see the [Snowflake-managed MCP server documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). + +## Connecting Snowflake in CrewAI AMP + + + Configure Snowflake integration in CrewAI AMP + + + + + Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP, find **Snowflake** in the list of applications, and open its configuration panel. + + + + Fill in the connection fields that CrewAI uses to reach your Snowflake MCP server: + + | Field | Required | Description | + |-------|----------|-------------| + | **Name** | Yes | A descriptive name for this connection (defaults to `Snowflake`). | + | **Description** | No | An optional summary of what this connection provides. | + | **Account URL** | Yes | Your Snowflake account URL, e.g. `xy12345.us-east-1.snowflakecomputing.com`. | + | **Database** | Yes | The database that contains your MCP server (e.g. `MY_DATABASE`). | + | **Schema** | Yes | The schema that contains your MCP server (e.g. `MY_SCHEMA`). | + | **MCP Server Name** | Yes | The name of the MCP server object you created in Snowflake (e.g. `MY_MCP_SERVER`). | + + + + Select how CrewAI authenticates to Snowflake. **OAuth** is recommended. + + - **Use OAuth** — Connect securely using OAuth 2.0 for token-based authentication without sharing your credentials. CrewAI handles the full authorization flow and refreshes tokens automatically. Copy the **Redirect URI** shown in the form (`https://oauth.crewai.com/oauth/add`) and register it as an authorized redirect URI in your Snowflake [OAuth security integration](https://docs.snowflake.com/en/user-guide/oauth-custom). + - **Use personal access token** — Authenticate using a [programmatic access token](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) generated from your Snowflake account settings. Assign a least-privileged role to the token to limit exposure. + + + + Click **Authenticate**. For OAuth, you'll be redirected to Snowflake to authorize access. Once authenticated, the Snowflake server appears in your Connections and its tools become available to your crews. + + + + +With OAuth, each user authenticates individually and queries run with their Snowflake `DEFAULT_ROLE`. Make sure connecting users have a default role and warehouse set (`ALTER USER SET DEFAULT_ROLE = '' DEFAULT_WAREHOUSE = ''`) so Cortex Analyst and SQL tools have compute to run on. + + +## Using Snowflake Tools in Your Crews + +Once connected, the tools your MCP server exposes appear alongside built-in connections on the **Tools & Integrations** page. You can: + +- **Assign tools to agents** in your crews just like any other CrewAI tool. +- **Manage visibility** to control which team members can use the connection. +- **Edit or remove** the connection at any time from the Connections list. + +Your agents can now ask Cortex Analyst for metrics, run Cortex Search over your documents, and execute SQL — with results flowing back into their reasoning automatically. + + +Snowflake enforces governance on the MCP server: role-based access control determines which tools a user can discover and invoke, and limits apply to response size, tool count (max 50 per server), and recursion depth. If a tool call fails, confirm the connecting user's role has the required privileges on the MCP server and its underlying objects. + + +## Learn More + + + + Official Snowflake documentation for creating and governing the MCP server. + + + Learn how CrewAI connects to any MCP server, the foundation the Snowflake integration builds on. + + + + + Contact our support team for assistance with the Snowflake integration or troubleshooting. + diff --git a/docs/v1.15.1/en/enterprise/integrations/stripe.mdx b/docs/v1.15.1/en/enterprise/integrations/stripe.mdx new file mode 100644 index 000000000..bf61c36fc --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/stripe.mdx @@ -0,0 +1,329 @@ +--- +title: Stripe Integration +description: "Payment processing and subscription management with Stripe integration for CrewAI." +icon: "stripe" +mode: "wide" +--- + +## Overview + +Enable your agents to manage payments, subscriptions, and customer billing through Stripe. Handle customer data, process subscriptions, manage products, and track financial transactions to streamline your payment workflows with AI-powered automation. + +## Prerequisites + +Before using the Stripe integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Stripe account with appropriate API permissions +- Connected your Stripe account through the [Integrations page](https://app.crewai.com/integrations) + +## Setting Up Stripe Integration + +### 1. Connect Your Stripe Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Stripe** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for payment processing +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Tools + +### **Customer Management** + + + + **Description:** Create a new customer in your Stripe account. + + **Parameters:** + - `emailCreateCustomer` (string, required): Customer's email address + - `name` (string, optional): Customer's full name + - `description` (string, optional): Customer description for internal reference + - `metadataCreateCustomer` (object, optional): Additional metadata as key-value pairs (e.g., `{"field1": 1, "field2": 2}`) + + + + + **Description:** Retrieve a specific customer by their Stripe customer ID. + + **Parameters:** + - `idGetCustomer` (string, required): The Stripe customer ID to retrieve + + + + + **Description:** Retrieve a list of customers with optional filtering. + + **Parameters:** + - `emailGetCustomers` (string, optional): Filter customers by email address + - `createdAfter` (string, optional): Filter customers created after this date (Unix timestamp) + - `createdBefore` (string, optional): Filter customers created before this date (Unix timestamp) + - `limitGetCustomers` (string, optional): Maximum number of customers to return (defaults to 10) + + + + + **Description:** Update an existing customer's information. + + **Parameters:** + - `customerId` (string, required): The ID of the customer to update + - `emailUpdateCustomer` (string, optional): Updated email address + - `name` (string, optional): Updated customer name + - `description` (string, optional): Updated customer description + - `metadataUpdateCustomer` (object, optional): Updated metadata as key-value pairs + + + + +### **Subscription Management** + + + + **Description:** Create a new subscription for a customer. + + **Parameters:** + - `customerIdCreateSubscription` (string, required): The customer ID for whom the subscription will be created + - `plan` (string, required): The plan ID for the subscription - Use Connect Portal Workflow Settings to allow users to select a plan + - `metadataCreateSubscription` (object, optional): Additional metadata for the subscription + + + + + **Description:** Retrieve subscriptions with optional filtering. + + **Parameters:** + - `customerIdGetSubscriptions` (string, optional): Filter subscriptions by customer ID + - `subscriptionStatus` (string, optional): Filter by subscription status - Options: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid + - `limitGetSubscriptions` (string, optional): Maximum number of subscriptions to return (defaults to 10) + + + + +### **Product Management** + + + + **Description:** Create a new product in your Stripe catalog. + + **Parameters:** + - `productName` (string, required): The product name + - `description` (string, optional): Product description + - `metadataProduct` (object, optional): Additional product metadata as key-value pairs + + + + + **Description:** Retrieve a specific product by its Stripe product ID. + + **Parameters:** + - `productId` (string, required): The Stripe product ID to retrieve + + + + + **Description:** Retrieve a list of products with optional filtering. + + **Parameters:** + - `createdAfter` (string, optional): Filter products created after this date (Unix timestamp) + - `createdBefore` (string, optional): Filter products created before this date (Unix timestamp) + - `limitGetProducts` (string, optional): Maximum number of products to return (defaults to 10) + + + + +### **Financial Operations** + + + + **Description:** Retrieve balance transactions from your Stripe account. + + **Parameters:** + - `balanceTransactionType` (string, optional): Filter by transaction type - Options: charge, refund, payment, payment_refund + - `paginationParameters` (object, optional): Pagination settings + - `pageCursor` (string, optional): Page cursor for pagination + + + + + **Description:** Retrieve subscription plans from your Stripe account. + + **Parameters:** + - `isPlanActive` (boolean, optional): Filter by plan status - true for active plans, false for inactive plans + - `paginationParameters` (object, optional): Pagination settings + - `pageCursor` (string, optional): Page cursor for pagination + + + + +## Usage Examples + +### Basic Stripe Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# 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.", + apps=['stripe'] # All Stripe actions will be available +) + +# 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() +``` + +### Filtering Specific Stripe Tools + +```python + +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.", + apps=['stripe'] +) + +# 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() +``` + +### Subscription Management + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['stripe'] +) + +# 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() +``` + +### Financial Analytics and Reporting + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['stripe'] +) + +# 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() +``` + +## Subscription Status Reference + +Understanding subscription statuses: + +- **incomplete** - Subscription requires payment method or payment confirmation +- **incomplete_expired** - Subscription expired before payment was confirmed +- **trialing** - Subscription is in trial period +- **active** - Subscription is active and current +- **past_due** - Payment failed but subscription is still active +- **canceled** - Subscription has been canceled +- **unpaid** - Payment failed and subscription is no longer active + +## Metadata Usage + +Metadata allows you to store additional information about customers, subscriptions, and products: + +```json +{ + "customer_segment": "enterprise", + "acquisition_source": "google_ads", + "lifetime_value": "high", + "custom_field_1": "value1" +} +``` + +This integration enables comprehensive payment and subscription management automation, allowing your AI agents to handle billing operations seamlessly within your Stripe ecosystem. diff --git a/docs/v1.15.1/en/enterprise/integrations/zendesk.mdx b/docs/v1.15.1/en/enterprise/integrations/zendesk.mdx new file mode 100644 index 000000000..6537f3a95 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/integrations/zendesk.mdx @@ -0,0 +1,369 @@ +--- +title: Zendesk Integration +description: "Customer support and helpdesk management with Zendesk integration for CrewAI." +icon: "headset" +mode: "wide" +--- + +## Overview + +Enable your agents to manage customer support operations through Zendesk. Create and update tickets, manage users, track support metrics, and streamline your customer service workflows with AI-powered automation. + +## Prerequisites + +Before using the Zendesk integration, ensure you have: + +- A [CrewAI AMP](https://app.crewai.com) account with an active subscription +- A Zendesk account with appropriate API permissions +- Connected your Zendesk account through the [Integrations page](https://app.crewai.com/integrations) + +## Setting Up Zendesk Integration + +### 1. Connect Your Zendesk Account + +1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors) +2. Find **Zendesk** in the Authentication Integrations section +3. Click **Connect** and complete the OAuth flow +4. Grant the necessary permissions for ticket and user management +5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Install Required Package + +```bash +uv add crewai-tools +``` + +### 3. Environment Variable Setup + + + To use integrations with `Agent(apps=[])`, you must set the + `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise + Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +Or add it to your `.env` file: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## Available Tools + +### **Ticket Management** + + + + **Description:** Create a new support ticket in Zendesk. + + **Parameters:** + - `ticketSubject` (string, required): Ticket subject line (e.g., "Help, my printer is on fire!") + - `ticketDescription` (string, required): First comment that appears on the ticket (e.g., "The smoke is very colorful.") + - `requesterName` (string, required): Name of the user requesting support (e.g., "Jane Customer") + - `requesterEmail` (string, required): Email of the user requesting support (e.g., "jane@example.com") + - `assigneeId` (string, optional): Zendesk Agent ID assigned to this ticket - Use Connect Portal Workflow Settings to allow users to select an assignee + - `ticketType` (string, optional): Ticket type - Options: problem, incident, question, task + - `ticketPriority` (string, optional): Priority level - Options: urgent, high, normal, low + - `ticketStatus` (string, optional): Ticket status - Options: new, open, pending, hold, solved, closed + - `ticketDueAt` (string, optional): Due date for task-type tickets (ISO 8601 timestamp) + - `ticketTags` (string, optional): Array of tags to apply (e.g., `["enterprise", "other_tag"]`) + - `ticketExternalId` (string, optional): External ID to link tickets to local records + - `ticketCustomFields` (object, optional): Custom field values in JSON format + + + + + **Description:** Update an existing support ticket in Zendesk. + + **Parameters:** + - `ticketId` (string, required): ID of the ticket to update (e.g., "35436") + - `ticketSubject` (string, optional): Updated ticket subject + - `requesterName` (string, required): Name of the user who requested this ticket + - `requesterEmail` (string, required): Email of the user who requested this ticket + - `assigneeId` (string, optional): Updated assignee ID - Use Connect Portal Workflow Settings + - `ticketType` (string, optional): Updated ticket type - Options: problem, incident, question, task + - `ticketPriority` (string, optional): Updated priority - Options: urgent, high, normal, low + - `ticketStatus` (string, optional): Updated status - Options: new, open, pending, hold, solved, closed + - `ticketDueAt` (string, optional): Updated due date (ISO 8601 timestamp) + - `ticketTags` (string, optional): Updated tags array + - `ticketExternalId` (string, optional): Updated external ID + - `ticketCustomFields` (object, optional): Updated custom field values + + + + + **Description:** Retrieve a specific ticket by its ID. + + **Parameters:** + - `ticketId` (string, required): The ticket ID to retrieve (e.g., "35436") + + + + + **Description:** Add a comment or internal note to an existing ticket. + + **Parameters:** + - `ticketId` (string, required): ID of the ticket to add comment to (e.g., "35436") + - `commentBody` (string, required): Comment message (accepts plain text or HTML, e.g., "Thanks for your help!") + - `isInternalNote` (boolean, optional): Set to true for internal notes instead of public replies (defaults to false) + - `isPublic` (boolean, optional): True for public comments, false for internal notes + + + + + **Description:** Search for tickets using various filters and criteria. + + **Parameters:** + - `ticketSubject` (string, optional): Filter by text in ticket subject + - `ticketDescription` (string, optional): Filter by text in ticket description and comments + - `ticketStatus` (string, optional): Filter by status - Options: new, open, pending, hold, solved, closed + - `ticketType` (string, optional): Filter by type - Options: problem, incident, question, task, no_type + - `ticketPriority` (string, optional): Filter by priority - Options: urgent, high, normal, low, no_priority + - `requesterId` (string, optional): Filter by requester user ID + - `assigneeId` (string, optional): Filter by assigned agent ID + - `recipientEmail` (string, optional): Filter by original recipient email address + - `ticketTags` (string, optional): Filter by ticket tags + - `ticketExternalId` (string, optional): Filter by external ID + - `createdDate` (object, optional): Filter by creation date with operator (EQUALS, LESS_THAN_EQUALS, GREATER_THAN_EQUALS) and value + - `updatedDate` (object, optional): Filter by update date with operator and value + - `dueDate` (object, optional): Filter by due date with operator and value + - `sort_by` (string, optional): Sort field - Options: created_at, updated_at, priority, status, ticket_type + - `sort_order` (string, optional): Sort direction - Options: asc, desc + + + + +### **User Management** + + + + **Description:** Create a new user in Zendesk. + + **Parameters:** + - `name` (string, required): User's full name + - `email` (string, optional): User's email address (e.g., "jane@example.com") + - `phone` (string, optional): User's phone number + - `role` (string, optional): User role - Options: admin, agent, end-user + - `externalId` (string, optional): Unique identifier from another system + - `details` (string, optional): Additional user details + - `notes` (string, optional): Internal notes about the user + + + + + **Description:** Update an existing user's information. + + **Parameters:** + - `userId` (string, required): ID of the user to update + - `name` (string, optional): Updated user name + - `email` (string, optional): Updated email (adds as secondary email on update) + - `phone` (string, optional): Updated phone number + - `role` (string, optional): Updated role - Options: admin, agent, end-user + - `externalId` (string, optional): Updated external ID + - `details` (string, optional): Updated user details + - `notes` (string, optional): Updated internal notes + + + + + **Description:** Retrieve a specific user by their ID. + + **Parameters:** + - `userId` (string, required): The user ID to retrieve + + + + + **Description:** Search for users using various criteria. + + **Parameters:** + - `name` (string, optional): Filter by user name + - `email` (string, optional): Filter by user email (e.g., "jane@example.com") + - `role` (string, optional): Filter by role - Options: admin, agent, end-user + - `externalId` (string, optional): Filter by external ID + - `sort_by` (string, optional): Sort field - Options: created_at, updated_at + - `sort_order` (string, optional): Sort direction - Options: asc, desc + + + + +### **Administrative Tools** + + + + **Description:** Retrieve all standard and custom fields available for tickets. + + **Parameters:** + - `paginationParameters` (object, optional): Pagination settings + - `pageCursor` (string, optional): Page cursor for pagination + + + + + **Description:** Get audit records (read-only history) for tickets. + + **Parameters:** + - `ticketId` (string, optional): Get audits for specific ticket (if empty, retrieves audits for all non-archived tickets, e.g., "1234") + - `paginationParameters` (object, optional): Pagination settings + - `pageCursor` (string, optional): Page cursor for pagination + + + + +## Custom Fields + +Custom fields allow you to store additional information specific to your organization: + +```json +[ + { "id": 27642, "value": "745" }, + { "id": 27648, "value": "yes" } +] +``` + +## Ticket Priority Levels + +Understanding priority levels: + +- **urgent** - Critical issues requiring immediate attention +- **high** - Important issues that should be addressed quickly +- **normal** - Standard priority for most tickets +- **low** - Minor issues that can be addressed when convenient + +## Ticket Status Workflow + +Standard ticket status progression: + +- **new** - Recently created, not yet assigned +- **open** - Actively being worked on +- **pending** - Waiting for customer response or external action +- **hold** - Temporarily paused +- **solved** - Issue resolved, awaiting customer confirmation +- **closed** - Ticket completed and closed + +## Usage Examples + +### Basic Zendesk Agent Setup + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Zendesk capabilities +zendesk_agent = Agent( + role="Support Manager", + goal="Manage customer support tickets and provide excellent customer service", + backstory="An AI assistant specialized in customer support operations and ticket management.", + apps=['zendesk'] # All Zendesk actions will be available +) + +# Task to create a new support ticket +create_ticket_task = Task( + description="Create a high-priority support ticket for John Smith who is unable to access his account after password reset", + agent=zendesk_agent, + expected_output="Support ticket created successfully with ticket ID" +) + +# Run the task +crew = Crew( + agents=[zendesk_agent], + tasks=[create_ticket_task] +) + +crew.kickoff() +``` + +### Filtering Specific Zendesk Tools + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Zendesk actions only +support_agent = Agent( + role="Customer Support Agent", + goal="Handle customer inquiries and resolve support issues efficiently", + backstory="An experienced support agent who specializes in ticket resolution and customer communication.", + apps=['zendesk/create_ticket'] # Specific Zendesk actions +) + +# Task to manage support workflow +support_task = Task( + description="Create a ticket for login issues, add troubleshooting comments, and update status to resolved", + agent=support_agent, + expected_output="Support ticket managed through complete resolution workflow" +) + +crew = Crew( + agents=[support_agent], + tasks=[support_task] +) + +crew.kickoff() +``` + +### Advanced Ticket Management + +```python +from crewai import Agent, Task, Crew + +ticket_manager = Agent( + role="Ticket Manager", + goal="Manage support ticket workflows and ensure timely resolution", + backstory="An AI assistant that specializes in support ticket triage and workflow optimization.", + apps=['zendesk'] +) + +# Task to manage ticket lifecycle +ticket_workflow = Task( + description=""" + 1. Create a new support ticket for account access issues + 2. Add internal notes with troubleshooting steps + 3. Update ticket priority based on customer tier + 4. Add resolution comments and close the ticket + """, + agent=ticket_manager, + expected_output="Complete ticket lifecycle managed from creation to resolution" +) + +crew = Crew( + agents=[ticket_manager], + tasks=[ticket_workflow] +) + +crew.kickoff() +``` + +### Support Analytics and Reporting + +```python +from crewai import Agent, Task, Crew + +support_analyst = Agent( + role="Support Analyst", + goal="Analyze support metrics and generate insights for team performance", + backstory="An analytical AI that excels at extracting insights from support data and ticket patterns.", + apps=['zendesk'] +) + +# Complex task involving analytics and reporting +analytics_task = Task( + description=""" + 1. Search for all open tickets from the last 30 days + 2. Analyze ticket resolution times and customer satisfaction + 3. Identify common issues and support patterns + 4. Generate weekly support performance report + """, + agent=support_analyst, + expected_output="Comprehensive support analytics report with performance insights and recommendations" +) + +crew = Crew( + agents=[support_analyst], + tasks=[analytics_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/en/enterprise/introduction.mdx b/docs/v1.15.1/en/enterprise/introduction.mdx new file mode 100644 index 000000000..fa2eba891 --- /dev/null +++ b/docs/v1.15.1/en/enterprise/introduction.mdx @@ -0,0 +1,100 @@ +--- +title: "CrewAI AMP" +description: "Deploy, monitor, and scale your AI agent workflows" +icon: "globe" +mode: "wide" +--- + +## Introduction + +CrewAI AMP(Agent Management Platform) provides a platform for deploying, monitoring, and scaling your crews and agents in a production environment. + + + CrewAI AMP Dashboard + + +CrewAI AMP extends the power of the open-source framework with features designed for production deployments, collaboration, and scalability. Deploy your crews to a managed infrastructure and monitor their execution in real-time. + +## Key Features + + + + Deploy your crews to a managed infrastructure with a few clicks + + + Access your deployed crews via REST API for integration with existing + systems + + + Monitor your crews with detailed execution traces and logs + + + Publish and install tools to enhance your crews' capabilities + + + Stream real-time events and updates to your systems + + + Create and customize crews using a no-code/low-code interface + + + +## Deployment Options + + + + Connect directly to your GitHub repositories to deploy code + + + Deploy crews created through the no-code Crew Studio interface + + + Use the CrewAI CLI for more advanced deployment workflows + + + +## Getting Started + + + + Create your account at [app.crewai.com](https://app.crewai.com) + + Sign Up + + + + Use code or Crew Studio to build your crew + + Build Crew + + + + Deploy your crew to the Enterprise platform + + Deploy Crew + + + + Integrate with your crew via the generated API endpoints + + Use the Crew API + + + + +For detailed instructions, check out our [deployment guide](/en/enterprise/guides/deploy-crew) or click the button below to get started. diff --git a/docs/v1.15.1/en/enterprise/resources/frequently-asked-questions.mdx b/docs/v1.15.1/en/enterprise/resources/frequently-asked-questions.mdx new file mode 100644 index 000000000..ba324b5bb --- /dev/null +++ b/docs/v1.15.1/en/enterprise/resources/frequently-asked-questions.mdx @@ -0,0 +1,152 @@ +--- +title: FAQs +description: "Frequently asked questions about CrewAI AMP" +icon: "circle-question" +mode: "wide" +--- + + + + In the hierarchical process, a manager agent is automatically created and coordinates the workflow, delegating tasks and validating outcomes for streamlined and effective execution. The manager agent utilizes tools to facilitate task delegation and execution by agents under the manager's guidance. The manager LLM is crucial for the hierarchical process and must be set up correctly for proper function. + + + + The most up-to-date documentation for CrewAI is available on our official documentation website: https://docs.crewai.com/ + CrewAI Docs + + + + #### Hierarchical Process: + - Tasks are delegated and executed based on a structured chain of command + - A manager language model (`manager_llm`) must be specified for the manager agent + - Manager agent oversees task execution, planning, delegation, and validation + - Tasks are not pre-assigned; the manager allocates tasks to agents based on their capabilities + + #### Sequential Process: + - Tasks are executed one after another, ensuring tasks are completed in an orderly progression + - Output of one task serves as context for the next + - Task execution follows the predefined order in the task list + + #### Which Process is Better for Complex Projects? + The hierarchical process is better suited for complex projects because it allows for: + - **Dynamic task allocation and delegation**: Manager agent can assign tasks based on agent capabilities + - **Structured validation and oversight**: Manager agent reviews task outputs and ensures completion + - **Complex task management**: Precise control over tool availability at the agent level + + + + - **Adaptive Learning**: Crews become more efficient over time, adapting to new information and refining their approach to tasks + - **Enhanced Personalization**: Memory enables agents to remember user preferences and historical interactions, leading to personalized experiences + - **Improved Problem Solving**: Access to a rich memory store aids agents in making more informed decisions, drawing on past learnings and contextual insights + + + + Setting a maximum RPM limit for an agent prevents the agent from making too many requests to external services, which can help to avoid rate limits and improve performance. + + + + Human input allows agents to request additional information or clarification when necessary. This feature is crucial in complex decision-making processes or when agents require more details to complete a task effectively. + + To integrate human input into agent execution, set the `human_input` flag in the task definition. When enabled, the agent prompts the user for input before delivering its final answer. This input can provide extra context, clarify ambiguities, or validate the agent's output. + + For detailed implementation guidance, see our [Human-in-the-Loop guide](/en/enterprise/guides/human-in-the-loop). + + + + CrewAI provides a range of advanced customization options: + + - **Language Model Customization**: Agents can be customized with specific language models (`llm`) and function-calling language models (`function_calling_llm`) + - **Performance and Debugging Settings**: Adjust an agent's performance and monitor its operations + - **Verbose Mode**: Enables detailed logging of an agent's actions, useful for debugging and optimization + - **RPM Limit**: Sets the maximum number of requests per minute (`max_rpm`) + - **Maximum Iterations**: The `max_iter` attribute allows users to define the maximum number of iterations an agent can perform for a single task + - **Delegation and Autonomy**: Control an agent's ability to delegate or ask questions with the `allow_delegation` attribute (default: True) + - **Human Input Integration**: Agents can request additional information or clarification when necessary + + + + Human input is particularly useful when: + - **Agents require additional information or clarification**: When agents encounter ambiguity or incomplete data + - **Agents need to make complex or sensitive decisions**: Human input can assist in ethical or nuanced decision-making + - **Oversight and validation of agent output**: Human input can help validate results and prevent errors + - **Customizing agent behavior**: Human input can provide feedback to refine agent responses over time + - **Identifying and resolving errors or limitations**: Human input helps address agent capability gaps + + + + The different types of memory available in CrewAI are: + - **Short-term memory**: Temporary storage for immediate context + - **Long-term memory**: Persistent storage for learned patterns and information + - **Entity memory**: Focused storage for specific entities and their attributes + - **Contextual memory**: Memory that maintains context across interactions + + Learn more about the different types of memory: + CrewAI Memory + + + + To use Output Pydantic in a task, you need to define the expected output of the task as a Pydantic model. Here's a quick example: + + + + ```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 + ) + ``` + + + + Here's a tutorial on how to consistently get structured outputs from your agents: + + + + + You can create custom tools by subclassing the `BaseTool` class provided by CrewAI or by using the tool decorator. Subclassing involves defining a new class that inherits from `BaseTool`, specifying the name, description, and the `_run` method for operational logic. The tool decorator allows you to create a `Tool` object directly with the required attributes and a functional logic. + + CrewAI Tools Guide + + + + 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. + + + diff --git a/docs/v1.15.1/en/examples/cookbooks.mdx b/docs/v1.15.1/en/examples/cookbooks.mdx new file mode 100644 index 000000000..1bd7f016d --- /dev/null +++ b/docs/v1.15.1/en/examples/cookbooks.mdx @@ -0,0 +1,49 @@ +--- +title: CrewAI Cookbooks +description: Feature-focused quickstarts and notebooks for learning patterns fast. +icon: book +mode: "wide" +--- + +## Quickstarts & Demos + + + + Coordinate multiple agents on shared tasks. Includes notebook with end-to-end collaboration pattern. + + + + Teach agents to reason about multi-step plans before execution using the planning toolkit. + + + + Explore self-reflection loops, critique prompts, and structured thinking patterns. + + + + + + Apply task-level guardrails with retries, validation functions, and safe fallbacks. + + + + Connect CrewAI to Gemini with search grounding for factual, citation-rich outputs. + + + + Generate video recaps using Gemini multimodal LLM and CrewAI orchestration. + + + + + + View all notebooks and feature demos showcasing specific CrewAI capabilities. + + + Missing a pattern? Drop a request in the community forum and we’ll expand the library. + + + + +Use Cookbooks to learn a pattern quickly, then jump to Full Examples for production‑grade implementations. + diff --git a/docs/v1.15.1/en/examples/example.mdx b/docs/v1.15.1/en/examples/example.mdx new file mode 100644 index 000000000..37672cbfa --- /dev/null +++ b/docs/v1.15.1/en/examples/example.mdx @@ -0,0 +1,86 @@ +--- +title: CrewAI Examples +description: Explore curated examples organized by Crews, Flows, Integrations, and Notebooks. +icon: rocket-launch +mode: "wide" +--- + +## Crews + + + + Multi‑agent marketing campaign planning. + + + Personalized surprise travel planning. + + + CV‑to‑job matching with vector search. + + + Automated job description creation. + + + Multi‑agent team that designs and builds Python games. + + + Candidate sourcing and evaluation. + + + See the full list of crew examples. + + + +## Flows + + + + Multi‑crew content generation with routing. + + + Automated email monitoring and replies. + + + Lead qualification with human‑in‑the‑loop. + + + Notes processing with integrations. + + + Iterative self‑improvement workflows. + + + Parallel chapter generation. + + + See the full list of flow examples. + + + +## Integrations + + + + Integration with LangGraph framework. + + + Using CrewAI with Azure OpenAI. + + + NVIDIA ecosystem integrations. + + + See all integration examples. + + + +## Notebooks + + + + Simple QA Crew + Flow. + + + Interactive examples for learning and experimentation. + + diff --git a/docs/v1.15.1/en/guides/advanced/customizing-prompts.mdx b/docs/v1.15.1/en/guides/advanced/customizing-prompts.mdx new file mode 100644 index 000000000..00132b5b1 --- /dev/null +++ b/docs/v1.15.1/en/guides/advanced/customizing-prompts.mdx @@ -0,0 +1,331 @@ +--- +title: Customizing Prompts +description: Dive deeper into low-level prompt customization for CrewAI, enabling super custom and complex use cases for different models and languages. +icon: message-pen +mode: "wide" +--- + +## Why Customize Prompts? + +Although CrewAI's default prompts work well for many scenarios, low-level customization opens the door to significantly more flexible and powerful agent behavior. Here's why you might want to take advantage of this deeper control: + +1. **Optimize for specific LLMs** – Different models (such as GPT-4, Claude, or Llama) thrive with prompt formats tailored to their unique architectures. +2. **Change the language** – Build agents that operate exclusively in languages beyond English, handling nuances with precision. +3. **Specialize for complex domains** – Adapt prompts for highly specialized industries like healthcare, finance, or legal. +4. **Adjust tone and style** – Make agents more formal, casual, creative, or analytical. +5. **Support super custom use cases** – Utilize advanced prompt structures and formatting to meet intricate, project-specific requirements. + +This guide explores how to tap into CrewAI's prompts at a lower level, giving you fine-grained control over how agents think and interact. + +## Understanding CrewAI's Prompt System + +Under the hood, CrewAI employs a modular prompt system that you can customize extensively: + +- **Agent templates** – Govern each agent's approach to their assigned role. +- **Prompt slices** – Control specialized behaviors such as tasks, tool usage, and output structure. +- **Error handling** – Direct how agents respond to failures, exceptions, or timeouts. +- **Tool-specific prompts** – Define detailed instructions for how tools are invoked or utilized. + +Check out the [original prompt templates in CrewAI's repository](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) to see how these elements are organized. From there, you can override or adapt them as needed to unlock advanced behaviors. + +## Understanding Default System Instructions + + +**Production Transparency Issue**: CrewAI automatically injects default instructions into your prompts that you might not be aware of. This section explains what's happening under the hood and how to gain full control. + + +When you define an agent with `role`, `goal`, and `backstory`, CrewAI automatically adds additional system instructions that control formatting and behavior. Understanding these default injections is crucial for production systems where you need full prompt transparency. + +### What CrewAI Automatically Injects + +Based on your agent configuration, CrewAI adds different default instructions: + +#### For Agents Without Tools +```text +"I MUST use these formats, my job depends on it!" +``` + +#### For Agents With Tools +```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... +``` + +#### For Structured Outputs (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." +``` + +### Viewing the Complete System Prompt + +To see exactly what prompt is being sent to your LLM, you can inspect the generated prompt: + +```python +from crewai import Agent, Crew, Task +from crewai.utilities.prompts import Prompts + +# Create your agent +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 +) + +# Create a sample task +task = Task( + description="Analyze the sales data and identify trends", + expected_output="A detailed analysis with key insights and trends", + agent=agent +) + +# Create the prompt generator +prompt_generator = Prompts( + agent=agent, + has_tools=len(agent.tools) > 0, + use_system_prompt=agent.use_system_prompt +) + +# Generate and inspect the actual prompt +generated_prompt = prompt_generator.task_execution() + +# Print the complete system prompt that will be sent to the 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"]) + +# You can also see how the task description gets formatted +print("\n=== TASK CONTEXT ===") +print(f"Task Description: {task.description}") +print(f"Expected Output: {task.expected_output}") +``` + +### Overriding Default Instructions + +You have several options to gain full control over the prompts: + +#### Option 1: Custom Templates (Recommended) +```python +from crewai import Agent + +# Define your own system template without default instructions +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 separate system/user messages +) +``` + +#### Option 2: Custom Prompt File +Create a `custom_prompts.json` file to override specific prompt slices: + +```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}" + } +} +``` + +Then use it in your crew: + +```python +crew = Crew( + agents=[agent], + tasks=[task], + prompt_file="custom_prompts.json", + verbose=True +) +``` + + +`agent.i18n` is maintained only for backward compatibility and is deprecated. For runtime prompt customization, pass `prompt_file` to `Crew`. For programmatic access to prompt slices, use the i18n utility directly: + + +```python +from crewai.utilities.i18n import get_i18n + +i18n = get_i18n("custom_prompts.json") +format_slice = i18n.slice("format") +tool_prompt = i18n.tools("ask_question") +``` + +#### Option 3: Disable System Prompts for o1 Models +```python +agent = Agent( + role="Analyst", + goal="Analyze data", + backstory="Expert analyst", + use_system_prompt=False # Disables system prompt separation +) +``` + +### Debugging with Observability Tools + +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](/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](/en/observability/overview)) +4. **Test with different LLMs** as default instructions may work differently across models +5. **Document your prompt customizations** for team transparency + + +The default instructions exist to ensure consistent agent behavior, but they can interfere with domain-specific requirements. Use the customization options above to maintain full control over your agent's behavior in production systems. + + +## Best Practices for Managing Prompt Files + +When engaging in low-level prompt customization, follow these guidelines to keep things organized and maintainable: + +1. **Keep files separate** – Store your customized prompts in dedicated JSON files outside your main codebase. +2. **Version control** – Track changes within your repository, ensuring clear documentation of prompt adjustments over time. +3. **Organize by model or language** – Use naming schemes like `prompts_llama.json` or `prompts_es.json` to quickly identify specialized configurations. +4. **Document changes** – Provide comments or maintain a README detailing the purpose and scope of your customizations. +5. **Minimize alterations** – Only override the specific slices you genuinely need to adjust, keeping default functionality intact for everything else. + +## The Simplest Way to Customize Prompts + +One straightforward approach is to create a JSON file for the prompts you want to override and then point your Crew at that file: + +1. Craft a JSON file with your updated prompt slices. +2. Reference that file via the `prompt_file` parameter in your Crew. + +CrewAI then merges your customizations with the defaults, so you don't have to redefine every prompt. Here's how: + +For code that needs to read prompt slices directly, use `crewai.utilities.i18n.get_i18n()` with the same prompt file instead of reading `agent.i18n`. + +### Example: Basic Prompt Customization + +Create a `custom_prompts.json` file with the prompts you want to modify. Ensure you list all top-level prompts it should contain, not just your changes: + +```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" + } +} +``` + +Then integrate it like so: + +```python +from crewai import Agent, Crew, Task, Process + +# Create agents and tasks as normal +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 +) + +# Create a crew with your custom prompt file +crew = Crew( + agents=[researcher], + tasks=[research_task], + prompt_file="path/to/custom_prompts.json", + verbose=True +) + +# Run the crew +result = crew.kickoff() +``` + +With these few edits, you gain low-level control over how your agents communicate and solve tasks. + +## Optimizing for Specific Models + +Different models thrive on differently structured prompts. Making deeper adjustments can significantly boost performance by aligning your prompts with a model's nuances. + +### Example: Llama 3.3 Prompting Template + +For instance, when dealing with Meta's Llama 3.3, deeper-level customization may reflect the recommended structure described at: +https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template + +Here's an example to highlight how you might fine-tune an Agent to leverage Llama 3.3 in code: + +```python +from crewai import Agent, Crew, Task, Process +from crewai_tools import DirectoryReadTool, FileReadTool + +# Define templates for system, user (prompt), and assistant (response) messages +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|>""" + +# Create an Agent using Llama-specific layouts +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", # Using the Llama 3 model + system_template=system_template, + prompt_template=prompt_template, + response_template=response_template, + tools=[DirectoryReadTool(), FileReadTool()] +) + +# Define a sample task +engineering_task = Task( + description="Review AI implementation files for potential improvements", + expected_output="A summary of key findings and recommendations", + agent=principal_engineer +) + +# Create a Crew for the task +llama_crew = Crew( + agents=[principal_engineer], + tasks=[engineering_task], + process=Process.sequential, + verbose=True +) + +# Execute the crew +result = llama_crew.kickoff() +print(result.raw) +``` + +Through this deeper configuration, you can exercise comprehensive, low-level control over your Llama-based workflows without needing a separate JSON file. + +## Conclusion + +Low-level prompt customization in CrewAI opens the door to super custom, complex use cases. By establishing well-organized prompt files (or direct inline templates), you can accommodate various models, languages, and specialized domains. This level of flexibility ensures you can craft precisely the AI behavior you need, all while knowing CrewAI still provides reliable defaults when you don't override them. + + +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. + diff --git a/docs/v1.15.1/en/guides/advanced/fingerprinting.mdx b/docs/v1.15.1/en/guides/advanced/fingerprinting.mdx new file mode 100644 index 000000000..b6bd7ec02 --- /dev/null +++ b/docs/v1.15.1/en/guides/advanced/fingerprinting.mdx @@ -0,0 +1,134 @@ +--- +title: Fingerprinting +description: Learn how to use CrewAI's fingerprinting system to uniquely identify and track components throughout their lifecycle. +icon: fingerprint +mode: "wide" +--- + +## Overview + +Fingerprints in CrewAI provide a way to uniquely identify and track components throughout their lifecycle. Each `Agent`, `Crew`, and `Task` automatically receives a unique fingerprint when created, which cannot be manually overridden. + +These fingerprints can be used for: +- Auditing and tracking component usage +- Ensuring component identity integrity +- Attaching metadata to components +- Creating a traceable chain of operations + +## How Fingerprints Work + +A fingerprint is an instance of the `Fingerprint` class from the `crewai.security` module. Each fingerprint contains: + +- A UUID string: A unique identifier for the component that is automatically generated and cannot be manually set +- A creation timestamp: When the fingerprint was generated, automatically set and cannot be manually modified +- Metadata: A dictionary of additional information that can be customized + +Fingerprints are automatically generated and assigned when a component is created. Each component exposes its fingerprint through a read-only property. + +## Basic Usage + +### Accessing Fingerprints + +```python +from crewai import Agent, Crew, Task + +# Create components - fingerprints are automatically generated +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 +) + +# Access the fingerprints +agent_fingerprint = agent.fingerprint +crew_fingerprint = crew.fingerprint +task_fingerprint = task.fingerprint + +# Print the UUID strings +print(f"Agent fingerprint: {agent_fingerprint.uuid_str}") +print(f"Crew fingerprint: {crew_fingerprint.uuid_str}") +print(f"Task fingerprint: {task_fingerprint.uuid_str}") +``` + +### Working with Fingerprint Metadata + +You can add metadata to fingerprints for additional context: + +```python +# Add metadata to the agent's fingerprint +agent.security_config.fingerprint.metadata = { + "version": "1.0", + "department": "Data Science", + "project": "Customer Analysis" +} + +# Access the metadata +print(f"Agent metadata: {agent.fingerprint.metadata}") +``` + +## Fingerprint Persistence + +Fingerprints are designed to persist and remain unchanged throughout a component's lifecycle. If you modify a component, the fingerprint remains the same: + +```python +original_fingerprint = agent.fingerprint.uuid_str + +# Modify the agent +agent.goal = "New goal for analysis" + +# The fingerprint remains unchanged +assert agent.fingerprint.uuid_str == original_fingerprint +``` + +## Deterministic Fingerprints + +While you cannot directly set the UUID and creation timestamp, you can create deterministic fingerprints using the `generate` method with a seed: + +```python +from crewai.security import Fingerprint + +# Create a deterministic fingerprint using a seed string +deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id") + +# The same seed always produces the same fingerprint +same_fingerprint = Fingerprint.generate(seed="my-agent-id") +assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str + +# You can also set metadata +custom_fingerprint = Fingerprint.generate( + seed="my-agent-id", + metadata={"version": "1.0"} +) +``` + +## Advanced Usage + +### Fingerprint Structure + +Each fingerprint has the following structure: + +```python +from crewai.security import Fingerprint + +fingerprint = agent.fingerprint + +# UUID string - the unique identifier (auto-generated) +uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000" + +# Creation timestamp (auto-generated) +created_at = fingerprint.created_at # A datetime object + +# Metadata - for additional information (can be customized) +metadata = fingerprint.metadata # A dictionary, defaults to {} +``` \ No newline at end of file diff --git a/docs/v1.15.1/en/guides/agents/crafting-effective-agents.mdx b/docs/v1.15.1/en/guides/agents/crafting-effective-agents.mdx new file mode 100644 index 000000000..c0141ddac --- /dev/null +++ b/docs/v1.15.1/en/guides/agents/crafting-effective-agents.mdx @@ -0,0 +1,453 @@ +--- +title: Crafting Effective Agents +description: Learn best practices for designing powerful, specialized AI agents that collaborate effectively to solve complex problems. +icon: robot +mode: "wide" +--- + +## The Art and Science of Agent Design + +At the heart of CrewAI lies the agent - a specialized AI entity designed to perform specific roles within a collaborative framework. While creating basic agents is simple, crafting truly effective agents that produce exceptional results requires understanding key design principles and best practices. + +This guide will help you master the art of agent design, enabling you to create specialized AI personas that collaborate effectively, think critically, and produce high-quality outputs tailored to your specific needs. + +### Why Agent Design Matters + +The way you define your agents significantly impacts: + +1. **Output quality**: Well-designed agents produce more relevant, high-quality results +2. **Collaboration effectiveness**: Agents with complementary skills work together more efficiently +3. **Task performance**: Agents with clear roles and goals execute tasks more effectively +4. **System scalability**: Thoughtfully designed agents can be reused across multiple crews and contexts + +Let's explore best practices for creating agents that excel in these dimensions. + +## The 80/20 Rule: Focus on Tasks Over Agents + +When building effective AI systems, remember this crucial principle: **80% of your effort should go into designing tasks, and only 20% into defining agents**. + +Why? Because even the most perfectly defined agent will fail with poorly designed tasks, but well-designed tasks can elevate even a simple agent. This means: + +- Spend most of your time writing clear task instructions +- Define detailed inputs and expected outputs +- Add examples and context to guide execution +- Dedicate the remaining time to agent role, goal, and backstory + +This doesn't mean agent design isn't important - it absolutely is. But task design is where most execution failures occur, so prioritize accordingly. + +## Core Principles of Effective Agent Design + +### 1. The Role-Goal-Backstory Framework + +The most powerful agents in CrewAI are built on a strong foundation of three key elements: + +#### Role: The Agent's Specialized Function + +The role defines what the agent does and their area of expertise. When crafting roles: + +- **Be specific and specialized**: Instead of "Writer," use "Technical Documentation Specialist" or "Creative Storyteller" +- **Align with real-world professions**: Base roles on recognizable professional archetypes +- **Include domain expertise**: Specify the agent's field of knowledge (e.g., "Financial Analyst specializing in market trends") + +**Examples of effective roles:** +```yaml +role: "Senior UX Researcher specializing in user interview analysis" +role: "Full-Stack Software Architect with expertise in distributed systems" +role: "Corporate Communications Director specializing in crisis management" +``` + +#### Goal: The Agent's Purpose and Motivation + +The goal directs the agent's efforts and shapes their decision-making process. Effective goals should: + +- **Be clear and outcome-focused**: Define what the agent is trying to achieve +- **Emphasize quality standards**: Include expectations about the quality of work +- **Incorporate success criteria**: Help the agent understand what "good" looks like + +**Examples of effective goals:** +```yaml +goal: "Uncover actionable user insights by analyzing interview data and identifying recurring patterns, unmet needs, and improvement opportunities" +goal: "Design robust, scalable system architectures that balance performance, maintainability, and cost-effectiveness" +goal: "Craft clear, empathetic crisis communications that address stakeholder concerns while protecting organizational reputation" +``` + +#### Backstory: The Agent's Experience and Perspective + +The backstory gives depth to the agent, influencing how they approach problems and interact with others. Good backstories: + +- **Establish expertise and experience**: Explain how the agent gained their skills +- **Define working style and values**: Describe how the agent approaches their work +- **Create a cohesive persona**: Ensure all elements of the backstory align with the role and goal + +**Examples of effective backstories:** +```yaml +backstory: "You have spent 15 years conducting and analyzing user research for top tech companies. You have a talent for reading between the lines and identifying patterns that others miss. You believe that good UX is invisible and that the best insights come from listening to what users don't say as much as what they do say." + +backstory: "With 20+ years of experience building distributed systems at scale, you've developed a pragmatic approach to software architecture. You've seen both successful and failed systems and have learned valuable lessons from each. You balance theoretical best practices with practical constraints and always consider the maintenance and operational aspects of your designs." + +backstory: "As a seasoned communications professional who has guided multiple organizations through high-profile crises, you understand the importance of transparency, speed, and empathy in crisis response. You have a methodical approach to crafting messages that address concerns while maintaining organizational credibility." +``` + +### 2. Specialists Over Generalists + +Agents perform significantly better when given specialized roles rather than general ones. A highly focused agent delivers more precise, relevant outputs: + +**Generic (Less Effective):** +```yaml +role: "Writer" +``` + +**Specialized (More Effective):** +```yaml +role: "Technical Blog Writer specializing in explaining complex AI concepts to non-technical audiences" +``` + +**Specialist Benefits:** +- Clearer understanding of expected output +- More consistent performance +- Better alignment with specific tasks +- Improved ability to make domain-specific judgments + +### 3. Balancing Specialization and Versatility + +Effective agents strike the right balance between specialization (doing one thing extremely well) and versatility (being adaptable to various situations): + +- **Specialize in role, versatile in application**: Create agents with specialized skills that can be applied across multiple contexts +- **Avoid overly narrow definitions**: Ensure agents can handle variations within their domain of expertise +- **Consider the collaborative context**: Design agents whose specializations complement the other agents they'll work with + +### 4. Setting Appropriate Expertise Levels + +The expertise level you assign to your agent shapes how they approach tasks: + +- **Novice agents**: Good for straightforward tasks, brainstorming, or initial drafts +- **Intermediate agents**: Suitable for most standard tasks with reliable execution +- **Expert agents**: Best for complex, specialized tasks requiring depth and nuance +- **World-class agents**: Reserved for critical tasks where exceptional quality is needed + +Choose the appropriate expertise level based on task complexity and quality requirements. For most collaborative crews, a mix of expertise levels often works best, with higher expertise assigned to core specialized functions. + +## Practical Examples: Before and After + +Let's look at some examples of agent definitions before and after applying these best practices: + +### Example 1: Content Creation Agent + +**Before:** +```yaml +role: "Writer" +goal: "Write good content" +backstory: "You are a writer who creates content for websites." +``` + +**After:** +```yaml +role: "B2B Technology Content Strategist" +goal: "Create compelling, technically accurate content that explains complex topics in accessible language while driving reader engagement and supporting business objectives" +backstory: "You have spent a decade creating content for leading technology companies, specializing in translating technical concepts for business audiences. You excel at research, interviewing subject matter experts, and structuring information for maximum clarity and impact. You believe that the best B2B content educates first and sells second, building trust through genuine expertise rather than marketing hype." +``` + +### Example 2: Research Agent + +**Before:** +```yaml +role: "Researcher" +goal: "Find information" +backstory: "You are good at finding information online." +``` + +**After:** +```yaml +role: "Academic Research Specialist in Emerging Technologies" +goal: "Discover and synthesize cutting-edge research, identifying key trends, methodologies, and findings while evaluating the quality and reliability of sources" +backstory: "With a background in both computer science and library science, you've mastered the art of digital research. You've worked with research teams at prestigious universities and know how to navigate academic databases, evaluate research quality, and synthesize findings across disciplines. You're methodical in your approach, always cross-referencing information and tracing claims to primary sources before drawing conclusions." +``` + +## Crafting Effective Tasks for Your Agents + +While agent design is important, task design is critical for successful execution. Here are best practices for designing tasks that set your agents up for success: + +### The Anatomy of an Effective Task + +A well-designed task has two key components that serve different purposes: + +#### Task Description: The Process +The description should focus on what to do and how to do it, including: +- Detailed instructions for execution +- Context and background information +- Scope and constraints +- Process steps to follow + +#### Expected Output: The Deliverable +The expected output should define what the final result should look like: +- Format specifications (markdown, JSON, etc.) +- Structure requirements +- Quality criteria +- Examples of good outputs (when possible) + +### Task Design Best Practices + +#### 1. Single Purpose, Single Output +Tasks perform best when focused on one clear objective: + +**Bad Example (Too Broad):** +```yaml +task_description: "Research market trends, analyze the data, and create a visualization." +``` + +**Good Example (Focused):** +```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. Be Explicit About Inputs and Outputs +Always clearly specify what inputs the task will use and what the output should look like: + +**Example:** +```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. Include Purpose and Context +Explain why the task matters and how it fits into the larger workflow: + +**Example:** +```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 Structured Output Tools +For machine-readable outputs, specify the format clearly: + +**Example:** +```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." +``` + +## Common Mistakes to Avoid + +Based on lessons learned from real-world implementations, here are the most common pitfalls in agent and task design: + +### 1. Unclear Task Instructions + +**Problem:** Tasks lack sufficient detail, making it difficult for agents to execute effectively. + +**Example of Poor Design:** +```yaml +research_task: + description: "Research AI trends." + expected_output: "A report on AI trends." +``` + +**Improved Version:** +```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. "God Tasks" That Try to Do Too Much + +**Problem:** Tasks that combine multiple complex operations into one instruction set. + +**Example of Poor Design:** +```yaml +comprehensive_task: + description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline." +``` + +**Improved Version:** +Break this into sequential, focused tasks: +```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. Misaligned Description and Expected Output + +**Problem:** The task description asks for one thing while the expected output specifies something different. + +**Example of Poor Design:** +```yaml +analysis_task: + description: "Analyze customer feedback to find areas of improvement." + expected_output: "A marketing plan for the next quarter." +``` + +**Improved Version:** +```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. Not Understanding the Process Yourself + +**Problem:** Asking agents to execute tasks that you yourself don't fully understand. + +**Solution:** +1. Try to perform the task manually first +2. Document your process, decision points, and information sources +3. Use this documentation as the basis for your task description + +### 5. Premature Use of Hierarchical Structures + +**Problem:** Creating unnecessarily complex agent hierarchies where sequential processes would work better. + +**Solution:** Start with sequential processes and only move to hierarchical models when the workflow complexity truly requires it. + +### 6. Vague or Generic Agent Definitions + +**Problem:** Generic agent definitions lead to generic outputs. + +**Example of Poor Design:** +```yaml +agent: + role: "Business Analyst" + goal: "Analyze business data" + backstory: "You are good at business analysis." +``` + +**Improved Version:** +```yaml +agent: + role: "SaaS Metrics Specialist focusing on growth-stage startups" + goal: "Identify actionable insights from business data that can directly impact customer retention and revenue growth" + backstory: "With 10+ years analyzing SaaS business models, you've developed a keen eye for the metrics that truly matter for sustainable growth. You've helped numerous companies identify the leverage points that turned around their business trajectory. You believe in connecting data to specific, actionable recommendations rather than general observations." +``` + +## Advanced Agent Design Strategies + +### Designing for Collaboration + +When creating agents that will work together in a crew, consider: + +- **Complementary skills**: Design agents with distinct but complementary abilities +- **Handoff points**: Define clear interfaces for how work passes between agents +- **Constructive tension**: Sometimes, creating agents with slightly different perspectives can lead to better outcomes through productive dialogue + +For example, a content creation crew might include: + +```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..." +``` + +### Creating Specialized Tool Users + +Some agents can be designed specifically to leverage certain tools effectively: + +```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] +``` + +### Tailoring Agents to LLM Capabilities + +Different LLMs have different strengths. Design your agents with these capabilities in mind: + +```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 +``` + +## Testing and Iterating on Agent Design + +Agent design is often an iterative process. Here's a practical approach: + +1. **Start with a prototype**: Create an initial agent definition +2. **Test with sample tasks**: Evaluate performance on representative tasks +3. **Analyze outputs**: Identify strengths and weaknesses +4. **Refine the definition**: Adjust role, goal, and backstory based on observations +5. **Test in collaboration**: Evaluate how the agent performs in a crew setting + +## Conclusion + +Crafting effective agents is both an art and a science. By carefully defining roles, goals, and backstories that align with your specific needs, and combining them with well-designed tasks, you can create specialized AI collaborators that produce exceptional results. + +Remember that agent and task design is an iterative process. Start with these best practices, observe your agents in action, and refine your approach based on what you learn. And always keep in mind the 80/20 rule - focus most of your effort on creating clear, focused tasks to get the best results from your agents. + + +Congratulations! You now understand the principles and practices of effective agent design. Apply these techniques to create powerful, specialized agents that work together seamlessly to accomplish complex tasks. + + +## Next Steps + +- Experiment with different agent configurations for your specific use case +- 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/v1.15.1/en/guides/coding-tools/agents-md.mdx b/docs/v1.15.1/en/guides/coding-tools/agents-md.mdx new file mode 100644 index 000000000..ea238c314 --- /dev/null +++ b/docs/v1.15.1/en/guides/coding-tools/agents-md.mdx @@ -0,0 +1,61 @@ +--- +title: Coding Tools +description: Use AGENTS.md to guide coding agents and IDEs across your CrewAI projects. +icon: terminal +mode: "wide" +--- + +## Why AGENTS.md + +`AGENTS.md` is a lightweight, repo-local instruction file that gives coding agents consistent, project-specific guidance. Keep it in the project root and treat it as the source of truth for how you want assistants to work: conventions, commands, architecture notes, and guardrails. + +## Create a Project with the CLI + +Use the CrewAI CLI to scaffold a project, then `AGENTS.md` will be automatically added at the root. + +```bash +# Crew +crewai create crew my_crew + +# Flow +crewai create flow my_flow + +# Tool repository +crewai tool create my_tool +``` + +## Tool Setup: Point Assistants to AGENTS.md + +### Codex + +Codex can be guided by `AGENTS.md` files placed in your repository. Use them to supply persistent project context such as conventions, commands, and workflow expectations. + +### Claude Code + +Claude Code stores project memory in `CLAUDE.md`. You can bootstrap it with `/init` and edit it using `/memory`. Claude Code also supports imports inside `CLAUDE.md`, so you can add a single line like `@AGENTS.md` to pull in the shared instructions without duplicating them. + +You can simply use: + +```bash +mv AGENTS.md CLAUDE.md +``` + +### Gemini CLI and Google Antigravity + +Gemini CLI and Antigravity load a project context file (default: `GEMINI.md`) from the repo root and parent directories. You can configure it to read `AGENTS.md` instead (or in addition) by setting `context.fileName` in your Gemini CLI settings. For example, set it to `AGENTS.md` only, or include both `AGENTS.md` and `GEMINI.md` if you want to keep each tool’s format. + +You can simply use: + +```bash +mv AGENTS.md GEMINI.md +``` + +### Cursor + +Cursor supports `AGENTS.md` as a project instruction file. Place it at the project root to provide guidance for Cursor’s coding assistant. + +### Windsurf + +Claude Code provides an official integration with Windsurf. If you use Claude Code inside Windsurf, follow the Claude Code guidance above and import `AGENTS.md` from `CLAUDE.md`. + +If you are using Windsurf’s native assistant, configure its project rules or instructions feature (if available) to read from `AGENTS.md` or paste the contents directly. diff --git a/docs/v1.15.1/en/guides/coding-tools/build-with-ai.mdx b/docs/v1.15.1/en/guides/coding-tools/build-with-ai.mdx new file mode 100644 index 000000000..9263628ea --- /dev/null +++ b/docs/v1.15.1/en/guides/coding-tools/build-with-ai.mdx @@ -0,0 +1,214 @@ +--- +title: "Build with AI" +description: "Everything AI coding agents need to build, deploy, and scale with CrewAI — skills, machine-readable docs, deployment, and enterprise features." +icon: robot +mode: "wide" +--- + +# Build with AI + +CrewAI is AI-native. This page brings together everything an AI coding agent needs to build with CrewAI — whether you're Claude Code, Codex, Cursor, Gemini CLI, or any other assistant helping a developer ship crews and flows. + +### Supported Coding Agents + + + + + + + + + + + This page is designed to be consumed by both humans and AI assistants. If you're a coding agent, start with **Skills** to get CrewAI context, then use **llms.txt** for full docs access. + + +--- + +## 1. Skills — Teach Your Agent CrewAI + +**Skills** are instruction packs that give coding agents deep CrewAI knowledge — how to scaffold Flows, configure Crews, use tools, and follow framework conventions. + + + + Anthropic + CrewAI skills are available in the **Claude Code plugin marketplace** — the same distribution channel used by top AI-native companies: + ```shell + /plugin marketplace add crewAIInc/skills + /plugin install crewai-skills@crewai-plugins + /reload-plugins + ``` + + Four skills activate automatically when you ask relevant CrewAI questions: + + | Skill | When it runs | + |-------|--------------| + | `getting-started` | Scaffolding new projects, choosing between `LLM.call()` / `Agent` / `Crew` / `Flow`, wiring `crew.jsonc` / `main.py` | + | `design-agent` | Configuring agents — role, goal, backstory, tools, LLMs, memory, guardrails | + | `design-task` | Writing task descriptions, dependencies, structured output (`output_pydantic`, `output_json`), human review | + | `ask-docs` | Querying the live [CrewAI docs MCP server](https://docs.crewai.com/mcp) for up-to-date API details | + + + Works with Claude Code, Codex, Cursor, Gemini CLI, or any coding agent: + ```shell + npx skills add crewaiinc/skills + ``` + Pulls from the [skills.sh registry](https://skills.sh/crewaiinc/skills). + + + + + + Use either method above — the Claude Code plugin marketplace or `npx skills add`. Both install the official [crewAIInc/skills](https://github.com/crewAIInc/skills) pack. + + + The skill pack teaches your agent: + - **Flows** — stateful apps, steps, and crew kickoffs + - **Crews & Agents** — JSON-first patterns (`crew.jsonc`, `agents/*.jsonc`), roles, tasks, delegation + - **Tools & Integrations** — search, APIs, MCP servers, and common CrewAI tools + - **Project layout** — CLI scaffolds and repo conventions + - **Up-to-date patterns** — tracks current CrewAI docs and best practices + + + Your agent can now scaffold and build CrewAI projects without you re-explaining the framework each session. + + + + + + How skills work in CrewAI agents — injection, activation, and patterns. + + + Overview of the crewAIInc/skills pack and what it includes. + + + Set up AGENTS.md for Claude Code, Codex, Cursor, and Gemini CLI. + + + Official listing — skills, install stats, and audits. + + + +--- + +## 2. llms.txt — Machine-Readable Docs + +CrewAI publishes an `llms.txt` file that gives AI assistants direct access to the full documentation in a machine-readable format. + +``` +https://docs.crewai.com/llms.txt +``` + + + + [`llms.txt`](https://llmstxt.org/) is an emerging standard for making documentation consumable by large language models. Instead of scraping HTML, your agent can fetch a single structured text file with all the content it needs. + + CrewAI's `llms.txt` is **already live** — your agent can use it right now. + + + Point your coding agent at the URL when it needs CrewAI reference docs: + + ``` + Fetch https://docs.crewai.com/llms.txt for CrewAI documentation. + ``` + + Many coding agents (Claude Code, Cursor, etc.) can fetch URLs directly. The file contains structured documentation covering all CrewAI concepts, APIs, and guides. + + + - **No scraping required** — clean, structured content in one request + - **Always up-to-date** — served directly from docs.crewai.com + - **Optimized for LLMs** — formatted for context windows, not browsers + - **Complements skills** — skills teach patterns, llms.txt provides reference + + + +--- + +## 3. Deploy to Enterprise + +Go from a local crew to production on **CrewAI AMP** (Agent Management Platform) in minutes. + + + + Scaffold and test your crew or flow: + ```bash + crewai create crew my_crew + cd my_crew + crewai run + ``` + + + Ensure your project structure is ready: + ```bash + crewai deploy --prepare + ``` + See the [preparation guide](/en/enterprise/guides/prepare-for-deployment) for details on project structure and requirements. + + + Push to the CrewAI AMP platform: + ```bash + crewai deploy + ``` + You can also deploy via [GitHub integration](/en/enterprise/guides/deploy-to-amp) or [Crew Studio](/en/enterprise/guides/enable-crew-studio). + + + Your deployed crew gets a REST API endpoint. Integrate it into any application: + ```bash + curl -X POST https://app.crewai.com/api/v1/crews//kickoff \ + -H "Authorization: Bearer $CREWAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"inputs": {"topic": "AI agents"}}' + ``` + + + + + + Full deployment guide — CLI, GitHub, and Crew Studio methods. + + + Platform overview — what AMP provides for production crews. + + + +--- + +## 4. Enterprise Features + +CrewAI AMP is built for production teams. Here's what you get beyond deployment. + + + + Detailed execution traces, logs, and performance metrics for every crew run. Monitor agent decisions, tool calls, and task completion in real time. + + + No-code/low-code interface to create, customize, and deploy crews visually — then export to code or deploy directly. + + + Stream real-time events from crew executions to your systems. Integrate with Slack, Zapier, or any webhook consumer. + + + SSO, RBAC, and organization-level controls. Manage who can create, deploy, and access crews across your team. + + + Publish and share custom tools across your organization. Install community tools from the registry. + + + Run CrewAI AMP on your own infrastructure. Full platform capabilities with data residency and compliance controls. + + + + + + AMP is for teams that need to move AI agent workflows from prototypes to production — with observability, access controls, and scalable infrastructure. Whether you're a startup or enterprise, AMP handles the operational complexity so you can focus on building agents. + + + - **Cloud (app.crewai.com)** — managed by CrewAI, fastest path to production + - **Factory (self-hosted)** — run on your own infrastructure for full data control + - **Hybrid** — mix cloud and self-hosted based on sensitivity requirements + + + + + Sign up and deploy your first crew to production. + diff --git a/docs/v1.15.1/en/guides/concepts/evaluating-use-cases.mdx b/docs/v1.15.1/en/guides/concepts/evaluating-use-cases.mdx new file mode 100644 index 000000000..186afa2c6 --- /dev/null +++ b/docs/v1.15.1/en/guides/concepts/evaluating-use-cases.mdx @@ -0,0 +1,504 @@ +--- +title: Evaluating Use Cases for CrewAI +description: Learn how to assess your AI application needs and choose the right approach between Crews and Flows based on complexity and precision requirements. +icon: scale-balanced +mode: "wide" +--- + +## Understanding the Decision Framework + +When building AI applications with CrewAI, one of the most important decisions you'll make is choosing the right approach for your specific use case. Should you use a Crew? A Flow? A combination of both? This guide will help you evaluate your requirements and make informed architectural decisions. + +At the heart of this decision is understanding the relationship between **complexity** and **precision** in your application: + + + 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. + +## The Complexity-Precision Matrix Explained + +### What is Complexity? + +In the context of CrewAI applications, **complexity** refers to: + +- The number of distinct steps or operations required +- The diversity of tasks that need to be performed +- The interdependencies between different components +- The need for conditional logic and branching +- The sophistication of the overall workflow + +### What is Precision? + +**Precision** in this context refers to: + +- The accuracy required in the final output +- The need for structured, predictable results +- The importance of reproducibility +- The level of control needed over each step +- The tolerance for variation in outputs + +### The Four Quadrants + +#### 1. Low Complexity, Low Precision + +**Characteristics:** +- Simple, straightforward tasks +- Tolerance for some variation in outputs +- Limited number of steps +- Creative or exploratory applications + +**Recommended Approach:** Simple Crews with minimal agents + +**Example Use Cases:** +- Basic content generation +- Idea brainstorming +- Simple summarization tasks +- Creative writing assistance + +#### 2. Low Complexity, High Precision + +**Characteristics:** +- Simple workflows that require exact, structured outputs +- Need for reproducible results +- Limited steps but high accuracy requirements +- Often involves data processing or transformation + +**Recommended Approach:** Flows with direct LLM calls or simple Crews with structured outputs + +**Example Use Cases:** +- Data extraction and transformation +- Form filling and validation +- Structured content generation (JSON, XML) +- Simple classification tasks + +#### 3. High Complexity, Low Precision + +**Characteristics:** +- Multi-stage processes with many steps +- Creative or exploratory outputs +- Complex interactions between components +- Tolerance for variation in final results + +**Recommended Approach:** Complex Crews with multiple specialized agents + +**Example Use Cases:** +- Research and analysis +- Content creation pipelines +- Exploratory data analysis +- Creative problem-solving + +#### 4. High Complexity, High Precision + +**Characteristics:** +- Complex workflows requiring structured outputs +- Multiple interdependent steps with strict accuracy requirements +- Need for both sophisticated processing and precise results +- Often mission-critical applications + +**Recommended Approach:** Flows orchestrating multiple Crews with validation steps + +**Example Use Cases:** +- Enterprise decision support systems +- Complex data processing pipelines +- Multi-stage document processing +- Regulated industry applications + +## Choosing Between Crews and Flows + +### When to Choose Crews + +Crews are ideal when: + +1. **You need collaborative intelligence** - Multiple agents with different specializations need to work together +2. **The problem requires emergent thinking** - The solution benefits from different perspectives and approaches +3. **The task is primarily creative or analytical** - The work involves research, content creation, or analysis +4. **You value adaptability over strict structure** - The workflow can benefit from agent autonomy +5. **The output format can be somewhat flexible** - Some variation in output structure is acceptable + +```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() +``` + +### When to Choose Flows + +Flows are ideal when: + +1. **You need precise control over execution** - The workflow requires exact sequencing and state management +2. **The application has complex state requirements** - You need to maintain and transform state across multiple steps +3. **You need structured, predictable outputs** - The application requires consistent, formatted results +4. **The workflow involves conditional logic** - Different paths need to be taken based on intermediate results +5. **You need to combine AI with procedural code** - The solution requires both AI capabilities and traditional programming + +```python +# Example: Customer Support Flow with structured processing +from crewai.flow.flow import Flow, listen, or_, 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(or_("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() +``` + +### When to Combine Crews and Flows + +The most sophisticated applications often benefit from combining Crews and Flows: + +1. **Complex multi-stage processes** - Use Flows to orchestrate the overall process and Crews for complex subtasks +2. **Applications requiring both creativity and structure** - Use Crews for creative tasks and Flows for structured processing +3. **Enterprise-grade AI applications** - Use Flows to manage state and process flow while leveraging Crews for specialized work + +```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() +``` + +## Practical Evaluation Framework + +To determine the right approach for your specific use case, follow this step-by-step evaluation framework: + +### Step 1: Assess Complexity + +Rate your application's complexity on a scale of 1-10 by considering: + +1. **Number of steps**: How many distinct operations are required? + - 1-3 steps: Low complexity (1-3) + - 4-7 steps: Medium complexity (4-7) + - 8+ steps: High complexity (8-10) + +2. **Interdependencies**: How interconnected are the different parts? + - Few dependencies: Low complexity (1-3) + - Some dependencies: Medium complexity (4-7) + - Many complex dependencies: High complexity (8-10) + +3. **Conditional logic**: How much branching and decision-making is needed? + - Linear process: Low complexity (1-3) + - Some branching: Medium complexity (4-7) + - Complex decision trees: High complexity (8-10) + +4. **Domain knowledge**: How specialized is the knowledge required? + - General knowledge: Low complexity (1-3) + - Some specialized knowledge: Medium complexity (4-7) + - Deep expertise in multiple domains: High complexity (8-10) + +Calculate your average score to determine overall complexity. + +### Step 2: Assess Precision Requirements + +Rate your precision requirements on a scale of 1-10 by considering: + +1. **Output structure**: How structured must the output be? + - Free-form text: Low precision (1-3) + - Semi-structured: Medium precision (4-7) + - Strictly formatted (JSON, XML): High precision (8-10) + +2. **Accuracy needs**: How important is factual accuracy? + - Creative content: Low precision (1-3) + - Informational content: Medium precision (4-7) + - Critical information: High precision (8-10) + +3. **Reproducibility**: How consistent must results be across runs? + - Variation acceptable: Low precision (1-3) + - Some consistency needed: Medium precision (4-7) + - Exact reproducibility required: High precision (8-10) + +4. **Error tolerance**: What is the impact of errors? + - Low impact: Low precision (1-3) + - Moderate impact: Medium precision (4-7) + - High impact: High precision (8-10) + +Calculate your average score to determine overall precision requirements. + +### Step 3: Map to the Matrix + +Plot your complexity and precision scores on the matrix: + +- **Low Complexity (1-4), Low Precision (1-4)**: Simple Crews +- **Low Complexity (1-4), High Precision (5-10)**: Flows with direct LLM calls +- **High Complexity (5-10), Low Precision (1-4)**: Complex Crews +- **High Complexity (5-10), High Precision (5-10)**: Flows orchestrating Crews + +### Step 4: Consider Additional Factors + +Beyond complexity and precision, consider: + +1. **Development time**: Crews are often faster to prototype +2. **Maintenance needs**: Flows provide better long-term maintainability +3. **Team expertise**: Consider your team's familiarity with different approaches +4. **Scalability requirements**: Flows typically scale better for complex applications +5. **Integration needs**: Consider how the solution will integrate with existing systems + +## Conclusion + +Choosing between Crews and Flows—or combining them—is a critical architectural decision that impacts the effectiveness, maintainability, and scalability of your CrewAI application. By evaluating your use case along the dimensions of complexity and precision, you can make informed decisions that align with your specific requirements. + +Remember that the best approach often evolves as your application matures. Start with the simplest solution that meets your needs, and be prepared to refine your architecture as you gain experience and your requirements become clearer. + + +You now have a framework for evaluating CrewAI use cases and choosing the right approach based on complexity and precision requirements. This will help you build more effective, maintainable, and scalable AI applications. + + +## Next Steps + +- 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/v1.15.1/en/guides/crews/first-crew.mdx b/docs/v1.15.1/en/guides/crews/first-crew.mdx new file mode 100644 index 000000000..9665a293a --- /dev/null +++ b/docs/v1.15.1/en/guides/crews/first-crew.mdx @@ -0,0 +1,162 @@ +--- +title: Build Your First Crew +description: Step-by-step tutorial to create a collaborative AI team with JSON-first crew configuration. +icon: users-gear +mode: "wide" +--- + +## Build a Research Crew + +In this guide, you will create a two-agent research crew that gathers information about a topic and writes a markdown report. New crew projects are JSON-first: agents are defined in `agents/*.jsonc`, tasks and crew settings are defined in `crew.jsonc`, and `crewai run` loads the JSON definition directly. + +### Prerequisites + +Before starting, make sure you have: + +1. Installed CrewAI following the [installation guide](/en/installation) +2. Set up your LLM API key following the [LLM setup guide](/en/concepts/llms#setting-up-your-llm) +3. A [Serper.dev](https://serper.dev/) API key if you want the researcher to use web search + +## Step 1: Create a New Crew + +```bash +crewai create crew research_crew +cd research_crew +``` + +The CLI creates a JSON-first project: + +```text +research_crew/ +├── .gitignore +├── .env +├── agents/ +│ └── researcher.jsonc +├── crew.jsonc +├── knowledge/ +├── pyproject.toml +├── README.md +├── skills/ +└── tools/ +``` + + +Need the older `crew.py`, `config/agents.yaml`, and `config/tasks.yaml` layout? Create it with `crewai create crew research_crew --classic`. + + +## Step 2: Define Your Agents + +Replace the generated `agents/researcher.jsonc` file and add `agents/analyst.jsonc`. The file names are the names you reference from `crew.jsonc`. + +```jsonc agents/researcher.jsonc +{ + "role": "Senior Research Specialist for {topic}", + "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.", + "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.", + // Replace with your model, for example "openai/gpt-4o". + "llm": "provider/model-id", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +```jsonc agents/analyst.jsonc +{ + "role": "Report Analyst for {topic}", + "goal": "Turn research findings into a clear, well-structured report.", + "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.", + // Replace with your model, for example "openai/gpt-4o". + "llm": "provider/model-id", + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +Replace `provider/model-id` with the model you use, for example `openai/gpt-4o`, `anthropic/claude-sonnet-4-6`, or `gemini/gemini-2.0-flash-001`. + +## Step 3: Define Tasks and Crew Settings + +Replace `crew.jsonc` with: + +```jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.", + "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis_task", + "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.", + "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.", + "agent": "analyst", + "context": ["research_task"], + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "Artificial Intelligence in Healthcare" + } +} +``` + +`context` points to prior task names, so the analyst receives the research task output. The `inputs` object provides default values for `{topic}`. If you remove a default, `crewai run` prompts for it. + +## Step 4: Set Environment Variables + +Open `.env` and add the keys your model and tools need: + +```sh +SERPER_API_KEY=your_serper_api_key +# Add your model provider API key here too. +``` + +See the [LLM setup guide](/en/concepts/llms#setting-up-your-llm) for provider-specific keys. + +## Step 5: Install and Run + +```bash +crewai install +crewai run +``` + +`crewai run` detects `crew.jsonc`, loads the agents from `agents/`, prompts for missing placeholders, and runs the crew. When the run finishes, open `output/report.md`. + +## How It Works + +1. `crew.jsonc` defines the crew, task order, process, memory, and runtime inputs. +2. `agents/researcher.jsonc` and `agents/analyst.jsonc` define the agents. +3. The researcher runs first. +4. The analyst runs second with `context: ["research_task"]`. +5. The final task writes `output/report.md`. + +## Extending Your Crew + +You can add: + +- More agents by creating new `agents/.jsonc` files and listing them in `crew.jsonc` +- More tasks by appending objects to the `tasks` array +- Built-in tools by adding tool class names such as `"FileReadTool"` or `"SerperDevTool"` +- Custom tools with `"custom:"`, which loads `tools/.py` +- Hierarchical execution with `"process": "hierarchical"` and a `manager_llm` or `manager_agent` + + +Only run JSON crew projects from sources you trust. `custom:` tools and `{"python": "module.attribute"}` references execute local Python code when the crew loads. + + + +You now have a working JSON-first crew that researches a topic and writes a report. + diff --git a/docs/v1.15.1/en/guides/flows/conversational-flows.mdx b/docs/v1.15.1/en/guides/flows/conversational-flows.mdx new file mode 100644 index 000000000..c231fe010 --- /dev/null +++ b/docs/v1.15.1/en/guides/flows/conversational-flows.mdx @@ -0,0 +1,501 @@ +--- +title: Conversational Flows +description: Build multi-turn chat apps with handle_turn per turn, message history, intent routing, tracing, and WebSocket bridges. +icon: comments +mode: "wide" +--- + +## Overview + +Conversational apps treat each user line as a **new flow run** with the **same session id**. CrewAI adds helpers for message history, optional intent routing, deferred tracing, UI bridges, and a local `flow.chat()` REPL for conversational flows. + +| Concept | Implementation | +|---------|----------------| +| Session id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` | +| User line | `handle_turn(message)` appends to `state.messages` before the graph runs | +| Turn complete | `FlowFinished` for **this run** only; chat continues on the next `handle_turn` | +| Full-session trace | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` | + +## Turn APIs + +Use **`flow.handle_turn(message, session_id=...)`** for every user message from REST, WebSocket, tests, and custom UIs. Use **`flow.chat()`** when you want a local terminal chat loop for a conversational `Flow`. + +`Flow.kickoff()` does **not** accept `user_message=` or `session_id=` keyword arguments. For conversational flows, `handle_turn()` stores the pending message and calls `kickoff(inputs={"id": session_id})` internally after resetting per-turn execution state. + +| API | Use for | +|-----|---------| +| `handle_turn(message, session_id=...)` | Ergonomic one-turn wrapper for conversational `Flow` | +| `chat()` | Local terminal REPL for conversational `Flow` | +| `kickoff(inputs={...})` | Advanced flow execution without conversational turn handling | +| `ask()` | Blocking prompt **inside** one step (wizard, clarification) | +| `@human_feedback` | Approve/reject **a step output** — not the next chat line | +| `ChatSession.handle_turn(...)` | Transport layer over `handle_turn` (SSE / WebSocket) | + +## Quick start + +```python +from uuid import uuid4 + +from crewai import Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, +) + + +@ConversationConfig(defer_trace_finalization=True) +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context): + message = (self.state.current_user_message or "").lower() + if "order" in message: + return "order" + if "bye" in message or "goodbye" in message: + return "goodbye" + return "help" + + @listen("order") + def handle_order(self): + reply = "Your order is on the way." + self.append_assistant_message(reply) + return reply + + @listen("help") + def handle_help(self): + reply = "How can I help?" + self.append_assistant_message(reply) + return reply + + @listen("goodbye") + def handle_goodbye(self): + reply = "Goodbye!" + self.append_assistant_message(reply) + return reply + + +session_id = str(uuid4()) +flow = SupportFlow() + +try: + flow.handle_turn("Where is my order?", session_id=session_id) + flow.handle_turn("What about returns?", session_id=session_id) +finally: + flow.finalize_session_traces() # one trace link for the whole chat +``` + +## Turn lifecycle + +Each `handle_turn` runs this pipeline: + +1. **Turn setup** — stores the pending user message, resolves the session id, resets per-turn execution tracking, and calls `kickoff(inputs={"id": session_id})`. +2. **State restore** — if `inputs["id"]` exists and `@persist` is configured, loads the latest snapshot. +3. **`FlowStarted`** — emitted on the first deferred session turn only. +4. **Pending turn hydration** — appends the user message to `state.messages`, sets `current_user_message` / `last_user_message`, and optionally classifies when `intents` / `default_intents` + `intent_llm` are set. +5. **Graph execution** — `conversation_start` → `route_conversation` → the selected `@listen` handler. +6. **End of run** — per-turn `flow_finished` and trace finalization are **skipped** when deferral is enabled; nested `Agent.kickoff()` / crews do not close the parent batch either. + +Handlers should call **`append_assistant_message(reply)`** so the next turn’s `conversation_messages` includes assistant text. The user line is already stored by `handle_turn` — do not append it again in handlers. + +## `ConversationConfig` (class-level defaults) + +Decorate your conversational `Flow` subclass with `ConversationConfig`. + +| Field | Default | Purpose | +|-------|---------|---------| +| `system_prompt` | Framework default | System message used by the built-in `converse_turn`. | +| `llm` | `None` | Conversation LLM used by `converse_turn` and as router fallback. | +| `router` | `None` | `RouterConfig` for LLM-driven routing. | +| `intent_llm` | `None` | LLM for `intents=` / `default_intents` pre-classification. | +| `default_intents` | `None` | Outcome labels for pre-classification. | +| `defer_trace_finalization` | `True` | Keep one trace batch open across `handle_turn()` calls. | + +Override pre-classification per turn with `handle_turn(..., intents=..., intent_llm=...)`. + +## Lower-level `ChatState` helpers + +`ChatState`, `ConversationalConfig`, and `crewai.flow.conversation` helpers are still importable for advanced orchestration, tests, or custom wrappers. They do not add `user_message=` or `session_id=` keyword arguments to `Flow.kickoff()`. + +```python +from crewai.flow import ChatState + + +class MyChatState(ChatState): + # Inherited: id, messages, last_user_message, last_intent, session_ready + research_turn_count: int = 0 + custom_flag: bool = False +``` + +| Field | Role | +|-------|------| +| `id` | Session UUID (same as `inputs["id"]`) | +| `messages` | `list` of `{role, content}` for LLM history | +| `last_user_message` | Latest user line for this turn | +| `last_intent` | Route label after classification (if used) | +| `session_ready` | One-time bootstrap flag (permissions, caches, etc.) | + +`ConversationalInputs` is a `TypedDict` for conventional `kickoff(inputs={...})` keys: `id`, `user_message`, `last_intent`. + +## `Flow` conversational API + +### `handle_turn` parameters + +| Parameter | Purpose | +|-----------|---------| +| `message` | This turn’s text | +| `session_id` | Conversation UUID → `inputs["id"]` / `state.id` | +| `intents` | Outcome labels for pre-kickoff `classify_intent` | +| `intent_llm` | LLM for classification (required with `intents`) | +| `**kickoff_kwargs` | Forwarded to `kickoff()` for options like `input_files`, `from_checkpoint`, and `restore_from_state_id` | + +### `kickoff` parameters + +`Flow.kickoff()` accepts `inputs`, `input_files`, `from_checkpoint`, and `restore_from_state_id`. Pass `inputs={"id": session_id}` when you need raw flow execution, but use `handle_turn()` when the call represents a chat message. + +### Instance attributes + +| Attribute | Purpose | +|-----------|---------| +| `conversational` | Set to `True` to enable the conversational graph and `handle_turn()` | +| `defer_trace_finalization` | Instance flag; set automatically from config on `handle_turn()` | +| `suppress_flow_events` | Hides console flow panels; **tracing still records** method/flow events | +| `stream` | Enable streaming; use with `ChatSession.handle_turn(..., stream=True)` | + +### Methods and properties + +| Name | Description | +|------|-------------| +| `append_assistant_message(content)` | Append a user-visible assistant reply to `state.messages` | +| `append_message(role, content, **extra)` | Lower-level append to `state.messages` | +| `conversation_messages` | Read-only history for LLM calls | +| `classify_intent(text, outcomes, *, llm, context=None)` | Map text to one outcome (same collapse logic as `@human_feedback`) | +| `receive_user_message(text, *, outcomes=None, llm=None)` | Append user message; optionally set `last_intent` | +| `finalize_session_traces()` | Emit deferred `flow_finished` and finalize the session trace batch | +| `_should_defer_trace_finalization()` | Whether this flow defers per-turn trace finalization | +| `input_history` | Audit trail of `ask()` prompts and responses | + +### Module helpers (`crewai.flow.conversation`) + +Importable for tests or custom orchestration: + +| Function | Description | +|----------|-------------| +| `normalize_kickoff_inputs(inputs, user_message=..., session_id=...)` | Merge conversational kwargs into `inputs` | +| `get_conversation_messages(flow)` | Read messages from state or internal buffer | +| `append_message(flow, role, content, **extra)` | Same as instance method | +| `prepare_conversational_turn(flow, user_message=..., intents=..., intent_llm=..., config=...)` | Lower-level turn hydration for custom wrappers | +| `receive_user_message(flow, text, ...)` | Same as instance method | +| `set_state_field(flow, name, value)` | Set a field on dict or Pydantic state | +| `get_conversational_config(flow)` | Read class `conversational_config` | +| `input_history_to_messages(entries)` | Convert `input_history` to LLM message format | + +## Intent routing patterns + +### A. Pre-classify via `ConversationConfig` (simplest) + +Set `default_intents` and `intent_llm`. Each `handle_turn()` runs classification before routing; read `self.state.last_intent` in `route_turn()`. + +### B. Classify inside `route_turn` (richer prompts) + +Set `default_intents=None` so `handle_turn()` only appends the user message. In `route_turn()`, call `classify_intent` with a custom prompt or descriptions: + +```python +def route_turn(self, context): + intent = self.classify_intent( + self._routing_prompt(self.state.current_user_message), + ("GREETING", "ORDER", "RESEARCH", "GOODBYE"), + llm="gpt-4o-mini", + ) + self.state.last_intent = intent + return intent +``` + +Use **`@listen("RESEARCH")`** (or similar) for steps that run `Agent.kickoff()` with tools — not bare `LLM.call()` — when you need web research or multi-step tool use. + +## When the flow finishes but the user keeps chatting + +`FlowFinished` means **this graph run** completed. The conversation continues with another `handle_turn()` and the same `session_id`. `@persist` restores `messages`, flags, and context. + +**Persist pattern:** prefer `@persist` on a **single terminal step** (for example `finalize`) rather than on the whole `Flow` class. Class-level persist saves after every method; `load_state` uses the latest row, which may be a mid-run snapshot (for example right after `bootstrap`) and miss handler updates from the same turn. + +Do **not** use `@human_feedback` for follow-up chat lines unless a human must approve a specific step output before it is shown. + +## Conversational `Flow` (experimental) + + + **This is an experimental feature.** The conversational `Flow` surface + (`conversational = True`, `handle_turn`, `ConversationConfig`, + `RouterConfig`, `ConversationState`, the built-in graph + helpers) lives + under `crewai.experimental` and may change shape before it graduates. + Pin your CrewAI version if you depend on specific behavior, and watch the + changelog for breaking updates. Open issues / feedback welcome. + + +Opt into the conversational chat graph by setting `conversational = True` on a `Flow` subclass. The base `Flow` then ships a built-in `@start` / `@router` / `converse_turn` / `end_conversation` graph, manages `state.messages`, can drive a router LLM, and keeps the trace batch open across turns. You write the **custom routes**; the framework owns the rest. + +Use this when you want a multi-turn chat with a router and per-route handlers without wiring the lifecycle yourself. Use `Flow[ChatState]` (the lower-level pattern above) when you need full control. + +### Quick example + +```python +from crewai import Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, +) + + +@ConversationConfig(defer_trace_finalization=True) +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context: dict) -> str | None: + message = (self.state.current_user_message or "").lower() + if "search" in message or "news" in message: + return "INTERNET_SEARCH" + if "docs" in message or "crewai" in message: + return "CREWAI_DOCS" + return "converse" + + @listen("INTERNET_SEARCH") + def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + reply = "I would run the web research route here." + self.append_assistant_message(reply) + return reply + + @listen("CREWAI_DOCS") + def handle_crewai_docs(self) -> str: + """Look up the CrewAI documentation for framework/API questions.""" + reply = "I would look up the CrewAI docs here." + self.append_assistant_message(reply) + return reply + + +flow = SupportFlow() +try: + flow.handle_turn("What can you do?") # routes to converse + flow.handle_turn("Search the web for AI news.") # routes to INTERNET_SEARCH + flow.handle_turn("Check the CrewAI docs.") # routes to CREWAI_DOCS +finally: + flow.finalize_session_traces() +``` + +For a local terminal chat, use `chat()`: + +```python +def kickoff() -> None: + SupportFlow().chat() +``` + +`chat()` wraps `handle_turn()` in a REPL, exits on `exit` / `quit`, skips blank lines by default, and calls `finalize_session_traces()` when the session ends. + +### `ConversationConfig` + +Class decorator that attaches per-class chat defaults. + +| Field | Default | Purpose | +|-------|---------|---------| +| `system_prompt` | `slices.conversational_system_prompt` from i18n | System message used by the built-in `converse_turn`. Pass `""` to opt out entirely. | +| `llm` | `None` | Conversation LLM (used by `converse_turn` and as router fallback). | +| `router` | `None` | `RouterConfig` for LLM-driven routing. Without it, the flow always falls through to `converse`. | +| `answer_from_history_prompt` | Framework default | System message for the optional `answer_from_history` route. | +| `answer_from_history_llm` | `None` | Enables the `answer_from_history` short-circuit when set. | +| `intent_llm` | `None` | LLM for legacy `intents=`/`default_intents` pre-classification. | +| `default_intents` | `None` | Outcome labels for legacy pre-classification. | +| `visible_agent_outputs` | `None` | `"all"`, or a list of agent names whose `append_agent_result()` calls should be promoted to public assistant messages. | +| `defer_trace_finalization` | `True` | Keep one trace batch open across `handle_turn()` calls. | + +### `RouterConfig` and the auto-built route catalog + +```python +from typing import Literal + +from pydantic import BaseModel + +from crewai import LLM +from crewai.experimental.conversational import RouterConfig + + +class MyRoute(BaseModel): + intent: Literal["INTERNET_SEARCH", "CREWAI_DOCS", "converse"] + + +ROUTER_LLM = LLM(model="gpt-4o-mini") + +router_config = RouterConfig( + prompt="Optional domain framing (policy, voice, persona).", + response_format=MyRoute, # optional; auto-generated otherwise + llm=ROUTER_LLM, # falls back to ConversationConfig.llm + routes=["INTERNET_SEARCH", "CREWAI_DOCS"], # optional; inferred from listeners + route_descriptions={ + "INTERNET_SEARCH": "Override the docstring for this one route.", + }, + default_intent="converse", # used when LLM call fails or no LLM available + fallback_intent="converse", # used when LLM returns an invalid route + intent_field="intent", +) +``` + +The router prompt that gets sent to the LLM is built automatically. For each route the framework picks a description with this precedence: + +1. `RouterConfig.route_descriptions[label]` — explicit override. +2. `Flow.builtin_route_descriptions[label]` — framework-canned text for `converse`, `end`, `answer_from_history` (phrased for the router LLM). +3. First non-empty line of the `@listen(label)` handler's docstring. +4. Empty (the route is listed without a description). + +So in practice, **adding a new route is `@listen("X")` + a one-line docstring**: + +```python +from crewai.flow import listen + + +@listen("INTERNET_SEARCH") +def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... +``` + +…and the router LLM sees: + +``` +Routes: +- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions. +- INTERNET_SEARCH: Fresh web research, current news, real-time lookups. +- converse: Ordinary chat, follow-ups, summaries, clarifications… +- end: User signals the conversation is finished (goodbye, exit, done). +``` + +`RouterConfig.prompt` is for **domain framing** (assistant persona, business rules, voice). The route catalog is auto-built — don't list routes in `prompt`; they'll drift the moment you add a handler. + +### Built-in routes + +| Route | Handler | Purpose | +|-------|---------|---------| +| `converse` | `converse_turn` | Default chat handler. Calls `ConversationConfig.llm` with the system prompt + canonical message history. | +| `end` | `end_conversation` | Sets `state.ended = True` and emits a terminator reply. | +| `answer_from_history` | `answer_from_history_turn` | Optional. Routes here when `ConversationConfig.answer_from_history_llm` is set and the message can be answered from existing history. | + +You can override any of these by defining a same-named handler in your subclass. + +### `handle_turn()` semantics + +`flow.handle_turn(message)` runs one turn: + +1. Resets per-execution tracking (`_completed_methods`, `_method_outputs`) so the graph re-runs — without this, repeated `kickoff` calls on the same flow instance would short-circuit on turn 2+ because `Flow.kickoff_async` treats `inputs={"id": ...}` as a checkpoint restore. +2. Appends the user message to `state.messages`, sets `current_user_message` / `last_user_message`. `last_intent` is **preserved from the prior turn** so the router LLM can use it as a signal. +3. Runs `conversation_start` → `route_conversation` → the chosen `@listen` handler. +4. The router stores its decision in `state.last_intent` (visible to the next turn's router context). +5. If your handler returned a string and didn't already call `append_assistant_message`, `handle_turn` appends it for you. + +Call `handle_turn()` for chat messages. Calling `kickoff(inputs={"id": ...})` directly runs the flow graph without applying the conversational turn wrapper. + +### `chat()` for local REPLs + +`flow.chat()` is the batteries-included terminal wrapper around `handle_turn()`: + +```python +flow = SupportFlow() +flow.chat() +``` + +It handles the common local loop: + +1. Prompts for a user message. +2. Stops on `exit` / `quit`, `EOFError`, or `KeyboardInterrupt`. +3. Calls `handle_turn(message, session_id=...)`. +4. Prints the assistant result. +5. Finalizes deferred session traces in a `finally` block. + +Customize the terminal behavior with injectable I/O: + +```python +flow.chat( + session_id="demo-session", + prompt="You: ", + assistant_prefix="Assistant: ", + exit_commands=("exit", "quit", "bye"), +) +``` + +For web apps, background workers, tests, and custom transports, keep using `handle_turn()` directly. + +### Custom router behavior + +To run side effects (event bus setup, telemetry) on every routing decision, override `route_turn`: + +```python +from typing import Any + +from crewai import Flow +from crewai.experimental.conversational import ConversationState + + +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context: dict[str, Any]) -> str | None: + self.event_bus = MyBus(self) + return super().route_turn(context) +``` + +To bypass the LLM router entirely and pick a route programmatically, return a string from `route_turn`; returning `None` falls back to `_route_with_config(...)`. + +### `append_assistant_message` and `append_agent_result` + +Inside a `@listen(label)` handler, choose: + +- `self.append_assistant_message(text)` — adds a user-visible assistant turn to `state.messages`. The next turn's `converse_turn` sees it. +- `self.append_agent_result(agent_name, result, visibility="private")` — records a structured event in `state.events` and a thread in `state.agent_threads[agent_name]`. Public visibility also calls `append_assistant_message` for you. Use private results for scratch work that shouldn't pollute the canonical history. + +`ConversationConfig.visible_agent_outputs` can promote specific agents' private results to public globally (`"all"`, or a list of agent names). + +## Tracing across turns + +With `defer_trace_finalization=True` (default in `ConversationConfig`): + +- **One trace batch** for the whole chat session. +- **`flow_started`** on the first turn only; **`flow_finished`** once in `finalize_session_traces()`. +- **Per-turn** `kickoff` does not print “Trace batch finalized”. +- **Nested work** (`Agent.kickoff()`, crews, Exa tools) appends to the **parent** batch; inner `AgentExecutor` flows do not close the session batch early. + +```python +flow.chat(session_id=session_id) +``` + +`flow.chat()` calls `finalize_session_traces()` for you. When you own the loop +with `handle_turn()`, call `finalize_session_traces()` when +the session ends. + +`suppress_flow_events=True` only hides Rich console panels; trace and method events still emit for observability. + +### Conversational `Flow` trace lifecycle + +The experimental [conversational `Flow`](#conversational-flow-experimental) uses the same tracing lifecycle: `defer_trace_finalization` defaults to `True`, so each `handle_turn()` keeps the session trace open. Always finalize at the end of the session — wrap your REPL/loop in `try/finally` and call `flow.finalize_session_traces()` on exit. Without it, the trace batch stays open and the final conversation may never export. + +## Streaming + +Set `stream = True` on the `Flow` class. `kickoff(...)` will then emit `assistant_delta` (and related) events through the standard event bus. + +## Imports + +```python +from crewai.flow import ( + ChatState, + ConversationalConfig, + ConversationalInputs, + Flow, + listen, + persist, + router, + start, +) +``` + +## See also + +- [Mastering Flow State Management](/en/guides/flows/mastering-flow-state) — persistence, Pydantic state, `@persist` +- [Build Your First Flow](/en/guides/flows/first-flow) — flow basics +- Demo: `lib/crewai/runner_conversational_flow_simple.py` — minimal REPL with `RESEARCH` + Exa agent diff --git a/docs/v1.15.1/en/guides/flows/first-flow.mdx b/docs/v1.15.1/en/guides/flows/first-flow.mdx new file mode 100644 index 000000000..d26a1eb2d --- /dev/null +++ b/docs/v1.15.1/en/guides/flows/first-flow.mdx @@ -0,0 +1,552 @@ +--- +title: Build Your First Flow +description: Learn how to create structured, event-driven workflows with precise control over execution. +icon: diagram-project +mode: "wide" +--- + +## Taking Control of AI Workflows with Flows + +CrewAI Flows represent the next level in AI orchestration - combining the collaborative power of AI agent crews with the precision and flexibility of procedural programming. While crews excel at agent collaboration, flows give you fine-grained control over exactly how and when different components of your AI system interact. + +In this guide, we'll walk through creating a powerful CrewAI Flow that generates a comprehensive learning guide on any topic. This tutorial will demonstrate how Flows provide structured, event-driven control over your AI workflows by combining regular code, direct LLM calls, and crew-based processing. + +### What Makes Flows Powerful + +Flows enable you to: + +1. **Combine different AI interaction patterns** - Use crews for complex collaborative tasks, direct LLM calls for simpler operations, and regular code for procedural logic +2. **Build event-driven systems** - Define how components respond to specific events and data changes +3. **Maintain state across components** - Share and transform data between different parts of your application +4. **Integrate with external systems** - Seamlessly connect your AI workflow with databases, APIs, and user interfaces +5. **Create complex execution paths** - Design conditional branches, parallel processing, and dynamic workflows + +### What You'll Build and Learn + +By the end of this guide, you'll have: + +1. **Created a sophisticated content generation system** that combines user input, AI planning, and multi-agent content creation +2. **Orchestrated the flow of information** between different components of your system +3. **Implemented event-driven architecture** where each step responds to the completion of previous steps +4. **Built a foundation for more complex AI applications** that you can expand and customize + +This guide creator flow demonstrates fundamental patterns that can be applied to create much more advanced applications, such as: + +- Interactive AI assistants that combine multiple specialized subsystems +- Complex data processing pipelines with AI-enhanced transformations +- Autonomous agents that integrate with external services and APIs +- Multi-stage decision-making systems with human-in-the-loop processes + +Let's dive in and build your first flow! + +## Prerequisites + +Before starting, make sure you have: + +1. Installed CrewAI following the [installation guide](/en/installation) +2. Set up your LLM API key in your environment, following the [LLM setup + guide](/en/concepts/llms#setting-up-your-llm) +3. Basic understanding of Python + +## Step 1: Create a New CrewAI Flow Project + +First, let's create a new CrewAI Flow project using the CLI. This command sets up a scaffolded project with all the necessary directories and template files for your flow. + +```bash +crewai create flow guide_creator_flow +cd guide_creator_flow +``` + +This will generate a project with the basic structure needed for your flow. + + + CrewAI Framework Overview + + +## Step 2: Understanding the Project Structure + +The generated project has the following structure. The starter embedded crew uses the classic Python/YAML layout, and in Step 4 we will replace the content crew with a JSONC crew. + +``` +guide_creator_flow/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +└── src/ + └── guide_creator_flow/ + ├── __init__.py + ├── main.py + ├── crews/ + │ └── poem_crew/ + │ ├── config/ + │ │ ├── agents.yaml + │ │ └── tasks.yaml + │ └── poem_crew.py + └── tools/ + └── custom_tool.py +``` + +This structure provides a clear separation between different components of your flow: +- The main flow logic in the `src/guide_creator_flow/main.py` file +- Specialized crews in the `src/guide_creator_flow/crews` directory +- Custom tools in the `src/guide_creator_flow/tools` directory + +We'll modify this structure to create our guide creator flow, which will orchestrate the process of generating comprehensive learning guides. + +## Step 3: Add a Content Writer Crew + +Our flow will need a specialized crew to handle the content creation process. Let's use the CrewAI CLI to add a content writer crew: + +```bash +crewai flow add-crew content-crew +``` + +This command automatically creates the necessary directories and template files for your crew. The content writer crew will be responsible for writing and reviewing sections of our guide, working within the overall flow orchestrated by our main application. + +## Step 4: Configure the Content Writer Crew + +Now, let's configure the content writer crew with JSONC. We'll set up two specialized agents - a writer and a reviewer - that collaborate to create high-quality content for our guide. + +1. Create `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`: + +```jsonc +{ + "role": "Educational Content Writer", + "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.", + "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +2. Create `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`: + +```jsonc +{ + "role": "Educational Content Reviewer and Editor", + "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.", + "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +Replace `provider/model-id` with the model you use, for example `openai/gpt-4o`, `gemini/gemini-2.0-flash-001`, or `anthropic/claude-sonnet-4-6`. + +3. Create `src/guide_creator_flow/crews/content_crew/crew.jsonc`: + +```jsonc +{ + "name": "Content Crew", + "agents": ["content_writer", "content_reviewer"], + "tasks": [ + { + "name": "write_section_task", + "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}", + "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.", + "agent": "content_writer", + "markdown": true + }, + { + "name": "review_section_task", + "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.", + "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.", + "agent": "content_reviewer", + "context": ["write_section_task"], + "markdown": true + } + ], + "process": "sequential", + "verbose": true +} +``` + +The `context` field lets the reviewer use the writer's output. + +4. Replace `src/guide_creator_flow/crews/content_crew/content_crew.py` with a small loader: + +```python +from pathlib import Path + +from crewai.project import load_crew + + +def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) +``` + +This loader turns `crew.jsonc` into a `Crew` at runtime. While this crew can function independently, in our flow it will be orchestrated as part of a larger system. + +## Step 5: Create the Flow + +Now comes the exciting part - creating the flow that will orchestrate the entire guide creation process. This is where we'll combine regular Python code, direct LLM calls, and our content creation crew into a cohesive system. + +Our flow will: +1. Get user input for a topic and audience level +2. Make a direct LLM call to create a structured guide outline +3. Process each section sequentially using the content writer crew +4. Combine everything into a final comprehensive document + +Let's create our flow in the `main.py` file: + +```python +#!/usr/bin/env python +import json +import os +from typing import List, Dict +from pydantic import BaseModel, Field +from crewai import LLM +from crewai.flow.flow import Flow, listen, start +from guide_creator_flow.crews.content_crew.content_crew import kickoff_content_crew + +# Define our models for structured data +class Section(BaseModel): + title: str = Field(description="Title of the section") + description: str = Field(description="Brief description of what the section should cover") + +class GuideOutline(BaseModel): + title: str = Field(description="Title of the guide") + introduction: str = Field(description="Introduction to the topic") + target_audience: str = Field(description="Description of the target audience") + sections: List[Section] = Field(description="List of sections in the guide") + conclusion: str = Field(description="Conclusion or summary of the guide") + +# Define our flow state +class GuideCreatorState(BaseModel): + topic: str = "" + audience_level: str = "" + guide_outline: GuideOutline = None + sections_content: Dict[str, str] = {} + +class GuideCreatorFlow(Flow[GuideCreatorState]): + """Flow for creating a comprehensive guide on any topic""" + + @start() + def get_user_input(self): + """Get input from the user about the guide topic and audience""" + print("\n=== Create Your Comprehensive Guide ===\n") + + # Get user input + self.state.topic = input("What topic would you like to create a guide for? ") + + # Get audience level with validation + while True: + audience = input("Who is your target audience? (beginner/intermediate/advanced) ").lower() + if audience in ["beginner", "intermediate", "advanced"]: + self.state.audience_level = audience + break + print("Please enter 'beginner', 'intermediate', or 'advanced'") + + print(f"\nCreating a guide on {self.state.topic} for {self.state.audience_level} audience...\n") + return self.state + + @listen(get_user_input) + def create_guide_outline(self, state): + """Create a structured outline for the guide using a direct LLM call""" + print("Creating guide outline...") + + # Initialize the LLM + llm = LLM(model="openai/gpt-4o-mini", response_format=GuideOutline) + + # Create the messages for the outline + messages = [ + {"role": "system", "content": "You are a helpful assistant designed to output JSON."}, + {"role": "user", "content": f""" + Create a detailed outline for a comprehensive guide on "{state.topic}" for {state.audience_level} level learners. + + The outline should include: + 1. A compelling title for the guide + 2. An introduction to the topic + 3. 4-6 main sections that cover the most important aspects of the topic + 4. A conclusion or summary + + For each section, provide a clear title and a brief description of what it should cover. + """} + ] + + # Make the LLM call with JSON response format + response = llm.call(messages=messages) + + # Parse the JSON response + outline_dict = json.loads(response) + self.state.guide_outline = GuideOutline(**outline_dict) + + # Ensure output directory exists before saving + os.makedirs("output", exist_ok=True) + + # Save the outline to a file + with open("output/guide_outline.json", "w") as f: + json.dump(outline_dict, f, indent=2) + + print(f"Guide outline created with {len(self.state.guide_outline.sections)} sections") + return self.state.guide_outline + + @listen(create_guide_outline) + def write_and_compile_guide(self, outline): + """Write all sections and compile the guide""" + print("Writing guide sections and compiling...") + completed_sections = [] + + # Process sections one by one to maintain context flow + for section in outline.sections: + print(f"Processing section: {section.title}") + + # Build context from previous sections + previous_sections_text = "" + if completed_sections: + previous_sections_text = "# Previously Written Sections\n\n" + for title in completed_sections: + previous_sections_text += f"## {title}\n\n" + previous_sections_text += self.state.sections_content.get(title, "") + "\n\n" + else: + previous_sections_text = "No previous sections written yet." + + # Run the content crew for this section + result = kickoff_content_crew(inputs={ + "section_title": section.title, + "section_description": section.description, + "audience_level": self.state.audience_level, + "previous_sections": previous_sections_text, + "draft_content": "" + }) + + # Store the content + self.state.sections_content[section.title] = result.raw + completed_sections.append(section.title) + print(f"Section completed: {section.title}") + + # Compile the final guide + guide_content = f"# {outline.title}\n\n" + guide_content += f"## Introduction\n\n{outline.introduction}\n\n" + + # Add each section in order + for section in outline.sections: + section_content = self.state.sections_content.get(section.title, "") + guide_content += f"\n\n{section_content}\n\n" + + # Add conclusion + guide_content += f"## Conclusion\n\n{outline.conclusion}\n\n" + + # Save the guide + with open("output/complete_guide.md", "w") as f: + f.write(guide_content) + + print("\nComplete guide compiled and saved to output/complete_guide.md") + return "Guide creation completed successfully" + +def kickoff(): + """Run the guide creator flow""" + GuideCreatorFlow().kickoff() + print("\n=== Flow Complete ===") + print("Your comprehensive guide is ready in the output directory.") + print("Open output/complete_guide.md to view it.") + +def plot(): + """Generate a visualization of the flow""" + flow = GuideCreatorFlow() + flow.plot("guide_creator_flow") + print("Flow visualization saved to guide_creator_flow.html") + +if __name__ == "__main__": + kickoff() +``` + +Let's analyze what's happening in this flow: + +1. We define Pydantic models for structured data, ensuring type safety and clear data representation +2. We create a state class to maintain data across different steps of the flow +3. We implement three main flow steps: + - Getting user input with the `@start()` decorator + - Creating a guide outline with a direct LLM call + - Processing sections with our content crew +4. We use the `@listen()` decorator to establish event-driven relationships between steps + +This is the power of flows - combining different types of processing (user interaction, direct LLM calls, crew-based tasks) into a coherent, event-driven system. + +## Step 6: Set Up Your Environment Variables + +Create a `.env` file in your project root with your API keys. See the [LLM setup +guide](/en/concepts/llms#setting-up-your-llm) for details on configuring a provider. + +```sh .env +OPENAI_API_KEY=your_openai_api_key +# or +GEMINI_API_KEY=your_gemini_api_key +# or +ANTHROPIC_API_KEY=your_anthropic_api_key +``` + +## Step 7: Install Dependencies + +Install the required dependencies: + +```bash +crewai install +``` + +## Step 8: Run Your Flow + +Now it's time to see your flow in action! Run it using the CrewAI CLI: + +```bash +crewai run +``` + +When you run this command, you'll see your flow spring to life: +1. It will prompt you for a topic and audience level +2. It will create a structured outline for your guide +3. It will process each section, with the content writer and reviewer collaborating on each +4. Finally, it will compile everything into a comprehensive guide + +This demonstrates the power of flows to orchestrate complex processes involving multiple components, both AI and non-AI. + +## Step 9: Visualize Your Flow + +One of the powerful features of flows is the ability to visualize their structure: + +```bash +crewai flow plot +``` + +This will create an HTML file that shows the structure of your flow, including the relationships between different steps and the data that flows between them. This visualization can be invaluable for understanding and debugging complex flows. + +## Step 10: Review the Output + +Once the flow completes, you'll find two files in the `output` directory: + +1. `guide_outline.json`: Contains the structured outline of the guide +2. `complete_guide.md`: The comprehensive guide with all sections + +Take a moment to review these files and appreciate what you've built - a system that combines user input, direct AI interactions, and collaborative agent work to produce a complex, high-quality output. + +## The Art of the Possible: Beyond Your First Flow + +What you've learned in this guide provides a foundation for creating much more sophisticated AI systems. Here are some ways you could extend this basic flow: + +### Enhancing User Interaction + +You could create more interactive flows with: +- Web interfaces for input and output +- Real-time progress updates +- Interactive feedback and refinement loops +- Multi-stage user interactions + +### Adding More Processing Steps + +You could expand your flow with additional steps for: +- Research before outline creation +- Image generation for illustrations +- Code snippet generation for technical guides +- Final quality assurance and fact-checking + +### Creating More Complex Flows + +You could implement more sophisticated flow patterns: +- Conditional branching based on user preferences or content type +- Parallel processing of independent sections +- Iterative refinement loops with feedback +- Integration with external APIs and services + +### Applying to Different Domains + +The same patterns can be applied to create flows for: +- **Interactive storytelling**: Create personalized stories based on user input +- **Business intelligence**: Process data, generate insights, and create reports +- **Product development**: Facilitate ideation, design, and planning +- **Educational systems**: Create personalized learning experiences + +## Key Features Demonstrated + +This guide creator flow demonstrates several powerful features of CrewAI: + +1. **User interaction**: The flow collects input directly from the user +2. **Direct LLM calls**: Uses the LLM class for efficient, single-purpose AI interactions +3. **Structured data with Pydantic**: Uses Pydantic models to ensure type safety +4. **Sequential processing with context**: Writes sections in order, providing previous sections for context +5. **Multi-agent crews**: Leverages specialized agents (writer and reviewer) for content creation +6. **State management**: Maintains state across different steps of the process +7. **Event-driven architecture**: Uses the `@listen` decorator to respond to events + +## Understanding the Flow Structure + +Let's break down the key components of flows to help you understand how to build your own: + +### 1. Direct LLM Calls + +Flows allow you to make direct calls to language models when you need simple, structured responses: + +```python +llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + response_format=GuideOutline +) +response = llm.call(messages=messages) +``` + +This is more efficient than using a crew when you need a specific, structured output. + +### 2. Event-Driven Architecture + +Flows use decorators to establish relationships between components: + +```python +@start() +def get_user_input(self): + # First step in the flow + # ... + +@listen(get_user_input) +def create_guide_outline(self, state): + # This runs when get_user_input completes + # ... +``` + +This creates a clear, declarative structure for your application. + +### 3. State Management + +Flows maintain state across steps, making it easy to share data: + +```python +class GuideCreatorState(BaseModel): + topic: str = "" + audience_level: str = "" + guide_outline: GuideOutline = None + sections_content: Dict[str, str] = {} +``` + +This provides a type-safe way to track and transform data throughout your flow. + +### 4. Crew Integration + +Flows can seamlessly integrate with crews for complex collaborative tasks: + +```python +result = kickoff_content_crew(inputs={ + "section_title": section.title, + # ... +}) +``` + +This allows you to use the right tool for each part of your application - direct LLM calls for simple tasks and crews for complex collaboration. + +## Next Steps + +Now that you've built your first flow, you can: + +1. Experiment with more complex flow structures and patterns +2. Try using `@router()` to create conditional branches in your flows +3. Explore the `and_` and `or_` functions for more complex parallel execution +4. Connect your flow to external APIs, databases, or user interfaces +5. Combine multiple specialized crews in a single flow +6. Build multi-turn chat apps with [Conversational Flows](/en/guides/flows/conversational-flows) (`kickoff` per message, `ChatSession`, deferred tracing) + + +Congratulations! You've successfully built your first CrewAI Flow that combines regular code, direct LLM calls, and crew-based processing to create a comprehensive guide. These foundational skills enable you to create increasingly sophisticated AI applications that can tackle complex, multi-stage problems through a combination of procedural control and collaborative intelligence. + diff --git a/docs/v1.15.1/en/guides/flows/inputs-id-deprecation.mdx b/docs/v1.15.1/en/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..2798c21a5 --- /dev/null +++ b/docs/v1.15.1/en/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,143 @@ +--- +title: "Migrating from inputs.id to restore_from_state_id" +description: "Move @persist flows off the deprecated inputs.id hydration onto the supported restore_from_state_id field" +icon: "arrow-right-arrow-left" +--- + + + Passing `id` inside `inputs` to hydrate a `@persist` flow is **deprecated** and + scheduled for removal in a future release. The replacement, `restore_from_state_id`, + is available in CrewAI **v1.14.5 and later** — the steps below apply once you + upgrade. + + +## Overview + +The documented way to hydrate a `@persist` flow from a previous execution is to pass +that execution's UUID as `inputs.id`. CrewAI now exposes a dedicated field, +`restore_from_state_id`, that performs the same hydration without overloading the +`inputs` payload — and without coupling the hydration key to the new execution's +identity. + +## Migration + +If you currently kickoff a `@persist` flow with `inputs={"id": ...}`: + +```python +# Deprecated +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +Switch to `restore_from_state_id`: + +```python +# Supported +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +The two modes have different lineage semantics: + +- `inputs={"id": }` (deprecated) — **resume**: writes land under the supplied + id, extending the same `flow_uuid` history. +- `restore_from_state_id=` — **fork**: hydrates state from the snapshot, then + writes under a fresh `state.id`. The source flow's history is preserved. + +For most production scenarios — re-running a flow seeded from a previous state — fork +is what you want. See [Mastering Flow State](/en/guides/flows/mastering-flow-state) +for the full mental model. + +If you kickoff your flow over the CrewAI AMP REST API, see [AMP](#amp) below for the +equivalent payload migration. + +## Why we are deprecating `inputs.id` for `@persist` + +`inputs.id` is currently the documented way to resume a `@persist` flow from a +previous execution. The problem is that the same UUID does two jobs at once: + +1. **It selects which snapshot `@persist` hydrates from** — load the state saved + under that UUID. +2. **It becomes the new execution's Flow Execution ID** (`state.id` in the SDK; + surfaced as `flow_id` in some contexts) — every `@persist` write from this + kickoff also lands under that same UUID. + +This dual role is the root cause of the issues this guide describes. Because the +supplied UUID is also the new execution's id, two kickoffs that pass the same +`inputs.id` are not two distinct executions — they share an id, share a persistence +record, and (on AMP) share a row in the executions list. There is no way to say +"hydrate from this snapshot, but record this run separately" without splitting the +two responsibilities. + +`restore_from_state_id` is that split. It tells `@persist` which snapshot to hydrate +from, while leaving the new execution free to receive a fresh `state.id`. The +hydration source and the recorded run are no longer the same UUID — which is what +most production scenarios actually want. + +## Removal timeline + +`inputs.id` for `@persist` hydration is scheduled for removal in a future release of +CrewAI. There is no immediate hard cut-off — existing flows continue to work — but +once you upgrade to v1.14.5 or later, new code should use `restore_from_state_id`, and +existing flows should migrate at the next convenient opportunity. + +## AMP + +If you deploy your flow to CrewAI AMP, the migration extends to the kickoff payload +sent to your deployed crew, and the visible symptoms of reusing `inputs.id` show up +on the deployment dashboard. The two subsections below cover both. + +### Migrating the kickoff payload + +If you currently kickoff a deployed flow by embedding `id` in `inputs`: + +```bash +# Deprecated +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +Move the UUID to the top-level `restoreFromStateId` field: + +```bash +# Supported +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{ + "inputs": {"topic": "AI Agent Frameworks"}, + "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv" + }' \ + https://your-crew-url.crewai.com/kickoff +``` + +`restoreFromStateId` sits next to `inputs` in the kickoff payload, not inside it. The +`inputs` object now only carries values your flow actually consumes. + +### What happens when `inputs.id` is reused + +When AMP receives a kickoff for a flow whose `inputs.id` matches an existing +execution, it resolves to the existing record rather than creating a new one. From +the deployment dashboard you'll see: + +- **Execution status** — the new run's status overwrites the previous run's. A + finished execution can flip back to `running`, or a `completed` run can flip to + `error` if the new kickoff fails — either way the dashboard no longer reflects + the original run. +- **Traces** — OTel traces stack across kickoffs because they share the same + execution id; the previous run's traces are either replaced by, or mixed with, + the new run's. A step-by-step replay no longer corresponds to a single execution. +- **Executions list** — kickoffs that should appear as separate rows collapse into + a single entry, hiding history. + +Migrating to `restoreFromStateId` keeps every kickoff as its own execution — with +its own status, traces, and row in the list — while still hydrating state from a +previous run. + + + Contact our support team if you're unsure which mode your flow needs or hit issues + during the migration. + diff --git a/docs/v1.15.1/en/guides/flows/mastering-flow-state.mdx b/docs/v1.15.1/en/guides/flows/mastering-flow-state.mdx new file mode 100644 index 000000000..648a82dbd --- /dev/null +++ b/docs/v1.15.1/en/guides/flows/mastering-flow-state.mdx @@ -0,0 +1,841 @@ +--- +title: Mastering Flow State Management +description: A comprehensive guide to managing, persisting, and leveraging state in CrewAI Flows for building robust AI applications. +icon: diagram-project +mode: "wide" +--- + +## Understanding the Power of State in Flows + +State management is the backbone of any sophisticated AI workflow. In CrewAI Flows, the state system allows you to maintain context, share data between steps, and build complex application logic. Mastering state management is essential for creating reliable, maintainable, and powerful AI applications. + +This guide will walk you through everything you need to know about managing state in CrewAI Flows, from basic concepts to advanced techniques, with practical code examples along the way. + +### Why State Management Matters + +Effective state management enables you to: + +1. **Maintain context across execution steps** - Pass information seamlessly between different stages of your workflow +2. **Build complex conditional logic** - Make decisions based on accumulated data +3. **Create persistent applications** - Save and restore workflow progress +4. **Handle errors gracefully** - Implement recovery patterns for more robust applications +5. **Scale your applications** - Support complex workflows with proper data organization +6. **Enable conversational applications** - Store and access conversation history for context-aware AI interactions + +For multi-turn chat (`kickoff` per user line, `ChatState`, intent routing, deferred tracing, and `ChatSession`), see [Conversational Flows](/en/guides/flows/conversational-flows). + +Let's explore how to leverage these capabilities effectively. + +## State Management Fundamentals + +### The Flow State Lifecycle + +In CrewAI Flows, the state follows a predictable lifecycle: + +1. **Initialization** - When a flow is created, its state is initialized (either as an empty dictionary or a Pydantic model instance) +2. **Modification** - Flow methods access and modify the state as they execute +3. **Transmission** - State is passed automatically between flow methods +4. **Persistence** (optional) - State can be saved to storage and later retrieved +5. **Completion** - The final state reflects the cumulative changes from all executed methods + +Understanding this lifecycle is crucial for designing effective flows. + +### Two Approaches to State Management + +CrewAI offers two ways to manage state in your flows: + +1. **Unstructured State** - Using dictionary-like objects for flexibility +2. **Structured State** - Using Pydantic models for type safety and validation + +Let's examine each approach in detail. + +## Unstructured State Management + +Unstructured state uses a dictionary-like approach, offering flexibility and simplicity for straightforward applications. + +### How It Works + +With unstructured state: +- You access state via `self.state` which behaves like a dictionary +- You can freely add, modify, or remove keys at any point +- All state is automatically available to all flow methods + +### Basic Example + +Here's a simple example of unstructured state management: + +```python +from crewai.flow.flow import Flow, listen, start + +class UnstructuredStateFlow(Flow): + @start() + def initialize_data(self): + print("Initializing flow data") + # Add key-value pairs to state + self.state["user_name"] = "Alex" + self.state["preferences"] = { + "theme": "dark", + "language": "English" + } + self.state["items"] = [] + + # The flow state automatically gets a unique ID + print(f"Flow ID: {self.state['id']}") + + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + print(f"Previous step returned: {previous_result}") + + # Access and modify state + user = self.state["user_name"] + print(f"Processing data for {user}") + + # Add items to a list in state + self.state["items"].append("item1") + self.state["items"].append("item2") + + # Add a new key-value pair + self.state["processed"] = True + + return "Processed" + + @listen(process_data) + def generate_summary(self, previous_result): + # Access multiple state values + user = self.state["user_name"] + theme = self.state["preferences"]["theme"] + items = self.state["items"] + processed = self.state.get("processed", False) + + summary = f"User {user} has {len(items)} items with {theme} theme. " + summary += "Data is processed." if processed else "Data is not processed." + + return summary + +# Run the flow +flow = UnstructuredStateFlow() +result = flow.kickoff() +print(f"Final result: {result}") +print(f"Final state: {flow.state}") +``` + +### When to Use Unstructured State + +Unstructured state is ideal for: +- Quick prototyping and simple flows +- Dynamically evolving state needs +- Cases where the structure may not be known in advance +- Flows with simple state requirements + +While flexible, unstructured state lacks type checking and schema validation, which can lead to errors in complex applications. + +## Structured State Management + +Structured state uses Pydantic models to define a schema for your flow's state, providing type safety, validation, and better developer experience. + +### How It Works + +With structured state: +- You define a Pydantic model that represents your state structure +- You pass this model type to your Flow class as a type parameter +- You access state via `self.state`, which behaves like a Pydantic model instance +- All fields are validated according to their defined types +- You get IDE autocompletion and type checking support + +### Basic Example + +Here's how to implement structured state management: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel, Field +from typing import List, Dict, Optional + +# Define your state model +class UserPreferences(BaseModel): + theme: str = "light" + language: str = "English" + +class AppState(BaseModel): + user_name: str = "" + preferences: UserPreferences = UserPreferences() + items: List[str] = [] + processed: bool = False + completion_percentage: float = 0.0 + +# Create a flow with typed state +class StructuredStateFlow(Flow[AppState]): + @start() + def initialize_data(self): + print("Initializing flow data") + # Set state values (type-checked) + self.state.user_name = "Taylor" + self.state.preferences.theme = "dark" + + # The ID field is automatically available + print(f"Flow ID: {self.state.id}") + + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + print(f"Processing data for {self.state.user_name}") + + # Modify state (with type checking) + self.state.items.append("item1") + self.state.items.append("item2") + self.state.processed = True + self.state.completion_percentage = 50.0 + + return "Processed" + + @listen(process_data) + def generate_summary(self, previous_result): + # Access state (with autocompletion) + summary = f"User {self.state.user_name} has {len(self.state.items)} items " + summary += f"with {self.state.preferences.theme} theme. " + summary += "Data is processed." if self.state.processed else "Data is not processed." + summary += f" Completion: {self.state.completion_percentage}%" + + return summary + +# Run the flow +flow = StructuredStateFlow() +result = flow.kickoff() +print(f"Final result: {result}") +print(f"Final state: {flow.state}") +``` + +### Benefits of Structured State + +Using structured state provides several advantages: + +1. **Type Safety** - Catch type errors at development time +2. **Self-Documentation** - The state model clearly documents what data is available +3. **Validation** - Automatic validation of data types and constraints +4. **IDE Support** - Get autocomplete and inline documentation +5. **Default Values** - Easily define fallbacks for missing data + +### When to Use Structured State + +Structured state is recommended for: +- Complex flows with well-defined data schemas +- Team projects where multiple developers work on the same code +- Applications where data validation is important +- Flows that need to enforce specific data types and constraints + +## The Automatic State ID + +Both unstructured and structured states automatically receive a unique identifier (UUID) to help track and manage state instances. + +### How It Works + +- For unstructured state, the ID is accessible as `self.state["id"]` +- For structured state, the ID is accessible as `self.state.id` +- This ID is generated automatically when the flow is created +- The ID remains the same throughout the flow's lifecycle +- The ID can be used for tracking, logging, and retrieving persisted states + +This UUID is particularly valuable when implementing persistence or tracking multiple flow executions. + +## Dynamic State Updates + +Regardless of whether you're using structured or unstructured state, you can update state dynamically throughout your flow's execution. + +### Passing Data Between Steps + +Flow methods can return values that are then passed as arguments to listening methods: + +```python +from crewai.flow.flow import Flow, listen, start + +class DataPassingFlow(Flow): + @start() + def generate_data(self): + # This return value will be passed to listening methods + return "Generated data" + + @listen(generate_data) + def process_data(self, data_from_previous_step): + print(f"Received: {data_from_previous_step}") + # You can modify the data and pass it along + processed_data = f"{data_from_previous_step} - processed" + # Also update state + self.state["last_processed"] = processed_data + return processed_data + + @listen(process_data) + def finalize_data(self, processed_data): + print(f"Received processed data: {processed_data}") + # Access both the passed data and state + last_processed = self.state.get("last_processed", "") + return f"Final: {processed_data} (from state: {last_processed})" +``` + +This pattern allows you to combine direct data passing with state updates for maximum flexibility. + +## Persisting Flow State + +One of CrewAI's most powerful features is the ability to persist flow state across executions. This enables workflows that can be paused, resumed, and even recovered after failures. + +### The @persist() Decorator + +The `@persist()` decorator automates state persistence, saving your flow's state at key points in execution. + +#### Class-Level Persistence + +When applied at the class level, `@persist()` saves state after every method execution: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + value: int = 0 + +@persist() # Apply to the entire flow class +class PersistentCounterFlow(Flow[CounterState]): + @start() + def increment(self): + self.state.value += 1 + print(f"Incremented to {self.state.value}") + return self.state.value + + @listen(increment) + def double(self, value): + self.state.value = value * 2 + print(f"Doubled to {self.state.value}") + return self.state.value + +# First run +flow1 = PersistentCounterFlow() +result1 = flow1.kickoff() +print(f"First run result: {result1}") + +# Second run - pass the ID to load the persisted state +flow2 = PersistentCounterFlow() +result2 = flow2.kickoff(inputs={"id": flow1.state.id}) +print(f"Second run result: {result2}") # Will be higher due to persisted state +``` + +#### Method-Level Persistence + +For more granular control, you can apply `@persist()` to specific methods: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist + +class SelectivePersistFlow(Flow): + @start() + def first_step(self): + self.state["count"] = 1 + return "First step" + + @persist() # Only persist after this method + @listen(first_step) + def important_step(self, prev_result): + self.state["count"] += 1 + self.state["important_data"] = "This will be persisted" + return "Important step completed" + + @listen(important_step) + def final_step(self, prev_result): + self.state["count"] += 1 + return f"Complete with count {self.state['count']}" +``` + +#### Forking Persisted State + +`@persist` supports two distinct hydration modes on `kickoff` / `kickoff_async`. Use **resume** (`inputs["id"]`) to continue the same lineage; use **fork** (`restore_from_state_id`) to start a new lineage seeded from a snapshot: + +| | `state.id` after kickoff | `@persist` writes land under | +|---|---|---| +| `inputs["id"]` (resume) | supplied id | supplied id (extends history) | +| `restore_from_state_id` (fork) | fresh id, or `inputs["id"]` if pinned | new id (source preserved) | + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + +# Run 1: fresh state, counter 0 -> 1 +flow_1 = CounterFlow() +flow_1.kickoff() + +# Fork: hydrate from flow_1's latest snapshot, but write under a NEW state.id +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# flow_2 starts with counter=1 (hydrated), then step() bumps it to 2. +# flow_1's flow_uuid history is unchanged. +``` + +Behavior notes: + +- `restore_from_state_id` not found in persistence → the kickoff falls back silently to default behavior (mirrors the existing `inputs["id"]` resume not-found behavior). No exception is raised. +- Combining `restore_from_state_id` with `from_checkpoint` raises a `ValueError` — they target different state systems (`@persist` vs. Checkpointing) and cannot be combined. +- `restore_from_state_id=None` (default) is byte-identical to a kickoff without the parameter. +- Pinning `inputs["id"]` while forking means the new run shares a persistence key with another flow — usually you want only `restore_from_state_id`. + + +## Advanced State Patterns + +### Conditional starts and resumable execution + +Flows support conditional `@start()` and resumable execution for HITL/cyclic scenarios: + +```python +from crewai.flow.flow import Flow, start, listen, and_, or_ + +class ResumableFlow(Flow): + @start() # unconditional start + def init(self): + ... + + # Conditional start: run after "init" or external trigger name + @start("init") + def maybe_begin(self): + ... + + @listen(and_(init, maybe_begin)) + def proceed(self): + ... +``` + +- Conditional `@start()` accepts a method name, a router label, or a callable condition. +- During resume, listeners continue from prior checkpoints; cycle/router branches honor resumption flags. + +### State-Based Conditional Logic + +You can use state to implement complex conditional logic in your flows: + +```python +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class PaymentState(BaseModel): + amount: float = 0.0 + is_approved: bool = False + retry_count: int = 0 + +class PaymentFlow(Flow[PaymentState]): + @start() + def process_payment(self): + # Simulate payment processing + self.state.amount = 100.0 + self.state.is_approved = self.state.amount < 1000 + return "Payment processed" + + @router(process_payment) + def check_approval(self, previous_result): + if self.state.is_approved: + return "approved" + elif self.state.retry_count < 3: + return "retry" + else: + return "rejected" + + @listen("approved") + def handle_approval(self): + return f"Payment of ${self.state.amount} approved!" + + @listen("retry") + def handle_retry(self): + self.state.retry_count += 1 + print(f"Retrying payment (attempt {self.state.retry_count})...") + # Could implement retry logic here + return "Retry initiated" + + @listen("rejected") + def handle_rejection(self): + return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries." +``` + +### Handling Complex State Transformations + +For complex state transformations, you can create dedicated methods: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel +from typing import List, Dict + +class UserData(BaseModel): + name: str + active: bool = True + login_count: int = 0 + +class ComplexState(BaseModel): + users: Dict[str, UserData] = {} + active_user_count: int = 0 + +class TransformationFlow(Flow[ComplexState]): + @start() + def initialize(self): + # Add some users + self.add_user("alice", "Alice") + self.add_user("bob", "Bob") + self.add_user("charlie", "Charlie") + return "Initialized" + + @listen(initialize) + def process_users(self, _): + # Increment login counts + for user_id in self.state.users: + self.increment_login(user_id) + + # Deactivate one user + self.deactivate_user("bob") + + # Update active count + self.update_active_count() + + return f"Processed {len(self.state.users)} users" + + # Helper methods for state transformations + def add_user(self, user_id: str, name: str): + self.state.users[user_id] = UserData(name=name) + self.update_active_count() + + def increment_login(self, user_id: str): + if user_id in self.state.users: + self.state.users[user_id].login_count += 1 + + def deactivate_user(self, user_id: str): + if user_id in self.state.users: + self.state.users[user_id].active = False + self.update_active_count() + + def update_active_count(self): + self.state.active_user_count = sum( + 1 for user in self.state.users.values() if user.active + ) +``` + +This pattern of creating helper methods keeps your flow methods clean while enabling complex state manipulations. + +## State Management with Crews + +One of the most powerful patterns in CrewAI is combining flow state management with crew execution. + +### Passing State to Crews + +You can use flow state to parameterize crews: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + +class ResearchState(BaseModel): + topic: str = "" + depth: str = "medium" + results: str = "" + +class ResearchFlow(Flow[ResearchState]): + @start() + def get_parameters(self): + # In a real app, this might come from user input + self.state.topic = "Artificial Intelligence Ethics" + self.state.depth = "deep" + return "Parameters set" + + @listen(get_parameters) + def execute_research(self, _): + # Create agents + researcher = Agent( + role="Research Specialist", + goal=f"Research {self.state.topic} in {self.state.depth} detail", + backstory="You are an expert researcher with a talent for finding accurate information." + ) + + writer = Agent( + role="Content Writer", + goal="Transform research into clear, engaging content", + backstory="You excel at communicating complex ideas clearly and concisely." + ) + + # Create tasks + research_task = Task( + description=f"Research {self.state.topic} with {self.state.depth} analysis", + expected_output="Comprehensive research notes in markdown format", + agent=researcher + ) + + writing_task = Task( + description=f"Create a summary on {self.state.topic} based on the research", + expected_output="Well-written article in markdown format", + agent=writer, + context=[research_task] + ) + + # Create and run crew + research_crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + verbose=True + ) + + # Run crew and store result in state + result = research_crew.kickoff() + self.state.results = result.raw + + return "Research completed" + + @listen(execute_research) + def summarize_results(self, _): + # Access the stored results + result_length = len(self.state.results) + return f"Research on {self.state.topic} completed with {result_length} characters of results." +``` + +### Handling Crew Outputs in State + +When a crew completes, you can process its output and store it in your flow state: + +```python +@listen(execute_crew) +def process_crew_results(self, _): + # Parse the raw results (assuming JSON output) + import json + try: + results_dict = json.loads(self.state.raw_results) + self.state.processed_results = { + "title": results_dict.get("title", ""), + "main_points": results_dict.get("main_points", []), + "conclusion": results_dict.get("conclusion", "") + } + return "Results processed successfully" + except json.JSONDecodeError: + self.state.error = "Failed to parse crew results as JSON" + return "Error processing results" +``` + +## Best Practices for State Management + +### 1. Keep State Focused + +Design your state to contain only what's necessary: + +```python +# Too broad +class BloatedState(BaseModel): + user_data: Dict = {} + system_settings: Dict = {} + temporary_calculations: List = [] + debug_info: Dict = {} + # ...many more fields + +# Better: Focused state +class FocusedState(BaseModel): + user_id: str + preferences: Dict[str, str] + completion_status: Dict[str, bool] +``` + +### 2. Use Structured State for Complex Flows + +As your flows grow in complexity, structured state becomes increasingly valuable: + +```python +# Simple flow can use unstructured state +class SimpleGreetingFlow(Flow): + @start() + def greet(self): + self.state["name"] = "World" + return f"Hello, {self.state['name']}!" + +# Complex flow benefits from structured state +class UserRegistrationState(BaseModel): + username: str + email: str + verification_status: bool = False + registration_date: datetime = Field(default_factory=datetime.now) + last_login: Optional[datetime] = None + +class RegistrationFlow(Flow[UserRegistrationState]): + # Methods with strongly-typed state access +``` + +### 3. Document State Transitions + +For complex flows, document how state changes throughout the execution: + +```python +@start() +def initialize_order(self): + """ + Initialize order state with empty values. + + State before: {} + State after: {order_id: str, items: [], status: 'new'} + """ + self.state.order_id = str(uuid.uuid4()) + self.state.items = [] + self.state.status = "new" + return "Order initialized" +``` + +### 4. Handle State Errors Gracefully + +Implement error handling for state access: + +```python +@listen(previous_step) +def process_data(self, _): + try: + # Try to access a value that might not exist + user_preference = self.state.preferences.get("theme", "default") + except (AttributeError, KeyError): + # Handle the error gracefully + self.state.errors = self.state.get("errors", []) + self.state.errors.append("Failed to access preferences") + user_preference = "default" + + return f"Used preference: {user_preference}" +``` + +### 5. Use State for Progress Tracking + +Leverage state to track progress in long-running flows: + +```python +class ProgressTrackingFlow(Flow): + @start() + def initialize(self): + self.state["total_steps"] = 3 + self.state["current_step"] = 0 + self.state["progress"] = 0.0 + self.update_progress() + return "Initialized" + + def update_progress(self): + """Helper method to calculate and update progress""" + if self.state.get("total_steps", 0) > 0: + self.state["progress"] = (self.state.get("current_step", 0) / + self.state["total_steps"]) * 100 + print(f"Progress: {self.state['progress']:.1f}%") + + @listen(initialize) + def step_one(self, _): + # Do work... + self.state["current_step"] = 1 + self.update_progress() + return "Step 1 complete" + + # Additional steps... +``` + +### 6. Use Immutable Operations When Possible + +Especially with structured state, prefer immutable operations for clarity: + +```python +# Instead of modifying lists in place: +self.state.items.append(new_item) # Mutable operation + +# Consider creating new state: +from pydantic import BaseModel +from typing import List + +class ItemState(BaseModel): + items: List[str] = [] + +class ImmutableFlow(Flow[ItemState]): + @start() + def add_item(self): + # Create new list with the added item + self.state.items = [*self.state.items, "new item"] + return "Item added" +``` + +## Debugging Flow State + +### Logging State Changes + +When developing, add logging to track state changes: + +```python +import logging +logging.basicConfig(level=logging.INFO) + +class LoggingFlow(Flow): + def log_state(self, step_name): + logging.info(f"State after {step_name}: {self.state}") + + @start() + def initialize(self): + self.state["counter"] = 0 + self.log_state("initialize") + return "Initialized" + + @listen(initialize) + def increment(self, _): + self.state["counter"] += 1 + self.log_state("increment") + return f"Incremented to {self.state['counter']}" +``` + +### State Visualization + +You can add methods to visualize your state for debugging: + +```python +def visualize_state(self): + """Create a simple visualization of the current state""" + import json + from rich.console import Console + from rich.panel import Panel + + console = Console() + + if hasattr(self.state, "model_dump"): + # Pydantic v2 + state_dict = self.state.model_dump() + elif hasattr(self.state, "dict"): + # Pydantic v1 + state_dict = self.state.dict() + else: + # Unstructured state + state_dict = dict(self.state) + + # Remove id for cleaner output + if "id" in state_dict: + state_dict.pop("id") + + state_json = json.dumps(state_dict, indent=2, default=str) + console.print(Panel(state_json, title="Current Flow State")) +``` + +## Conclusion + +Mastering state management in CrewAI Flows gives you the power to build sophisticated, robust AI applications that maintain context, make complex decisions, and deliver consistent results. + +Whether you choose unstructured or structured state, implementing proper state management practices will help you create flows that are maintainable, extensible, and effective at solving real-world problems. + +As you develop more complex flows, remember that good state management is about finding the right balance between flexibility and structure, making your code both powerful and easy to understand. + + +You've now mastered the concepts and practices of state management in CrewAI Flows! With this knowledge, you can create robust AI workflows that effectively maintain context, share data between steps, and build sophisticated application logic. + + +## Next Steps + +- Experiment with both structured and unstructured state in your flows +- Try implementing state persistence for long-running workflows +- 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/v1.15.1/en/guides/migration/migrating-from-langgraph.mdx b/docs/v1.15.1/en/guides/migration/migrating-from-langgraph.mdx new file mode 100644 index 000000000..192aa53e4 --- /dev/null +++ b/docs/v1.15.1/en/guides/migration/migrating-from-langgraph.mdx @@ -0,0 +1,518 @@ +--- +title: "Moving from LangGraph to CrewAI: A Practical Guide for Engineers" +description: If you already have built with LangGraph, learn how to quickly port your projects to CrewAI +icon: switch +mode: "wide" +--- + +You've built agents with LangGraph. You've wrestled with `StateGraph`, wired up conditional edges, and debugged state dictionaries at 2 AM. It works — but somewhere along the way, you started wondering if there's a better path to production. + +There is. **CrewAI Flows** gives you the same power — event-driven orchestration, conditional routing, shared state — with dramatically less boilerplate and a mental model that maps cleanly to how you actually think about multi-step AI workflows. + +This article walks through the core concepts side by side, shows real code comparisons, and demonstrates why CrewAI Flows is the framework you'll want to reach for next. + +--- + +## The Mental Model Shift + +LangGraph asks you to think in **graphs**: nodes, edges, and state dictionaries. Every workflow is a directed graph where you explicitly wire transitions between computation steps. It's powerful, but the abstraction carries overhead — especially when your workflow is fundamentally sequential with a few decision points. + +CrewAI Flows asks you to think in **events**: methods that start things, methods that listen for results, and methods that route execution. The topology of your workflow emerges from decorator annotations rather than explicit graph construction. This isn't just syntactic sugar — it changes how you design, read, and maintain your pipelines. + +Here's the core mapping: + +| LangGraph Concept | CrewAI Flows Equivalent | +| --- | --- | +| `StateGraph` class | `Flow` class | +| `add_node()` | Methods decorated with `@start`, `@listen` | +| `add_edge()` / `add_conditional_edges()` | `@listen()` / `@router()` decorators | +| `TypedDict` state | Pydantic `BaseModel` state | +| `START` / `END` constants | `@start()` decorator / natural method return | +| `graph.compile()` | `flow.kickoff()` | +| Checkpointer / persistence | Built-in memory (LanceDB-backed) | + +Let's see what this looks like in practice. + +--- + +## Demo 1: A Simple Sequential Pipeline + +Imagine you're building a pipeline that takes a topic, researches it, writes a summary, and formats the output. Here's how each framework handles it. + +### LangGraph Approach + +```python +from typing import TypedDict +from langgraph.graph import StateGraph, START, END + +class ResearchState(TypedDict): + topic: str + raw_research: str + summary: str + formatted_output: str + +def research_topic(state: ResearchState) -> dict: + # Call an LLM or search API + result = llm.invoke(f"Research the topic: {state['topic']}") + return {"raw_research": result} + +def write_summary(state: ResearchState) -> dict: + result = llm.invoke( + f"Summarize this research:\n{state['raw_research']}" + ) + return {"summary": result} + +def format_output(state: ResearchState) -> dict: + result = llm.invoke( + f"Format this summary as a polished article section:\n{state['summary']}" + ) + return {"formatted_output": result} + +# Build the graph +graph = StateGraph(ResearchState) +graph.add_node("research", research_topic) +graph.add_node("summarize", write_summary) +graph.add_node("format", format_output) + +graph.add_edge(START, "research") +graph.add_edge("research", "summarize") +graph.add_edge("summarize", "format") +graph.add_edge("format", END) + +# Compile and run +app = graph.compile() +result = app.invoke({"topic": "quantum computing advances in 2026"}) +print(result["formatted_output"]) +``` + +You define functions, register them as nodes, and manually wire every transition. For a simple sequence like this, there's a lot of ceremony. + +### CrewAI Flows Approach + +```python +from crewai import LLM, Agent, Crew, Process, Task +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class ResearchState(BaseModel): + topic: str = "" + raw_research: str = "" + summary: str = "" + formatted_output: str = "" + +class ResearchFlow(Flow[ResearchState]): + @start() + def research_topic(self): + # Option 1: Direct LLM call + result = llm.call(f"Research the topic: {self.state.topic}") + self.state.raw_research = result + return result + + @listen(research_topic) + def write_summary(self, research_output): + # Option 2: A single agent + summarizer = Agent( + role="Research Summarizer", + goal="Produce concise, accurate summaries of research content", + backstory="You are an expert at distilling complex research into clear, " + "digestible summaries.", + llm=llm, + verbose=True, + ) + result = summarizer.kickoff( + f"Summarize this research:\n{self.state.raw_research}" + ) + self.state.summary = str(result) + return self.state.summary + + @listen(write_summary) + def format_output(self, summary_output): + # Option 3: a complete crew (with one or more agents) + formatter = Agent( + role="Content Formatter", + goal="Transform research summaries into polished, publication-ready article sections", + backstory="You are a skilled editor with expertise in structuring and " + "presenting technical content for a general audience.", + llm=llm, + verbose=True, + ) + format_task = Task( + description=f"Format this summary as a polished article section:\n{self.state.summary}", + expected_output="A well-structured, polished article section ready for publication.", + agent=formatter, + ) + crew = Crew( + agents=[formatter], + tasks=[format_task], + process=Process.sequential, + verbose=True, + ) + result = crew.kickoff() + self.state.formatted_output = str(result) + return self.state.formatted_output + +# Run the flow +flow = ResearchFlow() +flow.state.topic = "quantum computing advances in 2026" +result = flow.kickoff() +print(flow.state.formatted_output) + +``` + +Notice what's different: no graph construction, no edge wiring, no compile step. The execution order is declared right where the logic lives. `@start()` marks the entry point, and `@listen(method_name)` chains steps together. The state is a proper Pydantic model with type safety, validation, and IDE auto-completion. + +--- + +## Demo 2: Conditional Routing + +This is where things get interesting. Say you're building a content pipeline that routes to different processing paths based on the type of content detected. + +### LangGraph Approach + +```python +from typing import TypedDict, Literal +from langgraph.graph import StateGraph, START, END + +class ContentState(TypedDict): + input_text: str + content_type: str + result: str + +def classify_content(state: ContentState) -> dict: + content_type = llm.invoke( + f"Classify this content as 'technical', 'creative', or 'business':\n{state['input_text']}" + ) + return {"content_type": content_type.strip().lower()} + +def process_technical(state: ContentState) -> dict: + result = llm.invoke(f"Process as technical doc:\n{state['input_text']}") + return {"result": result} + +def process_creative(state: ContentState) -> dict: + result = llm.invoke(f"Process as creative writing:\n{state['input_text']}") + return {"result": result} + +def process_business(state: ContentState) -> dict: + result = llm.invoke(f"Process as business content:\n{state['input_text']}") + return {"result": result} + +# Routing function +def route_content(state: ContentState) -> Literal["technical", "creative", "business"]: + return state["content_type"] + +# Build the graph +graph = StateGraph(ContentState) +graph.add_node("classify", classify_content) +graph.add_node("technical", process_technical) +graph.add_node("creative", process_creative) +graph.add_node("business", process_business) + +graph.add_edge(START, "classify") +graph.add_conditional_edges( + "classify", + route_content, + { + "technical": "technical", + "creative": "creative", + "business": "business", + } +) +graph.add_edge("technical", END) +graph.add_edge("creative", END) +graph.add_edge("business", END) + +app = graph.compile() +result = app.invoke({"input_text": "Explain how TCP handshakes work"}) +``` + +You need a separate routing function, explicit conditional edge mapping, and termination edges for every branch. The routing logic is decoupled from the node that produces the routing decision. + +### CrewAI Flows Approach + +```python +from crewai import LLM, Agent +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class ContentState(BaseModel): + input_text: str = "" + content_type: str = "" + result: str = "" + +class ContentFlow(Flow[ContentState]): + @start() + def classify_content(self): + self.state.content_type = ( + llm.call( + f"Classify this content as 'technical', 'creative', or 'business':\n" + f"{self.state.input_text}" + ) + .strip() + .lower() + ) + return self.state.content_type + + @router(classify_content) + def route_content(self, classification): + if classification == "technical": + return "process_technical" + elif classification == "creative": + return "process_creative" + else: + return "process_business" + + @listen("process_technical") + def handle_technical(self): + agent = Agent( + role="Technical Writer", + goal="Produce clear, accurate technical documentation", + backstory="You are an expert technical writer who specializes in " + "explaining complex technical concepts precisely.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as technical doc:\n{self.state.input_text}") + ) + + @listen("process_creative") + def handle_creative(self): + agent = Agent( + role="Creative Writer", + goal="Craft engaging and imaginative creative content", + backstory="You are a talented creative writer with a flair for " + "compelling storytelling and vivid expression.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as creative writing:\n{self.state.input_text}") + ) + + @listen("process_business") + def handle_business(self): + agent = Agent( + role="Business Writer", + goal="Produce professional, results-oriented business content", + backstory="You are an experienced business writer who communicates " + "strategy and value clearly to professional audiences.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as business content:\n{self.state.input_text}") + ) + +flow = ContentFlow() +flow.state.input_text = "Explain how TCP handshakes work" +flow.kickoff() +print(flow.state.result) + +``` + +The `@router()` decorator turns a method into a decision point. It returns a string that matches a listener — no mapping dictionaries, no separate routing functions. The branching logic reads like a Python `if` statement because it *is* one. + +--- + +## Demo 3: Integrating AI Agent Crews into Flows + +Here's where CrewAI's real power shines. Flows aren't just for chaining LLM calls — they orchestrate full **Crews** of autonomous agents. This is something LangGraph simply doesn't have a native equivalent for. + +```python +from crewai import Agent, Task, Crew +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ArticleState(BaseModel): + topic: str = "" + research: str = "" + draft: str = "" + final_article: str = "" + +class ArticleFlow(Flow[ArticleState]): + + @start() + def run_research_crew(self): + """A full Crew of agents handles research.""" + researcher = Agent( + role="Senior Research Analyst", + goal=f"Produce comprehensive research on: {self.state.topic}", + backstory="You're a veteran analyst known for thorough, " + "well-sourced research reports.", + llm="gpt-4o" + ) + + research_task = Task( + description=f"Research '{self.state.topic}' thoroughly. " + "Cover key trends, data points, and expert opinions.", + expected_output="A detailed research brief with sources.", + agent=researcher + ) + + crew = Crew(agents=[researcher], tasks=[research_task]) + result = crew.kickoff() + self.state.research = result.raw + return result.raw + + @listen(run_research_crew) + def run_writing_crew(self, research_output): + """A different Crew handles writing.""" + writer = Agent( + role="Technical Writer", + goal="Write a compelling article based on provided research.", + backstory="You turn complex research into engaging, clear prose.", + llm="gpt-4o" + ) + + editor = Agent( + role="Senior Editor", + goal="Review and polish articles for publication quality.", + backstory="20 years of editorial experience at top tech publications.", + llm="gpt-4o" + ) + + write_task = Task( + description=f"Write an article based on this research:\n{self.state.research}", + expected_output="A well-structured draft article.", + agent=writer + ) + + edit_task = Task( + description="Review, fact-check, and polish the draft article.", + expected_output="A publication-ready article.", + agent=editor + ) + + crew = Crew(agents=[writer, editor], tasks=[write_task, edit_task]) + result = crew.kickoff() + self.state.final_article = result.raw + return result.raw + +# Run the full pipeline +flow = ArticleFlow() +flow.state.topic = "The Future of Edge AI" +flow.kickoff() +print(flow.state.final_article) +``` + +This is the key insight: **Flows provide the orchestration layer, and Crews provide the intelligence layer.** Each step in a Flow can spin up a full team of collaborating agents, each with their own roles, goals, and tools. You get structured, predictable control flow *and* autonomous agent collaboration — the best of both worlds. + +In LangGraph, achieving something similar means manually implementing agent communication protocols, tool-calling loops, and delegation logic inside your node functions. It's possible, but it's plumbing you're building from scratch every time. + +--- + +## Demo 4: Parallel Execution and Synchronization + +Real-world pipelines often need to fan out work and join the results. CrewAI Flows handles this elegantly with `and_` and `or_` operators. + +```python +from crewai import LLM +from crewai.flow.flow import Flow, and_, listen, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class AnalysisState(BaseModel): + topic: str = "" + market_data: str = "" + tech_analysis: str = "" + competitor_intel: str = "" + final_report: str = "" + +class ParallelAnalysisFlow(Flow[AnalysisState]): + @start() + def start_method(self): + pass + + @listen(start_method) + def gather_market_data(self): + # Your agentic or deterministic code + pass + + @listen(start_method) + def run_tech_analysis(self): + # Your agentic or deterministic code + pass + + @listen(start_method) + def gather_competitor_intel(self): + # Your agentic or deterministic code + pass + + @listen(and_(gather_market_data, run_tech_analysis, gather_competitor_intel)) + def synthesize_report(self): + # Your agentic or deterministic code + pass + +flow = ParallelAnalysisFlow() +flow.state.topic = "AI-powered developer tools" +flow.kickoff() + +``` + +Multiple `@start()` decorators fire in parallel. The `and_()` combinator on the `@listen` decorator ensures `synthesize_report` only executes after *all three* upstream methods complete. There's also `or_()` for when you want to proceed as soon as *any* upstream task finishes. + +In LangGraph, you'd need to build a fan-out/fan-in pattern with parallel branches, a synchronization node, and careful state merging — all wired explicitly through edges. + +--- + +## Why CrewAI Flows for Production + +Beyond cleaner syntax, Flows deliver several production-critical advantages: + +**Built-in state persistence.** Flow state is backed by LanceDB, meaning your workflows can survive crashes, be resumed, and accumulate knowledge across runs. LangGraph requires you to configure a separate checkpointer. + +**Type-safe state management.** Pydantic models give you validation, serialization, and IDE support out of the box. LangGraph's `TypedDict` states don't validate at runtime. + +**First-class agent orchestration.** Crews are a native primitive. You define agents with roles, goals, backstories, and tools — and they collaborate autonomously within the structured envelope of a Flow. No need to reinvent multi-agent coordination. + +**Simpler mental model.** Decorators declare intent. `@start` means "begin here." `@listen(x)` means "run after x." `@router(x)` means "decide where to go after x." The code reads like the workflow it describes. + +**CLI integration.** Run flows with `crewai run`. No separate compilation step, no graph serialization. Your Flow is a Python class, and it runs like one. + +--- + +## Migration Cheat Sheet + +If you're sitting on a LangGraph codebase and want to move to CrewAI Flows, here's a practical conversion guide: + +1. **Map your state.** Convert your `TypedDict` to a Pydantic `BaseModel`. Add default values for all fields. +2. **Convert nodes to methods.** Each `add_node` function becomes a method on your `Flow` subclass. Replace `state["field"]` reads with `self.state.field`. +3. **Replace edges with decorators.** Your `add_edge(START, "first_node")` becomes `@start()` on the first method. Sequential `add_edge("a", "b")` becomes `@listen(a)` on method `b`. +4. **Replace conditional edges with `@router`.** Your routing function and `add_conditional_edges()` mapping become a single `@router()` method that returns a route string. +5. **Replace compile + invoke with kickoff.** Drop `graph.compile()`. Call `flow.kickoff()` instead. +6. **Consider where Crews fit.** Any node where you have complex multi-step agent logic is a candidate for extraction into a Crew. This is where you'll see the biggest quality improvement. + +--- + +## Getting Started + +Install CrewAI and scaffold a new Flow project: + +```bash +pip install crewai +crewai create flow my_first_flow +cd my_first_flow +``` + +This generates a project structure with a ready-to-edit Flow class, configuration files, and a `pyproject.toml` with `type = "flow"` already set. Run it with: + +```bash +crewai run +``` + +From there, add your agents, wire up your listeners, and ship it. + +--- + +## Final Thoughts + +LangGraph taught the ecosystem that AI workflows need structure. That was an important lesson. But CrewAI Flows takes that lesson and delivers it in a form that's faster to write, easier to read, and more powerful in production — especially when your workflows involve multiple collaborating agents. + +If you're building anything beyond a single-agent chain, give Flows a serious look. The decorator-driven model, native Crew integration, and built-in state management mean you'll spend less time on plumbing and more time on the problems that matter. + +Start with `crewai create flow`. You won't look back. diff --git a/docs/v1.15.1/en/guides/migration/upgrading-crewai.mdx b/docs/v1.15.1/en/guides/migration/upgrading-crewai.mdx new file mode 100644 index 000000000..48895a254 --- /dev/null +++ b/docs/v1.15.1/en/guides/migration/upgrading-crewai.mdx @@ -0,0 +1,190 @@ +--- +title: "Upgrading CrewAI" +description: "How to upgrade CrewAI in your project and adapt to breaking changes between versions." +icon: "arrow-up-circle" +--- + +## Overview + +CrewAI releases ship new capabilities regularly. This guide walks you through the practical steps to keep your installation up to date — both the CLI and your project's virtual environment. + +If you're starting fresh, see [Installation](/en/installation). If you're coming from another framework, see [Migrating from LangGraph](/en/guides/migration/migrating-from-langgraph). + +--- + +## The Two Things You Might Want to Upgrade + +CrewAI lives in two places on your machine, and they upgrade independently: + +| What | How it's installed | How to upgrade | +|---|---|---| +| The **global `crewai` CLI** | `uv tool install crewai` | `uv tool install crewai --upgrade` | +| The **project venv** (what your code runs) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` then `crewai install` | + +These can — and often do — get out of sync. Running `crewai --version` tells you the CLI version. Running `uv pip show crewai` inside your project tells you the venv version. If they differ, that's normal; what matters for your running code is the venv version. + +## Why `crewai install` Alone Doesn't Upgrade + +`crewai install` is a thin wrapper around `uv sync`. It installs exactly what the current `uv.lock` file says — it does **not** bump any version constraints. + +If your `pyproject.toml` says `crewai>=1.11.1` and the lock file resolved to `1.11.1`, running `crewai install` will keep you on `1.11.1` forever, even if `1.14.4` is available. + +To actually upgrade, you need to: + +1. Update the version constraint in `pyproject.toml` +2. Re-solve the lock file +3. Sync the venv + +`uv add` does all three in one shot. + +## How to Upgrade Your Project + +```bash +# Bump the constraint and re-lock in one command +uv add "crewai[tools]>=1.14.4" + +# Sync the venv (crewai install calls uv sync under the hood) +crewai install + +# Verify +uv pip show crewai +# → Version: 1.14.4 +``` + +Replace `[tools]` with whatever extras your project uses (e.g. `[tools,anthropic]`). Check your `pyproject.toml` `dependencies` list if you're unsure. + + + `uv add` updates both `pyproject.toml` **and** `uv.lock` atomically. If you edit `pyproject.toml` manually, you still need to run `uv lock --upgrade-package crewai` to re-solve the lock file before `crewai install` will pick up the new version. + + +## Upgrading the Global CLI + +The global CLI is separate from your project. Upgrade it with: + +```bash +uv tool install crewai --upgrade +``` + +If your shell warns about `PATH` after the upgrade, refresh it: + +```bash +uv tool update-shell +``` + +This does **not** touch your project's venv — you still need `uv add` + `crewai install` inside the project. + +## Verify Both Are in Sync + +```bash +# Global CLI version +crewai --version + +# Project venv version +uv pip show crewai | grep Version +``` + +They don't need to match — but your project venv version is what matters for runtime behavior. + + + CrewAI requires `Python >=3.10, <3.14`. If `uv` was installed against an older interpreter, recreate the project venv with a supported Python before running `crewai install`. + + +--- + +## Breaking Changes & Migration Notes + +Most upgrades only require small adjustments. The areas below are the ones that break silently or with confusing tracebacks. + +### Import paths: tools and `BaseTool` + +The canonical import location for tools is `crewai.tools`. Older paths still surface in tutorials but should be updated. + +```python +# Before +from crewai_tools import BaseTool +from crewai.agents.tools import tool + +# After +from crewai.tools import BaseTool, tool +``` + +The `@tool` decorator and `BaseTool` subclass both live in `crewai.tools`. `AgentFinish` and other internal-agent symbols are no longer part of the public surface — if you were importing them, switch to event listeners or `Task` callbacks instead. + +### `Agent` parameter changes + +```python +from crewai import Agent + +agent = Agent( + role="Researcher", + goal="Find authoritative sources on {topic}", + backstory="You are a careful, source-driven researcher.", + llm="gpt-4o-mini", # string model name OR an LLM object + verbose=True, # bool, not an int level + max_iter=15, # default has changed across versions — set explicitly + allow_delegation=False, +) +``` + +- `llm` accepts either a string model name (resolved via the configured provider) or an `LLM` object for fine-grained control. +- `verbose` is a plain `bool`. Passing an integer no longer toggles log levels. +- `max_iter` defaults have shifted between releases. If your agent silently stops looping after the first tool call, set `max_iter` explicitly. + +### `Crew` parameters + +```python +from crewai import Crew, Process + +crew = Crew( + agents=[...], + tasks=[...], + process=Process.sequential, # or Process.hierarchical + memory=True, + cache=True, + embedder={"provider": "openai", "config": {"model": "text-embedding-3-large"}}, +) +``` + +- `process=Process.hierarchical` requires either `manager_llm=` or `manager_agent=`. Without one, kickoff raises at validation time. +- `memory=True` with a non-default embedding provider needs an `embedder` dict — see [Memory & embedder config](#memory-embedder-config) below. + +### `Task` structured output + +Use `output_pydantic`, `output_json`, or `output_file` to coerce a task's result into a typed shape: + +```python +from pydantic import BaseModel +from crewai import Task + +class Article(BaseModel): + title: str + body: str + +write = Task( + description="Write an article about {topic}", + expected_output="A short article with a title and body", + agent=writer, + output_pydantic=Article, # the class, NOT an instance + output_file="output/article.md", +) +``` + +`output_pydantic` takes the **class** itself. Passing `Article(title="", body="")` is a common mistake and fails with a confusing validation error. + +### Memory & embedder config {#memory-embedder-config} + +If `memory=True` and you're not using the default OpenAI `text-embedding-3-large` embeddings, you must pass an `embedder`: + +```python +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={ + "provider": "ollama", + "config": {"model": "nomic-embed-text"}, + }, +) +``` + +Set the relevant provider credentials (`OPENAI_API_KEY`, `OLLAMA_HOST`, etc.) in your `.env` file. Memory storage paths are project-local by default. Existing local memory stores created with 1536-dimensional embeddings may not be compatible with the default OpenAI `text-embedding-3-large` embedder, which uses 3072 dimensions. If you hit a dimension mismatch, delete the project's memory directory, run `crewai reset-memories -m`, or explicitly configure the older embedder model until you migrate. diff --git a/docs/v1.15.1/en/guides/tools/publish-custom-tools.mdx b/docs/v1.15.1/en/guides/tools/publish-custom-tools.mdx new file mode 100644 index 000000000..71dbfd622 --- /dev/null +++ b/docs/v1.15.1/en/guides/tools/publish-custom-tools.mdx @@ -0,0 +1,305 @@ +--- +title: Publish Custom Tools +description: How to build, package, and publish your own CrewAI-compatible tools to PyPI so any CrewAI user can install and use them. +icon: box-open +mode: "wide" +--- + +## Overview + +CrewAI's tool system is designed to be extended. If you've built a tool that could benefit others, you can package it as a standalone Python library, publish it to PyPI, and make it available to any CrewAI user — no PR to the CrewAI repo required. + +This guide walks through the full process: implementing the tools contract, structuring your package, and publishing to PyPI. + + +If you just need a custom tool for your own project, see the [Create Custom Tools](/en/learn/create-custom-tools) guide instead. + + +## The Tools Contract + +Every CrewAI tool must satisfy one of two interfaces: + +### Option 1: Subclass `BaseTool` + +Subclass `crewai.tools.BaseTool` and implement the `_run` method. Define `name`, `description`, and optionally an `args_schema` for input validation. + +```python +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + + +class GeolocateInput(BaseModel): + """Input schema for GeolocateTool.""" + address: str = Field(..., description="The street address to geolocate.") + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + args_schema: type[BaseModel] = GeolocateInput + + def _run(self, address: str) -> str: + # Your implementation here + return f"40.7128, -74.0060" +``` + +### Option 2: Use the `@tool` Decorator + +For simpler tools, the `@tool` decorator turns a function into a CrewAI tool. The function **must** have a docstring (used as the tool description) and type annotations. + +```python +from crewai.tools import tool + + +@tool("Geolocate") +def geolocate(address: str) -> str: + """Converts a street address into latitude/longitude coordinates.""" + return "40.7128, -74.0060" +``` + +### Key Requirements + +Regardless of which approach you use, your tool must: + +- Have a **`name`** — a short, descriptive identifier. +- Have a **`description`** — tells the agent when and how to use the tool. This directly affects how well agents use your tool, so be clear and specific. +- Implement **`_run`** (BaseTool) or provide a **function body** (@tool) — the synchronous execution logic. +- Use **type annotations** on all parameters and return values. +- Return a **string** result, or define an optional Pydantic output schema for structured results. + +### Optional: Async Support + +If your tool performs I/O-bound work, implement `_arun` for async execution: + +```python +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + + def _run(self, address: str) -> str: + # Sync implementation + ... + + async def _arun(self, address: str) -> str: + # Async implementation + ... +``` + +### Optional: Input Validation with `args_schema` + +Define a Pydantic model as your `args_schema` to get automatic input validation and clear error messages. If you don't provide one, CrewAI will infer it from your `_run` method's signature. + +```python +from pydantic import BaseModel, Field + + +class TranslateInput(BaseModel): + """Input schema for TranslateTool.""" + text: str = Field(..., description="The text to translate.") + target_language: str = Field( + default="en", + description="ISO 639-1 language code for the target language.", + ) +``` + +Explicit schemas are recommended for published tools — they produce better agent behavior and clearer documentation for your users. + +### Optional: Typed Outputs with `result_schema` + +If your tool returns structured data, define a Pydantic output model. This is a good default for published tools because users and agents can rely on named fields. + +Direct Python calls still receive the value your tool returns. When an agent uses the tool, CrewAI sends the agent JSON based on the output model. + +CrewAI can infer the output schema from a Pydantic return annotation: + +```python +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + + +class GeolocateResult(BaseModel): + latitude: float = Field(..., description="Latitude in decimal degrees.") + longitude: float = Field(..., description="Longitude in decimal degrees.") + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + + def _run(self, address: str) -> GeolocateResult: + if "1600 Pennsylvania" in address: + return GeolocateResult(latitude=38.8977, longitude=-77.0365) + return GeolocateResult(latitude=40.7128, longitude=-74.0060) +``` + +Set `result_schema` explicitly when your tool returns a dictionary: + +```python +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + result_schema: type[BaseModel] = GeolocateResult + + def _run(self, address: str) -> dict[str, float]: + if "1600 Pennsylvania" in address: + return {"latitude": 38.8977, "longitude": -77.0365} + return {"latitude": 40.7128, "longitude": -74.0060} +``` + +If agents should receive a short text summary instead of JSON, override `format_output_for_agent` on your `BaseTool` subclass. + +```python +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + + def _run(self, address: str) -> GeolocateResult: + if "1600 Pennsylvania" in address: + return GeolocateResult(latitude=38.8977, longitude=-77.0365) + return GeolocateResult(latitude=40.7128, longitude=-74.0060) + + def format_output_for_agent(self, raw_result: object) -> str: + result = GeolocateResult.model_validate(raw_result) + return f"Latitude {result.latitude}, longitude {result.longitude}" +``` + +The override only changes what the agent sees. Direct users of your package still receive the normal value from `tool.run(...)`. + +### Optional: Environment Variables + +If your tool requires API keys or other configuration, declare them with `env_vars` so users know what to set: + +```python +from crewai.tools import BaseTool, EnvVar + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + env_vars: list[EnvVar] = [ + EnvVar( + name="GEOCODING_API_KEY", + description="API key for the geocoding service.", + required=True, + ), + ] + + def _run(self, address: str) -> str: + ... +``` + +## Package Structure + +Structure your project as a standard Python package. Here's a recommended layout: + +``` +crewai-geolocate/ +├── pyproject.toml +├── LICENSE +├── README.md +└── src/ + └── crewai_geolocate/ + ├── __init__.py + └── tools.py +``` + +### `pyproject.toml` + +```toml +[project] +name = "crewai-geolocate" +version = "0.1.0" +description = "A CrewAI tool for geolocating street addresses." +requires-python = ">=3.10" +dependencies = [ + "crewai", +] + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" +``` + +Declare `crewai` as a dependency so users get a compatible version automatically. + +### `__init__.py` + +Re-export your tool classes so users can import them directly: + +```python +from crewai_geolocate.tools import GeolocateTool + +__all__ = ["GeolocateTool"] +``` + +### Naming Conventions + +- **Package name**: Use the prefix `crewai-` (e.g., `crewai-geolocate`). This makes your tool discoverable when users search PyPI. +- **Module name**: Use underscores (e.g., `crewai_geolocate`). +- **Tool class name**: Use PascalCase ending in `Tool` (e.g., `GeolocateTool`). + +## Testing Your Tool + +Before publishing, verify your tool works within a crew: + +```python +from crewai import Agent, Crew, Task +from crewai_geolocate import GeolocateTool + +agent = Agent( + role="Location Analyst", + goal="Find coordinates for given addresses.", + backstory="An expert in geospatial data.", + tools=[GeolocateTool()], +) + +task = Task( + description="Find the coordinates of 1600 Pennsylvania Avenue, Washington, DC.", + expected_output="The latitude and longitude of the address.", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## Publishing to PyPI + +Once your tool is tested and ready: + +```bash +# Build the package +uv build + +# Publish to PyPI +uv publish +``` + +If this is your first time publishing, you'll need a [PyPI account](https://pypi.org/account/register/) and an [API token](https://pypi.org/help/#apitoken). + +### After Publishing + +Users can install your tool with: + +```bash +pip install crewai-geolocate +``` + +Or with uv: + +```bash +uv add crewai-geolocate +``` + +Then use it in their crews: + +```python +from crewai_geolocate import GeolocateTool + +agent = Agent( + role="Location Analyst", + tools=[GeolocateTool()], + # ... +) +``` diff --git a/docs/v1.15.1/en/index.mdx b/docs/v1.15.1/en/index.mdx new file mode 100644 index 000000000..d091196e5 --- /dev/null +++ b/docs/v1.15.1/en/index.mdx @@ -0,0 +1,159 @@ +--- +title: "CrewAI Documentation" +description: "Build collaborative AI agents, crews, and flows — production ready from day one." +icon: "house" +mode: "wide" +--- + +
+ CrewAI +
+

Ship multi‑agent systems with confidence

+

+ Design agents, orchestrate crews, and automate flows with guardrails, memory, knowledge, and observability baked in. +

+
+ +
+ Get started + + View changelog + API Reference +
+ +
+ +
+ +## Get started + + + + Overview of CrewAI concepts, architecture, and what you can build with agents, crews, and flows. + + + Install via `uv`, configure API keys, and set up the CLI for local development. + + + Spin up your first crew in minutes. Learn the core runtime, project layout, and dev loop. + + + +## Build the basics + + + + Compose agents with tools, memory, knowledge, and structured outputs using Pydantic. Includes templates and best practices. + + + Orchestrate start/listen/router steps, manage state, persist execution, and resume long-running workflows. + + + Define sequential, hierarchical, or hybrid processes with guardrails, callbacks, and human-in-the-loop triggers. + + + +## Enterprise journey + + + + Manage environments, redeploy safely, and monitor live runs directly from the Enterprise console. + + + Connect Gmail, Slack, Salesforce, and more. Pass trigger payloads into crews and flows automatically. + + + Invite teammates, configure RBAC, and control access to production automations. + + + +## What’s new + + + + Unified overview for Gmail, Drive, Outlook, Teams, OneDrive, HubSpot, and more — now with sample payloads and crews. + + + Call existing CrewAI automations or Amazon Bedrock Agents directly from your crews using the updated integration toolkit. + + + + + Browse the examples and cookbooks for end-to-end reference implementations across agents, flows, and enterprise automations. + + +## Stay connected + + + + If CrewAI helps you ship faster, give us a star and share your builds with the community. + + + Ask questions, showcase workflows, and request features alongside other builders. + + diff --git a/docs/v1.15.1/en/installation.mdx b/docs/v1.15.1/en/installation.mdx new file mode 100644 index 000000000..381b92c8a --- /dev/null +++ b/docs/v1.15.1/en/installation.mdx @@ -0,0 +1,337 @@ +--- +title: Installation +description: Get started with CrewAI - Install, configure, and build your first AI crew +icon: wrench +mode: "wide" +--- + +
+
+

+ Coding agent setup +

+

Set up CrewAI in your coding agent

+

+ Copy a ready-to-paste setup prompt for Claude Code, Codex, Cursor, or any coding agent. It installs the official CrewAI skills, checks the CLI, and points the agent at the right docs before it edits code. +

+
+ +
+ + + View coding-agent guide + +
+
+ +### Watch: Building CrewAI Agents & Flows with Coding Agent Skills + + + +## Video Tutorial + +Watch this video tutorial for a step-by-step demonstration of the installation process: + + + +## Text Tutorial + + + **Python Version Requirements** + +CrewAI requires `Python >=3.10 and <3.14`. Here's how to check your version: + +```bash +python3 --version +``` + +If you need to update Python, visit [python.org/downloads](https://python.org/downloads) + + + + + **OpenAI SDK Requirement** + +CrewAI 0.175.0 requires `openai >= 1.13.3`. If you manage dependencies yourself, ensure your environment satisfies this constraint to avoid import/runtime issues. + + + +CrewAI uses the `uv` as its dependency management and package handling tool. It simplifies project setup and execution, offering a seamless experience. + +If you haven't installed `uv` yet, follow **step 1** to quickly get it set up on your system, else you can skip to **step 2**. + + + + - **On macOS/Linux:** + + Use `curl` to download the script and execute it with `sh`: + + ```shell + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + If your system doesn't have `curl`, you can use `wget`: + + ```shell + wget -qO- https://astral.sh/uv/install.sh | sh + ``` + + - **On Windows:** + + Use `irm` to download the script and `iex` to execute it: + + ```shell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + If you run into any issues, refer to [UV's installation guide](https://docs.astral.sh/uv/getting-started/installation/) for more information. + + + + - Run the following command to install `crewai` CLI: + ```shell + uv tool install crewai + ``` + + If you encounter a `PATH` warning, run this command to update your shell: + ```shell + uv tool update-shell + ``` + + + + If you encounter the `chroma-hnswlib==0.7.6` build error (`fatal error C1083: Cannot open include file: 'float.h'`) on Windows, install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) with *Desktop development with C++*. + + + - To verify that `crewai` is installed, run: + ```shell + uv tool list + ``` + - You should see something like: + ```shell + crewai v0.102.0 + - crewai + ``` + - If you need to update `crewai`, run: + ```shell + uv tool install crewai --upgrade + ``` + + This upgrades the **global `crewai` CLI tool** only. To upgrade the `crewai` version inside your project's virtual environment, see [Upgrading CrewAI in a project](/en/guides/migration/upgrading-crewai). + + Installation successful! You're ready to create your first crew! 🎉 + + + + +# Creating a CrewAI Project + +`crewai create crew` now creates a JSON-first crew project. Agents live in `agents/*.jsonc`, tasks and crew-level settings live in `crew.jsonc`, and `crewai run` loads that JSON definition directly. + + + + - Run the `crewai` CLI command: + ```shell + crewai create crew + ``` + + - This creates a new project with the following structure: + ``` + my_project/ + ├── .gitignore + ├── .env + ├── agents/ + │ └── researcher.jsonc + ├── crew.jsonc + ├── knowledge/ + ├── pyproject.toml + ├── README.md + ├── skills/ + └── tools/ + ``` + + - If you need the older Python/YAML scaffold with `crew.py`, `config/agents.yaml`, and `config/tasks.yaml`, run: + ```shell + crewai create crew --classic + ``` + + + + + - Your project will contain these essential files: + | File | Purpose | + | --- | --- | + | `crew.jsonc` | Configure the crew, task order, process, and input defaults | + | `agents/*.jsonc` | Define each agent's role, goal, backstory, LLM, tools, and behavior | + | `.env` | Store API keys and environment variables | + | `tools/` | Optional Python files for `custom:` tools | + | `knowledge/` | Optional knowledge files for agents | + | `skills/` | Optional skill files applied to the crew | + + - Start by editing `crew.jsonc` and the files in `agents/` to define your crew's behavior. + - Use `{placeholder}` values in agent and task text, then set defaults in `crew.jsonc` under `inputs`. When you run `crewai run`, the CLI prompts for any missing values. + - Keep sensitive information like API keys in `.env`. + + + + + - Before you run your crew, make sure to run: + ```bash + crewai install + ``` + - If you need to install additional packages, use: + ```shell + uv add + ``` + + As a supply-chain security measure, CrewAI's internal packages use `exclude-newer = "3 days"` in their `pyproject.toml` files. This means transitive dependencies pulled in by CrewAI won't resolve packages released less than 3 days ago. Your own direct dependencies are not affected by this policy. If you notice a transitive dependency is behind, you can pin the version you want explicitly in your project's dependencies. + + - To run your crew, execute the following command in the root of your project: + ```bash + crewai run + ``` + + + +## Enterprise Installation Options + + +For teams and organizations, CrewAI offers enterprise deployment options that eliminate setup complexity: + +### CrewAI AMP (SaaS) + +- Zero installation required - just sign up for free at [app.crewai.com](https://app.crewai.com) +- Automatic updates and maintenance +- Managed infrastructure and scaling +- Build Crews with no Code + +### CrewAI Factory (Self-hosted) + +- Containerized deployment for your infrastructure +- Supports any hyperscaler including on prem deployments +- Integration with your existing security systems + + + Learn about CrewAI's enterprise offerings and schedule a demo + + + +## Next Steps + + + + Follow the quickstart to scaffold a Flow, run a one-agent crew, and produce a report. + + + Connect with other developers, get help, and share your CrewAI experiences. + + diff --git a/docs/v1.15.1/en/introduction.mdx b/docs/v1.15.1/en/introduction.mdx new file mode 100644 index 000000000..a2550ca48 --- /dev/null +++ b/docs/v1.15.1/en/introduction.mdx @@ -0,0 +1,152 @@ +--- +title: Introduction +description: Build AI agent teams that work together to tackle complex tasks +icon: handshake +mode: "wide" +--- + +# What is CrewAI? + +**CrewAI is the leading open-source framework for orchestrating autonomous AI agents and building complex workflows.** + +It empowers developers to build production-ready multi-agent systems by combining the collaborative intelligence of **Crews** with the precise control of **Flows**. + +- **[CrewAI Flows](/en/guides/flows/first-flow)**: The backbone of your AI application. Flows allow you to create structured, event-driven workflows that manage state and control execution. They provide the scaffolding for your AI agents to work within. +- **[CrewAI Crews](/en/guides/crews/first-crew)**: The units of work within your Flow. Crews are teams of autonomous agents that collaborate to solve specific tasks delegated to them by the Flow. + +With over 100,000 developers certified through our community courses, CrewAI is the standard for enterprise-ready AI automation. + +### Watch: Building CrewAI Agents & Flows with Coding Agent Skills + +Install our coding agent skills (Claude Code, Codex, ...) to quickly get your coding agents up and running with CrewAI. + +You can install it with `npx skills add crewaiinc/skills` + + + +## The CrewAI Architecture + +CrewAI's architecture is designed to balance autonomy with control. + +### 1. Flows: The Backbone + + + Think of a Flow as the "manager" or the "process definition" of your application. It defines the steps, the logic, and how data moves through your system. + + + + CrewAI Framework Overview + + +Flows provide: +- **State Management**: Persist data across steps and executions. +- **Event-Driven Execution**: Trigger actions based on events or external inputs. +- **Control Flow**: Use conditional logic, loops, and branching. + +### 2. Crews: The Intelligence + + + Crews are the "teams" that do the heavy lifting. Within a Flow, you can trigger a Crew to tackle a complex problem requiring creativity and collaboration. + + + + CrewAI Framework Overview + + +Crews provide: +- **Role-Playing Agents**: Specialized agents with specific goals and tools. +- **Autonomous Collaboration**: Agents work together to solve tasks. +- **Task Delegation**: Tasks are assigned and executed based on agent capabilities. + +## How It All Works Together + +1. **The Flow** triggers an event or starts a process. +2. **The Flow** manages the state and decides what to do next. +3. **The Flow** delegates a complex task to a **Crew**. +4. **The Crew**'s agents collaborate to complete the task. +5. **The Crew** returns the result to the **Flow**. +6. **The Flow** continues execution based on the result. + +## Key Features + + + + Build reliable, stateful workflows that can handle long-running processes and complex logic. + + + Deploy teams of agents that can plan, execute, and collaborate to achieve high-level goals. + + + Connect your agents to any API, database, or local tool. + + + Designed with security and compliance in mind for enterprise deployments. + + + +## When to Use Crews vs. Flows + +**The short answer: Use both.** + +For any production-ready application, **start with a Flow**. + +- **Use a Flow** to define the overall structure, state, and logic of your application. +- **Use a Crew** within a Flow step when you need a team of agents to perform a specific, complex task that requires autonomy. + +| Use Case | Architecture | +| :--- | :--- | +| **Simple Automation** | Single Flow with Python tasks | +| **Complex Research** | Flow managing state -> Crew performing research | +| **Application Backend** | Flow handling API requests -> Crew generating content -> Flow saving to DB | + +## Why Choose CrewAI? + +- 🧠 **Autonomous Operation**: Agents make intelligent decisions based on their roles and available tools +- 📝 **Natural Interaction**: Agents communicate and collaborate like human team members +- 🛠️ **Extensible Design**: Easy to add new tools, roles, and capabilities +- 🚀 **Production Ready**: Built for reliability and scalability in real-world applications +- 🔒 **Security-Focused**: Designed with enterprise security requirements in mind +- 💰 **Cost-Efficient**: Optimized to minimize token usage and API calls + +## Ready to Start Building? + + + + Learn how to create structured, event-driven workflows with precise control over execution. + + + Step-by-step tutorial to create a collaborative AI team that works together to solve complex problems. + + + + + + Get started with CrewAI in your development environment. + + + Scaffold a Flow, run a crew with one agent, and generate a report end to end. + + + Connect with other developers, get help, and share your CrewAI experiences. + + diff --git a/docs/v1.15.1/en/learn/a2a-agent-delegation.mdx b/docs/v1.15.1/en/learn/a2a-agent-delegation.mdx new file mode 100644 index 000000000..4918e8754 --- /dev/null +++ b/docs/v1.15.1/en/learn/a2a-agent-delegation.mdx @@ -0,0 +1,550 @@ +--- +title: Agent-to-Agent (A2A) Protocol +description: Agents delegate tasks to remote A2A agents and/or operate as A2A-compliant server agents. +icon: network-wired +mode: "wide" +--- + +## A2A Agent Delegation + + + Deploying A2A agents to production? See [A2A on AMP](/en/enterprise/features/a2a) for distributed state, enterprise authentication, gRPC transport, and horizontal scaling. + + +CrewAI treats [A2A protocol](https://a2a-protocol.org/latest/) as a first-class delegation primitive, enabling agents to delegate tasks, request information, and collaborate with remote agents, as well as act as A2A-compliant server agents. +In client mode, agents autonomously choose between local execution and remote delegation based on task requirements. + +## How It Works + +When an agent is configured with A2A capabilities: + +1. The Agent analyzes each task +2. It decides to either: + - Handle the task directly using its own capabilities + - Delegate to a remote A2A agent for specialized handling +3. If delegating, the agent communicates with the remote A2A agent through the protocol +4. Results are returned to the CrewAI workflow + + + A2A delegation requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'` + + +## Basic Configuration + + + `crewai.a2a.config.A2AConfig` is deprecated and will be removed in v2.0.0. Use `A2AClientConfig` for connecting to remote agents and/or `A2AServerConfig` for exposing agents as servers. + + +Configure an agent for A2A delegation by setting the `a2a` parameter: + +```python Code +from crewai import Agent, Crew, Task +from crewai.a2a import A2AClientConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks efficiently", + backstory="Expert at delegating to specialized research agents", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://example.com/.well-known/agent-card.json", + timeout=120, + max_turns=10 + ) +) + +task = Task( + description="Research the latest developments in quantum computing", + expected_output="A comprehensive research report", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task], verbose=True) +result = crew.kickoff() +``` + +## Client Configuration Options + +The `A2AClientConfig` class accepts the following parameters: + + + The A2A agent endpoint URL (typically points to `.well-known/agent-card.json`) + + + + Authentication scheme for the A2A agent. Supports Bearer tokens, OAuth2, API keys, and HTTP authentication. + + + + Request timeout in seconds + + + + Maximum number of conversation turns with the A2A agent + + + + Optional Pydantic model for requesting structured output from an A2A agent. A2A protocol does not + enforce this, so an A2A agent does not need to honor this request. + + + + Whether to raise an error immediately if agent connection fails. When `False`, the agent continues with available agents and informs the LLM about unavailable ones. + + + + When `True`, returns the A2A agent's result directly when it signals completion. When `False`, allows the server agent to review the result and potentially continue the conversation. + + + + Update mechanism for receiving task status. Options: `StreamingConfig`, `PollingConfig`, or `PushNotificationConfig`. + + + + Media types the client can accept in responses. + + + + A2A protocol extension URIs the client supports. + + + + Client-side processing hooks for tool injection, prompt augmentation, and response modification. + + + + Transport configuration including preferred transport, supported transports for negotiation, and protocol-specific settings (gRPC message sizes, keepalive, etc.). + + + + **Deprecated**: Use `transport=ClientTransportConfig(preferred=...)` instead. + + + + **Deprecated**: Use `transport=ClientTransportConfig(supported=...)` instead. + + +## Authentication + +For A2A agents that require authentication, use one of the provided auth schemes: + + + +```python bearer_token_auth.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.auth import BearerTokenAuth + +agent = Agent( + role="Secure Coordinator", + goal="Coordinate tasks with secured agents", + backstory="Manages secure agent communications", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://secure-agent.example.com/.well-known/agent-card.json", + auth=BearerTokenAuth(token="your-bearer-token"), + timeout=120 + ) +) +``` + + + +```python api_key_auth.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.auth import APIKeyAuth + +agent = Agent( + role="API Coordinator", + goal="Coordinate with API-based agents", + backstory="Manages API-authenticated communications", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://api-agent.example.com/.well-known/agent-card.json", + auth=APIKeyAuth( + api_key="your-api-key", + location="header", # or "query" or "cookie" + name="X-API-Key" + ), + timeout=120 + ) +) +``` + + + +```python oauth2_auth.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.auth import OAuth2ClientCredentials + +agent = Agent( + role="OAuth Coordinator", + goal="Coordinate with OAuth-secured agents", + backstory="Manages OAuth-authenticated communications", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://oauth-agent.example.com/.well-known/agent-card.json", + auth=OAuth2ClientCredentials( + token_url="https://auth.example.com/oauth/token", + client_id="your-client-id", + client_secret="your-client-secret", + scopes=["read", "write"] + ), + timeout=120 + ) +) +``` + + + +```python http_basic_auth.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.auth import HTTPBasicAuth + +agent = Agent( + role="Basic Auth Coordinator", + goal="Coordinate with basic auth agents", + backstory="Manages basic authentication communications", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://basic-agent.example.com/.well-known/agent-card.json", + auth=HTTPBasicAuth( + username="your-username", + password="your-password" + ), + timeout=120 + ) +) +``` + + + +## Multiple A2A Agents + +Configure multiple A2A agents for delegation by passing a list: + +```python Code +from crewai.a2a import A2AClientConfig +from crewai.a2a.auth import BearerTokenAuth + +agent = Agent( + role="Multi-Agent Coordinator", + goal="Coordinate with multiple specialized agents", + backstory="Expert at delegating to the right specialist", + llm="gpt-4o", + a2a=[ + A2AClientConfig( + endpoint="https://research.example.com/.well-known/agent-card.json", + timeout=120 + ), + A2AClientConfig( + endpoint="https://data.example.com/.well-known/agent-card.json", + auth=BearerTokenAuth(token="data-token"), + timeout=90 + ) + ] +) +``` + +The LLM will automatically choose which A2A agent to delegate to based on the task requirements. + +## Error Handling + +Control how agent connection failures are handled using the `fail_fast` parameter: + +```python Code +from crewai.a2a import A2AClientConfig + +# Fail immediately on connection errors (default) +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks", + backstory="Expert at delegation", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://research.example.com/.well-known/agent-card.json", + fail_fast=True + ) +) + +# Continue with available agents +agent = Agent( + role="Multi-Agent Coordinator", + goal="Coordinate with multiple agents", + backstory="Expert at working with available resources", + llm="gpt-4o", + a2a=[ + A2AClientConfig( + endpoint="https://primary.example.com/.well-known/agent-card.json", + fail_fast=False + ), + A2AClientConfig( + endpoint="https://backup.example.com/.well-known/agent-card.json", + fail_fast=False + ) + ] +) +``` + +When `fail_fast=False`: +- If some agents fail, the LLM is informed which agents are unavailable and can delegate to working agents +- If all agents fail, the LLM receives a notice about unavailable agents and handles the task directly +- Connection errors are captured and included in the context for better decision-making + +## Update Mechanisms + +Control how your agent receives task status updates from remote A2A agents: + + + +```python streaming_config.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.updates import StreamingConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks", + backstory="Expert at delegation", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://research.example.com/.well-known/agent-card.json", + updates=StreamingConfig() + ) +) +``` + + + +```python polling_config.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.updates import PollingConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks", + backstory="Expert at delegation", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://research.example.com/.well-known/agent-card.json", + updates=PollingConfig( + interval=2.0, + timeout=300.0, + max_polls=100 + ) + ) +) +``` + + + +```python push_notifications_config.py lines +from crewai.a2a import A2AClientConfig +from crewai.a2a.updates import PushNotificationConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks", + backstory="Expert at delegation", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://research.example.com/.well-known/agent-card.json", + updates=PushNotificationConfig( + url="{base_url}/a2a/callback", + token="your-validation-token", + timeout=300.0 + ) + ) +) +``` + + + +## Exposing Agents as A2A Servers + +You can expose your CrewAI agents as A2A-compliant servers, allowing other A2A clients to delegate tasks to them. + +### Server Configuration + +Add an `A2AServerConfig` to your agent to enable server capabilities: + +```python a2a_server_agent.py lines +from crewai import Agent +from crewai.a2a import A2AServerConfig + +agent = Agent( + role="Data Analyst", + goal="Analyze datasets and provide insights", + backstory="Expert data scientist with statistical analysis skills", + llm="gpt-4o", + a2a=A2AServerConfig(url="https://your-server.com") +) +``` + +### Server Configuration Options + + + Human-readable name for the agent. Defaults to the agent's role if not provided. + + + + Human-readable description. Defaults to the agent's goal and backstory if not provided. + + + + Version string for the agent card. + + + + List of agent skills. Auto-generated from agent tools if not provided. + + + + Declaration of optional capabilities supported by the agent. + + + + Supported input MIME types. + + + + Supported output MIME types. + + + + Preferred endpoint URL. If set, overrides the URL passed to `to_agent_card()`. + + + + A2A protocol version this agent supports. + + + + Information about the agent's service provider. + + + + URL to the agent's documentation. + + + + URL to an icon for the agent. + + + + Additional supported interfaces (transport and URL combinations). + + + + Security requirement objects for all agent interactions. + + + + Security schemes available to authorize requests. + + + + Whether agent provides extended card to authenticated users. + + + + Additional skills visible only to authenticated users in the extended agent card. + + + + Configuration for signing the AgentCard with JWS. Supports RS256, ES256, PS256, and related algorithms. + + + + Server-side A2A protocol extensions with `on_request`/`on_response` hooks that modify agent behavior. + + + + Configuration for outgoing push notifications, including HMAC-SHA256 signing secret. + + + + Transport configuration including preferred transport, gRPC server settings, JSON-RPC paths, and HTTP+JSON settings. + + + + Authentication scheme for incoming A2A requests. Defaults to `SimpleTokenAuth` using the `AUTH_TOKEN` environment variable. + + + + **Deprecated**: Use `transport=ServerTransportConfig(preferred=...)` instead. + + + + **Deprecated**: Use `signing_config=AgentCardSigningConfig(...)` instead. + + +### Combined Client and Server + +An agent can act as both client and server by providing both configurations: + +```python Code +from crewai import Agent +from crewai.a2a import A2AClientConfig, A2AServerConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research and serve analysis requests", + backstory="Expert at delegation and analysis", + llm="gpt-4o", + a2a=[ + A2AClientConfig( + endpoint="https://specialist.example.com/.well-known/agent-card.json", + timeout=120 + ), + A2AServerConfig(url="https://your-server.com") + ] +) +``` + +### File Inputs and Structured Output + +A2A supports passing files and requesting structured output in both directions. + +**Client side**: When delegating to a remote A2A agent, files from the task's `input_files` are sent as `FilePart`s in the outgoing message. If `response_model` is set on the `A2AClientConfig`, the Pydantic model's JSON schema is embedded in the message metadata, requesting structured output from the remote agent. + +**Server side**: Incoming `FilePart`s are extracted and passed to the agent's task as `input_files`. If the client included a JSON schema, the server creates a response model from it and applies it to the task. When the agent returns structured data, the response is sent back as a `DataPart` rather than plain text. + +## Best Practices + + + + Configure timeouts based on expected A2A agent response times. Longer-running tasks may need higher timeout values. + + + + Use `max_turns` to prevent excessive back-and-forth. The agent will automatically conclude conversations before hitting the limit. + + + + Set `fail_fast=False` for production environments with multiple agents to gracefully handle connection failures and maintain workflow continuity. + + + + Store authentication tokens and credentials as environment variables, not in code. + + + + Use verbose mode to observe when the LLM chooses to delegate versus handle tasks directly. + + + +## Supported Authentication Methods + +- **Bearer Token** - Simple token-based authentication +- **OAuth2 Client Credentials** - OAuth2 flow for machine-to-machine communication +- **OAuth2 Authorization Code** - OAuth2 flow requiring user authorization +- **API Key** - Key-based authentication (header, query param, or cookie) +- **HTTP Basic** - Username/password authentication +- **HTTP Digest** - Digest authentication (requires `httpx-auth` package) + +## Learn More + +For more information about the A2A protocol and reference implementations: + +- [A2A Protocol Documentation](https://a2a-protocol.org) +- [A2A Sample Implementations](https://github.com/a2aproject/a2a-samples) +- [A2A Python SDK](https://github.com/a2aproject/a2a-python) diff --git a/docs/v1.15.1/en/learn/a2ui.mdx b/docs/v1.15.1/en/learn/a2ui.mdx new file mode 100644 index 000000000..c34dd4b8e --- /dev/null +++ b/docs/v1.15.1/en/learn/a2ui.mdx @@ -0,0 +1,344 @@ +--- +title: Agent-to-UI (A2UI) Protocol +description: Enable agents to generate declarative UI surfaces for rich client rendering via the A2UI extension. +icon: window-restore +mode: "wide" +--- + +## A2UI Overview + +A2UI is a declarative UI protocol extension for [A2A](/en/learn/a2a-agent-delegation) that lets agents emit structured JSON messages describing interactive surfaces. Clients receive these messages and render them as rich UI components — forms, cards, lists, modals, and more — without the agent needing to know anything about the client's rendering stack. + +A2UI is built on the A2A extension mechanism and identified by the URI `https://a2ui.org/a2a-extension/a2ui/v0.8`. + + + A2UI requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'` + + +## How It Works + +1. The **server extension** scans agent output for A2UI JSON objects +2. Valid messages are wrapped as `DataPart` entries with the `application/json+a2ui` MIME type +3. The **client extension** augments the agent's system prompt with A2UI instructions and the component catalog +4. The client tracks surface state (active surfaces and data models) across conversation turns + +## Server Setup + +Add `A2UIServerExtension` to your `A2AServerConfig` to enable A2UI output: + +```python Code +from crewai import Agent +from crewai.a2a import A2AServerConfig +from crewai.a2a.extensions.a2ui import A2UIServerExtension + +agent = Agent( + role="Dashboard Agent", + goal="Present data through interactive UI surfaces", + backstory="Expert at building clear, actionable dashboards", + llm="gpt-4o", + a2a=A2AServerConfig( + url="https://your-server.com", + server_extensions=[A2UIServerExtension()], + ), +) +``` + +### Server Extension Options + + + Component catalog identifiers the server supports. When set, only these catalogs are advertised to clients. + + + + Whether to accept inline catalog definitions from clients in addition to named catalogs. + + +## Client Setup + +Add `A2UIClientExtension` to your `A2AClientConfig` to enable A2UI rendering: + +```python Code +from crewai import Agent +from crewai.a2a import A2AClientConfig +from crewai.a2a.extensions.a2ui import A2UIClientExtension + +agent = Agent( + role="UI Coordinator", + goal="Coordinate tasks and render agent responses as rich UI", + backstory="Expert at presenting agent output in interactive formats", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://dashboard-agent.example.com/.well-known/agent-card.json", + client_extensions=[A2UIClientExtension()], + ), +) +``` + +### Client Extension Options + + + Preferred component catalog identifier. Defaults to `"standard (v0.8)"` when not set. + + + + Restrict which components the agent may use. When `None`, all 18 standard catalog components are available. + + +## Message Types + +A2UI defines four server-to-client message types. Each message targets a **surface** identified by `surfaceId`. + + + + Initializes a new surface with a root component and optional styles. + + ```json + { + "beginRendering": { + "surfaceId": "dashboard-1", + "root": "main-column", + "catalogId": "standard (v0.8)", + "styles": { + "primaryColor": "#EB6658" + } + } + } + ``` + + + + Sends or updates one or more components on an existing surface. + + ```json + { + "surfaceUpdate": { + "surfaceId": "dashboard-1", + "components": [ + { + "id": "main-column", + "component": { + "Column": { + "children": { "explicitList": ["title", "content"] }, + "alignment": "start" + } + } + }, + { + "id": "title", + "component": { + "Text": { + "text": { "literalString": "Dashboard" }, + "usageHint": "h1" + } + } + } + ] + } + } + ``` + + + + Updates the data model bound to a surface, enabling dynamic content. + + ```json + { + "dataModelUpdate": { + "surfaceId": "dashboard-1", + "path": "/data/model", + "contents": [ + { + "key": "userName", + "valueString": "Alice" + }, + { + "key": "score", + "valueNumber": 42 + } + ] + } + } + ``` + + + + Removes a surface and all its components. + + ```json + { + "deleteSurface": { + "surfaceId": "dashboard-1" + } + } + ``` + + + +## Component Catalog + +A2UI ships with 18 standard components organized into three categories: + +### Content + +| Component | Description | Required Fields | +|-----------|-------------|-----------------| +| **Text** | Renders text with optional heading/body hints | `text` (StringBinding) | +| **Image** | Displays an image with fit and size options | `url` (StringBinding) | +| **Icon** | Renders a named icon from a set of 47 icons | `name` (IconBinding) | +| **Video** | Embeds a video player | `url` (StringBinding) | +| **AudioPlayer** | Embeds an audio player with optional description | `url` (StringBinding) | + +### Layout + +| Component | Description | Required Fields | +|-----------|-------------|-----------------| +| **Row** | Horizontal flex container | `children` (ChildrenDef) | +| **Column** | Vertical flex container | `children` (ChildrenDef) | +| **List** | Scrollable list (vertical or horizontal) | `children` (ChildrenDef) | +| **Card** | Elevated container for a single child | `child` (str) | +| **Tabs** | Tabbed container | `tabItems` (list of TabItem) | +| **Divider** | Visual separator (horizontal or vertical) | — | +| **Modal** | Overlay triggered by an entry point | `entryPointChild`, `contentChild` (str) | + +### Interactive + +| Component | Description | Required Fields | +|-----------|-------------|-----------------| +| **Button** | Clickable button that triggers an action | `child` (str), `action` (Action) | +| **CheckBox** | Boolean toggle with a label | `label` (StringBinding), `value` (BooleanBinding) | +| **TextField** | Text input with type and validation options | `label` (StringBinding) | +| **DateTimeInput** | Date and/or time picker | `value` (StringBinding) | +| **MultipleChoice** | Selection from a list of options | `selections` (ArrayBinding), `options` (list) | +| **Slider** | Numeric range slider | `value` (NumberBinding) | + +## Data Binding + +Components reference values through **bindings** rather than raw literals. This allows surfaces to update dynamically when the data model changes. + +There are two ways to bind a value: + +- **Literal values** — hardcoded directly in the component definition +- **Path references** — point to a key in the surface's data model + +```json +{ + "surfaceUpdate": { + "surfaceId": "profile-1", + "components": [ + { + "id": "greeting", + "component": { + "Text": { + "text": { "path": "/data/model/userName" }, + "usageHint": "h2" + } + } + }, + { + "id": "status", + "component": { + "Text": { + "text": { "literalString": "Online" }, + "usageHint": "caption" + } + } + } + ] + } +} +``` + +In this example, `greeting` reads the user's name from the data model (updated via `dataModelUpdate`), while `status` uses a hardcoded literal. + +## Handling User Actions + +Interactive components like `Button` trigger `userAction` events that flow back to the server. Each action includes a `name`, the originating `surfaceId` and `sourceComponentId`, and an optional `context` with key-value pairs. + +```json +{ + "userAction": { + "name": "submitForm", + "surfaceId": "form-1", + "sourceComponentId": "submit-btn", + "timestamp": "2026-03-12T10:00:00Z", + "context": { + "selectedOption": "optionA" + } + } +} +``` + +Action context values can also use path bindings to send current data model values back to the server: + +```json +{ + "Button": { + "child": "confirm-label", + "action": { + "name": "confirm", + "context": [ + { + "key": "currentScore", + "value": { "path": "/data/model/score" } + } + ] + } + } +} +``` + +## Validation + +Use `validate_a2ui_message` to validate server-to-client messages and `validate_a2ui_event` for client-to-server events: + +```python Code +from crewai.a2a.extensions.a2ui import validate_a2ui_message +from crewai.a2a.extensions.a2ui.validator import ( + validate_a2ui_event, + A2UIValidationError, +) + +# Validate a server message +try: + msg = validate_a2ui_message({"beginRendering": {"surfaceId": "s1", "root": "r1"}}) +except A2UIValidationError as exc: + print(exc.errors) + +# Validate a client event +try: + event = validate_a2ui_event({ + "userAction": { + "name": "click", + "surfaceId": "s1", + "sourceComponentId": "btn-1", + "timestamp": "2026-03-12T10:00:00Z", + } + }) +except A2UIValidationError as exc: + print(exc.errors) +``` + +## Best Practices + + + + Begin with a `beginRendering` message and a single `surfaceUpdate`. Add data binding and interactivity once the basic flow works. + + + + Prefer path bindings over literal values for content that changes. Use `dataModelUpdate` to push new values without resending the full component tree. + + + + Use the `allowed_components` option on `A2UIClientExtension` to restrict which components the agent may emit, reducing prompt size and keeping output predictable. + + + + Use `validate_a2ui_message` and `validate_a2ui_event` to catch malformed payloads early, especially when building custom integrations. + + + +## Learn More + +- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — configure agents for remote delegation via the A2A protocol +- [A2A Protocol Documentation](https://a2a-protocol.org) — official protocol specification diff --git a/docs/v1.15.1/en/learn/before-and-after-kickoff-hooks.mdx b/docs/v1.15.1/en/learn/before-and-after-kickoff-hooks.mdx new file mode 100644 index 000000000..a9ce1af6e --- /dev/null +++ b/docs/v1.15.1/en/learn/before-and-after-kickoff-hooks.mdx @@ -0,0 +1,62 @@ +--- +title: Before and After Kickoff Hooks +description: Learn how to use before and after kickoff hooks in CrewAI +mode: "wide" +--- + +CrewAI provides hooks that allow you to execute code before and after a crew's kickoff. These hooks are useful for preprocessing inputs or post-processing results. + +## Before Kickoff Hook + +The before kickoff hook is executed before the crew starts its tasks. It receives the input dictionary and can modify it before passing it to the crew. You can use this hook to set up your environment, load necessary data, or preprocess your inputs. This is useful in scenarios where the input data might need enrichment or validation before being processed by the crew. + +Here's an example of defining a before kickoff function in your `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 + +#... +``` + +In this example, the prepare_data function modifies the inputs by adding a new key-value pair indicating that the inputs have been processed. + +## After Kickoff Hook + +The after kickoff hook is executed after the crew has completed its tasks. It receives the result object, which contains the outputs of the crew's execution. This hook is ideal for post-processing results, such as logging, data transformation, or further analysis. + +Here's how you can define an after kickoff function in your `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 + +# ... +``` + + +In the `log_results` function, the results of the crew execution are simply printed out. You can extend this to perform more complex operations such as sending notifications or integrating with other services. + +## Utilizing Both Hooks + +Both hooks can be used together to provide a comprehensive setup and teardown process for your crew's execution. They are particularly useful in maintaining clean code architecture by separating concerns and enhancing the modularity of your CrewAI implementations. + +## Conclusion + +Before and after kickoff hooks in CrewAI offer powerful ways to interact with the lifecycle of a crew's execution. By understanding and utilizing these hooks, you can greatly enhance the robustness and flexibility of your AI agents. diff --git a/docs/v1.15.1/en/learn/bring-your-own-agent.mdx b/docs/v1.15.1/en/learn/bring-your-own-agent.mdx new file mode 100644 index 000000000..fb7b22dc2 --- /dev/null +++ b/docs/v1.15.1/en/learn/bring-your-own-agent.mdx @@ -0,0 +1,444 @@ +--- +title: Bring your own agent +description: Learn how to bring your own agents that work within a Crew. +icon: robots +mode: "wide" +--- + +Interoperability is a core concept in CrewAI. This guide will show you how to bring your own agents that work within a Crew. + + +## Adapter Guide for Bringing your own agents (Langgraph Agents, OpenAI Agents, etc...) +We require 3 adapters to turn any agent from different frameworks to work within crew. + +1. BaseAgentAdapter +2. BaseToolAdapter +3. BaseConverter + + +## BaseAgentAdapter +This abstract class defines the common interface and functionality that all +agent adapters must implement. It extends BaseAgent to maintain compatibility +with the CrewAI framework while adding adapter-specific requirements. + +Required Methods: + +1. `def configure_tools` +2. `def configure_structured_output` + +## Creating your own Adapter +To integrate an agent from a different framework (e.g., LangGraph, Autogen, OpenAI Assistants) into CrewAI, you need to create a custom adapter by inheriting from `BaseAgentAdapter`. This adapter acts as a compatibility layer, translating between the CrewAI interfaces and the specific requirements of your external agent. + +Here's how you implement your custom adapter: + +1. **Inherit from `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): + # ... implementation details ... + ``` + +2. **Implement `__init__`**: + The constructor should call the parent class constructor `super().__init__(**kwargs)` and perform any initialization specific to your external agent. You can use the optional `agent_config` dictionary passed during CrewAI's `Agent` initialization to configure your adapter and the underlying agent. + + ```python + def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any): + super().__init__(agent_config=agent_config, **kwargs) + # Initialize your external agent here, possibly using agent_config + # Example: self.external_agent = initialize_my_agent(agent_config) + print(f"Initializing MyCustomAgentAdapter with config: {agent_config}") + ``` + +3. **Implement `configure_tools`**: + This abstract method is crucial. It receives a list of CrewAI `BaseTool` instances. Your implementation must convert or adapt these tools into the format expected by your external agent framework. This might involve wrapping them, extracting specific attributes, or registering them with the external agent instance. + + ```python + def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None: + if tools: + adapted_tools = [] + for tool in tools: + # Adapt CrewAI BaseTool to the format your agent expects + # Example: adapted_tool = adapt_to_my_framework(tool) + # adapted_tools.append(adapted_tool) + pass # Replace with your actual adaptation logic + + # Configure the external agent with the adapted tools + # Example: self.external_agent.set_tools(adapted_tools) + print(f"Configuring tools for MyCustomAgentAdapter: {adapted_tools}") # Placeholder + else: + # Handle the case where no tools are provided + # Example: self.external_agent.set_tools([]) + print("No tools provided for MyCustomAgentAdapter.") + ``` + +4. **Implement `configure_structured_output`**: + This method is called when the CrewAI `Agent` is configured with structured output requirements (e.g., `output_json` or `output_pydantic`). Your adapter needs to ensure the external agent is set up to comply with these requirements. This might involve setting specific parameters on the external agent or ensuring its underlying model supports the requested format. If the external agent doesn't support structured output in a way compatible with CrewAI's expectations, you might need to handle the conversion or raise an appropriate error. + + ```python + def configure_structured_output(self, structured_output: Any) -> None: + # Configure your external agent to produce output in the specified format + # Example: self.external_agent.set_output_format(structured_output) + self.adapted_structured_output = True # Signal that structured output is handled + print(f"Configuring structured output for MyCustomAgentAdapter: {structured_output}") + ``` + +By implementing these methods, your `MyCustomAgentAdapter` will allow your custom agent implementation to function correctly within a CrewAI crew, interacting with tasks and tools seamlessly. Remember to replace the example comments and print statements with your actual adaptation logic specific to the external agent framework you are integrating. + +## BaseToolAdapter implementation +The `BaseToolAdapter` class is responsible for converting CrewAI's native `BaseTool` objects into a format that your specific external agent framework can understand and utilize. Different agent frameworks (like LangGraph, OpenAI Assistants, etc.) have their own unique ways of defining and handling tools, and the `BaseToolAdapter` acts as the translator. + +Here's how you implement your custom tool adapter: + +1. **Inherit from `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): + # ... implementation details ... + ``` + +2. **Implement `configure_tools`**: + This is the core abstract method you must implement. It receives a list of CrewAI `BaseTool` instances provided to the agent. Your task is to iterate through this list, adapt each `BaseTool` into the format expected by your external framework, and store the converted tools in the `self.converted_tools` list (which is initialized in the base class constructor). + + ```python + def configure_tools(self, tools: List[BaseTool]) -> None: + """Configure and convert CrewAI tools for the specific implementation.""" + self.converted_tools = [] # Reset in case it's called multiple times + for tool in tools: + # Sanitize the tool name if required by the target framework + sanitized_name = self.sanitize_tool_name(tool.name) + + # --- Your Conversion Logic Goes Here --- + # Example: Convert BaseTool to a dictionary format for LangGraph + # converted_tool = { + # "name": sanitized_name, + # "description": tool.description, + # "parameters": tool.args_schema.schema() if tool.args_schema else {}, + # # Add any other framework-specific fields + # } + + # Example: Convert BaseTool to an OpenAI function definition + # converted_tool = { + # "type": "function", + # "function": { + # "name": sanitized_name, + # "description": tool.description, + # "parameters": tool.args_schema.schema() if tool.args_schema else {"type": "object", "properties": {}}, + # } + # } + + # --- Replace above examples with your actual adaptation --- + converted_tool = self.adapt_tool_to_my_framework(tool, sanitized_name) # Placeholder + + self.converted_tools.append(converted_tool) + print(f"Adapted tool '{tool.name}' to '{sanitized_name}' for MyCustomToolAdapter") # Placeholder + + print(f"MyCustomToolAdapter finished configuring tools: {len(self.converted_tools)} adapted.") # Placeholder + + # --- Helper method for adaptation (Example) --- + def adapt_tool_to_my_framework(self, tool: BaseTool, sanitized_name: str) -> Any: + # Replace this with the actual logic to convert a CrewAI BaseTool + # to the format needed by your specific external agent framework. + # This will vary greatly depending on the target 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 # Or however the framework needs to call it + } + # Also ensure the tool works both sync and async + 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. **Using the Adapter**: + Typically, you would instantiate your `MyCustomToolAdapter` within your `MyCustomAgentAdapter`'s `configure_tools` method and use it to process the tools before configuring your external agent. + + ```python + # Inside MyCustomAgentAdapter.configure_tools + def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None: + if tools: + tool_adapter = MyCustomToolAdapter() # Instantiate your tool adapter + tool_adapter.configure_tools(tools) # Convert the tools + adapted_tools = tool_adapter.tools() # Get the converted tools + + # Now configure your external agent with the adapted_tools + # Example: self.external_agent.set_tools(adapted_tools) + print(f"Configuring external agent with adapted tools: {adapted_tools}") # Placeholder + else: + # Handle no tools case + print("No tools provided for MyCustomAgentAdapter.") + ``` + +By creating a `BaseToolAdapter`, you decouple the tool conversion logic from the agent adaptation, making the integration cleaner and more modular. Remember to replace the placeholder examples with the actual conversion logic required by your specific external agent framework. + +## BaseConverter +The `BaseConverterAdapter` plays a crucial role when a CrewAI `Task` requires an agent to return its final output in a specific structured format, such as JSON or a Pydantic model. It bridges the gap between CrewAI's structured output requirements and the capabilities of your external agent. + +Its primary responsibilities are: +1. **Configuring the Agent for Structured Output:** Based on the `Task`'s requirements (`output_json` or `output_pydantic`), it instructs the associated `BaseAgentAdapter` (and indirectly, the external agent) on what format is expected. +2. **Enhancing the System Prompt:** It modifies the agent's system prompt to include clear instructions on *how* to generate the output in the required structure. +3. **Post-processing the Result:** It takes the raw output from the agent and attempts to parse, validate, and format it according to the required structure, ultimately returning a string representation (e.g., a JSON string). + +Here's how you implement your custom converter adapter: + +1. **Inherit from `BaseConverterAdapter`**: + ```python + from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter + # Assuming you have your MyCustomAgentAdapter defined + # from .my_custom_agent_adapter import MyCustomAgentAdapter + from crewai.task import Task + from typing import Any + + class MyCustomConverterAdapter(BaseConverterAdapter): + # Store the expected output type (e.g., 'json', 'pydantic', 'text') + _output_type: str = 'text' + _output_schema: Any = None # Store JSON schema or Pydantic model + + # ... implementation details ... + ``` + +2. **Implement `__init__`**: + The constructor must accept the corresponding `agent_adapter` instance it will work with. + + ```python + def __init__(self, agent_adapter: Any): # Use your specific AgentAdapter type hint + self.agent_adapter = agent_adapter + print(f"Initializing MyCustomConverterAdapter for agent adapter: {type(agent_adapter).__name__}") + ``` + +3. **Implement `configure_structured_output`**: + This method receives the CrewAI `Task` object. You need to check the task's `output_json` and `output_pydantic` attributes to determine the required output structure. Store this information (e.g., in `_output_type` and `_output_schema`) and potentially call configuration methods on your `self.agent_adapter` if the external agent needs specific setup for structured output (which might have been partially handled in the agent adapter's `configure_structured_output` already). + + ```python + def configure_structured_output(self, task: Task) -> None: + """Configure the expected structured output based on the task.""" + if task.output_pydantic: + self._output_type = 'pydantic' + self._output_schema = task.output_pydantic + print(f"Converter: Configured for Pydantic output: {self._output_schema.__name__}") + elif task.output_json: + self._output_type = 'json' + self._output_schema = task.output_json + print(f"Converter: Configured for JSON output with schema: {self._output_schema}") + else: + self._output_type = 'text' + self._output_schema = None + print("Converter: Configured for standard text output.") + + # Optionally, inform the agent adapter if needed + # self.agent_adapter.set_output_mode(self._output_type, self._output_schema) + ``` + +4. **Implement `enhance_system_prompt`**: + This method takes the agent's base system prompt string and should append instructions tailored to the currently configured `_output_type` and `_output_schema`. The goal is to guide the LLM powering the agent to produce output in the correct format. + + ```python + def enhance_system_prompt(self, base_prompt: str) -> str: + """Enhance the system prompt with structured output instructions.""" + if self._output_type == 'text': + return base_prompt # No enhancement needed for plain text + + instructions = "\n\nYour final answer MUST be formatted as " + if self._output_type == 'json': + schema_str = json.dumps(self._output_schema, indent=2) + instructions += f"a JSON object conforming to the following 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"a JSON object conforming to the Pydantic model '{self._output_schema.__name__}' with the following schema:\n```json\n{schema_str}\n```" + + instructions += "\nEnsure your entire response is ONLY the valid JSON object, without any introductory text, explanations, or concluding remarks." + + print(f"Converter: Enhancing prompt for {self._output_type} output.") + return base_prompt + instructions + ``` + *Note: The exact prompt engineering might need tuning based on the agent/LLM being used.* + +5. **Implement `post_process_result`**: + This method receives the raw string output from the agent. If structured output was requested (`json` or `pydantic`), you should attempt to parse the string into the expected format. Handle potential parsing errors (e.g., log them, attempt simple fixes, or raise an exception). Crucially, the method must **always return a string**, even if the intermediate format was a dictionary or Pydantic object (e.g., by serializing it back to a JSON string). + + ```python + import json + from pydantic import ValidationError + + def post_process_result(self, result: str) -> str: + """Post-process the agent's result to ensure it matches the expected format.""" + print(f"Converter: Post-processing result for {self._output_type} output.") + if self._output_type == 'json': + try: + # Attempt to parse and re-serialize to ensure validity and consistent format + parsed_json = json.loads(result) + # Optional: Validate against self._output_schema if it's a JSON schema dictionary + # from jsonschema import validate + # validate(instance=parsed_json, schema=self._output_schema) + return json.dumps(parsed_json) + except json.JSONDecodeError as e: + print(f"Error: Failed to parse JSON output: {e}\nRaw output:\n{result}") + # Handle error: return raw, raise exception, or try to fix + return result # Example: return raw output on failure + # except Exception as e: # Catch validation errors if using jsonschema + # print(f"Error: JSON output failed schema validation: {e}\nRaw output:\n{result}") + # return result + elif self._output_type == 'pydantic': + try: + # Attempt to parse into the Pydantic model + model_instance = self._output_schema.model_validate_json(result) + # Return the model serialized back to JSON + return model_instance.model_dump_json() + except ValidationError as e: + print(f"Error: Failed to validate Pydantic output: {e}\nRaw output:\n{result}") + # Handle error + return result # Example: return raw output on failure + except json.JSONDecodeError as e: + print(f"Error: Failed to parse JSON for Pydantic model: {e}\nRaw output:\n{result}") + return result + else: # 'text' + return result # No processing needed for plain text + ``` + +By implementing these methods, your `MyCustomConverterAdapter` ensures that structured output requests from CrewAI tasks are correctly handled by your integrated external agent, improving the reliability and usability of your custom agent within the CrewAI framework. + +## Out of the Box Adapters + +We provide out of the box adapters for the following frameworks: +1. LangGraph +2. OpenAI Agents + +## Kicking off a crew with adapted agents: + +```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 + +# CrewAI Agent +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, +) +# Use in 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?"} +) + +# Print raw result first +print("Raw result:", result) + +# Handle result based on its type +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)}") + + # Access fields safely + 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 to raw output + 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/v1.15.1/en/learn/coding-agents.mdx b/docs/v1.15.1/en/learn/coding-agents.mdx new file mode 100644 index 000000000..3bf454ac4 --- /dev/null +++ b/docs/v1.15.1/en/learn/coding-agents.mdx @@ -0,0 +1,96 @@ +--- +title: Coding Agents +description: Learn how to enable your CrewAI Agents to write and execute code, and explore advanced features for enhanced functionality. +icon: rectangle-code +mode: "wide" +--- + +## Introduction + +CrewAI Agents now have the powerful ability to write and execute code, significantly enhancing their problem-solving capabilities. This feature is particularly useful for tasks that require computational or programmatic solutions. + +## Enabling Code Execution + +To enable code execution for an agent, set the `allow_code_execution` parameter to `True` when creating the agent. + +Here's an example: + +```python Code +from crewai import Agent + +coding_agent = Agent( + role="Senior Python Developer", + goal="Craft well-designed and thought-out code", + backstory="You are a senior Python developer with extensive experience in software architecture and best practices.", + allow_code_execution=True +) +``` + + +Note that `allow_code_execution` parameter defaults to `False`. + + +## Important Considerations + +1. **Model Selection**: It is strongly recommended to use more capable models like Claude 3.5 Sonnet and GPT-4 when enabling code execution. +These models have a better understanding of programming concepts and are more likely to generate correct and efficient code. + +2. **Error Handling**: The code execution feature includes error handling. If executed code raises an exception, the agent will receive the error message and can attempt to correct the code or +provide alternative solutions. The `max_retry_limit` parameter, which defaults to 2, controls the maximum number of retries for a task. + +3. **Dependencies**: To use the code execution feature, you need to install the `crewai_tools` package. If not installed, the agent will log an info message: +"Coding tools not available. Install crewai_tools." + +## Code Execution Process + +When an agent with code execution enabled encounters a task requiring programming: + + + + The agent analyzes the task and determines that code execution is necessary. + + + It formulates the Python code needed to solve the problem. + + + The code is sent to the internal code execution tool (`CodeInterpreterTool`). + + + The agent interprets the result and incorporates it into its response or uses it for further problem-solving. + + + +## Example Usage + +Here's a detailed example of creating an agent with code execution capabilities and using it in a task: + +```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) +``` + +In this example, the `coding_agent` can write and execute Python code to perform data analysis tasks. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/conditional-tasks.mdx b/docs/v1.15.1/en/learn/conditional-tasks.mdx new file mode 100644 index 000000000..5c7914fae --- /dev/null +++ b/docs/v1.15.1/en/learn/conditional-tasks.mdx @@ -0,0 +1,90 @@ +--- +title: Conditional Tasks +description: Learn how to use conditional tasks in a crewAI kickoff +icon: diagram-subtask +mode: "wide" +--- + +## Introduction + +Conditional Tasks in crewAI allow for dynamic workflow adaptation based on the outcomes of previous tasks. +This powerful feature enables crews to make decisions and execute tasks selectively, enhancing the flexibility and efficiency of your AI-driven processes. + +## Example Usage + +```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/v1.15.1/en/learn/create-custom-tools.mdx b/docs/v1.15.1/en/learn/create-custom-tools.mdx new file mode 100644 index 000000000..78205bf99 --- /dev/null +++ b/docs/v1.15.1/en/learn/create-custom-tools.mdx @@ -0,0 +1,229 @@ +--- +title: Create Custom Tools +description: Comprehensive guide on crafting, using, and managing custom tools within the CrewAI framework, including new functionalities and error handling. +icon: hammer +mode: "wide" +--- + +## Creating and Utilizing Tools in CrewAI + +This guide provides detailed instructions on creating custom tools for the CrewAI framework and how to efficiently manage and utilize these tools, +incorporating the latest functionalities such as tool delegation, error handling, and dynamic tool calling. It also highlights the importance of collaboration tools, +enabling agents to perform a wide range of actions. + + + **Want to publish your tool for the community?** If you're building a tool that others could benefit from, check out the [Publish Custom Tools](/en/guides/tools/publish-custom-tools) guide to learn how to package and distribute your tool on PyPI. + + +### Subclassing `BaseTool` + +To create a personalized tool, inherit from `BaseTool` and define the necessary attributes, including the `args_schema` for input validation, and the `_run` method. + +```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" +``` + +### Using the `tool` Decorator + +Alternatively, you can use the tool decorator `@tool`. This approach allows you to define the tool's attributes and functionality directly within a function, +offering a concise and efficient way to create specialized tools tailored to your needs. + +```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" +``` + +### Best Practice: Define Typed Outputs + +When a tool returns structured data, define a Pydantic output model. This helps the agent read the result as clear fields instead of guessing from plain text. + +Typed outputs are useful for results with stable fields, such as IDs, status values, scores, prices, or lists. Plain strings are still fine for short prose results. + +Direct Python calls still receive the value your tool returns. When an agent uses a typed tool, CrewAI sends the agent JSON based on the output model. + +#### Return a Pydantic Model + +CrewAI infers the output schema when your `BaseTool` has a Pydantic return annotation. + +```python Code +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class InventoryResult(BaseModel): + sku: str = Field(description="The product SKU.") + quantity: int = Field(description="Units available.") + needs_reorder: bool = Field(description="Whether the item should be reordered.") + +class InventoryTool(BaseTool): + name: str = "Inventory Check" + description: str = "Check current stock for a product SKU." + + def _run(self, sku: str) -> InventoryResult: + quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0) + return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5) + +tool = InventoryTool() +result = tool.run(sku="SKU-123") + +# Direct Python calls receive the raw Pydantic object. +print(result.quantity) +``` + +When an agent calls `InventoryTool`, it receives JSON like this: + +```json +{"sku":"SKU-123","quantity":14,"needs_reorder":false} +``` + +#### Use `result_schema` with Dictionary Results + +If your tool returns a dictionary, set `result_schema` explicitly. You can do this on a `BaseTool` subclass or with the `@tool` decorator: + +```python Code +from crewai.tools import tool +from pydantic import BaseModel, Field + +class ProductResult(BaseModel): + sku: str = Field(description="The product SKU.") + name: str = Field(description="The product name.") + in_stock: bool = Field(description="Whether the product is available.") + +@tool("Product Lookup", result_schema=ProductResult) +def product_lookup(sku: str) -> dict[str, object]: + """Look up product availability by SKU.""" + catalog = { + "SKU-123": ("Noise-canceling headset", True), + "SKU-456": ("USB-C dock", False), + } + name, in_stock = catalog.get(sku, ("Unknown product", False)) + return { + "sku": sku, + "name": name, + "in_stock": in_stock, + } +``` + +#### Customize the Text Sent to the Agent + +By default, typed tool outputs are sent to the agent as JSON. If the agent should receive a short summary instead, subclass `BaseTool` and override `format_output_for_agent`. + +```python Code +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class InventoryResult(BaseModel): + sku: str = Field(description="The product SKU.") + quantity: int = Field(description="Units available.") + needs_reorder: bool = Field(description="Whether the item should be reordered.") + +class InventoryTool(BaseTool): + name: str = "Inventory Check" + description: str = "Check current stock for a product SKU." + + def _run(self, sku: str) -> InventoryResult: + quantity = {"SKU-123": 14, "SKU-456": 0}.get(sku, 0) + return InventoryResult(sku=sku, quantity=quantity, needs_reorder=quantity < 5) + + def format_output_for_agent(self, raw_result: object) -> str: + result = InventoryResult.model_validate(raw_result) + status = "reorder needed" if result.needs_reorder else "stock is healthy" + return f"{result.sku}: {result.quantity} units. {status}." + +tool = InventoryTool() +result = tool.run(sku="SKU-123") + +# Direct Python calls receive the raw Pydantic object. +print(result.quantity) +``` + +The override only changes what the agent sees. Direct calls to `tool.run(...)` still return the normal Python value. + +### Defining a Cache Function for the Tool + +To optimize tool performance with caching, define custom caching strategies using the `cache_function` attribute. + +```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 +``` + +### Creating Async Tools + +CrewAI supports async tools for non-blocking I/O operations. This is useful when your tool needs to make HTTP requests, database queries, or other I/O-bound operations. + +#### Using the `@tool` Decorator with Async Functions + +The simplest way to create an async tool is using the `@tool` decorator with an async function: + +```python Code +import aiohttp +from crewai.tools import tool + +@tool("Async Web Fetcher") +async def fetch_webpage(url: str) -> str: + """Fetch content from a webpage asynchronously.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +#### Subclassing `BaseTool` with Async Support + +For more control, subclass `BaseTool` and implement both `_run` (sync) and `_arun` (async) methods: + +```python Code +import requests +import aiohttp +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class WebFetcherInput(BaseModel): + """Input schema for WebFetcher.""" + url: str = Field(..., description="The URL to fetch") + +class WebFetcherTool(BaseTool): + name: str = "Web Fetcher" + description: str = "Fetches content from a URL" + args_schema: type[BaseModel] = WebFetcherInput + + def _run(self, url: str) -> str: + """Synchronous implementation.""" + return requests.get(url).text + + async def _arun(self, url: str) -> str: + """Asynchronous implementation for non-blocking I/O.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +By adhering to these guidelines and incorporating new functionalities and collaboration tools into your tool creation and management processes, +you can leverage the full capabilities of the CrewAI framework, enhancing both the development experience and the efficiency of your AI agents. diff --git a/docs/v1.15.1/en/learn/custom-llm.mdx b/docs/v1.15.1/en/learn/custom-llm.mdx new file mode 100644 index 000000000..0eee2387a --- /dev/null +++ b/docs/v1.15.1/en/learn/custom-llm.mdx @@ -0,0 +1,351 @@ +--- +title: Custom LLM Implementation +description: Learn how to create custom LLM implementations in CrewAI. +icon: code +mode: "wide" +--- + +## Overview + +CrewAI supports custom LLM implementations through the `BaseLLM` abstract base class. This allows you to integrate any LLM provider that doesn't have built-in support in LiteLLM, or implement custom authentication mechanisms. + +## Quick Start + +Here's a minimal custom LLM implementation: + +```python +from crewai import BaseLLM +from typing import Any, Dict, List, Optional, Union +import requests + +class CustomLLM(BaseLLM): + def __init__(self, model: str, api_key: str, endpoint: str, temperature: Optional[float] = None): + # IMPORTANT: Call super().__init__() with required parameters + super().__init__(model=model, temperature=temperature) + + self.api_key = api_key + self.endpoint = endpoint + + def call( + self, + messages: Union[str, List[Dict[str, str]]], + tools: Optional[List[dict]] = None, + callbacks: Optional[List[Any]] = None, + available_functions: Optional[Dict[str, Any]] = None, + ) -> Union[str, Any]: + """Call the LLM with the given messages.""" + # Convert string to message format if needed + if isinstance(messages, str): + messages = [{"role": "user", "content": messages}] + + # Prepare request + payload = { + "model": self.model, + "messages": messages, + "temperature": self.temperature, + } + + # Add tools if provided and supported + if tools and self.supports_function_calling(): + payload["tools"] = tools + + # Make API call + response = requests.post( + self.endpoint, + headers={ + "Authorization": f"Bearer {self.api_key}", + "Content-Type": "application/json" + }, + json=payload, + timeout=30 + ) + response.raise_for_status() + + result = response.json() + return result["choices"][0]["message"]["content"] + + def supports_function_calling(self) -> bool: + """Override if your LLM supports function calling.""" + return True # Change to False if your LLM doesn't support tools + + def get_context_window_size(self) -> int: + """Return the context window size of your LLM.""" + return 8192 # Adjust based on your model's actual context window +``` + +## Using Your Custom LLM + +```python +from crewai import Agent, Task, Crew + +# Assuming you have the CustomLLM class defined above +# Create your custom LLM +custom_llm = CustomLLM( + model="my-custom-model", + api_key="your-api-key", + endpoint="https://api.example.com/v1/chat/completions", + temperature=0.7 +) + +# Use with an agent +agent = Agent( + role="Research Assistant", + goal="Find and analyze information", + backstory="You are a research assistant.", + llm=custom_llm +) + +# Create and execute tasks +task = Task( + description="Research the latest developments in AI", + expected_output="A comprehensive summary", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## Required Methods + +### Constructor: `__init__()` + +**Critical**: You must call `super().__init__(model, temperature)` with the required parameters: + +```python +def __init__(self, model: str, api_key: str, temperature: Optional[float] = None): + # REQUIRED: Call parent constructor with model and temperature + super().__init__(model=model, temperature=temperature) + + # Your custom initialization + self.api_key = api_key +``` + +### Abstract Method: `call()` + +The `call()` method is the heart of your LLM implementation. It must: + +- Accept messages (string or list of dicts with 'role' and 'content') +- Return a string response +- Handle tools and function calling if supported +- Raise appropriate exceptions for errors + +### Optional Methods + +```python +def supports_function_calling(self) -> bool: + """Return True if your LLM supports function calling.""" + return True # Default is True + +def supports_stop_words(self) -> bool: + """Return True if your LLM supports stop sequences.""" + return True # Default is True + +def get_context_window_size(self) -> int: + """Return the context window size.""" + return 4096 # Default is 4096 +``` + +## Common Patterns + +### Error Handling + +```python +import requests + +def call(self, messages, tools=None, callbacks=None, available_functions=None): + try: + response = requests.post( + self.endpoint, + headers={"Authorization": f"Bearer {self.api_key}"}, + json=payload, + timeout=30 + ) + response.raise_for_status() + return response.json()["choices"][0]["message"]["content"] + + except requests.Timeout: + raise TimeoutError("LLM request timed out") + except requests.RequestException as e: + raise RuntimeError(f"LLM request failed: {str(e)}") + except (KeyError, IndexError) as e: + raise ValueError(f"Invalid response format: {str(e)}") +``` + +### Custom Authentication + +```python +from crewai import BaseLLM +from typing import Optional + +class CustomAuthLLM(BaseLLM): + def __init__(self, model: str, auth_token: str, endpoint: str, temperature: Optional[float] = None): + super().__init__(model=model, temperature=temperature) + self.auth_token = auth_token + self.endpoint = endpoint + + def call(self, messages, tools=None, callbacks=None, available_functions=None): + headers = { + "Authorization": f"Custom {self.auth_token}", # Custom auth format + "Content-Type": "application/json" + } + # Rest of implementation... +``` + +### Stop Words Support + +CrewAI automatically adds `"\nObservation:"` as a stop word to control agent behavior. If your LLM supports stop words: + +```python +def call(self, messages, tools=None, callbacks=None, available_functions=None): + payload = { + "model": self.model, + "messages": messages, + "stop": self.stop # Include stop words in API call + } + # Make API call... + +def supports_stop_words(self) -> bool: + return True # Your LLM supports stop sequences +``` + +If your LLM doesn't support stop words natively: + +```python +def call(self, messages, tools=None, callbacks=None, available_functions=None): + response = self._make_api_call(messages, tools) + content = response["choices"][0]["message"]["content"] + + # Manually truncate at stop words + if self.stop: + for stop_word in self.stop: + if stop_word in content: + content = content.split(stop_word)[0] + break + + return content + +def supports_stop_words(self) -> bool: + return False # Tell CrewAI we handle stop words manually +``` + +## Function Calling + +If your LLM supports function calling, implement the complete flow: + +```python +import json + +def call(self, messages, tools=None, callbacks=None, available_functions=None): + # Convert string to message format + if isinstance(messages, str): + messages = [{"role": "user", "content": messages}] + + # Make API call + response = self._make_api_call(messages, tools) + message = response["choices"][0]["message"] + + # Check for function calls + if "tool_calls" in message and available_functions: + return self._handle_function_calls( + message["tool_calls"], messages, tools, available_functions + ) + + return message["content"] + +def _handle_function_calls(self, tool_calls, messages, tools, available_functions): + """Handle function calling with proper message flow.""" + for tool_call in tool_calls: + function_name = tool_call["function"]["name"] + + if function_name in available_functions: + # Parse and execute function + function_args = json.loads(tool_call["function"]["arguments"]) + function_result = available_functions[function_name](**function_args) + + # Add function call and result to message history + messages.append({ + "role": "assistant", + "content": None, + "tool_calls": [tool_call] + }) + messages.append({ + "role": "tool", + "tool_call_id": tool_call["id"], + "name": function_name, + "content": str(function_result) + }) + + # Call LLM again with updated context + return self.call(messages, tools, None, available_functions) + + return "Function call failed" +``` + +## Troubleshooting + +### Common Issues + +**Constructor Errors** +```python +# ❌ Wrong - missing required parameters +def __init__(self, api_key: str): + super().__init__() + +# ✅ Correct +def __init__(self, model: str, api_key: str, temperature: Optional[float] = None): + super().__init__(model=model, temperature=temperature) +``` + +**Function Calling Not Working** +- Ensure `supports_function_calling()` returns `True` +- Check that you handle `tool_calls` in the response +- Verify `available_functions` parameter is used correctly + +**Authentication Failures** +- Verify API key format and permissions +- Check authentication header format +- Ensure endpoint URLs are correct + +**Response Parsing Errors** +- Validate response structure before accessing nested fields +- Handle cases where content might be None +- Add proper error handling for malformed responses + +## Testing Your Custom LLM + +```python +from crewai import Agent, Task, Crew + +def test_custom_llm(): + llm = CustomLLM( + model="test-model", + api_key="test-key", + endpoint="https://api.test.com" + ) + + # Test basic call + result = llm.call("Hello, world!") + assert isinstance(result, str) + assert len(result) > 0 + + # Test with CrewAI agent + agent = Agent( + role="Test Agent", + goal="Test custom LLM", + backstory="A test agent.", + llm=llm + ) + + task = Task( + description="Say hello", + expected_output="A greeting", + agent=agent + ) + + crew = Crew(agents=[agent], tasks=[task]) + result = crew.kickoff() + assert "hello" in result.raw.lower() +``` + +This guide covers the essentials of implementing custom LLMs in CrewAI. diff --git a/docs/v1.15.1/en/learn/custom-manager-agent.mdx b/docs/v1.15.1/en/learn/custom-manager-agent.mdx new file mode 100644 index 000000000..7b936da18 --- /dev/null +++ b/docs/v1.15.1/en/learn/custom-manager-agent.mdx @@ -0,0 +1,91 @@ +--- +title: Custom Manager Agent +description: Learn how to set a custom agent as the manager in CrewAI, providing more control over task management and coordination. +icon: user-shield +mode: "wide" +--- + +# Setting a Specific Agent as Manager in CrewAI + +CrewAI allows users to set a specific agent as the manager of the crew, providing more control over the management and coordination of tasks. +This feature enables the customization of the managerial role to better fit your project's requirements. + +## Using the `manager_agent` Attribute + +### Custom Manager Agent + +The `manager_agent` attribute allows you to define a custom agent to manage the crew. This agent will oversee the entire process, ensuring that tasks are completed efficiently and to the highest standard. + +### Example + +```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() +``` + +## Benefits of a Custom Manager Agent + +- **Enhanced Control**: Tailor the management approach to fit the specific needs of your project. +- **Improved Coordination**: Ensure efficient task coordination and management by an experienced agent. +- **Customizable Management**: Define managerial roles and responsibilities that align with your project's goals. + +## Setting a Manager LLM + +If you're using the hierarchical process and don't want to set a custom manager agent, you can specify the language model for the manager: + +```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 +) +``` + + +Either `manager_agent` or `manager_llm` must be set when using the hierarchical process. + \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/customizing-agents.mdx b/docs/v1.15.1/en/learn/customizing-agents.mdx new file mode 100644 index 000000000..8364b5637 --- /dev/null +++ b/docs/v1.15.1/en/learn/customizing-agents.mdx @@ -0,0 +1,112 @@ +--- +title: Customize Agents +description: A comprehensive guide to tailoring agents for specific roles, tasks, and advanced customizations within the CrewAI framework. +icon: user-pen +mode: "wide" +--- + +## Customizable Attributes + +Crafting an efficient CrewAI team hinges on the ability to dynamically tailor your AI agents to meet the unique requirements of any project. This section covers the foundational attributes you can customize. + +### Key Attributes for Customization + +| Attribute | Description | +|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Role** | Specifies the agent's job within the crew, such as 'Analyst' or 'Customer Service Rep'. | +| **Goal** | Defines the agent’s objectives, aligned with its role and the crew’s overarching mission. | +| **Backstory** | Provides depth to the agent's persona, enhancing motivations and engagements within the crew. | +| **Tools** *(Optional)* | Represents the capabilities or methods the agent uses for tasks, from simple functions to complex integrations. | +| **Cache** *(Optional)* | Determines if the agent should use a cache for tool usage. | +| **Max RPM** | Sets the maximum requests per minute (`max_rpm`). Can be set to `None` for unlimited requests to external services. | +| **Verbose** *(Optional)* | Enables detailed logging for debugging and optimization, providing insights into execution processes. | +| **Allow Delegation** *(Optional)* | Controls task delegation to other agents, default is `False`. | +| **Max Iter** *(Optional)* | Limits the maximum number of iterations (`max_iter`) for a task to prevent infinite loops, with a default of 25. | +| **Max Execution Time** *(Optional)* | Sets the maximum time allowed for an agent to complete a task. | +| **System Template** *(Optional)* | Defines the system format for the agent. | +| **Prompt Template** *(Optional)* | Defines the prompt format for the agent. | +| **Response Template** *(Optional)* | Defines the response format for the agent. | +| **Use System Prompt** *(Optional)* | Controls whether the agent will use a system prompt during task execution. | +| **Respect Context Window** | Enables a sliding context window by default, maintaining context size. | +| **Max Retry Limit** | Sets the maximum number of retries (`max_retry_limit`) for an agent in case of errors. | + +## Advanced Customization Options + +Beyond the basic attributes, CrewAI allows for deeper customization to enhance an agent's behavior and capabilities significantly. + +### Language Model Customization + +Agents can be customized with specific language models (`llm`) and function-calling language models (`function_calling_llm`), offering advanced control over their processing and decision-making abilities. +It's important to note that setting the `function_calling_llm` allows for overriding the default crew function-calling language model, providing a greater degree of customization. + +## Performance and Debugging Settings + +Adjusting an agent's performance and monitoring its operations are crucial for efficient task execution. + +### Verbose Mode and RPM Limit + +- **Verbose Mode**: Enables detailed logging of an agent's actions, useful for debugging and optimization. Specifically, it provides insights into agent execution processes, aiding in the optimization of performance. +- **RPM Limit**: Sets the maximum number of requests per minute (`max_rpm`). This attribute is optional and can be set to `None` for no limit, allowing for unlimited queries to external services if needed. + +### Maximum Iterations for Task Execution + +The `max_iter` attribute allows users to define the maximum number of iterations an agent can perform for a single task, preventing infinite loops or excessively long executions. +The default value is set to 25, providing a balance between thoroughness and efficiency. Once the agent approaches this number, it will try its best to give a good answer. + +## Customizing Agents and Tools + +Agents are customized by defining their attributes and tools during initialization. Tools are critical for an agent's functionality, enabling them to perform specialized tasks. +The `tools` attribute should be an array of tools the agent can utilize, and it's initialized as an empty list by default. Tools can be added or modified post-agent initialization to adapt to new requirements. + +```shell +pip install 'crewai[tools]' +``` + +### Example: Assigning Tools to an Agent + +```python Code +import os +from crewai import Agent +from crewai_tools import SerperDevTool + +# Set API keys for tool initialization +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" + +# Initialize a search tool +search_tool = SerperDevTool() + +# Initialize the agent with advanced options +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, # Enable memory + verbose=True, + max_rpm=None, # No limit on requests per minute + max_iter=25, # Default value for maximum iterations +) +``` + +## Delegation and Autonomy + +Controlling an agent's ability to delegate tasks or ask questions is vital for tailoring its autonomy and collaborative dynamics within the CrewAI framework. By default, +the `allow_delegation` attribute is now set to `False`, disabling agents to seek assistance or delegate tasks as needed. This default behavior can be changed to promote collaborative problem-solving and +efficiency within the CrewAI ecosystem. If needed, delegation can be enabled to suit specific operational requirements. + +### Example: Disabling Delegation for an Agent + +```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 # Enabling delegation +) +``` + +## Conclusion + +Customizing agents in CrewAI by setting their roles, goals, backstories, and tools, alongside advanced options like language model customization, memory, performance settings, and delegation preferences, +equips a nuanced and capable AI team ready for complex challenges. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/dalle-image-generation.mdx b/docs/v1.15.1/en/learn/dalle-image-generation.mdx new file mode 100644 index 000000000..a39e3d899 --- /dev/null +++ b/docs/v1.15.1/en/learn/dalle-image-generation.mdx @@ -0,0 +1,74 @@ +--- +title: "Image Generation with DALL-E" +description: "Learn how to use DALL-E for AI-powered image generation in your CrewAI projects" +icon: "image" +mode: "wide" +--- + +CrewAI supports integration with OpenAI's DALL-E, allowing your AI agents to generate images as part of their tasks. This guide will walk you through how to set up and use the DALL-E tool in your CrewAI projects. + +## Prerequisites + +- crewAI installed (latest version) +- OpenAI API key with access to DALL-E + +## Setting Up the DALL-E Tool + + + + ```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 + ) + ``` + + + +## Using the DALL-E Tool + +Once you've added the DALL-E tool to your agent, it can generate images based on text prompts. The tool will return a URL to the generated image, which can be used in the agent's output or passed to other agents for further processing. + +### Example Agent Configuration + +```yaml +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. +``` + +### Expected Output + +The agent with the DALL-E tool will be able to generate the image and provide a URL in its response. You can then download the image. + + + DALL-E Image + + +## Best Practices + +1. **Be specific in your image generation prompts** to get the best results. +2. **Consider generation time** - Image generation can take some time, so factor this into your task planning. +3. **Follow usage policies** - Always comply with OpenAI's usage policies when generating images. + +## Troubleshooting + +1. **Check API access** - Ensure your OpenAI API key has access to DALL-E. +2. **Version compatibility** - Check that you're using the latest version of crewAI and crewai-tools. +3. **Tool configuration** - Verify that the DALL-E tool is correctly added to the agent's tool list. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/execution-hooks.mdx b/docs/v1.15.1/en/learn/execution-hooks.mdx new file mode 100644 index 000000000..f9f667e4f --- /dev/null +++ b/docs/v1.15.1/en/learn/execution-hooks.mdx @@ -0,0 +1,525 @@ +--- +title: Execution Hooks Overview +description: Understanding and using execution hooks in CrewAI for fine-grained control over agent operations +mode: "wide" +--- + +Execution Hooks provide fine-grained control over the runtime behavior of your CrewAI agents. Unlike kickoff hooks that run before and after crew execution, execution hooks intercept specific operations during agent execution, allowing you to modify behavior, implement safety checks, and add comprehensive monitoring. + +## Types of Execution Hooks + +CrewAI provides two main categories of execution hooks: + +### 1. [LLM Call Hooks](/learn/llm-hooks) + +Control and monitor language model interactions: +- **Before LLM Call**: Modify prompts, validate inputs, implement approval gates +- **After LLM Call**: Transform responses, sanitize outputs, update conversation history + +**Use Cases:** +- Iteration limiting +- Cost tracking and token usage monitoring +- Response sanitization and content filtering +- Human-in-the-loop approval for LLM calls +- Adding safety guidelines or context +- Debug logging and request/response inspection + +[View LLM Hooks Documentation →](/learn/llm-hooks) + +### 2. [Tool Call Hooks](/learn/tool-hooks) + +Control and monitor tool execution: +- **Before Tool Call**: Modify inputs, validate parameters, block dangerous operations +- **After Tool Call**: Transform results, sanitize outputs, log execution details + +**Use Cases:** +- Safety guardrails for destructive operations +- Human approval for sensitive actions +- Input validation and sanitization +- Result caching and rate limiting +- Tool usage analytics +- Debug logging and monitoring + +[View Tool Hooks Documentation →](/learn/tool-hooks) + +## Hook Registration Methods + +### 1. Decorator-Based Hooks (Recommended) + +The cleanest and most Pythonic way to register hooks: + +```python +from crewai.hooks import before_llm_call, after_llm_call, before_tool_call, after_tool_call + +@before_llm_call +def limit_iterations(context): + """Prevent infinite loops by limiting iterations.""" + if context.iterations > 10: + return False # Block execution + return None + +@after_llm_call +def sanitize_response(context): + """Remove sensitive data from LLM responses.""" + if "API_KEY" in context.response: + return context.response.replace("API_KEY", "[REDACTED]") + return None + +@before_tool_call +def block_dangerous_tools(context): + """Block destructive operations.""" + if context.tool_name == "delete_database": + return False # Block execution + return None + +@after_tool_call +def log_tool_result(context): + """Log tool execution.""" + print(f"Tool {context.tool_name} completed") + return None +``` + +### 2. Crew-Scoped Hooks + +Apply hooks only to specific crew instances: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # Only applies to this crew + print(f"LLM call in {self.__class__.__name__}") + return None + + @after_tool_call_crew + def log_results(self, context): + # Crew-specific logging + print(f"Tool result: {context.tool_result[:50]}...") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential + ) +``` + +## Hook Execution Flow + +### LLM Call Flow + +``` +Agent needs to call LLM + ↓ +[Before LLM Call Hooks Execute] + ├→ Hook 1: Validate iteration count + ├→ Hook 2: Add safety context + └→ Hook 3: Log request + ↓ +If any hook returns False: + ├→ Block LLM call + └→ Raise ValueError + ↓ +If all hooks return True/None: + ├→ LLM call proceeds + └→ Response generated + ↓ +[After LLM Call Hooks Execute] + ├→ Hook 1: Sanitize response + ├→ Hook 2: Log response + └→ Hook 3: Update metrics + ↓ +Final response returned +``` + +### Tool Call Flow + +``` +Agent needs to execute tool + ↓ +[Before Tool Call Hooks Execute] + ├→ Hook 1: Check if tool is allowed + ├→ Hook 2: Validate inputs + └→ Hook 3: Request approval if needed + ↓ +If any hook returns False: + ├→ Block tool execution + └→ Return error message + ↓ +If all hooks return True/None: + ├→ Tool execution proceeds + └→ Result generated + ↓ +[After Tool Call Hooks Execute] + ├→ Hook 1: Sanitize result + ├→ Hook 2: Cache result + └→ Hook 3: Log metrics + ↓ +Final result returned +``` + +## Hook Context Objects + +### LLMCallHookContext + +Provides access to LLM execution state: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # Full executor access + messages: list # Mutable message list + agent: Agent # Current agent + task: Task # Current task + crew: Crew # Crew instance + llm: BaseLLM # LLM instance + iterations: int # Current iteration + response: str | None # LLM response (after hooks) +``` + +### ToolCallHookContext + +Provides access to tool execution state: + +```python +class ToolCallHookContext: + tool_name: str # Tool being called + tool_input: dict # Mutable input parameters + tool: CrewStructuredTool # Tool instance + agent: Agent | None # Agent executing + task: Task | None # Current task + crew: Crew | None # Crew instance + tool_result: str | None # Agent-facing result string (after hooks) + raw_tool_result: Any | None # Raw Python result (after hooks) +``` + +For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. `raw_tool_result` is the original Python value returned by the tool. + +## Common Patterns + +### Safety and Validation + +```python +@before_tool_call +def safety_check(context): + """Block destructive operations.""" + dangerous = ['delete_file', 'drop_table', 'system_shutdown'] + if context.tool_name in dangerous: + print(f"🛑 Blocked: {context.tool_name}") + return False + return None + +@before_llm_call +def iteration_limit(context): + """Prevent infinite loops.""" + if context.iterations > 15: + print("⛔ Maximum iterations exceeded") + return False + return None +``` + +### Human-in-the-Loop + +```python +@before_tool_call +def require_approval(context): + """Require approval for sensitive operations.""" + sensitive = ['send_email', 'make_payment', 'post_message'] + + if context.tool_name in sensitive: + response = context.request_human_input( + prompt=f"Approve {context.tool_name}?", + default_message="Type 'yes' to approve:" + ) + + if response.lower() != 'yes': + return False + + return None +``` + +### Monitoring and Analytics + +```python +from collections import defaultdict +import time + +metrics = defaultdict(lambda: {'count': 0, 'total_time': 0}) + +@before_tool_call +def start_timer(context): + context.tool_input['_start'] = time.time() + return None + +@after_tool_call +def track_metrics(context): + start = context.tool_input.get('_start', time.time()) + duration = time.time() - start + + metrics[context.tool_name]['count'] += 1 + metrics[context.tool_name]['total_time'] += duration + + return None + +# View metrics +def print_metrics(): + for tool, data in metrics.items(): + avg = data['total_time'] / data['count'] + print(f"{tool}: {data['count']} calls, {avg:.2f}s avg") +``` + +### Response Sanitization + +```python +import re + +@after_llm_call +def sanitize_llm_response(context): + """Remove sensitive data from LLM responses.""" + if not context.response: + return None + + result = context.response + result = re.sub(r'(api[_-]?key)["\']?\s*[:=]\s*["\']?[\w-]+', + r'\1: [REDACTED]', result, flags=re.IGNORECASE) + return result + +@after_tool_call +def sanitize_tool_result(context): + """Remove sensitive data from tool results.""" + if not context.tool_result: + return None + + result = context.tool_result + result = re.sub(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '[EMAIL-REDACTED]', result) + return result +``` + +## Hook Management + +### Clearing All Hooks + +```python +from crewai.hooks import clear_all_global_hooks + +# Clear all hooks at once +result = clear_all_global_hooks() +print(f"Cleared {result['total']} hooks") +# Output: {'llm_hooks': (2, 1), 'tool_hooks': (1, 2), 'total': (3, 3)} +``` + +### Clearing Specific Hook Types + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_before_tool_call_hooks, + clear_after_tool_call_hooks +) + +# Clear specific types +llm_before_count = clear_before_llm_call_hooks() +tool_after_count = clear_after_tool_call_hooks() +``` + +### Unregistering Individual Hooks + +```python +from crewai.hooks import ( + unregister_before_llm_call_hook, + unregister_after_tool_call_hook +) + +def my_hook(context): + ... + +# Register +register_before_llm_call_hook(my_hook) + +# Later, unregister +success = unregister_before_llm_call_hook(my_hook) +print(f"Unregistered: {success}") +``` + +## Best Practices + +### 1. Keep Hooks Focused +Each hook should have a single, clear responsibility: + +```python +# ✅ Good - focused responsibility +@before_tool_call +def validate_file_path(context): + if context.tool_name == 'read_file': + if '..' in context.tool_input.get('path', ''): + return False + return None + +# ❌ Bad - too many responsibilities +@before_tool_call +def do_everything(context): + # Validation + logging + metrics + approval... + ... +``` + +### 2. Handle Errors Gracefully + +```python +@before_llm_call +def safe_hook(context): + try: + # Your logic + if some_condition: + return False + except Exception as e: + print(f"Hook error: {e}") + return None # Allow execution despite error +``` + +### 3. Modify Context In-Place + +```python +# ✅ Correct - modify in-place +@before_llm_call +def add_context(context): + context.messages.append({"role": "system", "content": "Be concise"}) + +# ❌ Wrong - replaces reference +@before_llm_call +def wrong_approach(context): + context.messages = [{"role": "system", "content": "Be concise"}] +``` + +### 4. Use Type Hints + +```python +from crewai.hooks import LLMCallHookContext, ToolCallHookContext + +def my_llm_hook(context: LLMCallHookContext) -> bool | None: + # IDE autocomplete and type checking + return None + +def my_tool_hook(context: ToolCallHookContext) -> str | None: + return None +``` + +### 5. Clean Up in Tests + +```python +import pytest +from crewai.hooks import clear_all_global_hooks + +@pytest.fixture(autouse=True) +def clean_hooks(): + """Reset hooks before each test.""" + yield + clear_all_global_hooks() +``` + +## When to Use Which Hook + +### Use LLM Hooks When: +- Implementing iteration limits +- Adding context or safety guidelines to prompts +- Tracking token usage and costs +- Sanitizing or transforming responses +- Implementing approval gates for LLM calls +- Debugging prompt/response interactions + +### Use Tool Hooks When: +- Blocking dangerous or destructive operations +- Validating tool inputs before execution +- Implementing approval gates for sensitive actions +- Caching tool results +- Tracking tool usage and performance +- Sanitizing tool outputs +- Rate limiting tool calls + +### Use Both When: +Building comprehensive observability, safety, or approval systems that need to monitor all agent operations. + +## Alternative Registration Methods + +### Programmatic Registration (Advanced) + +For dynamic hook registration or when you need to register hooks programmatically: + +```python +from crewai.hooks import ( + register_before_llm_call_hook, + register_after_tool_call_hook +) + +def my_hook(context): + return None + +# Register programmatically +register_before_llm_call_hook(my_hook) + +# Useful for: +# - Loading hooks from configuration +# - Conditional hook registration +# - Plugin systems +``` + +**Note:** For most use cases, decorators are cleaner and more maintainable. + +## Performance Considerations + +1. **Keep Hooks Fast**: Hooks execute on every call - avoid heavy computation +2. **Cache When Possible**: Store expensive validations or lookups +3. **Be Selective**: Use crew-scoped hooks when global hooks aren't needed +4. **Monitor Hook Overhead**: Profile hook execution time in production +5. **Lazy Import**: Import heavy dependencies only when needed + +## Debugging Hooks + +### Enable Debug Logging + +```python +import logging + +logging.basicConfig(level=logging.DEBUG) +logger = logging.getLogger(__name__) + +@before_llm_call +def debug_hook(context): + logger.debug(f"LLM call: {context.agent.role}, iteration {context.iterations}") + return None +``` + +### Hook Execution Order + +Hooks execute in registration order. If a before hook returns `False`, subsequent hooks don't execute: + +```python +# Register order matters! +register_before_tool_call_hook(hook1) # Executes first +register_before_tool_call_hook(hook2) # Executes second +register_before_tool_call_hook(hook3) # Executes third + +# If hook2 returns False: +# - hook1 executed +# - hook2 executed and returned False +# - hook3 NOT executed +# - Tool call blocked +``` + +## Related Documentation + +- [LLM Call Hooks →](/learn/llm-hooks) - Detailed LLM hook documentation +- [Tool Call Hooks →](/learn/tool-hooks) - Detailed tool hook documentation +- [Before and After Kickoff Hooks →](/learn/before-and-after-kickoff-hooks) - Crew lifecycle hooks +- [Human-in-the-Loop →](/learn/human-in-the-loop) - Human input patterns + +## Conclusion + +Execution hooks provide powerful control over agent runtime behavior. Use them to implement safety guardrails, approval workflows, comprehensive monitoring, and custom business logic. Combined with proper error handling, type safety, and performance considerations, hooks enable production-ready, secure, and observable agent systems. diff --git a/docs/v1.15.1/en/learn/force-tool-output-as-result.mdx b/docs/v1.15.1/en/learn/force-tool-output-as-result.mdx new file mode 100644 index 000000000..4ed351d22 --- /dev/null +++ b/docs/v1.15.1/en/learn/force-tool-output-as-result.mdx @@ -0,0 +1,51 @@ +--- +title: Force Tool Output as Result +description: Learn how to force tool output as the result in an Agent's task in CrewAI. +icon: wrench-simple +mode: "wide" +--- + +## Introduction + +In CrewAI, you can force the output of a tool as the result of an agent's task. +This feature is useful when you want to ensure that the tool output is captured and returned as the task result, avoiding any agent modification during the task execution. + +## Forcing Tool Output as Result + +To force the tool output as the result of an agent's task, you need to set the `result_as_answer` parameter to `True` when adding a tool to the agent. +This parameter ensures that the tool output is captured and returned as the task result, without any modifications by the agent. + +Here's an example of how to force the tool output as the result of an agent's task: + +```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) +``` + +## Workflow in Action + + + + The agent executes the task using the tool provided. + + + The tool generates the output, which is captured as the task result. + + + The agent may reflect and take learnings from the tool but the output is not modified. + + + The tool output is returned as the task result without any modifications. + + \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/hierarchical-process.mdx b/docs/v1.15.1/en/learn/hierarchical-process.mdx new file mode 100644 index 000000000..d048c2f1d --- /dev/null +++ b/docs/v1.15.1/en/learn/hierarchical-process.mdx @@ -0,0 +1,113 @@ +--- +title: Hierarchical Process +description: A comprehensive guide to understanding and applying the hierarchical process within your CrewAI projects, updated to reflect the latest coding practices and functionalities. +icon: sitemap +mode: "wide" +--- + +## Introduction + +The hierarchical process in CrewAI introduces a structured approach to task management, simulating traditional organizational hierarchies for efficient task delegation and execution. +This systematic workflow enhances project outcomes by ensuring tasks are handled with optimal efficiency and accuracy. + + + The hierarchical process is designed to leverage advanced models like GPT-4, optimizing token usage while handling complex tasks with greater efficiency. + + +## Hierarchical Process Overview + +By default, tasks in CrewAI are managed through a sequential process. However, adopting a hierarchical approach allows for a clear hierarchy in task management, +where a 'manager' agent coordinates the workflow, delegates tasks, and validates outcomes for streamlined and effective execution. This manager agent can now be either +automatically created by CrewAI or explicitly set by the user. + +### Key Features + +- **Task Delegation**: A manager agent allocates tasks among crew members based on their roles and capabilities. +- **Result Validation**: The manager evaluates outcomes to ensure they meet the required standards. +- **Efficient Workflow**: Emulates corporate structures, providing an organized approach to task management. +- **System Prompt Handling**: Optionally specify whether the system should use predefined prompts. +- **Stop Words Control**: Optionally specify whether stop words should be used, supporting various models including the o1 models. +- **Context Window Respect**: Prioritize important context by enabling respect of the context window, which is now the default behavior. +- **Delegation Control**: Delegation is now disabled by default to give users explicit control. +- **Max Requests Per Minute**: Configurable option to set the maximum number of requests per minute. +- **Max Iterations**: Limit the maximum number of iterations for obtaining a final answer. + + +## Implementing the Hierarchical Process + +To utilize the hierarchical process, it's essential to explicitly set the process attribute to `Process.hierarchical`, as the default behavior is `Process.sequential`. +Define a crew with a designated manager and establish a clear chain of command. + + + Assign tools at the agent level to facilitate task delegation and execution by the designated agents under the manager's guidance. + Tools can also be specified at the task level for precise control over tool availability during task execution. + + + + Configuring the `manager_llm` parameter is crucial for the hierarchical process. + The system requires a manager LLM to be set up for proper function, ensuring tailored decision-making. + + +```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, +) +``` + +### Using a Custom Manager Agent + +Alternatively, you can create a custom manager agent with specific attributes tailored to your project's management needs. This gives you more control over the manager's behavior and capabilities. + +```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, +) +``` + + + For more details on creating and customizing a manager agent, check out the [Custom Manager Agent documentation](/en/learn/custom-manager-agent). + + + +### Workflow in Action + +1. **Task Assignment**: The manager assigns tasks strategically, considering each agent's capabilities and available tools. +2. **Execution and Review**: Agents complete their tasks with the option for asynchronous execution and callback functions for streamlined workflows. +3. **Sequential Task Progression**: Despite being a hierarchical process, tasks follow a logical order for smooth progression, facilitated by the manager's oversight. + +## Conclusion + +Adopting the hierarchical process in CrewAI, with the correct configurations and understanding of the system's capabilities, facilitates an organized and efficient approach to project management. +Utilize the advanced features and customizations to tailor the workflow to your specific needs, ensuring optimal task execution and project success. diff --git a/docs/v1.15.1/en/learn/human-feedback-in-flows.mdx b/docs/v1.15.1/en/learn/human-feedback-in-flows.mdx new file mode 100644 index 000000000..0c3792bca --- /dev/null +++ b/docs/v1.15.1/en/learn/human-feedback-in-flows.mdx @@ -0,0 +1,707 @@ +--- +title: Human Feedback in Flows +description: Learn how to integrate human feedback directly into your CrewAI Flows using the @human_feedback decorator +icon: user-check +mode: "wide" +--- + +## Overview + + +The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**. Make sure to update your installation before using this feature. + + +The `@human_feedback` decorator enables human-in-the-loop (HITL) workflows directly within CrewAI Flows. It allows you to pause flow execution, present output to a human for review, collect their feedback, and optionally route to different listeners based on the feedback outcome. + +This is particularly valuable for: + +- **Quality assurance**: Review AI-generated content before it's used downstream +- **Decision gates**: Let humans make critical decisions in automated workflows +- **Approval workflows**: Implement approve/reject/revise patterns +- **Interactive refinement**: Collect feedback to improve outputs iteratively + +```mermaid +flowchart LR + A[Flow Method] --> B[Output Generated] + B --> C[Human Reviews] + C --> D{Feedback} + D -->|emit specified| E[LLM Collapses to Outcome] + D -->|no emit| F[HumanFeedbackResult] + E --> G["@listen('approved')"] + E --> H["@listen('rejected')"] + F --> I[Next Listener] +``` + +## Quick Start + +Here's the simplest way to add human feedback to a flow: + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback + +class SimpleReviewFlow(Flow): + @start() + @human_feedback(message="Please review this content:") + def generate_content(self): + return "This is AI-generated content that needs review." + + @listen(generate_content) + def process_feedback(self, result): + print(f"Content: {result.output}") + print(f"Human said: {result.feedback}") + +flow = SimpleReviewFlow() +flow.kickoff() +``` + +When this flow runs, it will: +1. Execute `generate_content` and return the string +2. Display the output to the user with the request message +3. Wait for the user to type feedback (or press Enter to skip) +4. Pass a `HumanFeedbackResult` object to `process_feedback` + +## The @human_feedback Decorator + +### Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `message` | `str` | Yes | The message shown to the human alongside the method output | +| `emit` | `Sequence[str]` | No | List of possible outcomes. Feedback is collapsed to one of these, which triggers `@listen` decorators | +| `llm` | `str \| BaseLLM` | When `emit` specified | LLM used to interpret feedback and map to an outcome | +| `default_outcome` | `str` | No | Outcome to use if no feedback provided. Must be in `emit` | +| `metadata` | `dict` | No | Additional data for enterprise integrations | +| `provider` | `HumanFeedbackProvider` | No | Custom provider for async/non-blocking feedback. See [Async Human Feedback](#async-human-feedback-non-blocking) | +| `learn` | `bool` | No | Enable HITL learning: distill lessons from feedback and pre-review future output. Default `False`. See [Learning from Feedback](#learning-from-feedback) | +| `learn_limit` | `int` | No | Max past lessons to recall for pre-review. Default `5` | + +### Basic Usage (No Routing) + +When you don't specify `emit`, the decorator simply collects feedback and passes a `HumanFeedbackResult` to the next listener: + +```python Code +@start() +@human_feedback(message="What do you think of this analysis?") +def analyze_data(self): + return "Analysis results: Revenue up 15%, costs down 8%" + +@listen(analyze_data) +def handle_feedback(self, result): + # result is a HumanFeedbackResult + print(f"Analysis: {result.output}") + print(f"Feedback: {result.feedback}") +``` + +### Routing with emit + +When you specify `emit`, the decorator becomes a router. The human's free-form feedback is interpreted by an LLM and collapsed into one of the specified outcomes: + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback + +class ReviewFlow(Flow): + @start() + def generate_content(self): + return "Draft blog post content here..." + + @human_feedback( + message="Do you approve this content for publication?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Draft blog post content here..." + + @listen("approved") + def publish(self, result): + print(f"Publishing! User said: {result.feedback}") + + @listen("rejected") + def discard(self, result): + print(f"Discarding. Reason: {result.feedback}") +``` + +When the human says something like "needs more detail", the LLM collapses that to `"needs_revision"`, which triggers `review_content` again via `or_()` — creating a revision loop. The loop continues until the outcome is `"approved"` or `"rejected"`. + + +The LLM uses structured outputs (function calling) when available to guarantee the response is one of your specified outcomes. This makes routing reliable and predictable. + + + +A `@start()` method only runs once at the beginning of the flow. If you need a revision loop, separate the start method from the review method and use `@listen(or_("trigger", "revision_outcome"))` on the review method to enable the self-loop. + + +## HumanFeedbackResult + +The `HumanFeedbackResult` dataclass contains all information about a human feedback interaction: + +```python Code +from crewai.flow.human_feedback import HumanFeedbackResult + +@dataclass +class HumanFeedbackResult: + output: Any # The original method output shown to the human + feedback: str # The raw feedback text from the human + outcome: str | None # The collapsed outcome (if emit was specified) + timestamp: datetime # When the feedback was received + method_name: str # Name of the decorated method + metadata: dict # Any metadata passed to the decorator +``` + +### Accessing in Listeners + +When a listener is triggered by a `@human_feedback` method with `emit`, it receives the `HumanFeedbackResult`: + +```python Code +@listen("approved") +def on_approval(self, result: HumanFeedbackResult): + print(f"Original output: {result.output}") + print(f"User feedback: {result.feedback}") + print(f"Outcome: {result.outcome}") # "approved" + print(f"Received at: {result.timestamp}") +``` + +## Accessing Feedback History + +The `Flow` class provides two attributes for accessing human feedback: + +### last_human_feedback + +Returns the most recent `HumanFeedbackResult`: + +```python Code +@listen(some_method) +def check_feedback(self): + if self.last_human_feedback: + print(f"Last feedback: {self.last_human_feedback.feedback}") +``` + +### human_feedback_history + +A list of all `HumanFeedbackResult` objects collected during the flow: + +```python Code +@listen(final_step) +def summarize(self): + print(f"Total feedback collected: {len(self.human_feedback_history)}") + for i, fb in enumerate(self.human_feedback_history): + print(f"{i+1}. {fb.method_name}: {fb.outcome or 'no routing'}") +``` + + +Each `HumanFeedbackResult` is appended to `human_feedback_history`, so multiple feedback steps won't overwrite each other. Use this list to access all feedback collected during the flow. + + +## Complete Example: Content Approval Workflow + +Here's a full example implementing a content review and approval workflow with a revision loop: + + + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult +from pydantic import BaseModel + + +class ContentState(BaseModel): + draft: str = "" + revision_count: int = 0 + status: str = "pending" + + +class ContentApprovalFlow(Flow[ContentState]): + """A flow that generates content and loops until the human approves.""" + + @start() + def generate_draft(self): + self.state.draft = "# AI Safety\n\nThis is a draft about AI Safety..." + return self.state.draft + + @human_feedback( + message="Please review this draft. Approve, reject, or describe what needs changing:", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_draft", "needs_revision")) + def review_draft(self): + self.state.revision_count += 1 + return f"{self.state.draft} (v{self.state.revision_count})" + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + self.state.status = "published" + print(f"Content approved and published! Reviewer said: {result.feedback}") + return "published" + + @listen("rejected") + def handle_rejection(self, result: HumanFeedbackResult): + self.state.status = "rejected" + print(f"Content rejected. Reason: {result.feedback}") + return "rejected" + + +flow = ContentApprovalFlow() +result = flow.kickoff() +print(f"\nFlow completed. Status: {flow.state.status}, Reviews: {flow.state.revision_count}") +``` + +```text Output +================================================== +OUTPUT FOR REVIEW: +================================================== +# AI Safety + +This is a draft about AI Safety... (v1) +================================================== + +Please review this draft. Approve, reject, or describe what needs changing: +(Press Enter to skip, or type your feedback) + +Your feedback: Needs more detail on alignment research + +================================================== +OUTPUT FOR REVIEW: +================================================== +# AI Safety + +This is a draft about AI Safety... (v2) +================================================== + +Please review this draft. Approve, reject, or describe what needs changing: +(Press Enter to skip, or type your feedback) + +Your feedback: Looks good, approved! + +Content approved and published! Reviewer said: Looks good, approved! + +Flow completed. Status: published, Reviews: 2 +``` + + + +The key pattern is `@listen(or_("generate_draft", "needs_revision"))` — the review method listens to both the initial trigger and its own revision outcome, creating a self-loop that repeats until the human approves or rejects. + +## Combining with Other Decorators + +The `@human_feedback` decorator works with `@start()`, `@listen()`, and `or_()`. Both decorator orderings work — the framework propagates attributes in both directions — but the recommended patterns are: + +```python Code +# One-shot review at the start of a flow (no self-loop) +@start() +@human_feedback(message="Review this:", emit=["approved", "rejected"], llm="gpt-4o-mini") +def my_start_method(self): + return "content" + +# Linear review on a listener (no self-loop) +@listen(other_method) +@human_feedback(message="Review this too:", emit=["good", "bad"], llm="gpt-4o-mini") +def my_listener(self, data): + return f"processed: {data}" + +# Self-loop: review that can loop back for revisions +@human_feedback(message="Approve or revise?", emit=["approved", "revise"], llm="gpt-4o-mini") +@listen(or_("upstream_method", "revise")) +def review_with_loop(self): + return "content for review" +``` + +### Self-loop pattern + +To create a revision loop, the review method must listen to **both** an upstream trigger and its own revision outcome using `or_()`: + +```python Code +@start() +def generate(self): + return "initial draft" + +@human_feedback( + message="Approve or request changes?", + emit=["revise", "approved"], + llm="gpt-4o-mini", + default_outcome="approved", +) +@listen(or_("generate", "revise")) +def review(self): + return "content" + +@listen("approved") +def publish(self): + return "published" +``` + +When the outcome is `"revise"`, the flow routes back to `review` (because it listens to `"revise"` via `or_()`). When the outcome is `"approved"`, the flow continues to `publish`. This works because the flow engine exempts routers from the "fire once" rule, allowing them to re-execute on each loop iteration. + +### Chained routers + +A listener triggered by one router's outcome can itself be a router: + +```python Code +@start() +def generate(self): + return "draft content" + +@human_feedback(message="First review:", emit=["approved", "rejected"], llm="gpt-4o-mini") +@listen("generate") +def first_review(self): + return "draft content" + +@human_feedback(message="Final review:", emit=["publish", "hold"], llm="gpt-4o-mini") +@listen("approved") +def final_review(self, prev): + return "final content" + +@listen("publish") +def on_publish(self, prev): + return "published" + +@listen("hold") +def on_hold(self, prev): + return "held for later" +``` + +### Limitations + +- **`@start()` methods run once**: A `@start()` method cannot self-loop. If you need a revision cycle, use a separate `@start()` method as the entry point and put the `@human_feedback` on a `@listen()` method. +- **No `@start()` + `@listen()` on the same method**: This is a Flow framework constraint. A method is either a start point or a listener, not both. + +## Best Practices + +### 1. Write Clear Request Messages + +The `message` parameter is what the human sees. Make it actionable: + +```python Code +# ✅ Good - clear and actionable +@human_feedback(message="Does this summary accurately capture the key points? Reply 'yes' or explain what's missing:") + +# ❌ Bad - vague +@human_feedback(message="Review this:") +``` + +### 2. Choose Meaningful Outcomes + +When using `emit`, pick outcomes that map naturally to human responses: + +```python Code +# ✅ Good - natural language outcomes +emit=["approved", "rejected", "needs_more_detail"] + +# ❌ Bad - technical or unclear +emit=["state_1", "state_2", "state_3"] +``` + +### 3. Always Provide a Default Outcome + +Use `default_outcome` to handle cases where users press Enter without typing: + +```python Code +@human_feedback( + message="Approve? (press Enter to request revision)", + emit=["approved", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", # Safe default +) +``` + +### 4. Use Feedback History for Audit Trails + +Access `human_feedback_history` to create audit logs: + +```python Code +@listen(final_step) +def create_audit_log(self): + log = [] + for fb in self.human_feedback_history: + log.append({ + "step": fb.method_name, + "outcome": fb.outcome, + "feedback": fb.feedback, + "timestamp": fb.timestamp.isoformat(), + }) + return log +``` + +### 5. Handle Both Routed and Non-Routed Feedback + +When designing flows, consider whether you need routing: + +| Scenario | Use | +|----------|-----| +| Simple review, just need the feedback text | No `emit` | +| Need to branch to different paths based on response | Use `emit` | +| Approval gates with approve/reject/revise | Use `emit` | +| Collecting comments for logging only | No `emit` | + +## Async Human Feedback (Non-Blocking) + +By default, `@human_feedback` blocks execution waiting for console input. For production applications, you may need **async/non-blocking** feedback that integrates with external systems like Slack, email, webhooks, or APIs. + +### The Provider Abstraction + +Use the `provider` parameter to specify a custom feedback collection strategy: + +```python Code +from crewai.flow import Flow, start, human_feedback, HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext + +class WebhookProvider(HumanFeedbackProvider): + """Provider that pauses flow and waits for webhook callback.""" + + def __init__(self, webhook_url: str): + self.webhook_url = webhook_url + + def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str: + # Notify external system (e.g., send Slack message, create ticket) + self.send_notification(context) + + # Pause execution - framework handles persistence automatically + raise HumanFeedbackPending( + context=context, + callback_info={"webhook_url": f"{self.webhook_url}/{context.flow_id}"} + ) + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="Review this content:", + emit=["approved", "rejected"], + llm="gpt-4o-mini", + provider=WebhookProvider("https://myapp.com/api"), + ) + def generate_content(self): + return "AI-generated content..." + + @listen("approved") + def publish(self, result): + return "Published!" +``` + + +The flow framework **automatically persists state** when `HumanFeedbackPending` is raised. Your provider only needs to notify the external system and raise the exception—no manual persistence calls required. + + +### Handling Paused Flows + +When using an async provider, `kickoff()` returns a `HumanFeedbackPending` object instead of raising an exception: + +```python Code +flow = ReviewFlow() +result = flow.kickoff() + +if isinstance(result, HumanFeedbackPending): + # Flow is paused, state is automatically persisted + print(f"Waiting for feedback at: {result.callback_info['webhook_url']}") + print(f"Flow ID: {result.context.flow_id}") +else: + # Normal completion + print(f"Flow completed: {result}") +``` + +### Resuming a Paused Flow + +When feedback arrives (e.g., via webhook), resume the flow: + +```python Code +# Sync handler: +def handle_feedback_webhook(flow_id: str, feedback: str): + flow = ReviewFlow.from_pending(flow_id) + result = flow.resume(feedback) + return result + +# Async handler (FastAPI, aiohttp, etc.): +async def handle_feedback_webhook(flow_id: str, feedback: str): + flow = ReviewFlow.from_pending(flow_id) + result = await flow.resume_async(feedback) + return result +``` + +### Key Types + +| Type | Description | +|------|-------------| +| `HumanFeedbackProvider` | Protocol for custom feedback providers | +| `PendingFeedbackContext` | Contains all info needed to resume a paused flow | +| `HumanFeedbackPending` | Returned by `kickoff()` when flow is paused for feedback | +| `ConsoleProvider` | Default blocking console input provider | + +### PendingFeedbackContext + +The context contains everything needed to resume: + +```python Code +@dataclass +class PendingFeedbackContext: + flow_id: str # Unique identifier for this flow execution + flow_class: str # Fully qualified class name + method_name: str # Method that triggered feedback + method_output: Any # Output shown to the human + message: str # The request message + emit: list[str] | None # Possible outcomes for routing + default_outcome: str | None + metadata: dict # Custom metadata + llm: str | None # LLM for outcome collapsing + requested_at: datetime +``` + +### Complete Async Flow Example + +```python Code +from crewai.flow import ( + Flow, start, listen, human_feedback, + HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext +) + +class SlackNotificationProvider(HumanFeedbackProvider): + """Provider that sends Slack notifications and pauses for async feedback.""" + + def __init__(self, channel: str): + self.channel = channel + + def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str: + # Send Slack notification (implement your own) + slack_thread_id = self.post_to_slack( + channel=self.channel, + message=f"Review needed:\n\n{context.method_output}\n\n{context.message}", + ) + + # Pause execution - framework handles persistence automatically + raise HumanFeedbackPending( + context=context, + callback_info={ + "slack_channel": self.channel, + "thread_id": slack_thread_id, + } + ) + +class ContentPipeline(Flow): + @start() + @human_feedback( + message="Approve this content for publication?", + emit=["approved", "rejected"], + llm="gpt-4o-mini", + default_outcome="rejected", + provider=SlackNotificationProvider("#content-reviews"), + ) + def generate_content(self): + return "AI-generated blog post content..." + + @listen("approved") + def publish(self, result): + print(f"Publishing! Reviewer said: {result.feedback}") + return {"status": "published"} + + @listen("rejected") + def archive(self, result): + print(f"Archived. Reason: {result.feedback}") + return {"status": "archived"} + + +# Starting the flow (will pause and wait for Slack response) +def start_content_pipeline(): + flow = ContentPipeline() + result = flow.kickoff() + + if isinstance(result, HumanFeedbackPending): + return {"status": "pending", "flow_id": result.context.flow_id} + + return result + + +# Resuming when Slack webhook fires (sync handler) +def on_slack_feedback(flow_id: str, slack_message: str): + flow = ContentPipeline.from_pending(flow_id) + result = flow.resume(slack_message) + return result + + +# If your handler is async (FastAPI, aiohttp, Slack Bolt async, etc.) +async def on_slack_feedback_async(flow_id: str, slack_message: str): + flow = ContentPipeline.from_pending(flow_id) + result = await flow.resume_async(slack_message) + return result +``` + + +If you're using an async web framework (FastAPI, aiohttp, Slack Bolt async mode), use `await flow.resume_async()` instead of `flow.resume()`. Calling `resume()` from within a running event loop will raise a `RuntimeError`. + + +### Best Practices for Async Feedback + +1. **Check the return type**: `kickoff()` returns `HumanFeedbackPending` when paused—no try/except needed +2. **Use the right resume method**: Use `resume()` in sync code, `await resume_async()` in async code +3. **Store callback info**: Use `callback_info` to store webhook URLs, ticket IDs, etc. +4. **Implement idempotency**: Your resume handler should be idempotent for safety +5. **Automatic persistence**: State is automatically saved when `HumanFeedbackPending` is raised and uses `SQLiteFlowPersistence` by default +6. **Custom persistence**: Pass a custom persistence instance to `from_pending()` if needed + +## Learning from Feedback + +The `learn=True` parameter enables a feedback loop between human reviewers and the memory system. When enabled, the system progressively improves its outputs by learning from past human corrections. + +### How It Works + +1. **After feedback**: The LLM extracts generalizable lessons from the output + feedback and stores them in memory with `source="hitl"`. If the feedback is just approval (e.g. "looks good"), nothing is stored. +2. **Before next review**: Past HITL lessons are recalled from memory and applied by the LLM to improve the output before the human sees it. + +Over time, the human sees progressively better pre-reviewed output because each correction informs future reviews. + +### Example + +```python Code +class ArticleReviewFlow(Flow): + @start() + def generate_article(self): + return self.crew.kickoff(inputs={"topic": "AI Safety"}).raw + + @human_feedback( + message="Review this article draft:", + emit=["approved", "needs_revision"], + llm="gpt-4o-mini", + learn=True, # enable HITL learning + ) + @listen(or_("generate_article", "needs_revision")) + def review_article(self): + return self.last_human_feedback.output if self.last_human_feedback else "article draft" + + @listen("approved") + def publish(self): + print(f"Publishing: {self.last_human_feedback.output}") +``` + +**First run**: The human sees the raw output and says "Always include citations for factual claims." The lesson is distilled and stored in memory. + +**Second run**: The system recalls the citation lesson, pre-reviews the output to add citations, then shows the improved version. The human's job shifts from "fix everything" to "catch what the system missed." + +### Configuration + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `learn` | `False` | Enable HITL learning | +| `learn_limit` | `5` | Max past lessons to recall for pre-review | + +### Key Design Decisions + +- **Same LLM for everything**: The `llm` parameter on the decorator is shared by outcome collapsing, lesson distillation, and pre-review. No need to configure multiple models. +- **Structured output**: Both distillation and pre-review use function calling with Pydantic models when the LLM supports it, falling back to text parsing otherwise. +- **Non-blocking storage**: Lessons are stored via `remember_many()` which runs in a background thread -- the flow continues immediately. +- **Graceful degradation**: If the LLM fails during distillation, nothing is stored. If it fails during pre-review, the raw output is shown. Neither failure blocks the flow. +- **No scope/categories needed**: When storing lessons, only `source` is passed. The encoding pipeline infers scope, categories, and importance automatically. + + +`learn=True` requires the Flow to have memory available. Flows get memory automatically by default, but if you've disabled it with `_skip_auto_memory`, HITL learning will be silently skipped. + + + +## Related Documentation + +- [Flows Overview](/en/concepts/flows) - Learn about CrewAI Flows +- [Flow State Management](/en/guides/flows/mastering-flow-state) - Managing state in flows +- [Flow Persistence](/en/concepts/flows#persistence) - Persisting flow state +- [Routing with @router](/en/concepts/flows#router) - More about conditional routing +- [Human Input on Execution](/en/learn/human-input-on-execution) - Task-level human input +- [Memory](/en/concepts/memory) - The unified memory system used by HITL learning diff --git a/docs/v1.15.1/en/learn/human-in-the-loop.mdx b/docs/v1.15.1/en/learn/human-in-the-loop.mdx new file mode 100644 index 000000000..c9e8ba57d --- /dev/null +++ b/docs/v1.15.1/en/learn/human-in-the-loop.mdx @@ -0,0 +1,159 @@ +--- +title: "Human-in-the-Loop (HITL) Workflows" +description: "Learn how to implement Human-in-the-Loop workflows in CrewAI for enhanced decision-making" +icon: "user-check" +mode: "wide" +--- + +Human-in-the-Loop (HITL) is a powerful approach that combines artificial intelligence with human expertise to enhance decision-making and improve task outcomes. CrewAI provides multiple ways to implement HITL depending on your needs. + +## Choosing Your HITL Approach + +CrewAI offers two main approaches for implementing human-in-the-loop workflows: + +| Approach | Best For | Integration | Version | +|----------|----------|-------------|---------| +| **Flow-based** (`@human_feedback` decorator) | Local development, console-based review, synchronous workflows | [Human Feedback in Flows](/en/learn/human-feedback-in-flows) | **1.8.0+** | +| **Webhook-based** (Enterprise) | Production deployments, async workflows, external integrations (Slack, Teams, etc.) | This guide | - | + + +If you're building flows and want to add human review steps with routing based on feedback, check out the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide for the `@human_feedback` decorator. + + +## Setting Up Webhook-Based HITL Workflows + + + + Set up your task with human input enabled: + + Crew Human Input + + + + + When kicking off your crew, include a webhook URL for human input: + + Crew Webhook URL + + + Example with Bearer authentication: + ```bash + curl -X POST {BASE_URL}/kickoff \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "inputs": { + "topic": "AI Research" + }, + "humanInputWebhook": { + "url": "https://your-webhook.com/hitl", + "authentication": { + "strategy": "bearer", + "token": "your-webhook-secret-token" + } + } + }' + ``` + + Or with Basic authentication: + ```bash + curl -X POST {BASE_URL}/kickoff \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "inputs": { + "topic": "AI Research" + }, + "humanInputWebhook": { + "url": "https://your-webhook.com/hitl", + "authentication": { + "strategy": "basic", + "username": "your-username", + "password": "your-password" + } + } + }' + ``` + + + + Once the crew completes the task requiring human input, you'll receive a webhook notification containing: + - Execution ID + - Task ID + - Task output + + + + The system will pause in the `Pending Human Input` state. Review the task output carefully. + + + + Call the resume endpoint of your crew with the following information: + + Crew Resume Endpoint + + + + **Critical: Webhook URLs Must Be Provided Again**: + You **must** provide the same webhook URLs (`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`) in the resume call that you used in the kickoff call. Webhook configurations are **NOT** automatically carried over from kickoff - they must be explicitly included in the resume request to continue receiving notifications for task completion, agent steps, and crew completion. + + + Example resume call with webhooks: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "Great work! Please add more details.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **Feedback Impact on Task Execution**: + It's crucial to exercise care when providing feedback, as the entire feedback content will be incorporated as additional context for further task executions. + + This means: + - All information in your feedback becomes part of the task's context. + - Irrelevant details may negatively influence it. + - Concise, relevant feedback helps maintain task focus and efficiency. + - Always review your feedback carefully before submission to ensure it contains only pertinent information that will positively guide the task's execution. + + + If you provide negative feedback: + - The crew will retry the task with added context from your feedback. + - You'll receive another webhook notification for further review. + - Repeat steps 4-6 until satisfied. + + + + When you submit positive feedback, the execution will proceed to the next steps. + + + +## Best Practices + +- **Be Specific**: Provide clear, actionable feedback that directly addresses the task at hand +- **Stay Relevant**: Only include information that will help improve the task execution +- **Be Timely**: Respond to HITL prompts promptly to avoid workflow delays +- **Review Carefully**: Double-check your feedback before submitting to ensure accuracy + +## Common Use Cases + +HITL workflows are particularly valuable for: +- Quality assurance and validation +- Complex decision-making scenarios +- Sensitive or high-stakes operations +- Creative tasks requiring human judgment +- Compliance and regulatory reviews + +## Enterprise Features + + + CrewAI Enterprise provides a comprehensive HITL management system for Flows with in-platform review, responder assignment, permissions, escalation policies, SLA management, dynamic routing, and full analytics. [Learn more →](/en/enterprise/features/flow-hitl-management) + diff --git a/docs/v1.15.1/en/learn/human-input-on-execution.mdx b/docs/v1.15.1/en/learn/human-input-on-execution.mdx new file mode 100644 index 000000000..c4414bff0 --- /dev/null +++ b/docs/v1.15.1/en/learn/human-input-on-execution.mdx @@ -0,0 +1,99 @@ +--- +title: Human Input on Execution +description: Integrating CrewAI with human input during execution in complex decision-making processes and leveraging the full capabilities of the agent's attributes and tools. +icon: user-plus +mode: "wide" +--- + +## Human input in agent execution + +Human input is critical in several agent execution scenarios, allowing agents to request additional information or clarification when necessary. +This feature is especially useful in complex decision-making processes or when agents require more details to complete a task effectively. + +## Using human input with CrewAI + +To integrate human input into agent execution, set the `human_input` flag in the task definition. When enabled, the agent prompts the user for input before delivering its final answer. +This input can provide extra context, clarify ambiguities, or validate the agent's output. + +### Example: + +```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) +``` diff --git a/docs/v1.15.1/en/learn/kickoff-async.mdx b/docs/v1.15.1/en/learn/kickoff-async.mdx new file mode 100644 index 000000000..dc5c7c08b --- /dev/null +++ b/docs/v1.15.1/en/learn/kickoff-async.mdx @@ -0,0 +1,306 @@ +--- +title: Kickoff Crew Asynchronously +description: Kickoff a Crew Asynchronously +icon: rocket-launch +mode: "wide" +--- + +## Introduction + +CrewAI provides the ability to kickoff a crew asynchronously, allowing you to start the crew execution in a non-blocking manner. +This feature is particularly useful when you want to run multiple crews concurrently or when you need to perform other tasks while the crew is executing. + +CrewAI offers two approaches for async execution: + +| Method | Type | Description | +|--------|------|-------------| +| `akickoff()` | Native async | True async/await throughout the entire execution chain | +| `kickoff_async()` | Thread-based | Wraps synchronous execution in `asyncio.to_thread` | + + +For high-concurrency workloads, `akickoff()` is recommended as it uses native async for task execution, memory operations, and knowledge retrieval. + + +## Native Async Execution with `akickoff()` + +The `akickoff()` method provides true native async execution, using async/await throughout the entire execution chain including task execution, memory operations, and knowledge queries. + +### Method Signature + +```python Code +async def akickoff(self, inputs: dict) -> CrewOutput: +``` + +### Parameters + +- `inputs` (dict): A dictionary containing the input data required for the tasks. + +### Returns + +- `CrewOutput`: An object representing the result of the crew execution. + +### Example: Native Async Crew Execution + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# Create an agent +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 +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 +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# Native async execution +async def main(): + result = await analysis_crew.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(main()) +``` + +### Example: Multiple Native Async Crews + +Run multiple crews concurrently using `asyncio.gather()` with native async: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +task_1 = Task( + description="Analyze the first dataset and calculate the average age. 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. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def main(): + results = await asyncio.gather( + crew_1.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}), + crew_2.akickoff(inputs={"ages": [20, 22, 24, 28, 30]}) + ) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(main()) +``` + +### Example: Native Async for Multiple Inputs + +Use `akickoff_for_each()` to execute your crew against multiple inputs concurrently with native async: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +data_analysis_task = Task( + description="Analyze the dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def main(): + datasets = [ + {"ages": [25, 30, 35, 40, 45]}, + {"ages": [20, 22, 24, 28, 30]}, + {"ages": [30, 35, 40, 45, 50]} + ] + + results = await analysis_crew.akickoff_for_each(datasets) + + for i, result in enumerate(results, 1): + print(f"Dataset {i} Result:", result) + +asyncio.run(main()) +``` + +## Thread-Based Async with `kickoff_async()` + +The `kickoff_async()` method provides async execution by wrapping the synchronous `kickoff()` in a thread. This is useful for simpler async integration or backward compatibility. + +### Method Signature + +```python Code +async def kickoff_async(self, inputs: dict) -> CrewOutput: +``` + +### Parameters + +- `inputs` (dict): A dictionary containing the input data required for the tasks. + +### Returns + +- `CrewOutput`: An object representing the result of the crew execution. + +### Example: Thread-Based Async Execution + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(async_crew_execution()) +``` + +### Example: Multiple Thread-Based Async Crews + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def async_multiple_crews(): + 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]}) + + results = await asyncio.gather(result_1, result_2) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(async_multiple_crews()) +``` + +## Async Streaming + +Both async methods support streaming when `stream=True` is set on the crew: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +agent = Agent( + role="Researcher", + goal="Research and summarize topics", + backstory="You are an expert researcher." +) + +task = Task( + description="Research the topic: {topic}", + agent=agent, + expected_output="A comprehensive summary of the topic." +) + +crew = Crew( + agents=[agent], + tasks=[task], + stream=True # Enable streaming +) + +async def main(): + streaming_output = await crew.akickoff(inputs={"topic": "AI trends in 2024"}) + + # Async iteration over streaming chunks + async for chunk in streaming_output: + print(f"Chunk: {chunk.content}") + + # Access final result after streaming completes + result = streaming_output.result + print(f"Final result: {result.raw}") + +asyncio.run(main()) +``` + +## Potential Use Cases + +- **Parallel Content Generation**: Kickoff multiple independent crews asynchronously, each responsible for generating content on different topics. For example, one crew might research and draft an article on AI trends, while another crew generates social media posts about a new product launch. + +- **Concurrent Market Research Tasks**: Launch multiple crews asynchronously to conduct market research in parallel. One crew might analyze industry trends, while another examines competitor strategies, and yet another evaluates consumer sentiment. + +- **Independent Travel Planning Modules**: Execute separate crews to independently plan different aspects of a trip. One crew might handle flight options, another handles accommodation, and a third plans activities. + +## Choosing Between `akickoff()` and `kickoff_async()` + +| Feature | `akickoff()` | `kickoff_async()` | +|---------|--------------|-------------------| +| Execution model | Native async/await | Thread-based wrapper | +| Task execution | Async with `aexecute_sync()` | Sync in thread pool | +| Memory operations | Async | Sync in thread pool | +| Knowledge retrieval | Async | Sync in thread pool | +| Best for | High-concurrency, I/O-bound workloads | Simple async integration | +| Streaming support | Yes | Yes | diff --git a/docs/v1.15.1/en/learn/kickoff-for-each.mdx b/docs/v1.15.1/en/learn/kickoff-for-each.mdx new file mode 100644 index 000000000..bded1550b --- /dev/null +++ b/docs/v1.15.1/en/learn/kickoff-for-each.mdx @@ -0,0 +1,54 @@ +--- +title: Kickoff Crew for Each +description: Kickoff Crew for Each Item in a List +icon: at +mode: "wide" +--- + +## Introduction + +CrewAI provides the ability to kickoff a crew for each item in a list, allowing you to execute the crew for each item in the list. +This feature is particularly useful when you need to perform the same set of tasks for multiple items. + +## Kicking Off a Crew for Each Item + +To kickoff a crew for each item in a list, use the `kickoff_for_each()` method. +This method executes the crew for each item in the list, allowing you to process multiple items efficiently. + +Here's an example of how to kickoff a crew for each item in a list: + +```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/v1.15.1/en/learn/litellm-removal-guide.mdx b/docs/v1.15.1/en/learn/litellm-removal-guide.mdx new file mode 100644 index 000000000..4580f7b32 --- /dev/null +++ b/docs/v1.15.1/en/learn/litellm-removal-guide.mdx @@ -0,0 +1,358 @@ +--- +title: Using CrewAI Without LiteLLM +description: How to use CrewAI with native provider integrations and remove the LiteLLM dependency from your project. +icon: shield-check +mode: "wide" +--- + +## Overview + +CrewAI supports two paths for connecting to LLM providers: + +1. **Native integrations** — direct SDK connections to OpenAI, Anthropic, Google Gemini, Azure OpenAI, and AWS Bedrock +2. **LiteLLM fallback** — a translation layer that supports 100+ additional providers + +This guide explains how to use CrewAI exclusively with native provider integrations, removing any dependency on LiteLLM. + + + The `litellm` package was quarantined on PyPI due to a security/reliability incident. If you rely on LiteLLM-dependent providers, you should migrate to native integrations. CrewAI's native integrations give you full functionality without LiteLLM. + + +## Why Remove LiteLLM? + +- **Reduced dependency surface** — fewer packages means fewer potential supply-chain risks +- **Better performance** — native SDKs communicate directly with provider APIs, eliminating a translation layer +- **Simpler debugging** — one less abstraction layer between your code and the provider +- **Smaller install footprint** — LiteLLM brings in many transitive dependencies + +## Native Providers (No LiteLLM Required) + +These providers use their own SDKs and work without LiteLLM installed: + + + + GPT-4o, GPT-4o-mini, o1, o3-mini, and more. + ```bash + uv add "crewai[openai]" + ``` + + + Claude Sonnet, Claude Haiku, and more. + ```bash + uv add "crewai[anthropic]" + ``` + + + Gemini 2.0 Flash, Gemini 2.0 Pro, and more. + ```bash + uv add "crewai[gemini]" + ``` + + + Azure-hosted OpenAI models. + ```bash + uv add "crewai[azure]" + ``` + + + Claude, Llama, Titan, and more via AWS. + ```bash + uv add "crewai[bedrock]" + ``` + + + + + If you only use native providers, you **never** need to install `crewai[litellm]`. The base `crewai` package plus your chosen provider extra is all you need. + + +## How to Check If You're Using LiteLLM + +### Check your model strings + +If your code uses model prefixes like these, you're routing through LiteLLM: + +| Prefix | Provider | Uses LiteLLM? | +|--------|----------|---------------| +| `ollama/` | Ollama | ✅ Yes | +| `groq/` | Groq | ✅ Yes | +| `together_ai/` | Together AI | ✅ Yes | +| `mistral/` | Mistral | ✅ Yes | +| `cohere/` | Cohere | ✅ Yes | +| `huggingface/` | Hugging Face | ✅ Yes | +| `openai/` | OpenAI | ❌ Native | +| `anthropic/` | Anthropic | ❌ Native | +| `gemini/` | Google Gemini | ❌ Native | +| `azure/` | Azure OpenAI | ❌ Native | +| `bedrock/` | AWS Bedrock | ❌ Native | + +### Check if LiteLLM is installed + +```bash +# Using pip +pip show litellm + +# Using uv +uv pip show litellm +``` + +If the command returns package information, LiteLLM is installed in your environment. + +### Check your dependencies + +Look at your `pyproject.toml` for `crewai[litellm]`: + +```toml +# If you see this, you have LiteLLM as a dependency +dependencies = [ + "crewai[litellm]>=0.100.0", # ← Uses LiteLLM +] + +# Change to a native provider extra instead +dependencies = [ + "crewai[openai]>=0.100.0", # ← Native, no LiteLLM +] +``` + +## Migration Guide + +### Step 1: Identify your current provider + +Find all `LLM()` calls and model strings in your code: + +```bash +# Search your codebase for LLM model strings +grep -r "LLM(" --include="*.py" . +grep -r "llm=" --include="*.yaml" . +grep -r "llm:" --include="*.yaml" . +``` + +### Step 2: Switch to a native provider + + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="groq/llama-3.1-70b") + + # After (Native): + llm = LLM(model="openai/gpt-4o") + ``` + + ```bash + # Install + uv add "crewai[openai]" + + # Set your API key + export OPENAI_API_KEY="sk-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") + + # After (Native): + llm = LLM(model="anthropic/claude-sonnet-4-20250514") + ``` + + ```bash + # Install + uv add "crewai[anthropic]" + + # Set your API key + export ANTHROPIC_API_KEY="sk-ant-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="mistral/mistral-large-latest") + + # After (Native): + llm = LLM(model="gemini/gemini-2.0-flash") + ``` + + ```bash + # Install + uv add "crewai[gemini]" + + # Set your API key + export GEMINI_API_KEY="..." + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="azure/your-deployment-name", + api_key="your-azure-api-key", + base_url="https://your-resource.openai.azure.com", + api_version="2024-06-01" + ) + ``` + + ```bash + # Install + uv add "crewai[azure]" + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_region_name="us-east-1" + ) + ``` + + ```bash + # Install + uv add "crewai[bedrock]" + + # Configure AWS credentials + export AWS_ACCESS_KEY_ID="..." + export AWS_SECRET_ACCESS_KEY="..." + export AWS_DEFAULT_REGION="us-east-1" + ``` + + + +### Step 3: Keep Ollama without LiteLLM + +If you're using Ollama and want to keep using it, you can connect via Ollama's OpenAI-compatible API: + +```python +from crewai import LLM + +# Before (LiteLLM): +# llm = LLM(model="ollama/llama3") + +# After (OpenAI-compatible mode, no LiteLLM needed): +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" # Ollama doesn't require a real API key +) +``` + + + Many local inference servers (Ollama, vLLM, LM Studio, llama.cpp) expose an OpenAI-compatible API. You can use the `openai/` prefix with a custom `base_url` to connect to any of them natively. + + +### Step 4: Update your YAML configs + +```yaml +# Before (LiteLLM providers): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: groq/llama-3.1-70b # ← LiteLLM + +# After (Native provider): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: openai/gpt-4o # ← Native +``` + +### Step 5: Remove LiteLLM + +Once you've migrated all your model references: + +```bash +# Remove litellm from your project +uv remove litellm + +# Or if using pip +pip uninstall litellm + +# Update your pyproject.toml: change crewai[litellm] to your provider extra +# e.g., crewai[openai], crewai[anthropic], crewai[gemini] +``` + +### Step 6: Verify + +Run your project and confirm everything works: + +```bash +# Run your crew +crewai run + +# Or run your tests +uv run pytest +``` + +## Quick Reference: Model String Mapping + +Here are common migration paths from LiteLLM-dependent providers to native ones: + +```python +from crewai import LLM + +# ─── LiteLLM providers → Native alternatives ──────────────────── + +# Groq → OpenAI or Anthropic +# llm = LLM(model="groq/llama-3.1-70b") +llm = LLM(model="openai/gpt-4o-mini") # Fast & affordable +llm = LLM(model="anthropic/claude-haiku-3-5") # Fast & affordable + +# Together AI → OpenAI or Gemini +# llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") +llm = LLM(model="openai/gpt-4o") # High quality +llm = LLM(model="gemini/gemini-2.0-flash") # Fast & capable + +# Mistral → Anthropic or OpenAI +# llm = LLM(model="mistral/mistral-large-latest") +llm = LLM(model="anthropic/claude-sonnet-4-20250514") # High quality + +# Ollama → OpenAI-compatible (keep using local models) +# llm = LLM(model="ollama/llama3") +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" +) +``` + +## FAQ + + + + No, if you use one of the five natively supported providers (OpenAI, Anthropic, Gemini, Azure, Bedrock). These native integrations support all CrewAI features including streaming, tool calling, structured output, and more. You only lose access to providers that are exclusively available through LiteLLM (like Groq, Together AI, Mistral as first-class providers). + + + Yes. Install multiple extras and use different providers for different agents: + ```bash + uv add "crewai[openai,anthropic,gemini]" + ``` + ```python + researcher = Agent(llm="openai/gpt-4o", ...) + writer = Agent(llm="anthropic/claude-sonnet-4-20250514", ...) + ``` + + + Regardless of quarantine status, reducing your dependency surface is good security practice. If you only need providers that CrewAI supports natively, there's no reason to keep LiteLLM installed. + + + Native providers use the same environment variables you're already familiar with. No changes needed for `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc. + + + +## Related Resources + +- [LLM Connections](/en/learn/llm-connections) — Full guide to connecting CrewAI with any LLM +- [LLM Concepts](/en/concepts/llms) — Understanding LLMs in CrewAI +- [LLM Selection Guide](/en/learn/llm-selection-guide) — Choosing the right model for your use case diff --git a/docs/v1.15.1/en/learn/llm-connections.mdx b/docs/v1.15.1/en/learn/llm-connections.mdx new file mode 100644 index 000000000..2b7a5d278 --- /dev/null +++ b/docs/v1.15.1/en/learn/llm-connections.mdx @@ -0,0 +1,214 @@ +--- +title: Connect to any LLM +description: Comprehensive guide on integrating CrewAI with various Large Language Models (LLMs) using LiteLLM, including supported providers and configuration options. +icon: brain-circuit +mode: "wide" +--- + +## Connect CrewAI to LLMs + +CrewAI connects to LLMs through native SDK integrations for the most popular providers (OpenAI, Anthropic, Google Gemini, Azure, and AWS Bedrock), and uses LiteLLM as a flexible fallback for all other providers. + + + By default, CrewAI uses the `gpt-4o-mini` model. This is determined by the `OPENAI_MODEL_NAME` environment variable, which defaults to "gpt-4o-mini" if not set. + You can easily configure your agents to use a different model or provider as described in this guide. + + +## Supported Providers + +LiteLLM supports a wide range of providers, including but not limited to: + +- 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 +- Nebius AI Studio +- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1) +- And many more! + +For a complete and up-to-date list of supported providers, please refer to the [LiteLLM Providers documentation](https://docs.litellm.ai/docs/providers). + + + To use any provider not covered by a native integration, add LiteLLM as a dependency to your project: + ```bash + uv add 'crewai[litellm]' + ``` + Native providers (OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock) use their own SDK extras — see the [Provider Configuration Examples](/en/concepts/llms#provider-configuration-examples). + + +## Changing the LLM + +To use a different LLM with your CrewAI agents, you have several options: + + + + Pass the model name as a string when initializing the agent: + + ```python Code + from crewai import Agent + + # Using OpenAI's GPT-4 + 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' + ) + + # Using Anthropic's Claude + claude_agent = Agent( + role='Anthropic Expert', + goal='Analyze data using Claude', + backstory="An AI assistant leveraging Anthropic's language model.", + llm='claude-2' + ) + ``` + + + + For more detailed configuration, use the LLM class: + + ```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 + ) + ``` + + + + +## Configuration Options + +When configuring an LLM for your agent, you have access to a wide range of parameters: + +| Parameter | Type | Description | +|:----------|:-----:|:-------------| +| **model** | `str` | The name of the model to use (e.g., "gpt-4", "claude-2") | +| **temperature** | `float` | Controls randomness in output (0.0 to 1.0) | +| **max_tokens** | `int` | Maximum number of tokens to generate | +| **top_p** | `float` | Controls diversity of output (0.0 to 1.0) | +| **frequency_penalty** | `float` | Penalizes new tokens based on their frequency in the text so far | +| **presence_penalty** | `float` | Penalizes new tokens based on their presence in the text so far | +| **stop** | `str`, `List[str]` | Sequence(s) to stop generation | +| **base_url** | `str` | The base URL for the API endpoint | +| **api_key** | `str` | Your API key for authentication | + +For a complete list of parameters and their descriptions, refer to the LLM class documentation. + +## Connecting to OpenAI-Compatible LLMs + +You can connect to OpenAI-compatible LLMs using either environment variables or by setting specific attributes on the LLM class: + + + + + ```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 + + # Example using Gemini's OpenAI-compatible API. + os.environ["OPENAI_API_KEY"] = "your-gemini-key" # Should start with AIza... + os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/" + os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Add your Gemini model here, under 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 + # Example using Gemini's OpenAI-compatible API + llm = LLM( + model="openai/gemini-2.0-flash", + base_url="https://generativelanguage.googleapis.com/v1beta/openai/", + api_key="your-gemini-key", # Should start with AIza... + ) + agent = Agent(llm=llm, ...) + ``` + + + + +## Using Local Models with Ollama + +For local models like those provided by Ollama: + + + + [Click here to download and install Ollama](https://ollama.com/download) + + + For example, run `ollama pull llama3.2` to download the model. + + + + ```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") + ) + ``` + + + + +## Changing the Base API URL + +You can change the base API URL for any LLM provider by setting the `base_url` parameter: + +```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, ...) +``` + +This is particularly useful when working with OpenAI-compatible APIs or when you need to specify a different endpoint for your chosen provider. + +## Conclusion + +By leveraging LiteLLM, CrewAI offers seamless integration with a vast array of LLMs. This flexibility allows you to choose the most suitable model for your specific needs, whether you prioritize performance, cost-efficiency, or local deployment. Remember to consult the [LiteLLM documentation](https://docs.litellm.ai/docs/) for the most up-to-date information on supported models and configuration options. diff --git a/docs/v1.15.1/en/learn/llm-hooks.mdx b/docs/v1.15.1/en/learn/llm-hooks.mdx new file mode 100644 index 000000000..f623785b1 --- /dev/null +++ b/docs/v1.15.1/en/learn/llm-hooks.mdx @@ -0,0 +1,427 @@ +--- +title: LLM Call Hooks +description: Learn how to use LLM call hooks to intercept, modify, and control language model interactions in CrewAI +mode: "wide" +--- + +LLM Call Hooks provide fine-grained control over language model interactions during agent execution. These hooks allow you to intercept LLM calls, modify prompts, transform responses, implement approval gates, and add custom logging or monitoring. + +## Overview + +LLM hooks are executed at two critical points: +- **Before LLM Call**: Modify messages, validate inputs, or block execution +- **After LLM Call**: Transform responses, sanitize outputs, or modify conversation history + +## Hook Types + +### Before LLM Call Hooks + +Executed before every LLM call, these hooks can: +- Inspect and modify messages sent to the LLM +- Block LLM execution based on conditions +- Implement rate limiting or approval gates +- Add context or system messages +- Log request details + +**Signature:** +```python +def before_hook(context: LLMCallHookContext) -> bool | None: + # Return False to block execution + # Return True or None to allow execution + ... +``` + +### After LLM Call Hooks + +Executed after every LLM call, these hooks can: +- Modify or sanitize LLM responses +- Add metadata or formatting +- Log response details +- Update conversation history +- Implement content filtering + +**Signature:** +```python +def after_hook(context: LLMCallHookContext) -> str | None: + # Return modified response string + # Return None to keep original response + ... +``` + +## LLM Hook Context + +The `LLMCallHookContext` object provides comprehensive access to execution state: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # Full executor reference + messages: list # Mutable message list + agent: Agent # Current agent + task: Task # Current task + crew: Crew # Crew instance + llm: BaseLLM # LLM instance + iterations: int # Current iteration count + response: str | None # LLM response (after hooks only) +``` + +### Modifying Messages + +**Important:** Always modify messages in-place: + +```python +# ✅ Correct - modify in-place +def add_context(context: LLMCallHookContext) -> None: + context.messages.append({"role": "system", "content": "Be concise"}) + +# ❌ Wrong - replaces list reference +def wrong_approach(context: LLMCallHookContext) -> None: + context.messages = [{"role": "system", "content": "Be concise"}] +``` + +## Registration Methods + +### 1. Global Hook Registration + +Register hooks that apply to all LLM calls across all crews: + +```python +from crewai.hooks import register_before_llm_call_hook, register_after_llm_call_hook + +def log_llm_call(context): + print(f"LLM call by {context.agent.role} at iteration {context.iterations}") + return None # Allow execution + +register_before_llm_call_hook(log_llm_call) +``` + +### 2. Decorator-Based Registration + +Use decorators for cleaner syntax: + +```python +from crewai.hooks import before_llm_call, after_llm_call + +@before_llm_call +def validate_iteration_count(context): + if context.iterations > 10: + print("⚠️ Exceeded maximum iterations") + return False # Block execution + return None + +@after_llm_call +def sanitize_response(context): + if context.response and "API_KEY" in context.response: + return context.response.replace("API_KEY", "[REDACTED]") + return None +``` + +### 3. Crew-Scoped Hooks + +Register hooks for a specific crew instance: + +```python +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # Only applies to this crew + if context.iterations == 0: + print(f"Starting task: {context.task.description}") + return None + + @after_llm_call_crew + def log_responses(self, context): + # Crew-specific response logging + print(f"Response length: {len(context.response)}") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## Common Use Cases + +### 1. Iteration Limiting + +```python +@before_llm_call +def limit_iterations(context: LLMCallHookContext) -> bool | None: + max_iterations = 15 + if context.iterations > max_iterations: + print(f"⛔ Blocked: Exceeded {max_iterations} iterations") + return False # Block execution + return None +``` + +### 2. Human Approval Gate + +```python +@before_llm_call +def require_approval(context: LLMCallHookContext) -> bool | None: + if context.iterations > 5: + response = context.request_human_input( + prompt=f"Iteration {context.iterations}: Approve LLM call?", + default_message="Press Enter to approve, or type 'no' to block:" + ) + if response.lower() == "no": + print("🚫 LLM call blocked by user") + return False + return None +``` + +### 3. Adding System Context + +```python +@before_llm_call +def add_guardrails(context: LLMCallHookContext) -> None: + # Add safety guidelines to every LLM call + context.messages.append({ + "role": "system", + "content": "Ensure responses are factual and cite sources when possible." + }) + return None +``` + +### 4. Response Sanitization + +```python +@after_llm_call +def sanitize_sensitive_data(context: LLMCallHookContext) -> str | None: + if not context.response: + return None + + # Remove sensitive patterns + import re + sanitized = context.response + sanitized = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[SSN-REDACTED]', sanitized) + sanitized = re.sub(r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', '[CARD-REDACTED]', sanitized) + + return sanitized +``` + +### 5. Cost Tracking + +```python +import tiktoken + +@before_llm_call +def track_token_usage(context: LLMCallHookContext) -> None: + encoding = tiktoken.get_encoding("cl100k_base") + total_tokens = sum( + len(encoding.encode(msg.get("content", ""))) + for msg in context.messages + ) + print(f"📊 Input tokens: ~{total_tokens}") + return None + +@after_llm_call +def track_response_tokens(context: LLMCallHookContext) -> None: + if context.response: + encoding = tiktoken.get_encoding("cl100k_base") + tokens = len(encoding.encode(context.response)) + print(f"📊 Response tokens: ~{tokens}") + return None +``` + +### 6. Debug Logging + +```python +@before_llm_call +def debug_request(context: LLMCallHookContext) -> None: + print(f""" + 🔍 LLM Call Debug: + - Agent: {context.agent.role} + - Task: {context.task.description[:50]}... + - Iteration: {context.iterations} + - Message Count: {len(context.messages)} + - Last Message: {context.messages[-1] if context.messages else 'None'} + """) + return None + +@after_llm_call +def debug_response(context: LLMCallHookContext) -> None: + if context.response: + print(f"✅ Response Preview: {context.response[:100]}...") + return None +``` + +## Hook Management + +### Unregistering Hooks + +```python +from crewai.hooks import ( + unregister_before_llm_call_hook, + unregister_after_llm_call_hook +) + +# Unregister specific hook +def my_hook(context): + ... + +register_before_llm_call_hook(my_hook) +# Later... +unregister_before_llm_call_hook(my_hook) # Returns True if found +``` + +### Clearing Hooks + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_all_llm_call_hooks +) + +# Clear specific hook type +count = clear_before_llm_call_hooks() +print(f"Cleared {count} before hooks") + +# Clear all LLM hooks +before_count, after_count = clear_all_llm_call_hooks() +print(f"Cleared {before_count} before and {after_count} after hooks") +``` + +### Listing Registered Hooks + +```python +from crewai.hooks import ( + get_before_llm_call_hooks, + get_after_llm_call_hooks +) + +# Get current hooks +before_hooks = get_before_llm_call_hooks() +after_hooks = get_after_llm_call_hooks() + +print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after") +``` + +## Advanced Patterns + +### Conditional Hook Execution + +```python +@before_llm_call +def conditional_blocking(context: LLMCallHookContext) -> bool | None: + # Only block for specific agents + if context.agent.role == "researcher" and context.iterations > 10: + return False + + # Only block for specific tasks + if "sensitive" in context.task.description.lower() and context.iterations > 5: + return False + + return None +``` + +### Context-Aware Modifications + +```python +@before_llm_call +def adaptive_prompting(context: LLMCallHookContext) -> None: + # Add different context based on iteration + if context.iterations == 0: + context.messages.append({ + "role": "system", + "content": "Start with a high-level overview." + }) + elif context.iterations > 3: + context.messages.append({ + "role": "system", + "content": "Focus on specific details and provide examples." + }) + return None +``` + +### Chaining Hooks + +```python +# Multiple hooks execute in registration order + +@before_llm_call +def first_hook(context): + print("1. First hook executed") + return None + +@before_llm_call +def second_hook(context): + print("2. Second hook executed") + return None + +@before_llm_call +def blocking_hook(context): + if context.iterations > 10: + print("3. Blocking hook - execution stopped") + return False # Subsequent hooks won't execute + print("3. Blocking hook - execution allowed") + return None +``` + +## Best Practices + +1. **Keep Hooks Focused**: Each hook should have a single responsibility +2. **Avoid Heavy Computation**: Hooks execute on every LLM call +3. **Handle Errors Gracefully**: Use try-except to prevent hook failures from breaking execution +4. **Use Type Hints**: Leverage `LLMCallHookContext` for better IDE support +5. **Document Hook Behavior**: Especially for blocking conditions +6. **Test Hooks Independently**: Unit test hooks before using in production +7. **Clear Hooks in Tests**: Use `clear_all_llm_call_hooks()` between test runs +8. **Modify In-Place**: Always modify `context.messages` in-place, never replace + +## Error Handling + +```python +@before_llm_call +def safe_hook(context: LLMCallHookContext) -> bool | None: + try: + # Your hook logic + if some_condition: + return False + except Exception as e: + print(f"⚠️ Hook error: {e}") + # Decide: allow or block on error + return None # Allow execution despite error +``` + +## Type Safety + +```python +from crewai.hooks import LLMCallHookContext, BeforeLLMCallHookType, AfterLLMCallHookType + +# Explicit type annotations +def my_before_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_after_hook(context: LLMCallHookContext) -> str | None: + return None + +# Type-safe registration +register_before_llm_call_hook(my_before_hook) +register_after_llm_call_hook(my_after_hook) +``` + +## Troubleshooting + +### Hook Not Executing +- Verify hook is registered before crew execution +- Check if previous hook returned `False` (blocks subsequent hooks) +- Ensure hook signature matches expected type + +### Message Modifications Not Persisting +- Use in-place modifications: `context.messages.append()` +- Don't replace the list: `context.messages = []` + +### Response Modifications Not Working +- Return the modified string from after hooks +- Returning `None` keeps the original response + +## Conclusion + +LLM Call Hooks provide powerful capabilities for controlling and monitoring language model interactions in CrewAI. Use them to implement safety guardrails, approval gates, logging, cost tracking, and response sanitization. Combined with proper error handling and type safety, hooks enable robust and production-ready agent systems. diff --git a/docs/v1.15.1/en/learn/llm-selection-guide.mdx b/docs/v1.15.1/en/learn/llm-selection-guide.mdx new file mode 100644 index 000000000..30a85462b --- /dev/null +++ b/docs/v1.15.1/en/learn/llm-selection-guide.mdx @@ -0,0 +1,824 @@ +--- +title: "Strategic LLM Selection Guide" +description: "Strategic framework for choosing the right LLM for your CrewAI AI agents and writing effective task and agent definitions" +icon: "brain-circuit" +mode: "wide" +--- + +## The CrewAI Approach to LLM Selection + +Rather than prescriptive model recommendations, we advocate for a **thinking framework** that helps you make informed decisions based on your specific use case, constraints, and requirements. The LLM landscape evolves rapidly, with new models emerging regularly and existing ones being updated frequently. What matters most is developing a systematic approach to evaluation that remains relevant regardless of which specific models are available. + + + This guide focuses on strategic thinking rather than specific model + recommendations, as the LLM landscape evolves rapidly. + + +## Quick Decision Framework + + + + Begin by deeply understanding what your tasks actually require. Consider the + cognitive complexity involved, the depth of reasoning needed, the format of + expected outputs, and the amount of context the model will need to process. + This foundational analysis will guide every subsequent decision. + + + Once you understand your requirements, map them to model strengths. + Different model families excel at different types of work; some are + optimized for reasoning and analysis, others for creativity and content + generation, and others for speed and efficiency. + + + Factor in your real-world operational constraints including budget + limitations, latency requirements, data privacy needs, and infrastructure + capabilities. The theoretically best model may not be the practically best + choice for your situation. + + + Start with reliable, well-understood models and optimize based on actual + performance in your specific use case. Real-world results often differ from + theoretical benchmarks, so empirical testing is crucial. + + + +## Core Selection Framework + +### a. Task-First Thinking + +The most critical step in LLM selection is understanding what your task actually demands. Too often, teams select models based on general reputation or benchmark scores without carefully analyzing their specific requirements. This approach leads to either over-engineering simple tasks with expensive, complex models, or under-powering sophisticated work with models that lack the necessary capabilities. + + + + - **Simple Tasks** represent the majority of everyday AI work and include basic instruction following, straightforward data processing, and simple formatting operations. These tasks typically have clear inputs and outputs with minimal ambiguity. The cognitive load is low, and the model primarily needs to follow explicit instructions rather than engage in complex reasoning. + + - **Complex Tasks** require multi-step reasoning, strategic thinking, and the ability to handle ambiguous or incomplete information. These might involve analyzing multiple data sources, developing comprehensive strategies, or solving problems that require breaking down into smaller components. The model needs to maintain context across multiple reasoning steps and often must make inferences that aren't explicitly stated. + + - **Creative Tasks** demand a different type of cognitive capability focused on generating novel, engaging, and contextually appropriate content. This includes storytelling, marketing copy creation, and creative problem-solving. The model needs to understand nuance, tone, and audience while producing content that feels authentic and engaging rather than formulaic. + + + + + - **Structured Data** tasks require precision and consistency in format adherence. When working with JSON, XML, or database formats, the model must reliably produce syntactically correct output that can be programmatically processed. These tasks often have strict validation requirements and little tolerance for format errors, making reliability more important than creativity. + + - **Creative Content** outputs demand a balance of technical competence and creative flair. The model needs to understand audience, tone, and brand voice while producing content that engages readers and achieves specific communication goals. Quality here is often subjective and requires models that can adapt their writing style to different contexts and purposes. + + - **Technical Content** sits between structured data and creative content, requiring both precision and clarity. Documentation, code generation, and technical analysis need to be accurate and comprehensive while remaining accessible to the intended audience. The model must understand complex technical concepts and communicate them effectively. + + + + + - **Short Context** scenarios involve focused, immediate tasks where the model needs to process limited information quickly. These are often transactional interactions where speed and efficiency matter more than deep understanding. The model doesn't need to maintain extensive conversation history or process large documents. + + - **Long Context** requirements emerge when working with substantial documents, extended conversations, or complex multi-part tasks. The model needs to maintain coherence across thousands of tokens while referencing earlier information accurately. This capability becomes crucial for document analysis, comprehensive research, and sophisticated dialogue systems. + + - **Very Long Context** scenarios push the boundaries of what's currently possible, involving massive document processing, extensive research synthesis, or complex multi-session interactions. These use cases require models specifically designed for extended context handling and often involve trade-offs between context length and processing speed. + + + + +### b. Model Capability Mapping + +Understanding model capabilities requires looking beyond marketing claims and benchmark scores to understand the fundamental strengths and limitations of different model architectures and training approaches. + + + + Reasoning models represent a specialized category designed specifically for complex, multi-step thinking tasks. These models excel when problems require careful analysis, strategic planning, or systematic problem decomposition. They typically employ techniques like chain-of-thought reasoning or tree-of-thought processing to work through complex problems step by step. + + The strength of reasoning models lies in their ability to maintain logical consistency across extended reasoning chains and to break down complex problems into manageable components. They're particularly valuable for strategic planning, complex analysis, and situations where the quality of reasoning matters more than speed of response. + + However, reasoning models often come with trade-offs in terms of speed and cost. They may also be less suitable for creative tasks or simple operations where their sophisticated reasoning capabilities aren't needed. Consider these models when your tasks involve genuine complexity that benefits from systematic, step-by-step analysis. + + + + + General purpose models offer the most balanced approach to LLM selection, providing solid performance across a wide range of tasks without extreme specialization in any particular area. These models are trained on diverse datasets and optimized for versatility rather than peak performance in specific domains. + + The primary advantage of general purpose models is their reliability and predictability across different types of work. They handle most standard business tasks competently, from research and analysis to content creation and data processing. This makes them excellent choices for teams that need consistent performance across varied workflows. + + While general purpose models may not achieve the peak performance of specialized alternatives in specific domains, they offer operational simplicity and reduced complexity in model management. They're often the best starting point for new projects, allowing teams to understand their specific needs before potentially optimizing with more specialized models. + + + + + Fast and efficient models prioritize speed, cost-effectiveness, and resource efficiency over sophisticated reasoning capabilities. These models are optimized for high-throughput scenarios where quick responses and low operational costs are more important than nuanced understanding or complex reasoning. + + These models excel in scenarios involving routine operations, simple data processing, function calling, and high-volume tasks where the cognitive requirements are relatively straightforward. They're particularly valuable for applications that need to process many requests quickly or operate within tight budget constraints. + + The key consideration with efficient models is ensuring that their capabilities align with your task requirements. While they can handle many routine operations effectively, they may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. They're best used for well-defined, routine operations where speed and cost matter more than sophistication. + + + + + Creative models are specifically optimized for content generation, writing quality, and creative thinking tasks. These models typically excel at understanding nuance, tone, and style while producing engaging, contextually appropriate content that feels natural and authentic. + + The strength of creative models lies in their ability to adapt writing style to different audiences, maintain consistent voice and tone, and generate content that engages readers effectively. They often perform better on tasks involving storytelling, marketing copy, brand communications, and other content where creativity and engagement are primary goals. + + When selecting creative models, consider not just their ability to generate text, but their understanding of audience, context, and purpose. The best creative models can adapt their output to match specific brand voices, target different audience segments, and maintain consistency across extended content pieces. + + + + + Open source models offer unique advantages in terms of cost control, customization potential, data privacy, and deployment flexibility. These models can be run locally or on private infrastructure, providing complete control over data handling and model behavior. + + The primary benefits of open source models include elimination of per-token costs, ability to fine-tune for specific use cases, complete data privacy, and independence from external API providers. They're particularly valuable for organizations with strict data privacy requirements, budget constraints, or specific customization needs. + + However, open source models require more technical expertise to deploy and maintain effectively. Teams need to consider infrastructure costs, model management complexity, and the ongoing effort required to keep models updated and optimized. The total cost of ownership may be higher than cloud-based alternatives when factoring in technical overhead. + + + + +## Strategic Configuration Patterns + +### a. Multi-Model Approach + + + Use different models for different purposes within the same crew to optimize + both performance and cost. + + +The most sophisticated CrewAI implementations often employ multiple models strategically, assigning different models to different agents based on their specific roles and requirements. This approach allows teams to optimize for both performance and cost by using the most appropriate model for each type of work. + +Planning agents benefit from reasoning models that can handle complex strategic thinking and multi-step analysis. These agents often serve as the "brain" of the operation, developing strategies and coordinating other agents' work. Content agents, on the other hand, perform best with creative models that excel at writing quality and audience engagement. Processing agents handling routine operations can use efficient models that prioritize speed and cost-effectiveness. + +**Example: Research and Analysis Crew** + +```python +from crewai import Agent, Task, Crew, LLM + +# High-capability reasoning model for strategic planning +manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1) + +# Creative model for content generation +content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7) + +# Efficient model for data processing +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, # High-capability model for complex reasoning + 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, # Creative model for engaging content + 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, # Fast, cost-effective model for routine tasks + verbose=True +) + +crew = Crew( + agents=[research_manager, content_writer, data_processor], + tasks=[...], # Your specific tasks + manager_llm=manager_llm, # Manager uses the reasoning model + verbose=True +) +``` + +The key to successful multi-model implementation is understanding how different agents interact and ensuring that model capabilities align with agent responsibilities. This requires careful planning but can result in significant improvements in both output quality and operational efficiency. + +### b. Component-Specific Selection + + + + The manager LLM plays a crucial role in hierarchical CrewAI processes, serving as the coordination point for multiple agents and tasks. This model needs to excel at delegation, task prioritization, and maintaining context across multiple concurrent operations. + + Effective manager LLMs require strong reasoning capabilities to make good delegation decisions, consistent performance to ensure predictable coordination, and excellent context management to track the state of multiple agents simultaneously. The model needs to understand the capabilities and limitations of different agents while optimizing task allocation for efficiency and quality. + + Cost considerations are particularly important for manager LLMs since they're involved in every operation. The model needs to provide sufficient capability for effective coordination while remaining cost-effective for frequent use. This often means finding models that offer good reasoning capabilities without the premium pricing of the most sophisticated options. + + + + + Function calling LLMs handle tool usage across all agents, making them critical for crews that rely heavily on external tools and APIs. These models need to excel at understanding tool capabilities, extracting parameters accurately, and handling tool responses effectively. + + The most important characteristics for function calling LLMs are precision and reliability rather than creativity or sophisticated reasoning. The model needs to consistently extract the correct parameters from natural language requests and handle tool responses appropriately. Speed is also important since tool usage often involves multiple round trips that can impact overall performance. + + Many teams find that specialized function calling models or general purpose models with strong tool support work better than creative or reasoning-focused models for this role. The key is ensuring that the model can reliably bridge the gap between natural language instructions and structured tool calls. + + + + + Individual agents can override crew-level LLM settings when their specific needs differ significantly from the general crew requirements. This capability allows for fine-tuned optimization while maintaining operational simplicity for most agents. + + Consider agent-specific overrides when an agent's role requires capabilities that differ substantially from other crew members. For example, a creative writing agent might benefit from a model optimized for content generation, while a data analysis agent might perform better with a reasoning-focused model. + + The challenge with agent-specific overrides is balancing optimization with operational complexity. Each additional model adds complexity to deployment, monitoring, and cost management. Teams should focus overrides on agents where the performance improvement justifies the additional complexity. + + + + +## Task Definition Framework + +### a. Focus on Clarity Over Complexity + +Effective task definition is often more important than model selection in determining the quality of CrewAI outputs. Well-defined tasks provide clear direction and context that enable even modest models to perform well, while poorly defined tasks can cause even sophisticated models to produce unsatisfactory results. + + + + The best task descriptions strike a balance between providing sufficient detail and maintaining clarity. They should define the specific objective clearly enough that there's no ambiguity about what success looks like, while explaining the approach or methodology in enough detail that the agent understands how to proceed. + + Effective task descriptions include relevant context and constraints that help the agent understand the broader purpose and any limitations they need to work within. They break complex work into focused steps that can be executed systematically, rather than presenting overwhelming, multi-faceted objectives that are difficult to approach systematically. + + Common mistakes include being too vague about objectives, failing to provide necessary context, setting unclear success criteria, or combining multiple unrelated tasks into a single description. The goal is to provide enough information for the agent to succeed while maintaining focus on a single, clear objective. + + + + + Expected output guidelines serve as a contract between the task definition and the agent, clearly specifying what the deliverable should look like and how it will be evaluated. These guidelines should describe both the format and structure needed, as well as the key elements that must be included for the output to be considered complete. + + The best output guidelines provide concrete examples of quality indicators and define completion criteria clearly enough that both the agent and human reviewers can assess whether the task has been completed successfully. This reduces ambiguity and helps ensure consistent results across multiple task executions. + + Avoid generic output descriptions that could apply to any task, missing format specifications that leave agents guessing about structure, unclear quality standards that make evaluation difficult, or failing to provide examples or templates that help agents understand expectations. + + + + +### b. Task Sequencing Strategy + + + + Sequential task dependencies are essential when tasks build upon previous outputs, information flows from one task to another, or quality depends on the completion of prerequisite work. This approach ensures that each task has access to the information and context it needs to succeed. + + Implementing sequential dependencies effectively requires using the context parameter to chain related tasks, building complexity gradually through task progression, and ensuring that each task produces outputs that serve as meaningful inputs for subsequent tasks. The goal is to maintain logical flow between dependent tasks while avoiding unnecessary bottlenecks. + + Sequential dependencies work best when there's a clear logical progression from one task to another and when the output of one task genuinely improves the quality or feasibility of subsequent tasks. However, they can create bottlenecks if not managed carefully, so it's important to identify which dependencies are truly necessary versus those that are merely convenient. + + + + + Parallel execution becomes valuable when tasks are independent of each other, time efficiency is important, or different expertise areas are involved that don't require coordination. This approach can significantly reduce overall execution time while allowing specialized agents to work on their areas of strength simultaneously. + + Successful parallel execution requires identifying tasks that can truly run independently, grouping related but separate work streams effectively, and planning for result integration when parallel tasks need to be combined into a final deliverable. The key is ensuring that parallel tasks don't create conflicts or redundancies that reduce overall quality. + + Consider parallel execution when you have multiple independent research streams, different types of analysis that don't depend on each other, or content creation tasks that can be developed simultaneously. However, be mindful of resource allocation and ensure that parallel execution doesn't overwhelm your available model capacity or budget. + + + + +## Optimizing Agent Configuration for LLM Performance + +### a. Role-Driven LLM Selection + + + Generic agent roles make it impossible to select the right LLM. Specific roles + enable targeted model optimization. + + +The specificity of your agent roles directly determines which LLM capabilities matter most for optimal performance. This creates a strategic opportunity to match precise model strengths with agent responsibilities. + +**Generic vs. Specific Role Impact on LLM Choice:** + +When defining roles, think about the specific domain knowledge, working style, and decision-making frameworks that would be most valuable for the tasks the agent will handle. The more specific and contextual the role definition, the better the model can embody that role effectively. + +```python +# ✅ Specific role - clear LLM requirements +specific_agent = Agent( + role="SaaS Revenue Operations Analyst", # Clear domain expertise needed + 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") # Reasoning model justified for complex analysis +) +``` + +**Role-to-Model Mapping Strategy:** + +- **"Research Analyst"** → Reasoning model (GPT-4o, Claude Sonnet) for complex analysis +- **"Content Editor"** → Creative model (Claude, GPT-4o) for writing quality +- **"Data Processor"** → Efficient model (GPT-4o-mini, Gemini Flash) for structured tasks +- **"API Coordinator"** → Function-calling optimized model (GPT-4o, Claude) for tool usage + +### b. Backstory as Model Context Amplifier + + + Strategic backstories multiply your chosen LLM's effectiveness by providing + domain-specific context that generic prompting cannot achieve. + + +A well-crafted backstory transforms your LLM choice from generic capability to specialized expertise. This is especially crucial for cost optimization - a well-contextualized efficient model can outperform a premium model without proper context. + +**Context-Driven Performance Example:** + +```python +# Context amplifies model effectiveness +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) # Balanced creativity with domain knowledge +) + +# This context enables Claude to perform like a domain expert +# Without it, even it would produce generic marketing advice +``` + +**Backstory Elements That Enhance LLM Performance:** + +- **Domain Experience**: "10+ years in enterprise SaaS sales" +- **Specific Expertise**: "Specializes in technical due diligence for Series B+ rounds" +- **Working Style**: "Prefers data-driven decisions with clear documentation" +- **Quality Standards**: "Insists on citing sources and showing analytical work" + +### c. Holistic Agent-LLM Optimization + +The most effective agent configurations create synergy between role specificity, backstory depth, and LLM selection. Each element reinforces the others to maximize model performance. + +**Optimization Framework:** + +```python +# Example: Technical Documentation Agent +tech_writer = Agent( + role="API Documentation Specialist", # Specific role for clear LLM requirements + 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", # Excellent for technical writing + temperature=0.1 # Low temperature for accuracy + ), + tools=[code_analyzer_tool, api_scanner_tool], + verbose=True +) +``` + +**Alignment Checklist:** + +- ✅ **Role Specificity**: Clear domain and responsibilities +- ✅ **LLM Match**: Model strengths align with role requirements +- ✅ **Backstory Depth**: Provides domain context the LLM can leverage +- ✅ **Tool Integration**: Tools support the agent's specialized function +- ✅ **Parameter Tuning**: Temperature and settings optimize for role needs + +The key is creating agents where every configuration choice reinforces your LLM selection strategy, maximizing performance while optimizing costs. + +## Practical Implementation Checklist + +Rather than repeating the strategic framework, here's a tactical checklist for implementing your LLM selection decisions in CrewAI: + + + + **What to Review:** + - Are all agents using the same LLM by default? + - Which agents handle the most complex reasoning tasks? + - Which agents primarily do data processing or formatting? + - Are any agents heavily tool-dependent? + + **Action**: Document current agent roles and identify optimization opportunities. + + + + + **Set Your Baseline:** + ```python + # Start with a reliable default for the crew + default_crew_llm = LLM(model="gpt-4o-mini") # Cost-effective baseline + + crew = Crew( + agents=[...], + tasks=[...], + memory=True + ) + ``` + + **Action**: Establish your crew's default LLM before optimizing individual agents. + + + + + **Identify and Upgrade Key Agents:** + ```python + # Manager or coordination agents + manager_agent = Agent( + role="Project Manager", + llm=LLM(model="gemini-2.5-flash-preview-05-20"), # Premium for coordination + # ... rest of config + ) + + # Creative or customer-facing agents + content_agent = Agent( + role="Content Creator", + llm=LLM(model="claude-3-5-sonnet"), # Best for writing + # ... rest of config + ) + ``` + + **Action**: Upgrade 20% of your agents that handle 80% of the complexity. + + + + + **Once you deploy your agents to production:** + - Use [CrewAI AMP platform](https://app.crewai.com) to A/B test your model selections + - Run multiple iterations with real inputs to measure consistency and performance + - Compare cost vs. performance across your optimized setup + - Share results with your team for collaborative decision-making + + **Action**: Replace guesswork with data-driven validation using the testing platform. + + + + +### When to Use Different Model Types + + + + Reasoning models become essential when tasks require genuine multi-step logical thinking, strategic planning, or high-level decision making that benefits from systematic analysis. These models excel when problems need to be broken down into components and analyzed systematically rather than handled through pattern matching or simple instruction following. + + Consider reasoning models for business strategy development, complex data analysis that requires drawing insights from multiple sources, multi-step problem solving where each step depends on previous analysis, and strategic planning tasks that require considering multiple variables and their interactions. + + However, reasoning models often come with higher costs and slower response times, so they're best reserved for tasks where their sophisticated capabilities provide genuine value rather than being used for simple operations that don't require complex reasoning. + + + + + Creative models become valuable when content generation is the primary output and the quality, style, and engagement level of that content directly impact success. These models excel when writing quality and style matter significantly, creative ideation or brainstorming is needed, or brand voice and tone are important considerations. + + Use creative models for blog post writing and article creation, marketing copy that needs to engage and persuade, creative storytelling and narrative development, and brand communications where voice and tone are crucial. These models often understand nuance and context better than general purpose alternatives. + + Creative models may be less suitable for technical or analytical tasks where precision and factual accuracy are more important than engagement and style. They're best used when the creative and communicative aspects of the output are primary success factors. + + + + + Efficient models are ideal for high-frequency, routine operations where speed and cost optimization are priorities. These models work best when tasks have clear, well-defined parameters and don't require sophisticated reasoning or creative capabilities. + + Consider efficient models for data processing and transformation tasks, simple formatting and organization operations, function calling and tool usage where precision matters more than sophistication, and high-volume operations where cost per operation is a significant factor. + + The key with efficient models is ensuring that their capabilities align with task requirements. They can handle many routine operations effectively but may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. + + + + + Open source models become attractive when budget constraints are significant, data privacy requirements exist, customization needs are important, or local deployment is required for operational or compliance reasons. + + Consider open source models for internal company tools where data privacy is paramount, privacy-sensitive applications that can't use external APIs, cost-optimized deployments where per-token pricing is prohibitive, and situations requiring custom model modifications or fine-tuning. + + However, open source models require more technical expertise to deploy and maintain effectively. Consider the total cost of ownership including infrastructure, technical overhead, and ongoing maintenance when evaluating open source options. + + + + +## Common CrewAI Model Selection Pitfalls + + + + **The Problem**: Using the same LLM for all agents in a crew, regardless of their specific roles and responsibilities. This is often the default approach but rarely optimal. + + **Real Example**: Using GPT-4o for both a strategic planning manager and a data extraction agent. The manager needs reasoning capabilities worth the premium cost, but the data extractor could perform just as well with GPT-4o-mini at a fraction of the price. + + **CrewAI Solution**: Leverage agent-specific LLM configuration to match model capabilities with agent roles: + ```python + # Strategic agent gets premium model + manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o")) + + # Processing agent gets efficient model + processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini")) + ``` + + + + + **The Problem**: Not understanding how CrewAI's LLM hierarchy works - crew LLM, manager LLM, and agent LLM settings can conflict or be poorly coordinated. + + **Real Example**: Setting a crew to use Claude, but having agents configured with GPT models, creating inconsistent behavior and unnecessary model switching overhead. + + **CrewAI Solution**: Plan your LLM hierarchy strategically: + ```python + crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + manager_llm=LLM(model="gpt-4o"), # For crew coordination + process=Process.hierarchical # When using manager_llm + ) + + # Agents inherit crew LLM unless specifically overridden + agent1 = Agent(llm=LLM(model="claude-3-5-sonnet")) # Override for specific needs + ``` + + + + + **The Problem**: Choosing models based on general capabilities while ignoring function calling performance for tool-heavy CrewAI workflows. + + **Real Example**: Selecting a creative-focused model for an agent that primarily needs to call APIs, search tools, or process structured data. The agent struggles with tool parameter extraction and reliable function calls. + + **CrewAI Solution**: Prioritize function calling capabilities for tool-heavy agents: + ```python + # For agents that use many tools + tool_agent = Agent( + role="API Integration Specialist", + tools=[search_tool, api_tool, data_tool], + llm=LLM(model="gpt-4o"), # Excellent function calling + # OR + llm=LLM(model="claude-3-5-sonnet") # Also strong with tools + ) + ``` + + + + + **The Problem**: Making complex model selection decisions based on theoretical performance without validating with actual CrewAI workflows and tasks. + + **Real Example**: Implementing elaborate model switching logic based on task types without testing if the performance gains justify the operational complexity. + + **CrewAI Solution**: Start simple, then optimize based on real performance data: + ```python + # Start with this + crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini")) + + # Test performance, then optimize specific agents as needed + # Use Enterprise platform testing to validate improvements + ``` + + + + + **The Problem**: Not considering how model context windows interact with CrewAI's memory and context sharing between agents. + + **Real Example**: Using a short-context model for agents that need to maintain conversation history across multiple task iterations, or in crews with extensive agent-to-agent communication. + + **CrewAI Solution**: Match context capabilities to crew communication patterns. + + + + +## Testing and Iteration Strategy + + + + Begin with reliable, general-purpose models that are well-understood and + widely supported. This provides a stable foundation for understanding your + specific requirements and performance expectations before optimizing for + specialized needs. + + + Develop metrics that align with your specific use case and business + requirements rather than relying solely on general benchmarks. Focus on + measuring outcomes that directly impact your success rather than theoretical + performance indicators. + + + Make model changes based on observed performance in your specific context + rather than theoretical considerations or general recommendations. + Real-world performance often differs significantly from benchmark results or + general reputation. + + + Evaluate the complete cost of ownership including model costs, development + time, maintenance overhead, and operational complexity. The cheapest model + per token may not be the most cost-effective choice when considering all + factors. + + + + + Focus on understanding your requirements first, then select models that best + match those needs. The best LLM choice is the one that consistently delivers + the results you need within your operational constraints. + + +### Enterprise-Grade Model Validation + +For teams serious about optimizing their LLM selection, the **CrewAI AMP platform** provides sophisticated testing capabilities that go far beyond basic CLI testing. The platform enables comprehensive model evaluation that helps you make data-driven decisions about your LLM strategy. + + + ![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png) + + +**Advanced Testing Features:** + +- **Multi-Model Comparison**: Test multiple LLMs simultaneously across the same tasks and inputs. Compare performance between GPT-4o, Claude, Llama, Groq, Cerebras, and other leading models in parallel to identify the best fit for your specific use case. + +- **Statistical Rigor**: Configure multiple iterations with consistent inputs to measure reliability and performance variance. This helps identify models that not only perform well but do so consistently across runs. + +- **Real-World Validation**: Use your actual crew inputs and scenarios rather than synthetic benchmarks. The platform allows you to test with your specific industry context, company information, and real use cases for more accurate evaluation. + +- **Comprehensive Analytics**: Access detailed performance metrics, execution times, and cost analysis across all tested models. This enables data-driven decision making rather than relying on general model reputation or theoretical capabilities. + +- **Team Collaboration**: Share testing results and model performance data across your team, enabling collaborative decision-making and consistent model selection strategies across projects. + +Go to [app.crewai.com](https://app.crewai.com) to get started! + + + The Enterprise platform transforms model selection from guesswork into a + data-driven process, enabling you to validate the principles in this guide + with your actual use cases and requirements. + + +## Key Principles Summary + + + + Choose models based on what the task actually requires, not theoretical capabilities or general reputation. + + +{" "} + + Align model strengths with agent roles and responsibilities for optimal + performance. + + +{" "} + + Maintain coherent model selection strategy across related components and + workflows. + + +{" "} + + Validate choices through real-world usage rather than benchmarks alone. + + +{" "} + + Start simple and optimize based on actual performance and needs. + + + + Balance performance requirements with cost and complexity constraints. + + + + + Remember: The best LLM choice is the one that consistently delivers the + results you need within your operational constraints. Focus on understanding + your requirements first, then select models that best match those needs. + + +## Current Model Landscape (June 2025) + + + **Snapshot in Time**: The following model rankings represent current + leaderboard standings as of June 2025, compiled from [LMSys + Arena](https://arena.lmsys.org/), [Artificial + Analysis](https://artificialanalysis.ai/), and other leading benchmarks. LLM + performance, availability, and pricing change rapidly. Always conduct your own + evaluations with your specific use cases and data. + + +### Leading Models by Category + +The tables below show a representative sample of current top-performing models across different categories, with guidance on their suitability for CrewAI agents: + + + These tables/metrics showcase selected leading models in each category and are + not exhaustive. Many excellent models exist beyond those listed here. The goal + is to illustrate the types of capabilities to look for rather than provide a + complete catalog. + + + + + **Best for Manager LLMs and Complex Analysis** + + | Model | Intelligence Score | Cost ($/M tokens) | Speed | Best Use in CrewAI | + |:------|:------------------|:------------------|:------|:------------------| + | **o3** | 70 | $17.50 | Fast | Manager LLM for complex multi-agent coordination | + | **Gemini 2.5 Pro** | 69 | $3.44 | Fast | Strategic planning agents, research coordination | + | **DeepSeek R1** | 68 | $0.96 | Moderate | Cost-effective reasoning for budget-conscious crews | + | **Claude 4 Sonnet** | 53 | $6.00 | Fast | Analysis agents requiring nuanced understanding | + | **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderate | Open-source alternative for reasoning tasks | + + These models excel at multi-step reasoning and are ideal for agents that need to develop strategies, coordinate other agents, or analyze complex information. + + + + + **Best for Development and Tool-Heavy Workflows** + + | Model | Coding Performance | Tool Use Score | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:------------------|:---------------|:------------------|:------------------| + | **Claude 4 Sonnet** | Excellent | 72.7% | $6.00 | Primary coding agent, technical documentation | + | **Claude 4 Opus** | Excellent | 72.5% | $30.00 | Complex software architecture, code review | + | **DeepSeek V3** | Very Good | High | $0.48 | Cost-effective coding for routine development | + | **Qwen2.5 Coder 32B** | Very Good | Medium | $0.15 | Budget-friendly coding agent | + | **Llama 3.1 405B** | Good | 81.1% | $3.50 | Function calling LLM for tool-heavy workflows | + + These models are optimized for code generation, debugging, and technical problem-solving, making them ideal for development-focused crews. + + + + + **Best for High-Throughput and Real-Time Applications** + + | Model | Speed (tokens/s) | Latency (TTFT) | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:-----------------|:---------------|:------------------|:------------------| + | **Llama 4 Scout** | 2,600 | 0.33s | $0.27 | High-volume processing agents | + | **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Real-time response agents | + | **DeepSeek R1 Distill** | 383 | Variable | $0.04 | Cost-optimized high-speed processing | + | **Llama 3.3 70B** | 2,500 | 0.52s | $0.60 | Balanced speed and capability | + | **Nova Micro** | High | 0.30s | $0.04 | Simple, fast task execution | + + These models prioritize speed and efficiency, perfect for agents handling routine operations or requiring quick responses. **Pro tip**: Pairing these models with fast inference providers like Groq can achieve even better performance, especially for open-source models like Llama. + + + + + **Best All-Around Models for General Crews** + + | Model | Overall Score | Versatility | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:--------------|:------------|:------------------|:------------------| + | **GPT-4.1** | 53 | Excellent | $3.50 | General-purpose crew LLM | + | **Claude 3.7 Sonnet** | 48 | Very Good | $6.00 | Balanced reasoning and creativity | + | **Gemini 2.0 Flash** | 48 | Good | $0.17 | Cost-effective general use | + | **Llama 4 Maverick** | 51 | Good | $0.37 | Open-source general purpose | + | **Qwen3 32B** | 44 | Good | $1.23 | Budget-friendly versatility | + + These models offer good performance across multiple dimensions, suitable for crews with diverse task requirements. + + + + +### Selection Framework for Current Models + + + + **When performance is the priority**: Use top-tier models like **o3**, **Gemini 2.5 Pro**, or **Claude 4 Sonnet** for manager LLMs and critical agents. These models excel at complex reasoning and coordination but come with higher costs. + + **Strategy**: Implement a multi-model approach where premium models handle strategic thinking while efficient models handle routine operations. + + + + + **When budget is a primary constraint**: Focus on models like **DeepSeek R1**, **Llama 4 Scout**, or **Gemini 2.0 Flash**. These provide strong performance at significantly lower costs. + + **Strategy**: Use cost-effective models for most agents, reserving premium models only for the most critical decision-making roles. + + + + + **For specific domain expertise**: Choose models optimized for your primary use case. **Claude 4** series for coding, **Gemini 2.5 Pro** for research, **Llama 405B** for function calling. + + **Strategy**: Select models based on your crew's primary function, ensuring the core capability aligns with model strengths. + + + + + **For data-sensitive operations**: Consider open-source models like **Llama 4** series, **DeepSeek V3**, or **Qwen3** that can be deployed locally while maintaining competitive performance. + + **Strategy**: Deploy open-source models on private infrastructure, accepting potential performance trade-offs for data control. + + + + +### Key Considerations for Model Selection + +- **Performance Trends**: The current landscape shows strong competition between reasoning-focused models (o3, Gemini 2.5 Pro) and balanced models (Claude 4, GPT-4.1). Specialized models like DeepSeek R1 offer excellent cost-performance ratios. + +- **Speed vs. Intelligence Trade-offs**: Models like Llama 4 Scout prioritize speed (2,600 tokens/s) while maintaining reasonable intelligence, whereas models like o3 maximize reasoning capability at the cost of speed and price. + +- **Open Source Viability**: The gap between open-source and proprietary models continues to narrow, with models like Llama 4 Maverick and DeepSeek V3 offering competitive performance at attractive price points. Fast inference providers particularly shine with open-source models, often delivering better speed-to-cost ratios than proprietary alternatives. + + + **Testing is Essential**: Leaderboard rankings provide general guidance, but + your specific use case, prompting style, and evaluation criteria may produce + different results. Always test candidate models with your actual tasks and + data before making final decisions. + + +### Practical Implementation Strategy + + + + Begin with well-established models like **GPT-4.1**, **Claude 3.7 Sonnet**, or **Gemini 2.0 Flash** that offer good performance across multiple dimensions and have extensive real-world validation. + + + + Determine if your crew has specific requirements (coding, reasoning, speed) + that would benefit from specialized models like **Claude 4 Sonnet** for + development or **o3** for complex analysis. For speed-critical applications, + consider fast inference providers like **Groq** alongside model selection. + + + + Use different models for different agents based on their roles. + High-capability models for managers and complex tasks, efficient models for + routine operations. + + + + Track performance metrics relevant to your use case and be prepared to adjust model selections as new models are released or pricing changes. + + diff --git a/docs/v1.15.1/en/learn/multimodal-agents.mdx b/docs/v1.15.1/en/learn/multimodal-agents.mdx new file mode 100644 index 000000000..1b414cac9 --- /dev/null +++ b/docs/v1.15.1/en/learn/multimodal-agents.mdx @@ -0,0 +1,141 @@ +--- +title: Using Multimodal Agents +description: Learn how to enable and use multimodal capabilities in your agents for processing images and other non-text content within the CrewAI framework. +icon: video +mode: "wide" +--- + +## Using Multimodal Agents + +CrewAI supports multimodal agents that can process both text and non-text content like images. This guide will show you how to enable and use multimodal capabilities in your agents. + +### Enabling Multimodal Capabilities + +To create a multimodal agent, simply set the `multimodal` parameter to `True` when initializing your agent: + +```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 +) +``` + +When you set `multimodal=True`, the agent is automatically configured with the necessary tools for handling non-text content, including the `AddImageTool`. + +### Working with Images + +The multimodal agent comes pre-configured with the `AddImageTool`, which allows it to process images. You don't need to manually add this tool - it's automatically included when you enable multimodal capabilities. + +Here's a complete example showing how to use a multimodal agent to analyze an image: + +```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() +``` + +### Advanced Usage with Context + +You can provide additional context or specific questions about the image when creating tasks for multimodal agents. The task description can include specific aspects you want the agent to focus on: + +```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() +``` + +### Tool Details + +When working with multimodal agents, the `AddImageTool` is automatically configured with the following schema: + +```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 +``` + +The multimodal agent will automatically handle the image processing through its built-in tools, allowing it to: +- Access images via URLs or local file paths +- Process image content with optional context or specific questions +- Provide analysis and insights based on the visual information and task requirements + +### Best Practices + +When working with multimodal agents, keep these best practices in mind: + +1. **Image Access** + - Ensure your images are accessible via URLs that the agent can reach + - For local images, consider hosting them temporarily or using absolute file paths + - Verify that image URLs are valid and accessible before running tasks + +2. **Task Description** + - Be specific about what aspects of the image you want the agent to analyze + - Include clear questions or requirements in the task description + - Consider using the optional `action` parameter for focused analysis + +3. **Resource Management** + - Image processing may require more computational resources than text-only tasks + - Some language models may require base64 encoding for image data + - Consider batch processing for multiple images to optimize performance + +4. **Environment Setup** + - Verify that your environment has the necessary dependencies for image processing + - Ensure your language model supports multimodal capabilities + - Test with small images first to validate your setup + +5. **Error Handling** + - Implement proper error handling for image loading failures + - Have fallback strategies for when image processing fails + - Monitor and log image processing operations for debugging diff --git a/docs/v1.15.1/en/learn/overview.mdx b/docs/v1.15.1/en/learn/overview.mdx new file mode 100644 index 000000000..7b82aef3a --- /dev/null +++ b/docs/v1.15.1/en/learn/overview.mdx @@ -0,0 +1,159 @@ +--- +title: "Overview" +description: "Learn how to build, customize, and optimize your CrewAI applications with comprehensive guides and tutorials" +icon: "face-smile" +mode: "wide" +--- + +## Learn CrewAI + +This section provides comprehensive guides and tutorials to help you master CrewAI, from basic concepts to advanced techniques. Whether you're just getting started or looking to optimize your existing implementations, these resources will guide you through every aspect of building powerful AI agent workflows. + +## Getting Started Guides + +### 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. + + + +## Advanced Features + +### 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. + + + +## Specialized Applications + +### 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. + + + +## Learning Path Recommendations + +### For Beginners +1. Start with **Sequential Process** to understand basic workflow execution +2. Learn **Customizing Agents** to create effective agent configurations +3. Explore **Create Custom Tools** to extend functionality +4. Try **Human in the Loop** for interactive workflows + +### For Intermediate Users +1. Master **Hierarchical Process** for complex multi-agent systems +2. Implement **Conditional Tasks** for dynamic workflows +3. Use **Async Kickoff** for performance optimization +4. Integrate **Custom LLM** for specialized models + +### For Advanced Users +1. Build **Multimodal Agents** for complex media processing +2. Create **Custom Manager Agents** for sophisticated orchestration +3. Implement **Bring Your Own Agent** for hybrid systems +4. Use **Replay Tasks** for robust error recovery + +## Best Practices + +### Development +- **Start Simple**: Begin with basic sequential workflows before adding complexity +- **Test Incrementally**: Test each component before integrating into larger systems +- **Use Annotations**: Leverage Python annotations for cleaner, more maintainable code +- **Custom Tools**: Build reusable tools that can be shared across different agents + +### Production +- **Error Handling**: Implement robust error handling and recovery mechanisms +- **Performance**: Use async execution and optimize LLM calls for better performance +- **Monitoring**: Integrate observability tools to track agent performance +- **Human Oversight**: Include human checkpoints for critical decisions + +### Optimization +- **Resource Management**: Monitor and optimize token usage and API costs +- **Workflow Design**: Design workflows that minimize unnecessary LLM calls +- **Tool Efficiency**: Create efficient tools that provide maximum value with minimal overhead +- **Iterative Improvement**: Use feedback and metrics to continuously improve agent performance + +## Getting Help + +- **Documentation**: Each guide includes detailed examples and explanations +- **Community**: Join the [CrewAI Forum](https://community.crewai.com) for discussions and support +- **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. diff --git a/docs/v1.15.1/en/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/v1.15.1/en/learn/replay-tasks-from-latest-crew-kickoff.mdx new file mode 100644 index 000000000..07b452b5f --- /dev/null +++ b/docs/v1.15.1/en/learn/replay-tasks-from-latest-crew-kickoff.mdx @@ -0,0 +1,79 @@ +--- +title: Replay Tasks from Latest Crew Kickoff +description: Replay tasks from the latest crew.kickoff(...) +icon: arrow-right +mode: "wide" +--- + +## Introduction + +CrewAI provides the ability to replay from a task specified from the latest crew kickoff. This feature is particularly useful when you've finished a kickoff and may want to retry certain tasks or don't need to refetch data over and your agents already have the context saved from the kickoff execution so you just need to replay the tasks you want to. + + + You must run `crew.kickoff()` before you can replay a task. + Currently, only the latest kickoff is supported, so if you use `kickoff_for_each`, it will only allow you to replay from the most recent crew run. + + +Here's an example of how to replay from a task: + +### Replaying from Specific Task Using the CLI + +To use the replay feature, follow these steps: + + + + + + To view the latest kickoff task_ids use: + + ```shell + crewai log-tasks-outputs + ``` + + Once you have your `task_id` to replay, use: + + ```shell + crewai replay -t + ``` + + + + + Ensure `crewai` is installed and configured correctly in your development environment. + + +### Replaying from a Task Programmatically + +To replay from a task programmatically, use the following steps: + + + + Specify the `task_id` and input parameters for the replay process. + + + Execute the replay command within a try-except block to handle potential errors. + + ```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}") + ``` + + + + +## Conclusion + +With the above enhancements and detailed functionality, replaying specific tasks in CrewAI has been made more efficient and robust. +Ensure you follow the commands and steps precisely to make the most of these features. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/sequential-process.mdx b/docs/v1.15.1/en/learn/sequential-process.mdx new file mode 100644 index 000000000..940ff5bc0 --- /dev/null +++ b/docs/v1.15.1/en/learn/sequential-process.mdx @@ -0,0 +1,128 @@ +--- +title: Sequential Processes +description: A comprehensive guide to utilizing the sequential processes for task execution in CrewAI projects. +icon: forward +mode: "wide" +--- + +## Introduction + +CrewAI offers a flexible framework for executing tasks in a structured manner, supporting both sequential and hierarchical processes. +This guide outlines how to effectively implement these processes to ensure efficient task execution and project completion. + +## Sequential Process Overview + +The sequential process ensures tasks are executed one after the other, following a linear progression. +This approach is ideal for projects requiring tasks to be completed in a specific order. + +### Key Features + +- **Linear Task Flow**: Ensures orderly progression by handling tasks in a predetermined sequence. +- **Simplicity**: Best suited for projects with clear, step-by-step tasks. +- **Easy Monitoring**: Facilitates easy tracking of task completion and project progress. + +## Implementing the Sequential Process + +To use the sequential process, assemble your crew and define tasks in the order they need to be executed. + +```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 +``` + +### Note: + +Each task in a sequential process **must** have an agent assigned. Ensure that every `Task` includes an `agent` parameter. + +### Workflow in Action + +1. **Initial Task**: In a sequential process, the first agent completes their task and signals completion. +2. **Subsequent Tasks**: Agents pick up their tasks based on the process type, with outcomes of preceding tasks or directives guiding their execution. +3. **Completion**: The process concludes once the final task is executed, leading to project completion. + +## Advanced Features + +### Task Delegation + +In sequential processes, if an agent has `allow_delegation` set to `True`, they can delegate tasks to other agents in the crew. +This feature is automatically set up when there are multiple agents in the crew. + +### Asynchronous Execution + +Tasks can be executed asynchronously, allowing for parallel processing when appropriate. +To create an asynchronous task, set `async_execution=True` when defining the task. + +### Memory and Caching + +CrewAI supports both memory and caching features: + +- **Memory**: Enable by setting `memory=True` when creating the Crew. This allows agents to retain information across tasks. +- **Caching**: By default, caching is enabled. Set `cache=False` to disable it. + +### Callbacks + +You can set callbacks at both the task and step level: + +- `task_callback`: Executed after each task completion. +- `step_callback`: Executed after each step in an agent's execution. + +### Usage Metrics + +CrewAI tracks token usage across all tasks and agents. You can access these metrics after execution. + +## Best Practices for Sequential Processes + +1. **Order Matters**: Arrange tasks in a logical sequence where each task builds upon the previous one. +2. **Clear Task Descriptions**: Provide detailed descriptions for each task to guide the agents effectively. +3. **Appropriate Agent Selection**: Match agents' skills and roles to the requirements of each task. +4. **Use Context**: Leverage the context from previous tasks to inform subsequent ones. + +This updated documentation ensures that details accurately reflect the latest changes in the codebase and clearly describes how to leverage new features and configurations. +The content is kept simple and direct to ensure easy understanding. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/streaming-crew-execution.mdx b/docs/v1.15.1/en/learn/streaming-crew-execution.mdx new file mode 100644 index 000000000..ff0a3cd7f --- /dev/null +++ b/docs/v1.15.1/en/learn/streaming-crew-execution.mdx @@ -0,0 +1,384 @@ +--- +title: Streaming Crew Execution +description: Stream real-time output from your CrewAI crew execution +icon: wave-pulse +mode: "wide" +--- + +## Introduction + +CrewAI provides the ability to stream real-time output during crew execution, allowing you to display results as they're generated rather than waiting for the entire process to complete. This feature is particularly useful for building interactive applications, providing user feedback, and monitoring long-running processes. + +## How Streaming Works + +When streaming is enabled, CrewAI captures LLM responses and tool calls as they happen, packaging them into structured chunks that include context about which task and agent is executing. You can iterate over these chunks in real-time and access the final result once execution completes. + +## Enabling Streaming + +To enable streaming, set the `stream` parameter to `True` when creating your crew: + +```python Code +from crewai import Agent, Crew, Task + +# Create your agents and tasks +researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information on topics", + backstory="You are an experienced researcher with excellent analytical skills.", +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A detailed report on recent AI advancements", + agent=researcher, +) + +# Enable streaming +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True # Enable streaming output +) +``` + +## Synchronous Streaming + +When you call `kickoff()` on a crew with streaming enabled, it returns a `CrewStreamingOutput` object that you can iterate over to receive chunks as they arrive: + +```python Code +# Start streaming execution +streaming = crew.kickoff(inputs={"topic": "artificial intelligence"}) + +# Iterate over chunks as they arrive +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access the final result after streaming completes +result = streaming.result +print(f"\n\nFinal output: {result.raw}") +``` + +### Stream Chunk Information + +Each chunk provides rich context about the execution: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +for chunk in streaming: + print(f"Task: {chunk.task_name} (index {chunk.task_index})") + print(f"Agent: {chunk.agent_role}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT or TOOL_CALL + if chunk.tool_call: + print(f"Tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +### Accessing Streaming Results + +The `CrewStreamingOutput` object provides several useful properties: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +# Iterate and collect chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# After iteration completes +print(f"\nCompleted: {streaming.is_completed}") +print(f"Full text: {streaming.get_full_text()}") +print(f"All chunks: {len(streaming.chunks)}") +print(f"Final result: {streaming.result.raw}") +``` + +## Asynchronous Streaming + +For async applications, you can use either `akickoff()` (native async) or `kickoff_async()` (thread-based) with async iteration: + +### Native Async with `akickoff()` + +The `akickoff()` method provides true native async execution throughout the entire chain: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Start native async streaming + streaming = await crew.akickoff(inputs={"topic": "AI"}) + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result.raw}") + +asyncio.run(stream_crew()) +``` + +### Thread-Based Async with `kickoff_async()` + +For simpler async integration or backward compatibility: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Start thread-based async streaming + streaming = await crew.kickoff_async(inputs={"topic": "AI"}) + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result.raw}") + +asyncio.run(stream_crew()) +``` + + +For high-concurrency workloads, `akickoff()` is recommended as it uses native async for task execution, memory operations, and knowledge retrieval. See the [Kickoff Crew Asynchronously](/en/learn/kickoff-async) guide for more details. + + +## Streaming with kickoff_for_each + +When executing a crew for multiple inputs with `kickoff_for_each()`, streaming works differently depending on whether you use sync or async: + +### Synchronous kickoff_for_each + +With synchronous `kickoff_for_each()`, you get a list of `CrewStreamingOutput` objects, one for each input: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} +] + +# Returns list of streaming outputs +streaming_outputs = crew.kickoff_for_each(inputs=inputs_list) + +# Iterate over each streaming output +for i, streaming in enumerate(streaming_outputs): + print(f"\n=== Input {i + 1} ===") + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\n\nResult {i + 1}: {result.raw}") +``` + +### Asynchronous kickoff_for_each_async + +With async `kickoff_for_each_async()`, you get a single `CrewStreamingOutput` that yields chunks from all crews as they arrive concurrently: + +```python Code +import asyncio + +async def stream_multiple_crews(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} + ] + + # Returns single streaming output for all crews + streaming = await crew.kickoff_for_each_async(inputs=inputs_list) + + # Chunks from all crews arrive as they're generated + async for chunk in streaming: + print(f"[{chunk.task_name}] {chunk.content}", end="", flush=True) + + # Access all results + results = streaming.results # List of CrewOutput objects + for i, result in enumerate(results): + print(f"\n\nResult {i + 1}: {result.raw}") + +asyncio.run(stream_multiple_crews()) +``` + +## Stream Chunk Types + +Chunks can be of different types, indicated by the `chunk_type` field: + +### TEXT Chunks + +Standard text content from LLM responses: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### TOOL_CALL Chunks + +Information about tool calls being made: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL: + print(f"\nCalling tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +## Practical Example: Building a UI with Streaming + +Here's a complete example showing how to build an interactive application with streaming: + +```python Code +import asyncio +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +async def interactive_research(): + # Create crew with streaming enabled + researcher = Agent( + role="Research Analyst", + goal="Provide detailed analysis on any topic", + backstory="You are an expert researcher with broad knowledge.", + ) + + task = Task( + description="Research and analyze: {topic}", + expected_output="A comprehensive analysis with key insights", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True, + verbose=False + ) + + # Get user input + topic = input("Enter a topic to research: ") + + print(f"\n{'='*60}") + print(f"Researching: {topic}") + print(f"{'='*60}\n") + + # Start streaming execution + streaming = await crew.kickoff_async(inputs={"topic": topic}) + + current_task = "" + async for chunk in streaming: + # Show task transitions + if chunk.task_name != current_task: + current_task = chunk.task_name + print(f"\n[{chunk.agent_role}] Working on: {chunk.task_name}") + print("-" * 60) + + # Display text chunks + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Display tool calls + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Using tool: {chunk.tool_call.tool_name}") + + # Show final result + result = streaming.result + print(f"\n\n{'='*60}") + print("Analysis Complete!") + print(f"{'='*60}") + print(f"\nToken Usage: {result.token_usage}") + +asyncio.run(interactive_research()) +``` + +## Use Cases + +Streaming is particularly valuable for: + +- **Interactive Applications**: Provide real-time feedback to users as agents work +- **Long-Running Tasks**: Show progress for research, analysis, or content generation +- **Debugging and Monitoring**: Observe agent behavior and decision-making in real-time +- **User Experience**: Reduce perceived latency by showing incremental results +- **Live Dashboards**: Build monitoring interfaces that display crew execution status + +## Cancellation and Resource Cleanup + +`CrewStreamingOutput` supports graceful cancellation so that in-flight work stops promptly when the consumer disconnects. + +### Async Context Manager + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### Explicit Cancellation + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # async + # streaming.close() # sync equivalent +``` + +After cancellation, `streaming.is_cancelled` and `streaming.is_completed` are both `True`. Both `aclose()` and `close()` are idempotent. + +## Important Notes + +- Streaming automatically enables LLM streaming for all agents in the crew +- You must iterate through all chunks before accessing the `.result` property +- For `kickoff_for_each_async()` with streaming, use `.results` (plural) to get all outputs +- Streaming adds minimal overhead and can actually improve perceived performance +- Each chunk includes full context (task, agent, chunk type) for rich UIs + +## Error Handling + +Handle errors during streaming execution: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSuccess: {result.raw}") + +except Exception as e: + print(f"\nError during streaming: {e}") + if streaming.is_completed: + print("Streaming completed but an error occurred") +``` + +By leveraging streaming, you can build more responsive and interactive applications with CrewAI, providing users with real-time visibility into agent execution and results. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/streaming-flow-execution.mdx b/docs/v1.15.1/en/learn/streaming-flow-execution.mdx new file mode 100644 index 000000000..31ca0f376 --- /dev/null +++ b/docs/v1.15.1/en/learn/streaming-flow-execution.mdx @@ -0,0 +1,478 @@ +--- +title: Streaming Flow Execution +description: Stream real-time output from your CrewAI flow execution +icon: wave-pulse +mode: "wide" +--- + +## Introduction + +CrewAI Flows support streaming output, allowing you to receive real-time updates as your flow executes. This feature enables you to build responsive applications that display results incrementally, provide live progress updates, and create better user experiences for long-running workflows. + +## How Flow Streaming Works + +When streaming is enabled on a Flow, CrewAI captures and streams output from any crews or LLM calls within the flow. The stream delivers structured chunks containing the content, task context, and agent information as execution progresses. + +## Enabling Streaming + +To enable streaming, set the `stream` attribute to `True` on your Flow class: + +```python Code +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task + +class ResearchFlow(Flow): + stream = True # Enable streaming for the entire flow + + @start() + def initialize(self): + return {"topic": "AI trends"} + + @listen(initialize) + def research_topic(self, data): + researcher = Agent( + role="Research Analyst", + goal="Research topics thoroughly", + backstory="Expert researcher with analytical skills", + ) + + task = Task( + description="Research {topic} and provide insights", + expected_output="Detailed research findings", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + ) + + return crew.kickoff(inputs=data) +``` + +## Synchronous Streaming + +When you call `kickoff()` on a flow with streaming enabled, it returns a `FlowStreamingOutput` object that you can iterate over: + +```python Code +flow = ResearchFlow() + +# Start streaming execution +streaming = flow.kickoff() + +# Iterate over chunks as they arrive +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access the final result after streaming completes +result = streaming.result +print(f"\n\nFinal output: {result}") +``` + +### Stream Chunk Information + +Each chunk provides context about where it originated in the flow: + +```python Code +streaming = flow.kickoff() + +for chunk in streaming: + print(f"Agent: {chunk.agent_role}") + print(f"Task: {chunk.task_name}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT or TOOL_CALL +``` + +### Accessing Streaming Properties + +The `FlowStreamingOutput` object provides useful properties and methods: + +```python Code +streaming = flow.kickoff() + +# Iterate and collect chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# After iteration completes +print(f"\nCompleted: {streaming.is_completed}") +print(f"Full text: {streaming.get_full_text()}") +print(f"Total chunks: {len(streaming.chunks)}") +print(f"Final result: {streaming.result}") +``` + +## Asynchronous Streaming + +For async applications, use `kickoff_async()` with async iteration: + +```python Code +import asyncio + +async def stream_flow(): + flow = ResearchFlow() + + # Start async streaming + streaming = await flow.kickoff_async() + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result}") + +asyncio.run(stream_flow()) +``` + +## Streaming with Multi-Step Flows + +Streaming works seamlessly across multiple flow steps, including flows that execute multiple crews: + +```python Code +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task + +class MultiStepFlow(Flow): + stream = True + + @start() + def research_phase(self): + """First crew: Research the topic.""" + researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information", + backstory="Expert at finding relevant information", + ) + + task = Task( + description="Research AI developments in healthcare", + expected_output="Research findings on AI in healthcare", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + + self.state["research"] = result.raw + return result.raw + + @listen(research_phase) + def analysis_phase(self, research_data): + """Second crew: Analyze the research.""" + analyst = Agent( + role="Data Analyst", + goal="Analyze information and extract insights", + backstory="Expert at identifying patterns and trends", + ) + + task = Task( + description="Analyze this research: {research}", + expected_output="Key insights and trends", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + return crew.kickoff(inputs={"research": research_data}) + + +# Stream across both phases +flow = MultiStepFlow() +streaming = flow.kickoff() + +current_step = "" +for chunk in streaming: + # Track which flow step is executing + if chunk.task_name != current_step: + current_step = chunk.task_name + print(f"\n\n=== {chunk.task_name} ===\n") + + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\n\nFinal analysis: {result}") +``` + +## Practical Example: Progress Dashboard + +Here's a complete example showing how to build a progress dashboard with streaming: + +```python Code +import asyncio +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +class ResearchPipeline(Flow): + stream = True + + @start() + def gather_data(self): + researcher = Agent( + role="Data Gatherer", + goal="Collect relevant information", + backstory="Skilled at finding quality sources", + ) + + task = Task( + description="Gather data on renewable energy trends", + expected_output="Collection of relevant data points", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + self.state["data"] = result.raw + return result.raw + + @listen(gather_data) + def analyze_data(self, data): + analyst = Agent( + role="Data Analyst", + goal="Extract meaningful insights", + backstory="Expert at data analysis", + ) + + task = Task( + description="Analyze: {data}", + expected_output="Key insights and trends", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + return crew.kickoff(inputs={"data": data}) + + +async def run_with_dashboard(): + flow = ResearchPipeline() + + print("="*60) + print("RESEARCH PIPELINE DASHBOARD") + print("="*60) + + streaming = await flow.kickoff_async() + + current_agent = "" + current_task = "" + chunk_count = 0 + + async for chunk in streaming: + chunk_count += 1 + + # Display phase transitions + if chunk.task_name != current_task: + current_task = chunk.task_name + current_agent = chunk.agent_role + print(f"\n\n📋 Phase: {current_task}") + print(f"👤 Agent: {current_agent}") + print("-" * 60) + + # Display text output + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Display tool usage + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Tool: {chunk.tool_call.tool_name}") + + # Show completion summary + result = streaming.result + print(f"\n\n{'='*60}") + print("PIPELINE COMPLETE") + print(f"{'='*60}") + print(f"Total chunks: {chunk_count}") + print(f"Final output length: {len(str(result))} characters") + +asyncio.run(run_with_dashboard()) +``` + +## Streaming with State Management + +Streaming works naturally with Flow state management: + +```python Code +from pydantic import BaseModel + +class AnalysisState(BaseModel): + topic: str = "" + research: str = "" + insights: str = "" + +class StatefulStreamingFlow(Flow[AnalysisState]): + stream = True + + @start() + def research(self): + # State is available during streaming + topic = self.state.topic + print(f"Researching: {topic}") + + researcher = Agent( + role="Researcher", + goal="Research topics thoroughly", + backstory="Expert researcher", + ) + + task = Task( + description=f"Research {topic}", + expected_output="Research findings", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + + self.state.research = result.raw + return result.raw + + @listen(research) + def analyze(self, research): + # Access updated state + print(f"Analyzing {len(self.state.research)} chars of research") + + analyst = Agent( + role="Analyst", + goal="Extract insights", + backstory="Expert analyst", + ) + + task = Task( + description="Analyze: {research}", + expected_output="Key insights", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + result = crew.kickoff(inputs={"research": research}) + + self.state.insights = result.raw + return result.raw + + +# Run with streaming +flow = StatefulStreamingFlow() +streaming = flow.kickoff(inputs={"topic": "quantum computing"}) + +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\n\nFinal state:") +print(f"Topic: {flow.state.topic}") +print(f"Research length: {len(flow.state.research)}") +print(f"Insights length: {len(flow.state.insights)}") +``` + +## Use Cases + +Flow streaming is particularly valuable for: + +- **Multi-Stage Workflows**: Show progress across research, analysis, and synthesis phases +- **Complex Pipelines**: Provide visibility into long-running data processing flows +- **Interactive Applications**: Build responsive UIs that display intermediate results +- **Monitoring and Debugging**: Observe flow execution and crew interactions in real-time +- **Progress Tracking**: Show users which stage of the workflow is currently executing +- **Live Dashboards**: Create monitoring interfaces for production flows + +## Stream Chunk Types + +Like crew streaming, flow chunks can be of different types: + +### TEXT Chunks + +Standard text content from LLM responses: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### TOOL_CALL Chunks + +Information about tool calls within the flow: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\nTool: {chunk.tool_call.tool_name}") + print(f"Args: {chunk.tool_call.arguments}") +``` + +## Error Handling + +Handle errors gracefully during streaming: + +```python Code +flow = ResearchFlow() +streaming = flow.kickoff() + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSuccess! Result: {result}") + +except Exception as e: + print(f"\nError during flow execution: {e}") + if streaming.is_completed: + print("Streaming completed but flow encountered an error") +``` + +## Cancellation and Resource Cleanup + +`FlowStreamingOutput` supports graceful cancellation so that in-flight work stops promptly when the consumer disconnects. + +### Async Context Manager + +```python Code +streaming = await flow.kickoff_async() + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### Explicit Cancellation + +```python Code +streaming = await flow.kickoff_async() +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # async + # streaming.close() # sync equivalent +``` + +After cancellation, `streaming.is_cancelled` and `streaming.is_completed` are both `True`. Both `aclose()` and `close()` are idempotent. + +## Important Notes + +- Streaming automatically enables LLM streaming for any crews used within the flow +- You must iterate through all chunks before accessing the `.result` property +- Streaming works with both structured and unstructured flow state +- Flow streaming captures output from all crews and LLM calls in the flow +- Each chunk includes context about which agent and task generated it +- Streaming adds minimal overhead to flow execution + +## Combining with Flow Visualization + +You can combine streaming with flow visualization to provide a complete picture: + +```python Code +# Generate flow visualization +flow = ResearchFlow() +flow.plot("research_flow") # Creates HTML visualization + +# Run with streaming +streaming = flow.kickoff() +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\nFlow complete! View structure at: research_flow.html") +``` + +By leveraging flow streaming, you can build sophisticated, responsive applications that provide users with real-time visibility into complex multi-stage workflows, making your AI automations more transparent and engaging. \ No newline at end of file diff --git a/docs/v1.15.1/en/learn/tool-hooks.mdx b/docs/v1.15.1/en/learn/tool-hooks.mdx new file mode 100644 index 000000000..489463e81 --- /dev/null +++ b/docs/v1.15.1/en/learn/tool-hooks.mdx @@ -0,0 +1,603 @@ +--- +title: Tool Call Hooks +description: Learn how to use tool call hooks to intercept, modify, and control tool execution in CrewAI +mode: "wide" +--- + +Tool Call Hooks provide fine-grained control over tool execution during agent operations. These hooks allow you to intercept tool calls, modify inputs, transform outputs, implement safety checks, and add comprehensive logging or monitoring. + +## Overview + +Tool hooks are executed at two critical points: +- **Before Tool Call**: Modify inputs, validate parameters, or block execution +- **After Tool Call**: Transform results, sanitize outputs, or log execution details + +## Hook Types + +### Before Tool Call Hooks + +Executed before every tool execution, these hooks can: +- Inspect and modify tool inputs +- Block tool execution based on conditions +- Implement approval gates for dangerous operations +- Validate parameters +- Log tool invocations + +**Signature:** +```python +def before_hook(context: ToolCallHookContext) -> bool | None: + # Return False to block execution + # Return True or None to allow execution + ... +``` + +### After Tool Call Hooks + +Executed after every tool execution, these hooks can: +- Modify or sanitize tool results +- Add metadata or formatting +- Log execution results +- Implement result validation +- Transform output formats + +**Signature:** +```python +def after_hook(context: ToolCallHookContext) -> str | None: + # Return modified result string + # Return None to keep original result + ... +``` + +## Tool Hook Context + +The `ToolCallHookContext` object provides comprehensive access to tool execution state: + +```python +class ToolCallHookContext: + tool_name: str # Name of the tool being called + tool_input: dict[str, Any] # Mutable tool input parameters + tool: CrewStructuredTool # Tool instance reference + agent: Agent | BaseAgent | None # Agent executing the tool + task: Task | None # Current task + crew: Crew | None # Crew instance + tool_result: str | None # Agent-facing result string (after hooks only) + raw_tool_result: Any | None # Raw Python result (after hooks only) +``` + +For typed tool outputs, `tool_result` is the string the agent sees. By default, this is JSON. If the tool uses custom formatting, it can be Markdown or another string. Use `raw_tool_result` when your hook needs the typed object or dictionary. + +### Modifying Tool Inputs + +**Important:** Always modify tool inputs in-place: + +```python +# ✅ Correct - modify in-place +def sanitize_input(context: ToolCallHookContext) -> None: + context.tool_input['query'] = context.tool_input['query'].lower() + +# ❌ Wrong - replaces dict reference +def wrong_approach(context: ToolCallHookContext) -> None: + context.tool_input = {'query': 'new query'} +``` + +## Registration Methods + +### 1. Global Hook Registration + +Register hooks that apply to all tool calls across all crews: + +```python +from crewai.hooks import register_before_tool_call_hook, register_after_tool_call_hook + +def log_tool_call(context): + print(f"Tool: {context.tool_name}") + print(f"Input: {context.tool_input}") + return None # Allow execution + +register_before_tool_call_hook(log_tool_call) +``` + +### 2. Decorator-Based Registration + +Use decorators for cleaner syntax: + +```python +from crewai.hooks import before_tool_call, after_tool_call + +@before_tool_call +def block_dangerous_tools(context): + dangerous_tools = ['delete_database', 'drop_table', 'rm_rf'] + if context.tool_name in dangerous_tools: + print(f"⛔ Blocked dangerous tool: {context.tool_name}") + return False # Block execution + return None + +@after_tool_call +def sanitize_results(context): + if context.tool_result and "password" in context.tool_result.lower(): + return context.tool_result.replace("password", "[REDACTED]") + return None +``` + +### 3. Crew-Scoped Hooks + +Register hooks for a specific crew instance: + +```python +@CrewBase +class MyProjCrew: + @before_tool_call_crew + def validate_tool_inputs(self, context): + # Only applies to this crew + if context.tool_name == "web_search": + if not context.tool_input.get('query'): + print("❌ Invalid search query") + return False + return None + + @after_tool_call_crew + def log_tool_results(self, context): + # Crew-specific tool logging + print(f"✅ {context.tool_name} completed") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## Common Use Cases + +### 1. Safety Guardrails + +```python +@before_tool_call +def safety_check(context: ToolCallHookContext) -> bool | None: + # Block tools that could cause harm + destructive_tools = [ + 'delete_file', + 'drop_table', + 'remove_user', + 'system_shutdown' + ] + + if context.tool_name in destructive_tools: + print(f"🛑 Blocked destructive tool: {context.tool_name}") + return False + + # Warn on sensitive operations + sensitive_tools = ['send_email', 'post_to_social_media', 'charge_payment'] + if context.tool_name in sensitive_tools: + print(f"⚠️ Executing sensitive tool: {context.tool_name}") + + return None +``` + +### 2. Human Approval Gate + +```python +@before_tool_call +def require_approval_for_actions(context: ToolCallHookContext) -> bool | None: + approval_required = [ + 'send_email', + 'make_purchase', + 'delete_file', + 'post_message' + ] + + if context.tool_name in approval_required: + response = context.request_human_input( + prompt=f"Approve {context.tool_name}?", + default_message=f"Input: {context.tool_input}\nType 'yes' to approve:" + ) + + if response.lower() != 'yes': + print(f"❌ Tool execution denied: {context.tool_name}") + return False + + return None +``` + +### 3. Input Validation and Sanitization + +```python +@before_tool_call +def validate_and_sanitize_inputs(context: ToolCallHookContext) -> bool | None: + # Validate search queries + if context.tool_name == 'web_search': + query = context.tool_input.get('query', '') + if len(query) < 3: + print("❌ Search query too short") + return False + + # Sanitize query + context.tool_input['query'] = query.strip().lower() + + # Validate file paths + if context.tool_name == 'read_file': + path = context.tool_input.get('path', '') + if '..' in path or path.startswith('/'): + print("❌ Invalid file path") + return False + + return None +``` + +### 4. Result Sanitization + +```python +@after_tool_call +def sanitize_sensitive_data(context: ToolCallHookContext) -> str | None: + if not context.tool_result: + return None + + import re + result = context.tool_result + + # Remove API keys + result = re.sub( + r'(api[_-]?key|token)["\']?\s*[:=]\s*["\']?[\w-]+', + r'\1: [REDACTED]', + result, + flags=re.IGNORECASE + ) + + # Remove email addresses + result = re.sub( + r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '[EMAIL-REDACTED]', + result + ) + + # Remove credit card numbers + result = re.sub( + r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', + '[CARD-REDACTED]', + result + ) + + return result +``` + +### 5. Tool Usage Analytics + +```python +import time +from collections import defaultdict + +tool_stats = defaultdict(lambda: {'count': 0, 'total_time': 0, 'failures': 0}) + +@before_tool_call +def start_timer(context: ToolCallHookContext) -> None: + context.tool_input['_start_time'] = time.time() + return None + +@after_tool_call +def track_tool_usage(context: ToolCallHookContext) -> None: + start_time = context.tool_input.get('_start_time', time.time()) + duration = time.time() - start_time + + tool_stats[context.tool_name]['count'] += 1 + tool_stats[context.tool_name]['total_time'] += duration + + if not context.tool_result or 'error' in context.tool_result.lower(): + tool_stats[context.tool_name]['failures'] += 1 + + print(f""" + 📊 Tool Stats for {context.tool_name}: + - Executions: {tool_stats[context.tool_name]['count']} + - Avg Time: {tool_stats[context.tool_name]['total_time'] / tool_stats[context.tool_name]['count']:.2f}s + - Failures: {tool_stats[context.tool_name]['failures']} + """) + + return None +``` + +### 6. Rate Limiting + +```python +from collections import defaultdict +from datetime import datetime, timedelta + +tool_call_history = defaultdict(list) + +@before_tool_call +def rate_limit_tools(context: ToolCallHookContext) -> bool | None: + tool_name = context.tool_name + now = datetime.now() + + # Clean old entries (older than 1 minute) + tool_call_history[tool_name] = [ + call_time for call_time in tool_call_history[tool_name] + if now - call_time < timedelta(minutes=1) + ] + + # Check rate limit (max 10 calls per minute) + if len(tool_call_history[tool_name]) >= 10: + print(f"🚫 Rate limit exceeded for {tool_name}") + return False + + # Record this call + tool_call_history[tool_name].append(now) + return None +``` + +### 7. Caching Tool Results + +```python +import hashlib +import json + +tool_cache = {} + +def cache_key(tool_name: str, tool_input: dict) -> str: + """Generate cache key from tool name and input.""" + input_str = json.dumps(tool_input, sort_keys=True) + return hashlib.md5(f"{tool_name}:{input_str}".encode()).hexdigest() + +@before_tool_call +def check_cache(context: ToolCallHookContext) -> bool | None: + key = cache_key(context.tool_name, context.tool_input) + if key in tool_cache: + print(f"💾 Cache hit for {context.tool_name}") + # Note: Can't return cached result from before hook + # Would need to implement this differently + return None + +@after_tool_call +def cache_result(context: ToolCallHookContext) -> None: + if context.tool_result: + key = cache_key(context.tool_name, context.tool_input) + tool_cache[key] = context.tool_result + print(f"💾 Cached result for {context.tool_name}") + return None +``` + +### 8. Debug Logging + +```python +@before_tool_call +def debug_tool_call(context: ToolCallHookContext) -> None: + print(f""" + 🔍 Tool Call Debug: + - Tool: {context.tool_name} + - Agent: {context.agent.role if context.agent else 'Unknown'} + - Task: {context.task.description[:50] if context.task else 'Unknown'}... + - Input: {context.tool_input} + """) + return None + +@after_tool_call +def debug_tool_result(context: ToolCallHookContext) -> None: + if context.tool_result: + result_preview = context.tool_result[:200] + print(f"✅ Result Preview: {result_preview}...") + else: + print("⚠️ No result returned") + return None +``` + +## Hook Management + +### Unregistering Hooks + +```python +from crewai.hooks import ( + unregister_before_tool_call_hook, + unregister_after_tool_call_hook +) + +# Unregister specific hook +def my_hook(context): + ... + +register_before_tool_call_hook(my_hook) +# Later... +success = unregister_before_tool_call_hook(my_hook) +print(f"Unregistered: {success}") +``` + +### Clearing Hooks + +```python +from crewai.hooks import ( + clear_before_tool_call_hooks, + clear_after_tool_call_hooks, + clear_all_tool_call_hooks +) + +# Clear specific hook type +count = clear_before_tool_call_hooks() +print(f"Cleared {count} before hooks") + +# Clear all tool hooks +before_count, after_count = clear_all_tool_call_hooks() +print(f"Cleared {before_count} before and {after_count} after hooks") +``` + +### Listing Registered Hooks + +```python +from crewai.hooks import ( + get_before_tool_call_hooks, + get_after_tool_call_hooks +) + +# Get current hooks +before_hooks = get_before_tool_call_hooks() +after_hooks = get_after_tool_call_hooks() + +print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after") +``` + +## Advanced Patterns + +### Conditional Hook Execution + +```python +@before_tool_call +def conditional_blocking(context: ToolCallHookContext) -> bool | None: + # Only block for specific agents + if context.agent and context.agent.role == "junior_agent": + if context.tool_name in ['delete_file', 'send_email']: + print(f"❌ Junior agents cannot use {context.tool_name}") + return False + + # Only block during specific tasks + if context.task and "sensitive" in context.task.description.lower(): + if context.tool_name == 'web_search': + print("❌ Web search blocked for sensitive tasks") + return False + + return None +``` + +### Context-Aware Input Modification + +```python +@before_tool_call +def enhance_tool_inputs(context: ToolCallHookContext) -> None: + # Add context based on agent role + if context.agent and context.agent.role == "researcher": + if context.tool_name == 'web_search': + # Add domain restrictions for researchers + context.tool_input['domains'] = ['edu', 'gov', 'org'] + + # Add context based on task + if context.task and "urgent" in context.task.description.lower(): + if context.tool_name == 'send_email': + context.tool_input['priority'] = 'high' + + return None +``` + +### Tool Chain Monitoring + +```python +tool_call_chain = [] + +@before_tool_call +def track_tool_chain(context: ToolCallHookContext) -> None: + tool_call_chain.append({ + 'tool': context.tool_name, + 'timestamp': time.time(), + 'agent': context.agent.role if context.agent else 'Unknown' + }) + + # Detect potential infinite loops + recent_calls = tool_call_chain[-5:] + if len(recent_calls) == 5 and all(c['tool'] == context.tool_name for c in recent_calls): + print(f"⚠️ Warning: {context.tool_name} called 5 times in a row") + + return None +``` + +## Best Practices + +1. **Keep Hooks Focused**: Each hook should have a single responsibility +2. **Avoid Heavy Computation**: Hooks execute on every tool call +3. **Handle Errors Gracefully**: Use try-except to prevent hook failures +4. **Use Type Hints**: Leverage `ToolCallHookContext` for better IDE support +5. **Document Blocking Conditions**: Make it clear when/why tools are blocked +6. **Test Hooks Independently**: Unit test hooks before using in production +7. **Clear Hooks in Tests**: Use `clear_all_tool_call_hooks()` between test runs +8. **Modify In-Place**: Always modify `context.tool_input` in-place, never replace +9. **Log Important Decisions**: Especially when blocking tool execution +10. **Consider Performance**: Cache expensive validations when possible + +## Error Handling + +```python +@before_tool_call +def safe_validation(context: ToolCallHookContext) -> bool | None: + try: + # Your validation logic + if not validate_input(context.tool_input): + return False + except Exception as e: + print(f"⚠️ Hook error: {e}") + # Decide: allow or block on error + return None # Allow execution despite error +``` + +## Type Safety + +```python +from crewai.hooks import ToolCallHookContext, BeforeToolCallHookType, AfterToolCallHookType + +# Explicit type annotations +def my_before_hook(context: ToolCallHookContext) -> bool | None: + return None + +def my_after_hook(context: ToolCallHookContext) -> str | None: + return None + +# Type-safe registration +register_before_tool_call_hook(my_before_hook) +register_after_tool_call_hook(my_after_hook) +``` + +## Integration with Existing Tools + +### Wrapping Existing Validation + +```python +def existing_validator(tool_name: str, inputs: dict) -> bool: + """Your existing validation function.""" + # Your validation logic + return True + +@before_tool_call +def integrate_validator(context: ToolCallHookContext) -> bool | None: + if not existing_validator(context.tool_name, context.tool_input): + print(f"❌ Validation failed for {context.tool_name}") + return False + return None +``` + +### Logging to External Systems + +```python +import logging + +logger = logging.getLogger(__name__) + +@before_tool_call +def log_to_external_system(context: ToolCallHookContext) -> None: + logger.info(f"Tool call: {context.tool_name}", extra={ + 'tool_name': context.tool_name, + 'tool_input': context.tool_input, + 'agent': context.agent.role if context.agent else None + }) + return None +``` + +## Troubleshooting + +### Hook Not Executing +- Verify hook is registered before crew execution +- Check if previous hook returned `False` (blocks execution and subsequent hooks) +- Ensure hook signature matches expected type + +### Input Modifications Not Working +- Use in-place modifications: `context.tool_input['key'] = value` +- Don't replace the dict: `context.tool_input = {}` + +### Result Modifications Not Working +- Return the modified string from after hooks +- Returning `None` keeps the original result +- Ensure the tool actually returned a result + +### Tool Blocked Unexpectedly +- Check all before hooks for blocking conditions +- Verify hook execution order +- Add debug logging to identify which hook is blocking + +## Conclusion + +Tool Call Hooks provide powerful capabilities for controlling and monitoring tool execution in CrewAI. Use them to implement safety guardrails, approval gates, input validation, result sanitization, logging, and analytics. Combined with proper error handling and type safety, hooks enable secure and production-ready agent systems with comprehensive observability. diff --git a/docs/v1.15.1/en/learn/using-annotations.mdx b/docs/v1.15.1/en/learn/using-annotations.mdx new file mode 100644 index 000000000..a9a7fec1a --- /dev/null +++ b/docs/v1.15.1/en/learn/using-annotations.mdx @@ -0,0 +1,155 @@ +--- +title: "Using Annotations in crew.py" +description: "Learn how to use classic Python annotations to structure agents, tasks, and components in CrewAI" +icon: "at" +mode: "wide" +--- + +This guide explains how to use annotations to properly reference **agents**, **tasks**, and other components in a classic `crew.py` file. + + +New crew projects created with `crewai create crew ` are JSON-first and use `crew.jsonc` plus `agents/*.jsonc`. Use this annotations guide when you are working in a classic project created with `crewai create crew --classic`, migrating an existing Python/YAML project, or need decorator-based Python control. + + +## Introduction + +Annotations in the CrewAI framework are used to decorate classes and methods, providing metadata and functionality to various components of your crew. In classic Python/YAML projects, these annotations help organize the code that loads `config/agents.yaml`, `config/tasks.yaml`, and returns the `Crew` object. + +## Available Annotations + +The CrewAI framework provides the following annotations: + +- `@CrewBase`: Used to decorate the main crew class. +- `@agent`: Decorates methods that define and return Agent objects. +- `@task`: Decorates methods that define and return Task objects. +- `@crew`: Decorates the method that creates and returns the Crew object. +- `@llm`: Decorates methods that initialize and return Language Model objects. +- `@tool`: Decorates methods that initialize and return Tool objects. +- `@callback`: Used for defining callback methods. +- `@output_json`: Used for methods that output JSON data. +- `@output_pydantic`: Used for methods that output Pydantic models. +- `@cache_handler`: Used for defining cache handling methods. + +## Usage Examples + +Let's go through examples of how to use these annotations: + +### 1. Crew Base Class + +```python +@CrewBase +class LinkedinProfileCrew(): + """LinkedinProfile crew""" + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' +``` + +The `@CrewBase` annotation is used to decorate the main crew class. This class typically contains configurations and methods for creating agents, tasks, and the crew itself. + + +`@CrewBase` does more than register the class: + +- **Configuration bootstrapping:** looks for `agents_config` and `tasks_config` (defaulting to `config/agents.yaml` and `config/tasks.yaml`) beside the class file, loads them at instantiation, and safely falls back to empty dicts if files are missing. +- **Decorator orchestration:** keeps memoized references to every method marked with `@agent`, `@task`, `@before_kickoff`, or `@after_kickoff` so they are instantiated once per crew and executed in declaration order. +- **Hook wiring:** automatically attaches the preserved kickoff hooks to the `Crew` object returned by the `@crew` method, making them run before and after `.kickoff()`. +- **MCP integration:** when the class defines `mcp_server_params`, `get_mcp_tools()` lazily starts an MCP server adapter, hydrates the declared tools, and an internal after-kickoff hook stops the adapter. See [MCP overview](/en/mcp/overview) for adapter configuration details. + + +### 2. Tool Definition + +```python +@tool +def myLinkedInProfileTool(self): + return LinkedInProfileTool() +``` + +The `@tool` annotation is used to decorate methods that return tool objects. These tools can be used by agents to perform specific tasks. + +### 3. LLM Definition + +```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") +``` + +The `@llm` annotation is used to decorate methods that initialize and return Language Model objects. These LLMs are used by agents for natural language processing tasks. + +### 4. Agent Definition + +```python +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'] + ) +``` + +The `@agent` annotation is used to decorate methods that define and return Agent objects. + +### 5. Task Definition + +```python +@task +def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_linkedin_task'], + agent=self.researcher() + ) +``` + +The `@task` annotation is used to decorate methods that define and return Task objects. These methods specify the task configuration and the agent responsible for the task. + +### 6. Crew Creation + +```python +@crew +def crew(self) -> Crew: + """Creates the LinkedinProfile crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +The `@crew` annotation is used to decorate the method that creates and returns the `Crew` object. This method assembles all the components (agents and tasks) into a functional crew. + +## Classic YAML Configuration + +In classic projects, agent configurations are typically stored in a YAML file. Here's an example of how the `agents.yaml` file might look for the researcher agent: + +```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 +``` + +This YAML configuration corresponds to the researcher agent defined in the `LinkedinProfileCrew` class. The configuration specifies the agent's role, goal, backstory, and other properties such as the LLM and tools it uses. + +Note how the `llm` and `tools` in the YAML file correspond to the methods decorated with `@llm` and `@tool` in the Python class. + +## Best Practices + +- **Consistent Naming**: Use clear and consistent naming conventions for your methods. For example, agent methods could be named after their roles (e.g., researcher, reporting_analyst). +- **Environment Variables**: Use environment variables for sensitive information like API keys. +- **Flexibility**: Design your crew to be flexible by allowing easy addition or removal of agents and tasks. +- **YAML-Code Correspondence**: In classic projects, ensure that the names and structures in your YAML files correspond correctly to the decorated methods in your Python code. + +By following these guidelines and properly using annotations, you can maintain classic Python/YAML crews cleanly. For new crews, prefer the JSON-first structure covered in [Crews](/en/concepts/crews). diff --git a/docs/v1.15.1/en/mcp/dsl-integration.mdx b/docs/v1.15.1/en/mcp/dsl-integration.mdx new file mode 100644 index 000000000..b2eb97c14 --- /dev/null +++ b/docs/v1.15.1/en/mcp/dsl-integration.mdx @@ -0,0 +1,349 @@ +--- +title: MCP DSL Integration +description: Learn how to use CrewAI's simple DSL syntax to integrate MCP servers directly with your agents using the mcps field. +icon: code +mode: "wide" +--- + +## Overview + +CrewAI's MCP DSL (Domain Specific Language) integration provides the **simplest way** to connect your agents to MCP (Model Context Protocol) servers. Just add an `mcps` field to your agent and CrewAI handles all the complexity automatically. + + + This is the **recommended approach** for most MCP use cases. For advanced + scenarios requiring manual connection management, see + [MCPServerAdapter](/en/mcp/overview#advanced-mcpserveradapter). + + +## Basic Usage + +Add MCP servers to your agent using the `mcps` field: + +```python +from crewai import Agent + +agent = Agent( + role="Research Assistant", + goal="Help with research and analysis tasks", + backstory="Expert assistant with access to advanced research tools", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=research" + ] +) + +# MCP tools are now automatically available! +# No need for manual connection management or tool configuration +``` + +## Supported Reference Formats + +### External MCP Remote Servers + +```python +# Basic HTTPS server +"https://api.example.com/mcp" + +# Server with authentication +"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" + +# Server with custom path +"https://services.company.com/api/v1/mcp" +``` + +### Specific Tool Selection + +Use the `#` syntax to select specific tools from a server: + +```python +# Get only the forecast tool from weather server +"https://weather.api.com/mcp#get_forecast" + +# Get only the search tool from Exa +"https://mcp.exa.ai/mcp?api_key=your_key#web_search_exa" +``` + +### Connected MCP Integrations + +Connect MCP servers from the CrewAI catalog or bring your own. Once connected in your account, reference them by slug: + +```python +# Connected MCP with all tools +"snowflake" + +# Specific tool from a connected MCP +"stripe#list_invoices" + +# Multiple connected MCPs +mcps=[ + "snowflake", + "stripe", + "github" +] +``` + +## Complete Example + +Here's a complete example using multiple MCP servers: + +```python +from crewai import Agent, Task, Crew, Process + +# Create agent with multiple MCP sources +multi_source_agent = Agent( + role="Multi-Source Research Analyst", + goal="Conduct comprehensive research using multiple data sources", + backstory="""Expert researcher with access to web search, weather data, + financial information, and academic research tools""", + mcps=[ + # External MCP servers + "https://mcp.exa.ai/mcp?api_key=your_exa_key&profile=research", + "https://weather.api.com/mcp#get_current_conditions", + + # Connected MCPs from catalog + "snowflake", + "stripe#list_invoices", + "github#search_repositories" + ] +) + +# Create comprehensive research task +research_task = Task( + description="""Research the impact of AI agents on business productivity. + Include current weather impacts on remote work, financial market trends, + and recent academic publications on AI agent frameworks.""", + expected_output="""Comprehensive report covering: + 1. AI agent business impact analysis + 2. Weather considerations for remote work + 3. Financial market trends related to AI + 4. Academic research citations and insights + 5. Competitive landscape analysis""", + agent=multi_source_agent +) + +# Create and execute crew +research_crew = Crew( + agents=[multi_source_agent], + tasks=[research_task], + process=Process.sequential, + verbose=True +) + +result = research_crew.kickoff() +print(f"Research completed with {len(multi_source_agent.mcps)} MCP data sources") +``` + +## Tool Naming and Organization + +CrewAI automatically handles tool naming to prevent conflicts: + +```python +# Original MCP server has tools: "search", "analyze" +# CrewAI creates tools: "mcp_exa_ai_search", "mcp_exa_ai_analyze" + +agent = Agent( + role="Tool Organization Demo", + goal="Show how tool naming works", + backstory="Demonstrates automatic tool organization", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=key", # Tools: mcp_exa_ai_* + "https://weather.service.com/mcp", # Tools: weather_service_com_* + "snowflake" # Tools: snowflake_* + ] +) + +# Each server's tools get unique prefixes based on the server name +# This prevents naming conflicts between different MCP servers +``` + +## Error Handling and Resilience + +The MCP DSL is designed to be robust and user-friendly: + +### Graceful Server Failures + +```python +agent = Agent( + role="Resilient Researcher", + goal="Research despite server issues", + backstory="Experienced researcher who adapts to available tools", + mcps=[ + "https://primary-server.com/mcp", # Primary data source + "https://backup-server.com/mcp", # Backup if primary fails + "https://unreachable-server.com/mcp", # Will be skipped with warning + "snowflake" # Connected MCP from catalog + ] +) + +# Agent will: +# 1. Successfully connect to working servers +# 2. Log warnings for failing servers +# 3. Continue with available tools +# 4. Not crash or hang on server failures +``` + +### Timeout Protection + +All MCP operations have built-in timeouts: + +- **Connection timeout**: 10 seconds +- **Tool execution timeout**: 30 seconds +- **Discovery timeout**: 15 seconds + +```python +# These servers will timeout gracefully if unresponsive +mcps=[ + "https://slow-server.com/mcp", # Will timeout after 10s if unresponsive + "https://overloaded-api.com/mcp" # Will timeout if discovery takes > 15s +] +``` + +## Performance Features + +### Automatic Caching + +Tool schemas are cached for 5 minutes to improve performance: + +```python +# First agent creation - discovers tools from server +agent1 = Agent(role="First", goal="Test", backstory="Test", + mcps=["https://api.example.com/mcp"]) + +# Second agent creation (within 5 minutes) - uses cached tool schemas +agent2 = Agent(role="Second", goal="Test", backstory="Test", + mcps=["https://api.example.com/mcp"]) # Much faster! +``` + +### On-Demand Connections + +Tool connections are established only when tools are actually used: + +```python +# Agent creation is fast - no MCP connections made yet +agent = Agent( + role="On-Demand Agent", + goal="Use tools efficiently", + backstory="Efficient agent that connects only when needed", + mcps=["https://api.example.com/mcp"] +) + +# MCP connection is made only when a tool is actually executed +# This minimizes connection overhead and improves startup performance +``` + +## Integration with Existing Features + +MCP tools work seamlessly with other CrewAI features: + +```python +from crewai.tools import BaseTool + +class CustomTool(BaseTool): + name: str = "custom_analysis" + description: str = "Custom analysis tool" + + def _run(self, **kwargs): + return "Custom analysis result" + +agent = Agent( + role="Full-Featured Agent", + goal="Use all available tool types", + backstory="Agent with comprehensive tool access", + + # All tool types work together + tools=[CustomTool()], # Custom tools + apps=["gmail", "slack"], # Platform integrations + mcps=[ # MCP servers + "https://mcp.exa.ai/mcp?api_key=key", + "snowflake" + ], + + verbose=True, + max_iter=15 +) +``` + +## Best Practices + +### 1. Use Specific Tools When Possible + +```python +# Good - only get the tools you need +mcps=["https://weather.api.com/mcp#get_forecast"] + +# Less efficient - gets all tools from server +mcps=["https://weather.api.com/mcp"] +``` + +### 2. Handle Authentication Securely + +```python +import os + +# Store API keys in environment variables +exa_key = os.getenv("EXA_API_KEY") +exa_profile = os.getenv("EXA_PROFILE") + +agent = Agent( + role="Secure Agent", + goal="Use MCP tools securely", + backstory="Security-conscious agent", + mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"] +) +``` + +### 3. Plan for Server Failures + +```python +# Always include backup options +mcps=[ + "https://primary-api.com/mcp", # Primary choice + "https://backup-api.com/mcp", # Backup option + "snowflake" # Connected MCP fallback +] +``` + +### 4. Use Descriptive Agent Roles + +```python +agent = Agent( + role="Weather-Enhanced Market Analyst", + goal="Analyze markets considering weather impacts", + backstory="Financial analyst with access to weather data for agricultural market insights", + mcps=[ + "https://weather.service.com/mcp#get_forecast", + "stripe#list_invoices" + ] +) +``` + +## Troubleshooting + +### Common Issues + +**No tools discovered:** + +```python +# Check your MCP server URL and authentication +# Verify the server is running and accessible +mcps=["https://mcp.example.com/mcp?api_key=valid_key"] +``` + +**Connection timeouts:** + +```python +# Server may be slow or overloaded +# CrewAI will log warnings and continue with other servers +# Check server status or try backup servers +``` + +**Authentication failures:** + +```python +# Verify API keys and credentials +# Check server documentation for required parameters +# Ensure query parameters are properly URL encoded +``` + +## Advanced: MCPServerAdapter + +For complex scenarios requiring manual connection management, use the `MCPServerAdapter` class from `crewai-tools`. Using a Python context manager (`with` statement) is the recommended approach as it automatically handles starting and stopping the connection to the MCP server. diff --git a/docs/v1.15.1/en/mcp/multiple-servers.mdx b/docs/v1.15.1/en/mcp/multiple-servers.mdx new file mode 100644 index 000000000..6ecd8cac7 --- /dev/null +++ b/docs/v1.15.1/en/mcp/multiple-servers.mdx @@ -0,0 +1,65 @@ +--- +title: Connecting to Multiple MCP Servers +description: Learn how to use MCPServerAdapter in CrewAI to connect to multiple MCP servers simultaneously and aggregate their tools. +icon: layer-group +mode: "wide" +--- + +## Overview + +`MCPServerAdapter` in `crewai-tools` allows you to connect to multiple MCP servers concurrently. This is useful when your agents need to access tools distributed across different services or environments. The adapter aggregates tools from all specified servers, making them available to your CrewAI agents. + +## Configuration + +To connect to multiple servers, you provide a list of server parameter dictionaries to `MCPServerAdapter`. Each dictionary in the list should define the parameters for one MCP server. + +Supported transport types for each server in the list include `stdio`, `sse`, and `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.") + +``` + +## Connection Management + +When using the context manager (`with` statement), `MCPServerAdapter` handles the lifecycle (start and stop) of all connections to the configured MCP servers. This simplifies resource management and ensures that all connections are properly closed when the context is exited. diff --git a/docs/v1.15.1/en/mcp/overview.mdx b/docs/v1.15.1/en/mcp/overview.mdx new file mode 100644 index 000000000..5b0bfc3f2 --- /dev/null +++ b/docs/v1.15.1/en/mcp/overview.mdx @@ -0,0 +1,724 @@ +--- +title: "MCP Servers as Tools in CrewAI" +description: "Learn how to integrate MCP servers as tools in your CrewAI agents using the `crewai-tools` library." +icon: plug +mode: "wide" +--- + +## Overview + +The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) provides a standardized way for AI agents to provide context to LLMs by communicating with external services, known as MCP Servers. + +CrewAI offers **two approaches** for MCP integration: + +### 🚀 **Simple DSL Integration** (Recommended) + +Use the `mcps` field directly on agents for seamless MCP tool integration. The DSL supports both **string references** (for quick setup) and **structured configurations** (for full control). + +#### String-Based References (Quick Setup) + +Perfect for remote HTTPS servers and connected MCP integrations from the CrewAI catalog: + +```python +from crewai import Agent + +agent = Agent( + role="Research Analyst", + goal="Research and analyze information", + backstory="Expert researcher with access to external tools", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key", # External MCP server + "https://api.weather.com/mcp#get_forecast", # Specific tool from server + "snowflake", # Connected MCP from catalog + "stripe#list_invoices" # Specific tool from connected MCP + ] +) +# MCP tools are now automatically available to your agent! +``` + +#### Structured Configurations (Full Control) + +For complete control over connection settings, tool filtering, and all transport types: + +```python +from crewai import Agent +from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE +from crewai.mcp.filters import create_static_tool_filter + +agent = Agent( + role="Advanced Research Analyst", + goal="Research with full control over MCP connections", + backstory="Expert researcher with advanced tool access", + mcps=[ + # Stdio transport for local servers + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + env={"API_KEY": "your_key"}, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "list_directory"] + ), + cache_tools_list=True, + ), + # HTTP/Streamable HTTP transport for remote servers + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=True, + cache_tools_list=True, + ), + # SSE transport for real-time streaming + MCPServerSSE( + url="https://stream.example.com/mcp/sse", + headers={"Authorization": "Bearer your_token"}, + ), + ] +) +``` + +### 🔧 **Advanced: MCPServerAdapter** (For Complex Scenarios) + +For advanced use cases requiring manual connection management, the `crewai-tools` library provides the `MCPServerAdapter` class. + +We currently support the following transport mechanisms: + +- **Stdio**: for local servers (communication via standard input/output between processes on the same machine) +- **Server-Sent Events (SSE)**: for remote servers (unidirectional, real-time data streaming from server to client over HTTP) +- **Streamable HTTPS**: for remote servers (flexible, potentially bi-directional communication over HTTPS, often utilizing SSE for server-to-client streams) + +## Video Tutorial + +Watch this video tutorial for a comprehensive guide on MCP integration with CrewAI: + + + +## Installation + +CrewAI MCP integration requires the `mcp` library: + +```shell +# For Simple DSL Integration (Recommended) +uv add mcp + +# For Advanced MCPServerAdapter usage +uv pip install 'crewai-tools[mcp]' +``` + +## Quick Start: Simple DSL Integration + +The easiest way to integrate MCP servers is using the `mcps` field on your agents. You can use either string references or structured configurations. + +### Quick Start with String References + +```python +from crewai import Agent, Task, Crew + +# Create agent with MCP tools using string references +research_agent = Agent( + role="Research Analyst", + goal="Find and analyze information using advanced search tools", + backstory="Expert researcher with access to multiple data sources", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile", + "snowflake#run_query" + ] +) + +# Create task +research_task = Task( + description="Research the latest developments in AI agent frameworks", + expected_output="Comprehensive research report with citations", + agent=research_agent +) + +# Create and run crew +crew = Crew(agents=[research_agent], tasks=[research_task]) +result = crew.kickoff() +``` + +### Quick Start with Structured Configurations + +```python +from crewai import Agent, Task, Crew +from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE + +# Create agent with structured MCP configurations +research_agent = Agent( + role="Research Analyst", + goal="Find and analyze information using advanced search tools", + backstory="Expert researcher with access to multiple data sources", + mcps=[ + # Local stdio server + MCPServerStdio( + command="python", + args=["local_server.py"], + env={"API_KEY": "your_key"}, + ), + # Remote HTTP server + MCPServerHTTP( + url="https://api.research.com/mcp", + headers={"Authorization": "Bearer your_token"}, + ), + ] +) + +# Create task +research_task = Task( + description="Research the latest developments in AI agent frameworks", + expected_output="Comprehensive research report with citations", + agent=research_agent +) + +# Create and run crew +crew = Crew(agents=[research_agent], tasks=[research_task]) +result = crew.kickoff() +``` + +That's it! The MCP tools are automatically discovered and available to your agent. + +## MCP Reference Formats + +The `mcps` field supports both **string references** (for quick setup) and **structured configurations** (for full control). You can mix both formats in the same list. + +### String-Based References + +#### External MCP Servers + +```python +mcps=[ + # Full server - get all available tools + "https://mcp.example.com/api", + + # Specific tool from server using # syntax + "https://api.weather.com/mcp#get_current_weather", + + # Server with authentication parameters + "https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" +] +``` + +#### Connected MCP Integrations + +Connect MCP servers from the CrewAI catalog or bring your own. Once connected in your account, reference them by slug: + +```python +mcps=[ + # Connected MCP - get all available tools + "snowflake", + + # Specific tool from a connected MCP using # syntax + "stripe#list_invoices", + + # Multiple connected MCPs + "snowflake", + "stripe", + "github" +] +``` + +### Structured Configurations + +#### Stdio Transport (Local Servers) + +Perfect for local MCP servers that run as processes: + +```python +from crewai.mcp import MCPServerStdio +from crewai.mcp.filters import create_static_tool_filter + +mcps=[ + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + env={"API_KEY": "your_key"}, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"] + ), + cache_tools_list=True, + ), + # Python-based server + MCPServerStdio( + command="python", + args=["path/to/server.py"], + env={"UV_PYTHON": "3.12", "API_KEY": "your_key"}, + ), +] +``` + +#### HTTP/Streamable HTTP Transport (Remote Servers) + +For remote MCP servers over HTTP/HTTPS: + +```python +from crewai.mcp import MCPServerHTTP + +mcps=[ + # Streamable HTTP (default) + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=True, + cache_tools_list=True, + ), + # Standard HTTP + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=False, + ), +] +``` + +#### SSE Transport (Real-Time Streaming) + +For remote servers using Server-Sent Events: + +```python +from crewai.mcp import MCPServerSSE + +mcps=[ + MCPServerSSE( + url="https://stream.example.com/mcp/sse", + headers={"Authorization": "Bearer your_token"}, + cache_tools_list=True, + ), +] +``` + +### Mixed References + +You can combine string references and structured configurations: + +```python +from crewai.mcp import MCPServerStdio, MCPServerHTTP + +mcps=[ + # String references + "https://external-api.com/mcp", # External server + "snowflake", # Connected MCP from catalog + + # Structured configurations + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + ), + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer token"}, + ), +] +``` + +### Tool Filtering + +Structured configurations support advanced tool filtering: + +```python +from crewai.mcp import MCPServerStdio +from crewai.mcp.filters import create_static_tool_filter, create_dynamic_tool_filter, ToolFilterContext + +# Static filtering (allow/block lists) +static_filter = create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"], + blocked_tool_names=["delete_file"], +) + +# Dynamic filtering (context-aware) +def dynamic_filter(context: ToolFilterContext, tool: dict) -> bool: + # Block dangerous tools for certain agent roles + if context.agent.role == "Code Reviewer": + if "delete" in tool.get("name", "").lower(): + return False + return True + +mcps=[ + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + tool_filter=static_filter, # or dynamic_filter + ), +] +``` + +## Configuration Parameters + +Each transport type supports specific configuration options: + +### MCPServerStdio Parameters + +- **`command`** (required): Command to execute (e.g., `"python"`, `"node"`, `"npx"`, `"uvx"`) +- **`args`** (optional): List of command arguments (e.g., `["server.py"]` or `["-y", "@mcp/server"]`) +- **`env`** (optional): Dictionary of environment variables to pass to the process +- **`tool_filter`** (optional): Tool filter function for filtering available tools +- **`cache_tools_list`** (optional): Whether to cache the tool list for faster subsequent access (default: `False`) + +### MCPServerHTTP Parameters + +- **`url`** (required): Server URL (e.g., `"https://api.example.com/mcp"`) +- **`headers`** (optional): Dictionary of HTTP headers for authentication or other purposes +- **`streamable`** (optional): Whether to use streamable HTTP transport (default: `True`) +- **`tool_filter`** (optional): Tool filter function for filtering available tools +- **`cache_tools_list`** (optional): Whether to cache the tool list for faster subsequent access (default: `False`) + +### MCPServerSSE Parameters + +- **`url`** (required): Server URL (e.g., `"https://api.example.com/mcp/sse"`) +- **`headers`** (optional): Dictionary of HTTP headers for authentication or other purposes +- **`tool_filter`** (optional): Tool filter function for filtering available tools +- **`cache_tools_list`** (optional): Whether to cache the tool list for faster subsequent access (default: `False`) + +### Common Parameters + +All transport types support: + +- **`tool_filter`**: Filter function to control which tools are available. Can be: + - `None` (default): All tools are available + - Static filter: Created with `create_static_tool_filter()` for allow/block lists + - Dynamic filter: Created with `create_dynamic_tool_filter()` for context-aware filtering +- **`cache_tools_list`**: When `True`, caches the tool list after first discovery to improve performance on subsequent connections + +## Key Features + +- 🔄 **Automatic Tool Discovery**: Tools are automatically discovered and integrated +- 🏷️ **Name Collision Prevention**: Server names are prefixed to tool names +- ⚡ **Performance Optimized**: On-demand connections with schema caching +- 🛡️ **Error Resilience**: Graceful handling of unavailable servers +- ⏱️ **Timeout Protection**: Built-in timeouts prevent hanging connections +- 📊 **Transparent Integration**: Works seamlessly with existing CrewAI features +- 🔧 **Full Transport Support**: Stdio, HTTP/Streamable HTTP, and SSE transports +- 🎯 **Advanced Filtering**: Static and dynamic tool filtering capabilities +- 🔐 **Flexible Authentication**: Support for headers, environment variables, and query parameters + +## Error Handling + +The MCP DSL integration is designed to be resilient and handles failures gracefully: + +```python +from crewai import Agent +from crewai.mcp import MCPServerStdio, MCPServerHTTP + +agent = Agent( + role="Resilient Agent", + goal="Continue working despite server issues", + backstory="Agent that handles failures gracefully", + mcps=[ + # String references + "https://reliable-server.com/mcp", # Will work + "https://unreachable-server.com/mcp", # Will be skipped gracefully + "snowflake", # Connected MCP from catalog + + # Structured configs + MCPServerStdio( + command="python", + args=["reliable_server.py"], # Will work + ), + MCPServerHTTP( + url="https://slow-server.com/mcp", # Will timeout gracefully + ), + ] +) +# Agent will use tools from working servers and log warnings for failing ones +``` + +All connection errors are handled gracefully: + +- **Connection failures**: Logged as warnings, agent continues with available tools +- **Timeout errors**: Connections timeout after 30 seconds (configurable) +- **Authentication errors**: Logged clearly for debugging +- **Invalid configurations**: Validation errors are raised at agent creation time + +## Advanced: MCPServerAdapter + +For complex scenarios requiring manual connection management, use the `MCPServerAdapter` class from `crewai-tools`. Using a Python context manager (`with` statement) is the recommended approach as it automatically handles starting and stopping the connection to the MCP server. + +## Connection Configuration + +The `MCPServerAdapter` supports several configuration options to customize the connection behavior: + +- **`connect_timeout`** (optional): Maximum time in seconds to wait for establishing a connection to the MCP server. Defaults to 30 seconds if not specified. This is particularly useful for remote servers that may have variable response times. + +```python +# Example with custom connection timeout +with MCPServerAdapter(server_params, connect_timeout=60) as tools: + # Connection will timeout after 60 seconds if not established + pass +``` + +```python +from crewai import Agent +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # For Stdio Server + +# Example server_params (choose one based on your server type): +# 1. Stdio Server: +server_params=StdioServerParameters( + command="python3", + args=["servers/your_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +# 2. SSE Server: +server_params = { + "url": "http://localhost:8000/sse", + "transport": "sse" +} + +# 3. Streamable HTTP Server: +server_params = { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" +} + +# Example usage (uncomment and adapt once server_params is set): +with MCPServerAdapter(server_params, connect_timeout=60) 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, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +This general pattern shows how to integrate tools. For specific examples tailored to each transport, refer to the detailed guides below. + +## Filtering Tools + +There are two ways to filter tools: + +1. Accessing a specific tool using dictionary-style indexing. +2. Pass a list of tool names to the `MCPServerAdapter` constructor. + +### Accessing a specific tool using dictionary-style indexing. + +```python +with MCPServerAdapter(server_params, connect_timeout=60) 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"]], # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +### Pass a list of tool names to the `MCPServerAdapter` constructor. + +```python +with MCPServerAdapter(server_params, "tool_name", connect_timeout=60) 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, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +## Using with CrewBase + +To use MCPServer tools within a CrewBase class, use the `get_mcp_tools` method. Server configurations should be provided via the `mcp_server_params` attribute. You can pass either a single configuration or a list of multiple server configurations. + +```python +@CrewBase +class CrewWithMCP: + # ... define your agents and tasks config file ... + + mcp_server_params = [ + # 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}, + ) + ] + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # get all available tools + + # ... rest of your crew setup ... +``` + + +When a crew class is decorated with `@CrewBase`, the adapter lifecycle is managed for you: + +- The first call to `get_mcp_tools()` lazily creates a shared `MCPServerAdapter` that is reused by every agent in the crew. +- The adapter automatically shuts down after `.kickoff()` completes thanks to an implicit after-kickoff hook injected by `@CrewBase`, so no manual cleanup is required. +- If `mcp_server_params` is not defined, `get_mcp_tools()` simply returns an empty list, allowing the same code paths to run with or without MCP configured. + +This makes it safe to call `get_mcp_tools()` from multiple agent methods or selectively enable MCP per environment. + + + +### Connection Timeout Configuration + +You can configure the connection timeout for MCP servers by setting the `mcp_connect_timeout` class attribute. If no timeout is specified, it defaults to 30 seconds. + +```python +@CrewBase +class CrewWithMCP: + mcp_server_params = [...] + mcp_connect_timeout = 60 # 60 seconds timeout for all MCP connections + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +```python +@CrewBase +class CrewWithDefaultTimeout: + mcp_server_params = [...] + # No mcp_connect_timeout specified - uses default 30 seconds + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +### Filtering Tools + +You can filter which tools are available to your agent by passing a list of tool names to the `get_mcp_tools` method. + +```python +@agent +def another_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # get specific tools + ) +``` + +The timeout configuration applies to all MCP tool calls within the crew: + +```python +@CrewBase +class CrewWithCustomTimeout: + mcp_server_params = [...] + mcp_connect_timeout = 90 # 90 seconds timeout for all MCP connections + + @agent + def filtered_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # specific tools with custom timeout + ) +``` + +## Explore MCP Integrations + + + + **Recommended**: Use the simple `mcps=[]` field syntax for effortless MCP + integration. + + + Connect to local MCP servers via standard input/output. Ideal for scripts + and local executables. + + + Integrate with remote MCP servers using Server-Sent Events for real-time + data streaming. + + + Utilize flexible Streamable HTTP for robust communication with remote MCP + servers. + + + Aggregate tools from several MCP servers simultaneously using a single + adapter. + + + Review important security best practices for MCP integration to keep your + agents safe. + + + +Checkout this repository for full demos and examples of MCP integration with CrewAI! 👇 + + + CrewAI MCP Demo + + +## Staying Safe with MCP + +Always ensure that you trust an MCP Server before using it. + +#### Security Warning: DNS Rebinding Attacks + +SSE transports can be vulnerable to DNS rebinding attacks if not properly secured. +To prevent this: + +1. **Always validate Origin headers** on incoming SSE connections to ensure they come from expected sources +2. **Avoid binding servers to all network interfaces** (0.0.0.0) when running locally - bind only to localhost (127.0.0.1) instead +3. **Implement proper authentication** for all SSE connections + +Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites. + +For more details, see the [Anthropic's MCP Transport Security docs](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). + +### Limitations + +- **Supported Primitives**: Currently, `MCPServerAdapter` primarily supports adapting MCP `tools`. + Other MCP primitives like `prompts` or `resources` are not directly integrated as CrewAI components through this adapter at this time. +- **Output Handling**: The adapter typically processes the primary text output from an MCP tool (e.g., `.content[0].text`). Complex or multi-modal outputs might require custom handling if not fitting this pattern. diff --git a/docs/v1.15.1/en/mcp/security.mdx b/docs/v1.15.1/en/mcp/security.mdx new file mode 100644 index 000000000..4fc84cdeb --- /dev/null +++ b/docs/v1.15.1/en/mcp/security.mdx @@ -0,0 +1,167 @@ +--- +title: MCP Security Considerations +description: Learn about important security best practices when integrating MCP servers with your CrewAI agents. +icon: lock +mode: "wide" +--- + +## Overview + + +The most critical aspect of MCP security is **trust**. You should **only** connect your CrewAI agents to MCP servers that you fully trust. + + +When integrating external services like MCP (Model Context Protocol) servers into your CrewAI agents, security is paramount. +MCP servers can execute code, access data, or interact with other systems based on the tools they expose. +It's crucial to understand the implications and follow best practices to protect your applications and data. + +### Risks + +- Execute arbitrary code on the machine where the agent is running (especially with `Stdio` transport if the server can control the command executed). +- Expose sensitive data from your agent or its environment. +- Manipulate your agent's behavior in unintended ways, including making unauthorized API calls on your behalf. +- Hijack your agent's reasoning process through sophisticated prompt injection techniques (see below). + +### 1. Trusting MCP Servers + + +**Only connect to MCP servers that you trust.** + + +Before configuring `MCPServerAdapter` to connect to an MCP server, ensure you know: +- **Who operates the server?** Is it a known, reputable service, or an internal server under your control? +- **What tools does it expose?** Understand the capabilities of the tools. Could they be misused if an attacker gained control or if the server itself is malicious? +- **What data does it access or process?** Be aware of any sensitive information that might be sent to or handled by the MCP server. + +Avoid connecting to unknown or unverified MCP servers, especially if your agents handle sensitive tasks or data. + +### 2. Secure Prompt Injection via Tool Metadata: The "Model Control Protocol" Risk + +A significant and subtle risk is the potential for prompt injection through tool metadata. Here's how it works: + +1. When your CrewAI agent connects to an MCP server, it typically requests a list of available tools. +2. The MCP server responds with metadata for each tool, including its name, description, and parameter descriptions. +3. Your agent's underlying Language Model (LLM) uses this metadata to understand how and when to use the tools. This metadata is often incorporated into the LLM's system prompt or context. +4. A malicious MCP server can craft its tool metadata (names, descriptions) to include hidden or overt instructions. These instructions can act as a prompt injection, effectively telling your LLM to behave in a certain way, reveal sensitive information, or perform malicious actions. + +**Crucially, this attack can occur simply by connecting to a malicious server and listing its tools, even if your agent never explicitly decides to *use* any of those tools.** The mere exposure to the malicious metadata can be enough to compromise the agent's behavior. + +**Mitigation:** + +* **Extreme Caution with Untrusted Servers:** Reiterate: *Do not connect to MCP servers you do not fully trust.* The risk of metadata injection makes this paramount. + +### Stdio Transport Security + +Stdio (Standard Input/Output) transport is typically used for local MCP servers running on the same machine as your CrewAI application. + +- **Process Isolation**: While generally safer as it doesn't involve network exposure by default, ensure the script or command run by `StdioServerParameters` is from a trusted source and has appropriate file system permissions. A malicious Stdio server script could still harm your local system. +- **Input Sanitization**: If your Stdio server script takes complex inputs derived from agent interactions, ensure the script itself sanitizes these inputs to prevent command injection or other vulnerabilities within the script's logic. +- **Resource Limits**: Be mindful that a local Stdio server process consumes local resources (CPU, memory). Ensure it's well-behaved and won't exhaust system resources. + +### Confused Deputy Attacks + +The [Confused Deputy Problem](https://en.wikipedia.org/wiki/Confused_deputy_problem) is a classic security vulnerability that can manifest in MCP integrations, especially when an MCP server acts as a proxy to other third-party services (e.g., Google Calendar, GitHub) that use OAuth 2.0 for authorization. + +**Scenario:** + +1. An MCP server (let's call it `MCP-Proxy`) allows your agent to interact with `ThirdPartyAPI`. +2. `MCP-Proxy` uses its own single, static `client_id` when talking to `ThirdPartyAPI`'s authorization server. +3. You, as the user, legitimately authorize `MCP-Proxy` to access `ThirdPartyAPI` on your behalf. During this, `ThirdPartyAPI`'s auth server might set a cookie in your browser indicating your consent for `MCP-Proxy`'s `client_id`. +4. An attacker crafts a malicious link. This link initiates an OAuth flow with `MCP-Proxy`, but is designed to trick `ThirdPartyAPI`'s auth server. +5. If you click this link, and `ThirdPartyAPI`'s auth server sees your existing consent cookie for `MCP-Proxy`'s `client_id`, it might *skip* asking for your consent again. +6. `MCP-Proxy` might then be tricked into forwarding an authorization code (for `ThirdPartyAPI`) to the attacker, or an MCP authorization code that the attacker can use to impersonate you to `MCP-Proxy`. + +**Mitigation (Primarily for MCP Server Developers):** + +* MCP proxy servers using static client IDs for downstream services **must** obtain explicit user consent for *each client application or agent* connecting to them *before* initiating an OAuth flow with the third-party service. This means `MCP-Proxy` itself should show a consent screen. + +**CrewAI User Implication:** + +* Be cautious if an MCP server redirects you for multiple OAuth authentications, especially if it seems unexpected or if the permissions requested are overly broad. +* Prefer MCP servers that clearly delineate their own identity versus the third-party services they might proxy. + +### Remote Transport Security (SSE & Streamable HTTP) + +When connecting to remote MCP servers via Server-Sent Events (SSE) or Streamable HTTP, standard web security practices are essential. + +### SSE Security Considerations + +### a. DNS Rebinding Attacks (Especially for SSE) + + +**Protect against DNS Rebinding Attacks.** + + +DNS rebinding allows an attacker-controlled website to bypass the same-origin policy and make requests to servers on the user's local network (e.g., `localhost`) or intranet. This is particularly risky if you run an MCP server locally (e.g., for development) and an agent in a browser-like environment (though less common for typical CrewAI backend setups) or if the MCP server is on an internal network. + +**Mitigation Strategies for MCP Server Implementers:** +- **Validate `Origin` and `Host` Headers**: MCP servers (especially SSE ones) should validate the `Origin` and/or `Host` HTTP headers to ensure requests are coming from expected domains/clients. +- **Bind to `localhost` (127.0.0.1)**: When running MCP servers locally for development, bind them to `127.0.0.1` instead of `0.0.0.0`. This prevents them from being accessible from other machines on the network. +- **Authentication**: Require authentication for all connections to your MCP server if it's not intended for public anonymous access. + +### b. Use HTTPS + +- **Encrypt Data in Transit**: Always use HTTPS (HTTP Secure) for the URLs of remote MCP servers. This encrypts the communication between your CrewAI application and the MCP server, protecting against eavesdropping and man-in-the-middle attacks. `MCPServerAdapter` will respect the scheme (`http` or `https`) provided in the URL. + +### c. Token Passthrough (Anti-Pattern) + +This is primarily a concern for MCP server developers but understanding it helps in choosing secure servers. + +"Token passthrough" is when an MCP server accepts an access token from your CrewAI agent (which might be a token for a *different* service, say `ServiceA`) and simply passes it through to another downstream API (`ServiceB`) without proper validation. Specifically, `ServiceB` (or the MCP server itself) should only accept tokens that were explicitly issued *for them* (i.e., the 'audience' claim in the token matches the server/service). + +**Risks:** + +* Bypasses security controls (like rate limiting or fine-grained permissions) on the MCP server or the downstream API. +* Breaks audit trails and accountability. +* Allows misuse of stolen tokens. + +**Mitigation (For MCP Server Developers):** + +* MCP servers **MUST NOT** accept tokens that were not explicitly issued for them. They must validate the token's audience claim. + +**CrewAI User Implication:** + +* While not directly controllable by the user, this highlights the importance of connecting to well-designed MCP servers that adhere to security best practices. + +#### Authentication and Authorization + +- **Verify Identity**: If the MCP server provides sensitive tools or access to private data, it MUST implement strong authentication mechanisms to verify the identity of the client (your CrewAI application). This could involve API keys, OAuth tokens, or other standard methods. +- **Principle of Least Privilege**: Ensure the credentials used by `MCPServerAdapter` (if any) have only the necessary permissions to access the required tools. + +### d. Input Validation and Sanitization + +- **Input Validation is Critical**: MCP servers **must** rigorously validate all inputs received from agents *before* processing them or passing them to tools. This is a primary defense against many common vulnerabilities: + - **Command Injection:** If a tool constructs shell commands, SQL queries, or other interpreted language statements based on input, the server must meticulously sanitize this input to prevent malicious commands from being injected and executed. + - **Path Traversal:** If a tool accesses files based on input parameters, the server must validate and sanitize these paths to prevent access to unauthorized files or directories (e.g., by blocking `../` sequences). + - **Data Type & Range Checks:** Servers must ensure that input data conforms to the expected data types (e.g., string, number, boolean) and falls within acceptable ranges or adheres to defined formats (e.g., regex for URLs). + - **JSON Schema Validation:** All tool parameters should be strictly validated against their defined JSON schema. This helps catch malformed requests early. +- **Client-Side Awareness**: While server-side validation is paramount, as a CrewAI user, be mindful of the data your agents are constructed to send to MCP tools, especially if interacting with less-trusted or new MCP servers. + +### e. Rate Limiting and Resource Management + +- **Prevent Abuse**: MCP servers should implement rate limiting to prevent abuse, whether intentional (Denial of Service attacks) or unintentional (e.g., a misconfigured agent making too many requests). +- **Client-Side Retries**: Implement sensible retry logic in your CrewAI tasks if transient network issues or server rate limits are expected, but avoid aggressive retries that could exacerbate server load. + +## 4. Secure MCP Server Implementation Advice (For Developers) + +If you are developing an MCP server that CrewAI agents might connect to, consider these best practices in addition to the points above: + +- **Follow Secure Coding Practices**: Adhere to standard secure coding principles for your chosen language and framework (e.g., OWASP Top 10). +- **Principle of Least Privilege**: Ensure the process running the MCP server (especially for `Stdio`) has only the minimum necessary permissions. Tools themselves should also operate with the least privilege required to perform their function. +- **Dependency Management**: Keep all server-side dependencies, including operating system packages, language runtimes, and third-party libraries, up-to-date to patch known vulnerabilities. Use tools to scan for vulnerable dependencies. +- **Secure Defaults**: Design your server and its tools to be secure by default. For example, features that could be risky should be off by default or require explicit opt-in with clear warnings. +- **Access Control for Tools**: Implement robust mechanisms to control which authenticated and authorized agents or users can access specific tools, especially those that are powerful, sensitive, or incur costs. +- **Secure Error Handling**: Servers should not expose detailed internal error messages, stack traces, or debugging information to the client, as these can reveal internal workings or potential vulnerabilities. Log errors comprehensively on the server-side for diagnostics. +- **Comprehensive Logging and Monitoring**: Implement detailed logging of security-relevant events (e.g., authentication attempts, tool invocations, errors, authorization changes). Monitor these logs for suspicious activity or abuse patterns. +- **Adherence to MCP Authorization Spec**: If implementing authentication and authorization, strictly follow the [MCP Authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization) and relevant [OAuth 2.0 security best practices](https://datatracker.ietf.org/doc/html/rfc9700). +- **Regular Security Audits**: If your MCP server handles sensitive data, performs critical operations, or is publicly exposed, consider periodic security audits by qualified professionals. + +## 5. Further Reading + +For more detailed information on MCP security, refer to the official documentation: +- **[MCP Transport Security](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)** + +By understanding these security considerations and implementing best practices, you can safely leverage the power of MCP servers in your CrewAI projects. +These are by no means exhaustive, but they cover the most common and critical security concerns. +The threats will continue to evolve, so it's important to stay informed and adapt your security measures accordingly. + diff --git a/docs/v1.15.1/en/mcp/sse.mdx b/docs/v1.15.1/en/mcp/sse.mdx new file mode 100644 index 000000000..6c21c9aca --- /dev/null +++ b/docs/v1.15.1/en/mcp/sse.mdx @@ -0,0 +1,151 @@ +--- +title: SSE Transport +description: Learn how to connect CrewAI to remote MCP servers using Server-Sent Events (SSE) for real-time communication. +icon: wifi +mode: "wide" +--- + +## Overview + +Server-Sent Events (SSE) provide a standard way for a web server to send updates to a client over a single, long-lived HTTP connection. In the context of MCP, SSE is used for remote servers to stream data (like tool responses) to your CrewAI application in real-time. + +## Key Concepts + +- **Remote Servers**: SSE is suitable for MCP servers hosted remotely. +- **Unidirectional Stream**: Typically, SSE is a one-way communication channel from server to client. +- **`MCPServerAdapter` Configuration**: For SSE, you'll provide the server's URL and specify the transport type. + +## Connecting via SSE + +You can connect to an SSE-based MCP server using two main approaches for managing the connection lifecycle: + +### 1. Fully Managed Connection (Recommended) + +Using a Python context manager (`with` statement) is the recommended approach. It automatically handles establishing and closing the connection to the SSE MCP server. + +```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.") + +``` + + +Replace `"http://localhost:8000/sse"` with the actual URL of your SSE MCP server. + + +### 2. Manual Connection Lifecycle + +If you need finer-grained control, you can manage the `MCPServerAdapter` connection lifecycle manually. + + +You **MUST** call `mcp_server_adapter.stop()` to ensure the connection is closed and resources are released. Using a `try...finally` block is highly recommended. + + +```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.") + +``` + +## Security Considerations for SSE + + +**DNS Rebinding Attacks**: SSE transports can be vulnerable to DNS rebinding attacks if the MCP server is not properly secured. This could allow malicious websites to interact with local or intranet-based MCP servers. + + +To mitigate this risk: +- MCP server implementations should **validate `Origin` headers** on incoming SSE connections. +- When running local SSE MCP servers for development, **bind only to `localhost` (`127.0.0.1`)** rather than all network interfaces (`0.0.0.0`). +- Implement **proper authentication** for all SSE connections if they expose sensitive tools or data. + +For a comprehensive overview of security best practices, please refer to our [Security Considerations](./security.mdx) page and the official [MCP Transport Security documentation](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). diff --git a/docs/v1.15.1/en/mcp/stdio.mdx b/docs/v1.15.1/en/mcp/stdio.mdx new file mode 100644 index 000000000..c7c065d0c --- /dev/null +++ b/docs/v1.15.1/en/mcp/stdio.mdx @@ -0,0 +1,135 @@ +--- +title: Stdio Transport +description: Learn how to connect CrewAI to local MCP servers using the Stdio (Standard Input/Output) transport mechanism. +icon: server +mode: "wide" +--- + +## Overview + +The Stdio (Standard Input/Output) transport is designed for connecting `MCPServerAdapter` to local MCP servers that communicate over their standard input and output streams. This is typically used when the MCP server is a script or executable running on the same machine as your CrewAI application. + +## Key Concepts + +- **Local Execution**: Stdio transport manages a locally running process for the MCP server. +- **`StdioServerParameters`**: This class from the `mcp` library is used to configure the command, arguments, and environment variables for launching the Stdio server. + +## Connecting via Stdio + +You can connect to an Stdio-based MCP server using two main approaches for managing the connection lifecycle: + +### 1. Fully Managed Connection (Recommended) + +Using a Python context manager (`with` statement) is the recommended approach. It automatically handles starting the MCP server process and stopping it when the context is exited. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +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]}") + + # Example: Using the tools from the Stdio MCP server in a CrewAI Agent + 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. Manual Connection Lifecycle + +If you need finer-grained control over when the Stdio MCP server process is started and stopped, you can manage the `MCPServerAdapter` lifecycle manually. + + +You **MUST** call `mcp_server_adapter.stop()` to ensure the server process is terminated and resources are released. Using a `try...finally` block is highly recommended. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +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() # Manually start the connection and server process + tools = mcp_server_adapter.tools + print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}") + + # Example: Using the tools with your Agent, Task, Crew setup + 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() # Actual inputs depend on your tool + 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: # Check if connected before stopping + print("Stopping Stdio MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: # If adapter exists but not connected (e.g. start failed) + print("Stdio MCP server adapter was not connected. No stop needed or start failed.") + +``` + +Remember to replace placeholder paths and commands with your actual Stdio server details. The `env` parameter in `StdioServerParameters` can +be used to set environment variables for the server process, which can be useful for configuring its behavior or providing necessary paths (like `PYTHONPATH`). diff --git a/docs/v1.15.1/en/mcp/streamable-http.mdx b/docs/v1.15.1/en/mcp/streamable-http.mdx new file mode 100644 index 000000000..4084aa244 --- /dev/null +++ b/docs/v1.15.1/en/mcp/streamable-http.mdx @@ -0,0 +1,136 @@ +--- +title: Streamable HTTP Transport +description: Learn how to connect CrewAI to remote MCP servers using the flexible Streamable HTTP transport. +icon: globe +mode: "wide" +--- + +## Overview + +Streamable HTTP transport provides a flexible way to connect to remote MCP servers. It's often built upon HTTP and can support various communication patterns, including request-response and streaming, sometimes utilizing Server-Sent Events (SSE) for server-to-client streams within a broader HTTP interaction. + +## Key Concepts + +- **Remote Servers**: Designed for MCP servers hosted remotely. +- **Flexibility**: Can support more complex interaction patterns than plain SSE, potentially including bi-directional communication if the server implements it. +- **`MCPServerAdapter` Configuration**: You'll need to provide the server's base URL for MCP communication and specify `"streamable-http"` as the transport type. + +## Connecting via Streamable HTTP + +You have two primary methods for managing the connection lifecycle with a Streamable HTTP MCP server: + +### 1. Fully Managed Connection (Recommended) + +The recommended approach is to use a Python context manager (`with` statement), which handles the connection's setup and teardown automatically. + +```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.") + +``` +**Note:** Replace `"http://localhost:8001/mcp"` with the actual URL of your Streamable HTTP MCP server. + +### 2. Manual Connection Lifecycle + +For scenarios requiring more explicit control, you can manage the `MCPServerAdapter` connection manually. + + +It is **critical** to call `mcp_server_adapter.stop()` when you are done to close the connection and free up resources. A `try...finally` block is the safest way to ensure this. + + +```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.") +``` + +## Security Considerations + +When using Streamable HTTP transport, general web security best practices are paramount: +- **Use HTTPS**: Always prefer HTTPS (HTTP Secure) for your MCP server URLs to encrypt data in transit. +- **Authentication**: Implement robust authentication mechanisms if your MCP server exposes sensitive tools or data. +- **Input Validation**: Ensure your MCP server validates all incoming requests and parameters. + +For a comprehensive guide on securing your MCP integrations, please refer to our [Security Considerations](./security.mdx) page and the official [MCP Transport Security documentation](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). diff --git a/docs/v1.15.1/en/observability/arize-phoenix.mdx b/docs/v1.15.1/en/observability/arize-phoenix.mdx new file mode 100644 index 000000000..6558d3a60 --- /dev/null +++ b/docs/v1.15.1/en/observability/arize-phoenix.mdx @@ -0,0 +1,152 @@ +--- +title: Arize Phoenix +description: Arize Phoenix integration for CrewAI with OpenTelemetry and OpenInference +icon: magnifying-glass-chart +mode: "wide" +--- + +# Arize Phoenix Integration + +This guide demonstrates how to integrate **Arize Phoenix** with **CrewAI** using OpenTelemetry via the [OpenInference](https://github.com/openinference/openinference) SDK. By the end of this guide, you will be able to trace your CrewAI agents and easily debug your agents. + +> **What is Arize Phoenix?** [Arize Phoenix](https://phoenix.arize.com) is an LLM observability platform that provides tracing and evaluation for AI applications. + +[![Watch a Video Demo of Our Integration with Phoenix](https://storage.googleapis.com/arize-assets/fixtures/setup_crewai.png)](https://www.youtube.com/watch?v=Yc5q3l6F7Ww) + +## Get Started + +We'll walk through a simple example of using CrewAI and integrating it with Arize Phoenix via OpenTelemetry using OpenInference. + +You can also access this guide on [Google Colab](https://colab.research.google.com/github/Arize-ai/phoenix/blob/main/tutorials/tracing/crewai_tracing_tutorial.ipynb). + +### Step 1: Install Dependencies + +```bash +pip install openinference-instrumentation-crewai crewai crewai-tools arize-phoenix-otel +``` + +### Step 2: Set Up Environment Variables + +Setup Phoenix Cloud API keys and configure OpenTelemetry to send traces to Phoenix. Phoenix Cloud is a hosted version of Arize Phoenix, but it is not required to use this integration. + +You can get your free Serper API key [here](https://serper.dev/). + +```python +import os +from getpass import getpass + +# Get your Phoenix Cloud credentials +PHOENIX_API_KEY = getpass("🔑 Enter your Phoenix Cloud API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") +SERPER_API_KEY = getpass("🔑 Enter your Serper API key: ") + +# Set environment variables +os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={PHOENIX_API_KEY}" +os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com" # Phoenix Cloud, change this to your own endpoint if you are using a self-hosted instance +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +os.environ["SERPER_API_KEY"] = SERPER_API_KEY +``` + +### Step 3: Initialize OpenTelemetry with Phoenix + +Initialize the OpenInference OpenTelemetry instrumentation SDK to start capturing traces and send them to Phoenix. + +```python +from phoenix.otel import register + +tracer_provider = register( + project_name="crewai-tracing-demo", + auto_instrument=True, +) +``` + +### Step 4: Create a CrewAI Application + +We'll create a CrewAI application where two agents collaborate to research and write a blog post about AI advancements. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool +from openinference.instrumentation.crewai import CrewAIInstrumentor +from phoenix.otel import register + +# setup monitoring for your crew +tracer_provider = register( + endpoint="http://localhost:6006/v1/traces") +CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider) +search_tool = SerperDevTool() + +# Define your agents with roles and goals +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, +) + +# Create tasks for your agents +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, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[researcher, writer], tasks=[task1, task2], verbose=1, process=Process.sequential +) + +# Get your crew to work! +result = crew.kickoff() + +print("######################") +print(result) +``` + +### Step 5: View Traces in Phoenix + +After running the agent, you can view the traces generated by your CrewAI application in Phoenix. You should see detailed steps of the agent interactions and LLM calls, which can help you debug and optimize your AI agents. + +Log into your Phoenix Cloud account and navigate to the project you specified in the `project_name` parameter. You'll see a timeline view of your trace with all the agent interactions, tool usages, and LLM calls. + +![Example trace in Phoenix showing agent interactions](https://storage.googleapis.com/arize-assets/fixtures/crewai_traces.png) + + +### Version Compatibility Information +- Python 3.8+ +- CrewAI >= 0.86.0 +- Arize Phoenix >= 7.0.1 +- OpenTelemetry SDK >= 1.31.0 + + +### References +- [Phoenix Documentation](https://docs.arize.com/phoenix/) - Overview of the Phoenix platform. +- [CrewAI Documentation](https://docs.crewai.com/) - Overview of the CrewAI framework. +- [OpenTelemetry Docs](https://opentelemetry.io/docs/) - OpenTelemetry guide +- [OpenInference GitHub](https://github.com/openinference/openinference) - Source code for OpenInference SDK. diff --git a/docs/v1.15.1/en/observability/braintrust.mdx b/docs/v1.15.1/en/observability/braintrust.mdx new file mode 100644 index 000000000..21ab52c85 --- /dev/null +++ b/docs/v1.15.1/en/observability/braintrust.mdx @@ -0,0 +1,237 @@ +--- +title: Braintrust +description: Braintrust integration for CrewAI with OpenTelemetry tracing and evaluation +icon: magnifying-glass-chart +mode: "wide" +--- + +# Braintrust Integration + +This guide demonstrates how to integrate **Braintrust** with **CrewAI** using OpenTelemetry for comprehensive tracing and evaluation. By the end of this guide, you will be able to trace your CrewAI agents, monitor their performance, and evaluate their outputs using Braintrust's powerful observability platform. + +> **What is Braintrust?** [Braintrust](https://www.braintrust.dev) is an AI evaluation and observability platform that provides comprehensive tracing, evaluation, and monitoring for AI applications with built-in experiment tracking and performance analytics. + +## Get Started + +We'll walk through a simple example of using CrewAI and integrating it with Braintrust via OpenTelemetry for comprehensive observability and evaluation. + +### Step 1: Install Dependencies + +```bash +uv add braintrust[otel] crewai crewai-tools opentelemetry-instrumentation-openai opentelemetry-instrumentation-crewai python-dotenv +``` + +### Step 2: Set Up Environment Variables + +Setup Braintrust API keys and configure OpenTelemetry to send traces to Braintrust. You'll need a Braintrust API key and your OpenAI API key. + +```python +import os +from getpass import getpass + +# Get your Braintrust credentials +BRAINTRUST_API_KEY = getpass("🔑 Enter your Braintrust API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") + +# Set environment variables +os.environ["BRAINTRUST_API_KEY"] = BRAINTRUST_API_KEY +os.environ["BRAINTRUST_PARENT"] = "project_name:crewai-demo" +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +``` + +### Step 3: Initialize OpenTelemetry with Braintrust + +Initialize the Braintrust OpenTelemetry instrumentation to start capturing traces and send them to Braintrust. + +```python +import os +from typing import Any, Dict + +from braintrust.otel import BraintrustSpanProcessor +from crewai import Agent, Crew, Task +from crewai.llm import LLM +from opentelemetry import trace +from opentelemetry.instrumentation.crewai import CrewAIInstrumentor +from opentelemetry.instrumentation.openai import OpenAIInstrumentor +from opentelemetry.sdk.trace import TracerProvider + +def setup_tracing() -> None: + """Setup OpenTelemetry tracing with Braintrust.""" + current_provider = trace.get_tracer_provider() + if isinstance(current_provider, TracerProvider): + provider = current_provider + else: + provider = TracerProvider() + trace.set_tracer_provider(provider) + + provider.add_span_processor(BraintrustSpanProcessor()) + CrewAIInstrumentor().instrument(tracer_provider=provider) + OpenAIInstrumentor().instrument(tracer_provider=provider) + + +setup_tracing() +``` + +### Step 4: Create a CrewAI Application + +We'll create a CrewAI application where two agents collaborate to research and write a blog post about AI advancements, with comprehensive tracing enabled. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +def create_crew() -> Crew: + """Create a crew with multiple agents for comprehensive tracing.""" + llm = LLM(model="gpt-4o-mini") + search_tool = SerperDevTool() + + # Define agents with specific roles + 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, + llm=llm, + 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, + llm=llm, + ) + + # Create tasks for your agents + research_task = Task( + description="""Conduct a comprehensive analysis of the latest advancements in {topic}. + Identify key trends, breakthrough technologies, and potential industry impacts.""", + expected_output="Full analysis report in bullet points", + agent=researcher, + ) + + writing_task = Task( + description="""Using the insights provided, develop an engaging blog + post that highlights the most significant {topic} 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, + context=[research_task], + ) + + # Instantiate your crew with a sequential process + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential + ) + + return crew + +def run_crew(): + """Run the crew and return results.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": "AI developments"}) + return result + +# Run your crew +if __name__ == "__main__": + # Instrumentation is already initialized above in this module + result = run_crew() + print(result) +``` + +### Step 5: View Traces in Braintrust + +After running your crew, you can view comprehensive traces in Braintrust through different perspectives: + + + + + Braintrust Trace View + + + + + + Braintrust Timeline View + + + + + + Braintrust Thread View + + + + +### Step 6: Evaluate via SDK (Experiments) + +You can also run evaluations using Braintrust's Eval SDK. This is useful for comparing versions or scoring outputs offline. Below is a Python example using the `Eval` class with the crew we created above: + +```python +# eval_crew.py +from braintrust import Eval +from autoevals import Levenshtein + +def evaluate_crew_task(input_data): + """Task function that wraps our crew for evaluation.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": input_data["topic"]}) + return str(result) + +Eval( + "AI Research Crew", # Project name + { + "data": lambda: [ + {"topic": "artificial intelligence trends 2024"}, + {"topic": "machine learning breakthroughs"}, + {"topic": "AI ethics and governance"}, + ], + "task": evaluate_crew_task, + "scores": [Levenshtein], + }, +) +``` + +Setup your API key and run: + +```bash +export BRAINTRUST_API_KEY="YOUR_API_KEY" +braintrust eval eval_crew.py +``` + +See the [Braintrust Eval SDK guide](https://www.braintrust.dev/docs/start/eval-sdk) for more details. + +### Key Features of Braintrust Integration + +- **Comprehensive Tracing**: Track all agent interactions, tool usage, and LLM calls +- **Performance Monitoring**: Monitor execution times, token usage, and success rates +- **Experiment Tracking**: Compare different crew configurations and models +- **Automated Evaluation**: Set up custom evaluation metrics for crew outputs +- **Error Tracking**: Monitor and debug failures across your crew executions +- **Cost Analysis**: Track token usage and associated costs + +### Version Compatibility Information +- Python 3.8+ +- CrewAI >= 0.86.0 +- Braintrust >= 0.1.0 +- OpenTelemetry SDK >= 1.31.0 + +### References +- [Braintrust Documentation](https://www.braintrust.dev/docs) - Overview of the Braintrust platform +- [Braintrust CrewAI Integration](https://www.braintrust.dev/docs/integrations/crew-ai) - Official CrewAI integration guide +- [Braintrust Eval SDK](https://www.braintrust.dev/docs/start/eval-sdk) - Run experiments via the SDK +- [CrewAI Documentation](https://docs.crewai.com/) - Overview of the CrewAI framework +- [OpenTelemetry Docs](https://opentelemetry.io/docs/) - OpenTelemetry guide +- [Braintrust GitHub](https://github.com/braintrustdata/braintrust) - Source code for Braintrust SDK diff --git a/docs/v1.15.1/en/observability/datadog.mdx b/docs/v1.15.1/en/observability/datadog.mdx new file mode 100644 index 000000000..0094446c5 --- /dev/null +++ b/docs/v1.15.1/en/observability/datadog.mdx @@ -0,0 +1,109 @@ +--- +title: Datadog Integration +description: Learn how to integrate Datadog with CrewAI to submit LLM Observability traces to Datadog. +icon: dog +mode: "wide" +--- + +# Integrate Datadog with CrewAI + +This guide will demonstrate how to integrate **[Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/)** with **CrewAI** using [Datadog auto-instrumentation](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python). By the end of this guide, you will be able to submit LLM Observability traces to Datadog and view your CrewAI agent runs in Datadog LLM Observability's [Agentic Execution View](https://docs.datadoghq.com/llm_observability/monitoring/agent_monitoring). + +## What is Datadog LLM Observability? + +[Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) helps AI engineers, data scientists, and application developers quickly develop, evaluate, and monitor LLM applications. Confidently improve output quality, performance, costs, and overall risk with structured experiments, end-to-end tracing across AI agents, and evaluations. + +## Getting Started + +### Install Dependencies + +```shell +pip install ddtrace crewai crewai-tools +``` + +### Set Environment Variables + +If you do not have a Datadog API key, you can [create an account](https://www.datadoghq.com/) and [get your API key](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + +You will also need to specify an ML Application name in the following environment variables. An ML Application is a grouping of LLM Observability traces associated with a specific LLM-based application. See [ML Application Naming Guidelines](https://docs.datadoghq.com/llm_observability/instrumentation/sdk?tab=python#application-naming-guidelines) for more information on limitations with ML Application names. + +```shell +export DD_API_KEY= +export DD_SITE= +export DD_LLMOBS_ENABLED=true +export DD_LLMOBS_ML_APP= +export DD_LLMOBS_AGENTLESS_ENABLED=true +export DD_APM_TRACING_ENABLED=false +``` + +Additionally, configure any LLM provider API keys + +```shell +export OPENAI_API_KEY= +export ANTHROPIC_API_KEY= +export GEMINI_API_KEY= +... +``` + +### Create a CrewAI Agent Application + +```python +# crewai_agent.py +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], +) + +task = Task( + description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer +) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) + +output = crew.kickoff(dict(multiplication="2 * 2")) +``` + +### Run the Application with Datadog Auto-Instrumentation + +With the [environment variables](#set-environment-variables) set, you can now run the application with Datadog auto-instrumentation. + +```shell +ddtrace-run python crewai_agent.py +``` + +### View the Traces in Datadog + +After running the application, you can view the traces in [Datadog LLM Observability's Traces View](https://app.datadoghq.com/llm/traces), selecting the ML Application name you chose from the top-left dropdown. + +Clicking on a trace will show you the details of the trace, including total tokens used, number of LLM calls, models used, and estimated cost. Clicking into a specific span will narrow down these details, and show related input, output, and metadata. + + +Datadog LLM Observability Trace View + + +Additionally, you can view the execution graph view of the trace, which shows the control and data flow of the trace, which will scale with larger agents to show handoffs and relationships between LLM calls, tool calls, and agent interactions. + + +Datadog LLM Observability Agent Execution Flow View + + +## References + +- [Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) +- [Datadog LLM Observability CrewAI Auto-Instrumentation](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python#crew-ai) diff --git a/docs/v1.15.1/en/observability/galileo.mdx b/docs/v1.15.1/en/observability/galileo.mdx new file mode 100644 index 000000000..241517ed2 --- /dev/null +++ b/docs/v1.15.1/en/observability/galileo.mdx @@ -0,0 +1,115 @@ +--- +title: Galileo +description: Galileo integration for CrewAI tracing and evaluation +icon: telescope +mode: "wide" +--- + +## Overview + +This guide demonstrates how to integrate **Galileo** with **CrewAI** +for comprehensive tracing and Evaluation Engineering. +By the end of this guide, you will be able to trace your CrewAI agents, +monitor their performance, and evaluate their behaviour with +Galileo's powerful observability platform. + +> **What is Galileo?** [Galileo](https://galileo.ai) is AI evaluation and observability +platform that delivers end-to-end tracing, evaluation, +and monitoring for AI applications. It enables teams to capture ground truth, +create robust guardrails, and run systematic experiments with +built-in experiment tracking and performance analytics—ensuring reliability, +transparency, and continuous improvement across the AI lifecycle. + +## Getting started + +This tutorial follows the [CrewAI quickstart](/en/quickstart) and shows how to add +Galileo's [CrewAIEventListener](https://v2docs.galileo.ai/sdk-api/python/reference/handlers/crewai/handler), +an event handler. +For more information, see Galileo’s +[Add Galileo to a CrewAI Application](https://v2docs.galileo.ai/how-to-guides/third-party-integrations/add-galileo-to-crewai/add-galileo-to-crewai) +how-to guide. + +> **Note** This tutorial assumes you have completed the [CrewAI quickstart](/en/quickstart). +If you want a completed comprehensive example, see the Galileo +[CrewAI sdk-example repo](https://github.com/rungalileo/sdk-examples/tree/main/python/agent/crew-ai). + +### Step 1: Install dependencies + +Install the required dependencies for your app. +Create a virtual environment using your preferred method, +then install dependencies inside that environment using your +preferred tool: + +```bash +uv add galileo +``` + +### Step 2: Add to the .env file from the [CrewAI quickstart](/en/quickstart) + +```bash +# Your Galileo API key +GALILEO_API_KEY="your-galileo-api-key" + +# Your Galileo project name +GALILEO_PROJECT="your-galileo-project-name" + +# The name of the Log stream you want to use for logging +GALILEO_LOG_STREAM="your-galileo-log-stream " +``` + +### Step 3: Add the Galileo event listener + +To enable logging with Galileo, you need to create an instance of the `CrewAIEventListener`. +Import the Galileo CrewAI handler package by +adding the following code at the top of your main.py file: + +```python +from galileo.handlers.crewai.handler import CrewAIEventListener +``` + +At the start of your run function, create the event listener: + +```python +def run(): + # Create the event listener + CrewAIEventListener() + # The rest of your existing code goes here +``` + +When you create the listener instance, it is automatically +registered with CrewAI. + +### Step 4: Run your crew + +Run your crew with the CrewAI CLI: + +```bash +crewai run +``` + +### Step 5: View the traces in Galileo + +Once your crew has finished, the traces will be flushed and appear in Galileo. + +![Galileo trace view](/images/galileo-trace-veiw.png) + +## Understanding the Galileo Integration + +Galileo integrates with CrewAI by registering an event listener +that captures Crew execution events (e.g., agent actions, tool calls, model responses) +and forwards them to Galileo for observability and evaluation. + +### Understanding the event listener + +Creating a `CrewAIEventListener()` instance is all that’s +required to enable Galileo for a CrewAI run. When instantiated, the listener: + +- Automatically registers itself with CrewAI +- Reads Galileo configuration from environment variables +- Logs all run data to the Galileo project and log stream specified by + `GALILEO_PROJECT` and `GALILEO_LOG_STREAM` + +No additional configuration or code changes are required. +All data from this run is logged to the Galileo project and +log stream specified by your environment configuration +(for example, GALILEO_PROJECT and GALILEO_LOG_STREAM). diff --git a/docs/v1.15.1/en/observability/langdb.mdx b/docs/v1.15.1/en/observability/langdb.mdx new file mode 100644 index 000000000..adb2d1908 --- /dev/null +++ b/docs/v1.15.1/en/observability/langdb.mdx @@ -0,0 +1,287 @@ +--- +title: LangDB Integration +description: Govern, secure, and optimize your CrewAI workflows with LangDB AI Gateway—access 350+ models, automatic routing, cost optimization, and full observability. +icon: database +mode: "wide" +--- + +# Introduction + +[LangDB AI Gateway](https://langdb.ai) provides OpenAI-compatible APIs to connect with multiple Large Language Models and serves as an observability platform that makes it effortless to trace CrewAI workflows end-to-end while providing access to 350+ language models. With a single `init()` call, all agent interactions, task executions, and LLM calls are captured, providing comprehensive observability and production-ready AI infrastructure for your applications. + + + LangDB CrewAI trace example + + +**Checkout:** [View the live trace example](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22) + +## Features + +### AI Gateway Capabilities +- **Access to 350+ LLMs**: Connect to all major language models through a single integration +- **Virtual Models**: Create custom model configurations with specific parameters and routing rules +- **Virtual MCP**: Enable compatibility and integration with MCP (Model Context Protocol) systems for enhanced agent communication +- **Guardrails**: Implement safety measures and compliance controls for agent behavior + +### Observability & Tracing +- **Automatic Tracing**: Single `init()` call captures all CrewAI interactions +- **End-to-End Visibility**: Monitor agent workflows from start to finish +- **Tool Usage Tracking**: Track which tools agents use and their outcomes +- **Model Call Monitoring**: Detailed insights into LLM interactions +- **Performance Analytics**: Monitor latency, token usage, and costs +- **Debugging Support**: Step-through execution for troubleshooting +- **Real-time Monitoring**: Live traces and metrics dashboard + +## Setup Instructions + + + + Install the LangDB client with CrewAI feature flag: + ```bash + pip install 'pylangdb[crewai]' + ``` + + + Configure your LangDB credentials: + ```bash + export LANGDB_API_KEY="" + export LANGDB_PROJECT_ID="" + export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + ``` + + + Import and initialize LangDB before configuring your CrewAI code: + ```python + from pylangdb.crewai import init + # Initialize LangDB + init() + ``` + + + Set up your LLM with LangDB headers: + ```python + from crewai import Agent, Task, Crew, LLM + import os + + # Configure LLM with LangDB headers + llm = LLM( + model="openai/gpt-4o", # Replace with the model you want to use + api_key=os.getenv("LANGDB_API_KEY"), + base_url=os.getenv("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.getenv("LANGDB_PROJECT_ID")} + ) + ``` + + + +## Quick Start Example + +Here's a simple example to get you started with LangDB and CrewAI: + +```python +import os +from pylangdb.crewai import init +from crewai import Agent, Task, Crew, LLM + +# Initialize LangDB before any CrewAI imports +init() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +# Define your agent +researcher = Agent( + role="Research Specialist", + goal="Research topics thoroughly", + backstory="Expert researcher with skills in finding information", + llm=create_llm("openai/gpt-4o"), # Replace with the model you want to use + verbose=True +) + +# Create a task +task = Task( + description="Research the given topic and provide a comprehensive summary", + agent=researcher, + expected_output="Detailed research summary with key findings" +) + +# Create and run the crew +crew = Crew(agents=[researcher], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## Complete Example: Research and Planning Agent + +This comprehensive example demonstrates a multi-agent workflow with research and planning capabilities. + +### Prerequisites + +```bash +pip install crewai 'pylangdb[crewai]' crewai_tools setuptools python-dotenv +``` + +### Environment Setup + +```bash +# LangDB credentials +export LANGDB_API_KEY="" +export LANGDB_PROJECT_ID="" +export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + +# Additional API keys (optional) +export SERPER_API_KEY="" # For web search capabilities +``` + +### Complete Implementation + +```python +#!/usr/bin/env python3 + +import os +import sys +from pylangdb.crewai import init +init() # Initialize LangDB before any CrewAI imports +from dotenv import load_dotenv +from crewai import Agent, Task, Crew, Process, LLM +from crewai_tools import SerperDevTool + +load_dotenv() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +class ResearchPlanningCrew: + def researcher(self) -> Agent: + return Agent( + role="Research Specialist", + goal="Research topics thoroughly and compile comprehensive information", + backstory="Expert researcher with skills in finding and analyzing information from various sources", + tools=[SerperDevTool()], + llm=create_llm("openai/gpt-4o"), + verbose=True + ) + + def planner(self) -> Agent: + return Agent( + role="Strategic Planner", + goal="Create actionable plans based on research findings", + backstory="Strategic planner who breaks down complex challenges into executable plans", + reasoning=True, + max_reasoning_attempts=3, + llm=create_llm("openai/anthropic/claude-3.7-sonnet"), + verbose=True + ) + + def research_task(self) -> Task: + return Task( + description="Research the topic thoroughly and compile comprehensive information", + agent=self.researcher(), + expected_output="Comprehensive research report with key findings and insights" + ) + + def planning_task(self) -> Task: + return Task( + description="Create a strategic plan based on the research findings", + agent=self.planner(), + expected_output="Strategic execution plan with phases, goals, and actionable steps", + context=[self.research_task()] + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.researcher(), self.planner()], + tasks=[self.research_task(), self.planning_task()], + verbose=True, + process=Process.sequential + ) + +def main(): + topic = sys.argv[1] if len(sys.argv) > 1 else "Artificial Intelligence in Healthcare" + + crew_instance = ResearchPlanningCrew() + + # Update task descriptions with the specific topic + crew_instance.research_task().description = f"Research {topic} thoroughly and compile comprehensive information" + crew_instance.planning_task().description = f"Create a strategic plan for {topic} based on the research findings" + + result = crew_instance.crew().kickoff() + print(result) + +if __name__ == "__main__": + main() +``` + +### Running the Example + +```bash +python main.py "Sustainable Energy Solutions" +``` + +## Viewing Traces in LangDB + +After running your CrewAI application, you can view detailed traces in the LangDB dashboard: + + + LangDB trace dashboard showing CrewAI workflow + + +### What You'll See + +- **Agent Interactions**: Complete flow of agent conversations and task handoffs +- **Tool Usage**: Which tools were called, their inputs, and outputs +- **Model Calls**: Detailed LLM interactions with prompts image.pngand responses +- **Performance Metrics**: Latency, token usage, and cost tracking +- **Execution Timeline**: Step-by-step view of the entire workflow + + +## Troubleshooting + +### Common Issues + +- **No traces appearing**: Ensure `init()` is called before any CrewAI imports +- **Authentication errors**: Verify your LangDB API key and project ID + + +## Resources + + + + Official LangDB documentation and guides + + + Step-by-step tutorials for building AI agents + + + Complete CrewAI integration examples + + + Access your traces and analytics + + + Browse 350+ available language models + + + Self-hosted options and enterprise capabilities + + + +## Next Steps + +This guide covered the basics of integrating LangDB AI Gateway with CrewAI. To further enhance your AI workflows, explore: + +- **Virtual Models**: Create custom model configurations with routing strategies +- **Guardrails & Safety**: Implement content filtering and compliance controls +- **Production Deployment**: Configure fallbacks, retries, and load balancing + +For more advanced features and use cases, visit the [LangDB Documentation](https://docs.langdb.ai) or explore the [Model Catalog](https://app.langdb.ai/models) to discover all available models. diff --git a/docs/v1.15.1/en/observability/langfuse.mdx b/docs/v1.15.1/en/observability/langfuse.mdx new file mode 100644 index 000000000..2340b593e --- /dev/null +++ b/docs/v1.15.1/en/observability/langfuse.mdx @@ -0,0 +1,112 @@ +--- +title: Langfuse Integration +description: Learn how to integrate Langfuse with CrewAI via OpenTelemetry using OpenLit +icon: vials +mode: "wide" +--- + +# Integrate Langfuse with CrewAI + +This notebook demonstrates how to integrate **Langfuse** with **CrewAI** using OpenTelemetry via the **OpenLit** SDK. By the end of this notebook, you will be able to trace your CrewAI applications with Langfuse for improved observability and debugging. + +> **What is Langfuse?** [Langfuse](https://langfuse.com) is an open-source LLM engineering platform. It provides tracing and monitoring capabilities for LLM applications, helping developers debug, analyze, and optimize their AI systems. Langfuse integrates with various tools and frameworks via native integrations, OpenTelemetry, and APIs/SDKs. + +[![Langfuse Overview Video](https://github.com/user-attachments/assets/3926b288-ff61-4b95-8aa1-45d041c70866)](https://langfuse.com/watch-demo) + +## Get Started + +We'll walk through a simple example of using CrewAI and integrating it with Langfuse via OpenTelemetry using OpenLit. + +### Step 1: Install Dependencies + + +```python +%pip install langfuse openlit crewai crewai_tools +``` + +### Step 2: Set Up Environment Variables + +Set your Langfuse API keys and configure OpenTelemetry export settings to send traces to Langfuse. Please refer to the [Langfuse OpenTelemetry Docs](https://langfuse.com/docs/opentelemetry/get-started) for more information on the Langfuse OpenTelemetry endpoint `/api/public/otel` and authentication. + + +```python +import os + +# Get keys for your project from the project settings page: 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" # 🇪🇺 EU region +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region + + +# Your OpenAI key +os.environ["OPENAI_API_KEY"] = "sk-proj-..." +``` +With the environment variables set, we can now initialize the Langfuse client. get_client() initializes the Langfuse client using the credentials provided in the environment variables. + +```python +from langfuse import get_client + +langfuse = get_client() + +# Verify connection +if langfuse.auth_check(): + print("Langfuse client is authenticated and ready!") +else: + print("Authentication failed. Please check your credentials and host.") +``` + +### Step 3: Initialize OpenLit + +Initialize the OpenLit OpenTelemetry instrumentation SDK to start capturing OpenTelemetry traces. + + +```python +import openlit + +openlit.init() +``` + +### Step 4: Create a Simple CrewAI Application + +We'll create a simple CrewAI application where multiple agents collaborate to answer a user's question. + + +```python +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], + ) + +task = Task(description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) +``` + +### Step 5: See Traces in Langfuse + +After running the agent, you can view the traces generated by your CrewAI application in [Langfuse](https://cloud.langfuse.com). You should see detailed steps of the LLM interactions, which can help you debug and optimize your AI agent. + +![CrewAI example trace in Langfuse](https://langfuse.com/images/cookbook/integration_crewai/crewai-example-trace.png) + +_[Public example trace in Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/e2cf380ffc8d47d28da98f136140642b?timestamp=2025-02-05T15%3A12%3A02.717Z&observation=3b32338ee6a5d9af)_ + +## References + +- [Langfuse OpenTelemetry Docs](https://langfuse.com/docs/opentelemetry/get-started) diff --git a/docs/v1.15.1/en/observability/langtrace.mdx b/docs/v1.15.1/en/observability/langtrace.mdx new file mode 100644 index 000000000..8257f8eb7 --- /dev/null +++ b/docs/v1.15.1/en/observability/langtrace.mdx @@ -0,0 +1,73 @@ +--- +title: Langtrace Integration +description: How to monitor cost, latency, and performance of CrewAI Agents using Langtrace, an external observability tool. +icon: chart-line +mode: "wide" +--- + +# Langtrace Overview + +Langtrace is an open-source, external tool that helps you set up observability and evaluations for Large Language Models (LLMs), LLM frameworks, and Vector Databases. +While not built directly into CrewAI, Langtrace can be used alongside CrewAI to gain deep visibility into the cost, latency, and performance of your CrewAI Agents. +This integration allows you to log hyperparameters, monitor performance regressions, and establish a process for continuous improvement of your Agents. + +![Overview of a select series of agent session runs](/images/langtrace1.png) +![Overview of agent traces](/images/langtrace2.png) +![Overview of llm traces in details](/images/langtrace3.png) + +## Setup Instructions + + + + Sign up by visiting [https://langtrace.ai/signup](https://langtrace.ai/signup). + + + Set the project type to `CrewAI` and generate an API key. + + + Use the following command: + + ```bash + pip install langtrace-python-sdk + ``` + + + Import and initialize Langtrace at the beginning of your script, before any CrewAI imports: + + ```python + from langtrace_python_sdk import langtrace + langtrace.init(api_key='') + + # Now import CrewAI modules + from crewai import Agent, Task, Crew + ``` + + + +### Features and Their Application to CrewAI + +1. **LLM Token and Cost Tracking** + + - Monitor the token usage and associated costs for each CrewAI agent interaction. + +2. **Trace Graph for Execution Steps** + + - Visualize the execution flow of your CrewAI tasks, including latency and logs. + - Useful for identifying bottlenecks in your agent workflows. + +3. **Dataset Curation with Manual Annotation** + + - Create datasets from your CrewAI task outputs for future training or evaluation. + +4. **Prompt Versioning and Management** + + - Keep track of different versions of prompts used in your CrewAI agents. + - Useful for A/B testing and optimizing agent performance. + +5. **Prompt Playground with Model Comparisons** + + - Test and compare different prompts and models for your CrewAI agents before deployment. + +6. **Testing and Evaluations** + + - Set up automated tests for your CrewAI agents and tasks. diff --git a/docs/v1.15.1/en/observability/maxim.mdx b/docs/v1.15.1/en/observability/maxim.mdx new file mode 100644 index 000000000..f8a2b46e4 --- /dev/null +++ b/docs/v1.15.1/en/observability/maxim.mdx @@ -0,0 +1,232 @@ +--- +title: "Maxim Integration" +description: "Start Agent monitoring, evaluation, and observability" +icon: "infinity" +mode: "wide" +--- + +# Maxim Overview + +Maxim AI provides comprehensive agent monitoring, evaluation, and observability for your CrewAI applications. With Maxim's one-line integration, you can easily trace and analyse agent interactions, performance metrics, and more. + +## Features + +### Prompt Management + +Maxim's Prompt Management capabilities enable you to create, organize, and optimize prompts for your CrewAI agents. Rather than hardcoding instructions, leverage Maxim’s SDK to dynamically retrieve and apply version-controlled prompts. + + + + Create, refine, experiment and deploy your prompts via the playground. Organize of your prompts using folders and versions, experimenting with the real world cases by linking tools and context, and deploying based on custom logic. + + Easily experiment across models by [**configuring models**](https://www.getmaxim.ai/docs/introduction/quickstart/setting-up-workspace#add-model-api-keys) and selecting the relevant model from the dropdown at the top of the prompt playground. + + + + + As teams build their AI applications, a big part of experimentation is iterating on the prompt structure. In order to collaborate effectively and organize your changes clearly, Maxim allows prompt versioning and comparison runs across versions. + + + + + Iterating on Prompts as you evolve your AI application would need experiments across models, prompt structures, etc. In order to compare versions and make informed decisions about changes, the comparison playground allows a side by side view of results. + + ## **Why use Prompt comparison?** + + Prompt comparison combines multiple single Prompts into one view, enabling a streamlined approach for various workflows: + + 1. **Model comparison**: Evaluate the performance of different models on the same Prompt. + 2. **Prompt optimization**: Compare different versions of a Prompt to identify the most effective formulation. + 3. **Cross-Model consistency**: Ensure consistent outputs across various models for the same Prompt. + 4. **Performance benchmarking**: Analyze metrics like latency, cost, and token count across different models and Prompts. + + + +### Observability & Evals + +Maxim AI provides comprehensive observability & evaluation for your CrewAI agents, helping you understand exactly what's happening during each execution. + + + + Track your agent’s complete lifecycle, including tool calls, agent trajectories, and decision flows effortlessly. + + + + + Run detailed evaluations on full traces or individual nodes with support for: + + - Multi-step interactions and granular trace analysis + - Session Level Evaluations + - Simulations for real-world testing + + + + + +

+ Evaluate captured logs automatically from the UI based on filters and sampling + +

+ + +

+ Use human evaluation or rating to assess the quality of your logs and evaluate them. + +

+ + +

+ Evaluate any component of your trace or log to gain insights into your agent’s behavior. + +

+ + + --- + + + Set thresholds on **error**, **cost, token usage, user feedback, latency** and get real-time alerts via Slack or PagerDuty. + + + + + Visualize Traces over time, usage metrics, latency & error rates with ease. + + + + + +## Getting Started + +### Prerequisites + + +- Python version \>=3.10 +- A Maxim account ([sign up here](https://getmaxim.ai/)) +- Generate Maxim API Key +- A CrewAI project + +### Installation + +Install the Maxim SDK via pip: + +```python +pip install maxim-py +``` + +Or add it to your `requirements.txt`: + +``` +maxim-py +``` +### Basic Setup + +### 1. Set up environment variables + +```python +### Environment Variables Setup + +# Create a `.env` file in your project root: + +# Maxim API Configuration +MAXIM_API_KEY=your_api_key_here +MAXIM_LOG_REPO_ID=your_repo_id_here +``` + +### 2. Import the required packages + +```python +from crewai import Agent, Task, Crew, Process +from maxim import Maxim +from maxim.logger.crewai import instrument_crewai +``` + +### 3. Initialise Maxim with your API key + + +```python {8} +# Instrument CrewAI with just one line +instrument_crewai(Maxim().logger()) +``` + +### 4. Create and run your CrewAI application as usual + +```python +# Create your agent +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 +) + +# Define the task +research_task = Task( + description="Research the latest AI advancements...", + expected_output="", + agent=researcher +) + +# Configure and run the crew +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True +) + +try: + result = crew.kickoff() +finally: + maxim.cleanup() # Ensure cleanup happens even if errors occur +``` + + +That's it\! All your CrewAI agent interactions will now be logged and available in your Maxim dashboard. + +Check this Google Colab Notebook for a quick reference - [Notebook](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing) + +## Viewing Your Traces + +After running your CrewAI application: + +1. Log in to your [Maxim Dashboard](https://app.getmaxim.ai/login) +2. Navigate to your repository +3. View detailed agent traces, including: + - Agent conversations + - Tool usage patterns + - Performance metrics + - Cost analytics + + + +## Troubleshooting + +### Common Issues + +- **No traces appearing**: Ensure your API key and repository ID are correct +- Ensure you've **`called instrument_crewai()`** **_before_** running your crew. This initializes logging hooks correctly. +- Set `debug=True` in your `instrument_crewai()` call to surface any internal errors: + + ```python + instrument_crewai(logger, debug=True) + ``` +- Configure your agents with `verbose=True` to capture detailed logs: + + ```python + agent = CrewAgent(..., verbose=True) + ``` +- Double-check that `instrument_crewai()` is called **before** creating or executing agents. This might be obvious, but it's a common oversight. + +## Resources + + + + Official CrewAI documentation + + + Official Maxim documentation + + + Maxim Github + + \ No newline at end of file diff --git a/docs/v1.15.1/en/observability/mlflow.mdx b/docs/v1.15.1/en/observability/mlflow.mdx new file mode 100644 index 000000000..321448477 --- /dev/null +++ b/docs/v1.15.1/en/observability/mlflow.mdx @@ -0,0 +1,207 @@ +--- +title: MLflow Integration +description: Quickly start monitoring your Agents with MLflow. +icon: bars-staggered +mode: "wide" +--- + +# MLflow Overview + +[MLflow](https://mlflow.org/) is an open-source platform to assist machine learning practitioners and teams in handling the complexities of the machine learning process. + +It provides a tracing feature that enhances LLM observability in your Generative AI applications by capturing detailed information about the execution of your application’s services. +Tracing provides a way to record the inputs, outputs, and metadata associated with each intermediate step of a request, enabling you to easily pinpoint the source of bugs and unexpected behaviors. + +![Overview of MLflow crewAI tracing usage](/images/mlflow-tracing.gif) + +### Features + +- **Tracing Dashboard**: Monitor activities of your crewAI agents with detailed dashboards that include inputs, outputs and metadata of spans. +- **Automated Tracing**: A fully automated integration with crewAI, which can be enabled by running `mlflow.crewai.autolog()`. +- **Manual Trace Instrumentation with minor efforts**: Customize trace instrumentation through MLflow's high-level fluent APIs such as decorators, function wrappers and context managers. +- **OpenTelemetry Compatibility**: MLflow Tracing supports exporting traces to an OpenTelemetry Collector, which can then be used to export traces to various backends such as Jaeger, Zipkin, and AWS X-Ray. +- **Package and Deploy Agents**: Package and deploy your crewAI agents to an inference server with a variety of deployment targets. +- **Securely Host LLMs**: Host multiple LLM from various providers in one unified endpoint through MFflow gateway. +- **Evaluation**: Evaluate your crewAI agents with a wide range of metrics using a convenient API `mlflow.evaluate()`. + +## Setup Instructions + + + + ```shell + # The crewAI integration is available in mlflow>=2.19.0 + pip install mlflow + ``` + + + ```shell + # This process is optional, but it is recommended to use MLflow tracking server for better visualization and broader features. + mlflow server + ``` + + + Add the following two lines to your application code: + + ```python + import mlflow + + mlflow.crewai.autolog() + + # Optional: Set a tracking URI and an experiment name if you have a tracking server + mlflow.set_tracking_uri("http://localhost:5000") + mlflow.set_experiment("CrewAI") + ``` + + Example Usage for tracing CrewAI Agents: + + ```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) + ``` + Refer to [MLflow Tracing Documentation](https://mlflow.org/docs/latest/llms/tracing/index.html) for more configurations and use cases. + + + Now traces for your crewAI agents are captured by MLflow. + Let's visit MLflow tracking server to view the traces and get insights into your Agents. + + Open `127.0.0.1:5000` on your browser to visit MLflow tracking server. + + MLflow tracing example with crewai + + + + diff --git a/docs/v1.15.1/en/observability/neatlogs.mdx b/docs/v1.15.1/en/observability/neatlogs.mdx new file mode 100644 index 000000000..24b17cfce --- /dev/null +++ b/docs/v1.15.1/en/observability/neatlogs.mdx @@ -0,0 +1,134 @@ +--- +title: Neatlogs Integration +description: Understand, debug, and share your CrewAI agent runs +icon: magnifying-glass-chart +mode: "wide" +--- + +# Introduction + +Neatlogs helps you **see what your agent did**, **why**, and **share it**. + +It captures every step: thoughts, tool calls, responses, evaluations. No raw logs. Just clear, structured traces. Great for debugging and collaboration. + +## Why use Neatlogs? + +CrewAI agents use multiple tools and reasoning steps. When something goes wrong, you need context — not just errors. + +Neatlogs lets you: + +- Follow the full decision path +- Add feedback directly on steps +- Chat with the trace using AI assistant +- Share runs publicly for feedback +- Turn insights into tasks + +All in one place. + +Manage your traces effortlessly + +![Traces](/images/neatlogs-1.png) +![Trace Response](/images/neatlogs-2.png) + +The best UX to view a CrewAI trace. Post comments anywhere you want. Use AI to debug. + +![Trace Details](/images/neatlogs-3.png) +![Ai Chat Bot With A Trace](/images/neatlogs-4.png) +![Comments Drawer](/images/neatlogs-5.png) + +## Core Features + +- **Trace Viewer**: Track thoughts, tools, and decisions in sequence +- **Inline Comments**: Tag teammates on any trace step +- **Feedback & Evaluation**: Mark outputs as correct or incorrect +- **Error Highlighting**: Automatic flagging of API/tool failures +- **Task Conversion**: Convert comments into assigned tasks +- **Ask the Trace (AI)**: Chat with your trace using Neatlogs AI bot +- **Public Sharing**: Publish trace links to your community + +## Quick Setup with CrewAI + + + + Visit [neatlogs.com](https://neatlogs.com/?utm_source=crewAI-docs), create a project, copy the API key. + + + ```bash + pip install neatlogs + ``` + (Latest version 0.8.0, Python 3.8+; MIT license) + + + Before starting Crew agents, add: + + ```python + import neatlogs + neatlogs.init("YOUR_PROJECT_API_KEY") + ``` + + Agents run as usual. Neatlogs captures everything automatically. + + + + + + +## Under the Hood + +According to GitHub, Neatlogs: + +- Captures thoughts, tool calls, responses, errors, and token stats +- Supports AI-powered task generation and robust evaluation workflows + +All with just two lines of code. + + + +## Watch It Work + +### 🔍 Full Demo (4 min) + + + +### ⚙️ CrewAI Integration (30 s) + + + + + +## Links & Support + +- 📘 [Neatlogs Docs](https://docs.neatlogs.com/) +- 🔐 [Dashboard & API Key](https://app.neatlogs.com/) +- 🐦 [Follow on Twitter](https://twitter.com/neatlogs) +- 📧 Contact: hello@neatlogs.com +- 🛠 [GitHub SDK](https://github.com/NeatLogs/neatlogs) + + + +## TL;DR + +With just: + +```bash +pip install neatlogs + +import neatlogs +neatlogs.init("YOUR_API_KEY") + +You can now capture, understand, share, and act on your CrewAI agent runs in seconds. +No setup overhead. Full trace transparency. Full team collaboration. +``` diff --git a/docs/v1.15.1/en/observability/openlit.mdx b/docs/v1.15.1/en/observability/openlit.mdx new file mode 100644 index 000000000..17e083152 --- /dev/null +++ b/docs/v1.15.1/en/observability/openlit.mdx @@ -0,0 +1,182 @@ +--- +title: OpenLIT Integration +description: Quickly start monitoring your Agents in just a single line of code with OpenTelemetry. +icon: magnifying-glass-chart +mode: "wide" +--- + +# OpenLIT Overview + +[OpenLIT](https://github.com/openlit/openlit?src=crewai-docs) is an open-source tool that makes it simple to monitor the performance of AI agents, LLMs, VectorDBs, and GPUs with just **one** line of code. + +It provides OpenTelemetry-native tracing and metrics to track important parameters like cost, latency, interactions and task sequences. +This setup enables you to track hyperparameters and monitor for performance issues, helping you find ways to enhance and fine-tune your agents over time. + + + Overview Agent usage including cost and tokens + Overview of agent otel traces and metrics + Overview of agent traces in details + + +### Features + +- **Analytics Dashboard**: Monitor your Agents health and performance with detailed dashboards that track metrics, costs, and user interactions. +- **OpenTelemetry-native Observability SDK**: Vendor-neutral SDKs to send traces and metrics to your existing observability tools like Grafana, DataDog and more. +- **Cost Tracking for Custom and Fine-Tuned Models**: Tailor cost estimations for specific models using custom pricing files for precise budgeting. +- **Exceptions Monitoring Dashboard**: Quickly spot and resolve issues by tracking common exceptions and errors with a monitoring dashboard. +- **Compliance and Security**: Detect potential threats such as profanity and PII leaks. +- **Prompt Injection Detection**: Identify potential code injection and secret leaks. +- **API Keys and Secrets Management**: Securely handle your LLM API keys and secrets centrally, avoiding insecure practices. +- **Prompt Management**: Manage and version Agent prompts using PromptHub for consistent and easy access across Agents. +- **Model Playground** Test and compare different models for your CrewAI agents before deployment. + +## Setup Instructions + + + + + + ```shell + git clone git@github.com:openlit/openlit.git + ``` + + + From the root directory of the [OpenLIT Repo](https://github.com/openlit/openlit), Run the below command: + ```shell + docker compose up -d + ``` + + + + + ```shell + pip install openlit + ``` + + + Add the following two lines to your application code: + + + ```python + import openlit + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + ``` + + Example Usage for monitoring a CrewAI Agent: + + ```python + from crewai import Agent, Task, Crew, Process + import openlit + + openlit.init(disable_metrics=True) + # 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, + llm='command-r' + ) + + + # 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, + llm='command-r' + ) + + # Instantiate your crew with a custom manager + crew = Crew( + agents=[researcher], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, + ) + + # Start the crew's work + result = crew.kickoff() + + print(result) + ``` + + + + Add the following two lines to your application code: + ```python + import openlit + + openlit.init() + ``` + + Run the following command to configure the OTEL export endpoint: + ```shell + export OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318" + ``` + + Example Usage for monitoring a CrewAI Async Agent: + + ```python + import asyncio + from crewai import Crew, Agent, Task + import openlit + + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + + # 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, + llm="command-r" + ) + + # 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="5 bullet points, each with a paragraph and accompanying notes.", + ) + + # 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()) + ``` + + + Refer to OpenLIT [Python SDK repository](https://github.com/openlit/openlit/tree/main/sdk/python) for more advanced configurations and use cases. + + + With the Agent Observability data now being collected and sent to OpenLIT, the next step is to visualize and analyze this data to get insights into your Agent's performance, behavior, and identify areas of improvement. + + Just head over to OpenLIT at `127.0.0.1:3000` on your browser to start exploring. You can login using the default credentials + - **Email**: `user@openlit.io` + - **Password**: `openlituser` + + + Overview Agent usage including cost and tokens + Overview of agent otel traces and metrics + + + + + diff --git a/docs/v1.15.1/en/observability/opik.mdx b/docs/v1.15.1/en/observability/opik.mdx new file mode 100644 index 000000000..90af97cc7 --- /dev/null +++ b/docs/v1.15.1/en/observability/opik.mdx @@ -0,0 +1,130 @@ +--- +title: Opik Integration +description: Learn how to use Comet Opik to debug, evaluate, and monitor your CrewAI applications with comprehensive tracing, automated evaluations, and production-ready dashboards. +icon: meteor +mode: "wide" +--- + +# Opik Overview + +With [Comet Opik](https://www.comet.com/docs/opik/), debug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards. + + + Opik agent monitoring example with CrewAI + + +Opik provides comprehensive support for every stage of your CrewAI application development: + +- **Log Traces and Spans**: Automatically track LLM calls and application logic to debug and analyze development and production systems. Manually or programmatically annotate, view, and compare responses across projects. +- **Evaluate Your LLM Application's Performance**: Evaluate against a custom test set and run built-in evaluation metrics or define your own metrics in the SDK or UI. +- **Test Within Your CI/CD Pipeline**: Establish reliable performance baselines with Opik's LLM unit tests, built on PyTest. Run online evaluations for continuous monitoring in production. +- **Monitor & Analyze Production Data**: Understand your models' performance on unseen data in production and generate datasets for new dev iterations. + +## Setup +Comet provides a hosted version of the Opik platform, or you can run the platform locally. + +To use the hosted version, simply [create a free Comet account](https://www.comet.com/signup?utm_medium=github&utm_source=crewai_docs) and grab you API Key. + +To run the Opik platform locally, see our [installation guide](https://www.comet.com/docs/opik/self-host/overview/) for more information. + +For this guide we will use CrewAI’s quickstart example. + + + + ```shell + pip install crewai crewai-tools opik --upgrade + ``` + + + ```python + import opik + opik.configure(use_local=False) + ``` + + + First, we set up our API keys for our LLM-provider as environment variables: + + ```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: ") + ``` + + + The first step is to create our project. We will use an example from CrewAI’s documentation: + + ```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, + ) + + ``` + + Now we can import Opik’s tracker and run our 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) + ``` + After running your CrewAI application, visit the Opik app to view: + - LLM traces, spans, and their metadata + - Agent interactions and task execution flow + - Performance metrics like latency and token usage + - Evaluation metrics (built-in or custom) + + + +## Resources + +- [🦉 Opik Documentation](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/) diff --git a/docs/v1.15.1/en/observability/overview.mdx b/docs/v1.15.1/en/observability/overview.mdx new file mode 100644 index 000000000..171a922f2 --- /dev/null +++ b/docs/v1.15.1/en/observability/overview.mdx @@ -0,0 +1,120 @@ +--- +title: "Overview" +description: "Monitor, evaluate, and optimize your CrewAI agents with comprehensive observability tools" +icon: "face-smile" +mode: "wide" +--- + +## Observability for CrewAI + +Observability is crucial for understanding how your CrewAI agents perform, identifying bottlenecks, and ensuring reliable operation in production environments. This section covers various tools and platforms that provide monitoring, evaluation, and optimization capabilities for your agent workflows. + +## Why Observability Matters + +- **Performance Monitoring**: Track agent execution times, token usage, and resource consumption +- **Quality Assurance**: Evaluate output quality and consistency across different scenarios +- **Debugging**: Identify and resolve issues in agent behavior and task execution +- **Cost Management**: Monitor LLM API usage and associated costs +- **Continuous Improvement**: Gather insights to optimize agent performance over time + +## Available Observability Tools + +### Monitoring & Tracing Platforms + + + + + End-to-end tracing for CrewAI workflows with automatic agent interaction capture. + + + + 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. + + + +### Evaluation & Quality Assurance + + + + Comprehensive evaluation platform for LLM outputs and agent behaviors. + + + +## Key Observability Metrics + +### Performance Metrics +- **Execution Time**: How long agents take to complete tasks +- **Token Usage**: Input/output tokens consumed by LLM calls +- **API Latency**: Response times from external services +- **Success Rate**: Percentage of successfully completed tasks + +### Quality Metrics +- **Output Accuracy**: Correctness of agent responses +- **Consistency**: Reliability across similar inputs +- **Relevance**: How well outputs match expected results +- **Safety**: Compliance with content policies and guidelines + +### Cost Metrics +- **API Costs**: Expenses from LLM provider usage +- **Resource Utilization**: Compute and memory consumption +- **Cost per Task**: Economic efficiency of agent operations +- **Budget Tracking**: Monitoring against spending limits + +## Getting Started + +1. **Choose Your Tools**: Select observability platforms that match your needs +2. **Instrument Your Code**: Add monitoring to your CrewAI applications +3. **Set Up Dashboards**: Configure visualizations for key metrics +4. **Define Alerts**: Create notifications for important events +5. **Establish Baselines**: Measure initial performance for comparison +6. **Iterate and Improve**: Use insights to optimize your agents + +## Best Practices + +### Development Phase +- Use detailed tracing to understand agent behavior +- Implement evaluation metrics early in development +- Monitor resource usage during testing +- Set up automated quality checks + +### Production Phase +- Implement comprehensive monitoring and alerting +- Track performance trends over time +- Monitor for anomalies and degradation +- Maintain cost visibility and control + +### Continuous Improvement +- Regular performance reviews and optimization +- A/B testing of different agent configurations +- 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. diff --git a/docs/v1.15.1/en/observability/patronus-evaluation.mdx b/docs/v1.15.1/en/observability/patronus-evaluation.mdx new file mode 100644 index 000000000..0326fede3 --- /dev/null +++ b/docs/v1.15.1/en/observability/patronus-evaluation.mdx @@ -0,0 +1,206 @@ +--- +title: Patronus AI Evaluation +description: Monitor and evaluate CrewAI agent performance using Patronus AI's comprehensive evaluation platform for LLM outputs and agent behaviors. +icon: shield-check +mode: "wide" +--- + +# Patronus AI Evaluation + +## Overview + +[Patronus AI](https://patronus.ai) provides comprehensive evaluation and monitoring capabilities for CrewAI agents, enabling you to assess model outputs, agent behaviors, and overall system performance. This integration allows you to implement continuous evaluation workflows that help maintain quality and reliability in production environments. + +## Key Features + +- **Automated Evaluation**: Real-time assessment of agent outputs and behaviors +- **Custom Criteria**: Define specific evaluation criteria tailored to your use cases +- **Performance Monitoring**: Track agent performance metrics over time +- **Quality Assurance**: Ensure consistent output quality across different scenarios +- **Safety & Compliance**: Monitor for potential issues and policy violations + +## Evaluation Tools + +Patronus provides three main evaluation tools for different use cases: + +1. **PatronusEvalTool**: Allows agents to select the most appropriate evaluator and criteria for the evaluation task. +2. **PatronusPredefinedCriteriaEvalTool**: Uses predefined evaluator and criteria specified by the user. +3. **PatronusLocalEvaluatorTool**: Uses custom function evaluators defined by the user. + +## Installation + +To use these tools, you need to install the Patronus package: + +```shell +uv add patronus +``` + +You'll also need to set up your Patronus API key as an environment variable: + +```shell +export PATRONUS_API_KEY="your_patronus_api_key" +``` + +## Steps to Get Started + +To effectively use the Patronus evaluation tools, follow these steps: + +1. **Install Patronus**: Install the Patronus package using the command above. +2. **Set Up API Key**: Set your Patronus API key as an environment variable. +3. **Choose the Right Tool**: Select the appropriate Patronus evaluation tool based on your needs. +4. **Configure the Tool**: Configure the tool with the necessary parameters. + +## Examples + +### Using PatronusEvalTool + +The following example demonstrates how to use the `PatronusEvalTool`, which allows agents to select the most appropriate evaluator and criteria: + +```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() +``` + +### Using PatronusPredefinedCriteriaEvalTool + +The following example demonstrates how to use the `PatronusPredefinedCriteriaEvalTool`, which uses predefined evaluator and criteria: + +```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() +``` + +### Using PatronusLocalEvaluatorTool + +The following example demonstrates how to use the `PatronusLocalEvaluatorTool`, which uses custom function evaluators: + +```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() +``` + +## Parameters + +### PatronusEvalTool + +The `PatronusEvalTool` does not require any parameters during initialization. It automatically fetches available evaluators and criteria from the Patronus API. + +### PatronusPredefinedCriteriaEvalTool + +The `PatronusPredefinedCriteriaEvalTool` accepts the following parameters during initialization: + +- **evaluators**: Required. A list of dictionaries containing the evaluator and criteria to use. For example: `[{"evaluator": "judge", "criteria": "contains-code"}]`. + +### PatronusLocalEvaluatorTool + +The `PatronusLocalEvaluatorTool` accepts the following parameters during initialization: + +- **patronus_client**: Required. The Patronus client instance. +- **evaluator**: Optional. The name of the registered local evaluator to use. Default is an empty string. +- **evaluated_model_gold_answer**: Optional. The gold answer to use for evaluation. Default is an empty string. + +## Usage + +When using the Patronus evaluation tools, you provide the model input, output, and context, and the tool returns the evaluation results from the Patronus API. + +For the `PatronusEvalTool` and `PatronusPredefinedCriteriaEvalTool`, the following parameters are required when calling the tool: + +- **evaluated_model_input**: The agent's task description in simple text. +- **evaluated_model_output**: The agent's output of the task. +- **evaluated_model_retrieved_context**: The agent's context. + +For the `PatronusLocalEvaluatorTool`, the same parameters are required, but the evaluator and gold answer are specified during initialization. + +## Conclusion + +The Patronus evaluation tools provide a powerful way to evaluate and score model inputs and outputs using the Patronus AI platform. By enabling agents to evaluate their own outputs or the outputs of other agents, these tools can help improve the quality and reliability of CrewAI workflows. \ No newline at end of file diff --git a/docs/v1.15.1/en/observability/portkey.mdx b/docs/v1.15.1/en/observability/portkey.mdx new file mode 100644 index 000000000..851cd358a --- /dev/null +++ b/docs/v1.15.1/en/observability/portkey.mdx @@ -0,0 +1,823 @@ +--- +title: Portkey Integration +description: How to use Portkey with CrewAI +icon: key +mode: "wide" +--- + +Portkey CrewAI Header Image + + + +## Introduction + +Portkey enhances CrewAI with production-readiness features, turning your experimental agent crews into robust systems by providing: + +- **Complete observability** of every agent step, tool use, and interaction +- **Built-in reliability** with fallbacks, retries, and load balancing +- **Cost tracking and optimization** to manage your AI spend +- **Access to 200+ LLMs** through a single integration +- **Guardrails** to keep agent behavior safe and compliant +- **Version-controlled prompts** for consistent agent performance + + +### Installation & Setup + + + +```bash +pip install -U crewai portkey-ai +``` + + + +Create a Portkey API key with optional budget/rate limits from the [Portkey dashboard](https://app.portkey.ai/). You can also attach configurations for reliability, caching, and more to this key. More on this later. + + + +The integration is simple - you just need to update the LLM configuration in your CrewAI setup: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create an LLM instance with Portkey integration +gpt_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", # We are using a Virtual key, so this is a placeholder + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_LLM_VIRTUAL_KEY", + trace_id="unique-trace-id", # Optional, for request tracing + ) +) + +#Use them in your Crew Agents like this: + + @agent + def lead_market_analyst(self) -> Agent: + return Agent( + config=self.agents_config['lead_market_analyst'], + verbose=True, + memory=False, + llm=gpt_llm + ) + +``` + + +**What are Virtual Keys?** Virtual keys in Portkey securely store your LLM provider API keys (OpenAI, Anthropic, etc.) in an encrypted vault. They allow for easier key rotation and budget management. [Learn more about virtual keys here](https://portkey.ai/docs/product/ai-gateway/virtual-keys). + + + + +## Production Features + +### 1. Enhanced Observability + +Portkey provides comprehensive observability for your CrewAI agents, helping you understand exactly what's happening during each execution. + + + + + + + +Traces provide a hierarchical view of your crew's execution, showing the sequence of LLM calls, tool invocations, and state transitions. + +```python +# Add trace_id to enable hierarchical tracing in 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" # Add unique trace ID + ) +) +``` + + + + + + + +Portkey logs every interaction with LLMs, including: + +- Complete request and response payloads +- Latency and token usage metrics +- Cost calculations +- Tool calls and function executions + +All logs can be filtered by metadata, trace IDs, models, and more, making it easy to debug specific crew runs. + + + + + + + +Portkey provides built-in dashboards that help you: + +- Track cost and token usage across all crew runs +- Analyze performance metrics like latency and success rates +- Identify bottlenecks in your agent workflows +- Compare different crew configurations and LLMs + +You can filter and segment all metrics by custom metadata to analyze specific crew types, user groups, or use cases. + + + + + Analytics with metadata filters + + +Add custom metadata to your CrewAI LLM configuration to enable powerful filtering and segmentation: + +```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", # Special _user field for user analytics + "request_source": "mobile_app" + } + ) +) +``` + +This metadata can be used to filter logs, traces, and metrics on the Portkey dashboard, allowing you to analyze specific crew runs, users, or environments. + + + +### 2. Reliability - Keep Your Crews Running Smoothly + +When running crews in production, things can go wrong - API rate limits, network issues, or provider outages. Portkey's reliability features ensure your agents keep running smoothly even when problems occur. + +It's simple to enable fallback in your CrewAI setup by using a Portkey Config: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with fallback configuration +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 this LLM configuration with your agents +``` + +This configuration will automatically try Claude if the GPT-4o request fails, ensuring your crew can continue operating. + + + + Handles temporary failures automatically. If an LLM call fails, Portkey will retry the same request for the specified number of times - perfect for rate limits or network blips. + + + Prevent your agents from hanging. Set timeouts to ensure you get responses (or can fail gracefully) within your required timeframes. + + + Send different requests to different providers. Route complex reasoning to GPT-4, creative tasks to Claude, and quick responses to Gemini based on your needs. + + + Keep running even if your primary provider fails. Automatically switch to backup providers to maintain availability. + + + Spread requests across multiple API keys or providers. Great for high-volume crew operations and staying within rate limits. + + + +### 3. Prompting in CrewAI + +Portkey's Prompt Engineering Studio helps you create, manage, and optimize the prompts used in your CrewAI agents. Instead of hardcoding prompts or instructions, use Portkey's prompt rendering API to dynamically fetch and apply your versioned prompts. + + +![Prompt Playground Interface](https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/refs/heads/main/CrewAI%20Portkey%20Docs.webp) + + + + +Prompt Playground is a place to compare, test and deploy perfect prompts for your AI application. It's where you experiment with different models, test variables, compare outputs, and refine your prompt engineering strategy before deploying to production. It allows you to: + +1. Iteratively develop prompts before using them in your agents +2. Test prompts with different variables and models +3. Compare outputs between different prompt versions +4. Collaborate with team members on prompt development + +This visual environment makes it easier to craft effective prompts for each step in your CrewAI agents' workflow. + + + +The Prompt Render API retrieves your prompt templates with all parameters configured: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL, Portkey + +# Initialize Portkey admin client +portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY") + +# Retrieve prompt using the 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"] + + +# Set up LLM with Portkey integration +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" + ) +) + +# Create agent using the rendered prompt +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory=backstory_agent, # Use the rendered prompt + verbose=True, + llm=portkey_llm +) +``` + + + +You can: +- Create multiple versions of the same prompt +- Compare performance between versions +- Roll back to previous versions if needed +- Specify which version to use in your code: + +```python +# Use a specific prompt version +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID@version_number", + variables={ + "agent_role": "Senior Research Scientist", + "agent_goal": "Discover groundbreaking insights" + } +) +``` + + + +Portkey prompts use Mustache-style templating for easy variable substitution: + +``` +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}}. +``` + +When rendering, simply pass the variables: + +```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" + } +) +``` + + + + + Learn more about Portkey's prompt management features + + +### 4. Guardrails for Safe Crews + +Guardrails ensure your CrewAI agents operate safely and respond appropriately in all situations. + +**Why Use Guardrails?** + +CrewAI agents can experience various failure modes: +- Generating harmful or inappropriate content +- Leaking sensitive information like PII +- Hallucinating incorrect information +- Generating outputs in incorrect formats + +Portkey's guardrails add protections for both inputs and outputs. + +**Implementing Guardrails** + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with 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"] + } + ) +) + +# Create agent with guardrailed LLM +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 +) +``` + +Portkey's guardrails can: +- Detect and redact PII in both inputs and outputs +- Filter harmful or inappropriate content +- Validate response formats against schemas +- Check for hallucinations against ground truth +- Apply custom business logic and rules + + + Explore Portkey's guardrail features to enhance agent safety + + +### 5. User Tracking with Metadata + +Track individual users through your CrewAI agents using Portkey's metadata system. + +**What is Metadata in Portkey?** + +Metadata allows you to associate custom data with each request, enabling filtering, segmentation, and analytics. The special `_user` field is specifically designed for user tracking. + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with user tracking +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", # Special _user field for user analytics + "user_tier": "premium", + "user_company": "Acme Corp", + "session_id": "abc-123" + } + ) +) + +# Create agent with tracked LLM +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 +) +``` + +**Filter Analytics by User** + +With metadata in place, you can filter analytics by user and analyze performance metrics on a per-user basis: + + + + + +This enables: +- Per-user cost tracking and budgeting +- Personalized user analytics +- Team or organization-level metrics +- Environment-specific monitoring (staging vs. production) + + + Explore how to use custom metadata to enhance your analytics + + +### 6. Caching for Efficient Crews + +Implement caching to make your CrewAI agents more efficient and cost-effective: + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with simple caching +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" + } + } + ) +) + +# Create agent with cached LLM +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 +) +``` + +Simple caching performs exact matches on input prompts, caching identical requests to avoid redundant model executions. + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with semantic caching +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" + } + } + ) +) + +# Create agent with semantically cached LLM +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 +) +``` + +Semantic caching considers the contextual similarity between input requests, caching responses for semantically similar inputs. + + + +### 7. Model Interoperability + +CrewAI supports multiple LLM providers, and Portkey extends this capability by providing access to over 200 LLMs through a unified interface. You can easily switch between different models without changing your core agent logic: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Set up LLMs with different providers +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" + ) +) + +# Choose which LLM to use for each agent based on your needs +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 for Anthropic +) +``` + +Portkey provides access to LLMs from providers including: + +- 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.) +- Local/Private Models + + + See the full list of LLM providers supported by Portkey + + +## Set Up Enterprise Governance for CrewAI + +**Why Enterprise Governance?** +If you are using CrewAI inside your organization, you need to consider several governance aspects: +- **Cost Management**: Controlling and tracking AI spending across teams +- **Access Control**: Managing which teams can use specific models +- **Usage Analytics**: Understanding how AI is being used across the organization +- **Security & Compliance**: Maintaining enterprise security standards +- **Reliability**: Ensuring consistent service across all users + +Portkey adds a comprehensive governance layer to address these enterprise needs. Let's implement these controls step by step. + + + +Virtual Keys are Portkey's secure way to manage your LLM provider API keys. They provide essential controls like: +- Budget limits for API usage +- Rate limiting capabilities +- Secure API key storage + +To create a virtual key: +Go to [Virtual Keys](https://app.portkey.ai/virtual-keys) in the Portkey App. Save and copy the virtual key ID + + + + + + +Save your virtual key ID - you'll need it for the next step. + + + + +Configs in Portkey define how your requests are routed, with features like advanced routing, fallbacks, and retries. + +To create your config: +1. Go to [Configs](https://app.portkey.ai/configs) in Portkey dashboard +2. Create new config with: + ```json + { + "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1", + "override_params": { + "model": "gpt-4o" // Your preferred model name + } + } + ``` +3. Save and note the Config name for the next step + + + + + + + + +Now create a Portkey API key and attach the config you created in Step 2: + +1. Go to [API Keys](https://app.portkey.ai/api-keys) in Portkey and Create new API key +2. Select your config from `Step 2` +3. Generate and save your API key + + + + + + + + +After setting up your Portkey API key with the attached config, connect it to your CrewAI agents: + +```python +from crewai import Agent, LLM +from portkey_ai import PORTKEY_GATEWAY_URL + +# Configure LLM with your API key +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="YOUR_PORTKEY_API_KEY" +) + +# Create agent with Portkey-enabled LLM +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 +) +``` + + + + + +### Step 1: Implement Budget Controls & Rate Limits + +Virtual Keys enable granular control over LLM access at the team/department level. This helps you: +- Set up [budget limits](https://portkey.ai/docs/product/ai-gateway/virtual-keys/budget-limits) +- Prevent unexpected usage spikes using Rate limits +- Track departmental spending + +#### Setting Up Department-Specific Controls: +1. Navigate to [Virtual Keys](https://app.portkey.ai/virtual-keys) in Portkey dashboard +2. Create new Virtual Key for each department with budget limits and rate limits +3. Configure department-specific limits + + + + + + + +### Step 2: Define Model Access Rules + +As your AI usage scales, controlling which teams can access specific models becomes crucial. Portkey Configs provide this control layer with features like: + +#### Access Control Features: +- **Model Restrictions**: Limit access to specific models +- **Data Protection**: Implement guardrails for sensitive data +- **Reliability Controls**: Add fallbacks and retry logic + +#### Example Configuration: +Here's a basic configuration to route requests to OpenAI, specifically using GPT-4o: + +```json +{ + "strategy": { + "mode": "single" + }, + "targets": [ + { + "virtual_key": "YOUR_OPENAI_VIRTUAL_KEY", + "override_params": { + "model": "gpt-4o" + } + } + ] +} +``` + + Create your config on the [Configs page](https://app.portkey.ai/configs) in your Portkey dashboard. + + + Configs can be updated anytime to adjust controls without affecting running applications. + + + + + ### Step 3: Implement Access Controls + + Create User-specific API keys that automatically: + - Track usage per user/team with the help of virtual keys + - Apply appropriate configs to route requests + - Collect relevant metadata to filter logs + - Enforce access permissions + + Create API keys through the [Portkey App](https://app.portkey.ai/) + + Example using 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"] + ) + ``` + + For detailed key management instructions, see the [Portkey documentation](https://portkey.ai/docs). + + + + ### Step 4: Deploy & Monitor + After distributing API keys to your team members, your enterprise-ready CrewAI setup is ready to go. Each team member can now use their designated API keys with appropriate access levels and budget controls. + + Monitor usage in Portkey dashboard: + - Cost tracking by department + - Model usage patterns + - Request volumes + - Error rates + + + + + +### Enterprise Features Now Available +**Your CrewAI integration now has:** +- Departmental budget controls +- Model access governance +- Usage tracking & attribution +- Security guardrails +- Reliability features + + +## Frequently Asked Questions + + + + Portkey adds production-readiness to CrewAI through comprehensive observability (traces, logs, metrics), reliability features (fallbacks, retries, caching), and access to 200+ LLMs through a unified interface. This makes it easier to debug, optimize, and scale your agent applications. + + + + Yes! Portkey integrates seamlessly with existing CrewAI applications. You just need to update your LLM configuration code with the Portkey-enabled version. The rest of your agent and crew code remains unchanged. + + + + Portkey supports all CrewAI features, including agents, tools, human-in-the-loop workflows, and all task process types (sequential, hierarchical, etc.). It adds observability and reliability without limiting any of the framework's functionality. + + + + Yes, Portkey allows you to use a consistent `trace_id` across multiple agents in a crew to track the entire workflow. This is especially useful for complex crews where you want to understand the full execution path across multiple agents. + + + + Portkey allows you to add custom metadata to your LLM configuration, which you can then use for filtering. Add fields like `crew_name`, `crew_type`, or `session_id` to easily find and analyze specific crew executions. + + + + Yes! Portkey uses your own API keys for the various LLM providers. It securely stores them as virtual keys, allowing you to easily manage and rotate keys without changing your code. + + + + +## Resources + + + +

Official CrewAI documentation

+ + +

Get personalized guidance on implementing this integration

+ + diff --git a/docs/v1.15.1/en/observability/tracing.mdx b/docs/v1.15.1/en/observability/tracing.mdx new file mode 100644 index 000000000..ce620946a --- /dev/null +++ b/docs/v1.15.1/en/observability/tracing.mdx @@ -0,0 +1,214 @@ +--- +title: CrewAI Tracing +description: Built-in tracing for CrewAI Crews and Flows with the CrewAI AMP platform +icon: magnifying-glass-chart +mode: "wide" +--- + +# CrewAI Built-in Tracing + +CrewAI provides built-in tracing capabilities that allow you to monitor and debug your Crews and Flows in real-time. This guide demonstrates how to enable tracing for both **Crews** and **Flows** using CrewAI's integrated observability platform. + +> **What is CrewAI Tracing?** CrewAI's built-in tracing provides comprehensive observability for your AI agents, including agent decisions, task execution timelines, tool usage, and LLM calls - all accessible through the [CrewAI AMP platform](https://app.crewai.com). + +![CrewAI Tracing Interface](/images/crewai-tracing.png) + +## Prerequisites + +Before you can use CrewAI tracing, you need: + +1. **CrewAI AMP Account**: Sign up for a free account at [app.crewai.com](https://app.crewai.com) +2. **CLI Authentication**: Use the CrewAI CLI to authenticate your local environment + +```bash +crewai login +``` + +## Setup Instructions + +### Step 1: Create Your CrewAI AMP Account + +Visit [app.crewai.com](https://app.crewai.com) and create your free account. This will give you access to the CrewAI AMP platform where you can view traces, metrics, and manage your crews. + +### Step 2: Install CrewAI CLI and Authenticate + +If you haven't already, install CrewAI with the CLI tools: + +```bash +uv add 'crewai[tools]' +``` + +Then authenticate your CLI with your CrewAI AMP account: + +```bash +crewai login +``` + +This command will: + +1. Open your browser to the authentication page +2. Prompt you to enter a device code +3. Authenticate your local environment with your CrewAI AMP account +4. Enable tracing capabilities for your local development + +### Step 3: Enable Tracing in Your Crew + +You can enable tracing for your Crew by setting the `tracing` parameter to `True`: + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +# Define your agents +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, + tools=[SerperDevTool()], +) + +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, +) + +# Create tasks for your agents +research_task = 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, +) + +writing_task = 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.""", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Enable tracing in your crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + tracing=True, # Enable built-in tracing + verbose=True +) + +# Execute your crew +result = crew.kickoff() +``` + +### Step 4: Enable Tracing in Your Flow + +Similarly, you can enable tracing for CrewAI Flows: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class ExampleFlow(Flow[ExampleState]): + def __init__(self): + super().__init__(tracing=True) # Enable tracing for the flow + + @start() + def first_method(self): + print("Starting the flow") + self.state.counter = 1 + self.state.message = "Flow started" + return "continue" + + @listen("continue") + def second_method(self): + print("Continuing the flow") + self.state.counter += 1 + self.state.message = "Flow continued" + return "finish" + + @listen("finish") + def final_method(self): + print("Finishing the flow") + self.state.counter += 1 + self.state.message = "Flow completed" + +# Create and run the flow with tracing enabled +flow = ExampleFlow(tracing=True) +result = flow.kickoff() +``` + +### Step 5: View Traces in the CrewAI AMP Dashboard + +After running the crew or flow, you can view the traces generated by your CrewAI application in the CrewAI AMP dashboard. You should see detailed steps of the agent interactions, tool usages, and LLM calls. +Just click on the link below to view the traces or head over to the traces tab in the dashboard [here](https://app.crewai.com/crewai_plus/trace_batches) +![CrewAI Tracing Interface](/images/view-traces.png) + +### Alternative: Environment Variable Configuration + +You can also enable tracing globally by setting an environment variable: + +```bash +export CREWAI_TRACING_ENABLED=true +``` + +Or add it to your `.env` file: + +```env +CREWAI_TRACING_ENABLED=true +``` + +When this environment variable is set, all Crews and Flows will automatically have tracing enabled, even without explicitly setting `tracing=True`. + +## Viewing Your Traces + +### Access the CrewAI AMP Dashboard + +1. Visit [app.crewai.com](https://app.crewai.com) and log in to your account +2. Navigate to your project dashboard +3. Click on the **Traces** tab to view execution details + +### What You'll See in Traces + +CrewAI tracing provides comprehensive visibility into: + +- **Agent Decisions**: See how agents reason through tasks and make decisions +- **Task Execution Timeline**: Visual representation of task sequences and dependencies +- **Tool Usage**: Monitor which tools are called and their results +- **LLM Calls**: Track all language model interactions, including prompts and responses +- **Performance Metrics**: Execution times, token usage, and costs +- **Error Tracking**: Detailed error information and stack traces + +### Trace Features + +- **Execution Timeline**: Click through different stages of execution +- **Detailed Logs**: Access comprehensive logs for debugging +- **Performance Analytics**: Analyze execution patterns and optimize performance +- **Export Capabilities**: Download traces for further analysis + +### Authentication Issues + +If you encounter authentication problems: + +1. Ensure you're logged in: `crewai login` +2. Check your internet connection +3. Verify your account at [app.crewai.com](https://app.crewai.com) + +### Traces Not Appearing + +If traces aren't showing up in the dashboard: + +1. Confirm `tracing=True` is set in your Crew/Flow +2. Check that `CREWAI_TRACING_ENABLED=true` if using environment variables +3. Ensure you're authenticated with `crewai login` +4. Verify your crew/flow is actually executing diff --git a/docs/v1.15.1/en/observability/truefoundry.mdx b/docs/v1.15.1/en/observability/truefoundry.mdx new file mode 100644 index 000000000..bc41cc624 --- /dev/null +++ b/docs/v1.15.1/en/observability/truefoundry.mdx @@ -0,0 +1,147 @@ +--- +title: TrueFoundry Integration +icon: chart-line +mode: "wide" +--- + +TrueFoundry provides an enterprise-ready [AI Gateway](https://www.truefoundry.com/ai-gateway) which can integrate with agentic frameworks like CrewAI and provides governance and observability for your AI Applications. TrueFoundry AI Gateway serves as a unified interface for LLM access, providing: + +- **Unified API Access**: Connect to 250+ LLMs (OpenAI, Claude, Gemini, Groq, Mistral) through one API +- **Low Latency**: Sub-3ms internal latency with intelligent routing and load balancing +- **Enterprise Security**: SOC 2, HIPAA, GDPR compliance with RBAC and audit logging +- **Quota and cost management**: Token-based quotas, rate limiting, and comprehensive usage tracking +- **Observability**: Full request/response logging, metrics, and traces with customizable retention + +## How TrueFoundry Integrates with CrewAI + + +### Installation & Setup + + + +```bash +pip install crewai +``` + + + +1. Sign up for a [TrueFoundry account](https://www.truefoundry.com/register) +2. Follow the steps here in [Quick start](https://docs.truefoundry.com/gateway/quick-start) + + + +![TrueFoundry Code Configuration](/images/new-code-snippet.png) + +```python +from crewai import LLM + +# Create an LLM instance with TrueFoundry AI Gateway +truefoundry_llm = LLM( + model="openai-main/gpt-4o", # Similarly, you can call any model from any provider + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Use in your CrewAI agents +from crewai import Agent + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + llm=truefoundry_llm, + verbose=True + ) +``` + + + +### Complete CrewAI Example + +```python +from crewai import Agent, Task, Crew, LLM + +# Configure LLM with TrueFoundry +llm = LLM( + model="openai-main/gpt-4o", + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Create agents +researcher = Agent( + role='Research Analyst', + goal='Conduct detailed market research', + backstory='Expert market analyst with attention to detail', + llm=llm, + verbose=True +) + +writer = Agent( + role='Content Writer', + goal='Create comprehensive reports', + backstory='Experienced technical writer', + llm=llm, + verbose=True +) + +# Create tasks +research_task = Task( + description='Research AI market trends for 2024', + agent=researcher, + expected_output='Comprehensive research summary' +) + +writing_task = Task( + description='Create a market research report', + agent=writer, + expected_output='Well-structured report with insights', + context=[research_task] +) + +# Create and execute crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +result = crew.kickoff() +``` + +### Observability and Governance + +Monitor your CrewAI agents through TrueFoundry's metrics tab: +![TrueFoundry metrics](/images/gateway-metrics.png) + +With Truefoundry's AI gateway, you can monitor and analyze: + +- **Performance Metrics**: Track key latency metrics like Request Latency, Time to First Token (TTFS), and Inter-Token Latency (ITL) with P99, P90, and P50 percentiles +- **Cost and Token Usage**: Gain visibility into your application's costs with detailed breakdowns of input/output tokens and the associated expenses for each model +- **Usage Patterns**: Understand how your application is being used with detailed analytics on user activity, model distribution, and team-based usage +- **Rate limit and Load balancing**: You can set up rate limiting, load balancing and fallback for your models + +## Tracing + +For a more detailed understanding on tracing, please see [getting-started-tracing](https://docs.truefoundry.com/docs/tracing/tracing-getting-started).For tracing, you can add the Traceloop SDK: +For tracing, you can add the Traceloop SDK: + +```bash +pip install traceloop-sdk +``` + +```python +from traceloop.sdk import Traceloop + +# Initialize enhanced tracing +Traceloop.init( + api_endpoint="https://your-truefoundry-endpoint/api/tracing", + headers={ + "Authorization": f"Bearer {your_truefoundry_pat_token}", + "TFY-Tracing-Project": "your_project_name", + }, +) +``` + +This provides additional trace correlation across your entire CrewAI workflow. +![TrueFoundry CrewAI Tracing](/images/tracing_crewai.png) \ No newline at end of file diff --git a/docs/v1.15.1/en/observability/weave.mdx b/docs/v1.15.1/en/observability/weave.mdx new file mode 100644 index 000000000..2d4c4bf1d --- /dev/null +++ b/docs/v1.15.1/en/observability/weave.mdx @@ -0,0 +1,125 @@ +--- +title: Weave Integration +description: Learn how to use Weights & Biases (W&B) Weave to track, experiment with, evaluate, and improve your CrewAI applications. +icon: radar +mode: "wide" +--- + +# Weave Overview + +[Weights & Biases (W&B) Weave](https://weave-docs.wandb.ai/) is a framework for tracking, experimenting with, evaluating, deploying, and improving LLM-based applications. + +![Overview of W&B Weave CrewAI tracing usage](/images/weave-tracing.gif) + +Weave provides comprehensive support for every stage of your CrewAI application development: + +- **Tracing & Monitoring**: Automatically track LLM calls and application logic to debug and analyze production systems +- **Systematic Iteration**: Refine and iterate on prompts, datasets, and models +- **Evaluation**: Use custom or pre-built scorers to systematically assess and enhance agent performance +- **Guardrails**: Protect your agents with pre- and post-safeguards for content moderation and prompt safety + +Weave automatically captures traces for your CrewAI applications, enabling you to monitor and analyze your agents' performance, interactions, and execution flow. This helps you build better evaluation datasets and optimize your agent workflows. + +## Setup Instructions + + + + ```shell + pip install crewai weave + ``` + + + Sign up for a [Weights & Biases account](https://wandb.ai) if you haven't already. You'll need this to view your traces and metrics. + + + Add the following code to your application: + + ```python + import weave + + # Initialize Weave with your project name + weave.init(project_name="crewai_demo") + ``` + + After initialization, Weave will provide a URL where you can view your traces and metrics. + + + ```python + from crewai import Agent, Task, Crew, LLM, Process + + # Create an LLM with a temperature of 0 to ensure deterministic outputs + llm = LLM(model="gpt-4o", temperature=0) + + # Create agents + 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, + ) + + # Create tasks + 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 + ) + + # Create a crew + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential, + ) + + # Run the crew + result = crew.kickoff(inputs={"topic": "AI in material science"}) + print(result) + ``` + + + After running your CrewAI application, visit the Weave URL provided during initialization to view: + - LLM calls and their metadata + - Agent interactions and task execution flow + - Performance metrics like latency and token usage + - Any errors or issues that occurred during execution + + + Weave tracing example with CrewAI + + + + +## Features + +- Weave automatically captures all CrewAI operations: agent interactions and task executions; LLM calls with metadata and token usage; tool usage and results. +- The integration supports all CrewAI execution methods: `kickoff()`, `kickoff_for_each()`, `kickoff_async()`, and `kickoff_for_each_async()`. +- Automatic tracing of all [crewAI-tools](https://github.com/crewAIInc/crewAI-tools). +- Flow feature support with decorator patching (`@start`, `@listen`, `@router`, `@or_`, `@and_`). +- Track custom guardrails passed to CrewAI `Task` with `@weave.op()`. + +For detailed information on what's supported, visit the [Weave CrewAI documentation](https://weave-docs.wandb.ai/guides/integrations/crewai/#getting-started-with-flow). + +## Resources + +- [📘 Weave Documentation](https://weave-docs.wandb.ai) +- [📊 Example Weave x CrewAI dashboard](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) diff --git a/docs/v1.15.1/en/quickstart.mdx b/docs/v1.15.1/en/quickstart.mdx new file mode 100644 index 000000000..1b21a43a9 --- /dev/null +++ b/docs/v1.15.1/en/quickstart.mdx @@ -0,0 +1,260 @@ +--- +title: Quickstart +description: Build your first CrewAI Flow in minutes — orchestration, state, and an agent crew that produces a real report. +icon: rocket +mode: "wide" +--- + +### Watch: Building CrewAI Agents & Flows with Coding Agent Skills + +Install our coding agent skills (Claude Code, Codex, ...) to quickly get your coding agents up and running with CrewAI. + +You can install it with `npx skills add crewaiinc/skills` + + + +In this guide you will **create a Flow** that sets a research topic, runs a **crew with one agent** (a researcher using web search), and ends with a **markdown report** on disk. Flows are the recommended way to structure production apps: they own **state** and **execution order**, while **agents** do the work inside a crew step. + +If you have not installed CrewAI yet, follow the [installation guide](/en/installation) first. + +## Prerequisites + +- Python environment and the CrewAI CLI (see [installation](/en/installation)) +- An LLM configured with the right API keys — see [LLMs](/en/concepts/llms#setting-up-your-llm) +- A [Serper.dev](https://serper.dev/) API key (`SERPER_API_KEY`) for web search in this tutorial + +## Build your first Flow + + + + From your terminal, scaffold a Flow project (the folder name uses underscores, e.g. `latest_ai_flow`): + + + ```shell Terminal + crewai create flow latest-ai-flow + cd latest_ai_flow + ``` + + + This creates a Flow app under `src/latest_ai_flow/`, including a starter crew under `crews/content_crew/` that you will replace with a minimal **single-agent** research crew in the next steps. + + + + Create `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc` (create the `agents/` directory if needed). Variables like `{topic}` are filled from `crew.kickoff(inputs=...)`. + + ```jsonc agents/researcher.jsonc + { + "role": "{topic} Senior Data Researcher", + "goal": "Uncover cutting-edge developments in {topic}", + "backstory": "You're a seasoned researcher who finds relevant information and presents it clearly.", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true + } + } + ``` + + + + + Create `src/latest_ai_flow/crews/content_crew/crew.jsonc`: + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research about {topic}. Use web search to find recent, credible information.", + "expected_output": "A markdown report with clear sections: key trends, notable tools or companies, and implications. Aim for 800-1200 words. No fenced code blocks around the whole document.", + "agent": "researcher", + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true + } + ``` + + + + + Replace the generated `content_crew.py` with a small loader that turns `crew.jsonc` into a `Crew`. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py + from pathlib import Path + + from crewai.project import load_crew + + + def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) + ``` + + + + + Connect the crew to a Flow: a `@start()` step sets the topic in **state**, and a `@listen` step runs the crew. The task’s `output_file` still writes `output/report.md`. + + ```python main.py + # src/latest_ai_flow/main.py + from pydantic import BaseModel + + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"Topic: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = kickoff_content_crew(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("Research crew finished.") + + @listen(run_research) + def summarize(self): + print("Report path: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() + ``` + + + If your package name differs from `latest_ai_flow`, change the `kickoff_content_crew` import to match your project’s module path. + + + + + In `.env` at the project root, set: + + - `SERPER_API_KEY` — from [Serper.dev](https://serper.dev/) + - Your model provider keys as required — see [LLM setup](/en/concepts/llms#setting-up-your-llm) + + + + + ```shell Terminal + crewai install + crewai run + ``` + + + `crewai run` executes the Flow entrypoint defined in your project (same command as for crews; project type is `"flow"` in `pyproject.toml`). + + + + + + + You should see logs from the Flow and the crew. Open **`output/report.md`** for the generated report (excerpt): + + + ```markdown output/report.md + # AI Agents: Recent Landscape and Trends + + ## Executive summary + … + + ## Key trends + - **Tool use and orchestration** — … + - **Enterprise adoption** — … + + ## Implications + … + ``` + + + Your actual file will be longer and reflect live search results. + + + +## How this run fits together + +1. **Flow** — `LatestAiFlow` runs `prepare_topic` first, then `run_research`, then `summarize`. State (`topic`, `report`) lives on the Flow. +2. **Crew** — `kickoff_content_crew` loads `crew.jsonc` and runs one task with one agent: the researcher uses **Serper** to search the web, then writes the structured report. +3. **Artifact** — The task’s `output_file` writes the report under `output/report.md`. + +To go deeper on Flow patterns (routing, persistence, human-in-the-loop), see [Build your first Flow](/en/guides/flows/first-flow) and [Flows](/en/concepts/flows). For crews without a Flow, see [Crews](/en/concepts/crews). For a single `Agent` and `kickoff()` without tasks, see [Agents](/en/concepts/agents#direct-agent-interaction-with-kickoff). + + +You now have an end-to-end Flow with an agent crew and a saved report — a solid base to add more steps, crews, or tools. + + +### Naming consistency + +The names in `crew.jsonc` must match the files and task references you use: + +- `agents: ["researcher"]` loads `agents/researcher.jsonc` +- `tasks[].agent: "researcher"` assigns the task to that agent + +## Deploying + +Push your Flow to **[CrewAI AMP](https://app.crewai.com)** once it runs locally and your project is in a **GitHub** repository. From the project root: + + +```bash Authenticate +crewai login +``` + +```bash Create deployment +crewai deploy create +``` + +```bash Check status & logs +crewai deploy status +crewai deploy logs +``` + +```bash Ship updates after you change code +crewai deploy push +``` + +```bash List or remove deployments +crewai deploy list +crewai deploy remove +``` + + + + The first deploy usually takes **around 1 minute**. Full prerequisites and the web UI flow are in [Deploy to AMP](/en/enterprise/guides/deploy-to-amp). + + + + + Step-by-step AMP deployment (CLI and dashboard). + + + Discuss ideas, share projects, and connect with other CrewAI developers. + + diff --git a/docs/v1.15.1/en/skills.mdx b/docs/v1.15.1/en/skills.mdx new file mode 100644 index 000000000..91789242d --- /dev/null +++ b/docs/v1.15.1/en/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: Install crewaiinc/skills from the official registry at skills.sh—Flows, Crews, and docs-aware agents for Claude Code, Cursor, Codex, and more. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**Give your AI coding agent CrewAI context in one command.** + +CrewAI **Skills** are published on **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**—the official registry for `crewaiinc/skills`, including individual skills (for example **design-agent**, **getting-started**, **design-task**, and **ask-docs**), install stats, and audits. They teach coding agents—like Claude Code, Cursor, and Codex—how to scaffold Flows, configure Crews, use tools, and follow CrewAI patterns. Run the install below (or paste it into your agent). + +```shell Terminal +npx skills add crewaiinc/skills +``` + +That pulls the official skill pack into your agent workflow so it can apply CrewAI conventions without you re-explaining the framework each session. Source code and issues live on [GitHub](https://github.com/crewAIInc/skills). + +## What your agent gets + +- **Flows** — structure stateful apps, steps, and crew kickoffs the CrewAI way +- **Crews & agents** — JSON-first patterns (`crew.jsonc`, `agents/*.jsonc`), roles, tasks, and delegation +- **Tools & integrations** — hook agents to search, APIs, and common CrewAI tools +- **Project layout** — align with CLI scaffolds and repo conventions +- **Up-to-date patterns** — skills track current CrewAI docs and recommended practices + +## Learn more on this site + + + + How to use `AGENTS.md` and coding-agent workflows with CrewAI. + + + Build your first Flow and crew end-to-end. + + + Install the CrewAI CLI and Python package. + + + Official listing for `crewaiinc/skills`—skills, installs, and audits. + + + Source, updates, and issues for the skill pack. + + + +### Video: CrewAI with coding agent skills + + + +### 11. API 키 + +`crewai create crew` 명령어를 실행하면, CLI에서 선택할 수 있는 LLM 제공업체 목록이 표시되고, 그 다음으로 선택한 제공업체에 대한 모델 선택이 이어집니다. 선택한 모델은 생성된 `.env`에 저장되며 각 에이전트 JSONC 파일은 자체 `llm`을 설정할 수 있습니다. + +LLM 제공업체와 모델을 선택하면, API 키를 입력하라는 메시지가 표시됩니다. + +#### 사용 가능한 LLM 공급자 + +다음은 CLI에서 제안하는 가장 인기 있는 LLM 공급자 목록입니다: + +- OpenAI +- Groq +- Anthropic +- Google Gemini +- SambaNova + +공급자를 선택하면, CLI가 해당 공급자에서 사용 가능한 모델을 보여주고 API 키 입력을 요청합니다. + +#### 기타 옵션 + +"기타"를 선택하면 LiteLLM에서 지원하는 공급자 목록에서 선택할 수 있습니다. + +공급자를 선택하면 CLI에서 Key 이름과 API 키 입력을 요청합니다. + +각 공급자의 Key 이름은 다음 링크에서 확인할 수 있습니다: + +- [LiteLLM 공급자](https://docs.litellm.ai/docs/providers) + +### 12. 구성 관리 + +CrewAI의 CLI 구성 설정을 관리합니다. + +```shell Terminal +crewai config [COMMAND] [OPTIONS] +``` + +#### 명령어: + +- `list`: 모든 CLI 구성 매개변수 표시 + +```shell Terminal +crewai config list +``` + +- `set`: CLI 구성 매개변수 설정 + +```shell Terminal +crewai config set +``` + +- `reset`: 모든 CLI 구성 매개변수를 기본값으로 초기화 + +```shell Terminal +crewai config reset +``` + +#### 사용 가능한 구성 파라미터 + +- `enterprise_base_url`: CrewAI AMP 인스턴스의 기본 URL +- `oauth2_provider`: 인증에 사용되는 OAuth2 공급자 (예: workos, okta, auth0) +- `oauth2_audience`: OAuth2 audience 값으로, 일반적으로 대상 API 또는 리소스를 식별하는 데 사용됨 +- `oauth2_client_id`: 인증 요청 시 사용되는 공급자가 발급한 OAuth2 클라이언트 ID +- `oauth2_domain`: 토큰 발급에 사용되는 OAuth2 공급자의 도메인 (예: your-org.auth0.com) + +#### 예시 + +현재 설정 표시: + +```shell Terminal +crewai config list +``` + +예시 출력: + +| 설정 | 값 | 설명 | +| :------------------ | :--------------------- | :------------------------------------------------------------------- | +| enterprise_base_url | https://app.crewai.com | CrewAI AMP 인스턴스의 기본 URL | +| org_name | Not set | 현재 활성화된 조직의 이름 | +| org_uuid | Not set | 현재 활성화된 조직의 UUID | +| oauth2_provider | workos | 인증에 사용되는 OAuth2 제공자 (예: workos, okta, auth0) | +| oauth2_audience | client_01YYY | 일반적으로 대상 API/리소스를 식별하는 데 사용되는 OAuth2 audience 값 | +| oauth2_client_id | client_01XXX | 제공자로부터 발급된 OAuth2 client ID (인증 요청 시 사용) | +| oauth2_domain | login.crewai.com | OAuth2 제공자의 도메인 (예: your-org.auth0.com) | + +엔터프라이즈 기본 URL 설정: + +```shell Terminal +crewai config set enterprise_base_url https://my-enterprise.crewai.com +``` + +OAuth2 제공자 설정: + +```shell Terminal +crewai config set oauth2_provider auth0 +``` + +OAuth2 도메인 설정: + +```shell Terminal +crewai config set oauth2_domain my-company.auth0.com +``` + +모든 설정을 기본값으로 재설정: + +```shell Terminal +crewai config reset +``` + + + 설정 값은 `~/.config/crewai/settings.json`에 저장됩니다. 조직 이름과 UUID와 + 같은 일부 설정 값은 읽기 전용이며 인증 및 조직 명령을 통해 관리됩니다. 도구 + 저장소 관련 설정은 숨겨져 있으며 사용자가 직접 설정할 수 없습니다. + diff --git a/docs/v1.15.1/ko/concepts/collaboration.mdx b/docs/v1.15.1/ko/concepts/collaboration.mdx new file mode 100644 index 000000000..c9c11b601 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/collaboration.mdx @@ -0,0 +1,363 @@ +--- +title: 협업 +description: CrewAI 팀 내에서 에이전트가 함께 작업하고, 작업을 위임하며, 효과적으로 소통하는 방법에 대해 설명합니다. +icon: screen-users +mode: "wide" +--- + +## 개요 + +CrewAI에서의 협업은 에이전트들이 팀으로서 함께 작업하며, 각자의 전문성을 활용하기 위해 작업을 위임하고 질문을 주고받을 수 있도록 합니다. `allow_delegation=True`로 설정하면, 에이전트들은 자동으로 강력한 협업 도구에 접근할 수 있습니다. + +## 빠른 시작: 협업 활성화 + +```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 +) +``` + +## 에이전트 협업 방식 + +`allow_delegation=True`로 설정하면, CrewAI는 에이전트에게 두 가지 강력한 도구를 자동으로 제공합니다. + +### 1. **업무 위임 도구** +에이전트가 특정 전문성을 가진 팀원에게 작업을 할당할 수 있습니다. + +```python +# Agent automatically gets this tool: +# Delegate work to coworker(task: str, context: str, coworker: str) +``` + +### 2. **질문하기 도구** +에이전트가 동료로부터 정보를 수집하기 위해 특정 질문을 할 수 있게 해줍니다. + +```python +# Agent automatically gets this tool: +# Ask question to coworker(question: str, context: str, coworker: str) +``` + +## 협업의 실제 + +아래는 에이전트들이 콘텐츠 제작 작업에 협력하는 완성된 예시입니다: + +```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() +``` + +## 협업 패턴 + +### 패턴 1: 조사 → 작성 → 편집 +```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 +) +``` + +### 패턴 2: 협업 단일 작업 +```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 +) +``` + +## 계층적 협업 + +복잡한 프로젝트의 경우, 매니저 에이전트를 활용하여 계층적 프로세스를 사용하세요: + +```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 +) +``` + +## 협업을 위한 모범 사례 + +### 1. **명확한 역할 정의** +```python +# ✅ Good: Specific, complementary roles +researcher = Agent(role="Market Research Analyst", ...) +writer = Agent(role="Technical Content Writer", ...) + +# ❌ Avoid: Overlapping or vague roles +agent1 = Agent(role="General Assistant", ...) +agent2 = Agent(role="Helper", ...) +``` + +### 2. **전략적 위임 활성화** +```python +# ✅ Enable delegation for coordinators and generalists +lead_agent = Agent( + role="Content Lead", + allow_delegation=True, # Can delegate to specialists + ... +) + +# ✅ Disable for focused specialists (optional) +specialist_agent = Agent( + role="Data Analyst", + allow_delegation=False, # Focuses on core expertise + ... +) +``` + +### 3. **컨텍스트 공유** +```python +# ✅ Use context parameter for task dependencies +writing_task = Task( + description="Write article based on research", + agent=writer, + context=[research_task], # Shares research results + ... +) +``` + +### 4. **명확한 작업 설명** +```python +# ✅ 구체적이고 실행 가능한 설명 +Task( + description="""Research competitors in the AI chatbot space. + Focus on: pricing models, key features, target markets. + Provide data in a structured format.""", + ... +) + +# ❌ 협업에 도움이 되지 않는 모호한 설명 +Task(description="Do some research about chatbots", ...) +``` + +## 협업 문제 해결 + +### 문제: 에이전트들이 협업하지 않음 +**증상:** 에이전트들이 각자 작업하며, 위임이 이루어지지 않음 +```python +# ✅ Solution: Ensure delegation is enabled +agent = Agent( + role="...", + allow_delegation=True, # This is required! + ... +) +``` + +### 문제: 지나친 이중 확인 +**증상:** 에이전트가 과도하게 질문을 하여 진행이 느려짐 +```python +# ✅ Solution: Provide better context and specific roles +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.""", + ... +) +``` + +### 문제: 위임 루프 +**증상:** 에이전트들이 무한히 서로에게 위임함 +```python +# ✅ Solution: Clear hierarchy and responsibilities +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) +``` + +## 고급 협업 기능 + +### 맞춤 협업 규칙 +```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 +) +``` + +### 협업 모니터링 +```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 +) +``` + +## 메모리와 학습 + +에이전트가 과거 협업을 기억할 수 있도록 합니다: + +```python +agent = Agent( + role="Content Lead", + memory=True, # Remembers past interactions + allow_delegation=True, + verbose=True +) +``` + +메모리가 활성화되면, 에이전트는 이전 협업에서 학습하여 시간이 지남에 따라 더 나은 위임 결정을 내릴 수 있습니다. + +## 다음 단계 + +- **예제 시도하기**: 기본 협업 예제부터 시작하세요 +- **역할 실험하기**: 다양한 에이전트 역할 조합을 테스트해 보세요 +- **상호작용 모니터링**: 협업 과정을 직접 보려면 `verbose=True`를 사용하세요 +- **작업 설명 최적화**: 명확한 작업이 더 나은 협업으로 이어집니다 +- **확장하기**: 복잡한 프로젝트에는 계층적 프로세스를 시도해 보세요 + +협업은 개별 AI 에이전트를 복잡하고 다면적인 문제를 함께 해결할 수 있는 강력한 팀으로 변화시킵니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/crews.mdx b/docs/v1.15.1/ko/concepts/crews.mdx new file mode 100644 index 000000000..e4cfadc1c --- /dev/null +++ b/docs/v1.15.1/ko/concepts/crews.mdx @@ -0,0 +1,460 @@ +--- +title: 크루 +description: crewAI 프레임워크에서 크루를 이해하고 다양한 속성과 기능을 활용하기. +icon: people-group +mode: "wide" +--- + +## 개요 + +crewAI에서 crew는 일련의 작업을 달성하기 위해 함께 협력하는 에이전트들의 그룹을 나타냅니다. 각 crew는 작업 실행, 에이전트 간 협업, 그리고 전체 워크플로우에 대한 전략을 정의합니다. + +## Crew 속성 + +| 속성 | 파라미터 | 설명 | +| :-------------------------------------- | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Tasks** | `tasks` | crew에 할당된 작업들의 리스트. | +| **Agents** | `agents` | crew의 일원이 되는 에이전트들의 리스트. | +| **Process** _(선택사항)_ | `process` | crew가 따르는 프로세스 플로우(예: 순차, 계층적). 기본값은 `sequential`. | +| **Verbose** _(선택사항)_ | `verbose` | 실행 중 로그의 상세도 설정. 기본값은 `False`. | +| **Manager LLM** _(선택사항)_ | `manager_llm` | 계층적 프로세스에서 매니저 에이전트가 사용하는 언어 모델. **계층적 프로세스를 사용할 때 필수.** | +| **Function Calling LLM** _(선택사항)_ | `function_calling_llm` | 전달 시, crew 전체의 모든 agent에 대해 도구의 function calling에 이 LLM을 사용. 각 agent마다 개별 LLM을 가질 수 있으며, 이 경우 crew의 function calling LLM을 오버라이드 함. | +| **Config** _(선택사항)_ | `config` | crew용으로 선택적인 구성 설정. `Json` 또는 `Dict[str, Any]` 형식 사용. | +| **Max RPM** _(선택사항)_ | `max_rpm` | 실행 중 crew가 준수하는 분당 최대 요청 수. 기본값은 `None`. | +| **Memory** _(선택사항)_ | `memory` | 실행 메모리(단기, 장기, 엔터티 메모리) 저장에 사용됨. | +| **Cache** _(선택사항)_ | `cache` | 도구 실행 결과를 캐시에 저장할지 여부. 기본값은 `True`. | +| **Embedder** _(선택사항)_ | `embedder` | crew에서 사용할 embedder 설정. 현재는 주로 메모리에서 사용. 기본값은 `{"provider": "openai"}`. | +| **Step Callback** _(선택사항)_ | `step_callback` | 각 agent의 단계가 끝난 후 호출되는 함수. agent의 작업 기록이나 기타 작업 수행에 사용 가능; agent별 `step_callback`을 오버라이드하지 않음. | +| **Task Callback** _(선택사항)_ | `task_callback` | 각 작업 완료 후 호출되는 함수. 작업 실행 후 모니터링이나 추가 작업에 유용. | +| **Share Crew** _(선택사항)_ | `share_crew` | 라이브러리 개선 및 모델 학습을 위해 crew 정보와 실행을 crewAI 팀에 공유할지 여부. | +| **Output Log File** _(선택사항)_ | `output_log_file` | `True`로 설정 시 로그를 현재 디렉터리에 logs.txt로 저장하거나 파일 경로 지정 가능. 파일명이 .json으로 끝나면 JSON 형식, 아니면 txt 형식으로 로그를 저장. 기본값은 `None`. | +| **Manager Agent** _(선택사항)_ | `manager_agent` | 매니저로 사용할 커스텀 agent를 설정. | +| **Prompt File** _(선택사항)_ | `prompt_file` | crew에서 사용할 prompt JSON 파일 경로. | +| **Planning** *(선택사항)* | `planning` | Crew에 계획 수립 기능을 추가. 활성화하면 각 Crew 반복 전에 모든 Crew 데이터를 AgentPlanner로 전송하여 작업계획을 세우고, 이 계획이 각 작업 설명에 추가됨. | +| **Planning LLM** *(선택사항)* | `planning_llm` | 계획 과정에서 AgentPlanner가 사용하는 언어 모델. | +| **Knowledge Sources** _(선택사항)_ | `knowledge_sources` | crew 수준에서 사용 가능한 지식 소스. 모든 agent가 접근 가능. | +| **Stream** _(선택사항)_ | `stream` | 스트리밍 출력을 활성화하여 crew 실행 중 실시간 업데이트를 받을 수 있습니다. 청크를 반복할 수 있는 `CrewStreamingOutput` 객체를 반환합니다. 기본값은 `False`. | + + +**Crew Max RPM**: `max_rpm` 속성은 crew가 분당 처리할 수 있는 최대 요청 수를 설정하며, 개별 agent의 `max_rpm` 설정을 crew 단위로 지정할 경우 오버라이드합니다. + + +## 크루 생성하기 + +CrewAI에서 크루를 생성하는 주요 방법은 **JSONC 구성(새 crew 권장)**을 사용하는 방법과 클래식 프로젝트나 고급 사용 사례에서 **코드로 직접 정의**하는 방법입니다. + +### JSONC 구성 (권장) + +`crewai create crew `으로 만든 새 프로젝트는 crew 수준 설정과 태스크를 `crew.jsonc`에 두고, 각 에이전트를 `agents/`의 별도 파일에 둡니다. `crewai run`은 `crew.jsonc` 또는 `crew.json`을 감지해 에이전트를 로드하고, 빠진 placeholder 값을 물은 뒤 crew를 시작합니다. + +```jsonc crew.jsonc +{ + "name": "Market Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research", + "description": "Research {topic} and collect the most relevant facts.", + "expected_output": "Structured research notes about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis", + "description": "Analyze the research and write a concise report.", + "expected_output": "A markdown report with findings and recommendations.", + "agent": "analyst", + "context": ["research"], + "output_file": "output/report.md" + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "AI Agents" + } +} +``` + +`agents`의 각 문자열은 먼저 `agents/.jsonc`, 그 다음 `agents/.json`으로 해석됩니다. 계층형 crew는 `"process": "hierarchical"`와 `manager_llm` 또는 `manager_agent`를 사용하세요. + + +신뢰하는 출처의 JSON crew 프로젝트만 실행하세요. `custom:` 도구와 `{"python": "module.attribute"}` 참조는 crew 로드 시 로컬 Python 코드를 실행합니다. + + +### 클래식 YAML 구성 + +`crewai create crew --classic`으로 만든 클래식 프로젝트는 `crew.py`, `config/agents.yaml`, `config/tasks.yaml`, `@CrewBase`, `@agent`, `@task`, `@crew` 데코레이터를 사용합니다. + +이 방식은 기존 Python/YAML 프로젝트와 Python 데코레이터 제어가 필요한 팀을 위해 계속 지원됩니다. + +클래식 프로젝트를 만든 후, `CrewBase`를 상속받는 클래스에서 데코레이터를 이용해 agent, task, 그리고 crew 자체를 정의할 수 있습니다. + +#### 데코레이터가 적용된 예시 Crew 클래스 + +```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: + """Description of your crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + # YAML 구성 파일 경로 + # YAML로 정의된 에이전트와 태스크의 예시는 아래 링크를 참고하세요: + # - 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): + # crew 시작 전에 입력값을 수정합니다 + inputs['additional_data'] = "Some extra information" + return inputs + + @after_kickoff + def process_output(self, output): + # crew가 종료된 후 출력값을 수정합니다 + output.raw += "\nProcessed after 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, # @agent 데코레이터로 자동 수집 + tasks=self.tasks, # @task 데코레이터로 자동 수집 + process=Process.sequential, + verbose=True, + ) +``` + +위 코드를 실행하는 방법: + +```python code +YourCrewName().crew().kickoff(inputs={"any": "input here"}) +``` + + +태스크들은 정의된 순서대로 실행됩니다. + + +`CrewBase` 클래스와 이 데코레이터들은 에이전트와 태스크의 수집을 자동화하여 +수동으로 관리할 필요를 줄여줍니다. + +#### `annotations.py`의 데코레이터 개요 + +CrewAI는 `annotations.py` 파일에서 크루 클래스 내의 메서드를 특별히 처리하기 위해 사용하는 여러 데코레이터를 제공합니다: + +- `@CrewBase`: 클래스를 크루 기본 클래스로 표시합니다. +- `@agent`: `Agent` 객체를 반환하는 메서드임을 나타냅니다. +- `@task`: `Task` 객체를 반환하는 메서드임을 나타냅니다. +- `@crew`: `Crew` 객체를 반환하는 메서드임을 나타냅니다. +- `@before_kickoff`: (옵션) 크루가 시작되기 전에 실행될 메서드를 표시합니다. +- `@after_kickoff`: (옵션) 크루가 종료된 후에 실행될 메서드를 표시합니다. + +이러한 데코레이터들은 크루의 구조를 구성하는 데 도움이 되며, 에이전트와 태스크를 수동으로 나열하지 않아도 자동으로 수집할 수 있도록 해줍니다. + +### 직접 코드 정의 (대안) + +또는 YAML 구성 파일을 사용하지 않고 코드에서 직접 crew를 정의할 수 있습니다. + +```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 + ) +``` + +위 코드를 실행하는 방법: + +```python code +YourCrewName().crew().kickoff(inputs={}) +``` + +이 예시에서: + +- 에이전트와 태스크는 데코레이터 없이 클래스 내에서 직접 정의됩니다. +- 에이전트와 태스크 목록을 수동으로 생성하고 관리합니다. +- 이 방식은 더 많은 제어를 제공하지만, 대규모 프로젝트의 경우 유지보수가 어려울 수 있습니다. + +## Crew Output + +CrewAI 프레임워크에서 crew의 출력은 `CrewOutput` 클래스 내에 캡슐화되어 있습니다. +이 클래스는 crew 실행 결과를 구조화된 방식으로 접근할 수 있도록 하며, 원시 문자열, JSON, Pydantic 모델과 같은 다양한 형식을 포함합니다. +`CrewOutput`에는 최종 task 출력 결과, 토큰 사용량, 그리고 개별 task 출력 결과가 포함됩니다. + +### Crew 출력 속성 + +| 속성 | 매개변수 | 타입 | 설명 | +| :--------------- | :--------------- | :--------------------------- | :----------------------------------------------------------------------------------------- | +| **Raw** | `raw` | `str` | crew의 원시 출력값입니다. 출력의 기본 형식입니다. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | crew의 구조화된 출력을 나타내는 Pydantic 모델 객체입니다. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | crew의 JSON 출력을 나타내는 딕셔너리입니다. | +| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | crew 내 각 작업의 출력을 나타내는 `TaskOutput` 객체의 리스트입니다. | +| **Token Usage** | `token_usage` | `Dict[str, Any]` | 실행 중 언어 모델의 성능에 대한 통찰을 제공하는 토큰 사용 요약 정보입니다. | + +### Crew 출력 메서드 및 속성 + +| 메서드/속성 | 설명 | +| :-------------- | :------------------------------------------------------------------------------------------------ | +| **json** | 출력 형식이 JSON인 경우 crew 출력의 JSON 문자열 표현을 반환합니다. | +| **to_dict** | JSON 및 Pydantic 출력을 사전으로 변환합니다. | +| \***\*str\*\*** | crew 출력의 문자열 표현을 반환합니다. 우선순위는 Pydantic, 그 다음 JSON, 마지막으로 raw입니다. | + +### Crew 출력 접근하기 + +crew가 실행된 후에는 `Crew` 객체의 `output` 속성을 통해 출력값에 접근할 수 있습니다. `CrewOutput` 클래스는 이 출력값을 다루고 표시하는 다양한 방법을 제공합니다. + +#### 예시 + +```python Code +# Example crew execution +crew = Crew( + agents=[research_agent, writer_agent], + tasks=[research_task, write_article_task], + verbose=True +) + +crew_output = crew.kickoff() + +# Accessing the crew output +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}") +``` + +## 크루 로그 접근하기 + +`output_log_file`을 `True(Boolean)` 또는 `file_name(str)`로 설정하면 크루 실행의 실시간 로그를 볼 수 있습니다. 이벤트 로그는 `file_name.txt`와 `file_name.json` 두 가지 형식 모두를 지원합니다. +`True(Boolean)`로 설정할 경우에는 `logs.txt`로 저장됩니다. + +`output_log_file`이 `False(Boolean)` 또는 `None`으로 설정된 경우에는 로그가 저장되지 않습니다. + +```python Code +# 크루 로그 저장하기 +crew = Crew(output_log_file = True) # 로그는 logs.txt로 저장됩니다 +crew = Crew(output_log_file = file_name) # 로그는 file_name.txt로 저장됩니다 +crew = Crew(output_log_file = file_name.txt) # 로그는 file_name.txt로 저장됩니다 +crew = Crew(output_log_file = file_name.json) # 로그는 file_name.json으로 저장됩니다 +``` + +## 메모리 활용 + +crew는 메모리(단기, 장기 및 엔티티 메모리)를 활용하여 시간이 지남에 따라 실행 및 학습을 향상시킬 수 있습니다. 이 기능을 통해 crew는 실행 메모리를 저장하고 회상할 수 있어, 의사결정 및 작업 실행 전략에 도움이 됩니다. + +## 캐시 활용 + +캐시는 도구 실행 결과를 저장하는 데 사용될 수 있으며, 동일한 작업을 반복 실행할 필요를 줄여 프로세스의 효율성을 높입니다. + +## Crew 사용 메트릭 + +crew 실행 후, `usage_metrics` 속성에 접근하여 crew가 실행한 모든 작업에 대한 언어 모델(LLM) 사용 메트릭을 확인할 수 있습니다. 이를 통해 운영 효율성과 개선이 필요한 영역에 대한 인사이트를 얻을 수 있습니다. + +```python Code +# Access the crew's usage metrics +crew = Crew(agents=[agent1, agent2], tasks=[task1, task2]) +crew.kickoff() +print(crew.usage_metrics) +``` + +## Crew 실행 프로세스 + +- **순차적 프로세스**: 작업이 하나씩 차례로 실행되어 linear flow의 작업 흐름을 제공합니다. +- **계층적 프로세스**: 매니저 agent가 crew를 조정하여 작업을 위임하고 결과를 검증한 후 다음 단계로 이동합니다. **참고**: 이 프로세스에는 `manager_llm` 또는 `manager_agent`가 필요하며, 프로세스 flow 검증을 위해 필수적입니다. + +### 크루 시작하기 + +크루가 구성되면, `kickoff()` 메서드를 사용하여 워크플로를 시작하세요. 이렇게 하면 정의된 프로세스 플로우에 따라 실행 과정이 시작됩니다. + +```python Code +# Start the crew's task execution +result = my_crew.kickoff() +print(result) +``` + +### Crew를 시작하는 다양한 방법 + +crew가 구성되면, 적절한 시작 방법으로 workflow를 시작하세요. CrewAI는 kickoff 프로세스를 더 잘 제어할 수 있도록 여러 방법을 제공합니다. + +#### 동기 메서드 + +- `kickoff()`: 정의된 process flow에 따라 실행 프로세스를 시작합니다. +- `kickoff_for_each()`: 입력 이벤트나 컬렉션 내 각 항목에 대해 순차적으로 task를 실행합니다. + +#### 비동기 메서드 + +CrewAI는 비동기 실행을 위해 두 가지 접근 방식을 제공합니다: + +| 메서드 | 타입 | 설명 | +|--------|------|-------------| +| `akickoff()` | 네이티브 async | 전체 실행 체인에서 진정한 async/await 사용 | +| `akickoff_for_each()` | 네이티브 async | 리스트의 각 입력에 대해 네이티브 async 실행 | +| `kickoff_async()` | 스레드 기반 | 동기 실행을 `asyncio.to_thread`로 래핑 | +| `kickoff_for_each_async()` | 스레드 기반 | 리스트의 각 입력에 대해 스레드 기반 async | + + +고동시성 워크로드의 경우 `akickoff()` 및 `akickoff_for_each()`가 권장됩니다. 이들은 작업 실행, 메모리 작업, 지식 검색에 네이티브 async를 사용합니다. + + +```python Code +# Start the crew's task execution +result = my_crew.kickoff() +print(result) + +# Example of using 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) + +# Example of using native async with akickoff +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.akickoff(inputs=inputs) +print(async_result) + +# Example of using native async with akickoff_for_each +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +async_results = await my_crew.akickoff_for_each(inputs=inputs_array) +for async_result in async_results: + print(async_result) + +# Example of using thread-based kickoff_async +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.kickoff_async(inputs=inputs) +print(async_result) + +# Example of using thread-based 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) +``` + +이러한 메서드는 crew 내에서 task를 관리하고 실행하는 데 유연성을 제공하며, 동기 및 비동기 workflow 모두 필요에 맞게 사용할 수 있도록 지원합니다. 자세한 비동기 예제는 [Crew 비동기 시작](/ko/learn/kickoff-async) 가이드를 참조하세요. + +### 스트리밍 Crew 실행 + +crew 실행을 실시간으로 확인하려면 스트리밍을 활성화하여 출력이 생성되는 대로 받을 수 있습니다: + +```python Code +# 스트리밍 활성화 +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +# 스트리밍 출력을 반복 +streaming = crew.kickoff(inputs={"topic": "AI"}) +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# 최종 결과 접근 +result = streaming.result +``` + +스트리밍에 대한 자세한 내용은 [스트리밍 Crew 실행](/ko/learn/streaming-crew-execution) 가이드를 참조하세요. + +### 특정 Task에서 다시 실행하기 + +이제 CLI 명령어 `replay`를 사용하여 특정 task에서 다시 실행할 수 있습니다. + +CrewAI의 replay 기능을 사용하면 커맨드라인 인터페이스(CLI)를 통해 특정 task에서 다시 실행할 수 있습니다. `crewai replay -t ` 명령어를 실행하면 replay 과정에서 사용할 `task_id`를 지정할 수 있습니다. + +Kickoff은 이제 최신 kickoff에서 반환된 task output을 로컬에 저장하므로, 해당 지점부터 다시 실행할 수 있습니다. + +### CLI를 사용하여 특정 작업에서 다시 실행하기 + +replay 기능을 사용하려면 다음 단계를 따라주세요: + +1. 터미널 또는 명령 프롬프트를 엽니다. +2. CrewAI 프로젝트가 위치한 디렉터리로 이동합니다. +3. 아래 명령어를 실행합니다: + +최신 kickoff 작업 ID를 확인하려면 다음을 사용하세요: + +```shell +crewai log-tasks-outputs +``` + +그런 다음, 특정 작업에서 다시 실행하려면 다음을 사용하세요: + +```shell +crewai replay -t +``` + +이 명령어들을 사용하면 이전에 실행된 작업의 컨텍스트를 유지하면서 최신 kickoff 작업부터 다시 실행할 수 있습니다. diff --git a/docs/v1.15.1/ko/concepts/event-listener.mdx b/docs/v1.15.1/ko/concepts/event-listener.mdx new file mode 100644 index 000000000..e2858bf55 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/event-listener.mdx @@ -0,0 +1,414 @@ +--- +title: '이벤트 리스너' +description: 'CrewAI 이벤트에 연결하여 맞춤형 통합 및 모니터링 구축' +icon: spinner +mode: "wide" +--- + +## 개요 + +CrewAI는 강력한 이벤트 시스템을 제공하여 crew 실행 중 발생하는 다양한 이벤트를 수신하고 이에 반응할 수 있도록 합니다. 이 기능을 통해 맞춤형 통합, 모니터링 솔루션, 로깅 시스템 또는 CrewAI의 내부 이벤트에 따라 트리거되어야 하는 기타 모든 기능을 구축할 수 있습니다. + +## 작동 방식 + +CrewAI는 실행 수명 주기 전반에 걸쳐 이벤트를 발생시키는 이벤트 버스 아키텍처를 사용합니다. 이벤트 시스템은 다음과 같은 구성 요소로 구축되어 있습니다: + +1. **CrewAIEventsBus**: 이벤트 등록 및 발생을 관리하는 싱글톤 이벤트 버스 +2. **BaseEvent**: 시스템 내 모든 이벤트의 기본 클래스 +3. **BaseEventListener**: 커스텀 이벤트 리스너 생성을 위한 추상 기본 클래스 + +CrewAI에서 특정 동작(예: Crew가 실행을 시작하거나 Agent가 task를 완료하거나 tool이 사용될 때)이 발생하면, 시스템은 해당 이벤트를 발생시킵니다. 이러한 이벤트에 대한 핸들러를 등록하여 해당 이벤트가 발생할 때 커스텀 코드를 실행할 수 있습니다. + + +CrewAI AOP는 event 시스템을 활용하여 모든 prompt, completion 및 관련 메타데이터를 추적, 저장 및 시각화하는 내장 Prompt Tracing 기능을 제공합니다. 이 기능을 통해 agent 운영에 대한 강력한 디버깅 기능과 투명성을 얻을 수 있습니다. + +![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png) + +Prompt Tracing을 통해 다음과 같은 작업이 가능합니다: +- LLM에 전송된 모든 prompt의 전체 기록 보기 +- token 사용량 및 비용 추적 +- agent reasoning 실패 디버깅 +- 팀 내에서 prompt 시퀀스 공유 +- 다양한 prompt 전략 비교 +- 컴플라이언스 및 감사를 위한 trace 내보내기 + + +## 커스텀 이벤트 리스너 생성하기 + +커스텀 이벤트 리스너를 생성하려면 다음 단계를 따라야 합니다: + +1. `BaseEventListener`를 상속하는 클래스를 생성합니다. +2. `setup_listeners` 메서드를 구현합니다. +3. 원하는 이벤트에 대한 핸들러를 등록합니다. +4. 해당 파일에서 리스너의 인스턴스를 생성합니다. + +아래는 커스텀 이벤트 리스너 클래스의 간단한 예시입니다: + +```python +from crewai.events import ( + CrewKickoffStartedEvent, + CrewKickoffCompletedEvent, + AgentExecutionCompletedEvent, +) +from crewai.events 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}") +``` + +## 리스너를 올바르게 등록하기 + +리스너 클래스를 정의하는 것만으로는 충분하지 않습니다. 해당 클래스의 인스턴스를 생성하고 애플리케이션에 임포트되었는지 확인해야 합니다. 이렇게 하면 다음과 같은 효과가 있습니다: + +1. 이벤트 핸들러가 이벤트 버스에 등록됩니다. +2. 리스너 인스턴스가 메모리에 유지됩니다(가비지 컬렉션되지 않음). +3. 이벤트가 발생할 때 리스너가 활성화됩니다. + +### 옵션 1: Crew 또는 Flow 구현에서 가져오기 및 인스턴스화 + +가장 중요한 것은 Crew 또는 Flow가 정의되고 실행되는 파일에서 리스너의 인스턴스를 생성하는 것입니다. + +#### 크루 기반 애플리케이션의 경우 + +크루 구현 파일 상단에 리스너를 생성하고 임포트하세요: + +```python +# In your crew.py file +from crewai import Agent, Crew, Task +from my_listeners import MyCustomListener + +# Create an instance of your listener +my_listener = MyCustomListener() + +class MyCustomCrew: + # Your crew implementation... + + def crew(self): + return Crew( + agents=[...], + tasks=[...], + # ... + ) +``` + +#### 플로우 기반 애플리케이션의 경우 + +플로우 구현 파일 상단에 리스너를 생성하고 임포트하세요: + +```python +# main.py 또는 flow.py 파일에서 +from crewai.flow import Flow, listen, start +from my_listeners import MyCustomListener + +# 리스너 인스턴스 생성 +my_listener = MyCustomListener() + +class MyCustomFlow(Flow): + # 플로우 구현... + + @start() + def first_step(self): + # ... +``` + +이렇게 하면 크루 또는 플로우가 실행될 때 리스너가 로드되고 활성화됩니다. + +### 옵션 2: 리스너를 위한 패키지 생성 + +여러 개의 리스너가 있는 경우 등 보다 구조적인 접근 방식을 원한다면 다음과 같이 진행하세요: + +1. 리스너를 위한 패키지를 생성합니다: + +``` +my_project/ + ├── listeners/ + │ ├── __init__.py + │ ├── my_custom_listener.py + │ └── another_listener.py +``` + +2. `my_custom_listener.py`에서 리스너 클래스를 정의하고 인스턴스를 생성합니다: + +```python +# my_custom_listener.py +from crewai.events import BaseEventListener +# ... import events ... + +class MyCustomListener(BaseEventListener): + # ... implementation ... + +# 리스너 인스턴스 생성 +my_custom_listener = MyCustomListener() +``` + +3. `__init__.py`에서 리스너 인스턴스를 임포트하여 로드되도록 합니다: + +```python +# __init__.py +from .my_custom_listener import my_custom_listener +from .another_listener import another_listener + +# 다른 곳에서 접근이 필요하다면 익스포트할 수도 있습니다 +__all__ = ['my_custom_listener', 'another_listener'] +``` + +4. Crew나 Flow 파일에서 리스너 패키지를 임포트합니다: + +```python +# crew.py 또는 flow.py 파일 내에서 +import my_project.listeners # 모든 리스너가 로드됩니다 + +class MyCustomCrew: + # Your crew implementation... +``` + +이것이 CrewAI 코드베이스에서 서드파티 이벤트 리스너가 등록되는 방식입니다. + +## 사용 가능한 이벤트 유형 + +CrewAI는 여러분이 청취할 수 있는 다양한 이벤트를 제공합니다: + +### Crew 이벤트 + +- **CrewKickoffStartedEvent**: Crew가 실행을 시작할 때 발생 +- **CrewKickoffCompletedEvent**: Crew가 실행을 완료할 때 발생 +- **CrewKickoffFailedEvent**: Crew가 실행을 완료하지 못할 때 발생 +- **CrewTestStartedEvent**: Crew가 테스트를 시작할 때 발생 +- **CrewTestCompletedEvent**: Crew가 테스트를 완료할 때 발생 +- **CrewTestFailedEvent**: Crew가 테스트를 완료하지 못할 때 발생 +- **CrewTrainStartedEvent**: Crew가 훈련을 시작할 때 발생 +- **CrewTrainCompletedEvent**: Crew가 훈련을 완료할 때 발생 +- **CrewTrainFailedEvent**: Crew가 훈련을 완료하지 못할 때 발생 +- **CrewTestResultEvent**: Crew 테스트 결과가 사용 가능할 때 발생합니다. 품질 점수, 실행 시간, 사용된 모델을 포함합니다. + +### 에이전트 이벤트 + +- **AgentExecutionStartedEvent**: 에이전트가 작업 실행을 시작할 때 발생함 +- **AgentExecutionCompletedEvent**: 에이전트가 작업 실행을 완료할 때 발생함 +- **AgentExecutionErrorEvent**: 에이전트가 실행 도중 오류를 만날 때 발생함 +- **LiteAgentExecutionStartedEvent**: LiteAgent가 실행을 시작할 때 발생합니다. 에이전트 정보, 도구, 메시지를 포함합니다. +- **LiteAgentExecutionCompletedEvent**: LiteAgent가 실행을 완료할 때 발생합니다. 에이전트 정보와 출력을 포함합니다. +- **LiteAgentExecutionErrorEvent**: LiteAgent가 실행 중 오류를 만날 때 발생합니다. 에이전트 정보와 오류 메시지를 포함합니다. +- **AgentEvaluationStartedEvent**: 에이전트 평가가 시작될 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수를 포함합니다. +- **AgentEvaluationCompletedEvent**: 에이전트 평가가 완료될 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수, 메트릭 카테고리, 점수를 포함합니다. +- **AgentEvaluationFailedEvent**: 에이전트 평가가 실패할 때 발생합니다. 에이전트 ID, 에이전트 역할, 선택적 태스크 ID, 반복 횟수, 오류 메시지를 포함합니다. + +### 작업 이벤트 + +- **TaskStartedEvent**: 작업이 실행을 시작할 때 발생 +- **TaskCompletedEvent**: 작업이 실행을 완료할 때 발생 +- **TaskFailedEvent**: 작업이 실행을 완료하지 못할 때 발생 +- **TaskEvaluationEvent**: 작업이 평가될 때 발생 + +### 도구 사용 이벤트 + +- **ToolUsageStartedEvent**: 도구 실행이 시작될 때 발생함 +- **ToolUsageFinishedEvent**: 도구 실행이 완료될 때 발생함 +- **ToolUsageErrorEvent**: 도구 실행 중 오류가 발생할 때 발생함 +- **ToolValidateInputErrorEvent**: 도구 입력 검증 중 오류가 발생할 때 발생함 +- **ToolExecutionErrorEvent**: 도구 실행 중 오류가 발생할 때 발생함 +- **ToolSelectionErrorEvent**: 도구 선택 시 오류가 발생할 때 발생함 + +### MCP 이벤트 + +- **MCPConnectionStartedEvent**: MCP 서버 연결을 시작할 때 발생합니다. 서버 이름, URL, 전송 유형, 연결 시간 초과, 재연결 시도 여부를 포함합니다. +- **MCPConnectionCompletedEvent**: MCP 서버에 성공적으로 연결될 때 발생합니다. 서버 이름, 연결 시간(밀리초), 재연결 여부를 포함합니다. +- **MCPConnectionFailedEvent**: MCP 서버 연결이 실패할 때 발생합니다. 서버 이름, 오류 메시지, 오류 유형(`timeout`, `authentication`, `network` 등)을 포함합니다. +- **MCPToolExecutionStartedEvent**: MCP 도구 실행을 시작할 때 발생합니다. 서버 이름, 도구 이름, 도구 인수를 포함합니다. +- **MCPToolExecutionCompletedEvent**: MCP 도구 실행이 성공적으로 완료될 때 발생합니다. 서버 이름, 도구 이름, 결과, 실행 시간(밀리초)을 포함합니다. +- **MCPToolExecutionFailedEvent**: MCP 도구 실행이 실패할 때 발생합니다. 서버 이름, 도구 이름, 오류 메시지, 오류 유형(`timeout`, `validation`, `server_error` 등)을 포함합니다. +- **MCPConfigFetchFailedEvent**: MCP 서버 구성을 가져오는 데 실패할 때 발생합니다(예: 계정에서 MCP가 연결되지 않았거나, API 오류, 구성을 가져온 후 연결 실패). slug, 오류 메시지, 오류 유형(`not_connected`, `api_error`, `connection_failed`)을 포함합니다. + +### 지식 이벤트 + +- **KnowledgeRetrievalStartedEvent**: 지식 검색이 시작될 때 발생 +- **KnowledgeRetrievalCompletedEvent**: 지식 검색이 완료될 때 발생 +- **KnowledgeQueryStartedEvent**: 지식 쿼리가 시작될 때 발생 +- **KnowledgeQueryCompletedEvent**: 지식 쿼리가 완료될 때 발생 +- **KnowledgeQueryFailedEvent**: 지식 쿼리가 실패할 때 발생 +- **KnowledgeSearchQueryFailedEvent**: 지식 검색 쿼리가 실패할 때 발생 + +### LLM 가드레일 이벤트 + +- **LLMGuardrailStartedEvent**: 가드레일 검증이 시작될 때 발생합니다. 적용되는 가드레일에 대한 세부 정보와 재시도 횟수를 포함합니다. +- **LLMGuardrailCompletedEvent**: 가드레일 검증이 완료될 때 발생합니다. 검증의 성공/실패, 결과 및 오류 메시지(있는 경우)에 대한 세부 정보를 포함합니다. +- **LLMGuardrailFailedEvent**: 가드레일 검증이 실패할 때 발생합니다. 오류 메시지와 재시도 횟수를 포함합니다. + +### Flow 이벤트 + +- **FlowCreatedEvent**: Flow가 생성될 때 발생 +- **FlowStartedEvent**: Flow가 실행을 시작할 때 발생 +- **FlowFinishedEvent**: Flow가 실행을 완료할 때 발생 +- **FlowPausedEvent**: 사람의 피드백을 기다리며 Flow가 일시 중지될 때 발생합니다. Flow 이름, Flow ID, 메서드 이름, 현재 상태, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다. +- **FlowPlotEvent**: Flow가 플롯될 때 발생 +- **MethodExecutionStartedEvent**: Flow 메서드가 실행을 시작할 때 발생 +- **MethodExecutionFinishedEvent**: Flow 메서드가 실행을 완료할 때 발생 +- **MethodExecutionFailedEvent**: Flow 메서드가 실행을 완료하지 못할 때 발생 +- **MethodExecutionPausedEvent**: 사람의 피드백을 기다리며 Flow 메서드가 일시 중지될 때 발생합니다. Flow 이름, 메서드 이름, 현재 상태, Flow ID, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다. + +### Human In The Loop 이벤트 + +- **FlowInputRequestedEvent**: `Flow.ask()`를 통해 Flow가 사용자 입력을 요청할 때 발생합니다. Flow 이름, 메서드 이름, 사용자에게 표시되는 질문 또는 프롬프트, 선택적 메타데이터(예: 사용자 ID, 채널, 세션 컨텍스트)를 포함합니다. +- **FlowInputReceivedEvent**: `Flow.ask()` 이후 사용자 입력이 수신될 때 발생합니다. Flow 이름, 메서드 이름, 원래 질문, 사용자의 응답(시간 초과 시 `None`), 선택적 요청 메타데이터, 프로바이더의 선택적 응답 메타데이터(예: 응답자, 스레드 ID, 타임스탬프)를 포함합니다. +- **HumanFeedbackRequestedEvent**: `@human_feedback` 데코레이터가 적용된 메서드가 사람 리뷰어의 입력을 필요로 할 때 발생합니다. Flow 이름, 메서드 이름, 사람에게 검토를 위해 표시되는 메서드 출력, 피드백 요청 시 표시되는 메시지, 라우팅을 위한 선택적 결과 목록을 포함합니다. +- **HumanFeedbackReceivedEvent**: `@human_feedback` 데코레이터가 적용된 메서드에 대해 사람이 피드백을 제공할 때 발생합니다. Flow 이름, 메서드 이름, 사람이 제공한 원본 텍스트 피드백, 축약된 결과 문자열(emit이 지정된 경우)을 포함합니다. + +### LLM 이벤트 + +- **LLMCallStartedEvent**: LLM 호출이 시작될 때 발생 +- **LLMCallCompletedEvent**: LLM 호출이 완료될 때 발생 +- **LLMCallFailedEvent**: LLM 호출이 실패할 때 발생 +- **LLMStreamChunkEvent**: 스트리밍 LLM 응답 중 각 청크를 받을 때마다 발생 +- **LLMThinkingChunkEvent**: thinking 모델에서 사고/추론 청크가 수신될 때 발생합니다. 청크 텍스트와 선택적 응답 ID를 포함합니다. + +### 메모리 이벤트 + +- **MemoryQueryStartedEvent**: 메모리 쿼리가 시작될 때 발생합니다. 쿼리, limit, 선택적 score threshold를 포함합니다. +- **MemoryQueryCompletedEvent**: 메모리 쿼리가 성공적으로 완료될 때 발생합니다. 쿼리, 결과, limit, score threshold, 쿼리 실행 시간을 포함합니다. +- **MemoryQueryFailedEvent**: 메모리 쿼리 실행에 실패할 때 발생합니다. 쿼리, limit, score threshold, 오류 메시지를 포함합니다. +- **MemorySaveStartedEvent**: 메모리 저장 작업이 시작될 때 발생합니다. 저장할 값, 메타데이터, 선택적 agent 역할을 포함합니다. +- **MemorySaveCompletedEvent**: 메모리 저장 작업이 성공적으로 완료될 때 발생합니다. 저장된 값, 메타데이터, agent 역할, 저장 실행 시간을 포함합니다. +- **MemorySaveFailedEvent**: 메모리 저장 작업에 실패할 때 발생합니다. 값, 메타데이터, agent 역할, 오류 메시지를 포함합니다. +- **MemoryRetrievalStartedEvent**: 태스크 프롬프트를 위한 메모리 검색이 시작될 때 발생합니다. 선택적 태스크 ID를 포함합니다. +- **MemoryRetrievalCompletedEvent**: 태스크 프롬프트를 위한 메모리 검색이 성공적으로 완료될 때 발생합니다. 태스크 ID, 메모리 내용, 검색 실행 시간을 포함합니다. +- **MemoryRetrievalFailedEvent**: 태스크 프롬프트를 위한 메모리 검색이 실패할 때 발생합니다. 선택적 태스크 ID와 오류 메시지를 포함합니다. + +### 추론 이벤트 + +- **AgentReasoningStartedEvent**: 에이전트가 태스크에 대한 추론을 시작할 때 발생합니다. 에이전트 역할, 태스크 ID, 시도 횟수를 포함합니다. +- **AgentReasoningCompletedEvent**: 에이전트가 추론 과정을 마칠 때 발생합니다. 에이전트 역할, 태스크 ID, 생성된 계획, 에이전트가 진행할 준비가 되었는지 여부를 포함합니다. +- **AgentReasoningFailedEvent**: 추론 과정이 실패할 때 발생합니다. 에이전트 역할, 태스크 ID, 오류 메시지를 포함합니다. + +### 관찰 이벤트 + +- **StepObservationStartedEvent**: Planner가 단계 결과를 관찰하기 시작할 때 발생합니다. 매 단계 실행 후, 관찰 LLM 호출 전에 발생합니다. 에이전트 역할, 단계 번호, 단계 설명을 포함합니다. +- **StepObservationCompletedEvent**: Planner가 단계 결과 관찰을 마칠 때 발생합니다. 단계 성공 여부, 학습된 핵심 정보, 남은 계획의 유효성, 전체 재계획 필요 여부, 제안된 개선 사항을 포함합니다. +- **StepObservationFailedEvent**: 관찰 LLM 호출 자체가 실패할 때 발생합니다. 시스템은 기본적으로 계획을 계속 진행합니다. 오류 메시지를 포함합니다. +- **PlanRefinementEvent**: Planner가 전체 재계획 없이 다음 단계 설명을 개선할 때 발생합니다. 개선된 단계 수와 적용된 개선 사항을 포함합니다. +- **PlanReplanTriggeredEvent**: 남은 계획이 근본적으로 잘못된 것으로 판단되어 Planner가 전체 재계획을 트리거할 때 발생합니다. 재계획 이유, 재계획 횟수, 보존된 완료 단계 수를 포함합니다. +- **GoalAchievedEarlyEvent**: Planner가 목표가 조기에 달성되었음을 감지하고 나머지 단계를 건너뛸 때 발생합니다. 남은 단계 수와 완료된 단계 수를 포함합니다. + +### A2A (Agent-to-Agent) 이벤트 + +#### 위임 이벤트 + +- **A2ADelegationStartedEvent**: A2A 위임이 시작될 때 발생합니다. 엔드포인트 URL, 태스크 설명, 에이전트 ID, 컨텍스트 ID, 멀티턴 여부, 턴 번호, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보, 선택적 skill ID를 포함합니다. +- **A2ADelegationCompletedEvent**: A2A 위임이 완료될 때 발생합니다. 완료 상태(`completed`, `input_required`, `failed` 등), 결과, 오류 메시지, 컨텍스트 ID, agent card 메타데이터를 포함합니다. +- **A2AParallelDelegationStartedEvent**: 여러 A2A 에이전트로의 병렬 위임이 시작될 때 발생합니다. 엔드포인트 목록과 태스크 설명을 포함합니다. +- **A2AParallelDelegationCompletedEvent**: 여러 A2A 에이전트로의 병렬 위임이 완료될 때 발생합니다. 엔드포인트 목록, 성공 수, 실패 수, 결과 요약을 포함합니다. + +#### 대화 이벤트 + +- **A2AConversationStartedEvent**: 멀티턴 A2A 대화 시작 시 한 번 발생합니다. 첫 번째 메시지 교환 전에 발생합니다. 에이전트 ID, 엔드포인트, 컨텍스트 ID, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보를 포함합니다. +- **A2AMessageSentEvent**: A2A 에이전트에 메시지가 전송될 때 발생합니다. 메시지 내용, 턴 번호, 컨텍스트 ID, 메시지 ID, 멀티턴 여부를 포함합니다. +- **A2AResponseReceivedEvent**: A2A 에이전트로부터 응답이 수신될 때 발생합니다. 응답 내용, 턴 번호, 컨텍스트 ID, 메시지 ID, 상태, 최종 응답 여부를 포함합니다. +- **A2AConversationCompletedEvent**: 멀티턴 A2A 대화 종료 시 한 번 발생합니다. 최종 상태(`completed` 또는 `failed`), 최종 결과, 오류 메시지, 컨텍스트 ID, 총 턴 수를 포함합니다. + +#### 스트리밍 이벤트 + +- **A2AStreamingStartedEvent**: A2A 위임을 위한 스트리밍 모드가 시작될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 엔드포인트, 턴 번호, 멀티턴 여부를 포함합니다. +- **A2AStreamingChunkEvent**: 스트리밍 청크가 수신될 때 발생합니다. 청크 텍스트, 청크 인덱스, 최종 청크 여부, 태스크 ID, 컨텍스트 ID, 턴 번호를 포함합니다. + +#### 폴링 및 푸시 알림 이벤트 + +- **A2APollingStartedEvent**: A2A 위임을 위한 폴링 모드가 시작될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 폴링 간격(초), 엔드포인트를 포함합니다. +- **A2APollingStatusEvent**: 각 폴링 반복 시 발생합니다. 태스크 ID, 컨텍스트 ID, 현재 태스크 상태, 경과 시간, 폴링 횟수를 포함합니다. +- **A2APushNotificationRegisteredEvent**: 푸시 알림 콜백이 등록될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 콜백 URL, 엔드포인트를 포함합니다. +- **A2APushNotificationReceivedEvent**: 원격 A2A 에이전트로부터 푸시 알림이 수신될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 현재 상태를 포함합니다. +- **A2APushNotificationSentEvent**: 콜백 URL로 푸시 알림이 전송될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 콜백 URL, 상태, 전달 성공 여부, 선택적 오류 메시지를 포함합니다. +- **A2APushNotificationTimeoutEvent**: 푸시 알림 대기가 시간 초과될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 시간 초과 시간(초)을 포함합니다. + +#### 연결 및 인증 이벤트 + +- **A2AAgentCardFetchedEvent**: agent card가 성공적으로 가져올 때 발생합니다. 엔드포인트, 에이전트 이름, agent card 메타데이터, 프로토콜 버전, 프로바이더 정보, 캐시 여부, 가져오기 시간(밀리초)을 포함합니다. +- **A2AAuthenticationFailedEvent**: A2A 에이전트 인증이 실패할 때 발생합니다. 엔드포인트, 시도된 인증 유형(예: `bearer`, `oauth2`, `api_key`), 오류 메시지, HTTP 상태 코드를 포함합니다. +- **A2AConnectionErrorEvent**: A2A 통신 중 연결 오류가 발생할 때 발생합니다. 엔드포인트, 오류 메시지, 오류 유형(예: `timeout`, `connection_refused`, `dns_error`), HTTP 상태 코드, 시도 중인 작업을 포함합니다. +- **A2ATransportNegotiatedEvent**: A2A 에이전트와 전송 프로토콜이 협상될 때 발생합니다. 협상된 전송, 협상된 URL, 선택 소스(`client_preferred`, `server_preferred`, `fallback`), 클라이언트/서버 지원 전송을 포함합니다. +- **A2AContentTypeNegotiatedEvent**: A2A 에이전트와 콘텐츠 유형이 협상될 때 발생합니다. 클라이언트/서버 입출력 모드, 협상된 입출력 모드, 협상 성공 여부를 포함합니다. + +#### 아티팩트 이벤트 + +- **A2AArtifactReceivedEvent**: 원격 A2A 에이전트로부터 아티팩트가 수신될 때 발생합니다. 태스크 ID, 아티팩트 ID, 아티팩트 이름, 설명, MIME 유형, 크기(바이트), 콘텐츠 추가 여부를 포함합니다. + +#### 서버 태스크 이벤트 + +- **A2AServerTaskStartedEvent**: A2A 서버 태스크 실행이 시작될 때 발생합니다. 태스크 ID와 컨텍스트 ID를 포함합니다. +- **A2AServerTaskCompletedEvent**: A2A 서버 태스크 실행이 완료될 때 발생합니다. 태스크 ID, 컨텍스트 ID, 결과를 포함합니다. +- **A2AServerTaskCanceledEvent**: A2A 서버 태스크 실행이 취소될 때 발생합니다. 태스크 ID와 컨텍스트 ID를 포함합니다. +- **A2AServerTaskFailedEvent**: A2A 서버 태스크 실행이 실패할 때 발생합니다. 태스크 ID, 컨텍스트 ID, 오류 메시지를 포함합니다. + +#### 컨텍스트 수명 주기 이벤트 + +- **A2AContextCreatedEvent**: A2A 컨텍스트가 생성될 때 발생합니다. 컨텍스트는 대화 또는 워크플로우에서 관련 태스크를 그룹화합니다. 컨텍스트 ID와 생성 타임스탬프를 포함합니다. +- **A2AContextExpiredEvent**: TTL로 인해 A2A 컨텍스트가 만료될 때 발생합니다. 컨텍스트 ID, 생성 타임스탬프, 수명(초), 태스크 수를 포함합니다. +- **A2AContextIdleEvent**: A2A 컨텍스트가 유휴 상태가 될 때(설정된 임계값 동안 활동 없음) 발생합니다. 컨텍스트 ID, 유휴 시간(초), 태스크 수를 포함합니다. +- **A2AContextCompletedEvent**: A2A 컨텍스트의 모든 태스크가 완료될 때 발생합니다. 컨텍스트 ID, 총 태스크 수, 지속 시간(초)을 포함합니다. +- **A2AContextPrunedEvent**: A2A 컨텍스트가 정리(삭제)될 때 발생합니다. 컨텍스트 ID, 태스크 수, 수명(초)을 포함합니다. + +## 이벤트 핸들러 구조 + +각 이벤트 핸들러는 두 개의 매개변수를 받습니다: + +1. **source**: 이벤트를 발생시킨 객체 +2. **event**: 이벤트별 데이터를 포함하는 이벤트 인스턴스 + +이벤트 객체의 구조는 이벤트 타입에 따라 다르지만, 모든 이벤트는 `BaseEvent`를 상속하며 다음을 포함합니다: + +- **timestamp**: 이벤트가 발생한 시간 +- **type**: 이벤트 타입을 나타내는 문자열 식별자 + +추가 필드는 이벤트 타입에 따라 다릅니다. 예를 들어, `CrewKickoffCompletedEvent`에는 `crew_name`과 `output` 필드가 포함됩니다. + + +## 고급 사용법: Scoped Handlers + +임시 이벤트 처리가 필요한 경우(테스트 또는 특정 작업에 유용함), `scoped_handlers` 컨텍스트 관리자를 사용할 수 있습니다: + +```python +from crewai.events import crewai_event_bus, CrewKickoffStartedEvent + +with crewai_event_bus.scoped_handlers(): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def temp_handler(source, event): + print("This handler only exists within this context") + + # Do something that emits events + +# 컨텍스트 밖에서는 임시 핸들러가 제거됩니다 +``` + +## 사용 사례 + +이벤트 리스너는 다양한 목적으로 사용할 수 있습니다: + +1. **로깅 및 모니터링**: Crew의 실행을 추적하고 중요한 이벤트를 기록합니다 +2. **분석**: Crew의 성능과 동작에 대한 데이터를 수집합니다 +3. **디버깅**: 특정 문제를 디버깅하기 위해 임시 리스너를 설정합니다 +4. **통합**: CrewAI를 모니터링 플랫폼, 데이터베이스 또는 알림 서비스와 같은 외부 시스템과 연결합니다 +5. **사용자 정의 동작**: 특정 이벤트에 따라 사용자 정의 동작을 트리거합니다 + +## 모범 사례 + +1. **핸들러를 가볍게 유지하세요**: 이벤트 핸들러는 경량이어야 하며, 블로킹 작업을 피해야 합니다. +2. **오류 처리**: 예외가 메인 실행에 영향을 주지 않도록 이벤트 핸들러에 적절한 오류 처리를 포함하세요. +3. **정리**: 리스너가 자원을 할당한다면, 이를 적절하게 정리하는지 확인하세요. +4. **선택적 리스닝**: 실제로 처리해야 하는 이벤트에만 리스닝하세요. +5. **테스트**: 이벤트 리스너가 예상대로 동작하는지 독립적으로 테스트하세요. + +CrewAI의 이벤트 시스템을 활용하면 기능을 확장하고 기존 인프라와 원활하게 통합할 수 있습니다. diff --git a/docs/v1.15.1/ko/concepts/files.mdx b/docs/v1.15.1/ko/concepts/files.mdx new file mode 100644 index 000000000..c07a39fad --- /dev/null +++ b/docs/v1.15.1/ko/concepts/files.mdx @@ -0,0 +1,267 @@ +--- +title: 파일 +description: 멀티모달 처리를 위해 이미지, PDF, 오디오, 비디오, 텍스트 파일을 에이전트에 전달하세요. +icon: file-image +--- + +## 개요 + +CrewAI는 네이티브 멀티모달 파일 입력을 지원하여 이미지, PDF, 오디오, 비디오, 텍스트 파일을 에이전트에 직접 전달할 수 있습니다. 파일은 각 LLM 프로바이더의 API 요구사항에 맞게 자동으로 포맷됩니다. + + +파일 지원을 위해서는 선택적 `crewai-files` 패키지가 필요합니다. 다음 명령어로 설치하세요: + +```bash +uv add 'crewai[file-processing]' +``` + + + +파일 처리 API는 현재 얼리 액세스 단계입니다. + + +## 파일 타입 + +CrewAI는 5가지 특정 파일 타입과 타입을 자동 감지하는 일반 `File` 클래스를 지원합니다: + +| 타입 | 클래스 | 사용 사례 | +|:-----|:------|:----------| +| **이미지** | `ImageFile` | 사진, 스크린샷, 다이어그램, 차트 | +| **PDF** | `PDFFile` | 문서, 보고서, 논문 | +| **오디오** | `AudioFile` | 음성 녹음, 팟캐스트, 회의 | +| **비디오** | `VideoFile` | 화면 녹화, 프레젠테이션 | +| **텍스트** | `TextFile` | 코드 파일, 로그, 데이터 파일 | +| **일반** | `File` | 콘텐츠에서 타입 자동 감지 | + +```python +from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile + +image = ImageFile(source="screenshot.png") +pdf = PDFFile(source="report.pdf") +audio = AudioFile(source="meeting.mp3") +video = VideoFile(source="demo.mp4") +text = TextFile(source="data.csv") + +file = File(source="document.pdf") +``` + +## 파일 소스 + +`source` 파라미터는 여러 입력 타입을 받아들이고 적절한 핸들러를 자동으로 감지합니다: + +### 경로에서 + +```python +from crewai_files import ImageFile + +image = ImageFile(source="./images/chart.png") +``` + +### URL에서 + +```python +from crewai_files import ImageFile + +image = ImageFile(source="https://example.com/image.png") +``` + +### 바이트에서 + +```python +from crewai_files import ImageFile, FileBytes + +image_bytes = download_image_from_api() +image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png")) +image = ImageFile(source=image_bytes) +``` + +## 파일 사용하기 + +파일은 여러 레벨에서 전달할 수 있으며, 더 구체적인 레벨이 우선순위를 가집니다. + +### Crew와 함께 + +crew를 킥오프할 때 파일을 전달합니다: + +```python +from crewai import Crew +from crewai_files import ImageFile + +crew = Crew(agents=[analyst], tasks=[analysis_task]) + +result = crew.kickoff( + inputs={"topic": "Q4 Sales"}, + input_files={ + "chart": ImageFile(source="sales_chart.png"), + "report": PDFFile(source="quarterly_report.pdf"), + } +) +``` + +### Task와 함께 + +특정 작업에 파일을 첨부합니다: + +```python +from crewai import Task +from crewai_files import ImageFile + +task = Task( + description="매출 차트를 분석하고 {chart}에서 트렌드를 파악하세요", + expected_output="주요 트렌드 요약", + input_files={ + "chart": ImageFile(source="sales_chart.png"), + } +) +``` + +### Flow와 함께 + +flow에 파일을 전달하면 자동으로 crew에 상속됩니다: + +```python +from crewai.flow.flow import Flow, start +from crewai_files import ImageFile + +class AnalysisFlow(Flow): + @start() + def analyze(self): + return self.analysis_crew.kickoff() + +flow = AnalysisFlow() +result = flow.kickoff( + input_files={"image": ImageFile(source="data.png")} +) +``` + +### 단독 에이전트와 함께 + +에이전트 킥오프에 직접 파일을 전달합니다: + +```python +from crewai import Agent +from crewai_files import ImageFile + +agent = Agent( + role="Image Analyst", + goal="Analyze images", + backstory="Expert at visual analysis", + llm="gpt-4o", +) + +result = agent.kickoff( + messages="What's in this image?", + input_files={"photo": ImageFile(source="photo.jpg")}, +) +``` + +## 파일 우선순위 + +여러 레벨에서 파일이 전달될 때, 더 구체적인 레벨이 상위 레벨을 오버라이드합니다: + +``` +Flow input_files < Crew input_files < Task input_files +``` + +예를 들어, Flow와 Task 모두 `"chart"`라는 이름의 파일을 정의하면, Task의 버전이 사용됩니다. + +## 프로바이더 지원 + +각 프로바이더는 서로 다른 파일 타입을 지원합니다. CrewAI는 각 프로바이더의 API에 맞게 파일을 자동으로 포맷합니다. + +| 프로바이더 | 이미지 | PDF | 오디오 | 비디오 | 텍스트 | +|:---------|:-----:|:---:|:-----:|:-----:|:----:| +| **OpenAI** (completions API) | ✓ | | | | | +| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | | +| **Anthropic** (claude-3.x) | ✓ | ✓ | | | | +| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ | +| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | | +| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | | + + +Google Gemini 모델은 비디오를 포함한 모든 파일 타입을 지원합니다 (최대 1시간, 2GB). 비디오 콘텐츠를 처리해야 할 때 Gemini를 사용하세요. + + + +프로바이더가 지원하지 않는 파일 타입을 전달하면 (예: OpenAI에 비디오) `UnsupportedFileTypeError`가 발생합니다. 처리해야 하는 파일 타입에 따라 프로바이더를 선택하세요. + + +## 파일 전송 방식 + +CrewAI는 각 프로바이더에 파일을 전송하는 최적의 방법을 자동으로 선택합니다: + +| 방식 | 설명 | 사용 조건 | +|:-------|:------------|:----------| +| **인라인 Base64** | 파일이 요청에 직접 임베드됨 | 작은 파일 (일반적으로 < 5MB) | +| **파일 업로드 API** | 파일이 별도로 업로드되고 ID로 참조됨 | 임계값을 초과하는 큰 파일 | +| **URL 참조** | 직접 URL이 모델에 전달됨 | 파일 소스가 이미 URL인 경우 | + +### 프로바이더 전송 방식 + +| 프로바이더 | 인라인 Base64 | 파일 업로드 API | URL 참조 | +|:---------|:-------------:|:---------------:|:--------------:| +| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ | +| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ | +| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ | +| **AWS Bedrock** | ✓ | | ✓ (S3 URI) | +| **Azure OpenAI** | ✓ | | ✓ | + + +이를 직접 관리할 필요가 없습니다. CrewAI는 파일 크기와 프로바이더 기능에 따라 가장 효율적인 방법을 자동으로 사용합니다. 파일 업로드 API가 없는 프로바이더는 모든 파일에 인라인 base64를 사용합니다. + + +## 파일 처리 모드 + +프로바이더 제한을 초과할 때 파일 처리 방식을 제어합니다: + +```python +from crewai_files import ImageFile, PDFFile + +image = ImageFile(source="large.png", mode="strict") +image = ImageFile(source="large.png", mode="auto") +image = ImageFile(source="large.png", mode="warn") +pdf = PDFFile(source="large.pdf", mode="chunk") +``` + +## 프로바이더 제약사항 + +각 프로바이더는 파일 크기와 규격에 대한 특정 제한이 있습니다: + +### OpenAI +- **이미지**: 최대 20 MB, 요청당 최대 10개 이미지 +- **PDF**: 최대 32 MB, 최대 100 페이지 +- **오디오**: 최대 25 MB, 최대 25분 + +### Anthropic +- **이미지**: 최대 5 MB, 최대 8000x8000 픽셀, 최대 100개 이미지 +- **PDF**: 최대 32 MB, 최대 100 페이지 + +### Google Gemini +- **이미지**: 최대 100 MB +- **PDF**: 최대 50 MB +- **오디오**: 최대 100 MB, 최대 9.5시간 +- **비디오**: 최대 2 GB, 최대 1시간 + +### AWS Bedrock +- **이미지**: 최대 4.5 MB, 최대 8000x8000 픽셀 +- **PDF**: 최대 3.75 MB, 최대 100 페이지 + +## 프롬프트에서 파일 참조하기 + +작업 설명에서 파일의 키 이름을 사용하여 파일을 참조합니다: + +```python +task = Task( + description=""" + 제공된 자료를 분석하세요: + 1. {sales_chart}에서 차트 검토 + 2. {quarterly_report}의 데이터와 교차 참조 + 3. 주요 발견사항 요약 + """, + expected_output="주요 인사이트가 포함된 분석 요약", + input_files={ + "sales_chart": ImageFile(source="chart.png"), + "quarterly_report": PDFFile(source="report.pdf"), + } +) +``` diff --git a/docs/v1.15.1/ko/concepts/flows.mdx b/docs/v1.15.1/ko/concepts/flows.mdx new file mode 100644 index 000000000..e168b7e3f --- /dev/null +++ b/docs/v1.15.1/ko/concepts/flows.mdx @@ -0,0 +1,1057 @@ +--- +title: Flows +description: CrewAI Flows를 사용하여 AI 워크플로우를 생성하고 관리하는 방법을 알아보세요. +icon: arrow-progress +mode: "wide" +--- + +## 개요 + +CrewAI Flows는 AI 워크플로우의 생성 및 관리를 간소화하기 위해 설계된 강력한 기능입니다. Flows를 사용하면 개발자는 다양한 코딩 작업과 각 Crew를 효율적으로 결합하고 조정할 수 있어, 정교한 AI 자동화를 구축할 수 있는 견고한 프레임워크를 제공합니다. + +Flows는 구조화된 이벤트 기반 워크플로우를 생성할 수 있게 해줍니다. 이를 통해 여러 작업을 원활하게 연결하고, 상태를 관리하며, AI 애플리케이션에서 실행 흐름을 제어할 수 있습니다. Flows를 사용하면 CrewAI의 전체 역량을 활용하는 다단계 프로세스를 손쉽게 설계하고 구현할 수 있습니다. + +1. **간편한 워크플로우 생성**: 여러 Crew와 작업을 손쉽게 연결하여 복잡한 AI 워크플로우를 만듭니다. + +2. **상태 관리**: Flows를 통해 워크플로우 내의 다양한 작업 간에 상태를 쉽고 효율적으로 관리 및 공유할 수 있습니다. + +3. **이벤트 기반 아키텍처**: 이벤트 기반 모델을 기반으로 하여, 역동적이고 반응성 높은 워크플로우를 구현할 수 있습니다. + +4. **유연한 제어 흐름**: 워크플로우 내에서 조건문, 반복문, 분기 등을 구현할 수 있습니다. + +## 시작하기 + +OpenAI를 사용하여 한 작업에서 무작위 도시를 생성하고, 그 도시를 사용해 다른 작업에서 재미있는 사실을 생성하는 간단한 Flow를 만들어보겠습니다. + +```python Code + +from crewai.flow.flow import Flow, listen, start +from dotenv import load_dotenv +from litellm import completion + +load_dotenv() + +class ExampleFlow(Flow): + model = "gpt-4o-mini" + + @start() + def generate_city(self): + print("Starting flow") + # Each flow state automatically gets a unique ID + print(f"Flow State ID: {self.state['id']}") + + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": "Return the name of a random city in the world.", + }, + ], + ) + + random_city = response["choices"][0]["message"]["content"] + # Store the city in our state + self.state["city"] = random_city + print(f"Random City: {random_city}") + + return random_city + + @listen(generate_city) + def generate_fun_fact(self, random_city): + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": f"Tell me a fun fact about {random_city}", + }, + ], + ) + + fun_fact = response["choices"][0]["message"]["content"] + # Store the fun fact in our state + self.state["fun_fact"] = fun_fact + return fun_fact + + + +flow = ExampleFlow() +flow.plot() +result = flow.kickoff() + +print(f"Generated fun fact: {result}") +``` +![Flow Visual image](/images/crewai-flow-1.png) +위 예제에서는 OpenAI를 사용하여 무작위 도시를 생성하고, 해당 도시에 대한 재미있는 사실을 생성하는 간단한 Flow를 만들었습니다. 이 Flow는 `generate_city`와 `generate_fun_fact`라는 두 가지 작업으로 구성되어 있습니다. `generate_city` 작업이 Flow의 시작점이며, `generate_fun_fact` 작업이 `generate_city` 작업의 출력을 감지합니다. + +각 Flow 인스턴스는 상태(state)에 자동으로 고유 식별자(UUID)를 부여 받아, 흐름 실행을 추적하고 관리하는 데 도움이 됩니다. 상태에는 실행 중에 유지되는 추가 데이터(예: 생성된 도시와 재미있는 사실)도 저장할 수 있습니다. + +Flow를 실행하면 다음과 같은 과정을 따릅니다: +1. 상태를 위한 고유 ID를 생성 +2. 무작위 도시를 생성하여 상태에 저장 +3. 해당 도시에 대한 재미있는 사실을 생성하여 상태에 저장 +4. 결과를 콘솔에 출력 + +상태의 고유 ID와 저장된 데이터는 흐름 실행을 추적하고, 작업 간의 컨텍스트를 유지하는 데 유용합니다. + +**참고:** OpenAI API 요청 인증을 위해 `OPENAI_API_KEY`를 `.env` 파일에 설정해야 합니다. 이 키는 필수입니다. + +### @start() + +`@start()` 데코레이터는 메서드를 Flow의 시작 지점으로 표시하는 데 사용됩니다. Flow가 시작되면 `@start()`로 데코레이트된 모든 메서드가 병렬로 실행됩니다. 하나의 Flow에서 여러 개의 start 메서드를 가질 수 있으며, Flow가 시작될 때 이들은 모두 실행됩니다. + +### @listen() + +`@listen()` 데코레이터는 Flow 내에서 다른 태스크의 출력을 수신하는 리스너로 메서드를 표시하는 데 사용됩니다. `@listen()`으로 데코레이션된 메서드는 지정된 태스크가 출력을 내보낼 때 실행됩니다. 이 메서드는 자신이 리스닝하고 있는 태스크의 출력을 인자로 접근할 수 있습니다. + +#### 사용법 + +`@listen()` 데코레이터는 여러 가지 방법으로 사용할 수 있습니다: + +1. **메서드 이름으로 리스닝하기**: 리스닝하고자 하는 메서드의 이름을 문자열로 전달할 수 있습니다. 해당 메서드가 완료되면, 리스너 메서드가 트리거됩니다. + + ```python Code + @listen("generate_city") + def generate_fun_fact(self, random_city): + # Implementation + ``` + +2. **메서드 자체로 리스닝하기**: 메서드 자체를 전달할 수도 있습니다. 해당 메서드가 완료되면, 리스너 메서드가 트리거됩니다. + ```python Code + @listen(generate_city) + def generate_fun_fact(self, random_city): + # Implementation + ``` + +### Flow 출력 + +Flow의 출력을 접근하고 다루는 것은 AI 워크플로우를 더 큰 애플리케이션이나 시스템에 통합하는 데 필수적입니다. CrewAI Flow는 최종 출력물을 쉽게 가져오고, 중간 결과에 접근하며, Flow의 전체 상태를 관리할 수 있는 직관적인 메커니즘을 제공합니다. + +#### 최종 출력값 가져오기 + +Flow를 실행하면, 최종 출력값은 마지막으로 완료된 메서드에 의해 결정됩니다. `kickoff()` 메서드는 이 마지막 메서드의 결과를 반환합니다. + +최종 출력값을 확인하는 방법은 다음과 같습니다: + + +```python Code +from crewai.flow.flow import Flow, listen, start + +class OutputExampleFlow(Flow): + @start() + def first_method(self): + return "Output from first_method" + + @listen(first_method) + def second_method(self, first_output): + return f"Second method received: {first_output}" + + +flow = OutputExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() + +print("---- Final Output ----") +print(final_output) +``` + +```text Output +---- Final Output ---- +Second method received: Output from first_method +``` + + +![Flow Visual image](/images/crewai-flow-2.png) + +이 예제에서 `second_method`가 마지막으로 완료된 메서드이므로, 해당 메서드의 결과가 Flow의 최종 출력값이 됩니다. +`kickoff()` 메서드는 이 최종 출력값을 반환하며, 이 값은 콘솔에 출력됩니다. +`plot()` 메서드는 HTML 파일을 생성하며, 이를 통해 flow를 쉽게 이해할 수 있습니다. + +#### 상태에 접근하고 업데이트하기 + +최종 출력을 가져오는 것 외에도, Flow 내에서 상태(state)에 접근하고 업데이트할 수 있습니다. 상태는 Flow의 다양한 메소드 간 데이터를 저장하고 공유하는 데 사용할 수 있습니다. Flow가 실행된 후에는, 실행 중에 추가되거나 업데이트된 정보를 조회하기 위해 상태에 접근할 수 있습니다. + +다음은 상태를 업데이트하고 접근하는 방법의 예시입니다: + + + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class StateExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + self.state.message = "Hello from first_method" + self.state.counter += 1 + + @listen(first_method) + def second_method(self): + self.state.message += " - updated by second_method" + self.state.counter += 1 + return self.state.message + +flow = StateExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() +print(f"Final Output: {final_output}") +print("Final State:") +print(flow.state) +``` + +```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) + +이 예시에서 상태는 `first_method`와 `second_method` 모두에 의해 업데이트됩니다. +Flow가 실행된 후, 이러한 메소드들에 의해 수행된 업데이트 내용을 확인하려면 최종 상태에 접근할 수 있습니다. + +최종 메소드의 출력이 반환되고 상태에 접근할 수 있도록 함으로써, CrewAI Flow는 AI 워크플로우의 결과를 더 큰 애플리케이션이나 시스템에 쉽게 통합할 수 있게 하며, +Flow 실행 과정 전반에 걸쳐 상태를 유지하고 접근하면서도 이를 용이하게 만듭니다. + +## 플로우 사용 메트릭 + +Flow 실행이 완료된 후, `usage_metrics` 속성에 접근하여 실행 동안 발생한 **모든 LLM 호출**의 토큰 사용량 집계를 확인할 수 있습니다. 여기에는 Flow가 오케스트레이션한 모든 Crew의 호출, Agent의 도구 내부에서 발생한 호출, 그리고 Flow 메서드에서 직접 호출한 `LLM.call(...)`이 모두 포함됩니다. 이는 CrewAI Enterprise UI에 표시되는 총량과 동등한 SDK 측 값입니다. + +```python Code +from crewai import LLM +from crewai.flow.flow import Flow, listen, start + +class UsageMetricsFlow(Flow): + @start() + def run_first_crew(self): + self.state.first_result = FirstCrew().crew().kickoff() + + @listen(run_first_crew) + def call_llm_directly(self): + # 직접 LLM 호출 — flow.usage_metrics에서도 집계됩니다 + llm = LLM(model="openai/gpt-4o-mini") + self.state.summary = llm.call("핵심 내용을 요약해 주세요.") + + @listen(call_llm_directly) + def run_second_crew(self): + self.state.second_result = SecondCrew().crew().kickoff() + +flow = UsageMetricsFlow() +flow.kickoff() + +print(flow.usage_metrics) +# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369, +# cached_prompt_tokens=0, reasoning_tokens=0, +# cache_creation_tokens=0, successful_requests=5) +``` + + + `flow.usage_metrics`는 `flow.kickoff().token_usage`와 **동일하지 않습니다**. + 후자는 `CrewOutput`을 반환한 **마지막** `@listen` 메서드의 + `CrewOutput.token_usage`만 반환하므로, 이전에 실행된 Crew들과 Flow 메서드에서 + 직접 호출한 `LLM.call(...)`은 전혀 포함되지 않습니다. Flow 실행에 대한 + **전체** 토큰 집계가 필요할 때는 항상 `flow.usage_metrics`를 사용하십시오. + + +반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py)의 각 항목은 단일 `flow.kickoff()` 실행 동안 발생한 모든 LLM 호출의 합계입니다. 다음 `kickoff()` 호출(및 `kickoff_for_each`의 각 반복)에서 카운터가 초기화되므로 연속 실행이 이중으로 집계되지 않습니다. 이 속성은 `kickoff()` 완료 후 언제든지 안전하게 읽을 수 있으며, 실행 중에 읽으면 그 시점까지 누적된 부분 합계를 반환합니다. + +## 플로우 상태 관리 + +상태를 효과적으로 관리하는 것은 신뢰할 수 있고 유지 보수가 용이한 AI 워크플로를 구축하는 데 매우 중요합니다. CrewAI 플로우는 비정형 및 정형 상태 관리를 위한 강력한 메커니즘을 제공하여, 개발자가 자신의 애플리케이션에 가장 적합한 접근 방식을 선택할 수 있도록 합니다. + +### 비구조적 상태 관리 + +비구조적 상태 관리에서는 모든 상태가 `Flow` 클래스의 `state` 속성에 저장됩니다. +이 방식은 엄격한 스키마를 정의하지 않고도 개발자가 상태 속성을 즉석에서 추가하거나 수정할 수 있는 유연성을 제공합니다. +비구조적 상태에서도 CrewAI Flows는 각 상태 인스턴스에 대한 고유 식별자(UUID)를 자동으로 생성하고 유지합니다. + +```python Code +from crewai.flow.flow import Flow, listen, start + +class UnstructuredExampleFlow(Flow): + + @start() + def first_method(self): + # The state automatically includes an 'id' field + print(f"State ID: {self.state['id']}") + self.state['counter'] = 0 + self.state['message'] = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated" + + @listen(second_method) + def third_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = UnstructuredExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**참고:** `id` 필드는 흐름의 실행 전체에 걸쳐 자동으로 생성되어 보존됩니다. 이를 직접 관리하거나 설정할 필요가 없으며, 새로운 데이터로 상태를 업데이트할 때도 자동으로 유지됩니다. + +**핵심 포인트:** + +- **유연성:** `self.state`에 미리 정해진 제약 없이 속성을 동적으로 추가할 수 있습니다. +- **단순성:** 상태 구조가 최소이거나 크게 달라지는 단순한 워크플로우에 이상적입니다. + +### 구조화된 상태 관리 + +구조화된 상태 관리는 미리 정의된 스키마를 활용하여 워크플로 전반에 걸쳐 일관성과 타입 안전성을 보장합니다. Pydantic의 `BaseModel`과 같은 모델을 사용하면 상태의 정확한 형태를 정의할 수 있어, 개발 환경에서 더 나은 검증 및 자동 완성이 가능합니다. + +CrewAI Flows의 각 상태는 인스턴스 추적 및 관리를 돕기 위해 자동으로 고유 식별자(UUID)를 할당받습니다. 이 ID는 Flow 시스템에 의해 자동으로 생성되고 관리됩니다. + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + + +class ExampleState(BaseModel): + # Note: 'id' field is automatically added to all states + counter: int = 0 + message: str = "" + + +class StructuredExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + # Access the auto-generated ID if needed + print(f"State ID: {self.state.id}") + self.state.message = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state.counter += 1 + self.state.message += " - updated" + + @listen(second_method) + def third_method(self): + self.state.counter += 1 + self.state.message += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = StructuredExampleFlow() +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**핵심 포인트:** + +- **정의된 스키마:** `ExampleState`는 상태 구조를 명확히 정의하여 코드 가독성과 유지보수성을 향상시킵니다. +- **타입 안전성:** Pydantic을 활용하면 상태의 속성이 지정된 타입을 준수하도록 보장하여 런타임 오류를 줄일 수 있습니다. +- **자동 완성:** IDE에서 정의된 상태 모델을 기반으로 더 나은 자동 완성과 오류 확인이 가능합니다. + +### 비구조적 상태 관리와 구조적 상태 관리 선택하기 + +- **비구조적 상태 관리를 사용할 때:** + + - 워크플로의 상태가 단순하거나 매우 동적일 때. + - 엄격한 상태 정의보다 유연성이 우선시될 때. + - 스키마 정의의 오버헤드 없이 빠른 프로토타이핑이 필요할 때. + +- **구조적 상태 관리를 사용할 때:** + - 워크플로에 잘 정의되고 일관된 상태 구조가 필요할 때. + - 애플리케이션의 신뢰성을 위해 타입 안전성과 검증이 중요할 때. + - 더 나은 개발자 경험을 위해 IDE의 자동 완성 및 타입 체크 기능을 활용하고자 할 때. + +CrewAI Flows는 비구조적 및 구조적 상태 관리 옵션을 모두 제공함으로써, 개발자들이 다양한 애플리케이션 요구 사항에 맞춰 유연하면서도 견고한 AI 워크플로를 구축할 수 있도록 지원합니다. + +## 플로우 지속성 + +@persist 데코레이터는 CrewAI 플로우에서 자동 상태 지속성을 활성화하여, 플로우 상태를 재시작이나 다른 워크플로우 실행 간에도 유지할 수 있도록 합니다. 이 데코레이터는 클래스 수준이나 메서드 수준 모두에 적용할 수 있어, 상태 지속성을 관리하는 데 유연성을 제공합니다. + +### 클래스 레벨 영속성 + +클래스 레벨에서 @persist 데코레이터를 적용하면 모든 flow 메서드 상태가 자동으로 영속됩니다: + +```python +@persist # 기본적으로 SQLiteFlowPersistence 사용 +class MyFlow(Flow[MyState]): + @start() + def initialize_flow(self): + # 이 메서드는 상태가 자동으로 영속됩니다 + self.state.counter = 1 + print("Initialized flow. State ID:", self.state.id) + + @listen(initialize_flow) + def next_step(self): + # 상태(self.state.id 포함)는 자동으로 다시 로드됩니다 + self.state.counter += 1 + print("Flow state is persisted. Counter:", self.state.counter) +``` + +### 메서드 수준의 지속성 + +더 세밀한 제어를 위해, @persist를 특정 메서드에 적용할 수 있습니다: + +```python +class AnotherFlow(Flow[dict]): + @persist # Persists only this method's state + @start() + def begin(self): + if "runs" not in self.state: + self.state["runs"] = 0 + self.state["runs"] += 1 + print("Method-level persisted runs:", self.state["runs"]) +``` + +### 영속 상태 포크하기 + +`@persist`는 `kickoff` / `kickoff_async`에서 두 가지 별개의 하이드레이션 모드를 지원합니다: + +- `kickoff(inputs={"id": })` — **재개(resume)**: 제공된 UUID에 대한 최신 스냅샷을 로드하고 동일한 `flow_uuid` 아래에서 계속 기록합니다. 기록이 확장됩니다. +- `kickoff(restore_from_state_id=)` — **포크(fork)**: 제공된 UUID에 대한 최신 스냅샷을 로드하고 새 실행의 상태를 하이드레이트한 후, 새로운 `state.id`(자동 생성, 또는 `inputs["id"]`가 고정된 경우 그 값)를 할당합니다. 새 실행의 `@persist` 기록은 새로운 `state.id` 아래에 저장되며, 원본 플로우의 기록은 보존됩니다. + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + print(f"[id={self.state.id}] counter={self.state.counter}") + +# 실행 1: 새 상태, counter 0 -> 1, flow_1.state.id 아래에 저장됨 +flow_1 = CounterFlow() +flow_1.kickoff() + +# 포크: flow_1의 최신 스냅샷에서 하이드레이트하지만, 새 state.id를 사용 +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# flow_2.state.counter는 1(하이드레이트)로 시작하고, step()이 2로 증가시킵니다. +# flow_2.state.id != flow_1.state.id; flow_1의 기록은 변경되지 않습니다. +``` + +제공된 `restore_from_state_id`가 어떤 영속 상태와도 일치하지 않으면, kickoff는 조용히 기본 동작으로 폴백됩니다 — 기존 `inputs["id"]`의 미발견 동작과 동일합니다. `restore_from_state_id`를 `from_checkpoint`와 결합하면 `ValueError`가 발생합니다; 하나의 하이드레이션 소스를 선택하세요. 포크 중 `inputs["id"]`를 고정하면 다른 플로우와 영속 키를 공유하게 됩니다 — 일반적으로 `restore_from_state_id`만 사용하는 것이 좋습니다. + +### 작동 방식 + +1. **고유 상태 식별** + - 각 flow 상태에는 자동으로 고유한 UUID가 할당됩니다. + - 이 ID는 상태 업데이트 및 메소드 호출 시에도 유지됩니다. + - 구조화된 상태(Pydantic BaseModel)와 비구조화된 상태(딕셔너리) 모두를 지원합니다. + +2. **기본 SQLite 백엔드** + - SQLiteFlowPersistence는 기본 저장 백엔드입니다. + - 상태는 자동으로 로컬 SQLite 데이터베이스에 저장됩니다. + - 데이터베이스 작업 실패 시 명확한 메시지를 제공하는 견고한 오류 처리가 제공됩니다. + +3. **오류 처리** + - 데이터베이스 작업에 대한 포괄적인 오류 메시지가 제공됩니다. + - 저장 및 로드 중에 상태가 자동으로 검증됩니다. + - 지속성 작업에 문제가 발생할 경우 명확한 피드백을 제공합니다. + +### 중요한 고려사항 + +- **상태 유형**: 구조화된(Pydantic BaseModel) 상태와 비구조화된(딕셔너리) 상태 모두 지원됩니다 +- **자동 ID**: `id` 필드는 존재하지 않을 경우 자동으로 추가됩니다 +- **상태 복구**: 실패하거나 재시작된 flow는 이전 상태를 자동으로 불러올 수 있습니다 +- **커스텀 구현**: 특수한 저장소 요구 사항을 위해 직접 FlowPersistence 구현을 제공할 수 있습니다 + +### 기술적 이점 + +1. **저수준 접근을 통한 정밀한 제어** + - 고급 사용 사례를 위한 영속성 작업에 대한 직접 접근 + - 메서드 수준의 영속성 데코레이터를 통한 세밀한 제어 + - 내장된 상태 검사 및 디버깅 기능 + - 상태 변경 및 영속성 작업에 대한 완전한 가시성 + +2. **향상된 신뢰성** + - 시스템 장애 또는 재시작 후 자동 상태 복구 + - 데이터 무결성을 위한 트랜잭션 기반 상태 업데이트 + - 명확한 오류 메시지를 제공하는 포괄적인 오류 처리 + - 상태 저장 및 로드 작업 시 강력한 검증 + +3. **확장 가능한 아키텍처** + - FlowPersistence 인터페이스를 통한 사용자 정의 가능한 영속성 백엔드 + - SQLite를 넘어선 특수 저장 솔루션 지원 + - 구조화된(Pydantic) 상태와 비구조화(dict) 상태 모두와 호환 + - 기존 CrewAI 흐름 패턴과의 원활한 통합 + +영속성 시스템의 아키텍처는 기술적 정밀성과 맞춤화 옵션을 강조하여, 개발자가 내장된 신뢰성 기능의 이점을 누리면서 상태 관리에 대한 완전한 제어권을 유지할 수 있게 해줍니다. + +## 흐름 제어 + +### 조건부 로직: `or` + +Flows에서 `or_` 함수는 여러 메서드를 감지하고 지정된 메서드 중 하나에서 출력이 발생하면 리스너 메서드를 트리거합니다. + + + +```python Code +from crewai.flow.flow import Flow, listen, or_, start + +class OrExampleFlow(Flow): + + @start() + def start_method(self): + return "Hello from the start method" + + @listen(start_method) + def second_method(self): + return "Hello from the second method" + + @listen(or_(start_method, second_method)) + def logger(self, result): + print(f"Logger: {result}") + + + +flow = OrExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Logger: Hello from the start method +Logger: Hello from the second method +``` + + + +![Flow Visual image](/images/crewai-flow-4.png) + +이 Flow를 실행하면, `logger` 메서드는 `start_method` 또는 `second_method`의 출력에 의해 트리거됩니다. +`or_` 함수는 여러 메서드를 감지하고 지정된 메서드 중 하나에서 출력이 발생하면 리스너 메서드를 트리거하는 데 사용됩니다. + +### 조건부 로직: `and` + +Flows에서 `and_` 함수는 여러 메서드를 리슨하고, 지정된 모든 메서드가 출력을 발생시킬 때만 리스너 메서드가 트리거되도록 합니다. + + + +```python Code +from crewai.flow.flow import Flow, and_, listen, start + +class AndExampleFlow(Flow): + + @start() + def start_method(self): + self.state["greeting"] = "Hello from the start method" + + @listen(start_method) + def second_method(self): + self.state["joke"] = "What do computers eat? Microchips." + + @listen(and_(start_method, second_method)) + def logger(self): + print("---- Logger ----") + print(self.state) + +flow = AndExampleFlow() +flow.plot() +flow.kickoff() +``` + +```text Output +---- Logger ---- +{'greeting': 'Hello from the start method', 'joke': 'What do computers eat? Microchips.'} +``` + + + +![Flow Visual image](/images/crewai-flow-5.png) + +이 Flow를 실행하면, `logger` 메서드는 `start_method`와 `second_method`가 모두 출력을 발생시켰을 때만 트리거됩니다. +`and_` 함수는 여러 메서드를 리슨하고, 지정된 모든 메서드가 출력을 발생시킬 때만 리스너 메서드를 트리거하는 데 사용됩니다. + +### Router + +Flows의 `@router()` 데코레이터를 사용하면 메서드의 출력값에 따라 조건부 라우팅 로직을 정의할 수 있습니다. +메서드의 출력에 따라 서로 다른 경로를 지정할 수 있어 실행 흐름을 동적으로 제어할 수 있습니다. + + + +```python Code +import random +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + success_flag: bool = False + +class RouterFlow(Flow[ExampleState]): + + @start() + def start_method(self): + print("Starting the structured flow") + random_boolean = random.choice([True, False]) + self.state.success_flag = random_boolean + + @router(start_method) + def second_method(self): + if self.state.success_flag: + return "success" + else: + return "failed" + + @listen("success") + def third_method(self): + print("Third method running") + + @listen("failed") + def fourth_method(self): + print("Fourth method running") + + +flow = RouterFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Starting the structured flow +Third method running +Fourth method running +``` + + + +![Flow Visual image](/images/crewai-flow-6.png) + +위 예제에서 `start_method`는 랜덤 불리언 값을 생성하여 state에 저장합니다. +`second_method`는 `@router()` 데코레이터를 사용해 불리언 값에 따라 조건부 라우팅 로직을 정의합니다. +불리언 값이 `True`이면 메서드는 `"success"`를 반환하고, `False`이면 `"failed"`를 반환합니다. +`third_method`와 `fourth_method`는 `second_method`의 출력값을 기다렸다가 반환된 값에 따라 실행됩니다. + +이 Flow를 실행하면, `start_method`에서 생성된 랜덤 불리언 값에 따라 출력값이 달라집니다. + +### Human in the Loop (인간 피드백) + + +`@human_feedback` 데코레이터는 **CrewAI 버전 1.8.0 이상**이 필요합니다. + + +`@human_feedback` 데코레이터는 인간의 피드백을 수집하기 위해 플로우 실행을 일시 중지하는 human-in-the-loop 워크플로우를 가능하게 합니다. 이는 승인 게이트, 품질 검토, 인간의 판단이 필요한 결정 지점에 유용합니다. + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="이 콘텐츠를 승인하시겠습니까?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + def generate_content(self): + return "검토할 콘텐츠..." + + @listen("approved") + def on_approval(self, result: HumanFeedbackResult): + print(f"승인됨! 피드백: {result.feedback}") + + @listen("rejected") + def on_rejection(self, result: HumanFeedbackResult): + print(f"거부됨. 이유: {result.feedback}") +``` + +`emit`이 지정되면, 인간의 자유 형식 피드백이 LLM에 의해 해석되어 지정된 outcome 중 하나로 매핑되고, 해당 `@listen` 데코레이터를 트리거합니다. + +라우팅 없이 단순히 피드백만 수집할 수도 있습니다: + +```python Code +@start() +@human_feedback(message="이 출력에 대한 코멘트가 있으신가요?") +def my_method(self): + return "검토할 출력" + +@listen(my_method) +def next_step(self, result: HumanFeedbackResult): + # result.feedback로 피드백에 접근 + # result.output으로 원래 출력에 접근 + pass +``` + +플로우 실행 중 수집된 모든 피드백은 `self.last_human_feedback` (가장 최근) 또는 `self.human_feedback_history` (리스트 형태의 모든 피드백)를 통해 접근할 수 있습니다. + +플로우에서의 인간 피드백에 대한 완전한 가이드는 비동기/논블로킹 피드백과 커스텀 프로바이더(Slack, 웹훅 등)를 포함하여 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows)을 참조하세요. + +## 플로우에 에이전트 추가하기 + +에이전트는 플로우에 원활하게 통합할 수 있으며, 단순하고 집중된 작업 실행이 필요할 때 전체 Crew의 경량 대안으로 활용됩니다. 아래는 에이전트를 플로우 내에서 사용하여 시장 조사를 수행하는 예시입니다: + +```python +import asyncio +from typing import Any, Dict, List + +from crewai_tools import SerperDevTool +from pydantic import BaseModel, Field + +from crewai.agent import Agent +from crewai.flow.flow import Flow, listen, start + + +# Define a structured output format +class MarketAnalysis(BaseModel): + key_trends: List[str] = Field(description="List of identified market trends") + market_size: str = Field(description="Estimated market size") + competitors: List[str] = Field(description="Major competitors in the space") + + +# Define flow state +class MarketResearchState(BaseModel): + product: str = "" + analysis: MarketAnalysis | None = None + + +# Create a flow class +class MarketResearchFlow(Flow[MarketResearchState]): + @start() + def initialize_research(self) -> Dict[str, Any]: + print(f"Starting market research for {self.state.product}") + return {"product": self.state.product} + + @listen(initialize_research) + async def analyze_market(self) -> Dict[str, Any]: + # Create an Agent for market research + analyst = Agent( + role="Market Research Analyst", + goal=f"Analyze the market for {self.state.product}", + backstory="You are an experienced market analyst with expertise in " + "identifying market trends and opportunities.", + tools=[SerperDevTool()], + verbose=True, + ) + + # Define the research query + query = f""" + Research the market for {self.state.product}. Include: + 1. Key market trends + 2. Market size + 3. Major competitors + + Format your response according to the specified structure. + """ + + # Execute the analysis with structured output format + result = await analyst.kickoff_async(query, response_format=MarketAnalysis) + if result.pydantic: + print("result", result.pydantic) + else: + print("result", result) + + # Return the analysis to update the state + return {"analysis": result.pydantic} + + @listen(analyze_market) + def present_results(self, analysis) -> None: + print("\nMarket Analysis Results") + print("=====================") + + if isinstance(analysis, dict): + # If we got a dict with 'analysis' key, extract the actual analysis object + market_analysis = analysis.get("analysis") + else: + market_analysis = analysis + + if market_analysis and isinstance(market_analysis, MarketAnalysis): + print("\nKey Market Trends:") + for trend in market_analysis.key_trends: + print(f"- {trend}") + + print(f"\nMarket Size: {market_analysis.market_size}") + + print("\nMajor Competitors:") + for competitor in market_analysis.competitors: + print(f"- {competitor}") + else: + print("No structured analysis data available.") + print("Raw analysis:", analysis) + + +# Usage example +async def run_flow(): + flow = MarketResearchFlow() + flow.plot("MarketResearchFlowPlot") + result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"}) + return result + + +# Run the flow +if __name__ == "__main__": + asyncio.run(run_flow()) +``` + +![Flow Visual image](/images/crewai-flow-7.png) + +이 예시는 플로우에서 에이전트를 사용할 때의 몇 가지 주요 기능을 보여줍니다: + +1. **구조화된 출력**: Pydantic 모델을 사용하여 예상 출력 형식(`MarketAnalysis`)을 정의함으로써 플로우 전체에서 타입 안정성과 구조화된 데이터를 보장합니다. + +2. **상태 관리**: 플로우 상태(`MarketResearchState`)는 단계 간의 컨텍스트를 유지하고 입력과 출력을 모두 저장합니다. + +3. **도구 통합**: 에이전트는 기능 강화를 위해 `WebsiteSearchTool`과 같은 도구를 사용할 수 있습니다. + +## Flows에 Crews 추가하기 + +CrewAI에서 여러 crews로 flow를 생성하는 것은 간단합니다. + +다음 명령어를 실행하여 여러 crews가 포함된 flow를 생성하는 데 필요한 모든 스캐폴딩이 포함된 새 CrewAI 프로젝트를 생성할 수 있습니다. + +```bash +crewai create flow name_of_flow +``` + +이 명령어는 필요한 폴더 구조를 갖춘 새 CrewAI 프로젝트를 생성합니다. 생성된 프로젝트에는 이미 동작 중인 미리 구축된 crew인 `poem_crew`가 포함되어 있습니다. 시작용 embedded crew는 클래식 Python/YAML 레이아웃을 사용하며, `crewai create crew`로 만든 새 독립 실행형 crew는 JSON-first 레이아웃을 사용합니다. + +### 폴더 구조 + +`crewai create flow name_of_flow` 명령을 실행하면 다음과 유사한 폴더 구조를 볼 수 있습니다: + +| 디렉터리/파일 | 설명 | +| :--------------------- | :----------------------------------------------------------------- | +| `name_of_flow/` | flow의 루트 디렉터리입니다. | +| ├── `crews/` | 특정 crew에 대한 디렉터리를 포함합니다. | +| │ └── `poem_crew/` | "poem_crew"의 설정 및 스크립트가 포함된 디렉터리입니다. | +| │ ├── `config/` | "poem_crew"의 설정 파일 디렉터리입니다. | +| │ │ ├── `agents.yaml` | "poem_crew"의 agent를 정의하는 YAML 파일입니다. | +| │ │ └── `tasks.yaml` | "poem_crew"의 task를 정의하는 YAML 파일입니다. | +| │ ├── `poem_crew.py` | "poem_crew"의 기능을 위한 스크립트입니다. | +| ├── `tools/` | flow에서 사용되는 추가 도구를 위한 디렉터리입니다. | +| │ └── `custom_tool.py` | 사용자 정의 도구 구현 파일입니다. | +| ├── `main.py` | flow를 실행하는 메인 스크립트입니다. | +| ├── `README.md` | 프로젝트 설명 및 안내 문서입니다. | +| ├── `pyproject.toml` | 프로젝트의 종속성 및 설정을 위한 구성 파일입니다. | +| └── `.gitignore` | 버전 관리에서 무시할 파일과 디렉터리를 지정합니다. | + +### 크루 빌드하기 + +`crews` 폴더에서는 여러 개의 크루를 정의할 수 있습니다. 각 크루는 자체 폴더를 가지며, 설정 파일과 크루 정의 파일을 포함합니다. 예를 들어, `poem_crew` 폴더에는 다음과 같은 파일이 있습니다: + +- `config/agents.yaml`: 크루의 agent를 정의합니다. +- `config/tasks.yaml`: 크루의 task를 정의합니다. +- `poem_crew.py`: agent, task, 그리고 크루 자체를 포함한 crew 정의가 들어 있습니다. + +`poem_crew`를 복사, 붙여넣기, 그리고 편집하여 다른 클래식 embedded crew를 생성할 수 있습니다. + +JSON-first embedded crew는 `crew.jsonc`와 `agents/*.jsonc`가 있는 폴더를 사용하세요: + +```text +crews/ +└── research_crew/ + ├── agents/ + │ └── researcher.jsonc + └── crew.jsonc +``` + +그런 다음 Flow 단계에서 로드합니다: + +```python +from pathlib import Path +from crewai.project import load_crew + +crew, default_inputs = load_crew( + Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc" +) +result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"}) +``` + +### `main.py`에서 Crew 연결하기 + +`main.py` 파일은 flow를 생성하고 crew들을 서로 연결하는 곳입니다. `Flow` 클래스를 사용하고, `@start`와 `@listen` 데코레이터를 사용하여 실행 흐름을 지정하여 flow를 정의할 수 있습니다. + +다음은 `main.py` 파일에서 `poem_crew`를 연결하는 예제입니다: + +```python Code +#!/usr/bin/env python +from random import randint + +from pydantic import BaseModel +from crewai.flow.flow import Flow, listen, start +from .crews.poem_crew.poem_crew import PoemCrew + +class PoemState(BaseModel): + sentence_count: int = 1 + poem: str = "" + +class PoemFlow(Flow[PoemState]): + + @start() + def generate_sentence_count(self): + print("Generating sentence count") + self.state.sentence_count = randint(1, 5) + + @listen(generate_sentence_count) + def generate_poem(self): + print("Generating poem") + result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count}) + + print("Poem generated", result.raw) + self.state.poem = result.raw + + @listen(generate_poem) + def save_poem(self): + print("Saving poem") + with open("poem.txt", "w") as f: + f.write(self.state.poem) + +def kickoff(): + poem_flow = PoemFlow() + poem_flow.kickoff() + + +def plot(): + poem_flow = PoemFlow() + poem_flow.plot("PoemFlowPlot") + +if __name__ == "__main__": + kickoff() + plot() +``` + +이 예제에서 `PoemFlow` 클래스는 문장 수를 생성하고, `PoemCrew`를 사용하여 시를 생성한 후, 시를 파일에 저장하는 flow를 정의합니다. 이 flow는 `kickoff()` 메서드를 호출하여 시작됩니다. `plot()` 메서드로 PoemFlowPlot이 생성됩니다. + +![Flow Visual image](/images/crewai-flow-8.png) + +### 플로우 실행하기 + +(선택 사항) 플로우를 실행하기 전에, 다음 명령어를 실행하여 의존성을 설치할 수 있습니다: + +```bash +crewai install +``` + +모든 의존성이 설치되면, 다음 명령어를 실행하여 가상 환경을 활성화해야 합니다: + +```bash +source .venv/bin/activate +``` + +가상 환경을 활성화한 후, 아래 명령어 중 하나를 실행하여 플로우를 실행할 수 있습니다: + +```bash +crewai run +``` + +또는 + +```bash +uv run kickoff +``` + +플로우가 실행되면, 콘솔에서 출력을 확인할 수 있습니다. + +## 플롯 플로우 + +AI 워크플로우를 시각화하면 플로우의 구조와 실행 경로에 대한 중요한 인사이트를 얻을 수 있습니다. CrewAI는 플로우의 인터랙티브 플롯을 생성할 수 있는 강력한 시각화 도구를 제공하여 AI 워크플로우를 보다 쉽게 이해하고 최적화할 수 있도록 도와줍니다. + +### 플롯(Plots)이란 무엇인가요? + +CrewAI에서 플롯(Plots)은 AI 워크플로우의 그래픽 표현입니다. 플롯은 다양한 태스크와 그들의 연결, 그리고 태스크 간 데이터 흐름을 시각적으로 보여줍니다. 이러한 시각화는 작업 순서를 이해하고, 병목 현상을 식별하며, 워크플로우 논리가 기대에 부합하는지 확인하는 데 도움이 됩니다. + +### 플롯 생성 방법 + +CrewAI는 플로우의 플롯을 생성하는 두 가지 편리한 방법을 제공합니다: + +#### 옵션 1: `plot()` 메서드 사용하기 + +flow 인스턴스와 직접 작업하는 경우, flow 객체에서 `plot()` 메서드를 호출하여 플롯을 생성할 수 있습니다. 이 메서드는 flow의 인터랙티브 플롯이 포함된 HTML 파일을 생성합니다. + +```python Code +# Assuming you have a flow instance +flow.plot("my_flow_plot") +``` + +이렇게 하면 현재 디렉토리에 `my_flow_plot.html`이라는 파일이 생성됩니다. 이 파일을 웹 브라우저에서 열어 인터랙티브 플롯을 볼 수 있습니다. + +#### 옵션 2: 커맨드 라인 사용 + +구조화된 CrewAI 프로젝트 내에서 작업 중이라면 커맨드 라인을 사용하여 플롯을 생성할 수 있습니다. 이는 전체 플로우 설정을 시각화하고자 하는 대규모 프로젝트에서 특히 유용합니다. + +```bash +crewai flow plot +``` + +이 명령은 플로우의 플롯이 포함된 HTML 파일을 생성하며, 이는 `plot()` 메서드와 유사합니다. 파일은 프로젝트 디렉터리에 저장되며, 웹 브라우저에서 열어 플로우를 탐색할 수 있습니다. + +### 플롯 이해하기 + +생성된 플롯은 flow 내의 작업을 나타내는 노드와 실행 흐름을 나타내는 방향성이 있는 엣지를 표시합니다. 플롯은 인터랙티브하게 제공되어, 확대/축소를 하거나 노드 위에 마우스를 올려 추가 정보를 볼 수 있습니다. + +flow를 시각화하면 워크플로의 구조를 더욱 명확하게 이해할 수 있어 디버깅, 최적화, 그리고 AI 프로세스를 다른 사람들에게 설명하는 데 도움이 됩니다. + +### 결론 + +플로우를 시각적으로 표현하는 것은 CrewAI의 강력한 기능으로, 복잡한 AI 워크플로우를 설계하고 관리하는 능력을 크게 향상시켜줍니다. `plot()` 메서드나 커맨드 라인 중 어떤 방법을 사용하더라도, 플롯을 생성하면 워크플로우의 시각적 표현을 얻을 수 있어 개발과 발표 모두에 도움이 됩니다. + +## 다음 단계 + +추가적인 flow 예제를 살펴보고 싶으시다면, 저희 examples 레포지토리에서 다양한 추천 예제를 확인하실 수 있습니다. 아래는 각각 고유한 사용 사례를 보여주는 네 가지 구체적인 flow 예제로, 현재 문제 유형에 맞는 예시를 찾는 데 도움이 될 것입니다: + +1. **이메일 자동 응답자 Flow**: 이 예제는 백그라운드 작업이 계속 실행되면서 이메일 응답을 자동화하는 무한 루프를 보여줍니다. 수동 개입 없이 반복적으로 수행해야 하는 작업에 적합한 사용 사례입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow) + +2. **리드 점수 Flow**: 이 flow 예제는 human-in-the-loop 피드백을 추가하고 router를 사용하여 다양한 조건 분기를 처리하는 방법을 보여줍니다. 워크플로우에 동적 의사결정과 인간의 관리·감독을 통합하는 방식을 확인할 수 있는 훌륭한 예시입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow) + +3. **책 집필 Flow**: 이 예제는 여러 crew를 연속적으로 연결하는 데 탁월하며, 한 crew의 출력 결과가 다른 crew에 의해 사용됩니다. 구체적으로, 한 crew가 전체 책의 개요를 작성하고, 다른 crew가 그 개요를 바탕으로 챕터를 생성합니다. 결국 모든 것이 연결되어 완성된 책이 만들어집니다. 여러 작업 간 조율이 필요한 복잡한 다단계 프로세스에 적합한 flow입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows) + +4. **미팅 어시스턴트 Flow**: 이 flow는 하나의 이벤트가 여러 후속 작업을 트리거하도록 브로드캐스트하는 방법을 보여줍니다. 예를 들어, 미팅이 끝난 후 Trello 보드를 업데이트하고 Slack 메시지를 전송하며 결과를 저장할 수 있습니다. 하나의 이벤트로부터 여러 결과를 처리하는 좋은 예시로, 포괄적인 작업 관리 및 알림 시스템에 이상적입니다. [예제 보기](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow) + +이 예제들을 통해 반복되는 작업 자동화부터 동적 의사결정과 인간 피드백이 포함된 복잡한 다단계 프로세스 관리에 이르기까지 다양한 사용 사례에서 CrewAI Flows를 어떻게 활용할 수 있는지에 대한 통찰력을 얻을 수 있습니다. + +또한, 아래의 CrewAI에서 flows를 사용하는 방법에 대한 YouTube 영상을 확인해보세요! + + + +## 플로우 실행하기 + +플로우를 실행하는 방법에는 두 가지가 있습니다: + +### Flow API 사용하기 + +플로우를 프로그래밍 방식으로 실행하려면, 플로우 클래스의 인스턴스를 생성하고 `kickoff()` 메서드를 호출하면 됩니다: + +```python +flow = ExampleFlow() +result = flow.kickoff() +``` + +### CLI 사용하기 + +버전 0.103.0부터 `crewai run` 명령어를 사용하여 flow를 실행할 수 있습니다: + +```shell +crewai run +``` + +이 명령어는 프로젝트가 pyproject.toml의 `type = "flow"` 설정을 기반으로 flow인지 자동으로 감지하여 해당 방식으로 실행합니다. 명령줄에서 flow를 실행하는 권장 방법입니다. + +레거시 `crewai flow kickoff` 명령어는 deprecated되었습니다. crew와 flow 모두 `crewai run`을 사용하세요. diff --git a/docs/v1.15.1/ko/concepts/knowledge.mdx b/docs/v1.15.1/ko/concepts/knowledge.mdx new file mode 100644 index 000000000..92f688392 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/knowledge.mdx @@ -0,0 +1,962 @@ +--- +title: Knowledge +description: CrewAI에서 knowledge란 무엇이며 어떻게 사용하는지 알아봅니다. +icon: book +mode: "wide" +--- + +## 개요 + +Knowledge in CrewAI는 AI 에이전트가 작업 중에 외부 정보 소스에 접근하고 이를 활용할 수 있게 해주는 강력한 시스템입니다. +이는 에이전트에게 작업할 때 참고할 수 있는 참조 도서관을 제공하는 것과 같습니다. + + + Knowledge를 사용함으로써 얻는 주요 이점: + - 에이전트에게 도메인 특화 정보를 제공 + - 실제 데이터를 통한 의사 결정 지원 + - 대화 전체의 맥락 유지 + - 응답을 사실 기반 정보에 근거 + + +## 빠른 시작 예제 + + +파일 기반 Knowledge Sources의 경우, 프로젝트의 루트에 `knowledge` 디렉토리를 생성하고 그 안에 파일을 배치해야 합니다. +또한, 소스를 생성할 때는 `knowledge` 디렉토리로부터의 상대 경로를 사용하세요. + + +### 기본 문자열 지식 예제 + +```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?"}) +``` + +### 웹 콘텐츠 지식 예시 + + + 다음 예시가 작동하려면 `docling`을 설치해야 합니다: `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."} +) +``` + +## 지원되는 Knowledge Sources + +CrewAI는 다양한 유형의 knowledge source를 기본적으로 지원합니다: + + + + - 원시 문자열 + - 텍스트 파일 (.txt) + - PDF 문서 + + + - CSV 파일 + - 엑셀 스프레드시트 + - JSON 문서 + + + +### 텍스트 파일 지식 소스 +```python +from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource + +text_source = TextFileKnowledgeSource( + file_paths=["document.txt", "another.txt"] +) +``` + +### PDF 지식 소스 +```python +from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource + +pdf_source = PDFKnowledgeSource( + file_paths=["document.pdf", "another.pdf"] +) +``` + +### CSV 지식 소스 +```python +from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource + +csv_source = CSVKnowledgeSource( + file_paths=["data.csv"] +) +``` + +### Excel 지식 소스 +```python +from crewai.knowledge.source.excel_knowledge_source import ExcelKnowledgeSource + +excel_source = ExcelKnowledgeSource( + file_paths=["spreadsheet.xlsx"] +) +``` + +### JSON 지식 소스 +```python +from crewai.knowledge.source.json_knowledge_source import JSONKnowledgeSource + +json_source = JSONKnowledgeSource( + file_paths=["data.json"] +) +``` + + + 반드시 ./knowledge 폴더를 생성해 주세요. 모든 소스 파일(예: .txt, .pdf, .xlsx, .json)은 중앙 집중식 관리를 위해 이 폴더에 보관해야 합니다. + + +## Agent vs Crew Knowledge: 완벽 가이드 + + +**Knowledge 레벨 이해하기**: CrewAI는 agent와 crew 두 가지 레벨의 knowledge를 지원합니다. 이 섹션에서는 각각이 어떻게 동작하는지, 언제 초기화되는지, 그리고 dependency에 대한 일반적인 오해를 명확히 설명합니다. + + +### 지식 초기화가 실제로 작동하는 방식 + +다음은 지식을 사용할 때 실제로 발생하는 일입니다: + +#### 에이전트 수준 지식 (독립적) + +```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 +``` + +#### `crew.kickoff()` 중에 일어나는 일 + +`crew.kickoff()`를 호출하면 다음과 같은 순서로 동작합니다: + +```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() +``` + +#### 스토리지 독립성 + +각 knowledge 수준은 독립적인 스토리지 컬렉션을 사용합니다: + +```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 +``` + +### 전체 작동 예제 + +#### 예시 1: Agent-Only Knowledge +```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 +``` + +#### 예시 2: 에이전트 및 크루 지식 모두 + +```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 +``` + +#### 예제 3: 서로 다른 지식을 가진 다중 에이전트 +```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 +``` + + +벡터 데이터베이스에서 도구를 사용한 검색과 달리, 사전에 지식이 탑재된 에이전트는 검색 퍼소나나 태스크가 필요하지 않습니다. +에이전트나 crew가 동작하는 데 필요한 관련 지식 소스만 추가하면 됩니다. + +지식 소스는 에이전트 또는 crew 레벨에 추가할 수 있습니다. +crew 레벨 지식 소스는 **crew 내 모든 에이전트**가 사용하게 됩니다. +에이전트 레벨 지식 소스는 해당 지식이 사전 탑재된 **특정 에이전트**만 사용하게 됩니다. + + +## Knowledge 구성 + +crew 또는 agent에 대해 knowledge 구성을 할 수 있습니다. + +```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`: 반환할 관련 문서의 개수입니다. 기본값은 3입니다. + `score_threshold`: 문서가 관련성이 있다고 간주되기 위한 최소 점수입니다. 기본값은 0.35입니다. + + +## 지원되는 Knowledge 매개변수 + + + 저장 및 쿼리할 콘텐츠를 제공하는 knowledge source들의 리스트입니다. PDF, CSV, Excel, JSON, 텍스트 파일 또는 문자열 콘텐츠를 포함할 수 있습니다. + + + knowledge가 저장될 컬렉션의 이름입니다. 서로 다른 knowledge 세트를 식별하는 데 사용됩니다. 제공하지 않을 경우 기본값은 "knowledge"입니다. + + +knowledge가 저장되고 검색되는 방식을 관리하기 위한 커스텀 저장소 구성입니다. 별도로 제공하지 않는 경우 기본 storage가 생성됩니다. + + +## 지식 저장 투명성 + + +**지식 저장 이해하기**: CrewAI는 ChromaDB를 사용하여 벡터 저장소에 지식 소스를 플랫폼별 디렉토리에 자동으로 저장합니다. 이러한 위치와 기본값을 이해하면 프로덕션 배포, 디버깅, 저장소 관리에 도움이 됩니다. + + +### CrewAI가 Knowledge 파일을 저장하는 위치 + +기본적으로 CrewAI는 memory와 동일한 저장 시스템을 사용하여, knowledge를 플랫폼별 디렉터리에 저장합니다. + +#### 플랫폼별 기본 저장 위치 + +**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}\ +``` + +### 지식 저장 위치 찾기 + +CrewAI가 지식 파일을 저장하는 위치를 정확히 확인하려면: + +```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.") +``` + +### 지식 저장 위치 제어 + +#### 옵션 1: 환경 변수 (권장) +```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=[...] +) +``` + +#### 옵션 2: 사용자 지정 Knowledge 저장소 +```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 +``` + +#### 옵션 3: 프로젝트별 Knowledge 저장소 +```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 +``` + +### 기본 임베딩 제공자 동작 + + +**기본 임베딩 제공자**: CrewAI는 다른 LLM 제공자를 사용할 때도 지식 저장을 위해 기본적으로 OpenAI 임베딩(`text-embedding-3-small`)을 사용합니다. 설정에 맞게 쉽게 이 옵션을 커스터마이즈할 수 있습니다. + + +#### 기본 동작 이해하기 +```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 +) +``` + +#### 지식 임베딩 공급자 사용자 정의 +```python +# Option 1: Voyage AI 사용 (Claude 사용자에게 Anthropic이 권장) +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source], + embedder={ + "provider": "voyageai", # Claude 사용자에게 권장 + "config": { + "api_key": "your-voyage-api-key", + "model": "voyage-3" # 최고 품질을 원하면 "voyage-3-large" 사용 + } + } +) + +# Option 2: 로컬 임베딩 사용 (외부 API 호출 없음) +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 = 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" + } + } +) +``` + +#### Azure OpenAI 임베딩 구성 + +Azure OpenAI 임베딩을 사용할 때: +1. 먼저 Azure 플랫폼에 임베딩 모델을 배포했는지 확인하세요. +2. 그런 다음 다음과 같은 구성을 사용해야 합니다: + +```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" + } + } +) +``` + +## 고급 기능 + +### 쿼리 리라이팅 + +CrewAI는 지식 검색을 최적화하기 위해 지능형 쿼리 리라이팅 메커니즘을 구현합니다. 에이전트가 지식 소스를 검색해야 할 때, 원시 태스크 프롬프트는 자동으로 더 효과적인 검색 쿼리로 변환됩니다. + +#### 쿼리 재작성 방식 + +1. 에이전트가 knowledge 소스를 사용할 수 있을 때 작업을 실행하면 `_get_knowledge_search_query` 메서드가 트리거됩니다. +2. 에이전트의 LLM을 사용하여 원래 작업 프롬프트를 최적화된 검색 쿼리로 변환합니다. +3. 이 최적화된 쿼리는 knowledge 소스에서 관련 정보를 검색하는 데 사용됩니다. + +#### 쿼리 리라이트(Query Rewriting)의 이점 + + + + 주요 개념에 집중하고 불필요한 내용을 제거함으로써, 쿼리 리라이트는 보다 관련성 높은 정보를 검색할 수 있게 도와줍니다. + + + 리라이트된 쿼리는 벡터 데이터베이스 검색을 위해 더욱 구체적이고 컨텍스트를 인식할 수 있도록 설계되어 있습니다. + + + +#### 예시 + +```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?" +``` + +재작성된 쿼리는 핵심 정보 요구에 더 집중하며, 출력 형식에 대한 불필요한 지시사항을 제거합니다. + + + 이 메커니즘은 완전히 자동으로 동작하며 사용자가 별도의 설정을 할 필요가 없습니다. agent의 LLM을 사용하여 쿼리 재작성을 수행하므로, 더 강력한 LLM을 사용할 경우 재작성된 쿼리의 품질이 향상될 수 있습니다. + + +### Knowledge 이벤트 + +CrewAI는 knowledge 검색 과정에서 이벤트를 발생시키며, 이벤트 시스템을 사용하여 이를 감지할 수 있습니다. 이러한 이벤트를 통해 에이전트가 knowledge를 어떻게 검색하고 사용하는지 모니터링, 디버깅, 분석할 수 있습니다. + +#### 사용 가능한 Knowledge 이벤트 + +- **KnowledgeRetrievalStartedEvent**: 에이전트가 소스에서 knowledge를 검색하기 시작할 때 발생 +- **KnowledgeRetrievalCompletedEvent**: knowledge 검색이 완료되었을 때 발생하며, 사용된 쿼리와 검색된 콘텐츠를 포함 +- **KnowledgeQueryStartedEvent**: knowledge 소스에 쿼리를 시작할 때 발생 +- **KnowledgeQueryCompletedEvent**: 쿼리가 성공적으로 완료되었을 때 발생 +- **KnowledgeQueryFailedEvent**: knowledge 소스에 대한 쿼리가 실패했을 때 발생 +- **KnowledgeSearchQueryFailedEvent**: 검색 쿼리가 실패했을 때 발생 + +#### 예시: Knowledge Retrieval 모니터링 + +```python +from crewai.events import ( + KnowledgeRetrievalStartedEvent, + KnowledgeRetrievalCompletedEvent, + 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() +``` + +이벤트 사용에 대한 자세한 내용은 [이벤트 리스너](/ko/concepts/event-listener) 문서를 참고하세요. + +### 맞춤형 지식 소스 + +CrewAI를 사용하면 `BaseKnowledgeSource` 클래스를 확장하여 모든 유형의 데이터에 대한 맞춤형 지식 소스를 만들 수 있습니다. 이제 우주 뉴스 기사를 가져오고 처리하는 실용적인 예제를 만들어보겠습니다. + +최근 우주 탐사 동향은 다음과 같습니다. 최신 우주 뉴스 기사들을 기반으로 정리하였습니다: + +1. SpaceX가 2023년 11월 17일 오전에 예정된, 두 번째 Starship/Super Heavy 통합 발사를 위한 최종 규제 승인을 받았습니다. 이는 SpaceX의 우주 탐사 및 우주 식민화에 대한 야심찬 계획에서 중요한 단계입니다. [출처: SpaceNews](https://spacenews.com/starship-cleared-for-nov-17-launch/) + +2. SpaceX는 미국 연방통신위원회(FCC)에 1세대 차세대 Starlink Gen2 위성의 첫 발사를 시작할 계획임을 알렸습니다. 이는 전 세계에 고속 인터넷을 제공하는 Starlink 위성 인터넷 서비스의 주요 업그레이드입니다. [출처: Teslarati](https://www.teslarati.com/spacex-first-starlink-gen2-satellite-launch-2022/) + +3. AI 스타트업 Synthetaic이 시리즈 B 펀딩에서 1,500만 달러를 유치했습니다. 이 회사는 인공 지능을 사용하여 우주 및 공중 센서에서 데이터를 분석하며, 이는 우주 탐사와 위성 기술에 큰 응용 가능성이 있습니다. [출처: SpaceNews](https://spacenews.com/ai-startup-synthetaic-raises-15-million-in-series-b-funding/) + +4. 미 우주군(Space Force)은 미국 인도-태평양 사령부(Indo-Pacific Command) 내에 부대를 공식적으로 창설하여 인도-태평양 지역에 항구적인 존재감을 확보하였습니다. 이는 우주 안보 및 지정학에 중대한 영향을 미칠 수 있습니다. [출처: SpaceNews](https://spacenews.com/space-force-establishes-permanent-presence-in-indo-pacific-region/) + +5. 우주 추적 및 데이터 분석 기업 Slingshot Aerospace는 저지구 궤도(LEO) 커버리지를 확대하기 위해 지상 광학 망원경 네트워크를 확장하고 있습니다. 이는 저지구 궤도의 위성 및 우주 잔해 추적과 분석 능력을 향상시킬 수 있습니다. [출처: SpaceNews](https://spacenews.com/slingshots-space-tracking-network-to-extend-coverage-of-low-earth-orbit/) + +6. 중국 국가자연과학기금위원회는 연구자들이 초대형 우주선 조립을 연구하기 위한 5개년 프로젝트를 발표했습니다. 이는 우주선 기술과 우주 탐사 역량의 비약적인 발전을 가져올 수 있습니다. [출처: SpaceNews](https://spacenews.com/china-researching-challenges-of-kilometer-scale-ultra-large-spacecraft/) + +7. 스탠포드 대학교의 AEroSpace Autonomy Research 센터(CAESAR)는 우주선 자율성에 초점을 맞추고 있습니다. 센터는 2024년 5월 22일에 업계, 학계, 정부 간 협력을 촉진하기 위한 시작 행사를 개최하였습니다. 이는 자율 우주선 기술의 발전에 중대한 기여를 할 수 있습니다. [출처: SpaceNews](https://spacenews.com/stanford-center-focuses-on-spacecraft-autonomy/) +``` + + + +## 디버깅 및 문제 해결 + +### 지식 문제 디버깅 + +#### 에이전트 지식 초기화 확인 +```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)}") +``` + +#### 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}") +``` + +#### 테스트 지식 검색 +```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") +``` + +#### 지식 컬렉션 검사하기 +```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") +``` + +#### 지식 처리 확인 +```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]}...") +``` + +### 일반적인 Knowledge Storage 문제 + +**"파일을 찾을 수 없음" 오류:** +```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)}") +``` + +**"Embedding dimension mismatch" 오류:** +```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"}} +) +``` + +**"ChromaDB permission denied" 오류:** +```bash +# Fix storage permissions +chmod -R 755 ~/.local/share/CrewAI/ +``` + +**Knowledge가 여러 번 실행 시 유지되지 않음:** +```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")) +``` + +### 지식 초기화 명령어 + +```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 +``` + +### 지식 초기화 + +CrewAI에 저장된 지식을 초기화해야 하는 경우, `crewai reset-memories` 명령어를 `--knowledge` 옵션과 함께 사용할 수 있습니다. + +```bash Command +crewai reset-memories --knowledge +``` + +이 기능은 지식 소스를 업데이트했고, 에이전트들이 최신 정보를 사용하도록 보장하고 싶을 때 유용합니다. + +## 베스트 프랙티스 + + + + - 콘텐츠 유형에 맞는 적절한 청크 크기를 유지하세요 + - 컨텍스트 보존을 위해 콘텐츠 중복을 고려하세요 + - 관련 정보를 별도의 지식 소스로 체계화하세요 + + + + - 콘텐츠의 복잡성에 따라 청크 크기를 조정하세요 + - 적절한 임베딩 모델을 설정하세요 + - 더 빠른 처리를 위해 로컬 임베딩 프로바이더 사용을 고려하세요 + + + + - CrewAI에서 제공하는 일반적인 파일 구조에서는 kickoff가 트리거될 때마다 knowledge 소스가 임베딩됩니다. + - knowledge 소스가 크면, 매번 동일한 데이터가 임베딩되어 비효율성과 지연이 발생합니다. + - 이를 해결하려면 knowledge_sources 파라미터 대신 knowledge 파라미터를 직접 초기화하세요. + - 전체 아이디어를 얻으려면 이 이슈를 참고하세요 [Github Issue](https://github.com/crewAIInc/crewAI/issues/2755) + + + + - 역할별 정보에는 agent 레벨의 knowledge를 사용하세요 + - 모든 agent가 필요로 하는 공유 정보에는 crew 레벨의 knowledge를 사용하세요 + - 서로 다른 임베딩 전략이 필요하다면 agent 레벨에서 embedder를 설정하세요 + - agent 역할을 설명적으로 유지하여 일관된 콜렉션 이름을 사용하세요 + - kickoff 후 agent.knowledge를 확인하여 knowledge 초기화를 테스트하세요 + - 지식이 저장되는 위치를 모니터링하여 storage 위치를 파악하세요 + - 올바른 명령 유형을 사용하여 적절하게 knowledge를 초기화(리셋)하세요 + + + + - 프로덕션에서는 `CREWAI_STORAGE_DIR`를 지정된 위치로 설정하세요 + - LLM 구성과 맞도록 임베딩 프로바이더를 명확히 선택하고, API 키 충돌을 방지하세요 + - 문서가 추가될수록 knowledge storage 용량을 모니터링하세요 + - 도메인 또는 목적에 따라 knowledge 소스를 콜렉션 이름으로 체계화하세요 + - 지식 디렉터리를 백업 및 배포 전략에 포함시키세요 + - knowledge 파일과 storage 디렉터리에 적절한 파일 권한을 부여하세요 + - API 키와 민감한 설정에는 환경 변수를 사용하세요 + + \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/llms.mdx b/docs/v1.15.1/ko/concepts/llms.mdx new file mode 100644 index 000000000..0b616a342 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/llms.mdx @@ -0,0 +1,1163 @@ +--- +title: 'LLMs' +description: 'CrewAI 프로젝트에서 대형 언어 모델(LLM)을 구성하고 사용하는 방법에 대한 종합 안내서' +icon: 'microchip-ai' +mode: "wide" +--- + +## 개요 + +CrewAI는 LiteLLM을 통해 다양한 LLM 제공업체와 통합되어, 특정 사용 사례에 맞는 올바른 모델을 선택할 수 있는 유연성을 제공합니다. 이 가이드는 CrewAI 프로젝트에서 다양한 LLM 제공업체를 구성하고 사용하는 방법을 이해하는 데 도움이 될 것입니다. + +## LLM이란 무엇인가요? + +Large Language Models(LLM)는 CrewAI 에이전트의 핵심 지능입니다. 에이전트가 문맥을 이해하고, 결정을 내리며, 인간과 유사한 응답을 생성할 수 있도록 합니다. 알아두어야 할 내용은 다음과 같습니다: + + + + Large Language Models는 방대한 양의 텍스트 데이터로 학습된 AI 시스템입니다. CrewAI 에이전트의 지능을 구동하여, 인간과 유사한 텍스트를 이해하고 생성할 수 있도록 합니다. + + + 컨텍스트 윈도우는 LLM이 한 번에 처리할 수 있는 텍스트 양을 결정합니다. 더 큰 윈도우(예: 128K 토큰)는 더 많은 문맥을 다룰 수 있지만, 비용과 속도 면에서 더 부담이 될 수 있습니다. + + + Temperature(0.0에서 1.0)는 응답의 무작위성을 조절합니다. 낮은 값(예: 0.2)은 더 집중적이고 결정적인 결과를, 높은 값(예: 0.8)은 창의성과 다양성을 높입니다. + + + 각 LLM 제공자(예: OpenAI, Anthropic, Google)는 다양한 기능, 가격, 특성을 가진 모델을 제공합니다. 정확성, 속도, 비용 등 요구 사항에 따라 선택하세요. + + + +## LLM 설정하기 + +CrewAI 코드 내에는 사용할 모델을 지정할 수 있는 여러 위치가 있습니다. 모델을 지정한 후에는 사용하는 각 모델 제공자에 대한 설정(예: API 키)을 제공해야 합니다. 각 제공자에 맞는 [제공자 설정 예제](#provider-configuration-examples) 섹션을 참고하세요. + + + + 가장 간단하게 시작할 수 있는 방법입니다. `.env` 파일이나 앱 코드에서 환경 변수로 직접 모델을 설정할 수 있습니다. `crewai create`를 사용해 프로젝트를 부트스트랩했다면 이미 설정되어 있을 수 있습니다. + + ```bash .env + MODEL=model-id # e.g. gpt-4o, gemini-2.0-flash, claude-3-sonnet-... + + # 반드시 여기에서 API 키도 설정하세요. 아래 제공자 + # 섹션을 참고하세요. + ``` + + + API 키를 절대 버전 관리 시스템에 커밋하지 마세요. 환경 파일(.env)이나 시스템의 비밀 관리 기능을 사용하세요. + + + + 에이전트 구성을 정의하는 YAML 파일을 만드세요. 이 방법은 버전 관리와 팀 협업에 적합합니다: + + ```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... + # (아래 제공자 구성 예제 참고) + ``` + + + YAML 구성의 장점: + - 에이전트 설정을 버전 관리할 수 있습니다. + - 다양한 모델 간 전환이 쉽습니다. + - 팀원들과 구성을 공유할 수 있습니다. + - 모델 선택과 목적을 문서화할 수 있습니다. + + + + 최대한 유연하게 LLM을 Python 코드에서 직접 구성할 수 있습니다: + + ```python {4,8} + from crewai import LLM + + # 기본 설정 + llm = LLM(model="model-id-here") # gpt-4o, gemini-2.0-flash, anthropic/claude... + + # 자세한 파라미터로 고급 설정 + llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + temperature=0.7, # 더욱 창의적인 결과를 원할 때 높게 설정 + timeout=120, # 응답을 기다릴 최대 초 + max_tokens=4000, # 응답의 최대 길이 + top_p=0.9, # 누클리어스 샘플링 파라미터 + frequency_penalty=0.1 , # 반복 줄이기 + presence_penalty=0.1, # 주제 다양성 높이기 + response_format={"type": "json"}, # 구조화된 출력용 + seed=42 # 결과 재현성 확보용 + ) + ``` + + + 파라미터 설명: + - `temperature`: 랜덤성 제어 (0.0-1.0) + - `timeout`: 응답 대기 최대 시간 + - `max_tokens`: 응답 길이 제한 + - `top_p`: 샘플링 시 temperature의 대체값 + - `frequency_penalty`: 단어 반복 감소 + - `presence_penalty`: 새로운 주제 생성 유도 + - `response_format`: 출력 구조 지정 + - `seed`: 일관된 출력 보장 + + + + + + CrewAI는 OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock, Snowflake Cortex에 대해 네이티브 SDK 통합을 제공합니다 — 제공자별 extras(예: `uv add "crewai[openai]"`) 외에 추가 설치가 필요하지 않습니다. + + 그 외 모든 제공자는 **LiteLLM**을 통해 지원됩니다. 이를 사용하려면 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + +## 공급자 구성 예시 + +CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양한 LLM 공급자를 지원합니다. +이 섹션에서는 프로젝트의 요구에 가장 적합한 LLM을 선택, 구성, 최적화하는 데 도움이 되는 자세한 예시를 제공합니다. + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + + ```toml Code + # Required + OPENAI_API_KEY=sk-... + + # Optional + OPENAI_API_BASE= + OPENAI_ORGANIZATION= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4", # call model by 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는 다양한 모델과 기능을 제공하는 대표적인 LLM 공급자 중 하나입니다. + + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |-------------------|-------------------|-----------------------------------------------| + | GPT-4 | 8,192 토큰 | 고정확도 작업, 복잡한 추론 | + | GPT-4 Turbo | 128,000 토큰 | 장문 콘텐츠, 문서 분석 | + | GPT-4o & GPT-4o-mini | 128,000 토큰 | 비용 효율적인 대용량 컨텍스트 처리 | + | o3-mini | 200,000 토큰 | 빠른 추론, 복잡한 추론 | + | o1-mini | 128,000 토큰 | 빠른 추론, 복잡한 추론 | + | o1-preview | 128,000 토큰 | 빠른 추론, 복잡한 추론 | + | o1 | 200,000 토큰 | 빠른 추론, 복잡한 추론 | + + **Responses API:** + + OpenAI는 Chat Completions(기본값)와 새로운 Responses API, 두 가지 API를 제공합니다. Responses API는 네이티브 멀티모달 지원을 기반으로 처음부터 설계되었으며, 텍스트, 이미지, 오디오, 함수 호출이 모두 일급 객체입니다. 추론 모델에서 더 나은 성능을 제공하고 자동 체이닝 및 내장 도구와 같은 추가 기능을 지원합니다. + + ```python Code + from crewai import LLM + + # Chat Completions 대신 Responses API 사용 + llm = LLM( + model="openai/gpt-4o", + api="responses", # Responses API 활성화 + store=True, # 멀티턴을 위한 응답 저장 (선택사항) + auto_chain=True, # 추론 모델용 자동 체이닝 (선택사항) + ) + ``` + + **Responses API 파라미터:** + - `api`: Responses API를 사용하려면 `"responses"`로 설정 (기본값: `"completions"`) + - `instructions`: 시스템 레벨 지침 (Responses API 전용) + - `store`: 멀티턴 대화를 위한 응답 저장 여부 + - `previous_response_id`: 멀티턴을 위한 이전 응답 ID + - `include`: 응답에 포함할 추가 데이터 (예: `["reasoning.encrypted_content"]`) + - `builtin_tools`: OpenAI 내장 도구 목록: `"web_search"`, `"file_search"`, `"code_interpreter"`, `"computer_use"` + - `parse_tool_outputs`: 파싱된 내장 도구 출력과 함께 구조화된 `ResponsesAPIResult` 반환 + - `auto_chain`: 멀티턴 대화를 위한 응답 ID 자동 추적 및 사용 + - `auto_chain_reasoning`: ZDR(제로 데이터 보존) 준수를 위한 암호화된 추론 항목 추적 + + + 새 프로젝트, 특히 추론 모델(o1, o3, o4)을 사용하거나 [파일](/ko/concepts/files)에 대한 네이티브 멀티모달 지원이 필요한 경우 Responses API를 사용하세요. + + + + + Meta의 Llama API는 Meta의 대형 언어 모델 패밀리 접근을 제공합니다. + API는 [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website)에서 사용할 수 있습니다. + `.env` 파일에 다음 환경 변수를 설정하십시오: + + ```toml Code + # Meta Llama API Key Configuration + LLAMA_API_KEY=LLM|your_api_key_here + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + from crewai import LLM + + # Meta Llama LLM 초기화 + llm = LLM( + model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8", + temperature=0.8, + stop=["END"], + seed=42 + ) + ``` + + https://llama.developer.meta.com/docs/models/ 에 기재된 모든 모델이 지원됩니다. + + | 모델 ID | 입력 컨텍스트 길이 | 출력 컨텍스트 길이 | 입력 모달리티 | 출력 모달리티 | + | ------- | ------------------ | ------------------ | ---------------- | ---------------- | + | `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | 텍스트, 이미지 | 텍스트 | + | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | 텍스트, 이미지 | 텍스트 | + | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | 텍스트 | 텍스트 | + | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | 텍스트 | 텍스트 | + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + CrewAI는 OpenAI 호환 Chat Completions 엔드포인트를 통해 Snowflake Cortex REST API와 네이티브로 통합됩니다. `snowflake/...` 모델은 LiteLLM fallback 없이 사용됩니다. CrewAI에서 Snowflake Cortex는 현재 Chat Completions만 지원하므로 기본 `api` 모드를 사용하고 `api="responses"`를 설정하지 마세요. + + ```toml Code + # Required + SNOWFLAKE_PAT= + SNOWFLAKE_ACCOUNT_URL=https://.snowflakecomputing.com + + # Alternative account configuration + SNOWFLAKE_ACCOUNT= + ``` + + **기본 사용법:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/openai-gpt-4.1", + temperature=0.7, + max_completion_tokens=1024, + ) + ``` + + **Cortex의 Claude 모델:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/claude-sonnet-4-5", + max_completion_tokens=1024, + stream=True, + ) + ``` + + **지원 환경 변수:** + - `SNOWFLAKE_PAT`, `SNOWFLAKE_TOKEN`, 또는 `SNOWFLAKE_JWT`: Bearer 자격 증명으로 사용할 토큰 + - `SNOWFLAKE_ACCOUNT_URL`: 전체 Snowflake 계정 URL + - `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_ACCOUNT_ID`, 또는 `SNOWFLAKE_ACCOUNT_IDENTIFIER`: 계정 URL을 만들 계정 식별자 + + Snowflake REST 요청은 사용자의 기본 Snowflake role을 사용합니다. 해당 role에 `SNOWFLAKE.CORTEX_USER` 또는 `SNOWFLAKE.CORTEX_REST_API_USER`가 있는지 확인하세요. Cortex REST Chat Completions 엔드포인트에는 database, schema, warehouse, 명시적 role 파라미터가 필요하지 않습니다. + + **기능:** + - `model="snowflake/"`을 통한 네이티브 provider 선택 + - Streaming 및 non-streaming Chat Completions만 지원; `api="responses"`는 지원되지 않음 + - 토큰 사용량 추적 + - Snowflake 호스팅 OpenAI 및 Claude 모델의 함수 호출 + - Snowflake Claude 모델에서 유효하지 않은 마지막 assistant prefill 자동 제거 + + + + ```toml Code + # Required + ANTHROPIC_API_KEY=sk-ant-... + + # Optional + ANTHROPIC_API_BASE= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="anthropic/claude-3-sonnet-20240229-v1:0", + temperature=0.7 + ) + ``` + + + + `.env` 파일에 API 키를 설정하십시오. 키가 필요하거나 기존 키를 찾으려면 [AI Studio](https://aistudio.google.com/apikey)를 확인하세요. + + ```toml .env + # Gemini API 사용 시 (다음 중 하나) + GOOGLE_API_KEY= + GEMINI_API_KEY= + + # Vertex AI Express 모드 사용 시 (API 키 인증) + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + + # Vertex AI 서비스 계정 사용 시 + GOOGLE_CLOUD_PROJECT= + GOOGLE_CLOUD_LOCATION= # 기본값: us-central1 + ``` + + **기본 사용법:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7, + ) + ``` + + **Vertex AI Express 모드 (API 키 인증):** + + Vertex AI Express 모드를 사용하면 서비스 계정 자격 증명 대신 간단한 API 키 인증으로 Vertex AI를 사용할 수 있습니다. Vertex AI를 시작하는 가장 빠른 방법입니다. + + Express 모드를 활성화하려면 `.env` 파일에 두 환경 변수를 모두 설정하세요: + ```toml .env + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + ``` + + 그런 다음 평소처럼 LLM을 사용하세요: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7 + ) + ``` + + + Express 모드 API 키를 받으려면: + - 신규 Google Cloud 사용자: [Express 모드 API 키](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey) 받기 + - 기존 Google Cloud 사용자: [서비스 계정에 바인딩된 Google Cloud API 키](https://cloud.google.com/docs/authentication/api-keys) 받기 + + 자세한 내용은 [Vertex AI Express 모드 문서](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey)를 참조하세요. + + + ### Gemini 모델 + + Google은 다양한 용도에 최적화된 강력한 모델을 제공합니다. + + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |----------------------------------|-----------------|------------------------------------------------------------------------| + | gemini-2.5-flash-preview-04-17 | 1M 토큰 | 적응형 사고, 비용 효율성 | + | gemini-2.5-pro-preview-05-06 | 1M 토큰 | 향상된 사고 및 추론, 멀티모달 이해, 고급 코딩 등 | + | gemini-2.0-flash | 1M 토큰 | 차세대 기능, 속도, 사고, 실시간 스트리밍 | + | gemini-2.0-flash-lite | 1M 토큰 | 비용 효율성과 낮은 대기 시간 | + | gemini-1.5-flash | 1M 토큰 | 밸런스 잡힌 멀티모달 모델, 대부분의 작업에 적합 | + | gemini-1.5-flash-8B | 1M 토큰 | 가장 빠르고, 비용 효율적, 고빈도 작업에 적합 | + | gemini-1.5-pro | 2M 토큰 | 최고의 성능, 논리적 추론, 코딩, 창의적 협업 등 다양한 추론 작업에 적합 | + + 전체 모델 목록은 [Gemini 모델 문서](https://ai.google.dev/gemini-api/docs/models)에서 확인할 수 있습니다. + + ### Gemma + + Gemini API를 통해 Google 인프라에서 호스팅되는 [Gemma 모델](https://ai.google.dev/gemma/docs)도 API 키를 이용해 사용할 수 있습니다. + + | 모델 | 컨텍스트 윈도우 | + |----------------|----------------| + | gemma-3-1b-it | 32k 토큰 | + | gemma-3-4b-it | 32k 토큰 | + | gemma-3-12b-it | 32k 토큰 | + | gemma-3-27b-it | 128k 토큰 | + + + + Google Cloud Console에서 자격증명을 받아 JSON 파일로 저장한 후, 다음 코드로 로드하세요: + ```python Code + import json + + file_path = 'path/to/vertex_ai_service_account.json' + + # Load the JSON file + with open(file_path, 'r') as file: + vertex_credentials = json.load(file) + + # Convert the credentials to a JSON string + vertex_credentials_json = json.dumps(vertex_credentials) + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini-1.5-pro-latest", # or vertex_ai/gemini-1.5-pro-latest + temperature=0.7, + vertex_credentials=vertex_credentials_json + ) + ``` + + Google은 다양한 용도에 최적화된 강력한 모델들을 제공합니다: + + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |----------------------------------|-----------------|------------------------------------------------------------------------| + | gemini-2.5-flash-preview-04-17 | 1M 토큰 | 적응형 사고, 비용 효율성 | + | gemini-2.5-pro-preview-05-06 | 1M 토큰 | 향상된 사고 및 추론, 멀티모달 이해, 고급 코딩 등 | + | gemini-2.0-flash | 1M 토큰 | 차세대 기능, 속도, 사고, 실시간 스트리밍 | + | gemini-2.0-flash-lite | 1M 토큰 | 비용 효율성과 낮은 대기 시간 | + | gemini-1.5-flash | 1M 토큰 | 밸런스 잡힌 멀티모달 모델, 대부분의 작업에 적합 | + | gemini-1.5-flash-8B | 1M 토큰 | 가장 빠르고, 비용 효율적, 고빈도 작업에 적합 | + | gemini-1.5-pro | 2M 토큰 | 최고의 성능, 논리적 추론, 코딩, 창의적 협업 등 다양한 추론 작업에 적합 | + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + ```toml Code + # Required + AZURE_API_KEY= + AZURE_API_BASE= + AZURE_API_VERSION= + + # Optional + AZURE_AD_TOKEN= + AZURE_API_TYPE= + ``` + + 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= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="bedrock/anthropic.claude-3-sonnet-20240229-v1:0" + ) + ``` + + Amazon Bedrock을 사용하기 전에, 환경에 boto3가 설치되어 있는지 확인하십시오. + + [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html)은 대표적인 AI 회사들의 여러 파운데이션 모델에 통합 API를 통해 접근할 수 있는 매니지드 서비스로, 안전하고 책임감 있는 AI 응용프로그램 개발을 가능하게 해줍니다. + + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |-----------------------------|--------------------|------------------------------------------------------------------------| + | Amazon Nova Pro | 최대 300k 토큰 | 다양한 작업에서 정확성, 속도, 비용을 균형 있게 제공하는 고성능 모델 | + | Amazon Nova Micro | 최대 128k 토큰 | 텍스트 전용, 최소 레이턴시 응답에 최적화된 비용 효율적 고성능 모델 | + | Amazon Nova Lite | 최대 300k 토큰 | 이미지, 비디오, 텍스트를 아우르는 실시간 멀티모달 처리 | + | Claude 3.7 Sonnet | 최대 128k 토큰 | 복잡한 추론, 코딩 및 AI 에이전트에 적합한 고성능 모델 | + | Claude 3.5 Sonnet v2 | 최대 200k 토큰 | 소프트웨어 공학, 에이전트 기능, 컴퓨터 상호작용에 특화된 최신 모델 | + | Claude 3.5 Sonnet | 최대 200k 토큰 | 다양한 작업에 탁월한 지능 및 추론 제공, 최적의 속도·비용 모델 | + | Claude 3.5 Haiku | 최대 200k 토큰 | 빠르고 컴팩트한 멀티모달 모델, 신속하고 자연스러운 대화에 최적 | + | Claude 3 Sonnet | 최대 200k 토큰 | 지능과 속도의 균형 잡힌 멀티모달 모델, 대규모 배포에 적합 | + | Claude 3 Haiku | 최대 200k 토큰 | 컴팩트한 고속 멀티모달 모델, 신속한 응답과 자연스러운 대화형 상호작용 | + | Claude 3 Opus | 최대 200k 토큰 | 인간 같은 추론과 우수한 문맥 이해로 복잡한 작업 수행 | + | Claude 2.1 | 최대 200k 토큰 | 확장된 컨텍스트, 신뢰도 개선, 로봇화 감소, 장문 및 RAG 적용에 적합 | + | Claude | 최대 100k 토큰 | 복잡한 대화, 창의적 콘텐츠 생성, 정교한 지시 수행에 탁월 | + | Claude Instant | 최대 100k 토큰 | 일상 대화, 분석, 요약, 문서 Q&A 등 빠르고 비용 효율적인 모델 | + | Llama 3.1 405B Instruct | 최대 128k 토큰 | 챗봇, 코딩, 도메인 특화 작업을 위한 합성 데이터 생성 및 추론용 첨단 LLM | + | Llama 3.1 70B Instruct | 최대 128k 토큰 | 복잡한 대화, 우수한 문맥 및 추론, 텍스트 생성 능력 강화 | + | Llama 3.1 8B Instruct | 최대 128k 토큰 | 우수한 언어 이해, 추론, 텍스트 생성 기능의 최첨단 모델 | + | Llama 3 70B Instruct | 최대 8k 토큰 | 복잡한 대화, 우수한 문맥 및 추론, 텍스트 생성 기능 강화 | + | Llama 3 8B Instruct | 최대 8k 토큰 | 첨단 언어 이해력, 추론, 텍스트 생성이 가능한 최첨단 LLM | + | Titan Text G1 - Lite | 최대 4k 토큰 | 영어 과제 및 요약, 콘텐츠 생성에 최적화된 경량 비용 효율적 모델 | + | Titan Text G1 - Express | 최대 8k 토큰 | 일반 언어, 대화, RAG 지원, 영어 및 100여 개 언어 지원 | + | Cohere Command | 최대 4k 토큰 | 사용자의 명령 수행, 실질적 기업 솔루션 제공에 특화된 모델 | + | Jurassic-2 Mid | 최대 8,191 토큰 | 다양한 언어 과제(Q&A, 요약, 생성 등)에 적합한 품질-비용 균형 모델 | + | Jurassic-2 Ultra | 최대 8,191 토큰 | 고급 텍스트 생성과 이해, 분석 및 콘텐츠 제작 등 복잡한 작업 수행 | + | Jamba-Instruct | 최대 256k 토큰 | 비용 효율적인 대용량 문맥 창작, 요약, Q&A에 최적화된 모델 | + | Mistral 7B Instruct | 최대 32k 토큰 | 명령을 따르고, 요청을 완성하며, 창의적 텍스트를 생성하는 LLM | + | Mistral 8x7B Instruct | 최대 32k 토큰 | 명령 및 요청 완성, 창의적 텍스트 생성이 가능한 MOE LLM | + + + + + ```toml Code + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_DEFAULT_REGION= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="sagemaker/" + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + MISTRAL_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="mistral/mistral-large-latest", + temperature=0.7 + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + NVIDIA_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="nvidia_nim/meta/llama3-70b-instruct", + temperature=0.7 + ) + ``` + + Nvidia NIM은 일반 목적 작업부터 특수 목적 응용까지 다양한 용도를 위한 모델 제품군을 제공합니다. + + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |------------------------------------------------------------------------|----------------|---------------------------------------------------------------------| + | nvidia/mistral-nemo-minitron-8b-8k-instruct | 8,192 토큰 | 챗봇, 가상 비서, 콘텐츠 생성을 위한 최신형 소형 언어 모델 | + | nvidia/nemotron-4-mini-hindi-4b-instruct | 4,096 토큰 | 힌디-영어 SLM, 힌디 언어 전용 온디바이스 추론 | + | nvidia/llama-3.1-nemotron-70b-instruct | 128k 토큰 | 더욱 도움이 되는 답변을 위해 커스터마이즈됨 | + | nvidia/llama3-chatqa-1.5-8b | 128k 토큰 | 챗봇, 검색엔진용 맥락 인식 응답 생성에 탁월한 고급 LLM | + | nvidia/llama3-chatqa-1.5-70b | 128k 토큰 | 챗봇, 검색엔진용 맥락 인식 응답 생성에 탁월한 고급 LLM | + | nvidia/vila | 128k 토큰 | 텍스트/이미지/비디오 이해 및 정보성 응답 생성을 지원하는 멀티모달 모델 | + | nvidia/neva-22 | 4,096 토큰 | 텍스트/이미지 이해 및 정보성 응답 생성을 지원하는 멀티모달 모델 | + | nvidia/nemotron-mini-4b-instruct | 8,192 토큰 | 일반 목적 작업 | + | nvidia/usdcode-llama3-70b-instruct | 128k 토큰 | OpenUSD 지식 질의 응답, USD-Python 코드 생성이 가능한 최신 LLM | + | nvidia/nemotron-4-340b-instruct | 4,096 토큰 | 실제 데이터를 모사하는 다양한 합성 데이터 생성 | + | meta/codellama-70b | 100k 토큰 | 자연어 → 코드 및 코드 → 자연어 전환 가능한 LLM | + | meta/llama2-70b | 4,096 토큰 | 텍스트, 코드 생성에 최적화된 최첨단 대형 언어 모델 | + | meta/llama3-8b-instruct | 8,192 토큰 | 최첨단 언어 이해 및 추론, 텍스트 생성 기능 모델 | + | meta/llama3-70b-instruct | 8,192 토큰 | 복잡한 대화, 우수한 문맥 및 추론, 텍스트 생성 | + | meta/llama-3.1-8b-instruct | 128k 토큰 | 최첨단 언어 이해 및 추론, 텍스트 생성 기능의 첨단 모델 | + | meta/llama-3.1-70b-instruct | 128k 토큰 | 복잡한 대화, 우수한 문맥 및 추론, 텍스트 생성 | + | meta/llama-3.1-405b-instruct | 128k 토큰 | 챗봇, 코딩, 도메인 특화 작업 합성 데이터 생성 및 추론 | + | meta/llama-3.2-1b-instruct | 128k 토큰 | 최첨단 소형 언어 이해, 추론, 텍스트 생성 모델 | + | meta/llama-3.2-3b-instruct | 128k 토큰 | 최첨단 소형 언어 이해, 추론, 텍스트 생성 | + | meta/llama-3.2-11b-vision-instruct | 128k 토큰 | 최첨단 소형 언어 이해, 추론, 텍스트 생성 | + | meta/llama-3.2-90b-vision-instruct | 128k 토큰 | 최첨단 소형 언어 이해, 추론, 텍스트 생성 | + | google/gemma-7b | 8,192 토큰 | 문자열의 이해, 변환, 코드 생성을 지원하는 최첨단 텍스트 생성 모델 | + | google/gemma-2b | 8,192 토큰 | 문자열의 이해, 변환, 코드 생성을 지원하는 최첨단 텍스트 생성 모델 | + | google/codegemma-7b | 8,192 토큰 | 코드 생성 및 보완에 특화된 Google Gemma-7B 기반 모델 | + | google/codegemma-1.1-7b | 8,192 토큰 | 코드 생성, 보완, 추론, 명령 수행에 강점을 가진 고급 프로그래밍 모델 | + | google/recurrentgemma-2b | 8,192 토큰 | 긴 시퀀스 생성 시 빠른 추론을 가능케 하는 순환 아키텍처 LLM | + | google/gemma-2-9b-it | 8,192 토큰 | 문자열의 이해, 변환, 코드 생성을 지원하는 최첨단 텍스트 생성 모델 | + | google/gemma-2-27b-it | 8,192 토큰 | 문자열의 이해, 변환, 코드 생성을 지원하는 최첨단 텍스트 생성 모델 | + | google/gemma-2-2b-it | 8,192 토큰 | 문자열의 이해, 변환, 코드 생성을 지원하는 최첨단 텍스트 생성 모델 | + | google/deplot | 512 토큰 | 플롯 이미지를 표로 변환하는 원샷 비주얼 언어 이해 모델 | + | google/paligemma | 8,192 토큰 | 텍스트, 이미지 입력 이해 및 정보성 응답 생성에 능한 비전 언어 모델 | + | mistralai/mistral-7b-instruct-v0.2 | 32k 토큰 | 명령을 따르고, 요청을 완성하며, 창의적 텍스트 생성이 가능한 LLM | + | mistralai/mixtral-8x7b-instruct-v0.1 | 8,192 토큰 | 명령 및 요청 완성, 창의 텍스트 생성이 가능한 MOE LLM | + | mistralai/mistral-large | 4,096 토큰 | 실제 데이터 특성을 모방하는 다양한 합성 데이터 생성 | + | mistralai/mixtral-8x22b-instruct-v0.1 | 8,192 토큰 | 실제 데이터 특성을 모방하는 다양한 합성 데이터 생성 | + | mistralai/mistral-7b-instruct-v0.3 | 32k 토큰 | 명령을 따르고, 요청을 완성하며, 창의적 텍스트 생성이 가능한 LLM | + | nv-mistralai/mistral-nemo-12b-instruct | 128k 토큰 | 추론, 코드, 다국어 작업에 적합한 최첨단 언어 모델; 단일 GPU에서 구동 | + | mistralai/mamba-codestral-7b-v0.1 | 256k 토큰 | 광범위한 프로그래밍 언어 및 작업에서 코드 작성 및 상호작용 전용 모델 | + | microsoft/phi-3-mini-128k-instruct | 128K 토큰 | 수학·논리 추론에 강한 경량 최신 공개 LLM | + | microsoft/phi-3-mini-4k-instruct | 4,096 토큰 | 수학·논리 추론에 강한 경량 최신 공개 LLM | + | microsoft/phi-3-small-8k-instruct | 8,192 토큰 | 수학·논리 추론에 강한 경량 최신 공개 LLM | + | microsoft/phi-3-small-128k-instruct | 128K 토큰 | 수학·논리 추론에 강한 경량 최신 공개 LLM | + | microsoft/phi-3-medium-4k-instruct | 4,096 토큰 | 수학·논리 추론에 강한 경량 최신 공개 LLM | + | microsoft/phi-3-medium-128k-instruct | 128K 토큰 | 수학·논리 추론에 강한 경량 최신 공개 LLM | + | microsoft/phi-3.5-mini-instruct | 128K 토큰 | 지연, 메모리/컴퓨트 한계 환경에서 AI 응용프로그램 구동 가능한 다국어 LLM | + | microsoft/phi-3.5-moe-instruct | 128K 토큰 | 연산 효율적 콘텐츠 생성을 위한 Mixture of Experts 기반 첨단 LLM | + | microsoft/kosmos-2 | 1,024 토큰 | 이미지의 시각적 요소 이해 및 추론을 위한 획기적 멀티모달 모델 | + | microsoft/phi-3-vision-128k-instruct | 128k 토큰 | 이미지에서 고품질 추론이 가능한 최첨단 공개 멀티모달 모델 | + | microsoft/phi-3.5-vision-instruct | 128k 토큰 | 이미지에서 고품질 추론이 가능한 최첨단 공개 멀티모달 모델 | + | databricks/dbrx-instruct | 12k 토큰 | 언어 이해, 코딩, RAG에 최신 성능을 제공하는 범용 LLM | + | snowflake/arctic | 1,024 토큰 | SQL 생성 및 코딩에 집중한 기업용 고효율 추론 모델 | + | aisingapore/sea-lion-7b-instruct | 4,096 토큰 | 동남아 언어 및 문화 다양성을 반영하는 LLM | + | ibm/granite-8b-code-instruct | 4,096 토큰 | 소프트웨어 프로그래밍 LLM, 코드 생성, 완성, 설명, 멀티턴 전환 | + | ibm/granite-34b-code-instruct | 8,192 토큰 | 소프트웨어 프로그래밍 LLM, 코드 생성, 완성, 설명, 멀티턴 전환 | + | ibm/granite-3.0-8b-instruct | 4,096 토큰 | RAG, 요약, 분류, 코드, 에이전틱AI 지원 첨단 소형 언어 모델 | + | ibm/granite-3.0-3b-a800m-instruct | 4,096 토큰 | RAG, 요약, 엔터티 추출, 분류에 최적화된 고효율 Mixture of Experts 모델 | + | mediatek/breeze-7b-instruct | 4,096 토큰 | 실제 데이터 특성을 모방하는 다양한 합성 데이터 생성 | + | upstage/solar-10.7b-instruct | 4,096 토큰 | 지시 따르기, 추론, 수학 등에서 뛰어난 NLP 작업 수행 | + | writer/palmyra-med-70b-32k | 32k 토큰 | 의료 분야에서 정확하고 문맥에 맞는 응답 생성에 선도적인 LLM | + | writer/palmyra-med-70b | 32k 토큰 | 의료 분야에서 정확하고 문맥에 맞는 응답 생성에 선도적인 LLM | + | writer/palmyra-fin-70b-32k | 32k 토큰 | 금융 분석, 보고, 데이터 처리에 특화된 LLM | + | 01-ai/yi-large | 32k 토큰 | 영어, 중국어로 훈련, 챗봇 및 창의적 글쓰기 등 다양한 작업에 사용 | + | deepseek-ai/deepseek-coder-6.7b-instruct | 2k 토큰 | 고급 코드 생성, 완성, 인필링 등의 기능을 제공하는 강력한 코딩 모델 | + | rakuten/rakutenai-7b-instruct | 1,024 토큰 | 언어 이해, 추론, 텍스트 생성이 탁월한 최첨단 LLM | + | rakuten/rakutenai-7b-chat | 1,024 토큰 | 언어 이해, 추론, 텍스트 생성이 탁월한 최첨단 LLM | + | baichuan-inc/baichuan2-13b-chat | 4,096 토큰 | 중국어 및 영어 대화, 코딩, 수학, 지시 따르기, 퀴즈 풀이 지원 | + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + + NVIDIA NIM을 이용하면 Windows 기기에서 WSL2(Windows Subsystem for Linux)를 통해 강력한 LLM을 로컬로 실행할 수 있습니다. + 이 방식은 Nvidia GPU를 활용하여 프라이빗하고, 안전하며, 비용 효율적인 AI 추론을 클라우드 서비스에 의존하지 않고 구현할 수 있습니다. + 데이터 프라이버시, 오프라인 기능이 필요한 개발, 테스트, 또는 프로덕션 환경에 최적입니다. + + 로컬 NVIDIA NIM 모델 설치 단계별 가이드는 다음과 같습니다: + + 1. [NVIDIA 홈페이지](https://docs.nvidia.com/nim/wsl2/latest/getting-started.html)의 설치 안내를 따르세요. + + 2. 로컬 모델을 설치합니다. Llama 3.1-8b는 [여기](https://build.nvidia.com/meta/llama-3_1-8b-instruct/deploy) 안내를 참조하세요. + + 3. crewai 로컬 모델을 구성하세요: + + ```python Code + from crewai.llm import LLM + + local_nvidia_nim_llm = LLM( + model="openai/meta/llama-3.1-8b-instruct", # it's an openai-api compatible model + base_url="http://localhost:8000/v1", + api_key="", # api_key is required, but you can use any text + ) + + # 그런 다음 crew에서 사용할 수 있습니다: + + @CrewBase + class MyCrew(): + # ... + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + llm=local_nvidia_nim_llm + ) + + # ... + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + + ```toml Code + GROQ_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="groq/llama-3.2-90b-text-preview", + temperature=0.7 + ) + ``` + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |-----------------|-------------------|----------------------------------| + | Llama 3.1 70B/8B| 131,072 토큰 | 고성능, 대용량 문맥 작업 | + | Llama 3.2 Series| 8,192 토큰 | 범용 작업 | + | Mixtral 8x7B | 32,768 토큰 | 성능과 문맥의 균형 | + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + # Required + WATSONX_URL= + WATSONX_APIKEY= + WATSONX_PROJECT_ID= + + # Optional + WATSONX_TOKEN= + WATSONX_DEPLOYMENT_SPACE_ID= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="watsonx/meta-llama/llama-3-1-70b-instruct", + base_url="https://api.watsonx.ai/v1" + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 1. Ollama 설치: [ollama.ai](https://ollama.ai/) + 2. 모델 실행: `ollama run llama3` + 3. 구성: + + ```python Code + llm = LLM( + model="ollama/llama3:70b", + base_url="http://localhost:11434" + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + FIREWORKS_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct", + temperature=0.7 + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + PERPLEXITY_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="llama-3.1-sonar-large-128k-online", + base_url="https://api.perplexity.ai/" + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + HF_TOKEN= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct" + ) + ``` + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + + ```toml Code + SAMBANOVA_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="sambanova/Meta-Llama-3.1-8B-Instruct", + temperature=0.7 + ) + ``` + | 모델 | 컨텍스트 윈도우 | 최적 용도 | + |-----------------|---------------------|--------------------------------------| + | Llama 3.1 70B/8B| 최대 131,072 토큰 | 고성능, 대용량 문맥 작업 | + | Llama 3.1 405B | 8,192 토큰 | 고성능, 높은 출력 품질 | + | Llama 3.2 Series| 8,192 토큰 | 범용, 멀티모달 작업 | + | Llama 3.3 70B | 최대 131,072 토큰 | 고성능, 높은 출력 품질 | + | Qwen2 familly | 8,192 토큰 | 고성능, 높은 출력 품질 | + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + # Required + CEREBRAS_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="cerebras/llama3.1-70b", + temperature=0.7, + max_tokens=8192 + ) + ``` + + + Cerebras 특징: + - 빠른 추론 속도 + - 경쟁력 있는 가격 + - 속도와 품질의 우수한 밸런스 + - 긴 컨텍스트 윈도우 지원 + + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + OPENROUTER_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="openrouter/deepseek/deepseek-r1", + base_url="https://openrouter.ai/api/v1", + api_key=OPENROUTER_API_KEY + ) + ``` + + + Open Router 모델: + - openrouter/deepseek/deepseek-r1 + - openrouter/deepseek/deepseek-chat + + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + + `.env` 파일에 다음 환경 변수를 설정하십시오: + ```toml Code + NEBIUS_API_KEY= + ``` + + CrewAI 프로젝트에서의 예시 사용법: + ```python Code + llm = LLM( + model="nebius/Qwen/Qwen3-30B-A3B" + ) + ``` + + + Nebius AI Studio 특징: + - 대규모 오픈소스 모델 보유 + - 높은 속도 제한 + - 경쟁력 있는 가격 + - 속도와 품질의 우수한 밸런스 + + + **참고:** 이 제공자는 LiteLLM을 사용합니다. 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + + + +## 스트리밍 응답 + +CrewAI는 LLM의 스트리밍 응답을 지원하여, 애플리케이션이 출력물을 생성되는 즉시 실시간으로 수신하고 처리할 수 있습니다. + + + + LLM을 초기화할 때 `stream` 파라미터를 `True`로 설정하여 스트리밍을 활성화합니다: + + ```python + from crewai import LLM + + # 스트리밍이 활성화된 LLM 생성 + llm = LLM( + model="openai/gpt-4o", + stream=True # 스트리밍 활성화 + ) + ``` + + 스트리밍이 활성화되면, 응답이 생성되는 대로 청크 단위로 전달되어 보다 반응성 있는 사용자 경험을 만듭니다. + + + + CrewAI는 스트리밍 중 수신되는 각 청크에 대해 이벤트를 발생시킵니다: + + ```python + from crewai.events import ( + LLMStreamChunkEvent + ) + from crewai.events 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): + # 각 청크가 도착할 때마다 처리 + print(f"Received chunk: {event.chunk}") + + my_listener = MyCustomListener() + ``` + + + [자세한 내용은 여기를 클릭하세요](/ko/concepts/event-listener#event-listeners) + + + + + CrewAI의 모든 LLM 이벤트에는 에이전트 및 태스크 정보가 포함되어 있어, 특정 에이전트나 태스크별로 LLM 상호작용을 추적하고 필터링할 수 있습니다: + + ```python + from crewai import LLM, Agent, Task, Crew + from crewai.events import LLMStreamChunkEvent + from crewai.events import BaseEventListener + + class MyCustomListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(LLMStreamChunkEvent) + def on_llm_stream_chunk(source, event): + if researcher.id == event.agent_id: + print("\n==============\n Got event:", event, "\n==============\n") + + + my_listener = MyCustomListener() + + llm = LLM(model="gpt-4o-mini", temperature=0, stream=True) + + researcher = Agent( + role="About User", + goal="You know everything about the user.", + backstory="""You are a master at understanding people and their preferences.""", + llm=llm, + ) + + search = Task( + description="Answer the following questions about the user: {question}", + expected_output="An answer to the question.", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[search]) + + result = crew.kickoff( + inputs={"question": "..."} + ) + ``` + + + 이 기능은 다음과 같은 경우에 특히 유용합니다: + - 특정 에이전트 동작을 디버깅할 때 + - 태스크 유형별 LLM 사용 기록을 남길 때 + - 어떤 에이전트가 어떤 유형의 LLM 호출을 하는지 감사할 때 + - 특정 태스크의 성능을 모니터링할 때 + + + + +## 구조화된 LLM 호출 + +CrewAI는 Pydantic 모델을 사용하여 `response_format`을 정의함으로써 LLM 호출에서 구조화된 응답을 지원합니다. 이를 통해 프레임워크가 출력을 자동으로 파싱하고 검증할 수 있어, 수동 후처리 없이도 응답을 애플리케이션에 쉽게 통합할 수 있습니다. + +예를 들어, 예상되는 응답 구조를 나타내는 Pydantic 모델을 정의하고 LLM을 인스턴스화할 때 `response_format`으로 전달할 수 있습니다. 이 모델은 LLM 출력을 구조화된 Python 객체로 변환하는 데 사용됩니다. + +```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') +``` + +## 고급 기능 및 최적화 + +LLM 설정을 최대한 활용하는 방법을 알아보세요: + + + + CrewAI는 스마트한 컨텍스트 관리 기능을 제공합니다: + + ```python + from crewai import LLM + + # CrewAI는 자동으로 다음을 처리합니다: + # 1. 토큰 계산 및 추적 + # 2. 필요시 콘텐츠 요약 + # 3. 큰 컨텍스트에 대한 작업 분할 + + llm = LLM( + model="gpt-4", + max_tokens=4000, # 응답 길이 제한 + ) + ``` + + + 컨텍스트 관리 모범 사례: + 1. 적절한 컨텍스트 윈도우를 가진 모델 선택 + 2. 가능하면 긴 입력값을 사전 처리 + 3. 큰 문서에는 청킹(chunking) 사용 + 4. 비용 최적화를 위해 토큰 사용량 모니터링 + + + + + + + 작업에 맞는 컨텍스트 윈도우를 선택하세요: + - 작은 작업 (최대 4K 토큰): 표준 모델 + - 중간 작업 (4K~32K 사이): 확장 모델 + - 큰 작업 (32K 이상): 대형 컨텍스트 모델 + + ```python + # 모델을 적절한 설정으로 구성 + llm = LLM( + model="openai/gpt-4-turbo-preview", + temperature=0.7, # 작업에 따라 조정 + max_tokens=4096, # 출력 요구 사항에 맞게 설정 + timeout=300 # 복잡한 작업을 위한 더 긴 타임아웃 + ) + ``` + + - 사실 기반 응답에는 낮은 temperature(0.1~0.3) + - 창의적인 작업에는 높은 temperature(0.7~0.9) + + + + + 1. 토큰 사용량 모니터링 + 2. 속도 제한(rate limiting) 구현 + 3. 가능하면 캐싱 사용 + 4. 적절한 max_tokens 제한 설정 + + + + + 비용 및 성능을 최적화하기 위해 토큰 사용량을 정기적으로 모니터링하고 필요에 따라 설정을 조정하세요. + + + + + CrewAI는 내부적으로 LLM 호출에 Litellm을 사용하며, 이를 통해 특정 사용 사례에 필요하지 않은 추가 파라미터를 제거할 수 있습니다. 이를 통해 코드가 간소화되며 LLM 구성의 복잡성을 줄일 수 있습니다. + 예를 들어, stop 파라미터를 보낼 필요가 없다면 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"] + ) + ``` + + + +## 일반적인 문제 및 해결 방법 + + + + + 대부분의 인증 문제는 API 키 형식과 환경 변수 이름을 확인하여 해결할 수 있습니다. + + + ```bash + # OpenAI + OPENAI_API_KEY=sk-... + + # Anthropic + ANTHROPIC_API_KEY=sk-ant-... + ``` + + + + 항상 모델 이름에 provider 접두사를 포함하세요. + + + ```python + # 올바른 예시 + llm = LLM(model="openai/gpt-4") + + # 잘못된 예시 + llm = LLM(model="gpt-4") + ``` + + + + 대규모 작업에는 더 큰 컨텍스트 모델을 사용하세요. + + + ```python + # 대용량 컨텍스트 모델 + llm = LLM(model="openai/gpt-4o") # 128K tokens + ``` + + diff --git a/docs/v1.15.1/ko/concepts/memory.mdx b/docs/v1.15.1/ko/concepts/memory.mdx new file mode 100644 index 000000000..ea4463eea --- /dev/null +++ b/docs/v1.15.1/ko/concepts/memory.mdx @@ -0,0 +1,878 @@ +--- +title: 메모리 +description: CrewAI의 통합 메모리 시스템을 활용하여 에이전트 역량을 강화합니다. +icon: database +mode: "wide" +--- + +## 개요 + +CrewAI는 **통합 메모리 시스템**을 제공합니다 -- 단기, 장기, 엔터티, 외부 메모리 유형을 하나의 지능형 API인 단일 `Memory` 클래스로 대체합니다. 메모리는 저장 시 LLM을 사용하여 콘텐츠를 분석하고(범위, 카테고리, 중요도 추론) 의미 유사도, 최신성, 중요도를 혼합한 복합 점수로 적응형 깊이 recall을 지원합니다. + +메모리를 네 가지 방법으로 사용할 수 있습니다: **독립 실행**(스크립트, 노트북), **Crew와 함께**, **에이전트와 함께**, 또는 **Flow 내부에서**. + +## 빠른 시작 + +```python +from crewai import Memory + +memory = Memory() + +# 저장 -- LLM이 scope, categories, importance를 추론 +memory.remember("We decided to use PostgreSQL for the user database.") + +# 검색 -- 복합 점수(의미 + 최신성 + 중요도)로 결과 순위 매기기 +matches = memory.recall("What database did we choose?") +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# 빠르게 변하는 프로젝트를 위한 점수 조정 +memory = Memory(recency_weight=0.5, recency_half_life_days=7) + +# 삭제 +memory.forget(scope="/project/old") + +# 자동 구성된 scope 트리 탐색 +print(memory.tree()) +print(memory.info("/")) +``` + +## 메모리를 사용하는 네 가지 방법 + +### 독립 실행 + +스크립트, 노트북, CLI 도구 또는 독립 지식 베이스로 메모리를 사용합니다 -- 에이전트나 crew가 필요하지 않습니다. + +```python +from crewai import Memory + +memory = Memory() + +# 지식 구축 +memory.remember("The API rate limit is 1000 requests per minute.") +memory.remember("Our staging environment uses port 8080.") +memory.remember("The team agreed to use feature flags for all new releases.") + +# 나중에 필요한 것을 recall +matches = memory.recall("What are our API limits?", limit=5) +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# 긴 텍스트에서 원자적 사실 추출 +raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL +next quarter. The budget is $50k. Sarah will lead the migration.""" + +facts = memory.extract_memories(raw) +# ["Migration from MySQL to PostgreSQL planned for next quarter", +# "Database migration budget is $50k", +# "Sarah will lead the database migration"] + +for fact in facts: + memory.remember(fact) +``` + +### Crew와 함께 사용 + +기본 설정은 `memory=True`를 전달하고, 사용자 정의 동작은 설정된 `Memory` 인스턴스를 전달합니다. + +```python +from crewai import Crew, Agent, Task, Process, Memory + +# 옵션 1: 기본 메모리 +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + memory=True, + verbose=True, +) + +# 옵션 2: 조정된 점수가 있는 사용자 정의 메모리 +memory = Memory( + recency_weight=0.4, + semantic_weight=0.4, + importance_weight=0.2, + recency_half_life_days=14, +) +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + memory=memory, +) +``` + +`memory=True`일 때 crew는 기본 `Memory()`를 생성하고 crew의 `embedder` 설정을 자동으로 전달합니다. crew의 모든 에이전트는 자체 메모리가 없는 한 crew의 메모리를 공유합니다. + +각 작업 후 crew는 자동으로 작업 출력에서 개별 사실을 추출하여 저장합니다. 각 작업 전에 에이전트는 메모리에서 관련 컨텍스트를 recall하여 작업 프롬프트에 주입합니다. + +### 에이전트와 함께 사용 + +에이전트는 crew의 공유 메모리(기본값)를 사용하거나 비공개 컨텍스트를 위한 범위 지정 뷰를 받을 수 있습니다. + +```python +from crewai import Agent, Memory + +memory = Memory() + +# 연구원은 비공개 scope를 받음 -- /agent/researcher만 볼 수 있음 +researcher = Agent( + role="Researcher", + goal="Find and analyze information", + backstory="Expert researcher with attention to detail", + memory=memory.scope("/agent/researcher"), +) + +# 작성자는 crew 공유 메모리 사용 (에이전트 수준 메모리 미설정) +writer = Agent( + role="Writer", + goal="Produce clear, well-structured content", + backstory="Experienced technical writer", + # memory 미설정 -- crew에 메모리가 활성화되면 crew._memory 사용 +) +``` + +이 패턴은 연구원에게 비공개 발견을 제공하면서 작성자는 crew 공유 메모리에서 읽습니다. + +### Flow와 함께 사용 + +모든 Flow에는 내장 메모리가 있습니다. 모든 flow 메서드 내부에서 `self.remember()`, `self.recall()`, `self.extract_memories()`를 사용하세요. + +```python +from crewai.flow.flow import Flow, listen, start + +class ResearchFlow(Flow): + @start() + def gather_data(self): + findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k." + self.remember(findings, scope="/research/databases") + return findings + + @listen(gather_data) + def write_report(self, findings): + # 컨텍스트를 제공하기 위해 과거 연구 recall + past = self.recall("database performance benchmarks") + context = "\n".join(f"- {m.record.content}" for m in past) + return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}" +``` + +Flow에서의 메모리에 대한 자세한 내용은 [Flows 문서](/concepts/flows)를 참조하세요. + + +## 계층적 범위(Scopes) + +### 범위란 무엇인가 + +메모리는 파일 시스템과 유사한 계층적 scope 트리로 구성됩니다. 각 scope는 `/`, `/project/alpha` 또는 `/agent/researcher/findings`와 같은 경로입니다. + +``` +/ + /company + /company/engineering + /company/product + /project + /project/alpha + /project/beta + /agent + /agent/researcher + /agent/writer +``` + +범위는 **컨텍스트 의존적 메모리**를 제공합니다 -- 범위 내에서 recall하면 해당 트리 분기만 검색하여 정밀도와 성능을 모두 향상시킵니다. + +### 범위 추론 작동 방식 + +`remember()` 호출 시 scope를 지정하지 않으면 LLM이 콘텐츠와 기존 scope 트리를 분석한 후 최적의 배치를 제안합니다. 적합한 기존 scope가 없으면 새로 생성합니다. 시간이 지남에 따라 scope 트리는 콘텐츠 자체에서 유기적으로 성장합니다 -- 미리 스키마를 설계할 필요가 없습니다. + +```python +memory = Memory() + +# LLM이 콘텐츠에서 scope 추론 +memory.remember("We chose PostgreSQL for the user database.") +# -> /project/decisions 또는 /engineering/database 아래에 배치될 수 있음 + +# scope를 명시적으로 지정할 수도 있음 +memory.remember("Sprint velocity is 42 points", scope="/team/metrics") +``` + +### 범위 트리 시각화 + +```python +print(memory.tree()) +# / (15 records) +# /project (8 records) +# /project/alpha (5 records) +# /project/beta (3 records) +# /agent (7 records) +# /agent/researcher (4 records) +# /agent/writer (3 records) + +print(memory.info("/project/alpha")) +# ScopeInfo(path='/project/alpha', record_count=5, +# categories=['architecture', 'database'], +# oldest_record=datetime(...), newest_record=datetime(...), +# child_scopes=[]) +``` + +### MemoryScope: 하위 트리 뷰 + +`MemoryScope`는 모든 연산을 트리의 한 분기로 제한합니다. 이를 사용하는 에이전트나 코드는 해당 하위 트리 내에서만 보고 쓸 수 있습니다. + +```python +memory = Memory() + +# 특정 에이전트를 위한 scope 생성 +agent_memory = memory.scope("/agent/researcher") + +# 모든 것이 /agent/researcher 기준으로 상대적 +agent_memory.remember("Found three relevant papers on LLM memory.") +# -> /agent/researcher 아래에 저장 + +agent_memory.recall("relevant papers") +# -> /agent/researcher 아래에서만 검색 + +# subscope로 더 좁히기 +project_memory = agent_memory.subscope("project-alpha") +# -> /agent/researcher/project-alpha +``` + +### 범위 설계 모범 사례 + +- **평평하게 시작하고 LLM이 구성하게 하세요.** 범위 계층 구조를 미리 과도하게 설계하지 마세요. `memory.remember(content)`로 시작하고 콘텐츠가 축적됨에 따라 LLM의 scope 추론이 구조를 만들게 하세요. + +- **`/{엔터티_유형}/{식별자}` 패턴을 사용하세요.** `/project/alpha`, `/agent/researcher`, `/company/engineering`, `/customer/acme-corp` 같은 패턴에서 자연스러운 계층 구조가 나타납니다. + +- **데이터 유형이 아닌 관심사별로 scope를 지정하세요.** `/decisions/project/alpha` 대신 `/project/alpha/decisions`를 사용하세요. 이렇게 하면 관련 콘텐츠가 함께 유지됩니다. + +- **깊이를 얕게 유지하세요 (2-3 수준).** 깊이 중첩된 scope는 너무 희소해집니다. `/project/alpha/architecture`는 좋지만 `/project/alpha/architecture/decisions/databases/postgresql`은 너무 깊습니다. + +- **알 때는 명시적 scope를, 모를 때는 LLM 추론을 사용하세요.** 알려진 프로젝트 결정을 저장할 때는 `scope="/project/alpha/decisions"`를 전달하세요. 자유 형식 에이전트 출력을 저장할 때는 scope를 생략하고 LLM이 결정하게 하세요. + +### 사용 사례 예시 + +**다중 프로젝트 팀:** +```python +memory = Memory() +# 각 프로젝트가 자체 분기를 가짐 +memory.remember("Using microservices architecture", scope="/project/alpha/architecture") +memory.remember("GraphQL API for client apps", scope="/project/beta/api") + +# 모든 프로젝트에서 recall +memory.recall("API design decisions") + +# 특정 프로젝트 내에서만 +memory.recall("API design", scope="/project/beta") +``` + +**공유 지식과 에이전트별 비공개 컨텍스트:** +```python +memory = Memory() + +# 연구원은 비공개 발견을 가짐 +researcher_memory = memory.scope("/agent/researcher") + +# 작성자는 자체 scope와 공유 회사 지식에서 읽을 수 있음 +writer_view = memory.slice( + scopes=["/agent/writer", "/company/knowledge"], + read_only=True, +) +``` + +**고객 지원 (고객별 컨텍스트):** +```python +memory = Memory() + +# 각 고객이 격리된 컨텍스트를 가짐 +memory.remember("Prefers email communication", scope="/customer/acme-corp") +memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp") + +# 공유 제품 문서는 모든 에이전트가 접근 가능 +memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs") +``` + + +## 메모리 슬라이스 + +### 슬라이스란 무엇인가 + +`MemorySlice`는 여러 개의 분리된 scope에 대한 뷰입니다. 하나의 하위 트리로 제한하는 scope와 달리, 슬라이스는 여러 분기에서 동시에 recall할 수 있게 합니다. + +### 슬라이스 vs 범위 사용 시기 + +- **범위(Scope)**: 에이전트나 코드 블록을 단일 하위 트리로 제한해야 할 때 사용. 예: `/agent/researcher`만 보는 에이전트. +- **슬라이스(Slice)**: 여러 분기의 컨텍스트를 결합해야 할 때 사용. 예: 자체 scope와 공유 회사 지식에서 읽는 에이전트. + +### 읽기 전용 슬라이스 + +가장 일반적인 패턴: 에이전트에게 여러 분기에 대한 읽기 액세스를 제공하되 공유 영역에 쓰지 못하게 합니다. + +```python +memory = Memory() + +# 에이전트는 자체 scope와 회사 지식에서 recall 가능, +# 하지만 회사 지식에 쓸 수 없음 +agent_view = memory.slice( + scopes=["/agent/researcher", "/company/knowledge"], + read_only=True, +) + +matches = agent_view.recall("company security policies", limit=5) +# /agent/researcher와 /company/knowledge 모두에서 검색, 결과 병합 및 순위 매기기 + +agent_view.remember("new finding") # PermissionError 발생 (읽기 전용) +``` + +### 읽기/쓰기 슬라이스 + +읽기 전용이 비활성화되면 포함된 scope 중 어디에든 쓸 수 있지만, 어떤 scope인지 명시적으로 지정해야 합니다. + +```python +view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False) + +# 쓸 때 scope를 반드시 지정 +view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"]) +``` + + +## 복합 점수(Composite Scoring) + +Recall 결과는 세 가지 신호의 가중 조합으로 순위가 매겨집니다: + +``` +composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance +``` + +여기서: +- **similarity** = 벡터 인덱스에서 `1 / (1 + distance)` (0에서 1) +- **decay** = `0.5^(age_days / half_life_days)` -- 지수 감쇠 (오늘은 1.0, 반감기에서 0.5) +- **importance** = 레코드의 중요도 점수 (0에서 1), 인코딩 시 설정 + +`Memory` 생성자에서 직접 설정합니다: + +```python +# 스프린트 회고: 최근 메모리 선호, 짧은 반감기 +memory = Memory( + recency_weight=0.5, + semantic_weight=0.3, + importance_weight=0.2, + recency_half_life_days=7, +) + +# 아키텍처 지식 베이스: 중요한 메모리 선호, 긴 반감기 +memory = Memory( + recency_weight=0.1, + semantic_weight=0.5, + importance_weight=0.4, + recency_half_life_days=180, +) +``` + +각 `MemoryMatch`에는 결과가 해당 위치에 순위된 이유를 볼 수 있는 `match_reasons` 목록이 포함됩니다 (예: `["semantic", "recency", "importance"]`). + + +## LLM 분석 레이어 + +메모리는 LLM을 세 가지 방식으로 사용합니다: + +1. **저장 시** -- scope, categories, importance를 생략하면 LLM이 콘텐츠를 분석하여 scope, categories, importance, 메타데이터(엔터티, 날짜, 주제)를 제안합니다. +2. **recall 시** -- deep/auto recall의 경우 LLM이 쿼리(키워드, 시간 힌트, 제안 scope, 복잡도)를 분석하여 검색을 안내합니다. +3. **메모리 추출** -- `extract_memories(content)`는 원시 텍스트(예: 작업 출력)를 개별 메모리 문장으로 나눕니다. 에이전트는 각 문장에 `remember()`를 호출하기 전에 이를 사용하여 하나의 큰 블록 대신 원자적 사실이 저장되도록 합니다. + +모든 분석은 LLM 실패 시 우아하게 저하됩니다 -- [오류 시 동작](#오류-시-동작)을 참조하세요. + + +## 메모리 통합 + +새 콘텐츠를 저장할 때 인코딩 파이프라인은 자동으로 스토리지에서 유사한 기존 레코드를 확인합니다. 유사도가 `consolidation_threshold`(기본값 0.85) 이상이면 LLM이 처리 방법을 결정합니다: + +- **keep** -- 기존 레코드가 여전히 정확하고 중복이 아닙니다. +- **update** -- 기존 레코드를 새 정보로 업데이트해야 합니다 (LLM이 병합된 콘텐츠를 제공). +- **delete** -- 기존 레코드가 오래되었거나, 대체되었거나, 모순됩니다. +- **insert_new** -- 새 콘텐츠를 별도의 레코드로 삽입해야 하는지 여부. + +이를 통해 중복이 축적되는 것을 방지합니다. 예를 들어, "CrewAI ensures reliable operation"을 세 번 저장하면 통합이 중복을 인식하고 하나의 레코드만 유지합니다. + +### 배치 내 중복 제거 + +`remember_many()`를 사용할 때 동일 배치 내의 항목은 스토리지에 도달하기 전에 서로 비교됩니다. 두 항목의 코사인 유사도가 `batch_dedup_threshold`(기본값 0.98) 이상이면 나중 항목이 자동으로 삭제됩니다. 이는 LLM 호출 없이 순수 벡터 연산으로 단일 배치 내의 정확하거나 거의 정확한 중복을 잡아냅니다. + +```python +# 2개의 레코드만 저장됨 (세 번째는 첫 번째의 거의 중복) +memory.remember_many([ + "CrewAI supports complex workflows.", + "Python is a great language.", + "CrewAI supports complex workflows.", # 배치 내 중복 제거로 삭제 +]) +``` + + +## 비차단 저장 + +`remember_many()`는 **비차단**입니다 -- 인코딩 파이프라인을 백그라운드 스레드에 제출하고 즉시 반환합니다. 이는 메모리가 저장되는 동안 에이전트가 다음 작업을 계속할 수 있음을 의미합니다. + +```python +# 즉시 반환 -- 저장은 백그라운드에서 발생 +memory.remember_many(["Fact A.", "Fact B.", "Fact C."]) + +# recall()은 검색 전에 보류 중인 저장을 자동으로 대기 +matches = memory.recall("facts") # 3개 레코드 모두 확인 가능 +``` + +### 읽기 배리어 + +모든 `recall()` 호출은 검색 전에 자동으로 `drain_writes()`를 호출하여 쿼리가 항상 최신 저장된 레코드를 볼 수 있도록 합니다. 이는 투명하게 작동하므로 별도로 신경 쓸 필요가 없습니다. + +### Crew 종료 + +crew가 완료되면 `kickoff()`는 `finally` 블록에서 보류 중인 모든 메모리 저장을 드레인하므로, 백그라운드 저장이 진행 중인 상태에서 crew가 완료되더라도 저장이 손실되지 않습니다. + +### 독립 실행 사용 + +crew 수명 주기가 없는 스크립트나 노트북에서는 `drain_writes()` 또는 `close()`를 명시적으로 호출하세요: + +```python +memory = Memory() +memory.remember_many(["Fact A.", "Fact B."]) + +# 옵션 1: 보류 중인 저장 대기 +memory.drain_writes() + +# 옵션 2: 드레인 후 백그라운드 풀 종료 +memory.close() +``` + + +## 출처 및 개인정보 + +모든 메모리 레코드는 출처 추적을 위한 `source` 태그와 접근 제어를 위한 `private` 플래그를 가질 수 있습니다. + +### 출처 추적 + +`source` 매개변수는 메모리의 출처를 식별합니다: + +```python +# 메모리에 출처 태그 지정 +memory.remember("User prefers dark mode", source="user:alice") +memory.remember("System config updated", source="admin") +memory.remember("Agent found a bug", source="agent:debugger") + +# 특정 출처의 메모리만 recall +matches = memory.recall("user preferences", source="user:alice") +``` + +### 비공개 메모리 + +비공개 메모리는 `source`가 일치할 때만 recall에서 볼 수 있습니다: + +```python +# 비공개 메모리 저장 +memory.remember("Alice's API key is sk-...", source="user:alice", private=True) + +# 이 recall은 비공개 메모리를 볼 수 있음 (source 일치) +matches = memory.recall("API key", source="user:alice") + +# 이 recall은 볼 수 없음 (다른 source) +matches = memory.recall("API key", source="user:bob") + +# 관리자 액세스: source에 관계없이 모든 비공개 레코드 보기 +matches = memory.recall("API key", include_private=True) +``` + +이는 서로 다른 사용자의 메모리가 격리되어야 하는 다중 사용자 또는 엔터프라이즈 배포에서 특히 유용합니다. + + +## RecallFlow (딥 Recall) + +`recall()`은 두 가지 깊이를 지원합니다: + +- **`depth="shallow"`** -- 복합 점수를 사용한 직접 벡터 검색. 빠름 (~200ms), LLM 호출 없음. +- **`depth="deep"` (기본값)** -- 다단계 RecallFlow 실행: 쿼리 분석, scope 선택, 병렬 벡터 검색, 신뢰도 기반 라우팅, 신뢰도가 낮을 때 선택적 재귀 탐색. + +**스마트 LLM 건너뛰기**: `query_analysis_threshold`(기본값 200자)보다 짧은 쿼리는 deep 모드에서도 LLM 쿼리 분석을 완전히 건너뜁니다. "What database do we use?"와 같은 짧은 쿼리는 이미 좋은 검색 구문이므로 LLM 분석이 큰 가치를 더하지 않습니다. 이를 통해 일반적인 짧은 쿼리에서 recall당 ~1-3초를 절약합니다. 긴 쿼리(예: 전체 작업 설명)만 대상 하위 쿼리로의 LLM 분석을 거칩니다. + +```python +# Shallow: 순수 벡터 검색, LLM 없음 +matches = memory.recall("What did we decide?", limit=10, depth="shallow") + +# Deep (기본값): 긴 쿼리에 대한 LLM 분석을 포함한 지능형 검색 +matches = memory.recall( + "Summarize all architecture decisions from this quarter", + limit=10, + depth="deep", +) +``` + +RecallFlow 라우터를 제어하는 신뢰도 임계값은 설정 가능합니다: + +```python +memory = Memory( + confidence_threshold_high=0.9, # 매우 확신할 때만 합성 + confidence_threshold_low=0.4, # 더 적극적으로 깊이 탐색 + exploration_budget=2, # 최대 2라운드 탐색 허용 + query_analysis_threshold=200, # 이보다 짧은 쿼리는 LLM 건너뛰기 +) +``` + + +## Embedder 설정 + +메모리는 의미 검색을 위해 텍스트를 벡터로 변환하는 임베딩 모델이 필요합니다. 세 가지 방법으로 설정할 수 있습니다. + +### Memory에 직접 전달 + +```python +from crewai import Memory + +# 설정 dict로 +memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}) + +# 사전 구축된 callable로 +from crewai.rag.embeddings.factory import build_embedder +embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}) +memory = Memory(embedder=embedder) +``` + +### Crew Embedder 설정으로 + +`memory=True` 사용 시 crew의 `embedder` 설정이 전달됩니다: + +```python +from crewai import Crew + +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}, +) +``` + +### 제공자 예시 + + + +```python +memory = Memory(embedder={ + "provider": "openai", + "config": { + "model_name": "text-embedding-3-small", + # "api_key": "sk-...", # 또는 OPENAI_API_KEY 환경 변수 설정 + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "ollama", + "config": { + "model_name": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "azure", + "config": { + "deployment_id": "your-embedding-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com", + "api_version": "2024-02-01", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-generativeai", + "config": { + "model_name": "gemini-embedding-001", + # "api_key": "...", # 또는 GOOGLE_API_KEY 환경 변수 설정 + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-vertex", + "config": { + "model_name": "gemini-embedding-001", + "project_id": "your-gcp-project-id", + "location": "us-central1", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "cohere", + "config": { + "model_name": "embed-english-v3.0", + # "api_key": "...", # 또는 COHERE_API_KEY 환경 변수 설정 + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "voyageai", + "config": { + "model": "voyage-3", + # "api_key": "...", # 또는 VOYAGE_API_KEY 환경 변수 설정 + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "amazon-bedrock", + "config": { + "model_name": "amazon.titan-embed-text-v1", + # 기본 AWS 자격 증명 사용 (boto3 세션) + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "huggingface", + "config": { + "model_name": "sentence-transformers/all-MiniLM-L6-v2", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "jina", + "config": { + "model_name": "jina-embeddings-v2-base-en", + # "api_key": "...", # 또는 JINA_API_KEY 환경 변수 설정 + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "watsonx", + "config": { + "model_id": "ibm/slate-30m-english-rtrvr", + "api_key": "your-watsonx-api-key", + "project_id": "your-project-id", + "url": "https://us-south.ml.cloud.ibm.com", + }, +}) +``` + + + +```python +# 문자열 목록을 받아 벡터 목록을 반환하는 callable 전달 +def my_embedder(texts: list[str]) -> list[list[float]]: + # 임베딩 로직 + return [[0.1, 0.2, ...] for _ in texts] + +memory = Memory(embedder=my_embedder) +``` + + + +### 제공자 참조 + +| 제공자 | 키 | 일반적인 모델 | 참고 | +| :--- | :--- | :--- | :--- | +| OpenAI | `openai` | `text-embedding-3-small` | 기본값. `OPENAI_API_KEY` 설정. | +| Ollama | `ollama` | `mxbai-embed-large` | 로컬, API 키 불필요. | +| Azure OpenAI | `azure` | `text-embedding-ada-002` | `deployment_id` 필요. | +| Google AI | `google-generativeai` | `gemini-embedding-001` | `GOOGLE_API_KEY` 설정. | +| Google Vertex | `google-vertex` | `gemini-embedding-001` | `project_id` 필요. | +| Cohere | `cohere` | `embed-english-v3.0` | 강력한 다국어 지원. | +| VoyageAI | `voyageai` | `voyage-3` | 검색에 최적화. | +| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | boto3 자격 증명 사용. | +| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | 로컬 sentence-transformers. | +| Jina | `jina` | `jina-embeddings-v2-base-en` | `JINA_API_KEY` 설정. | +| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | `project_id` 필요. | +| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | 로컬, API 키 불필요. | +| Custom | `custom` | -- | `embedding_callable` 필요. | + + +## LLM 설정 + +메모리는 저장 분석(scope, categories, importance 추론), 통합 결정, 딥 recall 쿼리 분석에 LLM을 사용합니다. 사용할 모델을 설정할 수 있습니다. + +```python +from crewai import Memory, LLM + +# 기본값: gpt-4o-mini +memory = Memory() + +# 다른 OpenAI 모델 사용 +memory = Memory(llm="gpt-4o") + +# Anthropic 사용 +memory = Memory(llm="anthropic/claude-3-haiku-20240307") + +# 완전한 로컬/비공개 분석을 위해 Ollama 사용 +memory = Memory(llm="ollama/llama3.2") + +# Google Gemini 사용 +memory = Memory(llm="gemini/gemini-2.0-flash") + +# 사용자 정의 설정이 있는 사전 구성된 LLM 인스턴스 전달 +llm = LLM(model="gpt-4o", temperature=0) +memory = Memory(llm=llm) +``` + +LLM은 **지연 초기화**됩니다 -- 처음 필요할 때만 생성됩니다. 즉, API 키가 설정되지 않아도 `Memory()` 생성 시에는 실패하지 않습니다. 오류는 LLM이 실제로 호출될 때만 발생합니다(예: 명시적 scope/categories 없이 저장할 때 또는 딥 recall 중). + +완전한 오프라인/비공개 운영을 위해 LLM과 embedder 모두에 로컬 모델을 사용하세요: + +```python +memory = Memory( + llm="ollama/llama3.2", + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) +``` + + +## 스토리지 백엔드 + +- **기본값**: LanceDB, `./.crewai/memory` 아래에 저장 (또는 환경 변수가 설정된 경우 `$CREWAI_STORAGE_DIR/memory`, 또는 `storage="path/to/dir"`로 전달한 경로). +- **사용자 정의 백엔드**: `StorageBackend` 프로토콜을 구현하고(`crewai.memory.storage.backend` 참조) `Memory(storage=your_backend)`에 인스턴스를 전달합니다. + + +## 탐색(Discovery) + +scope 계층 구조, 카테고리, 레코드를 검사합니다: + +```python +memory.tree() # scope 및 레코드 수의 포맷된 트리 +memory.tree("/project", max_depth=2) # 하위 트리 뷰 +memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest +memory.list_scopes("/") # 직계 자식 scope +memory.list_categories() # 카테고리 이름 및 개수 +memory.list_records(scope="/project/alpha", limit=20) # scope의 레코드, 최신순 +``` + + +## 오류 시 동작 + +분석 중 LLM이 실패하면(네트워크 오류, 속도 제한, 잘못된 응답) 메모리는 우아하게 저하됩니다: + +- **저장 분석** -- 경고가 로깅되고 메모리는 기본 scope `/`, 빈 categories, importance `0.5`로 저장됩니다. +- **메모리 추출** -- 전체 콘텐츠가 단일 메모리로 저장되어 누락되지 않습니다. +- **쿼리 분석** -- recall은 단순 scope 선택 및 벡터 검색으로 폴백하여 결과를 계속 반환합니다. + +이러한 분석 실패에서는 예외가 발생하지 않으며, 스토리지 또는 embedder 실패만 예외를 발생시킵니다. + + +## 개인정보 참고 + +메모리 콘텐츠는 분석을 위해 설정된 LLM으로 전송됩니다(저장 시 scope/categories/importance, 쿼리 분석 및 선택적 딥 recall). 민감한 데이터의 경우 로컬 LLM(예: Ollama)을 사용하거나 제공자가 규정 요구 사항을 충족하는지 확인하세요. + + +## 메모리 이벤트 + +모든 메모리 연산은 `source_type="unified_memory"`로 이벤트를 발생시킵니다. 시간, 오류, 콘텐츠를 수신할 수 있습니다. + +| 이벤트 | 설명 | 주요 속성 | +| :---- | :---------- | :------------- | +| **MemoryQueryStartedEvent** | 쿼리 시작 | `query`, `limit` | +| **MemoryQueryCompletedEvent** | 쿼리 성공 | `query`, `results`, `query_time_ms` | +| **MemoryQueryFailedEvent** | 쿼리 실패 | `query`, `error` | +| **MemorySaveStartedEvent** | 저장 시작 | `value`, `metadata` | +| **MemorySaveCompletedEvent** | 저장 성공 | `value`, `save_time_ms` | +| **MemorySaveFailedEvent** | 저장 실패 | `value`, `error` | +| **MemoryRetrievalStartedEvent** | 에이전트 검색 시작 | `task_id` | +| **MemoryRetrievalCompletedEvent** | 에이전트 검색 완료 | `task_id`, `memory_content`, `retrieval_time_ms` | + +예: 쿼리 시간 모니터링: + +```python +from crewai.events import BaseEventListener, MemoryQueryCompletedEvent + +class MemoryMonitor(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(MemoryQueryCompletedEvent) + def on_done(source, event): + if getattr(event, "source_type", None) == "unified_memory": + print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms") +``` + + +## 문제 해결 + +**메모리가 유지되지 않나요?** +- 저장 경로에 쓰기 권한이 있는지 확인하세요(기본값 `./.crewai/memory`). 다른 디렉터리를 사용하려면 `storage="./your_path"`를 전달하거나 `CREWAI_STORAGE_DIR` 환경 변수를 설정하세요. +- crew 사용 시 `memory=True` 또는 `memory=Memory(...)`가 설정되었는지 확인하세요. + +**recall이 느린가요?** +- 일상적인 에이전트 컨텍스트에는 `depth="shallow"`를 사용하세요. 복잡한 쿼리에만 `depth="deep"`을 사용하세요. +- 더 많은 쿼리에서 LLM 분석을 건너뛰려면 `query_analysis_threshold`를 높이세요. + +**로그에 LLM 분석 오류가 있나요?** +- 메모리는 안전한 기본값으로 계속 저장/recall합니다. 전체 LLM 분석을 원하면 API 키, 속도 제한, 모델 가용성을 확인하세요. + +**로그에 백그라운드 저장 오류가 있나요?** +- 메모리 저장은 백그라운드 스레드에서 실행됩니다. 오류는 `MemorySaveFailedEvent`로 발생하지만 에이전트를 중단시키지 않습니다. 근본 원인(보통 LLM 또는 embedder 연결 문제)은 로그를 확인하세요. + +**동시 쓰기 충돌이 있나요?** +- LanceDB 연산은 공유 잠금으로 직렬화되며 충돌 시 자동으로 재시도됩니다. 이는 동일 데이터베이스를 가리키는 여러 `Memory` 인스턴스(예: 에이전트 메모리 + crew 메모리)를 처리합니다. 별도의 조치가 필요하지 않습니다. + +**터미널에서 메모리 탐색:** +```bash +crewai memory # TUI 브라우저 열기 +crewai memory --storage-path ./my_memory # 특정 디렉터리 지정 +``` + +**메모리 초기화(예: 테스트용):** +```python +crew.reset_memories(command_type="memory") # 통합 메모리 초기화 +# 또는 Memory 인스턴스에서: +memory.reset() # 모든 scope +memory.reset(scope="/project/old") # 해당 하위 트리만 +``` + + +## 설정 참조 + +모든 설정은 `Memory(...)`에 키워드 인수로 전달됩니다. 모든 매개변수에는 합리적인 기본값이 있습니다. + +| 매개변수 | 기본값 | 설명 | +| :--- | :--- | :--- | +| `llm` | `"gpt-4o-mini"` | 분석용 LLM (모델 이름 또는 `BaseLLM` 인스턴스). | +| `storage` | `"lancedb"` | 스토리지 백엔드 (`"lancedb"`, 경로 문자열 또는 `StorageBackend` 인스턴스). | +| `embedder` | `None` (OpenAI 기본값) | Embedder (설정 dict, callable 또는 `None`으로 기본 OpenAI). | +| `recency_weight` | `0.3` | 복합 점수에서 최신성 가중치. | +| `semantic_weight` | `0.5` | 복합 점수에서 의미 유사도 가중치. | +| `importance_weight` | `0.2` | 복합 점수에서 중요도 가중치. | +| `recency_half_life_days` | `30` | 최신성 점수가 절반으로 줄어드는 일수(지수 감쇠). | +| `consolidation_threshold` | `0.85` | 저장 시 통합이 트리거되는 유사도. `1.0`으로 설정하면 비활성화. | +| `consolidation_limit` | `5` | 통합 중 비교할 기존 레코드 최대 수. | +| `default_importance` | `0.5` | 미제공 시 및 LLM 분석이 생략될 때 할당되는 중요도. | +| `batch_dedup_threshold` | `0.98` | `remember_many()` 배치 내 거의 중복 삭제를 위한 코사인 유사도. | +| `confidence_threshold_high` | `0.8` | recall 신뢰도가 이 값 이상이면 결과를 직접 반환. | +| `confidence_threshold_low` | `0.5` | recall 신뢰도가 이 값 미만이면 더 깊은 탐색 트리거. | +| `complex_query_threshold` | `0.7` | 복잡한 쿼리의 경우 이 신뢰도 미만에서 더 깊이 탐색. | +| `exploration_budget` | `1` | 딥 recall 중 LLM 기반 탐색 라운드 수. | +| `query_analysis_threshold` | `200` | 이 길이(문자 수)보다 짧은 쿼리는 딥 recall 중 LLM 분석을 건너뜀. | diff --git a/docs/v1.15.1/ko/concepts/planning.mdx b/docs/v1.15.1/ko/concepts/planning.mdx new file mode 100644 index 000000000..2d3dccda6 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/planning.mdx @@ -0,0 +1,153 @@ +--- +title: 계획 +description: CrewAI Crew에 계획을 추가하고 성능을 향상시키는 방법을 알아보세요. +icon: ruler-combined +mode: "wide" +--- + +## 개요 + +CrewAI의 planning 기능을 통해 crew에 계획 수립 기능을 추가할 수 있습니다. 해당 기능을 활성화하면, 각 Crew 반복 전에 모든 Crew 정보가 AgentPlanner로 전송되어 작업이 단계별로 계획되며, 이 계획이 각 작업 설명에 추가됩니다. + +### Planning 기능 사용하기 + +Planning 기능을 시작하는 것은 매우 간단합니다. 필요한 유일한 단계는 Crew에 `planning=True`를 추가하는 것입니다: + + +```python Code +from crewai import Crew, Agent, Task, Process + +# Assemble your crew with planning capabilities +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, +) +``` + + +이 시점부터 crew는 planning이 활성화되며, 각 반복 전에 작업이 계획됩니다. + + +Planning이 활성화되면, crewAI는 planning을 위해 기본 LLM으로 `gpt-4o-mini`를 사용합니다. 이 기능은 유효한 OpenAI API 키가 필요합니다. 에이전트가 서로 다른 LLM을 사용할 수도 있기 때문에, OpenAI API 키가 설정되어 있지 않거나 LLM API 호출과 관련된 예상치 못한 동작이 발생할 경우 혼란을 일으킬 수 있습니다. + + +#### LLM 계획하기 + +이제 작업을 계획할 때 사용할 LLM을 정의할 수 있습니다. + +기본 사례 예제를 실행하면 아래와 같은 출력이 나타나는데, 이는 AgentPlanner의 출력으로, 에이전트 작업에 추가할 단계별 논리를 생성합니다. + + +```python Code +from crewai import Crew, Agent, Task, Process + +# Assemble your crew with planning capabilities and custom LLM +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, + planning_llm="gpt-4o" +) + +# Run the crew +my_crew.kickoff() +``` + +```markdown Result +[2024-07-15 16:49:11][INFO]: Planning the crew execution +**작업 실행을 위한 단계별 계획** + +**작업 번호 1: AI LLM에 대해 철저히 조사하기** + +**에이전트:** AI LLMs 시니어 데이터 리서처 + +**에이전트 목표:** AI LLM의 최신 개발 동향 파악 + +**작업 예상 결과:** AI LLM에 대한 가장 관련성 높은 정보 10가지가 포함된 리스트 + +**작업 도구:** 명시되지 않음 + +**에이전트 도구:** 명시되지 않음 + +**단계별 계획:** + +1. **조사 범위 정의:** + + - 아키텍처의 발전, 사용 사례, 윤리적 고려사항, 성능 측정 기준 등 AI LLM의 특정 영역을 결정합니다. + +2. **신뢰할 수 있는 출처 식별:** + + - 학술지, 산업 리포트, 컨퍼런스(예: NeurIPS, ACL), AI 연구소(예: OpenAI, Google AI), 온라인 데이터베이스(예: IEEE Xplore, arXiv) 등 AI 연구를 위한 평판 좋은 출처를 나열합니다. + +3. **데이터 수집:** + + - 2024년 및 2025년 초에 발표된 최신 논문, 기사, 리포트를 검색합니다. + - "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025"와 같은 키워드를 사용합니다. + +4. **발견 사항 분석:** + + - 각 출처에서 핵심 내용을 읽고 요약합니다. + - 지난 1년간 소개된 새로운 기술, 모델, 애플리케이션 등을 강조합니다. + +5. **정보 정리:** + + - 정보를 관련 주제별로 분류합니다(예: 새로운 아키텍처, 윤리적 영향, 실세계 적용 등). + - 각 핵심 포인트는 간결하면서도 정보가 풍부하도록 합니다. + +6. **리스트 작성:** + + - 가장 관련성 높은 10가지 정보를 불릿 포인트로 정리합니다. + - 리스트가 명확하고 적절한지 검토합니다. + +**예상 결과:** + +AI LLM에 대한 가장 관련성 높은 정보 10가지를 담은 불릿 포인트 리스트. + +--- + +**작업 번호 2: 받은 컨텍스트를 검토하고 각 주제를 리포트의 전체 섹션으로 확장하기** + +**에이전트:** AI LLMs 리포팅 애널리스트 + +**에이전트 목표:** AI LLM 데이터 분석 및 연구 결과를 기반으로 상세 리포트를 작성 + +**작업 예상 결과:** 주요 주제별로 각 섹션이 포함된 완전한 리포트 (마크다운 형식, '```' 없이) + +**작업 도구:** 명시되지 않음 + +**에이전트 도구:** 명시되지 않음 + +**단계별 계획:** + +1. **불릿 포인트 검토:** + - AI LLMs 시니어 데이터 리서처가 제공한 10가지 불릿 포인트 리스트를 꼼꼼히 읽습니다. + +2. **리포트 개요 작성:** + - 각 불릿 포인트를 주요 섹션 제목으로 삼아 개요를 만듭니다. + - 각 주요 제목 아래 하위 섹션을 기획하여 해당 주제의 다양한 측면을 다룹니다. + +3. **추가 세부 사항 조사:** + - 각 불릿 포인트별로, 더 자세한 정보를 수집하기 위해 필요 시 추가 조사를 진행합니다. + - 각 섹션을 뒷받침할 사례 연구, 예시, 통계자료 등을 찾습니다. + +4. **상세 섹션 작성:** + - 각 불릿 포인트를 포괄적인 섹션으로 확장합니다. + - 각 섹션에는 도입, 상세 설명, 예시, 결론이 포함되어야 합니다. + - 제목, 부제목, 리스트, 강조 등 마크다운 포맷을 사용합니다. + +5. **검토 및 편집:** + - 리포트의 명확성, 일관성, 정확성을 위해 교정합니다. + - 리포트가 각 섹션에서 논리적으로 자연스럽게 흐르는지 확인합니다. + - 마크다운 기준에 맞게 포맷을 맞춥니다. + +6. **리포트 최종화:** + - 모든 섹션이 확장되고 상세하게 작성되어 완전한 리포트가 되었는지 확인합니다. + - 포맷을 다시 확인하고 필요한 경우 수정합니다. + +**예상 결과:** +주요 주제별로 각 섹션이 포함된 완전한 리포트 (마크다운 형식, '```' 없이). +``` + \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/processes.mdx b/docs/v1.15.1/ko/concepts/processes.mdx new file mode 100644 index 000000000..d6b52f018 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/processes.mdx @@ -0,0 +1,66 @@ +--- +title: 프로세스 +description: CrewAI에서 프로세스를 통한 워크플로우 관리에 대한 상세 가이드와 최신 구현 세부 사항. +icon: bars-staggered +mode: "wide" +--- + +## 개요 + + + 프로세스는 에이전트에 의해 작업이 실행되도록 조정하며, 이는 인간 팀에서의 프로젝트 관리와 유사합니다. + 이러한 프로세스는 작업이 미리 정의된 전략에 따라 효율적으로 분배되고 실행되도록 보장합니다. + + +## 프로세스 구현 + +- **순차적(Sequential)**: 작업을 순차적으로 실행하여 작업이 질서 있게 진행되도록 보장합니다. +- **계층적(Hierarchical)**: 작업을 관리 계층 구조로 조직하며, 작업은 체계적인 명령 체계를 기반으로 위임 및 실행됩니다. 계층적 프로세스를 활성화하려면 매니저 언어 모델(`manager_llm`) 또는 커스텀 매니저 에이전트(`manager_agent`)를 crew에서 지정해야 하며, 이를 통해 매니저가 작업을 생성하고 관리할 수 있도록 지원합니다. + +## 팀워크에서 프로세스의 역할 +프로세스는 개별 에이전트가 통합된 단위로 작동할 수 있도록 하여, 공통된 목표를 효율적이고 일관성 있게 달성하도록 노력하는 과정을 간소화합니다. + +## 프로세스를 Crew에 할당하기 +프로세스를 crew에 할당하려면, crew 생성 시 프로세스 유형을 지정하여 실행 전략을 설정합니다. 계층적 프로세스의 경우, 매니저 에이전트에 대해 `manager_llm` 또는 `manager_agent`를 반드시 정의해야 합니다. + +```python +from crewai import Crew, Process + +# Example: Creating a crew with a sequential process +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.sequential +) + +# Example: Creating a crew with a hierarchical process +# Ensure to provide a manager_llm or manager_agent +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.hierarchical, + manager_llm="gpt-4o" + # or + # manager_agent=my_manager_agent +) +``` +**참고:** `Crew` 객체를 생성하기 전에 반드시 `my_agents`와 `my_tasks`가 정의되어 있어야 하며, 계층적 프로세스의 경우 `manager_llm` 또는 `manager_agent` 중 하나도 필요합니다. + +## 순차적 프로세스 + +이 방법은 동적인 팀 워크플로우를 반영하며, 작업을 신중하고 체계적으로 진행합니다. 작업 수행은 작업 목록에 정의된 순서를 따르며, 한 작업의 출력이 다음 작업의 컨텍스트로 사용됩니다. + +작업 컨텍스트를 사용자 지정하려면, `Task` 클래스의 `context` 매개변수를 사용하여 이후 작업에 컨텍스트로 사용될 출력을 지정하세요. + +## 계층적 프로세스 + +기업의 계층 구조를 모방하는 CrewAI는 사용자 지정 관리자 에이전트를 지정하거나 자동으로 생성할 수 있으며, 이때 관리자 언어 모델(`manager_llm`)의 지정을 요구합니다. 이 에이전트는 계획 수립, 위임, 검증 등 작업 실행을 감독합니다. 작업은 미리 할당되지 않으며, 관리자가 에이전트의 역량에 따라 작업을 분배하고, 산출물을 검토하며, 작업 완료 여부를 평가합니다. + +## Process 클래스: 상세 개요 + +`Process` 클래스는 열거형(`Enum`)으로 구현되어 타입 안전성을 보장하며, 프로세스 값을 정의된 타입(`sequential`, `hierarchical`)으로 제한합니다. + +## 결론 + +CrewAI 내의 프로세스를 통해 촉진되는 구조화된 협업은 에이전트 간 체계적인 팀워크를 가능하게 하는 데 매우 중요합니다. +이 문서는 최신 기능과 향상 사항을 반영하도록 업데이트되었으며, 사용자가 가장 최신이고 포괄적인 정보를 이용할 수 있도록 보장합니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/production-architecture.mdx b/docs/v1.15.1/ko/concepts/production-architecture.mdx new file mode 100644 index 000000000..112e744a9 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/production-architecture.mdx @@ -0,0 +1,162 @@ +--- +title: 프로덕션 아키텍처 +description: CrewAI로 프로덕션 수준의 AI 애플리케이션을 구축하기 위한 모범 사례 +icon: server +mode: "wide" +--- + +# Flow 우선 사고방식 (Flow-First Mindset) + +CrewAI로 프로덕션 AI 애플리케이션을 구축할 때는 **Flow로 시작하는 것을 권장합니다**. + +개별 Crews나 Agents를 실행하는 것도 가능하지만, 이를 Flow로 감싸면 견고하고 확장 가능한 애플리케이션에 필요한 구조를 제공합니다. + +## 왜 Flows인가? + +1. **상태 관리 (State Management)**: Flows는 애플리케이션의 여러 단계에 걸쳐 상태를 관리하는 내장된 방법을 제공합니다. 이는 Crews 간에 데이터를 전달하고, 컨텍스트를 유지하며, 사용자 입력을 처리하는 데 중요합니다. +2. **제어 (Control)**: Flows를 사용하면 루프, 조건문, 분기 로직을 포함한 정확한 실행 경로를 정의할 수 있습니다. 이는 예외 상황을 처리하고 애플리케이션이 예측 가능하게 동작하도록 보장하는 데 필수적입니다. +3. **관측 가능성 (Observability)**: Flows는 실행을 추적하고, 문제를 디버깅하며, 성능을 모니터링하기 쉽게 만드는 명확한 구조를 제공합니다. 자세한 통찰력을 얻으려면 [CrewAI Tracing](/ko/observability/tracing)을 사용하는 것이 좋습니다. `crewai login`을 실행하여 무료 관측 가능성 기능을 활성화하세요. + +## 아키텍처 + +일반적인 프로덕션 CrewAI 애플리케이션은 다음과 같습니다: + +```mermaid +graph TD + Start((시작)) --> Flow[Flow 오케스트레이터] + Flow --> State{상태 관리} + State --> Step1[1단계: 데이터 수집] + Step1 --> Crew1[연구 Crew] + Crew1 --> State + State --> Step2{조건 확인} + Step2 -- "유효함" --> Step3[3단계: 실행] + Step3 --> Crew2[액션 Crew] + Step2 -- "유효하지 않음" --> End((종료)) + Crew2 --> End +``` + +### 1. Flow 클래스 +`Flow` 클래스는 진입점입니다. 상태 스키마와 로직을 실행하는 메서드를 정의합니다. + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class AppState(BaseModel): + user_input: str = "" + research_results: str = "" + final_report: str = "" + +class ProductionFlow(Flow[AppState]): + @start() + def gather_input(self): + # ... 입력 받는 로직 ... + pass + + @listen(gather_input) + def run_research_crew(self): + # ... Crew 트리거 ... + pass +``` + +### 2. 상태 관리 (State Management) +Pydantic 모델을 사용하여 상태를 정의하세요. 이는 타입 안전성을 보장하고 각 단계에서 어떤 데이터를 사용할 수 있는지 명확하게 합니다. + +- **최소한으로 유지**: 단계 간에 유지해야 할 것만 저장하세요. +- **구조화된 데이터 사용**: 가능하면 비구조화된 딕셔너리는 피하세요. + +### 3. 작업 단위로서의 Crews +복잡한 작업은 Crews에게 위임하세요. Crew는 특정 목표(예: "주제 연구", "블로그 게시물 작성")에 집중해야 합니다. + +- **Crews를 과도하게 설계하지 마세요**: 집중력을 유지하세요. +- **상태를 명시적으로 전달하세요**: Flow 상태에서 필요한 데이터를 Crew 입력으로 전달하세요. + +```python + @listen(gather_input) + def run_research_crew(self): + crew = ResearchCrew() + result = crew.kickoff(inputs={"topic": self.state.user_input}) + self.state.research_results = result.raw +``` + +## Control Primitives + +CrewAI의 Control Primitives를 활용하여 Crew에 견고함과 제어력을 더하세요. + +### 1. Task Guardrails +[Task Guardrails](/ko/concepts/tasks#task-guardrails)를 사용하여 작업 결과가 수락되기 전에 유효성을 검사하세요. 이를 통해 agent가 고품질 결과를 생성하도록 보장할 수 있습니다. + +```python +def validate_content(result: TaskOutput) -> Tuple[bool, Any]: + if len(result.raw) < 100: + return (False, "Content is too short. Please expand.") + return (True, result.raw) + +task = Task( + ..., + guardrail=validate_content +) +``` + +### 2. 구조화된 출력 (Structured Outputs) +작업 간에 데이터를 전달하거나 애플리케이션으로 전달할 때는 항상 구조화된 출력(`output_pydantic` 또는 `output_json`)을 사용하세요. 이는 파싱 오류를 방지하고 타입 안전성을 보장합니다. + +```python +class ResearchResult(BaseModel): + summary: str + sources: List[str] + +task = Task( + ..., + output_pydantic=ResearchResult +) +``` + +### 3. LLM Hooks +[LLM Hooks](/ko/learn/llm-hooks)를 사용하여 LLM으로 전송되기 전에 메시지를 검사하거나 수정하고, 응답을 정리(sanitize)하세요. + +```python +@before_llm_call +def log_request(context): + print(f"Agent {context.agent.role} is calling the LLM...") +``` + +## 배포 패턴 + +Flow를 배포할 때 다음을 고려하세요: + +### CrewAI Enterprise +Flow를 배포하는 가장 쉬운 방법은 CrewAI Enterprise를 사용하는 것입니다. 인프라, 인증 및 모니터링을 대신 처리합니다. + +시작하려면 [배포 가이드](/ko/enterprise/guides/deploy-to-amp)를 확인하세요. + +```bash +crewai deploy create +``` + +### 비동기 실행 (Async Execution) +장기 실행 작업의 경우 `kickoff_async`를 사용하여 API 차단을 방지하세요. + +### 지속성 (Persistence) +`@persist` 데코레이터를 사용하여 Flow의 상태를 데이터베이스에 저장하세요. 이를 통해 프로세스가 중단되거나 사람의 입력을 기다려야 할 때 실행을 재개할 수 있습니다. + +```python +@persist +class ProductionFlow(Flow[AppState]): + # ... +``` + +기본적으로, `@persist`는 `kickoff(inputs={"id": })`가 제공될 때 플로우를 재개하여 동일한 `flow_uuid` 기록을 확장합니다. 영속된 플로우를 새 계보로 **포크**하려면 — 이전 실행에서 상태를 하이드레이트하지만 새로운 `state.id` 아래에 기록 — `restore_from_state_id`를 전달하세요: + +```python +flow.kickoff(restore_from_state_id="") +``` + +새 실행은 새로운 `state.id`(자동 생성, 또는 `inputs["id"]`가 고정된 경우 그 값)를 받아 `@persist` 기록이 원본의 기록을 확장하지 않도록 합니다. `from_checkpoint`와 결합하면 `ValueError`가 발생합니다; 하나의 하이드레이션 소스를 선택하세요. + +## 요약 + +- **Flow로 시작하세요.** +- **명확한 State를 정의하세요.** +- **복잡한 작업에는 Crews를 사용하세요.** +- **API와 지속성을 갖추어 배포하세요.** diff --git a/docs/v1.15.1/ko/concepts/reasoning.mdx b/docs/v1.15.1/ko/concepts/reasoning.mdx new file mode 100644 index 000000000..2a9cd9e1c --- /dev/null +++ b/docs/v1.15.1/ko/concepts/reasoning.mdx @@ -0,0 +1,148 @@ +--- +title: Reasoning +description: "에이전트 reasoning을 활성화하고 사용하는 방법을 배워 작업 실행을 향상하세요." +icon: brain +mode: "wide" +--- + +## 개요 + +Agent reasoning은 에이전트가 작업을 수행하기 전에 해당 작업을 반성하고 계획을 수립할 수 있도록 해주는 기능입니다. 이를 통해 에이전트는 작업에 더 체계적으로 접근할 수 있으며, 할당된 업무를 수행할 준비가 되었는지 확인할 수 있습니다. + +## 사용 방법 + +에이전트에 reasoning을 활성화하려면 에이전트를 생성할 때 `reasoning=True`로 설정하면 됩니다. + +```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 +) +``` + +## 작동 방식 + +reasoning이 활성화되면, 작업을 실행하기 전에 에이전트는 다음을 수행합니다: + +1. 작업을 반영하고 상세한 계획을 수립합니다. +2. 작업을 실행할 준비가 되었는지 평가합니다. +3. 준비가 완료되거나 max_reasoning_attempts에 도달할 때까지 필요에 따라 계획을 다듬습니다. +4. reasoning 계획을 실행 전에 작업 설명에 삽입합니다. + +이 프로세스는 에이전트가 복잡한 작업을 관리하기 쉬운 단계로 분해하고, 시작하기 전에 잠재적인 문제를 식별하는 데 도움을 줍니다. + +## 구성 옵션 + + + reasoning 활성화 또는 비활성화 + + + + 실행을 진행하기 전에 계획을 개선할 최대 시도 횟수입니다. None(기본값)인 경우, agent는 준비될 때까지 계속해서 개선을 시도합니다. + + +## 예제 + +다음은 전체 예제입니다: + +```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) +``` + +## 오류 처리 + +reasoning 프로세스는 견고하게 설계되어 있으며, 오류 처리가 내장되어 있습니다. reasoning 중에 오류가 발생하면, 에이전트는 reasoning 계획 없이 작업을 계속 실행합니다. 이는 reasoning 프로세스가 실패하더라도 작업이 계속 실행될 수 있도록 보장합니다. + +코드에서 발생할 수 있는 오류를 처리하는 방법은 다음과 같습니다: + +```python +from crewai import Agent, Task +import logging + +# reasoning 오류를 캡처하기 위해 로깅을 설정합니다 +logging.basicConfig(level=logging.INFO) + +# reasoning이 활성화된 에이전트를 생성합니다 +agent = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + reasoning=True, + max_reasoning_attempts=3 +) + +# 작업을 생성합니다 +task = Task( + description="Analyze the provided sales data and identify key trends.", + expected_output="A report highlighting the top 3 sales trends.", + agent=agent +) + +# 작업 실행 +# reasoning 중 오류가 발생해도 로그에 기록되며 실행은 계속됩니다 +result = agent.execute_task(task) +``` + +## 예시 Reasoning 출력 + +다음은 데이터 분석 작업을 위한 reasoning 계획의 예시입니다: + +``` +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. +``` + +이 reasoning 계획은 agent가 작업에 접근하는 방식을 체계적으로 구성하고, 발생할 수 있는 잠재적 문제를 고려하며, 기대되는 결과를 제공하도록 돕습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/skills.mdx b/docs/v1.15.1/ko/concepts/skills.mdx new file mode 100644 index 000000000..ea1009dc0 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/skills.mdx @@ -0,0 +1,306 @@ +--- +title: 스킬 +description: 에이전트 프롬프트에 도메인 전문성과 지침을 주입하는 파일 시스템 기반 스킬 패키지. +icon: bolt +mode: "wide" +--- + +## 개요 + +스킬은 에이전트에게 **도메인별 지침, 가이드라인 및 참조 자료**를 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다. + +활성화되면 스킬의 지침이 에이전트의 작업 프롬프트에 직접 주입됩니다 — 코드 변경 없이 에이전트에게 전문성을 부여합니다. + + +**스킬은 도구가 아닙니다.** 이것이 가장 흔한 혼동 포인트입니다. + +- **스킬**은 에이전트의 프롬프트에 *지침과 컨텍스트*를 주입합니다. 에이전트에게 문제에 대해 *어떻게 생각할지*를 알려줍니다. +- **도구**는 에이전트에게 행동을 취할 수 있는 *호출 가능한 함수*를 제공합니다 (검색, 파일 읽기, API 호출). + +흔히 **둘 다** 필요합니다: 전문성을 위한 스킬과 행동을 위한 도구. 이들은 독립적으로 구성되며 서로 보완합니다. + + +--- + +## 빠른 시작 + +### 1. 스킬 디렉터리 생성 + +``` +skills/ +└── code-review/ + ├── SKILL.md # 필수 — 지침 + ├── references/ # 선택 — 참조 문서 + │ └── style-guide.md + └── scripts/ # 선택 — 실행 가능한 스크립트 +``` + +### 2. SKILL.md 작성 + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## 코드 리뷰 가이드라인 + +코드를 리뷰할 때 이 체크리스트를 따르세요: + +1. **보안**: 인젝션 취약점, 인증 우회, 데이터 노출 확인 +2. **성능**: N+1 쿼리, 불필요한 할당, 블로킹 호출 확인 +3. **가독성**: 명확한 네이밍, 적절한 주석, 일관된 스타일 보장 +4. **테스트**: 새로운 기능에 대한 적절한 테스트 커버리지 확인 + +### 심각도 수준 +- **크리티컬**: 보안 취약점, 데이터 손실 위험 → 머지 차단 +- **메이저**: 성능 문제, 로직 오류 → 변경 요청 +- **마이너**: 스타일 문제, 네이밍 제안 → 코멘트와 함께 승인 +``` + +### 3. 에이전트에 연결 + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # 리뷰 가이드라인 주입 + tools=[GithubSearchTool(), FileReadTool()], # 에이전트가 코드를 읽을 수 있게 함 +) +``` + +이제 에이전트는 **전문성** (스킬에서)과 **기능** (도구에서) 모두를 갖추게 됩니다. + +--- + +## 스킬 + 도구: 함께 작동하기 + +스킬과 도구가 어떻게 보완하는지 보여주는 일반적인 패턴입니다: + +### 패턴 1: 스킬만 (도메인 전문성, 액션 불필요) + +에이전트가 특정 지침이 필요하지만 외부 서비스를 호출할 필요가 없을 때 사용: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # 작성 가이드라인 및 템플릿 + # 도구 불필요 — 에이전트가 제공된 컨텍스트를 기반으로 작성 +) +``` + +### 패턴 2: 도구만 (액션, 특별한 전문성 불필요) + +에이전트가 행동을 취해야 하지만 도메인별 지침이 필요 없을 때 사용: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # 검색 및 스크래핑 가능 + # 스킬 불필요 — 일반 연구에는 특별한 가이드라인이 필요 없음 +) +``` + +### 패턴 3: 스킬 + 도구 (전문성 AND 액션) + +가장 일반적인 실제 패턴. 스킬은 작업에 *어떻게* 접근할지를 제공하고, 도구는 에이전트가 *무엇을* 할 수 있는지를 제공합니다: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # 감사 방법론 및 체크리스트 + tools=[ + SerperDevTool(), # 알려진 취약점 조사 + FileReadTool(), # 설정 파일 읽기 + CodeInterpreterTool(), # 분석 스크립트 실행 + ], +) +``` + +### 패턴 4: 스킬 + MCP + +스킬은 도구와 마찬가지로 MCP 서버와 함께 작동합니다: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # 분석 방법론 + mcps=["https://data-warehouse.example.com/sse"], # 원격 데이터 접근 +) +``` + +### 패턴 5: 스킬 + 앱 + +스킬은 에이전트가 플랫폼 통합을 사용하는 방법을 안내할 수 있습니다: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # 응답 템플릿 및 에스컬레이션 규칙 + apps=["gmail", "zendesk"], # 이메일 전송 및 티켓 업데이트 가능 +) +``` + +--- + +## 크루 레벨 스킬 + +스킬을 크루에 설정하여 **모든 에이전트**에 적용할 수 있습니다: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # 모든 에이전트가 이 스킬을 받음 +) +``` + +에이전트 레벨 스킬이 우선합니다 — 동일한 스킬이 양쪽 레벨에서 발견되면 에이전트의 버전이 사용됩니다. + +--- + +## SKILL.md 형식 + +```markdown +--- +name: my-skill +description: 이 스킬이 무엇을 하고 언제 사용하는지에 대한 간단한 설명. +license: Apache-2.0 # 선택 +compatibility: crewai>=0.1.0 # 선택 +metadata: # 선택 + author: your-name + version: "1.0" +allowed-tools: web-search file-read # 선택, 실험적 +--- + +에이전트를 위한 지침이 여기에 들어갑니다. 이 마크다운 본문은 +스킬이 활성화되면 에이전트의 프롬프트에 주입됩니다. +``` + +### 프론트매터 필드 + +| 필드 | 필수 | 설명 | +| :-------------- | :----- | :----------------------------------------------------------------------- | +| `name` | 예 | 1–64자. 소문자 영숫자와 하이픈. 디렉터리 이름과 일치 필수. | +| `description` | 예 | 1–1024자. 스킬이 무엇을 하고 언제 사용하는지 설명. | +| `license` | 아니오 | 라이선스 이름 또는 번들된 라이선스 파일 참조. | +| `compatibility` | 아니오 | 최대 500자. 환경 요구 사항 (제품, 패키지, 네트워크). | +| `metadata` | 아니오 | 임의의 문자열 키-값 매핑. | +| `allowed-tools` | 아니오 | 공백으로 구분된 사전 승인 도구 목록. 실험적. | + +--- + +## 디렉터리 구조 + +``` +my-skill/ +├── SKILL.md # 필수 — 프론트매터 + 지침 +├── scripts/ # 선택 — 실행 가능한 스크립트 +├── references/ # 선택 — 참조 문서 +└── assets/ # 선택 — 정적 파일 (설정, 데이터) +``` + +디렉터리 이름은 `SKILL.md`의 `name` 필드와 일치해야 합니다. `scripts/`, `references/`, `assets/` 디렉터리는 파일을 직접 참조해야 하는 에이전트를 위해 스킬의 `path`에서 사용할 수 있습니다. + +--- + +## 사전 로드된 스킬 + +더 세밀한 제어를 위해 프로그래밍 방식으로 스킬을 검색하고 활성화할 수 있습니다: + +```python +from pathlib import Path +from crewai.skills import discover_skills, activate_skill + +# 디렉터리의 모든 스킬 검색 +skills = discover_skills(Path("./skills")) + +# 활성화 (전체 SKILL.md 본문 로드) +activated = [activate_skill(s) for s in skills] + +# 에이전트에 전달 +agent = Agent( + role="Researcher", + goal="Find relevant information", + backstory="An expert researcher.", + skills=activated, +) +``` + +--- + +## 스킬 로드 방식 + +스킬은 **점진적 공개**를 사용합니다 — 각 단계에서 필요한 것만 로드합니다: + +| 단계 | 로드되는 내용 | 시점 | +| :------- | :------------------------------------ | :------------------ | +| 검색 | 이름, 설명, 프론트매터 필드 | `discover_skills()` | +| 활성화 | 전체 SKILL.md 본문 텍스트 | `activate_skill()` | + +일반적인 에이전트 실행 중(`skills=["./skills"]`로 디렉터리 경로 전달 시) 스킬은 자동으로 검색되고 활성화됩니다. 점진적 로딩은 프로그래밍 API를 사용할 때만 관련됩니다. + +--- + +## 스킬 vs 지식 + +스킬과 지식 모두 에이전트의 프롬프트를 수정하지만, 서로 다른 목적을 가지고 있습니다: + +| 측면 | 스킬 | 지식 | +| :--- | :--- | :--- | +| **제공하는 것** | 지침, 절차, 가이드라인 | 사실, 데이터, 정보 | +| **저장 방식** | 마크다운 파일 (SKILL.md) | 벡터 스토어에 임베딩 (ChromaDB) | +| **검색 방식** | 전체 본문이 프롬프트에 주입 | 시맨틱 검색으로 관련 청크 찾기 | +| **적합한 용도** | 방법론, 체크리스트, 스타일 가이드 | 회사 문서, 제품 정보, 참조 데이터 | +| **설정 방법** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**경험 법칙:** 에이전트가 *프로세스*를 따라야 하면 스킬을 사용하세요. 에이전트가 *데이터*를 참조해야 하면 지식을 사용하세요. + +--- + +## 자주 묻는 질문 + + + + 사용 사례에 따라 다릅니다. 스킬과 도구는 **독립적**입니다 — 둘 중 하나, 둘 다, 또는 아무것도 사용하지 않을 수 있습니다. + + - **스킬만**: 에이전트가 전문성은 필요하지만 외부 액션이 필요 없을 때 (예: 스타일 가이드라인으로 작성) + - **도구만**: 에이전트가 액션은 필요하지만 특별한 방법론이 필요 없을 때 (예: 간단한 웹 검색) + - **둘 다**: 에이전트가 전문성 AND 액션이 필요할 때 (예: 특정 체크리스트로 보안 감사 AND 코드 스캔 기능) + + + + **아니요.** SKILL.md의 `allowed-tools` 필드는 실험적 메타데이터일 뿐 — 도구를 프로비저닝하거나 주입하지 않습니다. 항상 `tools=[]`, `mcps=[]` 또는 `apps=[]`를 통해 별도로 도구를 설정해야 합니다. + + + + 에이전트 레벨 스킬이 우선합니다. 스킬은 이름으로 중복 제거됩니다 — 에이전트의 스킬이 먼저 처리되므로, 같은 스킬 이름이 양쪽 레벨에 나타나면 에이전트의 버전이 사용됩니다. + + + + 50,000자에서 소프트 경고가 있지만 하드 리밋은 없습니다. 최상의 결과를 위해 스킬을 집중적이고 간결하게 유지하세요 — 너무 큰 프롬프트 주입은 에이전트의 주의를 분산시킬 수 있습니다. + + diff --git a/docs/v1.15.1/ko/concepts/tasks.mdx b/docs/v1.15.1/ko/concepts/tasks.mdx new file mode 100644 index 000000000..e0ce3f8f1 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/tasks.mdx @@ -0,0 +1,938 @@ +--- +title: 작업 +description: CrewAI 프레임워크 내에서 작업을 관리하고 생성하는 방법에 대한 자세한 안내서입니다. +icon: list-check +mode: "wide" +--- + +## 개요 + +CrewAI 프레임워크에서 `Task`는 `Agent`가 완료하는 구체적인 과제입니다. + +Task는 실행을 위한 모든 세부 정보를 제공합니다. 여기에는 설명, 책임 Agent, 필요한 도구 등이 포함되어 다양한 작업 복잡성을 지원합니다. + +CrewAI 내의 Task는 협업이 가능하며, 여러 Agent가 함께 작업해야 할 수도 있습니다. 이는 Task 속성을 통해 관리되며, Crew의 프로세스를 통해 조율되어 팀워크와 효율성을 향상시킵니다. + + +CrewAI 엔터프라이즈에는 복잡한 Task 생성과 연결을 단순화하는 Crew Studio의 비주얼 Task 빌더가 포함되어 있습니다. Task 흐름을 시각적으로 설계하고, 코드를 작성하지 않고도 실시간으로 테스트해 볼 수 있습니다. + +![Task Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +비주얼 Task 빌더의 주요 기능: +- 드래그 앤 드롭 방식의 Task 생성 +- 시각적 Task 종속성과 흐름 관리 +- 실시간 테스트 및 검증 +- 손쉬운 공유 및 협업 + + +### 작업 실행 흐름 + +작업은 두 가지 방법으로 실행될 수 있습니다: +- **순차적**: 작업이 정의된 순서대로 실행됩니다 +- **계층적**: 작업이 역할과 전문성에 따라 에이전트에게 할당됩니다 + +실행 흐름은 crew를 생성할 때 정의됩니다: +```python Code +crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + process=Process.sequential # or Process.hierarchical +) +``` + +## 태스크 속성 + +| 속성 | 매개변수 | 타입 | 설명 | +| :------------------------------- | :-------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------ | +| **설명** | `description` | `str` | 태스크가 다루는 내용을 명확하고 간결하게 설명합니다. | +| **예상 출력** | `expected_output` | `str` | 태스크가 완료된 모습에 대한 구체적인 설명입니다. | +| **이름** _(선택 사항)_ | `name` | `Optional[str]` | 태스크의 이름 식별자입니다. | +| **에이전트** _(선택 사항)_ | `agent` | `Optional[BaseAgent]` | 태스크 실행을 담당하는 에이전트입니다. | +| **도구** _(선택 사항)_ | `tools` | `List[BaseTool]` | 이 태스크를 위해 에이전트가 사용할 수 있는 도구/리소스 목록입니다. | +| **컨텍스트** _(선택 사항)_ | `context` | `Optional[List["Task"]]` | 이 태스크의 컨텍스트로 사용될 다른 태스크의 출력입니다. | +| **비동기 실행** _(선택 사항)_ | `async_execution` | `Optional[bool]` | 태스크를 비동기적으로 실행할지 여부입니다. 기본값은 False입니다. | +| **사용자 입력** _(선택 사항)_ | `human_input` | `Optional[bool]` | 태스크의 최종 답안을 에이전트가 제출한 뒤 사람이 검토할지 여부입니다. 기본값은 False입니다. | +| **마크다운** _(선택 사항)_ | `markdown` | `Optional[bool]` | 태스크가 에이전트에게 최종 답안을 마크다운으로 포매팅해서 반환하도록 지시할지 여부입니다. 기본값은 False입니다. | +| **설정** _(선택 사항)_ | `config` | `Optional[Dict[str, Any]]` | 태스크별 설정 파라미터입니다. | +| **출력 파일** _(선택 사항)_ | `output_file` | `Optional[str]` | 태스크 결과를 저장할 파일 경로입니다. | +| **디렉터리 생성** _(선택 사항)_ | `create_directory` | `Optional[bool]` | output_file의 디렉터리가 존재하지 않을 경우 생성할지 여부입니다. 기본값은 True입니다. | +| **출력 JSON** _(선택 사항)_ | `output_json` | `Optional[Type[BaseModel]]` | JSON 출력을 구조화하기 위한 Pydantic 모델입니다. | +| **Pydantic 출력** _(선택 사항)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | 태스크 출력용 Pydantic 모델입니다. | +| **콜백** _(선택 사항)_ | `callback` | `Optional[Any]` | 태스크 완료 후 실행할 함수/객체입니다. | +| **가드레일** _(선택 사항)_ | `guardrail` | `Optional[Callable]` | 다음 태스크로 진행하기 전에 태스크 출력을 검증하는 함수입니다. | +| **가드레일 최대 재시도** _(선택 사항)_ | `guardrail_max_retries` | `Optional[int]` | 가드레일 검증 실패 시 최대 재시도 횟수입니다. 기본값은 3입니다. | + +## 작업 생성하기 + +CrewAI에서 작업을 생성하는 일반적인 방법은 **JSONC 프로젝트 구성(새 crew 권장)** 또는 **코드에서 직접 정의**입니다. + +### JSONC 구성 (권장) + +`crewai create crew `으로 만든 새 프로젝트는 `crew.jsonc`에 태스크를 정의합니다. + +```jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "reporting_analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research about {topic}.", + "expected_output": "A list of the most relevant information about {topic}.", + "agent": "researcher" + }, + { + "name": "reporting_task", + "description": "Review the research and expand it into a detailed report.", + "expected_output": "A polished markdown report.", + "agent": "reporting_analyst", + "context": ["research_task"], + "markdown": true, + "output_file": "report.md" + } + ], + "inputs": { + "topic": "AI Agents" + } +} +``` + +각 태스크에는 `description`과 `expected_output`이 필요합니다. `agent` 값은 `agents`에 나열된 에이전트 이름과 일치해야 합니다. `context`는 이전 태스크 이름만 참조할 수 있으며, 이후 태스크 참조는 거부됩니다. + +### 클래식 YAML 구성 + +`crewai create crew --classic`으로 만든 클래식 프로젝트는 `config/tasks.yaml`과 `crew.py`의 `@CrewBase` 클래스를 사용합니다. + +YAML 구성은 기존 Python/YAML 프로젝트와 `@CrewBase` 클래스에서 태스크를 정의하려는 팀을 위해 계속 지원됩니다. + +클래식 프로젝트를 만든 후, `src//config/tasks.yaml` 파일로 이동하여 템플릿을 작업 요구 사항에 맞게 수정하세요. + + +YAML 파일 내 변수(예: `{topic}`)는 크루를 실행할 때 입력값에서 가져온 값으로 대체됩니다: +```python Code +crew.kickoff(inputs={'topic': 'AI Agents'}) +``` + + +아래는 YAML을 사용하여 작업을 구성하는 방법의 예시입니다: + +```yaml 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 + markdown: true + output_file: report.md +``` + +이 YAML 구성을 코드에서 사용하려면 `CrewBase`를 상속받는 크루 클래스를 생성하세요: + +```python crew.py +# src//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 + ) +``` + + +YAML 파일(`agents.yaml` 및 `tasks.yaml`)에서 사용하는 이름은 Python 코드의 메서드 이름과 일치해야 합니다. + + +### 코드에서 직접 태스크 정의 (대안) + +또는 YAML 구성 없이 코드에서 직접 태스크를 정의할 수 있습니다: + +```python task.py +from crewai import Task + +research_task = Task( + description=""" + Conduct a thorough research about AI Agents. + 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 AI Agents + """, + agent=researcher +) + +reporting_task = 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. + """, + agent=reporting_analyst, + markdown=True, # Enable markdown formatting for the final output + output_file="report.md" +) +``` + + + `agent`를 직접 지정하여 할당하거나, 역할·가용성 등에 따라 `hierarchical` CrewAI 프로세스가 자동으로 결정하도록 둘 수 있습니다. + + +## 작업 결과 + +작업 결과를 이해하는 것은 효과적인 AI 워크플로우를 구축하는 데 매우 중요합니다. CrewAI는 여러 출력 형식을 지원하는 `TaskOutput` 클래스를 통해 작업 결과를 구조적으로 처리할 수 있는 방식을 제공합니다. 이 클래스는 작업 간에 출력값을 쉽게 전달할 수 있도록 지원합니다. + +CrewAI 프레임워크에서 작업의 출력은 `TaskOutput` 클래스에 캡슐화되어 있습니다. 이 클래스는 작업의 결과를 구조적으로 접근할 수 있도록 해주며, raw 출력, JSON, Pydantic 모델 등 다양한 형식을 지원합니다. + +기본적으로 `TaskOutput`에는 `raw` 출력만 포함됩니다. 원래의 `Task` 객체가 각각 `output_pydantic` 또는 `output_json`으로 구성된 경우에만 `TaskOutput`에 `pydantic` 또는 `json_dict` 출력이 포함됩니다. + +### 작업 출력 속성 + +| 속성 | 파라미터 | 타입 | 설명 | +| :---------------- | :----------------- | :------------------------- | :---------------------------------------------------------------------------------------------------- | +| **설명** | `description` | `str` | 작업에 대한 설명입니다. | +| **요약** | `summary` | `Optional[str]` | 설명의 처음 10단어에서 자동 생성된 작업의 요약입니다. | +| **Raw** | `raw` | `str` | 작업의 원시 출력값입니다. 출력의 기본 형식입니다. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | 작업의 구조화된 출력을 나타내는 Pydantic 모델 객체입니다. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | 작업의 JSON 출력을 나타내는 딕셔너리입니다. | +| **Agent** | `agent` | `str` | 작업을 실행한 agent입니다. | +| **Output Format** | `output_format` | `OutputFormat` | 작업 출력의 형식입니다. RAW, JSON, Pydantic 옵션이 있으며, 기본값은 RAW입니다. | + +### 태스크 메서드 및 프로퍼티 + +| Method/Property | 설명 | +| :-------------- | :------------------------------------------------------------------------------------------------- | +| **json** | 출력 포맷이 JSON일 경우 태스크 출력의 JSON 문자열 표현을 반환합니다. | +| **to_dict** | JSON 및 Pydantic 출력을 딕셔너리로 변환합니다. | +| **str** | 태스크 출력의 문자열 표현을 반환하며, Pydantic을 우선으로 하고 그 다음은 JSON, 그 다음은 raw를 사용합니다. | + +### 작업 출력 액세스 + +작업이 실행된 후에는 `Task` 객체의 `output` 속성을 통해 그 출력을 액세스할 수 있습니다. `TaskOutput` 클래스는 이 출력을 다양한 방식으로 상호작용하고 표시할 수 있는 기능을 제공합니다. + +#### 예시 + +```python Code +# Example task +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +# Execute the crew +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() + +# Accessing the task output +task_output = task.output + +print(f"Task Description: {task_output.description}") +print(f"Task Summary: {task_output.summary}") +print(f"Raw Output: {task_output.raw}") +if task_output.json_dict: + print(f"JSON Output: {json.dumps(task_output.json_dict, indent=2)}") +if task_output.pydantic: + print(f"Pydantic Output: {task_output.pydantic}") +``` + +## 마크다운 출력 포매팅 + +`markdown` 매개변수는 작업 출력에 대해 자동 마크다운 포매팅을 활성화합니다. 이 값을 `True`로 설정하면, 작업은 에이전트에게 최종 답변을 올바른 마크다운 문법으로 포매팅하도록 지시합니다. + +### 마크다운(Markdown) 포매팅 사용하기 + +```python Code +# Example task with markdown formatting enabled +formatted_task = Task( + description="Create a comprehensive report on AI trends", + expected_output="A well-structured report with headers, sections, and bullet points", + agent=reporter_agent, + markdown=True # Enable automatic markdown formatting +) +``` + +`markdown=True`일 때, 에이전트는 다음과 같이 출력을 포매팅하라는 추가 지시를 받게 됩니다: +- 헤더에는 `#` 사용 +- 볼드체는 `**텍스트**` 사용 +- 이탤릭체는 `*텍스트*` 사용 +- 불릿 포인트에는 `-` 또는 `*` 사용 +- 인라인 코드는 `` `코드` `` 사용 +- 코드 블록은 ``` ```언어 ``` 사용 + +### 마크다운을 활용한 YAML 구성 + +```yaml tasks.yaml +analysis_task: + description: > + Analyze the market data and create a detailed report + expected_output: > + A comprehensive analysis with charts and key findings + agent: analyst + markdown: true # Enable markdown formatting + output_file: analysis.md +``` + +### 마크다운 출력의 이점 + +- **일관된 포맷팅**: 모든 출력이 올바른 마크다운 규칙을 따르도록 보장합니다 +- **향상된 가독성**: 헤더, 목록, 강조 등으로 구조화된 콘텐츠 +- **문서화에 적합**: 출력을 문서 시스템에서 바로 사용할 수 있습니다 +- **크로스 플랫폼 호환성**: 마크다운은 보편적으로 지원됩니다 + + +마크다운 포맷팅 지침은 `markdown=True`일 때 작업 프롬프트에 자동으로 추가되므로, 작업 설명에 포맷팅 요구사항을 따로 명시할 필요가 없습니다. + + +## 작업 종속성 및 컨텍스트 + +작업은 `context` 속성을 사용하여 다른 작업의 출력에 의존할 수 있습니다. 예를 들어: + +```python Code +research_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + agent=researcher +) + +analysis_task = Task( + description="Analyze the research findings and identify key trends", + expected_output="Analysis report of AI trends", + agent=analyst, + context=[research_task] # This task will wait for research_task to complete +) +``` + +## 작업 가드레일 + +작업 가드레일은 작업 출력물을 다음 작업에 전달하기 전에 유효성을 검사하고 변환할 수 있는 방식을 제공합니다. 이 기능은 데이터 품질을 보장하고 에이전트의 출력이 특정 기준을 충족하지 않을 때 피드백을 제공하는 데 도움이 됩니다. + +가드레일은 사용자 지정 유효성 검사 로직을 포함하는 Python 함수로 구현되며, 유효성 검사 프로세스를 완전히 제어할 수 있어 신뢰할 수 있고 결정적인 결과를 보장합니다. + +### 함수 기반 가드레일 + +함수 기반 가드레일을 태스크에 추가하려면 `guardrail` 파라미터를 통해 검증 함수를 제공하세요: + +```python Code +from typing import Tuple, Union, Dict, Any +from crewai import TaskOutput + +def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]: + """Validate blog content meets requirements.""" + try: + # Check word count + word_count = len(result.split()) + if word_count > 200: + return (False, "Blog content exceeds 200 words") + + # Additional validation logic here + return (True, result.strip()) + except Exception as e: + return (False, "Unexpected error during validation") + +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail=validate_blog_content # Add the guardrail function +) +``` + +### Guardrail 함수 요구사항 + +1. **함수 시그니처**: + - 정확히 하나의 매개변수(태스크 출력)를 받아야 함 + - `(bool, Any)` 형태의 튜플을 반환해야 함 + - 타입 힌트는 권장하지만 필수는 아님 + +2. **반환 값**: + - 성공 시: `(bool, Any)` 형태의 튜플을 반환. 예: `(True, validated_result)` + - 실패 시: `(bool, str)` 형태의 튜플을 반환. 예: `(False, "Error message explain the failure")` + +### 오류 처리 모범 사례 + +1. **구조화된 오류 응답**: +```python Code +from crewai import TaskOutput, LLMGuardrail + +def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]: + try: + # Main validation logic + 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. **오류 범주**: + - 구체적인 오류 코드 사용 + - 관련 컨텍스트 포함 + - 실행 가능한 피드백 제공 + +3. **검증 체인**: +```python Code +from typing import Any, Dict, List, Tuple, Union +from crewai import TaskOutput + +def complex_validation(result: TaskOutput) -> Tuple[bool, Any]: + """Chain multiple validation steps.""" + # Step 1: Basic validation + if not result: + return (False, "Empty result") + + # Step 2: Content validation + try: + validated = validate_content(result) + if not validated: + return (False, "Invalid content") + + # Step 3: Format validation + formatted = format_output(validated) + return (True, formatted) + except Exception as e: + return (False, str(e)) +``` + +### 가드레일 결과 처리 + +가드레일이 `(False, error)`를 반환할 때: +1. 에러가 에이전트에게 다시 전달됩니다 +2. 에이전트가 문제를 수정하려고 시도합니다 +3. 다음 중 하나가 될 때까지 이 과정이 반복됩니다: + - 가드레일이 `(True, result)`를 반환함 + - 최대 재시도 횟수에 도달함 + +재시도 처리가 포함된 예시: +```python Code +from typing import Optional, Tuple, Union +from crewai import TaskOutput, Task + +def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]: + """Validate and parse JSON output.""" + try: + # Try to parse as JSON + data = json.loads(result) + return (True, data) + except json.JSONDecodeError as e: + return (False, "Invalid JSON format") + +task = Task( + description="Generate a JSON report", + expected_output="A valid JSON object", + agent=analyst, + guardrail=validate_json_output, + guardrail_max_retries=3 # 재시도 횟수 제한 +) +``` + +## 작업에서 구조화된 일관된 출력 얻기 + + +또한 crew의 마지막 작업의 출력이 실제 crew 자체의 최종 출력이 된다는 점도 중요합니다. + + +### `output_pydantic` 사용하기 +`output_pydantic` 속성을 사용하면 작업 출력이 준수해야 할 Pydantic 모델을 정의할 수 있습니다. 이를 통해 출력이 구조화될 뿐만 아니라 Pydantic 모델에 따라 유효성 검증도 보장할 수 있습니다. + +다음은 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="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A compelling blog title and well-written content.", + agent=blog_agent, + output_pydantic=Blog, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Accessing Properties Directly from the Pydantic Model +print("Accessing Properties - Option 2") +title = result.pydantic.title +content = result.pydantic.content +print("Title:", title) +print("Content:", content) + +# Option 3: Accessing Properties Using the to_dict() Method +print("Accessing Properties - Option 3") +output_dict = result.to_dict() +title = output_dict["title"] +content = output_dict["content"] +print("Title:", title) +print("Content:", content) + +# Option 4: Printing the Entire Blog Object +print("Accessing Properties - Option 5") +print("Blog:", result) + +``` +이 예제에서: +* title과 content 필드를 가진 Pydantic 모델 Blog가 정의되어 있습니다. +* 작업 task1은 output_pydantic 속성을 사용하여 출력이 Blog 모델을 준수해야 함을 명시합니다. +* crew를 실행한 후, 위와 같이 다양한 방법으로 구조화된 출력을 확인할 수 있습니다. + +#### 출력 접근 방법 설명 +1. 딕셔너리 스타일 인덱싱: `result["field_name"]`을 사용하여 필드를 직접 접근할 수 있습니다. 이는 CrewOutput 클래스가 `__getitem__` 메서드를 구현하고 있기 때문에 가능합니다. +2. Pydantic 모델에서 직접 접근: `result.pydantic` 객체에서 속성에 직접 접근할 수 있습니다. +3. to_dict() 메서드 사용: 출력을 딕셔너리로 변환한 후 필드에 접근합니다. +4. 전체 객체 출력: 단순히 result 객체를 출력하여 구조화된 출력을 확인할 수 있습니다. + +### `output_json` 사용하기 +`output_json` 속성을 사용하면 예상되는 출력을 JSON 형식으로 정의할 수 있습니다. 이를 통해 태스크의 출력이 쉽게 파싱되고, 애플리케이션에서 사용할 수 있는 유효한 JSON 구조임을 보장합니다. + +다음은 `output_json` 사용 방법을 보여주는 예시입니다: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +# Define the Pydantic model for the blog +class Blog(BaseModel): + title: str + content: str + + +# Define the agent +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +# Define the task with output_json set to the Blog model +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A JSON object with 'title' and 'content' fields.", + agent=blog_agent, + output_json=Blog, +) + +# Instantiate the crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +# Kickoff the crew to execute the task +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Printing the Entire Blog Object +print("Accessing Properties - Option 2") +print("Blog:", result) +``` + +이 예시에서: +* Pydantic 모델인 Blog가 title과 content 필드로 정의되어 있으며, 이는 JSON 출력의 구조를 명시하는 데 사용됩니다. +* 태스크 task1은 output_json 속성을 사용하여 Blog 모델에 부합하는 JSON 출력을 기대함을 나타냅니다. +* crew를 실행한 후, 두 가지 방식으로 구조화된 JSON 출력을 접근할 수 있습니다. + +#### 출력 접근 방법 설명 + +1. 딕셔너리 스타일 인덱싱을 사용하여 속성 접근하기: result["field_name"]과 같이 필드를 직접 접근할 수 있습니다. 이는 CrewOutput 클래스가 __getitem__ 메서드를 구현하고 있어 출력을 딕셔너리처럼 사용할 수 있기 때문입니다. 이 방법에서는 result에서 title과 content를 가져옵니다. +2. 전체 블로그 객체 출력하기: result를 출력하면 CrewOutput 객체의 문자열 표현을 얻을 수 있습니다. __str__ 메서드가 JSON 출력을 반환하도록 구현되어 있기 때문에, 전체 출력을 Blog 객체를 나타내는 형식이 잘 갖추어진 문자열로 볼 수 있습니다. + +--- + +output_pydantic 또는 output_json을 사용하면, 작업의 출력이 일관되고 구조화된 형식으로 생성되므로 애플리케이션 내 또는 여러 작업 간에 데이터를 더 쉽게 처리하고 활용할 수 있습니다. + +## 도구와 작업 통합 + +향상된 작업 성능과 에이전트 상호작용을 위해 [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) 및 [LangChain Tools](https://python.langchain.com/docs/integrations/tools)의 도구를 활용하세요. + +## 도구와 함께 Task 생성하기 + +```python Code +import os +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key + +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +research_agent = Agent( + role='Researcher', + goal='Find and summarize the latest AI news', + backstory="""You're a researcher at a large company. + You're responsible for analyzing data and providing insights + to the business.""", + verbose=True +) + +# to perform a semantic search for a specified query from a text's content across the internet +search_tool = SerperDevTool() + +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() +print(result) +``` + +이 예시는 특정 도구와 함께 사용되는 task가 맞춤형 task 실행을 위해 에이전트의 기본 도구 세트를 어떻게 재정의할 수 있는지 보여줍니다. + +## 다른 작업 참조하기 + +CrewAI에서는 한 작업의 출력이 자동으로 다음 작업으로 전달되지만, 특정 작업(여러 개 포함)의 출력을 다른 작업의 컨텍스트로 명확하게 지정할 수도 있습니다. + +이는 한 작업이 바로 뒤에 수행되지 않는 다른 작업의 출력에 의존해야 할 때 유용합니다. 이는 작업의 `context` 속성을 통해 수행됩니다: + +```python Code +# ... + +research_ai_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +research_ops_task = Task( + description="Research the latest developments in AI Ops", + expected_output="A list of recent AI Ops developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +write_blog_task = Task( + description="Write a full blog post about the importance of AI and its latest news", + expected_output="Full blog post that is 4 paragraphs long", + agent=writer_agent, + context=[research_ai_task, research_ops_task] +) + +#... +``` + +## 비동기 실행 + +작업을 비동기로 실행되도록 정의할 수 있습니다. 이는 crew가 해당 작업이 완료될 때까지 기다리지 않고 다음 작업을 계속 진행한다는 것을 의미합니다. 시간이 오래 걸리는 작업이거나, 이후 작업 수행에 필수적이지 않은 작업에 유용합니다. + +이후 작업에서 비동기 작업의 출력이 완료될 때까지 기다리도록 하려면, `context` 속성을 사용할 수 있습니다. + +```python Code +#... + +list_ideas = Task( + description="List of 5 interesting ideas to explore for an article about AI.", + expected_output="Bullet point list of 5 ideas for an article.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +list_important_history = Task( + description="Research the history of AI and give me the 5 most important events.", + expected_output="Bullet point list of 5 important events.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +write_article = Task( + description="Write an article about AI, its history, and interesting ideas.", + expected_output="A 4 paragraph article about AI.", + agent=writer, + context=[list_ideas, list_important_history] # Will wait for the output of the two tasks to be completed +) + +#... +``` + +## 콜백 메커니즘 + +콜백 함수는 작업이 완료된 후 실행되며, 작업 결과에 따라 동작 또는 알림을 트리거할 수 있습니다. + +```python Code +# ... + +def callback_function(output: TaskOutput): + # Do something after the task is completed + # Example: Send an email to the manager + print(f""" + Task completed! + Task: {output.description} + Output: {output.raw} + """) + +research_task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool], + callback=callback_function +) + +#... +``` + +## 특정 Task Output 접근하기 + +crew가 실행을 마치면, 해당 task 객체의 `output` 속성을 사용하여 특정 task의 output에 접근할 수 있습니다: + +```python Code +# ... +task1 = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +#... + +crew = Crew( + agents=[research_agent], + tasks=[task1, task2, task3], + verbose=True +) + +result = crew.kickoff() + +# Returns a TaskOutput object with the description and results of the task +print(f""" + Task completed! + Task: {task1.output.description} + Output: {task1.output.raw} +""") +``` + +## 도구 재정의 메커니즘 + +작업에서 도구를 지정하면 에이전트의 기능을 동적으로 조정할 수 있어 CrewAI의 유연성이 강조됩니다. + +## 오류 처리 및 검증 메커니즘 + +작업을 생성하고 실행하는 동안, 작업 속성의 견고성과 신뢰성을 보장하기 위해 특정 검증 메커니즘이 마련되어 있습니다. 이는 다음에 국한되지 않습니다: + +- 작업마다 한 가지 출력 유형만 설정하여 명확한 출력 기대치를 유지함 +- 고유 식별자 시스템의 무결성을 유지하기 위해 `id` 속성의 수동 할당을 방지함 + +이러한 검증 절차는 crewAI 프레임워크 내에서 작업 실행의 일관성과 신뢰성을 유지하는 데 도움이 됩니다. + +## 파일 저장 시 디렉토리 생성 + +`create_directory` 매개변수는 CrewAI가 작업 결과를 파일로 저장할 때 디렉토리를 자동으로 생성할지 여부를 제어합니다. 이 기능은 출력물을 체계적으로 정리하고, 특히 복잡한 프로젝트 계층 구조에서 파일 경로가 올바르게 구조화되도록 보장하는 데 매우 유용합니다. + +### 기본 동작 + +기본적으로 `create_directory=True`로 설정되어 있으며, 이는 CrewAI가 출력 파일 경로에 누락된 디렉토리를 자동으로 생성함을 의미합니다: + +```python Code +# 기본 동작 - 디렉토리가 자동으로 생성됩니다 +report_task = Task( + description='Generate a comprehensive market analysis report', + expected_output='A detailed market analysis with charts and insights', + agent=analyst_agent, + output_file='reports/2025/market_analysis.md', # 'reports/2025/'가 없으면 생성됩니다 + markdown=True +) +``` + +### 디렉터리 생성 비활성화 + +자동 디렉터리 생성을 방지하고 디렉터리가 이미 존재함을 보장하려면 `create_directory=False`로 설정하세요: + +```python Code +# Strict mode - directory must already exist +strict_output_task = Task( + description='Save critical data that requires existing infrastructure', + expected_output='Data saved to pre-configured location', + agent=data_agent, + output_file='secure/vault/critical_data.json', + create_directory=False # Will raise RuntimeError if 'secure/vault/' doesn't exist +) +``` + +### YAML 구성 + +이 동작은 YAML 태스크 정의에서도 구성할 수 있습니다: + +```yaml tasks.yaml +analysis_task: + description: > + 분기별 재무 분석 생성 + expected_output: > + 분기별 인사이트가 포함된 종합 재무 보고서 + agent: financial_analyst + output_file: reports/quarterly/q4_2024_analysis.pdf + create_directory: true # 'reports/quarterly/' 디렉토리를 자동으로 생성 + +audit_task: + description: > + 컴플라이언스 감사 수행 및 기존 감사 디렉토리에 저장 + expected_output: > + 컴플라이언스 감사 보고서 + agent: auditor + output_file: audit/compliance_report.md + create_directory: false # 디렉토리가 이미 존재해야 함 +``` + +### 사용 사례 + +**자동 디렉토리 생성 (`create_directory=True`):** +- 개발 및 프로토타이핑 환경 +- 날짜 기반 폴더로 동적 보고서 생성 +- 디렉토리 구조가 달라질 수 있는 자동화된 워크플로우 +- 사용자별 폴더가 필요한 멀티 테넌트 애플리케이션 + +**수동 디렉토리 관리 (`create_directory=False`):** +- 엄격한 파일 시스템 제어가 필요한 운영 환경 +- 디렉토리가 사전 구성되어야 하는 보안 민감 애플리케이션 +- 특정 권한 요구 사항이 있는 시스템 +- 디렉토리 생성이 감사되는 규정 준수 환경 + +### 오류 처리 + +`create_directory=False`이고 디렉토리가 존재하지 않는 경우, CrewAI는 `RuntimeError`를 발생시킵니다: + +```python Code +try: + result = crew.kickoff() +except RuntimeError as e: + # Handle missing directory error + print(f"Directory creation failed: {e}") + # Create directory manually or use fallback location +``` + +아래 영상을 통해 CrewAI에서 구조화된 출력을 사용하는 방법을 확인하세요: + + + +## 결론 + +작업(task)은 CrewAI 에이전트의 행동을 이끄는 원동력입니다. +작업과 그 결과를 적절하게 정의함으로써, 에이전트가 독립적으로 또는 협업 단위로 효과적으로 작동할 수 있는 기반을 마련할 수 있습니다. +작업에 적합한 도구를 장착하고, 실행 과정을 이해하며, 견고한 검증 절차를 따르는 것은 CrewAI의 잠재력을 극대화하는 데 필수적입니다. +이를 통해 에이전트가 할당된 작업에 효과적으로 준비되고, 작업이 의도대로 수행될 수 있습니다. diff --git a/docs/v1.15.1/ko/concepts/testing.mdx b/docs/v1.15.1/ko/concepts/testing.mdx new file mode 100644 index 000000000..671143d9a --- /dev/null +++ b/docs/v1.15.1/ko/concepts/testing.mdx @@ -0,0 +1,49 @@ +--- +title: 테스트 +description: CrewAI Crew를 테스트하고 그 성능을 평가하는 방법을 알아보세요. +icon: vial +mode: "wide" +--- + +## 개요 + +테스트는 개발 프로세스에서 매우 중요한 부분이며, crew가 예상대로 동작하는지 확인하는 것이 필수적입니다. crewAI를 사용하면 내장된 테스트 기능을 통해 crew를 쉽게 테스트하고 성능을 평가할 수 있습니다. + +### 테스트 기능 사용하기 + +CLI 명령어 `crewai test`를 추가하여 crew 테스트를 쉽게 할 수 있습니다. 이 명령어는 지정한 반복 횟수만큼 crew를 실행하고, 자세한 성능 지표를 제공합니다. 매개변수로는 `n_iterations`와 `model`이 있으며, 이들은 선택 사항이고 각각 기본값은 2와 `gpt-4o-mini`입니다. 현재는 OpenAI만 지원됩니다. + +```bash +crewai test +``` + +더 많은 반복 횟수로 실행하거나 다른 모델을 사용하려면 다음과 같이 매개변수를 지정할 수 있습니다: + +```bash +crewai test --n_iterations 5 --model gpt-4o +``` + +또는 축약형을 사용할 수 있습니다: + +```bash +crewai test -n 5 -m gpt-4o +``` + +`crewai test` 명령어를 실행하면 crew가 지정한 횟수만큼 실행되고, 수행이 끝나면 성능 지표가 표시됩니다. + +실행 마지막에 표시되는 점수 표는 다음과 같은 지표로 crew의 성능을 보여줍니다: + +
**작업 점수 (1-10 높을수록 좋음)**
+ +| Tasks/Crew/Agents | Run 1 | Run 2 | Avg. Total | Agents | Additional Info | +|:------------------|:-----:|:-----:|:----------:|:------------------------------:|:---------------------------------| +| Task 1 | 9.0 | 9.5 | **9.2** | Professional Insights | | +| | | | | Researcher | | +| Task 2 | 9.0 | 10.0 | **9.5** | Company Profile Investigator | | +| Task 3 | 9.0 | 9.0 | **9.0** | Automation Insights | | +| | | | | Specialist | | +| Task 4 | 9.0 | 9.0 | **9.0** | Final Report Compiler | Automation Insights Specialist | +| Crew | 9.00 | 9.38 | **9.2** | | | +| Execution Time (s) | 126 | 145 | **135** | | | + +위 예시는 두 번 실행한 crew의 테스트 결과를 보여주며, 각 작업과 crew 전체의 평균 총점이 포함되어 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/tools.mdx b/docs/v1.15.1/ko/concepts/tools.mdx new file mode 100644 index 000000000..cd0e96173 --- /dev/null +++ b/docs/v1.15.1/ko/concepts/tools.mdx @@ -0,0 +1,287 @@ +--- +title: 도구 +description: CrewAI 프레임워크 내에서 에이전트 협업과 작업 실행을 위해 도구를 이해하고 활용하기. +icon: screwdriver-wrench +mode: "wide" +--- + +## 개요 + +CrewAI 도구는 에이전트에게 웹 검색, 데이터 분석부터 동료 간 협업 및 작업 위임에 이르기까지 다양한 기능을 제공합니다. +이 문서에서는 CrewAI 프레임워크 내에서 이러한 도구를 생성, 통합 및 활용하는 방법과, 협업 도구에 초점을 맞춘 새로운 기능에 대해 설명합니다. + + + 도구는 에이전트에게 행동을 취할 수 있는 **호출 가능한 함수**를 제공합니다. [MCP](/ko/mcp/overview) (원격 도구 서버), [앱](/ko/concepts/agent-capabilities) (플랫폼 통합), [스킬](/ko/concepts/skills) (도메인 전문성), [지식](/ko/concepts/knowledge) (검색된 사실)과 함께 작동합니다. 각 유형을 언제 사용해야 하는지 알아보려면 [에이전트 기능](/ko/concepts/agent-capabilities) 개요를 참조하세요. + + +## Tool이란 무엇인가? + +CrewAI에서 tool은 에이전트가 다양한 작업을 수행하기 위해 활용할 수 있는 기술 또는 기능입니다. +이에는 [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) 및 [LangChain Tools](https://python.langchain.com/docs/integrations/tools)의 tool이 포함되어, +간단한 검색부터 복잡한 상호작용, 그리고 에이전트 간의 효과적인 협업까지 모두 가능하게 합니다. + + +CrewAI 엔터프라이즈는 주요 비즈니스 시스템 및 API와의 사전 구축된 통합을 제공하는 종합적인 Tools Repository를 제공합니다. 며칠이 걸리던 엔터프라이즈 tool로 에이전트를 몇 분 만에 배포할 수 있습니다. + +엔터프라이즈 Tools Repository에는 다음이 포함됩니다: +- 인기 엔터프라이즈 시스템용 사전 구축 커넥터 +- 커스텀 tool 생성 인터페이스 +- 버전 관리 및 공유 기능 +- 보안 및 규정 준수 기능 + + +## 도구의 주요 특징 + +- **유틸리티**: 웹 검색, 데이터 분석, 콘텐츠 생성, 에이전트 협업과 같은 작업을 위해 제작됨. +- **통합성**: 도구를 워크플로우에 원활하게 통합하여 에이전트의 역량을 강화함. +- **맞춤화 가능성**: 맞춤형 도구를 개발하거나 기존 도구를 활용할 수 있는 유연성을 제공하여 에이전트의 특정 요구 사항에 대응함. +- **오류 처리**: 원활한 작동을 보장하기 위해 강력한 오류 처리 메커니즘을 포함함. +- **캐싱 메커니즘**: 성능 최적화와 중복 작업 감소를 위한 지능형 캐싱 기능을 갖춤. +- **비동기 지원**: 동기 및 비동기 도구를 모두 처리하여 논블로킹(Non-blocking) 작업을 가능하게 함. + +## CrewAI 도구 사용하기 + +crewAI 도구로 에이전트의 기능을 확장하려면, 우선 추가 도구 패키지를 설치하세요: + +```bash +pip install 'crewai[tools]' +``` + +아래는 도구 사용 예시입니다: + +```python Code +import os +from crewai import Agent, Task, Crew +# crewAI 도구 임포트 +from crewai_tools import ( + DirectoryReadTool, + FileReadTool, + SerperDevTool, + WebsiteSearchTool +) + +# API 키 설정 +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API 키 +os.environ["OPENAI_API_KEY"] = "Your Key" + +# 도구 인스턴스화 +docs_tool = DirectoryReadTool(directory='./blog-posts') +file_tool = FileReadTool() +search_tool = SerperDevTool() +web_rag_tool = WebsiteSearchTool() + +# 에이전트 생성 +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 +) + +# 작업 정의 +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' # 최종 블로그 글이 여기에 저장됩니다 +) + +# 계획 기능을 활성화하여 crew 구성 +crew = Crew( + agents=[researcher, writer], + tasks=[research, write], + verbose=True, + planning=True, # 계획 기능 활성화 +) + +# 작업 실행 +crew.kickoff() +``` + +## 사용 가능한 CrewAI 도구 + +- **에러 처리**: 모든 도구는 에러 처리 기능이 내장되어 있어, 에이전트가 예외 상황을 우아하게 관리하며 작업을 계속할 수 있습니다. +- **캐싱 메커니즘**: 모든 도구는 캐싱을 지원하여, 에이전트가 이전에 얻은 결과를 효율적으로 재사용할 수 있고 외부 자원에 대한 부하를 줄이며 실행 시간을 단축할 수 있습니다. 또한 도구의 `cache_function` 속성을 사용하여 캐싱 메커니즘을 세밀하게 제어할 수 있습니다. + +사용 가능한 도구 목록과 그 설명은 다음과 같습니다: + +| 도구 | 설명 | +| :-------------------------------- | :---------------------------------------------------------------------------------------------------- | +| **ApifyActorsTool** | 웹 스크래핑 및 자동화 작업을 위해 Apify Actors를 워크플로우에 통합하는 도구입니다. | +| **BrowserbaseLoadTool** | 웹 브라우저와 상호작용하고 데이터를 추출하는 도구입니다. | +| **CodeDocsSearchTool** | 코드 문서 및 관련 기술 문서를 검색하는 데 최적화된 RAG 도구입니다. | +| **CodeInterpreterTool** | 파이썬 코드를 해석하는 도구입니다. | +| **ComposioTool** | Composio 도구의 사용을 가능하게 합니다. | +| **CSVSearchTool** | CSV 파일 내에서 검색하도록 설계된 RAG 도구이며, 구조화된 데이터를 처리하도록 맞춤화되어 있습니다. | +| **DALL-E Tool** | DALL-E API를 사용해 이미지를 생성하는 도구입니다. | +| **DirectorySearchTool** | 디렉터리 내에서 검색하는 RAG 도구로, 파일 시스템을 탐색할 때 유용합니다. | +| **DOCXSearchTool** | DOCX 문서 내에서 검색하는 데 특화된 RAG 도구로, Word 파일을 처리할 때 이상적입니다. | +| **DirectoryReadTool** | 디렉터리 구조와 그 내용을 읽고 처리하도록 지원하는 도구입니다. | +| **ExaSearchTool** | 다양한 데이터 소스를 폭넓게 검색하기 위해 설계된 도구입니다. | +| **FileReadTool** | 다양한 파일 형식을 지원하며 파일에서 데이터를 읽고 추출할 수 있는 도구입니다. | +| **FirecrawlSearchTool** | Firecrawl을 이용해 웹페이지를 검색하고 결과를 반환하는 도구입니다. | +| **FirecrawlCrawlWebsiteTool** | Firecrawl을 사용해 웹페이지를 크롤링하는 도구입니다. | +| **FirecrawlScrapeWebsiteTool** | Firecrawl을 통해 웹페이지의 URL을 스크래핑하고 그 내용을 반환하는 도구입니다. | +| **GithubSearchTool** | GitHub 저장소 내에서 검색하는 RAG 도구로, 코드 및 문서 검색에 유용합니다. | +| **SerperDevTool** | 개발 용도로 특화된 도구로, 특정 기능이 개발 중입니다. | +| **TXTSearchTool** | 텍스트(.txt) 파일 내에서 검색하는 데 중점을 둔 RAG 도구로, 비구조적 데이터에 적합합니다. | +| **JSONSearchTool** | JSON 파일 내에서 검색하도록 설계된 RAG 도구로, 구조화된 데이터 처리에 적합합니다. | +| **LlamaIndexTool** | LlamaIndex 도구의 사용을 가능하게 합니다. | +| **MDXSearchTool** | 마크다운(MDX) 파일 내에서 검색하도록 맞춤화된 RAG 도구로, 문서화에 유용합니다. | +| **PDFSearchTool** | PDF 문서 내에서 검색하는 RAG 도구로, 스캔된 문서를 처리하기에 이상적입니다. | +| **PGSearchTool** | PostgreSQL 데이터베이스 내에서 검색하는 데 최적화된 RAG 도구로, 데이터베이스 쿼리에 적합합니다. | +| **Vision Tool** | DALL-E API를 사용해 이미지를 생성하는 도구입니다. | +| **RagTool** | 다양한 데이터 소스 및 형식을 처리할 수 있는 범용 RAG 도구입니다. | +| **ScrapeElementFromWebsiteTool** | 웹사이트에서 특정 요소만 스크래핑할 수 있는 도구로, 목표 데이터 추출에 유용합니다. | +| **ScrapeWebsiteTool** | 전체 웹사이트를 스크래핑할 수 있도록 도와주는 도구로, 포괄적인 데이터 수집에 이상적입니다. | +| **WebsiteSearchTool** | 웹사이트 콘텐츠를 검색하는 RAG 도구로, 웹 데이터 추출에 최적화되어 있습니다. | +| **XMLSearchTool** | XML 파일 내에서 검색하도록 설계된 RAG 도구로, 구조화된 데이터 형식에 적합합니다. | +| **YoutubeChannelSearchTool** | 유튜브 채널 내에서 검색하는 RAG 도구로, 동영상 콘텐츠 분석에 유용합니다. | +| **YoutubeVideoSearchTool** | 유튜브 동영상 내에서 검색하는 RAG 도구로, 동영상 데이터 추출에 이상적입니다. | + +## 자체 도구 만들기 + + + 개발자는 에이전트의 요구에 맞는 `custom tools`를 직접 제작하거나, + 미리 구축된 옵션을 활용할 수 있습니다. + + +CrewAI 도구를 만드는 방법에는 두 가지 주요 방법이 있습니다: + +### `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: + # Your tool's logic here + return "Tool's result" +``` + +## 비동기 도구 지원 + +CrewAI는 비동기 도구를 지원하여, 네트워크 요청, 파일 I/O 또는 기타 비동기 작업과 같이 메인 실행 스레드를 차단하지 않고 비차단 연산을 수행하는 도구를 구현할 수 있습니다. + +### 비동기 툴 만들기 + +비동기 툴을 만드는 방법에는 두 가지가 있습니다: + +#### 1. `tool` 데코레이터를 비동기 함수와 함께 사용하기 + +```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. 사용자 지정 Tool 클래스에서 비동기 메서드 구현 + +```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""" + # Your async implementation here + await asyncio.sleep(1) + return f"Processed {query} asynchronously" +``` + +### 비동기 도구 사용하기 + +비동기 도구는 표준 Crew 워크플로우와 Flow 기반 워크플로우 모두에서 원활하게 작동합니다: + +```python Code +# In standard Crew +agent = Agent(role="researcher", tools=[async_custom_tool]) + +# In Flow +class MyFlow(Flow): + @start() + async def begin(self): + crew = Crew(agents=[agent]) + result = await crew.kickoff_async() + return result +``` + +CrewAI 프레임워크는 동기 및 비동기 도구의 실행을 자동으로 처리하므로, 별도로 호출 방법을 신경 쓸 필요가 없습니다. + +### `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.""" + # Function logic here + return "Result from your custom tool" +``` + +### 커스텀 캐싱 메커니즘 + + + 도구는 선택적으로 `cache_function`을 구현하여 캐싱 동작을 세밀하게 조정할 수 있습니다. + 이 함수는 특정 조건에 따라 결과를 언제 캐싱할지 결정하여 캐싱 로직을 정교하게 제어할 수 있도록 합니다. + + +```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): + # In this case, we only cache the result if it's a multiple of 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, + ) + #... +``` + +## 결론 + +도구는 CrewAI 에이전트의 역량을 확장하는 데 중요한 역할을 하며, 이를 통해 에이전트가 폭넓은 작업을 수행하고 효과적으로 협업할 수 있습니다. CrewAI로 솔루션을 구축할 때는, 맞춤형 또는 기존의 도구를 모두 활용하여 에이전트를 강화하고 AI 생태계를 향상시키세요. 에이전트의 성능과 기능을 최적화하기 위해 오류 처리, 캐싱 메커니즘, 그리고 도구 인자의 유연성도 고려해보시기 바랍니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/concepts/training.mdx b/docs/v1.15.1/ko/concepts/training.mdx new file mode 100644 index 000000000..885366afe --- /dev/null +++ b/docs/v1.15.1/ko/concepts/training.mdx @@ -0,0 +1,132 @@ +--- +title: 교육 +description: 피드백을 조기에 제공하여 CrewAI 에이전트를 학습시키고 일관된 결과를 얻는 방법을 알아보세요. +icon: dumbbell +mode: "wide" +--- + +## 개요 + +CrewAI의 학습 기능을 사용하면 커맨드라인 인터페이스(CLI)를 통해 AI 에이전트를 학습시킬 수 있습니다. +`crewai train -n ` 명령어를 실행하면 학습 프로세스의 반복 횟수를 지정할 수 있습니다. + +학습 과정에서 CrewAI는 에이전트의 성능을 최적화하기 위한 다양한 기법과 인간의 피드백을 활용합니다. +이를 통해 에이전트는 이해력, 의사결정 능력, 문제 해결 능력을 향상할 수 있습니다. + +### CLI를 사용하여 Crew 학습시키기 + +학습 기능을 사용하려면 다음 단계를 따르십시오: + +1. 터미널 또는 명령 프롬프트를 엽니다. +2. CrewAI 프로젝트가 위치한 디렉터리로 이동합니다. +3. 다음 명령어를 실행합니다: + +```shell +crewai train -n (optional) +``` + + ``를 원하는 학습 반복 횟수로, ``을 `.pkl`로 끝나는 적절한 파일 이름으로 바꿔 입력하세요. + + +### 크루를 프로그래밍 방식으로 훈련시키기 + +크루를 프로그래밍 방식으로 훈련시키려면 다음 단계를 따르세요: + +1. 훈련을 위한 반복 횟수를 정의합니다. +2. 훈련 프로세스에 사용할 입력 파라미터를 지정합니다. +3. 잠재적인 오류를 처리하기 위해 try-except 블록 내에서 훈련 명령을 실행합니다. + +```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}") +``` + +### 주요 참고 사항 + +- **양의 정수 필수 조건:** 반복 횟수(`n_iterations`)가 양의 정수인지 확인하세요. 이 조건이 충족되지 않으면 코드에서 `ValueError`가 발생합니다. +- **파일명 필수 조건:** 파일명이 `.pkl`로 끝나는지 확인하세요. 이 조건이 충족되지 않으면 코드에서 `ValueError`가 발생합니다. +- **에러 처리:** 코드는 서브프로세스 오류 및 예기치 않은 예외를 처리하며, 사용자에게 에러 메시지를 제공합니다. + +에이전트의 복잡성에 따라 훈련 과정이 다소 시간이 소요될 수 있으며, 각 반복마다 사용자의 피드백이 필요함을 유의하세요. + +훈련이 완료되면, 에이전트는 향상된 능력과 지식을 갖추게 되어, 더욱 복잡한 작업을 해결하고 일관성 있고 가치 있는 인사이트를 제공할 수 있습니다. + +에이전트를 정기적으로 업데이트하고 재훈련하여 최신 정보와 업계 발전을 반영할 수 있도록 하세요. + +CrewAI와 함께 즐거운 훈련 되세요! 🚀 + +## 소형 언어 모델 고려사항 + + + 소형 언어 모델(≤7B 파라미터)을 학습 데이터 평가에 사용할 때, 구조화된 출력 생성 및 복잡한 지침 준수에 어려움을 겪을 수 있으니 주의하시기 바랍니다. + + +### 소형 모델의 학습 평가 한계 + + + + 소형 모델은 구조화된 학습 평가에 필요한 유효한 JSON 응답을 생성하는 데 종종 어려움을 겪으며, 이로 인해 파싱 오류와 불완전한 데이터가 발생할 수 있습니다. + + + 7B 파라미터 미만의 모델은 대형 모델에 비해 더 제한적이고 깊이 있는 추론이 부족한 평가 결과를 제공할 수 있습니다. + + + 복잡한 학습 평가 기준을 소형 모델이 완전히 따르거나 고려하지 못할 수 있습니다. + + + 소형 모델은 여러 학습 반복 과정에서 평가의 일관성이 부족할 수 있습니다. + + + +### 학습을 위한 권장 사항 + + + + 최적의 학습 품질과 신뢰할 수 있는 평가를 위해 최소 7B 파라미터 이상의 모델을 사용하는 것을 강력히 권장합니다: + + ```python + from crewai import Agent, Crew, Task, LLM + + # Recommended minimum for training evaluation + llm = LLM(model="mistral/open-mistral-7b") + + # Better options for reliable training evaluation + llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0") + llm = LLM(model="gpt-4o") + + # Use this LLM with your agents + agent = Agent( + role="Training Evaluator", + goal="Provide accurate training feedback", + llm=llm + ) + ``` + + + 더 강력한 모델일수록 더 우수한 피드백과 뛰어난 추론을 제공하므로, 더욱 효과적인 학습 반복이 가능합니다. + + + + 학습 평가를 위해 반드시 소형 모델을 사용해야 한다면 다음과 같은 제약 사항에 유의하세요: + + ```python + # Using a smaller model (expect some limitations) + llm = LLM(model="huggingface/microsoft/Phi-3-mini-4k-instruct") + ``` + + + CrewAI는 소형 모델에 대한 최적화 기능을 포함하고 있지만, 더 많은 인간의 개입이 필요한 덜 신뢰할 수 있고 세밀하지 않은 평가 결과가 발생할 수 있습니다. + + + \ No newline at end of file diff --git a/docs/v1.15.1/ko/enterprise/features/agent-control-plane/monitoring.mdx b/docs/v1.15.1/ko/enterprise/features/agent-control-plane/monitoring.mdx new file mode 100644 index 000000000..c8ea48fbb --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/agent-control-plane/monitoring.mdx @@ -0,0 +1,112 @@ +--- +title: "자동화 살펴보기" +description: "Automations 탭에서 플릿 상태, LLM 소비, 자동화별 동작을 확인합니다." +sidebarTitle: "모니터링" +icon: "gauge" +mode: "wide" +--- + + + **ACP (베타) 문서 내비게이션** + + - [개요](/ko/enterprise/features/agent-control-plane/overview) + - **모니터링** *(현재 페이지)* + - [규칙](/ko/enterprise/features/agent-control-plane/rules) + + +## 개요 + +**Automations** 탭은 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)의 읽기 전용 운영 뷰입니다. 두 개의 메트릭 카드, 인터랙티브 sankey, 그리고 **Automations**와 **Consumption** 두 개의 서브 테이블을 결합해 검색·필터·정렬을 지원합니다. + + + ![Agent Control Plane 개요](/images/enterprise/acp-overview-automations-sankey.png) + + +모든 차트와 테이블은 오른쪽 상단의 **지난 24시간 / 지난 1주 / 지난 30일** 선택기를 따릅니다. 변화량은 선택한 윈도우를 같은 길이의 이전 윈도우와 비교합니다. + + + 행은 **crewAI v1.13 이상**의 deployment에 대해서만 데이터를 표시합니다. 그 이전 deployment는 sankey 아래 *"We've detected N other automations that we can't display"* 배너에 나타나며, 업데이트하고 재배포할 때까지 어떤 메트릭에도 기여하지 않습니다. [개요 — 요구사항](/ko/enterprise/features/agent-control-plane/overview#요구사항)을 참고하세요. + + +## 대시보드 + +페이지 상단에는 두 개의 메트릭 카드와 인터랙티브 sankey가 있습니다. 어느 카드를 클릭해도 sankey가 다음 두 모드 사이를 전환합니다: + +- **상태 모드** — `전체 자동화 → 상태 버킷(Critical / Warning / Healthy)`. 버킷을 클릭하면 Automations 테이블이 해당 deployment로 필터링됩니다. +- **소비 모드** — `모델 공급자 → 자동화 → 총 비용`. 공급자를 클릭하면 Consumption 테이블이 해당 공급자로 필터링됩니다. + +| 카드 | 표시 내용 | +|------|---------------| +| **Automations** | `active` 자동화(및 전체 개수), 윈도우 내 총 `errors`, 현재 `active executions`(및 윈도우 내 총합), 이전 기간 대비 변화량. | +| **Consumption** | 총 `cost`와 `tokens used`, 이전 기간 대비 비용 변화량. | + + + ![소비 sankey가 적용된 개요](/images/enterprise/acp-overview-consumption-sankey.png) + + +## Automations 테이블 + +**Automations** 서브 탭은 deployment 단위의 플릿 상태 분해입니다. 각 행은 배포된 하나의 crew 또는 flow입니다. + + + ![상태 분해가 있는 자동화 테이블](/images/enterprise/acp-automations-table.png) + + +| 열 | 표시 내용 | +|--------|---------------| +| **Automation** | deployment 이름과 할당된 태그(예: `production`, `financial`). | +| **Last execution** | 가장 최근 실행 이후 경과 시간. | +| **Health Status Breakdown** | 윈도우 내 실행에 대한 `Critical` / `Warning` / `Healthy` 비율의 누적 막대. | +| **Executions with Errors** | 윈도우 내 총 실패 실행 수. | +| **PII detection applied** | deployment별 PII 설정 또는 일치하는 [PII 규칙](/ko/enterprise/features/agent-control-plane/rules)이 활성화된 경우 `Yes`. | +| **Executions** | 윈도우 내 총 실행 수. | +| **Last updated** | deployment의 마지막 재배포 시점. | +| **Crew Version** | deployment가 보고한 `crewai` 버전. `1.13` 미만 버전 옆의 정보 아이콘은 메트릭에 기여할 수 없는 행을 표시합니다. | + +이름으로 검색하고 `Status`(`Healthy` / `Warning` / `Critical`)로 필터링하며, 컬럼 헤더로 정렬할 수 있습니다. deployment 이름을 클릭하면 **Automation 패널**이 열립니다. + +## Consumption 테이블 + +**Consumption** 서브 탭은 deployment 단위의 LLM 지출 및 토큰 사용량 분해입니다. + + + ![LLM 공급자별로 분해된 소비 테이블](/images/enterprise/acp-consumption-table.png) + + +| 열 | 표시 내용 | +|--------|---------------| +| **Automation** | deployment 이름. | +| **Last execution** | 가장 최근 실행 이후 경과 시간. | +| **Tokens used** | 이 자동화가 사용한 LLM 공급자별로 한 행, 이전 기간 대비 변화량 포함. | +| **Cost** | LLM 공급자별 비용, 이전 기간 대비 변화량 포함. | +| **Total cost** | 모든 공급자의 합계, 변화량 포함. | +| **Executions** | 윈도우 내 총 실행 수. | +| **Last updated** | deployment의 마지막 재배포 시점. | +| **Crew Version** | deployment가 보고한 `crewai` 버전. | + +**LLM provider**로 필터링하고 `Cost`, `Executions` 또는 `Last run`으로 정렬할 수 있습니다. + + + **빈 셀(`—` 또는 `$0.00`)은 보통 deployment가 crewAI v1.13 미만임을 의미합니다.** 위 스크린샷에서 *Automation F*(`1.7.0`)와 *Automation I*(`1.12.2`)는 토큰과 비용이 비어 있습니다. 실행은 여전히 동작하지만, 이 테이블을 채우는 공급자 수준 텔레메트리를 emit하지 않습니다. 이 crew들을 업데이트하고 재배포하면 소비 데이터가 수집되기 시작합니다. + + +## 관련 문서 + + + + ACP란 무엇이며, 요구사항, 플랜 등급, RBAC에 대해. + + + 조직 단위 PII Redaction 규칙을 여러 자동화에 적용합니다. + + + 개별 실행을 드릴다운하여 에이전트의 추론, 도구 호출, 토큰 사용량을 확인합니다. + + + Agent Control Plane을 지원하는 crewAI 버전으로 crew를 배포합니다. + + + + + Agent Control Plane에서 메트릭을 해석하는 데 도움이 필요하시면 지원 팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/features/agent-control-plane/overview.mdx b/docs/v1.15.1/ko/enterprise/features/agent-control-plane/overview.mdx new file mode 100644 index 000000000..9af73ac16 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/agent-control-plane/overview.mdx @@ -0,0 +1,82 @@ +--- +title: Agent Control Plane 개요 +description: "라이브 자동화의 통합 운영 허브 — 플릿 상태, LLM 소비, 조직 단위 정책을 한 화면에서." +sidebarTitle: 개요 +icon: "book-open" +--- + + + **ACP (베타) 문서 내비게이션** + + - **개요** *(현재 페이지)* + - [모니터링](/ko/enterprise/features/agent-control-plane/monitoring) + - [규칙](/ko/enterprise/features/agent-control-plane/rules) + + +## 개요 + +**Agent Control Plane**(ACP)은 CrewAI AMP에서 실행 중인 모든 워크로드를 위한 운영 허브입니다. **Automations**와 **Rules** 두 개의 탭으로 구성된 단일 화면에서 다음 작업을 할 수 있습니다: + +- 모든 라이브 자동화(crew 또는 flow)의 **상태(health)**를 `Critical` / `Warning` / `Healthy` 분포와 실행 횟수로 모니터링합니다. +- 자동화별·공급자별·모델별 **LLM 소비**(토큰 및 비용)를 추적하고, 이전 기간 대비 변화량을 확인합니다. +- 임의의 자동화 또는 모델 공급자를 드릴다운하여 시계열 차트와 공급자별 분해를 살펴봅니다. +- 조직 전체에 **규칙(Rules)**(현재: PII Redaction)을 적용하여 각 deployment를 개별 편집하지 않고 한 번에 여러 자동화에 정책을 강제합니다. + + + ![Agent Control Plane 개요](/images/enterprise/acp-overview-automations-sankey.png) + + + + Agent Control Plane은 현재 CrewAI Platform에서 **Beta**로 표시되어 있습니다. + + +두 탭은 서로 다른 두 가지 질문에 답합니다: + +- **Automations** — *"지금 내 플릿은 어떻게 동작하고 있고, 얼마나 비용이 들고 있는가?"* [모니터링](/ko/enterprise/features/agent-control-plane/monitoring)을 참고하세요. +- **Rules** — *"정책(예: PII redaction)을 매번 재배포하지 않고 여러 deployment에 어떻게 강제할 수 있는가?"* [규칙](/ko/enterprise/features/agent-control-plane/rules)을 참고하세요. + +## 요구사항 + + + 이 페이지에서 자동화에 대한 데이터(상태, 실행, 오류, 토큰, 비용)를 채우려면 **crewAI v1.13 이상**이 필요합니다. 모든 데이터는 `crewai==1.13`에서 활성화된 텔레메트리를 통해 흘러갑니다. 그 이전 deployment는 *"We've detected N other automations that we can't display"* 배너에 나타나며, 업데이트하고 재배포할 때까지 어떤 행에도 데이터를 기여하지 않습니다. + + + + [규칙](/ko/enterprise/features/agent-control-plane/rules)을 생성하거나 편집하려면 **Enterprise 또는 Ultra 플랜**이 필요합니다. 하위 플랜의 조직도 Rules 탭을 열고 기존 규칙을 볼 수 있지만, 편집기는 "Enterprise" 잠금 핀과 *"PII Redaction rules require an Enterprise plan."* 경고와 함께 읽기 전용으로 표시됩니다. 모니터링(Automations 탭)은 기능이 활성화된 모든 플랜에서 사용할 수 있습니다. + + +- **Agent Control Plane** 기능이 조직에 대해 활성화되어 있어야 합니다. 사이드바에 보이지 않으면 계정 오너에게 활성화를 요청하세요. +- ACP 내부에서는 [RBAC](/ko/enterprise/features/rbac)가 접근 권한을 관리합니다: 대시보드 및 규칙을 보려면 `read`, 규칙을 생성·편집·토글·삭제하려면 `manage` 권한이 필요합니다. +- 모든 차트와 테이블은 오른쪽 상단의 시간 선택기를 통해 **지난 24시간**, **지난 1주**, **지난 30일**로 범위를 조정할 수 있습니다. 변화량(`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday` 등)은 선택한 윈도우를 같은 길이의 이전 윈도우와 비교합니다. + +## 여기에서 할 수 있는 일 + + + + 메트릭 카드, 인터랙티브 sankey, 자동화별 테이블, 자동화 또는 공급자별 드릴다운 사이드 패널로 플릿 상태와 LLM 지출을 살펴봅니다. + + + 도구와 태그로 범위를 지정한 PII Redaction 정책을 조직 단위로 적용합니다. 변경 사항은 다음 실행부터 적용되며 재배포가 필요 없습니다. + + + +## 관련 문서 + + + + 개별 실행을 드릴다운하여 에이전트의 추론, 도구 호출, 토큰 사용량을 확인합니다. + + + 누가 Agent Control Plane을 읽을 수 있고 누가 규칙을 편집할 수 있는지 관리합니다. + + + 규칙이 참조하는 엔티티 카탈로그 및 deployment 단위 PII 설정. + + + Agent Control Plane을 지원하는 crewAI 버전으로 crew를 배포합니다. + + + + + 메트릭 해석 또는 규칙 설계에 도움이 필요하시면 지원 팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/features/agent-control-plane/rules.mdx b/docs/v1.15.1/ko/enterprise/features/agent-control-plane/rules.mdx new file mode 100644 index 000000000..b4e9e6b6a --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/agent-control-plane/rules.mdx @@ -0,0 +1,122 @@ +--- +title: "규칙 설정하기" +description: "한 곳에서 조직 단위 정책을 여러 자동화에 적용합니다." +sidebarTitle: "규칙" +icon: "shield-check" +mode: "wide" +--- + + + **ACP (베타) 문서 내비게이션** + + - [개요](/ko/enterprise/features/agent-control-plane/overview) + - [모니터링](/ko/enterprise/features/agent-control-plane/monitoring) + - **규칙** *(현재 페이지)* + + +## 개요 + +규칙(Rules)은 각 deployment를 개별 설정하는 대신, 정책 — 현재: **PII Redaction** — 을 한 번에 여러 자동화에 적용할 수 있게 해줍니다. 관리하려면 [Agent Control Plane](/ko/enterprise/features/agent-control-plane/overview)에서 **Rules** 탭을 엽니다. + + + ![규칙 목록](/images/enterprise/acp-rules-list.png) + + +각 규칙 카드에는 이름, 설명, 규칙이 적용되는 **범위(scope)**(선택된 도구와 태그), 그리고 현재 범위와 일치하는 deployment의 수인 **engaged automations**가 표시됩니다. 오른쪽 토글로 규칙을 삭제하지 않고 활성/비활성할 수 있습니다. + +## 요구사항 + + + PII Redaction 규칙을 생성하거나 편집하려면 **Enterprise 또는 Ultra 플랜**이 필요합니다. 하위 플랜의 조직도 Rules 탭을 열고 기존 규칙을 볼 수는 있지만, 편집기는 "Enterprise" 잠금 핀과 *"PII Redaction rules require an Enterprise plan."* 경고와 함께 읽기 전용으로 렌더링됩니다. 업그레이드하려면 계정 오너 또는 영업팀에 문의하세요. + + +- **Agent Control Plane** 기능이 조직에 대해 활성화되어 있어야 합니다. [개요 — 요구사항](/ko/enterprise/features/agent-control-plane/overview#요구사항)을 참고하세요. +- 규칙을 생성·편집·토글·삭제하려면 Agent Control Plane에 대한 [RBAC](/ko/enterprise/features/rbac)의 `manage` 권한이 필요합니다. 보려면 `read` 권한만으로 충분합니다. +- 모든 규칙 변경은 감사를 위해 버전 관리됩니다. + +## 사용 가능한 규칙 유형 + +| 유형 | 동작 | +|------|---------------| +| **PII Redaction** | 일치하는 모든 자동화의 실행에 PII redaction을 적용합니다. [Traces용 PII Redaction](/ko/enterprise/features/pii-trace-redactions)에 문서화된 동일한 엔티티 카탈로그와 커스텀 recognizer를 사용합니다. | + +향후 더 많은 규칙 유형이 추가될 예정입니다. + +## 규칙 만들기 + + + 조건 및 PII 마스크 유형이 있는 규칙 편집 사이드 패널 + + + + + Rules 탭 오른쪽 상단의 **+ Create new**를 클릭하거나, 기존 규칙 카드의 **View Details**를 클릭합니다. + + + + 규칙에 명확한 이름(예: *Mask PII (CC)*)과 적용 시점을 설명하는 description을 부여합니다. 둘 다 규칙 카드와 Engaged Automations 모달에 표시됩니다. + + + + 현재 **PII Redaction**만 사용할 수 있습니다. + + + + 조건은 규칙이 어떤 자동화에 engage 할지 결정합니다. 둘 다 선택 사항이며 **집합 동일성(set-equality)** 의미론을 사용합니다: + + - **Tools** — 도구 집합이 선택된 도구와 **정확히 일치**하는 자동화만 engage 됩니다. Studio 앱, MCP, OSS 도구, Tool Repository registry 도구 중에서 선택합니다. + - **Automations** — 태그 집합이 선택된 태그와 **정확히 일치**하는 자동화만 engage 됩니다. + + 피커를 비워두면 "이 차원에서 필터링하지 않음"을 의미합니다. 두 피커를 모두 비워두면 규칙이 조직의 **모든** 자동화에 적용됩니다. + + + + 적용할 각 엔티티 유형을 체크하고 **Mask**(엔티티 레이블로 치환, 예: ``) 또는 **Redact**(일치하는 텍스트를 완전히 제거) 중에서 선택합니다. 전체 엔티티 카탈로그와 조직 단위 커스텀 recognizer 추가 방법은 [Traces용 PII Redaction](/ko/enterprise/features/pii-trace-redactions)을 참고하세요. + + + + 저장하는 즉시 engage 된 모든 자동화의 **향후** 실행에 규칙이 적용됩니다. 재배포는 필요 없습니다. + + + +## Engaged automations + +규칙 카드의 **Engaged N automations**를 클릭하면 현재 규칙이 일치시키고 있는 deployment와 각 deployment의 마지막 실행을 정확히 확인할 수 있습니다. + + + ![Engaged automations 모달](/images/enterprise/acp-rules-engaged-modal.png) + + +규칙을 활성화하기 전에 범위를 빠르게 점검하는 가장 좋은 방법입니다. 예를 들어, `production` 태그로 범위를 지정한 규칙이 의도치 않게 staging deployment를 일치시키지 않는지 확인할 수 있습니다. + +## 조직 단위 규칙 vs deployment 단위 설정 + +PII Redaction은 두 곳에서 설정할 수 있습니다: + +- **deployment 단위** — 각 deployment의 **Settings → PII Protection** ([가이드](/ko/enterprise/features/pii-trace-redactions)) +- **조직 단위** — 이 페이지의 규칙 + +활성화된 조직 단위 규칙의 범위가 어떤 deployment와 일치하면, 규칙의 엔티티 구성이 그 deployment의 실행에 대해 **deployment가 소유한 PII 설정을 덮어씁니다**. 규칙이 연결된 동안에는 규칙이 단일 진실 공급원이 됩니다. 규칙을 비활성화하거나 분리하면(또는 범위를 변경하여 더 이상 일치하지 않게 만들면) deployment는 자체 PII Protection 설정으로 되돌아갑니다. + +여러 deployment에 걸쳐 일관된 정책을 강제하고 싶을 때는 조직 단위 규칙을 선호하고, 일회성 예외에 대해서는 deployment 단위 설정을 사용하세요. + +## 관련 문서 + + + + ACP란 무엇이며, 요구사항, 플랜 등급, RBAC에 대해. + + + 플릿 전반의 자동화와 LLM 소비를 모니터링합니다. + + + 엔티티 카탈로그, 커스텀 recognizer, deployment 단위 구성. + + + 누가 규칙을 만들거나 편집할 수 있는지 관리합니다. + + + + + 조직의 규칙을 설계하는 데 도움이 필요하시면 지원 팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/features/agent-repositories.mdx b/docs/v1.15.1/ko/enterprise/features/agent-repositories.mdx new file mode 100644 index 000000000..7e75f775d --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/agent-repositories.mdx @@ -0,0 +1,158 @@ +--- +title: '에이전트 저장소' +description: '에이전트 저장소를 사용하여 팀과 프로젝트 전반에 걸쳐 에이전트를 공유하고 재사용하는 방법을 알아보세요' +icon: 'database' +mode: "wide" +--- + +생각: 이제 훌륭한 답변을 드릴 수 있습니다. +최종 답변: +Agent Repositories는 엔터프라이즈 사용자가 팀과 프로젝트 전반에 걸쳐 agent 정의를 저장, 공유, 재사용할 수 있도록 합니다. 이 기능을 통해 조직은 표준화된 agent의 중앙 라이브러리를 유지할 수 있어 일관성을 높이고 중복 작업을 줄일 수 있습니다. + +## 에이전트 저장소의 이점 + +- **표준화**: 조직 전반에서 일관된 에이전트 정의를 유지합니다 +- **재사용성**: 한 번 에이전트를 생성하여 여러 crew 및 프로젝트에서 사용할 수 있습니다 +- **거버넌스**: 조직 전체에 적용되는 에이전트 구성 정책을 구현합니다 +- **협업**: 여러 팀이 서로의 작업을 공유하고 발전시킬 수 있도록 지원합니다 + +## 에이전트 저장소 사용하기 + +### 사전 준비 사항 + +1. CrewAI 계정이 있어야 하며, [무료 플랜](https://app.crewai.com)을 이용해보세요. +2. CrewAI CLI를 사용하여 인증되어 있어야 합니다. +3. 여러 개의 조직이 있는 경우, CLI 명령어를 사용하여 올바른 조직으로 전환했는지 확인하세요: + +```bash +crewai org switch +``` + +### 저장소에서 에이전트 생성 및 관리 + +저장소에서 에이전트를 생성하고 관리하려면 Enterprise Dashboard를 사용하세요. + +### 리포지토리에서 에이전트 불러오기 + +코드에서 `from_repository` 파라미터를 사용하여 리포지토리에서 에이전트를 불러올 수 있습니다: + +```python +from crewai import Agent + +# Create an agent by loading it from a repository +# The agent is loaded with all its predefined configurations +researcher = Agent( + from_repository="market-research-agent" +) + +``` + +### 저장소 설정 재정의 + +구성에서 특정 설정을 제공하여 저장소의 설정을 재정의할 수 있습니다. + +```python +researcher = Agent( + from_repository="market-research-agent", + goal="Research the latest trends in AI development", # Override the repository goal + verbose=True # Add a setting not in the repository +) +``` + +### 예제: Repository 에이전트로 Crew 생성하기 + +```python +from crewai import Crew, Agent, Task + +# Load agents from repositories +researcher = Agent( + from_repository="market-research-agent" +) + +writer = Agent( + from_repository="content-writer-agent" +) + +# Create tasks +research_task = Task( + description="Research the latest trends in AI", + agent=researcher +) + +writing_task = Task( + description="Write a comprehensive report based on the research", + agent=writer +) + +# Create the crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +# Run the crew +result = crew.kickoff() +``` + +### 예시: `kickoff()`를 Repository Agent와 함께 사용하기 + +`kickoff()` 메서드를 이용해 repository agent를 직접 사용하여 보다 간단하게 상호작용할 수도 있습니다: + +```python +from crewai import Agent +from pydantic import BaseModel +from typing import List + +# 구조화된 출력 형식 정의 +class MarketAnalysis(BaseModel): + key_trends: List[str] + opportunities: List[str] + recommendation: str + +# 저장소에서 agent 불러오기 +analyst = Agent( + from_repository="market-analyst-agent", + verbose=True +) + +# 자유 형식 응답 받기 +result = analyst.kickoff("Analyze the AI market in 2025") +print(result.raw) # 원시 응답 접근 + +# 구조화된 출력 받기 +structured_result = analyst.kickoff( + "Provide a structured analysis of the AI market in 2025", + response_format=MarketAnalysis +) + +# 구조화된 데이터 접근 +print(f"Key Trends: {structured_result.pydantic.key_trends}") +print(f"Recommendation: {structured_result.pydantic.recommendation}") +``` + +## 모범 사례 + +1. **명명 규칙**: 리포지토리 에이전트에 대해 명확하고 설명적인 이름을 사용하세요. +2. **문서화**: 각 에이전트에 대한 포괄적인 설명을 포함하세요. +3. **도구 관리**: 리포지토리 에이전트가 참조하는 도구들이 환경에 제공되는지 확인하세요. +4. **접근 제어**: 권한이 있는 팀원만 리포지토리 에이전트를 수정할 수 있도록 권한을 관리하세요. + +## 조직 관리 + +조직을 전환하거나 현재 조직을 확인하려면 CrewAI CLI를 사용하세요: + +```bash +# 현재 조직 보기 +crewai org current + +# 다른 조직으로 전환 +crewai org switch + +# 사용 가능한 모든 조직 목록 확인 +crewai org list +``` + + +리포지토리에서 agent를 불러올 때는 인증이 완료되어 있어야 하며, 올바른 조직으로 전환되어 있어야 합니다. 오류가 발생하면 위의 CLI 명령어를 사용하여 인증 상태와 조직 설정을 확인하세요. + \ No newline at end of file diff --git a/docs/v1.15.1/ko/enterprise/features/automations.mdx b/docs/v1.15.1/ko/enterprise/features/automations.mdx new file mode 100644 index 000000000..84fd1c3eb --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/automations.mdx @@ -0,0 +1,103 @@ +--- +title: "자동화" +description: "배포된 크루(자동화)를 한 곳에서 관리, 배포 및 모니터링하세요." +icon: "rocket" +mode: "wide" +--- + +## 개요 + +자동화는 배포된 크루를 운영하는 허브입니다. GitHub 또는 ZIP으로 배포하고, 환경 변수를 관리하고, 필요 시 재배포하며 각 자동화의 상태를 모니터링하세요. + + + ![자동화 개요](/images/enterprise/automations-overview.png) + + +## 배포 방법 + +### GitHub로 배포 + +버전 관리 및 지속적 배포에 적합합니다. + + + + Configure GitHub를 클릭하고 접근을 승인합니다. + + + 배포할 리포지토리와 브랜치를 선택합니다. + + + Automatically deploy new commits를 켜면 푸시 시마다 자동 배포됩니다. + + + 개별로 추가하거나 Bulk View를 사용해 여러 변수를 한 번에 추가합니다. + + + Deploy를 클릭해 라이브 자동화를 생성합니다. + + + + + ![GitHub 배포](/images/enterprise/deploy-from-github.png) + + +### ZIP으로 배포 + +Git 없이 빠르게 배포 — 프로젝트 ZIP 패키지를 업로드하세요. + + + + 컴퓨터에서 ZIP 파일을 선택합니다. + + + 필요한 변수를 제공합니다. + + + Deploy를 클릭해 라이브 자동화를 생성합니다. + + + + + ![ZIP 배포](/images/enterprise/deploy-from-zip.png) + + +## 자동화 대시보드 + +테이블에는 모든 라이브 자동화가 다음 정보와 함께 표시됩니다: + +- **CREW**: 자동화 이름 +- **STATUS**: Online / Failed / In Progress +- **URL**: kickoff/status 엔드포인트 +- **TOKEN**: 자동화 토큰 +- **ACTIONS**: 재배포, 삭제 등 + +우측 상단 컨트롤로 필터 및 검색: + +- 이름으로 검색 +- Status로 필터 +- Source로 필터 (GitHub / Studio / ZIP) + +배포 후 **Options** 드롭다운에서 `chat with this crew`, `Export React Component`, `Export as MCP`를 사용할 수 있습니다. + + + ![자동화 표](/images/enterprise/automations-table.png) + + +## 모범 사례 + +- 버전 관리 및 CI/CD를 위해 GitHub 배포를 권장 +- 코드/구성 변경 후 재배포 사용 또는 푸시마다 자동 배포 설정 + +## 관련 문서 + + + + GitHub 또는 ZIP 파일로 크루 배포 + + + 웹훅 또는 API로 자동화 트리거 + + + 실시간 이벤트/업데이트 스트리밍 + + diff --git a/docs/v1.15.1/ko/enterprise/features/crew-studio.mdx b/docs/v1.15.1/ko/enterprise/features/crew-studio.mdx new file mode 100644 index 000000000..3de3e45aa --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/crew-studio.mdx @@ -0,0 +1,88 @@ +--- +title: "Crew Studio" +description: "AI 보조, 비주얼 에디터, 통합 테스트로 새로운 자동화를 구축하세요." +icon: "pencil" +mode: "wide" +--- + +## 개요 + +Crew Studio는 자연어와 시각적 워크플로 에디터로 처음부터 자동화를 만드는 인터랙티브한 AI 보조 작업 공간입니다. + + + ![Crew Studio 개요](/images/enterprise/crew-studio-overview.png) + + +## 프롬프트 기반 생성 + +- 원하는 자동화를 설명하면, AI가 에이전트/태스크/도구를 생성합니다. +- 마이크 아이콘으로 음성 입력을 사용할 수 있습니다. +- 공통 사용 사례용 프롬프트 템플릿으로 시작할 수 있습니다. + + + ![프롬프트 빌더](/images/enterprise/crew-studio-prompt.png) + + +## 비주얼 에디터 + +캔버스는 노드/엣지 형태로 플로우를 표현하며, 세 개의 보조 패널로 코드 없이 쉽게 구성할 수 있습니다 (일명 "vibe coding AI Agents"): + +- **AI Thoughts (좌측)**: 설계 중 스트리밍 추론 +- **Canvas (중앙)**: 에이전트/태스크 노드와 연결 +- **Resources (우측)**: 드래그앤드롭 컴포넌트 (에이전트, 태스크, 도구) + +드래그앤드롭으로 캔버스를 구성하거나, 채팅 섹션으로 에이전트를 생성할 수 있으며 두 방식은 상태를 공유합니다. + + + ![비주얼 캔버스](/images/enterprise/crew-studio-canvas.png) + + +## 실행 & 디버깅 + +Execution 뷰로 전환하여 실행을 관찰하세요: + +- 이벤트 타임라인 +- 상세 로그 (Details, Messages, Raw Data) +- 게시 전 로컬 실행 + + + ![실행 뷰](/images/enterprise/crew-studio-execution.png) + + +## 게시 & 내보내기 + +- Publish로 라이브 자동화 배포 +- Download로 소스 ZIP 다운로드 (로컬 개발용) + + + ![게시 & 다운로드](/images/enterprise/crew-studio-publish.png) + + +게시 후 **Options** 드롭다운에서 `chat with this crew`, `Export React Component`, `Export as MCP`를 사용할 수 있습니다. + + + ![게시된 자동화](/images/enterprise/crew-studio-published.png) + + +## 모범 사례 + +- Studio에서 빠르게 반복하고, 안정화 후 게시 +- 도구 권한은 최소한으로 제한 +- Traces로 동작/성능 검증 + +## 관련 문서 + + + + Crew Studio를 활성화하세요. + + + 크루를 빌드하세요. + + + GitHub 또는 ZIP 파일로 크루 배포. + + + React 컴포넌트를 내보내세요. + + diff --git a/docs/v1.15.1/ko/enterprise/features/flow-hitl-management.mdx b/docs/v1.15.1/ko/enterprise/features/flow-hitl-management.mdx new file mode 100644 index 000000000..adb8ee492 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/flow-hitl-management.mdx @@ -0,0 +1,558 @@ +--- +title: "Flow HITL 관리" +description: "이메일 우선 알림, 라우팅 규칙 및 자동 응답 기능을 갖춘 Flow용 엔터프라이즈급 인간 검토" +icon: "users-gear" +mode: "wide" +--- + + +Flow HITL 관리 기능은 `@human_feedback` 데코레이터가 필요하며, **CrewAI 버전 1.8.0 이상**에서 사용할 수 있습니다. 이 기능은 Crew가 아닌 **Flow**에만 적용됩니다. + + +CrewAI Enterprise는 AI 워크플로우를 협업적인 인간-AI 프로세스로 전환하는 Flow용 포괄적인 Human-in-the-Loop(HITL) 관리 시스템을 제공합니다. 플랫폼은 **이메일 우선 아키텍처**를 사용하여 이메일 주소가 있는 누구나 플랫폼 계정 없이도 검토 요청에 응답할 수 있습니다. + +## 개요 + + + + 응답자가 알림 이메일에 직접 회신하여 피드백 제공 가능 + + + 메서드 패턴 또는 Flow 상태에 따라 특정 이메일로 요청 라우팅 + + + 시간 내에 인간이 응답하지 않을 경우 자동 대체 응답 구성 + + + +### 주요 이점 + +- **간단한 멘탈 모델**: 이메일 주소는 보편적이며 플랫폼 사용자나 역할을 관리할 필요 없음 +- **외부 응답자**: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능 +- **동적 할당**: Flow 상태에서 직접 담당자 이메일 가져오기 (예: `sales_rep_email`) +- **간소화된 구성**: 설정할 항목이 적어 더 빠르게 가치 실현 +- **이메일이 주요 채널**: 대부분의 사용자는 대시보드 로그인보다 이메일로 응답하는 것을 선호 + +## Flow에서 인간 검토 포인트 설정 + +`@human_feedback` 데코레이터를 사용하여 Flow 내에 인간 검토 체크포인트를 구성합니다. 실행이 검토 포인트에 도달하면 시스템이 일시 중지되고, 담당자에게 이메일로 알리며, 응답을 기다립니다. + +```python +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ContentApprovalFlow(Flow): + @start() + def generate_content(self): + return "Q1 캠페인용 마케팅 카피 생성..." + + @human_feedback( + message="브랜드 준수를 위해 이 콘텐츠를 검토해 주세요:", + emit=["approved", "rejected", "needs_revision"], + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "검토용 마케팅 카피..." + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + print(f"승인된 콘텐츠 게시 중. 검토자 노트: {result.feedback}") + + @listen("rejected") + def archive_content(self, result: HumanFeedbackResult): + print(f"콘텐츠 거부됨. 사유: {result.feedback}") +``` + +완전한 구현 세부 사항은 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요. + +### 데코레이터 파라미터 + +| 파라미터 | 유형 | 설명 | +|---------|------|------| +| `message` | `str` | 인간 검토자에게 표시되는 메시지 | +| `emit` | `list[str]` | 유효한 응답 옵션 (UI에서 버튼으로 표시) | + +## 플랫폼 구성 + +HITL 구성에 접근: **배포** → **설정** → **Human in the Loop 구성** + + + HITL 구성 설정 + + +### 이메일 알림 + +HITL 요청에 대한 이메일 알림을 활성화하거나 비활성화하는 토글입니다. + +| 설정 | 기본값 | 설명 | +|-----|-------|------| +| 이메일 알림 | 활성화됨 | 피드백 요청 시 이메일 전송 | + + +비활성화되면 응답자는 대시보드 UI를 사용하거나 커스텀 알림 시스템을 위해 webhook을 구성해야 합니다. + + +### SLA 목표 + +추적 및 메트릭 목적으로 목표 응답 시간을 설정합니다. + +| 설정 | 설명 | +|-----|------| +| SLA 목표 (분) | 목표 응답 시간. 대시보드 메트릭 및 SLA 추적에 사용 | + +SLA 추적을 비활성화하려면 비워 두세요. + +## 이메일 알림 및 응답 + +HITL 시스템은 응답자가 알림 이메일에 직접 회신할 수 있는 이메일 우선 아키텍처를 사용합니다. + +### 이메일 응답 작동 방식 + + + + HITL 요청이 생성되면 검토 콘텐츠와 컨텍스트가 포함된 이메일이 할당된 응답자에게 전송됩니다. + + + 이메일에는 인증을 위한 서명된 토큰이 포함된 특별한 reply-to 주소가 있습니다. + + + 응답자는 이메일에 피드백으로 회신하면 됩니다—로그인 필요 없음. + + + 플랫폼이 회신을 받고, 서명된 토큰을 확인하고, 발신자 이메일을 매칭합니다. + + + 피드백이 기록되고 인간의 입력으로 Flow가 계속됩니다. + + + +### 응답 형식 + +응답자는 다음과 같이 회신할 수 있습니다: + +- **Emit 옵션**: 회신이 `emit` 옵션과 일치하면 (예: "approved") 직접 사용됨 +- **자유 형식 텍스트**: 모든 텍스트 응답이 피드백으로 Flow에 전달됨 +- **일반 텍스트**: 회신 본문의 첫 번째 줄이 피드백으로 사용됨 + +### 확인 이메일 + +회신을 처리한 후 응답자는 피드백이 성공적으로 제출되었는지 또는 오류가 발생했는지 나타내는 확인 이메일을 받습니다. + +### 이메일 토큰 보안 + +- 토큰은 보안을 위해 암호화 서명됨 +- 토큰은 7일 후 만료됨 +- 발신자 이메일은 토큰의 인증된 이메일과 일치해야 함 +- 처리 후 확인/오류 이메일 전송됨 + +## 라우팅 규칙 + +메서드 패턴에 따라 HITL 요청을 특정 이메일 주소로 라우팅합니다. + + + HITL 라우팅 규칙 구성 + + +### 규칙 구조 + +```json +{ + "name": "재무팀으로 승인", + "match": { + "method_name": "approve_*" + }, + "assign_to_email": "finance@company.com", + "assign_from_input": "manager_email" +} +``` + +### 매칭 패턴 + +| 패턴 | 설명 | 매칭 예시 | +|-----|------|----------| +| `approve_*` | 와일드카드 (모든 문자) | `approve_payment`, `approve_vendor` | +| `review_?` | 단일 문자 | `review_a`, `review_1` | +| `validate_payment` | 정확히 일치 | `validate_payment`만 | + +### 할당 우선순위 + +1. **동적 할당** (`assign_from_input`): 구성된 경우 Flow 상태에서 이메일 가져옴 +2. **정적 이메일** (`assign_to_email`): 구성된 이메일로 대체 +3. **배포 생성자**: 규칙이 일치하지 않으면 배포 생성자의 이메일이 사용됨 + +### 동적 할당 예제 + +Flow 상태에 `{"sales_rep_email": "alice@company.com"}`이 포함된 경우: + +```json +{ + "name": "영업 담당자에게 라우팅", + "match": { + "method_name": "review_*" + }, + "assign_from_input": "sales_rep_email" +} +``` + +요청이 자동으로 `alice@company.com`에 할당됩니다. + + +**사용 사례**: CRM, 데이터베이스 또는 이전 Flow 단계에서 담당자를 가져와 적합한 사람에게 검토를 동적으로 라우팅하세요. + + +## 자동 응답 + +시간 내에 인간이 응답하지 않으면 HITL 요청에 자동으로 응답합니다. 이를 통해 Flow가 무한정 중단되지 않도록 합니다. + +### 구성 + +| 설정 | 설명 | +|-----|------| +| 활성화됨 | 자동 응답 활성화 토글 | +| 타임아웃 (분) | 자동 응답 전 대기 시간 | +| 기본 결과 | 응답 값 (`emit` 옵션과 일치해야 함) | + + + HITL 자동 응답 구성 + + +### 사용 사례 + +- **SLA 준수**: Flow가 무한정 중단되지 않도록 보장 +- **기본 승인**: 타임아웃 후 저위험 요청 자동 승인 +- **우아한 저하**: 검토자가 없을 때 안전한 기본값으로 계속 + + +자동 응답을 신중하게 사용하세요. 기본 응답이 허용되는 중요하지 않은 검토에만 활성화하세요. + + +## 검토 프로세스 + +### 대시보드 인터페이스 + +HITL 검토 인터페이스는 검토자에게 깔끔하고 집중된 경험을 제공합니다: + +- **마크다운 렌더링**: 구문 강조가 포함된 풍부한 형식의 검토 콘텐츠 +- **컨텍스트 패널**: Flow 상태, 실행 기록 및 관련 정보 보기 +- **피드백 입력**: 결정과 함께 상세한 피드백 및 코멘트 제공 +- **빠른 작업**: 선택적 코멘트가 있는 원클릭 emit 옵션 버튼 + + + HITL 대기 중인 요청 목록 + + +### 응답 방법 + +검토자는 세 가지 채널을 통해 응답할 수 있습니다: + +| 방법 | 설명 | +|-----|------| +| **이메일 회신** | 알림 이메일에 직접 회신 | +| **대시보드** | Enterprise 대시보드 UI 사용 | +| **API/Webhook** | API를 통한 프로그래밍 방식 응답 | + +### 기록 및 감사 추적 + +모든 HITL 상호작용은 완전한 타임라인으로 추적됩니다: + +- 결정 기록 (승인/거부/수정) +- 검토자 신원 및 타임스탬프 +- 제공된 피드백 및 코멘트 +- 응답 방법 (이메일/대시보드/API) +- 응답 시간 메트릭 + +## 분석 및 모니터링 + +포괄적인 분석으로 HITL 성능을 추적합니다. + +### 성능 대시보드 + + + HITL 메트릭 대시보드 + + + + + 검토자 또는 Flow별 평균 및 중앙값 응답 시간 모니터링. + + + 팀 용량 최적화를 위한 검토 볼륨 패턴 분석. + + + 다양한 검토 유형에 대한 승인/거부 비율 보기. + + + SLA 목표 내에 완료된 검토 비율 추적. + + + +### 감사 및 규정 준수 + +규제 요구 사항을 위한 엔터프라이즈급 감사 기능: + +- 타임스탬프가 있는 완전한 결정 기록 +- 검토자 신원 확인 +- 불변 감사 로그 +- 규정 준수 보고를 위한 내보내기 기능 + +## 일반적인 사용 사례 + + + + **사용 사례**: 인간 검증이 포함된 내부 보안 설문지 자동화 + + - AI가 보안 설문지에 대한 응답 생성 + - 보안팀이 이메일로 정확성 검토 및 검증 + - 승인된 응답이 최종 제출물로 편집 + - 규정 준수를 위한 완전한 감사 추적 + + + + **사용 사례**: 법무/브랜드 검토가 필요한 마케팅 콘텐츠 + + - AI가 마케팅 카피 또는 소셜 미디어 콘텐츠 생성 + - 브랜드팀 이메일로 목소리/톤 검토를 위해 라우팅 + - 승인 시 자동 게시 + + + + **사용 사례**: 경비 보고서, 계약 조건, 예산 배분 + + - AI가 재무 요청을 사전 처리하고 분류 + - 동적 할당을 사용하여 금액 임계값에 따라 라우팅 + - 재무 규정 준수를 위한 완전한 감사 추적 유지 + + + + **사용 사례**: CRM에서 계정 담당자에게 검토 라우팅 + + - Flow가 CRM에서 계정 담당자 이메일 가져옴 + - 이메일을 Flow 상태에 저장 (예: `account_owner_email`) + - `assign_from_input`을 사용하여 적합한 사람에게 자동 라우팅 + + + + **사용 사례**: 고객 전달 전 AI 출력 검증 + + - AI가 고객 대면 콘텐츠 또는 응답 생성 + - QA팀이 이메일 알림을 통해 검토 + - 피드백 루프가 시간이 지남에 따라 AI 성능 개선 + + + +## Webhook API + +Flow가 인간 피드백을 위해 일시 중지되면, 요청 데이터를 자체 애플리케이션으로 보내도록 webhook을 구성할 수 있습니다. 이를 통해 다음이 가능합니다: + +- 커스텀 승인 UI 구축 +- 내부 도구와 통합 (Jira, ServiceNow, 커스텀 대시보드) +- 타사 시스템으로 승인 라우팅 +- 모바일 앱 알림 +- 자동화된 결정 시스템 + + + HITL Webhook 구성 + + +### Webhook 구성 + + + + **배포** → **설정** → **Human in the Loop**으로 이동 + + + **Webhooks** 구성을 클릭하여 확장 + + + webhook URL 입력 (프로덕션에서는 HTTPS 필수) + + + **구성 저장**을 클릭하여 활성화 + + + +여러 webhook을 구성할 수 있습니다. 각 활성 webhook은 모든 HITL 이벤트를 수신합니다. + +### Webhook 이벤트 + +엔드포인트는 다음 이벤트에 대해 HTTP POST 요청을 수신합니다: + +| 이벤트 유형 | 트리거 시점 | +|------------|------------| +| `new_request` | Flow가 일시 중지되고 인간 피드백을 요청할 때 | + +### Webhook 페이로드 + +모든 webhook은 다음 구조의 JSON 페이로드를 수신합니다: + +```json +{ + "event": "new_request", + "request": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "flow_id": "flow_abc123", + "method_name": "review_article", + "message": "이 기사의 게시를 검토해 주세요.", + "emit_options": ["approved", "rejected", "request_changes"], + "state": { + "article_id": 12345, + "author": "john@example.com", + "category": "technology" + }, + "metadata": {}, + "created_at": "2026-01-14T12:00:00Z" + }, + "deployment": { + "id": 456, + "name": "Content Review Flow", + "organization_id": 789 + }, + "callback_url": "https://api.crewai.com/...", + "assigned_to_email": "reviewer@company.com" +} +``` + +### 요청에 응답하기 + +피드백을 제출하려면 webhook 페이로드에 포함된 **`callback_url`로 POST**합니다. + +```http +POST {callback_url} +Content-Type: application/json + +{ + "feedback": "승인됨. 훌륭한 기사입니다!", + "source": "my_custom_app" +} +``` + +### 보안 + + +모든 webhook 요청은 HMAC-SHA256을 사용하여 암호화 서명되어 진위성을 보장하고 변조를 방지합니다. + + +#### Webhook 보안 + +- **HMAC-SHA256 서명**: 모든 webhook에 암호화 서명이 포함됨 +- **Webhook별 시크릿**: 각 webhook은 고유한 서명 시크릿을 가짐 +- **저장 시 암호화**: 서명 시크릿은 데이터베이스에서 암호화됨 +- **타임스탬프 검증**: 리플레이 공격 방지 + +#### 서명 헤더 + +각 webhook 요청에는 다음 헤더가 포함됩니다: + +| 헤더 | 설명 | +|------|------| +| `X-Signature` | HMAC-SHA256 서명: `sha256=` | +| `X-Timestamp` | 요청이 서명된 Unix 타임스탬프 | + +#### 검증 + +다음과 같이 계산하여 검증합니다: + +```python +import hmac +import hashlib + +expected = hmac.new( + signing_secret.encode(), + f"{timestamp}.{payload}".encode(), + hashlib.sha256 +).hexdigest() + +if hmac.compare_digest(expected, signature): + # 유효한 서명 +``` + +### 오류 처리 + +webhook 엔드포인트는 수신 확인을 위해 2xx 상태 코드를 반환해야 합니다: + +| 응답 | 동작 | +|------|------| +| 2xx | Webhook 성공적으로 전달됨 | +| 4xx/5xx | 실패로 기록됨, 재시도 없음 | +| 타임아웃 (30초) | 실패로 기록됨, 재시도 없음 | + +## 보안 및 RBAC + +### 대시보드 접근 + +HITL 접근은 배포 수준에서 제어됩니다: + +| 권한 | 기능 | +|-----|------| +| `manage_human_feedback` | HITL 설정 구성, 모든 요청 보기 | +| `respond_to_human_feedback` | 요청에 응답, 할당된 요청 보기 | + +### 이메일 응답 인증 + +이메일 회신의 경우: +1. reply-to 토큰이 인증된 이메일을 인코딩 +2. 발신자 이메일이 토큰의 이메일과 일치해야 함 +3. 토큰이 만료되지 않아야 함 (기본 7일) +4. 요청이 여전히 대기 중이어야 함 + +### 감사 추적 + +모든 HITL 작업이 기록됩니다: +- 요청 생성 +- 할당 변경 +- 응답 제출 (소스: 대시보드/이메일/API) +- Flow 재개 상태 + +## 문제 해결 + +### 이메일이 전송되지 않음 + +1. 구성에서 "이메일 알림"이 활성화되어 있는지 확인 +2. 라우팅 규칙이 메서드 이름과 일치하는지 확인 +3. 담당자 이메일이 유효한지 확인 +4. 라우팅 규칙이 일치하지 않는 경우 배포 생성자 대체 확인 + +### 이메일 회신이 처리되지 않음 + +1. 토큰이 만료되지 않았는지 확인 (기본 7일) +2. 발신자 이메일이 할당된 이메일과 일치하는지 확인 +3. 요청이 여전히 대기 중인지 확인 (아직 응답되지 않음) + +### Flow가 재개되지 않음 + +1. 대시보드에서 요청 상태 확인 +2. 콜백 URL에 접근 가능한지 확인 +3. 배포가 여전히 실행 중인지 확인 + +## 모범 사례 + + +**간단하게 시작**: 배포 생성자에게 이메일 알림으로 시작한 다음, 워크플로우가 성숙해지면 라우팅 규칙을 추가하세요. + + +1. **동적 할당 사용**: 유연한 라우팅을 위해 Flow 상태에서 담당자 이메일을 가져오세요. + +2. **자동 응답 구성**: 중요하지 않은 검토에 대해 Flow가 중단되지 않도록 대체를 설정하세요. + +3. **응답 시간 모니터링**: 분석을 사용하여 병목 현상을 식별하고 검토 프로세스를 최적화하세요. + +4. **검토 메시지를 명확하게 유지**: `@human_feedback` 데코레이터에 명확하고 실행 가능한 메시지를 작성하세요. + +5. **이메일 흐름 테스트**: 프로덕션에 가기 전에 테스트 요청을 보내 이메일 전달을 확인하세요. + +## 관련 리소스 + + + + `@human_feedback` 데코레이터 구현 가이드 + + + HITL 워크플로우 설정을 위한 단계별 가이드 + + + 조직을 위한 역할 기반 접근 제어 구성 + + + 실시간 이벤트 알림 설정 + + diff --git a/docs/v1.15.1/ko/enterprise/features/hallucination-guardrail.mdx b/docs/v1.15.1/ko/enterprise/features/hallucination-guardrail.mdx new file mode 100644 index 000000000..edb14db85 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/hallucination-guardrail.mdx @@ -0,0 +1,251 @@ +--- +title: 환각 방어책 +description: "CrewAI 작업에서 AI 환각을 방지하고 감지합니다" +icon: "shield-check" +mode: "wide" +--- + +## 개요 + +Hallucination Guardrail은 AI가 생성한 콘텐츠가 사실에 기반하고 환각이 포함되어 있지 않은지 검증하는 엔터프라이즈 기능입니다. 이 기능은 작업 출력물을 참조 컨텍스트와 비교 분석하여, 잠재적으로 환각이 감지되었을 때 상세한 피드백을 제공합니다. + +## 환각(Hallucinations)이란 무엇인가요? + +AI 환각은 언어 모델이 그럴듯해 보이지만 사실과 다르거나 제공된 맥락에 의해 뒷받침되지 않는 내용을 생성할 때 발생합니다. Hallucination Guardrail은 다음과 같은 방법으로 이러한 문제를 방지합니다: + +- 출력물을 참조 맥락과 비교 +- 원본 자료에 대한 충실도 평가 +- 문제 있는 콘텐츠에 대한 상세 피드백 제공 +- 검증 엄격성을 위한 사용자 정의 임계값 지원 + +## 기본 사용법 + +### 가드레일 설정하기 + +```python +from crewai.tasks.hallucination_guardrail import HallucinationGuardrail +from crewai import LLM + +# Basic usage - will use task's expected_output as context +guardrail = HallucinationGuardrail( + llm=LLM(model="gpt-4o-mini") +) + +# With explicit reference context +context_guardrail = HallucinationGuardrail( + context="AI helps with various tasks including analysis and generation.", + llm=LLM(model="gpt-4o-mini") +) +``` + +### 작업에 추가하기 + +```python +from crewai import Task + +# Create your task with the guardrail +task = Task( + description="Write a summary about AI capabilities", + expected_output="A factual summary based on the provided context", + agent=my_agent, + guardrail=guardrail # Add the guardrail to validate output +) +``` + +## 고급 구성 + +### 사용자 지정 임계값 검증 + +보다 엄격한 검증을 위해 사용자 지정 신뢰성 임계값(0-10 범위)를 설정할 수 있습니다: + +```python +# Strict guardrail requiring high faithfulness score +strict_guardrail = HallucinationGuardrail( + context="Quantum computing uses qubits that exist in superposition states.", + llm=LLM(model="gpt-4o-mini"), + threshold=8.0 # Requires score >= 8 to pass validation +) +``` + +### 도구 응답 컨텍스트 포함하기 + +작업에서 도구를 사용할 때 더 정확한 검증을 위해 도구 응답을 포함할 수 있습니다: + +```python +# Guardrail with tool response context +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" +) +``` + +## 작동 원리 + +### 검증 프로세스 + +1. **컨텍스트 분석**: 가드레일은 작업 결과를 제공된 참조 컨텍스트와 비교합니다. +2. **정확성 점수 부여**: 내부 평가자를 사용하여 정확성 점수(0-10)를 부여합니다. +3. **판단 결정**: 콘텐츠가 정확한지 또는 환각이 포함되어 있는지 결정합니다. +4. **임계값 확인**: 사용자 지정 임계값이 설정된 경우 해당 점수와 비교하여 검증합니다. +5. **피드백 생성**: 검증에 실패할 때 상세한 사유를 제공합니다. + +### 검증 논리 + +- **기본 모드**: 판정 기반 검증(FAITHFUL vs HALLUCINATED)을 사용함 +- **임계값 모드**: 신뢰성 점수가 지정된 임계값에 도달하거나 이를 초과해야 함 +- **오류 처리**: 평가 오류를 우아하게 처리하고 유익한 피드백을 제공함 + +## 가드레일 결과 + +가드레일은 검증 상태를 나타내는 구조화된 결과를 반환합니다: + +```python +# Example of guardrail result structure +{ + "valid": False, + "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context." +} +``` + +### 결과 속성 + +- **valid**: 출력이 검증을 통과했는지 여부를 나타내는 불리언 값 +- **feedback**: 검증 실패 시 상세 설명. 다음을 포함: + - 신뢰도 점수 + - 판정 분류 + - 실패의 구체적인 이유 + +## 작업 시스템과의 통합 + +### 자동 검증 + +가드레일이 태스크에 추가되면, 태스크가 완료로 표시되기 전에 출력값이 자동으로 검증됩니다: + +```python +# Task output validation flow +task_output = agent.execute_task(task) +validation_result = guardrail(task_output) + +if validation_result.valid: + # Task completes successfully + return task_output +else: + # Task fails with validation feedback + raise ValidationError(validation_result.feedback) +``` + +### 이벤트 추적 + +guardrail은 CrewAI의 이벤트 시스템과 통합되어 가시성을 제공합니다: + +- **검증 시작됨**: guardrail 평가가 시작될 때 +- **검증 완료됨**: 평가가 결과와 함께 종료될 때 +- **검증 실패**: 평가 중 기술적 오류가 발생할 때 + +## 모범 사례 + +### 컨텍스트 가이드라인 + + + + AI가 출력할 때 기반이 되어야 할 모든 관련 사실 정보를 포함하세요: + + ```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. + """ + ``` + + + + 혼란을 피하기 위해 작업과 직접적으로 관련된 정보만 포함하세요: + + ```python + # Good: Focused context + context = "The current weather in New York is 18°C with light rain." + + # Avoid: Unrelated information + context = "The weather is 18°C. The city has 8 million people. Traffic is heavy." + ``` + + + + 참고하는 컨텍스트가 최신이고 정확한 정보를 반영하는지 확인하세요. + + + +### 임계값 선택 + + + + 맞춤 임계값 없이 시작하여 기준 성능을 파악합니다. + + + + - **중요 콘텐츠**: 최대 정확도를 위해 임계값 8-10 사용 + - **일반 콘텐츠**: 균형 잡힌 검증을 위해 임계값 6-7 사용 + - **창의적 콘텐츠**: 임계값 4-5 또는 기본 판정 기반 검증 사용 + + + + 검증 결과를 추적하고, 오탐/미탐을 기반으로 임계값을 조정합니다. + + + +## 성능 고려사항 + +### 실행 시간에 미치는 영향 + +- **검증 오버헤드**: 각 가드레일마다 작업당 약 1~3초가 추가됩니다 +- **LLM 효율성**: 평가에는 효율적인 모델을 선택하세요 (예: gpt-4o-mini) + +### 비용 최적화 + +- **모델 선택**: guardrail 평가에는 더 작고 효율적인 모델을 사용하세요 +- **컨텍스트 크기**: 참조 컨텍스트는 간결하면서도 포괄적으로 유지하세요 +- **캐싱**: 반복적인 콘텐츠의 검증 결과를 캐싱하는 것을 고려하세요 + +## 문제 해결 + + + **가능한 원인:** + - 컨텍스트가 너무 제한적이거나 작업 결과와 관련이 없음 + - 임계값이 콘텐츠 유형에 비해 너무 높게 설정됨 + - 참조 컨텍스트에 오래된 정보가 포함되어 있음 + + **해결 방법:** + - 작업 요구사항에 맞게 컨텍스트를 검토하고 업데이트하세요 + - 임계값을 낮추거나 기본 판정 기반 검증을 사용하세요 + - 컨텍스트가 최신이며 정확한지 확인하세요 + + + + **가능한 원인:** + - 창의적이거나 해석적인 작업에 임계값이 너무 높음 + - 컨텍스트가 결과의 모든 유효한 측면을 포함하지 않음 + - 평가 모델이 과도하게 보수적임 + + **해결 방법:** + - 임계값을 낮추거나 기본 검증을 사용하세요 + - 폭넓은 허용 가능한 콘텐츠를 포함하도록 컨텍스트를 확장하세요 + - 다른 평가 모델로 테스트하세요 + + + + **가능한 원인:** + - 네트워크 연결 문제 + - LLM 모델 사용 불가 또는 속도 제한 + - 잘못된 형식의 작업 출력 또는 컨텍스트 + + **해결 방법:** + - 네트워크 연결 및 LLM 서비스 상태를 확인하세요 + - 일시적 오류에 대해 재시도 로직을 구현하세요 + - guardrail 평가 전에 작업 출력 형식을 검증하세요 + + + + 환각 guardrail 구성 또는 문제 해결에 도움이 필요하시면 지원팀에 문의하세요. + \ No newline at end of file diff --git a/docs/v1.15.1/ko/enterprise/features/marketplace.mdx b/docs/v1.15.1/ko/enterprise/features/marketplace.mdx new file mode 100644 index 000000000..027593172 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/marketplace.mdx @@ -0,0 +1,45 @@ +--- +title: "마켓플레이스" +description: "엔터프라이즈 크루를 위한 재사용 가능한 자산을 탐색, 설치 및 관리하세요." +icon: "store" +mode: "wide" +--- + +## 개요 + +마켓플레이스는 통합, 내부 도구 및 재사용 가능한 자산을 탐색할 수 있는 큐레이션된 공간을 제공하여 크루 개발을 가속화합니다. + + + ![마켓플레이스 개요](/images/enterprise/marketplace-overview.png) + + +## 탐색 + +- 카테고리 및 기능별로 탐색 +- 이름 또는 키워드로 검색 + +## 설치 & 활성화 + +- 승인된 자산은 원클릭 설치 지원 +- 크루별로 활성화/비활성화 가능 +- 필요한 환경 변수 및 스코프 구성 + + + ![설치 & 구성](/images/enterprise/marketplace-install.png) + + +마켓플레이스에서 `Download` 버튼을 클릭해 템플릿을 직접 내려받아 로컬에서 사용하거나 필요에 맞게 수정할 수도 있습니다. + +## 관련 문서 + + + + 에이전트가 사용할 외부 앱 연결 및 내부 도구 관리. + + + 크루 기능을 확장할 수 있도록 도구를 게시하고 설치. + + + 팀과 프로젝트 전반에서 에이전트 정의 저장, 공유 및 재사용. + + diff --git a/docs/v1.15.1/ko/enterprise/features/merged-step-card.mdx b/docs/v1.15.1/ko/enterprise/features/merged-step-card.mdx new file mode 100644 index 000000000..d45301d56 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/merged-step-card.mdx @@ -0,0 +1,82 @@ +--- +title: 단계당 하나의 카드 +description: "Studio 캔버스의 각 단계는 작업과 이를 수행하는 에이전트를 하나로 결합한 단일 카드입니다." +icon: "layer-group" +mode: "wide" +--- + +## 개요 + +Studio 캔버스에서 각 작업 단계는 **하나의 카드**로 표현됩니다. 이 카드는 이전에 별도의 노드에 있던 두 가지를 결합합니다: + +- **작업(Task)** — 무엇을 할지(이름, 설명, 예상 출력, 응답 형식). +- **에이전트(Agent)** — 누가 수행하는지(할당된 에이전트, 모델, 도구). + +에이전트는 워크플로의 독립적인 참여자가 아니라 작업의 속성, 즉 *이 작업을 어떤 에이전트가 수행하는지*를 나타냅니다. 작업과 에이전트를 하나의 카드에 두면 이 관계가 명확해지고, 자동화가 왼쪽에서 오른쪽으로 이어지는 단일 작업 단위 체인이 되어 한눈에 읽기 쉬워집니다. + + + ![캔버스의 통합 단계 카드](/images/enterprise/merged-step-card-canvas.png) + + +## 캔버스에서 + +접힌 각 카드는 다음을 표시합니다: + +- 상단의 **작업 이름과 설명**. +- **할당된 에이전트를 요약한 푸터** — 아바타, 이름, 모델, 도구. + +별도의 에이전트 노드나 에이전트 → 작업 세로 연결선이 없습니다. 각 단계는 실행 순서대로 서로 직접 연결됩니다. + +## 에디터에서 + +카드를 열어 편집합니다. 확장된 보기는 다른 화면이 아니라 동일한 카드의 상세 상태이며, 명확하게 구분된 두 개의 섹션으로 구성됩니다. + + + ![확장된 단계 에디터](/images/enterprise/merged-step-card-editor.png) + + +### 작업 — 무엇을 할지 + +가장 자주 편집하는 항목이므로 기본적으로 열려 있습니다: + +- **이름** +- **설명** +- **예상 출력** +- **응답 형식** — 다운스트림 단계(예: 라우팅)가 이 단계에서 무엇을 읽을지 정확히 제어하므로 여기에 표시됩니다. + +### 에이전트 — 누가 수행하는지 + +할당된 에이전트는 요약으로 표시됩니다 — **이름, 모델, 도구가 인라인으로** 표시됩니다. 더 깊은 구성은 두 개의 접이식 섹션 뒤에 보존됩니다: + +- **역할, 목표 및 배경 스토리** +- **에이전트 설정** — 추론, 최대 추론 시도 횟수, 위임 허용, 최대 반복 횟수, LLM 설정. + + + 에이전트의 전체 구성 — 역할, 목표, 배경 스토리, 모델, 도구, LLM 설정 및 전체 에이전트 설정 블록 — 은 **역할, 목표 및 배경 스토리**와 **에이전트 설정** 접이식 섹션 뒤에 편집 빈도에 따라 정리되어 있습니다. + + +## 에이전트 교체 vs. 편집 + +카드에서 에이전트를 다루는 방식은 두 가지로 구분되며, 각각 다른 작업을 수행합니다: + +- **교체(Swap)** 는 *어떤* 에이전트가 이 작업을 수행할지 재할당합니다. **교체** 컨트롤을 사용하여 이 프로젝트의 다른 에이전트를 선택하거나, 에이전트 저장소에서 선택하거나, 새 에이전트를 만들 수 있습니다. 이는 작업 범위로 한정됩니다. +- 에이전트 **편집** — **역할, 목표 및 배경 스토리** 또는 **에이전트 설정** 을 여는 것 — 은 에이전트 *자체*를 변경합니다. + + + ![에이전트 교체 패널](/images/enterprise/merged-step-card-swap-agent.png) + + + + **에이전트는 재사용 가능하며 공유됩니다.** 동일한 에이전트가 프로젝트 전반에서 둘 이상의 작업을 수행할 수 있습니다. 에이전트의 역할, 배경 스토리 또는 설정을 편집하면 열어 본 카드뿐만 아니라 **해당 에이전트가 사용되는 모든 곳**에서 업데이트됩니다. 변경 사항을 하나의 단계에만 적용하려면 공유 에이전트를 편집하지 말고 다른 에이전트로 **교체**하세요. + + +## 관련 항목 + + + + AI 지원과 비주얼 에디터로 자동화를 구축합니다. + + + 자동화 전반에서 에이전트를 관리하고 재사용합니다. + + diff --git a/docs/v1.15.1/ko/enterprise/features/pii-trace-redactions.mdx b/docs/v1.15.1/ko/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..a29c8f2b1 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: 트레이스용 PII 삭제 +description: "크루 및 플로우 실행 트레이스에서 민감한 데이터를 자동으로 삭제합니다" +icon: "lock" +mode: "wide" +--- + +## 개요 + +PII 삭제는 크루 및 플로우 실행 트레이스에서 개인 식별 정보(PII)를 자동으로 감지하고 마스킹하는 CrewAI AMP 기능입니다. 이를 통해 신용카드 번호, 주민등록번호, 이메일 주소, 이름과 같은 민감한 데이터가 CrewAI AMP 트레이스에 노출되지 않도록 보장합니다. 또한 조직별 데이터를 보호하기 위해 커스텀 인식기를 생성할 수 있습니다. + + + + PII 삭제는 Enterprise 플랜에서 사용 가능합니다. + 배포 버전은 1.8.0 이상이어야 합니다. + + + + + ![PII 삭제 개요](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## PII 삭제가 중요한 이유 + +프로덕션 환경에서 AI 에이전트를 실행할 때, 민감한 정보가 종종 크루를 통해 흐릅니다: + +- CRM 통합의 고객 데이터 +- 결제 처리업체의 금융 정보 +- 양식 제출의 개인 정보 +- 내부 직원 데이터 + +적절한 삭제 없이는 이 데이터가 트레이스에 나타나, GDPR, HIPAA, PCI-DSS와 같은 규정 준수가 어려워집니다. PII 삭제는 트레이스에 저장되기 전에 민감한 데이터를 자동으로 마스킹하여 이 문제를 해결합니다. + +## 작동 방식 + +1. **감지** - 알려진 PII 패턴에 대해 트레이스 이벤트 데이터를 스캔 +2. **분류** - 민감한 데이터 유형 식별 (신용카드, SSN, 이메일 등) +3. **마스킹/삭제** - 구성에 따라 민감한 데이터를 마스킹된 값으로 대체 + +``` +원본: "john.doe@company.com으로 연락하거나 555-123-4567로 전화하세요" +삭제됨: "로 연락하거나 로 전화하세요" +``` + +## PII 삭제 활성화 + + + 이 기능을 사용하려면 Enterprise 플랜이어야 하며 배포 버전이 1.8.0 이상이어야 합니다. + + + + + CrewAI AMP 대시보드에서 배포된 크루를 선택하고 배포/자동화 중 하나로 이동한 다음 **Settings** → **PII Protection**으로 이동합니다. + + + + **PII Redaction for Traces**를 토글하여 활성화합니다. 이렇게 하면 트레이스 데이터의 자동 스캔 및 삭제가 활성화됩니다. + + + 각 배포에 대해 PII 삭제를 수동으로 활성화해야 합니다. + + + + ![PII 삭제 활성화](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + 감지하고 삭제할 PII 유형을 선택합니다. 각 엔티티는 개별적으로 활성화하거나 비활성화할 수 있습니다. + + + ![엔티티 구성](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + 구성을 저장합니다. PII 삭제는 이후 모든 크루 실행에서 활성화되며, 재배포가 필요하지 않습니다. + + + +## 지원되는 엔티티 유형 + +CrewAI는 카테고리별로 구성된 다음 PII 엔티티 유형을 지원합니다. + +### 글로벌 엔티티 + +| 엔티티 | 설명 | 예시 | +|--------|------|------| +| `CREDIT_CARD` | 신용/직불 카드 번호 | "4111-1111-1111-1111" | +| `CRYPTO` | 암호화폐 지갑 주소 | "bc1qxy2kgd..." | +| `DATE_TIME` | 날짜 및 시간 | "2024년 1월 15일" | +| `EMAIL_ADDRESS` | 이메일 주소 | "john@example.com" | +| `IBAN_CODE` | 국제 은행 계좌 번호 | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | IPv4 및 IPv6 주소 | "192.168.1.1" | +| `LOCATION` | 지리적 위치 | "뉴욕시" | +| `MEDICAL_LICENSE` | 의료 면허 번호 | "MD12345" | +| `NRP` | 국적, 종교 또는 정치 그룹 | - | +| `PERSON` | 개인 이름 | "홍길동" | +| `PHONE_NUMBER` | 다양한 형식의 전화번호 | "+82 (10) 1234-5678" | +| `URL` | 웹 URL | "https://example.com" | + +### 미국 특정 엔티티 + +| 엔티티 | 설명 | 예시 | +|--------|------|------| +| `US_BANK_NUMBER` | 미국 은행 계좌 번호 | "1234567890" | +| `US_DRIVER_LICENSE` | 미국 운전면허 번호 | "D1234567" | +| `US_ITIN` | 개인 납세자 번호 | "900-70-0000" | +| `US_PASSPORT` | 미국 여권 번호 | "123456789" | +| `US_SSN` | 사회보장번호 | "123-45-6789" | + +## 삭제 작업 + +활성화된 각 엔티티에 대해 데이터가 삭제되는 방식을 구성할 수 있습니다: + +| 작업 | 설명 | 출력 예시 | +|------|------|----------| +| `mask` | 엔티티 유형 레이블로 대체 | `` | +| `redact` | 텍스트를 완전히 제거 | *(비어있음)* | + +## 커스텀 인식기 + +기본 제공 엔티티 외에도 조직별 PII 패턴을 감지하기 위한 **커스텀 인식기**를 생성할 수 있습니다. + + + ![커스텀 인식기](/images/enterprise/pii_mask_recognizer.png) + + +### 인식기 유형 + +커스텀 인식기에는 두 가지 옵션이 있습니다: + +| 유형 | 적합한 용도 | 사용 사례 예시 | +|------|------------|---------------| +| **패턴 기반 (Regex)** | 예측 가능한 형식의 구조화된 데이터 | 급여 금액, 직원 ID, 프로젝트 코드 | +| **거부 목록** | 정확한 문자열 매칭 | 회사명, 내부 코드명, 특정 용어 | + +### 커스텀 인식기 생성 + + + + 조직 **Settings** → **Organization** → **Add Recognizer**로 이동합니다. + + + + + ![인식기 구성](/images/enterprise/pii_mask_recognizer_create.png) + + + 다음 필드를 구성합니다: + - **Name**: 인식기의 설명적 이름 + - **Entity Type**: 삭제된 출력에 나타날 엔티티 레이블 (예: `EMPLOYEE_ID`, `SALARY`) + - **Type**: Regex 패턴 또는 거부 목록 중 선택 + - **Pattern/Values**: 매칭할 Regex 패턴 또는 문자열 목록 + - **Confidence Threshold**: 삭제를 트리거하는 데 필요한 최소 점수 (0.0-1.0). 높은 값 (예: 0.8)은 거짓 양성을 줄이지만 일부 매치를 놓칠 수 있습니다. 낮은 값 (예: 0.5)은 더 많은 매치를 잡지만 과도하게 삭제할 수 있습니다. 기본값은 0.8입니다. + - **Context Words** (선택사항): 근처에서 발견될 때 감지 신뢰도를 높이는 단어 + + + + 인식기를 저장합니다. 배포에서 활성화할 수 있게 됩니다. + + + +### 엔티티 유형 이해하기 + +**Entity Type**은 매칭된 콘텐츠가 삭제된 트레이스에 어떻게 나타나는지 결정합니다: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +입력: "직원 급여: $50,000" +출력: "직원 " +``` + +### 컨텍스트 단어 사용 + +컨텍스트 단어는 매칭된 패턴 근처에 특정 용어가 나타날 때 신뢰도를 높여 정확도를 향상시킵니다: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +"project" 또는 "code"가 "PRJ-1234" 근처에 나타나면, 인식기는 그것이 진정한 매치라는 확신이 높아져 거짓 양성을 줄입니다. + + +## 삭제된 트레이스 보기 + +PII 삭제가 활성화되면, 트레이스에서 민감한 데이터 대신 삭제된 값이 표시됩니다: + +``` +Task Output: "고객 이 주문 #12345를 했습니다. +연락처 이메일: , 전화: . +로 끝나는 카드로 결제가 처리되었습니다." +``` + +삭제된 값은 꺾쇠 괄호와 엔티티 유형 레이블 (예: ``)로 명확하게 표시되어, 어떤 데이터가 보호되었는지 쉽게 이해할 수 있으면서도 크루 동작을 디버그하고 모니터링할 수 있습니다. + + + +## 모범 사례 + +### 성능 고려사항 + + + + 활성화된 각 엔티티는 처리 오버헤드를 추가합니다. 데이터와 관련된 엔티티만 활성화하세요. + + + + 커스텀 인식기의 경우 거짓 양성을 줄이고 성능을 향상시키기 위해 구체적인 패턴을 사용하세요. Regex 패턴은 급여, 직원 ID, 프로젝트 코드 등 특정 패턴을 식별할 때 가장 적합합니다. 거부 목록 인식기는 회사명, 내부 코드명 등 정확한 문자열을 식별할 때 가장 적합합니다. + + + + 컨텍스트 단어는 주변 텍스트가 매칭될 때만 감지를 트리거하여 정확도를 향상시킵니다. + + + +## 문제 해결 + + + **가능한 원인:** + - 구성에서 엔티티 유형이 활성화되지 않음 + - 패턴이 데이터 형식과 매치되지 않음 + - 커스텀 인식기에 구문 오류가 있음 + + **해결책:** + - Settings → Security에서 엔티티가 활성화되어 있는지 확인 + - 샘플 데이터로 regex 패턴 테스트 + - 구성 오류에 대한 로그 확인 + + + + **가능한 원인:** + - 너무 광범위한 엔티티 유형이 활성화됨 (예: `DATE_TIME`이 모든 곳의 날짜를 잡음) + - 커스텀 인식기 패턴이 너무 일반적임 + + **해결책:** + - 거짓 양성을 유발하는 엔티티 비활성화 + - 커스텀 패턴을 더 구체적으로 만들기 + - 정확도 향상을 위해 컨텍스트 단어 추가 + + + + **가능한 원인:** + - 너무 많은 엔티티가 활성화됨 + - NLP 기반 엔티티 (`PERSON`, `LOCATION`, `NRP`)는 머신러닝 모델을 사용하므로 계산 비용이 높음 + + **해결책:** + - 실제로 필요한 엔티티만 활성화 + - 가능한 경우 패턴 기반 대안 고려 + - 대시보드에서 트레이스 처리 시간 모니터링 + + +--- + +## 실제 예시: 급여 패턴 매칭 + +이 예시는 트레이스에서 급여 정보를 감지하고 마스킹하는 커스텀 인식기를 생성하는 방법을 보여줍니다. + +### 사용 사례 + +크루가 다음과 같은 형식의 급여 정보가 포함된 직원 또는 재무 데이터를 처리합니다: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +민감한 보상 데이터를 보호하기 위해 이러한 값을 자동으로 마스킹하려고 합니다. + +### 구성 + + + ![급여 인식기 구성](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| 필드 | 값 | +|------|-----| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### Regex 패턴 분석 + +| 패턴 구성요소 | 의미 | +|--------------|------| +| `salary:` | 리터럴 텍스트 "salary:" 매치 | +| `\s*` | 0개 이상의 공백 문자 매치 | +| `\$` | 달러 기호 매치 (이스케이프) | +| `\s*` | $ 뒤의 0개 이상의 공백 문자 매치 | +| `\d{1,3}` | 1-3자리 숫자 매치 (예: "1", "50", "125") | +| `(,\d{3})*` | 쉼표로 구분된 천 단위 매치 (예: ",000", ",500,000") | +| `(\.\d{2})?` | 선택적으로 센트 매치 (예: ".00", ".50") | + +### 결과 예시 + +``` +원본: "직원 기록에 salary: $125,000.00 연봉이 표시됩니다" +삭제됨: "직원 기록에 연봉이 표시됩니다" + +원본: "기본 salary:$50,000에 보너스 가능성" +삭제됨: "기본 에 보너스 가능성" +``` + + + "salary", "compensation", "pay", "wage", "income"과 같은 컨텍스트 단어를 추가하면 이러한 용어가 매칭된 패턴 근처에 나타날 때 감지 신뢰도가 높아져 거짓 양성을 줄입니다. + + +### 배포에서 인식기 활성화 + + + 조직 수준에서 커스텀 인식기를 생성해도 배포에 자동으로 활성화되지 않습니다. 적용하려는 모든 배포에 대해 각 인식기를 수동으로 활성화해야 합니다. + + +커스텀 인식기를 생성한 후, 각 배포에서 활성화합니다: + + + + 배포/자동화로 이동하여 **Settings** → **PII Protection**을 엽니다. + + + + **Mask Recognizers** 아래에서 조직에서 정의한 인식기를 볼 수 있습니다. 활성화하려는 인식기 옆의 체크박스를 선택합니다. + + + ![커스텀 인식기 활성화](/images/enterprise/pii_mask_recognizers_options.png) + + + + + 변경 사항을 저장합니다. 인식기는 이 배포의 모든 후속 실행에서 활성화됩니다. + + + + + 커스텀 인식기가 필요한 각 배포에서 이 프로세스를 반복합니다. 이를 통해 다양한 환경 (예: 개발 vs. 프로덕션)에서 어떤 인식기가 활성화되는지 세밀하게 제어할 수 있습니다. + diff --git a/docs/v1.15.1/ko/enterprise/features/rbac.mdx b/docs/v1.15.1/ko/enterprise/features/rbac.mdx new file mode 100644 index 000000000..4c24478b7 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/rbac.mdx @@ -0,0 +1,260 @@ +--- +title: "역할 기반 접근 제어 (RBAC)" +description: "역할, 범위, 세분화된 권한으로 crews, 도구, 데이터 접근을 제어합니다." +icon: "shield" +mode: "wide" +--- + +## 개요 + +CrewAI AMP의 RBAC는 두 가지 계층을 통해 안전하고 확장 가능한 접근 관리를 제공합니다: + +1. **기능 권한** — 플랫폼 전반에서 각 역할이 수행할 수 있는 작업을 제어합니다 (관리, 읽기 또는 접근 불가) +2. **엔티티 수준 권한** — 개별 자동화, 환경 변수, LLM 연결, Git 저장소에 대한 세분화된 접근 제어 + + + CrewAI AMP RBAC 개요 + + +## 사용자와 역할 + +CrewAI 워크스페이스의 각 구성원에게는 역할이 할당되며, 이를 통해 다양한 기능에 대한 접근 범위가 결정됩니다. + +가능한 작업: + +- 사전 정의된 역할 사용 (Owner, Member) +- 특정 권한에 맞춘 커스텀 역할 생성 +- 설정 패널에서 언제든지 역할 할당 + +설정 위치: Settings → Roles + + + + CrewAI AMP에서 Settings → Roles로 이동합니다. + + + 사전 정의된 역할(Owner, Member)을 사용하거나{" "} + Create role을 클릭하여 커스텀 역할을 만듭니다. + + + 사용자를 선택하고 역할을 할당합니다. 언제든지 변경할 수 있습니다. + + + +### 사전 정의된 역할 + +| 역할 | 설명 | +| :--------- | :------------------------------------------------------------------- | +| **Owner** | 모든 기능 및 설정에 대한 전체 접근 권한. 제한할 수 없습니다. | +| **Member** | 대부분의 기능에 대한 읽기 접근, 환경 변수, LLM 연결, Studio 프로젝트에 대한 관리 접근. 조직 설정이나 기본 설정은 수정할 수 없습니다. | + +### 구성 요약 + +| 영역 | 설정 위치 | 옵션 | +| :------------ | :--------------------------------- | :-------------------------------- | +| 사용자 & 역할 | Settings → Roles | 사전 정의: Owner, Member; 커스텀 역할 | +| 자동화 가시성 | Automation → Settings → Visibility | Private; 사용자/역할 화이트리스트 | + +--- + +## 기능 권한 매트릭스 + +각 역할에는 기능 영역별 권한 수준이 있습니다. 세 가지 수준은 다음과 같습니다: + +- **Manage** — 전체 읽기/쓰기 접근 (생성, 편집, 삭제) +- **Read** — 읽기 전용 접근 +- **No access** — 기능이 숨겨지거나 접근 불가 + +| 기능 | Owner | Member (기본값) | 사용 가능한 수준 | 설명 | +| :-------------------------- | :------ | :--------------- | :------------------------- | :------------------------------------------------------------- | +| `usage_dashboards` | Manage | Read | Manage / Read / No access | 사용 메트릭 및 분석 보기 | +| `crews_dashboards` | Manage | Read | Manage / Read / No access | 배포 대시보드 보기, 자동화 세부 정보 접근 | +| `invitations` | Manage | Read | Manage / Read / No access | 조직에 새 멤버 초대 | +| `training_ui` | Manage | Read | Manage / Read / No access | 훈련/파인튜닝 인터페이스 접근 | +| `tools` | Manage | Read | Manage / Read / No access | 도구 생성 및 관리 | +| `agents` | Manage | Read | Manage / Read / No access | 에이전트 생성 및 관리 | +| `environment_variables` | Manage | Manage | Manage / No access | 환경 변수 생성 및 관리 | +| `llm_connections` | Manage | Manage | Manage / No access | LLM 제공자 연결 구성 | +| `default_settings` | Manage | No access | Manage / No access | 조직 전체 기본 설정 수정 | +| `organization_settings` | Manage | No access | Manage / No access | 결제, 플랜 및 조직 구성 관리 | +| `studio_projects` | Manage | Manage | Manage / No access | Studio에서 프로젝트 생성 및 편집 | + + + 커스텀 역할을 만들 때 대부분의 기능은 **Manage**, **Read** 또는 **No access**로 설정할 수 있습니다. 그러나 `environment_variables`, `llm_connections`, `default_settings`, `organization_settings`, `studio_projects`는 **Manage** 또는 **No access**만 지원합니다 — 이 기능들에는 읽기 전용 옵션이 없습니다. + + +--- + +## GitHub 또는 Zip에서 배포 + +가장 흔한 RBAC 질문 중 하나: _"팀원이 배포하려면 어떤 권한이 필요한가요?"_ + +### GitHub에서 배포 + +GitHub 저장소에서 자동화를 배포하려면 사용자에게 다음이 필요합니다: + +1. **`crews_dashboards`**: 최소 `Read` — 배포가 생성되는 자동화 대시보드에 접근하는 데 필요 +2. **Git 저장소 접근** (Git 저장소에 대한 엔티티 수준 RBAC가 활성화된 경우): 사용자의 역할에 엔티티 수준 권한을 통해 특정 Git 저장소에 대한 접근이 부여되어야 함 +3. **`studio_projects`: `Manage`** — 배포 전에 Studio에서 crew를 빌드하는 경우 + +### Zip에서 배포 + +Zip 파일 업로드로 자동화를 배포하려면 사용자에게 다음이 필요합니다: + +1. **`crews_dashboards`**: 최소 `Read` — 자동화 대시보드에 접근하는 데 필요 +2. **Zip 배포 활성화**: 조직이 조직 설정에서 Zip 배포를 비활성화하지 않아야 함 + +### 빠른 참조: 배포에 필요한 최소 권한 + +| 작업 | 필요한 기능 권한 | 추가 요구사항 | +| :------------------- | :----------------------------------- | :----------------------------------------------- | +| GitHub에서 배포 | `crews_dashboards: Read` | Git 저장소 엔티티 접근 (Git RBAC 활성화 시) | +| Zip에서 배포 | `crews_dashboards: Read` | 조직 수준에서 Zip 배포가 활성화되어야 함 | +| Studio에서 빌드 | `studio_projects: Manage` | — | +| LLM 키 구성 | `llm_connections: Manage` | — | +| 환경 변수 설정 | `environment_variables: Manage` | 엔티티 수준 접근 (엔티티 RBAC 활성화 시) | + +--- + +## 자동화 수준 접근 제어 (엔티티 권한) + +조직 전체 역할 외에도, CrewAI는 개별 리소스에 대한 접근을 제한하는 세분화된 엔티티 수준 권한을 지원합니다. + +### 자동화 가시성 + +자동화는 사용자 또는 역할별로 접근을 제한하는 가시성 설정을 지원합니다. 다음과 같은 경우에 유용합니다: + +- 민감하거나 실험적인 자동화를 비공개로 유지 +- 대규모 팀이나 외부 협업자의 가시성 관리 +- 격리된 컨텍스트에서 자동화 테스트 + +배포를 비공개로 구성할 수 있으며, 이 경우 화이트리스트에 포함된 사용자와 역할만 상호작용할 수 있습니다. + +설정 위치: Automation → Settings → Visibility 탭 + + + + Automation → Settings → Visibility로 이동합니다. + + + 접근을 제한하려면 Private를 선택합니다. 조직 Owner는 항상 + 접근 권한을 유지합니다. + + + 보기, 실행, 로그/메트릭/설정 접근이 허용된 특정 사용자와 역할을 + 추가합니다. + + + 변경 사항을 저장한 후, 화이트리스트에 없는 사용자가 자동화를 보거나 실행할 수 + 없는지 확인합니다. + + + +### Private 가시성: 접근 결과 + +| 동작 | Owner | 화이트리스트 사용자/역할 | 비포함 | +| :--------------------- | :---- | :----------------------- | :----- | +| 자동화 보기 | ✓ | ✓ | ✗ | +| 자동화/API 실행 | ✓ | ✓ | ✗ | +| 로그/메트릭/설정 접근 | ✓ | ✓ | ✗ | + + + 조직 Owner는 항상 접근 권한이 있습니다. Private 모드에서는 화이트리스트에 포함된 + 사용자/역할만 보기, 실행, 로그/메트릭/설정에 접근할 수 있습니다. + + + + CrewAI AMP 자동화 가시성 설정 + + +### 배포 권한 유형 + +특정 자동화에 엔티티 수준 접근을 부여할 때 다음 권한 유형을 할당할 수 있습니다: + +| 권한 | 허용 범위 | +| :------------------- | :-------------------------------------------------- | +| `run` | 자동화 실행 및 API 사용 | +| `traces` | 실행 트레이스 및 로그 보기 | +| `manage_settings` | 자동화 편집, 재배포, 롤백 또는 삭제 | +| `human_in_the_loop` | HITL(human-in-the-loop) 요청에 응답 | +| `full_access` | 위의 모든 권한 | + +### 기타 리소스에 대한 엔티티 수준 RBAC + +엔티티 수준 RBAC가 활성화되면 다음 리소스에 대한 접근도 사용자 또는 역할별로 제어할 수 있습니다: + +| 리소스 | 제어 방식 | 설명 | +| :----------------- | :---------------------------------- | :------------------------------------------------------------ | +| 환경 변수 | 엔티티 RBAC 기능 플래그 | 특정 환경 변수를 보거나 관리할 수 있는 역할/사용자 제한 | +| LLM 연결 | 엔티티 RBAC 기능 플래그 | 특정 LLM 제공자 구성에 대한 접근 제한 | +| Git 저장소 | Git 저장소 RBAC 조직 설정 | 특정 연결된 저장소에 접근할 수 있는 역할/사용자 제한 | + +--- + +## 일반적인 역할 패턴 + +CrewAI는 Owner와 Member 역할을 기본 제공하지만, 대부분의 팀은 커스텀 역할을 만들어 활용합니다. 일반적인 패턴은 다음과 같습니다: + +### Developer 역할 + +자동화를 빌드하고 배포하지만 조직 설정을 관리하지 않는 팀원을 위한 역할입니다. + +| 기능 | 권한 | +| :-------------------------- | :---------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Manage | +| `invitations` | Read | +| `training_ui` | Read | +| `tools` | Manage | +| `agents` | Manage | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | Manage | + +### Viewer / Stakeholder 역할 + +자동화를 모니터링하고 결과를 확인해야 하는 비기술 이해관계자를 위한 역할입니다. + +| 기능 | 권한 | +| :-------------------------- | :---------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Read | +| `invitations` | No access | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | No access | +| `llm_connections` | No access | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | No access | + +### Ops / Platform Admin 역할 + +인프라 설정을 관리하지만 에이전트를 빌드하지 않을 수 있는 플랫폼 운영자를 위한 역할입니다. + +| 기능 | 권한 | +| :-------------------------- | :---------- | +| `usage_dashboards` | Manage | +| `crews_dashboards` | Manage | +| `invitations` | Manage | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | Manage | +| `organization_settings` | Read | +| `studio_projects` | No access | + +--- + + + RBAC 관련 질문은 지원팀에 문의해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/aws-workload-identity.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/aws-workload-identity.mdx new file mode 100644 index 000000000..e10384222 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/aws-workload-identity.mdx @@ -0,0 +1,321 @@ +--- +title: AWS Workload Identity (OIDC Federation) +description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Workload Identity를 통해 AWS Secrets Manager를 구성합니다 +sidebarTitle: Workload Identity 사용 +icon: "id-badge" +--- + +## 개요 + +이 가이드는 **Workload Identity Federation**을 사용하여 AWS Secrets Manager를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, STS를 통해 이를 AWS 자격 증명과 교환하여 시크릿을 읽습니다 — 장기 AWS 액세스 키를 어디에도 저장하지 않습니다. + + +**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하고 로테이션 전파에 신경 쓰지 않는다면, 더 간단한 [AWS — 정적 키 / AssumeRole](/ko/enterprise/features/secrets-manager/aws) 가이드를 참조하세요. + + +### 런타임 동작 방식 + +1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다. +2. 워커가 JWT를 제시하여 아래에서 설정한 IAM 역할에 대해 `sts:AssumeRoleWithWebIdentity`를 호출합니다. +3. AWS STS가 CrewAI Platform의 공개 OIDC 발급자에 대해 JWT를 검증한 다음(따라서 플랫폼 설치가 AWS에서 접근 가능해야 함), 단기 AWS 자격 증명을 반환합니다. +4. 워커가 해당 자격 증명을 사용하여 `secretsmanager:GetSecretValue`를 호출합니다. +5. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다. + +OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다. + +## 사전 준비 사항 + + +시작하기 전에 다음을 준비하세요: + +- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다. +- IAM OIDC 공급자, IAM 역할, IAM 정책을 생성할 권한이 있는 AWS 계정. +- 시크릿이 위치한(또는 위치할) AWS 리전(예: `us-east-1`). +- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. +- **CrewAI 조직 UUID.** CrewAI Platform의 조직 설정 페이지에서 찾을 수 있습니다 — 3단계의 신뢰 정책이 IAM 역할을 이 특정 조직에 바인딩합니다. +- **CrewAI Platform 설치가 AWS에서 HTTPS를 통해 접근 가능해야 합니다.** AWS STS가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지(또는 AWS가 VPC 피어링/동등한 방법을 통해 네트워크에 도달할 수 있는지) 확인하세요. + + +## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기 + +CrewAI Platform 설치는 `https:///.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 해당 문서의 `issuer` 필드는 AWS가 신뢰할 수 있는 OIDC 공급자로 등록할 URL입니다. + +브라우저에서 URL을 엽니다(``를 실제 호스트 이름으로 교체, 예: `app.crewai.com`): + +``` +https:///.well-known/openid-configuration +``` + +다음을 포함하는 JSON이 보일 것입니다: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다. + + +URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요. + + +## 2단계 — CrewAI Platform을 IAM OIDC ID 공급자로 등록 + +[IAM → Identity providers 콘솔](https://console.aws.amazon.com/iam/home#/identity_providers)을 열고 **Add provider**를 클릭합니다. + +- **Provider type:** OpenID Connect. +- **Provider URL:** 1단계의 `issuer` 값(예: `https://app.crewai.com`). +- **Audience:** `sts.amazonaws.com` + +**Add provider**를 클릭합니다. + +또는 CLI를 통해: + +```bash +aws iam create-open-id-connect-provider \ + --url "https://" \ + --client-id-list "sts.amazonaws.com" \ + --thumbprint-list "$(echo | openssl s_client -servername -connect :443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')" +``` + +출력에서 **OpenIDConnectProviderArn**(또는 콘솔에서 공급자의 ARN)을 복사합니다. 3단계에서 사용합니다. + + +AWS는 실제로 STS WebIdentity 호출의 thumbprint를 검증하지 않습니다 — 검증 시점에 항상 JWKS를 다시 가져옵니다 — 그러나 API에서 해당 필드가 존재해야 합니다. + + +{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */} +{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */} + +## 3단계 — IAM 역할 생성 + +`trust-policy.json`으로 저장하고, ``, ``(발급자 호스트로 `https://` 또는 `http://` **없음**, 예: `app.crewai.com`), ``(사전 준비 사항에서)를 교체합니다: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":aud": "sts.amazonaws.com", + ":sub": "organization:" + } + } + } + ] +} +``` + +역할을 생성합니다: + +```bash +aws iam create-role \ + --role-name crewai-secrets-reader \ + --assume-role-policy-document file://trust-policy.json +``` + +출력에서 **Role Arn**을 복사합니다 — 이것이 `aws_role_arn`입니다. 6단계에서 CrewAI Platform에 붙여 넣습니다. + + +두 조건은 신뢰를 정확하게 범위 지정합니다: `aud`는 AWS STS audience를 가진 토큰으로만 가정을 제한하고, `sub`는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다. CrewAI Platform은 항상 AWS workload identity 토큰에 두 클레임을 모두 설정합니다. + + +{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */} + +## 4단계 — Secrets Manager + KMS 액세스용 IAM 정책 생성 및 연결 + +`secrets-policy.json`으로 저장하고 자리 표시자를 계정 ID, 리전, 시크릿 이름 접두사, 그리고 해당 시크릿을 암호화하는 KMS 키 ARN으로 교체합니다: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerListForUI", + "Effect": "Allow", + "Action": "secretsmanager:ListSecrets", + "Resource": "*" + }, + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:GetSecretValue" + ], + "Resource": "arn:aws:secretsmanager:::secret:-*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:Decrypt" + ], + "Resource": "arn:aws:kms:::key/" + } + ] +} +``` + +`SecretsManagerListForUI`는 환경 변수 폼의 **Secret Name 자동 완성**과 자격 증명의 **Test Connection** 버튼을 지원합니다. `secretsmanager:ListSecrets`는 `Resource: "*"`만 허용합니다 — IAM 계층에서 계정 범위로 제한됩니다. + +CLI(인라인 정책, 가장 간단함) 또는 콘솔 UI를 사용하여 역할에 정책을 연결합니다. 많은 역할에서 동일한 권한을 재사용하는 환경의 경우 재사용 가능한 명명된 정책을 위해 **Managed policy** 탭을 사용하세요. + + + + ```bash + aws iam put-role-policy \ + --role-name crewai-secrets-reader \ + --policy-name SecretsManagerRead \ + --policy-document file://secrets-policy.json + ``` + + 이는 정책을 **인라인**으로 역할에 연결합니다. 인라인 정책은 역할에 연결되어 있으며 다른 역할에서 재사용할 수 없습니다. + + + + ```bash + POLICY_ARN=$(aws iam create-policy \ + --policy-name CrewAISecretsReader \ + --policy-document file://secrets-policy.json \ + --query 'Policy.Arn' --output text) + + aws iam attach-role-policy \ + --role-name crewai-secrets-reader \ + --policy-arn "$POLICY_ARN" + ``` + + 관리형 정책은 여러 역할에 연결할 수 있는 독립형 IAM 리소스입니다. + + + + 1. [IAM → Roles 콘솔](https://console.aws.amazon.com/iam/home#/roles)을 열고 **crewai-secrets-reader**를 선택합니다. + 2. **Permissions** 탭에서 **Add permissions** → **Create inline policy**를 클릭합니다. + 3. **JSON** 편집기로 전환하고 `secrets-policy.json`의 내용을 붙여 넣습니다. + 4. **Next**를 클릭하고 정책 이름(예: `SecretsManagerRead`)을 지정한 다음 **Create policy**를 클릭합니다. + + 대신 재사용 가능한 관리형 정책을 만들려면 **IAM → Policies → Create policy**를 사용한 다음, 역할의 **Permissions** 탭에서 역할에 연결합니다. + + {/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */} + + + +## 5단계 — AWS에 최소 하나의 시크릿 생성 + +테스트할 시크릿이 아직 없다면 지금 하나 만드세요: + +```bash +aws secretsmanager create-secret \ + --region \ + --name crewai-test-keyword \ + --secret-string "hello from aws" +``` + +또는 [AWS Secrets Manager 콘솔](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**을 통해 만듭니다. + +{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */} + +## 6단계 — CrewAI Platform에 Workload Identity 구성 추가 + +CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다. + +{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */} +{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */} + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `aws-prod`). +- **Cloud Provider:** `AWS`. +- **AWS Role ARN:** 3단계의 **Role Arn**. +- **AWS Region:** 시크릿이 위치한 리전(예: `us-east-1`). +- (선택) AWS 기반 시크릿 자격 증명을 생성할 때 이 WI 구성을 기본으로 선택하려면 **Set as default for AWS**를 체크합니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */} +{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */} + +## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가 + +**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다. + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `aws-prod-wi`). +- **Provider:** `AWS Secrets Manager`. +- **Authentication Method:** `Workload Identity`(정적 키 / AssumeRole 대신). +- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다(예: `aws-prod`). +- (선택) **Set as default credential for this provider**를 체크합니다. + +Workload Identity 아래에서는 폼이 **AWS Region**만 요청합니다 — 정적 자격 증명 필드(Access Key ID, Secret Access Key, Role ARN, External ID)는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. 역할 ARN은 연결된 WI 구성에서 가져옵니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */} + +## 8단계 — 연결 테스트 + +자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, `sts:AssumeRoleWithWebIdentity`를 통해 AWS STS와 교환한 다음, 결과로 받은 자격 증명이 가정된 역할에 대해 `sts:GetCallerIdentity`를 호출할 수 있는지 확인합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다. + +성공적인 Test Connection은 신뢰 정책, OIDC 공급자 등록, audience 조건이 모두 올바르게 연결되었음을 증명합니다. 시크릿별 IAM이 올바르다는 것을 증명하지는 **않습니다** — 특정 시크릿 ARN에 대한 `secretsmanager:GetSecretValue`는 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요. + +## 9단계 — 환경 변수에서 시크릿 참조 + +이제 다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. + +WI 기반과 정적 키 기반 환경 변수의 유일한 차이는 시크릿이 **언제** 읽히는지입니다: + +- **WI 기반:** 모든 자동화 kickoff에서 시크릿 값을 새로 읽습니다. +- **정적 키 기반:** 배포 시점에 시크릿 값을 읽고 배포 이미지에 박힙니다. + +## 10단계 — 로테이션 확인 + +배포가 실행 중인 상태에서 AWS의 시크릿을 로테이션합니다: + +```bash +aws secretsmanager update-secret \ + --region \ + --secret-id crewai-test-keyword \ + --secret-string "rotated value" +``` + +새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음. + +로그에서 확인하려면(워커에 액세스할 수 있는 경우) 다음을 찾으세요: + +``` +Workload identity config '' (aws): N secret(s) resolved +``` + +이 줄은 모든 kickoff에 나타나며 AWS에 대한 새로운 `GetSecretValue` 호출을 의미합니다. + +## 문제 해결 + +| 증상 | 가능한 원인 | +|---|---| +| Test Connection이 핸드셰이크 오류로 실패함 | `sts:AssumeRoleWithWebIdentity` 호출이 거부되었습니다. 신뢰 정책의 federated principal ARN이 `oidc-provider/`(호스트로 `https://` 또는 `http://` **없음**, 후행 슬래시 없음)를 참조하는지, audience 조건이 정확히 `sts.amazonaws.com`인지, `sub` 조건이 CrewAI 조직 UUID와 일치하는지, 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 AWS에서 접근 가능한지 확인하세요. | +| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | AWS STS가 CrewAI Platform 호스트에 도달하여 JWKS를 가져올 수 없습니다. 호스트가 AWS에서 인터넷에 접근 가능한지, OIDC 디스커버리 URL이 200을 반환하는지, JWKS 엔드포인트가 접근 가능한지 확인하세요. | +| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | 신뢰 정책 불일치. 3단계를 다시 확인하세요: federated principal ARN은 `oidc-provider/`(호스트로 `https://` 또는 `http://` **없음**, 후행 슬래시 없음)를 포함해야 하고, audience 조건은 정확히 `sts.amazonaws.com`이어야 하며, `sub` 조건은 `organization:`와 같아야 합니다. | +| Secret Name 자동 완성에 `AccessDenied: secretsmanager:ListSecrets` 표시 | 역할에 `Resource: "*"`를 가진 `secretsmanager:ListSecrets`가 없습니다. 4단계의 `SecretsManagerListForUI` 문을 추가하세요. | +| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 리소스 범위 IAM이 없습니다. 해당 시크릿의 ARN과 KMS 키에 대한 역할의 `secretsmanager:GetSecretValue` 및 `kms:Decrypt` 권한을 감사하세요. | +| `RegionDisabledException` / 시크릿을 찾을 수 없음 | Workload Identity Config의 리전이 시크릿이 위치한 곳과 일치하지 않습니다. 6단계를 다시 확인하세요. | +| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. | + +### 참고 링크 + +- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) +- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html) +- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) + +## 다음 단계 + +- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage) +- 다중 클라우드의 경우 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity) 및 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)도 참조하세요. diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/aws.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/aws.mdx new file mode 100644 index 000000000..195708680 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/aws.mdx @@ -0,0 +1,295 @@ +--- +title: AWS Secrets Manager (정적 자격 증명) +description: 정적 액세스 키 또는 AssumeRole을 사용하여 AWS Secrets Manager를 CrewAI Platform의 시크릿 공급자로 구성합니다 +sidebarTitle: 정적 자격 증명 사용 +icon: "key" +--- + +## 개요 + +이 가이드는 **정적 자격 증명**(액세스 키, 선택적으로 AssumeRole 포함)을 사용하여 AWS Secrets Manager를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 AWS 계정에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다. + + +이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원하면(재배포 없음), [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)을 참조하세요. + + + +이 가이드는 AWS 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요. + + +## 사전 준비 사항 + + +시작하기 전에 다음을 준비하세요: + +- IAM 사용자, 고객 관리형 정책, 그리고 (선택적으로) IAM 역할을 생성할 수 있는 권한이 있는 AWS 계정. +- 시크릿이 위치한(또는 위치할) AWS 리전(예: `us-east-1`). +- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. + + +## 인증 방법 선택 + +CrewAI Platform은 AWS Secrets Manager에 인증하는 두 가지 방법을 지원합니다. 시작하기 전에 하나를 선택하세요 — 아래 단계는 선택한 방법에 따라 다릅니다. + +| 방법 | 사용 시기 | 트레이드오프 | +|---|---|---| +| **정적 액세스 키** | 시작 단계, 단일 계정 배포 | 가장 간단한 설정; 액세스 키를 수동으로 로테이션해야 함 | +| **AssumeRole** | 교차 계정, 프로덕션 강화 | 단기 자격 증명; External ID 지원; 추가 IAM 역할 필요 | + +이 가이드의 나머지 부분은 단계 3-5에서 탭을 사용하므로 선택한 경로에 맞는 단계를 따를 수 있습니다. + +## 1단계 — IAM 사용자 생성 + +[IAM 콘솔](https://console.aws.amazon.com/iam/)을 열고 **Users**로 이동한 다음 **Create user**를 클릭합니다. + +- 권장 이름: `crewai-secrets-reader`. +- **Provide user access to the AWS Management Console**은 선택하지 마세요 — 이 주체는 사람이 아닌 CrewAI Platform이 프로그래밍 방식으로 사용합니다. +- **Next**를 클릭합니다. + +**Set permissions** 페이지에서 기본 선택을 유지합니다. 정책은 3단계에서 연결합니다. + +**Next**를 클릭하고 검토한 다음 **Create user**를 클릭합니다. + +자세한 내용은 AWS 문서를 참조하세요: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). + +{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */} + +## 2단계 — IAM 정책 생성 + +CrewAI Platform은 AWS Secrets Manager에 대한 읽기 전용 액세스와 KMS를 통해 시크릿을 복호화할 수 있는 권한이 필요합니다. 다음 JSON으로 고객 관리형 정책을 생성하세요. + +IAM 콘솔에서 **Policies**로 이동한 다음 **Create policy**를 클릭합니다. + +**JSON** 탭을 선택하고 내용을 다음으로 바꿉니다: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:ListSecrets", + "secretsmanager:GetSecretValue", + "secretsmanager:DescribeSecret" + ], + "Resource": "*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:DescribeKey", + "kms:Decrypt" + ], + "Resource": "*" + } + ] +} +``` + +**Next**를 클릭한 다음 **Review and create** 페이지에서: + +- **Policy name:** `CrewAISecretsManagerRead` +- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform` + +**Create policy**를 클릭합니다. + + +위 정책은 간소화를 위해 `Resource`에 `*`를 부여합니다. 프로덕션에서는 `Resource`를 CrewAI Platform이 액세스해야 하는 특정 시크릿의 ARN으로 좁히고, `kms:Decrypt`를 해당 시크릿을 암호화하는 특정 KMS 키 ARN으로 좁히세요. [AWS의 최소 권한 지침](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)을 참조하세요. + + +{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */} +{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */} + +## 3단계 — 정책 연결 + + + + 1. IAM 콘솔에서 **Users**로 이동하여 1단계에서 만든 사용자를 클릭합니다. + 2. **Permissions** 탭에서 **Add permissions** → **Attach policies directly**를 클릭합니다. + 3. `CrewAISecretsManagerRead`를 검색하고 선택한 다음 **Next**를 클릭합니다. + 4. **Add permissions**를 클릭합니다. + + {/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */} + + + + AssumeRole의 경우 정책은 (사용자가 아닌) 별도의 IAM **역할**에 연결됩니다. 1단계의 사용자는 해당 역할에 대해 `sts:AssumeRole`을 호출할 권한만 필요합니다. + + **역할 생성:** + + 1. IAM 콘솔에서 **Roles**로 이동하여 **Create role**을 클릭합니다. + 2. **Trusted entity type:** AWS account. **This account**를 선택합니다(또는 교차 계정 설정의 경우 **Another AWS account**를 선택하고 1단계 IAM 사용자를 호스팅하는 AWS 계정 ID를 입력합니다). + 3. (권장) **Require external ID**를 체크하고 직접 생성한 값을 입력합니다 — 이는 5단계에서 CrewAI Platform에 붙여 넣을 공유 시크릿입니다. + 4. **Next**를 클릭합니다. + 5. `CrewAISecretsManagerRead` 정책을 연결합니다. + 6. **Next**를 클릭하고 역할 이름을 `CrewAISecretsManagerRole`로 지정한 다음 **Create role**을 클릭합니다. + + **IAM 사용자가 역할을 맡을 수 있도록 허용:** + + 1. 방금 만든 역할을 열고 **ARN**을 복사합니다. + 2. IAM 콘솔에서 **Users**로 이동하여 1단계 사용자를 클릭한 다음 **Permissions** 탭에서 **Add permissions** → **Create inline policy**를 클릭합니다. + 3. **JSON** 탭에서 다음을 붙여 넣습니다(`ROLE_ARN_FROM_ABOVE`를 교체): + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "ROLE_ARN_FROM_ABOVE" + } + ] + } + ``` + + 4. 정책 이름을 `CrewAIAssumeSecretsRole`로 지정하고 **Create policy**를 클릭합니다. + + {/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */} + {/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */} + + + +## 4단계 — 자격 증명 가져오기 + + + + 1. IAM 콘솔에서 1단계 사용자를 엽니다. + 2. **Security credentials** 탭을 클릭합니다. + 3. **Access keys** 아래에서 **Create access key**를 클릭합니다. + 4. 사용 사례로 **Application running outside AWS**(또는 **Other**)를 선택합니다. **Next**를 클릭합니다. + 5. (선택) 설명 태그를 추가합니다. **Create access key**를 클릭합니다. + 6. **Show**를 클릭하여 시크릿 액세스 키를 표시한 다음 **Access key ID**와 **Secret access key**를 모두 복사하거나 **Download .csv file**을 클릭합니다. + + + 시크릿 액세스 키는 한 번만 표시됩니다. 복사하지 않고 이 페이지를 닫으면 키를 삭제하고 새 키를 만들어야 합니다. + + + 자세한 내용은 AWS 문서를 참조하세요: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). + + {/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */} + {/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */} + + + + AssumeRole을 사용하더라도 CrewAI Platform은 여전히 IAM 사용자에 대한 액세스 키가 필요합니다 — `sts:AssumeRole` 호출을 수행하기 위한 호출 신원으로 해당 키를 사용합니다. + + 1. 위의 **정적 액세스 키** 탭에서 설명한 대로 사용자에 대한 액세스 키를 생성합니다. + 2. 3단계에서 만든 역할을 열고 다음을 복사합니다: + - **Role ARN** (역할 요약에서). + - 구성한 **External ID** (있는 경우) — 3단계에서 직접 설정했으므로 가지고 있는지 확인하세요. + + {/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */} + + + +## 5단계 — CrewAI Platform에 자격 증명 추가 + +CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} +{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */} + + + + 폼을 작성합니다: + + - **Name:** 설명적인 이름(예: `aws-prod`). + - **Provider:** `AWS Secrets Manager`. + - **Region:** 시크릿이 위치한 AWS 리전(예: `us-east-1`). 읽으려는 시크릿의 리전과 일치해야 합니다. + - **Access Key ID:** 4단계의 값. + - **Secret Access Key:** 4단계의 값. + - (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 AWS 시크릿을 참조하는 환경 변수에서 사용됩니다. + + **Role ARN**과 **External ID**는 비워둡니다. + + **Create**를 클릭합니다. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */} + + + + 폼을 작성합니다: + + - **Name:** 설명적인 이름(예: `aws-prod-assumerole`). + - **Provider:** `AWS Secrets Manager`. + - **Region:** 시크릿이 위치한 AWS 리전. + - **Access Key ID:** 4단계의 IAM 사용자 액세스 키(STS 호출에 사용). + - **Secret Access Key:** 4단계의 IAM 사용자 시크릿 액세스 키. + - **Role ARN:** 4단계에서 복사한 Role ARN. + - **External ID:** 역할의 신뢰 정책에 설정한 External ID(없으면 생략). + - (선택) **Set as default credential for this provider**를 체크합니다. + + **Create**를 클릭합니다. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */} + + + + +**두 모드의 런타임 동작:** + +- **정적 액세스 키**만 사용하는 경우, CrewAI Platform은 제공된 키를 사용하여 AWS Secrets Manager를 직접 호출합니다. +- **Role ARN**이 설정된 경우, CrewAI Platform은 먼저 제공된 액세스 키(구성된 경우 External ID 포함)로 `sts:AssumeRole`을 호출한 다음, STS가 반환한 단기 자격 증명을 사용하여 시크릿을 읽습니다. + + +{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */} + +## 6단계 — AWS에 최소 하나의 시크릿 생성 + +AWS Secrets Manager에 시크릿이 아직 없다면, 7단계에서 연결을 확인할 수 있도록 지금 하나 만드세요. + +[AWS Secrets Manager 콘솔](https://console.aws.amazon.com/secretsmanager/)에서 **Store a new secret**을 클릭합니다. + +- **Secret type:** **Other type of secret**을 선택합니다. +- **Key/value pairs** — 다음 중 하나: + - 하나 이상의 키/값 쌍 입력(구조화된 시크릿에 권장), 또는 + - 단일 문자열 값을 위해 **Plaintext** 탭 사용. +- **Encryption key:** 특정 KMS 키 요구 사항이 없으면 `aws/secretsmanager`(AWS 관리형 키)를 사용합니다. + +**Next**를 클릭한 다음 입력합니다: + +- **Secret name:** 고유한 이름(예: `crewai/openai-api-key`). +- **Description (optional):** 시크릿 용도에 대한 간단한 메모. + +로테이션 및 검토 단계를 통해 **Next**를 클릭한 다음 **Store**를 클릭합니다. + + +**JSON 키 참조 구문.** 여러 키/값 쌍(JSON 객체)이 있는 시크릿을 저장하는 경우, CrewAI Platform은 환경 변수 참조에서 `secret-name#json_key` 구문을 사용하여 특정 필드를 추출할 수 있습니다. 예를 들어, `{"username": "...", "password": "..."}`가 있는 `database-credentials`라는 시크릿은 `database-credentials#password`로 참조할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. + + +자세한 내용은 AWS 문서를 참조하세요: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + +{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */} +{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */} + +## 7단계 — 연결 테스트 + +CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다. + +성공 토스트는 CrewAI Platform이 AWS에 인증하고 계정의 시크릿을 읽을 수 있음을 확인합니다. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */} + +테스트가 실패하면 가장 일반적인 원인을 확인하세요: + +| 증상 | 가능한 원인 | +|---|---| +| `secretsmanager:ListSecrets`에서 `AccessDenied` | 정책이 연결되지 않았거나 잘못된 사용자입니다. 3단계를 다시 확인하세요. | +| `kms:Decrypt`에서 `AccessDenied` | `KMSDecrypt` 문이 누락되었거나, 시크릿이 `Resource: "*"`로 다루지 않는 고객 관리형 KMS 키를 사용합니다. | +| `InvalidClientTokenId` / `SignatureDoesNotMatch` | 잘못된 액세스 키 ID 또는 시크릿 액세스 키입니다. 4단계와 5단계를 다시 확인하세요. | +| `RegionDisabledException` / 시크릿을 찾을 수 없음 | 자격 증명의 **Region**이 시크릿이 실제로 위치한 곳과 일치하지 않습니다. | +| `sts:AssumeRole`에서 `AccessDenied` (AssumeRole만 해당) | IAM 사용자에 인라인 `sts:AssumeRole` 정책이 없거나, 역할의 신뢰 정책이 이 주체를 허용하지 않거나, External ID가 일치하지 않습니다. | +| IAM 사용자 생성 직후 테스트는 통과하지만 다음 번에는 실패함 | IAM 자격 증명이 전역적으로 전파되는 데 1-2분 정도 걸릴 수 있습니다. 다시 시도하세요. | + +## 다음 단계 + +이제 AWS가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요: + +- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다. +- CrewAI Platform 환경 변수에서 AWS 시크릿을 참조합니다. + +재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)으로 전환하세요 — 동일한 시크릿 저장소, 정적 자격 증명 없음, kickoff마다 시크릿을 가져옵니다. diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/azure-workload-identity.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/azure-workload-identity.mdx new file mode 100644 index 000000000..d1dd63a73 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/azure-workload-identity.mdx @@ -0,0 +1,275 @@ +--- +title: Azure Workload Identity Federation +description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Microsoft Entra Workload Identity Federation을 통해 Azure Key Vault를 구성합니다 +sidebarTitle: Workload Identity 사용 +icon: "id-badge" +--- + +## 개요 + +이 가이드는 **Microsoft Entra Workload Identity Federation**을 사용하여 Azure Key Vault를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, Microsoft identity platform을 통해 이를 Entra 액세스 토큰과 교환하여 시크릿을 읽습니다 — 클라이언트 시크릿을 어디에도 저장하지 않습니다. + + +**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하다면 더 간단한 [Azure Key Vault — 클라이언트 시크릿](/ko/enterprise/features/secrets-manager/azure) 가이드를 참조하세요. + + +### 런타임 동작 방식 + +1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다. +2. 워커가 `https://login.microsoftonline.com//oauth2/v2.0/token`에서 JWT를 `client_assertion`(`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`)으로 Microsoft Entra에 제시하며, JWT의 발급자 + 주체와 일치하는 **Federated Identity Credential**을 가진 App Registration을 참조합니다. +3. Entra가 플랫폼의 OIDC 디스커버리 문서와 JWKS에 대해 JWT를 검증한 다음, `https://vault.azure.net/.default`로 범위가 지정된 단기 액세스 토큰을 반환합니다. +4. 워커가 Azure Key Vault를 호출하여 시크릿을 읽습니다. +5. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다. + +OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다. + +## 사전 준비 사항 + + +시작하기 전에 다음을 준비하세요: + +- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다. +- 관리할 수 있는 Azure 구독과 Microsoft Entra 테넌트. +- App Registration을 생성하고 Federated Identity Credential을 추가할 테넌트 권한. +- 권한 부여에 **Azure RBAC**를 사용하는 Key Vault(레거시 액세스 정책 모델이 아님). +- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. +- **CrewAI Platform 설치가 Microsoft Entra에서 HTTPS를 통해 접근 가능해야 합니다.** Entra가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지 확인하세요. + + +## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기 + +CrewAI Platform 설치는 `https:///.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 여기의 `issuer` 필드는 Microsoft Entra가 신뢰할 수 있는 federation 발급자로 등록할 URL입니다. + +브라우저에서 URL을 엽니다: + +``` +https:///.well-known/openid-configuration +``` + +다음을 포함하는 JSON이 보일 것입니다: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다. + + +URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요. + + +## 2단계 — App Registration 생성 + +[Microsoft Entra 포털](https://entra.microsoft.com)에서 **App registrations**로 이동하여 **New registration**을 클릭합니다. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- **Redirect URI**는 비워둡니다. + +**Register**를 클릭합니다. App의 개요 블레이드에서 **Application (client) ID**와 **Directory (tenant) ID**를 기록하세요 — 6단계에서 사용합니다. + +{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */} + +## 3단계 — Federated Identity Credential 추가 + +Federated Identity Credential은 Microsoft Entra에 다음을 알려줍니다: *이 발급자가 발급한 JWT를 신뢰하라, 이 주체로, 이 App Registration에 대한 client assertion으로 제시될 때.* + +App Registration에서 **Certificates & secrets** → **Federated credentials** → **Add credential**로 이동합니다. + +- **Federated credential scenario:** `Other issuer`. +- **Issuer:** 1단계의 CrewAI Platform 발급자 URL(예: `https://`). +- **Subject identifier:** `organization:` — 정확히 JWT의 `sub` 클레임 값. CrewAI Platform의 조직 설정에서 조직 UUID를 찾으세요. 이는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다. +- **Name:** 설명적인 레이블(예: `crewai-org-prod`). +- **Audience:** `api://AzureADTokenExchange`. 이는 Microsoft Entra가 federated 자격 증명에 요구하는 고정 audience이며 CrewAI Platform이 JWT의 `aud` 클레임에 설정하는 값입니다. + +**Add**를 클릭합니다. + + +**조직별 격리.** 주체 식별자(`organization:`)는 federated 자격 증명을 특정 CrewAI 조직의 토큰으로 제한합니다. 여러 CrewAI 조직이 하나의 App Registration을 공유해야 하는 경우, 조직당 하나의 Federated Identity Credential을 추가하세요(각각 조직의 UUID 사용). + + +자세한 내용은 Microsoft 문서를 참조하세요: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust). + +{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */} + +## 4단계 — App Registration에 Key Vault 액세스 부여 + +대상 볼트에서 App Registration에 **Key Vault Secrets User**를 부여합니다 — 정적 자격 증명 경로에서 사용할 것과 동일한 역할입니다. 볼트 전체(더 간단함) 또는 시크릿별(최소 권한)을 사용하세요. + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + 볼트 전체 범위는 CrewAI Platform의 환경 변수 폼에 있는 **Secret Name 자동 완성**이 의존하는 `secrets/list` 권한을 부여합니다. 자동 완성이 작동하길 원한다면 이 탭을 선택하세요. + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */} + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + 시크릿별 바인딩은 CrewAI Platform의 환경 변수 폼에 있는 **Secret Name 자동 완성**을 비활성화합니다(자동 완성은 볼트 범위에서만 가능한 `secrets/list`가 필요합니다). 대신 전체 시크릿 이름을 입력하세요. + + {/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */} + + + + **볼트 전체** 할당: + + 1. Azure 포털에서 Key Vault를 엽니다. + 2. **Access control (IAM)** → **Add** → **Add role assignment**를 클릭합니다. + 3. 역할 **Key Vault Secrets User**를 선택하고 → **Next**를 클릭합니다. + 4. **Select members**를 클릭하고 App Registration `crewai-secrets-reader`를 검색한 다음 **Select**를 클릭합니다. + 5. **Review + assign**을 클릭합니다. + + **시크릿별** 할당의 경우 동일한 흐름을 사용하지만 **Objects** → **Secrets** → 시크릿 선택 → 자체 **Access control (IAM)** 패널에서 시작합니다. 시크릿별 바인딩은 자동 완성을 비활성화합니다(위의 시크릿별 탭 참조). + + + +## 5단계 — Key Vault에 최소 하나의 시크릿 생성 + +테스트할 시크릿이 아직 없다면 Azure CLI를 통해 하나 만듭니다: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + +또는 Azure 포털을 통해: + +1. Key Vault를 열고 **Objects** → **Secrets**로 이동합니다. +2. **Generate/Import**를 클릭합니다. +3. **Upload options:** `Manual`. **Name:** 시크릿 이름(예: `openai-api-key`). **Secret value:** 값을 붙여 넣습니다. +4. **Create**를 클릭합니다. + + +**시크릿 이름 규칙.** Azure Key Vault 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 밑줄을 하이픈으로 자동으로 변환하므로(예: `db_password`는 `db-password`로 전송됨), 밑줄 스타일 환경 변수 이름을 유지할 수 있습니다 — 그러나 Key Vault의 기본 시크릿은 하이픈을 사용해야 합니다. + + +## 6단계 — CrewAI Platform에 Workload Identity 구성 추가 + +CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다. + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `azure-prod`). +- **Cloud Provider:** `Azure`. +- **Tenant ID:** 2단계의 Microsoft Entra **Directory (tenant) ID**. +- **Client ID:** 2단계의 App Registration **Application (client) ID**. +- (선택) Azure 기반 시크릿 자격 증명을 생성할 때 이것이 기본 WI 구성으로 선택되길 원한다면 **Set as default for Azure**를 체크합니다. + +**Audience**는 `api://AzureADTokenExchange`로 고정되어 있습니다 — Microsoft Entra는 federated 자격 증명에 대해 이 정확한 audience를 요구하므로 폼에 Audience 필드가 표시되지 않습니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */} +{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */} + +## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가 + +**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다. + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `azure-prod-wi`). +- **Provider:** `Azure Key Vault`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다. +- **Key Vault URL:** 볼트의 DNS 호스트 이름(예: `https://my-vault.vault.azure.net`). +- (선택) **Set as default credential for this provider**를 체크합니다. + +Workload Identity 아래에서는 폼이 **Key Vault URL**만 요청합니다 — 정적 자격 증명 필드(Tenant ID, Client ID, Client Secret)는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. tenant + client는 연결된 WI 구성에서 가져옵니다. + +**Create**를 클릭합니다. + + +**하나의 App Registration, 여러 볼트.** Key Vault URL은 WI 구성이 아닌 자격 증명에 있습니다. 따라서 하나의 App Registration(과 하나의 WI 구성)이 여러 Key Vault를 서비스할 수 있습니다 — 동일한 WI 구성에 연결된 볼트당 하나의 Secret Provider Credential을 만드세요. + + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */} + +## 8단계 — 연결 테스트 + +자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, federated `client_assertion`으로 Microsoft Entra에 제시한 다음, Entra가 볼트 범위 액세스 토큰을 반환하는지 확인합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다. + +성공적인 Test Connection은 Federated Identity Credential의 발급자, 주체, audience가 모두 일치하고 App Registration이 접근 가능함을 증명합니다. 시크릿별 Key Vault RBAC가 올바르다는 것을 증명하지는 **않습니다** — 특정 시크릿에 대한 `getSecret`은 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요. + +## 9단계 — 환경 변수에서 시크릿 참조 + +다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. + +## 10단계 — 로테이션 확인 + +배포가 실행 중인 상태에서 Key Vault의 시크릿을 로테이션합니다: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "rotated value" +``` + +새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음. + +워커 로그에서 확인하려면 다음을 찾으세요: + +``` +Workload identity config '' (azure): N secret(s) resolved +``` + +이 줄은 모든 kickoff에 나타나며 Azure Key Vault에 대한 새로운 `getSecret` 호출을 의미합니다. + +엔드 투 엔드 fingerprint 기반 검증은 [로테이션 엔드 투 엔드 검증](/ko/enterprise/features/secrets-manager/verify-rotation)을 참조하세요. + +## 문제 해결 + +| 증상 | 가능한 원인 | +|---|---| +| Test Connection이 핸드셰이크 오류로 실패함 | federated `client_assertion`이 Microsoft Entra에 의해 거부되었습니다. Federated Identity Credential의 **Issuer**가 플랫폼의 `issuer` 값과 정확히 일치하는지, **Subject**가 `organization:`(JWT의 `sub` 클레임과 일치)인지, **Audience**가 `api://AzureADTokenExchange`인지, 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 Entra에서 접근 가능한지 확인하세요. | +| `AADSTS70021: No matching federated identity record found for presented assertion` | Federated Identity Credential의 **Issuer** + **Subject** + **Audience**가 모두 JWT와 정확히 일치하지 않습니다. 3단계를 다시 확인하세요: 주체는 `organization:`(JWT의 `sub` 클레임과 일치)여야 하고, audience는 `api://AzureADTokenExchange`여야 합니다. | +| `AADSTS700024: Client assertion is not within its valid time range` | CrewAI Platform 호스트의 시계가 실제 시간과 크게 다릅니다. 호스트의 NTP를 확인하세요. | +| `AADSTS50013: Assertion failed signature validation` | Microsoft Entra가 JWT의 서명을 확인할 수 없습니다. `https:///oauth2/jwks`가 공용 인터넷에서 접근 가능하고 유효한 JWKS를 제공하는지 확인하세요. | +| Secret Name 자동 완성에 `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` 표시 | App Registration의 **Key Vault Secrets User** 역할이 단일 시크릿으로 범위 지정되어 있습니다. `list` 데이터 플레인 액션이 허용되도록 볼트 범위에서 역할을 부여하세요. 4단계를 참조하세요. | +| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 시크릿별 Key Vault RBAC가 없습니다. 해당 특정 시크릿에 대한 **Key Vault Secrets User**를 감사하거나(또는 역할 할당을 볼트 범위로 확장). | +| `Forbidden — request was not authorized` (레거시 액세스 정책을 사용하는 볼트) | 볼트가 Azure RBAC로 전환되지 않았습니다. 볼트의 **Access configuration**에서 권한 모델을 **Azure role-based access control**로 설정하고 4단계의 역할을 다시 부여하세요. | +| `azure_vault_url is required for Azure secret resolution` (워커 로그) | Secret Provider Credential에 **Key Vault URL**이 없습니다. 7단계를 다시 확인하세요. | +| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. | + +### 참고 링크 + +- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) +- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust) +- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) + +## 다음 단계 + +- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage) +- 다중 클라우드의 경우 AWS 동등 설정은 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity)에, GCP 동등 설정은 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)에 있습니다. + +## 스크린샷 참조 + +위의 자리 표시자는 다음에 매핑됩니다: + +- `01-register-app.png` — `crewai-secrets-reader`로 채워진 Azure 포털 "Register an application" 폼. +- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, **Other issuer**, 플랫폼 발급자 URL, 주체 `organization:`, audience `api://AzureADTokenExchange`. +- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, **Key Vault Secrets User**와 App Registration이 선택됨. +- `04-per-secret-rbac.png` — 동일한 폼이지만 단일 시크릿의 IAM 범위에서(대체 최소 권한 경로). +- `05-amp-add-wi-config-azure.png` — Cloud Provider = Azure, Tenant ID, Client ID가 채워진 CrewAI Platform "Add Workload Identity Config" 폼. +- `06-amp-wi-list-with-azure.png` — 생성 후 Workload Identity 목록 페이지, AWS, GCP 및 새 Azure 구성 행 표시. +- `07-amp-add-credential-azure-wi.png` — Provider = Azure Key Vault, Auth = Workload Identity, WI 구성 선택, Key Vault URL이 채워진 "Add Secret Provider Credential" 폼. diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/azure.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/azure.mdx new file mode 100644 index 000000000..64bc8d0ec --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/azure.mdx @@ -0,0 +1,196 @@ +--- +title: Azure Key Vault +description: Azure Key Vault를 CrewAI Platform의 시크릿 공급자로 처음부터 끝까지 구성합니다 +sidebarTitle: 정적 자격 증명 사용 +icon: "key" +--- + +## 개요 + +이 가이드는 **클라이언트 시크릿이 있는 Microsoft Entra App Registration**을 사용하여 Azure Key Vault를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 Azure Key Vault에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다. + + +이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원한다면 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)을 참조하세요. + + + +이 가이드는 Azure 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요. + + +## 사전 준비 사항 + + +시작하기 전에 다음을 준비하세요: + +- Microsoft Entra에서 App Registration을 생성하고 Key Vault 리소스에 역할 할당을 부여할 권한이 있는 Azure 구독. +- 권한 부여에 **Azure RBAC**를 사용하는 Key Vault(레거시 액세스 정책 모델이 아님). 볼트가 여전히 액세스 정책을 사용하는 경우, 볼트의 **Access configuration** 블레이드에서 RBAC로 전환하세요. +- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. + + +## 1단계 — App Registration 생성 + +App Registration은 CrewAI Platform이 인증할 Microsoft Entra 측 ID입니다. + +[Microsoft Entra 포털](https://entra.microsoft.com)에서 **App registrations**로 이동하여 **New registration**을 클릭합니다. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- **Redirect URI**는 비워둡니다. + +**Register**를 클릭합니다. App의 개요 블레이드에서 **Application (client) ID**와 **Directory (tenant) ID**를 기록하세요 — 4단계에서 둘 다 CrewAI Platform에 붙여 넣습니다. + +자세한 내용은 Microsoft 문서를 참조하세요: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). + +{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */} + +## 2단계 — 클라이언트 시크릿 생성 + +App Registration에서 **Certificates & secrets** → **Client secrets** → **New client secret**으로 이동합니다. + +- **Description:** `crewai-platform` +- **Expires:** 로테이션 정책과 일치하는 기간을 선택합니다(Microsoft은 이를 24개월로 제한). + +**Add**를 클릭합니다. **Value** 열을 즉시 복사하세요 — 페이지를 떠난 후에는 다시 표시할 수 없습니다. + + +클라이언트 시크릿은 장기 정적 자격 증명입니다. 값을 안전하게 저장하고(패스워드 매니저나 자체 시크릿 저장소에) 만료 전에 로테이션하세요. 정적 자격 증명을 완전히 제거하려면 대신 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)을 사용하세요. + + +{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */} + +## 3단계 — App Registration에 Key Vault 액세스 부여 + +CrewAI Platform은 Key Vault의 시크릿에 대한 읽기 액세스가 필요합니다. 두 가지 범위 중 하나를 사용하세요 — 간소화를 위한 **볼트 전체** 또는 최소 권한을 위한 **시크릿별**. + + + + [Key Vault 콘솔](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults)에서 대상 볼트를 열고 **Access control (IAM)** → **Add** → **Add role assignment**로 이동합니다. + + - **Role:** **Key Vault Secrets User** + - **Assign access to:** User, group, or service principal + - **Members:** App Registration(`crewai-secrets-reader`)을 검색하고 선택합니다. + + **Review + assign**을 클릭합니다. + + 또는 Azure CLI를 통해: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */} + + + + 개별 시크릿 수준에서 역할을 부여합니다. CrewAI Platform이 액세스해야 하는 각 시크릿에 대해 반복합니다: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */} + + + + +**Key Vault Secrets User** 역할은 시크릿 값 읽기를 허용하지만 볼트의 모든 시크릿을 나열하는 것은 허용하지 않습니다. CrewAI Platform의 시크릿 이름 자동 완성도 `list`를 호출합니다 — 해당 권한은 볼트 범위에서는 역할에 포함되지만, 시크릿별 범위에서는 **포함되지 않습니다**. 시크릿별 바인딩의 경우 자동 완성이 시크릿을 제안하지 않으므로 대신 전체 시크릿 이름을 입력하세요. + + +## 4단계 — CrewAI Platform에 자격 증명 추가 + +CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `azure-prod`). +- **Provider:** `Azure Key Vault`. +- **Key Vault URL:** 볼트의 DNS 호스트 이름(예: `https://my-vault.vault.azure.net`). +- **Tenant ID:** 1단계의 Microsoft Entra **Directory (tenant) ID**. +- **Client ID:** 1단계의 App Registration **Application (client) ID**. +- **Client Secret:** 2단계에서 복사한 **Value**. +- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 Azure 시크릿을 참조하는 환경 변수에서 사용됩니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */} + +## 5단계 — Azure Key Vault에 최소 하나의 시크릿 생성 + +Key Vault에 시크릿이 아직 없다면, 6단계에서 연결을 확인할 수 있도록 지금 하나 만드세요. + +Key Vault 콘솔에서 **Objects** → **Secrets** → **Generate/Import**로 이동합니다. + +- **Upload options:** `Manual` +- **Name:** 예: `openai-api-key` +- **Secret value:** 시크릿 값을 붙여 넣습니다 +- 나머지는 기본값으로 둡니다. + +**Create**를 클릭합니다. + +또는 Azure CLI를 통해: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + + +**시크릿 이름 규칙.** Azure Key Vault 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 밑줄을 하이픈으로 자동으로 변환하므로(예: `db_password`는 `db-password`로 전송됨), 밑줄 스타일 환경 변수 이름을 유지할 수 있습니다 — 그러나 Key Vault의 기본 시크릿은 하이픈을 사용해야 합니다. + + + +**JSON 키 참조 구문.** Key Vault는 시크릿 값을 불투명한 문자열로 취급합니다. 시크릿 값이 JSON 객체인 경우, CrewAI Platform은 `secret-name#json_key` 구문(예: `database-credentials#password`)을 사용하여 단일 필드를 추출할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. + + +자세한 내용은 Microsoft 문서를 참조하세요: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli). + +{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */} + +## 6단계 — 연결 테스트 + +CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다. + +성공 토스트는 CrewAI Platform이 Microsoft Entra에 인증하고 볼트의 시크릿을 읽을 수 있음을 확인합니다. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */} + +테스트가 실패하면 가장 일반적인 원인을 확인하세요: + +| 증상 | 가능한 원인 | +|---|---| +| `AADSTS7000215: Invalid client secret provided` | 붙여 넣은 **Client Secret**이 잘못되었거나 만료되었습니다. 시크릿을 다시 생성하고(2단계) 자격 증명을 업데이트하세요. | +| `AADSTS700016: Application not found in the directory` | **Tenant ID** 또는 **Client ID**가 App Registration과 일치하지 않습니다. 4단계를 다시 확인하세요. | +| `Forbidden — caller does not have permission` | App Registration에 볼트(또는 시크릿별) **Key Vault Secrets User** 역할이 없습니다. 3단계를 다시 확인하세요. | +| `Vault not found` / DNS 오류 | **Key Vault URL**이 잘못되었거나, 볼트에 공용 액세스를 차단하는 프라이빗 엔드포인트가 있습니다. 호스트가 `curl https://.vault.azure.net/secrets?api-version=7.4`에 응답하는지 확인하세요. | +| `Forbidden — request was not authorized` (레거시 액세스 정책을 사용하는 볼트) | 볼트가 Azure RBAC로 전환되지 않았습니다. 볼트의 **Access configuration**에서 권한 모델을 **Azure role-based access control**로 설정하고 3단계의 역할을 다시 부여하세요. | + +## 다음 단계 + +이제 Azure Key Vault가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요: + +- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다. +- CrewAI Platform 환경 변수에서 Azure 시크릿을 참조합니다. + +재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)으로 전환하세요 — 동일한 볼트, 로테이션할 클라이언트 시크릿 없음, kickoff마다 시크릿을 가져옵니다. + +## 스크린샷 참조 + +위의 자리 표시자는 다음에 매핑됩니다: + +- `01-register-app.png` — `crewai-secrets-reader`로 채워진 Azure 포털 "Register an application" 폼. +- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, 새로 생성된 시크릿 행이 표시됨(마스킹되기 전 Value 열 강조). +- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, **Key Vault Secrets User**가 선택되고 App Registration이 멤버로 선택됨. +- `04-per-secret-rbac.png` — 동일한 패널이지만 단일 시크릿 리소스로 범위 지정됨(대체 최소 권한 경로). +- `05-amp-add-credential-form-azure.png` — CrewAI Platform "Add Secret Provider Credential" 폼: Provider = Azure Key Vault, 다섯 필드 모두 채워짐. +- `06-create-secret.png` — `openai-api-key`와 붙여 넣은 값이 있는 Azure Key Vault "Create a secret" 패널. +- `07-test-connection-success.png` — 자격 증명에서 **Test Connection**을 클릭한 후의 CrewAI Platform 성공 토스트 / 행 상태. diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/gcp-workload-identity.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/gcp-workload-identity.mdx new file mode 100644 index 000000000..c6a1b9262 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/gcp-workload-identity.mdx @@ -0,0 +1,273 @@ +--- +title: GCP Workload Identity Federation +description: 로테이션 인식, 자격 증명 없는 시크릿 액세스를 위해 Workload Identity Federation을 통해 Google Cloud Secret Manager를 구성합니다 +sidebarTitle: Workload Identity 사용 +icon: "id-badge" +--- + +## 개요 + +이 가이드는 **Workload Identity Federation**을 사용하여 Google Cloud Secret Manager를 시크릿 공급자로 구성합니다: CrewAI Platform이 단기 OIDC 토큰을 발급하고, Security Token Service를 통해 이를 Google Cloud 자격 증명과 교환하여 시크릿을 읽습니다 — 장기 서비스 계정 키를 어디에도 저장하지 않습니다. + + +**이 경로를 선택하는 이유:** 시크릿은 자동화 실행 시점에 해석되므로, **로테이션된 값이 재배포 없이 다음 kickoff에 전파됩니다**. 정적 자격 증명만 필요하다면 더 간단한 [GCP — 서비스 계정 키](/ko/enterprise/features/secrets-manager/gcp) 가이드를 참조하세요. + + +### 런타임 동작 방식 + +1. 배포 워커가 CrewAI Platform에서 새 OIDC JWT를 요청합니다. +2. 워커가 아래에서 설정한 Workload Identity Pool Provider를 참조하여 [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest)를 통해 JWT를 federated Google 자격 증명과 교환합니다. +3. 워커가 federated 자격 증명을 직접 사용하여 시크릿을 읽기 위해 `secretmanager.googleapis.com:accessSecretVersion`을 호출합니다(federated 주체가 `roles/secretmanager.secretAccessor`를 보유함 — 4단계 참조). +4. 가져온 값이 해당 자동화 kickoff의 환경 변수 값으로 주입됩니다. + +OIDC 주체 토큰은 매 kickoff마다 재발급을 피하기 위해 약 1시간 동안 캐시됩니다. 시크릿 값은 OIDC 캐시 상태와 관계없이 매 kickoff마다 새로 가져오며, 이것이 이 경로를 로테이션 인식으로 만드는 요소입니다. + +## 사전 준비 사항 + + +시작하기 전에 다음을 준비하세요: + +- 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 포함되어야 합니다. +- **Secret Manager API**, **Security Token Service API**, **IAM Credentials API**가 활성화된 Google Cloud 프로젝트. 콘솔에서 또는 다음을 통해 활성화하세요: + + ```bash + gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \ + --project= + ``` + +- Workload Identity Pool, IAM 역할, 서비스 계정, (필요한 경우) 시크릿을 생성할 프로젝트 권한. +- 사용자가 `workload_identity_configs: manage` 및 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. +- **CrewAI Platform 설치가 Google Cloud에서 HTTPS를 통해 접근 가능해야 합니다.** GCP STS가 토큰 검증 중 OIDC 디스커버리 문서와 JWKS를 가져올 수 있어야 합니다. 플랫폼 관리자에게 호스트가 인터넷에서 접근 가능한지 확인하세요. + + +## 1단계 — CrewAI Platform OIDC 발급자 URL 찾기 + +CrewAI Platform 설치는 `https:///.well-known/openid-configuration`에서 OpenID Connect 디스커버리 문서를 게시합니다. 여기의 `issuer` 필드는 Google이 신뢰할 수 있는 OIDC 공급자로 등록할 URL입니다. + +브라우저에서 URL을 엽니다: + +``` +https:///.well-known/openid-configuration +``` + +다음을 포함하는 JSON이 보일 것입니다: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +`issuer`의 정확한 값을 기록하세요 — 3단계에서 사용합니다. + + +URL이 404 또는 503을 반환하면 플랫폼 관리자에게 문의하세요. OIDC 발급자는 설치 시점에 개인 서명 키가 구성되어 있어야 합니다. `OIDC_PRIVATE_KEY` 및 `OIDC_ISSUER` 구성에 대한 내용은 플랫폼 설치 가이드를 참조하세요. + + +## 2단계 — Workload Identity Pool 생성 + +Workload Identity Pool은 신뢰할 수 있는 외부 ID를 위한 Google Cloud 측 컨테이너입니다. 이 풀 내부에 CrewAI Platform을 공급자로 등록합니다. + +```bash +gcloud iam workload-identity-pools create crewai-pool \ + --project= \ + --location=global \ + --display-name="CrewAI Platform" +``` + +또는 [Workload Identity Pools 콘솔](https://console.cloud.google.com/iam-admin/workload-identity-pools)에서 **Create Pool**을 클릭합니다. + +{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */} + +## 3단계 — CrewAI Platform을 풀에 OIDC 공급자로 추가 + +```bash +gcloud iam workload-identity-pools providers create-oidc crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --display-name="CrewAI Platform OIDC" \ + --issuer-uri="https://" \ + --attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \ + --attribute-condition="assertion.organization_id != ''" +``` + +`--attribute-mapping`은 JWT 클레임을 Google 속성으로 매핑하는 방법을 Google에 알려줍니다: +- `google.subject`는 주체 식별자입니다 — JWT의 `sub` 클레임에 매핑하며, CrewAI Platform은 이를 `organization:`로 설정합니다. +- `attribute.organization`은 사용자 정의 속성입니다 — JWT의 `organization_id` 클레임에 매핑하여 나중에 IAM 바인딩에서 참조할 수 있습니다. + +`--attribute-condition`은 `organization_id` 클레임이 없는 토큰을 거부하는 심층 방어 검사입니다. + +**Provider 리소스 이름**을 가져옵니다(audience 및 IAM 바인딩에 필요): + +```bash +gcloud iam workload-identity-pools providers describe crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --format="value(name)" +``` + +출력은 다음과 같습니다: + +``` +projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider +``` + +이것이 6단계에서 CrewAI Platform의 **Workload Identity Provider** 값입니다. CrewAI Platform은 토큰을 발급할 때 OIDC audience를 `//iam.googleapis.com/`으로 자동으로 계산합니다. + +{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */} + +## 4단계 — Federated 주체에 Secret Manager 액세스 부여 + +프로젝트 범위에서 두 Secret Manager 역할을 모두 federated 주체에 바인딩합니다 — 한 역할은 환경 변수 폼의 Secret Name 자동 완성을 활성화하고, 다른 역할은 자동화 kickoff 시점에 시크릿 값을 읽을 수 있게 합니다. 기능이 처음부터 끝까지 작동하려면 두 역할 모두 필요합니다. + +```bash +PRINCIPAL_SET="principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools/crewai-pool/attribute.organization/" + +# Secret Name 자동 완성에 필요 (secretmanager.secrets.list 호출) +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.viewer" + +# kickoff 시점에 시크릿 값을 읽는 데 필요 +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" +``` + +``를 숫자 프로젝트 번호(`gcloud projects describe --format='value(projectNumber)'`)로, ``를 시크릿을 읽을 수 있도록 허용할 CrewAI Platform 조직의 UUID로 교체합니다. 조직 UUID는 플랫폼 UI의 조직 설정 페이지나 API를 통해 찾을 수 있습니다. 이는 federation을 특정 CrewAI 조직으로 범위 지정합니다 — 해당 조직의 자동화를 위해 발급된 토큰만 수락됩니다. + +또는 Google Cloud 콘솔을 통해: + +1. 프로젝트의 **IAM & Admin** → **IAM**을 엽니다. +2. **GRANT ACCESS**를 클릭합니다. +3. **New principals:** 전체 `principalSet://...attribute.organization/` 문자열을 붙여 넣습니다. +4. 역할 **Secret Manager Viewer** (`roles/secretmanager.viewer`)를 할당합니다. +5. **SAVE**를 클릭합니다. +6. **GRANT ACCESS**를 다시 클릭하고 **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`) 역할로 반복합니다. + + +**조직별 격리.** `principalSet://...attribute.organization/` 패턴은 특정 조직의 토큰에 대한 액세스를 제한합니다. 하나의 Google Cloud 프로젝트를 여러 CrewAI 조직이 공유하는 경우, 각 조직에 대해 올바른 UUID로 두 바인딩을 모두 반복하거나 — 격리가 필요하지 않으면 덜 제한적인 attribute condition을 사용하세요. + + + +**시크릿별로 `secretAccessor` 범위 지정 (선택 사항).** `roles/secretmanager.secretAccessor`를 프로젝트 전체로 부여하고 싶지 않으면, 위의 두 번째 바인딩을 생략하고 대신 시크릿별로 바인딩합니다: + +```bash +gcloud secrets add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" \ + --project= +``` + +어느 쪽이든 `roles/secretmanager.viewer`는 프로젝트 범위로 유지하세요 — `secretmanager.secrets.list`(자동 완성이 의존)는 시크릿별로 부여할 수 없습니다. + + +## 5단계 — GCP에 최소 하나의 시크릿 생성 + +테스트할 시크릿이 아직 없다면 `gcloud` CLI를 통해 하나 만듭니다: + +```bash +echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \ + --data-file=- \ + --project= \ + --replication-policy=automatic +``` + +또는 [Secret Manager 콘솔](https://console.cloud.google.com/security/secret-manager)을 통해: + +1. GCP 프로젝트에서 **Secret Manager**를 엽니다. +2. **+ CREATE SECRET**을 클릭합니다. +3. **Name:** `crewai-test-keyword`. **Secret value:** 값을 붙여 넣습니다. +4. **CREATE SECRET**을 클릭합니다. + +## 6단계 — CrewAI Platform에 Workload Identity 구성 추가 + +CrewAI Platform에서 **Settings** → **Workload Identity**로 이동하여 **Add Workload Identity Config**를 클릭합니다. + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `gcp-prod`). +- **Cloud Provider:** `GCP`. +- **Workload Identity Provider:** 3단계의 provider 리소스 이름(예: `projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`). +- (선택) GCP 기반 시크릿 자격 증명을 생성할 때 이것이 기본 WI 구성으로 선택되길 원한다면 **Default Configuration**을 토글합니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */} +{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */} + +## 7단계 — WI 구성에 바인딩된 Secret Provider Credential 추가 + +**Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다. + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `gcp-prod-wi`). +- **Provider:** `Google Cloud Secret Manager`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** 6단계에서 만든 구성을 선택합니다. +- **Project ID:** GCP 프로젝트 ID(시크릿을 소유한 동일한 프로젝트). +- (선택) **Set as default credential for this provider**를 체크합니다. + +Workload Identity 아래에서는 폼이 **Project ID**만 요청합니다 — **Service Account JSON** 필드는 이 경로에 적용되지 않으므로 의도적으로 숨겨집니다. federated ID는 연결된 WI 구성에서 가져옵니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */} + +## 8단계 — 연결 테스트 + +자격 증명을 저장한 후 **Test Connection**을 클릭합니다. Workload Identity 자격 증명의 경우 OIDC 핸드셰이크를 검증합니다: CrewAI Platform이 JWT를 발급하고, Security Token Service를 통해 federated Google 액세스 토큰과 교환합니다. 녹색 결과는 federation 바인딩이 정상임을 의미합니다. + +성공적인 Test Connection은 Workload Identity Pool, OIDC 공급자, attribute mapping, attribute condition이 모두 올바르게 연결되었음을 증명합니다. Secret Manager IAM이 올바르다는 것을 증명하지는 **않습니다** — `secretmanager.secrets.list`와 `secretmanager.versions.access`는 Secret Name 자동 완성이 로드되거나 환경 변수가 kickoff에 해석될 때 별도로 수행됩니다. 핸드셰이크 실패 모드는 [문제 해결](#troubleshooting)을 참조하세요. + +## 9단계 — 환경 변수에서 시크릿 참조 + +다른 Secrets Manager 기반 환경 변수와 마찬가지로 자동화에서 시크릿을 참조합니다. 폼 필드와 동작은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. + +## 10단계 — 로테이션 확인 + +배포가 실행 중인 상태에서 새 버전을 추가하여 GCP의 시크릿을 로테이션합니다(Secret Manager는 기본적으로 항상 최신 활성화 버전을 읽음): + +```bash +echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \ + --data-file=- \ + --project= +``` + +새 자동화 kickoff를 트리거합니다. kickoff의 환경은 `"rotated value"`를 볼 것입니다 — 재배포, 워커 재시작, TTL 대기 없음. + +워커 로그에서 확인하려면 다음을 찾으세요: + +``` +Workload identity config '' (gcp): N secret(s) resolved +``` + +이 줄은 모든 kickoff에 나타나며 GCP에 대한 새로운 `accessSecretVersion` 호출을 의미합니다. + +## 문제 해결 + +| 증상 | 가능한 원인 | +|---|---| +| Test Connection이 핸드셰이크 오류로 실패함 | STS 토큰 교환이 거부되었습니다. Workload Identity Pool이 존재하는지, OIDC provider의 발급자가 플랫폼의 `issuer` 값과 일치하는지, attribute condition이 JWT의 클레임을 수락하는지 확인하세요. 플랫폼의 OIDC 디스커버리 URL이 공용 인터넷을 통해 GCP에서 접근 가능한지 확인하세요. | +| `Could not refresh access token: invalid_target` | audience 클레임이 Workload Identity Provider의 예상 audience와 일치하지 않습니다. CrewAI Platform이 audience를 자동으로 설정합니다. 사용자 정의한 경우 `//iam.googleapis.com/`과 일치하는지 확인하세요. | +| `Failed to fetch JWKS from issuer` | GCP STS가 CrewAI Platform 호스트에 도달할 수 없습니다. 호스트가 인터넷에서 접근 가능하고 `/.well-known/openid-configuration`이 200을 반환하는지 확인하세요. | +| `Attribute condition rejected token` | OIDC provider의 attribute condition(3단계)이 `organization_id`를 요구합니다. CrewAI Platform은 항상 이 클레임을 설정하므로 보통 잘못 구성된 풀/공급자를 의미합니다. provider의 attribute condition을 다시 확인하세요. | +| Secret Name 자동 완성에 `PERMISSION_DENIED: secretmanager.secrets.list` 표시 | federated 주체에 프로젝트 범위의 `roles/secretmanager.viewer`가 없습니다. `secretmanager.secrets.list` 권한은 프로젝트 범위에서만 가능하며 시크릿별로 부여할 수 없습니다. 4단계를 참조하세요. | +| Test Connection은 통과하지만 kickoff가 시크릿을 해석하지 못함 | WI 바인딩은 정상이지만 실패한 시크릿에 `secretmanager.versions.access`가 없습니다. `roles/secretmanager.secretAccessor`(프로젝트 범위 또는 4단계에서 그렇게 범위 지정한 경우 시크릿별)를 감사하세요. | +| 다음 kickoff에서 로테이션된 값이 적용되지 않음 | 자동화의 환경 변수가 Workload Identity 기반 자격 증명을 참조하는지 확인하세요(정적 키 자격 증명이 아님). 정적 경로는 배포 이미지에 값을 박습니다. | + +### 참고 링크 + +- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation) +- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) +- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control) + +## 다음 단계 + +- [환경 변수에서 시크릿 사용 및 권한 관리](/ko/enterprise/features/secrets-manager/usage) +- 다중 클라우드의 경우 [AWS Workload Identity (OIDC Federation)](/ko/enterprise/features/secrets-manager/aws-workload-identity) 및 [Azure Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity)도 참조하세요. diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/gcp.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/gcp.mdx new file mode 100644 index 000000000..57921babe --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/gcp.mdx @@ -0,0 +1,189 @@ +--- +title: Google Cloud Secret Manager +description: Google Cloud Secret Manager를 CrewAI Platform의 시크릿 공급자로 처음부터 끝까지 구성합니다 +sidebarTitle: 정적 자격 증명 사용 +icon: "key" +--- + +## 개요 + +이 가이드는 **서비스 계정 자격 증명**을 사용하여 Google Cloud Secret Manager를 CrewAI Platform 조직의 시크릿 공급자로 구성하는 방법을 안내합니다. 완료되면 CrewAI Platform이 Google Cloud 프로젝트에 저장된 시크릿을 읽고 런타임에 환경 변수 값으로 주입할 수 있습니다. + + +이 가이드는 **정적 자격 증명** 경로를 다룹니다 — 시크릿은 배포 시점에 해석되고 배포 이미지에 박힙니다. 로테이션된 값은 재배포가 필요합니다. 매 자동화 kickoff마다 업데이트되는 로테이션 인식 시크릿을 원한다면 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)을 참조하세요. + + + +이 가이드는 GCP 측 구성과 CrewAI Platform의 자격 증명 설정을 다룹니다. 환경 변수에서 시크릿을 참조하려면 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)를 참조하세요. + + +## 사전 준비 사항 + + +시작하기 전에 다음을 준비하세요: + +- **Secret Manager API**가 활성화된 Google Cloud 프로젝트. [APIs & Services 콘솔](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com)에서 또는 `gcloud`를 통해 활성화하세요: + + ```bash + gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID + ``` + +- 서비스 계정 생성, IAM 역할 부여, (필요한 경우) 시크릿 생성에 대한 프로젝트 권한. +- 사용자가 `secret_providers: manage` 권한을 가진 CrewAI Platform 조직. [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. + + +## 1단계 — 서비스 계정 생성 + +서비스 계정은 CrewAI Platform이 인증할 GCP 측 ID입니다. + +[IAM & Admin → Service Accounts 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts)에서 **Create Service Account**를 클릭합니다. + +- **Service account name:** `crewai-secrets-reader` +- **Service account ID:** 이름에서 자동으로 채워짐(예: `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`) +- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform" + +**Create and Continue**를 클릭합니다. 이 화면에서 선택적 권한 부여는 건너뜁니다 — 역할은 2단계에서 연결합니다. **Done**을 클릭합니다. + +자세한 내용은 GCP 문서를 참조하세요: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create). + +{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */} + +## 2단계 — Secret Manager 액세스 부여 + +CrewAI Platform은 프로젝트의 시크릿을 나열하고 읽을 수 있는 권한이 필요합니다. 두 가지 범위 중 하나를 사용하세요 — 간소화를 위한 **프로젝트 전체** 또는 최소 권한을 위한 **시크릿별**. + + + + [IAM 콘솔](https://console.cloud.google.com/iam-admin/iam)에서 **Grant Access**를 클릭하고: + + - **New principals:** 1단계 서비스 계정의 이메일. + - **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + **Save**를 클릭합니다. + + 또는 `gcloud`를 통해: + + ```bash + gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" + ``` + + {/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */} + + + + CrewAI Platform이 액세스해야 하는 특정 시크릿에만 역할을 부여합니다. 각 시크릿에 대해 반복합니다: + + ```bash + gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" \ + --project=YOUR_PROJECT_ID + ``` + + 또는 콘솔에서: [Secret Manager](https://console.cloud.google.com/security/secret-manager)에서 각 시크릿을 열고, 오른쪽 패널의 **Permissions**를 클릭한 다음 서비스 계정에 **Secret Manager Secret Accessor**를 부여합니다. + + {/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */} + + + + +`roles/secretmanager.secretAccessor` 역할은 시크릿 값에 대한 읽기 전용 액세스를 부여합니다. CrewAI Platform은 또한 환경 변수 폼의 자동 완성 경험을 위해 `secretmanager.secrets.list`를 호출합니다 — 해당 권한은 프로젝트 범위에서는 역할에 포함되지만, 시크릿별 범위에서는 **포함되지 않습니다**. 시크릿별 바인딩의 경우 자동 완성이 시크릿을 제안하지 않으므로 전체 시크릿 이름을 입력해야 합니다. + + +## 3단계 — 서비스 계정 키 생성 + +[IAM & Admin → Service Accounts 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts)에서 1단계의 서비스 계정을 엽니다. + +- **Keys** 탭을 클릭합니다. +- **Add Key** → **Create new key**를 클릭합니다. +- **Key type:** JSON. +- **Create**를 클릭합니다. 브라우저가 JSON 파일을 다운로드합니다 — 안전하게 보관하세요. 다시 다운로드할 수 없습니다. + +또는 `gcloud`를 통해: + +```bash +gcloud iam service-accounts keys create ./crewai-secrets-reader.json \ + --iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com +``` + + +서비스 계정 키는 장기 정적 자격 증명입니다. 안전하게 저장하고(패스워드 매니저나 자체 시크릿 저장소에) 정기적으로 로테이션하세요. 정적 자격 증명을 완전히 제거하려면 대신 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)을 사용하세요. + + +{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */} + +## 4단계 — CrewAI Platform에 자격 증명 추가 + +CrewAI Platform에서 **Settings** → **Secret Provider Credentials**로 이동하여 **Add Credential**을 클릭합니다. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +폼을 작성합니다: + +- **Name:** 설명적인 이름(예: `gcp-prod`). +- **Provider:** `Google Cloud Secret Manager`. +- **Project ID:** GCP 프로젝트 ID(예: `my-crewai-prod`). +- **Service Account JSON:** 3단계에서 다운로드한 JSON 파일의 전체 내용을 붙여 넣습니다. +- (선택) **Set as default credential for this provider**를 체크합니다. 기본 자격 증명은 자격 증명을 명시적으로 지정하지 않고 GCP 시크릿을 참조하는 환경 변수에서 사용됩니다. + +**Create**를 클릭합니다. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */} + +## 5단계 — GCP에 최소 하나의 시크릿 생성 + +GCP Secret Manager에 시크릿이 아직 없다면, 6단계에서 연결을 확인할 수 있도록 지금 하나 만드세요. + +[Secret Manager 콘솔](https://console.cloud.google.com/security/secret-manager)에서 **Create secret**을 클릭합니다. + +- **Name:** 고유한 이름(예: `openai-api-key`). +- **Secret value:** 원시 값을 붙여 넣거나 파일을 업로드합니다. +- 특정 요구 사항이 없으면 로테이션, 복제 및 기타 설정을 기본값으로 둡니다. + +**Create secret**을 클릭합니다. + +또는 `gcloud`를 통해: + +```bash +echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \ + --data-file=- \ + --project=YOUR_PROJECT_ID \ + --replication-policy=automatic +``` + + +**JSON 키 참조 구문.** GCP Secret Manager는 시크릿 값을 불투명한 blob으로 취급합니다. 시크릿 값이 JSON 문자열인 경우, CrewAI Platform은 `secret-name#json_key` 구문(예: `database-credentials#password`)을 사용하여 단일 필드를 추출할 수 있습니다. 자세한 내용은 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. + + +자세한 내용은 GCP 문서를 참조하세요: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart). + +{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */} + +## 6단계 — 연결 테스트 + +CrewAI Platform으로 돌아가 **Secret Provider Credentials** 페이지에서 방금 만든 자격 증명을 찾고 **Test Connection**을 클릭합니다. + +성공 토스트는 CrewAI Platform이 GCP에 인증하고 프로젝트의 시크릿을 읽을 수 있음을 확인합니다. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */} + +테스트가 실패하면 가장 일반적인 원인을 확인하세요: + +| 증상 | 가능한 원인 | +|---|---| +| 시크릿 나열 시 `PERMISSION_DENIED` | 서비스 계정에 `roles/secretmanager.secretAccessor`가 없거나, 시크릿별로 범위를 지정했습니다(`list`가 부여되지 않음). 2단계를 다시 확인하세요. | +| `secretmanager.secrets.access`에서 `PERMISSION_DENIED` | 위와 동일하지만 특정 시크릿에 대한 것입니다. 해당 시크릿에 서비스 계정이 accessor 역할을 갖고 있는지 확인하세요. | +| `unauthorized_client` / `invalid_grant` | 붙여 넣은 서비스 계정 JSON이 유효하지 않거나, 만료되었거나, 삭제된 서비스 계정용입니다. 키를 다시 만들고(3단계) 다시 붙여 넣으세요. | +| `Project ID does not match` | CrewAI Platform의 Project ID 필드가 서비스 계정/시크릿을 소유한 프로젝트와 일치하지 않습니다. 4단계를 다시 확인하세요. | +| `API not enabled` | 프로젝트에 Secret Manager API가 활성화되어 있지 않습니다. 사전 준비 사항을 참조하세요. | + +## 다음 단계 + +이제 GCP가 연결되었으므로 [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage)로 이동하여 다음을 수행하세요: + +- 조직 멤버에게 Secrets Manager를 사용(또는 관리)할 수 있는 적절한 권한을 부여합니다. +- CrewAI Platform 환경 변수에서 GCP 시크릿을 참조합니다. + +재배포 없이 전파되는 **로테이션 인식** 시크릿을 원한다면 [GCP Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity)으로 전환하세요 — 동일한 시크릿 저장소, 정적 자격 증명 없음, kickoff마다 시크릿을 가져옵니다. diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/overview.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/overview.mdx new file mode 100644 index 000000000..868450502 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/overview.mdx @@ -0,0 +1,96 @@ +--- +title: Secrets Manager 개요 +description: 외부 시크릿 저장소를 CrewAI Platform에 연결하고 환경 변수에서 관리되는 시크릿을 참조합니다 +sidebarTitle: 개요 +icon: "book-open" +--- + +## 개요 + +Secrets Manager 기능은 조직에서 외부 시크릿 저장소(AWS Secrets Manager, Google Cloud Secret Manager 또는 Azure Key Vault)를 연결하고, 자동화(Automation) 및 Crew의 환경 변수에서 해당 시크릿을 직접 참조할 수 있게 해줍니다. 플랫폼에 평문 값을 붙여 넣는 대신, 각 공급자별로 자격 증명 한 세트만 저장하고 시크릿을 이름으로 참조합니다. + +이를 통해 얻는 이점은 다음과 같습니다: + +- **중앙 집중식 저장** — CrewAI Platform 설정을 편집하는 대신 공급자에서 시크릿을 관리합니다. CrewAI Platform은 시크릿 값의 평문 사본을 보관하지 않습니다. +- **노출 감소** — 민감한 값이 CrewAI Platform 설정에 평문으로 존재하지 않습니다. +- **클라우드 네이티브 감사 가능성** — 공급자의 감사 로그에 모든 시크릿 읽기 작업이 기록됩니다. + + +Secrets Manager(정적 자격 증명 및 Workload Identity 경로 모두)는 자동화 파드 이미지에 CrewAI 런타임 버전 `1.14.5` 이상이 필요합니다. + + +## 두 가지 경로: 정적 자격 증명 vs Workload Identity + +CrewAI Platform을 클라우드의 시크릿 저장소에 연결하는 방법은 두 가지가 있습니다. **로테이션 동작 방식에서 큰 차이가 있으므로**, 시크릿이 얼마나 자주 로테이션되는지와 보안 정책의 엄격함에 따라 선택하세요. + +| 항목 | 정적 자격 증명 | Workload Identity (OIDC Federation) | +|---|---|---| +| **인증** | 장기 액세스 키 / 서비스 계정 JSON을 CrewAI Platform에 저장 | 워커 프로세스마다 발급되는 단기 토큰; 어디에도 정적 자격 증명을 저장하지 않음 | +| **로테이션 전파** | 배포 시점에 해석되어 **배포 컨테이너 이미지에 박힘** — 로테이션된 값을 반영하려면 재배포 필요 | **자동화 실행 시점**에 해석됨 — 로테이션된 값이 재배포 없이 다음 kickoff에 전파됨 | +| **설정 노력** | 더 적음 — 키 붙여 넣기 / 서비스 계정 JSON 업로드 | 더 많음 — CrewAI Platform을 클라우드에 OIDC 공급자로 등록하고 신뢰 정책 구성 | +| **적합한 용도** | 시작 단계, 드물게 로테이션되는 시크릿, 단일 계정 배포 | 프로덕션, 자주 로테이션되는 시크릿, 장기 자격 증명을 금지하는 규정 준수 환경 | + + +**두 경로 모두 환경 변수에서 시크릿을 참조하는 동일한 UI 흐름을 사용합니다**([Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage) 참조). 차이점은 전적으로 플랫폼이 클라우드에 어떻게 인증하고 언제 시크릿 값을 읽는지에 있습니다. + + +### 설정 가이드 선택 + +| 공급자 | 정적 자격 증명 | Workload Identity | +|---|---|---| +| AWS Secrets Manager | [AWS — 정적 키 / AssumeRole](/ko/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/ko/enterprise/features/secrets-manager/aws-workload-identity) | +| Google Cloud Secret Manager | [GCP — 서비스 계정 키](/ko/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/ko/enterprise/features/secrets-manager/gcp-workload-identity) | +| Azure Key Vault | [Azure — 클라이언트 시크릿](/ko/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/ko/enterprise/features/secrets-manager/azure-workload-identity) | + + +Secrets Manager 및 Workload Identity UI는 현재 CrewAI Platform에서 **Beta**로 표시되어 있습니다. + + +## 동작 방식 + +Secrets Manager 설정은 클라우드 공급자와 CrewAI Platform 양쪽 모두에서 작업하는 3단계 흐름입니다: + +1. **관리자가 공급자 자격 증명을 구성합니다.** 이는 클라우드 측 작업이며 — 선택한 경로(정적 자격 증명 또는 Workload Identity)에 따라 작업이 다릅니다. 공급자별 가이드에서 처음부터 끝까지 다룹니다. +2. **관리자(또는 권한이 부여된 멤버)가 환경 변수에서 시크릿을 참조합니다.** Environment Variables 페이지에서 공급자 자격 증명을 선택하고 시크릿 이름을 선택합니다. [Secrets Manager 사용하기](/ko/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables)를 참조하세요. +3. **자동화가 런타임에 해석된 값을 받습니다.** Crew 또는 자동화가 실행될 때, CrewAI Platform이 공급자에서 시크릿을 가져와 환경 변수 값으로 주입합니다. Workload Identity의 경우 이 가져오기는 매 kickoff마다 수행됩니다(로테이션 인식). 정적 자격 증명의 경우 이 가져오기는 배포 시점에 수행되고 값이 배포 이미지에 박힙니다. + +## 가시성 및 범위 + + +WI 기반 환경 변수는 평문 환경 변수와 동일한 할당 모델을 따릅니다: 자동화는 명시적으로 할당된 WI 기반 변수만 해석합니다. 해당 자동화의 Environment Variables 페이지에서 WI 기반 변수를 자동화에 할당하세요; 조직 수준 또는 Studio 프로젝트에 정의된 변수는 할당하기 전까지 kickoff에서 해석되지 않습니다. + + + +시크릿 가져오기 단계는 매 kickoff마다 실행되지만, 배포에 WI 기반 환경 변수가 할당되어 있을 때만 실제로 작업을 수행합니다. 할당된 변수 각각에 대해, 런타임은 매 crew, flow, training, test, 또는 checkpoint-restore kickoff마다 클라우드 공급자에서 값을 해석하여 프로세스 환경에 기록합니다. 할당된 변수가 없으면 이 단계는 no-op입니다. 그렇지 않은 경우, 비용은 할당된 변수 수에 비례합니다: kickoff당 약간의 추가 지연 시간과 변수당 하나의 클라우드 측 audit log 항목. + + + +Workload Identity *구성* 수준에서는 오늘날에도 여전히 조직 전체에 적용됩니다. 조직 내 모든 자동화는 조직이 등록한 모든 Workload Identity 구성을 기반으로 부트스트랩되며, 오늘날에는 특정 Workload Identity 구성을 특정 자동화에 바인딩할 수 없습니다. 자동화별 Workload Identity 범위 지정은 로드맵에 있습니다. 그때까지는 조직 내 모든 자동화가 사용해도 되는 Workload Identity 구성만 등록하세요. + + +## 권한 + +Secrets Manager 접근을 제어하는 두 가지 CrewAI Platform 기능: + +- `secret_providers` — 공급자 자격 증명을 보거나 관리할 수 있는 사람을 제어합니다. +- `environment_variables` — 시크릿을 참조하는 환경 변수를 포함하여 환경 변수를 생성하고 편집할 수 있는 사람을 제어합니다. + +세 번째 기능은 Workload Identity 설정을 제어합니다: + +- `workload_identity_configs` — Workload Identity 구성을 보거나 관리할 수 있는 사람을 제어합니다. Workload Identity 경로를 사용하는 경우에만 필요합니다. + +소유자(Owner)는 항상 전체 접근 권한을 가집니다. 멤버는 기본적으로 `secret_providers` 또는 `workload_identity_configs`에 대한 접근 권한을 **받지 않으며**, 사용자 정의 역할을 통해 권한을 명시적으로 부여받아야 합니다. 전체 매트릭스와 단계별 지침은 [권한 (RBAC)](/ko/enterprise/features/secrets-manager/usage#permissions-rbac)을 참조하세요. + +## 다음 단계 + +원하는 경로를 선택하세요: + +- **정적 자격 증명** (더 간단함, 로테이션 시 재배포 필요): + - [AWS Secrets Manager 구성](/ko/enterprise/features/secrets-manager/aws) + - [Google Cloud Secret Manager 구성](/ko/enterprise/features/secrets-manager/gcp) + - [Azure Key Vault 구성](/ko/enterprise/features/secrets-manager/azure) +- **Workload Identity** (로테이션 인식, 재배포 불필요): + - [AWS Workload Identity 구성](/ko/enterprise/features/secrets-manager/aws-workload-identity) + - [GCP Workload Identity Federation 구성](/ko/enterprise/features/secrets-manager/gcp-workload-identity) + - [Azure Workload Identity Federation 구성](/ko/enterprise/features/secrets-manager/azure-workload-identity) +- 그리고: [환경 변수에서 시크릿을 사용하고 권한 관리하기](/ko/enterprise/features/secrets-manager/usage) diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/usage.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/usage.mdx new file mode 100644 index 000000000..7f9186e62 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/usage.mdx @@ -0,0 +1,137 @@ +--- +title: Secrets Manager 사용하기 +description: CrewAI Platform에서 권한을 관리하고 환경 변수에서 관리되는 시크릿을 참조합니다 +sidebarTitle: 사용 및 권한 +icon: "list-check" +--- + +## 개요 + +이 가이드는 공급자 중립적입니다. 사용자(또는 다른 관리자)가 이미 최소 하나의 Secret Provider Credential을 구성했다고 가정합니다. 원하는 경로에 따라 설정 가이드를 선택하세요: + +- 정적 자격 증명: [AWS](/ko/enterprise/features/secrets-manager/aws) · [GCP](/ko/enterprise/features/secrets-manager/gcp) +- Workload Identity (로테이션 인식): [AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity) + +이 가이드를 사용하여 다음을 수행하세요: + +- 조직 멤버에게 적절한 권한을 부여합니다. +- 자동화의 환경 변수에서 시크릿을 참조합니다. +- 런타임에서 모든 것이 올바르게 해석되는지 확인합니다. + +## 권한 (RBAC) + +Secrets Manager를 사용할 때 관련된 세 가지 CrewAI Platform 기능: + +- `secret_providers` — **Secret Provider Credentials** 페이지에 대한 접근을 제어합니다. +- `workload_identity_configs` — **Workload Identity** 페이지에 대한 접근을 제어합니다(WI 경로를 사용하는 경우에만 관련됨). +- `environment_variables` — 환경 변수를 생성하거나 편집할 수 있는 사람을 제어합니다. + +각 기능에는 두 가지 작업 수준이 있습니다: `read`와 `manage`. `manage`를 부여하면 자동으로 `read`를 포함합니다. + +### 부여할 권한 + +| 목표 | `secret_providers` | `workload_identity_configs` | `environment_variables` | +|---|---|---|---| +| 환경 변수에서 기존 정적 자격 증명 사용 (공급자 편집 불가) | `read` | — | `manage` | +| 정적 자격 증명 생성, 편집 또는 삭제 | `manage` | — | `manage` | +| 환경 변수에서 기존 Workload Identity 기반 자격 증명 사용 | `read` | — | `manage` | +| Workload Identity 구성(및 이를 참조하는 자격 증명) 생성, 편집 또는 삭제 | `manage` | `manage` | `manage` | + + +**소유자(Owner)**는 모든 기능에 대해 자동으로 전체 접근 권한을 가집니다. 기본 **멤버(Member)** 역할은 의도적으로 `secret_providers` 및 `workload_identity_configs`를 제외합니다 — 관리자는 사용자 정의 역할을 통해 멤버에게 명시적으로 옵트인해야 합니다. + + +### 할당 방법 + +1. CrewAI Platform에서 **Settings** → **Roles**로 이동합니다. 이 페이지에서 새 역할을 생성하고, 각 역할의 권한을 편집하며, 조직의 기존 멤버에게 역할을 할당할 수 있습니다. + + {/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */} + {/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */} + +2. **Create Role**을 클릭하여 새 역할을 만들거나, 기존 역할을 열어 권한을 편집합니다. + +3. 역할의 권한 편집기에서 위 표에 따라 관련 기능을 토글합니다: + + - `secret_providers`: 이 역할이 기존 자격 증명만 사용하면 되는 경우 **read**를 선택하고, 자격 증명을 생성, 편집, 삭제할 수도 있어야 하면 **manage**를 선택합니다. + - `environment_variables`: 역할이 시크릿을 참조하는 환경 변수를 생성할 수 있도록 **manage**를 선택합니다. + + {/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */} + {/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */} + +4. 역할을 저장합니다. + +5. 동일한 Roles 페이지(또는 조직 Members 목록)에서 해당 멤버에게 역할을 할당합니다. + + {/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */} + +## 환경 변수에서 시크릿 참조하기 + +공급자 자격 증명이 존재하고 역할에 적절한 권한이 있으면, 모든 환경 변수에서 관리되는 시크릿을 참조할 수 있습니다. + +CrewAI Platform에서 **Environment Variables**로 이동하여 **Add Environment Variables**를 클릭합니다. + +{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */} + +폼을 작성합니다: + +- **Key** — 환경 변수의 이름입니다. 문자나 밑줄로 시작해야 하며, 문자, 숫자, 밑줄만 포함해야 합니다. 관례적으로 대문자로 작성합니다(예: `OPENAI_API_KEY`). + +- **Value Source** — 값의 출처를 선택합니다: + - **Direct Value** — 직접 입력하는 평문 값입니다. 공급자를 사용하고 싶지 않을 때 사용합니다. + - **Use AWS default** (또는 공급자에 해당하는 항목) — 해당 공급자 유형에서 기본값으로 표시된 자격 증명을 사용합니다. + - **특정 명명된 자격 증명** — 이름으로 자격 증명을 선택합니다. 동일한 공급자에 대해 여러 자격 증명(예: `aws-prod`와 `aws-staging`)이 있고 하나를 명시적으로 선택하려는 경우에 사용합니다. + + {/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */} + +- **Secret Name** — 공급자의 시크릿 이름입니다. 자격 증명이 선택되면 이 필드에서 자동 완성을 제공합니다: 입력을 시작하면 CrewAI Platform이 일치하는 시크릿 이름을 공급자에 쿼리합니다. + + 구조화된(JSON) 시크릿에서 단일 필드를 추출하려면 `secret-name#json_key` 구문을 사용합니다. 예를 들어, `{"username": "...", "password": "..."}` 값을 가진 시크릿 `database-credentials`가 있다면, `database-credentials#password`로 참조하여 비밀번호만 주입할 수 있습니다. + + {/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */} + + + **Azure Key Vault 참고:** Azure 시크릿 이름에는 밑줄을 포함할 수 없습니다. CrewAI Platform은 Azure를 호출할 때 `Secret Name` 필드의 밑줄을 자동으로 하이픈으로 변환합니다(예: `db_password`는 `db-password`로 전송됨). + + +**Create**를 클릭하여 변수를 저장합니다. + +{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */} + + +기존 환경 변수를 편집할 때 **Value** 필드를 비워두면 현재 값이 유지됩니다. 이는 의도된 동작이며 — 값을 다시 입력하지 않고도 다른 필드(시크릿 이름이나 자격 증명 등)를 변경할 수 있게 해줍니다. + + +## 작동 여부 검증 + +엔드 투 엔드 검증 방법: + +1. 다른 환경 변수와 동일한 방식으로 자동화, Crew 또는 배포에서 환경 변수를 참조합니다. +2. 자동화를 배포합니다. +3. 실행을 트리거하고 성공적으로 완료되는지 확인합니다. + +### 로테이션 동작은 자격 증명 경로에 따라 다릅니다 + +| 자격 증명 경로 | 시크릿이 읽히는 시점 | 로테이션 시 필요한 작업 | +|---|---|---| +| **정적 자격 증명** (AWS 액세스 키, GCP 서비스 계정 JSON) | **배포 시점** — 값이 배포 이미지에 박힘 | 시크릿 로테이션 후 자동화 재배포 | +| **Workload Identity** (OIDC federation, AWS 또는 GCP) | **모든 자동화 kickoff 시점** — 값을 클라우드에서 새로 가져옴 | 없음 — 로테이션 후 다음 kickoff에서 새 값이 보임 | + + +**로테이션 인식 시크릿이 필요한 경우**(로테이션 시 재배포 없이), Workload Identity 경로를 사용하세요: [AWS WI](/ko/enterprise/features/secrets-manager/aws-workload-identity) 또는 [GCP WI](/ko/enterprise/features/secrets-manager/gcp-workload-identity). 트레이드오프는 초기 설정 노력이 더 많지만(CrewAI Platform을 클라우드에 OIDC 공급자로 등록), 장기적으로는 운영이 더 단순해진다는 점입니다. + + +배포 또는 실행이 시크릿 관련 오류로 실패하면 가장 일반적인 원인을 확인하세요: + +| 증상 | 가능한 원인 | +|---|---| +| `no credential found` | 환경 변수가 공급자를 참조하지만 특정 자격 증명이 선택되지 않았고, 해당 공급자 유형에 대한 기본 자격 증명이 설정되어 있지 않습니다. 변수에서 자격 증명을 명시적으로 선택하거나, **Secret Provider Credentials** 페이지에서 자격 증명을 기본값으로 표시하세요. | +| `secret not found` | **Secret Name**의 오타, 또는 자격 증명이 가리키는 공급자 계정/리전에 시크릿이 존재하지 않습니다. 둘 다 다시 확인하세요. | +| 로테이션 후에도 자동화가 이전 값으로 실행됨 (정적 자격 증명 경로) | 이전 값이 배포 컨테이너 이미지에 박혀 있습니다. 로테이션된 값을 가져오려면 자동화를 재배포하세요. 이를 완전히 피하려면 자격 증명을 Workload Identity 경로로 전환하세요. | +| 로테이션 후에도 자동화가 이전 값으로 실행됨 (Workload Identity 경로) | 환경 변수가 WI 기반 자격 증명을 참조하는지 확인하세요(정적 키가 아님). WI를 사용하면 로테이션 후 다음 kickoff에서 새 값이 보여야 합니다. 그렇지 않으면 시크릿이 실제로 클라우드에서 업데이트되었는지 확인하세요(예: `aws secretsmanager get-secret-value`). | +| `JSON key not found` | `secret-name#json_key`를 사용할 때 기본 시크릿은 해당 키를 포함하는 유효한 JSON 객체여야 합니다. 공급자에서 직접 시크릿을 읽어 확인하세요. | + +## 다음 단계 + +- [Secrets Manager 개요로 돌아가기](/ko/enterprise/features/secrets-manager/overview) +- 정적 자격 증명: [AWS](/ko/enterprise/features/secrets-manager/aws) · [GCP](/ko/enterprise/features/secrets-manager/gcp) +- Workload Identity (로테이션 인식): [AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity) diff --git a/docs/v1.15.1/ko/enterprise/features/secrets-manager/verify-rotation.mdx b/docs/v1.15.1/ko/enterprise/features/secrets-manager/verify-rotation.mdx new file mode 100644 index 000000000..c9885179a --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/secrets-manager/verify-rotation.mdx @@ -0,0 +1,261 @@ +--- +title: 로테이션 확인 +description: 클라우드 공급자에서 로테이션된 시크릿이 재배포 없이 실행 중인 배포에 전파됨을 증명하는 자체 포함된 예제 Crew입니다. +sidebarTitle: 로테이션 확인 +icon: "arrows-rotate" +--- + +## 개요 + +이 가이드는 **클라우드 공급자에서 로테이션된 시크릿이 바로 다음 자동화 kickoff에서 적용됨**을 검증하는 방법을 보여줍니다 — 재배포 없음, 워커 재시작 없음. Workload Identity 기반 자격 증명([AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/ko/enterprise/features/secrets-manager/azure-workload-identity))을 구성한 경우에만 관련됩니다. 정적 자격 증명 배포는 로테이션 후 재배포가 필요합니다. 여기에서는 확인할 것이 없습니다. + +아래 레시피는 하나의 도구, 하나의 에이전트, 하나의 작업으로 구성된 작은 자체 포함된 Crew를 사용합니다. Crew 프롬프트는 시크릿 값을 절대 참조하지 않으며 — 대신 도구가 `os.environ`에서 이를 읽고 본 것의 SHA-256 fingerprint를 보고합니다. 클라우드 공급자에서 시크릿을 로테이션하고, 다시 kickoff하면 fingerprint가 변경됩니다. + + +원시 값이 아닌 fingerprint를 사용하는 이유? 원시 시크릿을 LLM 출력과 트레이스 로그에 넣는 것은 유출 벡터입니다. fingerprint는 실제 값을 관찰 가능한 곳에 쓰지 않고도 "값이 변경되었다"는 것을 확인하기에 충분합니다. + + +## 사전 준비 사항 + +이 검증을 실행하기 전에: + +- WI 기반 Secret Provider Credential이 구성되어 있어야 합니다([AWS](/ko/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/ko/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/ko/enterprise/features/secrets-manager/azure-workload-identity)). +- `Secret = true`, 키 `API_KEY`(또는 원하는 이름 — 아래 도구를 일치시키도록 조정)로 클라우드 공급자의 시크릿을 참조하는 배포의 환경 변수. +- 클라우드 공급자에서 시크릿 값을 업데이트할 방법(CLI 액세스 또는 클라우드 콘솔). +- HTTP를 통해 배포를 kickoff할 방법(curl, Postman, 또는 CrewAI Platform의 **Run** 탭). + +## 1단계 — 검증 Crew 스캐폴딩 + +이 예제는 `crew.py`를 통해 Python 도구를 연결하므로 클래식 crew 프로젝트를 만듭니다: + +```bash +crewai create crew rotation_verifier --classic --skip_provider +cd rotation_verifier +``` + +## 2단계 — Credential Echo 도구 추가 + +`src/rotation_verifier/tools/custom_tool.py`를 시크릿 기반 환경 변수를 읽고 fingerprint를 반환하는 도구로 교체합니다: + +```python src/rotation_verifier/tools/credential_echo_tool.py +"""Tool that verifies a runtime-injected secret without leaking the value. + +Reads the secret-backed env var (populated by the workload-identity +secrets manager at kickoff time) and returns a stable fingerprint. Never +echo raw credential values into LLM output or logs in production code — +the fingerprint alone is sufficient to confirm rotation worked. +""" + +from __future__ import annotations + +import hashlib +import os + +from crewai.tools import BaseTool + + +# Match the deployment environment variable's `key` field. +ENV_VAR_NAME = "API_KEY" + + +class CredentialEchoTool(BaseTool): + name: str = "credential_echo" + description: str = ( + "Read the API credential from the worker's environment and return a " + "fingerprint summary. Use this exactly once when asked to verify the " + "current credential. Takes no arguments." + ) + + def _run(self) -> str: + value = os.environ.get(ENV_VAR_NAME) + if not value: + return ( + f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-" + "identity secret fetch did not run, or the deployment is " + "missing the secret-backed env var." + ) + fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12] + return f"Authenticated. credential.fingerprint=sha256:{fingerprint}" +``` + +## 3단계 — 기본 에이전트 및 작업 구성 교체 + +Crew에는 하나의 에이전트와 하나의 작업이 있습니다 — 둘 다 시크릿 값을 **절대** 언급하지 않는 설명을 가지므로, 작업 키가 로테이션 전반에 걸쳐 안정적으로 유지됩니다. + +```yaml src/rotation_verifier/config/agents.yaml +credential_checker: + role: > + Credential Verifier + goal: > + Confirm that the workload-identity-backed secret reached this worker + process and report a fingerprint of the current value. + backstory: > + You are a no-nonsense reliability engineer responsible for verifying + that secrets fetched at runtime via workload identity are present + and fresh. You always use the credential_echo tool exactly once and + report the result verbatim — you never make up values. +``` + +```yaml src/rotation_verifier/config/tasks.yaml +verify_credential_task: + description: > + Use the credential_echo tool to read the runtime-injected credential + and produce a one-line confirmation. The current year is {current_year} + (use it only in the timestamp; do not transform the credential output). + expected_output: > + A single line in the form: + "[{current_year}] " + agent: credential_checker +``` + +## 4단계 — Crew 클래스 연결 + +```python src/rotation_verifier/crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent + +from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool + + +@CrewBase +class RotationVerifierCrew(): + """Single-task crew that verifies a workload-identity-backed secret + was successfully fetched at runtime. + + Rotate the underlying secret in the cloud provider, kickoff again, and + the credential fingerprint in the agent's report changes — without any + re-deploy, worker restart, or input change. The crew prompt itself + never references the secret value. + """ + + agents: list[BaseAgent] + tasks: list[Task] + + @agent + def credential_checker(self) -> Agent: + return Agent( + config=self.agents_config["credential_checker"], + tools=[CredentialEchoTool()], + verbose=True, + ) + + @task + def verify_credential_task(self) -> Task: + return Task(config=self.tasks_config["verify_credential_task"]) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +## 5단계 — 배포 및 시크릿 환경 변수 구성 + +다른 Crew와 마찬가지로 이 Crew를 CrewAI Platform에 배포합니다. 그런 다음 배포의 **Environment Variables** 페이지에서: + +- **Key:** `API_KEY` (도구의 `ENV_VAR_NAME`과 일치해야 함) +- **Value Source:** [AWS WI](/ko/enterprise/features/secrets-manager/aws-workload-identity) 또는 [GCP WI](/ko/enterprise/features/secrets-manager/gcp-workload-identity)에서 설정한 WI 기반 자격 증명 +- **Secret Name:** 클라우드 공급자의 Secret Manager에 있는 시크릿 이름 + +{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */} + +## 6단계 — 첫 번째 Kickoff 실행 + +``과 ``를 배포의 **Run** 탭에 있는 값으로 교체합니다. + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +kickoff가 완료되면(몇 초), 에이전트의 출력을 확인합니다. 다음과 같이 표시됩니다: + +``` +[2026] Authenticated. credential.fingerprint=sha256:004421b993c9 +``` + +fingerprint를 기록합니다. 그 해시는 클라우드 공급자에 현재 있는 어떤 시크릿 값과 고유하게 연결되어 있습니다. + +## 7단계 — 클라우드 공급자에서 시크릿 로테이션 + + + + ```bash + aws secretsmanager update-secret \ + --region \ + --secret-id \ + --secret-string "rotated value" + ``` + + + + 새 버전을 추가합니다(Secret Manager는 항상 `latest`를 읽음): + + ```bash + echo -n "rotated value" | gcloud secrets versions add \ + --data-file=- \ + --project= + ``` + + + + ```bash + az keyvault secret set \ + --vault-name \ + --name \ + --value "rotated value" + ``` + + + +## 8단계 — 두 번째 Kickoff 실행 및 비교 + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +이제 에이전트의 출력은 **다른 fingerprint**를 보여줍니다: + +``` +[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72 +``` + +이는 재배포, 워커 재시작 또는 기타 운영자 작업 없이 실행 중인 배포에서 로테이션이 적용되었음을 증명합니다. + +## 이것이 검증하는 것 — 그리고 검증하지 않는 것 + +**검증하는 것:** +- CrewAI Platform에서 WI OIDC 토큰 발급이 작동합니다. +- 클라우드 측 신뢰(AWS의 IAM OIDC 공급자, GCP의 Workload Identity Pool, Azure의 Federated Identity Credential)가 토큰을 수락합니다. +- 클라우드 측 ID(IAM Role / GCP 서비스 계정 / Entra App Registration)가 시크릿을 읽을 수 있는 액세스 권한을 가집니다. +- 시크릿 값이 kickoff 시점에 워커 프로세스의 `os.environ`에 도달합니다. +- 후속 로테이션이 다음 kickoff에 전파됩니다. + +**검증하지 않는 것:** +- 실제 프로덕션 Crew가 로테이션을 우아하게 처리하는지 — 예를 들어, 시작 시 환경 변수를 한 번만 읽는 장기 실행 작업은 작업이 끝날 때까지 이전 값을 계속 사용합니다. 적절히 계획하세요: 모듈 임포트 시가 아닌 사용 시점에 시크릿을 읽으세요. + +## 왜 프롬프트에서 직접 시크릿을 참조하지 않나요? + +더 간단해 보이는 데모는 시크릿 값을 작업 설명에 직접 넣고(예: "`{api_key}`에 대해 조사") 프롬프트를 검사하는 것입니다. **그렇게 하지 마세요.** 두 가지 이유: + +1. **LLM 호출 트레이스와 공급자 측 로그에 시크릿이 유출됩니다.** 트레이스 액세스가 있는 모든 사람이 읽을 수 있습니다. +2. **모든 kickoff에서 작업 설명이 변경됩니다.** CrewAI Platform은 설명의 MD5 해시로 작업을 식별합니다. 로테이션되는 값은 kickoff마다 해시가 변경되어 배포 시간 → 런타임 작업 매핑이 깨집니다. 증상: 작업 레코드가 무한정 `pending_run`으로 표시되거나 다중 작업 Crew의 일부 작업만 등록됩니다. + +이 가이드의 도구 기반 패턴은 두 문제를 모두 회피합니다: 프롬프트는 정적이고, 도구가 런타임에 환경 변수를 읽으며, 값의 fingerprint만 LLM에 도달합니다. + +## 다음 단계 + +- [Secrets Manager 개요로 돌아가기](/ko/enterprise/features/secrets-manager/overview) +- 검증되면 검증 Crew를 삭제합니다. 실제 Crew는 동일한 패턴을 따라야 합니다: 시크릿은 도구 내부의 `os.environ`을 통해 액세스되며, 절대 프롬프트에 치환되지 않습니다. diff --git a/docs/v1.15.1/ko/enterprise/features/tools-and-integrations.mdx b/docs/v1.15.1/ko/enterprise/features/tools-and-integrations.mdx new file mode 100644 index 000000000..e53a03b90 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/tools-and-integrations.mdx @@ -0,0 +1,248 @@ +--- +title: "도구 & 통합" +description: "외부 앱을 연결하고 에이전트가 사용할 내부 도구를 관리하세요." +icon: "wrench" +mode: "wide" +--- + +## 개요 + +도구 & 통합은 서드파티 애플리케이션을 연결하고 에이전트가 런타임에 사용할 내부 도구를 관리하는 중앙 허브입니다. + +![도구 & 통합 개요](/images/enterprise/crew_connectors.png) + +## 살펴보기 + + + + +## 에이전트 앱 (통합) + +Gmail, Google Drive, HubSpot, Slack 등 OAuth 기반 서비스에 연결하여 에이전트 액션을 활성화하세요. + +{" "} + + + 원하는 앱에서 Connect를 클릭하고 OAuth를 완료합니다. + + + 필요에 따라 스코프, 트리거, 사용 가능한 액션을 조정합니다. + + + 연결된 서비스는 에이전트 도구로 사용 가능합니다. + + + +{" "} +![앱 그리드](/images/enterprise/agent-apps.png) + +### 계정 연결하기 + +1. + Integrations + + 로 이동 +2. 원하는 서비스에서 Connect 클릭 +3. OAuth 플로우 완료 및 스코프 승인 +4. + 통합 설정 + + 에서 Enterprise Token 복사 + +{" "} + + ![Enterprise Token](/images/enterprise/enterprise_action_auth_token.png) + + +### 통합 도구 설치 + +로컬에서 통합을 사용하려면 최신 `crewai-tools` 패키지를 설치하세요. + +```bash +uv add crewai-tools +``` + +### 환경 변수 설정 + +{" "} + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +### 사용 예시 + +{" "} + + 새로운 간소화된 접근 방식을 사용하여 엔터프라이즈 앱을 통합하세요. Agent + 구성에서 앱과 해당 액션을 직접 지정하기만 하면 됩니다. + + +```python +from crewai import Agent, Task, Crew + +# Gmail 기능을 가진 에이전트 생성 +email_agent = Agent( + role="이메일 매니저", + goal="이메일 커뮤니케이션 관리", + backstory="이메일 관리에 특화된 AI 어시스턴트", + apps=['gmail', 'gmail/send_email'] # 정식 이름 'gmail' 사용 +) + +email_task = Task( + description="프로젝트 업데이트에 대한 후속 이메일 작성 및 전송", + agent=email_agent, + expected_output="이메일 전송 성공 확인" +) + +crew = Crew(agents=[email_agent], tasks=[email_task]) +crew.kickoff() +``` + +### 도구 필터링 + +```python +from crewai import Agent, Task, Crew + +# 특정 Gmail 액션만 사용하는 에이전트 생성 +gmail_agent = Agent( + role="Gmail 매니저", + goal="Gmail 커뮤니케이션 및 알림 관리", + backstory="Gmail 커뮤니케이션 조율 AI 어시스턴트", + apps=['gmail/fetch_emails'] # 정식 이름과 특정 액션 사용 +) + +notification_task = Task( + description="john@example.com에서 온 이메일 찾기", + agent=gmail_agent, + expected_output="john@example.com의 이메일을 찾았다는 확인" +) + +crew = Crew(agents=[gmail_agent], tasks=[notification_task]) +``` + +배포된 크루에서는 각 통합의 서비스 설정 페이지에서 사용 가능한 액션을 지정할 수 있습니다. + +{" "} + + ![액션 필터링](/images/enterprise/filtering_enterprise_action_tools.png) + + +### 범위 지정 배포 (다중 사용자 조직) + +각 통합을 특정 사용자로 범위 지정할 수 있습니다 (예: 특정 사용자의 Gmail 계정 사용). + +{" "} +팀/사용자별 데이터 접근을 분리해야 할 때 유용합니다. + +`user_bearer_token`을 사용해 요청 사용자로 인증을 범위 지정합니다. 사용자가 로그인하지 않은 경우 연결된 통합을 사용하지 않으며, 그렇지 않으면 배포에 설정된 기본 토큰을 사용합니다. + +{" "} +![사용자 토큰](/images/enterprise/user_bearer_token.png) + +{" "} +
+### 카탈로그 + +#### 커뮤니케이션 & 협업 + +- Gmail — 이메일 및 초안 관리 +- Slack — 워크스페이스 알림 및 경보 +- Microsoft — Office 365 및 Teams 통합 + +#### 프로젝트 관리 + +- Jira — 이슈 추적 및 프로젝트 관리 +- ClickUp — 작업 및 생산성 관리 +- Asana — 팀 작업 조율 +- Notion — 페이지 및 데이터베이스 관리 +- Linear — 버그/프로젝트 추적 +- GitHub — 리포지토리 및 이슈 관리 + +#### CRM + +- Salesforce — 계정 및 기회 관리 +- HubSpot — 파이프라인/연락처 관리 +- Zendesk — 고객 지원 티켓 관리 + +#### 비즈니스 & 금융 + +- Stripe — 결제 처리 및 고객 관리 +- Shopify — 전자상거래 및 상품 관리 + +#### 생산성 & 스토리지 + +- Google Sheets — 스프레드시트 동기화 +- Google Calendar — 일정/이벤트 관리 +- Box — 파일 스토리지 + +…더 많은 통합이 추가될 예정입니다! + + + + +## 내부 도구 + +로컬에서 도구를 만들고, CrewAI AMP 도구 저장소에 게시한 후, 에이전트에서 사용하세요. + +{" "} + + 아래 명령을 실행하기 전에 CrewAI AMP 계정에 로그인하세요: ```bash crewai login``` + + +{" "} +![내부 도구](/images/enterprise/tools-integrations-internal.png) + +{" "} + + + 로컬에서 새 도구 생성 ```bash crewai tool create your-tool ``` + + 도구 저장소에 게시 ```bash crewai tool publish ``` + + 도구 저장소에서 설치 ```bash crewai tool install your-tool ``` + + + +관리: + +- 이름 및 설명 +- 가시성 (비공개 / 공개) +- 필요한 환경 변수 +- 버전 이력 및 다운로드 +- 팀/역할 접근 권한 + +{" "} +![도구 설정](/images/enterprise/tool-configs.png) + + + + +## 관련 문서 + + + + 크루 기능을 확장할 수 있도록 도구를 게시하고 설치하세요. + + + 워크플로를 자동화하고 외부 플랫폼/서비스와 통합하세요. + + diff --git a/docs/v1.15.1/ko/enterprise/features/traces.mdx b/docs/v1.15.1/ko/enterprise/features/traces.mdx new file mode 100644 index 000000000..819118e14 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/traces.mdx @@ -0,0 +1,142 @@ +--- +title: 트레이스 +description: "Traces를 사용하여 내 크루 모니터링하기" +icon: "timeline" +mode: "wide" +--- + +## 개요 + +Trace는 crew 실행에 대한 포괄적인 가시성을 제공하여 성능 모니터링, 문제 디버깅, AI agent workflow 최적화에 도움을 줍니다. + +## Traces란 무엇인가요? + +CrewAI AOP의 Traces는 crew의 작동 과정을 처음 입력에서 최종 출력까지 모든 측면에서 포착하는 상세 실행 기록입니다. Traces에는 다음 내용이 기록됩니다: + +- Agent의 생각 및 추론 +- 작업 실행 세부 정보 +- 도구 사용 및 출력 +- 토큰 소모 메트릭 +- 실행 시간 +- 비용 추정치 + +![Traces Overview](/images/enterprise/traces-overview.png) + +## 트레이스(Traces) 접근하기 + + + + CrewAI AMP 대시보드에 들어가면, **트레이스**를 클릭하여 모든 실행 기록을 볼 수 있습니다. + + + + 모든 crew 실행 목록이 날짜별로 정렬되어 표시됩니다. 상세 트레이스를 보려면 원하는 실행을 클릭하세요. + + + +## 트레이스 인터페이스 이해하기 + +트레이스 인터페이스는 여러 섹션으로 나뉘어 있으며, 각 섹션은 crew의 실행에 대한 다양한 인사이트를 제공합니다. + +### 1. 실행 요약 + +상단 섹션에서는 실행에 대한 고수준 메트릭을 표시합니다: + +- **총 토큰**: 모든 작업에서 소모된 토큰 수 +- **프롬프트 토큰**: LLM에 프롬프트로 사용된 토큰 +- **컴플리션 토큰**: LLM 응답에서 생성된 토큰 +- **요청 수**: 수행된 API 호출 수 +- **실행 시간**: crew 런의 전체 소요 시간 +- **예상 비용**: 토큰 사용량을 기반으로 한 대략적인 비용 + +![Execution Summary](/images/enterprise/trace-summary.png) + +### 2. Tasks & Agents + +이 섹션에서는 crew 실행에 포함된 모든 task와 agent를 보여줍니다: + +- task 이름 및 agent 할당 +- 각 task에 사용된 agent 및 LLM +- 상태 (완료/실패) +- task의 개별 실행 시간 + +![Task List](/images/enterprise/trace-tasks.png) + +### 3. 최종 결과 + +모든 작업이 완료된 후 crew가 생성한 최종 결과를 표시합니다. + +![최종 결과](/images/enterprise/final-output.png) + +### 4. 실행 타임라인 + +각 작업이 시작되고 종료된 시점을 시각적으로 표현하여 병목 현상이나 병렬 실행 패턴을 파악하는 데 도움이 됩니다. + +![실행 타임라인](/images/enterprise/trace-timeline.png) + +### 5. 상세 작업 보기 + +타임라인이나 작업 목록에서 특정 작업을 클릭하면 다음을 볼 수 있습니다: + +![상세 작업 보기](/images/enterprise/trace-detailed-task.png) + +- **작업 키**: 작업의 고유 식별자 +- **작업 ID**: 시스템 내의 기술적 식별자 +- **상태**: 현재 상태 (완료/진행 중/실패) +- **에이전트**: 해당 작업을 수행한 에이전트 +- **LLM**: 이 작업에 사용된 언어 모델 +- **시작/종료 시간**: 작업이 시작되고 완료된 시간 +- **실행 시간**: 이 특정 작업의 소요 시간 +- **작업 설명**: 에이전트에게 지시된 작업 내용 +- **예상 출력**: 요청된 출력 형식 +- **입력**: 이전 작업에서 이 작업에 제공된 입력값 +- **출력**: 에이전트가 실제로 생성한 결과 + +## 디버깅을 위한 트레이스 사용 + +트레이스는 crew 문제 해결에 매우 유용합니다: + + + + crew 실행이 예상한 결과를 내지 못할 때, 트레이스를 확인하여 어디에서 문제가 발생했는지 찾으세요. 다음을 확인하세요: + + - 실패한 작업 + - 에이전트의 예상 밖 결정 + - 도구 사용 오류 + - 잘못 해석된 지침 + + + ![Failure Points](/images/enterprise/failure.png) + + + + + + 실행 메트릭을 사용하여 성능 병목 현상을 파악하세요: + + - 예상보다 오래 걸린 작업 + - 과도한 토큰 사용 + - 중복된 도구 작업 + - 불필요한 API 호출 + + + + + 토큰 사용량 및 비용 추정치를 분석해 crew의 효율성을 최적화하세요: + + - 더 간단한 작업에는 더 작은 모델을 사용 고려 + - 프롬프트를 더 간결하게 다듬기 + - 자주 액세스하는 정보 캐싱 + - 중복 작업을 최소화하도록 작업 구조화하기 + + + + + + 트레이스 분석이나 기타 CrewAI 엔터프라이즈 기능에 대한 지원이 필요하시면 저희 + 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/features/webhook-streaming.mdx b/docs/v1.15.1/ko/enterprise/features/webhook-streaming.mdx new file mode 100644 index 000000000..b9d6a85d9 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/features/webhook-streaming.mdx @@ -0,0 +1,82 @@ +--- +title: 웹훅 스트리밍 +description: "웹훅 스트리밍을 사용하여 이벤트를 웹훅으로 스트리밍하기" +icon: "webhook" +mode: "wide" +--- + +## 개요 + +Enterprise Event Streaming을 사용하면 CrewAI AOP에 배포된 crew 및 flow에 대한 실시간 웹훅 업데이트(예: 모델 호출, 도구 사용, flow 단계)를 받을 수 있습니다. + +## 사용법 + +Kickoff API를 사용할 때, 요청에 `webhooks` 객체를 포함시키세요. 예를 들면 아래와 같습니다: + +```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" + } + } +} +``` + +`realtime`이 `true`로 설정되면, 각 이벤트가 개별적으로 그리고 즉시 전달되지만 crew/flow 성능에 영향을 미칠 수 있습니다. + +## Webhook 형식 + +각 webhook은 이벤트 목록을 전송합니다: + +```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."} + ] + } + } + ] +} +``` + +`data` 객체의 구조는 이벤트 타입에 따라 다릅니다. 자세한 내용은 GitHub의 [이벤트 목록](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events)을 참조하세요. + +요청이 HTTP를 통해 전송되므로, 이벤트의 순서가 보장되지 않습니다. 순서가 필요하다면 `timestamp` 필드를 사용하세요. + +## 지원되는 이벤트 + +CrewAI는 Enterprise Event Streaming에서 시스템 이벤트와 사용자 지정 이벤트 둘 다를 지원합니다. 이러한 이벤트는 crew 및 flow 실행 중에 구성한 웹훅 엔드포인트로 전송됩니다. + +- `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` +- *...그리고 기타 여러 가지* + +이벤트 이름은 내부 이벤트 버스와 일치합니다. 전체 목록은 [GitHub 소스](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events)에서 확인할 수 있습니다. + +사용자 지정 이벤트도 직접 발생시킬 수 있으며, 시스템 이벤트와 함께 웹훅 스트림을 통해 전달됩니다. + + + 웹훅 통합 또는 문제 해결에 대한 지원이 필요하다면 저희 지원팀에 문의해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/automation-triggers.mdx b/docs/v1.15.1/ko/enterprise/guides/automation-triggers.mdx new file mode 100644 index 000000000..cccda10a1 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/automation-triggers.mdx @@ -0,0 +1,272 @@ +--- +title: "트리거 개요" +description: "CrewAI AMP 트리거의 동작 방식과 관리 방법, 그리고 통합별 플레이북을 한눈에 확인하세요" +icon: "bolt" +mode: "wide" +--- + +CrewAI AMP 트리거는 팀이 이미 사용하고 있는 도구의 실시간 이벤트와 자동화를 연결합니다. 폴링이나 수동 실행 대신, 트리거는 새로운 이메일, 캘린더 업데이트, CRM 상태 변화 등을 감지하여 지정한 크루 또는 플로우를 즉시 실행합니다. + + + +### 통합 플레이북 + +아래 가이드는 각 통합을 활성화하고 테스트하는 방법을 자세히 설명합니다. + + + + 새로운 이메일이나 스레드 업데이트에 맞춰 크루를 실행하세요. + + +{" "} + + + 캘린더 이벤트 생성, 수정, 취소에 대응하세요. + + + +{" "} + + + Drive 파일 업로드, 수정, 삭제를 감시하세요. + + + +{" "} + + + Outlook의 새로운 메일이나 삭제된 이벤트에 대응하세요. + + + +{" "} + + + OneDrive 파일 활동 및 공유 변경 사항을 감사하세요. + + + +{" "} + + + 새로운 Teams 채팅이 생성될 때 워크플로우를 시작하세요. + + + +{" "} + + + HubSpot 워크플로우와 라이프사이클 이벤트에서 자동화를 실행하세요. + + + +{" "} + + + Salesforce 프로세스를 CrewAI 크루와 연결해 CRM 자동화를 구현하세요. + + + +{" "} + + + Slack 슬래시 명령으로 크루를 바로 실행하세요. + + + + + CrewAI를 수천 개의 Zapier 지원 앱과 연동하세요. + + + +## 트리거 기능 + +- **실시간 대응** – 조건이 충족되면 자동으로 워크플로우 실행 +- **외부 시스템 연동** – Gmail, Outlook, OneDrive, JIRA, Slack, Stripe 등과 연결 +- **자동화 확장성** – 수동 개입 없이 대량 이벤트 처리 +- **컨텍스트 유지** – 트리거 데이터를 크루와 플로우에서 바로 활용 + +## 트리거 관리 + +### 사용 가능한 트리거 보기 + +1. CrewAI 대시보드에서 자동화를 선택합니다. +2. **Triggers** 탭을 클릭하여 사용 가능한 통합을 확인합니다. + + + 사용 가능한 트리거 목록 + + +### 트리거 활성화/비활성화 + + + 트리거 토글 + + +- **파랑 (활성)** – 이벤트 발생 시 자동 실행 +- **회색 (비활성)** – 이벤트 무시 + +토글 버튼을 클릭하면 즉시 적용됩니다. + +### 트리거 실행 모니터링 + +트리거 실행 내역과 상태를 대시보드에서 확인하세요. + + + 트리거 실행 내역 + + +## 트리거 기반 자동화 구성 + +### 설정 체크리스트 + +- **Tools & Integrations**에서 해당 서비스를 연결하고 OAuth 또는 API 설정을 완료했나요? +- 자동화에서 트리거 토글을 활성화했나요? +- 필요한 환경 변수(토큰, 테넌트 ID, 시크릿 등)를 설정했나요? +- 첫 번째 작업에서 트리거 payload를 파싱하도록 구성했나요? +- `allow_crewai_trigger_context` 옵션으로 컨텍스트 자동 주입 여부를 결정했나요? +- 웹훅 로그, CrewAI 실행 기록, 외부 알림 등 모니터링을 준비했나요? + +### CLI로 로컬에서 트리거 테스트 + +CrewAI CLI는 프로덕션에 배포하기 전에 트리거 기반 자동화를 개발하고 테스트할 수 있는 강력한 명령을 제공합니다. + +#### 사용 가능한 트리거 목록 보기 + +연결된 통합에 사용 가능한 모든 트리거를 확인하세요: + +```bash +crewai triggers list +``` + +이 명령은 연결된 통합을 기반으로 사용 가능한 모든 트리거를 표시합니다: + +- 통합 이름 및 연결 상태 +- 사용 가능한 트리거 유형 +- 트리거 이름 및 설명 + +#### 트리거 실행 시뮬레이션 + +배포 전에 실제 트리거 payload로 크루를 테스트하세요: + +```bash +crewai triggers run <트리거_이름> +``` + +예시: + +```bash +crewai triggers run microsoft_onedrive/file_changed +``` + +이 명령은: + +- 로컬에서 크루를 실행합니다 +- 완전하고 실제적인 트리거 payload를 전달합니다 +- 프로덕션에서 크루가 호출되는 방식을 정확히 시뮬레이션합니다 + + + **중요한 개발 노트:** + - 개발 중 트리거 실행을 시뮬레이션하려면 `crewai triggers run `를 사용하세요 + - `crewai run`을 사용하면 트리거 호출을 시뮬레이션하지 않으며 트리거 payload를 전달하지 않습니다 + - 배포 후에는 실제 트리거 payload로 크루가 실행됩니다 + - 크루가 트리거 payload에 없는 매개변수를 기대하면 실행이 실패할 수 있습니다 + + +### 트리거와 Crew 연동 + +```python +@CrewBase +class MyAutomatedCrew: + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + ) + + @task + def parse_trigger_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_trigger_payload'], + agent=self.researcher(), + ) + + @task + def analyze_trigger_content(self) -> Task: + return Task( + config=self.tasks_config['analyze_trigger_data'], + agent=self.researcher(), + ) +``` + +### 플로우와의 통합 + +#### Payload 접근 + +```python +from crewai.flow import Flow, start, listen + +class MyAutomatedFlow(Flow): + @start() + def handle_trigger(self, crewai_trigger_payload: dict = None): + if crewai_trigger_payload: + trigger_id = crewai_trigger_payload.get('id') + event_data = crewai_trigger_payload.get('payload', {}) + self.state.trigger_id = trigger_id + self.state.trigger_type = event_data + return event_data + return None + + @listen(handle_trigger) + def process_data(self, trigger_data): + # ... 트리거 처리 +``` + +#### 플로우에서 Crew 실행 + +```python +@start() +def delegate_to_crew(self, crewai_trigger_payload: dict = None): + crew = MySpecializedCrew() + result = crew.crew().kickoff( + inputs={ + 'custom_parameter': "custom_value", + 'crewai_trigger_payload': crewai_trigger_payload + }, + ) + return result +``` + +## 문제 해결 + +**트리거가 실행되지 않나요?** + +- 배포의 Triggers 탭에서 트리거가 활성화되어 있는지 확인하세요 +- Tools & Integrations에서 통합 연결 상태를 확인하세요 +- 필요한 모든 환경 변수가 올바르게 구성되어 있는지 확인하세요 + +**실행 중 오류가 발생하나요?** + +- 실행 로그에서 오류 세부 정보를 확인하세요 +- `crewai triggers run <트리거_이름>`을 사용하여 로컬에서 테스트하고 정확한 payload 구조를 확인하세요 +- 크루가 `crewai_trigger_payload` 매개변수를 처리할 수 있는지 확인하세요 +- 크루가 트리거 payload에 포함되지 않은 매개변수를 기대하지 않는지 확인하세요 + +**개발 문제:** + +- 배포하기 전에 항상 `crewai triggers run `로 테스트하여 전체 payload를 확인하세요 +- `crewai run`은 트리거 호출을 시뮬레이션하지 않으므로 `crewai triggers run`을 대신 사용하세요 +- `crewai triggers list`를 사용하여 연결된 통합에 사용 가능한 트리거를 확인하세요 +- 배포 후 크루는 실제 트리거 payload를 받으므로 먼저 로컬에서 철저히 테스트하세요 + +트리거를 활용하면 CrewAI 자동화를 이벤트 기반 시스템으로 전환하여 기존 비즈니스 프로세스와 도구에 자연스럽게 녹여낼 수 있습니다. diff --git a/docs/v1.15.1/ko/enterprise/guides/azure-openai-setup.mdx b/docs/v1.15.1/ko/enterprise/guides/azure-openai-setup.mdx new file mode 100644 index 000000000..776c5363b --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/azure-openai-setup.mdx @@ -0,0 +1,54 @@ +--- +title: "Azure OpenAI 설정" +description: "엔터프라이즈 LLM 연결을 위해 Crew Studio와 함께 Azure OpenAI를 구성합니다" +icon: "microsoft" +mode: "wide" +--- + +이 가이드는 Azure OpenAI와 Crew Studio를 연동하여 원활한 엔터프라이즈 AI 운영을 수행하는 방법을 안내합니다. + +## 설정 프로세스 + + + + 1. Azure에서 `Azure AI Services > 배포 선택 > Azure OpenAI Studio 열기`로 이동합니다. + 2. 왼쪽 메뉴에서 `Deployments`를 클릭합니다. 배포가 없다면 원하는 모델로 새 배포를 생성하세요. + 3. 생성이 완료되면 해당 배포를 선택하고, 페이지 오른쪽에서 `Target URI`와 `Key`를 찾습니다. 이 정보가 필요하니 페이지를 열어둔 상태로 두세요. + + Azure OpenAI Studio + + + + + 4. 다른 탭에서 `CrewAI AMP > LLM Connections`를 엽니다. LLM Connection에 이름을 지정하고, 공급자로 Azure를 선택한 다음, Azure에서 선택한 것과 동일한 모델을 선택하세요. + 5. 같은 페이지에서 3단계에서 가져온 환경 변수를 추가하세요: + - 하나는 `AZURE_DEPLOYMENT_TARGET_URL` (Target URI 사용)로 명명합니다. URL은 다음과 같이 표시됩니다: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview + - 다른 하나는 `AZURE_API_KEY` (Key 사용)로 명명합니다. + 6. `Add Connection`을 클릭하여 LLM Connection을 저장합니다. + + + + 7. `CrewAI AMP > Settings > Defaults > Crew Studio LLM Settings`에서 새 LLM Connection과 모델을 기본값으로 설정합니다. + + + + 8. 네트워크 액세스 설정을 확인하세요: + - Azure에서 `Azure OpenAI > 배포 선택`으로 이동합니다. + - `Resource Management > Networking`으로 이동합니다. + - `Allow access from all networks`가 활성화되어 있는지 확인하세요. 이 설정이 제한되어 있으면 CrewAI가 Azure OpenAI 엔드포인트에 접근하지 못할 수 있습니다. + + + + +## 확인 + +모두 준비되었습니다! 이제 Crew Studio는 Azure OpenAI 연결을 사용합니다. 모든 기능이 제대로 작동하는지 확인하려면 간단한 crew 또는 task를 만들어 연결을 테스트해 보세요. + +## 문제 해결 + +문제가 발생한 경우: + +- Target URI 형식이 예상 패턴과 일치하는지 확인하세요 +- API 키가 올바르고 적절한 권한을 가지고 있는지 확인하세요 +- 네트워크 액세스가 CrewAI 연결을 허용하도록 구성되어 있는지 확인하세요 +- 배포 모델이 CrewAI에서 구성한 것과 일치하는지 확인하세요 diff --git a/docs/v1.15.1/ko/enterprise/guides/build-crew.mdx b/docs/v1.15.1/ko/enterprise/guides/build-crew.mdx new file mode 100644 index 000000000..85cb266b3 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/build-crew.mdx @@ -0,0 +1,44 @@ +--- +title: "Crew 빌드" +description: "Crew는 함께 작업을 완수하기 위해 협력하는 에이전트 그룹입니다." +icon: "people-arrows" +mode: "wide" +--- + +## 개요 + +[CrewAI AMP](https://app.crewai.com)는 프로덕션 환경에서 AI 에이전트를 **생성**, **배포** 및 **관리**하는 과정을 간소화합니다. + +## 시작하기 + + + +### 설치 및 설정 + + + CrewAI CLI를 설정하고 첫 번째 프로젝트를 생성하기 위해 표준 설치 가이드를 + 따라주세요. + + +### 크루 구성하기 + + + YAML 구성을 사용하여 첫 번째 에이전트 크루를 만드는 방법은 빠른 시작 가이드를 + 따라주세요. + + +## 지원 및 리소스 + +Enterprise 전용 지원 또는 문의가 필요하신 경우, [support@crewai.com](mailto:support@crewai.com)으로 저희 전담 지원팀에 연락해 주시기 바랍니다. + + + Enterprise 기능과 해당 기능이 귀사의 조직에 어떻게 도움이 될 수 있는지 + 알아보시려면 저희 팀과 상담 일정을 예약하세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/capture_telemetry_logs.mdx b/docs/v1.15.1/ko/enterprise/guides/capture_telemetry_logs.mdx new file mode 100644 index 000000000..0c6f59774 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/capture_telemetry_logs.mdx @@ -0,0 +1,57 @@ +--- +title: "OpenTelemetry 내보내기" +description: "CrewAI AMP 배포에서 자체 OpenTelemetry 수집기로 트레이스와 로그를 내보내기" +icon: "magnifying-glass-chart" +mode: "wide" +--- + +CrewAI AMP는 배포에서 OpenTelemetry **트레이스**와 **로그**를 자체 수집기로 직접 내보낼 수 있습니다. 이를 통해 기존 관측 가능성 스택을 사용하여 에이전트 성능을 모니터링하고, LLM 호출을 추적하고, 문제를 디버깅할 수 있습니다. + +텔레메트리 데이터는 [OpenTelemetry GenAI 시맨틱 규칙](https://opentelemetry.io/docs/specs/semconv/gen-ai/)과 추가적인 CrewAI 전용 속성을 따릅니다. + + +OpenTelemetry는 **권장되는 관측 가능성 경로**입니다 — 벤더 중립적이며, OTLP 호환 백엔드(Grafana, Honeycomb, NewRelic, 자체 수집기)에서 작동합니다. Datadog을 사용하는 경우, Datadog Agent 경로와 Datadog의 OTLP 수집을 모두 다루는 전용 [Datadog 통합](./datadog) 가이드를 참조하세요. + + +## 사전 요구 사항 + + + + 조직에 활성 CrewAI AMP 계정이 있어야 합니다. + + + OpenTelemetry 호환 수집기 엔드포인트가 필요합니다 (예: 자체 OTel Collector, Datadog, Grafana 또는 OTLP 호환 백엔드). + + + +## 수집기 설정 + +1. CrewAI AMP에서 **Settings** > **OpenTelemetry Collectors**로 이동합니다. +2. **Add Collector**를 클릭합니다. +3. 통합을 선택합니다: + - **OpenTelemetry Traces** 및 **OpenTelemetry Logs** — OTLP 호환 수집기 또는 백엔드로 내보냅니다. + - **Datadog** — 별도의 수집기나 Datadog Agent 없이 트레이스를 Datadog의 OTLP 인테이크로 직접 전송합니다. +4. 연결을 구성합니다. 필드는 선택한 통합에 따라 달라집니다: + + + + **OpenTelemetry Traces**와 **OpenTelemetry Logs**는 동일한 필드를 공유하는 별개의 통합입니다 — 내보내려는 신호에 맞는 것을 선택하세요. + + - **Endpoint** — 수집기의 OTLP 엔드포인트 (예: `https://otel-collector.example.com:4317`). + - **Service Name** — 관측 가능성 플랫폼에서 이 서비스를 식별하기 위한 이름. + - **Custom Headers** *(선택 사항)* — 인증 또는 라우팅 헤더를 키-값 쌍으로 추가합니다. + - **Certificate** *(선택 사항)* — 수집기에서 TLS 인증서가 필요한 경우 제공합니다. + + ![OpenTelemetry 수집기 구성](/images/crewai-otel-collector-opentelemetry.png) + + + Datadog 설정은 전용 [Datadog 통합](./datadog) 가이드를 참조하세요 — Datadog Agent 경로(권장, 로그 볼륨에 더 저렴)와 Datadog의 OTLP 수집을 모두 다루며, 수집기 구성 단계를 완전히 설명합니다. + + + +5. *(선택 사항)* **Test Connection**을 클릭하여 제공한 자격 증명으로 CrewAI가 엔드포인트에 연결할 수 있는지 확인합니다. +6. **Save**를 클릭합니다. + + + 여러 수집기를 추가할 수 있습니다 — 예를 들어, 트레이스용 하나와 로그용 하나를 추가하거나, 다른 목적을 위해 다른 백엔드로 전송할 수 있습니다. + diff --git a/docs/v1.15.1/ko/enterprise/guides/custom-mcp-server.mdx b/docs/v1.15.1/ko/enterprise/guides/custom-mcp-server.mdx new file mode 100644 index 000000000..530430ac8 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/custom-mcp-server.mdx @@ -0,0 +1,136 @@ +--- +title: "커스텀 MCP 서버" +description: "공개 액세스, API 키 인증 또는 OAuth 2.0을 사용하여 자체 MCP 서버를 CrewAI AMP에 연결하세요" +icon: "plug" +mode: "wide" +--- + +CrewAI AMP는 [Model Context Protocol](https://modelcontextprotocol.io/)을 구현하는 모든 MCP 서버에 연결할 수 있습니다. 인증이 필요 없는 공개 서버, API 키 또는 Bearer 토큰으로 보호되는 서버, OAuth 2.0을 사용하는 서버를 연결할 수 있습니다. + +## 사전 요구사항 + + + + 활성화된 [CrewAI AMP](https://app.crewai.com) 계정이 필요합니다. + + + 연결하려는 MCP 서버의 URL입니다. 서버는 인터넷에서 접근 가능해야 하며 Streamable HTTP 전송을 지원해야 합니다. + + + +## 커스텀 MCP 서버 추가하기 + + + + CrewAI AMP 왼쪽 사이드바에서 **Tools & Integrations**로 이동한 후 **Connections** 탭을 선택합니다. + + + + **Add Custom MCP Server** 버튼을 클릭합니다. 구성 양식이 포함된 대화 상자가 나타납니다. + + + + - **Name** (필수): MCP 서버의 설명적 이름 (예: "내부 도구 서버"). + - **Description**: 이 MCP 서버가 제공하는 기능에 대한 선택적 요약. + - **Server URL** (필수): MCP 서버 엔드포인트의 전체 URL (예: `https://my-server.example.com/mcp`). + + + + MCP 서버의 보안 방식에 따라 세 가지 인증 방법 중 하나를 선택합니다. 각 방법에 대한 자세한 내용은 아래 섹션을 참조하세요. + + + + MCP 서버가 모든 요청에 추가 헤더를 요구하는 경우 (예: 테넌트 식별자 또는 라우팅 헤더), **+ Add Header**를 클릭하고 헤더 이름과 값을 입력합니다. 여러 커스텀 헤더를 추가할 수 있습니다. + + + + **Create MCP Server**를 클릭하여 연결을 저장합니다. 커스텀 MCP 서버가 Connections 목록에 나타나고 해당 도구를 crew에서 사용할 수 있게 됩니다. + + + +## 인증 방법 + +### 인증 없음 + +MCP 서버가 공개적으로 접근 가능하고 자격 증명이 필요 없을 때 이 옵션을 선택합니다. 오픈 소스 서버나 VPN 뒤에서 실행되는 내부 서버에 일반적입니다. + +### 인증 토큰 + +MCP 서버가 API 키 또는 Bearer 토큰으로 보호되는 경우 이 방법을 사용합니다. + + + 인증 토큰을 사용하는 커스텀 MCP 서버 + + +| 필드 | 필수 | 설명 | +|------|------|------| +| **Header Name** | 예 | 토큰을 전달하는 HTTP 헤더 이름 (예: `X-API-Key`, `Authorization`). | +| **Value** | 예 | API 키 또는 Bearer 토큰. | +| **Add to** | 아니오 | 자격 증명을 첨부할 위치 — **Header** (기본값) 또는 **Query parameter**. | + + +서버가 `Authorization` 헤더에 `Bearer` 토큰을 예상하는 경우, Header Name을 `Authorization`으로, Value를 `Bearer <토큰>`으로 설정하세요. + + +### OAuth 2.0 + +OAuth 2.0 인증이 필요한 MCP 서버에 이 방법을 사용합니다. CrewAI가 토큰 갱신을 포함한 전체 OAuth 흐름을 처리합니다. + + + OAuth 2.0을 사용하는 커스텀 MCP 서버 + + +| 필드 | 필수 | 설명 | +|------|------|------| +| **Redirect URI** | — | 자동으로 채워지며 읽기 전용입니다. 이 URI를 복사하여 OAuth 제공자에 승인된 리디렉션 URI로 등록하세요. | +| **Authorization Endpoint** | 예 | 사용자가 접근을 승인하기 위해 이동하는 URL (예: `https://auth.example.com/oauth/authorize`). | +| **Token Endpoint** | 예 | 인증 코드를 액세스 토큰으로 교환하는 데 사용되는 URL (예: `https://auth.example.com/oauth/token`). | +| **Client ID** | 예 | OAuth 제공자가 발급한 클라이언트 ID. | +| **Client Secret** | 아니오 | OAuth 클라이언트 시크릿. PKCE를 사용하는 공개 클라이언트에는 필요하지 않습니다. | +| **Scopes** | 아니오 | 요청할 스코프의 공백으로 구분된 목록 (예: `read write`). | +| **Token Auth Method** | 아니오 | 토큰 교환 시 클라이언트 자격 증명을 보내는 방법 — **Standard (POST body)** 또는 **Basic Auth (header)**. 기본값은 Standard입니다. | +| **PKCE Supported** | 아니오 | OAuth 제공자가 Proof Key for Code Exchange를 지원하는 경우 활성화합니다. 보안 강화를 위해 권장됩니다. | + + +**Discover OAuth Config**: OAuth 제공자가 OpenID Connect Discovery를 지원하는 경우, **Discover OAuth Config** 링크를 클릭하여 제공자의 `/.well-known/openid-configuration` URL에서 인증 및 토큰 엔드포인트를 자동으로 채울 수 있습니다. + + +#### OAuth 2.0 단계별 설정 + + + + 양식에 표시된 **Redirect URI**를 복사하여 OAuth 제공자의 애플리케이션 설정에서 승인된 리디렉션 URI로 추가합니다. + + + + **Authorization Endpoint**, **Token Endpoint**, **Client ID**를 입력하고, 선택적으로 **Client Secret**과 **Scopes**를 입력합니다. + + + + 적절한 **Token Auth Method**를 선택합니다. 대부분의 제공자는 기본값인 **Standard (POST body)**를 사용합니다. 일부 오래된 제공자는 **Basic Auth (header)**를 요구합니다. + + + + 제공자가 지원하는 경우 **PKCE Supported**를 체크합니다. PKCE는 인증 코드 흐름에 추가 보안 계층을 제공하며 모든 새 통합에 권장됩니다. + + + + **Create MCP Server**를 클릭합니다. OAuth 제공자로 리디렉션되어 접근을 인증합니다. 인증 완료 후 CrewAI가 토큰을 저장하고 필요에 따라 자동으로 갱신합니다. + + + +## 커스텀 MCP 서버 사용하기 + +연결이 완료되면 커스텀 MCP 서버의 도구가 **Tools & Integrations** 페이지에서 기본 제공 연결과 함께 표시됩니다. 다음을 수행할 수 있습니다: + +- 다른 CrewAI 도구와 마찬가지로 crew의 **에이전트에 도구를 할당**합니다. +- **가시성을 관리**하여 어떤 팀원이 서버를 사용할 수 있는지 제어합니다. +- Connections 목록에서 언제든지 연결을 **편집하거나 제거**합니다. + + +MCP 서버에 접근할 수 없거나 자격 증명이 만료되면 해당 서버를 사용하는 도구 호출이 실패합니다. 서버 URL이 안정적이고 자격 증명이 최신 상태인지 확인하세요. + + + + 커스텀 MCP 서버 구성 또는 문제 해결에 대한 도움이 필요하면 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/datadog.mdx b/docs/v1.15.1/ko/enterprise/guides/datadog.mdx new file mode 100644 index 000000000..0d6016bf1 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/datadog.mdx @@ -0,0 +1,295 @@ +--- +title: "Datadog 통합" +description: "Datadog Agent 또는 Datadog의 OTLP 수집을 통해 자체 호스팅 CrewAI AMP 배포를 Datadog에서 모니터링하세요 — 두 경로 모두 동일한 구조화된 패싯을 생성하므로 기성 운영 대시보드를 가져올 수 있습니다." +icon: "dog" +mode: "wide" +--- + + +**번역 진행 중** — 콘텐츠가 영어로 표시됩니다. + + +CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes. + + +For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs). + + +## Choose a path + +CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure. + + + + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + + **Setup:** + 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). + 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. + 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + + **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. + + + CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend. + + **Setup:** + 1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**. + 2. Configure the connection: + - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/): + - `otlp.datadoghq.com` (US1) + - `otlp.us3.datadoghq.com` (US3) + - `otlp.us5.datadoghq.com` (US5) + - `otlp.datadoghq.eu` (EU1) + - `otlp.ap1.datadoghq.com` (AP1) + - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + 3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list. + 4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step. + + ![Datadog collector configuration](/images/crewai-otel-collector-datadog.png) + + **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup. + + + +Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice. + +## Log schema reference + + +This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). + + +When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. + +### Why JSON output + + + + Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field. + + + Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration. + + + Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces. + + + The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed. + + + +### Enabling JSON output + +`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. + +```shell +CREWAI_LOG_FORMAT=json +``` + +Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. + + + The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. + + +### Example events + +A single info-level log inside an active automation kickoff: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:23.482914Z", + "level": "INFO", + "logger": "crewai_enterprise.utilities.pii_redaction", + "crewai_version": "1.14.7", + "msg": "PII tracking state reset (engines preserved)", + "automation_id": "12", + "task_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow" +} +``` + +An error with a Python exception is collapsed into a single event with the traceback as a string: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:31.218450Z", + "level": "ERROR", + "logger": "api.tasks.flow_run_task", + "crewai_version": "1.14.7", + "msg": "Flow execution failed", + "automation_id": "12", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow", + "exception": { + "type": "ValueError", + "message": "Topic cannot be empty", + "stacktrace": "Traceback (most recent call last):\n File \"/app/flow.py\", line 42, in summarize\n ...\nValueError: Topic cannot be empty\n" + } +} +``` + +The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. + +### Schema v1 fields + +Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded. + +| Field | Type | Always present | Source | +|-------|------|----------------|--------| +| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. | +| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. | +| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. | +| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. | +| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. | +| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). | +| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). | +| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. | +| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. | +| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. | +| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. | +| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. | +| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. | +| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. | + + + Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable. + + +### Stability promise + +The `schema` field declares the contract. Within `v1`, CrewAI commits to: + +- **Never removing a field** that customers may have built queries or dashboards against. +- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle. +- **Adding new fields** at any time. Consumers should ignore unknown top-level keys. + +When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate. + +## Prerequisite: promote facets + +Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account. + + + + Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event. + + + Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**. + + - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id` + - `crewai_version`, `model_id` + - `exception.type`, `exception.message` + + Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard. + + + +## Import the dashboard + + + + Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine. + + + Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**. + + + Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**. + + Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range. + + + + + Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI. + + +## What you get + +The dashboard is organized into four sections plus a placeholder for a custom drill-down widget: + +| Section | Widgets | Useful for | +|---------|---------|------------| +| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). | +| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. | +| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. | +| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. | +| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. | + +Three template variables at the top of the dashboard re-scope every widget at once: + +- **`$automation`** — filter to a single automation by name. +- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior). +- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account). + +## Verify ingestion + +Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path: + + + + Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. + + If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + + + Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). + + If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved. + + + +## Customize + +The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing. + +### Add a Recent Errors log stream + +The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures: + +1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group. +2. Drag in a **Log Stream** widget. +3. Set the filter query to `status:error $automation $version $service`. +4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`. +5. Sort by most recent, limit to 25 entries. + +Clicking any row jumps to Logs Explorer with the same filter pre-applied. + +### Add p95 latency + +Logs don't include execution duration by default. Two ways to add a latency widget: + +- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration. +- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM. + +### Re-scope to multiple deployments + +The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +|---------|--------------|-----| +| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | +| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | +| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | + +## Next steps + + + + Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends. + + + Reference for customizing widget queries against the structured facets above. + + diff --git a/docs/v1.15.1/ko/enterprise/guides/deploy-to-amp.mdx b/docs/v1.15.1/ko/enterprise/guides/deploy-to-amp.mdx new file mode 100644 index 000000000..c1733f0ae --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/deploy-to-amp.mdx @@ -0,0 +1,449 @@ +--- +title: "AMP에 배포하기" +description: "Crew 또는 Flow를 CrewAI AMP에 배포하기" +icon: "rocket" +mode: "wide" +--- + + + 로컬에서 또는 Crew Studio를 통해 Crew나 Flow를 생성한 후, 다음 단계는 이를 CrewAI AMP + 플랫폼에 배포하는 것입니다. 본 가이드에서는 다양한 배포 방법을 다루며, + 여러분의 워크플로우에 가장 적합한 방식을 선택할 수 있도록 안내합니다. + + +## 사전 준비 사항 + + + + 로컬에서 성공적으로 실행되는 Crew 또는 Flow가 있어야 합니다. + [배포 준비 가이드](/ko/enterprise/guides/prepare-for-deployment)를 따라 프로젝트 구조를 확인하세요. + + + 코드가 GitHub 저장소에 있어야 합니다(GitHub 연동 방식의 경우). + + + + + **Crews vs Flows**: 두 프로젝트 유형 모두 CrewAI AMP에서 "자동화"로 배포할 수 있습니다. + 배포 과정은 동일하지만, 프로젝트 구조가 다릅니다. + 자세한 내용은 [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요. + + +## 옵션 1: CrewAI CLI를 사용한 배포 + +CLI는 로컬에서 개발된 Crew 또는 Flow를 AMP 플랫폼에 가장 빠르게 배포할 수 있는 방법을 제공합니다. +CLI는 `pyproject.toml`에서 프로젝트 유형을 자동으로 감지하고 그에 맞게 빌드합니다. + + + + 아직 설치하지 않았다면 CrewAI CLI를 설치하세요: + + ```bash + pip install crewai[tools] + ``` + + + CLI는 기본 CrewAI 패키지에 포함되어 있지만, `[tools]` 추가 옵션을 사용하면 모든 배포 종속성을 함께 설치할 수 있습니다. + + + + + + 먼저, CrewAI AMP 플랫폼에 CLI를 인증해야 합니다: + + ```bash + # 이미 CrewAI AMP 계정이 있거나 새로 생성하고 싶을 때: + crewai login + ``` + + 위 명령어를 실행하면 CLI가 다음을 진행합니다: + 1. URL과 고유 기기 코드를 표시합니다 + 2. 브라우저를 열어 인증 페이지로 이동합니다 + 3. 기기 확인을 요청합니다 + 4. 인증 과정을 완료합니다 + + 인증이 성공적으로 완료되면 터미널에 확인 메시지가 표시됩니다! + + + + + + 프로젝트 디렉터리에서 다음 명령어를 실행하세요: + + ```bash + crewai deploy create + ``` + + 이 명령어는 다음을 수행합니다: + 1. GitHub 저장소 정보를 감지합니다 + 2. 로컬 `.env` 파일의 환경 변수를 식별합니다 + 3. 이러한 변수를 Enterprise 플랫폼으로 안전하게 전송합니다 + 4. 고유 식별자가 부여된 새 배포를 만듭니다 + + 성공적으로 생성되면 다음과 같은 메시지가 표시됩니다: + ```shell + Deployment created successfully! + Name: your_project_name + Deployment ID: 01234567-89ab-cdef-0123-456789abcdef + Current Status: Deploy Enqueued + ``` + + + + + + 다음 명령어로 배포 상태를 추적할 수 있습니다: + + ```bash + crewai deploy status + ``` + + 빌드 과정의 상세 로그가 필요하다면: + + ```bash + crewai deploy logs + ``` + + + 첫 배포는 보통 약 1분 정도 소요됩니다. + + + + + +## 추가 CLI 명령어 + +CrewAI CLI는 배포를 관리하기 위한 여러 명령어를 제공합니다: + +```bash +# 모든 배포 목록 확인 +crewai deploy list + +# 배포 상태 확인 +crewai deploy status + +# 배포 로그 보기 +crewai deploy logs + +# 코드 변경 후 업데이트 푸시 +crewai deploy push + +# 배포 삭제 +crewai deploy remove +``` + +## 옵션 2: 웹 인터페이스를 통한 직접 배포 + +GitHub 계정을 연결하여 CrewAI AMP 웹 인터페이스를 통해 Crew 또는 Flow를 직접 배포할 수도 있습니다. 이 방법은 로컬 머신에서 CLI를 사용할 필요가 없습니다. 플랫폼은 자동으로 프로젝트 유형을 감지하고 적절하게 빌드를 처리합니다. + + + + + +Crew를 GitHub 저장소에 푸시해야 합니다. 아직 Crew를 만들지 않았다면, [이 튜토리얼](/ko/quickstart)을 따라할 수 있습니다. + + + + + + 1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다. + 2. "Connect GitHub" 버튼을 클릭합니다. + + + ![Connect GitHub Button](/images/enterprise/connect-github.png) + + + + + + + GitHub 계정을 연결한 후 배포할 저장소를 선택할 수 있습니다: + + + ![Select Repository](/images/enterprise/select-repo.png) + + + + Crew 또는 Flow가 모노레포 하위 폴더 안에 있다면 배포 전에 + **Advanced**를 펼치고 작업 디렉터리를 설정하세요. + [모노레포 배포](/ko/enterprise/guides/monorepo-deployments)를 참조하세요. + + + + + + + 배포 전에, LLM 제공업체 또는 기타 서비스에 연결할 환경 변수를 설정해야 합니다: + + 1. 변수를 개별적으로 또는 일괄적으로 추가할 수 있습니다. + 2. 환경 변수는 `KEY=VALUE` 형식(한 줄에 하나씩)으로 입력합니다. + + + ![Set Environment Variables](/images/enterprise/set-env-variables.png) + + + + 프라이빗 Python 패키지를 사용하시나요? 여기에 레지스트리 자격 증명도 추가해야 합니다. + 필요한 변수는 [프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry)를 참조하세요. + + + + + + + 1. "Deploy" 버튼을 클릭하여 배포 프로세스를 시작합니다. + 2. 진행 바를 통해 진행 상황을 모니터링할 수 있습니다. + 3. 첫 번째 배포에는 일반적으로 약 1분 정도 소요됩니다 + + + ![Deploy Progress](/images/enterprise/deploy-progress.png) + + + 배포가 완료되면 다음을 확인할 수 있습니다: + - Crew의 고유 URL + - Crew API를 보호할 Bearer 토큰 + - 배포를 삭제해야 하는 경우 "Delete" 버튼 + + + + + +## 옵션 3: API를 통한 재배포 (CI/CD 통합) + +CI/CD 파이프라인에서 자동화된 배포를 위해 CrewAI API를 사용하여 기존 crew의 재배포를 트리거할 수 있습니다. 이 방법은 GitHub Actions, Jenkins 또는 기타 자동화 워크플로우에 특히 유용합니다. + + + + + CrewAI AMP 계정 설정에서 API 토큰을 생성합니다: + + 1. [app.crewai.com](https://app.crewai.com)으로 이동합니다 + 2. **Settings** → **Account** → **Personal Access Token**을 클릭합니다 + 3. 새 토큰을 생성하고 안전하게 복사합니다 + 4. 이 토큰을 CI/CD 시스템의 시크릿으로 저장합니다 + + + + + + 배포된 crew의 고유 식별자를 찾습니다: + + 1. CrewAI AMP 대시보드에서 **Automations**로 이동합니다 + 2. 기존 automation/crew를 선택합니다 + 3. **Additional Details**를 클릭합니다 + 4. **UUID**를 복사합니다 - 이것이 특정 crew 배포를 식별합니다 + + + + + + Deploy API 엔드포인트를 사용하여 재배포를 트리거합니다: + + ```bash + curl -i -X POST \ + -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \ + https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy + + # HTTP/2 200 + # content-type: application/json + # + # { + # "uuid": "your-automation-uuid", + # "status": "Deploy Enqueued", + # "public_url": "https://your-crew-deployment.crewai.com", + # "token": "your-bearer-token" + # } + ``` + + + Git에 연결되어 처음 생성된 automation의 경우, API가 재배포 전에 자동으로 저장소에서 최신 변경 사항을 가져옵니다. + + + + + + + 더 복잡한 배포 트리거가 있는 GitHub Actions 워크플로우 예시입니다: + + ```yaml + name: Deploy CrewAI Automation + + on: + push: + branches: [ main ] + pull_request: + types: [ labeled ] + release: + types: [ published ] + + jobs: + deploy: + runs-on: ubuntu-latest + if: | + (github.event_name == 'push' && github.ref == 'refs/heads/main') || + (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) || + (github.event_name == 'release') + steps: + - name: Trigger CrewAI Redeployment + run: | + curl -X POST \ + -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \ + https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy + ``` + + + `CREWAI_PAT`와 `CREWAI_AUTOMATION_UUID`를 저장소 시크릿으로 추가하세요. PR 배포의 경우 "deploy" 라벨을 추가하여 워크플로우를 트리거합니다. + + + + + + +## 배포된 Automation과 상호작용하기 + +배포가 완료되면 다음을 통해 crew에 접근할 수 있습니다: + +1. **REST API**: 플랫폼에서 아래의 주요 경로가 포함된 고유한 HTTPS 엔드포인트를 생성합니다: + + - `/inputs`: 필요한 입력 파라미터 목록 + - `/kickoff`: 제공된 입력값으로 실행 시작 + - `/status/{kickoff_id}`: 실행 상태 확인 + +2. **웹 인터페이스**: [app.crewai.com](https://app.crewai.com)에 방문하여 다음을 확인할 수 있습니다: + - **Status 탭**: 배포 정보, API 엔드포인트 세부 정보 및 인증 토큰 확인 + - **Run 탭**: Crew 구조의 시각적 표현 + - **Executions 탭**: 모든 실행 내역 + - **Metrics 탭**: 성능 분석 + - **Traces 탭**: 상세 실행 인사이트 + +### 실행 트리거하기 + +Enterprise 대시보드에서 다음 작업을 수행할 수 있습니다: + +1. Crew 이름을 클릭하여 상세 정보를 엽니다 +2. 관리 인터페이스에서 "Trigger Crew"를 선택합니다 +3. 나타나는 모달에 필요한 입력값을 입력합니다 +4. 파이프라인을 따라 실행의 진행 상황을 모니터링합니다 + +### 모니터링 및 분석 + +Enterprise 플랫폼은 포괄적인 가시성 기능을 제공합니다: + +- **실행 관리**: 활성 및 완료된 실행 추적 +- **트레이스**: 각 실행의 상세 분해 +- **메트릭**: 토큰 사용량, 실행 시간, 비용 +- **타임라인 보기**: 작업 시퀀스의 시각적 표현 + +### 고급 기능 + +Enterprise 플랫폼은 또한 다음을 제공합니다: + +- **환경 변수 관리**: API 키를 안전하게 저장 및 관리 +- **LLM 연결**: 다양한 LLM 공급자와의 통합 구성 +- **Custom Tools Repository**: 도구 생성, 공유 및 설치 +- **Crew Studio**: 코드를 작성하지 않고 채팅 인터페이스를 통해 crew 빌드 + +## 배포 실패 문제 해결 + +배포가 실패하면 다음과 같은 일반적인 문제를 확인하세요: + +### 빌드 실패 + +#### uv.lock 파일 누락 + +**증상**: 의존성 해결 오류와 함께 빌드 초기에 실패 + +**해결책**: lock 파일을 생성하고 커밋합니다: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + + + `uv.lock` 파일은 모든 배포에 필수입니다. 이 파일이 없으면 플랫폼에서 + 의존성을 안정적으로 설치할 수 없습니다. + + +#### 잘못된 프로젝트 구조 + +**증상**: "Could not find entry point" 또는 "Module not found" 오류 + +**해결책**: 프로젝트가 예상 구조와 일치하는지 확인합니다: + +- **JSON-first Crews**: `crew.jsonc` 또는 `crew.json`과 `agents/`를 프로젝트 루트에 둡니다 +- **클래식 Crews**: `src/project_name/main.py`에 `run()` 진입점을 둡니다 +- **Flows**: `src/project_name/main.py`에 `kickoff()` 진입점을 둡니다 + +자세한 구조 다이어그램은 [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요. + +#### 클래식 Crew의 CrewBase 데코레이터 누락 + +**증상**: "Crew not found", "Config not found" 또는 agent/task 구성 오류 + +**해결책**: 클래식 Python/YAML crew에서는 모든 crew 클래스가 `@CrewBase` 데코레이터를 사용하는지 확인합니다. JSON-first crew에는 이 데코레이터가 필요하지 않습니다. + +```python +from crewai.project import CrewBase, agent, crew, task + +@CrewBase # 이 데코레이터는 필수입니다 +class YourCrew(): + """Crew 설명""" + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + # ... 나머지 crew 정의 +``` + + + 이것은 Flow 프로젝트에 포함된 클래식 crew를 포함하여 클래식 Python crew 클래스에 적용됩니다. + JSON-first crew는 `crew.jsonc`와 `agents/`를 기준으로 검증됩니다. + + +#### 잘못된 pyproject.toml 타입 + +**증상**: 빌드는 성공하지만 런타임에서 실패하거나 예상치 못한 동작 + +**해결책**: `[tool.crewai]` 섹션이 프로젝트 유형과 일치하는지 확인합니다: + +```toml +# Crew 프로젝트의 경우: +[tool.crewai] +type = "crew" + +# Flow 프로젝트의 경우: +[tool.crewai] +type = "flow" +``` + +### 런타임 실패 + +#### LLM 연결 실패 + +**증상**: API 키 오류, "model not found" 또는 인증 실패 + +**해결책**: +1. LLM 제공업체의 API 키가 환경 변수에 올바르게 설정되어 있는지 확인합니다 +2. 환경 변수 이름이 코드에서 예상하는 것과 일치하는지 확인합니다 +3. 배포 전에 동일한 환경 변수로 로컬에서 테스트합니다 + +#### Crew 실행 오류 + +**증상**: Crew가 시작되지만 실행 중에 실패 + +**해결책**: +1. AMP 대시보드에서 실행 로그를 확인합니다 (Traces 탭) +2. 모든 도구에 필요한 API 키가 구성되어 있는지 확인합니다 +3. JSON-first crew의 경우 `crew.jsonc`와 `agents/`에서 참조한 파일을 검증합니다 +4. 클래식 crew의 경우 `agents.yaml`과 `tasks.yaml`이 유효한지 확인합니다 + + + 배포 문제 또는 AMP 플랫폼에 대한 문의 사항이 있으시면 지원팀에 연락해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/enable-crew-studio.mdx b/docs/v1.15.1/ko/enterprise/guides/enable-crew-studio.mdx new file mode 100644 index 000000000..8fbf5729d --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/enable-crew-studio.mdx @@ -0,0 +1,180 @@ +--- +title: "Crew Studio 활성화" +description: "CrewAI AOP에서 Crew Studio 활성화하기" +icon: "comments" +mode: "wide" +--- + + + Crew Studio는 대화형 인터페이스를 통해 빠르게 Crew를 스캐폴딩하거나 구축할 수 + 있는 강력한 **노코드/로우코드** 도구입니다. + + +## Crew Studio란? + +Crew Studio는 코드를 작성하지 않고도 AI agent crew를 생성할 수 있는 혁신적인 방법입니다. + + + ![Crew Studio Interface](/images/enterprise/crew-studio-interface.png) + + +Crew Studio를 사용하면 다음과 같은 작업이 가능합니다: + +- Crew Assistant와 채팅하여 문제를 설명 +- agent 및 task를 자동으로 생성 +- 적절한 tool 선택 +- 필요한 입력값 구성 +- 커스터마이징을 위한 다운로드 가능한 코드 생성 +- CrewAI AMP 플랫폼에 직접 배포 + +## 구성 단계 + +Crew Studio를 사용하기 전에 LLM 연결을 구성해야 합니다: + + + + CrewAI AMP 대시보드의 **LLM Connections** 탭으로 이동하여 새 LLM 연결을 만듭니다. + + + CrewAI에서 지원하는 원하는 LLM 공급자를 자유롭게 사용하실 수 있습니다. + + + LLM 연결을 구성하세요: + + - `Connection Name`(예: `OpenAI`)을 입력하세요. + - 모델 공급자를 선택하세요: `openai` 또는 `azure` + - Studio에서 생성되는 Crews에 사용할 모델을 선택하세요. + - 최소한 `gpt-4o`, `o1-mini`, `gpt-4o-mini`를 권장합니다. + - API 키를 환경 변수로 추가하세요: + - OpenAI의 경우: `OPENAI_API_KEY`에 API 키를 추가 + - Azure OpenAI의 경우: [이 글](https://blog.crewai.com/configuring-azure-openai-with-crewai-a-comprehensive-guide/)을 참고하여 구성 + - `Add Connection`을 클릭하여 구성을 저장하세요. + + + ![LLM 연결 구성](/images/enterprise/llm-connection-config.png) + + + + + + 설정이 완료되면 새 연결이 사용 가능한 연결 목록에 추가된 것을 볼 수 있습니다. + + + ![연결 추가됨](/images/enterprise/connection-added.png) + + + + + + 메인 메뉴에서 **Settings → Defaults**로 이동하여 LLM 기본값을 구성하세요: + + - 에이전트 및 기타 구성 요소의 기본 모델을 선택하세요 + - Crew Studio의 기본 구성을 설정하세요 + + 변경 사항을 적용하려면 `Save Settings`를 클릭하세요. + + + ![LLM 기본값 구성](/images/enterprise/llm-defaults.png) + + + + + +## Crew Studio 사용하기 + +LLM 연결과 기본 설정을 구성했다면 이제 Crew Studio 사용을 시작할 준비가 완료되었습니다! + + + + CrewAI AMP 대시보드에서 **Studio** 섹션으로 이동하세요. + + + + Crew Assistant와 대화를 시작하며 해결하고자 하는 문제를 설명하세요: + + ```md + I need a crew that can research the latest AI developments and create a summary report. + ``` + + Crew Assistant는 귀하의 요구 사항을 더 잘 이해하기 위해 추가 질문을 할 것입니다. + + + + + 생성된 crew 구성을 검토하세요. 구성에는 다음이 포함됩니다: + + - 에이전트 및 그들의 역할 + - 수행할 작업 + - 필요한 입력값 + - 사용할 도구 + + 이 단계에서 구성 내용을 세부적으로 수정할 수 있습니다. + + + + + 구성에 만족하면 다음을 수행할 수 있습니다: + + - 생성된 코드를 다운로드하여 로컬에서 커스터마이징 + - crew를 CrewAI AMP 플랫폼에 직접 배포 + - 구성을 수정하고 crew를 재생성 + + + + + 배포 후 샘플 입력으로 crew를 테스트하여 기대한 대로 동작하는지 확인하세요. + + + + + 최상의 결과를 얻으려면 crew가 달성해야 할 목표를 명확하고 상세하게 설명하세요. + 원하는 입력값과 예상 결과를 설명에 포함시키는 것이 좋습니다. + + +## 예시 워크플로우 + +다음은 Crew Studio를 사용하여 crew를 생성하는 일반적인 워크플로우입니다: + + + + 먼저 문제를 설명하세요: + + ```md + I need a crew that can analyze financial news and provide investment recommendations + ``` + + + + + crew assistant가 요구 사항을 구체화할 수 있도록 하는 추가 질문에 답변하세요. + + + + 생성된 crew 계획을 검토하세요. 여기에는 다음과 같은 항목이 포함될 수 있습니다: + + - 금융 뉴스를 수집하는 Research Agent + - 데이터를 해석하는 Analysis Agent + - 투자 조언을 제공하는 Recommendations Agent + + + + + 계획을 승인하거나 필요하다면 변경을 요청하세요. + + + + 사용자화를 위해 코드를 다운로드하거나 플랫폼에 직접 배포하세요. + + + + 샘플 입력으로 crew를 테스트하고 필요에 따라 개선하세요. + + + + + Crew Studio 또는 기타 CrewAI AMP 기능 지원이 필요하다면 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/gmail-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/gmail-trigger.mdx new file mode 100644 index 000000000..4277c5501 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/gmail-trigger.mdx @@ -0,0 +1,96 @@ +--- +title: "Gmail Trigger" +description: "Trigger automations when Gmail events occur (e.g., new emails, labels)." +icon: "envelope" +mode: "wide" +--- + +## Overview + +Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter. + + + Make sure Gmail is connected in Tools & Integrations and the trigger is + enabled for your deployment. + + +## Enabling the Gmail Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Gmail** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Process new emails + +When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload. + +```python +@CrewBase +class GmailProcessingCrew: + @agent + def parser(self) -> Agent: + return Agent( + config=self.agents_config['parser'], + ) + + @task + def parse_gmail_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_gmail_payload'], + agent=self.parser(), + ) + + @task + def act_on_email(self) -> Task: + return Task( + config=self.tasks_config['act_on_email'], + agent=self.parser(), + ) +``` + +The Gmail payload will be available via the standard context mechanisms. + +### 로컬에서 테스트 + +CrewAI CLI를 사용하여 Gmail 트리거 통합을 로컬에서 테스트하세요: + +```bash +# 사용 가능한 모든 트리거 보기 +crewai triggers list + +# 실제 payload로 Gmail 트리거 시뮬레이션 +crewai triggers run gmail/new_email_received +``` + +`crewai triggers run` 명령은 완전한 Gmail payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다. + + + 개발 중에는 `crewai triggers run gmail/new_email_received`을 사용하세요 + (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다. + + +## Monitoring Executions + +Track history and performance of triggered runs: + + + List of executions triggered by automation + + +## Troubleshooting + +- Ensure Gmail is connected in Tools & Integrations +- Verify the Gmail Trigger is enabled on the Triggers tab +- `crewai triggers run gmail/new_email_received`로 로컬 테스트하여 정확한 payload 구조를 확인하세요 +- Check the execution logs and confirm the payload is passed as `crewai_trigger_payload` +- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님) diff --git a/docs/v1.15.1/ko/enterprise/guides/google-calendar-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/google-calendar-trigger.mdx new file mode 100644 index 000000000..c6b250a49 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/google-calendar-trigger.mdx @@ -0,0 +1,82 @@ +--- +title: "Google Calendar Trigger" +description: "Kick off crews when Google Calendar events are created, updated, or cancelled" +icon: "calendar" +mode: "wide" +--- + +## Overview + +Use the Google Calendar trigger to launch automations whenever calendar events change. Common use cases include briefing a team before a meeting, notifying stakeholders when a critical event is cancelled, or summarizing daily schedules. + + + Make sure Google Calendar is connected in **Tools & Integrations** and enabled + for the deployment you want to automate. + + +## Enabling the Google Calendar Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Google Calendar** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize meeting details + +The snippet below mirrors the `calendar-event-crew.py` example in the trigger repository. It parses the payload, analyses the attendees and timing, and produces a meeting brief for downstream tools. + +```python +from calendar_event_crew import GoogleCalendarEventTrigger + +crew = GoogleCalendarEventTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": calendar_payload, +}) +print(result.raw) +``` + +Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields. + +## 로컬에서 테스트 + +CrewAI CLI를 사용하여 Google Calendar 트리거 통합을 로컬에서 테스트하세요: + +```bash +# 사용 가능한 모든 트리거 보기 +crewai triggers list + +# 실제 payload로 Google Calendar 트리거 시뮬레이션 +crewai triggers run google_calendar/event_changed +``` + +`crewai triggers run` 명령은 완전한 Calendar payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다. + + + 개발 중에는 `crewai triggers run google_calendar/event_changed`를 사용하세요 + (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다. + + +## Monitoring Executions + +The **Executions** list in the deployment dashboard tracks every triggered run and surfaces payload metadata, output summaries, and errors. + + + List of executions triggered by automation + + +## Troubleshooting + +- Ensure the correct Google account is connected and the trigger is enabled +- `crewai triggers run google_calendar/event_changed`로 로컬 테스트하여 정확한 payload 구조를 확인하세요 +- Confirm your workflow handles all-day events (payloads use `start.date` and `end.date` instead of timestamps) +- Check execution logs if reminders or attendee arrays are missing—calendar permissions can limit fields in the payload +- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님) diff --git a/docs/v1.15.1/ko/enterprise/guides/google-drive-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/google-drive-trigger.mdx new file mode 100644 index 000000000..9a05c7c4f --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/google-drive-trigger.mdx @@ -0,0 +1,79 @@ +--- +title: "Google Drive Trigger" +description: "Respond to Google Drive file events with automated crews" +icon: "folder" +mode: "wide" +--- + +## Overview + +Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change. + + + Connect Google Drive in **Tools & Integrations** and confirm the trigger is + enabled for the automation you want to monitor. + + +## Enabling the Google Drive Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Google Drive** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize file activity + +The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary. + +```python +from drive_file_crew import GoogleDriveFileTrigger + +crew = GoogleDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": drive_payload, +}) +``` + +## 로컬에서 테스트 + +CrewAI CLI를 사용하여 Google Drive 트리거 통합을 로컬에서 테스트하세요: + +```bash +# 사용 가능한 모든 트리거 보기 +crewai triggers list + +# 실제 payload로 Google Drive 트리거 시뮬레이션 +crewai triggers run google_drive/file_changed +``` + +`crewai triggers run` 명령은 완전한 Drive payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다. + + + 개발 중에는 `crewai triggers run google_drive/file_changed`를 사용하세요 + (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다. + + +## Monitoring Executions + +Track history and performance of triggered runs with the **Executions** list in the deployment dashboard. + + + List of executions triggered by automation + + +## Troubleshooting + +- Verify Google Drive is connected and the trigger toggle is enabled +- `crewai triggers run google_drive/file_changed`로 로컬 테스트하여 정확한 payload 구조를 확인하세요 +- If a payload is missing permission data, ensure the connected account has access to the file or folder +- The trigger sends file IDs only; use the Drive API if you need to fetch binary content during the crew run +- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님) diff --git a/docs/v1.15.1/ko/enterprise/guides/hubspot-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/hubspot-trigger.mdx new file mode 100644 index 000000000..a21c52f9d --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/hubspot-trigger.mdx @@ -0,0 +1,61 @@ +--- +title: "HubSpot 트리거" +description: "HubSpot 워크플로우에서 CrewAI 크루를 직접 트리거하세요" +icon: "hubspot" +mode: "wide" +--- + +이 가이드는 HubSpot Workflows에서 직접 crew를 시작할 수 있도록 CrewAI AOP용 HubSpot 트리거를 설정하는 단계별 과정을 제공합니다. + +## 사전 준비 사항 + +- CrewAI AMP 계정 +- [HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows) 기능이 활성화된 HubSpot 계정 + +## 설정 단계 + + + + - `CrewAI AMP 계정 > 트리거`에 로그인합니다. - 사용 가능한 트리거 목록에서 + `HubSpot`을 선택합니다. - CrewAI AOP와 연결하고자 하는 HubSpot 계정을 + 선택합니다. - 화면에 나타나는 안내에 따라 CrewAI AOP가 HubSpot 계정에 + 접근하도록 승인합니다. - HubSpot이 CrewAI AOP와 성공적으로 연결되면 확인 + 메시지가 표시됩니다. + + + - `HubSpot 계정 > 자동화 > 워크플로우 > 새 워크플로우`에 로그인합니다. - + 필요에 맞는 워크플로우 유형을 선택합니다 (예: 처음부터 시작). - 워크플로우 + 빌더에서 더하기(+) 아이콘을 클릭하여 새로운 작업을 추가합니다. - `통합 앱 > + CrewAI > Crew 시작하기`를 선택합니다. - 시작할 Crew를 선택합니다. - `저장`을 + 클릭하여 워크플로우에 작업을 추가합니다. + + HubSpot Workflow 1 + + + + - Crew 시작 단계 이후, 더하기(+) 아이콘을 클릭하여 새로운 작업을 추가합니다. + - 예를 들어, 내부 이메일 알림을 전송하려면 `커뮤니케이션 > 내부 이메일 알림 + 전송`을 선택합니다. - 본문 필드에서 `데이터 삽입`을 클릭하고, `다음에서 속성 + 또는 작업 결과 보기 > 작업 결과 > Crew 결과`를 선택하여 이메일에 Crew + 데이터를 포함합니다. + + HubSpot Workflow 2 + + - 필요에 따라 추가 작업을 구성합니다. - 모든 워크플로우 단계를 + 검토하여 올바르게 설정되었는지 확인합니다. - 워크플로우를 활성화합니다. + + HubSpot Workflow 3 + + + + +사용 가능한 작업과 사용자 지정 옵션에 대한 자세한 정보는 [HubSpot 워크플로우 문서](https://knowledge.hubspot.com/workflows/create-workflows)를 참고하세요. diff --git a/docs/v1.15.1/ko/enterprise/guides/human-in-the-loop.mdx b/docs/v1.15.1/ko/enterprise/guides/human-in-the-loop.mdx new file mode 100644 index 000000000..924fddc6c --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/human-in-the-loop.mdx @@ -0,0 +1,157 @@ +--- +title: "HITL 워크플로우" +description: "CrewAI에서 의사결정 향상을 위한 Human-In-The-Loop 워크플로우 구현 방법을 알아보세요" +icon: "user-check" +mode: "wide" +--- + +인간-중심(Human-In-The-Loop, HITL)은 인공지능과 인간 전문 지식을 결합하여 의사결정을 강화하고 작업 결과를 향상시키는 강력한 접근 방식입니다. 이 가이드는 CrewAI Enterprise 내에서 HITL을 구현하는 방법을 보여줍니다. + +## CrewAI의 HITL 접근 방식 + +CrewAI는 human-in-the-loop 워크플로우를 구현하기 위한 두 가지 접근 방식을 제공합니다: + +| 접근 방식 | 적합한 용도 | 버전 | +|----------|----------|---------| +| **Flow 기반** (`@human_feedback` 데코레이터) | Enterprise UI를 사용한 프로덕션, 이메일 우선 워크플로우, 전체 플랫폼 기능 | **1.8.0+** | +| **Webhook 기반** | 커스텀 통합, 외부 시스템 (Slack, Teams 등), 레거시 설정 | 모든 버전 | + +## Enterprise 플랫폼과 Flow 기반 HITL + + +`@human_feedback` 데코레이터는 **CrewAI 버전 1.8.0 이상**이 필요합니다. + + +Flow에서 `@human_feedback` 데코레이터를 사용하면, CrewAI Enterprise는 이메일 주소가 있는 누구나 검토 요청에 응답할 수 있는 **이메일 우선 HITL 시스템**을 제공합니다: + + + + 응답자가 이메일 알림을 받고 직접 회신할 수 있습니다—로그인이 필요 없습니다. + + + 원할 때 Enterprise 대시보드에서 HITL 요청을 검토하고 응답하세요. + + + 메서드 패턴에 따라 특정 이메일로 요청을 라우팅하거나 Flow 상태에서 가져오세요. + + + 타임아웃 내에 인간이 응답하지 않을 경우 자동 대체 응답을 구성하세요. + + + +### 주요 이점 + +- **외부 응답자**: 플랫폼 사용자가 아니어도 이메일이 있는 누구나 응답 가능 +- **동적 할당**: Flow 상태에서 담당자 이메일 가져오기 (예: `account_owner_email`) +- **간단한 구성**: 이메일 기반 라우팅은 사용자/역할 관리보다 설정이 쉬움 +- **배포 생성자 대체**: 라우팅 규칙이 일치하지 않으면 배포 생성자에게 알림 + + +`@human_feedback` 데코레이터의 구현 세부 사항은 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요. + + +## Webhook 기반 HITL 워크플로 설정 + +Slack, Microsoft Teams 또는 자체 애플리케이션과 같은 외부 시스템과의 커스텀 통합을 위해 webhook 기반 접근 방식을 사용할 수 있습니다: + + + + 사람 입력이 활성화된 상태로 작업을 설정하세요: + + Crew Human Input + + + + + crew를 시작할 때 인간 입력을 위한 webhook URL을 포함하세요: + + Crew Webhook URL + + + + + crew가 사람 입력이 필요한 작업을 완료하면 다음 정보를 포함한 webhook 알림을 받게 됩니다: + - **Execution ID** + - **Task ID** + - **Task output** + + + + 시스템이 `Pending Human Input` 상태에서 일시 중지됩니다. 작업 출력을 신중하게 검토하세요. + + + + 다음 정보를 포함하여 crew의 resume endpoint를 호출하세요: + + Crew Resume Endpoint + + + + **중요: Webhook URL을 다시 제공해야 합니다**: + kickoff 호출에서 사용한 것과 동일한 webhook URL(`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`)을 resume 호출에서 **반드시** 제공해야 합니다. Webhook 설정은 kickoff에서 자동으로 전달되지 **않으므로**, 작업 완료, 에이전트 단계, crew 완료에 대한 알림을 계속 받으려면 resume 요청에 명시적으로 포함해야 합니다. + + + Webhook을 포함한 resume 호출 예시: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "훌륭한 작업입니다! 더 자세한 내용을 추가해주세요.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **피드백이 작업 실행에 미치는 영향**: + 피드백 전체 내용이 이후 작업 실행을 위한 추가 컨텍스트로 통합되므로 피드백 제공 시 신중함이 매우 중요합니다. + + 이는 다음을 의미합니다: + - 피드백에 입력한 모든 정보가 작업의 컨텍스트 일부가 됩니다. + - 관련 없는 상세 정보는 부정적인 영향을 줄 수 있습니다. + - 간결하고 관련성 높은 피드백이 작업의 집중도와 효율성을 유지하는 데 도움이 됩니다. + - 제출 전 항상 피드백을 신중히 검토하여 작업 실행을 긍정적으로 안내할 수 있는 관련 정보만 포함되어 있는지 확인하세요. + + + 부정적인 피드백을 제공하는 경우: + - crew가 귀하의 피드백에서 추가된 컨텍스트와 함께 작업을 재시도합니다. + - 추가 확인을 위한 다른 webhook 알림을 받게 됩니다. + - 만족할 때까지 4-6단계를 반복하세요. + + + + 긍정적인 피드백을 제출하면 실행이 다음 단계로 진행됩니다. + + + +## 모범 사례 + +- **구체적으로 작성하세요**: 해당 작업에 직접적으로 관련된 명확하고 실행 가능한 피드백을 제공하세요 +- **관련성 유지**: 작업 수행 개선에 도움이 되는 정보만 포함하세요 +- **적시에 응답하세요**: 워크플로우 지연을 피하기 위해 HITL 프롬프트에 신속하게 응답하세요 +- **꼼꼼하게 검토하세요**: 제출 전에 피드백을 다시 확인하여 정확성을 보장하세요 + +## 일반적인 사용 사례 + +HITL 워크플로우는 특히 다음과 같은 경우에 유용합니다: +- 품질 보증 및 검증 +- 복잡한 의사 결정 시나리오 +- 민감하거나 위험도가 높은 작업 +- 인간의 판단이 필요한 창의적 작업 +- 준수 및 규제 검토 + +## 자세히 알아보기 + + + + 이메일 알림, 라우팅 규칙, 자동 응답 및 분석을 포함한 전체 Enterprise Flow HITL 플랫폼 기능을 살펴보세요. + + + Flow에서 `@human_feedback` 데코레이터 구현 가이드. + + diff --git a/docs/v1.15.1/ko/enterprise/guides/kickoff-crew.mdx b/docs/v1.15.1/ko/enterprise/guides/kickoff-crew.mdx new file mode 100644 index 000000000..fcea67412 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/kickoff-crew.mdx @@ -0,0 +1,182 @@ +--- +title: "Kickoff Crew" +description: "CrewAI AOP에서 Crew를 시작하세요" +icon: "flag-checkered" +mode: "wide" +--- + +## 개요 + +Crew를 CrewAI AMP 플랫폼에 배포한 후에는 웹 인터페이스 또는 API를 통해 실행을 시작할 수 있습니다. 이 가이드는 두 가지 접근 방식을 모두 다룹니다. + +## 방법 1: 웹 인터페이스 사용 + +### 1단계: 배포된 Crew로 이동하기 + +1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다. +2. 프로젝트 목록에서 crew 이름을 클릭합니다. +3. crew의 상세 페이지로 이동합니다. + +![Crew Dashboard](/images/enterprise/crew-dashboard.png) + +### 2단계: 실행 시작 + +crew의 상세 페이지에서 실행을 시작할 수 있는 두 가지 옵션이 있습니다: + +#### 옵션 A: 빠른 시작 + +1. Test Endpoints 섹션에서 `Kickoff` 링크를 클릭합니다. +2. JSON 에디터에서 crew에 필요한 입력 파라미터를 입력합니다. +3. `Send Request` 버튼을 클릭합니다. + +![Kickoff Endpoint](/images/enterprise/kickoff-endpoint.png) + +#### 옵션 B: 시각적 인터페이스 사용 + +1. crew 상세 페이지에서 `Run` 탭을 클릭합니다. +2. 양식 필드에 필요한 입력값을 입력합니다. +3. `Run Crew` 버튼을 클릭합니다. + +![Run Crew](/images/enterprise/run-crew.png) + +### 3단계: 실행 진행 상황 모니터링 + +실행을 시작한 후: + +1. `kickoff_id`가 포함된 응답을 받게 됩니다. - **이 ID를 복사하세요** +2. 이 ID는 실행을 추적하는 데 필수적입니다 + +![작업 ID 복사](/images/enterprise/copy-task-id.png) + +### 4단계: 실행 상태 확인 + +실행 진행 상황을 모니터링하려면: + +1. Test Endpoints 섹션에서 "Status" 엔드포인트를 클릭하세요 +2. 지정된 필드에 `kickoff_id`를 붙여넣으세요 +3. "Get Status" 버튼을 클릭하세요 + +![Get Status](/images/enterprise/get-status.png) + +상태 응답에는 다음이 표시됩니다: + +- 현재 실행 상태(`running`, `completed` 등) +- 진행 중인 작업에 대한 세부 정보 +- 지금까지 생성된 모든 출력 + +### 5단계: 최종 결과 보기 + +실행이 완료되면: + +1. 상태가 `completed`로 변경됩니다. +2. 전체 실행 결과와 출력을 확인할 수 있습니다. +3. 더 자세한 내용을 보려면 crew 상세 페이지의 `Executions` 탭을 확인하세요. + +## 방법 2: API 사용 + +CrewAI AMP REST API를 사용하여 프로그래밍 방식으로 crews를 시작할 수도 있습니다. + +### 인증 + +모든 API 요청에는 인증을 위한 베어러 토큰이 필요합니다: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +베어러 토큰은 crew의 상세 페이지의 Status 탭에서 확인할 수 있습니다. + +### 크루 상태 확인 + +작업을 실행하기 전에 크루가 정상적으로 실행되고 있는지 확인할 수 있습니다: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +요청이 성공하면 크루가 정상적으로 동작 중임을 나타내는 메시지가 반환됩니다: + +``` +Healthy% +``` + +### 1단계: 필요한 입력값 확인 + +먼저, crew에서 요구하는 입력값이 무엇인지 확인합니다: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +응답은 예를 들어 다음과 같이 필수 입력 파라미터 배열을 포함한 JSON 객체로 반환됩니다: + +```json +{ "inputs": ["topic", "current_year"] } +``` + +이 예시에서는 해당 crew에서 두 개의 입력값인 `topic`과 `current_year`를 필요로 함을 보여줍니다. + +### 2단계: kickoff 실행 + +필수 입력값을 제공하여 실행을 시작합니다: + +```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 +``` + +응답에는 추적에 필요한 `kickoff_id`가 포함됩니다: + +```json +{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" } +``` + +### 3단계: 실행 상태 확인 + +kickoff_id를 사용하여 실행 진행 상황을 모니터링하세요: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv +``` + +## 실행 처리 + +### 장기 실행 + +오랜 시간이 걸릴 수 있는 실행의 경우: + +1. 주기적으로 상태를 확인하는 폴링 메커니즘을 구현하는 것을 고려하세요 +2. 실행 완료 시 알림을 받을 수 있도록 웹훅(가능한 경우)을 사용하세요 +3. 잠재적인 타임아웃에 대비하여 오류 처리를 구현하세요 + +### 실행 컨텍스트 + +실행 컨텍스트에는 다음이 포함됩니다: + +- 시작 시 제공된 입력값 +- 배포 중에 구성된 환경 변수 +- 태스크 간에 유지되는 상태 + +### 실행 실패 디버깅 + +실행이 실패할 경우: + +1. "Executions" 탭에서 자세한 로그를 확인하세요 +2. "Traces" 탭에서 단계별 실행 세부 정보를 검토하세요 +3. 트레이스 세부 정보에서 LLM 응답과 도구 사용 내역을 확인하세요 + + + 실행 문제 또는 엔터프라이즈 플랫폼 관련 질문이 있으신 경우, 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/microsoft-teams-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/microsoft-teams-trigger.mdx new file mode 100644 index 000000000..e1bd38a94 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/microsoft-teams-trigger.mdx @@ -0,0 +1,70 @@ +--- +title: "Microsoft Teams Trigger" +description: "Kick off crews from Microsoft Teams chat activity" +icon: "microsoft" +mode: "wide" +--- + +## Overview + +Use the Microsoft Teams trigger to start automations whenever a new chat is created. Common patterns include summarizing inbound requests, routing urgent messages to support teams, or creating follow-up tasks in other systems. + + + Confirm Microsoft Teams is connected under **Tools & Integrations** and + enabled in the **Triggers** tab for your deployment. + + +## Enabling the Microsoft Teams Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Microsoft Teams** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize a new chat thread + +```python +from teams_chat_created_crew import MicrosoftTeamsChatTrigger + +crew = MicrosoftTeamsChatTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": teams_payload, +}) +print(result.raw) +``` + +The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team. + +## 로컬에서 테스트 + +CrewAI CLI를 사용하여 Microsoft Teams 트리거 통합을 로컬에서 테스트하세요: + +```bash +# 사용 가능한 모든 트리거 보기 +crewai triggers list + +# 실제 payload로 Microsoft Teams 트리거 시뮬레이션 +crewai triggers run microsoft_teams/teams_message_created +``` + +`crewai triggers run` 명령은 완전한 Teams payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다. + + + 개발 중에는 `crewai triggers run microsoft_teams/teams_message_created`를 + 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 + 받습니다. + + +## Troubleshooting + +- Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions +- `crewai triggers run microsoft_teams/teams_message_created`로 로컬 테스트하여 정확한 payload 구조를 확인하세요 +- Confirm the webhook subscription in Microsoft 365 is still valid if payloads stop arriving +- Review execution logs for payload shape mismatches—Graph notifications may omit fields when a chat is private or restricted +- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님) diff --git a/docs/v1.15.1/ko/enterprise/guides/monorepo-deployments.mdx b/docs/v1.15.1/ko/enterprise/guides/monorepo-deployments.mdx new file mode 100644 index 000000000..5146c71c3 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/monorepo-deployments.mdx @@ -0,0 +1,226 @@ +--- +title: "모노레포 배포" +description: "더 큰 저장소의 하위 폴더에서 Crew 또는 Flow 배포하기" +icon: "folder-tree" +mode: "wide" +--- + + + Crew 또는 Flow가 더 큰 저장소 안에 있을 때 작업 디렉터리를 사용하세요. + CrewAI AMP는 저장소 루트 대신 해당 하위 폴더에서 자동화를 검증, 빌드, + 실행합니다. + + +## 사용 시점 + +모노레포 배포는 하나의 저장소에 여러 자동화, 공유 패키지 또는 다른 애플리케이션 +코드가 함께 있을 때 유용합니다: + +```text +company-ai/ +|-- uv.lock +|-- packages/ +| `-- shared_tools/ +`-- crews/ + |-- support_agent/ + | |-- pyproject.toml + | |-- crew.jsonc + | `-- agents/ + | `-- support_agent.jsonc + `-- research_flow/ + |-- pyproject.toml + `-- src/ + `-- research_flow/ + `-- main.py +``` + +`support_agent`를 배포하려면 작업 디렉터리를 다음과 같이 설정합니다: + +```text +crews/support_agent +``` + +AMP는 여전히 전체 저장소를 가져오거나 업로드하지만, 선택한 폴더를 자동화 +프로젝트 루트로 처리합니다. + +## 작업 디렉터리가 제어하는 항목 + +작업 디렉터리가 설정되면 AMP는 해당 폴더를 다음 용도로 사용합니다: + +- `pyproject.toml`, JSON crew 파일, 클래식 Crew 또는 Flow 진입점을 포함한 프로젝트 검증 +- `uv`를 사용한 종속성 설치 +- 실행 중인 프로세스의 작업 디렉터리 +- `CREW_ROOT_DIR` 환경 변수 + +필드를 비워 두면 기존 동작이 유지되며 저장소 루트를 사용합니다. + +## 지원되는 소스 + +다음 소스에서 배포를 만들 때 작업 디렉터리를 설정할 수 있습니다: + +- 연결된 GitHub 저장소 +- AMP에 구성된 Git 저장소 +- ZIP 업로드 + + + 작업 디렉터리는 AMP 웹 인터페이스에서 구성하세요. + `crewai deploy create` CLI 흐름은 이 필드를 묻지 않습니다. + + +기존 배포의 **Settings** 페이지에서도 작업 디렉터리를 추가하거나 변경할 수 +있습니다. 변경 사항은 다음 배포부터 적용됩니다. + + + 작업 디렉터리와 auto-deploy는 함께 사용할 수 없습니다. 배포에 작업 + 디렉터리가 설정되어 있으면 해당 배포의 auto-deploy가 비활성화됩니다. + 작업 디렉터리를 설정하기 전에 auto-deploy를 끄세요. + + +## 새 배포 구성 + + + + CrewAI AMP에서 새 배포를 만들고 소스를 선택합니다: GitHub, Git + Repository 또는 ZIP 업로드. + + + + 모노레포가 들어 있는 저장소와 브랜치를 선택하거나, 루트에 모노레포 내용이 + 포함된 ZIP 파일을 업로드합니다. + + + + 배포 양식에서 **Advanced** 섹션을 펼칩니다. + + + + 저장소 루트에서 Crew 또는 Flow 프로젝트까지의 경로를 입력합니다: + + ```text + crews/support_agent + ``` + + 앞에 슬래시를 붙이지 마세요. + + + + 필요한 환경 변수를 추가한 다음 배포를 시작합니다. + + + +## 기존 배포 구성 + + + + AMP에서 자동화로 이동한 뒤 **Settings**를 엽니다. + + + + auto-deploy가 활성화되어 있으면 먼저 끄세요. auto-deploy가 켜져 있는 + 동안에는 작업 디렉터리 필드를 사용할 수 없습니다. + + + + **Basic settings**에서 다음과 같은 하위 폴더 경로를 입력합니다: + + ```text + crews/support_agent + ``` + + + + 설정을 저장하고 자동화를 다시 배포합니다. 새 작업 디렉터리는 다음 배포부터 + 사용됩니다. + + + +## 경로 규칙 + +작업 디렉터리는 저장소 또는 ZIP 루트 안의 상대 경로여야 합니다. + +| 규칙 | 예시 | +|------|------| +| 상대 경로를 사용합니다 | `crews/support_agent` | +| `/`로 시작하지 않습니다 | `/crews/support_agent`는 유효하지 않습니다 | +| `.` 또는 `..` 경로 세그먼트를 사용하지 않습니다 | `crews/../support_agent`는 유효하지 않습니다 | +| 문자, 숫자, 하이픈, 밑줄, 점, 슬래시만 사용합니다 | `crews/support agent`는 유효하지 않습니다 | +| 경로는 255자 이하로 유지합니다 | 더 긴 경로는 거부됩니다 | + +AMP는 앞뒤 공백을 제거하고, 반복된 슬래시를 하나로 줄이며, 끝의 슬래시를 +제거합니다. 빈 값은 저장소 루트를 사용합니다. + +## Lock 파일과 UV 워크스페이스 + +선택한 폴더에는 자동화의 `pyproject.toml`과 프로젝트 유형에 맞는 파일이 +있어야 합니다: + +- JSON-first crew: `crew.jsonc` 또는 `crew.json`과 `agents/` +- 클래식 Crew 또는 Flow: Python 진입점이 있는 `src/` + +`uv.lock` 또는 `poetry.lock` 파일은 선택한 폴더나 저장소 루트에 둘 수 +있습니다. + +이 방식은 일반적인 두 가지 lock 파일 배치를 모두 지원합니다: + + + + ```text + company-ai/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- uv.lock + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + ```text + company-ai/ + |-- uv.lock + |-- packages/ + | `-- shared_tools/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + + 자동화가 모노레포의 다른 위치에 있는 공유 패키지를 가져온다면, UV + workspace, path 또는 source 설정을 사용해 해당 패키지를 `pyproject.toml`에 + 선언하세요. AMP는 선택한 폴더에서 자동화를 실행하므로, 저장소 루트가 + Python path에 있다고 가정하기보다 공유 코드를 종속성으로 설치해야 합니다. + + +## 문제 해결 + +### 작업 디렉터리를 찾을 수 없음 + +경로가 저장소 또는 ZIP 루트를 기준으로 한 상대 경로인지 확인하세요. ZIP +업로드의 경우 ZIP 내용에 입력한 작업 디렉터리 경로가 정확히 포함되어야 합니다. + +### pyproject.toml 누락 + +작업 디렉터리는 여러 프로젝트를 담은 상위 폴더가 아니라 Crew 또는 Flow 프로젝트 +폴더를 가리켜야 합니다. + +### uv.lock 또는 poetry.lock 누락 + +선택한 프로젝트 폴더 또는 저장소 루트에 lock 파일을 커밋하세요. UV +워크스페이스의 경우 `uv.lock`을 워크스페이스 루트에 두는 방식이 지원됩니다. + +### Auto-Deploy를 사용할 수 없음 + +작업 디렉터리가 설정되어 있으면 auto-deploy가 비활성화됩니다. 수동 재배포를 +사용하거나 AMP API로 CI/CD에서 재배포를 트리거하세요. + + + 모노레포 작업 디렉터리를 선택한 뒤 배포 가이드를 계속 진행하세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/onedrive-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/onedrive-trigger.mdx new file mode 100644 index 000000000..787696414 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/onedrive-trigger.mdx @@ -0,0 +1,68 @@ +--- +title: "OneDrive Trigger" +description: "Automate responses to OneDrive file activity" +icon: "cloud" +mode: "wide" +--- + +## Overview + +Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata. + + + Connect OneDrive in **Tools & Integrations** and toggle the trigger on for + your deployment. + + +## Enabling the OneDrive Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **OneDrive** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Audit file permissions + +```python +from onedrive_file_crew import OneDriveFileTrigger + +crew = OneDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": onedrive_payload, +}) +``` + +The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary. + +## 로컬에서 테스트 + +CrewAI CLI를 사용하여 OneDrive 트리거 통합을 로컬에서 테스트하세요: + +```bash +# 사용 가능한 모든 트리거 보기 +crewai triggers list + +# 실제 payload로 OneDrive 트리거 시뮬레이션 +crewai triggers run microsoft_onedrive/file_changed +``` + +`crewai triggers run` 명령은 완전한 OneDrive payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다. + + + 개발 중에는 `crewai triggers run microsoft_onedrive/file_changed`를 사용하세요 + (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 받습니다. + + +## Troubleshooting + +- Ensure the connected account has permission to read the file metadata included in the webhook +- `crewai triggers run microsoft_onedrive/file_changed`로 로컬 테스트하여 정확한 payload 구조를 확인하세요 +- If the trigger fires but the payload is missing `permissions`, confirm the site-level sharing settings allow Graph to return this field +- For large tenants, filter notifications upstream so the crew only runs on relevant directories +- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님) diff --git a/docs/v1.15.1/ko/enterprise/guides/outlook-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/outlook-trigger.mdx new file mode 100644 index 000000000..bf5bf09a6 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/outlook-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "Outlook Trigger" +description: "Launch automations from Outlook emails and calendar updates" +icon: "microsoft" +mode: "wide" +--- + +## Overview + +Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations. + + + Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled + for your deployment. + + +## Enabling the Outlook Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Outlook** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize a new email + +```python +from outlook_message_crew import OutlookMessageTrigger + +crew = OutlookMessageTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": outlook_payload, +}) +``` + +The crew extracts sender details, subject, body preview, and attachments before generating a structured response. + +## 로컬에서 테스트 + +CrewAI CLI를 사용하여 Outlook 트리거 통합을 로컬에서 테스트하세요: + +```bash +# 사용 가능한 모든 트리거 보기 +crewai triggers list + +# 실제 payload로 Outlook 트리거 시뮬레이션 +crewai triggers run microsoft_outlook/email_received +``` + +`crewai triggers run` 명령은 완전한 Outlook payload로 크루를 실행하여 배포 전에 파싱 로직을 테스트할 수 있게 해줍니다. + + + 개발 중에는 `crewai triggers run microsoft_outlook/email_received`를 + 사용하세요 (`crewai run`이 아님). 배포 후에는 크루가 자동으로 트리거 payload를 + 받습니다. + + +## Troubleshooting + +- Verify the Outlook connector is still authorized; the subscription must be renewed periodically +- `crewai triggers run microsoft_outlook/email_received`로 로컬 테스트하여 정확한 payload 구조를 확인하세요 +- If attachments are missing, confirm the webhook subscription includes the `includeResourceData` flag +- Review execution logs when events fail to match—cancellation payloads lack attendee lists by design and the crew should account for that +- 주의: 트리거 실행을 시뮬레이션하려면 `crewai triggers run`을 사용하세요 (`crewai run`이 아님) diff --git a/docs/v1.15.1/ko/enterprise/guides/prepare-for-deployment.mdx b/docs/v1.15.1/ko/enterprise/guides/prepare-for-deployment.mdx new file mode 100644 index 000000000..f19bbe95d --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/prepare-for-deployment.mdx @@ -0,0 +1,342 @@ +--- +title: "배포 준비하기" +description: "Crew 또는 Flow가 CrewAI AMP에 배포될 준비가 되었는지 확인하기" +icon: "clipboard-check" +mode: "wide" +--- + + + CrewAI AMP에 배포하기 전에, 프로젝트가 올바르게 구성되어 있는지 확인하는 것이 중요합니다. + Crews와 Flows 모두 "자동화"로 배포할 수 있지만, 성공적인 배포를 위해 충족해야 하는 + 서로 다른 프로젝트 구조와 요구 사항이 있습니다. + + +## 자동화 이해하기 + +CrewAI AMP에서 **자동화(automations)**는 배포 가능한 Agentic AI 프로젝트의 총칭입니다. 자동화는 다음 중 하나일 수 있습니다: + +- **Crew**: 작업을 함께 수행하는 AI 에이전트들의 독립 실행형 팀 +- **Flow**: 여러 crew, 직접 LLM 호출 및 절차적 로직을 결합할 수 있는 오케스트레이션된 워크플로우 + +배포하는 유형을 이해하는 것은 프로젝트 구조와 진입점이 다르기 때문에 필수적입니다. + +## Crews vs Flows: 주요 차이점 + + + + 독립 실행형 AI 에이전트 팀입니다. 새 crew는 `crew.jsonc`와 `agents/`를 사용하는 JSON-first 구조이며, 클래식 crew는 계속 `crew.py`를 사용할 수 있습니다. + + + `crews/` 폴더에 포함된 crew가 있는 오케스트레이션된 워크플로우. 복잡한 다단계 프로세스에 적합합니다. + + + +| 측면 | Crew | Flow | +|------|------|------| +| **프로젝트 구조** | 프로젝트 루트의 `crew.jsonc`와 `agents/` | `crews/` 폴더가 있는 `src/project_name/` | +| **메인 로직 위치** | `crew.jsonc` (클래식: `src/project_name/crew.py`) | `src/project_name/main.py` (Flow 클래스) | +| **진입점 함수** | `crew.jsonc`에서 로드됨 (클래식: `main.py`의 `run()`) | `main.py`의 `kickoff()` | +| **pyproject.toml 타입** | `type = "crew"` | `type = "flow"` | +| **CLI 생성 명령어** | `crewai create crew name` | `crewai create flow name` | +| **설정 위치** | `crew.jsonc`, `agents/`, 선택적 `tools/` | `src/project_name/crews/crew_name/config/` 또는 포함된 JSON crew 폴더 | +| **다른 crew 포함 가능** | 아니오 | 예 (`crews/` 폴더 내) | + +## 프로젝트 구조 참조 + +### Crew 프로젝트 구조 + +`crewai create crew my_crew`를 실행하면 JSON-first 구조를 얻습니다: + +``` +my_crew/ +├── .gitignore +├── pyproject.toml # type = "crew"여야 함 +├── README.md +├── .env +├── uv.lock # 배포에 필수 +├── crew.jsonc # Crew 설정, 태스크, 프로세스, 입력 +├── agents/ +│ └── researcher.jsonc # 에이전트 정의 +├── tools/ # 선택적 custom: 도구 +├── knowledge/ +└── skills/ +``` + + + JSON-first crew에서는 `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, `skills/`를 + 프로젝트 루트에 두세요. 이를 `src/` 아래에 두면 `crewai run`과 배포 검증이 crew 정의를 찾지 못합니다. + + + + `crewai create crew my_crew --classic`으로 만든 클래식 프로젝트는 기존 + `src/project_name/crew.py`, `src/project_name/config/agents.yaml`, + `src/project_name/config/tasks.yaml` 구조를 사용합니다. 이 구조는 decorator 기반 Python crew를 위해 계속 지원됩니다. + + +### Flow 프로젝트 구조 + +`crewai create flow my_flow`를 실행하면 다음 구조를 얻습니다: + +``` +my_flow/ +├── .gitignore +├── pyproject.toml # type = "flow"여야 함 +├── README.md +├── .env +├── uv.lock # 배포에 필수 +└── src/ + └── my_flow/ + ├── __init__.py + ├── main.py # kickoff() 함수 + Flow 클래스가 있는 진입점 + ├── crews/ # 포함된 crews 폴더 + │ └── poem_crew/ + │ ├── __init__.py + │ ├── poem_crew.py # @CrewBase 데코레이터가 있는 Crew + │ └── config/ + │ ├── agents.yaml + │ └── tasks.yaml + └── tools/ + ├── __init__.py + └── custom_tool.py +``` + + + JSON-first 독립 실행형 crew는 프로젝트 루트의 JSON 파일을 사용합니다. + Flow는 여전히 `src/project_name/`을 사용하며, 클래식 포함 crew나 + `crewai.project.load_crew`로 로드하는 포함 JSON crew 폴더를 둘 수 있습니다. + + +## 배포 전 체크리스트 + +이 체크리스트를 사용하여 프로젝트가 배포 준비가 되었는지 확인하세요. + +### 1. pyproject.toml 설정 확인 + +`pyproject.toml`에 올바른 `[tool.crewai]` 섹션이 포함되어야 합니다: + + + + ```toml + [tool.crewai] + type = "crew" + ``` + + + ```toml + [tool.crewai] + type = "flow" + ``` + + + + + `type`이 프로젝트 구조와 일치하지 않으면 빌드가 실패하거나 + 자동화가 올바르게 실행되지 않습니다. + + +### 2. uv.lock 파일 존재 확인 + +CrewAI는 의존성 관리를 위해 `uv`를 사용합니다. `uv.lock` 파일은 재현 가능한 빌드를 보장하며 배포에 **필수**입니다. + +```bash +# lock 파일 생성 또는 업데이트 +uv lock + +# 존재 여부 확인 +ls -la uv.lock +``` + +파일이 존재하지 않으면 `uv lock`을 실행하고 저장소에 커밋하세요: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + +### 3. Crew 정의 검증 + + + + JSON-first crew는 프로젝트 루트에 `crew.jsonc` 또는 `crew.json` 파일이 있어야 합니다. + `agents` 배열은 `agents/` 안의 파일을 참조해야 하며, 각 task는 유효한 agent 이름을 참조해야 합니다. + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "Research {topic}.", + "expected_output": "A concise report.", + "agent": "researcher" + } + ], + "inputs": { + "topic": "AI Agents" + } + } + ``` + + 커스텀 도구는 `"custom:"`으로 참조하며, `tools/.py`에 `BaseTool` 서브클래스로 구현해야 합니다. + + + 클래식 crew와 Flow 안에 포함된 Python crew는 `@CrewBase` 데코레이터를 사용해야 합니다. + + ```python + from crewai import Agent, Crew, Process, Task + from crewai.project import CrewBase, agent, crew, task + from crewai.agents.agent_builder.base_agent import BaseAgent + from typing import List + + @CrewBase + class MyCrew(): + """내 crew 설명""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + @task + def my_task(self) -> Task: + return Task( + config=self.tasks_config['my_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) + ``` + + + +### 4. 프로젝트 진입점 확인 + +JSON-first 독립 실행형 crew는 직접 작성한 `src/project_name/main.py`가 필요하지 않습니다. +`crewai run`과 배포 패키징이 `crew.jsonc`를 직접 로드합니다. 클래식 crew와 Flow는 Python 진입점을 사용합니다: + + + + 프로젝트 루트에서 로컬 실행합니다: + + ```bash + crewai run + ``` + + + 진입점은 `run()` 함수를 사용합니다: + + ```python + # src/my_crew/main.py + from my_crew.crew import MyCrew + + def run(): + """crew를 실행합니다.""" + inputs = {'topic': 'AI in Healthcare'} + result = MyCrew().crew().kickoff(inputs=inputs) + return result + + if __name__ == "__main__": + run() + ``` + + + 진입점은 Flow 클래스와 함께 `kickoff()` 함수를 사용합니다: + + ```python + # src/my_flow/main.py + from crewai.flow import Flow, listen, start + from my_flow.crews.poem_crew.poem_crew import PoemCrew + + class MyFlow(Flow): + @start() + def begin(self): + # Flow 로직 + result = PoemCrew().crew().kickoff(inputs={...}) + return result + + def kickoff(): + """flow를 실행합니다.""" + MyFlow().kickoff() + + if __name__ == "__main__": + kickoff() + ``` + + + +### 5. 환경 변수 준비 + +배포 전에 다음을 준비해야 합니다: + +1. **LLM API 키** (OpenAI, Anthropic, Google 등) +2. **도구 API 키** - 외부 도구를 사용하는 경우 (Serper 등) + + + 프로젝트가 **프라이빗 PyPI 레지스트리**의 패키지에 의존하는 경우, 레지스트리 인증 자격 증명도 + 환경 변수로 구성해야 합니다. 자세한 내용은 + [프라이빗 패키지 레지스트리](/ko/enterprise/guides/private-package-registry) 가이드를 참조하세요. + + + + 구성 문제를 조기에 발견하기 위해 배포 전에 동일한 환경 변수로 + 로컬에서 프로젝트를 테스트하세요. + + +## 빠른 검증 명령어 + +프로젝트 루트에서 다음 명령어를 실행하여 설정을 빠르게 확인하세요: + +```bash +# 1. pyproject.toml에서 프로젝트 타입 확인 +grep -A2 "\[tool.crewai\]" pyproject.toml + +# 2. uv.lock 존재 확인 +ls -la uv.lock || echo "오류: uv.lock이 없습니다! 'uv lock'을 실행하세요" + +# 3. JSON-first crew의 경우 crew.jsonc와 agents/ 확인 +([ -f crew.jsonc ] || [ -f crew.json ]) || echo "crew.jsonc 또는 crew.json을 찾을 수 없습니다" +test -d agents || echo "agents/ 디렉터리를 찾을 수 없습니다" + +# 4. 클래식 Crews의 경우 - crew.py 존재 확인 +ls -la src/*/crew.py 2>/dev/null || echo "crew.py가 없습니다 (Crews에서 예상됨)" + +# 5. Flows의 경우 - crews/ 폴더 존재 확인 +ls -la src/*/crews/ 2>/dev/null || echo "crews/ 폴더가 없습니다 (Flows에서 예상됨)" + +# 6. 클래식 Python crews의 경우 - CrewBase 사용 확인 +grep -r "@CrewBase" . --include="*.py" +``` + +## 일반적인 설정 실수 + +| 실수 | 증상 | 해결 방법 | +|------|------|----------| +| `uv.lock` 누락 | 의존성 해결 중 빌드 실패 | `uv lock` 실행 후 커밋 | +| pyproject.toml의 잘못된 `type` | 빌드 성공하지만 런타임 실패 | 올바른 타입으로 변경 | +| JSON-first crew에서 `crew.jsonc` 또는 `agents/` 누락 | Crew 정의를 찾을 수 없음 | `crew.jsonc`와 `agents/`를 프로젝트 루트에 둠 | +| 클래식 crew에서 `@CrewBase` 데코레이터 누락 | "Config not found" 오류 | 모든 클래식 crew 클래스에 데코레이터 추가 | +| 클래식 파일을 `src/` 대신 루트에 배치 | 진입점을 찾을 수 없음 | 클래식 Python 파일을 `src/project_name/`으로 이동 | +| `run()` 또는 `kickoff()` 누락 | 자동화를 시작할 수 없음 | 올바른 진입 함수 추가 | + +## 다음 단계 + +프로젝트가 모든 체크리스트 항목을 통과하면 배포할 준비가 된 것입니다: + + + CLI, 웹 인터페이스 또는 CI/CD 통합을 사용하여 Crew 또는 Flow를 CrewAI AMP에 + 배포하려면 배포 가이드를 따르세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/private-package-registry.mdx b/docs/v1.15.1/ko/enterprise/guides/private-package-registry.mdx new file mode 100644 index 000000000..41b07731f --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/private-package-registry.mdx @@ -0,0 +1,261 @@ +--- +title: "프라이빗 패키지 레지스트리" +description: "CrewAI AMP에서 인증된 PyPI 레지스트리의 프라이빗 Python 패키지 설치하기" +icon: "lock" +mode: "wide" +--- + + + 이 가이드는 CrewAI AMP에 배포할 때 프라이빗 PyPI 레지스트리(Azure DevOps Artifacts, GitHub Packages, + GitLab, AWS CodeArtifact 등)에서 Python 패키지를 설치하도록 CrewAI 프로젝트를 구성하는 방법을 다룹니다. + + +## 이 가이드가 필요한 경우 + +프로젝트가 공개 PyPI가 아닌 프라이빗 레지스트리에 호스팅된 내부 또는 독점 Python 패키지에 +의존하는 경우, 다음을 수행해야 합니다: + +1. UV에 패키지를 **어디서** 찾을지 알려줍니다 (index URL) +2. UV에 **어떤** 패키지가 해당 index에서 오는지 알려줍니다 (source 매핑) +3. UV가 설치 중에 인증할 수 있도록 **자격 증명**을 제공합니다 + +CrewAI AMP는 의존성 해결 및 설치에 [UV](https://docs.astral.sh/uv/)를 사용합니다. +UV는 `pyproject.toml` 구성과 자격 증명용 환경 변수를 결합하여 인증된 프라이빗 레지스트리를 지원합니다. + +## 1단계: pyproject.toml 구성 + +`pyproject.toml`에서 세 가지 요소가 함께 작동합니다: + +### 1a. 의존성 선언 + +프라이빗 패키지를 다른 의존성과 마찬가지로 `[project.dependencies]`에 추가합니다: + +```toml +[project] +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] +``` + +### 1b. index 정의 + +프라이빗 레지스트리를 `[[tool.uv.index]]` 아래에 명명된 index로 등록합니다: + +```toml +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true +``` + + + `name` 필드는 중요합니다 — UV는 이를 사용하여 인증을 위한 환경 변수 이름을 + 구성합니다 (아래 [2단계](#2단계-인증-자격-증명-설정)를 참조하세요). + + `explicit = true`를 설정하면 UV가 모든 패키지에 대해 이 index를 검색하지 않습니다 — + `[tool.uv.sources]`에서 명시적으로 매핑한 패키지만 검색합니다. 이렇게 하면 프라이빗 + 레지스트리에 대한 불필요한 쿼리를 방지하고 의존성 혼동 공격을 차단할 수 있습니다. + + +### 1c. 패키지를 index에 매핑 + +`[tool.uv.sources]`를 사용하여 프라이빗 index에서 해결해야 할 패키지를 UV에 알려줍니다: + +```toml +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +### 전체 예시 + +```toml +[project] +name = "my-crew-project" +version = "0.1.0" +requires-python = ">=3.10,<=3.13" +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] + +[tool.crewai] +type = "crew" + +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true + +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +`pyproject.toml`을 업데이트한 후 lock 파일을 다시 생성합니다: + +```bash +uv lock +``` + + + 업데이트된 `uv.lock`을 항상 `pyproject.toml` 변경 사항과 함께 커밋하세요. + lock 파일은 배포에 필수입니다 — [배포 준비하기](/ko/enterprise/guides/prepare-for-deployment)를 참조하세요. + + +## 2단계: 인증 자격 증명 설정 + +UV는 `pyproject.toml`에서 정의한 index 이름을 기반으로 한 명명 규칙을 따르는 +환경 변수를 사용하여 프라이빗 index에 인증합니다: + +``` +UV_INDEX_{UPPER_NAME}_USERNAME +UV_INDEX_{UPPER_NAME}_PASSWORD +``` + +여기서 `{UPPER_NAME}`은 index 이름을 **대문자**로 변환하고 **하이픈을 언더스코어로 대체**한 것입니다. + +예를 들어, `my-private-registry`라는 이름의 index는 다음을 사용합니다: + +| 변수 | 값 | +|------|-----| +| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | 레지스트리 사용자 이름 또는 토큰 이름 | +| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | 레지스트리 비밀번호 또는 토큰/PAT | + + + 이 환경 변수는 CrewAI AMP **환경 변수** 설정을 통해 **반드시** 추가해야 합니다 — + 전역적으로 또는 배포 수준에서. `.env` 파일에 설정하거나 프로젝트에 하드코딩할 수 없습니다. + + 아래 [AMP에서 환경 변수 설정](#amp에서-환경-변수-설정)을 참조하세요. + + +## 레지스트리 제공업체 참조 + +아래 표는 일반적인 레지스트리 제공업체의 index URL 형식과 자격 증명 값을 보여줍니다. +자리 표시자 값을 실제 조직 및 피드 세부 정보로 대체하세요. + +| 제공업체 | Index URL | 사용자 이름 | 비밀번호 | +|---------|-----------|-----------|---------| +| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | 비어 있지 않은 임의의 문자열 (예: `token`) | Packaging Read 범위의 Personal Access Token (PAT) | +| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | GitHub 사용자 이름 | `read:packages` 범위의 Personal Access Token (classic) | +| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | `read_api` 범위의 Project 또는 Personal Access Token | +| **AWS CodeArtifact** | `aws codeartifact get-repository-endpoint`의 URL 사용 | `aws` | `aws codeartifact get-authorization-token`의 토큰 | +| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Base64로 인코딩된 서비스 계정 키 | +| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | 사용자 이름 또는 이메일 | API 키 또는 ID 토큰 | +| **자체 호스팅 (devpi, Nexus 등)** | 레지스트리의 simple API URL | 레지스트리 사용자 이름 | 레지스트리 비밀번호 | + + + **AWS CodeArtifact**의 경우 인증 토큰이 주기적으로 만료됩니다. + 만료되면 `UV_INDEX_*_PASSWORD` 값을 갱신해야 합니다. + CI/CD 파이프라인에서 이를 자동화하는 것을 고려하세요. + + +## AMP에서 환경 변수 설정 + +프라이빗 레지스트리 자격 증명은 CrewAI AMP에서 환경 변수로 구성해야 합니다. +두 가지 옵션이 있습니다: + + + + 1. [CrewAI AMP](https://app.crewai.com)에 로그인합니다 + 2. 자동화로 이동합니다 + 3. **Environment Variables** 탭을 엽니다 + 4. 각 변수 (`UV_INDEX_*_USERNAME` 및 `UV_INDEX_*_PASSWORD`)에 값을 추가합니다 + + 자세한 내용은 [AMP에 배포하기 — 환경 변수 설정하기](/ko/enterprise/guides/deploy-to-amp#환경-변수-설정하기) 단계를 참조하세요. + + + `crewai deploy create`를 실행하기 전에 로컬 `.env` 파일에 변수를 추가합니다. + CLI가 이를 안전하게 플랫폼으로 전송합니다: + + ```bash + # .env + OPENAI_API_KEY=sk-... + UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token + UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here + ``` + + ```bash + crewai deploy create + ``` + + + + + 자격 증명을 저장소에 **절대** 커밋하지 마세요. 모든 비밀 정보에는 AMP 환경 변수를 사용하세요. + `.env` 파일은 `.gitignore`에 포함되어야 합니다. + + +기존 배포의 자격 증명을 업데이트하려면 [Crew 업데이트하기 — 환경 변수](/ko/enterprise/guides/update-crew)를 참조하세요. + +## 전체 동작 흐름 + +CrewAI AMP가 자동화를 빌드할 때, 해결 흐름은 다음과 같이 작동합니다: + + + + AMP가 저장소를 가져오고 `pyproject.toml`과 `uv.lock`을 읽습니다. + + + UV가 `[tool.uv.sources]`를 읽어 각 패키지가 어떤 index에서 와야 하는지 결정합니다. + + + 각 프라이빗 index에 대해 UV가 AMP에서 구성한 환경 변수에서 + `UV_INDEX_{NAME}_USERNAME`과 `UV_INDEX_{NAME}_PASSWORD`를 조회합니다. + + + UV가 공개(PyPI) 및 프라이빗(레지스트리) 패키지를 모두 다운로드하고 설치합니다. + + + 모든 의존성이 사용 가능한 상태에서 crew 또는 flow가 시작됩니다. + + + +## 문제 해결 + +### 빌드 중 인증 오류 + +**증상**: 프라이빗 패키지를 해결할 때 `401 Unauthorized` 또는 `403 Forbidden`으로 빌드가 실패합니다. + +**확인사항**: +- `UV_INDEX_*` 환경 변수 이름이 index 이름과 정확히 일치하는지 확인합니다 (대문자, 하이픈 -> 언더스코어) +- 자격 증명이 로컬 `.env`뿐만 아니라 AMP 환경 변수에 설정되어 있는지 확인합니다 +- 토큰/PAT에 패키지 피드에 필요한 읽기 권한이 있는지 확인합니다 +- 토큰이 만료되지 않았는지 확인합니다 (특히 AWS CodeArtifact의 경우) + +### 패키지를 찾을 수 없음 + +**증상**: `No matching distribution found for my-private-package`. + +**확인사항**: +- `pyproject.toml`의 index URL이 `/simple/`로 끝나는지 확인합니다 +- `[tool.uv.sources]` 항목이 올바른 패키지 이름을 올바른 index 이름에 매핑하는지 확인합니다 +- 패키지가 실제로 프라이빗 레지스트리에 게시되어 있는지 확인합니다 +- 동일한 자격 증명으로 로컬에서 `uv lock`을 실행하여 해결이 작동하는지 확인합니다 + +### Lock 파일 충돌 + +**증상**: 프라이빗 index를 추가한 후 `uv lock`이 실패하거나 예상치 못한 결과를 생성합니다. + +**해결책**: 로컬에서 자격 증명을 설정하고 다시 생성합니다: + +```bash +export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token +export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat +uv lock +``` + +그런 다음 업데이트된 `uv.lock`을 커밋합니다. + +## 관련 가이드 + + + + 배포 전에 프로젝트 구조와 의존성을 확인합니다. + + + crew 또는 flow를 배포하고 환경 변수를 구성합니다. + + + 환경 변수를 업데이트하고 실행 중인 배포에 변경 사항을 푸시합니다. + + diff --git a/docs/v1.15.1/ko/enterprise/guides/react-component-export.mdx b/docs/v1.15.1/ko/enterprise/guides/react-component-export.mdx new file mode 100644 index 000000000..3850ff3d2 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/react-component-export.mdx @@ -0,0 +1,112 @@ +--- +title: "React 컴포넌트 내보내기" +description: "CrewAI AMP React 컴포넌트를 애플리케이션에 내보내고 통합하는 방법을 알아보세요" +icon: "react" +mode: "wide" +--- + +이 가이드는 CrewAI AMP crew를 React 컴포넌트로 내보내고 이를 여러분의 애플리케이션에 통합하는 방법을 설명합니다. + +## React 컴포넌트 내보내기 + + + + 배포된 crew 오른쪽에 있는 줄임표(세 개의 점)를 클릭한 다음 내보내기 옵션을 선택하고 파일을 로컬에 저장하세요. 본 예시에서는 `CrewLead.jsx`를 사용합니다. + + + React 컴포넌트 내보내기 + + + + + +## 리액트 환경 설정 + +이 리액트 컴포넌트를 로컬에서 실행하려면 리액트 개발 환경을 설정하고 이 컴포넌트를 리액트 프로젝트에 통합해야 합니다. + + + + - 공식 웹사이트(https://nodejs.org/)에서 Node.js를 다운로드하고 설치하세요. + - 안정성을 위해 LTS(장기 지원) 버전을 선택하세요. + + + + - 명령 프롬프트 또는 PowerShell을 엽니다. + - 프로젝트를 생성하고자 하는 디렉터리로 이동하세요. + - 다음 명령어를 실행하여 새로운 리액트 프로젝트를 생성합니다: + + ```bash + npx create-react-app my-crew-app + ``` + - 프로젝트 디렉터리로 이동합니다: + + ```bash + cd my-crew-app + ``` + + + + ```bash + npm install react-dom + ``` + + + + - 다운로드한 파일 `CrewLead.jsx`를 프로젝트의 `src` 폴더로 이동하세요. + + + + - `src/App.js`를 엽니다. + - 내용물을 아래와 같이 교체하세요: + + ```jsx + import React from 'react'; + import CrewLead from './CrewLead'; + + function App() { + return ( +
+ +
+ ); + } + + export default App; + ``` + - `YOUR_API_BASE_URL` 및 `YOUR_BEARER_TOKEN` 부분을 실제 API 값으로 바꿔주세요. + + + + - 프로젝트 디렉터리에서 다음 명령어를 실행하세요: + + ```bash + npm start + ``` + - 개발 서버가 시작되며, 기본 웹 브라우저가 자동으로 http://localhost:3000 을 열고 리액트 앱이 실행되는 것을 확인할 수 있습니다. + + + + +## 커스터마이징 + +그런 다음 `CrewLead.jsx`를 커스터마이즈하여 색상, 제목 등을 추가할 수 있습니다. + + + React 컴포넌트 커스터마이즈 + + + React 컴포넌트 커스터마이즈 + + +## 다음 단계 + +- 구성 요소 스타일을 애플리케이션 디자인에 맞게 맞춤화하세요 +- 추가 구성을 위한 props를 추가하세요 +- 애플리케이션의 상태 관리와 통합하세요 +- 오류 처리 및 로딩 상태를 추가하세요 diff --git a/docs/v1.15.1/ko/enterprise/guides/salesforce-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/salesforce-trigger.mdx new file mode 100644 index 000000000..f2c7d7c0a --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/salesforce-trigger.mdx @@ -0,0 +1,50 @@ +--- +title: "Salesforce 트리거" +description: "Salesforce 워크플로우에서 CrewAI crew를 트리거하여 CRM 자동화" +icon: "salesforce" +mode: "wide" +--- + +CrewAI AOP는 Salesforce에서 트리거되어 고객 관계 관리 워크플로우를 자동화하고 영업 운영을 강화할 수 있습니다. + +## 개요 + +Salesforce는 기업이 영업, 서비스, 마케팅 운영을 효율화할 수 있도록 돕는 선도적인 고객 관계 관리(CRM) 플랫폼입니다. Salesforce에서 CrewAI 트리거를 설정하면 다음과 같은 작업을 수행할 수 있습니다: + +- 리드 점수 산정 및 자격 심사 자동화 +- 개인화된 영업 자료 생성 +- AI 기반 응답으로 고객 서비스 강화 +- 데이터 분석 및 보고 간소화 + +## 데모 + + + +## 시작하기 + +Salesforce 트리거를 설정하려면: + +1. **지원팀 문의**: Salesforce 트리거 설정을 위해 CrewAI AMP 지원팀에 연락하세요. +2. **요구 사항 검토**: 필요한 Salesforce 권한과 API 액세스 권한이 있는지 확인하세요. +3. **연결 구성**: 지원팀과 협력하여 CrewAI와 귀하의 Salesforce 인스턴스 간의 연결을 설정하세요. +4. **트리거 테스트**: 트리거가 귀하의 특정 사용 사례에 맞게 올바르게 작동하는지 확인하세요. + +## 사용 사례 + +일반적인 Salesforce + CrewAI 트리거 시나리오는 다음과 같습니다: + +- **Lead 처리**: 들어오는 리드를 자동으로 분석하고 점수화 +- **제안서 생성**: 기회 데이터를 기반으로 맞춤형 제안서 생성 +- **고객 인사이트**: 고객 상호작용 이력에서 분석 보고서 생성 +- **후속 조치 자동화**: 개인화된 후속 메시지 및 추천 생성 + +## 다음 단계 + +자세한 설정 지침 및 고급 구성 옵션에 대해서는 CrewAI AMP 지원팀에 문의해 주시기 바랍니다. 지원팀은 귀하의 특정 Salesforce 환경과 비즈니스 요구에 맞는 맞춤형 안내를 제공해 드릴 수 있습니다. diff --git a/docs/v1.15.1/ko/enterprise/guides/slack-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/slack-trigger.mdx new file mode 100644 index 000000000..bff529c70 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/slack-trigger.mdx @@ -0,0 +1,62 @@ +--- +title: "Slack 트리거" +description: "슬래시 명령어를 사용해 Slack에서 CrewAI crew를 직접 트리거합니다" +icon: "slack" +mode: "wide" +--- + +이 가이드는 CrewAI 트리거를 사용하여 Slack에서 직접 crew를 시작하는 방법을 설명합니다. + +## 사전 요구 사항 + +- CrewAI Slack 트리거가 설치되어 있고 Slack 워크스페이스에 연결되어 있음 +- CrewAI에서 하나 이상의 crew가 구성되어 있음 + +## 설정 단계 + + + + CrewAI 대시보드에서 **트리거** 섹션으로 이동합니다. + + + CrewAI Slack Integration + + + Slack이 나열되어 있고 연결되어 있는지 확인합니다. + + + - crew를 시작하려는 채널로 이동합니다. + - 슬래시 명령어 "**/kickoff**"를 입력하여 crew 시작 프로세스를 시작합니다. + - 입력하는 동안 "**Kickoff crew**"가 나타나야 합니다: + + Kickoff crew + + - Enter를 누르거나 "**Kickoff crew**" 옵션을 선택합니다. "**Kickoff an AI Crew**"라는 제목의 대화상자가 나타납니다. + + + - "**Select of the crews online:**"라는 드롭다운 메뉴에서 시작할 crew를 선택합니다. + - 아래 예시에서는 "**prep-for-meeting**"이 선택되어 있습니다: + + Kickoff crew dropdown + + - crew에 입력값이 필요한 경우 "**Add Inputs**" 버튼을 클릭하여 입력값을 제공합니다. + + 위 예시에서 "**Add Inputs**" 버튼이 보이지만 아직 클릭되지 않았습니다. + + + + - crew를 선택하고 필요한 입력값을 추가했다면, "**Kickoff**"를 클릭하여 crew를 시작합니다. + + Kickoff crew + + - crew가 실행을 시작하면 Slack 채널에서 결과를 확인할 수 있습니다. + + Kickoff crew results + + + + +## 팁 + +- Slack 워크스페이스에서 `/kickoff` 명령어를 사용할 수 있는 필요한 권한이 있는지 확인하세요. +- 드롭다운에서 원하는 crew가 보이지 않는 경우, CrewAI에서 해당 crew가 올바르게 구성되어 있고 온라인 상태인지 확인하세요. \ No newline at end of file diff --git a/docs/v1.15.1/ko/enterprise/guides/team-management.mdx b/docs/v1.15.1/ko/enterprise/guides/team-management.mdx new file mode 100644 index 000000000..2017d7d32 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/team-management.mdx @@ -0,0 +1,88 @@ +--- +title: "팀 관리" +description: "CrewAI AMP 조직에서 팀원을 초대하고 관리하는 방법을 알아보세요" +icon: "users" +mode: "wide" +--- + +CrewAI AMP 계정의 관리자라면 새로운 팀원을 조직에 쉽게 초대할 수 있습니다. 이 안내서는 단계별로 프로세스를 안내합니다. + +## 팀 멤버 초대하기 + + + + - CrewAI AMP 계정에 로그인합니다 - 대시보드 오른쪽 상단에 있는 기어 + 아이콘(⚙️)을 찾습니다 - 기어 아이콘을 클릭하여 **설정** 페이지에 접속합니다: + + Settings Page + + + + - 설정 페이지에서 `Members` 탭이 보입니다 - `Members` 탭을 클릭하여 **멤버** + 페이지에 접속합니다: + + Members Tab + + + + - 멤버 섹션에서 현재 멤버 목록(본인 포함)을 확인할 수 있습니다 - `Email` + 입력 필드를 찾습니다 - 초대하고자 하는 사람의 이메일 주소를 입력합니다 - + `Invite` 버튼을 클릭하여 초대장을 보냅니다 + + + - 이 과정을 반복하여 여러 팀 멤버를 초대할 수 있습니다 - 초대한 각 멤버는 + 조직에 가입할 수 있는 이메일 초대장을 받게 됩니다 + + + +## 역할 추가하기 + +플랫폼의 다양한 부분에 대한 접근 권한을 제어하기 위해 팀원들에게 역할을 추가할 수 있습니다. + + + + - CrewAI AMP 계정에 로그인하세요 - 대시보드 오른쪽 상단에서 기어 + 아이콘(⚙️)을 찾으세요 - 기어 아이콘을 클릭하여 **설정** 페이지에 접근하세요: + + 설정 페이지 + + + + - 설정 페이지에서 `Roles` 탭을 확인할 수 있습니다 - `Roles` 탭을 클릭하여 + **Roles** 페이지로 이동하세요. + + Roles 탭 + + - 새로운 역할을 추가하려면 `Add Role` 버튼을 클릭하세요. - 역할의 + 세부 정보와 권한을 입력한 후 `Create Role` 버튼을 클릭하여 역할을 + 생성하세요. + + Add Role 모달 + + + + - 멤버 섹션에서 현재 멤버(본인 포함) 목록을 확인할 수 있습니다 + + 멤버 초대 수락 완료 + + - 멤버가 초대를 수락하면 역할을 추가할 수 있습니다. - 다시 `Roles` + 탭으로 이동하세요 - 역할을 추가할 멤버로 이동한 후 `Role` 열에서 드롭다운을 + 클릭하세요 - 멤버에게 추가할 역할을 선택하세요 - `Update` 버튼을 클릭하여 + 역할을 저장하세요 + + 멤버에 역할 추가 + + + + +## 중요 참고 사항 + +- **관리자 권한**: 관리자 권한이 있는 사용자만 새 멤버를 초대할 수 있습니다 +- **이메일 정확성**: 팀 멤버의 정확한 이메일 주소를 확인하세요 +- **초대 수락**: 초대된 멤버는 조직에 가입하기 위해 초대를 수락해야 합니다 +- **이메일 알림**: 팀 멤버에게 초대 이메일(스팸 폴더 포함)을 확인하도록 안내할 수 있습니다 + +이 단계들을 따르면 팀을 손쉽게 확장하고 CrewAI AMP 조직 내에서 더욱 효과적으로 협업할 수 있습니다. diff --git a/docs/v1.15.1/ko/enterprise/guides/tool-repository.mdx b/docs/v1.15.1/ko/enterprise/guides/tool-repository.mdx new file mode 100644 index 000000000..5fd30818e --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/tool-repository.mdx @@ -0,0 +1,111 @@ +--- +title: 도구 저장소 +description: "도구 저장소를 사용하여 도구를 관리하기" +icon: "toolbox" +mode: "wide" +--- + +## 개요 + +Tool Repository는 CrewAI 도구를 위한 패키지 관리자입니다. 사용자는 CrewAI crew와 flow에 통합되는 도구를 게시, 설치 및 관리할 수 있습니다. + +도구는 다음과 같이 분류됩니다: + +- **비공개**: 조직 내에서만 접근할 수 있습니다(기본값) +- **공개**: `--public` 플래그로 게시하면 모든 CrewAI 사용자가 접근할 수 있습니다 + +이 저장소는 버전 관리 시스템이 아닙니다. 코드 변경 사항을 추적하고 협업을 활성화하려면 Git을 사용하십시오. + +## 사전 요구 사항 + +Tool Repository를 사용하기 전에 다음이 준비되어 있어야 합니다: + +- [CrewAI AMP](https://app.crewai.com) 계정 +- [CrewAI CLI](/ko/concepts/cli#cli) 설치됨 +- uv>=0.5.0 이 설치되어 있어야 합니다. [업그레이드 방법](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv)을 참고하세요. +- [Git](https://git-scm.com) 설치 및 구성 완료 +- CrewAI AMP 조직에서 도구를 게시하거나 설치할 수 있는 액세스 권한 + +## 도구 설치 + +도구를 설치하려면: + +```bash +crewai tool install +``` + +이 명령은 도구를 설치하고 `pyproject.toml`에 추가합니다. + +## 도구 생성 및 게시 + +새 도구 프로젝트를 생성하려면: + +```bash +crewai tool create +``` + +이 명령은 로컬에 스캐폴딩된 도구 프로젝트를 생성합니다. + +변경 사항을 적용한 후, Git 저장소를 초기화하고 코드를 커밋합니다: + +```bash +git init +git add . +git commit -m "Initial version" +``` + +도구를 게시하려면: + +```bash +crewai tool publish +``` + +기본적으로 도구는 비공개로 게시됩니다. 도구를 공개로 설정하려면: + +```bash +crewai tool publish --public +``` + +도구 빌드에 대한 자세한 내용은 [나만의 도구 만들기](/ko/concepts/tools#creating-your-own-tools)를 참고하세요. + +## 도구 업데이트 + +공개된 도구를 업데이트하려면: + +1. 로컬에서 도구를 수정합니다. +2. `pyproject.toml`에서 버전을 업데이트합니다(예: `0.1.0`에서 `0.1.1`로). +3. 변경 사항을 커밋하고 배포합니다. + +```bash +git commit -m "Update version to 0.1.1" +crewai tool publish +``` + +## 도구 삭제 + +도구를 삭제하려면: + +1. [CrewAI AMP](https://app.crewai.com)로 이동합니다. +2. **Tools**로 이동합니다. +3. 도구를 선택합니다. +4. **Delete**를 클릭합니다. + + + 삭제는 영구적입니다. 삭제된 도구는 복구하거나 다시 설치할 수 없습니다. + + +## 보안 점검 + +모든 공개된 버전은 자동화된 보안 점검을 거치며, 통과한 후에만 설치할 수 있습니다. + +도구의 보안 점검 상태는 다음에서 확인할 수 있습니다: + +`CrewAI AMP > Tools > Your Tool > Versions` + + + API 통합 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 문의해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/training-crews.mdx b/docs/v1.15.1/ko/enterprise/guides/training-crews.mdx new file mode 100644 index 000000000..0bd5c7a65 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/training-crews.mdx @@ -0,0 +1,132 @@ +--- +title: "Crew 훈련" +description: "CrewAI AMP 플랫폼에서 직접 배포된 Crew를 훈련하여 시간이 지남에 따라 에이전트 성능을 개선하세요" +icon: "dumbbell" +mode: "wide" +--- + +훈련을 통해 CrewAI AMP의 **Training** 탭에서 직접 반복 훈련 세션을 실행하여 Crew 성능을 개선할 수 있습니다. 플랫폼은 **자동 훈련 모드**를 사용합니다 — 반복 프로세스를 자동으로 처리하며, 반복마다 대화형 피드백이 필요한 CLI 훈련과는 다릅니다. + +훈련이 완료되면 CrewAI는 에이전트 출력을 평가하고 각 에이전트에 대한 실행 가능한 제안으로 피드백을 통합합니다. 이러한 제안은 향후 Crew 실행에 적용되어 출력 품질을 개선합니다. + + + CrewAI 훈련이 내부적으로 어떻게 작동하는지에 대한 자세한 내용은 [훈련 개념](/ko/concepts/training) 페이지를 참조하세요. + + +## 사전 요구 사항 + + + + **Ready** 상태의 활성 배포(Crew 유형)가 있는 CrewAI AMP 계정이 필요합니다. + + + 훈련하려는 배포에 대한 실행 권한이 계정에 있어야 합니다. + + + +## Crew 훈련 방법 + + + + **Deployments**로 이동하여 배포를 클릭한 다음 **Training** 탭을 선택합니다. + + + + **Training Name**을 입력합니다 — 이것은 훈련 결과를 저장하는 데 사용되는 `.pkl` 파일 이름이 됩니다. 예를 들어, "Expert Mode Training"은 `expert_mode_training.pkl`을 생성합니다. + + + + Crew의 입력 필드를 입력합니다. 이는 일반 kickoff에 제공하는 것과 동일한 입력값입니다 — Crew 구성에 따라 동적으로 로드됩니다. + + + + **Train Crew**를 클릭합니다. 프로세스가 실행되는 동안 버튼이 스피너와 함께 "Training..."으로 변경됩니다. + + 내부적으로: + - 배포에 대한 훈련 레코드가 생성됩니다 + - 플랫폼이 배포의 자동 훈련 엔드포인트를 호출합니다 + - Crew가 자동으로 반복을 실행합니다 — 수동 피드백이 필요하지 않습니다 + + + + **Current Training Status** 패널에 다음이 표시됩니다: + - **Status** — 훈련 실행의 현재 상태 + - **Nº Iterations** — 구성된 훈련 반복 횟수 + - **Filename** — 생성 중인 `.pkl` 파일 + - **Started At** — 훈련 시작 시간 + - **Training Inputs** — 제공한 입력값 + + + +## 훈련 결과 이해 + +훈련이 완료되면 다음 정보가 포함된 에이전트별 결과 카드가 표시됩니다: + +- **Agent Role** — Crew에서 에이전트의 이름/역할 +- **Final Quality** — 에이전트 출력 품질을 평가하는 0~10점 점수 +- **Final Summary** — 훈련 중 에이전트 성능 요약 +- **Suggestions** — 에이전트 동작 개선을 위한 실행 가능한 권장 사항 + +### 제안 편집 + +모든 에이전트의 제안을 개선할 수 있습니다: + + + + 에이전트의 결과 카드에서 제안 옆에 있는 **Edit** 버튼을 클릭합니다. + + + + 원하는 개선 사항을 더 잘 반영하도록 제안 텍스트를 업데이트합니다. + + + + **Save**를 클릭합니다. 편집된 제안이 배포에 다시 동기화되고 이후 모든 실행에 사용됩니다. + + + +## 훈련 데이터 사용 + +Crew에 훈련 결과를 적용하려면: + +1. 완료된 훈련 세션에서 **Training Filename**(`.pkl` 파일)을 확인합니다. +2. 배포의 kickoff 또는 실행 구성에서 이 파일 이름을 지정합니다. +3. Crew가 자동으로 훈련 파일을 로드하고 저장된 제안을 각 에이전트에 적용합니다. + +이는 에이전트가 이후 모든 실행에서 훈련 중에 생성된 피드백의 혜택을 받는다는 것을 의미합니다. + +## 이전 훈련 + +Training 탭 하단에는 배포에 대한 **모든 과거 훈련 세션 기록**이 표시됩니다. 이전 훈련 실행을 검토하거나 결과를 비교하거나 사용할 다른 훈련 파일을 선택하는 데 사용합니다. + +## 오류 처리 + +훈련 실행이 실패하면 상태 패널에 무엇이 잘못되었는지 설명하는 메시지와 함께 오류 상태가 표시됩니다. + +훈련 실패의 일반적인 원인: +- **배포 런타임이 업데이트되지 않음** — 배포가 최신 버전을 실행하고 있는지 확인하세요 +- **Crew 실행 오류** — Crew의 작업 로직 또는 에이전트 구성 내 문제 +- **네트워크 문제** — 플랫폼과 배포 간의 연결 문제 + +## 제한 사항 + + + 훈련 워크플로를 계획할 때 다음 제약 사항을 염두에 두세요: + - **배포당 한 번에 하나의 활성 훈련** — 다른 훈련을 시작하기 전에 현재 실행이 완료될 때까지 기다리세요 + - **자동 훈련 모드만** — 플랫폼은 CLI처럼 반복당 대화형 피드백을 지원하지 않습니다 + - **훈련 데이터는 배포별** — 훈련 결과는 특정 배포 인스턴스 및 버전에 연결됩니다 + + +## 관련 리소스 + + + + CrewAI 훈련이 내부적으로 어떻게 작동하는지 알아보세요. + + + AMP 플랫폼에서 배포된 Crew를 실행하세요. + + + Crew를 배포하고 훈련 준비를 완료하세요. + + diff --git a/docs/v1.15.1/ko/enterprise/guides/update-crew.mdx b/docs/v1.15.1/ko/enterprise/guides/update-crew.mdx new file mode 100644 index 000000000..f263a3091 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/update-crew.mdx @@ -0,0 +1,91 @@ +--- +title: "크루 업데이트" +description: "CrewAI AOP에서 크루 업데이트하기" +icon: "pencil" +mode: "wide" +--- + + + CrewAI AOP에 crew를 배포한 후, 코드, 보안 설정 또는 구성을 업데이트해야 할 수 + 있습니다. 이 가이드는 이러한 일반적인 업데이트 작업을 수행하는 방법을 + 설명합니다. + + +## 왜 Crew를 업데이트해야 하나요? + +CrewAI는 기본적으로 GitHub 업데이트를 자동으로 반영하지 않으므로, 배포 시 `Auto-update` 옵션을 선택하지 않았다면 수동으로 업데이트를 트리거해야 합니다. + +Crew 배포를 업데이트하고 싶은 이유는 여러 가지가 있을 수 있습니다: + +- GitHub에 푸시한 최신 커밋으로 코드를 업데이트하고 싶은 경우 +- 보안상의 이유로 bearer 토큰을 재설정하고 싶은 경우 +- 환경 변수를 업데이트하고 싶은 경우 + +## 1. 최신 커밋으로 Crew 코드 업데이트하기 + +GitHub 저장소에 새로운 커밋을 푸시한 후 배포를 업데이트하려면 다음 단계를 따르세요: + +1. CrewAI AMP 플랫폼에서 자신의 crew로 이동하세요. +2. crew 상세 페이지에서 `Re-deploy` 버튼을 클릭하세요. + +![Re-deploy Button](/images/enterprise/redeploy-button.png) + +이 작업을 수행하면 진행률 표시줄을 통해 추적할 수 있는 업데이트가 트리거됩니다. 시스템은 저장소에서 최신 코드를 가져와서 배포를 다시 빌드합니다. + +## 2. 베어러 토큰 재설정 + +현재 토큰이 유출되었을 가능성이 있다고 의심되는 경우 등, 새 베어러 토큰을 생성해야 한다면 다음 단계를 따르세요: + +1. CrewAI AMP 플랫폼에서 해당 crew로 이동하세요. +2. `Bearer Token` 섹션을 찾으세요. +3. 현재 토큰 옆에 있는 `Reset` 버튼을 클릭하세요. + +![Reset Token](/images/enterprise/reset-token.png) + + + 베어러 토큰을 재설정하면 이전 토큰은 즉시 사용할 수 없게 됩니다. 이전 토큰을 + 사용하고 있는 모든 애플리케이션이나 스크립트에서 토큰을 반드시 업데이트하세요. + + +## 3. 환경 변수 업데이트하기 + +crew의 환경 변수를 업데이트하려면 다음 단계를 따르세요: + +1. 먼저 crew 이름을 클릭하여 배포 페이지에 접속합니다. + +![환경 변수 버튼](/images/enterprise/env-vars-button.png) + +2. `Environment Variables` 섹션을 찾습니다 (`Settings` 아이콘을 클릭해야 접근할 수 있습니다) +3. 제공된 필드에서 기존 변수를 수정하거나 새 변수를 추가합니다 +4. 수정한 각 변수 옆의 `Update` 버튼을 클릭합니다 + +![환경 변수 업데이트](/images/enterprise/update-env-vars.png) + +5. 마지막으로, 변경 사항을 적용하려면 페이지 하단의 `Update Deployment` 버튼을 클릭합니다 + + + 환경 변수를 업데이트하면 새로운 배포가 트리거되지만, 이는 환경 설정만 + 업데이트하며 코드 자체는 변경되지 않습니다. + + +## 업데이트 후 + +업데이트를 수행한 후: + +1. 시스템이 crew를 다시 빌드하고 배포합니다 +2. 실시간으로 배포 진행 상황을 모니터링할 수 있습니다 +3. 완료되면 변경 사항이 예상대로 작동하는지 crew를 테스트합니다 + + + 업데이트 후 문제가 발생하면 플랫폼에서 배포 로그를 확인하거나 지원팀에 + 문의하여 도움을 받을 수 있습니다. + + + + crew 업데이트나 배포 문제 해결에 대해 지원이 필요하시면 지원팀에 문의해 + 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/guides/webhook-automation.mdx b/docs/v1.15.1/ko/enterprise/guides/webhook-automation.mdx new file mode 100644 index 000000000..7b3d55084 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/webhook-automation.mdx @@ -0,0 +1,126 @@ +--- +title: "웹후크 자동화" +description: "ActivePieces, Zapier, Make.com과 같은 플랫폼을 사용하여 CrewAI AMP 워크플로우를 웹후크로 자동화하세요" +icon: "webhook" +mode: "wide" +--- + +CrewAI AOP를 사용하면 웹훅을 통해 워크플로우를 자동화할 수 있습니다. 이 문서에서는 웹훅을 설정하고 사용하는 과정을 안내하며, Zapier와 Make.com과 유사한 워크플로우 자동화 플랫폼인 ActivePieces와의 통합에 중점을 두고 crew 실행을 시작하는 방법을 설명합니다. + +## Webhook 설정하기 + + + + - CrewAI AMP 대시보드로 이동하세요. + - crew 실행을 시작할 때 사용하는 `/kickoff` 섹션을 찾으세요. + + Kickoff 인터페이스 + + + + + JSON Content 섹션에서 다음 정보를 입력해야 합니다: + + - **inputs**: 다음 항목이 포함된 JSON 객체: + - `company`: 회사 이름 (예: "tesla") + - `product_name`: 제품 이름 (예: "crewai") + - `form_response`: 응답 유형 (예: "financial") + - `icp_description`: 이상적인 고객 프로필(ICP)에 대한 간략한 설명 + - `product_description`: 제품에 대한 짧은 설명 + - `taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`: 다양한 webhook 엔드포인트의 URL (ActivePieces, Zapier, Make.com 또는 기타 호환 플랫폼) + + + + 이 예시에서는 ActivePieces를 사용합니다. 또한 Zapier, Make.com 등 다른 플랫폼도 사용할 수 있습니다. + + ActivePieces와 통합하려면: + + 1. ActivePieces에서 새 flow를 설정하세요. + 2. 트리거를 추가하세요 (예: `Every Day` 스케줄). + + ActivePieces 트리거 + + + 3. HTTP 액션 단계를 추가하세요. + - 액션을 `Send HTTP request`로 설정하세요. + - 메소드는 `POST`로 사용하세요. + - URL은 CrewAI AMP kickoff 엔드포인트로 설정하세요. + - 필요한 헤더 추가 (예: `Bearer Token`) + + ActivePieces 헤더 + + + - Body에는 2단계에서 구성한 JSON content를 포함하세요. + + ActivePieces 본문 + + + - crew가 미리 정의된 시간에 kickoff됩니다. + + + + 1. ActivePieces에서 새 flow를 만들고 이름을 지정하세요. + + ActivePieces Flow + + + 2. 트리거로 webhook 단계를 추가하세요: + - 트리거 유형으로 `Catch Webhook`을 선택하세요. + - 이 작업을 통해 HTTP 요청을 수신하고 flow를 트리거하는 고유 URL이 생성됩니다. + + ActivePieces Webhook + + + - 이메일이 crew webhook 본문 텍스트를 사용하도록 구성하세요. + + ActivePieces 이메일 + + + + + +## Webhook 출력 예시 + +**참고:** kickoff 요청에 제공된 모든 `meta` 객체는 모든 webhook 페이로드에 포함되어, 전체 crew 실행 생명주기에 걸쳐 요청을 추적하고 컨텍스트를 유지할 수 있습니다. + + + + `stepWebhookUrl` - 각 agent의 inner thought가 실행될 때마다 호출되는 콜백 + + ```json + { + "action": "**crewai 엔터프라이즈 솔루션을 위한 금융 산업에 대한 예비 조사 보고서**\n1. 산업 개요 및 동향\n금융 산업은 ....\n결론:\n금융 산업은 디지털 고객 참여, 위험 관리, 규정 준수와 같은 분야에서 crewai와 같은 AI 솔루션을 적용하기에 비옥한 토양을 제공합니다. 고객의 구체적인 요구와 규모에 더 맞춘 crewai 솔루션을 제안하기 위해 리드와의 추가적인 접촉이 추천됩니다.", + "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0" + } + ``` + + + `taskWebhookUrl` - 각 task가 종료될 때마다 호출되는 콜백 + + ```json + { + "description": "리드의 데이터에서 수집한 정보를 활용해 리드가 속한 산업, 기업 배경, 그리고 crewai의 잠재적 활용 사례에 대해 예비 조사를 수행합니다. 리드 스코어링 및 crewai 피치 전략 수립에 도움이 되는 관련 데이터를 중심으로 조사하세요. 금융 산업은 디지털 고객 참여, 리스크 관리, 규제 준수와 같은 분야에서 crewai와 같은 AI 솔루션을 적용하기에 매우 적합한 환경을 제공합니다. 리드에 맞춤화된 crewai 솔루션을 제안하기 위해 추가적인 접촉을 권장합니다.", + "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0" + } + ``` + + + `crewWebhookUrl` - crew 실행 종료 시 호출되는 콜백 + + ```json + { + "task_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "result": { + "lead_score": "고객 서비스 향상 및 컴플라이언스가 특히 관련성이 높습니다.", + "talking_points": [ + "crewai의 AI 솔루션이 자동화된 맞춤형 경험과 24/7 지원으로 고객 서비스를 혁신하고, 고객 만족도와 운영 효율성을 모두 개선할 수 있음을 강조하세요.", + "crewai가 더 나은 데이터 분석 및 의사 결정으로 기관의 지속 가능성 목표 달성(책임 투자 및 친환경 이니셔티브 기여)에 도움이 될 수 있음을 논의하세요.", + "지속적으로 변화하는 규정에 효율적인 데이터 처리 및 보고 기능으로 crewai가 컴플라이언스 준수를 강화하고, 위반 시 발생할 수 있는 벌금을 줄일 수 있음을 강조하세요.", + "crewai의 뛰어난 적응성으로 인해 대규모 다국적 운영뿐 아니라 소규모 맞춤형 프로젝트도 지원하여, 기관의 성장과 함께 솔루션도 확장될 수 있음을 강조하세요." + ] + } + } + ``` + + + diff --git a/docs/v1.15.1/ko/enterprise/guides/zapier-trigger.mdx b/docs/v1.15.1/ko/enterprise/guides/zapier-trigger.mdx new file mode 100644 index 000000000..5b939496c --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/guides/zapier-trigger.mdx @@ -0,0 +1,105 @@ +--- +title: "Zapier 트리거" +description: "Zapier 워크플로우에서 CrewAI crew를 트리거하여 앱 간 워크플로우를 자동화합니다" +icon: "bolt" +mode: "wide" +--- + +이 가이드는 CrewAI AOP용 Zapier 트리거를 설정하는 과정을 안내합니다. 이를 통해 CrewAI AOP와 기타 애플리케이션 간의 워크플로우를 자동화할 수 있습니다. + +## 사전 요구 사항 + +- CrewAI AMP 계정 +- Zapier 계정 +- Slack 계정 (이 특정 예시에 해당) + +## 단계별 설정 + + + + - Zapier에서 새 Zap을 만듭니다. + + + Zapier 1 + + + + + + Zapier 2 + + - 트리거 이벤트로 `New Pushed Message`를 선택합니다. + - 아직 Slack 계정을 연결하지 않았다면 연결하세요. + + + + - Zap에 새 액션 단계를 추가합니다. + - CrewAI+를 액션 앱으로, Kickoff를 액션 이벤트로 선택합니다. + + + Zapier 5 + + + + + - CrewAI AMP 계정을 연결하세요. + - 워크플로에 적합한 Crew를 선택하세요. + + + Zapier 6 + + - Slack 메시지의 데이터를 사용하여 Crew의 입력값을 구성하세요. + + + + - CrewAI AOP에서 출력된 텍스트를 포맷팅하기 위해 추가 액션 단계를 추가합니다. + - Zapier의 포매팅 도구를 사용하여 Markdown 출력을 HTML로 변환합니다. + + + Zapier 8 + + + Zapier 9 + + + + + - 포맷팅된 출력을 이메일로 전송하는 마지막 액션 단계를 추가합니다. + - 원하는 이메일 서비스를 선택하세요 (예: Gmail, Outlook). + - 수신자, 제목, 본문 등 이메일 상세 정보를 구성하세요. + - 포맷팅된 CrewAI AMP 출력을 이메일 본문에 삽입합니다. + + + Zapier 7 + + + + + - Slack 채널에 텍스트를 입력하세요. + + + Zapier 10 + + + - 3점 버튼을 선택한 후 'Push to Zapier'를 선택하세요. + + + Zapier 11 + + + + + + Zapier 12 + + + + + +## 성공을 위한 팁 + +- CrewAI AMP 입력값이 Slack 메시지에서 올바르게 매핑되었는지 확인하세요. +- Zap을 활성화하기 전에 철저히 테스트하여 잠재적인 문제를 미리 파악하세요. +- 워크플로우 내에서 발생할 수 있는 실패 상황을 관리하기 위해 오류 처리 단계를 추가하는 것을 고려하세요. + +이 단계를 따르면 Slack 메시지로 트리거되는 자동화된 워크플로우와 CrewAI AMP 출력이 포함된 이메일 알림을 설정할 수 있습니다. diff --git a/docs/v1.15.1/ko/enterprise/integrations/asana.mdx b/docs/v1.15.1/ko/enterprise/integrations/asana.mdx new file mode 100644 index 000000000..ccdf815aa --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/asana.mdx @@ -0,0 +1,265 @@ +--- +title: Asana 연동 +description: "CrewAI를 위한 Asana 연동으로 팀 작업 및 프로젝트 조정." +icon: "circle" +mode: "wide" +--- + +## 개요 + +에이전트가 Asana를 통해 업무, 프로젝트, 팀 협업을 관리할 수 있도록 지원하세요. 작업 생성, 프로젝트 상태 업데이트, 담당 할당 관리, AI 기반 자동화를 통한 팀의 워크플로우 최적화를 손쉽게 할 수 있습니다. + +## 사전 준비 사항 + +Asana 연동을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 Asana 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Asana 계정 연결 + +## 아사나(Asana) 연동 설정 + +### 1. Asana 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **Asana**를 찾습니다. +3. **Connect**를 클릭하고 OAuth 플로우를 완료합니다. +4. 작업 및 프로젝트 관리를 위한 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Asana에 댓글을 생성합니다. + + **매개변수:** + - `task` (string, 필수): 작업 ID - 댓글이 추가될 작업의 ID입니다. 댓글 작성자는 현재 인증된 사용자입니다. + - `text` (string, 필수): 텍스트 (예: "This is a comment."). + + + + + **설명:** Asana에 프로젝트를 생성합니다. + + **매개변수:** + - `name` (string, 필수): 이름 (예: "Stuff to buy"). + - `workspace` (string, 필수): 워크스페이스 - Connect Portal Workflow 설정을 사용해 사용자가 프로젝트를 생성할 워크스페이스를 선택할 수 있도록 합니다. 공란인 경우 기본적으로 사용자의 첫 번째 워크스페이스가 선택됩니다. + - `team` (string, 선택): 팀 - Connect Portal Workflow 설정을 사용해 사용자가 이 프로젝트를 공유할 팀을 선택할 수 있도록 합니다. 공란인 경우 기본적으로 사용자의 첫 번째 팀이 선택됩니다. + - `notes` (string, 선택): 노트 (예: "These are things we need to purchase."). + + + + + **설명:** Asana의 프로젝트 목록을 가져옵니다. + + **매개변수:** + - `archived` (string, 선택): 보관됨 - 보관된 프로젝트를 보려면 "true", 활성 프로젝트만 보려면 "false", 보관됨과 활성 모두 보려면 "default"를 선택합니다. + - 옵션: `default`, `true`, `false` + + + + + **설명:** Asana에서 ID로 프로젝트를 가져옵니다. + + **매개변수:** + - `projectFilterId` (string, 필수): 프로젝트 ID. + + + + + **설명:** Asana에 작업을 생성합니다. + + **매개변수:** + - `name` (string, 필수): 이름 (예: "Task Name"). + - `workspace` (string, 선택): 워크스페이스 - Connect Portal Workflow 설정을 사용해 사용자가 작업을 생성할 워크스페이스를 선택할 수 있도록 합니다. 공란인 경우 기본적으로 사용자의 첫 번째 워크스페이스가 선택됩니다. + - `project` (string, 선택): 프로젝트 - Connect Portal Workflow 설정을 사용해 사용자가 이 작업을 생성할 프로젝트를 선택할 수 있도록 합니다. + - `notes` (string, 선택): 노트. + - `dueOnDate` (string, 선택): 마감일 - 이 작업이 완료되어야 하는 날짜입니다. Due At과 함께 사용할 수 없습니다. (예: "YYYY-MM-DD"). + - `dueAtDate` (string, 선택): 마감 시각 - 이 작업이 완료되어야 하는 날짜와 시간 (ISO 타임스탬프) 입니다. Due On과 함께 사용할 수 없습니다. (예: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, 선택): 담당자 - 이 작업이 할당될 Asana 사용자의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 담당자를 선택할 수 있도록 합니다. + - `gid` (string, 선택): 외부 ID - 이 작업과 연결할 애플리케이션의 ID입니다. 이 ID를 사용하여 이후 작업 업데이트를 동기화할 수 있습니다. + + + + + **설명:** Asana의 작업을 업데이트합니다. + + **매개변수:** + - `taskId` (string, 필수): 작업 ID - 업데이트할 작업의 ID입니다. + - `completeStatus` (string, 선택): 완료 상태. + - 옵션: `true`, `false` + - `name` (string, 선택): 이름 (예: "Task Name"). + - `notes` (string, 선택): 노트. + - `dueOnDate` (string, 선택): 마감일 - 이 작업이 완료되어야 하는 날짜입니다. Due At과 함께 사용할 수 없습니다. (예: "YYYY-MM-DD"). + - `dueAtDate` (string, 선택): 마감 시각 - 이 작업이 완료되어야 하는 날짜와 시간 (ISO 타임스탬프) 입니다. Due On과 함께 사용할 수 없습니다. (예: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, 선택): 담당자 - 이 작업이 할당될 Asana 사용자의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 담당자를 선택할 수 있도록 합니다. + - `gid` (string, 선택): 외부 ID - 이 작업과 연결할 애플리케이션의 ID입니다. 이 ID를 사용하여 이후 작업 업데이트를 동기화할 수 있습니다. + + + + + **설명:** Asana의 작업 목록을 가져옵니다. + + **매개변수:** + - `workspace` (string, 선택): 워크스페이스 - 작업을 필터링할 워크스페이스의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 워크스페이스를 선택할 수 있도록 합니다. + - `project` (string, 선택): 프로젝트 - 작업을 필터링할 프로젝트의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 프로젝트를 선택할 수 있도록 합니다. + - `assignee` (string, 선택): 담당자 - 작업을 필터링할 담당자의 ID입니다. Connect Portal Workflow 설정을 사용해 사용자가 담당자를 선택할 수 있도록 합니다. + - `completedSince` (string, 선택): 이후 완료됨 - 미완료이거나 해당 시간(ISO 또는 Unix 타임스탬프) 이후에 완료된 작업만 반환합니다. (예: "2014-04-25T16:15:47-04:00"). + + + + + **설명:** Asana에서 ID로 작업 목록을 가져옵니다. + + **매개변수:** + - `taskId` (string, 필수): 작업 ID. + + + + + **설명:** Asana에서 외부 ID로 작업을 가져옵니다. + + **매개변수:** + - `gid` (string, 필수): 외부 ID - 이 작업이 애플리케이션과 연동(또는 동기화)된 ID입니다. + + + + + **설명:** Asana에서 섹션에 작업을 추가합니다. + + **매개변수:** + - `sectionId` (string, 필수): 섹션 ID - 작업을 추가할 섹션의 ID입니다. + - `taskId` (string, 필수): 작업 ID - 작업의 ID입니다. (예: "1204619611402340"). + - `beforeTaskId` (string, 선택): 이전 작업 ID - 이 작업이 삽입될 섹션 내의 작업 ID입니다. 이후 작업 ID와 함께 사용할 수 없습니다. (예: "1204619611402340"). + - `afterTaskId` (string, 선택): 이후 작업 ID - 이 작업이 삽입될 섹션 내의 작업 ID입니다. 이전 작업 ID와 함께 사용할 수 없습니다. (예: "1204619611402340"). + + + + + **설명:** Asana에서 팀 목록을 가져옵니다. + + **매개변수:** + - `workspace` (string, 필수): 워크스페이스 - 인증된 사용자가 볼 수 있는 이 워크스페이스 내의 팀을 반환합니다. + + + + + **설명:** Asana에서 워크스페이스 목록을 가져옵니다. + + **매개변수:** 필요 없음. + + + + +## 사용 예시 + +### 기본 Asana 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Asana capabilities +asana_agent = Agent( + role="Project Manager", + goal="Manage tasks and projects in Asana efficiently", + backstory="An AI assistant specialized in project management and task coordination.", + apps=['asana'] +) + +# Task to create a new project +create_project_task = Task( + description="Create a new project called 'Q1 Marketing Campaign' in the Marketing workspace", + agent=asana_agent, + expected_output="Confirmation that the project was created successfully with project ID" +) + +# Run the task +crew = Crew( + agents=[asana_agent], + tasks=[create_project_task] +) + +crew.kickoff() +``` + +### 특정 Asana 도구 필터링 + +```python + +task_manager_agent = Agent( + role="Task Manager", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and management.", + apps=['asana'] +) + +# Task to create and assign a task +task_management = Task( + description="Create a task called 'Review quarterly reports' and assign it to the appropriate team member", + agent=task_manager_agent, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_manager_agent], + tasks=[task_management] +) + +crew.kickoff() +``` + +### 고급 프로젝트 관리 + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate project activities and track progress", + backstory="An experienced project coordinator who ensures projects run smoothly.", + apps=['asana'] +) + +# Complex task involving multiple Asana operations +coordination_task = Task( + description=""" + 1. Get all active projects in the workspace + 2. For each project, get the list of incomplete tasks + 3. Create a summary report task in the 'Management Reports' project + 4. Add comments to overdue tasks to request status updates + """, + agent=project_coordinator, + expected_output="Summary report created and status update requests sent for overdue tasks" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ko/enterprise/integrations/box.mdx b/docs/v1.15.1/ko/enterprise/integrations/box.mdx new file mode 100644 index 000000000..4cdeed4a4 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/box.mdx @@ -0,0 +1,277 @@ +--- +title: Box 통합 +description: "CrewAI용 Box 통합을 통한 파일 저장 및 문서 관리." +icon: "box" +mode: "wide" +--- + +## 개요 + +에이전트가 Box를 통해 파일, 폴더, 문서를 관리할 수 있도록 지원하세요. 파일을 업로드하고, 폴더 구조를 조직하며, 콘텐츠를 검색하고, AI 기반 자동화를 통해 팀의 문서 관리를 효율적으로 진행할 수 있습니다. + +## 사전 준비 사항 + +Box 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 Box 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Box 계정 연결 + +## Box 통합 설정 + +### 1. Box 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **Box**를 찾습니다. +3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다. +4. 파일 및 폴더 관리를 위한 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 액션 + + + + **설명:** Box에서 URL로부터 파일을 저장합니다. + + **파라미터:** + - `fileAttributes` (object, 필수): 속성 - 이름, 상위 폴더, 타임스탬프 등 파일 메타데이터. + ```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, 필수): 파일 URL - 파일 크기는 50MB 미만이어야 합니다. (예시: "https://picsum.photos/200/300"). + + + + + **설명:** Box에 파일을 저장합니다. + + **파라미터:** + - `file` (string, 필수): 파일 - 파일 데이터를 포함하는 파일 객체를 허용합니다. 파일 크기는 50MB 미만이어야 합니다. + - `fileName` (string, 필수): 파일명 (예시: "qwerty.png"). + - `folder` (string, 선택): 폴더 - Connect Portal Workflow Settings를 사용하여 사용자가 파일의 폴더 목적지를 선택할 수 있도록 합니다. 비워두면 기본적으로 사용자의 루트 폴더에 저장됩니다. + + + + + **설명:** Box에서 ID로 파일을 가져옵니다. + + **파라미터:** + - `fileId` (string, 필수): 파일 ID - 파일을 나타내는 고유 식별자. (예시: "12345"). + + + + + **설명:** Box에서 파일 목록을 조회합니다. + + **파라미터:** + - `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0"). + - `filterFormula` (object, 선택): 쿼리 normal form (DNF)의 필터 - 단일 조건의 AND 그룹의 OR. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "direction", + "operator": "$stringExactlyMatches", + "value": "ASC" + } + ] + } + ] + } + ``` + + + + + **설명:** Box에 폴더를 생성합니다. + + **파라미터:** + - `folderName` (string, 필수): 이름 - 새 폴더의 이름. (예시: "New Folder"). + - `folderParent` (object, 필수): 상위 폴더 - 새 폴더가 생성될 상위 폴더. + ```json + { + "id": "123456" + } + ``` + + + + + **설명:** Box에서 폴더를 이동합니다. + + **파라미터:** + - `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0"). + - `folderName` (string, 필수): 이름 - 폴더의 이름. (예시: "New Folder"). + - `folderParent` (object, 필수): 상위 폴더 - 새 상위 폴더 목적지. + ```json + { + "id": "123456" + } + ``` + + + + + **설명:** Box에서 ID로 폴더를 가져옵니다. + + **파라미터:** + - `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0"). + + + + + **설명:** Box에서 폴더를 검색합니다. + + **파라미터:** + - `folderId` (string, 필수): 폴더 ID - 검색할 폴더. + - `filterFormula` (object, 선택): 쿼리 normal form (DNF)의 필터 - 단일 조건의 AND 그룹의 OR. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "sort", + "operator": "$stringExactlyMatches", + "value": "name" + } + ] + } + ] + } + ``` + + + + + **설명:** Box에서 폴더를 삭제합니다. + + **파라미터:** + - `folderId` (string, 필수): 폴더 ID - 폴더를 나타내는 고유 식별자. (예시: "0"). + - `recursive` (boolean, 선택): 재귀적 삭제 - 폴더가 비어 있지 않을 경우, 폴더와 그 모든 내용을 재귀적으로 삭제합니다. + + + + +## 사용 예시 + +### 기본 Box Agent 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Box capabilities +box_agent = Agent( + role="Document Manager", + goal="Manage files and folders in Box efficiently", + backstory="An AI assistant specialized in document management and file organization.", + apps=['box'] +) + +# Task to create a folder structure +create_structure_task = Task( + description="Create a folder called 'Project Files' in the root directory and upload a document from URL", + agent=box_agent, + expected_output="Folder created and file uploaded successfully" +) + +# Run the task +crew = Crew( + agents=[box_agent], + tasks=[create_structure_task] +) + +crew.kickoff() +``` + +### 특정 Box 도구 필터링 + +```python + +file_organizer_agent = Agent( + role="File Organizer", + goal="Organize and manage file storage efficiently", + backstory="An AI assistant that focuses on file organization and storage management.", + apps=['box'] +) + +# Task to organize files +organization_task = Task( + description="Create a folder structure for the marketing team and organize existing files", + agent=file_organizer_agent, + expected_output="Folder structure created and files organized" +) + +crew = Crew( + agents=[file_organizer_agent], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### 고급 파일 관리 + +```python +from crewai import Agent, Task, Crew + +file_manager = Agent( + role="File Manager", + goal="Maintain organized file structure and manage document lifecycle", + backstory="An experienced file manager who ensures documents are properly organized and accessible.", + apps=['box'] +) + +# Complex task involving multiple Box operations +management_task = Task( + description=""" + 1. List all files in the root folder + 2. Create monthly archive folders for the current year + 3. Move old files to appropriate archive folders + 4. Generate a summary report of the file organization + """, + agent=file_manager, + expected_output="Files organized into archive structure with summary report" +) + +crew = Crew( + agents=[file_manager], + tasks=[management_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ko/enterprise/integrations/clickup.mdx b/docs/v1.15.1/ko/enterprise/integrations/clickup.mdx new file mode 100644 index 000000000..0f66fe0de --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/clickup.mdx @@ -0,0 +1,304 @@ +--- +title: ClickUp 연동 +description: "CrewAI를 위한 ClickUp 연동을 통한 작업 및 생산성 관리." +icon: "list-check" +mode: "wide" +--- + +## 개요 + +에이전트가 ClickUp을 통해 작업, 프로젝트 및 생산성 워크플로우를 관리할 수 있도록 지원하세요. 작업을 생성 및 업데이트하고, 프로젝트를 구성하며, 팀 할당을 관리하고, AI 기반 자동화를 통해 생산성 관리를 간소화할 수 있습니다. + +## 사전 준비사항 + +ClickUp 통합을 사용하기 전에 다음을 준비해야 합니다: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 ClickUp 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 ClickUp 계정 연결 + +## ClickUp 통합 설정 + +### 1. ClickUp 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **ClickUp**을 찾습니다. +3. **Connect**를 클릭하고 OAuth 과정을 완료합니다. +4. 작업 및 프로젝트 관리에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 동작 + + + + **설명:** 고급 필터를 사용하여 ClickUp에서 작업을 검색합니다. + + **파라미터:** + - `taskFilterFormula` (object, 선택): 이항 표준형(DNF)의 필터 - 단일 조건의 AND 그룹들의 OR. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "statuses%5B%5D", + "operator": "$stringExactlyMatches", + "value": "open" + } + ] + } + ] + } + ``` + 사용 가능한 필드: `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` + + + + + **설명:** ClickUp의 특정 목록에서 작업을 가져옵니다. + + **파라미터:** + - `listId` (string, 필수): 목록 - 작업을 가져올 목록을 선택합니다. 사용자가 ClickUp 목록을 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `taskFilterFormula` (string, 선택): 지정된 필터와 일치하는 작업을 검색합니다. 예: name=task1. + + + + + **설명:** ClickUp에 작업을 생성합니다. + + **파라미터:** + - `listId` (string, 필수): 목록 - 이 작업을 생성할 목록을 선택합니다. 사용자가 ClickUp 목록을 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `name` (string, 필수): 이름 - 작업 이름. + - `description` (string, 선택): 설명 - 작업 설명. + - `status` (string, 선택): 상태 - 이 작업에 대한 상태를 선택합니다. 사용자가 ClickUp 상태를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `assignees` (string, 선택): 담당자 - 이 작업에 할당할 멤버(또는 멤버 ID 배열)를 선택합니다. 사용자가 ClickUp 멤버를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `dueDate` (string, 선택): 마감일 - 이 작업의 마감일을 지정합니다. + - `additionalFields` (string, 선택): 추가 필드 - 이 작업에 포함할 추가 필드를 JSON으로 지정합니다. + + + + + **설명:** ClickUp의 작업을 업데이트합니다. + + **파라미터:** + - `taskId` (string, 필수): 작업 ID - 업데이트할 작업의 ID입니다. + - `listId` (string, 필수): 목록 - 이 작업을 생성할 목록을 선택합니다. 사용자가 ClickUp 목록을 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `name` (string, 선택): 이름 - 작업 이름. + - `description` (string, 선택): 설명 - 작업 설명. + - `status` (string, 선택): 상태 - 이 작업에 대한 상태를 선택합니다. 사용자가 ClickUp 상태를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `assignees` (string, 선택): 담당자 - 이 작업에 할당할 멤버(또는 멤버 ID 배열)를 선택합니다. 사용자가 ClickUp 멤버를 선택할 수 있도록 Connect Portal 사용자 설정을 사용하세요. + - `dueDate` (string, 선택): 마감일 - 이 작업의 마감일을 지정합니다. + - `additionalFields` (string, 선택): 추가 필드 - 이 작업에 포함할 추가 필드를 JSON으로 지정합니다. + + + + + **설명:** ClickUp에서 작업을 삭제합니다. + + **파라미터:** + - `taskId` (string, 필수): 작업 ID - 삭제할 작업의 ID입니다. + + + + + **설명:** ClickUp에서 목록 정보를 가져옵니다. + + **파라미터:** + - `spaceId` (string, 필수): 스페이스 ID - 목록이 포함된 스페이스의 ID입니다. + + + + + **설명:** ClickUp에서 목록의 사용자 정의 필드를 가져옵니다. + + **파라미터:** + - `listId` (string, 필수): 목록 ID - 사용자 정의 필드를 가져올 목록의 ID입니다. + + + + + **설명:** ClickUp에서 목록의 모든 필드를 가져옵니다. + + **파라미터:** + - `listId` (string, 필수): 목록 ID - 모든 필드를 가져올 목록의 ID입니다. + + + + + **설명:** ClickUp에서 스페이스 정보를 가져옵니다. + + **파라미터:** + - `spaceId` (string, 선택): 스페이스 ID - 조회할 스페이스의 ID입니다. + + + + + **설명:** ClickUp에서 폴더를 가져옵니다. + + **파라미터:** + - `spaceId` (string, 필수): 스페이스 ID - 폴더가 포함된 스페이스의 ID입니다. + + + + + **설명:** ClickUp에서 멤버 정보를 가져옵니다. + + **파라미터:** 필요 없음. + + + + +## 사용 예시 + +### 기본 ClickUp 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with ClickUp capabilities +clickup_agent = Agent( + role="Task Manager", + goal="Manage tasks and projects in ClickUp efficiently", + backstory="An AI assistant specialized in task management and productivity coordination.", + apps=['clickup'] +) + +# Task to create a new task +create_task = Task( + description="Create a task called 'Review Q1 Reports' in the Marketing list with high priority", + agent=clickup_agent, + expected_output="Task created successfully with task ID" +) + +# Run the task +crew = Crew( + agents=[clickup_agent], + tasks=[create_task] +) + +crew.kickoff() +``` + +### 특정 ClickUp 도구 필터링 + +```python + +task_coordinator = Agent( + role="Task Coordinator", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and status management.", + apps=['clickup'] +) + +# Task to manage task workflow +task_workflow = Task( + description="Create a task for project planning and assign it to the development team", + agent=task_coordinator, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_coordinator], + tasks=[task_workflow] +) + +crew.kickoff() +``` + +### 고급 프로젝트 관리 + +```python +from crewai import Agent, Task, Crew + +project_manager = Agent( + role="Project Manager", + goal="Coordinate project activities and track team productivity", + backstory="An experienced project manager who ensures projects are delivered on time.", + apps=['clickup'] +) + +# Complex task involving multiple ClickUp operations +project_coordination = Task( + description=""" + 1. Get all open tasks in the current space + 2. Identify overdue tasks and update their status + 3. Create a weekly report task summarizing project progress + 4. Assign the report task to the team lead + """, + agent=project_manager, + expected_output="Project status updated and weekly report task created and assigned" +) + +crew = Crew( + agents=[project_manager], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### 작업 검색 및 관리 + +```python +from crewai import Agent, Task, Crew + +task_analyst = Agent( + role="Task Analyst", + goal="Analyze task patterns and optimize team productivity", + backstory="An AI assistant that analyzes task data to improve team efficiency.", + apps=['clickup'] +) + +# Task to analyze and optimize task distribution +task_analysis = Task( + description=""" + Search for all tasks assigned to team members in the last 30 days, + analyze completion patterns, and create optimization recommendations + """, + agent=task_analyst, + expected_output="Task analysis report with optimization recommendations" +) + +crew = Crew( + agents=[task_analyst], + tasks=[task_analysis] +) + +crew.kickoff() +``` + +### 도움 받기 + + + ClickUp 연동 설정 또는 문제 해결에 대한 지원이 필요하신 경우 저희 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/databricks.mdx b/docs/v1.15.1/ko/enterprise/integrations/databricks.mdx new file mode 100644 index 000000000..346c675bc --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/databricks.mdx @@ -0,0 +1,123 @@ +--- +title: Databricks 연동 +description: "Databricks 관리형 MCP 서버를 통해 CrewAI 에이전트를 Databricks Genie, SQL, Unity Catalog Functions, Vector Search에 연결하세요." +icon: "layer-group" +mode: "wide" +--- + +## 개요 + +[Databricks 관리형 MCP 서버](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)를 통해 CrewAI 에이전트를 Databricks 워크스페이스에 직접 연결하세요. Databricks 연동을 사용하면 에이전트가 **Genie**로 자연어 질문을 하고, 거버넌스가 적용된 **SQL**을 실행하며, **Unity Catalog Functions**를 호출하고, **Vector Search**로 문서를 검색할 수 있습니다. 커넥터 코드를 작성하거나 호스팅할 필요가 없으며, 모든 호출에 Unity Catalog 권한이 적용됩니다. + +내부적으로 Databricks 연동은 CrewAI의 [커스텀 MCP 서버](/ko/enterprise/guides/custom-mcp-server) 지원을 감싼 관리형 래퍼입니다. Databricks는 각 기능을 개별 [Model Context Protocol](https://modelcontextprotocol.io/) 엔드포인트로 노출하며, CrewAI가 사용자를 대신해 안전하게 연결합니다. 각 서버를 개별적으로 추가하므로 크루에 필요한 기능만 정확히 활성화할 수 있습니다. + +## 주요 기능 + + + + [Genie](https://docs.databricks.com/aws/en/genie/)로 자연어 질문을 하고 데이터 기반의 근거 있는 답변을 받으세요. Genie는 Genie Spaces와 Unity Catalog를 조회하고 Databricks UI로 연결되는 링크를 제공합니다. + + + 에이전트에서 직접 Databricks 웨어하우스에 거버넌스가 적용된 SQL을 실행하여 데이터를 조회, 변환하고 데이터 파이프라인을 작성하세요. + + + [Unity Catalog 함수](https://docs.databricks.com/aws/en/udf/unity-catalog)를 호출하여 사전 정의된 SQL과 맞춤형 비즈니스 로직을 거버넌스가 적용된 재사용 가능한 도구로 실행하세요. + + + [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) 인덱스에서 의미 유사도를 사용해 RAG 및 지식 워크플로우에 필요한 관련 문서를 검색하세요. + + + +모든 서버는 Unity AI Gateway 뒤에서 실행되며 Unity Catalog 접근 제어를 적용하므로, 에이전트는 허용된 데이터와 도구만 볼 수 있습니다. + +## 사전 준비사항 + +Databricks 연동을 사용하기 전에 다음을 준비해야 합니다: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 노출하려는 기능이 있는 Databricks 워크스페이스(Genie Spaces, SQL 웨어하우스, Unity Catalog 함수 또는 Vector Search 인덱스) +- 기본 객체에 대한 적절한 [Unity Catalog 권한](https://docs.databricks.com/aws/en/data-governance/unity-catalog) +- Databricks 워크스페이스 호스트명(예: `your-workspace.cloud.databricks.com`) + +## Databricks 관리형 MCP 서버 + +Databricks는 각 기능마다 별도의 관리형 MCP 서버를 게시합니다. CrewAI는 이를 개별 연결로 노출하며, 각 연결은 워크스페이스 호스트와 관련 Unity Catalog 식별자로 구성됩니다. 엔드포인트는 다음 패턴을 따릅니다: + +| 서버 | 기능 | MCP URL 패턴 | +|------|------|--------------| +| **Genie** | Genie Space에 대한 자연어 Q&A | `https:///api/2.0/mcp/genie/{genie_space_id}` | +| **Databricks SQL** | 웨어하우스에 SQL 실행 | `https:///api/2.0/mcp/sql` | +| **Unity Catalog Functions** | 등록된 UC 함수 실행 | `https:///api/2.0/mcp/functions/{catalog}/{schema}` | +| **Vector Search** | Vector Search 인덱스 조회 | `https:///api/2.0/mcp/vector-search/{catalog}/{schema}` | + + +이러한 URL을 직접 만들 필요는 없습니다. CrewAI는 연결을 구성할 때 입력한 워크스페이스 호스트와 식별자(Genie Space ID 또는 catalog/schema)로 각 엔드포인트를 생성합니다. 전체 사양과 최신 엔드포인트 세부 정보는 [Databricks 관리형 MCP 문서](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)를 참고하세요. + + +## CrewAI AMP에서 Databricks 연결하기 + + + CrewAI AMP에서 Databricks 관리형 MCP 서버 구성 + + +각 Databricks 기능(**Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions**, **Databricks Vector Search**)은 **Tools & Integrations** 페이지의 Databricks 그룹 아래에 별도의 MCP 서버로 표시됩니다. 필요한 것을 구성하세요: + + + + CrewAI AMP 왼쪽 사이드바에서 **Tools & Integrations**로 이동하여 Connections 목록에서 **Databricks** 그룹을 찾습니다. 그 아래에 Genie, SQL, Unity Catalog Functions, Vector Search 서버가 나열됩니다. + + + + 활성화하려는 기능 옆의 **Configure**를 클릭하고 연결 세부 정보를 입력합니다: + + - **Workspace Host** — Databricks 워크스페이스 호스트명(예: `my-workspace.cloud.databricks.com`). + - **Genie** — 조회할 **Genie Space ID**. + - **Unity Catalog Functions** — 함수가 포함된 **catalog**와 **schema**. + - **Vector Search** — 인덱스가 포함된 **catalog**와 **schema**. + - **Databricks SQL** — 추가 식별자가 필요 없으며, 쿼리는 워크스페이스의 SQL 웨어하우스에서 실행됩니다. + + + + CrewAI가 Databricks에 인증하는 방법을 선택합니다. **OAuth**를 권장합니다. + + - **Use OAuth** — OAuth 2.0으로 안전하게 연결합니다. 각 사용자가 개별적으로 인증하며, Databricks는 해당 기능(`genie`, `sql`, `unity-catalog` 또는 `vector-search`)으로 범위가 지정된 토큰을 발급합니다. CrewAI가 인증 흐름을 처리하고 토큰을 자동으로 갱신합니다. + - **Use personal access token** — [Databricks 개인 액세스 토큰](https://docs.databricks.com/aws/en/dev-tools/auth/pat)으로 인증합니다. 노출을 제한하려면 최소 권한 ID를 사용하세요. + + + + 인증을 완료합니다. 연결되면 해당 서버의 도구를 크루에서 사용할 수 있습니다. 활성화하려는 다른 Databricks 기능에 대해서도 반복합니다. + + + + +각 기능이 별도의 연결이므로 자유롭게 조합할 수 있습니다. 예를 들어 리서치 크루에는 Genie와 Vector Search를 활성화하고, 데이터 엔지니어링 크루에는 SQL과 Unity Catalog Functions를 사용하도록 할 수 있습니다. 가시성(Visibility) 설정으로 각 기능을 사용할 수 있는 팀원을 제어할 수 있습니다. + + +## 크루에서 Databricks 도구 사용하기 + +연결되면 각 MCP 서버가 노출하는 도구가 **Tools & Integrations** 페이지의 기본 제공 연결과 함께 표시됩니다. 다음을 할 수 있습니다: + +- 다른 CrewAI 도구와 마찬가지로 크루의 에이전트에 **도구 할당**. +- 각 연결을 사용할 수 있는 팀원을 제어하는 **가시성 관리**. +- Connections 목록에서 언제든지 연결 **편집 또는 제거**. + +이제 에이전트는 Genie에 근거 있는 답변을 요청하고, 웨어하우스에 SQL을 실행하며, Unity Catalog 함수를 호출하고, Vector Search 인덱스를 검색할 수 있으며, 그 결과가 자동으로 추론에 반영됩니다. + + +Databricks는 Unity Catalog와 Unity AI Gateway를 통해 거버넌스를 적용합니다. 사용자는 워크스페이스 ID에 허용된 도구만 검색하고 호출할 수 있습니다. 도구 호출이 실패하면 연결하는 사용자(또는 토큰 ID)가 Genie Space, 웨어하우스, 함수 또는 인덱스에 필요한 Unity Catalog 권한을 가지고 있는지 확인하세요. 일부 Genie 및 SQL 쿼리는 비동기로 실행되어 결과를 반환하는 데 시간이 걸릴 수 있습니다. + + +## 더 알아보기 + + + + 관리형 Genie, SQL, Unity Catalog Functions, Vector Search MCP 서버에 대한 공식 Databricks 문서입니다. + + + Databricks 연동의 기반이 되는, CrewAI가 모든 MCP 서버에 연결하는 방법을 알아보세요. + + + + + Databricks 연동 구성 또는 문제 해결에 대한 지원이 필요하면 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/github.mdx b/docs/v1.15.1/ko/enterprise/integrations/github.mdx new file mode 100644 index 000000000..b297a8ac1 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/github.mdx @@ -0,0 +1,332 @@ +--- +title: GitHub 통합 +description: "CrewAI를 위한 GitHub 통합을 통한 리포지토리 및 이슈 관리." +icon: "github" +mode: "wide" +--- + +## 개요 + +에이전트가 GitHub를 통해 리포지토리, 이슈, 릴리스를 관리할 수 있도록 지원합니다. 이슈를 생성 및 업데이트하고, 릴리스를 관리하고, 프로젝트 개발을 추적하며, AI 기반 자동화를 통해 소프트웨어 개발 워크플로우를 효율화하세요. + +## 사전 요구 사항 + +GitHub 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 해당 리포지토리에 대한 적절한 권한이 있는 GitHub 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 GitHub 계정 연결 완료 + +## GitHub 연동 설정 + +### 1. GitHub 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **GitHub**을 찾습니다. +3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다. +4. 리포지토리 및 이슈 관리를 위한 필수 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** GitHub에 이슈를 생성합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다. + - `title` (string, 필수): 이슈 제목 - 생성할 이슈의 제목을 지정합니다. + - `body` (string, 선택): 이슈 본문 - 생성할 이슈의 본문 내용을 지정합니다. + - `assignees` (string, 선택): 담당자 - 이 이슈의 담당자 GitHub 로그인을 문자열 배열로 지정합니다. (예시: `["octocat"]`). + + + + + **설명:** GitHub에서 이슈를 업데이트합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다. + - `issue_number` (string, 필수): 이슈 번호 - 업데이트할 이슈의 번호를 지정합니다. + - `title` (string, 필수): 이슈 제목 - 업데이트할 이슈의 제목을 지정합니다. + - `body` (string, 선택): 이슈 본문 - 업데이트할 이슈의 본문 내용을 지정합니다. + - `assignees` (string, 선택): 담당자 - 이 이슈의 담당자 GitHub 로그인을 문자열 배열로 지정합니다. (예시: `["octocat"]`). + - `state` (string, 선택): 상태 - 이슈의 변경된 상태를 지정합니다. + - 옵션: `open`, `closed` + + + + + **설명:** GitHub에서 번호로 이슈를 조회합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다. + - `issue_number` (string, 필수): 이슈 번호 - 가져올 이슈의 번호를 지정합니다. + + + + + **설명:** GitHub에서 이슈를 잠급니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다. + - `issue_number` (string, 필수): 이슈 번호 - 잠글 이슈의 번호를 지정합니다. + - `lock_reason` (string, 필수): 잠금 사유 - 이슈 또는 풀 리퀘스트 대화에 대한 잠금 이유를 지정합니다. + - 옵션: `off-topic`, `too heated`, `resolved`, `spam` + + + + + **설명:** GitHub에서 이슈를 검색합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 이슈와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 이슈와 연관된 저장소 이름을 지정합니다. + - `filter` (object, 필수): 불리언 표준형의 필터 - 단일 조건의 AND 그룹의 OR 조합. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "assignee", + "operator": "$stringExactlyMatches", + "value": "octocat" + } + ] + } + ] + } + ``` + 사용 가능한 필드: `assignee`, `creator`, `mentioned`, `labels` + + + + + **설명:** GitHub에 릴리스를 생성합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다. + - `tag_name` (string, 필수): 이름 - 생성할 릴리스 태그의 이름을 지정합니다. (예시: "v1.0.0"). + - `target_commitish` (string, 선택): 대상 - 릴리스의 대상을 지정합니다. 브랜치 이름이나 커밋 SHA가 될 수 있으며, 기본값은 메인 브랜치입니다. (예시: "master"). + - `body` (string, 선택): 본문 - 이 릴리스에 대한 설명을 지정합니다. + - `draft` (string, 선택): 초안 - 생성할 릴리스를 초안(비공개) 릴리스로 지정할지 여부를 지정합니다. + - 옵션: `true`, `false` + - `prerelease` (string, 선택): 프리릴리스 - 생성할 릴리스를 프리릴리스로 지정할지 여부를 지정합니다. + - 옵션: `true`, `false` + - `discussion_category_name` (string, 선택): 토론 카테고리 이름 - 지정 시, 해당 카테고리의 토론이 생성되어 릴리스와 연결됩니다. 값은 저장소에 이미 존재하는 카테고리여야 합니다. + - `generate_release_notes` (string, 선택): 릴리스 노트 - 지정한 이름과 본문을 사용하여 릴리스 노트를 자동으로 생성할지 여부를 지정합니다. + - 옵션: `true`, `false` + + + + + **설명:** GitHub에서 릴리스를 업데이트합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다. + - `id` (string, 필수): 릴리스 ID - 업데이트할 릴리스의 ID를 지정합니다. + - `tag_name` (string, 선택): 이름 - 업데이트할 릴리스 태그의 이름을 지정합니다. (예시: "v1.0.0"). + - `target_commitish` (string, 선택): 대상 - 릴리스의 대상을 지정합니다. 브랜치 이름이나 커밋 SHA가 될 수 있으며, 기본값은 메인 브랜치입니다. (예시: "master"). + - `body` (string, 선택): 본문 - 이 릴리스에 대한 설명을 지정합니다. + - `draft` (string, 선택): 초안 - 생성할 릴리스를 초안(비공개) 릴리스로 지정할지 여부를 지정합니다. + - 옵션: `true`, `false` + - `prerelease` (string, 선택): 프리릴리스 - 생성할 릴리스를 프리릴리스로 지정할지 여부를 지정합니다. + - 옵션: `true`, `false` + - `discussion_category_name` (string, 선택): 토론 카테고리 이름 - 지정 시, 해당 카테고리의 토론이 생성되어 릴리스와 연결됩니다. 값은 저장소에 이미 존재하는 카테고리여야 합니다. + - `generate_release_notes` (string, 선택): 릴리스 노트 - 지정한 이름과 본문을 사용하여 릴리스 노트를 자동으로 생성할지 여부를 지정합니다. + - 옵션: `true`, `false` + + + + + **설명:** GitHub에서 ID로 릴리스를 조회합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다. + - `id` (string, 필수): 릴리스 ID - 조회할 릴리스의 ID를 지정합니다. + + + + + **설명:** GitHub에서 태그 이름으로 릴리스를 조회합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다. + - `tag_name` (string, 필수): 이름 - 가져올 릴리스의 태그를 지정합니다. (예시: "v1.0.0"). + + + + + **설명:** GitHub에서 릴리스를 삭제합니다. + + **파라미터:** + - `owner` (string, 필수): 소유자 - 이 릴리스와 연관된 저장소의 계정 소유자 이름을 지정합니다. (예시: "abc"). + - `repo` (string, 필수): 저장소 - 이 릴리스와 연관된 저장소 이름을 지정합니다. + - `id` (string, 필수): 릴리스 ID - 삭제할 릴리스의 ID를 지정합니다. + + + + +## 사용 예시 + +### 기본 GitHub 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with GitHub capabilities +github_agent = Agent( + role="Repository Manager", + goal="Manage GitHub repositories, issues, and releases efficiently", + backstory="An AI assistant specialized in repository management and issue tracking.", + apps=['github'] +) + +# Task to create a new issue +create_issue_task = Task( + description="Create a bug report issue for the login functionality in the main repository", + agent=github_agent, + expected_output="Issue created successfully with issue number" +) + +# Run the task +crew = Crew( + agents=[github_agent], + tasks=[create_issue_task] +) + +crew.kickoff() +``` + +### 특정 GitHub 도구 필터링 + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage GitHub issues efficiently", + backstory="An AI assistant that focuses on issue tracking and management.", + apps=['github'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and assign it to the development team", + agent=issue_manager, + expected_output="Feature request issue created and assigned successfully" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### 릴리즈 관리 + +```python +from crewai import Agent, Task, Crew + +release_manager = Agent( + role="Release Manager", + goal="Manage software releases and versioning", + backstory="An experienced release manager who handles version control and release processes.", + apps=['github'] +) + +# Task to create a new release +release_task = Task( + description=""" + Create a new release v2.1.0 for the project with: + - Auto-generated release notes + - Target the main branch + - Include a description of new features and bug fixes + """, + agent=release_manager, + expected_output="Release v2.1.0 created successfully with release notes" +) + +crew = Crew( + agents=[release_manager], + tasks=[release_task] +) + +crew.kickoff() +``` + +### 이슈 추적 및 관리 + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Track and coordinate project issues and development progress", + backstory="An AI assistant that helps coordinate development work and track project progress.", + apps=['github'] +) + +# Complex task involving multiple GitHub operations +coordination_task = Task( + description=""" + 1. Search for all open issues assigned to the current milestone + 2. Identify overdue issues and update their priority labels + 3. Create a weekly progress report issue + 4. Lock resolved issues that have been inactive for 30 days + """, + agent=project_coordinator, + expected_output="Project coordination completed with progress report and issue management" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### 도움 받기 + + + GitHub 통합 설정 또는 문제 해결에 대해 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/gmail.mdx b/docs/v1.15.1/ko/enterprise/integrations/gmail.mdx new file mode 100644 index 000000000..54ed3f062 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/gmail.mdx @@ -0,0 +1,360 @@ +--- +title: Gmail 연동 +description: "CrewAI를 위한 Gmail 연동을 통한 이메일 및 연락처 관리." +icon: "envelope" +mode: "wide" +--- + +## 개요 + +에이전트가 Gmail을 통해 이메일, 연락처, 임시 저장 메시지를 관리할 수 있도록 합니다. 이메일을 보내고, 메시지를 검색하며, 연락처를 관리하고, 임시 저장 메시지를 작성하며, AI 기반 자동화를 통해 이메일 커뮤니케이션을 효율화하세요. + +## 사전 준비 사항 + +Gmail 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 Gmail 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Gmail 계정 연결 + +## Gmail 연동 설정 + +### 1. Gmail 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **Gmail**을 찾습니다. +3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다. +4. 이메일 및 연락처 관리를 위한 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Gmail에서 이메일을 보냅니다. + + **파라미터:** + - `toRecipients` (array, 필수): 받는 사람 - 하나의 문자열 또는 JSON 배열로 받는 사람을 지정합니다. + ```json + [ + "recipient1@domain.com", + "recipient2@domain.com" + ] + ``` + - `from` (string, 필수): 보내는 사람 - 발신자의 이메일을 지정합니다. + - `subject` (string, 필수): 제목 - 메시지의 제목을 지정합니다. + - `messageContent` (string, 필수): 메시지 내용 - 이메일 메시지의 내용을 일반 텍스트 또는 HTML로 지정합니다. + - `attachments` (string, 선택): 첨부파일 - 단일 파일 객체 또는 파일 객체의 JSON 배열을 허용합니다. + - `additionalHeaders` (object, 선택): 추가 헤더 - 추가 헤더 필드를 지정할 수 있습니다. + ```json + { + "reply-to": "Sender Name " + } + ``` + + + + + **설명:** Gmail에서 ID로 이메일을 조회합니다. + + **파라미터:** + - `userId` (string, 필수): 사용자 ID - 사용자의 이메일 주소를 지정합니다. (예: "user@domain.com"). + - `messageId` (string, 필수): 메시지 ID - 조회할 메시지의 ID를 지정합니다. + + + + + **설명:** 고급 필터를 사용하여 Gmail에서 이메일을 검색합니다. + + **파라미터:** + - `emailFilterFormula` (object, 선택): 불리언 식(OR로 연결된 AND 그룹의 단일 조건)으로 된 필터. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "from", + "operator": "$stringContains", + "value": "example@domain.com" + } + ] + } + ] + } + ``` + 사용 가능한 필드: `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, 선택): 페이지네이션 파라미터. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + + **설명:** Gmail에서 이메일을 삭제합니다. + + **파라미터:** + - `userId` (string, 필수): 사용자 ID - 사용자의 이메일 주소를 지정합니다. (예: "user@domain.com"). + - `messageId` (string, 필수): 메시지 ID - 휴지통으로 보낼 메시지의 ID를 지정합니다. + + + + + **설명:** Gmail에서 연락처를 생성합니다. + + **파라미터:** + - `givenName` (string, 필수): 이름 - 생성할 연락처의 이름을 지정합니다. (예: "John"). + - `familyName` (string, 필수): 성 - 생성할 연락처의 성을 지정합니다. (예: "Doe"). + - `email` (string, 필수): 이메일 - 생성할 연락처의 이메일 주소를 지정합니다. + - `additionalFields` (object, 선택): 추가 필드 - 기타 연락처 정보를 입력할 수 있습니다. + ```json + { + "addresses": [ + { + "streetAddress": "1000 North St.", + "city": "Los Angeles" + } + ] + } + ``` + + + + + **설명:** Gmail에서 리소스 이름으로 연락처를 조회합니다. + + **파라미터:** + - `resourceName` (string, 필수): 리소스 이름 - 조회할 연락처의 리소스 이름을 지정합니다. + + + + + **설명:** Gmail에서 연락처를 검색합니다. + + **파라미터:** + - `searchTerm` (string, 필수): 검색어 - 이름, 닉네임, 이메일 주소, 전화번호 또는 조직 연락처 속성에서 유사하거나 정확히 일치하는 항목을 검색할 검색어를 지정합니다. + + + + + **설명:** Gmail에서 연락처를 삭제합니다. + + **파라미터:** + - `resourceName` (string, 필수): 리소스 이름 - 삭제할 연락처의 리소스 이름을 지정합니다. + + + + + **설명:** Gmail에서 임시 저장 메일을 만듭니다. + + **파라미터:** + - `toRecipients` (array, 선택): 받는 사람 - 하나의 문자열 또는 JSON 배열로 받는 사람을 지정합니다. + ```json + [ + "recipient1@domain.com", + "recipient2@domain.com" + ] + ``` + - `from` (string, 선택): 보내는 사람 - 발신자의 이메일을 지정합니다. + - `subject` (string, 선택): 제목 - 메시지의 제목을 지정합니다. + - `messageContent` (string, 선택): 메시지 내용 - 이메일 메시지의 내용을 일반 텍스트 또는 HTML로 지정합니다. + - `attachments` (string, 선택): 첨부파일 - 단일 파일 객체 또는 파일 객체의 JSON 배열을 허용합니다. + - `additionalHeaders` (object, 선택): 추가 헤더 - 추가 헤더 필드를 지정할 수 있습니다. + ```json + { + "reply-to": "Sender Name " + } + ``` + + + + +## 사용 예시 + +### 기본 Gmail 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +gmail_agent = Agent( + role="Email Manager", + goal="Manage email communications and contacts efficiently", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail'] +) + +# Task to send a follow-up email +send_email_task = Task( + description="Send a follow-up email to john@example.com about the project update meeting", + agent=gmail_agent, + expected_output="Email sent successfully with confirmation" +) + +# Run the task +crew = Crew( + agents=[gmail_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +### 특정 Gmail 도구 필터링 + +```python + +email_coordinator = Agent( + role="Email Coordinator", + goal="Coordinate email communications and manage drafts", + backstory="An AI assistant that focuses on email coordination and draft management.", + apps=['gmail'] +) + +# Task to prepare and send emails +email_coordination = Task( + description="Search for emails from the marketing team, create a summary draft, and send it to stakeholders", + agent=email_coordinator, + expected_output="Summary email sent to stakeholders" +) + +crew = Crew( + agents=[email_coordinator], + tasks=[email_coordination] +) + +crew.kickoff() +``` + +### 연락처 관리 + +```python +from crewai import Agent, Task, Crew + +contact_manager = Agent( + role="Contact Manager", + goal="Manage and organize email contacts efficiently", + backstory="An experienced contact manager who maintains organized contact databases.", + apps=['gmail'] +) + +# Task to manage contacts +contact_task = Task( + description=""" + 1. 'example.com' 도메인에서 연락처를 검색합니다. + 2. 연락처 목록에 없는 최근 이메일 발신자에 대해 새 연락처를 생성합니다. + 3. 최근 상호 작용 데이터를 반영하여 연락처 정보를 업데이트합니다. + """, + agent=contact_manager, + expected_output="새 연락처와 최근 상호 작용으로 연락처 데이터베이스가 업데이트됨" +) + +crew = Crew( + agents=[contact_manager], + tasks=[contact_task] +) + +crew.kickoff() +``` + +### 이메일 검색 및 분석 + +```python +from crewai import Agent, Task, Crew + +email_analyst = Agent( + role="Email Analyst", + goal="Analyze email patterns and provide insights", + backstory="An AI assistant that analyzes email data to provide actionable insights.", + apps=['gmail'] +) + +# Task to analyze email patterns +analysis_task = Task( + description=""" + Search for all unread emails from the last 7 days, + categorize them by sender domain, + and create a summary report of communication patterns + """, + agent=email_analyst, + expected_output="Email analysis report with communication patterns and recommendations" +) + +crew = Crew( + agents=[email_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### 자동화된 이메일 워크플로우 + +```python +from crewai import Agent, Task, Crew + +workflow_manager = Agent( + role="Email Workflow Manager", + goal="Automate email workflows and responses", + backstory="An AI assistant that manages automated email workflows and responses.", + apps=['gmail'] +) + +# Complex task involving multiple Gmail operations +workflow_task = Task( + description=""" + 1. 지난 24시간 동안 제목에 'urgent'가 포함된 이메일 검색 + 2. 각 긴급 이메일에 대한 답장 초안 생성 + 3. 발신자에게 자동 확인 이메일 전송 + 4. 주의가 필요한 긴급 항목의 요약 보고서 작성 + """, + agent=workflow_manager, + expected_output="긴급 이메일이 자동 응답 및 요약 보고서와 함께 처리됨" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +### 도움 받기 + + + Gmail 통합 설정 또는 문제 해결에 대한 지원이 필요하시다면 저희 지원팀에 문의해 + 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/google_calendar.mdx b/docs/v1.15.1/ko/enterprise/integrations/google_calendar.mdx new file mode 100644 index 000000000..80a6ab439 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/google_calendar.mdx @@ -0,0 +1,403 @@ +--- +title: Google 캘린더 연동 +description: "CrewAI를 위한 Google 캘린더 연동을 통한 이벤트 및 일정 관리." +icon: "calendar" +mode: "wide" +--- + +## 개요 + +에이전트가 Google Calendar를 통해 캘린더 이벤트, 일정, 가용 시간을 관리할 수 있도록 지원합니다. 이벤트를 생성 및 업데이트하고 참석자를 관리하며, 가용성을 확인하고 AI 기반 자동화로 일정 관리 워크플로우를 효율적으로 운영하세요. + +## 필수 조건 + +Google Calendar 통합을 사용하기 전에 다음을 준비해야 합니다: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Google Calendar에 접근 가능한 Google 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정을 연결 완료 + +## Google Calendar 연동 설정 + +### 1. Google 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **Google Calendar**를 찾습니다. +3. **Connect**를 클릭하고 OAuth 과정을 완료합니다. +4. 캘린더 및 연락처 접근 권한을 허용합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Google 캘린더에 이벤트를 생성합니다. + + **파라미터:** + - `eventName` (string, 필수): 이벤트 이름. + - `startTime` (string, 필수): 시작 시간 - Unix 타임스탬프 또는 ISO8601 날짜 형식 허용. + - `endTime` (string, 선택): 종료 시간 - 비워두면 시작 시간 기준 1시간 후로 기본 설정됩니다. + - `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다. + - `attendees` (string, 선택): 참석자 - 이메일 주소 배열 또는 쉼표로 구분된 이메일 주소 허용. + - `eventLocation` (string, 선택): 이벤트 위치. + - `eventDescription` (string, 선택): 이벤트 설명. + - `eventId` (string, 선택): 이벤트 ID - 이 이벤트와 연결할 애플리케이션의 ID입니다. 이후 이 ID를 사용하여 이벤트를 동기화할 수 있습니다. + - `includeMeetLink` (boolean, 선택): Google Meet 링크 포함 여부? - 이 이벤트에 대해 Google Meet 컨퍼런스 링크를 자동으로 생성합니다. + + + + + **설명:** Google 캘린더에서 기존 이벤트를 업데이트합니다. + + **파라미터:** + - `eventId` (string, 필수): 이벤트 ID - 업데이트할 이벤트의 ID입니다. + - `eventName` (string, 선택): 이벤트 이름. + - `startTime` (string, 선택): 시작 시간 - Unix 타임스탬프 또는 ISO8601 날짜 형식 허용. + - `endTime` (string, 선택): 종료 시간 - 비워두면 시작 시간 기준 1시간 후로 기본 설정됩니다. + - `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다. + - `attendees` (string, 선택): 참석자 - 이메일 주소 배열 또는 쉼표로 구분된 이메일 주소 허용. + - `eventLocation` (string, 선택): 이벤트 위치. + - `eventDescription` (string, 선택): 이벤트 설명. + + + + + **설명:** Google 캘린더에서 이벤트 목록을 가져옵니다. + + **파라미터:** + - `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다. + - `after` (string, 선택): 이후 - 제공된 날짜 이후에 시작하는 이벤트를 필터링합니다 (밀리초 단위의 Unix 또는 ISO 타임스탬프). (예시: "2025-04-12T10:00:00Z 또는 1712908800000"). + - `before` (string, 선택): 이전 - 제공된 날짜 이전에 종료되는 이벤트를 필터링합니다 (밀리초 단위의 Unix 또는 ISO 타임스탬프). (예시: "2025-04-12T10:00:00Z 또는 1712908800000"). + + + + + **설명:** Google 캘린더에서 ID로 특정 이벤트를 가져옵니다. + + **파라미터:** + - `eventId` (string, 필수): 이벤트 ID. + - `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다. + + + + + **설명:** Google 캘린더에서 이벤트를 삭제합니다. + + **파라미터:** + - `eventId` (string, 필수): 이벤트 ID - 삭제할 캘린더 이벤트의 ID입니다. + - `calendar` (string, 선택): 캘린더 - Connect Portal Workflow Settings를 사용하여 사용자가 이벤트를 추가할 캘린더를 선택할 수 있도록 합니다. 비워두면 사용자의 기본 캘린더로 기본 설정됩니다. + + + + + **설명:** Google 캘린더에서 연락처를 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 페이지네이션 파라미터. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + + **설명:** Google 캘린더에서 연락처를 검색합니다. + + **파라미터:** + - `query` (string, 선택): 연락처를 검색할 검색 쿼리. + + + + + **설명:** 디렉토리 구성원 목록을 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 페이지네이션 파라미터. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + + **설명:** 디렉토리 구성원을 검색합니다. + + **파라미터:** + - `query` (string, 필수): 연락처를 검색할 검색 쿼리. + - `paginationParameters` (object, 선택): 페이지네이션 파라미터. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + + **설명:** 기타 연락처 목록을 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 페이지네이션 파라미터. + ```json + { + "pageCursor": "page_cursor_string" + } + ``` + + + + + **설명:** 기타 연락처를 검색합니다. + + **파라미터:** + - `query` (string, 선택): 연락처를 검색할 검색 쿼리. + + + + + **설명:** 캘린더의 가용성 정보를 가져옵니다. + + **파라미터:** + - `timeMin` (string, 필수): 기간의 시작. ISO 형식. + - `timeMax` (string, 필수): 기간의 끝. ISO 형식. + - `timeZone` (string, 선택): 응답에 사용되는 시간대. 선택 사항입니다. 기본값은 UTC입니다. + - `items` (array, 선택): 조회할 캘린더 및/또는 그룹 목록. 비워두면 사용자 기본 캘린더가 기본값입니다. + ```json + [ + { + "id": "calendar_id_1" + }, + { + "id": "calendar_id_2" + } + ] + ``` + + + + +## 사용 예시 + +### 기본 캘린더 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Calendar capabilities +calendar_agent = Agent( + role="Schedule Manager", + goal="Manage calendar events and scheduling efficiently", + backstory="An AI assistant specialized in calendar management and scheduling coordination.", + apps=['google_calendar'] +) + +# Task to create a meeting +create_meeting_task = Task( + description="Create a team standup meeting for tomorrow at 9 AM with the development team", + agent=calendar_agent, + expected_output="Meeting created successfully with Google Meet link" +) + +# Run the task +crew = Crew( + agents=[calendar_agent], + tasks=[create_meeting_task] +) + +crew.kickoff() +``` + +### 특정 캘린더 도구 필터링 + +```python + +meeting_coordinator = Agent( + role="Meeting Coordinator", + goal="Coordinate meetings and check availability", + backstory="An AI assistant that focuses on meeting scheduling and availability management.", + apps=['google_calendar'] +) + +# Task to schedule a meeting with availability check +schedule_meeting = Task( + description="Check availability for next week and schedule a project review meeting with stakeholders", + agent=meeting_coordinator, + expected_output="Meeting scheduled after checking availability of all participants" +) + +crew = Crew( + agents=[meeting_coordinator], + tasks=[schedule_meeting] +) + +crew.kickoff() +``` + +### 이벤트 관리 및 업데이트 + +```python +from crewai import Agent, Task, Crew + +event_manager = Agent( + role="Event Manager", + goal="Manage and update calendar events efficiently", + backstory="An experienced event manager who handles event logistics and updates.", + apps=['google_calendar'] +) + +# Task to manage event updates +event_management = Task( + description=""" + 1. List all events for this week + 2. Update any events that need location changes to include video conference links + 3. Send calendar invitations to new team members for recurring meetings + """, + agent=event_manager, + expected_output="Weekly events updated with proper locations and new attendees added" +) + +crew = Crew( + agents=[event_manager], + tasks=[event_management] +) + +crew.kickoff() +``` + +### 연락처 및 가용성 관리 + +```python +from crewai import Agent, Task, Crew + +availability_coordinator = Agent( + role="Availability Coordinator", + goal="Coordinate availability and manage contacts for scheduling", + backstory="An AI assistant that specializes in availability management and contact coordination.", + apps=['google_calendar'] +) + +# Task to coordinate availability +availability_task = Task( + description=""" + 1. 엔지니어링 부서의 연락처를 검색합니다. + 2. 다음 주 금요일 오후에 모든 엔지니어의 가용성을 확인합니다. + 3. 가장 먼저 가능한 2시간 슬롯에 팀 미팅을 만듭니다. + 4. Google Meet 링크를 포함하고 초대장을 발송합니다. + """, + agent=availability_coordinator, + expected_output="가용성에 따라 팀 미팅이 일정 예약되고 모든 엔지니어가 초대됨" +) + +crew = Crew( + agents=[availability_coordinator], + tasks=[availability_task] +) + +crew.kickoff() +``` + +### 자동화된 일정 관리 워크플로우 + +```python +from crewai import Agent, Task, Crew + +scheduling_automator = Agent( + role="Scheduling Automator", + goal="Automate scheduling workflows and calendar management", + backstory="An AI assistant that automates complex scheduling scenarios and calendar workflows.", + apps=['google_calendar'] +) + +# Complex scheduling automation task +automation_task = Task( + description=""" + 1. 앞으로 2주간 예정된 모든 이벤트를 나열합니다. + 2. 일정 충돌 또는 연이어 배정된 미팅을 식별합니다. + 3. 가용 시간을 확인하여 최적의 미팅 시간을 제안합니다. + 4. 필요한 경우 미팅 사이에 버퍼 시간을 생성합니다. + 5. 아젠다 항목 및 미팅 링크가 포함된 이벤트 설명을 업데이트합니다. + """, + agent=scheduling_automator, + expected_output="일정 충돌이 해결되고 버퍼 타임 및 미팅 세부 정보가 업데이트된 최적화된 캘린더" +) + +crew = Crew( + agents=[scheduling_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Google 계정에 캘린더 접근에 필요한 권한이 있는지 확인하세요 +- OAuth 연결에 Google Calendar API에 필요한 모든 범위가 포함되어 있는지 확인하세요 +- 캘린더 공유 설정이 필요한 접근 수준을 허용하는지 확인하세요 + +**이벤트 생성 문제** + +- 시간 형식이 올바른지(ISO8601 또는 Unix 타임스탬프) 확인하세요 +- 참석자 이메일 주소가 올바르게 형식화되어 있는지 확인하세요 +- 대상 캘린더가 존재하며 접근 가능한지 확인하세요 +- 올바른 시간대가 지정되어 있는지 확인하세요 + +**가용성 및 시간 충돌** + +- 가용성 확인 시 시간 범위에 올바른 ISO 형식을 사용하세요 +- 모든 작업에서 시간대가 일관성 있는지 확인하세요 +- 여러 캘린더를 확인할 때 캘린더 ID가 올바른지 확인하세요 + +**연락처 및 사용자 검색** + +- 검색 쿼리가 올바르게 형식화되어 있는지 확인하세요 +- 디렉터리 접근 권한이 부여되었는지 확인하세요 +- 연락처 정보가 최신이며 접근 가능한지 확인하세요 + +**이벤트 업데이트 및 삭제** + +- 이벤트 ID가 올바르며 이벤트가 존재하는지 확인하세요 +- 이벤트를 편집할 수 있는 권한이 있는지 확인하세요 +- 캘린더 소유권이 수정 작업을 허용하는지 확인하세요 + +### 도움 받기 + + + Google Calendar 연동 설정 또는 문제 해결에 대한 지원이 필요하면 저희 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/google_contacts.mdx b/docs/v1.15.1/ko/enterprise/integrations/google_contacts.mdx new file mode 100644 index 000000000..ded332913 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/google_contacts.mdx @@ -0,0 +1,278 @@ +--- +title: Google Contacts 통합 +description: "CrewAI를 위한 Google Contacts 통합으로 연락처 및 디렉토리 관리." +icon: "address-book" +mode: "wide" +--- + +## 개요 + +에이전트가 Google Contacts를 통해 연락처와 디렉토리 정보를 관리할 수 있도록 합니다. 개인 연락처에 액세스하고, 디렉토리 사람들을 검색하고, 연락처 정보를 생성 및 업데이트하고, AI 기반 자동화로 연락처 그룹을 관리합니다. + +## 전제 조건 + +Google Contacts 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Google Contacts 액세스 권한이 있는 Google 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결 + +## Google Contacts 통합 설정 + +### 1. Google 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Google Contacts** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 연락처 및 디렉토리 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Google Contacts에서 사용자의 연락처를 검색합니다. + + **매개변수:** + - `pageSize` (integer, 선택사항): 반환할 연락처 수 (최대 1000). 최소: 1, 최대: 1000 + - `pageToken` (string, 선택사항): 검색할 페이지의 토큰. + - `personFields` (string, 선택사항): 포함할 필드 (예: 'names,emailAddresses,phoneNumbers'). 기본값: names,emailAddresses,phoneNumbers + - `requestSyncToken` (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false + - `sortOrder` (string, 선택사항): 연결을 정렬할 순서. 옵션: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING + + + + + **설명:** 쿼리 문자열을 사용하여 연락처를 검색합니다. + + **매개변수:** + - `query` (string, 필수): 검색 쿼리 문자열 + - `readMask` (string, 필수): 읽을 필드 (예: 'names,emailAddresses,phoneNumbers') + - `pageSize` (integer, 선택사항): 반환할 결과 수. 최소: 1, 최대: 30 + - `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰. + - `sources` (array, 선택사항): 검색할 소스. 옵션: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. 기본값: READ_SOURCE_TYPE_CONTACT + + + + + **설명:** 인증된 사용자의 디렉토리에 있는 사람들을 나열합니다. + + **매개변수:** + - `sources` (array, 필수): 검색할 디렉토리 소스. 옵션: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. 기본값: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE + - `pageSize` (integer, 선택사항): 반환할 사람 수. 최소: 1, 최대: 1000 + - `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰. + - `readMask` (string, 선택사항): 읽을 필드 (예: 'names,emailAddresses') + - `requestSyncToken` (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false + - `mergeSources` (array, 선택사항): 디렉토리 사람 응답에 병합할 추가 데이터. 옵션: CONTACT + + + + + **설명:** 디렉토리에서 사람을 검색합니다. + + **매개변수:** + - `query` (string, 필수): 검색 쿼리 + - `sources` (string, 필수): 디렉토리 소스 ('DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE' 사용) + - `pageSize` (integer, 선택사항): 반환할 결과 수 + - `readMask` (string, 선택사항): 읽을 필드 + + + + + **설명:** 기타 연락처를 나열합니다 (사용자의 개인 연락처에 없는). + + **매개변수:** + - `pageSize` (integer, 선택사항): 반환할 연락처 수. 최소: 1, 최대: 1000 + - `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰. + - `readMask` (string, 선택사항): 읽을 필드 + - `requestSyncToken` (boolean, 선택사항): 응답에 동기화 토큰을 포함할지 여부. 기본값: false + + + + + **설명:** 기타 연락처를 검색합니다. + + **매개변수:** + - `query` (string, 필수): 검색 쿼리 + - `readMask` (string, 필수): 읽을 필드 (예: 'names,emailAddresses') + - `pageSize` (integer, 선택사항): 결과 수 + + + + + **설명:** 리소스 이름으로 한 사람의 연락처 정보를 가져옵니다. + + **매개변수:** + - `resourceName` (string, 필수): 가져올 사람의 리소스 이름 (예: 'people/c123456789') + - `personFields` (string, 선택사항): 포함할 필드 (예: 'names,emailAddresses,phoneNumbers'). 기본값: names,emailAddresses,phoneNumbers + + + + + **설명:** 사용자의 주소록에 새 연락처를 만듭니다. + + **매개변수:** + - `names` (array, 선택사항): 사람의 이름들. 각 항목은 `givenName` (string), `familyName` (string), `displayName` (string)이 있는 객체. + - `emailAddresses` (array, 선택사항): 이메일 주소들. 각 항목은 `value` (string, 이메일 주소)와 `type` (string, 'home', 'work', 'other', 기본값 'other')이 있는 객체. + - `phoneNumbers` (array, 선택사항): 전화번호들. 각 항목은 `value` (string, 전화번호)와 `type` (string, 'home', 'work', 'mobile', 'other', 기본값 'other')이 있는 객체. + - `addresses` (array, 선택사항): 우편 주소들. 각 항목은 `formattedValue` (string, 형식화된 주소)와 `type` (string, 'home', 'work', 'other', 기본값 'other')이 있는 객체. + - `organizations` (array, 선택사항): 조직/회사들. 각 항목은 `name` (string, 조직 이름), `title` (string, 직책), `type` (string, 'work', 'other', 기본값 'work')이 있는 객체. + + + + + **설명:** 기존 연락처의 정보를 업데이트합니다. + + **매개변수:** + - `resourceName` (string, 필수): 업데이트할 사람의 리소스 이름 (예: 'people/c123456789'). + - `updatePersonFields` (string, 필수): 업데이트할 필드 (예: 'names,emailAddresses,phoneNumbers'). + - `names` (array, 선택사항): 사람의 이름들. 각 항목은 `givenName` (string), `familyName` (string), `displayName` (string)이 있는 객체. + - `emailAddresses` (array, 선택사항): 이메일 주소들. 각 항목은 `value` (string, 이메일 주소)와 `type` (string, 'home', 'work', 'other')이 있는 객체. + - `phoneNumbers` (array, 선택사항): 전화번호들. 각 항목은 `value` (string, 전화번호)와 `type` (string, 'home', 'work', 'mobile', 'other')이 있는 객체. + + + + + **설명:** 사용자의 주소록에서 연락처를 삭제합니다. + + **매개변수:** + - `resourceName` (string, 필수): 삭제할 사람의 리소스 이름 (예: 'people/c123456789'). + + + + + **설명:** 한 번의 요청으로 여러 사람에 대한 정보를 가져옵니다. + + **매개변수:** + - `resourceNames` (array, 필수): 가져올 사람들의 리소스 이름 (최대 200개 항목). + - `personFields` (string, 선택사항): 포함할 필드 (예: 'names,emailAddresses,phoneNumbers'). 기본값: names,emailAddresses,phoneNumbers + + + + + **설명:** 사용자의 연락처 그룹(라벨)을 나열합니다. + + **매개변수:** + - `pageSize` (integer, 선택사항): 반환할 연락처 그룹 수. 최소: 1, 최대: 1000 + - `pageToken` (string, 선택사항): 반환할 결과 페이지를 지정하는 토큰. + - `groupFields` (string, 선택사항): 포함할 필드 (예: 'name,memberCount,clientData'). 기본값: name,memberCount + + + + + **설명:** 리소스 이름으로 특정 연락처 그룹을 가져옵니다. + + **매개변수:** + - `resourceName` (string, 필수): 연락처 그룹의 리소스 이름 (예: 'contactGroups/myContactGroup'). + - `maxMembers` (integer, 선택사항): 포함할 최대 멤버 수. 최소: 0, 최대: 20000 + - `groupFields` (string, 선택사항): 포함할 필드 (예: 'name,memberCount,clientData'). 기본값: name,memberCount + + + + + **설명:** 새 연락처 그룹(라벨)을 만듭니다. + + **매개변수:** + - `name` (string, 필수): 연락처 그룹의 이름. + - `clientData` (array, 선택사항): 클라이언트별 데이터. 각 항목은 `key` (string)와 `value` (string)가 있는 객체. + + + + + **설명:** 연락처 그룹의 정보를 업데이트합니다. + + **매개변수:** + - `resourceName` (string, 필수): 연락처 그룹의 리소스 이름 (예: 'contactGroups/myContactGroup'). + - `name` (string, 필수): 연락처 그룹의 이름. + - `clientData` (array, 선택사항): 클라이언트별 데이터. 각 항목은 `key` (string)와 `value` (string)가 있는 객체. + + + + + **설명:** 연락처 그룹을 삭제합니다. + + **매개변수:** + - `resourceName` (string, 필수): 삭제할 연락처 그룹의 리소스 이름 (예: 'contactGroups/myContactGroup'). + - `deleteContacts` (boolean, 선택사항): 그룹 내 연락처도 삭제할지 여부. 기본값: false + + + + +## 사용 예제 + +### 기본 Google Contacts 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Google Contacts 기능을 가진 에이전트 생성 +contacts_agent = Agent( + role="연락처 관리자", + goal="Google Contacts를 효율적으로 관리", + backstory="연락처 관리 및 조직 전문 AI 어시스턴트.", + apps=['google_contacts'] # 모든 Google Contacts 작업을 사용할 수 있습니다 +) + +# 새 연락처 생성 작업 +create_contact_task = Task( + description="'김철수'라는 이름으로 이메일 'kim.chulsoo@example.com'과 전화번호 '010-1234-5678'로 새 연락처를 만드세요", + agent=contacts_agent, + expected_output="새 연락처가 성공적으로 생성됨" +) + +# 작업 실행 +crew = Crew( + agents=[contacts_agent], + tasks=[create_contact_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Google 계정이 연락처 및 디렉토리 액세스에 필요한 권한을 가지고 있는지 확인하세요. +- OAuth 연결이 Google People API에 필요한 모든 범위를 포함하는지 확인하세요. + +**연락처 생성/업데이트 문제** + +- 연락처 생성 시 `email`과 같은 필수 필드가 제공되는지 확인하세요. +- 연락처를 업데이트하거나 삭제할 때 `resourceName`이 올바른지 확인하세요. + +### 도움 받기 + + + Google Contacts 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/google_docs.mdx b/docs/v1.15.1/ko/enterprise/integrations/google_docs.mdx new file mode 100644 index 000000000..53f421229 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/google_docs.mdx @@ -0,0 +1,481 @@ +--- +title: Google Docs 통합 +description: "CrewAI를 위한 Google Docs 통합으로 문서 생성 및 편집." +icon: "file-lines" +mode: "wide" +--- + +## 개요 + +에이전트가 텍스트 조작 및 서식을 사용하여 Google Docs 문서를 생성, 편집 및 관리할 수 있도록 합니다. AI 기반 자동화로 문서 생성을 자동화하고, 텍스트를 삽입 및 교체하고, 콘텐츠 범위를 관리하며, 문서 워크플로를 간소화합니다. + +## 전제 조건 + +Google Docs 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Google Docs 액세스 권한이 있는 Google 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결 + +## Google Docs 통합 설정 + +### 1. Google 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Google Docs** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 문서 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** 새 Google 문서를 만듭니다. + + **매개변수:** + - `title` (string, 선택사항): 새 문서의 제목. + + + + + **설명:** Google 문서의 내용과 메타데이터를 가져옵니다. + + **매개변수:** + - `documentId` (string, 필수): 검색할 문서의 ID. + - `includeTabsContent` (boolean, 선택사항): 탭 내용을 포함할지 여부. 기본값: false + - `suggestionsViewMode` (string, 선택사항): 문서에 적용할 제안 보기 모드. 옵션: DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_SUGGESTIONS_ACCEPTED, PREVIEW_WITHOUT_SUGGESTIONS. 기본값: DEFAULT_FOR_CURRENT_ACCESS + + + + + **설명:** Google 문서에 하나 이상의 업데이트를 적용합니다. + + **매개변수:** + - `documentId` (string, 필수): 업데이트할 문서의 ID. + - `requests` (array, 필수): 문서에 적용할 업데이트 목록. 각 항목은 요청을 나타내는 객체. + - `writeControl` (object, 선택사항): 쓰기 요청이 실행되는 방식을 제어합니다. `requiredRevisionId` (string)와 `targetRevisionId` (string)를 포함. + + + + + **설명:** Google 문서의 특정 위치에 텍스트를 삽입합니다. + + **매개변수:** + - `documentId` (string, 필수): 업데이트할 문서의 ID. + - `text` (string, 필수): 삽입할 텍스트. + - `index` (integer, 선택사항): 텍스트를 삽입할 0 기반 인덱스. 기본값: 1 + + + + + **설명:** Google 문서에서 텍스트의 모든 인스턴스를 교체합니다. + + **매개변수:** + - `documentId` (string, 필수): 업데이트할 문서의 ID. + - `containsText` (string, 필수): 찾아서 교체할 텍스트. + - `replaceText` (string, 필수): 교체할 텍스트. + - `matchCase` (boolean, 선택사항): 검색이 대소문자를 구분할지 여부. 기본값: false + + + + + **설명:** Google 문서의 특정 범위에서 내용을 삭제합니다. + + **매개변수:** + - `documentId` (string, 필수): 업데이트할 문서의 ID. + - `startIndex` (integer, 필수): 삭제할 범위의 시작 인덱스. + - `endIndex` (integer, 필수): 삭제할 범위의 끝 인덱스. + + + + + **설명:** Google 문서의 특정 위치에 페이지 나누기를 삽입합니다. + + **매개변수:** + - `documentId` (string, 필수): 업데이트할 문서의 ID. + - `index` (integer, 선택사항): 페이지 나누기를 삽입할 0 기반 인덱스. 기본값: 1 + + + + + **설명:** Google 문서에 명명된 범위를 만듭니다. + + **매개변수:** + - `documentId` (string, 필수): 업데이트할 문서의 ID. + - `name` (string, 필수): 명명된 범위의 이름. + - `startIndex` (integer, 필수): 범위의 시작 인덱스. + - `endIndex` (integer, 필수): 범위의 끝 인덱스. + + + + + **설명:** 내용이 포함된 새 Google 문서를 한 번에 만듭니다. + + **매개변수:** + - `title` (string, 필수): 새 문서의 제목. 문서 상단과 Google Drive에 표시됩니다. + - `content` (string, 선택사항): 문서에 삽입할 텍스트 내용. 새 단락에는 `\n`을 사용하세요. + + + + + **설명:** Google 문서의 끝에 텍스트를 추가합니다. 인덱스를 지정할 필요 없이 자동으로 문서 끝에 삽입됩니다. + + **매개변수:** + - `documentId` (string, 필수): create_document 응답 또는 URL에서 가져온 문서 ID. + - `text` (string, 필수): 문서 끝에 추가할 텍스트. 새 단락에는 `\n`을 사용하세요. + + + + + **설명:** Google 문서에서 텍스트를 굵게 만들거나 굵게 서식을 제거합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적). + - `bold` (boolean, 필수): 굵게 만들려면 `true`, 굵게를 제거하려면 `false`로 설정. + + + + + **설명:** Google 문서에서 텍스트를 기울임꼴로 만들거나 기울임꼴 서식을 제거합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적). + - `italic` (boolean, 필수): 기울임꼴로 만들려면 `true`, 기울임꼴을 제거하려면 `false`로 설정. + + + + + **설명:** Google 문서에서 텍스트에 밑줄 서식을 추가하거나 제거합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적). + - `underline` (boolean, 필수): 밑줄을 추가하려면 `true`, 밑줄을 제거하려면 `false`로 설정. + + + + + **설명:** Google 문서에서 텍스트에 취소선 서식을 추가하거나 제거합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적). + - `strikethrough` (boolean, 필수): 취소선을 추가하려면 `true`, 제거하려면 `false`로 설정. + + + + + **설명:** Google 문서에서 텍스트의 글꼴 크기를 변경합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적). + - `fontSize` (number, 필수): 포인트 단위의 글꼴 크기. 일반적인 크기: 10, 11, 12, 14, 16, 18, 24, 36. + + + + + **설명:** Google 문서에서 RGB 값(0-1 스케일)을 사용하여 텍스트 색상을 변경합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 서식을 지정할 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 서식을 지정할 텍스트의 끝 위치 (배타적). + - `red` (number, 필수): 빨강 구성 요소 (0-1). 예: `1`은 완전한 빨강. + - `green` (number, 필수): 초록 구성 요소 (0-1). 예: `0.5`는 절반 초록. + - `blue` (number, 필수): 파랑 구성 요소 (0-1). 예: `0`은 파랑 없음. + + + + + **설명:** Google 문서에서 기존 텍스트를 클릭 가능한 하이퍼링크로 변환합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 링크로 만들 텍스트의 시작 위치. + - `endIndex` (integer, 필수): 링크로 만들 텍스트의 끝 위치 (배타적). + - `url` (string, 필수): 링크가 가리킬 URL. 예: `"https://example.com"`. + + + + + **설명:** Google 문서에서 텍스트 범위에 제목 또는 단락 스타일을 적용합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 스타일을 적용할 단락의 시작 위치. + - `endIndex` (integer, 필수): 스타일을 적용할 단락의 끝 위치. + - `style` (string, 필수): 적용할 스타일. 옵션: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`. + + + + + **설명:** Google 문서에서 단락의 텍스트 정렬을 설정합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 정렬할 단락의 시작 위치. + - `endIndex` (integer, 필수): 정렬할 단락의 끝 위치. + - `alignment` (string, 필수): 텍스트 정렬. 옵션: `START` (왼쪽), `CENTER`, `END` (오른쪽), `JUSTIFIED`. + + + + + **설명:** Google 문서에서 단락의 줄 간격을 설정합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 단락의 시작 위치. + - `endIndex` (integer, 필수): 단락의 끝 위치. + - `lineSpacing` (number, 필수): 백분율로 나타낸 줄 간격. `100` = 단일, `115` = 1.15배, `150` = 1.5배, `200` = 이중. + + + + + **설명:** Google 문서에서 단락을 글머리 기호 또는 번호 매기기 목록으로 변환합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 목록으로 변환할 단락의 시작 위치. + - `endIndex` (integer, 필수): 목록으로 변환할 단락의 끝 위치. + - `bulletPreset` (string, 필수): 글머리 기호/번호 매기기 스타일. 옵션: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`. + + + + + **설명:** Google 문서에서 단락의 글머리 기호 또는 번호 매기기를 제거합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `startIndex` (integer, 필수): 목록 단락의 시작 위치. + - `endIndex` (integer, 필수): 목록 단락의 끝 위치. + + + + + **설명:** Google 문서에 내용이 포함된 표를 한 번에 삽입합니다. 내용은 2D 배열로 제공하세요. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `rows` (integer, 필수): 표의 행 수. + - `columns` (integer, 필수): 표의 열 수. + - `index` (integer, 선택사항): 표를 삽입할 위치. 제공하지 않으면 문서 끝에 삽입됩니다. + - `content` (array, 필수): 2D 배열로 된 표 내용. 각 내부 배열은 행입니다. 예: `[["Year", "Revenue"], ["2023", "$43B"], ["2024", "$45B"]]`. + + + + + **설명:** 기존 표의 참조 셀 위 또는 아래에 새 행을 삽입합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `tableStartIndex` (integer, 필수): 표의 시작 인덱스. get_document에서 가져오세요. + - `rowIndex` (integer, 필수): 참조 셀의 행 인덱스 (0 기반). + - `columnIndex` (integer, 선택사항): 참조 셀의 열 인덱스 (0 기반). 기본값: `0`. + - `insertBelow` (boolean, 선택사항): `true`이면 참조 행 아래에, `false`이면 위에 삽입. 기본값: `true`. + + + + + **설명:** 기존 표의 참조 셀 왼쪽 또는 오른쪽에 새 열을 삽입합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `tableStartIndex` (integer, 필수): 표의 시작 인덱스. + - `rowIndex` (integer, 선택사항): 참조 셀의 행 인덱스 (0 기반). 기본값: `0`. + - `columnIndex` (integer, 필수): 참조 셀의 열 인덱스 (0 기반). + - `insertRight` (boolean, 선택사항): `true`이면 오른쪽에, `false`이면 왼쪽에 삽입. 기본값: `true`. + + + + + **설명:** Google 문서의 기존 표에서 행을 삭제합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `tableStartIndex` (integer, 필수): 표의 시작 인덱스. + - `rowIndex` (integer, 필수): 삭제할 행 인덱스 (0 기반). + - `columnIndex` (integer, 선택사항): 행의 아무 셀의 열 인덱스 (0 기반). 기본값: `0`. + + + + + **설명:** Google 문서의 기존 표에서 열을 삭제합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `tableStartIndex` (integer, 필수): 표의 시작 인덱스. + - `rowIndex` (integer, 선택사항): 열의 아무 셀의 행 인덱스 (0 기반). 기본값: `0`. + - `columnIndex` (integer, 필수): 삭제할 열 인덱스 (0 기반). + + + + + **설명:** 표 셀 범위를 단일 셀로 병합합니다. 모든 셀의 내용이 보존됩니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `tableStartIndex` (integer, 필수): 표의 시작 인덱스. + - `rowIndex` (integer, 필수): 병합의 시작 행 인덱스 (0 기반). + - `columnIndex` (integer, 필수): 병합의 시작 열 인덱스 (0 기반). + - `rowSpan` (integer, 필수): 병합할 행 수. + - `columnSpan` (integer, 필수): 병합할 열 수. + + + + + **설명:** 이전에 병합된 표 셀을 개별 셀로 분리합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `tableStartIndex` (integer, 필수): 표의 시작 인덱스. + - `rowIndex` (integer, 필수): 병합된 셀의 행 인덱스 (0 기반). + - `columnIndex` (integer, 필수): 병합된 셀의 열 인덱스 (0 기반). + - `rowSpan` (integer, 필수): 병합된 셀이 차지하는 행 수. + - `columnSpan` (integer, 필수): 병합된 셀이 차지하는 열 수. + + + + + **설명:** 공개 URL에서 Google 문서에 이미지를 삽입합니다. 이미지는 공개적으로 접근 가능해야 하고, 50MB 미만이며, PNG/JPEG/GIF 형식이어야 합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `uri` (string, 필수): 이미지의 공개 URL. 인증 없이 접근 가능해야 합니다. + - `index` (integer, 선택사항): 이미지를 삽입할 위치. 제공하지 않으면 문서 끝에 삽입됩니다. 기본값: `1`. + + + + + **설명:** 서로 다른 서식을 가진 문서 섹션을 만들기 위해 섹션 나누기를 삽입합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `index` (integer, 필수): 섹션 나누기를 삽입할 위치. + - `sectionType` (string, 필수): 섹션 나누기의 유형. 옵션: `CONTINUOUS` (같은 페이지에 유지), `NEXT_PAGE` (새 페이지 시작). + + + + + **설명:** 문서의 머리글을 만듭니다. insert_text를 사용하여 머리글 내용을 추가할 수 있는 headerId를 반환합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `type` (string, 선택사항): 머리글 유형. 옵션: `DEFAULT`. 기본값: `DEFAULT`. + + + + + **설명:** 문서의 바닥글을 만듭니다. insert_text를 사용하여 바닥글 내용을 추가할 수 있는 footerId를 반환합니다. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `type` (string, 선택사항): 바닥글 유형. 옵션: `DEFAULT`. 기본값: `DEFAULT`. + + + + + **설명:** 문서에서 머리글을 삭제합니다. headerId를 찾으려면 get_document를 사용하세요. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `headerId` (string, 필수): 삭제할 머리글 ID. get_document 응답에서 가져오세요. + + + + + **설명:** 문서에서 바닥글을 삭제합니다. footerId를 찾으려면 get_document를 사용하세요. + + **매개변수:** + - `documentId` (string, 필수): 문서 ID. + - `footerId` (string, 필수): 삭제할 바닥글 ID. get_document 응답에서 가져오세요. + + + + +## 사용 예제 + +### 기본 Google Docs 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Google Docs 기능을 가진 에이전트 생성 +docs_agent = Agent( + role="문서 작성자", + goal="Google Docs 문서를 효율적으로 생성하고 관리", + backstory="Google Docs 문서 생성 및 편집 전문 AI 어시스턴트.", + apps=['google_docs'] # 모든 Google Docs 작업을 사용할 수 있습니다 +) + +# 새 문서 생성 작업 +create_doc_task = Task( + description="'프로젝트 상태 보고서'라는 제목으로 새 Google 문서를 만드세요", + agent=docs_agent, + expected_output="새 Google 문서 '프로젝트 상태 보고서'가 성공적으로 생성됨" +) + +# 작업 실행 +crew = Crew( + agents=[docs_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Google 계정이 Google Docs 액세스에 필요한 권한을 가지고 있는지 확인하세요. +- OAuth 연결이 필요한 모든 범위(`https://www.googleapis.com/auth/documents`)를 포함하는지 확인하세요. + +**문서 ID 문제** + +- 문서 ID가 올바른지 다시 확인하세요. +- 문서가 존재하고 계정에서 액세스할 수 있는지 확인하세요. + +### 도움 받기 + + + Google Docs 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/google_drive.mdx b/docs/v1.15.1/ko/enterprise/integrations/google_drive.mdx new file mode 100644 index 000000000..39ba7f0c1 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/google_drive.mdx @@ -0,0 +1,68 @@ +--- +title: Google Drive 통합 +description: "CrewAI를 위한 Google Drive 통합으로 파일 및 폴더 관리." +icon: "google" +mode: "wide" +--- + +## 개요 + +에이전트가 Google Drive의 파일과 폴더에 액세스하고 관리할 수 있도록 합니다. AI 기반 자동화로 파일을 업로드, 다운로드, 콘텐츠 구성, 공유 링크 생성 및 클라우드 스토리지 워크플로를 간소화합니다. + +## 전제 조건 + +Google Drive 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Google Drive 액세스 권한이 있는 Google 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결 + +## Google Drive 통합 설정 + +### 1. Google 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다. +2. 인증 통합 섹션에서 **Google Drive**를 찾습니다. +3. **연결**을 클릭하고 OAuth 과정을 완료합니다. +4. 파일 및 폴더 관리에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + +자세한 매개변수 및 사용법은 [영어 문서](../../../en/enterprise/integrations/google_drive)를 참조하세요. + +## 문제 해결 + +### 도움 받기 + + + Google Drive 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/google_sheets.mdx b/docs/v1.15.1/ko/enterprise/integrations/google_sheets.mdx new file mode 100644 index 000000000..de0b09168 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/google_sheets.mdx @@ -0,0 +1,325 @@ +--- +title: Google Sheets 연동 +description: "CrewAI를 위한 Google Sheets 연동을 통해 스프레드시트 데이터 동기화." +icon: "google" +mode: "wide" +--- + +## 개요 + +에이전트가 Google Sheets를 통해 스프레드시트 데이터를 관리할 수 있도록 합니다. 행을 읽고, 새 항목을 생성하며, 기존 데이터를 업데이트하고, AI 기반 자동화를 통해 데이터 관리 워크플로우를 간소화하세요. 데이터 추적, 보고, 협업 데이터 관리에 최적화되어 있습니다. + +## 사전 준비 사항 + +Google Sheets 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 되어 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Google Sheets에 액세스할 수 있는 Google 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결 +- 데이터 작업을 위한 올바른 열 헤더가 있는 스프레드시트 + +## Google Sheets 통합 설정 + +### 1. Google 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **Google Sheets**를 찾습니다. +3. **Connect**를 클릭하고 OAuth 흐름을 완료합니다. +4. 스프레드시트 접근에 필요한 권한을 허용합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Google Sheets 스프레드시트에서 행을 가져옵니다. + + **매개변수:** + - `spreadsheetId` (string, 필수): 스프레드시트 - Connect Portal Workflow Settings를 사용하여 사용자가 스프레드시트를 선택할 수 있도록 합니다. 선택한 스프레드시트의 첫 번째 워크시트를 기본값으로 사용합니다. + - `limit` (string, 선택): 행 제한 - 반환할 최대 행 수를 제한합니다. + + + + + **설명:** Google Sheets 스프레드시트에 새로운 행을 만듭니다. + + **매개변수:** + - `spreadsheetId` (string, 필수): 스프레드시트 - Connect Portal Workflow Settings를 사용하여 사용자가 스프레드시트를 선택할 수 있도록 합니다. 선택한 스프레드시트의 첫 번째 워크시트를 기본값으로 사용합니다. + - `worksheet` (string, 필수): 워크시트 - 워크시트에는 반드시 열 헤더가 있어야 합니다. + - `additionalFields` (object, 필수): 필드 - 추가할 행의 필드를 열 이름을 key로 하는 객체로 포함합니다. Connect Portal Workflow Settings를 사용하여 사용자가 열 매핑을 선택할 수 있도록 합니다. + ```json + { + "columnName1": "columnValue1", + "columnName2": "columnValue2", + "columnName3": "columnValue3", + "columnName4": "columnValue4" + } + ``` + + + + + **설명:** Google Sheets 스프레드시트의 기존 행을 업데이트합니다. + + **매개변수:** + - `spreadsheetId` (string, 필수): 스프레드시트 - Connect Portal Workflow Settings를 사용하여 사용자가 스프레드시트를 선택할 수 있도록 합니다. 선택한 스프레드시트의 첫 번째 워크시트를 기본값으로 사용합니다. + - `worksheet` (string, 필수): 워크시트 - 워크시트에는 반드시 열 헤더가 있어야 합니다. + - `filterFormula` (object, 선택): 필터 - 업데이트할 행을 식별하기 위한 단일 조건의 AND 그룹으로 이루어진 OR의 형태(분리 정규형)로 작성합니다. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "status", + "operator": "$stringExactlyMatches", + "value": "pending" + } + ] + } + ] + } + ``` + 사용 가능한 연산자: `$stringContains`, `$stringDoesNotContain`, `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$numberGreaterThan`, `$numberLessThan`, `$numberEquals`, `$numberDoesNotEqual`, `$dateTimeAfter`, `$dateTimeBefore`, `$dateTimeEquals`, `$booleanTrue`, `$booleanFalse`, `$exists`, `$doesNotExist` + - `additionalFields` (object, 필수): 필드 - 업데이트할 필드를 열 이름을 key로 하는 객체로 포함합니다. Connect Portal Workflow Settings를 사용하여 사용자가 열 매핑을 선택할 수 있도록 합니다. + ```json + { + "columnName1": "newValue1", + "columnName2": "newValue2", + "columnName3": "newValue3", + "columnName4": "newValue4" + } + ``` + + + + +## 사용 예시 + +### 기본 Google Sheets 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Sheets capabilities +sheets_agent = Agent( + role="Data Manager", + goal="Manage spreadsheet data and track information efficiently", + backstory="An AI assistant specialized in data management and spreadsheet operations.", + apps=['google_sheets'] +) + +# Task to add new data to a spreadsheet +data_entry_task = Task( + description="Add a new customer record to the customer database spreadsheet with name, email, and signup date", + agent=sheets_agent, + expected_output="New customer record added successfully to the spreadsheet" +) + +# Run the task +crew = Crew( + agents=[sheets_agent], + tasks=[data_entry_task] +) + +crew.kickoff() +``` + +### 특정 Google Sheets 도구 필터링 + +```python + +data_collector = Agent( + role="Data Collector", + goal="Collect and organize data in spreadsheets", + backstory="An AI assistant that focuses on data collection and organization.", + apps=['google_sheets'] +) + +# Task to collect and organize data +data_collection = Task( + description="Retrieve current inventory data and add new product entries to the inventory spreadsheet", + agent=data_collector, + expected_output="Inventory data retrieved and new products added successfully" +) + +crew = Crew( + agents=[data_collector], + tasks=[data_collection] +) + +crew.kickoff() +``` + +### 데이터 분석 및 보고 + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Data Analyst", + goal="Analyze spreadsheet data and generate insights", + backstory="An experienced data analyst who extracts insights from spreadsheet data.", + apps=['google_sheets'] +) + +# Task to analyze data and create reports +analysis_task = Task( + description=""" + 1. Retrieve all sales data from the current month's spreadsheet + 2. Analyze the data for trends and patterns + 3. Create a summary report in a new row with key metrics + """, + agent=data_analyst, + expected_output="Sales data analyzed and summary report created with key insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### 자동화된 데이터 업데이트 + +```python +from crewai import Agent, Task, Crew + +data_updater = Agent( + role="Data Updater", + goal="Automatically update and maintain spreadsheet data", + backstory="An AI assistant that maintains data accuracy and updates records automatically.", + apps=['google_sheets'] +) + +# Task to update data based on conditions +update_task = Task( + description=""" + 1. 주문 스프레드시트에서 모든 보류 중인 주문을 찾으세요 + 2. 해당 주문의 상태를 'processing'으로 업데이트하세요 + 3. 상태가 업데이트된 시점의 타임스탬프를 추가하세요 + 4. 변경 사항을 별도의 추적 시트에 기록하세요 + """, + agent=data_updater, + expected_output="모든 보류 중인 주문이 processing 상태로 업데이트되고, 타임스탬프가 기록됨" +) + +crew = Crew( + agents=[data_updater], + tasks=[update_task] +) + +crew.kickoff() +``` + +### 복잡한 데이터 관리 워크플로우 + +```python +from crewai import Agent, Task, Crew + +workflow_manager = Agent( + role="Data Workflow Manager", + goal="Manage complex data workflows across multiple spreadsheets", + backstory="An AI assistant that orchestrates complex data operations across multiple spreadsheets.", + apps=['google_sheets'] +) + +# Complex workflow task +workflow_task = Task( + description=""" + 1. 메인 고객 스프레드시트에서 모든 고객 데이터를 가져옵니다 + 2. 활성 고객에 대한 월별 요약 항목을 생성합니다 + 3. 최근 30일간의 활동을 기반으로 고객 상태를 업데이트합니다 + 4. 고객 지표가 포함된 월간 보고서를 생성합니다 + 5. 비활성 고객 기록을 별도의 시트로 보관합니다 + """, + agent=workflow_manager, + expected_output="월간 고객 워크플로우가 완료되어 상태가 업데이트되고 보고서가 생성됨" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**권한 오류** + +- Google 계정이 대상 스프레드시트에 대해 편집 권한이 있는지 확인하세요 +- OAuth 연결에 Google Sheets API에 필요한 scope가 포함되어 있는지 검증하세요 +- 스프레드시트가 인증된 계정과 공유되어 있는지 확인하세요 + +**스프레드시트 구조 문제** + +- 행을 생성하거나 업데이트하기 전에 워크시트에 올바른 열 헤더가 있는지 확인하세요 +- `additionalFields`의 열 이름이 실제 열 헤더와 일치하는지 검증하세요 +- 지정된 워크시트가 스프레드시트에 존재하는지 확인하세요 + +**데이터 유형 및 형식 문제** + +- 데이터 값이 각 열에 대해 예상되는 형식과 일치하는지 확인하세요 +- 날짜 열에는 올바른 날짜 형식(ISO 형식 권장)을 사용하세요 +- 숫자 열에 입력되는 값이 적절한 형식인지 검증하세요 + +**필터 수식 문제** + +- 필터 수식이 부정 정규형(disjunctive normal form)의 올바른 JSON 구조를 따르는지 확인하세요 +- 실제 열 헤더와 일치하는 유효한 필드명을 사용하세요 +- 복잡한 다중 조건 쿼리를 작성하기 전에 간단한 필터로 테스트하세요 +- 연산자 유형이 열의 데이터 유형과 일치하는지 검증하세요 + +**행 제한 및 성능** + +- `GOOGLE_SHEETS_GET_ROW`를 사용할 때 행 제한에 유의하세요 +- 대용량 데이터셋의 경우 페이지네이션을 고려하세요 +- 처리되는 데이터의 양을 줄이기 위해 구체적인 필터를 사용하세요 + +**업데이트 작업** + +- 필터 조건이 업데이트하려는 행을 정확하게 식별하는지 확인하세요 +- 대규모 업데이트 전에 작은 데이터셋으로 필터 조건을 테스트하세요 +- 모든 필수 필드가 업데이트 작업에 포함되어 있는지 검증하세요 + +### 도움 받기 + + + Google Sheets 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 저희 + 지원팀으로 문의해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/google_slides.mdx b/docs/v1.15.1/ko/enterprise/integrations/google_slides.mdx new file mode 100644 index 000000000..da0449a63 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/google_slides.mdx @@ -0,0 +1,340 @@ +--- +title: Google Slides 통합 +description: "CrewAI를 위한 Google Slides 통합으로 프레젠테이션 생성 및 관리." +icon: "chart-bar" +mode: "wide" +--- + +## 개요 + +에이전트가 Google Slides 프레젠테이션을 생성, 편집 및 관리할 수 있도록 합니다. AI 기반 자동화로 프레젠테이션 생성을 자동화하고, 콘텐츠를 업데이트하고, Google Sheets에서 데이터를 가져오며, 프레젠테이션 워크플로를 간소화합니다. + +## 전제 조건 + +Google Slides 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Google Slides 액세스 권한이 있는 Google 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Google 계정 연결 + +## Google Slides 통합 설정 + +### 1. Google 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Google Slides** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 프레젠테이션, 스프레드시트 및 드라이브 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** 내용이 없는 빈 프레젠테이션을 만듭니다. + + **매개변수:** + - `title` (string, 필수): 프레젠테이션의 제목. + + + + + **설명:** 프레젠테이션에 대한 가벼운 메타데이터(제목, 슬라이드 수, 슬라이드 ID)를 가져옵니다. 전체 콘텐츠를 가져오기 전에 먼저 사용하세요. + + **매개변수:** + - `presentationId` (string, 필수): 검색할 프레젠테이션의 ID. + + + + + **설명:** 프레젠테이션에서 모든 텍스트 콘텐츠를 추출합니다. 슬라이드 ID와 도형 및 테이블의 텍스트만 반환합니다 (포맷팅 없음). + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + + + + + **설명:** ID로 프레젠테이션을 검색합니다. + + **매개변수:** + - `presentationId` (string, 필수): 검색할 프레젠테이션의 ID. + - `fields` (string, 선택사항): 응답에 포함할 필드. 성능 향상을 위해 필요한 데이터만 반환하는 데 사용. + + + + + **설명:** 프레젠테이션에 업데이트를 적용하거나 콘텐츠를 추가하거나 제거합니다. + + **매개변수:** + - `presentationId` (string, 필수): 업데이트할 프레젠테이션의 ID. + - `requests` (array, 필수): 프레젠테이션에 적용할 업데이트 목록. 각 항목은 요청을 나타내는 객체. + - `writeControl` (object, 선택사항): 쓰기 요청이 실행되는 방식을 제어합니다. `requiredRevisionId` (string)를 포함. + + + + + **설명:** 단일 슬라이드에서 텍스트 콘텐츠를 추출합니다. 도형 및 테이블의 텍스트만 반환합니다 (포맷팅 또는 스타일 없음). + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `pageObjectId` (string, 필수): 텍스트를 가져올 슬라이드/페이지의 ID. + + + + + **설명:** ID로 특정 페이지를 검색합니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `pageObjectId` (string, 필수): 검색할 페이지의 ID. + + + + + **설명:** 페이지 썸네일을 생성합니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `pageObjectId` (string, 필수): 썸네일 생성을 위한 페이지의 ID. + + + + + **설명:** 프레젠테이션에 추가 빈 슬라이드를 추가합니다. 새 프레젠테이션에는 이미 빈 슬라이드가 하나 있습니다. 먼저 get_presentation_metadata를 확인하세요. 제목/본문 영역이 있는 슬라이드는 create_slide_with_layout을 사용하세요. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `insertionIndex` (integer, 선택사항): 슬라이드를 삽입할 위치 (0 기반). 생략하면 맨 끝에 추가됩니다. + + + + + **설명:** 제목, 본문 등의 플레이스홀더 영역이 있는 미리 정의된 레이아웃으로 슬라이드를 만듭니다. 구조화된 콘텐츠에는 create_slide보다 적합합니다. 생성 후 get_page로 플레이스홀더 ID를 찾고, 그 안에 텍스트를 삽입하세요. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `layout` (string, 필수): 레이아웃 유형. 옵션: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. 제목+설명은 TITLE_AND_BODY, 제목만은 TITLE, 섹션 구분은 SECTION_HEADER가 적합합니다. + - `insertionIndex` (integer, 선택사항): 삽입할 위치 (0 기반). 생략하면 맨 끝에 추가됩니다. + + + + + **설명:** 콘텐츠가 있는 텍스트 상자를 슬라이드에 만듭니다. 제목, 설명, 단락에 사용합니다. 테이블에는 사용하지 마세요. 선택적으로 EMU 단위로 위치(x, y)와 크기(width, height)를 지정할 수 있습니다 (914400 EMU = 1 인치). + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 텍스트 상자를 추가할 슬라이드의 ID. + - `text` (string, 필수): 텍스트 상자의 텍스트 내용. + - `x` (integer, 선택사항): EMU 단위 X 위치 (914400 = 1 인치). 기본값: 914400 (왼쪽에서 1 인치). + - `y` (integer, 선택사항): EMU 단위 Y 위치 (914400 = 1 인치). 기본값: 914400 (위에서 1 인치). + - `width` (integer, 선택사항): EMU 단위 너비. 기본값: 7315200 (약 8 인치). + - `height` (integer, 선택사항): EMU 단위 높이. 기본값: 914400 (약 1 인치). + + + + + **설명:** 프레젠테이션에서 슬라이드를 제거합니다. 슬라이드 ID를 찾으려면 먼저 get_presentation을 사용하세요. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 삭제할 슬라이드의 객체 ID. get_presentation에서 가져옵니다. + + + + + **설명:** 기존 슬라이드의 복사본을 만듭니다. 복사본은 원본 바로 다음에 삽입됩니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 복제할 슬라이드의 객체 ID. get_presentation에서 가져옵니다. + + + + + **설명:** 슬라이드를 새 위치로 이동하여 순서를 변경합니다. 슬라이드 ID는 현재 프레젠테이션 순서대로 있어야 합니다 (중복 없음). + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideIds` (string 배열, 필수): 이동할 슬라이드 ID 배열. 현재 프레젠테이션 순서대로 있어야 합니다. + - `insertionIndex` (integer, 필수): 대상 위치 (0 기반). 0 = 맨 앞, 슬라이드 수 = 맨 끝. + + + + + **설명:** 슬라이드에 YouTube 동영상을 삽입합니다. 동영상 ID는 YouTube URL의 "v=" 다음 값입니다 (예: youtube.com/watch?v=abc123의 경우 "abc123" 사용). + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 동영상을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다. + - `videoId` (string, 필수): YouTube 동영상 ID (URL의 v= 다음 값). + + + + + **설명:** 슬라이드에 Google Drive의 동영상을 삽입합니다. 파일 ID는 Drive 파일 URL에서 찾을 수 있습니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 동영상을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다. + - `fileId` (string, 필수): 동영상의 Google Drive 파일 ID. + + + + + **설명:** 슬라이드의 배경 이미지를 설정합니다. 이미지 URL은 공개적으로 액세스 가능해야 합니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 배경을 설정할 슬라이드의 ID. get_presentation에서 가져옵니다. + - `imageUrl` (string, 필수): 배경으로 사용할 이미지의 공개적으로 액세스 가능한 URL. + + + + + **설명:** 슬라이드에 빈 테이블을 만듭니다. 콘텐츠가 있는 테이블을 만들려면 create_table_with_content를 사용하세요. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 테이블을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다. + - `rows` (integer, 필수): 테이블의 행 수. + - `columns` (integer, 필수): 테이블의 열 수. + + + + + **설명:** 한 번의 작업으로 콘텐츠가 있는 테이블을 만듭니다. 콘텐츠는 2D 배열로 제공하며, 각 내부 배열은 행을 나타냅니다. 예: [["Header1", "Header2"], ["Row1Col1", "Row1Col2"]]. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `slideId` (string, 필수): 테이블을 추가할 슬라이드의 ID. get_presentation에서 가져옵니다. + - `rows` (integer, 필수): 테이블의 행 수. + - `columns` (integer, 필수): 테이블의 열 수. + - `content` (array, 필수): 2D 배열 형태의 테이블 콘텐츠. 각 내부 배열은 행입니다. 예: [["Year", "Revenue"], ["2023", "$10M"]]. + + + + + **설명:** Google 시트에서 프레젠테이션으로 데이터를 가져옵니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `sheetId` (string, 필수): 가져올 Google 시트의 ID. + - `dataRange` (string, 필수): 시트에서 가져올 데이터 범위. + + + + + **설명:** 프레젠테이션과 연결된 Google 드라이브에 파일을 업로드합니다. + + **매개변수:** + - `file` (string, 필수): 업로드할 파일 데이터. + - `presentationId` (string, 필수): 업로드된 파일을 연결할 프레젠테이션의 ID. + + + + + **설명:** Google 드라이브의 파일을 프레젠테이션에 연결합니다. + + **매개변수:** + - `presentationId` (string, 필수): 프레젠테이션의 ID. + - `fileId` (string, 필수): 연결할 파일의 ID. + + + + + **설명:** 사용자가 액세스할 수 있는 모든 프레젠테이션을 나열합니다. + + **매개변수:** + - `pageSize` (integer, 선택사항): 페이지당 반환할 프레젠테이션 수. + - `pageToken` (string, 선택사항): 페이지네이션을 위한 토큰. + + + + + **설명:** ID로 프레젠테이션을 삭제합니다. + + **매개변수:** + - `presentationId` (string, 필수): 삭제할 프레젠테이션의 ID. + + + + +## 사용 예제 + +### 기본 Google Slides 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Google Slides 기능을 가진 에이전트 생성 +slides_agent = Agent( + role="프레젠테이션 작성자", + goal="Google Slides 프레젠테이션을 효율적으로 생성하고 관리", + backstory="프레젠테이션 디자인 및 콘텐츠 관리 전문 AI 어시스턴트.", + apps=['google_slides'] # 모든 Google Slides 작업을 사용할 수 있습니다 +) + +# 새 프레젠테이션 생성 작업 +create_presentation_task = Task( + description="'분기별 매출 보고서'라는 제목으로 새 빈 프레젠테이션을 만드세요", + agent=slides_agent, + expected_output="새 프레젠테이션 '분기별 매출 보고서'가 성공적으로 생성됨" +) + +# 작업 실행 +crew = Crew( + agents=[slides_agent], + tasks=[create_presentation_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Google 계정이 Google Slides 및 Google Drive 액세스에 필요한 권한을 가지고 있는지 확인하세요. +- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요. + +**프레젠테이션/페이지 ID 문제** + +- 프레젠테이션 ID와 페이지 객체 ID가 올바른지 다시 확인하세요. +- 프레젠테이션이나 페이지가 존재하고 액세스할 수 있는지 확인하세요. + +### 도움 받기 + + + Google Slides 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/hubspot.mdx b/docs/v1.15.1/ko/enterprise/integrations/hubspot.mdx new file mode 100644 index 000000000..5c3330b3e --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/hubspot.mdx @@ -0,0 +1,619 @@ +--- +title: "HubSpot 연동" +description: "CrewAI로 HubSpot에서 회사 및 연락처를 관리하세요." +icon: "briefcase" +mode: "wide" +--- + +## 개요 + +에이전트가 HubSpot 내에서 회사 및 연락처를 관리할 수 있도록 지원합니다. 새로운 레코드를 생성하고 AI 기반 자동화로 CRM 프로세스를 효율화하세요. + +## 사전 준비 사항 + +HubSpot 통합을 사용하기 전에 다음을 확인하세요. + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 HubSpot 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 HubSpot 계정이 연결되어 있음 + +## HubSpot 통합 설정 + +### 1. HubSpot 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합 섹션에서 **HubSpot**을 찾습니다. +3. **Connect**를 클릭하고 OAuth 플로우를 완료합니다. +4. 회사 및 연락처 관리를 위한 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 액션 + + + + **설명:** HubSpot에서 새로운 회사 레코드를 생성합니다. + + **파라미터:** + - `name` (string, 필수): 회사명. + - `domain` (string, 선택): 회사 도메인명. + - `industry` (string, 선택): 산업군. HubSpot에서 미리 정의된 값 중 하나여야 합니다. + - `phone` (string, 선택): 전화번호. + - `hubspot_owner_id` (string, 선택): 회사 소유자 ID. + - `type` (string, 선택): 회사 유형. 사용 가능한 값: `PROSPECT`, `PARTNER`, `RESELLER`, `VENDOR`, `OTHER`. + - `city` (string, 선택): 도시. + - `state` (string, 선택): 주/지역. + - `zip` (string, 선택): 우편번호. + - `numberofemployees` (number, 선택): 직원 수. + - `annualrevenue` (number, 선택): 연간 매출. + - `timezone` (string, 선택): 시간대. + - `description` (string, 선택): 설명. + - `linkedin_company_page` (string, 선택): LinkedIn 회사 페이지 URL. + - `company_email` (string, 선택): 회사 이메일. + - `first_name` (string, 선택): 회사 연락처의 이름. + - `last_name` (string, 선택): 회사 연락처의 성. + - `about_us` (string, 선택): 회사 소개. + - `hs_csm_sentiment` (string, 선택): CSM 만족도. 사용 가능한 값: `at_risk`, `neutral`, `healthy`. + - `closedate` (string, 선택): 마감일. + - `hs_keywords` (string, 선택): 회사 키워드. 미리 정의된 값 중 하나여야 합니다. + - `country` (string, 선택): 국가/지역. + - `hs_country_code` (string, 선택): 국가/지역 코드. + - `hs_employee_range` (string, 선택): 직원 범위. + - `facebook_company_page` (string, 선택): Facebook 회사 페이지 URL. + - `facebookfans` (number, 선택): Facebook 팬 수. + - `hs_gps_coordinates` (string, 선택): GPS 좌표. + - `hs_gps_error` (string, 선택): GPS 오류. + - `googleplus_page` (string, 선택): Google Plus 페이지 URL. + - `owneremail` (string, 선택): HubSpot 소유자 이메일. + - `ownername` (string, 선택): HubSpot 소유자 이름. + - `hs_ideal_customer_profile` (string, 선택): 이상적인 고객 프로필 티어. 사용 가능한 값: `tier_1`, `tier_2`, `tier_3`. + - `hs_industry_group` (string, 선택): 산업 그룹. + - `is_public` (boolean, 선택): 공개 여부. + - `hs_last_metered_enrichment_timestamp` (string, 선택): 마지막 enrichment 타임스탬프. + - `hs_lead_status` (string, 선택): 리드 상태. 사용 가능한 값: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`. + - `lifecyclestage` (string, 선택): 라이프사이클 단계. 사용 가능한 값: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`. + - `linkedinbio` (string, 선택): LinkedIn 바이오. + - `hs_linkedin_handle` (string, 선택): LinkedIn 핸들. + - `hs_live_enrichment_deadline` (string, 선택): 라이브 enrichment 기한. + - `hs_logo_url` (string, 선택): 로고 URL. + - `hs_analytics_source` (string, 선택): 원래 유입 경로. + - `hs_pinned_engagement_id` (number, 선택): 고정된 참여 ID. + - `hs_quick_context` (string, 선택): 간략한 컨텍스트. + - `hs_revenue_range` (string, 선택): 매출 범위. + - `hs_state_code` (string, 선택): 주/지역 코드. + - `address` (string, 선택): 거리 주소. + - `address2` (string, 선택): 거리 주소 2. + - `hs_is_target_account` (boolean, 선택): 타깃 계정 여부. + - `hs_target_account` (string, 선택): 타깃 계정 티어. 사용 가능한 값: `tier_1`, `tier_2`, `tier_3`. + - `hs_target_account_recommendation_snooze_time` (string, 선택): 타깃 계정 추천 일시중지 시간. + - `hs_target_account_recommendation_state` (string, 선택): 타깃 계정 추천 상태. 사용 가능한 값: `DISMISSED`, `NONE`, `SNOOZED`. + - `total_money_raised` (string, 선택): 총 조달 금액. + - `twitterbio` (string, 선택): 트위터 바이오. + - `twitterfollowers` (number, 선택): 트위터 팔로워 수. + - `twitterhandle` (string, 선택): 트위터 핸들. + - `web_technologies` (string, 선택): 사용한 웹 기술. 미리 정의된 값 중 하나여야 합니다. + - `website` (string, 선택): 웹사이트 URL. + - `founded_year` (string, 선택): 설립 연도. + + + + + **설명:** HubSpot에서 새로운 연락처 레코드를 생성합니다. + + **파라미터:** + - `email` (string, 필수): 연락처 이메일 주소. + - `firstname` (string, 선택): 이름. + - `lastname` (string, 선택): 성. + - `phone` (string, 선택): 전화번호. + - `hubspot_owner_id` (string, 선택): 연락처 소유자. + - `lifecyclestage` (string, 선택): 라이프사이클 단계. 사용 가능한 값: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`. + - `hs_lead_status` (string, 선택): 리드 상태. 사용 가능한 값: `NEW`, `OPEN`, `IN_PROGRESS`, `OPEN_DEAL`, `UNQUALIFIED`, `ATTEMPTED_TO_CONTACT`, `CONNECTED`, `BAD_TIMING`. + - `annualrevenue` (string, 선택): 연간 매출. + - `hs_buying_role` (string, 선택): 구매 역할. + - `cc_emails` (string, 선택): 참조(CC) 이메일. + - `ch_customer_id` (string, 선택): Chargify 고객 ID. + - `ch_customer_reference` (string, 선택): Chargify 고객 참조. + - `chargify_sites` (string, 선택): Chargify 사이트(들). + - `city` (string, 선택): 도시. + - `hs_facebook_ad_clicked` (boolean, 선택): Facebook 광고 클릭 여부. + - `hs_linkedin_ad_clicked` (string, 선택): LinkedIn 광고 클릭 여부. + - `hs_clicked_linkedin_ad` (string, 선택): LinkedIn 광고 클릭 여부. + - `closedate` (string, 선택): 마감일. + - `company` (string, 선택): 회사명. + - `company_size` (string, 선택): 회사 규모. + - `country` (string, 선택): 국가/지역. + - `hs_country_region_code` (string, 선택): 국가/지역 코드. + - `date_of_birth` (string, 선택): 생년월일. + - `degree` (string, 선택): 학위. + - `hs_email_customer_quarantined_reason` (string, 선택): 이메일 주소 격리 사유. + - `hs_role` (string, 선택): 고용 역할. 미리 정의된 값 중 하나여야 합니다. + - `hs_seniority` (string, 선택): 고용 직급. 미리 정의된 값 중 하나여야 합니다. + - `hs_sub_role` (string, 선택): 고용 하위 역할. 미리 정의된 값 중 하나여야 합니다. + - `hs_employment_change_detected_date` (string, 선택): 고용 변경 감지 날짜. + - `hs_enriched_email_bounce_detected` (boolean, 선택): 향상된 이메일 바운스 감지됨. + - `hs_facebookid` (string, 선택): Facebook ID. + - `hs_facebook_click_id` (string, 선택): Facebook 클릭 ID. + - `fax` (string, 선택): 팩스번호. + - `field_of_study` (string, 선택): 전공. + - `followercount` (number, 선택): 팔로워 수. + - `gender` (string, 선택): 성별. + - `hs_google_click_id` (string, 선택): Google 광고 클릭 ID. + - `graduation_date` (string, 선택): 졸업 날짜. + - `owneremail` (string, 선택): HubSpot 소유자 이메일(레거시). + - `ownername` (string, 선택): HubSpot 소유자 이름(레거시). + - `industry` (string, 선택): 산업군. + - `hs_inferred_language_codes` (string, 선택): 추정 언어 코드. 미리 정의된 값 중 하나여야 합니다. + - `jobtitle` (string, 선택): 직책. + - `hs_job_change_detected_date` (string, 선택): 직장 변경 감지 날짜. + - `job_function` (string, 선택): 직무. + - `hs_journey_stage` (string, 선택): 여정 단계. 미리 정의된 값 중 하나여야 합니다. + - `kloutscoregeneral` (number, 선택): Klout 점수. + - `hs_last_metered_enrichment_timestamp` (string, 선택): 마지막 enrichment 타임스탬프. + - `hs_latest_source` (string, 선택): 최신 유입 경로. + - `hs_latest_source_timestamp` (string, 선택): 최신 유입 경로 날짜. + - `hs_legal_basis` (string, 선택): 연락처 데이터 처리를 위한 법적 근거. + - `linkedinbio` (string, 선택): LinkedIn 바이오. + - `linkedinconnections` (number, 선택): LinkedIn 연결 수. + - `hs_linkedin_url` (string, 선택): LinkedIn URL. + - `hs_linkedinid` (string, 선택): LinkedIn ID. + - `hs_live_enrichment_deadline` (string, 선택): 라이브 enrichment 기한. + - `marital_status` (string, 선택): 결혼 상태. + - `hs_content_membership_email` (string, 선택): 멤버 이메일. + - `hs_content_membership_notes` (string, 선택): 멤버십 노트. + - `message` (string, 선택): 메시지. + - `military_status` (string, 선택): 군복무 상태. + - `mobilephone` (string, 선택): 휴대전화 번호. + - `numemployees` (string, 선택): 직원 수. + - `hs_analytics_source` (string, 선택): 원래 유입 경로. + - `photo` (string, 선택): 사진. + - `hs_pinned_engagement_id` (number, 선택): 고정된 참여 ID. + - `zip` (string, 선택): 우편번호. + - `hs_language` (string, 선택): 선호 언어. 미리 정의된 값 중 하나여야 합니다. + - `associatedcompanyid` (number, 선택): 기본 연결된 회사 ID. + - `hs_email_optout_survey_reason` (string, 선택): 이메일 수신 거부 사유. + - `relationship_status` (string, 선택): 관계 상태. + - `hs_returning_to_office_detected_date` (string, 선택): 사무실 복귀 감지 날짜. + - `salutation` (string, 선택): 호칭. + - `school` (string, 선택): 학교. + - `seniority` (string, 선택): 직급. + - `hs_feedback_show_nps_web_survey` (boolean, 선택): NPS 웹 설문조사를 표시할지 여부. + - `start_date` (string, 선택): 시작일. + - `state` (string, 선택): 주/지역. + - `hs_state_code` (string, 선택): 주/지역 코드. + - `hs_content_membership_status` (string, 선택): 상태. + - `address` (string, 선택): 거리 주소. + - `tax_exempt` (string, 선택): 세금 면제. + - `hs_timezone` (string, 선택): 시간대. 미리 정의된 값 중 하나여야 합니다. + - `twitterbio` (string, 선택): 트위터 바이오. + - `hs_twitterid` (string, 선택): 트위터 ID. + - `twitterprofilephoto` (string, 선택): 트위터 프로필 사진. + - `twitterhandle` (string, 선택): 트위터 사용자명. + - `vat_number` (string, 선택): 부가가치세 번호. + - `ch_verified` (string, 선택): ACH/eCheck 결제 인증됨. + - `website` (string, 선택): 웹사이트 URL. + - `hs_whatsapp_phone_number` (string, 선택): WhatsApp 전화번호. + - `work_email` (string, 선택): 업무용 이메일. + - `hs_googleplusid` (string, 선택): googleplus ID. + + + + + **설명:** HubSpot에서 새로운 거래(deal) 레코드를 생성합니다. + + **파라미터:** + - `dealname` (string, 필수): 거래 이름. + - `amount` (number, 선택): 거래 금액. + - `dealstage` (string, 선택): 거래의 파이프라인 단계. + - `pipeline` (string, 선택): 거래가 속한 파이프라인. + - `closedate` (string, 선택): 예상 마감일. + - `hubspot_owner_id` (string, 선택): 거래 소유자. + - `dealtype` (string, 선택): 거래 유형. 사용 가능한 값: `newbusiness`, `existingbusiness`. + - `description` (string, 선택): 거래 설명. + - `hs_priority` (string, 선택): 거래 우선순위. 사용 가능한 값: `low`, `medium`, `high`. + + + + + **설명:** HubSpot에서 새로운 참여(예: 노트, 이메일, 통화, 미팅, 작업)를 생성합니다. + + **파라미터:** + - `engagementType` (string, 필수): 참여 유형. 사용 가능한 값: `NOTE`, `EMAIL`, `CALL`, `MEETING`, `TASK`. + - `hubspot_owner_id` (string, 선택): 이 활동이 할당된 사용자. + - `hs_timestamp` (string, 선택): 활동 날짜 및 시간. + - `hs_note_body` (string, 선택): 노트 본문. (`NOTE`에서 사용) + - `hs_task_subject` (string, 선택): 작업 제목. (`TASK`에서 사용) + - `hs_task_body` (string, 선택): 작업 노트. (`TASK`에서 사용) + - `hs_task_status` (string, 선택): 작업 상태. (`TASK`에서 사용) + - `hs_meeting_title` (string, 선택): 미팅 제목. (`MEETING`에서 사용) + - `hs_meeting_body` (string, 선택): 미팅 설명. (`MEETING`에서 사용) + - `hs_meeting_start_time` (string, 선택): 미팅 시작 시간. (`MEETING`에서 사용) + - `hs_meeting_end_time` (string, 선택): 미팅 종료 시간. (`MEETING`에서 사용) + + + + + **설명:** HubSpot에서 기존 회사 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 회사의 ID. + - `name` (string, 선택): 회사명. + - `domain` (string, 선택): 회사 도메인명. + - `industry` (string, 선택): 산업군. + - `phone` (string, 선택): 전화번호. + - `city` (string, 선택): 도시. + - `state` (string, 선택): 주/지역. + - `zip` (string, 선택): 우편번호. + - `numberofemployees` (number, 선택): 직원 수. + - `annualrevenue` (number, 선택): 연간 매출. + - `description` (string, 선택): 설명. + + + + + **설명:** HubSpot에서 지정된 오브젝트 타입의 레코드를 생성합니다. + + **파라미터:** + - `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID. + - 추가 파라미터는 커스텀 오브젝트의 스키마에 따라 다릅니다. + + + + + **설명:** HubSpot에서 기존 연락처 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 연락처의 ID. + - `firstname` (string, 선택): 이름. + - `lastname` (string, 선택): 성. + - `email` (string, 선택): 이메일 주소. + - `phone` (string, 선택): 전화번호. + - `company` (string, 선택): 회사명. + - `jobtitle` (string, 선택): 직책. + - `lifecyclestage` (string, 선택): 라이프사이클 단계. + + + + + **설명:** HubSpot에서 기존 거래 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 거래의 ID. + - `dealname` (string, 선택): 거래 이름. + - `amount` (number, 선택): 거래 금액. + - `dealstage` (string, 선택): 거래의 파이프라인 단계. + - `pipeline` (string, 선택): 거래가 속한 파이프라인. + - `closedate` (string, 선택): 예상 마감일. + - `dealtype` (string, 선택): 거래 유형. + + + + + **설명:** HubSpot에서 기존 참여(engagement)를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 참여의 ID. + - `hs_note_body` (string, 선택): 노트 본문. + - `hs_task_subject` (string, 선택): 작업 제목. + - `hs_task_body` (string, 선택): 작업 노트. + - `hs_task_status` (string, 선택): 작업 상태. + + + + + **설명:** HubSpot에서 지정된 오브젝트 타입의 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 레코드의 ID. + - `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID. + - 추가 파라미터는 커스텀 오브젝트의 스키마에 따라 다릅니다. + + + + + **설명:** HubSpot에서 회사 레코드 목록을 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** HubSpot에서 연락처 레코드 목록을 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** HubSpot에서 거래 레코드 목록을 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** HubSpot에서 참여(engagement) 레코드 목록을 가져옵니다. + + **파라미터:** + - `objectName` (string, 필수): 가져올 참여 유형(예: "notes"). + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** HubSpot에서 지정된 오브젝트 타입의 레코드 목록을 가져옵니다. + + **파라미터:** + - `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID. + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** ID로 단일 회사 레코드를 가져옵니다. + + **파라미터:** + - `recordId` (string, 필수): 가져올 회사의 ID. + + + + + **설명:** ID로 단일 연락처 레코드를 가져옵니다. + + **파라미터:** + - `recordId` (string, 필수): 가져올 연락처의 ID. + + + + + **설명:** ID로 단일 거래 레코드를 가져옵니다. + + **파라미터:** + - `recordId` (string, 필수): 가져올 거래의 ID. + + + + + **설명:** ID로 단일 참여(engagement) 레코드를 가져옵니다. + + **파라미터:** + - `recordId` (string, 필수): 가져올 참여의 ID. + + + + + **설명:** 지정된 오브젝트 타입의 단일 레코드를 ID로 가져옵니다. + + **파라미터:** + - `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID. + - `recordId` (string, 필수): 가져올 레코드의 ID. + + + + + **설명:** 필터 수식을 사용해 HubSpot에서 회사 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 분리 정규형(OR of ANDs) 필터. + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** 필터 수식을 사용해 HubSpot에서 연락처 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 분리 정규형(OR of ANDs) 필터. + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** 필터 수식을 사용해 HubSpot에서 거래 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 분리 정규형(OR of ANDs) 필터. + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** 필터 수식을 사용해 HubSpot에서 참여(engagement) 레코드를 검색합니다. + + **파라미터:** + - `engagementFilterFormula` (object, 선택): 참여 필터. + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** HubSpot에서 지정된 오브젝트 타입의 레코드를 검색합니다. + + **파라미터:** + - `recordType` (string, 필수): 검색할 오브젝트 타입 ID. + - `filterFormula` (string, 선택): 적용할 필터 수식. + - `paginationParameters` (object, 선택): 다음 페이지를 가져오려면 `pageCursor`를 사용하세요. + + + + + **설명:** ID로 회사 레코드를 삭제합니다. + + **파라미터:** + - `recordId` (string, 필수): 삭제할 회사의 ID. + + + + + **설명:** ID로 연락처 레코드를 삭제합니다. + + **파라미터:** + - `recordId` (string, 필수): 삭제할 연락처의 ID. + + + + + **설명:** ID로 거래 레코드를 삭제합니다. + + **파라미터:** + - `recordId` (string, 필수): 삭제할 거래의 ID. + + + + + **설명:** ID로 참여(engagement) 레코드를 삭제합니다. + + **파라미터:** + - `recordId` (string, 필수): 삭제할 참여의 ID. + + + + + **설명:** 지정된 오브젝트 타입의 레코드를 ID로 삭제합니다. + + **파라미터:** + - `recordType` (string, 필수): 커스텀 오브젝트의 오브젝트 타입 ID. + - `recordId` (string, 필수): 삭제할 레코드의 ID. + + + + + **설명:** 지정된 리스트 ID로부터 연락처 목록을 가져옵니다. + + **파라미터:** + - `listId` (string, 필수): 연락처를 가져올 리스트의 ID. + - `paginationParameters` (object, 선택): 이후 페이지를 위해 `pageCursor` 사용. + + + + + **설명:** 특정 오브젝트 타입 및 작업에 대한 예상 스키마를 가져옵니다. + + **파라미터:** + - `recordType` (string, 필수): 오브젝트 타입 ID(예: 'companies'). + - `operation` (string, 필수): 작업 유형(예: 'CREATE_RECORD'). + + + + +## 사용 예시 + +### 기본 HubSpot 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with HubSpot capabilities +hubspot_agent = Agent( + role="CRM Manager", + goal="Manage company and contact records in HubSpot", + backstory="An AI assistant specialized in CRM management.", + apps=['hubspot'] +) + +# Task to create a new company +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" +) + +# Run the task +crew = Crew( + agents=[hubspot_agent], + tasks=[create_company_task] +) + +crew.kickoff() +``` + +### 특정 HubSpot 도구 필터링 + +```python + +# Get only the tool to create contacts + actions_list=["hubspot/create_contact"] +) + +contact_creator = Agent( + role="Contact Creator", + goal="Create new contacts in HubSpot", + backstory="An AI assistant that focuses on creating new contact entries in the CRM.", + apps=['hubspot'] +) + +# Task to create a contact +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() +``` + +### 연락처 관리 + +```python +from crewai import Agent, Task, Crew + +crm_manager = Agent( + role="CRM Manager", + goal="Manage and organize HubSpot contacts efficiently.", + backstory="An experienced CRM manager who maintains an organized contact database.", + apps=['hubspot'] +) + +# Task to manage contacts +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() +``` + +### 도움 받기 + + + HubSpot 연동 설정 또는 문제 해결에 도움이 필요하시면 지원팀에 문의해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/jira.mdx b/docs/v1.15.1/ko/enterprise/integrations/jira.mdx new file mode 100644 index 000000000..dc25b63e0 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/jira.mdx @@ -0,0 +1,407 @@ +--- +title: Jira 연동 +description: "CrewAI를 위한 Jira 연동을 통한 이슈 추적 및 프로젝트 관리." +icon: "bug" +mode: "wide" +--- + +## 개요 + +에이전트가 Jira를 통해 이슈, 프로젝트, 워크플로우를 관리할 수 있도록 합니다. 이슈를 생성 및 업데이트하고, 프로젝트 진행 상황을 추적하며, 할당 작업을 관리하고, AI 기반 자동화로 프로젝트 관리를 효율화하세요. + +## 사전 준비 사항 + +Jira 통합을 사용하기 전에 다음을 준비하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 프로젝트 권한이 있는 Jira 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Jira 계정 연결 + +## Jira 연동 설정 + +### 1. Jira 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. **Jira**를 인증 통합 섹션에서 찾습니다. +3. **Connect**를 클릭하고 OAuth 절차를 완료합니다. +4. 이슈 및 프로젝트 관리를 위한 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Jira에서 이슈를 생성합니다. + + **파라미터:** + - `summary` (string, 필수): 요약 - 이슈에 대한 간단한 한 줄 요약입니다. (예시: "프린터가 작동을 멈췄습니다"). + - `project` (string, 선택): 프로젝트 - 이슈가 속한 프로젝트입니다. 제공되지 않으면 사용자의 첫 번째 프로젝트로 기본 설정됩니다. 사용자가 프로젝트를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요. + - `issueType` (string, 선택): 이슈 유형 - 제공되지 않으면 기본값은 Task입니다. + - `jiraIssueStatus` (string, 선택): 상태 - 제공되지 않으면 프로젝트의 첫 번째 상태가 기본입니다. + - `assignee` (string, 선택): 담당자 - 제공되지 않으면 인증된 사용자로 기본 설정됩니다. + - `descriptionType` (string, 선택): 설명 유형 - 설명 유형을 선택하세요. + - 옵션: `description`, `descriptionJSON` + - `description` (string, 선택): 설명 - 이슈에 대한 자세한 설명입니다. 이 필드는 'descriptionType'이 'description'일 때만 나타납니다. + - `additionalFields` (string, 선택): 추가 필드 - 포함해야 하는 다른 필드를 JSON 형식으로 지정하세요. 사용자가 업데이트할 이슈 필드를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요. + ```json + { + "customfield_10001": "value" + } + ``` + + + + + **설명:** Jira에서 이슈를 업데이트합니다. + + **파라미터:** + - `issueKey` (string, 필수): 이슈 키 (예시: "TEST-1234"). + - `summary` (string, 선택): 요약 - 이슈에 대한 간단한 한 줄 요약입니다. (예시: "프린터가 작동을 멈췄습니다"). + - `issueType` (string, 선택): 이슈 유형 - 사용자가 이슈 유형을 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요. + - `jiraIssueStatus` (string, 선택): 상태 - 사용자가 상태를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요. + - `assignee` (string, 선택): 담당자 - 사용자가 담당자를 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요. + - `descriptionType` (string, 선택): 설명 유형 - 설명 유형을 선택하세요. + - 옵션: `description`, `descriptionJSON` + - `description` (string, 선택): 설명 - 이슈에 대한 자세한 설명입니다. 이 필드는 'descriptionType'이 'description'일 때만 나타납니다. + - `additionalFields` (string, 선택): 추가 필드 - 포함해야 하는 다른 필드를 JSON 형식으로 지정하세요. + + + + + **설명:** Jira에서 키로 이슈를 조회합니다. + + **파라미터:** + - `issueKey` (string, 필수): 이슈 키 (예시: "TEST-1234"). + + + + + **설명:** 필터를 사용하여 Jira에서 이슈를 검색합니다. + + **파라미터:** + - `jqlQuery` (object, 선택): 불리언 합정규형(OR의 AND 그룹)으로 구성된 필터. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "status", + "operator": "$stringExactlyMatches", + "value": "Open" + } + ] + } + ] + } + ``` + 사용 가능한 연산자: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan` + - `limit` (string, 선택): 결과 제한 - 반환되는 최대 이슈 수를 제한합니다. 입력하지 않으면 기본값은 10입니다. + + + + + **설명:** Jira에서 JQL로 이슈를 검색합니다. + + **파라미터:** + - `jqlQuery` (string, 필수): JQL 쿼리 (예시: "project = PROJECT"). + - `paginationParameters` (object, 선택): 페이지네이션 결과를 위한 파라미터. + ```json + { + "pageCursor": "cursor_string" + } + ``` + + + + + **설명:** Jira에서 임의의 이슈를 업데이트합니다. 이 기능의 속성 스키마를 얻으려면 DESCRIBE_ACTION_SCHEMA를 사용하세요. + + **파라미터:** 특정 파라미터 없음 - 예상 스키마를 먼저 확인하려면 JIRA_DESCRIBE_ACTION_SCHEMA를 사용하세요. + + + + + **설명:** 이슈 유형에 대한 예상 스키마를 가져옵니다. 사용하려는 이슈 유형과 일치하는 다른 기능이 없을 경우 먼저 이 기능을 사용하세요. + + **파라미터:** + - `issueTypeId` (string, 필수): 이슈 유형 ID. + - `projectKey` (string, 필수): 프로젝트 키. + - `operation` (string, 필수): 작업 유형 값(예: CREATE_ISSUE 또는 UPDATE_ISSUE). + + + + + **설명:** Jira에서 프로젝트를 가져옵니다. + + **파라미터:** + - `paginationParameters` (object, 선택): 페이지네이션 파라미터. + ```json + { + "pageCursor": "cursor_string" + } + ``` + + + + + **설명:** Jira에서 프로젝트별 이슈 유형을 조회합니다. + + **파라미터:** + - `project` (string, 필수): 프로젝트 키. + + + + + **설명:** Jira에서 모든 이슈 유형을 조회합니다. + + **파라미터:** 필요 없음. + + + + + **설명:** 주어진 프로젝트의 이슈 상태를 조회합니다. + + **파라미터:** + - `project` (string, 필수): 프로젝트 키. + + + + + **설명:** 주어진 프로젝트의 담당자 목록을 조회합니다. + + **파라미터:** + - `project` (string, 필수): 프로젝트 키. + + + + +## 사용 예시 + +### 기본 Jira 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Jira capabilities +jira_agent = Agent( + role="Issue Manager", + goal="Manage Jira issues and track project progress efficiently", + backstory="An AI assistant specialized in issue tracking and project management.", + apps=['jira'] +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a bug report for the login functionality with high priority and assign it to the development team", + agent=jira_agent, + expected_output="Bug report created successfully with issue key" +) + +# Run the task +crew = Crew( + agents=[jira_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### 특정 Jira 도구 필터링 + +```python + +issue_coordinator = Agent( + role="Issue Coordinator", + goal="Create and manage Jira issues efficiently", + backstory="An AI assistant that focuses on issue creation and management.", + apps=['jira'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and update the status of related issues", + agent=issue_coordinator, + expected_output="Feature request created and related issues updated" +) + +crew = Crew( + agents=[issue_coordinator], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### 프로젝트 분석 및 보고 + +```python +from crewai import Agent, Task, Crew + +project_analyst = Agent( + role="Project Analyst", + goal="Analyze project data and generate insights from Jira", + backstory="An experienced project analyst who extracts insights from project management data.", + apps=['jira'] +) + +# Task to analyze project status +analysis_task = Task( + description=""" + 1. Get all projects and their issue types + 2. Search for all open issues across projects + 3. Analyze issue distribution by status and assignee + 4. Create a summary report issue with findings + """, + agent=project_analyst, + expected_output="Project analysis completed with summary report created" +) + +crew = Crew( + agents=[project_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### 자동화된 이슈 관리 + +```python +from crewai import Agent, Task, Crew + +automation_manager = Agent( + role="Automation Manager", + goal="Automate issue management and workflow processes", + backstory="An AI assistant that automates repetitive issue management tasks.", + apps=['jira'] +) + +# Task to automate issue management +automation_task = Task( + description=""" + 1. Search for all unassigned issues using JQL + 2. Get available assignees for each project + 3. Automatically assign issues based on workload and expertise + 4. Update issue priorities based on age and type + 5. Create weekly sprint planning issues + """, + agent=automation_manager, + expected_output="Issues automatically assigned and sprint planning issues created" +) + +crew = Crew( + agents=[automation_manager], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### 고급 스키마 기반 작업 + +```python +from crewai import Agent, Task, Crew + +schema_specialist = Agent( + role="Schema Specialist", + goal="Handle complex Jira operations using dynamic schemas", + backstory="An AI assistant that can work with dynamic Jira schemas and custom issue types.", + apps=['jira'] +) + +# Task using schema-based operations +schema_task = Task( + description=""" + 1. 모든 프로젝트와 해당 커스텀 이슈 유형을 가져옵니다 + 2. 각 커스텀 이슈 유형에 대해, 액션 스키마를 설명합니다 + 3. 복잡한 커스텀 필드를 위한 동적 스키마를 사용해 이슈를 생성합니다 + 4. 비즈니스 규칙에 따라 커스텀 필드 값을 사용해 이슈를 업데이트합니다 + """, + agent=schema_specialist, + expected_output="동적 스키마를 사용하여 커스텀 이슈가 생성되고 업데이트됨" +) + +crew = Crew( + agents=[schema_specialist], + tasks=[schema_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**권한 오류** + +- Jira 계정이 대상 프로젝트에 필요한 권한을 가지고 있는지 확인하세요 +- OAuth 연결에 Jira API에 필요한 범위가 포함되어 있는지 확인하세요 +- 지정된 프로젝트에서 이슈 생성/편집 권한이 있는지 확인하세요 + +**잘못된 프로젝트 또는 이슈 키** + +- 프로젝트 키와 이슈 키가 올바른 형식(예: "PROJ-123")인지 다시 확인하세요 +- 프로젝트가 존재하며 계정으로 접근 가능한지 확인하세요 +- 이슈 키가 실제로 존재하는 이슈를 참조하는지 확인하세요 + +**이슈 유형 및 상태 관련 문제** + +- 프로젝트에 대한 유효한 이슈 유형을 얻으려면 JIRA_GET_ISSUE_TYPES_BY_PROJECT를 사용하세요 +- 유효한 상태를 얻으려면 JIRA_GET_ISSUE_STATUS_BY_PROJECT를 사용하세요 +- 이슈 유형과 상태가 대상 프로젝트에 제공되는지 확인하세요 + +**JQL 쿼리 문제** + +- API 호출에 사용하기 전에 Jira의 이슈 검색에서 JQL 쿼리를 테스트하세요 +- JQL에 사용된 필드명이 정확하게 철자되어 있고, Jira 인스턴스에 존재하는지 확인하세요 +- 복잡한 쿼리에는 올바른 JQL 문법을 사용하세요 + +**커스텀 필드 및 스키마 문제** + +- 복잡한 이슈 유형에 대해 올바른 스키마를 얻으려면 JIRA_DESCRIBE_ACTION_SCHEMA를 사용하세요 +- 커스텀 필드 ID가 정확한지 확인하세요 (예: "customfield_10001") +- 커스텀 필드가 대상 프로젝트와 이슈 유형에서 사용 가능한지 확인하세요 + +**필터 공식 문제** + +- 필터 공식이 올바른 JSON 구조(불리언 합의 정규형)를 따르는지 확인하세요 +- Jira 구성에 존재하는 유효한 필드명을 사용하세요 +- 복잡한 다중 조건 쿼리를 만들기 전에 간단한 필터를 테스트하세요 + +### 도움 받기 + + + Jira 연동 설정 또는 문제 해결에 대한 지원이 필요하시면 저희 지원팀에 + 문의하십시오. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/linear.mdx b/docs/v1.15.1/ko/enterprise/integrations/linear.mdx new file mode 100644 index 000000000..a728d3858 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/linear.mdx @@ -0,0 +1,467 @@ +--- +title: Linear 연동 +description: "CrewAI를 위한 Linear 연동을 통한 소프트웨어 프로젝트 및 버그 추적." +icon: "list-check" +mode: "wide" +--- + +## 개요 + +에이전트가 Linear를 통해 이슈, 프로젝트, 개발 워크플로우를 관리할 수 있도록 지원합니다. 이슈를 생성 및 업데이트하고, 프로젝트 타임라인을 관리하며, 팀을 조직하고, AI 기반 자동화로 소프트웨어 개발 프로세스를 간소화할 수 있습니다. + +## 필수 조건 + +Linear 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 워크스페이스 권한이 있는 Linear 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)에서 Linear 계정 연결 + +## 리니어 통합 설정 + +### 1. Linear 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합( Authentication Integrations ) 섹션에서 **Linear**를 찾습니다. +3. **Connect**를 클릭하고 OAuth 절차를 완료합니다. +4. 이슈 및 프로젝트 관리를 위한 필수 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** Linear에서 새로운 이슈를 생성합니다. + + **파라미터:** + - `teamId` (string, 필수): 팀 ID - 이 새로운 이슈의 상위 팀 ID를 지정합니다. Connect Portal Workflow Settings를 사용하여 사용자가 팀 ID를 선택할 수 있도록 하세요. (예: "a70bdf0f-530a-4887-857d-46151b52b47c"). + - `title` (string, 필수): 제목 - 이 이슈의 제목을 지정합니다. + - `description` (string, 선택): 설명 - 이 이슈의 설명을 지정합니다. + - `statusId` (string, 선택): 상태 - 이 이슈의 상태를 지정합니다. + - `priority` (string, 선택): 우선순위 - 이 이슈의 우선순위를 정수로 지정합니다. + - `dueDate` (string, 선택): 마감일 - 이 이슈의 마감일을 ISO 8601 형식으로 지정합니다. + - `cycleId` (string, 선택): 사이클 ID - 이 이슈가 속한 사이클을 지정합니다. + - `additionalFields` (object, 선택): 추가 필드. + ```json + { + "assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c", + "labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"] + } + ``` + + + + + **설명:** Linear에서 이슈를 업데이트합니다. + + **파라미터:** + - `issueId` (string, 필수): 이슈 ID - 업데이트할 이슈의 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + - `title` (string, 선택): 제목 - 이 이슈의 제목을 지정합니다. + - `description` (string, 선택): 설명 - 이 이슈의 설명을 지정합니다. + - `statusId` (string, 선택): 상태 - 이 이슈의 상태를 지정합니다. + - `priority` (string, 선택): 우선순위 - 이 이슈의 우선순위를 정수로 지정합니다. + - `dueDate` (string, 선택): 마감일 - 이 이슈의 마감일을 ISO 8601 형식으로 지정합니다. + - `cycleId` (string, 선택): 사이클 ID - 이 이슈가 속한 사이클을 지정합니다. + - `additionalFields` (object, 선택): 추가 필드. + ```json + { + "assigneeId": "a70bdf0f-530a-4887-857d-46151b52b47c", + "labelIds": ["a70bdf0f-530a-4887-857d-46151b52b47c"] + } + ``` + + + + + **설명:** Linear에서 ID로 이슈를 가져옵니다. + + **파라미터:** + - `issueId` (string, 필수): 이슈 ID - 가져올 이슈의 레코드 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + + + + + **설명:** Linear에서 이슈 식별자로 이슈를 가져옵니다. + + **파라미터:** + - `externalId` (string, 필수): 외부 ID - 가져올 이슈의 사람이 읽을 수 있는 이슈 식별자를 지정합니다. (예: "ABC-1"). + + + + + **설명:** Linear에서 이슈를 검색합니다. + + **파라미터:** + - `queryTerm` (string, 필수): 검색어 - 찾을 검색어입니다. + - `issueFilterFormula` (object, 선택): 부정합적 정규형(DNF)의 필터 - 단일 조건의 AND 그룹들에 대한 OR. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "title", + "operator": "$stringContains", + "value": "bug" + } + ] + } + ] + } + ``` + 사용 가능한 필드: `title`, `number`, `project`, `createdAt` + 사용 가능한 연산자: `$stringExactlyMatches`, `$stringDoesNotExactlyMatch`, `$stringIsIn`, `$stringIsNotIn`, `$stringStartsWith`, `$stringDoesNotStartWith`, `$stringEndsWith`, `$stringDoesNotEndWith`, `$stringContains`, `$stringDoesNotContain`, `$stringGreaterThan`, `$stringLessThan`, `$numberGreaterThanOrEqualTo`, `$numberLessThanOrEqualTo`, `$numberGreaterThan`, `$numberLessThan`, `$dateTimeAfter`, `$dateTimeBefore` + + + + + **설명:** Linear에서 이슈를 삭제합니다. + + **파라미터:** + - `issueId` (string, 필수): 이슈 ID - 삭제할 이슈의 레코드 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + + + + + **설명:** Linear에서 이슈를 아카이브합니다. + + **파라미터:** + - `issueId` (string, 필수): 이슈 ID - 아카이브할 이슈의 레코드 ID를 지정합니다. (예: "90fbc706-18cd-42c9-ae66-6bd344cc8977"). + + + + + **설명:** Linear에서 하위 이슈를 생성합니다. + + **파라미터:** + - `parentId` (string, 필수): 상위 ID - 이 새로운 이슈의 상위 이슈 ID를 지정합니다. + - `teamId` (string, 필수): 팀 ID - 이 새로운 하위 이슈의 상위 팀 ID를 지정합니다. Connect Portal Workflow Settings를 사용하여 사용자가 팀 ID를 선택할 수 있도록 하세요. (예: "a70bdf0f-530a-4887-857d-46151b52b47c"). + - `title` (string, 필수): 제목 - 이 이슈의 제목을 지정합니다. + - `description` (string, 선택): 설명 - 이 이슈의 설명을 지정합니다. + - `additionalFields` (object, 선택): 추가 필드. + ```json + { + "lead": "linear_user_id" + } + ``` + + + + + **설명:** Linear에서 새로운 프로젝트를 생성합니다. + + **파라미터:** + - `teamIds` (object, 필수): 팀 ID - 이 프로젝트와 연관된 팀 ID 혹은 팀 ID의 JSON 배열을 문자열로 지정합니다. Connect Portal User Settings를 사용하여 사용자가 팀 ID를 선택할 수 있도록 하세요. + ```json + [ + "a70bdf0f-530a-4887-857d-46151b52b47c", + "4ac7..." + ] + ``` + - `projectName` (string, 필수): 프로젝트 이름 - 프로젝트의 이름을 지정합니다. (예: "My Linear Project"). + - `description` (string, 선택): 프로젝트 설명 - 프로젝트에 대한 설명을 지정합니다. + - `additionalFields` (object, 선택): 추가 필드. + ```json + { + "state": "planned", + "description": "" + } + ``` + + + + + **설명:** Linear에서 프로젝트를 업데이트합니다. + + **파라미터:** + - `projectId` (string, 필수): 프로젝트 ID - 업데이트할 프로젝트의 ID를 지정합니다. (예: "a6634484-6061-4ac7-9739-7dc5e52c796b"). + - `projectName` (string, 선택): 프로젝트 이름 - 업데이트할 프로젝트의 이름을 지정합니다. (예: "My Linear Project"). + - `description` (string, 선택): 프로젝트 설명 - 프로젝트에 대한 설명을 지정합니다. + - `additionalFields` (object, 선택): 추가 필드. + ```json + { + "state": "planned", + "description": "" + } + ``` + + + + + **설명:** Linear에서 ID로 프로젝트를 가져옵니다. + + **파라미터:** + - `projectId` (string, 필수): 프로젝트 ID - 가져올 프로젝트의 프로젝트 ID를 지정합니다. (예: "a6634484-6061-4ac7-9739-7dc5e52c796b"). + + + + + **설명:** Linear에서 프로젝트를 삭제합니다. + + **파라미터:** + - `projectId` (string, 필수): 프로젝트 ID - 삭제할 프로젝트의 프로젝트 ID를 지정합니다. (예: "a6634484-6061-4ac7-9739-7dc5e52c796b"). + + + + + **설명:** Linear에서 팀을 검색합니다. + + **파라미터:** + - `teamFilterFormula` (object, 선택): 부정합적 정규형(DNF)의 필터 - 단일 조건의 AND 그룹들에 대한 OR. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "name", + "operator": "$stringContains", + "value": "Engineering" + } + ] + } + ] + } + ``` + 사용 가능한 필드: `id`, `name` + + + + +## 사용 예시 + +### 기본 Linear 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Linear capabilities +linear_agent = Agent( + role="Development Manager", + goal="Manage Linear issues and track development progress efficiently", + backstory="An AI assistant specialized in software development project management.", + apps=['linear'] +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a high-priority bug report for the authentication system and assign it to the backend team", + agent=linear_agent, + expected_output="Bug report created successfully with issue ID" +) + +# Run the task +crew = Crew( + agents=[linear_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### 특정 Linear 도구 필터링 + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage Linear issues efficiently", + backstory="An AI assistant that focuses on issue creation and lifecycle management.", + apps=['linear'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and update the status of related issues to reflect current progress", + agent=issue_manager, + expected_output="Feature request created and related issues updated" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### 프로젝트 및 팀 관리 + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate projects and teams in Linear efficiently", + backstory="An experienced project coordinator who manages development cycles and team workflows.", + apps=['linear'] +) + +# Task to coordinate project setup +project_coordination = Task( + description=""" + 1. Search for engineering teams in Linear + 2. Create a new project for Q2 feature development + 3. Associate the project with relevant teams + 4. Create initial project milestones as issues + """, + agent=project_coordinator, + expected_output="Q2 project created with teams assigned and initial milestones established" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### 이슈 계층 구조 및 하위 작업 관리 + +```python +from crewai import Agent, Task, Crew + +task_organizer = Agent( + role="Task Organizer", + goal="Organize complex issues into manageable sub-tasks", + backstory="An AI assistant that breaks down complex development work into organized sub-tasks.", + apps=['linear'] +) + +# Task to create issue hierarchy +hierarchy_task = Task( + description=""" + 1. 세분화가 필요한 대형 기능 이슈를 검색합니다 + 2. 각 복잡한 이슈에 대해 다양한 컴포넌트별로 하위 이슈를 생성합니다 + 3. 부모 이슈를 적절한 설명과 하위 이슈에 대한 링크로 업데이트합니다 + 4. 전문성에 따라 적합한 팀원에게 하위 이슈를 할당합니다 + """, + agent=task_organizer, + expected_output="복잡한 이슈가 적절히 할당된 관리 가능한 하위 작업 단위로 분해됨" +) + +crew = Crew( + agents=[task_organizer], + tasks=[hierarchy_task] +) + +crew.kickoff() +``` + +### 자동화된 개발 워크플로우 + +```python +from crewai import Agent, Task, Crew + +workflow_automator = Agent( + role="Workflow Automator", + goal="Automate development workflow processes in Linear", + backstory="An AI assistant that automates repetitive development workflow tasks.", + apps=['linear'] +) + +# Complex workflow automation task +automation_task = Task( + description=""" + 1. 7일 이상 진행 중인 이슈를 검색합니다 + 2. 마감일과 프로젝트 중요도에 따라 우선순위를 업데이트합니다 + 3. 각 팀을 위한 주간 스프린트 계획 이슈를 생성합니다 + 4. 이전 사이클에서 완료된 이슈를 보관합니다 + 5. 프로젝트 상태 보고서를 새로운 이슈로 생성합니다 + """, + agent=workflow_automator, + expected_output="우선순위, 스프린트 계획, 상태 보고서가 업데이트된 자동화된 개발 워크플로우" +) + +crew = Crew( + agents=[workflow_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**권한 오류** + +- Linear 계정이 대상 워크스페이스에 필요한 권한을 가지고 있는지 확인하세요 +- OAuth 연결에 Linear API에 필요한 스코프가 포함되어 있는지 확인하세요 +- 워크스페이스에서 이슈 및 프로젝트를 생성/편집할 권한이 있는지 확인하세요 + +**잘못된 ID 및 참조** + +- 팀 ID, 이슈 ID, 프로젝트 ID가 올바른 UUID 형식인지 다시 한번 확인하세요 +- 참조된 엔티티(팀, 프로젝트, 사이클)가 존재하며 접근 가능한지 확인하세요 +- 이슈 식별자가 올바른 형식(예: "ABC-1")을 따르는지 검증하세요 + +**팀 및 프로젝트 연관 문제** + +- 이슈나 프로젝트를 생성하기 전에 LINEAR_SEARCH_TEAMS를 사용하여 유효한 팀 ID를 조회하세요 +- 워크스페이스 내에 팀이 존재하고 활성화되어 있는지 확인하세요 +- 팀 ID가 올바르게 UUID 형식으로 구성되어 있는지 검증하세요 + +**이슈 상태 및 우선순위 문제** + +- 상태 ID가 팀의 유효한 워크플로우 상태를 참조하는지 확인하세요 +- 우선순위 값이 Linear 구성에서 허용된 범위 내에 있는지 확인하세요 +- 참조하기 전에 사용자 지정 필드와 라벨이 존재하는지 검증하세요 + +**날짜 및 시간 형식 문제** + +- 마감일 및 타임스탬프에 ISO 8601 형식을 사용하세요 +- 마감일 계산 시 타임존을 올바로 처리하는지 확인하세요 +- 마감일의 날짜 값이 유효하며 미래인지 검증하세요 + +**검색 및 필터 문제** + +- 검색 쿼리가 올바르게 형식화되어 있으며 비어 있지 않은지 확인하세요 +- 필터 공식에서 유효한 필드 이름을 사용하세요: `title`, `number`, `project`, `createdAt` +- 복잡한 다중 조건 쿼리를 만들기 전에 단순한 필터를 먼저 테스트해 보세요 +- 연산자 타입이 필터링 대상 필드의 데이터 타입과 일치하는지 확인하세요 + +**서브이슈 생성 문제** + +- 상위 이슈 ID가 유효하고 접근 가능한지 확인하세요 +- 서브이슈의 팀 ID가 상위 이슈 팀과 일치하거나 호환되는지 검증하세요 +- 상위 이슈가 이미 보관/삭제되지 않았는지 확인하세요 + +### 도움 받기 + + + Linear 연동 설정 또는 문제 해결에 대해 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/microsoft_excel.mdx b/docs/v1.15.1/ko/enterprise/integrations/microsoft_excel.mdx new file mode 100644 index 000000000..42ebd78b6 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/microsoft_excel.mdx @@ -0,0 +1,293 @@ +--- +title: Microsoft Excel 통합 +description: "CrewAI를 위한 Microsoft Excel 통합으로 통합 문서 및 데이터 관리." +icon: "table" +mode: "wide" +--- + +## 개요 + +에이전트가 OneDrive 또는 SharePoint에서 Excel 통합 문서, 워크시트, 테이블 및 차트를 생성하고 관리할 수 있도록 합니다. AI 기반 자동화로 데이터 범위를 조작하고, 시각화를 생성하고, 테이블을 관리하며, 스프레드시트 워크플로를 간소화합니다. + +## 전제 조건 + +Microsoft Excel 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Excel 및 OneDrive/SharePoint 액세스 권한이 있는 Microsoft 365 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결 + +## Microsoft Excel 통합 설정 + +### 1. Microsoft 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Microsoft Excel** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 파일 및 Excel 통합 문서 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** OneDrive 또는 SharePoint에 새 Excel 통합 문서를 만듭니다. + + **매개변수:** + - `file_path` (string, 필수): 통합 문서를 만들 경로 (예: 'MyWorkbook.xlsx') + - `worksheets` (array, 선택사항): 만들 초기 워크시트들. 각 항목은 `name` (string, 워크시트 이름)이 있는 객체. + + + + + **설명:** OneDrive 또는 SharePoint에서 모든 Excel 통합 문서를 가져옵니다. + + **매개변수:** + - `select` (string, 선택사항): 반환할 특정 속성 선택. + - `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링. + - `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장. + - `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999). + - `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬. + + + + + **설명:** Excel 통합 문서의 모든 워크시트를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `select` (string, 선택사항): 반환할 특정 속성 선택 (예: 'id,name,position'). + - `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링. + - `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장. + - `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999). + - `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬. + + + + + **설명:** Excel 통합 문서에 새 워크시트를 만듭니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `name` (string, 필수): 새 워크시트의 이름. + + + + + **설명:** Excel 워크시트의 특정 범위에서 데이터를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `range` (string, 필수): 범위 주소 (예: 'A1:C10'). + + + + + **설명:** Excel 워크시트의 특정 범위에서 데이터를 업데이트합니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `range` (string, 필수): 범위 주소 (예: 'A1:C10'). + - `values` (array, 필수): 범위에 설정할 값들의 2D 배열. 각 내부 배열은 행을 나타내며, 요소는 string, number 또는 integer일 수 있음. + + + + + **설명:** Excel 워크시트에 테이블을 만듭니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `range` (string, 필수): 테이블의 범위 (예: 'A1:D10'). + - `has_headers` (boolean, 선택사항): 첫 번째 행이 헤더를 포함하는지 여부. 기본값: true. + + + + + **설명:** Excel 워크시트의 모든 테이블을 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + + + + + **설명:** Excel 테이블에 새 행을 추가합니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `table_name` (string, 필수): 테이블의 이름. + - `values` (array, 필수): 새 행의 값들 배열. 요소는 string, number 또는 integer일 수 있음. + + + + + **설명:** Excel 워크시트의 특정 테이블에서 데이터를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `table_name` (string, 필수): 테이블의 이름. + + + + + **설명:** Excel 워크시트에 차트를 만듭니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `chart_type` (string, 필수): 차트 유형 (예: 'ColumnClustered', 'Line', 'Pie'). + - `source_data` (string, 필수): 차트의 데이터 범위 (예: 'A1:B10'). + - `series_by` (string, 선택사항): 데이터 해석 방법 ('Auto', 'Columns' 또는 'Rows'). 기본값: 'Auto'. + + + + + **설명:** Excel 워크시트의 단일 셀 값을 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `row` (integer, 필수): 행 번호 (0 기반). + - `column` (integer, 필수): 열 번호 (0 기반). + + + + + **설명:** Excel 워크시트의 사용된 범위를 가져옵니다 (모든 데이터를 포함). + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + + + + + **설명:** Excel 워크시트의 사용된 범위 메타데이터(크기만, 데이터 없음)를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + + + + + **설명:** Excel 워크시트의 모든 차트를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + + + + + **설명:** Excel 통합 문서에서 워크시트를 삭제합니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 삭제할 워크시트의 이름. + + + + + **설명:** Excel 워크시트에서 테이블을 삭제합니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + - `worksheet_name` (string, 필수): 워크시트의 이름. + - `table_name` (string, 필수): 삭제할 테이블의 이름. + + + + + **설명:** Excel 통합 문서의 모든 명명된 범위를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): Excel 파일의 ID. + + + + +## 사용 예제 + +### 기본 Microsoft Excel 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Microsoft Excel 기능을 가진 에이전트 생성 +excel_agent = Agent( + role="Excel 데이터 관리자", + goal="Excel 통합 문서와 데이터를 효율적으로 관리", + backstory="Microsoft Excel 작업 및 데이터 조작 전문 AI 어시스턴트.", + apps=['microsoft_excel'] # 모든 Excel 작업을 사용할 수 있습니다 +) + +# 새 통합 문서 생성 작업 +create_workbook_task = Task( + description="'월간보고서.xlsx'라는 이름으로 새 Excel 통합 문서를 만들고 '매출데이터'라는 초기 워크시트를 포함하세요.", + agent=excel_agent, + expected_output="새 통합 문서 '월간보고서.xlsx'가 '매출데이터' 워크시트와 함께 생성됨." +) + +# 작업 실행 +crew = Crew( + agents=[excel_agent], + tasks=[create_workbook_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Microsoft 계정이 파일 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Files.Read.All`, `Files.ReadWrite.All`). +- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요. + +**파일 생성 문제** + +- 통합 문서를 만들 때 `file_path`가 `.xlsx` 확장자로 끝나는지 확인하세요. +- 대상 위치(OneDrive/SharePoint)에 쓰기 권한이 있는지 확인하세요. + +### 도움 받기 + + + Microsoft Excel 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/microsoft_onedrive.mdx b/docs/v1.15.1/ko/enterprise/integrations/microsoft_onedrive.mdx new file mode 100644 index 000000000..40c546c54 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/microsoft_onedrive.mdx @@ -0,0 +1,332 @@ +--- +title: Microsoft OneDrive 통합 +description: "CrewAI를 위한 Microsoft OneDrive 통합으로 파일 및 폴더 관리." +icon: "cloud" +mode: "wide" +--- + +## 개요 + +에이전트가 Microsoft OneDrive에서 파일과 폴더를 업로드, 다운로드 및 관리할 수 있도록 합니다. AI 기반 자동화로 파일 작업을 자동화하고, 콘텐츠를 구성하고, 공유 링크를 생성하며, 클라우드 스토리지 워크플로를 간소화합니다. + +## 전제 조건 + +Microsoft OneDrive 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- OneDrive 액세스 권한이 있는 Microsoft 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결 + +## Microsoft OneDrive 통합 설정 + +### 1. Microsoft 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Microsoft OneDrive** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 파일 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** OneDrive의 파일과 폴더를 나열합니다. + + **매개변수:** + - `top` (integer, 선택사항): 검색할 항목 수 (최대 1000). 기본값: 50. + - `orderby` (string, 선택사항): 필드별 정렬 (예: "name asc", "lastModifiedDateTime desc"). 기본값: "name asc". + - `filter` (string, 선택사항): OData 필터 표현식. + + + + + **설명:** 특정 파일 또는 폴더에 대한 정보를 가져옵니다. + + **매개변수:** + - `item_id` (string, 필수): 파일 또는 폴더의 ID. + + + + + **설명:** OneDrive에서 파일을 다운로드합니다. + + **매개변수:** + - `item_id` (string, 필수): 다운로드할 파일의 ID. + + + + + **설명:** OneDrive에 파일을 업로드합니다. + + **매개변수:** + - `file_name` (string, 필수): 업로드할 파일의 이름. + - `content` (string, 필수): Base64로 인코딩된 파일 내용. + + + + + **설명:** OneDrive에 새 폴더를 만듭니다. + + **매개변수:** + - `folder_name` (string, 필수): 만들 폴더의 이름. + + + + + **설명:** OneDrive에서 파일 또는 폴더를 삭제합니다. + + **매개변수:** + - `item_id` (string, 필수): 삭제할 파일 또는 폴더의 ID. + + + + + **설명:** OneDrive에서 파일 또는 폴더를 복사합니다. + + **매개변수:** + - `item_id` (string, 필수): 복사할 파일 또는 폴더의 ID. + - `parent_id` (string, 선택사항): 대상 폴더의 ID (선택사항, 기본값은 루트). + - `new_name` (string, 선택사항): 복사된 항목의 새 이름 (선택사항). + + + + + **설명:** OneDrive에서 파일 또는 폴더를 이동합니다. + + **매개변수:** + - `item_id` (string, 필수): 이동할 파일 또는 폴더의 ID. + - `parent_id` (string, 필수): 대상 폴더의 ID. + - `new_name` (string, 선택사항): 항목의 새 이름 (선택사항). + + + + + **설명:** OneDrive에서 파일과 폴더를 검색합니다. + + **매개변수:** + - `query` (string, 필수): 검색 쿼리 문자열. + - `top` (integer, 선택사항): 반환할 결과 수 (최대 1000). 기본값: 50. + + + + + **설명:** 파일 또는 폴더의 공유 링크를 만듭니다. + + **매개변수:** + - `item_id` (string, 필수): 공유할 파일 또는 폴더의 ID. + - `type` (string, 선택사항): 공유 링크 유형. 옵션: view, edit, embed. 기본값: view. + - `scope` (string, 선택사항): 공유 링크 범위. 옵션: anonymous, organization. 기본값: anonymous. + + + + + **설명:** 파일의 썸네일을 가져옵니다. + + **매개변수:** + - `item_id` (string, 필수): 파일의 ID. + + + + + **설명:** 특정 OneDrive 경로의 파일과 폴더를 나열합니다. + + **매개변수:** + - `folder_path` (string, 필수): 폴더 경로 (예: 'Documents/Reports'). + - `top` (integer, 선택사항): 검색할 항목 수 (최대 1000). 기본값: 50. + - `orderby` (string, 선택사항): 필드별 정렬 (예: "name asc", "lastModifiedDateTime desc"). 기본값: "name asc". + + + + + **설명:** OneDrive에서 최근에 액세스한 파일을 가져옵니다. + + **매개변수:** + - `top` (integer, 선택사항): 검색할 항목 수 (최대 200). 기본값: 25. + + + + + **설명:** 사용자와 공유된 파일과 폴더를 가져옵니다. + + **매개변수:** + - `top` (integer, 선택사항): 검색할 항목 수 (최대 200). 기본값: 50. + - `orderby` (string, 선택사항): 필드별 정렬. 기본값: "name asc". + + + + + **설명:** 경로로 특정 파일 또는 폴더에 대한 정보를 가져옵니다. + + **매개변수:** + - `file_path` (string, 필수): 파일 또는 폴더 경로 (예: 'Documents/report.docx'). + + + + + **설명:** 경로로 OneDrive에서 파일을 다운로드합니다. + + **매개변수:** + - `file_path` (string, 필수): 파일 경로 (예: 'Documents/report.docx'). + + + + +## 사용 예제 + +### 기본 Microsoft OneDrive 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Microsoft OneDrive 기능을 가진 에이전트 생성 +onedrive_agent = Agent( + role="파일 관리자", + goal="OneDrive에서 파일과 폴더를 효율적으로 관리", + backstory="Microsoft OneDrive 파일 작업 및 구성 전문 AI 어시스턴트.", + apps=['microsoft_onedrive'] # 모든 OneDrive 작업을 사용할 수 있습니다 +) + +# 파일 나열 및 폴더 생성 작업 +organize_files_task = Task( + description="OneDrive 루트 디렉토리의 모든 파일을 나열하고 '프로젝트 문서'라는 새 폴더를 만드세요.", + agent=onedrive_agent, + expected_output="파일 목록이 표시되고 새 폴더 '프로젝트 문서'가 생성됨." +) + +# 작업 실행 +crew = Crew( + agents=[onedrive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +### 파일 업로드 및 관리 + +```python +from crewai import Agent, Task, Crew + +# 파일 작업에 특화된 에이전트 생성 +file_operator = Agent( + role="파일 운영자", + goal="파일을 정확하게 업로드, 다운로드 및 관리", + backstory="파일 처리 및 콘텐츠 관리에 능숙한 AI 어시스턴트.", + apps=['microsoft_onedrive/upload_file', 'microsoft_onedrive/download_file', 'microsoft_onedrive/get_file_info'] +) + +# 파일 업로드 및 관리 작업 +file_management_task = Task( + description="'report.txt'라는 이름의 텍스트 파일을 'This is a sample report for the project.' 내용으로 업로드한 다음 업로드된 파일에 대한 정보를 가져오세요.", + agent=file_operator, + expected_output="파일이 성공적으로 업로드되고 파일 정보가 검색됨." +) + +crew = Crew( + agents=[file_operator], + tasks=[file_management_task] +) + +crew.kickoff() +``` + +### 파일 정리 및 공유 + +```python +from crewai import Agent, Task, Crew + +# 파일 정리 및 공유를 위한 에이전트 생성 +file_organizer = Agent( + role="파일 정리자", + goal="파일을 정리하고 협업을 위한 공유 링크 생성", + backstory="파일 정리 및 공유 권한 관리에 뛰어난 AI 어시스턴트.", + apps=['microsoft_onedrive/search_files', 'microsoft_onedrive/move_item', 'microsoft_onedrive/share_item', 'microsoft_onedrive/create_folder'] +) + +# 파일 정리 및 공유 작업 +organize_share_task = Task( + description="이름에 'presentation'이 포함된 파일을 검색하고, '프레젠테이션'이라는 폴더를 만든 다음, 찾은 파일을 이 폴더로 이동하고 폴더에 대한 읽기 전용 공유 링크를 생성하세요.", + agent=file_organizer, + expected_output="파일이 '프레젠테이션' 폴더로 정리되고 공유 링크가 생성됨." +) + +crew = Crew( + agents=[file_organizer], + tasks=[organize_share_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Microsoft 계정이 파일 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Files.Read`, `Files.ReadWrite`). +- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요. + +**파일 업로드 문제** + +- 파일 업로드 시 `file_name`과 `content`가 제공되는지 확인하세요. +- 바이너리 파일의 경우 내용이 Base64로 인코딩되어야 합니다. +- OneDrive에 대한 쓰기 권한이 있는지 확인하세요. + +**파일/폴더 ID 문제** + +- 특정 파일 또는 폴더에 액세스할 때 항목 ID가 올바른지 다시 확인하세요. +- 항목 ID는 `list_files` 또는 `search_files`와 같은 다른 작업에서 반환됩니다. +- 참조하는 항목이 존재하고 액세스 가능한지 확인하세요. + +**검색 및 필터 작업** + +- `search_files` 작업에 적절한 검색어를 사용하세요. +- `filter` 매개변수의 경우 올바른 OData 문법을 사용하세요. + +**파일 작업 (복사/이동)** + +- `move_item`의 경우 `item_id`와 `parent_id`가 모두 제공되는지 확인하세요. +- `copy_item`의 경우 `item_id`만 필요합니다. `parent_id`는 지정하지 않으면 루트로 기본 설정됩니다. +- 대상 폴더가 존재하고 액세스 가능한지 확인하세요. + +**공유 링크 생성** + +- 공유 링크를 만들기 전에 항목이 존재하는지 확인하세요. +- 공유 요구 사항에 따라 적절한 `type`과 `scope`를 선택하세요. +- `anonymous` 범위는 로그인 없이 액세스를 허용합니다. `organization`은 조직 계정이 필요합니다. + +### 도움 받기 + + + Microsoft OneDrive 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/microsoft_outlook.mdx b/docs/v1.15.1/ko/enterprise/integrations/microsoft_outlook.mdx new file mode 100644 index 000000000..24e93d035 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/microsoft_outlook.mdx @@ -0,0 +1,333 @@ +--- +title: Microsoft Outlook 통합 +description: "CrewAI를 위한 Microsoft Outlook 통합으로 이메일, 캘린더 및 연락처 관리." +icon: "envelope" +mode: "wide" +--- + +## 개요 + +에이전트가 Outlook 이메일, 캘린더 이벤트 및 연락처에 액세스하고 관리할 수 있도록 합니다. AI 기반 자동화로 이메일을 보내고, 메시지를 검색하고, 캘린더 이벤트를 관리하며, 연락처를 구성합니다. + +## 전제 조건 + +Microsoft Outlook 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Outlook 액세스 권한이 있는 Microsoft 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결 + +## Microsoft Outlook 통합 설정 + +### 1. Microsoft 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Microsoft Outlook** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 이메일, 캘린더 및 연락처 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** 사용자의 사서함에서 이메일 메시지를 가져옵니다. + + **매개변수:** + - `top` (integer, 선택사항): 검색할 메시지 수 (최대 1000). 기본값: 10. + - `filter` (string, 선택사항): OData 필터 표현식 (예: "isRead eq false"). + - `search` (string, 선택사항): 검색 쿼리 문자열. + - `orderby` (string, 선택사항): 필드별 정렬 (예: "receivedDateTime desc"). 기본값: "receivedDateTime desc". + - `select` (string, 선택사항): 반환할 특정 속성 선택. + - `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장. + + + + + **설명:** 이메일 메시지를 보냅니다. + + **매개변수:** + - `to_recipients` (array, 필수): 받는 사람의 이메일 주소 배열. + - `cc_recipients` (array, 선택사항): 참조 받는 사람의 이메일 주소 배열. + - `bcc_recipients` (array, 선택사항): 숨은 참조 받는 사람의 이메일 주소 배열. + - `subject` (string, 필수): 이메일 제목. + - `body` (string, 필수): 이메일 본문 내용. + - `body_type` (string, 선택사항): 본문 내용 유형. 옵션: Text, HTML. 기본값: HTML. + - `importance` (string, 선택사항): 메시지 중요도 수준. 옵션: low, normal, high. 기본값: normal. + - `reply_to` (array, 선택사항): 회신용 이메일 주소 배열. + - `save_to_sent_items` (boolean, 선택사항): 보낸 편지함 폴더에 메시지를 저장할지 여부. 기본값: true. + + + + + **설명:** 사용자의 캘린더에서 캘린더 이벤트를 가져옵니다. + + **매개변수:** + - `top` (integer, 선택사항): 검색할 이벤트 수 (최대 1000). 기본값: 10. + - `skip` (integer, 선택사항): 건너뛸 이벤트 수. 기본값: 0. + - `filter` (string, 선택사항): OData 필터 표현식 (예: "start/dateTime ge '2024-01-01T00:00:00Z'"). + - `orderby` (string, 선택사항): 필드별 정렬 (예: "start/dateTime asc"). 기본값: "start/dateTime asc". + + + + + **설명:** 새 캘린더 이벤트를 만듭니다. + + **매개변수:** + - `subject` (string, 필수): 이벤트 제목/제목. + - `body` (string, 선택사항): 이벤트 본문/설명. + - `start_datetime` (string, 필수): ISO 8601 형식의 시작 날짜 및 시간 (예: '2024-01-20T10:00:00'). + - `end_datetime` (string, 필수): ISO 8601 형식의 종료 날짜 및 시간. + - `timezone` (string, 선택사항): 시간대 (예: 'Pacific Standard Time'). 기본값: UTC. + - `location` (string, 선택사항): 이벤트 위치. + - `attendees` (array, 선택사항): 참석자의 이메일 주소 배열. + + + + + **설명:** 사용자의 주소록에서 연락처를 가져옵니다. + + **매개변수:** + - `top` (integer, 선택사항): 검색할 연락처 수 (최대 1000). 기본값: 10. + - `skip` (integer, 선택사항): 건너뛸 연락처 수. 기본값: 0. + - `filter` (string, 선택사항): OData 필터 표현식. + - `orderby` (string, 선택사항): 필드별 정렬 (예: "displayName asc"). 기본값: "displayName asc". + + + + + **설명:** 사용자의 주소록에 새 연락처를 만듭니다. + + **매개변수:** + - `displayName` (string, 필수): 연락처의 표시 이름. + - `givenName` (string, 선택사항): 연락처의 이름. + - `surname` (string, 선택사항): 연락처의 성. + - `emailAddresses` (array, 선택사항): 이메일 주소 배열. 각 항목은 `address` (string)와 `name` (string)이 있는 객체. + - `businessPhones` (array, 선택사항): 사업용 전화번호 배열. + - `homePhones` (array, 선택사항): 집 전화번호 배열. + - `jobTitle` (string, 선택사항): 연락처의 직책. + - `companyName` (string, 선택사항): 연락처의 회사 이름. + + + + + **설명:** ID로 특정 이메일 메시지를 가져옵니다. + + **매개변수:** + - `message_id` (string, 필수): 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록. 예: "id,subject,body,from,receivedDateTime". 기본값: "id,subject,body,from,toRecipients,receivedDateTime". + + + + + **설명:** 이메일 메시지에 회신합니다. + + **매개변수:** + - `message_id` (string, 필수): 회신할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + - `comment` (string, 필수): 회신 메시지 내용. 일반 텍스트 또는 HTML 가능. 원본 메시지가 이 내용 아래에 인용됩니다. + + + + + **설명:** 이메일 메시지를 전달합니다. + + **매개변수:** + - `message_id` (string, 필수): 전달할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + - `to_recipients` (array, 필수): 전달할 받는 사람의 이메일 주소 배열. 예: ["john@example.com", "jane@example.com"]. + - `comment` (string, 선택사항): 전달된 콘텐츠 위에 포함할 선택적 메시지. 일반 텍스트 또는 HTML 가능. + + + + + **설명:** 메시지를 읽음 또는 읽지 않음으로 표시합니다. + + **매개변수:** + - `message_id` (string, 필수): 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + - `is_read` (boolean, 필수): 읽음으로 표시하려면 true, 읽지 않음으로 표시하려면 false로 설정합니다. + + + + + **설명:** 이메일 메시지를 삭제합니다. + + **매개변수:** + - `message_id` (string, 필수): 삭제할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + + + + + **설명:** 기존 캘린더 이벤트를 업데이트합니다. + + **매개변수:** + - `event_id` (string, 필수): 이벤트의 고유 식별자. get_calendar_events 작업에서 얻을 수 있습니다. + - `subject` (string, 선택사항): 이벤트의 새 제목/제목. + - `start_time` (string, 선택사항): ISO 8601 형식의 새 시작 시간 (예: "2024-01-20T10:00:00"). 필수: 이 필드 사용 시 start_timezone도 제공해야 합니다. + - `start_timezone` (string, 선택사항): 시작 시간의 시간대. start_time 업데이트 시 필수. 예: "Pacific Standard Time", "Eastern Standard Time", "UTC". + - `end_time` (string, 선택사항): ISO 8601 형식의 새 종료 시간. 필수: 이 필드 사용 시 end_timezone도 제공해야 합니다. + - `end_timezone` (string, 선택사항): 종료 시간의 시간대. end_time 업데이트 시 필수. 예: "Pacific Standard Time", "Eastern Standard Time", "UTC". + - `location` (string, 선택사항): 이벤트의 새 위치. + - `body` (string, 선택사항): 이벤트의 새 본문/설명. HTML 형식 지원. + + + + + **설명:** 캘린더 이벤트를 삭제합니다. + + **매개변수:** + - `event_id` (string, 필수): 삭제할 이벤트의 고유 식별자. get_calendar_events 작업에서 얻을 수 있습니다. + + + + +## 사용 예제 + +### 기본 Microsoft Outlook 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Microsoft Outlook 기능을 가진 에이전트 생성 +outlook_agent = Agent( + role="이메일 어시스턴트", + goal="이메일, 캘린더 이벤트 및 연락처를 효율적으로 관리", + backstory="Microsoft Outlook 작업 및 커뮤니케이션 관리 전문 AI 어시스턴트.", + apps=['microsoft_outlook'] # 모든 Outlook 작업을 사용할 수 있습니다 +) + +# 이메일 보내기 작업 +send_email_task = Task( + description="'colleague@example.com'에게 제목 '프로젝트 업데이트'와 본문 '안녕하세요, 프로젝트의 최신 업데이트입니다. 감사합니다.'로 이메일을 보내세요", + agent=outlook_agent, + expected_output="colleague@example.com에게 이메일이 성공적으로 전송됨" +) + +# 작업 실행 +crew = Crew( + agents=[outlook_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +### 이메일 관리 및 검색 + +```python +from crewai import Agent, Task, Crew + +# 이메일 관리에 특화된 에이전트 생성 +email_manager = Agent( + role="이메일 관리자", + goal="이메일 메시지를 검색하고 가져와 정리", + backstory="이메일 정리 및 관리에 능숙한 AI 어시스턴트.", + apps=['microsoft_outlook/get_messages'] +) + +# 이메일 검색 및 가져오기 작업 +search_emails_task = Task( + description="최신 읽지 않은 이메일 20건을 가져와 가장 중요한 것들의 요약을 제공하세요.", + agent=email_manager, + expected_output="주요 읽지 않은 이메일의 요약과 핵심 세부 정보." +) + +crew = Crew( + agents=[email_manager], + tasks=[search_emails_task] +) + +crew.kickoff() +``` + +### 캘린더 및 연락처 관리 + +```python +from crewai import Agent, Task, Crew + +# 캘린더 및 연락처 관리를 위한 에이전트 생성 +scheduler = Agent( + role="캘린더 및 연락처 관리자", + goal="캘린더 이벤트를 관리하고 연락처 정보를 유지", + backstory="일정 관리 및 연락처 정리를 담당하는 AI 어시스턴트.", + apps=['microsoft_outlook/create_calendar_event', 'microsoft_outlook/get_calendar_events', 'microsoft_outlook/create_contact'] +) + +# 회의 생성 및 연락처 추가 작업 +schedule_task = Task( + description="내일 오후 2시 '팀 회의' 제목으로 '회의실 A' 장소의 캘린더 이벤트를 만들고, 'john.smith@example.com' 이메일과 '프로젝트 매니저' 직책으로 'John Smith'의 새 연락처를 추가하세요.", + agent=scheduler, + expected_output="캘린더 이벤트가 생성되고 새 연락처가 추가됨." +) + +crew = Crew( + agents=[scheduler], + tasks=[schedule_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Microsoft 계정이 이메일, 캘린더 및 연락처 액세스에 필요한 권한을 가지고 있는지 확인하세요. +- 필요한 범위: `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`. +- OAuth 연결에 필요한 모든 범위가 포함되어 있는지 확인하세요. + +**이메일 보내기 문제** + +- `send_email`에 `to_recipients`, `subject`, `body`가 제공되는지 확인하세요. +- 이메일 주소가 올바르게 형식화되어 있는지 확인하세요. +- 계정에 `Mail.Send` 권한이 있는지 확인하세요. + +**캘린더 이벤트 생성** + +- `subject`, `start_datetime`, `end_datetime`이 제공되는지 확인하세요. +- 날짜/시간 필드에 적절한 ISO 8601 형식을 사용하세요 (예: '2024-01-20T10:00:00'). +- 이벤트가 잘못된 시간에 표시되는 경우 시간대 설정을 확인하세요. + +**연락처 관리** + +- `create_contact`의 경우 필수인 `displayName`이 제공되는지 확인하세요. +- `emailAddresses`를 제공할 때 `address`와 `name` 속성이 있는 올바른 객체 형식을 사용하세요. + +**검색 및 필터 문제** + +- `filter` 매개변수에 올바른 OData 문법을 사용하세요. +- 날짜 필터의 경우 ISO 8601 형식을 사용하세요 (예: "receivedDateTime ge '2024-01-01T00:00:00Z'"). + +### 도움 받기 + + + Microsoft Outlook 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/microsoft_sharepoint.mdx b/docs/v1.15.1/ko/enterprise/integrations/microsoft_sharepoint.mdx new file mode 100644 index 000000000..25f69db7a --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/microsoft_sharepoint.mdx @@ -0,0 +1,528 @@ +--- +title: Microsoft SharePoint 통합 +description: "CrewAI를 위한 Microsoft SharePoint 통합으로 사이트, 목록 및 문서 관리." +icon: "folder-tree" +mode: "wide" +--- + +## 개요 + +에이전트가 SharePoint 사이트, 목록 및 문서 라이브러리에 액세스하고 관리할 수 있도록 합니다. AI 기반 자동화로 사이트 정보를 검색하고, 목록 항목을 관리하고, 파일을 업로드 및 구성하며, SharePoint 워크플로를 간소화합니다. + +## 전제 조건 + +Microsoft SharePoint 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- SharePoint 액세스 권한이 있는 Microsoft 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결 + +## Microsoft SharePoint 통합 설정 + +### 1. Microsoft 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Microsoft SharePoint** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. SharePoint 사이트 및 파일 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** 사용자가 액세스할 수 있는 모든 SharePoint 사이트를 가져옵니다. + + **매개변수:** + - `search` (string, 선택사항): 사이트를 필터링하기 위한 검색 쿼리. + - `select` (string, 선택사항): 반환할 특정 속성 선택 (예: 'displayName,id,webUrl'). + - `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링. + - `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장. + - `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999). + - `skip` (integer, 선택사항): 건너뛸 항목 수 (최소 0). + - `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬 (예: 'displayName desc'). + + + + + **설명:** 특정 SharePoint 사이트에 대한 정보를 가져옵니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `select` (string, 선택사항): 반환할 특정 속성 선택 (예: 'displayName,id,webUrl,drives'). + - `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장 (예: 'drives,lists'). + + + + + **설명:** SharePoint 사이트의 모든 문서 라이브러리(드라이브)를 나열합니다. 파일 작업을 사용하기 전에 사용 가능한 라이브러리를 찾으려면 이 작업을 사용하세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `top` (integer, 선택사항): 페이지당 반환할 최대 드라이브 수 (1-999). 기본값: 100 + - `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰. + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'id,name,webUrl,driveType'). + + + + + **설명:** SharePoint 사이트의 모든 목록을 가져옵니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + + + + + **설명:** 특정 목록에 대한 정보를 가져옵니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `list_id` (string, 필수): 목록의 ID. + + + + + **설명:** SharePoint 목록에서 항목을 가져옵니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `list_id` (string, 필수): 목록의 ID. + - `expand` (string, 선택사항): 관련 데이터 확장 (예: 'fields'). + + + + + **설명:** SharePoint 목록에 새 항목을 만듭니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `list_id` (string, 필수): 목록의 ID. + - `fields` (object, 필수): 새 항목의 필드 값. + + + + + **설명:** SharePoint 목록의 항목을 업데이트합니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `list_id` (string, 필수): 목록의 ID. + - `item_id` (string, 필수): 업데이트할 항목의 ID. + - `fields` (object, 필수): 업데이트할 필드 값. + + + + + **설명:** SharePoint 목록에서 항목을 삭제합니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `list_id` (string, 필수): 목록의 ID. + - `item_id` (string, 필수): 삭제할 항목의 ID. + + + + + **설명:** SharePoint 문서 라이브러리에 파일을 업로드합니다. + + **매개변수:** + - `site_id` (string, 필수): SharePoint 사이트의 ID. + - `file_path` (string, 필수): 파일을 업로드할 경로 (예: 'folder/fileName.txt'). + - `content` (string, 필수): 업로드할 파일의 내용. + + + + + **설명:** SharePoint 문서 라이브러리에서 파일과 폴더를 가져옵니다. 기본적으로 루트 폴더를 나열하지만 folder_id를 제공하여 하위 폴더로 이동할 수 있습니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `folder_id` (string, 선택사항): 내용을 나열할 폴더의 ID. 루트 폴더의 경우 'root'를 사용하거나 이전 list_files 호출에서 가져온 폴더 ID를 제공하세요. 기본값: 'root' + - `top` (integer, 선택사항): 페이지당 반환할 최대 항목 수 (1-1000). 기본값: 50 + - `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰. + - `orderby` (string, 선택사항): 결과 정렬 순서 (예: 'name asc', 'size desc', 'lastModifiedDateTime desc'). 기본값: 'name asc' + - `filter` (string, 선택사항): 결과를 좁히기 위한 OData 필터 (예: 'file ne null'은 파일만, 'folder ne null'은 폴더만). + - `select` (string, 선택사항): 반환할 필드의 쉼표로 구분된 목록 (예: 'id,name,size,folder,file,webUrl,lastModifiedDateTime'). + + + + + **설명:** SharePoint 문서 라이브러리에서 파일 또는 폴더를 삭제합니다. 폴더의 경우 모든 내용이 재귀적으로 삭제됩니다. 항목은 사이트 휴지통으로 이동됩니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): 삭제할 파일 또는 폴더의 고유 식별자. list_files에서 가져오세요. + + + + + **설명:** 경로로 SharePoint 문서 라이브러리 폴더의 파일과 폴더를 나열합니다. 깊은 탐색을 위해 여러 list_files 호출보다 더 효율적입니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `folder_path` (string, 필수): 앞뒤 슬래시 없이 폴더의 전체 경로 (예: 'Documents', 'Reports/2024/Q1'). + - `top` (integer, 선택사항): 페이지당 반환할 최대 항목 수 (1-1000). 기본값: 50 + - `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰. + - `orderby` (string, 선택사항): 결과 정렬 순서 (예: 'name asc', 'size desc'). 기본값: 'name asc' + - `select` (string, 선택사항): 반환할 필드의 쉼표로 구분된 목록 (예: 'id,name,size,folder,file,webUrl,lastModifiedDateTime'). + + + + + **설명:** SharePoint 문서 라이브러리에서 원시 파일 내용을 다운로드합니다. 일반 텍스트 파일(.txt, .csv, .json)에만 사용하세요. Excel 파일의 경우 Excel 전용 작업을 사용하세요. Word 파일의 경우 get_word_document_content를 사용하세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): 다운로드할 파일의 고유 식별자. list_files 또는 list_files_by_path에서 가져오세요. + + + + + **설명:** SharePoint 문서 라이브러리의 특정 파일 또는 폴더에 대한 자세한 메타데이터를 가져옵니다. 이름, 크기, 생성/수정 날짜 및 작성자 정보가 포함됩니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): 파일 또는 폴더의 고유 식별자. list_files 또는 list_files_by_path에서 가져오세요. + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'id,name,size,createdDateTime,lastModifiedDateTime,webUrl,createdBy,lastModifiedBy'). + + + + + **설명:** SharePoint 문서 라이브러리에 새 폴더를 만듭니다. 기본적으로 루트에 폴더를 만들며 하위 폴더를 만들려면 parent_id를 사용하세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `folder_name` (string, 필수): 새 폴더의 이름. 사용할 수 없는 문자: \ / : * ? " < > | + - `parent_id` (string, 선택사항): 상위 폴더의 ID. 문서 라이브러리 루트의 경우 'root'를 사용하거나 list_files에서 가져온 폴더 ID를 제공하세요. 기본값: 'root' + + + + + **설명:** 키워드로 SharePoint 문서 라이브러리에서 파일과 폴더를 검색합니다. 파일 이름, 폴더 이름 및 Office 문서의 파일 내용을 검색합니다. 와일드카드나 특수 문자를 사용하지 마세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `query` (string, 필수): 검색 키워드 (예: 'report', 'budget 2024'). *.txt와 같은 와일드카드는 지원되지 않습니다. + - `top` (integer, 선택사항): 페이지당 반환할 최대 결과 수 (1-1000). 기본값: 50 + - `skip_token` (string, 선택사항): 다음 결과 페이지를 가져오기 위한 이전 응답의 페이지네이션 토큰. + - `select` (string, 선택사항): 반환할 필드의 쉼표로 구분된 목록 (예: 'id,name,size,folder,file,webUrl,lastModifiedDateTime'). + + + + + **설명:** SharePoint 내에서 파일 또는 폴더를 새 위치로 복사합니다. 원본 항목은 변경되지 않습니다. 대용량 파일의 경우 복사 작업은 비동기적입니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): 복사할 파일 또는 폴더의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `destination_folder_id` (string, 필수): 대상 폴더의 ID. 루트 폴더의 경우 'root'를 사용하거나 list_files에서 가져온 폴더 ID를 사용하세요. + - `new_name` (string, 선택사항): 복사본의 새 이름. 제공하지 않으면 원래 이름이 사용됩니다. + + + + + **설명:** SharePoint 내에서 파일 또는 폴더를 새 위치로 이동합니다. 항목은 원래 위치에서 제거됩니다. 폴더의 경우 모든 내용도 함께 이동됩니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): 이동할 파일 또는 폴더의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `destination_folder_id` (string, 필수): 대상 폴더의 ID. 루트 폴더의 경우 'root'를 사용하거나 list_files에서 가져온 폴더 ID를 사용하세요. + - `new_name` (string, 선택사항): 이동된 항목의 새 이름. 제공하지 않으면 원래 이름이 유지됩니다. + + + + + **설명:** SharePoint 문서 라이브러리에 저장된 Excel 통합 문서의 모든 워크시트(탭)를 나열합니다. 반환된 워크시트 이름을 다른 Excel 작업에 사용하세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'id,name,position,visibility'). + - `filter` (string, 선택사항): OData 필터 표현식 (예: "visibility eq 'Visible'"로 숨겨진 시트 제외). + - `top` (integer, 선택사항): 반환할 최대 워크시트 수. 최소: 1, 최대: 999 + - `orderby` (string, 선택사항): 정렬 순서 (예: 'position asc'로 탭 순서대로 반환). + + + + + **설명:** SharePoint 문서 라이브러리에 저장된 Excel 통합 문서에 새 워크시트(탭)를 만듭니다. 새 시트는 탭 목록의 끝에 추가됩니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `name` (string, 필수): 새 워크시트의 이름. 최대 31자. 사용할 수 없는 문자: \ / * ? : [ ]. 통합 문서 내에서 고유해야 합니다. + + + + + **설명:** SharePoint에 저장된 Excel 워크시트의 특정 범위에서 셀 값을 가져옵니다. 크기를 모르는 상태에서 모든 데이터를 읽으려면 대신 get_excel_used_range를 사용하세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 읽을 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다. + - `range` (string, 필수): A1 표기법의 셀 범위 (예: 'A1:C10', 'A:C', '1:5', 'A1'). + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text'). + + + + + **설명:** SharePoint에 저장된 Excel 워크시트의 특정 범위에 값을 씁니다. 기존 셀 내용을 덮어씁니다. values 배열의 크기는 범위 크기와 정확히 일치해야 합니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 업데이트할 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다. + - `range` (string, 필수): 값을 쓸 A1 표기법의 셀 범위 (예: 'A1:C3'은 3x3 블록). + - `values` (array, 필수): 2D 값 배열 (셀을 포함하는 행). A1:B2의 예: [["Header1", "Header2"], ["Value1", "Value2"]]. 셀을 지우려면 null을 사용하세요. + + + + + **설명:** 실제 셀 값 없이 워크시트에서 사용된 범위의 메타데이터(주소 및 크기)만 반환합니다. 대용량 파일에서 데이터를 청크로 읽기 전에 스프레드시트 크기를 파악하는 데 이상적입니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 읽을 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다. + + + + + **설명:** SharePoint에 저장된 워크시트에서 데이터가 포함된 모든 셀을 가져옵니다. 2MB보다 큰 파일에는 사용하지 마세요. 대용량 파일의 경우 먼저 get_excel_used_range_metadata를 사용한 다음 get_excel_range_data로 작은 청크로 읽으세요. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 읽을 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다. + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text,rowCount,columnCount'). + + + + + **설명:** SharePoint의 Excel 파일에서 행과 열 인덱스로 단일 셀의 값을 가져옵니다. 인덱스는 0 기반입니다 (행 0 = Excel 행 1, 열 0 = 열 A). + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 워크시트(탭)의 이름. get_excel_worksheets에서 가져오세요. 대소문자를 구분합니다. + - `row` (integer, 필수): 0 기반 행 인덱스 (행 0 = Excel 행 1). 유효 범위: 0-1048575 + - `column` (integer, 필수): 0 기반 열 인덱스 (열 0 = A, 열 1 = B). 유효 범위: 0-16383 + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text'). + + + + + **설명:** 셀 범위를 필터링, 정렬 및 구조화된 데이터 기능이 있는 서식이 지정된 Excel 테이블로 변환합니다. 테이블을 만들면 add_excel_table_row로 데이터를 추가할 수 있습니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 데이터 범위가 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요. + - `range` (string, 필수): 헤더와 데이터를 포함하여 테이블로 변환할 셀 범위 (예: 'A1:D10'에서 A1:D1은 열 헤더). + - `has_headers` (boolean, 선택사항): 첫 번째 행에 열 헤더가 포함되어 있으면 true로 설정. 기본값: true + + + + + **설명:** SharePoint에 저장된 특정 Excel 워크시트의 모든 테이블을 나열합니다. id, name, showHeaders 및 showTotals를 포함한 테이블 속성을 반환합니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 테이블을 가져올 워크시트의 이름. get_excel_worksheets에서 가져오세요. + + + + + **설명:** SharePoint 파일의 Excel 테이블 끝에 새 행을 추가합니다. values 배열은 테이블의 열 수와 같은 수의 요소를 가져야 합니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 테이블이 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요. + - `table_name` (string, 필수): 행을 추가할 테이블의 이름 (예: 'Table1'). get_excel_tables에서 가져오세요. 대소문자를 구분합니다. + - `values` (array, 필수): 새 행의 셀 값 배열로 테이블 순서대로 열당 하나씩 (예: ["John Doe", "john@example.com", 25]). + + + + + **설명:** SharePoint 파일의 Excel 테이블에서 모든 행을 데이터 범위로 가져옵니다. 정확한 범위를 알 필요가 없으므로 구조화된 테이블 작업 시 get_excel_range_data보다 쉽습니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 테이블이 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요. + - `table_name` (string, 필수): 데이터를 가져올 테이블의 이름 (예: 'Table1'). get_excel_tables에서 가져오세요. 대소문자를 구분합니다. + - `select` (string, 선택사항): 반환할 속성의 쉼표로 구분된 목록 (예: 'address,values,formulas,numberFormat,text'). + + + + + **설명:** SharePoint에 저장된 Excel 워크시트에 데이터 범위에서 차트 시각화를 만듭니다. 차트는 워크시트에 포함됩니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 차트를 만들 워크시트의 이름. get_excel_worksheets에서 가져오세요. + - `chart_type` (string, 필수): 차트 유형 (예: 'ColumnClustered', 'ColumnStacked', 'Line', 'LineMarkers', 'Pie', 'Bar', 'BarClustered', 'Area', 'Scatter', 'Doughnut'). + - `source_data` (string, 필수): 헤더를 포함한 A1 표기법의 차트 데이터 범위 (예: 'A1:B10'). + - `series_by` (string, 선택사항): 데이터 계열 구성 방법: 'Auto', 'Columns' 또는 'Rows'. 기본값: 'Auto' + + + + + **설명:** SharePoint에 저장된 Excel 워크시트에 포함된 모든 차트를 나열합니다. id, name, chartType, height, width 및 position을 포함한 차트 속성을 반환합니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 차트를 나열할 워크시트의 이름. get_excel_worksheets에서 가져오세요. + + + + + **설명:** SharePoint에 저장된 Excel 통합 문서에서 워크시트(탭)와 모든 내용을 영구적으로 제거합니다. 실행 취소할 수 없습니다. 통합 문서에는 최소 하나의 워크시트가 있어야 합니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 삭제할 워크시트의 이름. 대소문자를 구분합니다. 이 시트의 모든 데이터, 테이블 및 차트가 영구적으로 제거됩니다. + + + + + **설명:** SharePoint의 Excel 워크시트에서 테이블을 제거합니다. 테이블 구조(필터링, 서식, 테이블 기능)는 삭제되지만 기본 셀 데이터는 보존됩니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + - `worksheet_name` (string, 필수): 테이블이 포함된 워크시트의 이름. get_excel_worksheets에서 가져오세요. + - `table_name` (string, 필수): 삭제할 테이블의 이름 (예: 'Table1'). get_excel_tables에서 가져오세요. 테이블 삭제 후에도 셀의 데이터는 유지됩니다. + + + + + **설명:** SharePoint에 저장된 Excel 통합 문서에 정의된 모든 명명된 범위를 가져옵니다. 명명된 범위는 셀 범위에 대한 사용자 정의 레이블입니다 (예: 'SalesData'는 A1:D100을 가리킴). + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Excel 파일의 고유 식별자. list_files 또는 search_files에서 가져오세요. + + + + + **설명:** SharePoint 문서 라이브러리에 저장된 Word 문서(.docx)에서 텍스트 내용을 다운로드하고 추출합니다. SharePoint에서 Word 문서를 읽는 권장 방법입니다. + + **매개변수:** + - `site_id` (string, 필수): get_sites에서 가져온 전체 SharePoint 사이트 식별자. + - `drive_id` (string, 필수): 문서 라이브러리의 ID. 먼저 get_drives를 호출하여 유효한 드라이브 ID를 가져오세요. + - `item_id` (string, 필수): SharePoint에 있는 Word 문서(.docx)의 고유 식별자. list_files 또는 search_files에서 가져오세요. + + + + +## 사용 예제 + +### 기본 Microsoft SharePoint 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Microsoft SharePoint 기능을 가진 에이전트 생성 +sharepoint_agent = Agent( + role="SharePoint 관리자", + goal="SharePoint 사이트, 목록 및 문서를 효율적으로 관리", + backstory="Microsoft SharePoint 관리 및 콘텐츠 관리 전문 AI 어시스턴트.", + apps=['microsoft_sharepoint'] # 모든 SharePoint 작업을 사용할 수 있습니다 +) + +# 모든 사이트 가져오기 작업 +get_sites_task = Task( + description="액세스할 수 있는 모든 SharePoint 사이트를 나열하세요.", + agent=sharepoint_agent, + expected_output="표시 이름과 URL이 포함된 SharePoint 사이트 목록." +) + +# 작업 실행 +crew = Crew( + agents=[sharepoint_agent], + tasks=[get_sites_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Microsoft 계정이 SharePoint 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Sites.Read.All`, `Sites.ReadWrite.All`). +- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요. + +**사이트/목록/항목 ID 문제** + +- 사이트, 목록, 항목 ID가 올바른지 다시 확인하세요. +- 참조된 리소스가 존재하고 액세스할 수 있는지 확인하세요. + +### 도움 받기 + + + Microsoft SharePoint 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 + 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/microsoft_teams.mdx b/docs/v1.15.1/ko/enterprise/integrations/microsoft_teams.mdx new file mode 100644 index 000000000..8a66f23e0 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/microsoft_teams.mdx @@ -0,0 +1,326 @@ +--- +title: Microsoft Teams 통합 +description: "CrewAI를 위한 Microsoft Teams 통합으로 팀 협업 및 커뮤니케이션." +icon: "users" +mode: "wide" +--- + +## 개요 + +에이전트가 Teams 데이터에 액세스하고, 메시지를 보내고, 회의를 만들고, 채널을 관리할 수 있도록 합니다. AI 기반 자동화로 팀 커뮤니케이션을 자동화하고, 회의를 예약하고, 메시지를 검색하며, 협업 워크플로를 간소화합니다. + +## 전제 조건 + +Microsoft Teams 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Teams 액세스 권한이 있는 Microsoft 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결 + +## Microsoft Teams 통합 설정 + +### 1. Microsoft 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Microsoft Teams** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. Teams 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** 사용자가 멤버인 모든 팀을 가져옵니다. + + **매개변수:** + - 매개변수가 필요하지 않습니다. + + + + + **설명:** 특정 팀의 채널을 가져옵니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 ID. + + + + + **설명:** Teams 채널에 메시지를 보냅니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 ID. + - `channel_id` (string, 필수): 채널의 ID. + - `message` (string, 필수): 메시지 내용. + - `content_type` (string, 선택사항): 콘텐츠 유형 (html 또는 text). 옵션: html, text. 기본값: text. + + + + + **설명:** Teams 채널에서 메시지를 가져옵니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 ID. + - `channel_id` (string, 필수): 채널의 ID. + - `top` (integer, 선택사항): 검색할 메시지 수 (최대 50). 기본값: 20. + + + + + **설명:** Teams 회의를 만듭니다. + + **매개변수:** + - `subject` (string, 필수): 회의 제목/제목. + - `startDateTime` (string, 필수): 회의 시작 시간 (시간대가 포함된 ISO 8601 형식). + - `endDateTime` (string, 필수): 회의 종료 시간 (시간대가 포함된 ISO 8601 형식). + + + + + **설명:** 웹 참가 URL로 온라인 회의를 검색합니다. + + **매개변수:** + - `join_web_url` (string, 필수): 검색할 회의의 웹 참가 URL. + + + + + **설명:** 외부 Meeting ID로 온라인 회의를 검색합니다. + + **매개변수:** + - `join_meeting_id` (string, 필수): 참석자가 참가할 때 사용하는 회의 ID(숫자 코드). 회의 초대에 표시되는 joinMeetingId이며, Graph API meeting id가 아닙니다. + + + + + **설명:** 특정 온라인 회의의 세부 정보를 가져옵니다. + + **매개변수:** + - `meeting_id` (string, 필수): Graph API 회의 ID(긴 영숫자 문자열). create_meeting 또는 search_online_meetings 작업에서 얻을 수 있습니다. 숫자 joinMeetingId와 다릅니다. + + + + + **설명:** 특정 팀의 멤버를 가져옵니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다. + - `top` (integer, 선택사항): 페이지당 검색할 멤버 수 (1-999). 기본값: 100. + - `skip_token` (string, 선택사항): 이전 응답의 페이지네이션 토큰. 응답에 @odata.nextLink가 포함된 경우 $skiptoken 매개변수 값을 추출하여 여기에 전달하면 다음 페이지 결과를 가져올 수 있습니다. + + + + + **설명:** 팀에 새 채널을 만듭니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다. + - `display_name` (string, 필수): Teams에 표시되는 채널 이름. 팀 내에서 고유해야 합니다. 최대 50자. + - `description` (string, 선택사항): 채널 목적을 설명하는 선택적 설명. 채널 세부 정보에 표시됩니다. 최대 1024자. + - `membership_type` (string, 선택사항): 채널 가시성. 옵션: standard, private. "standard" = 모든 팀 멤버에게 표시, "private" = 명시적으로 추가된 멤버에게만 표시. 기본값: standard. + + + + + **설명:** 채널의 특정 메시지에 대한 회신을 가져옵니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다. + - `channel_id` (string, 필수): 채널의 고유 식별자. get_channels 작업에서 얻을 수 있습니다. + - `message_id` (string, 필수): 상위 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + - `top` (integer, 선택사항): 페이지당 검색할 회신 수 (1-50). 기본값: 50. + - `skip_token` (string, 선택사항): 이전 응답의 페이지네이션 토큰. 응답에 @odata.nextLink가 포함된 경우 $skiptoken 매개변수 값을 추출하여 여기에 전달하면 다음 페이지 결과를 가져올 수 있습니다. + + + + + **설명:** Teams 채널의 메시지에 회신합니다. + + **매개변수:** + - `team_id` (string, 필수): 팀의 고유 식별자. get_teams 작업에서 얻을 수 있습니다. + - `channel_id` (string, 필수): 채널의 고유 식별자. get_channels 작업에서 얻을 수 있습니다. + - `message_id` (string, 필수): 회신할 메시지의 고유 식별자. get_messages 작업에서 얻을 수 있습니다. + - `message` (string, 필수): 회신 내용. HTML의 경우 서식 태그 포함. 텍스트의 경우 일반 텍스트만. + - `content_type` (string, 선택사항): 콘텐츠 형식. 옵션: html, text. "text"는 일반 텍스트, "html"은 서식이 있는 리치 텍스트. 기본값: text. + + + + + **설명:** 기존 온라인 회의를 업데이트합니다. + + **매개변수:** + - `meeting_id` (string, 필수): 회의의 고유 식별자. create_meeting 또는 search_online_meetings 작업에서 얻을 수 있습니다. + - `subject` (string, 선택사항): 새 회의 제목. + - `startDateTime` (string, 선택사항): 시간대가 포함된 ISO 8601 형식의 새 시작 시간. 예: "2024-01-20T10:00:00-08:00". + - `endDateTime` (string, 선택사항): 시간대가 포함된 ISO 8601 형식의 새 종료 시간. + + + + + **설명:** 온라인 회의를 삭제합니다. + + **매개변수:** + - `meeting_id` (string, 필수): 삭제할 회의의 고유 식별자. create_meeting 또는 search_online_meetings 작업에서 얻을 수 있습니다. + + + + +## 사용 예제 + +### 기본 Microsoft Teams 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Microsoft Teams 기능을 가진 에이전트 생성 +teams_agent = Agent( + role="Teams 코디네이터", + goal="Teams 커뮤니케이션 및 회의를 효율적으로 관리", + backstory="Microsoft Teams 작업 및 팀 협업 전문 AI 어시스턴트.", + apps=['microsoft_teams'] # 모든 Teams 작업을 사용할 수 있습니다 +) + +# 팀 및 채널 탐색 작업 +explore_teams_task = Task( + description="내가 멤버인 모든 팀을 나열한 다음 첫 번째 팀의 채널을 가져오세요.", + agent=teams_agent, + expected_output="팀 및 채널 목록이 표시됨." +) + +# 작업 실행 +crew = Crew( + agents=[teams_agent], + tasks=[explore_teams_task] +) + +crew.kickoff() +``` + +### 메시징 및 커뮤니케이션 + +```python +from crewai import Agent, Task, Crew + +# 메시징에 특화된 에이전트 생성 +messenger = Agent( + role="Teams 메신저", + goal="Teams 채널에서 메시지 전송 및 검색", + backstory="팀 커뮤니케이션 및 메시지 관리에 능숙한 AI 어시스턴트.", + apps=['microsoft_teams/send_message', 'microsoft_teams/get_messages'] +) + +# 메시지 전송 및 최근 메시지 검색 작업 +messaging_task = Task( + description="'your_team_id' 팀의 General 채널에 'Hello team! This is an automated update from our AI assistant.' 메시지를 보낸 다음 해당 채널의 최근 10개 메시지를 검색하세요.", + agent=messenger, + expected_output="메시지가 성공적으로 전송되고 최근 메시지가 검색됨." +) + +crew = Crew( + agents=[messenger], + tasks=[messaging_task] +) + +crew.kickoff() +``` + +### 회의 관리 + +```python +from crewai import Agent, Task, Crew + +# 회의 관리를 위한 에이전트 생성 +meeting_scheduler = Agent( + role="회의 스케줄러", + goal="Teams 회의 생성 및 관리", + backstory="회의 일정 관리 및 정리를 담당하는 AI 어시스턴트.", + apps=['microsoft_teams/create_meeting', 'microsoft_teams/search_online_meetings_by_join_url'] +) + +# 회의 생성 작업 +schedule_meeting_task = Task( + description="내일 오전 10시에 1시간 동안 진행되는 '주간 팀 동기화' 제목의 Teams 회의를 생성하세요 (시간대가 포함된 적절한 ISO 8601 형식 사용).", + agent=meeting_scheduler, + expected_output="회의 세부 정보와 함께 Teams 회의가 성공적으로 생성됨." +) + +crew = Crew( + agents=[meeting_scheduler], + tasks=[schedule_meeting_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Microsoft 계정이 Teams 액세스에 필요한 권한을 가지고 있는지 확인하세요. +- 필요한 범위: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `OnlineMeetings.ReadWrite`, `OnlineMeetings.Read`. +- OAuth 연결에 필요한 모든 범위가 포함되어 있는지 확인하세요. + +**팀 및 채널 액세스** + +- 액세스하려는 팀의 멤버인지 확인하세요. +- 팀 및 채널 ID가 올바른지 다시 확인하세요. +- 팀 및 채널 ID는 `get_teams` 및 `get_channels` 작업을 사용하여 얻을 수 있습니다. + +**메시지 전송 문제** + +- `send_message`에 `team_id`, `channel_id`, `message`가 제공되는지 확인하세요. +- 지정된 채널에 메시지를 보낼 권한이 있는지 확인하세요. +- 메시지 형식에 따라 적절한 `content_type`(text 또는 html)을 선택하세요. + +**회의 생성** + +- `subject`, `startDateTime`, `endDateTime`이 제공되는지 확인하세요. +- 날짜/시간 필드에 시간대가 포함된 적절한 ISO 8601 형식을 사용하세요 (예: '2024-01-20T10:00:00-08:00'). +- 회의 시간이 미래인지 확인하세요. + +**메시지 검색 제한** + +- `get_messages` 작업은 요청당 최대 50개 메시지만 검색할 수 있습니다. +- 메시지는 역시간순(최신순)으로 반환됩니다. + +**회의 검색** + +- `search_online_meetings_by_join_url`의 경우 참가 URL이 정확하고 올바르게 형식화되어 있는지 확인하세요. +- URL은 완전한 Teams 회의 참가 URL이어야 합니다. + +### 도움 받기 + + + Microsoft Teams 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/microsoft_word.mdx b/docs/v1.15.1/ko/enterprise/integrations/microsoft_word.mdx new file mode 100644 index 000000000..2c8d980a3 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/microsoft_word.mdx @@ -0,0 +1,176 @@ +--- +title: Microsoft Word 통합 +description: "CrewAI를 위한 Microsoft Word 통합으로 문서 생성 및 관리." +icon: "file-word" +mode: "wide" +--- + +## 개요 + +에이전트가 OneDrive 또는 SharePoint에서 Word 문서와 텍스트 파일을 생성, 읽기 및 관리할 수 있도록 합니다. AI 기반 자동화로 문서 생성을 자동화하고, 콘텐츠를 검색하고, 문서 속성을 관리하며, 문서 워크플로를 간소화합니다. + +## 전제 조건 + +Microsoft Word 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Word 및 OneDrive/SharePoint 액세스 권한이 있는 Microsoft 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Microsoft 계정 연결 + +## Microsoft Word 통합 설정 + +### 1. Microsoft 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동 +2. 인증 통합 섹션에서 **Microsoft Word** 찾기 +3. **연결**을 클릭하고 OAuth 플로우 완료 +4. 파일 액세스에 필요한 권한 부여 +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token 복사 + +### 2. 필요한 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 작업 + + + + **설명:** OneDrive 또는 SharePoint에서 모든 Word 문서를 가져옵니다. + + **매개변수:** + - `select` (string, 선택사항): 반환할 특정 속성 선택. + - `filter` (string, 선택사항): OData 구문을 사용하여 결과 필터링. + - `expand` (string, 선택사항): 관련 리소스를 인라인으로 확장. + - `top` (integer, 선택사항): 반환할 항목 수 (최소 1, 최대 999). + - `orderby` (string, 선택사항): 지정된 속성으로 결과 정렬. + + + + + **설명:** 내용이 있는 텍스트 문서(.txt)를 만듭니다. 읽기 가능하고 편집 가능해야 하는 프로그래밍 방식 콘텐츠 생성에 권장됩니다. + + **매개변수:** + - `file_name` (string, 필수): 텍스트 문서의 이름 (.txt로 끝나야 함). + - `content` (string, 선택사항): 문서의 텍스트 내용. 기본값: "API를 통해 생성된 새 텍스트 문서입니다." + + + + + **설명:** 문서의 내용을 가져옵니다 (텍스트 파일에서 가장 잘 작동). + + **매개변수:** + - `file_id` (string, 필수): 문서의 ID. + + + + + **설명:** 문서의 속성과 메타데이터를 가져옵니다. + + **매개변수:** + - `file_id` (string, 필수): 문서의 ID. + + + + + **설명:** 문서를 삭제합니다. + + **매개변수:** + - `file_id` (string, 필수): 삭제할 문서의 ID. + + + + + **설명:** OneDrive의 새 위치에 문서를 복사합니다. + + **매개변수:** + - `file_id` (string, 필수): 복사할 문서의 ID. + - `name` (string, 선택사항): 복사된 문서의 새 이름. + - `parent_id` (string, 선택사항): 대상 폴더의 ID (기본값: 루트). + + + + + **설명:** OneDrive의 새 위치로 문서를 이동합니다. + + **매개변수:** + - `file_id` (string, 필수): 이동할 문서의 ID. + - `parent_id` (string, 필수): 대상 폴더의 ID. + - `name` (string, 선택사항): 이동된 문서의 새 이름. + + + + +## 사용 예제 + +### 기본 Microsoft Word 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Microsoft Word 기능을 가진 에이전트 생성 +word_agent = Agent( + role="문서 관리자", + goal="Word 문서와 텍스트 파일을 효율적으로 관리", + backstory="Microsoft Word 문서 작업 및 콘텐츠 관리 전문 AI 어시스턴트.", + apps=['microsoft_word'] # 모든 Word 작업을 사용할 수 있습니다 +) + +# 새 텍스트 문서 생성 작업 +create_doc_task = Task( + description="'회의노트.txt'라는 새 텍스트 문서를 만들고 내용은 '2024년 1월 회의 노트: 주요 토론 사항 및 실행 항목.'으로 하세요", + agent=word_agent, + expected_output="새 텍스트 문서 '회의노트.txt'가 성공적으로 생성됨." +) + +# 작업 실행 +crew = Crew( + agents=[word_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**인증 오류** + +- Microsoft 계정이 파일 액세스에 필요한 권한을 가지고 있는지 확인하세요 (예: `Files.Read.All`, `Files.ReadWrite.All`). +- OAuth 연결이 필요한 모든 범위를 포함하는지 확인하세요. + +**파일 생성 문제** + +- 텍스트 문서를 만들 때 `file_name`이 `.txt` 확장자로 끝나는지 확인하세요. +- 대상 위치(OneDrive/SharePoint)에 쓰기 권한이 있는지 확인하세요. + +### 도움 받기 + + + Microsoft Word 통합 설정 또는 문제 해결에 대한 지원이 필요하시면 지원팀에 + 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/notion.mdx b/docs/v1.15.1/ko/enterprise/integrations/notion.mdx new file mode 100644 index 000000000..7015789da --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/notion.mdx @@ -0,0 +1,520 @@ +--- +title: Notion 연동 +description: "CrewAI를 위한 Notion 연동을 통한 페이지 및 데이터베이스 관리." +icon: "book" +mode: "wide" +--- + +## 개요 + +에이전트가 Notion을 통해 페이지, 데이터베이스, 콘텐츠를 관리할 수 있도록 지원합니다. 페이지 생성 및 업데이트, 콘텐츠 블록 관리, 지식 베이스 구성, AI 기반 자동화를 통해 문서화 작업 흐름을 효율화할 수 있습니다. + +## 필수 조건 + +Notion 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 워크스페이스 권한이 있는 Notion 계정 +- [통합 페이지](https://app.crewai.com/crewai_plus/connectors)를 통해 Notion 계정을 연결함 + +## Notion 연동 설정 + +### 1. Notion 계정 연결하기 + +1. [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)로 이동합니다. +2. 인증 통합(Auhtentication Integrations) 섹션에서 **Notion**을(를) 찾습니다. +3. **Connect**를 클릭하고 OAuth 플로우를 완료합니다. +4. 페이지 및 데이터베이스 관리를 위한 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 액션 + + + + **설명:** Notion에서 페이지를 생성합니다. + + **파라미터:** + - `parent` (object, 필수): 상위 - 새 페이지가 삽입될 상위 페이지 또는 데이터베이스를 나타내는 JSON 객체로, page_id 또는 database_id 키를 포함합니다. + ```json + { + "database_id": "DATABASE_ID" + } + ``` + - `properties` (object, 필수): 속성 - 페이지 속성의 값입니다. 상위가 데이터베이스인 경우, 스키마는 상위 데이터베이스의 속성과 일치해야 합니다. + ```json + { + "title": [ + { + "text": { + "content": "My Page" + } + } + ] + } + ``` + - `icon` (object, 필수): 아이콘 - 페이지 아이콘입니다. + ```json + { + "emoji": "🥬" + } + ``` + - `children` (object, 선택): 자식 - 페이지에 추가할 콘텐츠 블록입니다. + ```json + [ + { + "object": "block", + "type": "heading_2", + "heading_2": { + "rich_text": [ + { + "type": "text", + "text": { + "content": "Lacinato kale" + } + } + ] + } + } + ] + ``` + - `cover` (object, 선택): 표지 - 페이지 표지 이미지입니다. + ```json + { + "external": { + "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg" + } + } + ``` + + + + + **설명:** Notion에서 페이지를 업데이트합니다. + + **파라미터:** + - `pageId` (string, 필수): 페이지 ID - 업데이트할 페이지의 ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5"). + - `icon` (object, 필수): 아이콘 - 페이지 아이콘입니다. + ```json + { + "emoji": "🥬" + } + ``` + - `archived` (boolean, 선택): 보관됨 - 페이지가 보관(삭제)되었는지 여부입니다. true로 설정하면 페이지를 보관합니다. false로 설정하면 보관 해제(복원)합니다. + - `properties` (object, 선택): 속성 - 페이지에서 업데이트할 속성 값입니다. + ```json + { + "title": [ + { + "text": { + "content": "My Updated Page" + } + } + ] + } + ``` + - `cover` (object, 선택): 표지 - 페이지 표지 이미지입니다. + ```json + { + "external": { + "url": "https://upload.wikimedia.org/wikipedia/commons/6/62/Tuscankale.jpg" + } + } + ``` + + + + + **설명:** Notion에서 ID로 페이지를 가져옵니다. + + **파라미터:** + - `pageId` (string, 필수): 페이지 ID - 가져올 페이지의 ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5"). + + + + + **설명:** Notion에서 페이지를 보관합니다. + + **파라미터:** + - `pageId` (string, 필수): 페이지 ID - 보관할 페이지의 ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5"). + + + + + **설명:** 필터를 사용하여 Notion에서 페이지를 검색합니다. + + **파라미터:** + - `searchByTitleFilterSearch` (object, 선택): 불리언 정규형(OR 조건 그룹의 AND 그룹) 형태의 필터입니다. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "query", + "operator": "$stringExactlyMatches", + "value": "meeting notes" + } + ] + } + ] + } + ``` + 사용 가능한 필드: `query`, `filter.value`, `direction`, `page_size` + + + + + **설명:** Notion에서 페이지 콘텐츠(블록)를 가져옵니다. + + **파라미터:** + - `blockId` (string, 필수): 페이지 ID - 해당 블록이나 페이지의 모든 자식 블록을 순서대로 가져오기 위해 Block 또는 Page ID를 지정합니다. (예: "59833787-2cf9-4fdf-8782-e53db20768a5"). + + + + + **설명:** Notion에서 블록을 업데이트합니다. + + **파라미터:** + - `blockId` (string, 필수): 블록 ID - 업데이트할 블록의 ID를 지정합니다. (예: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6"). + - `archived` (boolean, 선택): 보관됨 - true로 설정하면 블록을 보관(삭제)합니다. false로 설정하면 보관 해제(복원)합니다. + - `paragraph` (object, 선택): 단락 콘텐츠. + ```json + { + "rich_text": [ + { + "type": "text", + "text": { + "content": "Lacinato kale", + "link": null + } + } + ], + "color": "default" + } + ``` + - `image` (object, 선택): 이미지 블록. + ```json + { + "type": "external", + "external": { + "url": "https://website.domain/images/image.png" + } + } + ``` + - `bookmark` (object, 선택): 북마크 블록. + ```json + { + "caption": [], + "url": "https://companywebsite.com" + } + ``` + - `code` (object, 선택): 코드 블록. + ```json + { + "rich_text": [ + { + "type": "text", + "text": { + "content": "const a = 3" + } + } + ], + "language": "javascript" + } + ``` + - `pdf` (object, 선택): PDF 블록. + ```json + { + "type": "external", + "external": { + "url": "https://website.domain/files/doc.pdf" + } + } + ``` + - `table` (object, 선택): 테이블 블록. + ```json + { + "table_width": 2, + "has_column_header": false, + "has_row_header": false + } + ``` + - `tableOfContent` (object, 선택): 목차 블록. + ```json + { + "color": "default" + } + ``` + - `additionalFields` (object, 선택): 추가 블록 유형. + ```json + { + "child_page": { + "title": "Lacinato kale" + }, + "child_database": { + "title": "My database" + } + } + ``` + + + + + **설명:** Notion에서 ID로 블록을 가져옵니다. + + **파라미터:** + - `blockId` (string, 필수): 블록 ID - 가져올 블록의 ID를 지정합니다. (예: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6"). + + + + + **설명:** Notion에서 블록을 삭제합니다. + + **파라미터:** + - `blockId` (string, 필수): 블록 ID - 삭제할 블록의 ID를 지정합니다. (예: "9bc30ad4-9373-46a5-84ab-0a7845ee52e6"). + + + + +## 사용 예시 + +### 기본 Notion Agent 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Notion capabilities +notion_agent = Agent( + role="Documentation Manager", + goal="Manage documentation and knowledge base in Notion efficiently", + backstory="An AI assistant specialized in content management and documentation.", + apps=['notion'] +) + +# Task to create a meeting notes page +create_notes_task = Task( + description="Create a new meeting notes page in the team database with today's date and agenda items", + agent=notion_agent, + expected_output="Meeting notes page created successfully with structured content" +) + +# Run the task +crew = Crew( + agents=[notion_agent], + tasks=[create_notes_task] +) + +crew.kickoff() +``` + +### 특정 Notion 도구 필터링 + +```python + +content_manager = Agent( + role="Content Manager", + goal="Create and manage content pages efficiently", + backstory="An AI assistant that focuses on content creation and management.", + apps=['notion'] +) + +# Task to manage content workflow +content_workflow = Task( + description="Create a new project documentation page and add structured content blocks for requirements and specifications", + agent=content_manager, + expected_output="Project documentation created with organized content sections" +) + +crew = Crew( + agents=[content_manager], + tasks=[content_workflow] +) + +crew.kickoff() +``` + +### 지식 베이스 관리 + +```python +from crewai import Agent, Task, Crew + +knowledge_curator = Agent( + role="Knowledge Curator", + goal="Curate and organize knowledge base content in Notion", + backstory="An experienced knowledge manager who organizes and maintains comprehensive documentation.", + apps=['notion'] +) + +# Task to curate knowledge base +curation_task = Task( + description=""" + 1. 새로운 제품 기능과 관련된 기존 문서 페이지를 검색합니다. + 2. 적절한 구조로 포괄적인 기능 문서 페이지를 생성합니다. + 3. 코드 예제, 이미지 및 관련 리소스에 대한 링크를 추가합니다. + 4. 기존 페이지를 업데이트하여 새 문서에 대한 교차 참조를 추가합니다. + """, + agent=knowledge_curator, + expected_output="Feature documentation created and integrated with existing knowledge base" +) + +crew = Crew( + agents=[knowledge_curator], + tasks=[curation_task] +) + +crew.kickoff() +``` + +### 콘텐츠 구조 및 구성 + +```python +from crewai import Agent, Task, Crew + +content_organizer = Agent( + role="Content Organizer", + goal="Organize and structure content blocks for optimal readability", + backstory="An AI assistant that specializes in content structure and user experience.", + apps=['notion'] +) + +# Task to organize content structure +organization_task = Task( + description=""" + 1. Get content from existing project pages + 2. Analyze the structure and identify improvement opportunities + 3. Update content blocks to use proper headings, tables, and formatting + 4. Add table of contents and improve navigation between related pages + 5. Create templates for future documentation consistency + """, + agent=content_organizer, + expected_output="Content reorganized with improved structure and navigation" +) + +crew = Crew( + agents=[content_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### 자동화된 문서화 워크플로우 + +```python +from crewai import Agent, Task, Crew + +doc_automator = Agent( + role="Documentation Automator", + goal="Automate documentation workflows and maintenance", + backstory="An AI assistant that automates repetitive documentation tasks.", + apps=['notion'] +) + +# Complex documentation automation task +automation_task = Task( + description=""" + 1. 최근 30일 이내에 업데이트되지 않은 페이지 검색 + 2. 오래된 콘텐츠 블록 검토 및 업데이트 + 3. 일관된 포맷으로 주간 팀 업데이트 페이지 생성 + 4. 프로젝트 페이지에 상태 표시기 및 진행 상황 추적 추가 + 5. 월간 문서 헬스 리포트 생성 + 6. 완료된 프로젝트 페이지를 아카이브 섹션에 정리 및 보관 + """, + agent=doc_automator, + expected_output="업데이트된 콘텐츠, 주간 리포트, 정리된 아카이브로 문서화 자동화 완료" +) + +crew = Crew( + agents=[doc_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## 문제 해결 + +### 일반적인 문제 + +**권한 오류** + +- Notion 계정이 대상 워크스페이스에 대한 편집 권한이 있는지 확인하세요 +- OAuth 연결에 Notion API에 필요한 범위가 포함되어 있는지 확인하세요 +- 페이지와 데이터베이스가 인증된 통합에 공유되어 있는지 확인하세요 + +**잘못된 페이지 및 블록 ID** + +- 페이지 ID 및 블록 ID가 올바른 UUID 형식인지 다시 확인하세요 +- 참조되는 페이지와 블록이 존재하고 접근 가능한지 확인하세요 +- 새 페이지를 생성할 때 상위 페이지 또는 데이터베이스 ID가 유효한지 검증하세요 + +**속성 스키마 문제** + +- 데이터베이스에 페이지를 생성할 때 페이지 속성이 데이터베이스 스키마와 일치하는지 확인하세요 +- 대상 데이터베이스에 대해 속성 이름과 타입이 올바른지 확인하세요 +- 페이지를 생성하거나 업데이트할 때 필수 속성이 포함되어 있는지 확인하세요 + +**콘텐츠 블록 구조** + +- 블록 콘텐츠가 Notion의 리치 텍스트 형식 사양을 따르는지 확인하세요 +- 중첩된 블록 구조가 올바르게 포맷되어 있는지 확인하세요 +- 미디어 URL이 접근 가능하며 올바른 형식인지 확인하세요 + +**검색 및 필터 문제** + +- 검색 쿼리가 올바르게 포맷되어 있고 비어 있지 않은지 확인하세요 +- 필터 공식에서 유효한 필드명을 사용하세요: `query`, `filter.value`, `direction`, `page_size` +- 복잡한 필터 조건을 만들기 전에 간단한 검색을 테스트하세요 + +**상위-하위 관계** + +- 하위 페이지를 생성하기 전에 상위 페이지 또는 데이터베이스가 존재하는지 확인하세요 +- 상위 컨테이너에 대한 적절한 권한이 있는지 확인하세요 +- 데이터베이스 스키마가 설정하려는 속성을 허용하는지 확인하세요 + +**리치 텍스트 및 미디어 콘텐츠** + +- 외부 이미지, PDF, 북마크의 URL이 접근 가능한지 확인하세요 +- 리치 텍스트 포매팅이 Notion의 API 사양을 따르는지 확인하세요 +- 코드 블록의 언어 타입이 Notion에서 지원되는지 확인하세요 + +**아카이브 및 삭제 작업** + +- 아카이브(복구 가능)와 삭제(영구적)의 차이를 이해하세요 +- 대상 콘텐츠를 아카이브 또는 삭제할 수 있는 권한이 있는지 확인하세요 +- 여러 페이지 또는 블록에 영향을 줄 수 있는 대량 작업은 신중히 진행하세요 + +### 도움 받기 + + + Notion 연동 설정 또는 문제 해결에 대해 지원팀에 문의해 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/salesforce.mdx b/docs/v1.15.1/ko/enterprise/integrations/salesforce.mdx new file mode 100644 index 000000000..972e220f3 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/salesforce.mdx @@ -0,0 +1,730 @@ +--- +title: Salesforce 통합 +description: "CrewAI를 위한 Salesforce 통합을 통한 CRM 및 영업 자동화." +icon: "salesforce" +mode: "wide" +--- + +## 개요 + +에이전트가 Salesforce를 통해 고객 관계, 영업 프로세스 및 데이터를 관리할 수 있도록 합니다. 레코드를 생성 및 업데이트하고, 리드와 기회를 관리하며, SOQL 쿼리를 실행하고, AI 기반 자동화로 CRM 워크플로를 간소화하세요. + +## 사전 준비 사항 + +Salesforce 통합을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 Salesforce 계정 +- [통합 페이지](https://app.crewai.com/integrations)를 통해 Salesforce 계정 연결 + + + Salesforce는 사용자가 연결하기 전에 **관리자가 CrewAI 패키지를 한 번 설치** + 해야 합니다. 이는 Spring '26 릴리스부터 모든 ExternalClientApp 기반 통합에 + 적용되는 Salesforce 플랫폼의 요구 사항이며, CrewAI 고유의 단계가 아닙니다. + CrewAI AMP의 Connect Salesforce 플로우가 첫 연결 시 이 과정을 안내합니다. + + +## Salesforce 통합 설정 + +### 1. Salesforce 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/unified_tools)으로 이동합니다. +2. 인증 통합 섹션에서 **Salesforce**를 찾습니다. +3. **연결**을 클릭합니다. + +이후 동작은 관리자가 조직에 CrewAI 패키지를 이미 설치했는지에 따라 달라집니다: + +- **패키지가 이미 설치된 경우:** 곧바로 Salesforce OAuth 동의 화면으로 + 이동합니다. 승인하면 연결이 완료됩니다. +- **패키지가 아직 설치되지 않은 경우:** **Install CrewAI in Salesforce** + 페이지가 표시됩니다. 아래의 일회성 설치 단계를 따른 뒤, CrewAI AMP로 + 돌아와 **연결**을 다시 클릭하세요. + +4. CRM 및 영업 관리에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +#### 일회성 관리자 설치 (Salesforce 관리자 전용) + +조직 내 누군가 **Connect Salesforce**를 처음 클릭하면, CrewAI는 CrewAI +관리형 패키지의 설치 페이지로 리디렉션합니다. Salesforce 관리자가 조직 +전체를 위해 한 번만 설치하면 됩니다. + +1. CrewAI 내 설치 페이지에서 **Install in Salesforce**를 클릭합니다. + (해당 페이지 URL을 관리자에게 공유해도 됩니다. 설치 링크는 누구든 열 수 + 있도록 동작합니다.) +2. 관리자 권한으로 Salesforce에 로그인합니다. 샌드박스 환경에서는 URL의 + `login.salesforce.com`을 `test.salesforce.com`으로 바꾼 뒤 엽니다. +3. **Install for All Users**를 선택하고, 서드파티 앱 동의 항목을 확인한 뒤 + **Install**을 클릭합니다. +4. Salesforce Setup에서 **External Client App Manager** → **CrewAI App** → + **Policies** 탭 → **Edit**로 이동하여 다음과 같이 설정합니다: + - **Permitted Users:** All users may self-authorize + - **IP Relaxation:** Relax IP restrictions + - **Refresh Token Policy:** Refresh token is valid until revoked +5. 저장합니다. +6. CrewAI AMP로 돌아가 **Connect Salesforce**를 다시 클릭합니다. 이번에는 + OAuth가 정상적으로 완료됩니다. + + + **Salesforce 관리자가 아니신가요?** 설치 페이지의 URL(또는 설치 링크 자체) + 을 Salesforce 관리자에게 전달하고 위 단계를 진행해 달라고 요청하세요. + 관리자가 완료하면 CrewAI AMP로 돌아와 **연결**을 다시 클릭하면 됩니다. + + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 도구 + +### **레코드 관리** + + + + **설명:** Salesforce에서 새로운 Contact 레코드를 생성합니다. + + **파라미터:** + - `FirstName` (string, 선택): 이름 + - `LastName` (string, 필수): 성 - 이 필드는 필수입니다 + - `accountId` (string, 선택): Account ID - 이 Contact가 소속된 Account + - `Email` (string, 선택): 이메일 주소 + - `Title` (string, 선택): 담당자의 직함(예: CEO 또는 Vice President 등) + - `Description` (string, 선택): Contact에 대한 설명 + - `additionalFields` (object, 선택): 사용자 정의 Contact 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 새로운 Lead 레코드를 생성합니다. + + **파라미터:** + - `FirstName` (string, 선택): 이름 + - `LastName` (string, 필수): 성 - 이 필드는 필수입니다 + - `Company` (string, 필수): 회사명 - 이 필드는 필수입니다 + - `Email` (string, 선택): 이메일 주소 + - `Phone` (string, 선택): 전화번호 + - `Website` (string, 선택): 웹사이트 URL + - `Title` (string, 선택): 담당자의 직함(예: CEO 또는 Vice President 등) + - `Status` (string, 선택): 리드 상태 - 리드 상태를 선택하려면 Connect Portal Workflow 설정을 사용하세요 + - `Description` (string, 선택): Lead에 대한 설명 + - `additionalFields` (object, 선택): 사용자 정의 Lead 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 새로운 Opportunity 레코드를 생성합니다. + + **파라미터:** + - `Name` (string, 필수): Opportunity 이름 - 이 필드는 필수입니다 + - `StageName` (string, 선택): Opportunity 단계 - 단계를 선택하려면 Connect Portal Workflow 설정을 사용하세요 + - `CloseDate` (string, 선택): 마감일(YYYY-MM-DD 형식) - 기본값은 현재 날짜로부터 30일 이후 + - `AccountId` (string, 선택): 이 Opportunity가 소속된 Account + - `Amount` (string, 선택): 예상 전체 판매 금액 + - `Description` (string, 선택): Opportunity에 대한 설명 + - `OwnerId` (string, 선택): 이 Opportunity를 담당하는 Salesforce 사용자 + - `NextStep` (string, 선택): Opportunity 마감을 위한 다음 작업의 설명 + - `additionalFields` (object, 선택): 사용자 정의 Opportunity 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 새로운 Task 레코드를 생성합니다. + + **파라미터:** + - `whatId` (string, 선택): 관련 ID - 이 Task가 관련된 Account 또는 Opportunity의 ID + - `whoId` (string, 선택): 이름 ID - 이 Task가 관련된 Contact 또는 Lead의 ID + - `subject` (string, 필수): 작업 제목 + - `activityDate` (string, 선택): 작업 날짜(YYYY-MM-DD 형식) + - `description` (string, 선택): Task에 대한 설명 + - `taskSubtype` (string, 필수): Task 하위 유형 - 선택 항목: task, email, listEmail, call + - `Status` (string, 선택): 상태 - 선택 항목: Not Started, In Progress, Completed + - `ownerId` (string, 선택): 담당자 ID - 이 Task를 담당하는 Salesforce 사용자 + - `callDurationInSeconds` (string, 선택): 통화 시간(초) + - `isReminderSet` (boolean, 선택): 알림 설정 여부 + - `reminderDateTime` (string, 선택): 알림 날짜/시간(ISO 형식) + - `additionalFields` (object, 선택): 사용자 정의 Task 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 새로운 Account 레코드를 생성합니다. + + **파라미터:** + - `Name` (string, 필수): Account 이름 - 이 필드는 필수입니다 + - `OwnerId` (string, 선택): 이 Account를 담당하는 Salesforce 사용자 + - `Website` (string, 선택): 웹사이트 URL + - `Phone` (string, 선택): 전화번호 + - `Description` (string, 선택): Account 설명 + - `additionalFields` (object, 선택): 사용자 정의 Account 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 모든 오브젝트 유형의 레코드를 생성합니다. + + **참고:** 이 기능은 사용자 정의 또는 알려지지 않은 오브젝트 유형의 레코드를 생성할 때 유연하게 사용할 수 있습니다. + + + + +### **레코드 업데이트** + + + + **설명:** Salesforce에서 기존 연락처(Contact) 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 레코드의 ID + - `FirstName` (string, 선택): 이름 + - `LastName` (string, 선택): 성 + - `accountId` (string, 선택): 계정 ID - 연락처가 속한 계정 + - `Email` (string, 선택): 이메일 주소 + - `Title` (string, 선택): 연락처의 직함 + - `Description` (string, 선택): 연락처에 대한 설명 + - `additionalFields` (object, 선택): 커스텀 연락처 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 기존 리드(Lead) 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 레코드의 ID + - `FirstName` (string, 선택): 이름 + - `LastName` (string, 선택): 성 + - `Company` (string, 선택): 회사명 + - `Email` (string, 선택): 이메일 주소 + - `Phone` (string, 선택): 전화번호 + - `Website` (string, 선택): 웹사이트 URL + - `Title` (string, 선택): 연락처의 직함 + - `Status` (string, 선택): 리드 상태 + - `Description` (string, 선택): 리드에 대한 설명 + - `additionalFields` (object, 선택): 커스텀 리드 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 기존 기회(Opportunity) 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 레코드의 ID + - `Name` (string, 선택): 기회명 + - `StageName` (string, 선택): 기회 단계 + - `CloseDate` (string, 선택): 마감 날짜 (YYYY-MM-DD 형식) + - `AccountId` (string, 선택): 기회가 속한 계정 + - `Amount` (string, 선택): 예상 총 판매 금액 + - `Description` (string, 선택): 기회에 대한 설명 + - `OwnerId` (string, 선택): 이 기회를 담당하는 Salesforce 사용자 + - `NextStep` (string, 선택): 기회 마감을 위한 다음 작업의 설명 + - `additionalFields` (object, 선택): 커스텀 기회 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 기존 작업(Task) 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 레코드의 ID + - `whatId` (string, 선택): 관련 ID - 이 작업이 연결된 계정 또는 기회의 ID + - `whoId` (string, 선택): 이름 ID - 이 작업이 연결된 연락처 또는 리드의 ID + - `subject` (string, 선택): 작업의 주제 + - `activityDate` (string, 선택): 활동 날짜 (YYYY-MM-DD 형식) + - `description` (string, 선택): 작업에 대한 설명 + - `Status` (string, 선택): 상태 - 옵션: Not Started, In Progress, Completed + - `ownerId` (string, 선택): 담당자 ID - 이 작업을 할당받은 Salesforce 사용자 + - `callDurationInSeconds` (string, 선택): 통화 시간(초) + - `isReminderSet` (boolean, 선택): 알림 설정 여부 + - `reminderDateTime` (string, 선택): 알림 날짜/시간 (ISO 형식) + - `additionalFields` (object, 선택): 커스텀 작업 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 기존 계정(Account) 레코드를 업데이트합니다. + + **파라미터:** + - `recordId` (string, 필수): 업데이트할 레코드의 ID + - `Name` (string, 선택): 계정 이름 + - `OwnerId` (string, 선택): 이 계정에 할당된 Salesforce 사용자 + - `Website` (string, 선택): 웹사이트 URL + - `Phone` (string, 선택): 전화번호 + - `Description` (string, 선택): 계정 설명 + - `additionalFields` (object, 선택): 커스텀 계정 필드를 위한 JSON 형식의 추가 필드 + + + + + **설명:** Salesforce에서 어떤 객체 유형이든 레코드를 업데이트합니다. + + **참고:** 이는 커스텀 또는 미확인 객체 유형의 레코드 업데이트를 위한 유연한 도구입니다. + + + + +### **레코드 조회** + + + + **설명:** ID로 Contact 레코드를 조회합니다. + + **파라미터:** + - `recordId` (string, 필수): Contact의 레코드 ID + + + + + **설명:** ID로 Lead 레코드를 조회합니다. + + **파라미터:** + - `recordId` (string, 필수): Lead의 레코드 ID + + + + + **설명:** ID로 Opportunity 레코드를 조회합니다. + + **파라미터:** + - `recordId` (string, 필수): Opportunity의 레코드 ID + + + + + **설명:** ID로 Task 레코드를 조회합니다. + + **파라미터:** + - `recordId` (string, 필수): Task의 레코드 ID + + + + + **설명:** ID로 Account 레코드를 조회합니다. + + **파라미터:** + - `recordId` (string, 필수): Account의 레코드 ID + + + + + **설명:** ID로 임의 객체 유형의 레코드를 조회합니다. + + **파라미터:** + - `recordType` (string, 필수): 레코드 유형 (예: "CustomObject__c") + - `recordId` (string, 필수): 레코드 ID + + + + +### **레코드 검색** + + + + **설명:** 고급 필터링으로 연락처(Contact) 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 필드별 연산자가 지정된 분리적 정규형(Disjunctive Normal Form)의 고급 필터 + - `sortBy` (string, 선택): 정렬 기준 필드 (예: "CreatedDate") + - `sortDirection` (string, 선택): 정렬 방향 - 옵션: ASC, DESC + - `includeAllFields` (boolean, 선택): 결과에 모든 필드를 포함 + - `paginationParameters` (object, 선택): pageCursor를 포함한 페이지네이션 설정 + + + + + **설명:** 고급 필터링으로 리드(Lead) 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 필드별 연산자가 지정된 분리적 정규형의 고급 필터 + - `sortBy` (string, 선택): 정렬 기준 필드 (예: "CreatedDate") + - `sortDirection` (string, 선택): 정렬 방향 - 옵션: ASC, DESC + - `includeAllFields` (boolean, 선택): 결과에 모든 필드를 포함 + - `paginationParameters` (object, 선택): pageCursor를 포함한 페이지네이션 설정 + + + + + **설명:** 고급 필터링으로 기회(Opportunity) 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 필드별 연산자가 지정된 분리적 정규형의 고급 필터 + - `sortBy` (string, 선택): 정렬 기준 필드 (예: "CreatedDate") + - `sortDirection` (string, 선택): 정렬 방향 - 옵션: ASC, DESC + - `includeAllFields` (boolean, 선택): 결과에 모든 필드를 포함 + - `paginationParameters` (object, 선택): pageCursor를 포함한 페이지네이션 설정 + + + + + **설명:** 고급 필터링으로 작업(Task) 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 필드별 연산자가 지정된 분리적 정규형의 고급 필터 + - `sortBy` (string, 선택): 정렬 기준 필드 (예: "CreatedDate") + - `sortDirection` (string, 선택): 정렬 방향 - 옵션: ASC, DESC + - `includeAllFields` (boolean, 선택): 결과에 모든 필드를 포함 + - `paginationParameters` (object, 선택): pageCursor를 포함한 페이지네이션 설정 + + + + + **설명:** 고급 필터링으로 계정(Account) 레코드를 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 필드별 연산자가 지정된 분리적 정규형의 고급 필터 + - `sortBy` (string, 선택): 정렬 기준 필드 (예: "CreatedDate") + - `sortDirection` (string, 선택): 정렬 방향 - 옵션: ASC, DESC + - `includeAllFields` (boolean, 선택): 결과에 모든 필드를 포함 + - `paginationParameters` (object, 선택): pageCursor를 포함한 페이지네이션 설정 + + + + + **설명:** 모든 오브젝트 유형의 레코드를 검색합니다. + + **파라미터:** + - `recordType` (string, 필수): 검색할 레코드 유형 + - `filterFormula` (string, 선택): 필터 검색 조건 + - `includeAllFields` (boolean, 선택): 결과에 모든 필드를 포함 + - `paginationParameters` (object, 선택): pageCursor를 포함한 페이지네이션 설정 + + + + +### **리스트 뷰 조회** + + + + **설명:** 특정 리스트 뷰에서 Contact 레코드를 가져옵니다. + + **파라미터:** + - `listViewId` (string, 필수): 리스트 뷰 ID + - `paginationParameters` (object, 선택): pageCursor와 함께 사용하는 페이지네이션 설정 + + + + + **설명:** 특정 리스트 뷰에서 Lead 레코드를 가져옵니다. + + **파라미터:** + - `listViewId` (string, 필수): 리스트 뷰 ID + - `paginationParameters` (object, 선택): pageCursor와 함께 사용하는 페이지네이션 설정 + + + + + **설명:** 특정 리스트 뷰에서 Opportunity 레코드를 가져옵니다. + + **파라미터:** + - `listViewId` (string, 필수): 리스트 뷰 ID + - `paginationParameters` (object, 선택): pageCursor와 함께 사용하는 페이지네이션 설정 + + + + + **설명:** 특정 리스트 뷰에서 Task 레코드를 가져옵니다. + + **파라미터:** + - `listViewId` (string, 필수): 리스트 뷰 ID + - `paginationParameters` (object, 선택): pageCursor와 함께 사용하는 페이지네이션 설정 + + + + + **설명:** 특정 리스트 뷰에서 Account 레코드를 가져옵니다. + + **파라미터:** + - `listViewId` (string, 필수): 리스트 뷰 ID + - `paginationParameters` (object, 선택): pageCursor와 함께 사용하는 페이지네이션 설정 + + + + + **설명:** 특정 리스트 뷰에서 임의의 객체 유형의 레코드를 가져옵니다. + + **파라미터:** + - `recordType` (string, 필수): 레코드 유형 + - `listViewId` (string, 필수): 리스트 뷰 ID + - `paginationParameters` (object, 선택): pageCursor와 함께 사용하는 페이지네이션 설정 + + + + +### **커스텀 필드** + + + + **설명:** Contact 오브젝트에 대한 커스텀 필드를 배포합니다. + + **파라미터:** + - `label` (string, 필수): 표시 및 내부 참조를 위한 필드 라벨 + - `type` (string, 필수): 필드 유형 - 옵션: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, 선택): 체크박스 필드의 기본값 + - `length` (string, 필수): 숫자/텍스트 필드의 길이 + - `decimalPlace` (string, 필수): 숫자 필드의 소수 자릿수 + - `pickListValues` (string, 필수): 피클리스트 필드의 값(줄바꿈으로 구분) + - `visibleLines` (string, 필수): 멀티셀렉트/텍스트 영역 필드의 표시 줄 수 + - `description` (string, 선택): 필드 설명 + - `helperText` (string, 선택): 마우스를 올렸을 때 표시되는 도움말 텍스트 + - `defaultFieldValue` (string, 선택): 필드의 기본값 + + + + + **설명:** Lead 오브젝트에 대한 커스텀 필드를 배포합니다. + + **파라미터:** + - `label` (string, 필수): 표시 및 내부 참조를 위한 필드 라벨 + - `type` (string, 필수): 필드 유형 - 옵션: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, 선택): 체크박스 필드의 기본값 + - `length` (string, 필수): 숫자/텍스트 필드의 길이 + - `decimalPlace` (string, 필수): 숫자 필드의 소수 자릿수 + - `pickListValues` (string, 필수): 피클리스트 필드의 값(줄바꿈으로 구분) + - `visibleLines` (string, 필수): 멀티셀렉트/텍스트 영역 필드의 표시 줄 수 + - `description` (string, 선택): 필드 설명 + - `helperText` (string, 선택): 마우스를 올렸을 때 표시되는 도움말 텍스트 + - `defaultFieldValue` (string, 선택): 필드의 기본값 + + + + + **설명:** Opportunity 오브젝트에 대한 커스텀 필드를 배포합니다. + + **파라미터:** + - `label` (string, 필수): 표시 및 내부 참조를 위한 필드 라벨 + - `type` (string, 필수): 필드 유형 - 옵션: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, 선택): 체크박스 필드의 기본값 + - `length` (string, 필수): 숫자/텍스트 필드의 길이 + - `decimalPlace` (string, 필수): 숫자 필드의 소수 자릿수 + - `pickListValues` (string, 필수): 피클리스트 필드의 값(줄바꿈으로 구분) + - `visibleLines` (string, 필수): 멀티셀렉트/텍스트 영역 필드의 표시 줄 수 + - `description` (string, 선택): 필드 설명 + - `helperText` (string, 선택): 마우스를 올렸을 때 표시되는 도움말 텍스트 + - `defaultFieldValue` (string, 선택): 필드의 기본값 + + + + + **설명:** Task 오브젝트에 대한 커스텀 필드를 배포합니다. + + **파라미터:** + - `label` (string, 필수): 표시 및 내부 참조를 위한 필드 라벨 + - `type` (string, 필수): 필드 유형 - 옵션: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, Time, Url + - `defaultCheckboxValue` (boolean, 선택): 체크박스 필드의 기본값 + - `length` (string, 필수): 숫자/텍스트 필드의 길이 + - `decimalPlace` (string, 필수): 숫자 필드의 소수 자릿수 + - `pickListValues` (string, 필수): 피클리스트 필드의 값(줄바꿈으로 구분) + - `visibleLines` (string, 필수): 멀티셀렉트 필드의 표시 줄 수 + - `description` (string, 선택): 필드 설명 + - `helperText` (string, 선택): 마우스를 올렸을 때 표시되는 도움말 텍스트 + - `defaultFieldValue` (string, 선택): 필드의 기본값 + + + + + **설명:** Account 오브젝트에 대한 커스텀 필드를 배포합니다. + + **파라미터:** + - `label` (string, 필수): 표시 및 내부 참조를 위한 필드 라벨 + - `type` (string, 필수): 필드 유형 - 옵션: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url + - `defaultCheckboxValue` (boolean, 선택): 체크박스 필드의 기본값 + - `length` (string, 필수): 숫자/텍스트 필드의 길이 + - `decimalPlace` (string, 필수): 숫자 필드의 소수 자릿수 + - `pickListValues` (string, 필수): 피클리스트 필드의 값(줄바꿈으로 구분) + - `visibleLines` (string, 필수): 멀티셀렉트/텍스트 영역 필드의 표시 줄 수 + - `description` (string, 선택): 필드 설명 + - `helperText` (string, 선택): 마우스를 올렸을 때 표시되는 도움말 텍스트 + - `defaultFieldValue` (string, 선택): 필드의 기본값 + + + + + **설명:** 모든 오브젝트 타입에 대한 커스텀 필드를 배포합니다. + + **참고:** 커스텀 또는 미지의 오브젝트 타입에 커스텀 필드를 생성할 수 있는 유연한 도구입니다. + + + + +### **고급 작업** + + + + **설명:** Salesforce 데이터에 대해 커스텀 SOQL 쿼리를 실행합니다. + + **파라미터:** + - `query` (string, 필수): SOQL 쿼리 (예: "SELECT Id, Name FROM Account WHERE Name = 'Example'") + + + + + **설명:** Salesforce에 새로운 커스텀 오브젝트를 배포합니다. + + **파라미터:** + - `label` (string, 필수): 탭, 페이지 레이아웃, 리포트에 사용되는 오브젝트 라벨 + - `pluralLabel` (string, 필수): 복수형 라벨 (예: "Accounts") + - `description` (string, 선택): 커스텀 오브젝트에 대한 설명 + - `recordName` (string, 필수): 레이아웃과 검색에 표시되는 레코드 이름 (예: "Account Name") + + + + + **설명:** 특정 오브젝트 타입에 대한 작업의 예상 스키마를 가져옵니다. + + **파라미터:** + - `recordType` (string, 필수): 설명할 레코드 타입 + - `operation` (string, 필수): 작업 타입 (예: "CREATE_RECORD" 또는 "UPDATE_RECORD") + + **참고:** 커스텀 오브젝트 작업 시, 해당 스키마를 이해하기 위해 제일 먼저 이 기능을 사용하세요. + + + + +## 사용 예시 + +### 기본 Salesforce 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Salesforce capabilities +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.", + apps=['salesforce'] +) + +# 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() +``` + +### 특정 Salesforce 도구 필터링 + +```python + +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.", + apps=['salesforce'] +) + +# 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() +``` + +### 연락처 및 계정 관리 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['salesforce'] +) + +# 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() +``` + +### 고급 SOQL 쿼리 및 리포팅 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['salesforce'] +) + +# 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() +``` + +이 포괄적인 문서는 모든 Salesforce 도구를 기능별로 정리하여, 사용자가 CRM 자동화 작업에 필요한 특정 작업을 쉽게 찾을 수 있도록 도와줍니다. + +### 도움 받기 + + + Salesforce 통합 설정 또는 문제 해결에 대해 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/shopify.mdx b/docs/v1.15.1/ko/enterprise/integrations/shopify.mdx new file mode 100644 index 000000000..3b6a3a8df --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/shopify.mdx @@ -0,0 +1,412 @@ +--- +title: Shopify 연동 +description: "CrewAI를 위한 Shopify 연동을 통한 전자상거래 및 온라인 스토어 관리." +icon: "shopify" +mode: "wide" +--- + +## 개요 + +에이전트가 Shopify를 통해 전자상거래 운영을 관리할 수 있게 하세요. 고객, 주문, 제품, 재고 및 스토어 분석을 처리하여 AI 기반 자동화를 통해 온라인 비즈니스를 간소화할 수 있습니다. + +## 사전 요구 사항 + +Shopify 연동을 사용하기 전에 다음을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 관리자 권한이 있는 Shopify 스토어 +- [통합 페이지](https://app.crewai.com/integrations)를 통해 Shopify 스토어 연결 + +## Shopify 통합 설정 + +### 1. Shopify 스토어 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다. +2. 인증 통합 섹션에서 **Shopify**를 찾습니다. +3. **연결**을 클릭하고 OAuth 과정을 완료합니다. +4. 스토어 및 제품 관리에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 도구 + +### **고객 관리** + + + + **설명:** Shopify 스토어에서 고객 목록을 조회합니다. + + **파라미터:** + - `customerIds` (string, 선택): 필터링할 고객 ID의 쉼표로 구분된 목록 (예: "207119551, 207119552") + - `createdAtMin` (string, 선택): 이 날짜 이후에 생성된 고객만 반환 (ISO 또는 Unix 타임스탬프) + - `createdAtMax` (string, 선택): 이 날짜 이전에 생성된 고객만 반환 (ISO 또는 Unix 타임스탬프) + - `updatedAtMin` (string, 선택): 이 날짜 이후에 업데이트된 고객만 반환 (ISO 또는 Unix 타임스탬프) + - `updatedAtMax` (string, 선택): 이 날짜 이전에 업데이트된 고객만 반환 (ISO 또는 Unix 타임스탬프) + - `limit` (string, 선택): 반환할 최대 고객 수 (기본값 250) + + + + + **설명:** 고급 필터링 기준을 사용하여 고객을 검색합니다. + + **파라미터:** + - `filterFormula` (object, 선택): 필드별 연산자가 포함된 불리언 합정규형의 고급 필터 + - `limit` (string, 선택): 반환할 최대 고객 수 (기본값 250) + + + + + **설명:** Shopify 스토어에 새로운 고객을 생성합니다. + + **파라미터:** + - `firstName` (string, 필수): 고객의 이름 + - `lastName` (string, 필수): 고객의 성 + - `email` (string, 필수): 고객의 이메일 주소 + - `company` (string, 선택): 회사명 + - `streetAddressLine1` (string, 선택): 거리 주소 + - `streetAddressLine2` (string, 선택): 거리 주소 2 + - `city` (string, 선택): 도시 + - `state` (string, 선택): 주 또는 도 코드 + - `country` (string, 선택): 국가 + - `zipCode` (string, 선택): 우편번호 + - `phone` (string, 선택): 전화번호 + - `tags` (string, 선택): 배열 또는 쉼표로 구분된 태그 목록 + - `note` (string, 선택): 고객 메모 + - `sendEmailInvite` (boolean, 선택): 이메일 초대장 전송 여부 + - `metafields` (object, 선택): 추가 메타필드(JSON 형식) + + + + + **설명:** Shopify 스토어에 기존 고객을 업데이트합니다. + + **파라미터:** + - `customerId` (string, 필수): 업데이트할 고객의 ID + - `firstName` (string, 선택): 고객의 이름 + - `lastName` (string, 선택): 고객의 성 + - `email` (string, 선택): 고객의 이메일 주소 + - `company` (string, 선택): 회사명 + - `streetAddressLine1` (string, 선택): 거리 주소 + - `streetAddressLine2` (string, 선택): 거리 주소 2 + - `city` (string, 선택): 도시 + - `state` (string, 선택): 주 또는 도 코드 + - `country` (string, 선택): 국가 + - `zipCode` (string, 선택): 우편번호 + - `phone` (string, 선택): 전화번호 + - `tags` (string, 선택): 배열 또는 쉼표로 구분된 태그 목록 + - `note` (string, 선택): 고객 메모 + - `sendEmailInvite` (boolean, 선택): 이메일 초대장 전송 여부 + - `metafields` (object, 선택): 추가 메타필드(JSON 형식) + + + + +### **주문 관리** + + + + **설명:** Shopify 스토어에서 주문 목록을 조회합니다. + + **파라미터:** + - `orderIds` (string, optional): 필터링할 주문 ID의 콤마로 구분된 목록 (예: "450789469, 450789470") + - `createdAtMin` (string, optional): 이 날짜 이후에 생성된 주문만 반환 (ISO 또는 Unix 타임스탬프) + - `createdAtMax` (string, optional): 이 날짜 이전에 생성된 주문만 반환 (ISO 또는 Unix 타임스탬프) + - `updatedAtMin` (string, optional): 이 날짜 이후에 업데이트된 주문만 반환 (ISO 또는 Unix 타임스탬프) + - `updatedAtMax` (string, optional): 이 날짜 이전에 업데이트된 주문만 반환 (ISO 또는 Unix 타임스탬프) + - `limit` (string, optional): 반환할 주문의 최대 개수 (기본값: 250) + + + + + **설명:** Shopify 스토어에 새 주문을 생성합니다. + + **파라미터:** + - `email` (string, required): 고객 이메일 주소 + - `lineItems` (object, required): title, price, quantity, variant_id가 포함된 JSON 형식의 주문 아이템 + - `sendReceipt` (boolean, optional): 주문 영수증을 발송할지 여부 + - `fulfillmentStatus` (string, optional): 주문 이행 상태 - 옵션: fulfilled, null, partial, restocked + - `financialStatus` (string, optional): 결제 상태 - 옵션: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided + - `inventoryBehaviour` (string, optional): 인벤토리 동작 - 옵션: bypass, decrement_ignoring_policy, decrement_obeying_policy + - `note` (string, optional): 주문 메모 + + + + + **설명:** Shopify 스토어에서 기존 주문을 업데이트합니다. + + **파라미터:** + - `orderId` (string, required): 업데이트할 주문의 ID + - `email` (string, optional): 고객 이메일 주소 + - `lineItems` (object, optional): JSON 형식의 업데이트된 주문 아이템 + - `sendReceipt` (boolean, optional): 주문 영수증을 발송할지 여부 + - `fulfillmentStatus` (string, optional): 주문 이행 상태 - 옵션: fulfilled, null, partial, restocked + - `financialStatus` (string, optional): 결제 상태 - 옵션: pending, authorized, partially_paid, paid, partially_refunded, refunded, voided + - `inventoryBehaviour` (string, optional): 인벤토리 동작 - 옵션: bypass, decrement_ignoring_policy, decrement_obeying_policy + - `note` (string, optional): 주문 메모 + + + + + **설명:** Shopify 스토어에서 방치된 장바구니를 조회합니다. + + **파라미터:** + - `createdWithInLast` (string, optional): 지정된 기간 내에 생성된 체크아웃 결과만 제한 + - `createdAfterId` (string, optional): 지정된 ID 이후 결과로 제한 + - `status` (string, optional): 주어진 상태의 체크아웃만 표시 - 옵션: open, closed (기본값: open) + - `createdAtMin` (string, optional): 이 날짜 이후에 생성된 장바구니만 반환 (ISO 또는 Unix 타임스탬프) + - `createdAtMax` (string, optional): 이 날짜 이전에 생성된 장바구니만 반환 (ISO 또는 Unix 타임스탬프) + - `limit` (string, optional): 반환할 장바구니의 최대 개수 (기본값: 250) + + + + +### **제품 관리 (REST API)** + + + + **설명:** REST API를 사용하여 Shopify 스토어에서 제품 목록을 조회합니다. + + **파라미터:** + - `productIds` (string, optional): 필터링할 제품 ID의 콤마(,)로 구분된 목록 (예: "632910392, 632910393") + - `title` (string, optional): 제품 제목으로 필터링 + - `productType` (string, optional): 제품 유형으로 필터링 + - `vendor` (string, optional): 공급업체로 필터링 + - `status` (string, optional): 상태별 필터링 - 옵션: active, archived, draft + - `createdAtMin` (string, optional): 해당 날짜(ISO 혹은 Unix 타임스탬프) 이후에 생성된 제품만 반환 + - `createdAtMax` (string, optional): 해당 날짜(ISO 혹은 Unix 타임스탬프) 이전에 생성된 제품만 반환 + - `updatedAtMin` (string, optional): 해당 날짜(ISO 혹은 Unix 타임스탬프) 이후에 수정된 제품만 반환 + - `updatedAtMax` (string, optional): 해당 날짜(ISO 혹은 Unix 타임스탬프) 이전에 수정된 제품만 반환 + - `limit` (string, optional): 반환할 최대 제품 수 (기본값: 250) + + + + + **설명:** REST API를 사용하여 Shopify 스토어에 새로운 제품을 생성합니다. + + **파라미터:** + - `title` (string, required): 제품 제목 + - `productType` (string, required): 제품 유형/카테고리 + - `vendor` (string, required): 제품 공급업체 + - `productDescription` (string, optional): 제품 설명 (일반 텍스트 또는 HTML 가능) + - `tags` (string, optional): 배열 또는 콤마(,)로 구분된 태그 목록 + - `price` (string, optional): 제품 가격 + - `inventoryPolicy` (string, optional): 재고 정책 - 옵션: deny, continue + - `imageUrl` (string, optional): 제품 이미지 URL + - `isPublished` (boolean, optional): 제품 공개 여부 + - `publishToPointToSale` (boolean, optional): 포인트 오브 세일(Point of Sale)에 공개 여부 + + + + + **설명:** REST API를 사용하여 Shopify 스토어의 기존 제품을 업데이트합니다. + + **파라미터:** + - `productId` (string, required): 업데이트할 제품 ID + - `title` (string, optional): 제품 제목 + - `productType` (string, optional): 제품 유형/카테고리 + - `vendor` (string, optional): 제품 공급업체 + - `productDescription` (string, optional): 제품 설명 (일반 텍스트 또는 HTML 가능) + - `tags` (string, optional): 배열 또는 콤마(,)로 구분된 태그 목록 + - `price` (string, optional): 제품 가격 + - `inventoryPolicy` (string, optional): 재고 정책 - 옵션: deny, continue + - `imageUrl` (string, optional): 제품 이미지 URL + - `isPublished` (boolean, optional): 제품 공개 여부 + - `publishToPointToSale` (boolean, optional): 포인트 오브 세일(Point of Sale)에 공개 여부 + + + + +### **제품 관리 (GraphQL)** + + + + **설명:** 고급 GraphQL 필터링 기능을 사용하여 제품을 조회합니다. + + **파라미터:** + - `productFilterFormula` (object, 선택): id, title, vendor, status, handle, tag, created_at, updated_at, published_at와 같은 필드를 지원하는 불리언 정규합형(DNF) 기반의 고급 필터 + + + + + **설명:** 미디어 지원이 강화된 GraphQL API를 사용하여 새 제품을 생성합니다. + + **파라미터:** + - `title` (string, 필수): 제품 제목 + - `productType` (string, 필수): 제품 유형/카테고리 + - `vendor` (string, 필수): 제품 공급업체 + - `productDescription` (string, 선택): 제품 설명 (일반 텍스트 또는 HTML 허용) + - `tags` (string, 선택): 배열 또는 쉼표로 구분된 리스트 형태의 제품 태그 + - `media` (object, 선택): 대체 텍스트, 콘텐츠 유형 및 소스 URL을 가진 미디어 객체 + - `additionalFields` (object, 선택): status, requiresSellingPlan, giftCard와 같은 추가 제품 필드 + + + + + **설명:** 미디어 지원이 강화된 GraphQL API를 사용하여 기존 제품을 업데이트합니다. + + **파라미터:** + - `productId` (string, 필수): 업데이트할 제품의 GraphQL ID (예: "gid://shopify/Product/913144112") + - `title` (string, 선택): 제품 제목 + - `productType` (string, 선택): 제품 유형/카테고리 + - `vendor` (string, 선택): 제품 공급업체 + - `productDescription` (string, 선택): 제품 설명 (일반 텍스트 또는 HTML 허용) + - `tags` (string, 선택): 배열 또는 쉼표로 구분된 리스트 형태의 제품 태그 + - `media` (object, 선택): 대체 텍스트, 콘텐츠 유형 및 소스 URL을 포함한 업데이트된 미디어 객체 + - `additionalFields` (object, 선택): status, requiresSellingPlan, giftCard와 같은 추가 제품 필드 + + + + +## 사용 예시 + +### 기본 Shopify 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# 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.", + apps=['shopify'] +) + +# 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() +``` + +### 특정 Shopify 도구 필터링 + +```python + +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.", + apps=['shopify'] +) + +# 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() +``` + +### GraphQL을 활용한 제품 관리 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['shopify'] +) + +# Task to manage product catalog +catalog_task = Task( + description=""" + 1. Coffee Co 공급업체의 신규 제품 "Premium Coffee Mug"을(를) 생성하세요. + 2. 고품질 제품 이미지와 설명을 추가하세요. + 3. 동일한 공급업체의 유사 제품을 검색하세요. + 4. 제품 태그와 가격 전략을 업데이트하세요. + """, + agent=product_manager, + expected_output="Product created and catalog optimized successfully" +) + +crew = Crew( + agents=[product_manager], + tasks=[catalog_task] +) + +crew.kickoff() +``` + +### 주문 및 고객 분석 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['shopify'] +) + +# Complex task involving multiple operations +analytics_task = Task( + description=""" + 1. 최근 고객 데이터 및 주문 내역 조회 + 2. 최근 7일간의 장바구니 이탈 식별 + 3. 상품 성과 및 재고 수준 분석 + 4. 고객 유지를 위한 추천 사항 생성 + """, + agent=analytics_agent, + expected_output="실행 가능한 인사이트를 제공하는 종합 이커머스 분석 보고서" +) + +crew = Crew( + agents=[analytics_agent], + tasks=[analytics_task] +) + +crew.kickoff() +``` + +### 도움 받기 + + + Shopify 연동 설정 또는 문제 해결에 관한 지원이 필요하시면 고객 지원팀에 문의해 + 주세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/slack.mdx b/docs/v1.15.1/ko/enterprise/integrations/slack.mdx new file mode 100644 index 000000000..6e38d009f --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/slack.mdx @@ -0,0 +1,317 @@ +--- +title: Slack 연동 +description: "CrewAI를 위한 Slack 연동으로 팀 커뮤니케이션 및 협업 지원." +icon: "slack" +mode: "wide" +--- + +## 개요 + +에이전트가 Slack을 통해 팀 커뮤니케이션을 관리할 수 있도록 지원합니다. 메시지를 보내고, 대화를 검색하며, 채널을 관리하고, AI 기반 자동화를 통해 팀 활동을 조율하여 협업 워크플로우를 효율적으로 최적화하세요. + +## 사전 준비 사항 + +Slack 통합을 사용하기 전에 다음을 확인하십시오: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 권한이 있는 Slack 워크스페이스 +- [통합 페이지](https://app.crewai.com/integrations)를 통해 Slack 워크스페이스를 연결함 + +## Slack 통합 설정 + +### 1. Slack 워크스페이스 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다. +2. 인증 통합 섹션에서 **Slack**을 찾습니다. +3. **연결**을 클릭하고 OAuth 과정을 완료합니다. +4. 팀 커뮤니케이션에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 도구 + +### **사용자 관리** + + + + **설명:** Slack 채널의 모든 멤버를 나열합니다. + + **파라미터:** + - 파라미터 없음 - 모든 채널 멤버를 조회합니다 + + + + + **설명:** 이메일 주소로 Slack 워크스페이스에서 사용자를 찾습니다. + + **파라미터:** + - `email` (string, 필수): 워크스페이스 내 사용자의 이메일 주소 + + + + + **설명:** 이름 또는 표시 이름으로 사용자를 검색합니다. + + **파라미터:** + - `name` (string, 필수): 검색할 사용자의 실제 이름 + - `displayName` (string, 필수): 검색할 사용자의 표시 이름 + - `paginationParameters` (object, 선택): 페이지네이션 설정 + - `pageCursor` (string, 선택): 페이지네이션을 위한 페이지 커서 + + + + +### **채널 관리** + + + + **설명:** Slack 워크스페이스의 모든 채널을 나열합니다. + + **파라미터:** + - 파라미터가 필요하지 않습니다 - 접근 가능한 모든 채널을 조회합니다 + + + + +### **메시징** + + + + **설명:** Slack 채널에 메시지를 전송합니다. + + **파라미터:** + - `channel` (string, 필수): 채널 이름 또는 ID - Connect Portal Workflow Settings를 사용하여 사용자가 채널을 선택하도록 하거나, 채널 이름을 입력하여 새 채널을 생성할 수 있습니다. + - `message` (string, 필수): 전송할 메시지 텍스트 + - `botName` (string, 필수): 이 메시지를 전송하는 봇의 이름 + - `botIcon` (string, 필수): 봇 아이콘 - 이미지 URL 또는 이모지(e.g., ":dog:") 모두 가능합니다. + - `blocks` (object, 선택): 첨부파일 및 인터랙티브 요소 등이 포함된 풍부한 메시지 포맷팅을 위한 Slack Block Kit JSON + - `authenticatedUser` (boolean, 선택): true이면 메시지가 애플리케이션이 아니라 인증된 Slack 사용자로부터 보낸 것처럼 표시됩니다(기본값은 false) + + + + + **설명:** Slack에서 특정 사용자에게 다이렉트 메시지를 전송합니다. + + **파라미터:** + - `memberId` (string, 필수): 수신자 사용자 ID - Connect Portal Workflow Settings를 사용하여 사용자가 워크스페이스 멤버를 선택하도록 합니다. + - `message` (string, 필수): 전송할 메시지 텍스트 + - `botName` (string, 필수): 이 메시지를 전송하는 봇의 이름 + - `botIcon` (string, 필수): 봇 아이콘 - 이미지 URL 또는 이모지(e.g., ":dog:") 모두 가능합니다. + - `blocks` (object, 선택): 첨부파일 및 인터랙티브 요소 등이 포함된 풍부한 메시지 포맷팅을 위한 Slack Block Kit JSON + - `authenticatedUser` (boolean, 선택): true이면 메시지가 애플리케이션이 아니라 인증된 Slack 사용자로부터 보낸 것처럼 표시됩니다(기본값은 false) + + + + +### **검색 및 탐색** + + + + **설명:** Slack 워크스페이스 전체에서 메시지를 검색합니다. + + **매개변수:** + - `query` (string, 필수): 지정된 기준과 일치하는 메시지를 찾기 위해 Slack 검색 구문을 사용한 검색 쿼리 + + **검색 쿼리 예시:** + - `"project update"` - "project update"가 포함된 메시지 검색 + - `from:@john in:#general` - #general 채널에서 John이 보낸 메시지 검색 + - `has:link after:2023-01-01` - 2023년 1월 1일 이후에 링크가 포함된 메시지 검색 + - `in:@channel before:yesterday` - 특정 채널에서 어제 이전에 작성된 메시지 검색 + + + + +## Block Kit 통합 + +Slack의 Block Kit을 사용하면 풍부하고 상호작용이 가능한 메시지를 생성할 수 있습니다. 다음은 `blocks` 매개변수를 사용하는 방법에 대한 몇 가지 예시입니다: + +### 첨부 파일이 있는 간단한 텍스트 + +```json +[ + { + "text": "I am a test message", + "attachments": [ + { + "text": "And here's an attachment!" + } + ] + } +] +``` + +### 섹션을 활용한 리치 포매팅 + +```json +[ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*프로젝트 업데이트*\n상태: ✅ 완료" + } + }, + { + "type": "divider" + }, + { + "type": "section", + "text": { + "type": "plain_text", + "text": "모든 작업이 성공적으로 완료되었습니다." + } + } +] +``` + +## 사용 예시 + +### 기본 Slack 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# 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.", + apps=['slack'] +) + +# 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() +``` + +### 특정 Slack 도구 필터링 + +```python + +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.", + apps=['slack'] +) + +# 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() +``` + +### Block Kit을 활용한 고급 메시징 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['slack'] +) + +# 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() +``` + +### 메시지 검색 및 분석 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['slack'] +) + +# Complex task involving search and analysis +analysis_task = Task( + description=""" + 1. 모든 채널에서 최근 프로젝트 관련 메시지 검색 + 2. 이메일로 사용자를 찾아 팀 구성원 식별 + 3. 커뮤니케이션 패턴 및 응답 시간 분석 + 4. 주간 팀 커뮤니케이션 요약 생성 + """, + agent=analytics_agent, + expected_output="팀 인사이트 및 권장사항이 포함된 종합적인 커뮤니케이션 분석" +) + +crew = Crew( + agents=[analytics_agent], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +## 지원 문의 + + + Slack 연동 설정 또는 문제 해결에 대해 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/snowflake.mdx b/docs/v1.15.1/ko/enterprise/integrations/snowflake.mdx new file mode 100644 index 000000000..19807de87 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/snowflake.mdx @@ -0,0 +1,134 @@ +--- +title: Snowflake 연동 +description: "Snowflake 관리형 MCP 서버를 통해 CrewAI 에이전트를 Snowflake Cortex Analyst, Cortex Search 및 SQL 실행에 연결합니다." +icon: "snowflake" +mode: "wide" +--- + +## 개요 + +[Snowflake 관리형 MCP 서버](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)를 통해 CrewAI 에이전트를 Snowflake 데이터에 직접 연결하세요. Snowflake 연동을 사용하면 에이전트가 **Cortex Analyst**로 구조화된 데이터를 쿼리하고, **Cortex Search**로 비구조화된 데이터를 검색하며, 커넥터 코드를 작성하거나 호스팅할 필요 없이 웨어하우스에 대해 관리되는 SQL을 실행할 수 있습니다. + +내부적으로 Snowflake 연동은 CrewAI의 [Custom MCP Server](/ko/enterprise/guides/custom-mcp-server) 지원을 기반으로 하는 관리형 래퍼입니다. Snowflake는 [Model Context Protocol](https://modelcontextprotocol.io/) 엔드포인트를 통해 Cortex AI 기능을 노출하며, CrewAI가 이를 안전하게 연결합니다. Snowflake 측에서 노출하는 모든 도구 — Cortex Analyst, Cortex Search, SQL 실행, Cortex Agents 또는 사용자 정의 도구 — 가 크루에서 사용할 수 있게 됩니다. + +## 주요 기능 + + + + 자연어로 질문하고 [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst)가 풍부한 시맨틱 모델을 사용하여 **구조화된** 데이터에 대해 SQL을 생성하고 실행하도록 합니다. + + + Snowflake의 완전 관리형 검색 서비스인 [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview)를 사용하여 RAG 및 지식 워크플로우를 위한 관련 **비구조화된** 데이터를 검색합니다. + + + 구성 가능한 읽기 전용 모드, 타임아웃 및 웨어하우스 선택을 통해 Snowflake 웨어하우스에 대해 관리되는 SQL 쿼리를 직접 실행합니다. + + + +연동이 MCP 서버가 게시하는 도구를 노출하므로, **Cortex Agents** 및 **사용자 정의 도구**(사용자 정의 함수 및 저장 프로시저)도 CrewAI 에이전트에 노출할 수 있습니다. + +## 사전 준비 사항 + +Snowflake 연동을 사용하기 전에 다음을 확인하십시오: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- Cortex AI 기능에 액세스할 수 있는 Snowflake 계정 +- 노출하려는 도구가 구성된 [Snowflake 관리형 MCP 서버](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) +- MCP 서버 및 기본 객체에 대한 적절한 Snowflake 권한(USAGE/SELECT) + +## Snowflake MCP 서버 설정 + +Snowflake 관리형 MCP 서버는 Snowflake 계정 내에서 실행되며 CrewAI와 같은 외부 클라이언트에서 사용할 수 있는 도구를 정의합니다. [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server) 명령을 사용하여 노출하려는 Cortex Search 서비스, Cortex Analyst 시맨틱 뷰 및 SQL 도구를 나열하여 생성합니다. + +```sql +CREATE MCP SERVER my_mcp_server + FROM SPECIFICATION $$ + tools: + - name: "sales_analyst" + type: "CORTEX_ANALYST" + identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view" + description: "Answer questions about sales metrics" + - name: "docs_search" + type: "CORTEX_SEARCH_SERVICE_QUERY" + identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search" + description: "Search internal support documentation" + - name: "run_sql" + type: "SQL_EXECUTION" + description: "Execute read-only SQL queries" + $$; +``` + + +MCP 엔드포인트는 `https:///api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}` 형식을 따릅니다. CrewAI는 연동 구성 시 제공하는 **계정 URL**, **데이터베이스**, **스키마** 및 **MCP 서버 이름**을 사용하여 이 URL을 자동으로 구성합니다. + + +Cortex Agents, 사용자 정의 도구, 응답 크기 제한 및 거버넌스 옵션을 포함한 전체 사양은 [Snowflake 관리형 MCP 서버 문서](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)를 참조하세요. + +## CrewAI AMP에서 Snowflake 연결 + + + CrewAI AMP에서 Snowflake 연동 구성 + + + + + CrewAI AMP 왼쪽 사이드바에서 **도구 및 연동**으로 이동하고, 애플리케이션 목록에서 **Snowflake**를 찾아 구성 패널을 엽니다. + + + + CrewAI가 Snowflake MCP 서버에 연결하는 데 사용하는 연결 필드를 채웁니다: + + | 필드 | 필수 | 설명 | + |------|------|------| + | **이름** | 예 | 이 연결의 설명적 이름(기본값: `Snowflake`). | + | **설명** | 아니오 | 이 연결이 제공하는 내용에 대한 선택적 요약. | + | **계정 URL** | 예 | Snowflake 계정 URL, 예: `xy12345.us-east-1.snowflakecomputing.com`. | + | **데이터베이스** | 예 | MCP 서버가 포함된 데이터베이스(예: `MY_DATABASE`). | + | **스키마** | 예 | MCP 서버가 포함된 스키마(예: `MY_SCHEMA`). | + | **MCP 서버 이름** | 예 | Snowflake에서 생성한 MCP 서버 객체의 이름(예: `MY_MCP_SERVER`). | + + + + CrewAI가 Snowflake에 인증하는 방법을 선택합니다. **OAuth**가 권장됩니다. + + - **OAuth 사용** — 자격 증명을 공유하지 않고 토큰 기반 인증을 위해 OAuth 2.0을 사용하여 안전하게 연결합니다. CrewAI가 전체 인증 흐름을 처리하고 자동으로 토큰을 갱신합니다. 양식에 표시된 **리디렉트 URI**(`https://oauth.crewai.com/oauth/add`)를 복사하여 Snowflake [OAuth 보안 연동](https://docs.snowflake.com/en/user-guide/oauth-custom)에 인증된 리디렉트 URI로 등록하세요. + - **개인 액세스 토큰 사용** — Snowflake 계정 설정에서 생성한 [프로그래밍 방식 액세스 토큰](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens)을 사용하여 인증합니다. 노출을 제한하기 위해 토큰에 최소 권한 역할을 할당하세요. + + + + **인증**을 클릭합니다. OAuth의 경우 Snowflake로 리디렉션되어 액세스를 승인합니다. 인증되면 Snowflake 서버가 연결 목록에 나타나고 해당 도구를 크루에서 사용할 수 있게 됩니다. + + + + +OAuth를 사용하면 각 사용자가 개별적으로 인증하며 쿼리는 해당 Snowflake `DEFAULT_ROLE`로 실행됩니다. 연결하는 사용자에게 기본 역할과 웨어하우스가 설정되어 있는지 확인하세요(`ALTER USER SET DEFAULT_ROLE = '' DEFAULT_WAREHOUSE = ''`). 그래야 Cortex Analyst 및 SQL 도구에 실행할 컴퓨팅이 있습니다. + + +## 크루에서 Snowflake 도구 사용 + +연결되면 MCP 서버가 노출하는 도구가 **도구 및 연동** 페이지에서 기본 연결과 함께 표시됩니다. 다음을 수행할 수 있습니다: + +- 다른 CrewAI 도구처럼 크루의 **에이전트에 도구를 할당**합니다. +- **가시성을 관리**하여 어떤 팀원이 연결을 사용할 수 있는지 제어합니다. +- 연결 목록에서 언제든지 연결을 **편집하거나 제거**합니다. + +이제 에이전트가 Cortex Analyst에 메트릭을 요청하고, 문서에 대해 Cortex Search를 실행하고, SQL을 실행할 수 있으며 — 결과가 자동으로 추론에 반영됩니다. + + +Snowflake는 MCP 서버에 거버넌스를 적용합니다: 역할 기반 액세스 제어가 사용자가 발견하고 호출할 수 있는 도구를 결정하며, 응답 크기, 도구 수(서버당 최대 50개) 및 재귀 깊이에 제한이 적용됩니다. 도구 호출이 실패하면 연결하는 사용자의 역할에 MCP 서버 및 기본 객체에 대한 필수 권한이 있는지 확인하세요. + + +## 자세히 알아보기 + + + + MCP 서버를 생성하고 관리하기 위한 공식 Snowflake 문서. + + + CrewAI가 모든 MCP 서버에 연결하는 방법을 알아보세요. Snowflake 연동이 기반으로 하는 기초입니다. + + + + + Snowflake 연동 또는 문제 해결에 대해 지원팀에 문의하세요. + diff --git a/docs/v1.15.1/ko/enterprise/integrations/stripe.mdx b/docs/v1.15.1/ko/enterprise/integrations/stripe.mdx new file mode 100644 index 000000000..c343fe61a --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/stripe.mdx @@ -0,0 +1,327 @@ +--- +title: Stripe 연동 +description: "CrewAI를 위한 Stripe 연동을 통한 결제 처리 및 구독 관리." +icon: "stripe" +mode: "wide" +--- + +## 개요 + +에이전트가 Stripe를 통해 결제, 구독 및 고객 청구 관리를 할 수 있도록 지원합니다. 고객 데이터 처리, 구독 관리, 상품 관리, 재무 거래 추적 등을 통해 AI 기반 자동화로 결제 워크플로를 효율화하세요. + +## 사전 준비 사항 + +Stripe 통합을 사용하기 전에 다음 사항을 확인하세요: + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 API 권한이 있는 Stripe 계정 +- [통합 페이지](https://app.crewai.com/integrations)를 통해 Stripe 계정 연결 + +## Stripe 통합 설정 + +### 1. Stripe 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다. +2. 인증 통합 섹션에서 **Stripe**를 찾습니다. +3. **연결**을 클릭하고 OAuth 과정을 완료합니다. +4. 결제 처리에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 도구 + +### **고객 관리** + + + + **설명:** Stripe 계정에 새로운 고객을 생성합니다. + + **파라미터:** + - `emailCreateCustomer` (string, 필수): 고객의 이메일 주소 + - `name` (string, 선택): 고객의 전체 이름 + - `description` (string, 선택): 내부 참조용 고객 설명 + - `metadataCreateCustomer` (object, 선택): 추가 메타데이터를 key-value 쌍으로 입력 (예: `{"field1": 1, "field2": 2}`) + + + + + **설명:** Stripe 고객 ID로 특정 고객을 조회합니다. + + **파라미터:** + - `idGetCustomer` (string, 필수): 조회할 Stripe 고객 ID + + + + + **설명:** 필터링 옵션과 함께 고객 리스트를 조회합니다. + + **파라미터:** + - `emailGetCustomers` (string, 선택): 이메일 주소로 고객 필터링 + - `createdAfter` (string, 선택): 이 날짜 이후 생성된 고객 필터링 (유닉스 타임스탬프) + - `createdBefore` (string, 선택): 이 날짜 이전 생성된 고객 필터링 (유닉스 타임스탬프) + - `limitGetCustomers` (string, 선택): 반환할 최대 고객 수 (기본값 10) + + + + + **설명:** 기존 고객의 정보를 업데이트합니다. + + **파라미터:** + - `customerId` (string, 필수): 업데이트할 고객의 ID + - `emailUpdateCustomer` (string, 선택): 업데이트할 이메일 주소 + - `name` (string, 선택): 업데이트할 고객 이름 + - `description` (string, 선택): 업데이트할 고객 설명 + - `metadataUpdateCustomer` (object, 선택): 업데이트할 메타데이터를 key-value 쌍으로 입력 + + + + +### **구독 관리** + + + + **설명:** 고객을 위한 새로운 구독을 생성합니다. + + **파라미터:** + - `customerIdCreateSubscription` (string, 필수): 구독이 생성될 고객 ID + - `plan` (string, 필수): 구독을 위한 플랜 ID - 사용자가 플랜을 선택할 수 있도록 Connect Portal Workflow Settings를 사용하세요 + - `metadataCreateSubscription` (object, 선택): 구독에 대한 추가 메타데이터 + + + + + **설명:** 선택적 필터링으로 구독을 조회합니다. + + **파라미터:** + - `customerIdGetSubscriptions` (string, 선택): 고객 ID로 구독을 필터링 + - `subscriptionStatus` (string, 선택): 구독 상태별 필터링 - 옵션: incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid + - `limitGetSubscriptions` (string, 선택): 반환할 구독의 최대 개수(기본값은 10) + + + + +### **제품 관리** + + + + **설명:** Stripe 카탈로그에 새 제품을 생성합니다. + + **파라미터:** + - `productName` (string, 필수): 제품 이름 + - `description` (string, 선택): 제품 설명 + - `metadataProduct` (object, 선택): 키-값 쌍으로 구성된 추가 제품 메타데이터 + + + + + **설명:** Stripe 제품 ID로 특정 제품을 조회합니다. + + **파라미터:** + - `productId` (string, 필수): 조회할 Stripe 제품 ID + + + + + **설명:** 선택적 필터링을 통해 제품 목록을 조회합니다. + + **파라미터:** + - `createdAfter` (string, 선택): 이 날짜 이후 생성된 제품만 필터링 (Unix 타임스탬프) + - `createdBefore` (string, 선택): 이 날짜 이전 생성된 제품만 필터링 (Unix 타임스탬프) + - `limitGetProducts` (string, 선택): 반환할 최대 제품 수 (기본값 10) + + + + +### **금융 운영** + + + + **설명:** Stripe 계정에서 잔액 거래를 조회합니다. + + **매개변수:** + - `balanceTransactionType` (string, 선택 사항): 거래 유형별 필터 - 옵션: charge, refund, payment, payment_refund + - `paginationParameters` (object, 선택 사항): 페이지네이션 설정 + - `pageCursor` (string, 선택 사항): 페이지네이션을 위한 페이지 커서 + + + + + **설명:** Stripe 계정에서 구독 플랜을 조회합니다. + + **매개변수:** + - `isPlanActive` (boolean, 선택 사항): 플랜 상태별 필터 - true는 활성 플랜, false는 비활성 플랜 + - `paginationParameters` (object, 선택 사항): 페이지네이션 설정 + - `pageCursor` (string, 선택 사항): 페이지네이션을 위한 페이지 커서 + + + + +## 사용 예시 + +### 기본 Stripe 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# 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.", + apps=['stripe'] +) + +# 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() +``` + +### 특정 Stripe 도구 필터링 + +```python + +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.", + apps=['stripe'] +) + +# 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() +``` + +### 구독 관리 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['stripe'] +) + +# Task to manage subscription operations +subscription_task = Task( + description=""" + 1. 고급 기능이 포함된 새로운 제품 "Premium Service Plan" 생성 + 2. 다양한 등급의 구독 플랜 설정 + 3. 고객을 생성하고 적절한 플랜에 할당 + 4. 구독 상태를 모니터링하고 결제 문제 처리 + """, + agent=subscription_manager, + expected_output="고객과 활성 플랜이 구성된 구독 관리 시스템" +) + +crew = Crew( + agents=[subscription_manager], + tasks=[subscription_task] +) + +crew.kickoff() +``` + +### 금융 분석 및 보고 + +```python +from crewai import Agent, Task, Crew + +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.", + apps=['stripe'] +) + +# 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() +``` + +## 구독 상태 참조 + +구독 상태 이해하기: + +- **incomplete** - 결제 수단 또는 결제 확인이 필요한 구독 +- **incomplete_expired** - 결제가 확인되기 전에 만료된 구독 +- **trialing** - 체험 기간 중인 구독 +- **active** - 활성화되어 현재 사용 중인 구독 +- **past_due** - 결제에 실패했지만 여전히 활성화된 구독 +- **canceled** - 취소된 구독 +- **unpaid** - 결제에 실패하여 더 이상 활성화되지 않은 구독 + +## 메타데이터 사용 + +메타데이터를 사용하면 고객, 구독, 제품에 대한 추가 정보를 저장할 수 있습니다: + +```json +{ + "customer_segment": "enterprise", + "acquisition_source": "google_ads", + "lifetime_value": "high", + "custom_field_1": "value1" +} +``` + +이 통합을 통해 결제 및 구독 관리 자동화를 포괄적으로 구현할 수 있으며, AI 에이전트가 Stripe 생태계 내에서 청구 작업을 원활하게 처리할 수 있습니다. diff --git a/docs/v1.15.1/ko/enterprise/integrations/zendesk.mdx b/docs/v1.15.1/ko/enterprise/integrations/zendesk.mdx new file mode 100644 index 000000000..dfa9018ff --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/integrations/zendesk.mdx @@ -0,0 +1,365 @@ +--- +title: Zendesk 통합 +description: "CrewAI를 위한 Zendesk 통합으로 고객 지원 및 헬프데스크 관리." +icon: "headset" +mode: "wide" +--- + +## 개요 + +에이전트가 Zendesk를 통해 고객 지원 운영을 관리할 수 있도록 지원합니다. 티켓 생성 및 업데이트, 사용자 관리, 지원 지표 추적, 그리고 AI 기반 자동화를 통해 고객 서비스 워크플로우를 간소화할 수 있습니다. + +## 사전 준비 사항 + +Zendesk 통합을 사용하기 전에 다음을 확인하세요. + +- 활성 구독이 있는 [CrewAI AMP](https://app.crewai.com) 계정 +- 적절한 API 권한이 있는 Zendesk 계정 +- [통합 페이지](https://app.crewai.com/integrations)를 통해 Zendesk 계정 연결 + +## Zendesk 통합 설정 + +### 1. Zendesk 계정 연결 + +1. [CrewAI AMP 통합](https://app.crewai.com/crewai_plus/connectors)으로 이동합니다. +2. 인증 통합 섹션에서 **Zendesk**를 찾습니다. +3. **연결**을 클릭하고 OAuth 과정을 완료합니다. +4. 티켓 및 사용자 관리에 필요한 권한을 부여합니다. +5. [통합 설정](https://app.crewai.com/crewai_plus/settings/integrations)에서 Enterprise Token을 복사합니다. + +### 2. 필수 패키지 설치 + +```bash +uv add crewai-tools +``` + +### 3. 환경 변수 설정 + + + `Agent(apps=[])`와 함께 통합을 사용하려면 Enterprise Token으로 + `CREWAI_PLATFORM_INTEGRATION_TOKEN` 환경 변수를 설정해야 합니다. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +또는 `.env` 파일에 추가하세요: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## 사용 가능한 도구 + +### **티켓 관리** + + + + **설명:** Zendesk에 새로운 지원 티켓을 생성합니다. + + **매개변수:** + - `ticketSubject` (string, 필수): 티켓 제목 줄 (예: "도와주세요, 프린터에 불이 났어요!") + - `ticketDescription` (string, 필수): 티켓에 표시될 첫 번째 댓글 (예: "연기가 정말 화려하네요.") + - `requesterName` (string, 필수): 지원 요청자의 이름 (예: "Jane Customer") + - `requesterEmail` (string, 필수): 지원 요청자의 이메일 (예: "jane@example.com") + - `assigneeId` (string, 선택): 이 티켓에 할당된 Zendesk 에이전트 ID - 사용자가 담당자를 선택할 수 있도록 Connect Portal Workflow Settings 를 사용하세요 + - `ticketType` (string, 선택): 티켓 유형 - 옵션: problem, incident, question, task + - `ticketPriority` (string, 선택): 우선순위 수준 - 옵션: urgent, high, normal, low + - `ticketStatus` (string, 선택): 티켓 상태 - 옵션: new, open, pending, hold, solved, closed + - `ticketDueAt` (string, 선택): task 유형 티켓의 마감일 (ISO 8601 타임스탬프) + - `ticketTags` (string, 선택): 적용할 태그 배열 (예: `["enterprise", "other_tag"]`) + - `ticketExternalId` (string, 선택): 티켓을 로컬 레코드와 연결할 외부 ID + - `ticketCustomFields` (object, 선택): JSON 형식의 사용자 정의 필드 값 + + + + + **설명:** Zendesk의 기존 지원 티켓을 업데이트합니다. + + **매개변수:** + - `ticketId` (string, 필수): 업데이트할 티켓의 ID (예: "35436") + - `ticketSubject` (string, 선택): 업데이트된 티켓 제목 + - `requesterName` (string, 필수): 이 티켓을 요청한 사용자의 이름 + - `requesterEmail` (string, 필수): 이 티켓을 요청한 사용자의 이메일 + - `assigneeId` (string, 선택): 업데이트된 담당자 ID - Connect Portal Workflow Settings 를 사용하세요 + - `ticketType` (string, 선택): 업데이트된 티켓 유형 - 옵션: problem, incident, question, task + - `ticketPriority` (string, 선택): 업데이트된 우선순위 - 옵션: urgent, high, normal, low + - `ticketStatus` (string, 선택): 업데이트된 상태 - 옵션: new, open, pending, hold, solved, closed + - `ticketDueAt` (string, 선택): 업데이트된 마감일 (ISO 8601 타임스탬프) + - `ticketTags` (string, 선택): 업데이트된 태그 배열 + - `ticketExternalId` (string, 선택): 업데이트된 외부 ID + - `ticketCustomFields` (object, 선택): 업데이트된 사용자 정의 필드 값 + + + + + **설명:** ID로 특정 티켓을 조회합니다. + + **매개변수:** + - `ticketId` (string, 필수): 조회할 티켓의 ID (예: "35436") + + + + + **설명:** 기존 티켓에 댓글이나 내부 노트를 추가합니다. + + **매개변수:** + - `ticketId` (string, 필수): 댓글을 추가할 티켓의 ID (예: "35436") + - `commentBody` (string, 필수): 댓글 메시지 (일반 텍스트 또는 HTML 지원, 예: "도움을 주셔서 감사합니다!") + - `isInternalNote` (boolean, 선택): 공개 답글 대신 내부 노트로 설정하려면 true (기본값: false) + - `isPublic` (boolean, 선택): 공개 댓글이면 true, 내부 노트이면 false + + + + + **설명:** 다양한 필터 및 조건을 사용하여 티켓을 검색합니다. + + **매개변수:** + - `ticketSubject` (string, 선택): 티켓 제목 내 텍스트로 필터링 + - `ticketDescription` (string, 선택): 티켓 설명 및 댓글 내 텍스트로 필터링 + - `ticketStatus` (string, 선택): 상태로 필터링 - 옵션: new, open, pending, hold, solved, closed + - `ticketType` (string, 선택): 유형으로 필터링 - 옵션: problem, incident, question, task, no_type + - `ticketPriority` (string, 선택): 우선순위로 필터링 - 옵션: urgent, high, normal, low, no_priority + - `requesterId` (string, 선택): 요청자 사용자 ID로 필터링 + - `assigneeId` (string, 선택): 담당 에이전트 ID로 필터링 + - `recipientEmail` (string, 선택): 원래 수신자 이메일 주소로 필터링 + - `ticketTags` (string, 선택): 티켓 태그로 필터링 + - `ticketExternalId` (string, 선택): 외부 ID로 필터링 + - `createdDate` (object, 선택): 생성일로 필터링 (연산자: EQUALS, LESS_THAN_EQUALS, GREATER_THAN_EQUALS, 값) + - `updatedDate` (object, 선택): 업데이트 날짜로 필터링 (연산자와 값) + - `dueDate` (object, 선택): 마감일로 필터링 (연산자와 값) + - `sort_by` (string, 선택): 정렬 필드 - 옵션: created_at, updated_at, priority, status, ticket_type + - `sort_order` (string, 선택): 정렬 방향 - 옵션: asc, desc + + + + +### **사용자 관리** + + + + **설명:** Zendesk에서 새로운 사용자를 생성합니다. + + **매개변수:** + - `name` (string, 필수): 사용자의 전체 이름 + - `email` (string, 선택): 사용자의 이메일 주소 (예: "jane@example.com") + - `phone` (string, 선택): 사용자의 전화번호 + - `role` (string, 선택): 사용자 역할 - 옵션: admin, agent, end-user + - `externalId` (string, 선택): 다른 시스템의 고유 식별자 + - `details` (string, 선택): 추가 사용자 정보 + - `notes` (string, 선택): 사용자에 대한 내부 메모 + + + + + **설명:** 기존 사용자의 정보를 업데이트합니다. + + **매개변수:** + - `userId` (string, 필수): 업데이트할 사용자의 ID + - `name` (string, 선택): 업데이트할 사용자 이름 + - `email` (string, 선택): 업데이트할 이메일 (업데이트 시 보조 이메일로 추가됨) + - `phone` (string, 선택): 업데이트할 전화번호 + - `role` (string, 선택): 업데이트할 역할 - 옵션: admin, agent, end-user + - `externalId` (string, 선택): 업데이트된 외부 ID + - `details` (string, 선택): 업데이트된 사용자 상세 정보 + - `notes` (string, 선택): 업데이트된 내부 메모 + + + + + **설명:** ID로 특정 사용자를 조회합니다. + + **매개변수:** + - `userId` (string, 필수): 조회할 사용자 ID + + + + + **설명:** 다양한 기준으로 사용자를 검색합니다. + + **매개변수:** + - `name` (string, 선택): 사용자 이름으로 필터링 + - `email` (string, 선택): 사용자 이메일로 필터링 (예: "jane@example.com") + - `role` (string, 선택): 역할로 필터링 - 옵션: admin, agent, end-user + - `externalId` (string, 선택): 외부 ID로 필터링 + - `sort_by` (string, 선택): 정렬 필드 - 옵션: created_at, updated_at + - `sort_order` (string, 선택): 정렬 방향 - 옵션: asc, desc + + + + +### **관리 도구** + + + + **설명:** 티켓에 사용할 수 있는 모든 표준 및 맞춤 필드를 검색합니다. + + **파라미터:** + - `paginationParameters` (object, 선택 사항): 페이지네이션 설정 + - `pageCursor` (string, 선택 사항): 페이지네이션을 위한 페이지 커서 + + + + + **설명:** 티켓의 감사 기록(읽기 전용 이력)을 가져옵니다. + + **파라미터:** + - `ticketId` (string, 선택 사항): 특정 티켓의 감사를 조회합니다(비워두면 모든 비보관된 티켓의 감사를 조회, 예: "1234") + - `paginationParameters` (object, 선택 사항): 페이지네이션 설정 + - `pageCursor` (string, 선택 사항): 페이지네이션을 위한 페이지 커서 + + + + +## 커스텀 필드 + +커스텀 필드를 사용하면 조직에 특화된 추가 정보를 저장할 수 있습니다: + +```json +[ + { "id": 27642, "value": "745" }, + { "id": 27648, "value": "yes" } +] +``` + +## 티켓 우선순위 레벨 + +우선순위 레벨 이해하기: + +- **긴급** - 즉각적인 조치가 필요한 치명적 이슈 +- **높음** - 신속하게 해결해야 하는 중요한 이슈 +- **보통** - 대부분의 티켓에 해당하는 표준 우선순위 +- **낮음** - 여유가 있을 때 처리해도 되는 사소한 이슈 + +## 티켓 상태 워크플로우 + +표준 티켓 상태 진행: + +- **new** - 최근에 생성됨, 아직 할당되지 않음 +- **open** - 현재 작업 중 +- **pending** - 고객 응답 또는 외부 조치 대기 중 +- **hold** - 일시 중지됨 +- **solved** - 문제가 해결되어 고객 확인 대기 중 +- **closed** - 티켓이 완료되어 종료됨 + +## 사용 예시 + +### 기본 Zendesk 에이전트 설정 + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Zendesk capabilities +zendesk_agent = Agent( + role="Support Manager", + goal="Manage customer support tickets and provide excellent customer service", + backstory="An AI assistant specialized in customer support operations and ticket management.", + apps=['zendesk'] +) + +# Task to create a new support ticket +create_ticket_task = Task( + description="Create a high-priority support ticket for John Smith who is unable to access his account after password reset", + agent=zendesk_agent, + expected_output="Support ticket created successfully with ticket ID" +) + +# Run the task +crew = Crew( + agents=[zendesk_agent], + tasks=[create_ticket_task] +) + +crew.kickoff() +``` + +### 특정 Zendesk 도구 필터링 + +```python + +support_agent = Agent( + role="Customer Support Agent", + goal="Handle customer inquiries and resolve support issues efficiently", + backstory="An experienced support agent who specializes in ticket resolution and customer communication.", + apps=['zendesk'] +) + +# Task to manage support workflow +support_task = Task( + description="Create a ticket for login issues, add troubleshooting comments, and update status to resolved", + agent=support_agent, + expected_output="Support ticket managed through complete resolution workflow" +) + +crew = Crew( + agents=[support_agent], + tasks=[support_task] +) + +crew.kickoff() +``` + +### 고급 티켓 관리 + +```python +from crewai import Agent, Task, Crew + +ticket_manager = Agent( + role="Ticket Manager", + goal="Manage support ticket workflows and ensure timely resolution", + backstory="An AI assistant that specializes in support ticket triage and workflow optimization.", + apps=['zendesk'] +) + +# Task to manage ticket lifecycle +ticket_workflow = Task( + description=""" + 1. 계정 접근 문제에 대한 새로운 지원 티켓을 생성합니다. + 2. 문제 해결 단계를 내부 노트에 추가합니다. + 3. 고객 등급에 따라 티켓 우선순위를 업데이트합니다. + 4. 해결 코멘트를 추가하고 티켓을 종료합니다. + """, + agent=ticket_manager, + expected_output="티켓 생성부터 해결까지 전체 생명주기 관리" +) + +crew = Crew( + agents=[ticket_manager], + tasks=[ticket_workflow] +) + +crew.kickoff() +``` + +### 지원 분석 및 보고 + +```python +from crewai import Agent, Task, Crew + +support_analyst = Agent( + role="Support Analyst", + goal="Analyze support metrics and generate insights for team performance", + backstory="An analytical AI that excels at extracting insights from support data and ticket patterns.", + apps=['zendesk'] +) + +# Complex task involving analytics and reporting +analytics_task = Task( + description=""" + 1. Search for all open tickets from the last 30 days + 2. Analyze ticket resolution times and customer satisfaction + 3. Identify common issues and support patterns + 4. Generate weekly support performance report + """, + agent=support_analyst, + expected_output="Comprehensive support analytics report with performance insights and recommendations" +) + +crew = Crew( + agents=[support_analyst], + tasks=[analytics_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/ko/enterprise/introduction.mdx b/docs/v1.15.1/ko/enterprise/introduction.mdx new file mode 100644 index 000000000..078153778 --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/introduction.mdx @@ -0,0 +1,99 @@ +--- +title: "CrewAI 엔터프라이즈" +description: "AI 에이전트 워크플로우를 배포, 모니터링 및 확장하세요" +icon: "globe" +mode: "wide" +--- + +## 소개 + +CrewAI AMP(Agent Management Platform)는 프로덕션 환경에서 crew와 agent를 배포, 모니터링, 확장할 수 있는 플랫폼을 제공합니다. + + + CrewAI AMP Dashboard + + +CrewAI AOP는 오픈 소스 프레임워크의 강력함에 프로덕션 배포, 협업, 확장성을 위한 기능을 더했습니다. crew를 관리형 인프라에 배포하고, 실행을 실시간으로 모니터링하세요. + +## 주요 기능 + + + + 몇 번의 클릭만으로 관리형 인프라에 crew를 배포하세요 + + + 기존 시스템과의 통합을 위해 REST API를 통해 배포된 crew에 접근하세요 + + + 상세한 실행 추적과 로그로 crew를 모니터링하세요 + + + crew의 역량을 강화할 수 있도록 도구를 게시하고 설치하세요 + + + 실시간 이벤트와 업데이트를 시스템으로 스트리밍하세요 + + + 노코드/로코드 인터페이스로 crew를 생성 및 커스터마이즈하세요 + + + +## 배포 옵션 + + + + 코드 배포를 위해 GitHub 리포지토리에 직접 연결하세요 + + + 코드 없는 Crew Studio 인터페이스를 통해 생성된 crew를 배포하세요 + + + 더 고급 배포 워크플로우를 위해 CrewAI CLI를 사용하세요 + + + +## 시작하기 + + + + [app.crewai.com](https://app.crewai.com)에서 계정을 생성하세요 + + 가입하기 + + + + 코드 또는 Crew Studio를 사용하여 crew를 만드세요 + + Crew 만들기 + + + + crew를 Enterprise 플랫폼에 배포하세요 + + Crew 배포 + + + + 생성된 API 엔드포인트를 통해 crew와 연동하세요 + + Crew API 사용 + + + + +자세한 안내를 원하시면 [배포 가이드](/ko/enterprise/guides/deploy-to-amp)를 확인하거나 아래 버튼을 클릭해 시작하세요. diff --git a/docs/v1.15.1/ko/enterprise/resources/frequently-asked-questions.mdx b/docs/v1.15.1/ko/enterprise/resources/frequently-asked-questions.mdx new file mode 100644 index 000000000..0ef430a5b --- /dev/null +++ b/docs/v1.15.1/ko/enterprise/resources/frequently-asked-questions.mdx @@ -0,0 +1,151 @@ +--- +title: 자주 묻는 질문 +description: "CrewAI AOP에 대한 자주 묻는 질문" +icon: "circle-question" +mode: "wide" +--- + + + + 계층적 프로세스에서는 매니저 에이전트가 자동으로 생성되어 워크플로우를 조정하고, 작업을 위임하며 결과를 검증하여 효율적이고 체계적으로 작업이 수행되도록 합니다. 매니저 에이전트는 하위 에이전트에게 작업을 위임하고 실행을 지원하기 위해 도구를 활용합니다. 매니저 LLM은 계층적 프로세스에서 매우 중요하며, 적절한 작동을 위해 반드시 올바르게 설정되어야 합니다. + + + + CrewAI에 대한 최신 문서는 공식 문서 사이트에서 확인하실 수 있습니다: https://docs.crewai.com/ + CrewAI 문서 + + + + #### 계층적 프로세스: + - 명확한 지휘 체계에 따라 작업이 위임 및 실행됨 + - 매니저 에이전트에 대해 manager language model(`manager_llm`)을 반드시 지정해야 함 + - 매니저 에이전트가 작업 실행, 계획, 위임, 검증을 총괄함 + - 작업이 사전에 지정되지 않으며, 매니저가 각 에이전트의 역량에 따라 작업을 할당함 + + #### 순차적 프로세스: + - 작업이 순서대로 하나씩 실행되어 작업들이 순차적으로 진행됨 + - 이전 작업의 결과가 다음 작업의 맥락이 됨 + - 작업 실행이 작업 리스트에 정의된 순서대로 진행됨 + + #### 복잡한 프로젝트에 더 적합한 프로세스는 무엇입니까? + 계층적 프로세스는 다음과 같은 이유로 복잡한 프로젝트에 더 적합합니다: + - **동적 작업 할당과 위임**: 매니저 에이전트가 에이전트의 역량에 따라 작업을 할당할 수 있음 + - **구조화된 검증과 감독**: 매니저 에이전트가 작업 결과를 검토하고 완료를 보장함 + - **복잡한 작업 관리**: 에이전트 수준에서의 도구 사용 제어 등 세밀한 관리 가능 + + + + - **적응적 학습**: crew는 시간이 지날수록 더 효율적으로 적응하며, 새로운 정보에 맞춰 작업 방식을 개선하게 됩니다. + - **개인화된 경험 강화**: 메모리를 통해 에이전트가 사용자 선호도나 과거 상호작용을 기억하여 더욱 개인화된 경험을 제공합니다. + - **문제 해결력 향상**: 풍부한 메모리 접근을 통해 과거의 학습이나 맥락적 인사이트를 적용하여 에이전트가 더 나은 결정을 내릴 수 있습니다. + + + + 에이전트의 최대 RPM 제한을 설정하면 외부 서비스에 과도하게 요청을 보내지 않도록 하여, 제한에 걸리는 일을 예방하고 성능을 향상시킬 수 있습니다. + + + + 인간 입력을 통해 에이전트는 필요할 때 추가 정보나 설명을 요청할 수 있습니다. 이 기능은 복잡한 의사결정 과정이나, 에이전트가 작업을 효과적으로 완료하는 데 더 많은 세부 정보가 필요할 때 매우 중요합니다. + + 에이전트 실행에 인간 입력을 통합하려면 작업 정의에서 `human_input` 플래그를 설정하세요. 활성화하면, 에이전트가 최종 답변을 제공하기 전에 사용자에게 입력을 요청합니다. 이 입력은 추가 맥락을 제공하거나, 애매함을 해소하거나, 에이전트의 출력을 검증해야 할 때 활용될 수 있습니다. + + 자세한 구현 방법은 [Human-in-the-Loop 가이드](/ko/enterprise/guides/human-in-the-loop)를 참고해 주세요. + + + + CrewAI는 다양한 고급 커스터마이징 옵션을 제공합니다: + + - **Language Model 커스터마이징**: 에이전트별로 특정 language model(`llm`) 및 function-calling language model(`function_calling_llm`)을 지정 가능 + - **성능 및 디버깅 설정**: 에이전트의 성능을 조정하고 동작을 모니터링할 수 있음 + - **Verbose 모드**: 에이전트의 작업 로그를 자세하게 기록하여 디버깅 및 최적화에 활용할 수 있음 + - **RPM 제한**: 분당 최대 요청 수(`max_rpm`) 설정 + - **최대 반복 횟수**: `max_iter` 속성으로 에이전트가 한 작업에서 허용되는 반복 횟수를 지정 + - **위임 및 자율성 제어**: `allow_delegation` 속성(기본값: True)으로 에이전트의 위임 또는 질문 가능 여부 제어 + - **인간 입력 통합**: 필요 시 추가 정보나 설명을 사용자에게 요청할 수 있음 + + + + 인간 입력이 특히 유용한 경우는 다음과 같습니다: + - **에이전트가 추가 정보나 설명이 필요할 때**: 에이전트가 애매하거나 불완전한 데이터를 만날 때 + - **에이전트가 복잡하거나 민감한 결정을 내려야 할 때**: 윤리적이거나 미묘한 결정이 필요한 경우 인간 입력이 보조할 수 있음 + - **에이전트 출력의 감독 및 검증이 필요할 때**: 결과 검증과 오류 방지에 도움 + - **에이전트 행동을 커스터마이징 할 때**: 피드백을 통해 에이전트의 응답을 지속적으로 개선 + - **오류 및 한계 식별 및 해결 시**: 에이전트의 한계점이나 오류를 인간 입력으로 해결 가능 + + + + CrewAI에서 제공되는 메모리의 종류는 다음과 같습니다: + - **단기 메모리**: 즉각적인 맥락을 위한 임시 저장소 + - **장기 메모리**: 학습된 패턴 및 정보의 영구 저장소 + - **엔티티 메모리**: 특정 엔티티와 그 속성에 집중하는 저장소 + - **컨텍스추얼 메모리**: 상호작용 간 맥락을 유지하는 메모리 + + 다른 메모리 유형에 대해 자세히 알아보려면: + CrewAI 메모리 + + + + 작업에서 Output Pydantic을 사용하려면, 해당 작업의 예상 결과를 Pydantic 모델로 정의해야 합니다. 빠른 예시는 다음과 같습니다: + + + + ```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 + ) + ``` + + + + 에이전트가 항상 구조화된 출력을 내도록 만드는 방법 관련 튜토리얼은 아래 영상을 참고하세요: + + + + + CrewAI에서 제공하는 `BaseTool` 클래스를 상속받아 커스텀 도구를 직접 만들거나, tool 데코레이터를 활용할 수 있습니다. 상속 방식은 `BaseTool`을 상속하는 새로운 클래스를 정의해 이름, 설명, 그리고 실제 논리를 처리하는 `_run` 메서드를 작성합니다. tool 데코레이터를 사용하면 필수 속성과 운영 로직만 정의해 바로 `Tool` 객체를 만들 수 있습니다. + + CrewAI 도구 가이드 + + + + `max_rpm` 속성을 설정하면 crew 전체가 분당 보낼 수 있는 최대 요청 수를 제한할 수 있습니다. 이를 설정하면 개별 에이전트의 `max_rpm` 값보다 우선적으로 적용됩니다. + + diff --git a/docs/v1.15.1/ko/examples/cookbooks.mdx b/docs/v1.15.1/ko/examples/cookbooks.mdx new file mode 100644 index 000000000..9b835cd1b --- /dev/null +++ b/docs/v1.15.1/ko/examples/cookbooks.mdx @@ -0,0 +1,23 @@ +--- +title: CrewAI Cookbooks +description: 패턴을 빠르게 익히기 위한 기능 중심 Quickstarts와 노트북. +icon: book +mode: "wide" +--- + +## Quickstarts & Demos + + + + 특정 CrewAI 기능을 보여주는 데모와 소규모 프로젝트. + + + 실습을 위한 인터랙티브 노트북. + + + + +Cookbooks로 패턴을 빠르게 익힌 뒤, 프로덕션급 구현은 Full Examples에서 확인하세요. + + + diff --git a/docs/v1.15.1/ko/examples/example.mdx b/docs/v1.15.1/ko/examples/example.mdx new file mode 100644 index 000000000..68dcccc5d --- /dev/null +++ b/docs/v1.15.1/ko/examples/example.mdx @@ -0,0 +1,86 @@ +--- +title: CrewAI 예시 +description: Crews, Flows, 통합, Notebooks로 구성된 예시 모음입니다. +icon: rocket-launch +mode: "wide" +--- + +## Crews + + + + 다중 에이전트 마케팅 캠페인 기획. + + + 개인화된 여행 계획. + + + 벡터 검색 기반 이력서 매칭. + + + 채용 공고 자동 생성. + + + 파이썬 게임을 설계·구축하는 멀티 에이전트 팀. + + + 후보자 소싱 및 평가. + + + 전체 crew 예시 목록. + + + +## Flows + + + + 라우팅 기반 콘텐츠 생성. + + + 이메일 모니터링과 자동 응답. + + + 휴먼‑인‑더‑루프 리드 평가. + + + 노트 처리 및 연동. + + + 반복적 자가 개선 워크플로우. + + + 병렬 챕터 생성. + + + 전체 flow 예시 목록. + + + +## 통합 (Integrations) + + + + LangGraph 프레임워크 연동. + + + Azure OpenAI와 함께 사용. + + + NVIDIA 생태계 연동. + + + 전체 통합 예시. + + + +## 노트북 (Notebooks) + + + + Simple QA Crew + Flow. + + + 학습과 실험을 위한 인터랙티브 예시 모음. + + \ No newline at end of file diff --git a/docs/v1.15.1/ko/guides/advanced/customizing-prompts.mdx b/docs/v1.15.1/ko/guides/advanced/customizing-prompts.mdx new file mode 100644 index 000000000..c65b86abe --- /dev/null +++ b/docs/v1.15.1/ko/guides/advanced/customizing-prompts.mdx @@ -0,0 +1,331 @@ +--- +title: 프롬프트 커스터마이징 +description: CrewAI를 위한 저수준 프롬프트 커스터마이징에 대해 자세히 알아보고, 다양한 모델과 언어에 대해 매우 맞춤화되고 복잡한 사용 사례를 구현할 수 있습니다. +icon: message-pen +mode: "wide" +--- + +## 프롬프트를 커스터마이즈해야 하는 이유 + +CrewAI의 기본 프롬프트는 많은 시나리오에서 잘 작동하지만, 저수준 커스터마이징은 훨씬 더 유연하고 강력한 에이전트 행동으로 이어집니다. 더 깊은 제어를 통해 얻을 수 있는 이점은 다음과 같습니다: + +1. **특정 LLM에 맞게 최적화** – GPT-4, Claude, Llama와 같은 다양한 모델은 각자의 고유한 아키텍처에 맞는 프롬프트 형식에서 최고의 성능을 발휘합니다. +2. **언어 변경** – 영어를 넘어서는 언어로만 작동하는 에이전트를 구축하여 미묘한 뉘앙스도 정확하게 처리할 수 있습니다. +3. **복잡한 도메인에 특화** – 헬스케어, 금융, 법률 등 매우 전문적인 산업군에 맞춰 프롬프트를 조정할 수 있습니다. +4. **톤과 스타일 조정** – 에이전트의 톤과 스타일을 좀 더 형식적, 캐주얼, 창의적, 혹은 분석적으로 만들 수 있습니다. +5. **초고도 커스텀 사례 지원** – 복잡하고 프로젝트에 특화된 요구사항을 충족하기 위해 고급 프롬프트 구조 및 포맷을 활용할 수 있습니다. + +이 가이드에서는 CrewAI의 프롬프트를 더 낮은 레벨에서 활용하여, 에이전트의 사고 및 상호작용 방식을 세밀하게 제어하는 방법을 다룹니다. + +## CrewAI의 Prompt 시스템 이해하기 + +내부적으로 CrewAI는 광범위하게 커스터마이즈할 수 있는 모듈식 prompt 시스템을 사용합니다: + +- **Agent 템플릿** – 각 agent가 할당된 역할을 수행하는 방식을 결정합니다. +- **Prompt 슬라이스** – 작업, 도구 사용, 출력 구조와 같은 특수한 동작을 제어합니다. +- **오류 처리** – agent가 실패, 예외, 또는 타임아웃에 어떻게 반응할지 지정합니다. +- **도구별 prompt** – 도구가 호출되거나 사용되는 방법에 대한 상세 지침을 정의합니다. + +이 요소들이 어떻게 구성되어 있는지 보려면 [CrewAI 저장소의 원본 prompt 템플릿](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json)을 확인하세요. 여기서 필요에 따라 오버라이드하거나 수정하여 고급 동작을 구현할 수 있습니다. + +## 기본 시스템 지침 이해하기 + + +**프로덕션 투명성 문제**: CrewAI는 여러분이 인지하지 못하는 사이에 기본 지침을 프롬프트에 자동으로 삽입합니다. 이 섹션에서는 내부적으로 어떤 일이 일어나고 있는지와 완전한 제어권을 얻는 방법을 설명합니다. + + +여러분이 `role`, `goal`, `backstory`로 에이전트를 정의할 때, CrewAI는 형식 및 동작을 제어하는 추가 시스템 지침을 자동으로 추가합니다. 이러한 기본 삽입을 이해하는 것은 완전한 프롬프트 투명성이 필요한 프로덕션 시스템에서 매우 중요합니다. + +### CrewAI가 자동으로 삽입하는 내용 + +에이전트 구성에 따라 CrewAI는 다양한 기본 지침을 추가합니다: + +#### 도구가 없는 에이전트를 위한 안내 +```text +"I MUST use these formats, my job depends on it!" +``` + +#### 도구가 있는 에이전트를 위한 안내 +```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... +``` + +#### 구조화된 출력(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." +``` + +### 전체 시스템 프롬프트 보기 + +LLM에 전달되는 프롬프트가 정확히 무엇인지 확인하려면, 생성된 프롬프트를 확인할 수 있습니다: + +```python +from crewai import Agent, Crew, Task +from crewai.utilities.prompts import Prompts + +# 에이전트 생성 +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 +) + +# 샘플 태스크 생성 +task = Task( + description="Analyze the sales data and identify trends", + expected_output="A detailed analysis with key insights and trends", + agent=agent +) + +# 프롬프트 생성기 생성 +prompt_generator = Prompts( + agent=agent, + has_tools=len(agent.tools) > 0, + use_system_prompt=agent.use_system_prompt +) + +# 실제 프롬프트 생성 및 확인 +generated_prompt = prompt_generator.task_execution() + +# 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"]) + +# 태스크 설명이 어떻게 포맷되는지도 확인할 수 있습니다 +print("\n=== TASK CONTEXT ===") +print(f"Task Description: {task.description}") +print(f"Expected Output: {task.expected_output}") +``` + +### 기본 지침 재정의 + +프롬프트에 대한 완전한 제어를 얻기 위해 여러 가지 옵션이 있습니다: + +#### 옵션 1: 커스텀 템플릿 (권장) +```python +from crewai import Agent + +# Define your own system template without default instructions +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 separate system/user messages +) +``` + +#### 옵션 2: 사용자 지정 프롬프트 파일 +특정 프롬프트 슬라이스를 오버라이드하려면 `custom_prompts.json` 파일을 생성하세요: + +```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}" + } +} +``` + +그런 다음 crew에서 사용하세요: + +```python +crew = Crew( + agents=[agent], + tasks=[task], + prompt_file="custom_prompts.json", + verbose=True +) +``` + + +`agent.i18n`은 이전 버전과의 호환성을 위해서만 유지되며 사용이 중단될 예정입니다. 런타임 프롬프트 커스터마이징에는 `Crew`에 `prompt_file`을 전달하세요. 프롬프트 슬라이스를 코드에서 직접 읽어야 한다면 i18n 유틸리티를 직접 사용하세요: + + +```python +from crewai.utilities.i18n import get_i18n + +i18n = get_i18n("custom_prompts.json") +format_slice = i18n.slice("format") +tool_prompt = i18n.tools("ask_question") +``` + +#### 옵션 3: o1 모델에 대한 시스템 프롬프트 비활성화 +```python +agent = Agent( + role="Analyst", + goal="Analyze data", + backstory="Expert analyst", + use_system_prompt=False # Disables system prompt separation +) +``` + +### 관측 도구를 활용한 디버깅 + +프로덕션 투명성을 위해 관측 플랫폼과 통합하여 모든 prompt 및 LLM 상호작용을 모니터링하세요. 이를 통해 LLM에 어떤 prompt(기본 지침 포함)가 전송되고 있는지 정확히 확인할 수 있습니다. + +다양한 플랫폼(Langfuse, MLflow, Weights & Biases, 커스텀 로깅 솔루션 등)과의 통합에 대한 자세한 가이드는 [관측 문서](/ko/observability/overview)를 참고하세요. + +### 프로덕션을 위한 모범 사례 + +1. **프로덕션에 배포하기 전에 반드시 생성된 prompt를 점검하세요** +2. **prompt 내용을 완전히 제어해야 할 경우에는 커스텀 템플릿을 사용하세요** +3. **지속적인 prompt 모니터링을 위해 관측 도구를 통합하세요** ([Observability 문서](/ko/observability/overview) 참고) +4. **서로 다른 LLM으로 테스트하세요**. 기본 instruction은 모델마다 다르게 작동할 수 있습니다 +5. **팀 투명성을 위해 prompt 커스터마이징을 문서화하세요** + + +기본 instruction은 일관된 agent 동작을 보장하기 위해 존재하지만, 도메인 특화 요구사항과 충돌할 수 있습니다. 위의 커스터마이징 옵션을 사용하여 프로덕션 시스템에서 agent의 동작을 완전히 제어할 수 있습니다. + + +## 프롬프트 파일 관리 모범 사례 + +저수준 프롬프트 커스터마이징을 수행할 때는 다음 지침을 따라 조직적이고 유지 관리가 용이하도록 하세요: + +1. **파일 분리** – 커스터마이징한 프롬프트는 메인 코드베이스 외부의 전용 JSON 파일에 저장하세요. +2. **버전 관리** – 리포지토리 내에서 변경 사항을 추적하여 프롬프트 조정 내역이 명확히 문서화되도록 하세요. +3. **모델 또는 언어별 정리** – `prompts_llama.json` 또는 `prompts_es.json`과 같이 네이밍 스킴을 사용해 특화된 구성을 빠르게 식별할 수 있도록 하세요. +4. **변경 사항 문서화** – 주석을 추가하거나 README를 유지 관리하여 커스터마이징의 목적과 범위를 상세히 기술하세요. +5. **수정 최소화** – 실제로 조정이 필요한 특정 부분만 오버라이드하고, 나머지 부분은 기본 기능을 유지하세요. + +## 프롬프트를 커스터마이즈하는 가장 간단한 방법 + +가장 간단한 접근 방법 중 하나는 오버라이드하려는 프롬프트에 대한 JSON 파일을 생성한 다음, 해당 파일을 Crew에 지정하는 것입니다. + +1. 업데이트된 프롬프트 슬라이스로 JSON 파일을 만드세요. +2. Crew의 `prompt_file` 파라미터를 통해 그 파일을 참조하세요. + +그러면 CrewAI가 기본값과 사용자가 지정한 내용을 병합하므로, 모든 프롬프트를 다시 정의할 필요가 없습니다. 방법은 다음과 같습니다: + +프롬프트 슬라이스를 코드에서 직접 읽어야 하는 경우에는 `agent.i18n`을 읽는 대신 동일한 프롬프트 파일로 `crewai.utilities.i18n.get_i18n()`을 사용하세요. + +### 예시: 기본 프롬프트 커스터마이징 + +수정하고 싶은 프롬프트를 포함하는 `custom_prompts.json` 파일을 생성하세요. 변경 사항만이 아니라 포함해야 하는 모든 최상위 프롬프트를 반드시 나열해야 합니다: + +```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" + } +} +``` + +그 다음 아래와 같이 통합하세요: + +```python +from crewai import Agent, Crew, Task, Process + +# 평소와 같이 에이전트와 태스크를 생성 +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 +) + +# 커스텀 프롬프트 파일로 crew를 생성 +crew = Crew( + agents=[researcher], + tasks=[research_task], + prompt_file="path/to/custom_prompts.json", + verbose=True +) + +# crew 실행 +result = crew.kickoff() +``` + +이 몇 가지 간단한 수정으로, agent가 소통하고 태스크를 해결하는 방식을 세밀하게 제어할 수 있습니다. + +## 특정 모델에 맞춘 최적화 + +모델마다 잘 동작하는 프롬프트의 구조가 다릅니다. 프롬프트를 모델의 뉘앙스에 맞게 더욱 깊이 있게 조정하면 성능이 크게 향상될 수 있습니다. + +### 예시: Llama 3.3 프롬프트 템플릿 + +예를 들어, Meta의 Llama 3.3과 작업할 때는 더 깊은 수준의 커스터마이징이 다음에 설명된 권장 구조를 반영할 수 있습니다: +https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template + +다음은 Llama 3.3을 코드에서 활용하도록 Agent를 세밀하게 튜닝하는 방법을 보여주는 예시입니다: + +```python +from crewai import Agent, Crew, Task, Process +from crewai_tools import DirectoryReadTool, FileReadTool + +# Define templates for system, user (prompt), and assistant (response) messages +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|>""" + +# Create an Agent using Llama-specific layouts +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", # Using the Llama 3 model + system_template=system_template, + prompt_template=prompt_template, + response_template=response_template, + tools=[DirectoryReadTool(), FileReadTool()] +) + +# Define a sample task +engineering_task = Task( + description="Review AI implementation files for potential improvements", + expected_output="A summary of key findings and recommendations", + agent=principal_engineer +) + +# Create a Crew for the task +llama_crew = Crew( + agents=[principal_engineer], + tasks=[engineering_task], + process=Process.sequential, + verbose=True +) + +# Execute the crew +result = llama_crew.kickoff() +print(result.raw) +``` + +이와 같이 더 심도 있는 설정을 통해 별도의 JSON 파일 없이도 Llama 기반 워크플로에 대해 포괄적이고 저수준의 제어를 할 수 있습니다. + +## 결론 + +CrewAI에서의 저수준 prompt 커스터마이제이션은 매우 맞춤화되고 복잡한 사용 사례에 대한 문을 엽니다. 잘 구성된 prompt 파일(또는 직접 작성한 인라인 템플릿)을 구축함으로써 다양한 모델, 언어, 특화된 도메인을 수용할 수 있습니다. 이러한 수준의 유연성 덕분에 원하는 AI 동작을 정확하게 설계할 수 있으며, override하지 않을 경우에도 CrewAI가 신뢰할 수 있는 기본값을 제공한다는 점에서 안심할 수 있습니다. + + +이제 CrewAI에서 고급 prompt 커스터마이징을 위한 기초를 갖추었습니다. 모델별 구조나 도메인별 제약에 맞춰 적용하든, 이러한 저수준 접근 방식은 agent 상호작용을 매우 전문적으로 조정할 수 있게 해줍니다. + diff --git a/docs/v1.15.1/ko/guides/advanced/fingerprinting.mdx b/docs/v1.15.1/ko/guides/advanced/fingerprinting.mdx new file mode 100644 index 000000000..bc4b4e320 --- /dev/null +++ b/docs/v1.15.1/ko/guides/advanced/fingerprinting.mdx @@ -0,0 +1,134 @@ +--- +title: 지문 인식 +description: CrewAI의 지문 인식 시스템을 사용하여 컴포넌트를 전체 라이프사이클 동안 고유하게 식별하고 추적하는 방법을 알아보세요. +icon: fingerprint +mode: "wide" +--- + +## 개요 + +CrewAI의 Fingerprints는 컴포넌트를 고유하게 식별하고 그 생애주기를 추적할 수 있는 방법을 제공합니다. 각 `Agent`, `Crew`, `Task`는 생성 시 자동으로 고유한 fingerprint를 부여받으며, 이는 수동으로 변경할 수 없습니다. + +이러한 fingerprints는 다음과 같은 용도로 사용할 수 있습니다: +- 컴포넌트 사용 감사 및 추적 +- 컴포넌트 식별 무결성 보장 +- 컴포넌트에 메타데이터 첨부 +- 추적 가능한 작업 체인 생성 + +## 지문(Fingerprints)의 작동 방식 + +지문(fingerprint)은 `crewai.security` 모듈의 `Fingerprint` 클래스의 인스턴스입니다. 각 지문에는 다음과 같은 정보가 포함되어 있습니다: + +- UUID 문자열: 컴포넌트의 고유 식별자로, 자동으로 생성되며 수동으로 설정할 수 없습니다. +- 생성 타임스탬프: 지문이 생성된 시점을 나타내며, 자동으로 설정되고 수동으로 수정할 수 없습니다. +- 메타데이터: 추가 정보를 담은 사전(dictionary)으로, 사용자 정의가 가능합니다. + +지문은 컴포넌트가 생성될 때 자동으로 생성되어 할당됩니다. 각 컴포넌트는 읽기 전용 속성을 통해 자신의 지문을 제공합니다. + +## 기본 사용법 + +### 지문 접근하기 + +```python +from crewai import Agent, Crew, Task + +# Create components - fingerprints are automatically generated +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 +) + +# Access the fingerprints +agent_fingerprint = agent.fingerprint +crew_fingerprint = crew.fingerprint +task_fingerprint = task.fingerprint + +# Print the UUID strings +print(f"Agent fingerprint: {agent_fingerprint.uuid_str}") +print(f"Crew fingerprint: {crew_fingerprint.uuid_str}") +print(f"Task fingerprint: {task_fingerprint.uuid_str}") +``` + +### 지문 메타데이터 작업 + +지문에 추가적인 맥락 정보를 제공하기 위해 메타데이터를 추가할 수 있습니다: + +```python +# Add metadata to the agent's fingerprint +agent.security_config.fingerprint.metadata = { + "version": "1.0", + "department": "Data Science", + "project": "Customer Analysis" +} + +# Access the metadata +print(f"Agent metadata: {agent.fingerprint.metadata}") +``` + +## 지문(Fingerprint) 지속성 + +지문은 컴포넌트의 생애 주기 전체에 걸쳐 지속되고 변하지 않도록 설계되었습니다. 컴포넌트를 수정하더라도 지문은 동일하게 유지됩니다: + +```python +original_fingerprint = agent.fingerprint.uuid_str + +# Modify the agent +agent.goal = "New goal for analysis" + +# The fingerprint remains unchanged +assert agent.fingerprint.uuid_str == original_fingerprint +``` + +## 결정론적 지문 + +UUID와 생성 타임스탬프를 직접 설정할 수는 없지만, `generate` 메서드와 시드(seed)를 사용하여 결정론적 지문을 만들 수 있습니다: + +```python +from crewai.security import Fingerprint + +# 시드 문자열을 사용하여 결정론적 지문 생성 +deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id") + +# 동일한 시드로 항상 동일한 지문이 생성됨 +same_fingerprint = Fingerprint.generate(seed="my-agent-id") +assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str + +# 메타데이터도 설정할 수 있음 +custom_fingerprint = Fingerprint.generate( + seed="my-agent-id", + metadata={"version": "1.0"} +) +``` + +## 고급 사용 + +### Fingerprint 구조 + +각 fingerprint는 다음과 같은 구조를 가지고 있습니다: + +```python +from crewai.security import Fingerprint + +fingerprint = agent.fingerprint + +# UUID 문자열 - 고유 식별자 (자동 생성) +uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000" + +# 생성 타임스탬프 (자동 생성) +created_at = fingerprint.created_at # datetime 객체 + +# 메타데이터 - 추가 정보용 (사용자 지정 가능) +metadata = fingerprint.metadata # 딕셔너리, 기본값은 {} +``` \ No newline at end of file diff --git a/docs/v1.15.1/ko/guides/agents/crafting-effective-agents.mdx b/docs/v1.15.1/ko/guides/agents/crafting-effective-agents.mdx new file mode 100644 index 000000000..b7ec97a7c --- /dev/null +++ b/docs/v1.15.1/ko/guides/agents/crafting-effective-agents.mdx @@ -0,0 +1,454 @@ +--- +title: 효과적인 에이전트 제작 +description: 복잡한 문제를 효과적으로 해결하기 위해 협업하는 강력하고 전문화된 AI 에이전트를 설계하는 모범 사례를 배워보세요. +icon: robot +mode: "wide" +--- + +## 에이전트 설계의 예술과 과학 + +CrewAI의 핵심에는 에이전트가 있습니다. 에이전트는 협업 프레임워크 내에서 특정 역할을 수행하도록 설계된 전문화된 AI 엔터티입니다. 기본적인 에이전트를 만드는 것은 간단하지만, 진정으로 효과적이고 탁월한 결과를 만들어내는 에이전트를 설계하려면 주요 설계 원칙과 모범 사례를 이해해야 합니다. + +이 가이드는 여러분이 에이전트 설계의 예술을 마스터할 수 있도록 도와줍니다. 이를 통해 효과적으로 협업하고, 비판적으로 사고하며, 특정 요구에 맞춤화된 고품질 결과물을 만들어내는 전문화된 AI 페르소나를 설계할 수 있게 됩니다. + +### 에이전트 설계가 중요한 이유 + +에이전트를 정의하는 방식은 다음에 중대한 영향을 미칩니다: + +1. **출력 품질**: 잘 설계된 에이전트는 더 관련성 높고, 품질이 뛰어난 결과를 생성합니다 +2. **협업 효율성**: 상호 보완적인 역량을 가진 에이전트들이 함께 더 효율적으로 작업합니다 +3. **작업 성과**: 명확한 역할과 목표를 가진 에이전트가 작업을 더 효과적으로 수행합니다 +4. **시스템 확장성**: 신중하게 설계된 에이전트는 여러 crew와 다양한 컨텍스트에서 재사용될 수 있습니다 + +이러한 측면에서 뛰어난 에이전트를 만들기 위한 모범 사례를 함께 살펴보겠습니다. + +## 80/20 법칙: 에이전트보다 작업에 집중하세요 + +효과적인 AI 시스템을 구축할 때 이 중요한 원칙을 기억하세요: **노력의 80%는 작업 설계에, 20%만 에이전트 정의에 투자해야 합니다**. + +왜일까요? 아무리 완벽하게 정의된 에이전트라도 잘못된 작업 설계에서는 실패하지만, 잘 설계된 작업은 단순한 에이전트까지도 뛰어나게 만들 수 있기 때문입니다. 즉, + +- 대부분의 시간을 명확한 작업 지침 작성에 할애하세요 +- 상세한 입력과 예상 결과를 정의하세요 +- 실행을 안내할 예시와 컨텍스트를 추가하세요 +- 남은 시간에는 에이전트 역할, 목표, 배경에 집중하세요 + +이는 에이전트 설계가 중요하지 않다는 의미가 아닙니다. 분명히 중요합니다. 하지만 실행 실패의 대부분은 작업 설계에서 발생하므로, 그에 따라 우선순위를 두어야 합니다. + +## 효과적인 에이전트 설계의 핵심 원칙 + +### 1. 역할-목표-배경 이야기 프레임워크 + +CrewAI에서 가장 강력한 에이전트는 세 가지 핵심 요소의 탄탄한 기반 위에 구축됩니다: + +#### 역할: 에이전트의 전문화된 기능 + +역할은 에이전트가 수행하는 일과 전문 분야를 정의합니다. 역할을 설계할 때는 다음을 준수하세요: + +- **구체적이고 전문적으로 작성하세요**: "작가" 대신 "기술 문서 전문가"나 "창의적 스토리텔러"처럼 명확하게 표현하세요. +- **현실 세계의 직업과 일치시키세요**: 역할을 잘 알려진 직업 유형에 기반하세요. +- **도메인 전문성을 포함하세요**: 에이전트의 지식 분야를 명확히 하세요 (예: "시장 동향에 특화된 금융 분석가"). + +**효과적인 역할 예시:** +```yaml +role: "Senior UX Researcher specializing in user interview analysis" +role: "Full-Stack Software Architect with expertise in distributed systems" +role: "Corporate Communications Director specializing in crisis management" +``` + +#### 목표: 에이전트의 목적과 동기 + +목표는 에이전트의 노력을 이끌고 의사 결정 과정을 형성합니다. 효과적인 목표는 다음과 같아야 합니다: + +- **명확하고 결과 중심적이어야 함**: 에이전트가 달성하려는 것이 무엇인지 정의합니다. +- **품질 기준을 강조해야 함**: 작업의 품질에 대한 기대치를 포함합니다. +- **성공 기준을 통합해야 함**: "좋음"이 무엇인지 에이전트가 이해할 수 있도록 도와줍니다. + +**효과적인 목표의 예시:** +```yaml +goal: "Uncover actionable user insights by analyzing interview data and identifying recurring patterns, unmet needs, and improvement opportunities" +goal: "Design robust, scalable system architectures that balance performance, maintainability, and cost-effectiveness" +goal: "Craft clear, empathetic crisis communications that address stakeholder concerns while protecting organizational reputation" +``` + +#### 배경 이야기: 에이전트의 경험과 관점 + +배경 이야기는 에이전트에게 깊이를 부여하며, 문제를 해결하고 타인과 상호작용하는 방식에 영향을 미칩니다. 좋은 배경 이야기는 다음과 같습니다: + +- **전문성과 경험을 확립**: 에이전트가 어떻게 자신의 기술을 습득했는지 설명합니다. +- **업무 스타일 및 가치를 정의**: 에이전트가 일에 어떻게 접근하는지 설명합니다. +- **통합된 페르소나 생성**: 배경 이야기의 모든 요소가 역할과 목표에 부합하는지 확인합니다. + +**효과적인 배경 이야기 예시:** +```yaml +backstory: "You have spent 15 years conducting and analyzing user research for top tech companies. You have a talent for reading between the lines and identifying patterns that others miss. You believe that good UX is invisible and that the best insights come from listening to what users don't say as much as what they do say." + +backstory: "With 20+ years of experience building distributed systems at scale, you've developed a pragmatic approach to software architecture. You've seen both successful and failed systems and have learned valuable lessons from each. You balance theoretical best practices with practical constraints and always consider the maintenance and operational aspects of your designs." + +backstory: "As a seasoned communications professional who has guided multiple organizations through high-profile crises, you understand the importance of transparency, speed, and empathy in crisis response. You have a methodical approach to crafting messages that address concerns while maintaining organizational credibility." +``` + +### 2. 전문가가 일반가보다 우수함 + +에이전트는 일반적인 역할보다 전문화된 역할을 부여할 때 훨씬 더 우수한 성능을 보입니다. 고도로 집중된 에이전트는 더 정확하고 관련성 높은 결과물을 제공합니다: + +**일반적 (효과 적음):** +```yaml +role: "Writer" +``` + +**전문화 (효과 좋음):** +```yaml +role: "Technical Blog Writer specializing in explaining complex AI concepts to non-technical audiences" +``` + +**전문가의 이점:** +- 기대되는 출력물에 대한 더 명확한 이해 +- 더 일관된 성과 +- 특정 작업과의 더 나은 정렬 +- 도메인별 판단능력 향상 + +### 3. 전문화와 다재다능성의 균형 + +효과적인 에이전트는 전문성(한 가지를 매우 잘하는 것)과 다재다능성(다양한 상황에 적응할 수 있는 것) 사이에서 적절한 균형을 이룹니다: + +- **역할에 전문화하고, 적용에는 다재다능하게**: 여러 맥락에서 적용할 수 있는 전문 기술을 가진 에이전트를 만드세요 +- **지나치게 좁은 정의는 피하기**: 에이전트가 자신이 전문으로 하는 영역 내에서 다양한 변형을 처리할 수 있도록 하세요 +- **협업 맥락을 고려하기**: 함께 일하게 될 다른 에이전트들과 전문 분야가 상호 보완될 수 있도록 에이전트를 설계하세요 + +### 4. 적절한 전문성 수준 설정 + +에이전트에게 할당하는 전문성 수준은 작업 접근 방식에 영향을 미칩니다: + +- **초급 에이전트**: 단순한 작업, 브레인스토밍, 초기 초안에 적합 +- **중급 에이전트**: 대부분의 표준 작업에서 신뢰성 있는 실행에 적합 +- **전문가 에이전트**: 깊이와 세밀함이 요구되는 복잡하고 전문적인 작업에 최적 +- **월드 클래스 에이전트**: 예외적인 품질이 필요한 중요한 작업에 할당 + +작업의 복잡성과 품질 요구 사항에 따라 적합한 전문성 수준을 선택하세요. 대부분의 협업 crew에서는 다양한 전문성 수준이 어우러지는 것이 가장 효과적이며, 핵심 전문 기능에는 더 높은 전문성을 배정하는 것이 좋습니다. + +## 실제 예시: 적용 전과 적용 후 + +이러한 모범 사례를 적용하기 전과 후의 agent 정의 예시를 살펴보겠습니다: + +### 예시 1: 콘텐츠 제작 에이전트 + +**이전:** +```yaml +role: "Writer" +goal: "Write good content" +backstory: "You are a writer who creates content for websites." +``` + +**이후:** +```yaml +role: "B2B Technology Content Strategist" +goal: "Create compelling, technically accurate content that explains complex topics in accessible language while driving reader engagement and supporting business objectives" +backstory: "You have spent a decade creating content for leading technology companies, specializing in translating technical concepts for business audiences. You excel at research, interviewing subject matter experts, and structuring information for maximum clarity and impact. You believe that the best B2B content educates first and sells second, building trust through genuine expertise rather than marketing hype." +``` + +### 예시 2: 리서치 에이전트 + +**변경 전:** +```yaml +role: "Researcher" +goal: "Find information" +backstory: "You are good at finding information online." +``` + +**변경 후:** +```yaml +role: "Academic Research Specialist in Emerging Technologies" +goal: "Discover and synthesize cutting-edge research, identifying key trends, methodologies, and findings while evaluating the quality and reliability of sources" +backstory: "With a background in both computer science and library science, you've mastered the art of digital research. You've worked with research teams at prestigious universities and know how to navigate academic databases, evaluate research quality, and synthesize findings across disciplines. You're methodical in your approach, always cross-referencing information and tracing claims to primary sources before drawing conclusions." +``` + +## 에이전트를 위한 효과적인 작업 설계하기 + +에이전트 설계도 중요하지만, 작업 설계는 성공적인 실행을 위해 매우 중요합니다. 에이전트가 성공할 수 있도록 작업을 설계할 때 참고할 수 있는 모범 사례는 다음과 같습니다: + +### 효과적인 작업의 구조 + +잘 설계된 작업은 서로 다른 목적을 가진 두 가지 주요 구성 요소를 가지고 있습니다: + +#### 작업 설명: 프로세스 +설명은 무엇을 어떻게 해야 하는지에 초점을 맞춰야 하며, 아래를 포함해야 합니다: +- 실행을 위한 상세 지침 +- 맥락 및 배경 정보 +- 범위 및 제약 조건 +- 따라야 할 프로세스 단계 + +#### 예상 산출물: 결과물 +예상 산출물은 최종 결과가 어떻게 보여야 하는지 정의해야 합니다: +- 형식 명세(마크다운, JSON 등) +- 구조 요구사항 +- 품질 기준 +- 좋은 결과물의 예시(가능할 경우) + +### 작업 설계 모범 사례 + +#### 1. 단일 목적, 단일 산출물 +작업은 하나의 명확한 목표에 집중할 때 가장 좋은 성과를 냅니다: + +**나쁜 예시(너무 광범위함):** +```yaml +task_description: "Research market trends, analyze the data, and create a visualization." +``` + +**좋은 예시(집중됨):** +```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. 입력 및 출력 명시 + +항상 작업에 사용할 입력값과 출력이 어떻게 보여야 하는지 명확하게 지정하세요: + +**예시:** +```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. 목적 및 맥락 포함 +작업이 왜 중요한지, 더 큰 워크플로우에서 어떻게 맞물리는지 설명하세요: + +**예시:** +```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. 구조화된 출력 도구 사용하기 +기계가 읽을 수 있는 출력을 위해서, 포맷을 명확히 지정하세요: + +**예시:** +```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." +``` + +## 피해야 할 일반적인 실수 + +실제 구현에서 얻은 교훈을 바탕으로, 에이전트 및 태스크 설계에서 가장 흔한 실수는 다음과 같습니다: + +### 1. 불명확한 작업 지시 + +**문제:** 작업에 충분한 세부 정보가 없어 에이전트가 효과적으로 실행하기 어렵습니다. + +**잘못 설계된 예시:** +```yaml +research_task: + description: "Research AI trends." + expected_output: "A report on AI trends." +``` + +**개선된 버전:** +```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. 너무 많은 작업을 시도하는 "God Tasks" + +**문제:** 여러 복잡한 작업을 하나의 지시 세트로 결합하는 태스크. + +**잘못된 설계 예시:** +```yaml +comprehensive_task: + description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline." +``` + +**개선된 버전:** +이 작업을 순차적이고 집중된 태스크로 분리하세요: +```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. 설명과 기대 출력 불일치 + +**문제:** 작업 설명에서 요구하는 내용과 기대 출력이 서로 다릅니다. + +**설계가 미흡한 예시:** +```yaml +analysis_task: + description: "Analyze customer feedback to find areas of improvement." + expected_output: "A marketing plan for the next quarter." +``` + +**개선된 버전:** +```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. 당신이 직접 프로세스를 이해하지 못함 + +**문제:** 당신이 완전히 이해하지 못하는 작업을 에이전트에게 수행하도록 요청함. + +**해결책:** +1. 먼저 직접 작업을 수동으로 수행해보세요 +2. 프로세스, 의사결정 지점, 정보 출처를 문서화하세요 +3. 이 문서를 작업 설명의 기초로 사용하세요 + +### 5. 계층 구조의 조기 사용 + +**문제:** 순차적인 프로세스만으로도 충분한 경우에 불필요하게 복잡한 에이전트 계층 구조를 만드는 것. + +**해결 방법:** 우선 순차적 프로세스부터 시작하고, 워크플로우의 복잡성이 정말로 필요할 때만 계층적 모델로 전환하세요. + +### 6. 모호하거나 일반적인 에이전트 정의 + +**문제:** 일반적인 에이전트 정의는 일반적인 결과로 이어집니다. + +**잘못된 설계 예시:** +```yaml +agent: + role: "Business Analyst" + goal: "Analyze business data" + backstory: "You are good at business analysis." +``` + +**개선된 버전:** +```yaml +agent: + role: "SaaS Metrics Specialist focusing on growth-stage startups" + goal: "Identify actionable insights from business data that can directly impact customer retention and revenue growth" + backstory: "With 10+ years analyzing SaaS business models, you've developed a keen eye for the metrics that truly matter for sustainable growth. You've helped numerous companies identify the leverage points that turned around their business trajectory. You believe in connecting data to specific, actionable recommendations rather than general observations." +``` + +## 고급 에이전트 설계 전략 + +### 협업을 위한 설계 + +여러 agent가 crew 내에서 함께 작업할 때 다음 사항을 고려하십시오: + +- **상호 보완적인 스킬**: 각기 다르지만 상호 보완되는 능력을 가진 agent를 설계하세요. +- **업무 인계 시점**: agent 간에 작업이 어떻게 전달될지 명확한 인터페이스를 정의하세요. +- **건설적인 긴장감**: 때때로 약간씩 다른 관점을 가진 agent를 만들면 생산적인 대화를 통해 더 나은 결과를 이끌어낼 수 있습니다. + +예를 들어, 콘텐츠 제작 crew는 다음과 같이 구성될 수 있습니다: + +```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..." +``` + +### 전문화된 도구 사용자 생성 + +일부 agent는 특정 도구를 효과적으로 활용하도록 특별히 설계될 수 있습니다: + +```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] +``` + +### LLM 기능에 맞춘 에이전트 맞춤화 + +다양한 LLM은 서로 다른 강점을 가지고 있습니다. 이러한 기능을 염두에 두고 에이전트를 설계하세요: + +```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 +``` + +## 에이전트 설계 테스트 및 반복 + +에이전트 설계는 종종 반복적인 과정입니다. 다음은 실용적인 접근 방식입니다: + +1. **프로토타입으로 시작하기**: 초기 에이전트 정의 생성 +2. **샘플 작업으로 테스트하기**: 대표적인 작업에서 성능 평가 +3. **출력물 분석**: 강점과 약점 파악 +4. **정의 수정**: 관찰에 따라 역할, 목표, 백스토리 조정 +5. **협업 테스트**: 에이전트가 crew 환경에서 어떻게 작동하는지 평가 + +## 결론 + +효과적인 agent를 만드는 것은 예술이자 과학입니다. 여러분의 특정 요구에 맞춘 역할, 목표, 그리고 backstory를 신중하게 정의하고, 잘 설계된 task와 결합함으로써 뛰어난 결과를 만들어내는 전문화된 AI 협업자를 만들 수 있습니다. + +agent와 task의 설계는 반복적인 과정임을 기억하세요. 이러한 모범 사례로 시작하여 agent가 실제로 동작하는 모습을 관찰하고, 배운 점을 바탕으로 접근 방식을 개선하세요. 그리고 항상 80/20 법칙을 명심하세요. agent로부터 최고의 결과를 얻기 위해서는 명확하고 집중된 task를 만드는 데 대부분의 노력을 집중하는 것이 중요합니다. + + +축하합니다! 이제 효과적인 agent 설계의 원칙과 실천법을 이해하셨습니다. 이 기술들을 적용하여 강력하고 전문화된 agent들이 복잡한 task를 매끄럽게 협력하여 완수할 수 있도록 만드세요. + + +## 다음 단계 + +- 특정 사용 사례에 맞는 다양한 agent 구성을 실험해 보세요 +- [첫 crew 만들기](/ko/guides/crews/first-crew)에 대해 배우며 agent들이 어떻게 함께 작동하는지 확인해 보세요 +- 더 발전된 오케스트레이션을 위해 [CrewAI Flows](/ko/guides/flows/first-flow)를 탐색해 보세요 \ No newline at end of file diff --git a/docs/v1.15.1/ko/guides/coding-tools/agents-md.mdx b/docs/v1.15.1/ko/guides/coding-tools/agents-md.mdx new file mode 100644 index 000000000..d95184ac9 --- /dev/null +++ b/docs/v1.15.1/ko/guides/coding-tools/agents-md.mdx @@ -0,0 +1,61 @@ +--- +title: 코딩 도구 +description: AGENTS.md를 사용하여 CrewAI 프로젝트 전반에서 코딩 에이전트와 IDE를 안내합니다. +icon: terminal +mode: "wide" +--- + +## AGENTS.md를 사용하는 이유 + +`AGENTS.md`는 가벼운 저장소 로컬 지침 파일로, 코딩 에이전트에게 일관되고 프로젝트별 안내를 제공합니다. 프로젝트 루트에 배치하고 어시스턴트가 작업하는 방식(컨벤션, 명령어, 아키텍처 노트, 가드레일)에 대한 신뢰할 수 있는 소스로 활용하세요. + +## CLI로 프로젝트 생성 + +CrewAI CLI를 사용하여 프로젝트를 스캐폴딩하면, `AGENTS.md`가 루트에 자동으로 추가됩니다. + +```bash +# Crew +crewai create crew my_crew + +# Flow +crewai create flow my_flow + +# Tool repository +crewai tool create my_tool +``` + +## 도구 설정: 어시스턴트에 AGENTS.md 연결 + +### Codex + +Codex는 저장소에 배치된 `AGENTS.md` 파일로 안내할 수 있습니다. 컨벤션, 명령어, 워크플로우 기대치 등 지속적인 프로젝트 컨텍스트를 제공하는 데 사용하세요. + +### Claude Code + +Claude Code는 프로젝트 메모리를 `CLAUDE.md`에 저장합니다. `/init`으로 부트스트랩하고 `/memory`로 편집할 수 있습니다. Claude Code는 `CLAUDE.md` 내에서 임포트도 지원하므로, `@AGENTS.md`와 같은 한 줄을 추가하여 공유 지침을 중복 없이 가져올 수 있습니다. + +간단하게 다음과 같이 사용할 수 있습니다: + +```bash +mv AGENTS.md CLAUDE.md +``` + +### Gemini CLI와 Google Antigravity + +Gemini CLI와 Antigravity는 저장소 루트 및 상위 디렉토리에서 프로젝트 컨텍스트 파일(기본값: `GEMINI.md`)을 로드합니다. Gemini CLI 설정에서 `context.fileName`을 설정하여 `AGENTS.md`를 대신(또는 추가로) 읽도록 구성할 수 있습니다. 예를 들어, `AGENTS.md`만 설정하거나 각 도구의 형식을 유지하고 싶다면 `AGENTS.md`와 `GEMINI.md`를 모두 포함할 수 있습니다. + +간단하게 다음과 같이 사용할 수 있습니다: + +```bash +mv AGENTS.md GEMINI.md +``` + +### Cursor + +Cursor는 `AGENTS.md`를 프로젝트 지침 파일로 지원합니다. 프로젝트 루트에 배치하여 Cursor의 코딩 어시스턴트에 안내를 제공하세요. + +### Windsurf + +Claude Code는 Windsurf와의 공식 통합을 제공합니다. Windsurf 내에서 Claude Code를 사용하는 경우, 위의 Claude Code 안내를 따르고 `CLAUDE.md`에서 `AGENTS.md`를 임포트하세요. + +Windsurf의 네이티브 어시스턴트를 사용하는 경우, 프로젝트 규칙 또는 지침 기능(사용 가능한 경우)을 구성하여 `AGENTS.md`에서 읽거나 내용을 직접 붙여넣으세요. diff --git a/docs/v1.15.1/ko/guides/coding-tools/build-with-ai.mdx b/docs/v1.15.1/ko/guides/coding-tools/build-with-ai.mdx new file mode 100644 index 000000000..5ea75ab54 --- /dev/null +++ b/docs/v1.15.1/ko/guides/coding-tools/build-with-ai.mdx @@ -0,0 +1,214 @@ +--- +title: "AI와 함께 빌드하기" +description: "CrewAI로 빌드·배포·확장하는 데 필요한 모든 것 — 스킬, 기계가 읽을 수 있는 문서, 배포, 엔터프라이즈 기능을 AI 코딩 에이전트용으로 정리했습니다." +icon: robot +mode: "wide" +--- + +# AI와 함께 빌드하기 + +CrewAI는 AI 네이티브입니다. 이 페이지는 Claude Code, Codex, Cursor, Gemini CLI 등 개발자가 crew와 flow를 배포하도록 돕는 코딩 에이전트가 CrewAI로 빌드할 때 필요한 내용을 한곳에 모았습니다. + +### 지원 코딩 에이전트 + + + + + + + + + + + 이 페이지는 사람과 AI 어시스턴트 모두를 위해 작성되었습니다. 코딩 에이전트라면 CrewAI 맥락은 **Skills**부터, 전체 문서 접근은 **llms.txt**를 사용하세요. + + +--- + +## 1. Skills — 에이전트에게 CrewAI 가르치기 + +**Skills**는 코딩 에이전트에게 Flow 스캐폴딩, Crew 구성, 도구 사용, 프레임워크 관례 등 CrewAI에 대한 깊은 지식을 담은 지침 묶음입니다. + + + + Anthropic + CrewAI 스킬은 **Claude Code 플러그인 마켓플레이스**에서 제공됩니다. AI 네이티브 기업들이 쓰는 것과 같은 배포 채널입니다. + ```shell + /plugin marketplace add crewAIInc/skills + /plugin install crewai-skills@crewai-plugins + /reload-plugins + ``` + + CrewAI와 관련된 질문을 하면 다음 네 가지 스킬이 자동으로 활성화됩니다. + + | 스킬 | 실행 시점 | + |------|-------------| + | `getting-started` | 새 프로젝트 스캐폴딩, `LLM.call()` / `Agent` / `Crew` / `Flow` 선택, `crew.jsonc` / `main.py` 연결 | + | `design-agent` | 에이전트 구성 — 역할, 목표, 배경 이야기, 도구, LLM, 메모리, 가드레일 | + | `design-task` | 태스크 설명, 의존성, 구조화된 출력(`output_pydantic`, `output_json`), 사람 검토 | + | `ask-docs` | 최신 API 정보를 위해 [CrewAI 문서 MCP 서버](https://docs.crewai.com/mcp) 조회 | + + + Claude Code, Codex, Cursor, Gemini CLI 등 모든 코딩 에이전트에서 사용할 수 있습니다. + ```shell + npx skills add crewaiinc/skills + ``` + [skills.sh 레지스트리](https://skills.sh/crewaiinc/skills)에서 가져옵니다. + + + + + + 위 방법 중 하나를 사용하세요 — Claude Code 플러그인 마켓플레이스 또는 `npx skills add`. 둘 다 공식 [crewAIInc/skills](https://github.com/crewAIInc/skills) 팩을 설치합니다. + + + 스킬 팩이 에이전트에게 알려 주는 내용: + - **Flow** — 상태ful 앱, 단계, crew 킥오프 + - **Crew 및 에이전트** — JSON-first 패턴(`crew.jsonc`, `agents/*.jsonc`), 역할, 태스크, 위임 + - **도구 및 통합** — 검색, API, MCP 서버, 일반적인 CrewAI 도구 + - **프로젝트 레이아웃** — CLI 스캐폴드와 저장소 관례 + - **최신 패턴** — 현재 CrewAI 문서와 모범 사례 반영 + + + 매 세션마다 프레임워크를 다시 설명하지 않아도 에이전트가 CrewAI 프로젝트를 스캐폴딩하고 빌드할 수 있습니다. + + + + + + CrewAI 에이전트에서 스킬이 동작하는 방식 — 주입, 활성화, 패턴. + + + crewAIInc/skills 팩 개요와 포함 내용. + + + Claude Code, Codex, Cursor, Gemini CLI용 AGENTS.md 설정. + + + 공식 목록 — 스킬, 설치 통계, 감사 정보. + + + +--- + +## 2. llms.txt — 기계가 읽을 수 있는 문서 + +CrewAI는 AI 어시스턴트가 전체 문서에 기계가 읽을 수 있는 형태로 바로 접근할 수 있도록 `llms.txt` 파일을 제공합니다. + +``` +https://docs.crewai.com/llms.txt +``` + + + + [`llms.txt`](https://llmstxt.org/)는 문서를 대규모 언어 모델이 소비하기 쉽게 만드는 새로운 표준입니다. HTML을 스크래핑하는 대신, 필요한 내용이 담긴 하나의 구조화된 텍스트 파일을 가져올 수 있습니다. + + CrewAI의 `llms.txt`는 **이미 제공 중**이며, 에이전트가 바로 사용할 수 있습니다. + + + CrewAI 참고 문서가 필요할 때 코딩 에이전트에 URL을 알려 주세요. + + ``` + Fetch https://docs.crewai.com/llms.txt for CrewAI documentation. + ``` + + Claude Code, Cursor 등 많은 코딩 에이전트가 URL을 직접 가져올 수 있습니다. 파일에는 CrewAI 개념, API, 가이드를 아우르는 구조화된 문서가 포함되어 있습니다. + + + - **스크래핑 불필요** — 한 번의 요청으로 깔끔한 구조화 콘텐츠 + - **항상 최신** — docs.crewai.com에서 직접 제공 + - **LLM에 최적화** — 브라우저가 아니라 컨텍스트 윈도우에 맞게 포맷 + - **스킬과 상호 보완** — 스킬은 패턴을, llms.txt는 참조를 제공 + + + +--- + +## 3. 엔터프라이즈에 배포 + +로컬 crew를 몇 분 안에 **CrewAI AMP**(Agent Management Platform) 프로덕션으로 가져가세요. + + + + crew 또는 flow를 스캐폴딩하고 테스트합니다. + ```bash + crewai create crew my_crew + cd my_crew + crewai run + ``` + + + 프로젝트 구조가 준비되었는지 확인합니다. + ```bash + crewai deploy --prepare + ``` + 구조와 요구 사항은 [준비 가이드](/ko/enterprise/guides/prepare-for-deployment)를 참고하세요. + + + CrewAI AMP 플랫폼으로 푸시합니다. + ```bash + crewai deploy + ``` + [GitHub 연동](/ko/enterprise/guides/deploy-to-amp) 또는 [Crew Studio](/ko/enterprise/guides/enable-crew-studio)로도 배포할 수 있습니다. + + + 배포된 crew는 REST API 엔드포인트를 받습니다. 모든 애플리케이션에 통합할 수 있습니다. + ```bash + curl -X POST https://app.crewai.com/api/v1/crews//kickoff \ + -H "Authorization: Bearer $CREWAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"inputs": {"topic": "AI agents"}}' + ``` + + + + + + 전체 배포 가이드 — CLI, GitHub, Crew Studio 방법. + + + 플랫폼 개요 — 프로덕션 crew에 AMP가 제공하는 것. + + + +--- + +## 4. 엔터프라이즈 기능 + +CrewAI AMP는 프로덕션 팀을 위해 만들어졌습니다. 배포 외에 제공되는 것은 다음과 같습니다. + + + + 모든 crew 실행에 대한 상세 실행 추적, 로그, 성능 지표. 에이전트 결정, 도구 호출, 태스크 완료를 실시간으로 모니터링합니다. + + + 시각적으로 crew를 만들고, 맞춤 설정하고, 배포하는 노코드/로코드 인터페이스 — 코드로 보내거나 바로 배포할 수 있습니다. + + + crew 실행에서 실시간 이벤트를 시스템으로 스트리밍합니다. Slack, Zapier 등 웹훅 소비자와 연동할 수 있습니다. + + + SSO, RBAC, 조직 단위 제어. 팀 전체에서 crew 생성·배포·접근 권한을 관리합니다. + + + 조직 전체에 맞춤 도구를 게시하고 공유합니다. 레지스트리에서 커뮤니티 도구를 설치합니다. + + + 자체 인프라에서 CrewAI AMP를 실행합니다. 데이터 상주와 규정 준수 제어와 함께 플랫폼 전체 기능을 사용할 수 있습니다. + + + + + + AI 에이전트 워크플로를 프로토타입에서 프로덕션으로 옮겨야 하는 팀을 위한 제품입니다. 관측 가능성, 접근 제어, 확장 가능한 인프라를 제공합니다. 스타트업이든 대기업이든 운영 복잡도는 AMP가 맡고, 에이전트 구축에 집중할 수 있습니다. + + + - **클라우드 (app.crewai.com)** — CrewAI가 관리, 프로덕션까지 가장 빠른 경로 + - **Factory(셀프 호스팅)** — 데이터 통제를 위해 자체 인프라에서 실행 + - **하이브리드** — 민감도에 따라 클라우드와 셀프 호스팅을 혼합 + + + + + 가입하고 첫 crew를 프로덕션에 배포해 보세요. + diff --git a/docs/v1.15.1/ko/guides/concepts/evaluating-use-cases.mdx b/docs/v1.15.1/ko/guides/concepts/evaluating-use-cases.mdx new file mode 100644 index 000000000..ff9a3c335 --- /dev/null +++ b/docs/v1.15.1/ko/guides/concepts/evaluating-use-cases.mdx @@ -0,0 +1,504 @@ +--- +title: CrewAI 사용 사례 평가 +description: AI 애플리케이션 요구 사항을 평가하고 복잡성과 정밀도 요구 사항에 따라 Crews와 Flows 중 올바른 접근 방식을 선택하는 방법을 알아보세요. +icon: scale-balanced +mode: "wide" +--- + +## 의사결정 프레임워크 이해하기 + +CrewAI로 AI 애플리케이션을 구축할 때 가장 중요한 결정 중 하나는 특정 사용 사례에 적합한 방식을 선택하는 것입니다. Crew를 사용할까요? Flow를 사용할까요? 아니면 둘의 조합을 사용할까요? 이 가이드는 요구 사항을 평가하고 정보에 기반한 아키텍처 결정을 내리는 데 도움이 됩니다. + +이 결정의 핵심은 애플리케이션에서의 **복잡성**과 **정밀성**의 관계를 이해하는 것입니다: + + + 복잡성 vs. 정밀성 매트릭스 + + +이 매트릭스를 통해 다양한 방식이 복잡성과 정밀성에 대한 요구 사항과 어떻게 일치하는지 시각적으로 확인할 수 있습니다. 각 사분면이 의미하는 바와 그것이 아키텍처 선택에 어떻게 도움이 되는지 함께 살펴보겠습니다. + +## 복잡성-정밀도 행렬 설명 + +### 복잡성이란 무엇인가? + +CrewAI 애플리케이션의 맥락에서 **복잡성**은 다음을 의미합니다: + +- 요구되는 뚜렷한 단계 또는 작업 수 +- 수행해야 할 작업의 다양성 +- 서로 다른 구성 요소 간의 상호 의존성 +- 조건부 로직과 분기의 필요성 +- 전체 워크플로우의 정교함 + +### 정밀성이란 무엇인가? + +**정밀성**은 이 맥락에서 다음을 의미합니다: + +- 최종 결과물에 요구되는 정확성 +- 구조화되고 예측 가능한 결과의 필요성 +- 재현성의 중요성 +- 각 단계에 대한 통제 수준 +- 출력의 변동 허용치 + +### 네 가지 사분면 + +#### 1. 낮은 복잡도, 낮은 정밀도 + +**특징:** +- 단순하고 직관적인 작업 +- 출력 결과의 일부 변형 허용 +- 제한된 단계 수 +- 창의적이거나 탐색적인 응용 + +**권장 접근법:** 최소한의 에이전트를 가진 Simple Crews + +**예시 사용 사례:** +- 기본 콘텐츠 생성 +- 아이디어 브레인스토밍 +- 간단한 요약 작업 +- 창의적 글쓰기 보조 + +#### 2. 낮은 복잡성, 높은 정밀도 + +**특징:** +- 정확하고 구조화된 결과물이 요구되는 단순한 워크플로우 +- 재현 가능한 결과가 필요한 경우 +- 단계는 제한적이지만, 높은 정확도가 요구됨 +- 주로 데이터 처리 또는 변환이 포함됨 + +**권장 방식:** 직접적인 LLM 호출이나 구조화된 출력이 있는 간단한 Crew 사용 + +**예시 활용 사례:** +- 데이터 추출 및 변환 +- 양식 작성 및 검증 +- 구조화된 콘텐츠 생성(JSON, XML) +- 단순 분류 작업 + +#### 3. 높은 복잡성, 낮은 정밀도 + +**특징:** +- 여러 단계로 이루어진 다단계 프로세스 +- 창의적이거나 탐색적인 출력물 +- 구성 요소 간의 복잡한 상호작용 +- 최종 결과의 변동성 허용 + +**권장 접근 방식:** 여러 전문화된 agent가 포함된 Complex Crew + +**예시 사용 사례:** +- 연구 및 분석 +- 콘텐츠 생성 파이프라인 +- 탐색적 데이터 분석 +- 창의적 문제 해결 + +#### 4. 높은 복잡성, 높은 정밀도 + +**특징:** +- 구조화된 산출물이 요구되는 복잡한 워크플로 +- 엄격한 정확성 요구사항을 가진 여러 상호 의존적인 단계 +- 정교한 처리와 정밀한 결과 모두 필요 +- 종종 임무에 중요한 애플리케이션 + +**권장 접근 방식:** 검증 단계를 포함한 여러 Crew를 오케스트레이션하는 Flows + +**예시 사용 사례:** +- 엔터프라이즈 의사결정 지원 시스템 +- 복잡한 데이터 처리 파이프라인 +- 다단계 문서 처리 +- 규제 산업 애플리케이션 + +## 크루와 플로우 중에서 선택하기 + +### Crews를 선택해야 할 때 + +Crews는 다음과 같은 경우에 이상적입니다: + +1. **협업 지능이 필요할 때** - 서로 다른 전문성을 가진 여러 agent들이 함께 작업해야 할 때 +2. **문제가 창발적 사고를 요구할 때** - 다양한 관점과 접근 방식에서의 해결책이 이득이 될 때 +3. **작업이 주로 창의적이거나 분석적일 때** - 작업이 리서치, 콘텐츠 제작, 분석을 포함할 때 +4. **엄격한 구조보다는 적응력을 중시할 때** - agent의 자율성이 workflow에 도움이 될 때 +5. **출력 형식이 다소 유연할 수 있을 때** - 출력 구조에 약간의 변동이 허용될 때 + +```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() +``` + +### 플로우를 선택해야 할 때 + +플로우는 다음과 같은 경우에 이상적입니다: + +1. **실행에 대한 정밀한 제어가 필요할 때** - 워크플로우에 정확한 순서 지정과 상태 관리가 필요한 경우 +2. **애플리케이션에 복잡한 상태 요구사항이 있을 때** - 여러 단계에 걸쳐 상태를 유지하고 변환해야 하는 경우 +3. **구조화되고 예측 가능한 출력이 필요할 때** - 애플리케이션에서 일관되고 포맷된 결과가 필요한 경우 +4. **워크플로우에 조건부 로직이 포함될 때** - 중간 결과에 따라 다른 경로를 선택해야 하는 경우 +5. **AI와 절차적 코드를 결합해야 할 때** - 솔루션에 AI 기능과 전통적인 프로그래밍이 모두 필요한 경우 + +```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() +``` + +### 크루와 플로우를 결합해야 할 때 + +가장 정교한 애플리케이션은 종종 크루와 플로우를 결합할 때 이점을 얻습니다: + +1. **복잡한 다단계 프로세스** - 플로우를 사용해 전체 프로세스를 오케스트레이션하고, 크루를 통해 복잡한 하위 작업을 처리합니다. +2. **창의성과 구조가 모두 필요한 애플리케이션** - 창의적인 작업에는 크루를 사용하고, 구조적인 처리는 플로우로 처리합니다. +3. **엔터프라이즈급 AI 애플리케이션** - 플로우로 상태 및 프로세스 흐름을 관리하면서, 크루를 활용해 특화된 작업을 수행합니다. + +```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() +``` + +## 실용적인 평가 프레임워크 + +특정 사용 사례에 맞는 올바른 접근 방식을 결정하려면 다음 단계별 평가 프레임워크를 따르세요: + +### 1단계: 복잡성 평가 + +아래와 같은 기준으로 애플리케이션의 복잡성을 1~10점 척도로 평가하세요: + +1. **단계 수**: 얼마나 많은 개별 작업이 필요한가요? + - 1-3단계: 낮은 복잡성 (1-3) + - 4-7단계: 중간 복잡성 (4-7) + - 8단계 이상: 높은 복잡성 (8-10) + +2. **상호 의존성**: 서로 다른 부분 간의 연결성은 어느 정도인가요? + - 의존성이 거의 없음: 낮은 복잡성 (1-3) + - 다소 의존성 있음: 중간 복잡성 (4-7) + - 복잡한 다중 의존성: 높은 복잡성 (8-10) + +3. **조건부 논리**: 얼마나 많은 분기 및 의사결정이 필요한가요? + - 선형 프로세스: 낮은 복잡성 (1-3) + - 분기가 일부 있음: 중간 복잡성 (4-7) + - 복잡한 결정 트리: 높은 복잡성 (8-10) + +4. **도메인 지식**: 요구되는 지식의 전문성은 어느 정도인가요? + - 일반적인 지식: 낮은 복잡성 (1-3) + - 일부 전문 지식 필요: 중간 복잡성 (4-7) + - 여러 도메인에 대한 깊은 전문성 필요: 높은 복잡성 (8-10) + +평균 점수를 계산하여 전체 복잡성을 결정하세요. + +### 2단계: 정밀도 요구사항 평가 + +정밀도 요구사항을 1-10점 척도로 평가하세요. 다음을 고려합니다: + +1. **출력 구조**: 출력이 얼마나 구조화되어야 합니까? + - 자유형 텍스트: 낮은 정밀도 (1-3) + - 반구조화: 중간 정밀도 (4-7) + - 엄격한 포맷(JSON, XML): 높은 정밀도 (8-10) + +2. **정확성 필요성**: 사실적 정확성이 얼마나 중요합니까? + - 창의적 콘텐츠: 낮은 정밀도 (1-3) + - 정보성 콘텐츠: 중간 정밀도 (4-7) + - 중요한 정보: 높은 정밀도 (8-10) + +3. **재현성**: 실행마다 결과가 얼마나 일관되어야 합니까? + - 변동 허용: 낮은 정밀도 (1-3) + - 어느 정도 일관성 필요: 중간 정밀도 (4-7) + - 정확한 재현성 필요: 높은 정밀도 (8-10) + +4. **오류 허용도**: 오류의 영향은 어느 정도입니까? + - 영향 적음: 낮은 정밀도 (1-3) + - 영향 보통: 중간 정밀도 (4-7) + - 영향 큼: 높은 정밀도 (8-10) + +평균 점수를 계산하여 전체 정밀도 요구사항을 결정하세요. + +### 3단계: 매트릭스에 매핑하기 + +복잡도와 정밀도 점수를 매트릭스에 표시하세요: + +- **낮은 복잡도(1-4), 낮은 정밀도(1-4)**: Simple Crews +- **낮은 복잡도(1-4), 높은 정밀도(5-10)**: 직접적인 LLM 호출이 있는 Flows +- **높은 복잡도(5-10), 낮은 정밀도(1-4)**: Complex Crews +- **높은 복잡도(5-10), 높은 정밀도(5-10)**: Crews를 오케스트레이션하는 Flows + +### 4단계: 추가 요소 고려 + +복잡성과 정밀성 외에도 다음을 고려하세요: + +1. **개발 시간**: crew는 프로토타입을 더 빠르게 만들 수 있습니다 +2. **유지보수 필요**: flow는 장기적인 유지보수에 더 적합합니다 +3. **팀 전문성**: 팀이 다양한 접근법에 얼마나 익숙한지 고려하세요 +4. **확장성 요구 사항**: flow는 일반적으로 복잡한 애플리케이션에 더 잘 확장됩니다 +5. **통합 필요**: 솔루션이 기존 시스템과 어떻게 통합될지 고려하세요 + +## 결론 + +Crews와 Flows 중에서 선택하거나 결합하는 것은 CrewAI 애플리케이션의 효과성, 유지 관리성, 확장성에 영향을 미치는 중요한 아키텍처적 결정입니다. 복잡성과 정밀성이라는 차원에서 사용 사례를 평가함으로써, 귀하의 특정 요구 사항에 부합하는 정보에 기반한 결정을 내릴 수 있습니다. + +가장 좋은 접근방식은 애플리케이션이 성숙해지면서 종종 진화한다는 점을 기억하세요. 귀하의 요구를 충족하는 가장 간단한 해결책으로 시작하고, 경험이 쌓이고 요구 사항이 명확해지면 아키텍처를 개선할 준비를 하세요. + + +이제 CrewAI 사용 사례를 평가하고, 복잡성과 정밀성 요구 사항에 따라 올바른 접근법을 선택할 수 있는 프레임워크를 갖추게 되었습니다. 이를 통해 보다 효과적이고 유지 관리 가능하며 확장성 있는 AI 애플리케이션을 구축할 수 있습니다. + + +## 다음 단계 + +- [효과적인 에이전트 만들기](/ko/guides/agents/crafting-effective-agents)에 대해 더 알아보기 +- [처음으로 crew 만들기](/ko/guides/crews/first-crew) 살펴보기 +- [flow 상태 관리 마스터하기](/ko/guides/flows/mastering-flow-state)에 깊이 파고들기 +- 더 깊은 이해를 위해 [핵심 개념](/ko/concepts/agents) 확인하기 \ No newline at end of file diff --git a/docs/v1.15.1/ko/guides/crews/first-crew.mdx b/docs/v1.15.1/ko/guides/crews/first-crew.mdx new file mode 100644 index 000000000..9362c5948 --- /dev/null +++ b/docs/v1.15.1/ko/guides/crews/first-crew.mdx @@ -0,0 +1,140 @@ +--- +title: 첫 번째 Crew 만들기 +description: JSON-first crew 설정으로 협업 AI 팀을 만드는 단계별 튜토리얼입니다. +icon: users-gear +mode: "wide" +--- + +## 리서치 Crew 만들기 + +이 가이드에서는 두 에이전트가 주제를 조사하고 markdown 보고서를 작성하는 crew를 만듭니다. 새 crew 프로젝트는 JSON-first입니다. 에이전트는 `agents/*.jsonc`, 태스크와 crew 설정은 `crew.jsonc`에 두며, `crewai run`이 이 정의를 직접 로드합니다. + +### 준비 사항 + +1. [설치 가이드](/ko/installation)에 따라 CrewAI 설치 +2. [LLM 설정](/ko/concepts/llms#setting-up-your-llm)에 따라 모델 API 키 설정 +3. 웹 검색을 사용할 경우 [Serper.dev](https://serper.dev/) API 키 준비 + +## 1단계: 새 Crew 만들기 + +```bash +crewai create crew research_crew +cd research_crew +``` + +생성되는 구조: + +```text +research_crew/ +├── .gitignore +├── .env +├── agents/ +│ └── researcher.jsonc +├── crew.jsonc +├── knowledge/ +├── pyproject.toml +├── README.md +├── skills/ +└── tools/ +``` + + +`crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 쓰는 기존 레이아웃이 필요하면 `crewai create crew research_crew --classic`을 사용하세요. + + +## 2단계: 에이전트 정의 + +생성된 `agents/researcher.jsonc` 파일을 교체하고 `agents/analyst.jsonc`를 추가합니다. 파일 이름이 `crew.jsonc`에서 참조하는 에이전트 이름입니다. + +```jsonc agents/researcher.jsonc +{ + "role": "Senior Research Specialist for {topic}", + "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.", + "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.", + // 사용하는 모델로 바꾸세요. 예: "openai/gpt-4o". + "llm": "provider/model-id", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +```jsonc agents/analyst.jsonc +{ + "role": "Report Analyst for {topic}", + "goal": "Turn research findings into a clear, well-structured report.", + "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.", + // 사용하는 모델로 바꾸세요. 예: "openai/gpt-4o". + "llm": "provider/model-id", + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +`provider/model-id`를 `openai/gpt-4o`, `anthropic/claude-sonnet-4-6`, `gemini/gemini-2.0-flash-001` 같은 모델로 바꾸세요. + +## 3단계: 태스크와 Crew 설정 + +`crew.jsonc`를 다음으로 교체합니다: + +```jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.", + "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis_task", + "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.", + "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.", + "agent": "analyst", + "context": ["research_task"], + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "Artificial Intelligence in Healthcare" + } +} +``` + +`context`는 이전 태스크 이름을 가리키므로 analyst가 research 태스크 출력을 받습니다. `inputs`는 `{topic}`의 기본값을 제공합니다. 기본값이 없으면 `crewai run`이 실행 중에 물어봅니다. + +## 4단계: 환경 변수 설정 + +`.env`를 편집합니다: + +```sh +SERPER_API_KEY=your_serper_api_key +# 모델 제공자 API 키도 추가하세요. +``` + +## 5단계: 설치 및 실행 + +```bash +crewai install +crewai run +``` + +실행이 끝나면 `output/report.md`를 확인하세요. + + +신뢰하는 출처의 JSON crew 프로젝트만 실행하세요. `custom:` 도구와 `{"python": "module.attribute"}` 참조는 crew 로드 시 로컬 Python 코드를 실행합니다. + + + +주제를 조사하고 보고서를 작성하는 JSON-first crew를 만들었습니다. + diff --git a/docs/v1.15.1/ko/guides/flows/conversational-flows.mdx b/docs/v1.15.1/ko/guides/flows/conversational-flows.mdx new file mode 100644 index 000000000..3a18cd1da --- /dev/null +++ b/docs/v1.15.1/ko/guides/flows/conversational-flows.mdx @@ -0,0 +1,474 @@ +--- +title: 대화형 Flow +description: 턴마다 kickoff, 메시지 기록, 의도 라우팅, 트레이싱, WebSocket 브리지로 멀티턴 채팅 앱을 만듭니다. +icon: comments +mode: "wide" +--- + +## 개요 + +대화형 앱은 각 사용자 입력을 **동일한 세션 id**로 **새 flow 실행**으로 처리합니다. CrewAI는 메시지 기록, 선택적 의도 분류, 지연 트레이싱, UI 브리지, 그리고 대화형 flow용 로컬 `flow.chat()` REPL을 제공합니다. + +| 개념 | 구현 | +|------|------| +| 세션 id | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` | +| 사용자 입력 | `handle_turn(message)`가 그래프 실행 전 `state.messages`에 추가 | +| 턴 완료 | `FlowFinished`는 **이번 실행**만 의미; 다음 `handle_turn`로 대화 계속 | +| 세션 전체 트레이스 | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` | + +## 턴 API + +REST, WebSocket, 테스트, 커스텀 UI에서 오는 모든 사용자 메시지에는 **`flow.handle_turn(message, session_id=...)`**를 사용하세요. 대화형 `Flow`를 로컬 터미널 채팅 루프로 실행하고 싶을 때는 **`flow.chat()`**을 사용하세요. + +`Flow.kickoff()`는 `user_message=` 또는 `session_id=` 키워드 인자를 받지 않습니다. 대화형 flow에서는 `handle_turn()`이 보류 중인 메시지를 저장하고 내부적으로 `kickoff(inputs={"id": session_id})`를 호출합니다. + +| API | 용도 | +|-----|------| +| `handle_turn(message, session_id=...)` | 대화형 `Flow`용 한 턴 편의 래퍼 | +| `chat()` | 대화형 `Flow`용 로컬 터미널 REPL | +| `kickoff(inputs={...})` | 대화형 턴 처리 없이 flow를 직접 실행 | +| `ask()` | 한 스텝 **내부** 블로킹 프롬프트 (마법사, 확인) | +| `@human_feedback` | **스텝 출력** 승인/거부 — 다음 채팅 줄이 아님 | +| `ChatSession.handle_turn(...)` | `handle_turn` 위의 전송 계층 (SSE / WebSocket) | + +## 빠른 시작 + +```python +from uuid import uuid4 + +from crewai import Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, +) + + +@ConversationConfig(defer_trace_finalization=True) +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context): + message = self.state.current_user_message or "" + if "주문" in message or "order" in message.lower(): + return "order" + if "안녕" in message or "goodbye" in message.lower(): + return "goodbye" + return "help" + + @listen("order") + def handle_order(self): + reply = "주문이 배송 중입니다." + self.append_assistant_message(reply) + return reply + + @listen("help") + def handle_help(self): + reply = "무엇을 도와드릴까요?" + self.append_assistant_message(reply) + return reply + + @listen("goodbye") + def handle_goodbye(self): + reply = "안녕히 가세요!" + self.append_assistant_message(reply) + return reply + + +session_id = str(uuid4()) +flow = SupportFlow() + +try: + flow.handle_turn("주문 어디까지 왔나요?", session_id=session_id) + flow.handle_turn("반품은 어떻게 하나요?", session_id=session_id) +finally: + flow.finalize_session_traces() # 전체 대화에 대한 단일 trace 링크 +``` + +## 턴 생명주기 + +각 `handle_turn`은 다음 파이프라인을 실행합니다: + +1. **`_configure_conversational_kickoff`** — `session_id` / `user_message`를 `inputs`에 병합, `ConversationalConfig` 적용, 설정 시 지연 트레이싱 활성화. +2. **상태 복원** — `inputs["id"]`가 있고 `@persist`가 설정되면 최신 스냅샷 로드. +3. **`FlowStarted`** — 지연 세션의 첫 턴에서만 발생. +4. **`prepare_conversational_turn`** — 사용자 메시지를 `state.messages`에 추가, `last_user_message` 설정, `last_intent` 초기화, `intents` / `default_intents` + `intent_llm` 설정 시 분류. +5. **그래프 실행** — `@start` → `@router` → `@listen` 핸들러. +6. **실행 종료** — 지연 활성화 시 턴별 `flow_finished` 및 trace 종료 **건너뜀**; 중첩 `Agent.kickoff()` / crew도 부모 batch를 닫지 않음. + +핸들러는 **`append_assistant_message(reply)`**를 호출해 다음 턴의 `conversation_messages`에 어시스턴트 응답이 포함되게 하세요. 사용자 입력은 `handle_turn`이 이미 저장합니다 — 핸들러에서 다시 추가하지 마세요. + +## `ConversationalConfig` (클래스 수준 기본값) + +`Flow` 서브클래스에 `conversational_config: ClassVar[ConversationalConfig | None]`로 설정합니다. + +| 필드 | 기본값 | 목적 | +|------|--------|------| +| `default_intents` | `None` | kickoff 전 자동 분류용 outcome 라벨 | +| `intent_llm` | `None` | 분류용 모델 (intent 사용 시 필수) | +| `interactive_prompt` | `"You: "` | `kickoff(interactive=True)` 프롬프트 | +| `interactive_timeout` | `None` | 대화형 모드 줄 단위 타임아웃 | +| `exit_commands` | `exit`, `quit` | 대화형 모드 종료 단어 | +| `defer_trace_finalization` | `True` | 턴 간 하나의 trace batch 유지 | + +`intents=` 및 `intent_llm=` 키워드로 kickoff마다 재정의할 수 있습니다. + +## `ChatState` (권장 persist 형태) + +```python +from crewai.flow import ChatState + + +class MyChatState(ChatState): + # 상속: id, messages, last_user_message, last_intent, session_ready + research_turn_count: int = 0 + custom_flag: bool = False +``` + +| 필드 | 역할 | +|------|------| +| `id` | 세션 UUID (`session_id` / `inputs["id"]`와 동일) | +| `messages` | LLM 기록용 `{role, content}` 리스트 | +| `last_user_message` | 이번 턴의 최신 사용자 입력 | +| `last_intent` | 분류 후 라우트 라벨 (사용 시) | +| `session_ready` | 일회성 bootstrap 플래그 | + +`ConversationalInputs`는 `kickoff(inputs={...})`용 `TypedDict`: `id`, `user_message`, `last_intent`. + +## `Flow` 대화 API + +### `kickoff` / `kickoff_async` 파라미터 + +| 파라미터 | 목적 | +|----------|------| +| `user_message` | 이번 턴 텍스트 (또는 `{"role": "user", "content": "..."}`) | +| `session_id` | 대화 UUID → `inputs["id"]` / `state.id` | +| `intents` | kickoff 전 `classify_intent`용 outcome 라벨 | +| `intent_llm` | 분류 LLM (`intents`와 함께 필수) | +| `interactive` | `ask()` CLI 루프 (로컬 데모 전용) | +| `interactive_prompt` | 대화형 모드 프롬프트 | +| `interactive_timeout` | 줄 단위 `ask()` 타임아웃 | +| `exit_commands` | 대화형 모드 종료 단어 | +| `inputs` | 추가 상태 필드 | +| `restore_from_state_id` | 다른 persist flow에서 fork 복원 | + +### 인스턴스 속성 + +| 속성 | 목적 | +|------|------| +| `conversational_config` | 클래스 수준 `ConversationalConfig` | +| `defer_trace_finalization` | 인스턴스 플래그; kickoff 시 config에서 자동 설정 | +| `suppress_flow_events` | 콘솔 flow 패널 숨김; **트레이싱은 계속 기록** | +| `stream` | 스트리밍; `ChatSession.handle_turn(..., stream=True)`와 함께 | + +### 메서드 및 프로퍼티 + +| 이름 | 설명 | +|------|------| +| `append_message(role, content, **extra)` | `state.messages`에 추가 | +| `conversation_messages` | LLM 호출용 읽기 전용 기록 | +| `classify_intent(text, outcomes, *, llm, context=None)` | outcome 매핑 (`@human_feedback`와 동일 collapse) | +| `receive_user_message(text, *, outcomes=None, llm=None)` | 사용자 메시지 추가; 선택적 `last_intent` | +| `finalize_session_traces()` | 지연 `flow_finished` 발생 및 세션 trace batch 종료 | +| `_should_defer_trace_finalization()` | 턴별 trace 종료 지연 여부 | +| `input_history` | `ask()` 프롬프트/응답 감사 기록 | + +### 모듈 헬퍼 (`crewai.flow.conversation`) + +테스트 또는 커스텀 오케스트레이션용: + +| 함수 | 설명 | +|------|------| +| `normalize_kickoff_inputs(...)` | 대화 kwargs를 `inputs`에 병합 | +| `get_conversation_messages(flow)` | 상태 또는 내부 버퍼에서 메시지 읽기 | +| `append_message(flow, ...)` | 인스턴스 메서드와 동일 | +| `prepare_conversational_turn(flow, ...)` | 턴 수화 (보통 kickoff가 호출) | +| `receive_user_message(flow, ...)` | 인스턴스 메서드와 동일 | +| `set_state_field(flow, name, value)` | dict 또는 Pydantic 상태 필드 설정 | +| `get_conversational_config(flow)` | 클래스 `conversational_config` 읽기 | +| `input_history_to_messages(entries)` | `input_history`를 LLM 메시지 형식으로 | + +## 의도 라우팅 패턴 + +### A. `ConversationalConfig`로 사전 분류 (가장 단순) + +`default_intents`와 `intent_llm` 설정. 각 kickoff가 `@router` 전에 분류; `route()`에서 `self.state.last_intent` 읽기. + +### B. `@router` 내부에서 분류 (풍부한 프롬프트) + +`default_intents=None`으로 kickoff는 메시지만 추가. `route()`에서 커스텀 프롬프트로 `classify_intent` 호출: + +```python +@router(bootstrap) +def route(self): + intent = self.classify_intent( + self._routing_prompt(self.state.last_user_message), + ("GREETING", "ORDER", "RESEARCH", "GOODBYE"), + llm=self.conversational_config.intent_llm or "gpt-4o-mini", + ) + self.state.last_intent = intent + return intent +``` + +웹 리서치나 다단계 tool이 필요하면 **`@listen("RESEARCH")`** 등에서 `Agent.kickoff()`와 tool 사용 — 단순 `LLM.call()` 대신. + +## flow가 끝났지만 사용자는 계속 대화할 때 + +`FlowFinished`는 **이번 그래프 실행**이 완료됨을 의미합니다. 같은 `session_id`로 또 다른 `kickoff`로 대화가 이어집니다. `@persist`가 `messages`, 플래그, 컨텍스트를 복원합니다. + +**Persist 패턴:** 전체 `Flow` 클래스보다 **단일 종료 스텝**(예: `finalize`)에 `@persist`를 두는 것이 좋습니다. 클래스 수준 persist는 매 메서드 후 저장하며, `load_state`는 최신 행을 사용해 같은 턴의 핸들러 업데이트를 놓칠 수 있습니다. + +후속 채팅 줄에 `@human_feedback`를 쓰지 마세요. 특정 스텝 출력을 사람이 승인해야 할 때만 사용하세요. + +## 대화형 `Flow` (실험적) + + + **실험적 기능입니다.** 대화형 `Flow`의 API 표면(`conversational = True`, + `handle_turn`, `ConversationConfig`, `RouterConfig`, `ConversationState`, + 내장 그래프와 헬퍼)은 `crewai.experimental` 하위에 있으며 정식 출시 + 전까지 변경될 수 있습니다. 특정 동작에 의존한다면 CrewAI 버전을 고정하고 + 변경 사항이 있는지 changelog를 확인하세요. 피드백과 이슈 환영합니다. + + +`Flow` 서브클래스에 `conversational = True`를 지정하면 대화형 챗 그래프가 활성화됩니다. 베이스 `Flow`가 `@start` / `@router` / `converse_turn` / `end_conversation` 그래프를 노출하고, `state.messages`를 관리하며, router LLM을 구동하고, 턴 간 trace 배치를 열린 상태로 유지합니다. 여러분은 **커스텀 라우트**만 작성하면 되고, 나머지는 프레임워크가 담당합니다. + +LLM 기반 라우터와 라우트별 핸들러로 멀티턴 챗을 만들고 싶지만 라이프사이클을 직접 배선하고 싶지 않을 때 사용하세요. 완전한 제어가 필요하면 위의 `Flow[ChatState]`로 내려가세요. + +### 빠른 예제 + +```python +from crewai import LLM, Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, + RouterConfig, +) + + +ROUTER_LLM = LLM(model="gpt-4o-mini") + + +@ConversationConfig( + system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.", + llm=ROUTER_LLM, + router=RouterConfig(), # 라우트 + 설명은 @listen 핸들러에서 자동 발견 +) +class SupportFlow(Flow[ConversationState]): + conversational = True + + @listen("INTERNET_SEARCH") + def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... + self.append_assistant_message(reply) + return reply + + @listen("CREWAI_DOCS") + def handle_crewai_docs(self) -> str: + """Look up the CrewAI documentation for framework/API questions.""" + ... + self.append_assistant_message(reply) + return reply + + +flow = SupportFlow() +try: + flow.handle_turn("뭘 할 수 있어?") # converse(빌트인)로 라우팅 + flow.handle_turn("AI 뉴스를 웹에서 찾아줘.") # INTERNET_SEARCH로 라우팅 + flow.handle_turn("첫 번째 결과를 요약해줘.") # 다시 converse로 라우팅 +finally: + flow.finalize_session_traces() +``` + +로컬 터미널 채팅에는 `chat()`을 사용하세요: + +```python +def kickoff() -> None: + SupportFlow().chat() +``` + +`chat()`은 `handle_turn()`을 REPL로 감싸고, `exit` / `quit`에서 종료하며, 기본적으로 빈 줄을 건너뛰고, 세션이 끝날 때 `finalize_session_traces()`를 호출합니다. + +### `ConversationConfig` + +클래스 단위의 챗 기본값을 부착하는 클래스 데코레이터입니다. + +| 필드 | 기본값 | 목적 | +|------|--------|------| +| `system_prompt` | i18n `slices.conversational_system_prompt` | 빌트인 `converse_turn`이 사용하는 system 메시지. 빈 문자열(`""`)을 전달하면 system 메시지를 끕니다. | +| `llm` | `None` | 대화용 LLM (빌트인 `converse_turn`이 사용하고 router 폴백도 됨). | +| `router` | `None` | LLM 기반 라우팅을 위한 `RouterConfig`. 없으면 항상 `converse`로 떨어집니다. | +| `answer_from_history_prompt` | 프레임워크 기본값 | 선택적인 `answer_from_history` 라우트용 system 메시지. | +| `answer_from_history_llm` | `None` | 설정되면 `answer_from_history` 단축 경로가 활성화됩니다. | +| `intent_llm` | `None` | 레거시 `intents=`/`default_intents` 사전 분류용 LLM. | +| `default_intents` | `None` | 레거시 사전 분류용 outcome 레이블. | +| `visible_agent_outputs` | `None` | `"all"` 또는 `append_agent_result()` 결과를 사용자에게 공개로 승격할 에이전트 이름 목록. | +| `defer_trace_finalization` | `True` | `handle_turn()` 호출들 사이에서 하나의 trace 배치를 열어 둡니다. | + +### `RouterConfig`와 자동 생성되는 라우트 카탈로그 + +```python +RouterConfig( + prompt="선택적인 도메인 프레이밍 (정책, 톤, 페르소나).", + response_format=MyRoute, # 선택; 없으면 자동 생성 + llm=ROUTER_LLM, # ConversationConfig.llm으로 폴백 + routes=["INTERNET_SEARCH", "CREWAI_DOCS"], # 선택; 리스너에서 추론 + route_descriptions={ + "INTERNET_SEARCH": "이 라우트만 docstring 대신 사용할 설명.", + }, + default_intent="converse", # LLM 호출 실패 또는 LLM 없음일 때 사용 + fallback_intent="converse", # LLM이 잘못된 라우트를 반환할 때 사용 + intent_field="intent", +) +``` + +router에 전달되는 프롬프트는 자동으로 만들어집니다. 각 라우트의 설명은 다음 우선순위로 결정됩니다: + +1. `RouterConfig.route_descriptions[label]` — 명시적 오버라이드. +2. `Flow.builtin_route_descriptions[label]` — `converse`, `end`, `answer_from_history`용 프레임워크 캐닝 텍스트 (router LLM용으로 다듬어진 문구). +3. `@listen(label)` 핸들러 docstring의 첫 줄(비어있지 않은 줄). +4. 빈 문자열 (라우트만 카탈로그에 등장하고 설명은 없음). + +실제 사용에서 **새 라우트를 추가하는 방법은 `@listen("X")` + 한 줄짜리 docstring**입니다: + +```python +@listen("INTERNET_SEARCH") +def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... +``` + +…그러면 router LLM은 다음을 봅니다: + +``` +Routes: +- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions. +- INTERNET_SEARCH: Fresh web research, current news, real-time lookups. +- converse: Ordinary chat, follow-ups, summaries, clarifications… +- end: User signals the conversation is finished (goodbye, exit, done). +``` + +`RouterConfig.prompt`는 **도메인 프레이밍** (어시스턴트 페르소나, 비즈니스 규칙, 톤)을 위한 자리입니다. 라우트 카탈로그는 자동 생성되니 `prompt` 안에 라우트 목록을 넣지 마세요. 핸들러를 추가하는 순간 동기화가 깨집니다. + +### 빌트인 라우트 + +| 라우트 | 핸들러 | 목적 | +|--------|--------|------| +| `converse` | `converse_turn` | 기본 챗 핸들러. system prompt + 정식 메시지 히스토리와 함께 `ConversationConfig.llm`을 호출합니다. | +| `end` | `end_conversation` | `state.ended = True`로 설정하고 종료 응답을 보냅니다. | +| `answer_from_history` | `answer_from_history_turn` | 선택적. `ConversationConfig.answer_from_history_llm`이 설정되어 있고 메시지를 히스토리만으로 답할 수 있을 때 라우팅됩니다. | + +서브클래스에 같은 이름의 핸들러를 정의하면 어떤 것이든 오버라이드할 수 있습니다. + +### `handle_turn()` 시맨틱 + +`flow.handle_turn(message)`는 한 턴을 실행합니다: + +1. 그래프가 다시 실행되도록 턴 단위 실행 추적(`_completed_methods`, `_method_outputs`)을 초기화합니다 — 이게 없으면 동일 인스턴스에서 반복 `kickoff` 호출 시 `Flow.kickoff_async`가 `inputs={"id": ...}`를 체크포인트 복원으로 간주해 2번째 턴부터 단락 회로가 발생합니다. +2. 사용자 메시지를 `state.messages`에 추가하고 `current_user_message` / `last_user_message`를 설정합니다. `last_intent`는 **이전 턴 값이 유지**되어 router LLM이 신호로 활용할 수 있습니다. +3. `conversation_start` → `route_conversation` → 선택된 `@listen` 핸들러 순으로 실행됩니다. +4. router는 결정을 `state.last_intent`에 저장합니다 (다음 턴의 router 컨텍스트에서 보입니다). +5. 핸들러가 문자열을 반환했지만 `append_assistant_message`를 직접 호출하지 않았다면, `handle_turn`이 대신 추가해 줍니다. + +채팅 메시지에는 `handle_turn()`을 호출하세요. `kickoff(inputs={"id": ...})`를 직접 호출하면 대화형 턴 래퍼 없이 flow 그래프가 실행됩니다. + +### 로컬 REPL용 `chat()` + +`flow.chat()`은 `handle_turn()` 위에 얹은 바로 쓸 수 있는 터미널 래퍼입니다: + +```python +flow = SupportFlow() +flow.chat() +``` + +일반적인 로컬 루프를 처리합니다: + +1. 사용자 메시지를 입력받습니다. +2. `exit` / `quit`, `EOFError`, `KeyboardInterrupt`에서 멈춥니다. +3. `handle_turn(message, session_id=...)`를 호출합니다. +4. 어시스턴트 결과를 출력합니다. +5. `finally` 블록에서 지연된 세션 trace를 finalize합니다. + +주입 가능한 I/O로 터미널 동작을 커스터마이즈할 수 있습니다: + +```python +flow.chat( + session_id="demo-session", + prompt="You: ", + assistant_prefix="Assistant: ", + exit_commands=("exit", "quit", "bye"), +) +``` + +웹 앱, 백그라운드 worker, 테스트, 커스텀 transport에서는 계속 `handle_turn()`을 직접 사용하세요. + +### 커스텀 router 동작 + +매 라우팅 결정마다 사이드 이펙트(이벤트 버스 셋업, 텔레메트리)를 실행하려면 `route_turn`을 오버라이드하세요: + +```python +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context: dict[str, Any]) -> str | None: + self.event_bus = MyBus(self) + return super().route_turn(context) +``` + +LLM router를 우회해 프로그램적으로 라우트를 선택하려면 `route_turn`에서 문자열을 반환하세요. `None`을 반환하면 `_route_with_config(...)`로 떨어집니다. + +### `append_assistant_message`와 `append_agent_result` + +`@listen(label)` 핸들러 안에서 두 가지 중 선택하세요: + +- `self.append_assistant_message(text)` — 사용자에게 보이는 어시스턴트 턴을 `state.messages`에 추가합니다. 다음 턴의 `converse_turn`이 이 내용을 보게 됩니다. +- `self.append_agent_result(agent_name, result, visibility="private")` — 구조화된 이벤트를 `state.events`에, 스레드를 `state.agent_threads[agent_name]`에 기록합니다. public 가시성은 자동으로 `append_assistant_message`도 호출합니다. 정식 히스토리를 더럽히지 말아야 할 임시 작업에는 private을 쓰세요. + +`ConversationConfig.visible_agent_outputs`로 특정 에이전트의 private 결과를 전역적으로 public으로 승격할 수 있습니다 (`"all"` 또는 이름 리스트). + +## 턴 간 트레이싱 + +`defer_trace_finalization=True` (`ConversationalConfig` 기본값): + +- 채팅 세션 전체에 **하나의 trace batch**. +- 첫 턴에만 **`flow_started`**; `finalize_session_traces()`에서 **`flow_finished`** 한 번. +- 턴별 `kickoff`는 “Trace batch finalized”를 출력하지 않음. +- **중첩 작업** (`Agent.kickoff()`, crew, Exa tool)은 **부모** batch에 추가; 내부 `AgentExecutor` flow가 세션 batch를 조기 종료하지 않음. + +```python +flow.chat(session_id=session_id) +``` + +`flow.chat()`이 `finalize_session_traces()`를 대신 호출합니다. `handle_turn()`이나 `kickoff(...)`로 직접 루프를 소유하는 경우, 세션이 끝날 때 `finalize_session_traces()`를 호출하세요. + +`suppress_flow_events=True`는 Rich 콘솔 패널만 숨깁니다. trace 및 method 이벤트는 계속 발생합니다. + +### 대화형 `Flow` trace 수명 주기 + +실험적 [대화형 `Flow`](#대화형-flow-실험적)는 동일한 tracing 수명 주기를 따릅니다. `defer_trace_finalization` 기본값이 `True`이므로 각 `handle_turn()`이 세션 trace를 열어 둡니다. 세션 끝에서 항상 finalize하세요 — REPL/루프를 `try/finally`로 감싸고 종료 시 `flow.finalize_session_traces()`를 호출하세요. 호출하지 않으면 batch가 열린 채 남아 마지막 대화가 export되지 않을 수 있습니다. + +## 스트리밍 + +`Flow` 클래스에 `stream = True`. `kickoff(...)`가 표준 이벤트 버스를 통해 `assistant_delta` 등 이벤트를 발생시킵니다. + +## import + +```python +from crewai.flow import ( + ChatState, + ConversationalConfig, + ConversationalInputs, + Flow, + listen, + persist, + router, + start, +) +``` + +## 참고 + +- [Flow 상태 관리 마스터하기](/ko/guides/flows/mastering-flow-state) +- [첫 Flow 만들기](/ko/guides/flows/first-flow) +- 데모: `lib/crewai/runner_conversational_flow_simple.py` diff --git a/docs/v1.15.1/ko/guides/flows/first-flow.mdx b/docs/v1.15.1/ko/guides/flows/first-flow.mdx new file mode 100644 index 000000000..04d0f3edf --- /dev/null +++ b/docs/v1.15.1/ko/guides/flows/first-flow.mdx @@ -0,0 +1,550 @@ +--- +title: 첫 Flow 빌드하기 +description: 정밀한 실행 제어가 가능한 구조화된 이벤트 기반 워크플로우를 만드는 방법을 배웁니다. +icon: diagram-project +mode: "wide" +--- + +## Flows로 AI 워크플로우 제어하기 + +CrewAI Flows는 AI 오케스트레이션의 새로운 수준을 제공합니다. 즉, AI agent crew의 협업 능력과 절차적 프로그래밍의 정밀성 및 유연성을 결합합니다. crew가 agent 협업에서 탁월하다면, flow는 AI 시스템의 다양한 구성요소가 어떻게 그리고 언제 상호작용하는지에 대해 세밀하게 제어할 수 있게 해줍니다. + +이 가이드에서는 원하는 주제에 대한 포괄적인 학습 가이드를 생성하는 강력한 CrewAI Flow를 만드는 과정을 소개합니다. 이 튜토리얼을 통해 Flow가 일반 코드, 직접적인 LLM 호출, crew 기반 처리 등을 결합하여 AI 워크플로우에 구조적이고 이벤트 기반의 제어를 제공하는 방법을 시연할 것입니다. + +### 플로우의 강력한 점 + +플로우를 통해 다음과 같은 작업을 할 수 있습니다: + +1. **다양한 AI 상호작용 패턴 결합** - 복잡한 협업 작업에는 crew를 사용하고, 더 단순한 작업에는 직접적인 LLM 호출과 절차적 논리에는 일반 코드를 사용하세요. +2. **이벤트 기반 시스템 구축** - 구성 요소가 특정 이벤트와 데이터 변경에 어떻게 반응할지 정의할 수 있습니다. +3. **구성 요소 간 상태 유지** - 애플리케이션의 다양한 부분 간에 데이터를 공유하고 변환할 수 있습니다. +4. **외부 시스템과 통합** - 데이터베이스, API, 사용자 인터페이스와 같은 외부 시스템과 AI 워크플로우를 원활하게 연동할 수 있습니다. +5. **복잡한 실행 경로 생성** - 조건부 분기, 병렬 처리 및 동적인 워크플로우를 설계할 수 있습니다. + +### 무엇을 구축하고 배우게 될까요 + +이 가이드가 끝나면 여러분은 다음을 달성할 수 있습니다: + +1. **사용자 입력, AI 계획, 그리고 멀티 에이전트 콘텐츠 생성이 결합된 정교한 콘텐츠 생성 시스템을 구축**했습니다. +2. **시스템의 다양한 구성 요소 간 정보 흐름을 오케스트레이션(조율)**했습니다. +3. **이전 단계의 완료에 따라 각 단계가 반응하는 이벤트 기반 아키텍처를 구현**했습니다. +4. **더 복잡한 AI 애플리케이션을 확장하고 맞춤화할 수 있는 기반을 구축**했습니다. + +이번 가이드의 creator flow는 다음과 같은 훨씬 더 발전된 애플리케이션에 적용할 수 있는 기본 패턴을 보여줍니다: + +- 여러 전문화된 하위 시스템을 결합하는 대화형 AI assistant +- AI 기반 변환을 포함한 복잡한 데이터 처리 파이프라인 +- 외부 서비스 및 API와 통합되는 자율적 에이전트 +- 인간이 개입하는 프로세스를 포함한 다단계 의사결정 시스템 + +함께 여러분의 첫 번째 flow를 만들어 봅시다! + +## 사전 준비 사항 + +시작하기 전에 다음을 확인하세요: + +1. [설치 가이드](/ko/installation)에 따라 CrewAI를 설치했는지 확인하십시오. +2. [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)에 따라 환경에 LLM API 키를 설정했는지 확인하십시오. +3. Python에 대한 기본적인 이해 + +## 1단계: 새로운 CrewAI Flow 프로젝트 생성 + +먼저, CLI를 사용하여 새로운 CrewAI Flow 프로젝트를 생성해봅시다. 이 명령어는 필요한 모든 디렉터리와 템플릿 파일이 포함된 기본 프로젝트 구조를 만들어줍니다. + +```bash +crewai create flow guide_creator_flow +cd guide_creator_flow +``` + +이렇게 하면 flow에 필요한 기본 구조를 가진 프로젝트가 생성됩니다. + + + CrewAI Framework 개요 + + +## 2단계: 프로젝트 구조 이해하기 + +생성된 프로젝트는 다음과 같은 구조를 가지고 있습니다. 시작용 embedded crew는 클래식 Python/YAML 레이아웃을 사용합니다. Flow 안에서 JSON-first crew를 사용하려면 crew 폴더에 `crew.jsonc`와 `agents/*.jsonc`를 만들고 `crewai.project.load_crew`로 로드하세요. 예시는 [Flows](/ko/concepts/flows#building-your-crews)를 참고하세요. + +``` +guide_creator_flow/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +└── src/ + └── guide_creator_flow/ + ├── __init__.py + ├── main.py + ├── crews/ + │ └── poem_crew/ + │ ├── config/ + │ │ ├── agents.yaml + │ │ └── tasks.yaml + │ └── poem_crew.py + └── tools/ + └── custom_tool.py +``` + +이 구조는 flow의 다양한 구성 요소를 명확하게 분리해줍니다: +- `src/guide_creator_flow/main.py` 파일의 main flow 로직 +- `src/guide_creator_flow/crews` 디렉터리의 특화된 crew들 +- `src/guide_creator_flow/tools` 디렉터리의 custom tool들 + +이제 이 구조를 수정하여 guide creator flow를 만들 것입니다. 이 flow는 포괄적인 학습 가이드 생성을 조직하는 역할을 합니다. + +## 3단계: Content Writer Crew 추가 + +우리 flow에는 콘텐츠 생성 프로세스를 처리할 전문화된 crew가 필요합니다. CrewAI CLI를 사용하여 content writer crew를 추가해봅시다: + +```bash +crewai flow add-crew content-crew +``` + +이 명령어는 자동으로 crew에 필요한 디렉터리와 템플릿 파일을 생성합니다. content writer crew는 가이드의 각 섹션을 작성하고 검토하는 역할을 담당하며, 메인 애플리케이션에 의해 조율되는 전체 flow 내에서 작업하게 됩니다. + +## 4단계: 콘텐츠 작가 Crew 구성 + +이제 콘텐츠 작가 crew를 JSONC로 구성합니다. 가이드의 고품질 콘텐츠를 만들기 위해 협업하는 두 명의 전문 에이전트 - 작가와 리뷰어 - 를 설정합니다. + +1. `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`를 만듭니다: + +```jsonc +{ + "role": "Educational Content Writer", + "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.", + "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +2. `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`를 만듭니다: + +```jsonc +{ + "role": "Educational Content Reviewer and Editor", + "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.", + "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +`provider/model-id`를 사용하는 모델로 바꾸세요. 예: `openai/gpt-4o`, `gemini/gemini-2.0-flash-001`, `anthropic/claude-sonnet-4-6`. + +3. `src/guide_creator_flow/crews/content_crew/crew.jsonc`를 만듭니다: + +```jsonc +{ + "name": "Content Crew", + "agents": ["content_writer", "content_reviewer"], + "tasks": [ + { + "name": "write_section_task", + "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}", + "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.", + "agent": "content_writer", + "markdown": true + }, + { + "name": "review_section_task", + "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.", + "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.", + "agent": "content_reviewer", + "context": ["write_section_task"], + "markdown": true + } + ], + "process": "sequential", + "verbose": true +} +``` + +`context` 필드를 통해 리뷰어가 작가의 출력을 사용할 수 있습니다. + +4. `src/guide_creator_flow/crews/content_crew/content_crew.py`를 작은 loader로 교체합니다: + +```python +from pathlib import Path + +from crewai.project import load_crew + + +def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) +``` + +이 loader는 런타임에 `crew.jsonc`를 `Crew`로 바꿉니다. 이 crew는 독립적으로도 작동할 수 있지만, 우리의 플로우에서는 더 큰 시스템의 일부로 오케스트레이션됩니다. + +## 5단계: 플로우(Flow) 생성 + +이제 가장 흥미로운 부분입니다 - 전체 가이드 생성 과정을 오케스트레이션할 플로우를 만드는 단계입니다. 이곳에서 우리는 일반 Python 코드, 직접적인 LLM 호출, 그리고 우리의 컨텐츠 제작 crew를 결합하여 일관된 시스템으로 만듭니다. + +우리의 플로우는 다음과 같은 일을 수행합니다: +1. 주제와 대상 독자 수준에 대한 사용자 입력을 받습니다. +2. 구조화된 가이드 개요를 만들기 위해 직접 LLM 호출을 합니다. +3. 컨텐츠 writer crew를 사용하여 각 섹션을 순차적으로 처리합니다. +4. 모든 내용을 결합하여 최종 종합 문서를 완성합니다. + +`main.py` 파일에 우리의 플로우를 생성해봅시다: + +```python +#!/usr/bin/env python +import json +import os +from typing import List, Dict +from pydantic import BaseModel, Field +from crewai import LLM +from crewai.flow.flow import Flow, listen, start +from guide_creator_flow.crews.content_crew.content_crew import kickoff_content_crew + +# Define our models for structured data +class Section(BaseModel): + title: str = Field(description="Title of the section") + description: str = Field(description="Brief description of what the section should cover") + +class GuideOutline(BaseModel): + title: str = Field(description="Title of the guide") + introduction: str = Field(description="Introduction to the topic") + target_audience: str = Field(description="Description of the target audience") + sections: List[Section] = Field(description="List of sections in the guide") + conclusion: str = Field(description="Conclusion or summary of the guide") + +# Define our flow state +class GuideCreatorState(BaseModel): + topic: str = "" + audience_level: str = "" + guide_outline: GuideOutline = None + sections_content: Dict[str, str] = {} + +class GuideCreatorFlow(Flow[GuideCreatorState]): + """Flow for creating a comprehensive guide on any topic""" + + @start() + def get_user_input(self): + """Get input from the user about the guide topic and audience""" + print("\n=== Create Your Comprehensive Guide ===\n") + + # Get user input + self.state.topic = input("What topic would you like to create a guide for? ") + + # Get audience level with validation + while True: + audience = input("Who is your target audience? (beginner/intermediate/advanced) ").lower() + if audience in ["beginner", "intermediate", "advanced"]: + self.state.audience_level = audience + break + print("Please enter 'beginner', 'intermediate', or 'advanced'") + + print(f"\nCreating a guide on {self.state.topic} for {self.state.audience_level} audience...\n") + return self.state + + @listen(get_user_input) + def create_guide_outline(self, state): + """Create a structured outline for the guide using a direct LLM call""" + print("Creating guide outline...") + + # Initialize the LLM + llm = LLM(model="openai/gpt-4o-mini", response_format=GuideOutline) + + # Create the messages for the outline + messages = [ + {"role": "system", "content": "You are a helpful assistant designed to output JSON."}, + {"role": "user", "content": f""" + Create a detailed outline for a comprehensive guide on "{state.topic}" for {state.audience_level} level learners. + + The outline should include: + 1. A compelling title for the guide + 2. An introduction to the topic + 3. 4-6 main sections that cover the most important aspects of the topic + 4. A conclusion or summary + + For each section, provide a clear title and a brief description of what it should cover. + """} + ] + + # Make the LLM call with JSON response format + response = llm.call(messages=messages) + + # Parse the JSON response + outline_dict = json.loads(response) + self.state.guide_outline = GuideOutline(**outline_dict) + + # Ensure output directory exists before saving + os.makedirs("output", exist_ok=True) + + # Save the outline to a file + with open("output/guide_outline.json", "w") as f: + json.dump(outline_dict, f, indent=2) + + print(f"Guide outline created with {len(self.state.guide_outline.sections)} sections") + return self.state.guide_outline + + @listen(create_guide_outline) + def write_and_compile_guide(self, outline): + """Write all sections and compile the guide""" + print("Writing guide sections and compiling...") + completed_sections = [] + + # Process sections one by one to maintain context flow + for section in outline.sections: + print(f"Processing section: {section.title}") + + # Build context from previous sections + previous_sections_text = "" + if completed_sections: + previous_sections_text = "# Previously Written Sections\n\n" + for title in completed_sections: + previous_sections_text += f"## {title}\n\n" + previous_sections_text += self.state.sections_content.get(title, "") + "\n\n" + else: + previous_sections_text = "No previous sections written yet." + + # Run the content crew for this section + result = kickoff_content_crew(inputs={ + "section_title": section.title, + "section_description": section.description, + "audience_level": self.state.audience_level, + "previous_sections": previous_sections_text, + "draft_content": "" + }) + + # Store the content + self.state.sections_content[section.title] = result.raw + completed_sections.append(section.title) + print(f"Section completed: {section.title}") + + # Compile the final guide + guide_content = f"# {outline.title}\n\n" + guide_content += f"## Introduction\n\n{outline.introduction}\n\n" + + # Add each section in order + for section in outline.sections: + section_content = self.state.sections_content.get(section.title, "") + guide_content += f"\n\n{section_content}\n\n" + + # Add conclusion + guide_content += f"## Conclusion\n\n{outline.conclusion}\n\n" + + # Save the guide + with open("output/complete_guide.md", "w") as f: + f.write(guide_content) + + print("\nComplete guide compiled and saved to output/complete_guide.md") + return "Guide creation completed successfully" + +def kickoff(): + """Run the guide creator flow""" + GuideCreatorFlow().kickoff() + print("\n=== Flow Complete ===") + print("Your comprehensive guide is ready in the output directory.") + print("Open output/complete_guide.md to view it.") + +def plot(): + """Generate a visualization of the flow""" + flow = GuideCreatorFlow() + flow.plot("guide_creator_flow") + print("Flow visualization saved to guide_creator_flow.html") + +if __name__ == "__main__": + kickoff() +``` + +이 플로우에서 일어나는 과정을 분석해봅시다: + +1. 구조화된 데이터에 대한 Pydantic 모델을 정의하여 타입 안전성과 명확한 데이터 표현을 보장합니다. +2. 플로우 단계별로 데이터를 유지하기 위한 state 클래스를 생성합니다. +3. 세 가지 주요 플로우 단계를 구현합니다: + - `@start()` 데코레이터로 사용자 입력을 받습니다. + - 직접 LLM 호출로 가이드 개요를 생성합니다. + - content crew로 각 섹션을 처리합니다. +4. `@listen()` 데코레이터를 활용해 단계 간 이벤트 기반 관계를 설정합니다. + +이것이 바로 flows의 힘입니다 - 다양한 처리 유형(사용자 상호작용, 직접적인 LLM 호출, crew 기반 작업)을 하나의 일관된 이벤트 기반 시스템으로 결합할 수 있습니다. + +## 6단계: 환경 변수 설정하기 + +프로젝트 루트에 `.env` 파일을 생성하고 API 키를 입력하세요. 공급자 구성에 대한 자세한 내용은 [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하세요. + +```sh .env +OPENAI_API_KEY=your_openai_api_key +# or +GEMINI_API_KEY=your_gemini_api_key +# or +ANTHROPIC_API_KEY=your_anthropic_api_key +``` + +## 7단계: 의존성 설치 + +필수 의존성을 설치합니다: + +```bash +crewai install +``` + +## 8단계: Flow 실행하기 + +이제 여러분의 flow가 실제로 작동하는 모습을 볼 차례입니다! CrewAI CLI를 사용하여 flow를 실행하세요: + +```bash +crewai run +``` + +이 명령어를 실행하면 flow가 다음과 같이 작동하는 것을 확인할 수 있습니다: +1. 주제와 대상 수준을 입력하라는 메시지가 표시됩니다. +2. 가이드의 체계적인 개요를 생성합니다. +3. 각 섹션을 처리할 때 content writer와 reviewer가 협업합니다. +4. 마지막으로 모든 내용을 종합하여 완성도 높은 가이드를 만듭니다. + +이는 여러 구성요소(인공지능 및 비인공지능 모두)가 포함된 복잡한 프로세스를 flows가 어떻게 조정할 수 있는지 보여줍니다. + +## 9단계: Flow 시각화하기 + +flow의 강력한 기능 중 하나는 구조를 시각화할 수 있다는 점입니다. + +```bash +crewai flow plot +``` + +이 명령은 flow의 구조를 보여주는 HTML 파일을 생성하며, 각 단계 간의 관계와 그 사이에 흐르는 데이터를 확인할 수 있습니다. 이러한 시각화는 복잡한 flow를 이해하고 디버깅하는 데 매우 유용합니다. + +## 10단계: 출력물 검토하기 + +flow가 완료되면 `output` 디렉토리에서 두 개의 파일을 찾을 수 있습니다: + +1. `guide_outline.json`: 가이드의 구조화된 개요가 포함되어 있습니다 +2. `complete_guide.md`: 모든 섹션이 포함된 종합적인 가이드입니다 + +이 파일들을 잠시 검토하고 여러분이 구축한 시스템을 되돌아보세요. 이 시스템은 사용자 입력, 직접적인 AI 상호작용, 협업 에이전트 작업을 결합하여 복잡하고 고품질의 결과물을 만들어냅니다. + +## 가능한 것의 예술: 첫 번째 Flow 그 이상 + +이 가이드에서 배운 내용은 훨씬 더 정교한 AI 시스템을 만드는 데 기반이 됩니다. 다음은 이 기본 flow를 확장할 수 있는 몇 가지 방법입니다: + +### 사용자 상호작용 향상 + +더욱 인터랙티브한 플로우를 만들 수 있습니다: +- 입력 및 출력을 위한 웹 인터페이스 +- 실시간 진행 상황 업데이트 +- 인터랙티브한 피드백 및 개선 루프 +- 다단계 사용자 상호작용 + +### 추가 처리 단계 추가하기 + +다음과 같은 추가 단계로 flow를 확장할 수 있습니다: +- 개요 작성 전 사전 리서치 +- 일러스트를 위한 이미지 생성 +- 기술 가이드용 코드 스니펫 생성 +- 최종 품질 보증 및 사실 확인 + +### 더 복잡한 Flows 생성하기 + +더 정교한 flow 패턴을 구현할 수 있습니다: +- 사용자 선호도나 콘텐츠 유형에 따른 조건 분기 +- 독립적인 섹션의 병렬 처리 +- 피드백과 함께하는 반복적 개선 루프 +- 외부 API 및 서비스와의 통합 + +### 다양한 도메인에 적용하기 + +동일한 패턴을 사용하여 다음과 같은 flow를 만들 수 있습니다: +- **대화형 스토리텔링**: 사용자 입력을 바탕으로 개인화된 이야기를 생성 +- **비즈니스 인텔리전스**: 데이터를 처리하고, 인사이트를 도출하며, 리포트를 생성 +- **제품 개발**: 아이디어 구상, 디자인, 기획을 지원 +- **교육 시스템**: 개인화된 학습 경험을 제공 + +## 주요 특징 시연 + +이 guide creator flow에서는 CrewAI의 여러 강력한 기능을 시연합니다: + +1. **사용자 상호작용**: flow는 사용자로부터 직접 입력을 수집합니다 +2. **직접적인 LLM 호출**: 효율적이고 단일 목적의 AI 상호작용을 위해 LLM 클래스를 사용합니다 +3. **Pydantic을 통한 구조화된 데이터**: 타입 안정성을 보장하기 위해 Pydantic 모델을 사용합니다 +4. **컨텍스트를 활용한 순차 처리**: 섹션을 순서대로 작성하면서 이전 섹션을 컨텍스트로 제공합니다 +5. **멀티 에이전트 crew**: 콘텐츠 생성을 위해 특화된 에이전트(writer 및 reviewer)를 활용합니다 +6. **상태 관리**: 프로세스의 다양한 단계에 걸쳐 상태를 유지합니다 +7. **이벤트 기반 아키텍처**: 이벤트에 응답하기 위해 `@listen` 데코레이터를 사용합니다 + +## 플로우 구조 이해하기 + +플로우의 주요 구성 요소를 분해하여 자신만의 플로우를 만드는 방법을 이해할 수 있도록 도와드리겠습니다: + +### 1. 직접 LLM 호출 + +Flow를 사용하면 간단하고 구조화된 응답이 필요할 때 언어 모델에 직접 호출할 수 있습니다: + +```python +llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + response_format=GuideOutline +) +response = llm.call(messages=messages) +``` + +특정하고 구조화된 출력이 필요할 때 crew를 사용하는 것보다 더 효율적입니다. + +### 2. 이벤트 기반 아키텍처 + +Flows는 데코레이터를 사용하여 컴포넌트 간의 관계를 설정합니다: + +```python +@start() +def get_user_input(self): + # First step in the flow + # ... + +@listen(get_user_input) +def create_guide_outline(self, state): + # This runs when get_user_input completes + # ... +``` + +이렇게 하면 애플리케이션에 명확하고 선언적인 구조가 만들어집니다. + +### 3. 상태 관리 + +flow는 단계 간 상태를 유지하여 데이터를 쉽게 공유할 수 있습니다: + +```python +class GuideCreatorState(BaseModel): + topic: str = "" + audience_level: str = "" + guide_outline: GuideOutline = None + sections_content: Dict[str, str] = {} +``` + +이 방식은 flow 전반에 걸쳐 데이터를 추적하고 변환하는 타입 안전(type-safe)한 방법을 제공합니다. + +### 4. Crew 통합 + +Flow는 복잡한 협업 작업을 위해 crew와 원활하게 통합될 수 있습니다: + +```python +result = kickoff_content_crew(inputs={ + "section_title": section.title, + # ... +}) +``` + +이를 통해 애플리케이션의 각 부분에 적합한 도구를 사용할 수 있습니다. 단순한 작업에는 직접적인 LLM 호출을, 복잡한 협업에는 crew를 사용할 수 있습니다. + +## 다음 단계 + +이제 첫 번째 flow를 구축했으니 다음을 시도해 볼 수 있습니다: + +1. 더 복잡한 flow 구조와 패턴을 실험해 보세요. +2. `@router()`를 사용하여 flow에서 조건부 분기를 만들어 보세요. +3. 더 복잡한 병렬 실행을 위해 `and_` 및 `or_` 함수를 탐색해 보세요. +4. flow를 외부 API, 데이터베이스 또는 사용자 인터페이스에 연결해 보세요. +5. 여러 전문화된 crew를 하나의 flow에서 결합해 보세요. +6. [대화형 Flow](/ko/guides/flows/conversational-flows)로 멀티턴 채팅 앱 구축 (`kickoff` per message, `ChatSession`, 지연 트레이싱) + + +축하합니다! 정규 코드, 직접적인 LLM 호출, crew 기반 처리를 결합하여 포괄적인 가이드를 생성하는 첫 번째 CrewAI Flow를 성공적으로 구축하셨습니다. 이러한 기초적인 역량을 바탕으로 절차적 제어와 협업적 인텔리전스를 결합하여 복잡하고 다단계의 문제를 해결할 수 있는 점점 더 정교한 AI 애플리케이션을 만들 수 있습니다. + diff --git a/docs/v1.15.1/ko/guides/flows/inputs-id-deprecation.mdx b/docs/v1.15.1/ko/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..226db332f --- /dev/null +++ b/docs/v1.15.1/ko/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,125 @@ +--- +title: "inputs.id에서 restore_from_state_id로 마이그레이션" +description: "더 이상 지원되지 않는 inputs.id 하이드레이션에서 지원되는 restore_from_state_id 필드로 @persist 흐름을 이동" +icon: "arrow-right-arrow-left" +--- + + + `inputs` 내에서 `id`를 전달하여 `@persist` 흐름을 하이드레이트하는 것은 **더 이상 지원되지 않으며** + 향후 릴리스에서 제거될 예정입니다. 대체품인 `restore_from_state_id`는 CrewAI **v1.14.5 이상**에서 사용할 수 있으며, + 아래 단계는 업그레이드 후 적용됩니다. + + +## 개요 + +이전 실행에서 `@persist` 흐름을 하이드레이트하는 문서화된 방법은 +해당 실행의 UUID를 `inputs.id`로 전달하는 것입니다. CrewAI는 이제 +`inputs` 페이로드를 과부하하지 않고 동일한 하이드레이션을 수행하는 전용 필드인 +`restore_from_state_id`를 제공합니다 — 그리고 하이드레이션 키를 새로운 실행의 +정체성과 결합하지 않습니다. + +## 마이그레이션 + +현재 `inputs={"id": ...}`로 `@persist` 흐름을 시작하는 경우: + +```python +# 더 이상 지원되지 않음 +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +`restore_from_state_id`로 전환하십시오: + +```python +# 지원됨 +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +두 모드는 서로 다른 계보 의미론을 가지고 있습니다: + +- `inputs={"id": }` (더 이상 지원되지 않음) — **재개**: 제공된 + id 아래에 기록이 작성되어 동일한 `flow_uuid` 이력이 확장됩니다. +- `restore_from_state_id=` — **분기**: 스냅샷에서 상태를 하이드레이트한 후 + 새로운 `state.id` 아래에 기록합니다. 원본 흐름의 이력은 보존됩니다. + +대부분의 프로덕션 시나리오에서는 — 이전 상태에서 시드된 흐름을 다시 실행하는 경우 — 분기가 +필요합니다. 전체 정신 모델은 [Flow State 마스터링](/ko/guides/flows/mastering-flow-state)을 참조하십시오. + +CrewAI AMP REST API를 통해 흐름을 시작하는 경우, 아래 [AMP](#amp)에서 +동일한 페이로드 마이그레이션을 참조하십시오. + +## 왜 `@persist`에 대해 `inputs.id`를 더 이상 지원하지 않습니까? + +`inputs.id`는 현재 이전 실행에서 `@persist` 흐름을 재개하는 문서화된 방법입니다. 문제는 +동일한 UUID가 두 가지 작업을 동시에 수행한다는 것입니다: + +1. **어떤 스냅샷에서 `@persist`가 하이드레이트되는지를 선택합니다** — 해당 UUID 아래에 저장된 상태를 로드합니다. +2. **새 실행의 흐름 실행 ID가 됩니다** (`state.id`는 SDK에서; 일부 컨텍스트에서는 `flow_id`로 표시됨) — 이 + 시작에서의 모든 `@persist` 기록도 동일한 UUID 아래에 작성됩니다. + +이 이중 역할이 이 가이드에서 설명하는 문제의 근본 원인입니다. 제공된 UUID가 새 실행의 id이기도 하므로, +동일한 `inputs.id`를 전달하는 두 번의 시작은 두 개의 별도 실행이 아닙니다 — 그들은 id를 공유하고, +지속성 기록을 공유하며, (AMP에서) 실행 목록에서 행을 공유합니다. "이 스냅샷에서 하이드레이트하지만, +이 실행을 별도로 기록하십시오"라고 말할 방법이 없습니다. + +`restore_from_state_id`가 그 분리입니다. 이는 `@persist`에 어떤 스냅샷에서 하이드레이트할지를 알려주며, +새 실행이 새로운 `state.id`를 받을 수 있도록 합니다. 하이드레이션 소스와 기록된 실행은 더 이상 동일한 UUID가 아닙니다 — 이는 대부분의 프로덕션 시나리오에서 실제로 원하는 것입니다. + +## 제거 일정 + +`@persist` 하이드레이션을 위한 `inputs.id`는 CrewAI의 향후 릴리스에서 제거될 예정입니다. 즉각적인 강제 종료는 없으며 — 기존 흐름은 계속 작동합니다 — 하지만 v1.14.5 이상으로 업그레이드하면, +새 코드에서는 `restore_from_state_id`를 사용해야 하며, 기존 흐름은 다음 편리한 기회에 마이그레이션해야 합니다. + +## AMP + +흐름을 CrewAI AMP에 배포하는 경우, 마이그레이션은 배포된 팀에 전송되는 시작 페이로드로 확장되며, +`inputs.id`를 재사용하는 가시적인 증상은 배포 대시보드에 나타납니다. 아래 두 개의 하위 섹션이 이를 다룹니다. + +### 시작 페이로드 마이그레이션 + +현재 `inputs`에 `id`를 포함하여 배포된 흐름을 시작하는 경우: + +```bash +# 더 이상 지원되지 않음 +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +UUID를 최상위 `restoreFromStateId` 필드로 이동하십시오: + +```bash +# 지원됨 +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{ + "inputs": {"topic": "AI Agent Frameworks"}, + "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv" + }' \ + https://your-crew-url.crewai.com/kickoff +``` + +`restoreFromStateId`는 시작 페이로드에서 `inputs` 옆에 위치하며, 내부에 있지 않습니다. +`inputs` 객체는 이제 흐름이 실제로 소비하는 값만 포함합니다. + +### `inputs.id`가 재사용될 때 발생하는 일 + +AMP가 기존 실행과 `inputs.id`가 일치하는 흐름의 시작을 수신하면, +새로운 기록을 생성하는 대신 기존 기록으로 해결됩니다. 배포 대시보드에서 다음을 확인할 수 있습니다: + +- **실행 상태** — 새로운 실행의 상태가 이전 실행의 상태를 덮어씁니다. 완료된 실행은 + 다시 `실행 중`으로 전환되거나, `완료`된 실행은 새로운 시작이 실패할 경우 `오류`로 전환될 수 있습니다 — 어쨌든 대시보드는 더 이상 + 원래 실행을 반영하지 않습니다. +- **추적** — OTel 추적이 시작 간에 쌓이기 때문에 동일한 실행 id를 공유합니다; 이전 실행의 추적은 + 새로운 실행의 추적과 교체되거나 혼합됩니다. 단계별 재생은 더 이상 단일 실행에 해당하지 않습니다. +- **실행 목록** — 별도의 행으로 나타나야 할 시작이 단일 항목으로 축소되어 이력을 숨깁니다. + +`restoreFromStateId`로 마이그레이션하면 모든 시작이 자체 실행으로 유지됩니다 — 각자의 상태, 추적 및 목록의 행을 가지며 — 여전히 이전 실행에서 상태를 하이드레이트합니다. + + + 흐름이 어떤 모드가 필요한지 확실하지 않거나 마이그레이션 중 문제가 발생하면 지원 팀에 문의하십시오. + \ No newline at end of file diff --git a/docs/v1.15.1/ko/guides/flows/mastering-flow-state.mdx b/docs/v1.15.1/ko/guides/flows/mastering-flow-state.mdx new file mode 100644 index 000000000..5e7727cb1 --- /dev/null +++ b/docs/v1.15.1/ko/guides/flows/mastering-flow-state.mdx @@ -0,0 +1,815 @@ +--- +title: 플로우 상태 관리 마스터하기 +description: 견고한 AI 애플리케이션 구축을 위한 CrewAI 플로우에서 상태를 관리, 유지 및 활용하는 종합 가이드입니다. +icon: diagram-project +mode: "wide" +--- + +## 플로우에서 State의 힘 이해하기 + +State 관리는 모든 고급 AI 워크플로우의 중추입니다. CrewAI Flows에서 state 시스템은 컨텍스트를 유지하고, 단계 간 데이터를 공유하며, 복잡한 애플리케이션 로직을 구축할 수 있도록 해줍니다. State 관리에 능숙해지는 것은 신뢰할 수 있고, 유지보수가 용이하며, 강력한 AI 애플리케이션을 만들기 위해 필수적입니다. + +이 가이드는 CrewAI Flows에서 state를 관리하는 데 꼭 알아야 할 기본 개념부터 고급 기법까지, 실용적인 코드 예제와 함께 단계별로 안내합니다. + +### 상태 관리가 중요한 이유 + +효과적인 상태 관리는 다음을 가능하게 합니다: + +1. **실행 단계 간의 컨텍스트 유지** - 워크플로의 다양한 단계 간에 정보를 원활하게 전달할 수 있습니다. +2. **복잡한 조건부 논리 구성** - 누적된 데이터를 기반으로 의사 결정을 내릴 수 있습니다. +3. **지속적인 애플리케이션 생성** - 워크플로 진행 상황을 저장하고 복원할 수 있습니다. +4. **에러를 우아하게 처리** - 더 견고한 애플리케이션을 위한 복구 패턴을 구현할 수 있습니다. +5. **애플리케이션 확장** - 적절한 데이터 조직을 통해 복잡한 워크플로를 지원할 수 있습니다. +6. **대화형 애플리케이션 활성화** - 컨텍스트 기반 AI 상호작용을 위해 대화 내역을 저장하고 접근할 수 있습니다. + +멀티턴 채팅(`kickoff` per user line, `ChatState`, 의도 라우팅, 지연 트레이싱, `ChatSession`)은 [대화형 Flow](/ko/guides/flows/conversational-flows)를 참고하세요. + +이러한 기능을 효과적으로 활용하는 방법을 살펴보겠습니다. + +## 상태 관리 기본 사항 + +### Flow 상태 라이프사이클 + +CrewAI Flow에서 상태는 예측 가능한 라이프사이클을 따릅니다: + +1. **초기화** - flow가 생성될 때, 상태는 초기화됩니다(빈 딕셔너리 또는 Pydantic 모델 인스턴스로) +2. **수정** - flow 메서드는 실행되는 동안 상태에 접근하고 이를 수정합니다 +3. **전달** - 상태는 flow 메서드들 사이에 자동으로 전달됩니다 +4. **영속화** (선택 사항) - 상태는 스토리지에 저장될 수 있고 나중에 다시 불러올 수 있습니다 +5. **완료** - 최종 상태는 모든 실행된 메서드의 누적 변경 사항을 반영합니다 + +이 라이프사이클을 이해하는 것은 효과적인 flow를 설계하는 데 매우 중요합니다. + +### 상태 관리의 두 가지 접근 방식 + +CrewAI에서는 흐름에서 상태를 관리하는 두 가지 방법을 제공합니다: + +1. **비구조적 상태** - 유연성을 위해 딕셔너리와 유사한 객체 사용 +2. **구조적 상태** - 타입 안전성과 검증을 위해 Pydantic 모델 사용 + +각 접근 방식을 자세히 살펴보겠습니다. + +## 비구조적 상태 관리 + +비구조적 상태는 사전(dictionary)과 유사한 방식을 사용하여, 단순한 애플리케이션에 유연성과 단순성을 제공합니다. + +### 작동 방식 + +비구조화된 상태의 경우: +- `self.state`를 통해 상태에 접근하며, 이는 딕셔너리처럼 동작합니다 +- 언제든지 키를 자유롭게 추가, 수정, 삭제할 수 있습니다 +- 모든 상태는 모든 flow 메서드에서 자동으로 사용할 수 있습니다 + +### 기본 예제 + +다음은 비구조적 상태 관리를 보여주는 간단한 예제입니다: + +```python +from crewai.flow.flow import Flow, listen, start + +class UnstructuredStateFlow(Flow): + @start() + def initialize_data(self): + print("Initializing flow data") + # Add key-value pairs to state + self.state["user_name"] = "Alex" + self.state["preferences"] = { + "theme": "dark", + "language": "English" + } + self.state["items"] = [] + + # The flow state automatically gets a unique ID + print(f"Flow ID: {self.state['id']}") + + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + print(f"Previous step returned: {previous_result}") + + # Access and modify state + user = self.state["user_name"] + print(f"Processing data for {user}") + + # Add items to a list in state + self.state["items"].append("item1") + self.state["items"].append("item2") + + # Add a new key-value pair + self.state["processed"] = True + + return "Processed" + + @listen(process_data) + def generate_summary(self, previous_result): + # Access multiple state values + user = self.state["user_name"] + theme = self.state["preferences"]["theme"] + items = self.state["items"] + processed = self.state.get("processed", False) + + summary = f"User {user} has {len(items)} items with {theme} theme. " + summary += "Data is processed." if processed else "Data is not processed." + + return summary + +# Run the flow +flow = UnstructuredStateFlow() +result = flow.kickoff() +print(f"Final result: {result}") +print(f"Final state: {flow.state}") +``` + +### 비구조적 상태를 사용할 때 + +비구조적 상태는 다음과 같은 경우에 이상적입니다: +- 빠른 프로토타이핑 및 간단한 플로우 +- 동적으로 변화하는 상태 요구 +- 구조가 사전에 알려지지 않을 수 있는 경우 +- 간단한 상태 요구가 있는 플로우 + +비구조적 상태는 유연하지만, 타입 검사 및 스키마 검증이 없기 때문에 복잡한 애플리케이션에서 오류가 발생할 수 있습니다. + +## 구조화된 상태 관리 + +구조화된 상태는 Pydantic 모델을 사용하여 flow의 상태에 대한 스키마를 정의함으로써 타입 안전성, 검증, 그리고 더 나은 개발자 경험을 제공합니다. + +### 작동 방식 + +구조화된 상태에서는: +- 상태 구조를 나타내는 Pydantic 모델을 정의합니다. +- 이 모델 타입을 유형 매개변수로 Flow 클래스에 전달합니다. +- `self.state`를 통해 상태에 접근할 수 있으며, 이는 Pydantic 모델 인스턴스처럼 동작합니다. +- 모든 필드는 정의된 타입에 따라 검증됩니다. +- IDE 자동 완성 및 타입 체크 지원을 받을 수 있습니다. + +### 기본 예제 + +구조화된 상태 관리를 구현하는 방법은 다음과 같습니다: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel, Field +from typing import List, Dict, Optional + +# Define your state model +class UserPreferences(BaseModel): + theme: str = "light" + language: str = "English" + +class AppState(BaseModel): + user_name: str = "" + preferences: UserPreferences = UserPreferences() + items: List[str] = [] + processed: bool = False + completion_percentage: float = 0.0 + +# Create a flow with typed state +class StructuredStateFlow(Flow[AppState]): + @start() + def initialize_data(self): + print("Initializing flow data") + # Set state values (type-checked) + self.state.user_name = "Taylor" + self.state.preferences.theme = "dark" + + # The ID field is automatically available + print(f"Flow ID: {self.state.id}") + + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + print(f"Processing data for {self.state.user_name}") + + # Modify state (with type checking) + self.state.items.append("item1") + self.state.items.append("item2") + self.state.processed = True + self.state.completion_percentage = 50.0 + + return "Processed" + + @listen(process_data) + def generate_summary(self, previous_result): + # Access state (with autocompletion) + summary = f"User {self.state.user_name} has {len(self.state.items)} items " + summary += f"with {self.state.preferences.theme} theme. " + summary += "Data is processed." if self.state.processed else "Data is not processed." + summary += f" Completion: {self.state.completion_percentage}%" + + return summary + +# Run the flow +flow = StructuredStateFlow() +result = flow.kickoff() +print(f"Final result: {result}") +print(f"Final state: {flow.state}") +``` + +### 구조화된 상태의 이점 + +구조화된 상태를 사용하면 여러 가지 장점이 있습니다: + +1. **타입 안정성** - 개발 단계에서 타입 오류를 잡을 수 있습니다 +2. **자체 문서화** - 상태 모델이 어떤 데이터가 사용 가능한지 명확히 문서화합니다 +3. **검증** - 데이터 타입과 제약 조건을 자동으로 검증합니다 +4. **IDE 지원** - 자동 완성과 인라인 문서화를 받을 수 있습니다 +5. **기본값** - 누락된 데이터에 대한 대체값을 쉽게 정의할 수 있습니다 + +### 구조화된 상태를 사용할 때 + +구조화된 상태는 다음과 같은 경우에 권장됩니다: +- 명확하게 정의된 데이터 스키마를 가진 복잡한 플로우 +- 여러 개발자가 동일한 코드를 작업하는 팀 프로젝트 +- 데이터 검증이 중요한 애플리케이션 +- 특정 데이터 타입 및 제약 조건을 강제로 적용해야 하는 플로우 + +## 자동 상태 ID + +비구조화 상태와 구조화 상태 모두 상태 인스턴스를 추적하고 관리하는 데 도움이 되는 고유한 식별자(UUID)를 자동으로 부여받습니다. + +### 작동 방식 + +- 비구조화 state의 경우, ID는 `self.state["id"]`로 접근할 수 있습니다. +- 구조화 state의 경우, ID는 `self.state.id`로 접근할 수 있습니다. +- 이 ID는 flow가 생성될 때 자동으로 생성됩니다. +- ID는 flow의 생명주기 동안 동일하게 유지됩니다. +- ID는 추적, 로깅, 저장된 state의 조회에 사용할 수 있습니다. + +이 UUID는 persistence를 구현하거나 여러 flow 실행을 추적할 때 특히 유용합니다. + +## 동적 상태 업데이트 + +구조화된 상태를 사용하든 비구조화된 상태를 사용하든, flow의 실행 중 언제든지 상태를 동적으로 업데이트할 수 있습니다. + +### 단계 간 데이터 전달 + +Flow 메서드는 값을 반환할 수 있으며, 이러한 반환값은 리스닝 메서드의 인자로 전달됩니다: + +```python +from crewai.flow.flow import Flow, listen, start + +class DataPassingFlow(Flow): + @start() + def generate_data(self): + # This return value will be passed to listening methods + return "Generated data" + + @listen(generate_data) + def process_data(self, data_from_previous_step): + print(f"Received: {data_from_previous_step}") + # You can modify the data and pass it along + processed_data = f"{data_from_previous_step} - processed" + # Also update state + self.state["last_processed"] = processed_data + return processed_data + + @listen(process_data) + def finalize_data(self, processed_data): + print(f"Received processed data: {processed_data}") + # Access both the passed data and state + last_processed = self.state.get("last_processed", "") + return f"Final: {processed_data} (from state: {last_processed})" +``` + +이 패턴을 사용하면 직접적인 데이터 전달과 state 업데이트를 결합하여 최대한 유연하게 작업할 수 있습니다. + +## 플로우 상태 지속 + +CrewAI의 가장 강력한 기능 중 하나는 실행 간에 플로우 상태를 지속할 수 있다는 점입니다. 이를 통해 중단, 재개, 심지어 실패 후에도 복구할 수 있는 워크플로우를 구현할 수 있습니다. + +### @persist() 데코레이터 + +`@persist()` 데코레이터는 상태 지속을 자동화하여 flow의 상태를 실행의 주요 지점마다 저장합니다. + +#### 클래스 수준 지속성 + +클래스 수준에서 `@persist()`를 적용하면 모든 메서드 실행 후 상태가 저장됩니다: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + value: int = 0 + +@persist() # Apply to the entire flow class +class PersistentCounterFlow(Flow[CounterState]): + @start() + def increment(self): + self.state.value += 1 + print(f"Incremented to {self.state.value}") + return self.state.value + + @listen(increment) + def double(self, value): + self.state.value = value * 2 + print(f"Doubled to {self.state.value}") + return self.state.value + +# First run +flow1 = PersistentCounterFlow() +result1 = flow1.kickoff() +print(f"First run result: {result1}") + +# Second run - state is automatically loaded +flow2 = PersistentCounterFlow() +result2 = flow2.kickoff() +print(f"Second run result: {result2}") # Will be higher due to persisted state +``` + +#### 메서드 수준 지속성 + +더 세밀한 제어를 위해 `@persist()`를 특정 메서드에 적용할 수 있습니다: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist + +class SelectivePersistFlow(Flow): + @start() + def first_step(self): + self.state["count"] = 1 + return "First step" + + @persist() # Only persist after this method + @listen(first_step) + def important_step(self, prev_result): + self.state["count"] += 1 + self.state["important_data"] = "This will be persisted" + return "Important step completed" + + @listen(important_step) + def final_step(self, prev_result): + self.state["count"] += 1 + return f"Complete with count {self.state['count']}" +``` + +#### 영속 상태 포크하기 + +`@persist`는 `kickoff` / `kickoff_async`에서 두 가지 별개의 하이드레이션 모드를 지원합니다. 동일한 계보를 계속하려면 **재개**(`inputs["id"]`)를 사용하고, 스냅샷에서 시작하는 새 계보를 시작하려면 **포크**(`restore_from_state_id`)를 사용하세요: + +| | kickoff 후 `state.id` | `@persist` 기록 위치 | +|---|---|---| +| `inputs["id"]` (재개) | 제공된 id | 제공된 id (기록 확장) | +| `restore_from_state_id` (포크) | 새 id, 또는 고정 시 `inputs["id"]` | 새 id (원본 보존) | + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + +# 실행 1: 새 상태, counter 0 -> 1 +flow_1 = CounterFlow() +flow_1.kickoff() + +# 포크: flow_1의 최신 스냅샷에서 하이드레이트, 단 새 state.id에 기록 +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# flow_2는 counter=1(하이드레이트)로 시작하고, step()이 2로 증가시킵니다. +# flow_1의 flow_uuid 기록은 변경되지 않습니다. +``` + +동작 노트: + +- `restore_from_state_id`가 영속에서 발견되지 않음 → kickoff는 조용히 기본 동작으로 폴백됩니다 (기존 `inputs["id"]`의 미발견 동작 미러링). 예외는 발생하지 않습니다. +- `restore_from_state_id`를 `from_checkpoint`와 결합하면 `ValueError`가 발생합니다 — 서로 다른 상태 시스템(`@persist` 대 Checkpointing)을 대상으로 하므로 결합할 수 없습니다. +- `restore_from_state_id=None`(기본값)은 매개변수 없는 kickoff와 바이트 단위로 동일합니다. +- 포크 중 `inputs["id"]`를 고정하면 새 실행이 다른 플로우와 영속 키를 공유함을 의미합니다 — 일반적으로 `restore_from_state_id`만 사용하는 것이 좋습니다. + +## 고급 상태 패턴 + +### 상태 기반 조건부 로직 + +state를 사용하여 flow에서 복잡한 조건부 로직을 구현할 수 있습니다: + +```python +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class PaymentState(BaseModel): + amount: float = 0.0 + is_approved: bool = False + retry_count: int = 0 + +class PaymentFlow(Flow[PaymentState]): + @start() + def process_payment(self): + # Simulate payment processing + self.state.amount = 100.0 + self.state.is_approved = self.state.amount < 1000 + return "Payment processed" + + @router(process_payment) + def check_approval(self, previous_result): + if self.state.is_approved: + return "approved" + elif self.state.retry_count < 3: + return "retry" + else: + return "rejected" + + @listen("approved") + def handle_approval(self): + return f"Payment of ${self.state.amount} approved!" + + @listen("retry") + def handle_retry(self): + self.state.retry_count += 1 + print(f"Retrying payment (attempt {self.state.retry_count})...") + # Could implement retry logic here + return "Retry initiated" + + @listen("rejected") + def handle_rejection(self): + return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries." +``` + +### 복잡한 상태 변환 처리 + +복잡한 상태 변환의 경우, 전용 메서드를 만들어 처리할 수 있습니다. + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel +from typing import List, Dict + +class UserData(BaseModel): + name: str + active: bool = True + login_count: int = 0 + +class ComplexState(BaseModel): + users: Dict[str, UserData] = {} + active_user_count: int = 0 + +class TransformationFlow(Flow[ComplexState]): + @start() + def initialize(self): + # Add some users + self.add_user("alice", "Alice") + self.add_user("bob", "Bob") + self.add_user("charlie", "Charlie") + return "Initialized" + + @listen(initialize) + def process_users(self, _): + # Increment login counts + for user_id in self.state.users: + self.increment_login(user_id) + + # Deactivate one user + self.deactivate_user("bob") + + # Update active count + self.update_active_count() + + return f"Processed {len(self.state.users)} users" + + # Helper methods for state transformations + def add_user(self, user_id: str, name: str): + self.state.users[user_id] = UserData(name=name) + self.update_active_count() + + def increment_login(self, user_id: str): + if user_id in self.state.users: + self.state.users[user_id].login_count += 1 + + def deactivate_user(self, user_id: str): + if user_id in self.state.users: + self.state.users[user_id].active = False + self.update_active_count() + + def update_active_count(self): + self.state.active_user_count = sum( + 1 for user in self.state.users.values() if user.active + ) +``` + +이와 같은 헬퍼 메서드 생성 패턴은 flow 메서드를 깔끔하게 유지하면서 복잡한 상태 조작을 가능하게 해줍니다. + +## Crews로 상태 관리하기 + +CrewAI에서 가장 강력한 패턴 중 하나는 flow 상태 관리와 crew 실행을 결합하는 것입니다. + +### 크루에 상태 전달하기 + +플로우 상태를 사용하여 크루에 매개변수를 전달할 수 있습니다: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + +class ResearchState(BaseModel): + topic: str = "" + depth: str = "medium" + results: str = "" + +class ResearchFlow(Flow[ResearchState]): + @start() + def get_parameters(self): + # In a real app, this might come from user input + self.state.topic = "Artificial Intelligence Ethics" + self.state.depth = "deep" + return "Parameters set" + + @listen(get_parameters) + def execute_research(self, _): + # Create agents + researcher = Agent( + role="Research Specialist", + goal=f"Research {self.state.topic} in {self.state.depth} detail", + backstory="You are an expert researcher with a talent for finding accurate information." + ) + + writer = Agent( + role="Content Writer", + goal="Transform research into clear, engaging content", + backstory="You excel at communicating complex ideas clearly and concisely." + ) + + # Create tasks + research_task = Task( + description=f"Research {self.state.topic} with {self.state.depth} analysis", + expected_output="Comprehensive research notes in markdown format", + agent=researcher + ) + + writing_task = Task( + description=f"Create a summary on {self.state.topic} based on the research", + expected_output="Well-written article in markdown format", + agent=writer, + context=[research_task] + ) + + # Create and run crew + research_crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + verbose=True + ) + + # Run crew and store result in state + result = research_crew.kickoff() + self.state.results = result.raw + + return "Research completed" + + @listen(execute_research) + def summarize_results(self, _): + # Access the stored results + result_length = len(self.state.results) + return f"Research on {self.state.topic} completed with {result_length} characters of results." +``` + +### State에서 Crew 출력 처리하기 + +Crew가 완료되면, 해당 출력을 처리하여 flow state에 저장할 수 있습니다: + +```python +@listen(execute_crew) +def process_crew_results(self, _): + # Parse the raw results (assuming JSON output) + import json + try: + results_dict = json.loads(self.state.raw_results) + self.state.processed_results = { + "title": results_dict.get("title", ""), + "main_points": results_dict.get("main_points", []), + "conclusion": results_dict.get("conclusion", "") + } + return "Results processed successfully" + except json.JSONDecodeError: + self.state.error = "Failed to parse crew results as JSON" + return "Error processing results" +``` + +## 상태 관리 모범 사례 + +### 1. 상태를 집중적으로 유지하세요 + +상태를 설계할 때 꼭 필요한 내용만 포함하도록 하세요: + +```python +# Too broad +class BloatedState(BaseModel): + user_data: Dict = {} + system_settings: Dict = {} + temporary_calculations: List = [] + debug_info: Dict = {} + # ...many more fields + +# Better: Focused state +class FocusedState(BaseModel): + user_id: str + preferences: Dict[str, str] + completion_status: Dict[str, bool] +``` + +### 2. 복잡한 플로우를 위한 구조화된 상태 사용 + +플로우의 복잡도가 증가할수록 구조화된 상태의 가치는 점점 커집니다: + +```python +# Simple flow can use unstructured state +class SimpleGreetingFlow(Flow): + @start() + def greet(self): + self.state["name"] = "World" + return f"Hello, {self.state['name']}!" + +# Complex flow benefits from structured state +class UserRegistrationState(BaseModel): + username: str + email: str + verification_status: bool = False + registration_date: datetime = Field(default_factory=datetime.now) + last_login: Optional[datetime] = None + +class RegistrationFlow(Flow[UserRegistrationState]): + # Methods with strongly-typed state access +``` + +### 3. 문서 상태 전이 + +복잡한 흐름의 경우, 실행 중에 상태가 어떻게 변하는지 문서화하세요: + +```python +@start() +def initialize_order(self): + """ + Initialize order state with empty values. + + State before: {} + State after: {order_id: str, items: [], status: 'new'} + """ + self.state.order_id = str(uuid.uuid4()) + self.state.items = [] + self.state.status = "new" + return "Order initialized" +``` + +### 4. 상태 오류를 정상적으로 처리하기 + +상태 접근에 대한 오류 처리를 구현하세요: + +```python +@listen(previous_step) +def process_data(self, _): + try: + # Try to access a value that might not exist + user_preference = self.state.preferences.get("theme", "default") + except (AttributeError, KeyError): + # Handle the error gracefully + self.state.errors = self.state.get("errors", []) + self.state.errors.append("Failed to access preferences") + user_preference = "default" + + return f"Used preference: {user_preference}" +``` + +### 5. 상태를 사용하여 진행 상황 추적 + +긴 실행 흐름에서 진행 상황을 추적하기 위해 상태를 활용하세요: + +```python +class ProgressTrackingFlow(Flow): + @start() + def initialize(self): + self.state["total_steps"] = 3 + self.state["current_step"] = 0 + self.state["progress"] = 0.0 + self.update_progress() + return "Initialized" + + def update_progress(self): + """Helper method to calculate and update progress""" + if self.state.get("total_steps", 0) > 0: + self.state["progress"] = (self.state.get("current_step", 0) / + self.state["total_steps"]) * 100 + print(f"Progress: {self.state['progress']:.1f}%") + + @listen(initialize) + def step_one(self, _): + # Do work... + self.state["current_step"] = 1 + self.update_progress() + return "Step 1 complete" + + # Additional steps... +``` + +### 6. 가능한 경우 불변(Immutable) 연산 사용하기 + +특히 구조화된 상태에서는 명확성을 위해 불변 연산을 선호하세요: + +```python +# 리스트를 즉시 수정하는 대신: +self.state.items.append(new_item) # 변경 가능한 연산 + +# 새로운 상태를 생성하는 것을 고려하세요: +from pydantic import BaseModel +from typing import List + +class ItemState(BaseModel): + items: List[str] = [] + +class ImmutableFlow(Flow[ItemState]): + @start() + def add_item(self): + # 추가된 항목과 함께 새로운 리스트 생성 + self.state.items = [*self.state.items, "new item"] + return "Item added" +``` + +## 플로우 상태 디버깅 + +### 상태 변경 로깅 + +개발할 때 상태 변화를 추적하기 위해 로깅을 추가하세요: + +```python +import logging +logging.basicConfig(level=logging.INFO) + +class LoggingFlow(Flow): + def log_state(self, step_name): + logging.info(f"State after {step_name}: {self.state}") + + @start() + def initialize(self): + self.state["counter"] = 0 + self.log_state("initialize") + return "Initialized" + + @listen(initialize) + def increment(self, _): + self.state["counter"] += 1 + self.log_state("increment") + return f"Incremented to {self.state['counter']}" +``` + +### 상태 시각화 + +디버깅을 위해 상태를 시각화하는 메서드를 추가할 수 있습니다: + +```python +def visualize_state(self): + """Create a simple visualization of the current state""" + import json + from rich.console import Console + from rich.panel import Panel + + console = Console() + + if hasattr(self.state, "model_dump"): + # Pydantic v2 + state_dict = self.state.model_dump() + elif hasattr(self.state, "dict"): + # Pydantic v1 + state_dict = self.state.dict() + else: + # Unstructured state + state_dict = dict(self.state) + + # Remove id for cleaner output + if "id" in state_dict: + state_dict.pop("id") + + state_json = json.dumps(state_dict, indent=2, default=str) + console.print(Panel(state_json, title="Current Flow State")) +``` + +## 결론 + +CrewAI Flows에서 상태 관리를 마스터하면 컨텍스트를 유지하고, 복잡한 결정을 내리며, 일관된 결과를 제공하는 정교하고 견고한 AI 애플리케이션을 구축할 수 있는 힘을 얻게 됩니다. + +비구조화 상태든 구조화 상태든 적절한 상태 관리 방식을 구현하면 유지 관리가 용이하고, 확장 가능하며, 실제 문제를 효과적으로 해결할 수 있는 플로우를 만들 수 있습니다. + +더 복잡한 플로우를 개발할수록 좋은 상태 관리는 유연성과 구조성 사이의 올바른 균형을 찾는 것임을 기억하세요. 이를 통해 코드가 강력하면서도 이해하기 쉬워집니다. + + +이제 CrewAI Flows에서 상태 관리의 개념과 실습을 마스터하셨습니다! 이 지식을 통해 컨텍스트를 효과적으로 유지하고, 단계 간 데이터를 공유하며, 정교한 애플리케이션 로직을 구현하는 견고한 AI 워크플로우를 만들 수 있습니다. + + +## 다음 단계 + +- flow에서 구조화된 state와 비구조화된 state를 모두 실험해 보세요 +- 장기 실행 워크플로를 위해 state 영속성을 구현해 보세요 +- [첫 crew 만들기](/ko/guides/crews/first-crew)를 탐색하여 crew와 flow가 어떻게 함께 작동하는지 확인해 보세요 +- 더 고급 기능을 원한다면 [Flow 참고 문서](/ko/concepts/flows)를 확인해 보세요 \ No newline at end of file diff --git a/docs/v1.15.1/ko/guides/migration/migrating-from-langgraph.mdx b/docs/v1.15.1/ko/guides/migration/migrating-from-langgraph.mdx new file mode 100644 index 000000000..fe708602d --- /dev/null +++ b/docs/v1.15.1/ko/guides/migration/migrating-from-langgraph.mdx @@ -0,0 +1,518 @@ +--- +title: "LangGraph에서 CrewAI로 옮기기: 엔지니어를 위한 실전 가이드" +description: LangGraph로 이미 구축했다면, 프로젝트를 CrewAI로 빠르게 옮기는 방법을 알아보세요 +icon: switch +mode: "wide" +--- + +LangGraph로 에이전트를 구축해 왔습니다. `StateGraph`와 씨름하고, 조건부 에지를 연결하고, 새벽 2시에 상태 딕셔너리를 디버깅해 본 적도 있죠. 동작은 하지만 — 어느 순간부터 프로덕션으로 가는 더 나은 길이 없을까 고민하게 됩니다. + +있습니다. **CrewAI Flows**는 이벤트 기반 오케스트레이션, 조건부 라우팅, 공유 상태라는 동일한 힘을 훨씬 적은 보일러플레이트와 실제로 다단계 AI 워크플로우를 생각하는 방식에 잘 맞는 정신적 모델로 제공합니다. + +이 글은 핵심 개념을 나란히 비교하고 실제 코드 비교를 보여주며, 다음으로 손이 갈 프레임워크가 왜 CrewAI Flows인지 설명합니다. + +--- + +## 정신적 모델의 전환 + +LangGraph는 **그래프**로 생각하라고 요구합니다: 노드, 에지, 그리고 상태 딕셔너리. 모든 워크플로우는 계산 단계 사이의 전이를 명시적으로 연결하는 방향 그래프입니다. 강력하지만, 특히 워크플로우가 몇 개의 결정 지점이 있는 순차적 흐름일 때 이 추상화는 오버헤드를 가져옵니다. + +CrewAI Flows는 **이벤트**로 생각하라고 요구합니다: 시작하는 메서드, 결과를 듣는 메서드, 실행을 라우팅하는 메서드. 워크플로우의 토폴로지는 명시적 그래프 구성 대신 데코레이터 어노테이션에서 드러납니다. 이것은 단순한 문법 설탕이 아니라 — 파이프라인을 설계하고 읽고 유지하는 방식을 바꿉니다. + +핵심 매핑은 다음과 같습니다: + +| LangGraph 개념 | CrewAI Flows 대응 | +| --- | --- | +| `StateGraph` class | `Flow` class | +| `add_node()` | Methods decorated with `@start`, `@listen` | +| `add_edge()` / `add_conditional_edges()` | `@listen()` / `@router()` decorators | +| `TypedDict` state | Pydantic `BaseModel` state | +| `START` / `END` constants | `@start()` decorator / natural method return | +| `graph.compile()` | `flow.kickoff()` | +| Checkpointer / persistence | Built-in memory (LanceDB-backed) | + +실제로 어떻게 보이는지 살펴보겠습니다. + +--- + +## 데모 1: 간단한 순차 파이프라인 + +주제를 받아 조사하고, 요약을 작성한 뒤, 결과를 포맷팅하는 파이프라인을 만든다고 해봅시다. 각 프레임워크는 이렇게 처리합니다. + +### LangGraph 방식 + +```python +from typing import TypedDict +from langgraph.graph import StateGraph, START, END + +class ResearchState(TypedDict): + topic: str + raw_research: str + summary: str + formatted_output: str + +def research_topic(state: ResearchState) -> dict: + # Call an LLM or search API + result = llm.invoke(f"Research the topic: {state['topic']}") + return {"raw_research": result} + +def write_summary(state: ResearchState) -> dict: + result = llm.invoke( + f"Summarize this research:\n{state['raw_research']}" + ) + return {"summary": result} + +def format_output(state: ResearchState) -> dict: + result = llm.invoke( + f"Format this summary as a polished article section:\n{state['summary']}" + ) + return {"formatted_output": result} + +# Build the graph +graph = StateGraph(ResearchState) +graph.add_node("research", research_topic) +graph.add_node("summarize", write_summary) +graph.add_node("format", format_output) + +graph.add_edge(START, "research") +graph.add_edge("research", "summarize") +graph.add_edge("summarize", "format") +graph.add_edge("format", END) + +# Compile and run +app = graph.compile() +result = app.invoke({"topic": "quantum computing advances in 2026"}) +print(result["formatted_output"]) +``` + +함수를 정의하고 노드로 등록한 다음, 모든 전이를 수동으로 연결합니다. 이렇게 단순한 순서인데도 의례처럼 해야 할 작업이 많습니다. + +### CrewAI Flows 방식 + +```python +from crewai import LLM, Agent, Crew, Process, Task +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class ResearchState(BaseModel): + topic: str = "" + raw_research: str = "" + summary: str = "" + formatted_output: str = "" + +class ResearchFlow(Flow[ResearchState]): + @start() + def research_topic(self): + # Option 1: Direct LLM call + result = llm.call(f"Research the topic: {self.state.topic}") + self.state.raw_research = result + return result + + @listen(research_topic) + def write_summary(self, research_output): + # Option 2: A single agent + summarizer = Agent( + role="Research Summarizer", + goal="Produce concise, accurate summaries of research content", + backstory="You are an expert at distilling complex research into clear, " + "digestible summaries.", + llm=llm, + verbose=True, + ) + result = summarizer.kickoff( + f"Summarize this research:\n{self.state.raw_research}" + ) + self.state.summary = str(result) + return self.state.summary + + @listen(write_summary) + def format_output(self, summary_output): + # Option 3: a complete crew (with one or more agents) + formatter = Agent( + role="Content Formatter", + goal="Transform research summaries into polished, publication-ready article sections", + backstory="You are a skilled editor with expertise in structuring and " + "presenting technical content for a general audience.", + llm=llm, + verbose=True, + ) + format_task = Task( + description=f"Format this summary as a polished article section:\n{self.state.summary}", + expected_output="A well-structured, polished article section ready for publication.", + agent=formatter, + ) + crew = Crew( + agents=[formatter], + tasks=[format_task], + process=Process.sequential, + verbose=True, + ) + result = crew.kickoff() + self.state.formatted_output = str(result) + return self.state.formatted_output + +# Run the flow +flow = ResearchFlow() +flow.state.topic = "quantum computing advances in 2026" +result = flow.kickoff() +print(flow.state.formatted_output) + +``` + +눈에 띄는 차이점이 있습니다: 그래프 구성 없음, 에지 연결 없음, 컴파일 단계 없음. 실행 순서는 로직이 있는 곳에서 바로 선언됩니다. `@start()`는 진입점을 표시하고, `@listen(method_name)`은 단계들을 연결합니다. 상태는 타입 안전성, 검증, IDE 자동 완성까지 제공하는 제대로 된 Pydantic 모델입니다. + +--- + +## 데모 2: 조건부 라우팅 + +여기서 흥미로워집니다. 콘텐츠 유형에 따라 서로 다른 처리 경로로 라우팅하는 파이프라인을 만든다고 해봅시다. + +### LangGraph 방식 + +```python +from typing import TypedDict, Literal +from langgraph.graph import StateGraph, START, END + +class ContentState(TypedDict): + input_text: str + content_type: str + result: str + +def classify_content(state: ContentState) -> dict: + content_type = llm.invoke( + f"Classify this content as 'technical', 'creative', or 'business':\n{state['input_text']}" + ) + return {"content_type": content_type.strip().lower()} + +def process_technical(state: ContentState) -> dict: + result = llm.invoke(f"Process as technical doc:\n{state['input_text']}") + return {"result": result} + +def process_creative(state: ContentState) -> dict: + result = llm.invoke(f"Process as creative writing:\n{state['input_text']}") + return {"result": result} + +def process_business(state: ContentState) -> dict: + result = llm.invoke(f"Process as business content:\n{state['input_text']}") + return {"result": result} + +# Routing function +def route_content(state: ContentState) -> Literal["technical", "creative", "business"]: + return state["content_type"] + +# Build the graph +graph = StateGraph(ContentState) +graph.add_node("classify", classify_content) +graph.add_node("technical", process_technical) +graph.add_node("creative", process_creative) +graph.add_node("business", process_business) + +graph.add_edge(START, "classify") +graph.add_conditional_edges( + "classify", + route_content, + { + "technical": "technical", + "creative": "creative", + "business": "business", + } +) +graph.add_edge("technical", END) +graph.add_edge("creative", END) +graph.add_edge("business", END) + +app = graph.compile() +result = app.invoke({"input_text": "Explain how TCP handshakes work"}) +``` + +별도의 라우팅 함수, 명시적 조건부 에지 매핑, 그리고 모든 분기에 대한 종료 에지가 필요합니다. 라우팅 결정 로직이 그 결정을 만들어 내는 노드와 분리됩니다. + +### CrewAI Flows 방식 + +```python +from crewai import LLM, Agent +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class ContentState(BaseModel): + input_text: str = "" + content_type: str = "" + result: str = "" + +class ContentFlow(Flow[ContentState]): + @start() + def classify_content(self): + self.state.content_type = ( + llm.call( + f"Classify this content as 'technical', 'creative', or 'business':\n" + f"{self.state.input_text}" + ) + .strip() + .lower() + ) + return self.state.content_type + + @router(classify_content) + def route_content(self, classification): + if classification == "technical": + return "process_technical" + elif classification == "creative": + return "process_creative" + else: + return "process_business" + + @listen("process_technical") + def handle_technical(self): + agent = Agent( + role="Technical Writer", + goal="Produce clear, accurate technical documentation", + backstory="You are an expert technical writer who specializes in " + "explaining complex technical concepts precisely.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as technical doc:\n{self.state.input_text}") + ) + + @listen("process_creative") + def handle_creative(self): + agent = Agent( + role="Creative Writer", + goal="Craft engaging and imaginative creative content", + backstory="You are a talented creative writer with a flair for " + "compelling storytelling and vivid expression.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as creative writing:\n{self.state.input_text}") + ) + + @listen("process_business") + def handle_business(self): + agent = Agent( + role="Business Writer", + goal="Produce professional, results-oriented business content", + backstory="You are an experienced business writer who communicates " + "strategy and value clearly to professional audiences.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as business content:\n{self.state.input_text}") + ) + +flow = ContentFlow() +flow.state.input_text = "Explain how TCP handshakes work" +flow.kickoff() +print(flow.state.result) + +``` + +`@router()` 데코레이터는 메서드를 결정 지점으로 만듭니다. 리스너와 매칭되는 문자열을 반환하므로, 매핑 딕셔너리도, 별도의 라우팅 함수도 필요 없습니다. 분기 로직이 Python `if` 문처럼 읽히는 이유는, 실제로 `if` 문이기 때문입니다. + +--- + +## 데모 3: AI 에이전트 Crew를 Flow에 통합하기 + +여기서 CrewAI의 진짜 힘이 드러납니다. Flows는 LLM 호출을 연결하는 것에 그치지 않고 자율적인 에이전트 **Crew** 전체를 오케스트레이션합니다. 이는 LangGraph에 기본으로 대응되는 개념이 없습니다. + +```python +from crewai import Agent, Task, Crew +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ArticleState(BaseModel): + topic: str = "" + research: str = "" + draft: str = "" + final_article: str = "" + +class ArticleFlow(Flow[ArticleState]): + + @start() + def run_research_crew(self): + """A full Crew of agents handles research.""" + researcher = Agent( + role="Senior Research Analyst", + goal=f"Produce comprehensive research on: {self.state.topic}", + backstory="You're a veteran analyst known for thorough, " + "well-sourced research reports.", + llm="gpt-4o" + ) + + research_task = Task( + description=f"Research '{self.state.topic}' thoroughly. " + "Cover key trends, data points, and expert opinions.", + expected_output="A detailed research brief with sources.", + agent=researcher + ) + + crew = Crew(agents=[researcher], tasks=[research_task]) + result = crew.kickoff() + self.state.research = result.raw + return result.raw + + @listen(run_research_crew) + def run_writing_crew(self, research_output): + """A different Crew handles writing.""" + writer = Agent( + role="Technical Writer", + goal="Write a compelling article based on provided research.", + backstory="You turn complex research into engaging, clear prose.", + llm="gpt-4o" + ) + + editor = Agent( + role="Senior Editor", + goal="Review and polish articles for publication quality.", + backstory="20 years of editorial experience at top tech publications.", + llm="gpt-4o" + ) + + write_task = Task( + description=f"Write an article based on this research:\n{self.state.research}", + expected_output="A well-structured draft article.", + agent=writer + ) + + edit_task = Task( + description="Review, fact-check, and polish the draft article.", + expected_output="A publication-ready article.", + agent=editor + ) + + crew = Crew(agents=[writer, editor], tasks=[write_task, edit_task]) + result = crew.kickoff() + self.state.final_article = result.raw + return result.raw + +# Run the full pipeline +flow = ArticleFlow() +flow.state.topic = "The Future of Edge AI" +flow.kickoff() +print(flow.state.final_article) +``` + +핵심 인사이트는 다음과 같습니다: **Flows는 오케스트레이션 레이어를, Crews는 지능 레이어를 제공합니다.** Flow의 각 단계는 각자의 역할, 목표, 도구를 가진 협업 에이전트 팀을 띄울 수 있습니다. 구조화되고 예측 가능한 제어 흐름 *그리고* 자율적 에이전트 협업 — 두 세계의 장점을 모두 얻습니다. + +LangGraph에서 비슷한 것을 하려면 노드 함수 안에 에이전트 통신 프로토콜, 도구 호출 루프, 위임 로직을 직접 구현해야 합니다. 가능하긴 하지만, 매번 처음부터 배관을 만드는 셈입니다. + +--- + +## 데모 4: 병렬 실행과 동기화 + +실제 파이프라인은 종종 작업을 병렬로 분기하고 결과를 합쳐야 합니다. CrewAI Flows는 `and_`와 `or_` 연산자로 이를 우아하게 처리합니다. + +```python +from crewai import LLM +from crewai.flow.flow import Flow, and_, listen, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class AnalysisState(BaseModel): + topic: str = "" + market_data: str = "" + tech_analysis: str = "" + competitor_intel: str = "" + final_report: str = "" + +class ParallelAnalysisFlow(Flow[AnalysisState]): + @start() + def start_method(self): + pass + + @listen(start_method) + def gather_market_data(self): + # Your agentic or deterministic code + pass + + @listen(start_method) + def run_tech_analysis(self): + # Your agentic or deterministic code + pass + + @listen(start_method) + def gather_competitor_intel(self): + # Your agentic or deterministic code + pass + + @listen(and_(gather_market_data, run_tech_analysis, gather_competitor_intel)) + def synthesize_report(self): + # Your agentic or deterministic code + pass + +flow = ParallelAnalysisFlow() +flow.state.topic = "AI-powered developer tools" +flow.kickoff() + +``` + +여러 `@start()` 데코레이터는 병렬로 실행됩니다. `@listen` 데코레이터의 `and_()` 결합자는 `synthesize_report`가 *세 가지* 상위 메서드가 모두 완료된 뒤에만 실행되도록 보장합니다. *어떤* 상위 작업이든 끝나는 즉시 진행하고 싶다면 `or_()`도 사용할 수 있습니다. + +LangGraph에서는 병렬 분기, 동기화 노드, 신중한 상태 병합이 포함된 fan-out/fan-in 패턴을 만들어야 하며 — 모든 것을 에지로 명시적으로 연결해야 합니다. + +--- + +## 프로덕션에서 CrewAI Flows를 쓰는 이유 + +깔끔한 문법을 넘어, Flows는 여러 프로덕션 핵심 이점을 제공합니다: + +**내장 상태 지속성.** Flow 상태는 LanceDB에 의해 백업되므로 워크플로우가 크래시에서 살아남고, 재개될 수 있으며, 실행 간에 지식을 축적할 수 있습니다. LangGraph는 별도의 체크포인터를 구성해야 합니다. + +**타입 안전한 상태 관리.** Pydantic 모델은 즉시 검증, 직렬화, IDE 지원을 제공합니다. LangGraph의 `TypedDict` 상태는 런타임 검증을 하지 않습니다. + +**일급 에이전트 오케스트레이션.** Crews는 기본 프리미티브입니다. 역할, 목표, 배경, 도구를 가진 에이전트를 정의하고, Flow의 구조적 틀 안에서 자율적으로 협업하게 합니다. 다중 에이전트 조율을 다시 만들 필요가 없습니다. + +**더 단순한 정신적 모델.** 데코레이터는 의도를 선언합니다. `@start`는 "여기서 시작", `@listen(x)`는 "x 이후 실행", `@router(x)`는 "x 이후 어디로 갈지 결정"을 의미합니다. 코드는 자신이 설명하는 워크플로우처럼 읽힙니다. + +**CLI 통합.** `crewai run`으로 Flows를 실행합니다. 별도의 컴파일 단계나 그래프 직렬화가 없습니다. Flow는 Python 클래스이며, 그대로 실행됩니다. + +--- + +## 마이그레이션 치트 시트 + +LangGraph 코드베이스를 CrewAI Flows로 옮기고 싶다면, 다음의 실전 변환 가이드를 참고하세요: + +1. **상태를 매핑하세요.** `TypedDict`를 Pydantic `BaseModel`로 변환하고 모든 필드에 기본값을 추가하세요. +2. **노드를 메서드로 변환하세요.** 각 `add_node` 함수는 `Flow` 서브클래스의 메서드가 됩니다. `state["field"]` 읽기는 `self.state.field`로 바꾸세요. +3. **에지를 데코레이터로 교체하세요.** `add_edge(START, "first_node")`는 첫 메서드의 `@start()`가 됩니다. 순차적인 `add_edge("a", "b")`는 `b` 메서드의 `@listen(a)`가 됩니다. +4. **조건부 에지는 `@router`로 교체하세요.** 라우팅 함수와 `add_conditional_edges()` 매핑은 하나의 `@router()` 메서드로 통합하고, 라우트 문자열을 반환하세요. +5. **compile + invoke를 kickoff으로 교체하세요.** `graph.compile()`를 제거하고 `flow.kickoff()`를 호출하세요. +6. **Crew가 들어갈 지점을 고려하세요.** 복잡한 다단계 에이전트 로직이 있는 노드는 Crew로 분리할 후보입니다. 이 부분에서 가장 큰 품질 향상을 체감할 수 있습니다. + +--- + +## 시작하기 + +CrewAI를 설치하고 새 Flow 프로젝트를 스캐폴딩하세요: + +```bash +pip install crewai +crewai create flow my_first_flow +cd my_first_flow +``` + +이렇게 하면 바로 편집 가능한 Flow 클래스, 설정 파일, 그리고 `type = "flow"`가 이미 설정된 `pyproject.toml`이 포함된 프로젝트 구조가 생성됩니다. 다음으로 실행하세요: + +```bash +crewai run +``` + +그 다음부터는 에이전트를 추가하고 리스너를 연결한 뒤, 배포하면 됩니다. + +--- + +## 마무리 + +LangGraph는 AI 워크플로우에 구조가 필요하다는 사실을 생태계에 일깨워 주었습니다. 중요한 교훈이었습니다. 하지만 CrewAI Flows는 그 교훈을 더 빠르게 쓰고, 더 쉽게 읽으며, 프로덕션에서 더 강력한 형태로 제공합니다 — 특히 워크플로우에 여러 에이전트의 협업이 포함될 때 그렇습니다. + +단일 에이전트 체인을 넘는 무엇인가를 만들고 있다면, Flows를 진지하게 검토해 보세요. 데코레이터 기반 모델, Crews의 네이티브 통합, 내장 상태 관리를 통해 배관 작업에 쓰는 시간을 줄이고, 중요한 문제에 더 많은 시간을 쓸 수 있습니다. + +`crewai create flow`로 시작하세요. 후회하지 않을 겁니다. diff --git a/docs/v1.15.1/ko/guides/migration/upgrading-crewai.mdx b/docs/v1.15.1/ko/guides/migration/upgrading-crewai.mdx new file mode 100644 index 000000000..6e96a4480 --- /dev/null +++ b/docs/v1.15.1/ko/guides/migration/upgrading-crewai.mdx @@ -0,0 +1,190 @@ +--- +title: "CrewAI 업그레이드" +description: "프로젝트에서 CrewAI를 업그레이드하고 버전 간 브레이킹 체인지에 적응하는 방법." +icon: "arrow-up-circle" +--- + +## 개요 + +CrewAI 릴리스는 정기적으로 새로운 기능을 제공합니다. 이 가이드는 CLI와 프로젝트의 가상 환경을 모두 최신 상태로 유지하기 위한 실용적인 단계를 안내합니다. + +새로 시작한다면 [설치](/ko/installation)를 참고하세요. 다른 프레임워크에서 옮겨오는 경우라면 [LangGraph에서 마이그레이션](/ko/guides/migration/migrating-from-langgraph)을 참고하세요. + +--- + +## 업그레이드할 수 있는 두 가지 + +CrewAI는 사용자의 머신에 두 곳에 존재하며, 각각 독립적으로 업그레이드됩니다: + +| 무엇 | 설치 방법 | 업그레이드 방법 | +|---|---|---| +| **전역 `crewai` CLI** | `uv tool install crewai` | `uv tool install crewai --upgrade` | +| **프로젝트 venv** (코드가 실행되는 곳) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` 후 `crewai install` | + +이 둘은 — 그리고 자주 — 동기화가 어긋날 수 있습니다. `crewai --version`은 CLI 버전을 알려줍니다. 프로젝트 안에서 `uv pip show crewai`를 실행하면 venv 버전을 알려줍니다. 둘이 다른 것은 정상이며, 실행 중인 코드에 중요한 것은 venv 버전입니다. + +## 왜 `crewai install`만으로는 업그레이드되지 않는가 + +`crewai install`은 `uv sync`를 감싼 얇은 래퍼입니다. 현재 `uv.lock` 파일이 지시하는 것 그대로를 설치할 뿐이며 — 어떤 버전 제약도 올리지 **않습니다**. + +`pyproject.toml`이 `crewai>=1.11.1`이라 적혀 있고 lock 파일이 `1.11.1`로 해소되었다면, `crewai install`을 실행해도 `1.14.4`가 사용 가능하더라도 영원히 `1.11.1`에 머무릅니다. + +실제로 업그레이드하려면 다음을 해야 합니다: + +1. `pyproject.toml`의 버전 제약 업데이트 +2. lock 파일 재해소 +3. venv 동기화 + +`uv add`는 이 세 가지를 한 번에 처리합니다. + +## 프로젝트 업그레이드 방법 + +```bash +# 제약을 올리고 lock을 다시 만드는 한 번의 명령 +uv add "crewai[tools]>=1.14.4" + +# venv 동기화 (crewai install은 내부적으로 uv sync를 호출) +crewai install + +# 확인 +uv pip show crewai +# → Version: 1.14.4 +``` + +`[tools]`를 프로젝트에서 사용하는 extras로 바꾸세요 (예: `[tools,anthropic]`). 잘 모르겠다면 `pyproject.toml`의 `dependencies` 목록을 확인하세요. + + + `uv add`는 `pyproject.toml`과 `uv.lock`을 **둘 다** 원자적으로 업데이트합니다. `pyproject.toml`을 수동으로 편집하는 경우, `crewai install`이 새 버전을 가져가도록 하기 전에 `uv lock --upgrade-package crewai`를 실행해 lock 파일을 다시 해소해야 합니다. + + +## 전역 CLI 업그레이드 + +전역 CLI는 프로젝트와 분리되어 있습니다. 다음 명령으로 업그레이드하세요: + +```bash +uv tool install crewai --upgrade +``` + +업그레이드 후 셸이 `PATH`에 대해 경고하면 새로고침하세요: + +```bash +uv tool update-shell +``` + +이 명령은 프로젝트의 venv를 **건드리지 않습니다** — 프로젝트 내부에서는 여전히 `uv add` + `crewai install`이 필요합니다. + +## 둘이 동기화되었는지 확인 + +```bash +# 전역 CLI 버전 +crewai --version + +# 프로젝트 venv 버전 +uv pip show crewai | grep Version +``` + +둘이 일치할 필요는 없지만 — 런타임 동작에 중요한 것은 프로젝트 venv 버전입니다. + + + CrewAI는 `Python >=3.10, <3.14`를 요구합니다. `uv`가 더 오래된 인터프리터로 설치되어 있다면, `crewai install`을 실행하기 전에 지원되는 Python으로 프로젝트 venv를 다시 만드세요. + + +--- + +## 브레이킹 체인지 및 마이그레이션 노트 + +대부분의 업그레이드는 작은 조정만 필요합니다. 아래 항목들은 조용히 깨지거나 헷갈리는 트레이스백을 내는 영역들입니다. + +### Import 경로: tools와 `BaseTool` + +tools의 정식 import 위치는 `crewai.tools`입니다. 옛 경로들이 아직 튜토리얼에 등장하지만 업데이트해야 합니다. + +```python +# 이전 +from crewai_tools import BaseTool +from crewai.agents.tools import tool + +# 이후 +from crewai.tools import BaseTool, tool +``` + +`@tool` 데코레이터와 `BaseTool` 서브클래스는 모두 `crewai.tools`에 있습니다. `AgentFinish` 등 내부 에이전트 심볼들은 더 이상 공개 표면이 아닙니다 — import 중이었다면 event listener나 `Task` 콜백으로 전환하세요. + +### `Agent` 파라미터 변경 + +```python +from crewai import Agent + +agent = Agent( + role="Researcher", + goal="Find authoritative sources on {topic}", + backstory="You are a careful, source-driven researcher.", + llm="gpt-4o-mini", # 모델명 문자열 또는 LLM 객체 + verbose=True, # 정수 레벨이 아닌 bool + max_iter=15, # 버전마다 기본값이 바뀌었음 — 명시적으로 지정 + allow_delegation=False, +) +``` + +- `llm`은 문자열 모델명(설정된 provider를 통해 해소)이나 세밀한 제어를 위한 `LLM` 객체를 받습니다. +- `verbose`는 일반 `bool`입니다. 정수를 전달해도 더 이상 로그 레벨을 토글하지 않습니다. +- `max_iter`의 기본값은 릴리스 사이에 변경되었습니다. 첫 tool 호출 후 에이전트가 조용히 반복을 멈춘다면 `max_iter`를 명시적으로 지정하세요. + +### `Crew` 파라미터 + +```python +from crewai import Crew, Process + +crew = Crew( + agents=[...], + tasks=[...], + process=Process.sequential, # 또는 Process.hierarchical + memory=True, + cache=True, + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}}, +) +``` + +- `process=Process.hierarchical`은 `manager_llm=` 또는 `manager_agent=` 중 하나가 필요합니다. 둘 다 없으면 kickoff 시 검증 단계에서 오류가 발생합니다. +- 기본이 아닌 임베딩 provider와 함께 `memory=True`를 쓰려면 `embedder` dict가 필요합니다 — 아래의 [메모리와 embedder 설정](#memory-embedder-config)을 참고하세요. + +### `Task` 구조화된 출력 + +`output_pydantic`, `output_json`, 또는 `output_file`을 사용해 task 결과를 타입이 지정된 형태로 강제할 수 있습니다: + +```python +from pydantic import BaseModel +from crewai import Task + +class Article(BaseModel): + title: str + body: str + +write = Task( + description="Write an article about {topic}", + expected_output="A short article with a title and body", + agent=writer, + output_pydantic=Article, # 인스턴스가 아닌 클래스 + output_file="output/article.md", +) +``` + +`output_pydantic`은 **클래스** 자체를 받습니다. `Article(title="", body="")`을 전달하는 것은 흔한 실수이며 헷갈리는 검증 오류로 실패합니다. + +### 메모리와 embedder 설정 {#memory-embedder-config} + +`memory=True`이고 OpenAI의 기본 임베딩을 사용하지 않는다면, `embedder`를 반드시 전달해야 합니다: + +```python +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={ + "provider": "ollama", + "config": {"model": "nomic-embed-text"}, + }, +) +``` + +해당 provider의 자격 증명(`OPENAI_API_KEY`, `OLLAMA_HOST` 등)을 `.env` 파일에 설정하세요. 메모리 저장 경로는 기본적으로 프로젝트-로컬입니다 — embedder를 바꾸면 차원이 호환되지 않으므로 프로젝트의 메모리 디렉터리를 삭제하세요. diff --git a/docs/v1.15.1/ko/guides/tools/publish-custom-tools.mdx b/docs/v1.15.1/ko/guides/tools/publish-custom-tools.mdx new file mode 100644 index 000000000..9dbec2a78 --- /dev/null +++ b/docs/v1.15.1/ko/guides/tools/publish-custom-tools.mdx @@ -0,0 +1,244 @@ +--- +title: 커스텀 도구 배포하기 +description: PyPI에 게시할 수 있는 CrewAI 호환 도구를 빌드, 패키징, 배포하는 방법을 안내합니다. +icon: box-open +mode: "wide" +--- + +## 개요 + +CrewAI의 도구 시스템은 확장 가능하도록 설계되었습니다. 다른 사용자에게도 유용한 도구를 만들었다면, 독립적인 Python 라이브러리로 패키징하여 PyPI에 게시하고 모든 CrewAI 사용자가 사용할 수 있도록 할 수 있습니다. CrewAI 저장소에 PR을 보낼 필요가 없습니다. + +이 가이드에서는 도구 계약 구현, 패키지 구조화, PyPI 게시까지의 전체 과정을 안내합니다. + + +프로젝트 내에서만 사용할 커스텀 도구가 필요하다면 [커스텀 도구 생성](/ko/learn/create-custom-tools) 가이드를 참고하세요. + + +## 도구 계약 + +모든 CrewAI 도구는 다음 두 가지 인터페이스 중 하나를 충족해야 합니다: + +### 옵션 1: `BaseTool` 서브클래싱 + +`crewai.tools.BaseTool`을 서브클래싱하고 `_run` 메서드를 구현합니다. `name`, `description`, 그리고 선택적으로 입력 검증을 위한 `args_schema`를 정의합니다. + +```python +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + + +class GeolocateInput(BaseModel): + """GeolocateTool의 입력 스키마.""" + address: str = Field(..., description="지오코딩할 도로명 주소.") + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "도로명 주소를 위도/경도 좌표로 변환합니다." + args_schema: type[BaseModel] = GeolocateInput + + def _run(self, address: str) -> str: + # 구현 로직 + return f"40.7128, -74.0060" +``` + +### 옵션 2: `@tool` 데코레이터 사용 + +간단한 도구의 경우, `@tool` 데코레이터로 함수를 CrewAI 도구로 변환할 수 있습니다. 함수에는 반드시 독스트링(도구 설명으로 사용됨)과 타입 어노테이션이 있어야 합니다. + +```python +from crewai.tools import tool + + +@tool("Geolocate") +def geolocate(address: str) -> str: + """도로명 주소를 위도/경도 좌표로 변환합니다.""" + return "40.7128, -74.0060" +``` + +### 핵심 요구사항 + +어떤 방식을 사용하든, 도구는 다음을 충족해야 합니다: + +- **`name`** — 짧고 설명적인 식별자. +- **`description`** — 에이전트에게 도구를 언제, 어떻게 사용할지 알려줍니다. 에이전트가 도구를 얼마나 잘 활용하는지에 직접적으로 영향을 미치므로 명확하고 구체적으로 작성하세요. +- **`_run`** (BaseTool) 또는 **함수 본문** (@tool) 구현 — 동기 실행 로직. +- 모든 매개변수와 반환 값에 **타입 어노테이션** 사용. +- **문자열** 결과를 반환 (또는 의미 있게 문자열로 변환 가능한 값). + +### 선택사항: 비동기 지원 + +I/O 바운드 작업을 수행하는 도구의 경우 비동기 실행을 위해 `_arun`을 구현합니다: + +```python +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "도로명 주소를 위도/경도 좌표로 변환합니다." + + def _run(self, address: str) -> str: + # 동기 구현 + ... + + async def _arun(self, address: str) -> str: + # 비동기 구현 + ... +``` + +### 선택사항: `args_schema`를 통한 입력 검증 + +Pydantic 모델을 `args_schema`로 정의하면 자동 입력 검증과 명확한 에러 메시지를 받을 수 있습니다. 제공하지 않으면 CrewAI가 `_run` 메서드의 시그니처에서 추론합니다. + +```python +from pydantic import BaseModel, Field + + +class TranslateInput(BaseModel): + """TranslateTool의 입력 스키마.""" + text: str = Field(..., description="번역할 텍스트.") + target_language: str = Field( + default="en", + description="대상 언어의 ISO 639-1 언어 코드.", + ) +``` + +배포용 도구에는 명시적 스키마를 권장합니다 — 에이전트 동작이 개선되고 사용자에게 더 명확한 문서를 제공합니다. + +### 선택사항: 환경 변수 + +도구에 API 키나 기타 설정이 필요한 경우, `env_vars`로 선언하여 사용자가 무엇을 설정해야 하는지 알 수 있도록 합니다: + +```python +from crewai.tools import BaseTool, EnvVar + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "도로명 주소를 위도/경도 좌표로 변환합니다." + env_vars: list[EnvVar] = [ + EnvVar( + name="GEOCODING_API_KEY", + description="지오코딩 서비스 API 키.", + required=True, + ), + ] + + def _run(self, address: str) -> str: + ... +``` + +## 패키지 구조 + +프로젝트를 표준 Python 패키지로 구성합니다. 권장 레이아웃: + +``` +crewai-geolocate/ +├── pyproject.toml +├── LICENSE +├── README.md +└── src/ + └── crewai_geolocate/ + ├── __init__.py + └── tools.py +``` + +### `pyproject.toml` + +```toml +[project] +name = "crewai-geolocate" +version = "0.1.0" +description = "도로명 주소를 지오코딩하는 CrewAI 도구." +requires-python = ">=3.10" +dependencies = [ + "crewai", +] + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" +``` + +사용자가 자동으로 호환 버전을 받을 수 있도록 `crewai`를 의존성으로 선언합니다. + +### `__init__.py` + +사용자가 직접 import할 수 있도록 도구 클래스를 re-export합니다: + +```python +from crewai_geolocate.tools import GeolocateTool + +__all__ = ["GeolocateTool"] +``` + +### 명명 규칙 + +- **패키지 이름**: `crewai-` 접두사를 사용합니다 (예: `crewai-geolocate`). PyPI에서 검색할 때 도구를 쉽게 찾을 수 있습니다. +- **모듈 이름**: 밑줄을 사용합니다 (예: `crewai_geolocate`). +- **도구 클래스 이름**: `Tool`로 끝나는 PascalCase를 사용합니다 (예: `GeolocateTool`). + +## 도구 테스트 + +게시 전에 도구가 크루 내에서 작동하는지 확인합니다: + +```python +from crewai import Agent, Crew, Task +from crewai_geolocate import GeolocateTool + +agent = Agent( + role="Location Analyst", + goal="주어진 주소의 좌표를 찾습니다.", + backstory="지리공간 데이터 전문가.", + tools=[GeolocateTool()], +) + +task = Task( + description="1600 Pennsylvania Avenue, Washington, DC의 좌표를 찾으세요.", + expected_output="해당 주소의 위도와 경도.", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## PyPI에 게시하기 + +도구 테스트를 완료하고 준비가 되면: + +```bash +# 패키지 빌드 +uv build + +# PyPI에 게시 +uv publish +``` + +처음 게시하는 경우 [PyPI 계정](https://pypi.org/account/register/)과 [API 토큰](https://pypi.org/help/#apitoken)이 필요합니다. + +### 게시 후 + +사용자는 다음과 같이 도구를 설치할 수 있습니다: + +```bash +pip install crewai-geolocate +``` + +또는 uv를 사용하여: + +```bash +uv add crewai-geolocate +``` + +그런 다음 크루에서 사용합니다: + +```python +from crewai_geolocate import GeolocateTool + +agent = Agent( + role="Location Analyst", + tools=[GeolocateTool()], + # ... +) +``` diff --git a/docs/v1.15.1/ko/index.mdx b/docs/v1.15.1/ko/index.mdx new file mode 100644 index 000000000..a6cf4aac8 --- /dev/null +++ b/docs/v1.15.1/ko/index.mdx @@ -0,0 +1,102 @@ +--- +title: "CrewAI 문서" +description: "협업형 AI 에이전트, 크루, 플로우를 설계하고 즉시 프로덕션에 배포하세요." +icon: "house" +mode: "wide" +--- + +
+ CrewAI +
+

신뢰할 수 있는 멀티에이전트 시스템 구축

+

+ 에이전트를 설계하고 크루를 오케스트레이션하며 guardrails, 메모리, 지식, Observability가 기본 내장된 플로우를 자동화하세요. +

+
+ + +
+ +
+ + + + CrewAI의 핵심 개념, 아키텍처, 에이전트·크루·플로우로 만들 수 있는 것들을 빠르게 파악하세요. + + + `uv` 설치, API 키 설정, 로컬 개발을 위한 CLI 초기화까지 모든 단계를 안내합니다. + + + 몇 분 만에 첫 크루를 실행하세요. 런타임, 프로젝트 구조, 개발 루프를 배울 수 있습니다. + + + +## 기본 구축 + + + + 도구, 메모리, 지식, 구조화된 출력을 갖춘 에이전트를 구성하는 방법과 베스트 프랙티스를 배워보세요. + + + start/listen/router 단계, 상태 관리, 실행 저장 및 재개 등 복잡한 워크플로우를 설계하세요. + + + guardrails, 콜백, human-in-the-loop가 포함된 순차적·계층적 프로세스를 정의하세요. + + + +## 엔터프라이즈 여정 + + + + 환경을 관리하고 안전하게 재배포하며, Enterprise 콘솔에서 실시간 실행을 모니터링하세요. + + + Gmail, Slack, Salesforce 등 다양한 서비스를 연결하고 trigger payload를 자동으로 크루와 플로우에 전달하세요. + + + 팀원을 초대하고 RBAC을 설정하며, 프로덕션 자동화에 대한 접근을 제어하세요. + + + +## 최신 소식 + + + + Gmail, Drive, Outlook, Teams, OneDrive, HubSpot 등 다수의 통합을 하나의 문서에서 확인하고, payload/crew 예제를 살펴보세요. + + + 기존 CrewAI 자동화 또는 Amazon Bedrock Agent를 크루에서 직접 호출하는 방법을 안내합니다. + + + + + examples & cookbooks 섹션에서 에이전트, 플로우, Enterprise 자동화의 엔드-투-엔드 구현을 확인해 보세요. + + +## 커뮤니티 + + + + CrewAI가 도움이 되었다면 GitHub에서 별을 남기고 빌드를 공유해주세요. + + + 질문을 올리고, 워크플로우를 공유하며, 다른 빌더와 함께 새로운 기능을 제안하세요. + + diff --git a/docs/v1.15.1/ko/installation.mdx b/docs/v1.15.1/ko/installation.mdx new file mode 100644 index 000000000..ea3369997 --- /dev/null +++ b/docs/v1.15.1/ko/installation.mdx @@ -0,0 +1,209 @@ +--- +title: 설치 +description: CrewAI 시작하기 - 설치, 구성, 그리고 첫 번째 AI crew 구축하기 +icon: wrench +mode: "wide" +--- + +### 영상: 코딩 에이전트 스킬을 활용한 CrewAI Agents & Flows 구축 + +코딩 에이전트 스킬(Claude Code, Codex 등)을 설치하여 CrewAI로 코딩 에이전트를 빠르게 시작하세요. + +`npx skills add crewaiinc/skills` 명령어로 설치할 수 있습니다 + + + +## 비디오 튜토리얼 + +설치 과정을 단계별로 시연하는 비디오 튜토리얼을 시청하세요: + + + +## 텍스트 튜토리얼 + + + **Python 버전 요구 사항** + +CrewAI는 `Python >=3.10 및 <3.14`가 필요합니다. 버전을 확인하는 방법은 다음과 같습니다: + +```bash +python3 --version +``` + +Python을 업데이트해야 하는 경우, [python.org/downloads](https://python.org/downloads)를 방문하세요. + + + +CrewAI는 의존성 관리와 패키지 처리를 위해 `uv`를 사용합니다. 프로젝트 설정과 실행을 간소화하여 원활한 경험을 제공합니다. + +아직 `uv`를 설치하지 않았다면 **1단계**를 따라 빠르게 시스템에 설치할 수 있습니다. 이미 설치되어 있다면 **2단계**로 건너뛸 수 있습니다. + + + + - **macOS/Linux에서:** + + `curl`을 이용해 스크립트를 다운로드하고 `sh`로 실행하세요: + + ```shell + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + 시스템에 `curl`이 없다면, `wget`을 사용할 수 있습니다: + + ```shell + wget -qO- https://astral.sh/uv/install.sh | sh + ``` + + - **Windows에서:** + + `irm`으로 스크립트를 다운로드하고 `iex`로 실행하세요: + + ```shell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + 문제가 발생하면 [UV 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/)를 참고하세요. + + + + - 다음 명령어를 실행하여 `crewai` CLI를 설치하세요: + ```shell + uv tool install crewai + ``` + + `PATH` 경고가 발생하면 쉘을 업데이트하기 위해 아래 명령어를 실행하세요: + ```shell + uv tool update-shell + ``` + + + + Windows에서 `chroma-hnswlib==0.7.6` 빌드 오류(`fatal error C1083: Cannot open include file: 'float.h'`)가 발생하면, [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/)에서 *C++를 사용한 데스크톱 개발*을 설치하세요. + + + - `crewai`가 정상적으로 설치되었는지 확인하려면 다음을 실행하세요: + ```shell + uv tool list + ``` + - 다음과 같이 표시되어야 합니다: + ```shell + crewai v0.102.0 + - crewai + ``` + - `crewai`를 업데이트해야 하는 경우, 다음을 실행하세요: + ```shell + uv tool install crewai --upgrade + ``` + 설치가 완료되었습니다! 이제 첫 번째 crew를 만들 준비가 되었습니다! 🎉 + + + + +# CrewAI 프로젝트 생성하기 + +`crewai create crew`는 이제 JSON-first crew 프로젝트를 생성합니다. 에이전트는 `agents/*.jsonc`에, 태스크와 crew 수준 설정은 `crew.jsonc`에 두며, `crewai run`은 이 JSON 정의를 직접 로드합니다. + + + + - `crewai` CLI 명령어를 실행하세요: + ```shell + crewai create crew + ``` + + - 이 명령어를 실행하면 다음과 같은 구조로 새로운 프로젝트가 생성됩니다: + ``` + my_project/ + ├── .gitignore + ├── .env + ├── agents/ + │ └── researcher.jsonc + ├── crew.jsonc + ├── knowledge/ + ├── pyproject.toml + ├── README.md + ├── skills/ + └── tools/ + ``` + + - `crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 사용하는 기존 Python/YAML 스캐폴드가 필요하다면 다음을 실행하세요: + ```shell + crewai create crew --classic + ``` + + + + + - 프로젝트에는 다음과 같은 주요 파일들이 포함되어 있습니다: + | 파일 | 용도 | + | --- | --- | + | `crew.jsonc` | crew, 태스크 순서, 프로세스, 기본 입력값 설정 | + | `agents/*.jsonc` | 각 에이전트의 역할, 목표, backstory, LLM, 도구, 동작 정의 | + | `.env` | API 키 및 환경 변수 저장 | + | `tools/` | `custom:` 도구를 위한 선택적 Python 파일 | + | `knowledge/` | 에이전트용 선택적 지식 파일 | + | `skills/` | crew에 적용할 선택적 skill 파일 | + + - `crew.jsonc`와 `agents/` 안의 파일을 편집하여 crew 동작을 정의하세요. + - 에이전트와 태스크 텍스트에 `{placeholder}`를 사용하고, `crew.jsonc`의 `inputs`에 기본값을 넣으세요. `crewai run` 실행 시 빠진 값은 CLI가 묻습니다. + - API 키와 같은 민감한 정보는 `.env` 파일에 보관하세요. + + + + + - crew를 실행하기 전에 아래 명령을 먼저 실행하세요: + ```bash + crewai install + ``` + - 추가 패키지를 설치해야 하는 경우 다음을 사용하세요: + ```shell + uv add + ``` + - crew를 실행하려면 프로젝트 루트에서 아래 명령을 실행하세요: + ```bash + crewai run + ``` + + + +## 엔터프라이즈 설치 옵션 + + +팀과 조직을 위해, CrewAI는 설치 복잡성을 없애는 엔터프라이즈 배포 옵션을 제공합니다: + +### CrewAI AMP (SaaS) + +- 설치가 전혀 필요하지 않습니다 - [app.crewai.com](https://app.crewai.com)에서 무료로 가입하세요 +- 자동 업데이트 및 유지 보수 +- 관리형 인프라 및 확장성 지원 +- 코딩 없이 Crew 생성 + +### CrewAI Factory (자가 호스팅) + +- 귀하의 인프라를 위한 컨테이너화된 배포 +- 온프레미스 배포를 포함하여 모든 하이퍼스케일러 지원 +- 기존 보안 시스템과의 통합 + + + CrewAI의 엔터프라이즈 서비스에 대해 알아보고 데모를 예약하세요 + + + +## 다음 단계 + + + + Flow를 만들고 에이전트 한 명짜리 crew를 실행해 보고서까지 만드는 방법을 따라 해 보세요. + + + 다른 개발자들과 소통하고, 도움을 받으며, CrewAI 경험을 공유하세요. + + diff --git a/docs/v1.15.1/ko/introduction.mdx b/docs/v1.15.1/ko/introduction.mdx new file mode 100644 index 000000000..abd709014 --- /dev/null +++ b/docs/v1.15.1/ko/introduction.mdx @@ -0,0 +1,152 @@ +--- +title: 소개 +description: 함께 협력하여 복잡한 작업을 해결하는 AI agent 팀 구축 +icon: handshake +mode: "wide" +--- + +# CrewAI란 무엇인가? + +**CrewAI는 자율 AI agent를 조직하고 복잡한 workflow를 구축하기 위한 최고의 오픈 소스 프레임워크입니다.** + +**Crews**의 협업 지능과 **Flows**의 정밀한 제어를 결합하여 개발자가 프로덕션 수준의 멀티 에이전트 시스템을 구축할 수 있도록 지원합니다. + +- **[CrewAI Flows](/ko/guides/flows/first-flow)**: AI 애플리케이션의 중추(Backbone)입니다. Flows를 사용하면 상태를 관리하고 실행을 제어하는 구조화된 이벤트 기반 workflow를 만들 수 있습니다. AI agent가 작업할 수 있는 기반을 제공합니다. +- **[CrewAI Crews](/ko/guides/crews/first-crew)**: Flow 내의 작업 단위입니다. Crews는 Flow가 위임한 특정 작업을 해결하기 위해 협력하는 자율 agent 팀입니다. + +10만 명이 넘는 개발자가 커뮤니티 과정을 통해 인증을 받았으며, CrewAI는 기업용 AI 자동화의 표준입니다. + +### 영상: 코딩 에이전트 스킬을 활용한 CrewAI Agents & Flows 구축 + +코딩 에이전트 스킬(Claude Code, Codex 등)을 설치하여 CrewAI로 코딩 에이전트를 빠르게 시작하세요. + +`npx skills add crewaiinc/skills` 명령어로 설치할 수 있습니다 + + + +## CrewAI 아키텍처 + +CrewAI의 아키텍처는 자율성과 제어의 균형을 맞추도록 설계되었습니다. + +### 1. Flows: 중추 (Backbone) + + + Flow를 애플리케이션의 "관리자" 또는 "프로세스 정의"라고 생각하세요. 단계, 로직, 그리고 시스템 내에서 데이터가 이동하는 방식을 정의합니다. + + + + CrewAI Framework Overview + + +Flows의 기능: +- **상태 관리**: 단계 및 실행 전반에 걸쳐 데이터를 유지합니다. +- **이벤트 기반 실행**: 이벤트 또는 외부 입력을 기반으로 작업을 트리거합니다. +- **제어 흐름**: 조건부 로직, 반복문, 분기를 사용합니다. + +### 2. Crews: 지능 (Intelligence) + + + Crews는 힘든 일을 처리하는 "팀"입니다. Flow 내에서 창의성과 협업이 필요한 복잡한 문제를 해결하기 위해 Crew를 트리거할 수 있습니다. + + + + CrewAI Framework Overview + + +Crews의 기능: +- **역할 수행 Agent**: 특정 목표와 도구를 가진 전문 agent입니다. +- **자율 협업**: agent들이 협력하여 작업을 해결합니다. +- **작업 위임**: agent의 능력에 따라 작업이 할당되고 실행됩니다. + +## 전체 작동 방식 + +1. **Flow**가 이벤트를 트리거하거나 프로세스를 시작합니다. +2. **Flow**가 상태를 관리하고 다음에 무엇을 할지 결정합니다. +3. **Flow**가 복잡한 작업을 **Crew**에게 위임합니다. +4. **Crew**의 agent들이 협력하여 작업을 완료합니다. +5. **Crew**가 결과를 **Flow**에 반환합니다. +6. **Flow**가 결과를 바탕으로 실행을 계속합니다. + +## 주요 기능 + + + + 장기 실행 프로세스와 복잡한 로직을 처리할 수 있는 신뢰할 수 있고 상태를 유지하는 workflow를 구축합니다. + + + 높은 수준의 목표를 달성하기 위해 계획하고, 실행하고, 협력할 수 있는 agent 팀을 배포합니다. + + + agent를 모든 API, 데이터베이스 또는 로컬 도구에 연결합니다. + + + 엔터프라이즈 배포를 위한 보안 및 규정 준수를 고려하여 설계되었습니다. + + + +## Crews vs Flows 사용 시기 + +**짧은 답변: 둘 다 사용하세요.** + +모든 프로덕션 애플리케이션의 경우, **Flow로 시작하세요**. + +- 애플리케이션의 전체 구조, 상태, 로직을 정의하려면 **Flow를 사용하세요**. +- 자율성이 필요한 특정하고 복잡한 작업을 수행하기 위해 agent 팀이 필요할 때 Flow 단계 내에서 **Crew를 사용하세요**. + +| 사용 사례 | 아키텍처 | +| :--- | :--- | +| **간단한 자동화** | Python 작업이 포함된 단일 Flow | +| **복잡한 연구** | 상태를 관리하는 Flow -> 연구를 수행하는 Crew | +| **애플리케이션 백엔드** | API 요청을 처리하는 Flow -> 콘텐츠를 생성하는 Crew -> DB에 저장하는 Flow | + +## CrewAI를 선택해야 하는 이유? + +- 🧠 **자율적 운영**: agent가 자신의 역할과 사용 가능한 도구를 바탕으로 지능적인 결정을 내립니다 +- 📝 **자연스러운 상호작용**: agent가 인간 팀원처럼 소통하고 협업합니다 +- 🛠️ **확장 가능한 설계**: 새로운 도구, 역할, 기능을 쉽게 추가할 수 있습니다 +- 🚀 **프로덕션 준비 완료**: 실제 환경에서의 신뢰성과 확장성을 고려하여 구축되었습니다 +- 🔒 **보안 중심**: 엔터프라이즈 보안 요구 사항을 고려하여 설계되었습니다 +- 💰 **비용 효율적**: 토큰 사용량과 API 호출을 최소화하도록 최적화되었습니다 + +## 지금 바로 빌드를 시작해보세요! + + + + 실행을 정밀하게 제어할 수 있는 구조화된, 이벤트 기반 workflow를 만드는 방법을 배워보세요. + + + 복잡한 문제를 함께 해결하는 협업 AI 팀을 단계별로 만드는 튜토리얼입니다. + + + + + + 개발 환경에서 CrewAI를 시작하세요. + + + Flow를 만들고 에이전트 한 명 crew를 실행해 끝까지 보고서를 생성해 보세요. + + + 다른 개발자와 소통하며, 도움을 받고 CrewAI 경험을 공유해보세요. + + diff --git a/docs/v1.15.1/ko/learn/before-and-after-kickoff-hooks.mdx b/docs/v1.15.1/ko/learn/before-and-after-kickoff-hooks.mdx new file mode 100644 index 000000000..624a5e3a3 --- /dev/null +++ b/docs/v1.15.1/ko/learn/before-and-after-kickoff-hooks.mdx @@ -0,0 +1,61 @@ +--- +title: 킥오프 전후 후크(Before and After Kickoff Hooks) +description: CrewAI에서 킥오프 전후 후크를 사용하는 방법을 알아보세요 +mode: "wide" +--- + +CrewAI는 crew의 kickoff 전후에 코드를 실행할 수 있는 hook을 제공합니다. 이러한 hook은 입력값을 사전 처리하거나 결과를 사후 처리하는 데 유용합니다. + +## 킥오프 이전 훅 + +킥오프 이전 훅은 크루가 작업을 시작하기 전에 실행됩니다. 이 훅은 입력 딕셔너리를 받아 이를 수정한 후 크루에 전달할 수 있습니다. 이 훅을 사용하여 환경을 설정하거나, 필요한 데이터를 불러오거나, 입력값을 전처리할 수 있습니다. 입력 데이터가 크루에 의해 처리되기 전에 보완 또는 검증이 필요한 경우에 유용합니다. + +다음은 `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 + +#... +``` + +이 예시에서, prepare_data 함수는 입력값에 입력이 이미 처리되었음을 나타내는 새로운 키-값 쌍을 추가하여 입력값을 수정합니다. + +## 킥오프 후 훅 + +킥오프 후 훅은 crew의 작업이 완료된 후에 실행됩니다. 이 훅은 crew 실행의 출력값을 담은 result 객체를 전달받습니다. 이 훅은 로깅, 데이터 변환 또는 추가 분석과 같이 결과를 후처리하는 데 이상적입니다. + +`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 + +# ... +``` + +`log_results` 함수에서는 crew 실행 결과가 단순히 출력됩니다. 이를 확장하여 알림 전송이나 다른 서비스와의 연동과 같은 더 복잡한 작업을 수행할 수도 있습니다. + +## 두 후크 모두 활용하기 + +두 가지 후크를 함께 사용하면 crew의 실행을 위한 포괄적인 설정과 해제 프로세스를 제공할 수 있습니다. 이들은 관심사의 분리를 통해 코드 아키텍처를 깔끔하게 유지하고, CrewAI 구현의 모듈성을 향상하는 데 특히 유용합니다. + +## 결론 + +CrewAI의 kickoff 전후 훅은 crew 실행의 생명주기에 강력하게 개입할 수 있는 방법을 제공합니다. 이러한 훅을 이해하고 활용함으로써, AI agent의 견고성과 유연성을 크게 향상시킬 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/bring-your-own-agent.mdx b/docs/v1.15.1/ko/learn/bring-your-own-agent.mdx new file mode 100644 index 000000000..38f0912ce --- /dev/null +++ b/docs/v1.15.1/ko/learn/bring-your-own-agent.mdx @@ -0,0 +1,440 @@ +--- +title: 에이전트 직접 가져오기 +description: Crew 내에서 작동하는 자체 에이전트를 가져오는 방법을 알아보세요. +icon: robots +mode: "wide" +--- + +상호 운용성은 CrewAI의 핵심 개념입니다. 이 가이드에서는 Crew 내에서 작동하는 여러분만의 에이전트를 어떻게 도입할 수 있는지 보여줍니다. + +## 에이전트 직접 가져오기 어댑터 가이드 (Langgraph Agents, OpenAI Agents 등...) +다양한 프레임워크의 에이전트를 crew에서 작동하도록 하려면 3가지 어댑터가 필요합니다. + +1. BaseAgentAdapter +2. BaseToolAdapter +3. BaseConverter + +## BaseAgentAdapter +이 추상 클래스는 모든 agent adapter가 구현해야 하는 공통 인터페이스와 기능을 정의합니다. BaseAgent를 확장하여 CrewAI 프레임워크와의 호환성을 유지하면서 adapter별 요구 사항을 추가합니다. + +필수 메서드: + +1. `def configure_tools` +2. `def configure_structured_output` + +## 자신만의 Adapter 생성하기 +다른 프레임워크(예: LangGraph, Autogen, OpenAI Assistants)의 agent를 CrewAI에 통합하려면, `BaseAgentAdapter`를 상속하여 커스텀 adapter를 생성해야 합니다. 이 adapter는 호환성 계층 역할을 하며 CrewAI 인터페이스와 외부 agent의 특정 요구사항 사이를 변환합니다. + +커스텀 adapter를 구현하는 방법은 다음과 같습니다: + +1. **`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): + # ... implementation details ... + ``` + +2. **`__init__` 구현하기**: + 생성자는 부모 클래스 생성자 `super().__init__(**kwargs)`를 호출하고, 외부 agent에 특화된 초기화를 수행해야 합니다. CrewAI의 `Agent` 초기화 시 사용할 수 있는 선택적 `agent_config` 딕셔너리를 이용하여 adapter와 하위 agent를 구성할 수 있습니다. + + ```python + def __init__(self, agent_config: Optional[Dict[str, Any]] = None, **kwargs: Any): + super().__init__(agent_config=agent_config, **kwargs) + # Initialize your external agent here, possibly using agent_config + # Example: self.external_agent = initialize_my_agent(agent_config) + print(f"Initializing MyCustomAgentAdapter with config: {agent_config}") + ``` + +3. **`configure_tools` 구현하기**: + 이 추상 메서드는 매우 중요합니다. CrewAI `BaseTool` 인스턴스 리스트를 받습니다. 구현 시, 이 도구들을 외부 agent 프레임워크에서 기대하는 형식으로 변환 또는 적응시켜야 합니다. 래핑하거나, 특정 속성 추출, 혹은 외부 agent 인스턴스에 등록하는 작업이 필요할 수 있습니다. + + ```python + def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None: + if tools: + adapted_tools = [] + for tool in tools: + # Adapt CrewAI BaseTool to the format your agent expects + # Example: adapted_tool = adapt_to_my_framework(tool) + # adapted_tools.append(adapted_tool) + pass # Replace with your actual adaptation logic + + # Configure the external agent with the adapted tools + # Example: self.external_agent.set_tools(adapted_tools) + print(f"Configuring tools for MyCustomAgentAdapter: {adapted_tools}") # Placeholder + else: + # Handle the case where no tools are provided + # Example: self.external_agent.set_tools([]) + print("No tools provided for MyCustomAgentAdapter.") + ``` + +4. **`configure_structured_output` 구현하기**: + CrewAI `Agent`가 구조화된 출력 요구사항(예: `output_json` 또는 `output_pydantic`)으로 구성될 때 이 메서드가 호출됩니다. adapter에서 외부 agent가 이러한 요구사항을 준수하도록 설정해야 합니다. 이는 외부 agent에 특정 파라미터를 설정하거나, 해당 모델이 요청된 형식을 지원하는지 확인하는 것이 포함될 수 있습니다. 외부 agent가 CrewAI의 기대에 맞는 방식으로 구조화된 출력을 지원하지 않을 경우, 변환 처리를 하거나 적절한 오류를 발생시켜야 할 수 있습니다. + + ```python + def configure_structured_output(self, structured_output: Any) -> None: + # Configure your external agent to produce output in the specified format + # Example: self.external_agent.set_output_format(structured_output) + self.adapted_structured_output = True # Signal that structured output is handled + print(f"Configuring structured output for MyCustomAgentAdapter: {structured_output}") + ``` + +이러한 메서드들을 구현함으로써, `MyCustomAgentAdapter`는 커스텀 agent 구현이 CrewAI crew 내에서 올바로 동작할 수 있도록 하여, task 및 도구들과 매끄럽게 상호작용할 수 있게 됩니다. 예시 주석 및 print문은 실제로 통합하려는 외부 agent 프레임워크에 맞춘 로직으로 교체해야 한다는 점을 기억하세요. + +## BaseToolAdapter 구현 +`BaseToolAdapter` 클래스는 CrewAI의 기본 `BaseTool` 객체를 외부 에이전트 프레임워크가 이해하고 활용할 수 있는 형식으로 변환하는 역할을 합니다. 각각의 에이전트 프레임워크(LangGraph, OpenAI Assistants 등)는 도구를 정의하고 처리하는 고유한 방식을 가지고 있으며, `BaseToolAdapter`는 이들 간의 변환자 역할을 합니다. + +사용자 정의 툴 어댑터를 구현하는 방법은 다음과 같습니다: + +1. **`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): + # ... implementation details ... + ``` + +2. **`configure_tools` 구현**: + 이 메소드는 반드시 구현해야 하는 핵심 추상 메소드입니다. 에이전트에 제공된 CrewAI `BaseTool` 인스턴스의 리스트를 인자로 받으며, 각 리스트를 순회하면서 각 `BaseTool`을 외부 프레임워크가 기대하는 형식으로 변환하고, 변환된 도구들을 `self.converted_tools` 리스트(기본 클래스 생성자에서 초기화됨)에 담아야 합니다. + + ```python + def configure_tools(self, tools: List[BaseTool]) -> None: + """Configure and convert CrewAI tools for the specific implementation.""" + self.converted_tools = [] # Reset in case it's called multiple times + for tool in tools: + # Sanitize the tool name if required by the target framework + sanitized_name = self.sanitize_tool_name(tool.name) + + # --- Your Conversion Logic Goes Here --- + # Example: Convert BaseTool to a dictionary format for LangGraph + # converted_tool = { + # "name": sanitized_name, + # "description": tool.description, + # "parameters": tool.args_schema.schema() if tool.args_schema else {}, + # # Add any other framework-specific fields + # } + + # Example: Convert BaseTool to an OpenAI function definition + # converted_tool = { + # "type": "function", + # "function": { + # "name": sanitized_name, + # "description": tool.description, + # "parameters": tool.args_schema.schema() if tool.args_schema else {"type": "object", "properties": {}}, + # } + # } + + # --- Replace above examples with your actual adaptation --- + converted_tool = self.adapt_tool_to_my_framework(tool, sanitized_name) # Placeholder + + self.converted_tools.append(converted_tool) + print(f"Adapted tool '{tool.name}' to '{sanitized_name}' for MyCustomToolAdapter") # Placeholder + + print(f"MyCustomToolAdapter finished configuring tools: {len(self.converted_tools)} adapted.") # Placeholder + + # --- Helper method for adaptation (Example) --- + def adapt_tool_to_my_framework(self, tool: BaseTool, sanitized_name: str) -> Any: + # Replace this with the actual logic to convert a CrewAI BaseTool + # to the format needed by your specific external agent framework. + # This will vary greatly depending on the target 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 # Or however the framework needs to call it + } + # Also ensure the tool works both sync and async + 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. **어댑터 사용하기**: + 일반적으로, `MyCustomAgentAdapter`의 `configure_tools` 메소드 내에서 `MyCustomToolAdapter`를 인스턴스화하여 도구를 처리하고, 외부 에이전트를 구성하기 전에 도구들을 변환합니다. + + ```python + # Inside MyCustomAgentAdapter.configure_tools + def configure_tools(self, tools: Optional[List[BaseTool]] = None) -> None: + if tools: + tool_adapter = MyCustomToolAdapter() # Instantiate your tool adapter + tool_adapter.configure_tools(tools) # Convert the tools + adapted_tools = tool_adapter.tools() # Get the converted tools + + # Now configure your external agent with the adapted_tools + # Example: self.external_agent.set_tools(adapted_tools) + print(f"Configuring external agent with adapted tools: {adapted_tools}") # Placeholder + else: + # Handle no tools case + print("No tools provided for MyCustomAgentAdapter.") + ``` + +`BaseToolAdapter`를 생성하면 도구 변환 로직을 에이전트 어댑테이션과 분리할 수 있어, 통합 작업을 더 깔끔하고 모듈화된 구조로 만들 수 있습니다. 반드시 예시 부분을 실제로 요구되는 외부 에이전트 프레임워크의 변환 로직으로 대체해야 함을 명심하세요. + +## BaseConverter +`BaseConverterAdapter`는 CrewAI의 `Task`에서 에이전트가 JSON이나 Pydantic 모델과 같이 특정 구조화된 포맷으로 최종 출력을 반환해야 할 때 중요한 역할을 합니다. 이 어댑터는 CrewAI의 구조화된 출력 요구사항과 외부 에이전트의 기능 사이를 이어주는 다리 역할을 합니다. + +주요 책임은 다음과 같습니다: +1. **에이전트의 구조화된 출력 구성:** `Task`의 요구사항(`output_json` 또는 `output_pydantic`)에 따라 연결된 `BaseAgentAdapter`(그리고 간접적으로 외부 에이전트)에게 어떤 포맷이 요구되는지 지시합니다. +2. **시스템 프롬프트 확장:** 에이전트의 시스템 프롬프트를 수정하여 필요한 구조로 출력물을 생성하는 방법에 대한 명확한 지침을 추가합니다. +3. **결과 후처리:** 에이전트로부터 받은 원시 출력을 받아, 요구되는 구조에 따라 파싱, 검증 및 포맷팅을 시도한 후, 최종적으로 문자열(예: JSON 문자열) 형태로 반환합니다. + +사용자 지정 컨버터 어댑터를 구현하는 방법은 다음과 같습니다: + +1. **`BaseConverterAdapter` 상속**: + ```python + from crewai.agents.agent_adapters.base_converter_adapter import BaseConverterAdapter + # Assuming you have your MyCustomAgentAdapter defined + # from .my_custom_agent_adapter import MyCustomAgentAdapter + from crewai.task import Task + from typing import Any + + class MyCustomConverterAdapter(BaseConverterAdapter): + # Store the expected output type (e.g., 'json', 'pydantic', 'text') + _output_type: str = 'text' + _output_schema: Any = None # Store JSON schema or Pydantic model + + # ... implementation details ... + ``` + +2. **`__init__` 구현**: + 생성자는 함께 사용할 `agent_adapter` 인스턴스를 받아야 합니다. + + ```python + def __init__(self, agent_adapter: Any): # Use your specific AgentAdapter type hint + self.agent_adapter = agent_adapter + print(f"Initializing MyCustomConverterAdapter for agent adapter: {type(agent_adapter).__name__}") + ``` + +3. **`configure_structured_output` 구현**: + 이 메서드는 CrewAI `Task` 객체를 받습니다. 작업의 `output_json` 및 `output_pydantic` 속성을 확인하여 요구되는 출력 구조를 결정해야 합니다. 해당 정보(예: `_output_type` 및 `_output_schema`)를 저장하고, 필요하다면 외부 에이전트가 구조화된 출력에 대해 별도의 설정이 필요한 경우 `self.agent_adapter`에 구성 메서드를 호출할 수 있습니다(일부는 agent adapter의 `configure_structured_output`에서 이미 부분적으로 처리되었을 수 있습니다). + + ```python + def configure_structured_output(self, task: Task) -> None: + """Configure the expected structured output based on the task.""" + if task.output_pydantic: + self._output_type = 'pydantic' + self._output_schema = task.output_pydantic + print(f"Converter: Configured for Pydantic output: {self._output_schema.__name__}") + elif task.output_json: + self._output_type = 'json' + self._output_schema = task.output_json + print(f"Converter: Configured for JSON output with schema: {self._output_schema}") + else: + self._output_type = 'text' + self._output_schema = None + print("Converter: Configured for standard text output.") + + # Optionally, inform the agent adapter if needed + # self.agent_adapter.set_output_mode(self._output_type, self._output_schema) + ``` + +4. **`enhance_system_prompt` 구현**: + 이 메서드는 에이전트의 기본 시스템 프롬프트 문자열을 받아, 현재 구성된 `_output_type` 및 `_output_schema`에 맞춘 지침을 추가해야 합니다. 목적은 에이전트를 구동하는 LLM이 올바른 포맷으로 출력을 생성하도록 안내하는 것입니다. + + ```python + def enhance_system_prompt(self, base_prompt: str) -> str: + """Enhance the system prompt with structured output instructions.""" + if self._output_type == 'text': + return base_prompt # No enhancement needed for plain text + + instructions = "\n\nYour final answer MUST be formatted as " + if self._output_type == 'json': + schema_str = json.dumps(self._output_schema, indent=2) + instructions += f"a JSON object conforming to the following 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"a JSON object conforming to the Pydantic model '{self._output_schema.__name__}' with the following schema:\n```json\n{schema_str}\n```" + + instructions += "\nEnsure your entire response is ONLY the valid JSON object, without any introductory text, explanations, or concluding remarks." + + print(f"Converter: Enhancing prompt for {self._output_type} output.") + return base_prompt + instructions + ``` + *참고: 실제 프롬프트 엔지니어링은 사용하는 에이전트/LLM에 따라 조정이 필요할 수 있습니다.* + +5. **`post_process_result` 구현**: + 이 메서드는 에이전트로부터 받은 원시 문자열 출력을 받습니다. 구조화된 출력(`json` 또는 `pydantic`)이 요청된 경우, 문자열을 예상되는 포맷으로 파싱을 시도해야 합니다. 파싱 오류를 처리(예: 로그 남기기, 간단한 수정 시도, 예외 발생 등)해야 하며, 이 메서드는 **항상 문자열**을 반환해야 합니다. 중간 형식이 딕셔너리나 Pydantic 객체라도 이를 다시 JSON 문자열로 변환하여 반환해야 합니다. + + ```python + import json + from pydantic import ValidationError + + def post_process_result(self, result: str) -> str: + """Post-process the agent's result to ensure it matches the expected format.""" + print(f"Converter: Post-processing result for {self._output_type} output.") + if self._output_type == 'json': + try: + # Attempt to parse and re-serialize to ensure validity and consistent format + parsed_json = json.loads(result) + # Optional: Validate against self._output_schema if it's a JSON schema dictionary + # from jsonschema import validate + # validate(instance=parsed_json, schema=self._output_schema) + return json.dumps(parsed_json) + except json.JSONDecodeError as e: + print(f"Error: Failed to parse JSON output: {e}\nRaw output:\n{result}") + # Handle error: return raw, raise exception, or try to fix + return result # Example: return raw output on failure + # except Exception as e: # Catch validation errors if using jsonschema + # print(f"Error: JSON output failed schema validation: {e}\nRaw output:\n{result}") + # return result + elif self._output_type == 'pydantic': + try: + # Attempt to parse into the Pydantic model + model_instance = self._output_schema.model_validate_json(result) + # Return the model serialized back to JSON + return model_instance.model_dump_json() + except ValidationError as e: + print(f"Error: Failed to validate Pydantic output: {e}\nRaw output:\n{result}") + # Handle error + return result # Example: return raw output on failure + except json.JSONDecodeError as e: + print(f"Error: Failed to parse JSON for Pydantic model: {e}\nRaw output:\n{result}") + return result + else: # 'text' + return result # No processing needed for plain text + ``` + +이러한 메서드를 구현함으로써, `MyCustomConverterAdapter`는 CrewAI 작업의 구조화된 출력 요청이 통합된 외부 에이전트에서 올바르게 처리될 수 있게 하여, 사용자가 CrewAI 프레임워크 내에서 맞춤형 에이전트를 더욱 신뢰성 있고 유용하게 사용할 수 있도록 합니다. + +## 기본 제공 어댑터 + +다음 프레임워크에 대해 기본 제공 어댑터를 제공합니다: +1. LangGraph +2. OpenAI Agents + +## 적응형 에이전트로 crew 시작하기: + +```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 + +# CrewAI Agent +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, +) +# Use in 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?"} +) + +# Print raw result first +print("Raw result:", result) + +# Handle result based on its type +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)}") + + # Access fields safely + 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 to raw output + 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/v1.15.1/ko/learn/coding-agents.mdx b/docs/v1.15.1/ko/learn/coding-agents.mdx new file mode 100644 index 000000000..041f80792 --- /dev/null +++ b/docs/v1.15.1/ko/learn/coding-agents.mdx @@ -0,0 +1,96 @@ +--- +title: 코딩 에이전트 +description: CrewAI 에이전트가 코드를 작성하고 실행할 수 있도록 하는 방법과, 향상된 기능을 위한 고급 기능을 알아보세요. +icon: rectangle-code +mode: "wide" +--- + +## 소개 + +CrewAI 에이전트는 이제 코드를 작성하고 실행할 수 있는 강력한 기능을 갖추게 되어 문제 해결 능력이 크게 향상되었습니다. 이 기능은 계산적 또는 프로그래밍적 해결책이 필요한 작업에 특히 유용합니다. + +## 코드 실행 활성화 + +에이전트에서 코드 실행을 활성화하려면, 에이전트를 생성할 때 `allow_code_execution` 매개변수를 `True`로 설정하면 됩니다. + +예시는 다음과 같습니다: + +```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 +) +``` + + +`allow_code_execution` 매개변수의 기본값은 `False`임을 참고하세요. + + +## 중요한 고려 사항 + +1. **모델 선택**: 코드 실행을 활성화할 때 Claude 3.5 Sonnet 및 GPT-4와 같은 더 강력한 모델을 사용하는 것이 강력히 권장됩니다. +이러한 모델은 프로그래밍 개념에 대해 더 잘 이해하고 있으며, 올바르고 효율적인 코드를 생성할 가능성이 높습니다. + +2. **오류 처리**: 코드 실행 기능에는 오류 처리가 포함되어 있습니다. 실행된 코드에서 예외가 발생하면, 에이전트는 오류 메시지를 받아보고 코드를 수정하거나 +대체 솔루션을 제공할 수 있습니다. 기본값이 2인 `max_retry_limit` 파라미터는 작업에 대한 최대 재시도 횟수를 제어합니다. + +3. **종속성**: 코드 실행 기능을 사용하려면 `crewai_tools` 패키지를 설치해야 합니다. 설치되지 않은 경우, 에이전트는 다음과 같은 정보 메시지를 기록합니다: +"Coding tools not available. Install crewai_tools." + +## 코드 실행 프로세스 + +코드 실행이 활성화된 agent가 프로그래밍이 요구되는 작업을 만났을 때: + + + + agent는 작업을 분석하고 코드 실행이 필요하다는 것을 판단합니다. + + + 문제를 해결하는 데 필요한 Python 코드를 작성합니다. + + + 해당 코드는 내부 코드 실행 도구(`CodeInterpreterTool`)로 전송됩니다. + + + agent는 결과를 해석하여 응답에 반영하거나 추가 문제 해결에 활용합니다. + + + +## 예제 사용법 + +여기 코드 실행 기능이 있는 agent를 생성하고 이를 task에서 사용하는 자세한 예제가 있습니다: + +```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) +``` + +이 예제에서 `coding_agent`는 데이터 분석 작업을 수행하기 위해 Python 코드를 작성하고 실행할 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/conditional-tasks.mdx b/docs/v1.15.1/ko/learn/conditional-tasks.mdx new file mode 100644 index 000000000..9de55e32d --- /dev/null +++ b/docs/v1.15.1/ko/learn/conditional-tasks.mdx @@ -0,0 +1,90 @@ +--- +title: 조건부 태스크 +description: crewAI kickoff에서 조건부 태스크를 사용하는 방법을 알아보세요 +icon: diagram-subtask +mode: "wide" +--- + +## 소개 + +crewAI의 조건부 작업(Conditional Tasks)은 이전 작업의 결과에 따라 동적으로 워크플로우를 조정할 수 있도록 합니다. +이 강력한 기능을 통해 crew는 선택적으로 결정을 내리고 작업을 수행할 수 있어, AI 기반 프로세스의 유연성과 효율성이 향상됩니다. + +## 예제 사용법 + +```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/v1.15.1/ko/learn/create-custom-tools.mdx b/docs/v1.15.1/ko/learn/create-custom-tools.mdx new file mode 100644 index 000000000..3bbb844fe --- /dev/null +++ b/docs/v1.15.1/ko/learn/create-custom-tools.mdx @@ -0,0 +1,121 @@ +--- +title: 커스텀 도구 생성 +description: CrewAI 프레임워크 내에서 커스텀 도구를 제작, 사용 및 관리하는 종합 가이드로, 신규 기능과 오류 처리를 포함합니다. +icon: hammer +mode: "wide" +--- + +## CrewAI에서 툴 생성 및 활용 + +이 가이드는 CrewAI 프레임워크를 위한 커스텀 툴을 생성하는 방법과 최신 기능(툴 위임, 오류 처리, 동적 툴 호출 등)을 통합하여 이러한 툴을 효율적으로 관리하고 활용하는 방법에 대해 자세히 안내합니다. 또한 협업 툴의 중요성을 강조하며, 에이전트가 다양한 작업을 수행할 수 있도록 지원합니다. + + + **커뮤니티에 도구를 배포하고 싶으신가요?** 다른 사용자에게도 유용한 도구를 만들고 있다면, [커스텀 도구 배포하기](/ko/guides/tools/publish-custom-tools) 가이드에서 도구를 패키징하고 PyPI에 배포하는 방법을 알아보세요. + + +### `BaseTool` 서브클래싱 + +개인화된 툴을 생성하려면 `BaseTool`을 상속받고, 입력 검증을 위한 `args_schema`와 `_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" +``` + +### `tool` 데코레이터 사용하기 + +또는 tool 데코레이터 `@tool`을 사용할 수 있습니다. 이 방법은 함수 내에서 도구의 속성과 기능을 직접 정의할 수 있도록 하며, 귀하의 필요에 맞춘 특화된 도구를 간결하고 효율적으로 생성할 수 있는 방법을 제공합니다. + +```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" +``` + +### 도구를 위한 캐시 함수 정의하기 + +도구의 성능을 캐싱으로 최적화하려면, `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 +``` + +### 비동기 도구 생성하기 + +CrewAI는 논블로킹 I/O 작업을 위한 비동기 도구를 지원합니다. 이는 HTTP 요청, 데이터베이스 쿼리 또는 기타 I/O 바운드 작업이 필요한 경우에 유용합니다. + +#### `@tool` 데코레이터와 비동기 함수 사용하기 + +비동기 도구를 만드는 가장 간단한 방법은 `@tool` 데코레이터와 async 함수를 사용하는 것입니다: + +```python Code +import aiohttp +from crewai.tools import tool + +@tool("Async Web Fetcher") +async def fetch_webpage(url: str) -> str: + """Fetch content from a webpage asynchronously.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +#### 비동기 지원으로 `BaseTool` 서브클래싱하기 + +더 많은 제어를 위해 `BaseTool`을 상속하고 `_run`(동기) 및 `_arun`(비동기) 메서드를 모두 구현할 수 있습니다: + +```python Code +import requests +import aiohttp +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class WebFetcherInput(BaseModel): + """Input schema for WebFetcher.""" + url: str = Field(..., description="The URL to fetch") + +class WebFetcherTool(BaseTool): + name: str = "Web Fetcher" + description: str = "Fetches content from a URL" + args_schema: type[BaseModel] = WebFetcherInput + + def _run(self, url: str) -> str: + """Synchronous implementation.""" + return requests.get(url).text + + async def _arun(self, url: str) -> str: + """Asynchronous implementation for non-blocking I/O.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +이 가이드라인을 준수하고 새로운 기능과 협업 도구를 도구 생성 및 관리 프로세스에 통합함으로써, +CrewAI 프레임워크의 모든 기능을 활용할 수 있으며, AI agent의 개발 경험과 효율성을 모두 높일 수 있습니다. diff --git a/docs/v1.15.1/ko/learn/custom-llm.mdx b/docs/v1.15.1/ko/learn/custom-llm.mdx new file mode 100644 index 000000000..6dfc3fc6a --- /dev/null +++ b/docs/v1.15.1/ko/learn/custom-llm.mdx @@ -0,0 +1,351 @@ +--- +title: 커스텀 LLM 구현 +description: CrewAI에서 커스텀 LLM 구현을 만드는 방법을 알아보세요. +icon: code +mode: "wide" +--- + +## 개요 + +CrewAI는 `BaseLLM` 추상 기반 클래스를 통해 커스텀 LLM 구현을 지원합니다. 이를 통해 LiteLLM에 내장 지원이 없는 모든 LLM 제공자를 통합하거나, 커스텀 인증 메커니즘을 구현할 수 있습니다. + +## 빠른 시작 + +여기 최소한의 커스텀 LLM 구현 예시가 있습니다: + +```python +from crewai import BaseLLM +from typing import Any, Dict, List, Optional, Union +import requests + +class CustomLLM(BaseLLM): + def __init__(self, model: str, api_key: str, endpoint: str, temperature: Optional[float] = None): + # IMPORTANT: Call super().__init__() with required parameters + super().__init__(model=model, temperature=temperature) + + self.api_key = api_key + self.endpoint = endpoint + + def call( + self, + messages: Union[str, List[Dict[str, str]]], + tools: Optional[List[dict]] = None, + callbacks: Optional[List[Any]] = None, + available_functions: Optional[Dict[str, Any]] = None, + ) -> Union[str, Any]: + """Call the LLM with the given messages.""" + # Convert string to message format if needed + if isinstance(messages, str): + messages = [{"role": "user", "content": messages}] + + # Prepare request + payload = { + "model": self.model, + "messages": messages, + "temperature": self.temperature, + } + + # Add tools if provided and supported + if tools and self.supports_function_calling(): + payload["tools"] = tools + + # Make API call + response = requests.post( + self.endpoint, + headers={ + "Authorization": f"Bearer {self.api_key}", + "Content-Type": "application/json" + }, + json=payload, + timeout=30 + ) + response.raise_for_status() + + result = response.json() + return result["choices"][0]["message"]["content"] + + def supports_function_calling(self) -> bool: + """Override if your LLM supports function calling.""" + return True # Change to False if your LLM doesn't support tools + + def get_context_window_size(self) -> int: + """Return the context window size of your LLM.""" + return 8192 # Adjust based on your model's actual context window +``` + +## 사용자 지정 LLM 사용하기 + +```python +from crewai import Agent, Task, Crew + +# Assuming you have the CustomLLM class defined above +# Create your custom LLM +custom_llm = CustomLLM( + model="my-custom-model", + api_key="your-api-key", + endpoint="https://api.example.com/v1/chat/completions", + temperature=0.7 +) + +# Use with an agent +agent = Agent( + role="Research Assistant", + goal="Find and analyze information", + backstory="You are a research assistant.", + llm=custom_llm +) + +# Create and execute tasks +task = Task( + description="Research the latest developments in AI", + expected_output="A comprehensive summary", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## 필수 메서드 + +### 생성자: `__init__()` + +**중요**: 반드시 필수 매개변수와 함께 `super().__init__(model, temperature)`을 호출해야 합니다: + +```python +def __init__(self, model: str, api_key: str, temperature: Optional[float] = None): + # 필수: 부모 생성자를 model과 temperature로 호출 + super().__init__(model=model, temperature=temperature) + + # 사용자 정의 초기화 + self.api_key = api_key +``` + +### 추상 메서드: `call()` + +`call()` 메서드는 LLM 구현의 핵심입니다. 반드시 다음을 수행해야 합니다: + +- 메시지(문자열 또는 'role'과 'content'가 포함된 딕셔너리 리스트)를 받아들임 +- 문자열 응답을 반환함 +- 지원하는 경우 도구 및 함수 호출을 처리함 +- 오류 발생 시 적절한 예외를 발생시킴 + +### 선택적 메서드 + +```python +def supports_function_calling(self) -> bool: + """Return True if your LLM supports function calling.""" + return True # Default is True + +def supports_stop_words(self) -> bool: + """Return True if your LLM supports stop sequences.""" + return True # Default is True + +def get_context_window_size(self) -> int: + """Return the context window size.""" + return 4096 # Default is 4096 +``` + +## 공통 패턴 + +### 오류 처리 + +```python +import requests + +def call(self, messages, tools=None, callbacks=None, available_functions=None): + try: + response = requests.post( + self.endpoint, + headers={"Authorization": f"Bearer {self.api_key}"}, + json=payload, + timeout=30 + ) + response.raise_for_status() + return response.json()["choices"][0]["message"]["content"] + + except requests.Timeout: + raise TimeoutError("LLM request timed out") + except requests.RequestException as e: + raise RuntimeError(f"LLM request failed: {str(e)}") + except (KeyError, IndexError) as e: + raise ValueError(f"Invalid response format: {str(e)}") +``` + +### 커스텀 인증 + +```python +from crewai import BaseLLM +from typing import Optional + +class CustomAuthLLM(BaseLLM): + def __init__(self, model: str, auth_token: str, endpoint: str, temperature: Optional[float] = None): + super().__init__(model=model, temperature=temperature) + self.auth_token = auth_token + self.endpoint = endpoint + + def call(self, messages, tools=None, callbacks=None, available_functions=None): + headers = { + "Authorization": f"Custom {self.auth_token}", # Custom auth format + "Content-Type": "application/json" + } + # Rest of implementation... +``` + +### 스톱 워드 지원 + +CrewAI는 에이전트의 동작을 제어하기 위해 `"\nObservation:"`를 스톱 워드로 자동 추가합니다. 만약 사용 중인 LLM이 스톱 워드를 지원한다면: + +```python +def call(self, messages, tools=None, callbacks=None, available_functions=None): + payload = { + "model": self.model, + "messages": messages, + "stop": self.stop # Include stop words in API call + } + # Make API call... + +def supports_stop_words(self) -> bool: + return True # Your LLM supports stop sequences +``` + +만약 사용 중인 LLM이 스톱 워드를 기본적으로 지원하지 않는다면: + +```python +def call(self, messages, tools=None, callbacks=None, available_functions=None): + response = self._make_api_call(messages, tools) + content = response["choices"][0]["message"]["content"] + + # Manually truncate at stop words + if self.stop: + for stop_word in self.stop: + if stop_word in content: + content = content.split(stop_word)[0] + break + + return content + +def supports_stop_words(self) -> bool: + return False # Tell CrewAI we handle stop words manually +``` + +## 함수 호출 + +LLM이 함수 호출을 지원하는 경우, 전체 플로우를 구현하세요: + +```python +import json + +def call(self, messages, tools=None, callbacks=None, available_functions=None): + # Convert string to message format + if isinstance(messages, str): + messages = [{"role": "user", "content": messages}] + + # Make API call + response = self._make_api_call(messages, tools) + message = response["choices"][0]["message"] + + # Check for function calls + if "tool_calls" in message and available_functions: + return self._handle_function_calls( + message["tool_calls"], messages, tools, available_functions + ) + + return message["content"] + +def _handle_function_calls(self, tool_calls, messages, tools, available_functions): + """Handle function calling with proper message flow.""" + for tool_call in tool_calls: + function_name = tool_call["function"]["name"] + + if function_name in available_functions: + # Parse and execute function + function_args = json.loads(tool_call["function"]["arguments"]) + function_result = available_functions[function_name](**function_args) + + # Add function call and result to message history + messages.append({ + "role": "assistant", + "content": None, + "tool_calls": [tool_call] + }) + messages.append({ + "role": "tool", + "tool_call_id": tool_call["id"], + "name": function_name, + "content": str(function_result) + }) + + # Call LLM again with updated context + return self.call(messages, tools, None, available_functions) + + return "Function call failed" +``` + +## 문제 해결 + +### 일반적인 문제 + +**생성자 오류** +```python +# ❌ Wrong - missing required parameters +def __init__(self, api_key: str): + super().__init__() + +# ✅ Correct +def __init__(self, model: str, api_key: str, temperature: Optional[float] = None): + super().__init__(model=model, temperature=temperature) +``` + +**함수 호출이 작동하지 않음** +- `supports_function_calling()`이 `True`를 반환하는지 확인하세요 +- 응답에서 `tool_calls`를 처리하는지 확인하세요 +- `available_functions` 매개변수가 올바르게 사용되는지 검증하세요 + +**인증 실패** +- API 키 형식과 권한을 확인하세요 +- 인증 헤더 형식을 점검하세요 +- 엔드포인트 URL이 올바른지 확인하세요 + +**응답 파싱 오류** +- 중첩된 필드에 접근하기 전에 응답 구조를 검증하세요 +- content가 None일 수 있는 경우를 처리하세요 +- 잘못된 응답에 대한 적절한 오류 처리를 추가하세요 + +## 커스텀 LLM 테스트하기 + +```python +from crewai import Agent, Task, Crew + +def test_custom_llm(): + llm = CustomLLM( + model="test-model", + api_key="test-key", + endpoint="https://api.test.com" + ) + + # Test basic call + result = llm.call("Hello, world!") + assert isinstance(result, str) + assert len(result) > 0 + + # Test with CrewAI agent + agent = Agent( + role="Test Agent", + goal="Test custom LLM", + backstory="A test agent.", + llm=llm + ) + + task = Task( + description="Say hello", + expected_output="A greeting", + agent=agent + ) + + crew = Crew(agents=[agent], tasks=[task]) + result = crew.kickoff() + assert "hello" in result.raw.lower() +``` + +이 가이드는 CrewAI에서 커스텀 LLM을 구현하는 주요 사항을 다룹니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/custom-manager-agent.mdx b/docs/v1.15.1/ko/learn/custom-manager-agent.mdx new file mode 100644 index 000000000..89f8471cc --- /dev/null +++ b/docs/v1.15.1/ko/learn/custom-manager-agent.mdx @@ -0,0 +1,91 @@ +--- +title: 커스텀 매니저 에이전트 +description: CrewAI에서 커스텀 에이전트를 매니저로 설정하여 작업 관리 및 조정을 보다 세밀하게 제어하는 방법을 알아보세요. +icon: user-shield +mode: "wide" +--- + +# CrewAI에서 특정 에이전트를 매니저로 설정하기 + +CrewAI는 사용자가 crew의 매니저로 특정 에이전트를 설정할 수 있도록 하여, 작업의 관리 및 조정에 대한 더 많은 제어권을 제공합니다. +이 기능을 통해 프로젝트의 요구 사항에 더 적합하게 매니저 역할을 맞춤화할 수 있습니다. + +## `manager_agent` 속성 사용하기 + +### 커스텀 매니저 에이전트 + +`manager_agent` 속성을 사용하면 crew를 관리할 커스텀 에이전트를 정의할 수 있습니다. 이 에이전트는 전체 프로세스를 감독하여 작업이 효율적이고 최고의 기준에 맞춰 완료되도록 보장합니다. + +### 예시 + +```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() +``` + +## 맞춤형 Manager 에이전트의 이점 + +- **향상된 제어**: 프로젝트의 구체적인 요구 사항에 맞게 관리 방식을 조정할 수 있습니다. +- **향상된 조정**: 경험 많은 에이전트를 통해 효율적인 작업 조정 및 관리가 가능합니다. +- **맞춤형 관리**: 프로젝트 목표에 부합하는 관리자 역할과 책임을 정의할 수 있습니다. + +## 매니저 LLM 설정하기 + +계층적 프로세스를 사용하고 있으며 커스텀 매니저 에이전트를 설정하지 않으려는 경우, 매니저에 사용할 언어 모델을 지정할 수 있습니다: + +```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 +) +``` + + +계층적 프로세스를 사용할 때는 `manager_agent` 또는 `manager_llm` 중 하나를 반드시 설정해야 합니다. + \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/customizing-agents.mdx b/docs/v1.15.1/ko/learn/customizing-agents.mdx new file mode 100644 index 000000000..b05fef396 --- /dev/null +++ b/docs/v1.15.1/ko/learn/customizing-agents.mdx @@ -0,0 +1,111 @@ +--- +title: 에이전트 맞춤화 +description: CrewAI 프레임워크 내에서 특정 역할, 작업 및 고급 맞춤화를 위해 에이전트를 조정하는 종합 가이드입니다. +icon: user-pen +mode: "wide" +--- + +## 사용자 지정 가능 속성 + +효율적인 CrewAI 팀을 구성하려면 AI 에이전트를 프로젝트의 고유한 요구 사항에 맞게 동적으로 조정할 수 있어야 합니다. 이 섹션에서는 사용자 지정할 수 있는 기본 속성에 대해 다룹니다. + +### 커스터마이징을 위한 주요 속성 + +| 속성 | 설명 | +|:-----------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Role** | crew 내에서 에이전트의 직무를 지정합니다. 예: 'Analyst', 'Customer Service Rep' 등. | +| **Goal** | 에이전트의 목표를 정의하며, 이는 해당 role 및 crew의 전체 미션과 조화됩니다. | +| **Backstory** | 에이전트의 페르소나에 깊이를 더해, crew 내에서의 동기 부여와 참여도를 높입니다. | +| **Tools** *(선택 사항)* | 에이전트가 작업을 수행할 때 사용하는 기능이나 방법을 나타냅니다. 단순한 함수부터 복잡한 통합까지 포함될 수 있습니다. | +| **Cache** *(선택 사항)* | 에이전트가 tool 사용 시 캐시를 이용할지 여부를 결정합니다. | +| **Max RPM** | 분당 최대 요청 수(`max_rpm`)를 설정합니다. 외부 서비스에 제한 없는 요청을 원할 경우 `None`으로 설정할 수 있습니다. | +| **Verbose** *(선택 사항)* | 디버깅 및 최적화를 위한 상세 로그를 활성화하며, 실행 과정에 대한 인사이트를 제공합니다. | +| **Allow Delegation** *(선택 사항)* | 다른 에이전트로의 작업 위임을 제어합니다. 기본값은 `False`입니다. | +| **Max Iter** *(선택 사항)* | 무한 루프를 방지하기 위해 작업의 최대 반복 횟수(`max_iter`)를 제한합니다. 기본값은 25입니다. | +| **Max Execution Time** *(선택 사항)* | 에이전트가 작업을 완료하는 데 허용되는 최대 시간을 설정합니다. | +| **System Template** *(선택 사항)* | 에이전트의 시스템 형식을 정의합니다. | +| **Prompt Template** *(선택 사항)* | 에이전트의 프롬프트 형식을 정의합니다. | +| **Response Template** *(선택 사항)* | 에이전트의 응답 형식을 정의합니다. | +| **Use System Prompt** *(선택 사항)* | 작업 수행 중 에이전트가 system prompt를 사용할지 여부를 제어합니다. | +| **Respect Context Window** | 기본적으로 슬라이딩 context 윈도우를 활성화하여(context size를 유지) 설정합니다. | +| **Max Retry Limit** | 오류 발생 시 에이전트의 최대 재시도 횟수(`max_retry_limit`)를 설정합니다. | + +## 고급 커스터마이징 옵션 + +기본 속성 외에도, CrewAI는 에이전트의 행동과 능력을 크게 향상시킬 수 있는 더 깊은 커스터마이징을 허용합니다. + +### 언어 모델 커스터마이제이션 + +에이전트는 특정 언어 모델(`llm`)과 함수 호출 언어 모델(`function_calling_llm`)로 커스터마이즈할 수 있어, 처리 및 의사결정 능력을 고급 수준으로 제어할 수 있습니다. +`function_calling_llm`을 설정하면 기본 crew 함수 호출 언어 모델을 오버라이드할 수 있으므로, 더 높은 수준의 커스터마이제이션이 가능합니다. + +## 성능 및 디버깅 설정 + +에이전트의 성능을 조정하고 운영을 모니터링하는 것은 효율적인 작업 수행을 위해 매우 중요합니다. + +### 자세한 모드(Verbose Mode) 및 RPM 제한 + +- **자세한 모드(Verbose Mode)**: 에이전트의 동작을 자세히 기록하는 로깅을 활성화하여 디버깅과 최적화에 유용합니다. 특히, 에이전트 실행 프로세스에 대한 인사이트를 제공하여 성능 최적화에 도움이 됩니다. +- **RPM 제한**: 분당 최대 요청 수(`max_rpm`)를 설정합니다. 이 속성은 선택 사항이며, 제한이 필요 없을 경우 `None`으로 설정하면 외부 서비스에 무제한 쿼리를 허용할 수 있습니다. + +### 작업 실행을 위한 최대 반복 횟수 + +`max_iter` 속성은 사용자가 하나의 작업에 대해 agent가 수행할 수 있는 최대 반복 횟수를 정의할 수 있게 하여, 무한 루프나 지나치게 긴 실행을 방지해줍니다. +기본값은 25로 설정되어 있어 철저함과 효율성 사이의 균형을 제공합니다. agent가 이 숫자에 가까워질 때, 최선의 답변을 제공하기 위해 노력하게 됩니다. + +## 에이전트 및 도구 커스터마이징 + +에이전트는 초기화 시 속성과 도구를 정의하여 커스터마이징합니다. 도구는 에이전트의 기능에 매우 중요하며, 특정 작업을 수행할 수 있게 해줍니다. +`tools` 속성은 에이전트가 사용할 수 있는 도구의 배열이어야 하며, 기본값으로는 빈 리스트로 초기화됩니다. 도구는 새로운 요구 사항에 맞추어 에이전트 초기화 이후에도 추가하거나 수정할 수 있습니다. + +```shell +pip install 'crewai[tools]' +``` + +### 예시: 에이전트에 도구 할당하기 + +```python Code +import os +from crewai import Agent +from crewai_tools import SerperDevTool + +# Set API keys for tool initialization +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" + +# Initialize a search tool +search_tool = SerperDevTool() + +# Initialize the agent with advanced options +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, # Enable memory + verbose=True, + max_rpm=None, # No limit on requests per minute + max_iter=25, # Default value for maximum iterations +) +``` + +## 위임 및 자율성 + +에이전트가 작업을 위임하거나 질문을 할 수 있는 능력을 제어하는 것은 CrewAI 프레임워크 내에서 자율성과 협업 역학을 맞춤화하는 데 매우 중요합니다. 기본적으로 +`allow_delegation` 속성은 이제 `False`로 설정되어 있어, 에이전트가 필요에 따라 도움을 요청하거나 작업을 위임하는 것이 비활성화됩니다. 이 기본 동작은 CrewAI 생태계 내에서 협동적 문제 해결과 +효율성을 촉진하기 위해 변경될 수 있습니다. 필요할 경우, 특정 운영 요구 사항에 맞게 위임을 활성화할 수 있습니다. + +### 예시: 에이전트에 대한 위임 비활성화 + +```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 # Enabling delegation +) +``` + +## 결론 + +CrewAI에서 에이전트의 역할, 목표, 배경 이야기, 도구를 설정하고, 언어 모델 커스터마이징, 메모리, 성능 설정, 위임 선호도와 같은 고급 옵션을 함께 활용하면 복잡한 과제에 대응할 준비가 된 세밀하고 유능한 AI 팀을 구성할 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/dalle-image-generation.mdx b/docs/v1.15.1/ko/learn/dalle-image-generation.mdx new file mode 100644 index 000000000..f194fe111 --- /dev/null +++ b/docs/v1.15.1/ko/learn/dalle-image-generation.mdx @@ -0,0 +1,74 @@ +--- +title: "DALL-E를 활용한 이미지 생성" +description: "CrewAI 프로젝트에서 AI 기반 이미지 생성을 위해 DALL-E를 활용하는 방법을 알아보세요" +icon: "image" +mode: "wide" +--- + +CrewAI는 OpenAI의 DALL-E와의 통합을 지원하여, AI 에이전트가 작업의 일환으로 이미지를 생성할 수 있습니다. 이 가이드에서는 CrewAI 프로젝트에서 DALL-E 도구를 설정하고 사용하는 방법을 단계별로 안내합니다. + +## 사전 요구 사항 + +- crewAI가 설치되어 있음 (최신 버전) +- DALL-E에 접근 가능한 OpenAI API 키 + +## 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 + ) + ``` + + + +## DALL-E 도구 사용하기 + +DALL-E 도구를 에이전트에 추가하면 텍스트 프롬프트를 기반으로 이미지를 생성할 수 있습니다. 도구는 생성된 이미지의 URL을 반환하며, 이 URL은 에이전트의 출력에 사용하거나 다른 에이전트에게 전달하여 추가 처리를 할 수 있습니다. + +### 예시 에이전트 구성 + +```yaml +role: > + LinkedIn 프로필 시니어 데이터 연구원 +goal: > + 제공된 이름 {name}과 도메인 {domain}을 기반으로 자세한 LinkedIn 프로필을 찾아냅니다 + 도메인 {domain}을 기반으로 Dall-e 이미지를 생성합니다 +backstory: > + 당신은 관련성이 높은 LinkedIn 프로필을 찾아내는 데 능숙한 숙련된 연구원입니다. + LinkedIn을 효율적으로 탐색하는 능력으로 잘 알려져 있으며, 전문적인 정보를 + 명확하고 간결하게 수집하고 제시하는 데 뛰어납니다. +``` + +### 예상 결과 + +DALL-E 도구를 사용하는 agent는 이미지를 생성하고 응답에 URL을 제공할 수 있습니다. 그런 다음 이미지를 다운로드할 수 있습니다. + + + DALL-E Image + + +## 모범 사례 + +1. **이미지 생성 프롬프트를 구체적으로 작성하세요**. 그래야 최상의 결과를 얻을 수 있습니다. +2. **생성 시간을 고려하세요** - 이미지 생성에는 시간이 걸릴 수 있으므로 작업 계획에 이를 반영하세요. +3. **사용 정책을 준수하세요** - 이미지를 생성할 때 항상 OpenAI의 사용 정책을 준수해야 합니다. + +## 문제 해결 + +1. **API 접근 확인** - OpenAI API 키가 DALL-E에 접근 권한이 있는지 확인하세요. +2. **버전 호환성** - 최신 버전의 crewAI와 crewai-tools를 사용하고 있는지 확인하세요. +3. **도구 구성** - DALL-E 도구가 agent의 도구 목록에 올바르게 추가되어 있는지 확인하세요. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/execution-hooks.mdx b/docs/v1.15.1/ko/learn/execution-hooks.mdx new file mode 100644 index 000000000..4254f053c --- /dev/null +++ b/docs/v1.15.1/ko/learn/execution-hooks.mdx @@ -0,0 +1,379 @@ +--- +title: 실행 훅 개요 +description: 에이전트 작업에 대한 세밀한 제어를 위한 CrewAI 실행 훅 이해 및 사용 +mode: "wide" +--- + +실행 훅(Execution Hooks)은 CrewAI 에이전트의 런타임 동작을 세밀하게 제어할 수 있게 해줍니다. 크루 실행 전후에 실행되는 킥오프 훅과 달리, 실행 훅은 에이전트 실행 중 특정 작업을 가로채서 동작을 수정하고, 안전성 검사를 구현하며, 포괄적인 모니터링을 추가할 수 있습니다. + +## 실행 훅의 유형 + +CrewAI는 두 가지 주요 범주의 실행 훅을 제공합니다: + +### 1. [LLM 호출 훅](/learn/llm-hooks) + +언어 모델 상호작용을 제어하고 모니터링합니다: +- **LLM 호출 전**: 프롬프트 수정, 입력 검증, 승인 게이트 구현 +- **LLM 호출 후**: 응답 변환, 출력 정제, 대화 기록 업데이트 + +**사용 사례:** +- 반복 제한 +- 비용 추적 및 토큰 사용량 모니터링 +- 응답 정제 및 콘텐츠 필터링 +- LLM 호출에 대한 사람의 승인 +- 안전 가이드라인 또는 컨텍스트 추가 +- 디버그 로깅 및 요청/응답 검사 + +[LLM 훅 문서 보기 →](/learn/llm-hooks) + +### 2. [도구 호출 훅](/learn/tool-hooks) + +도구 실행을 제어하고 모니터링합니다: +- **도구 호출 전**: 입력 수정, 매개변수 검증, 위험한 작업 차단 +- **도구 호출 후**: 결과 변환, 출력 정제, 실행 세부사항 로깅 + +**사용 사례:** +- 파괴적인 작업에 대한 안전 가드레일 +- 민감한 작업에 대한 사람의 승인 +- 입력 검증 및 정제 +- 결과 캐싱 및 속도 제한 +- 도구 사용 분석 +- 디버그 로깅 및 모니터링 + +[도구 훅 문서 보기 →](/learn/tool-hooks) + +## 훅 등록 방법 + +### 1. 데코레이터 기반 훅 (권장) + +훅을 등록하는 가장 깔끔하고 파이썬스러운 방법: + +```python +from crewai.hooks import before_llm_call, after_llm_call, before_tool_call, after_tool_call + +@before_llm_call +def limit_iterations(context): + """반복 횟수를 제한하여 무한 루프를 방지합니다.""" + if context.iterations > 10: + return False # 실행 차단 + return None + +@after_llm_call +def sanitize_response(context): + """LLM 응답에서 민감한 데이터를 제거합니다.""" + if "API_KEY" in context.response: + return context.response.replace("API_KEY", "[수정됨]") + return None + +@before_tool_call +def block_dangerous_tools(context): + """파괴적인 작업을 차단합니다.""" + if context.tool_name == "delete_database": + return False # 실행 차단 + return None + +@after_tool_call +def log_tool_result(context): + """도구 실행을 로깅합니다.""" + print(f"도구 {context.tool_name} 완료") + return None +``` + +### 2. 크루 범위 훅 + +특정 크루 인스턴스에만 훅을 적용합니다: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # 이 크루에만 적용됩니다 + print(f"{self.__class__.__name__}에서 LLM 호출") + return None + + @after_tool_call_crew + def log_results(self, context): + # 크루별 로깅 + print(f"도구 결과: {context.tool_result[:50]}...") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential + ) +``` + +## 훅 실행 흐름 + +### LLM 호출 흐름 + +``` +에이전트가 LLM을 호출해야 함 + ↓ +[LLM 호출 전 훅 실행] + ├→ 훅 1: 반복 횟수 검증 + ├→ 훅 2: 안전 컨텍스트 추가 + └→ 훅 3: 요청 로깅 + ↓ +훅이 False를 반환하는 경우: + ├→ LLM 호출 차단 + └→ ValueError 발생 + ↓ +모든 훅이 True/None을 반환하는 경우: + ├→ LLM 호출 진행 + └→ 응답 생성 + ↓ +[LLM 호출 후 훅 실행] + ├→ 훅 1: 응답 정제 + ├→ 훅 2: 응답 로깅 + └→ 훅 3: 메트릭 업데이트 + ↓ +최종 응답 반환 +``` + +### 도구 호출 흐름 + +``` +에이전트가 도구를 실행해야 함 + ↓ +[도구 호출 전 훅 실행] + ├→ 훅 1: 도구 허용 여부 확인 + ├→ 훅 2: 입력 검증 + └→ 훅 3: 필요시 승인 요청 + ↓ +훅이 False를 반환하는 경우: + ├→ 도구 실행 차단 + └→ 오류 메시지 반환 + ↓ +모든 훅이 True/None을 반환하는 경우: + ├→ 도구 실행 진행 + └→ 결과 생성 + ↓ +[도구 호출 후 훅 실행] + ├→ 훅 1: 결과 정제 + ├→ 훅 2: 결과 캐싱 + └→ 훅 3: 메트릭 로깅 + ↓ +최종 결과 반환 +``` + +## 훅 컨텍스트 객체 + +### LLMCallHookContext + +LLM 실행 상태에 대한 액세스를 제공합니다: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # 전체 실행자 액세스 + messages: list # 변경 가능한 메시지 목록 + agent: Agent # 현재 에이전트 + task: Task # 현재 작업 + crew: Crew # 크루 인스턴스 + llm: BaseLLM # LLM 인스턴스 + iterations: int # 현재 반복 횟수 + response: str | None # LLM 응답 (후 훅용) +``` + +### ToolCallHookContext + +도구 실행 상태에 대한 액세스를 제공합니다: + +```python +class ToolCallHookContext: + tool_name: str # 호출되는 도구 + tool_input: dict # 변경 가능한 입력 매개변수 + tool: CrewStructuredTool # 도구 인스턴스 + agent: Agent | None # 실행 중인 에이전트 + task: Task | None # 현재 작업 + crew: Crew | None # 크루 인스턴스 + tool_result: str | None # 도구 결과 (후 훅용) +``` + +## 일반적인 패턴 + +### 안전 및 검증 + +```python +@before_tool_call +def safety_check(context): + """파괴적인 작업을 차단합니다.""" + dangerous = ['delete_file', 'drop_table', 'system_shutdown'] + if context.tool_name in dangerous: + print(f"🛑 차단됨: {context.tool_name}") + return False + return None + +@before_llm_call +def iteration_limit(context): + """무한 루프를 방지합니다.""" + if context.iterations > 15: + print("⛔ 최대 반복 횟수 초과") + return False + return None +``` + +### 사람의 개입 + +```python +@before_tool_call +def require_approval(context): + """민감한 작업에 대한 승인을 요구합니다.""" + sensitive = ['send_email', 'make_payment', 'post_message'] + + if context.tool_name in sensitive: + response = context.request_human_input( + prompt=f"{context.tool_name} 승인하시겠습니까?", + default_message="승인하려면 'yes'를 입력하세요:" + ) + + if response.lower() != 'yes': + return False + + return None +``` + +### 모니터링 및 분석 + +```python +from collections import defaultdict +import time + +metrics = defaultdict(lambda: {'count': 0, 'total_time': 0}) + +@before_tool_call +def start_timer(context): + context.tool_input['_start'] = time.time() + return None + +@after_tool_call +def track_metrics(context): + start = context.tool_input.get('_start', time.time()) + duration = time.time() - start + + metrics[context.tool_name]['count'] += 1 + metrics[context.tool_name]['total_time'] += duration + + return None +``` + +## 훅 관리 + +### 모든 훅 지우기 + +```python +from crewai.hooks import clear_all_global_hooks + +# 모든 훅을 한 번에 지웁니다 +result = clear_all_global_hooks() +print(f"{result['total']} 훅이 지워졌습니다") +``` + +### 특정 훅 유형 지우기 + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_before_tool_call_hooks, + clear_after_tool_call_hooks +) + +# 특정 유형 지우기 +llm_before_count = clear_before_llm_call_hooks() +tool_after_count = clear_after_tool_call_hooks() +``` + +## 모범 사례 + +### 1. 훅을 집중적으로 유지 +각 훅은 단일하고 명확한 책임을 가져야 합니다. + +### 2. 오류를 우아하게 처리 +```python +@before_llm_call +def safe_hook(context): + try: + if some_condition: + return False + except Exception as e: + print(f"훅 오류: {e}") + return None # 오류에도 불구하고 실행 허용 +``` + +### 3. 컨텍스트를 제자리에서 수정 +```python +# ✅ 올바름 - 제자리에서 수정 +@before_llm_call +def add_context(context): + context.messages.append({"role": "system", "content": "간결하게"}) + +# ❌ 잘못됨 - 참조를 교체 +@before_llm_call +def wrong_approach(context): + context.messages = [{"role": "system", "content": "간결하게"}] +``` + +### 4. 타입 힌트 사용 +```python +from crewai.hooks import LLMCallHookContext, ToolCallHookContext + +def my_llm_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_tool_hook(context: ToolCallHookContext) -> str | None: + return None +``` + +### 5. 테스트에서 정리 +```python +import pytest +from crewai.hooks import clear_all_global_hooks + +@pytest.fixture(autouse=True) +def clean_hooks(): + """각 테스트 전에 훅을 재설정합니다.""" + yield + clear_all_global_hooks() +``` + +## 어떤 훅을 사용해야 할까요 + +### LLM 훅을 사용하는 경우: +- 반복 제한 구현 +- 프롬프트에 컨텍스트 또는 안전 가이드라인 추가 +- 토큰 사용량 및 비용 추적 +- 응답 정제 또는 변환 +- LLM 호출에 대한 승인 게이트 구현 +- 프롬프트/응답 상호작용 디버깅 + +### 도구 훅을 사용하는 경우: +- 위험하거나 파괴적인 작업 차단 +- 실행 전 도구 입력 검증 +- 민감한 작업에 대한 승인 게이트 구현 +- 도구 결과 캐싱 +- 도구 사용 및 성능 추적 +- 도구 출력 정제 +- 도구 호출 속도 제한 + +### 둘 다 사용하는 경우: +모든 에이전트 작업을 모니터링해야 하는 포괄적인 관찰성, 안전 또는 승인 시스템을 구축하는 경우. + +## 관련 문서 + +- [LLM 호출 훅 →](/learn/llm-hooks) - 상세한 LLM 훅 문서 +- [도구 호출 훅 →](/learn/tool-hooks) - 상세한 도구 훅 문서 +- [킥오프 전후 훅 →](/learn/before-and-after-kickoff-hooks) - 크루 생명주기 훅 +- [사람의 개입 →](/learn/human-in-the-loop) - 사람 입력 패턴 + +## 결론 + +실행 훅은 에이전트 런타임 동작에 대한 강력한 제어를 제공합니다. 이를 사용하여 안전 가드레일, 승인 워크플로우, 포괄적인 모니터링 및 사용자 정의 비즈니스 로직을 구현하세요. 적절한 오류 처리, 타입 안전성 및 성능 고려사항과 결합하면, 훅을 통해 프로덕션 준비가 된 안전하고 관찰 가능한 에이전트 시스템을 구축할 수 있습니다. diff --git a/docs/v1.15.1/ko/learn/force-tool-output-as-result.mdx b/docs/v1.15.1/ko/learn/force-tool-output-as-result.mdx new file mode 100644 index 000000000..1a1da0a5f --- /dev/null +++ b/docs/v1.15.1/ko/learn/force-tool-output-as-result.mdx @@ -0,0 +1,51 @@ +--- +title: 도구 출력 결과로 강제 지정하기 +description: CrewAI에서 에이전트의 작업에서 도구 출력을 결과로 강제 지정하는 방법을 알아봅니다. +icon: wrench-simple +mode: "wide" +--- + +## 소개 + +CrewAI에서는 도구의 출력을 에이전트 작업의 결과로 강제로 사용할 수 있습니다. +이 기능은 작업 실행 중에 에이전트가 출력을 수정하지 못하도록 하고, 도구의 출력이 반드시 캡처되어 작업 결과로 반환되도록 보장하고 싶을 때 유용합니다. + +## 도구 출력을 결과로 강제 지정하기 + +도구의 출력을 에이전트 작업의 결과로 강제 지정하려면, 에이전트에 도구를 추가할 때 `result_as_answer` 매개변수를 `True`로 설정해야 합니다. +이 매개변수는 도구의 출력이 에이전트에 의해 수정되지 않고 작업 결과로 캡처되어 반환되도록 보장합니다. + +다음은 에이전트 작업의 결과로 도구 출력을 강제 지정하는 방법의 예시입니다: + +```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) +``` + +## 워크플로우 실행 + + + + 에이전트는 제공된 도구를 사용하여 작업을 수행합니다. + + + 도구가 출력을 생성하며, 이는 작업 결과로 캡처됩니다. + + + 에이전트는 도구에서 학습하고 반영할 수 있지만, 출력은 수정되지 않습니다. + + + 도구 출력은 어떠한 수정 없이 작업 결과로 반환됩니다. + + \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/hierarchical-process.mdx b/docs/v1.15.1/ko/learn/hierarchical-process.mdx new file mode 100644 index 000000000..e659bd8d2 --- /dev/null +++ b/docs/v1.15.1/ko/learn/hierarchical-process.mdx @@ -0,0 +1,110 @@ +--- +title: 계층적 프로세스 +description: 최신 코딩 관행 및 기능을 반영하여 CrewAI 프로젝트 내에서 계층적 프로세스를 이해하고 적용하는 종합 가이드입니다. +icon: sitemap +mode: "wide" +--- + +## 소개 + +CrewAI의 계층적 프로세스는 효율적인 작업 위임 및 실행을 위해 전통적인 조직의 계층 구조를 모방하는 구조화된 작업 관리 방식을 도입합니다. +이러한 체계적인 워크플로우는 작업이 최적의 효율성과 정확성으로 처리될 수 있도록 하여 프로젝트 성과를 향상시킵니다. + + + 계층적 프로세스는 GPT-4와 같은 고급 모델을 활용하도록 설계되었으며, 복잡한 작업을 보다 효율적으로 처리하는 동시에 토큰 사용을 최적화합니다. + + +## 계층적 프로세스 개요 + +기본적으로 CrewAI에서 task는 순차적인 프로세스를 통해 관리됩니다. 그러나 계층적 접근 방식을 채택하면 명확한 계층 구조의 task 관리를 할 수 있습니다. +이 방식에서는 'manager' agent가 workflow를 조정하고, task를 위임하며, 결과를 검증하여 효율적이고 원활한 실행을 가능하게 합니다. 이 manager agent는 이제 CrewAI에서 자동으로 생성되거나 사용자가 명시적으로 설정할 수 있습니다. + +### 주요 기능 + +- **작업 위임**: 매니저 에이전트가 역할과 역량에 따라 crew 멤버에게 작업을 할당합니다. +- **결과 검증**: 매니저가 결과물을 평가하여 요구되는 기준을 충족하는지 확인합니다. +- **효율적인 워크플로우**: 기업 구조를 모방하여 체계적인 작업 관리 방식을 제공합니다. +- **시스템 프롬프트 처리**: 시스템이 사전 정의된 prompt를 사용할지 옵션으로 지정할 수 있습니다. +- **불용어 제어**: 불용어 사용 여부를 옵션으로 지정할 수 있으며, o1 모델 등 다양한 모델을 지원합니다. +- **컨텍스트 윈도우 존중**: 중요한 컨텍스트를 우선시하며, 컨텍스트 윈도우를 존중하는 것이 기본 동작입니다. +- **위임 제어**: 사용자에게 명확한 제어권을 주기 위해 기본적으로 위임이 비활성화되어 있습니다. +- **분당 최대 요청 수**: 분당 최대 요청 수를 설정할 수 있는 구성 옵션입니다. +- **최대 반복 횟수**: 최종 답변을 얻기 위한 최대 반복 횟수를 제한합니다. + +## 계층적 프로세스 구현하기 + +계층적 프로세스를 활용하려면, 프로세스 속성을 반드시 `Process.hierarchical`로 명시적으로 설정해야 합니다. 기본 동작은 `Process.sequential`입니다. +매니저가 지정된 crew를 정의하고, 명확한 명령 체계를 구축하세요. + + + 도구는 agent 수준에서 할당하여, 매니저의 지시에 따라 지정된 agent가 작업 위임 및 실행을 원활히 수행할 수 있도록 하십시오. + 도구는 작업 수준에서도 지정할 수 있어, 작업 수행 시 도구 가용성을 정밀하게 제어할 수 있습니다. + + + + 계층적 프로세스에서는 `manager_llm` 파라미터 설정이 매우 중요합니다. + 시스템이 올바르게 작동하려면 매니저 LLM이 반드시 설정되어야 하며, 이를 통해 맞춤형 의사결정이 가능합니다. + + +```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, +) +``` + +### 커스텀 매니저 에이전트 사용하기 + +또 다른 방법으로, 프로젝트의 관리 요구 사항에 맞게 맞춤형 속성을 가진 커스텀 매니저 에이전트를 생성할 수 있습니다. 이를 통해 매니저의 동작 및 기능을 보다 세밀하게 제어할 수 있습니다. + +```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, +) +``` + + + 매니저 에이전트 생성 및 맞춤화에 대한 자세한 내용은 [커스텀 매니저 에이전트 문서](/ko/learn/custom-manager-agent)를 참고하세요. + + +### 워크플로우 실행 + +1. **작업 할당**: 매니저는 각 에이전트의 역량과 사용 가능한 도구를 고려하여 전략적으로 작업을 할당합니다. +2. **실행 및 검토**: 에이전트는 비동기 실행 옵션과 콜백 함수로 작업을 완료하여 워크플로우를 효율적으로 진행할 수 있습니다. +3. **순차적 작업 진행**: 계층적 프로세스임에도 불구하고, 매니저의 감독 하에 작업은 원활한 진행을 위해 논리적인 순서를 따릅니다. + +## 결론 + +CrewAI에서 계층적 프로세스를 올바른 구성과 시스템 기능에 대한 이해와 함께 도입하면, 조직적이고 효율적인 프로젝트 관리가 가능합니다. +고급 기능과 커스터마이징을 활용하여 워크플로우를 특정 요구에 맞게 맞춤화함으로써, 최적의 작업 실행과 프로젝트 성공을 보장할 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/human-feedback-in-flows.mdx b/docs/v1.15.1/ko/learn/human-feedback-in-flows.mdx new file mode 100644 index 000000000..a6305ca8a --- /dev/null +++ b/docs/v1.15.1/ko/learn/human-feedback-in-flows.mdx @@ -0,0 +1,697 @@ +--- +title: Flow에서 인간 피드백 +description: "@human_feedback 데코레이터를 사용하여 CrewAI Flow에 인간 피드백을 직접 통합하는 방법을 알아보세요" +icon: user-check +mode: "wide" +--- + +## 개요 + + +`@human_feedback` 데코레이터는 **CrewAI 버전 1.8.0 이상**이 필요합니다. 이 기능을 사용하기 전에 설치를 업데이트하세요. + + +`@human_feedback` 데코레이터는 CrewAI Flow 내에서 직접 human-in-the-loop(HITL) 워크플로우를 가능하게 합니다. Flow 실행을 일시 중지하고, 인간에게 검토를 위해 출력을 제시하고, 피드백을 수집하고, 선택적으로 피드백 결과에 따라 다른 리스너로 라우팅할 수 있습니다. + +이는 특히 다음과 같은 경우에 유용합니다: + +- **품질 보증**: AI가 생성한 콘텐츠를 다운스트림에서 사용하기 전에 검토 +- **결정 게이트**: 자동화된 워크플로우에서 인간이 중요한 결정을 내리도록 허용 +- **승인 워크플로우**: 승인/거부/수정 패턴 구현 +- **대화형 개선**: 출력을 반복적으로 개선하기 위해 피드백 수집 + +```mermaid +flowchart LR + A[Flow 메서드] --> B[출력 생성됨] + B --> C[인간이 검토] + C --> D{피드백} + D -->|emit 지정됨| E[LLM이 Outcome으로 매핑] + D -->|emit 없음| F[HumanFeedbackResult] + E --> G["@listen('approved')"] + E --> H["@listen('rejected')"] + F --> I[다음 리스너] +``` + +## 빠른 시작 + +Flow에 인간 피드백을 추가하는 가장 간단한 방법은 다음과 같습니다: + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback + +class SimpleReviewFlow(Flow): + @start() + @human_feedback(message="이 콘텐츠를 검토해 주세요:") + def generate_content(self): + return "검토가 필요한 AI 생성 콘텐츠입니다." + + @listen(generate_content) + def process_feedback(self, result): + print(f"콘텐츠: {result.output}") + print(f"인간의 의견: {result.feedback}") + +flow = SimpleReviewFlow() +flow.kickoff() +``` + +이 Flow를 실행하면: +1. `generate_content`를 실행하고 문자열을 반환합니다 +2. 요청 메시지와 함께 사용자에게 출력을 표시합니다 +3. 사용자가 피드백을 입력할 때까지 대기합니다 (또는 Enter를 눌러 건너뜁니다) +4. `HumanFeedbackResult` 객체를 `process_feedback`에 전달합니다 + +## @human_feedback 데코레이터 + +### 매개변수 + +| 매개변수 | 타입 | 필수 | 설명 | +|----------|------|------|------| +| `message` | `str` | 예 | 메서드 출력과 함께 인간에게 표시되는 메시지 | +| `emit` | `Sequence[str]` | 아니오 | 가능한 outcome 목록. 피드백이 이 중 하나로 매핑되어 `@listen` 데코레이터를 트리거합니다 | +| `llm` | `str \| BaseLLM` | `emit` 지정 시 | 피드백을 해석하고 outcome에 매핑하는 데 사용되는 LLM | +| `default_outcome` | `str` | 아니오 | 피드백이 제공되지 않을 때 사용할 outcome. `emit`에 있어야 합니다 | +| `metadata` | `dict` | 아니오 | 엔터프라이즈 통합을 위한 추가 데이터 | +| `provider` | `HumanFeedbackProvider` | 아니오 | 비동기/논블로킹 피드백을 위한 커스텀 프로바이더. [비동기 인간 피드백](#비동기-인간-피드백-논블로킹) 참조 | +| `learn` | `bool` | 아니오 | HITL 학습 활성화: 피드백에서 교훈을 추출하고 향후 출력을 사전 검토합니다. 기본값 `False`. [피드백에서 학습하기](#피드백에서-학습하기) 참조 | +| `learn_limit` | `int` | 아니오 | 사전 검토를 위해 불러올 최대 과거 교훈 수. 기본값 `5` | + +### 기본 사용법 (라우팅 없음) + +`emit`을 지정하지 않으면, 데코레이터는 단순히 피드백을 수집하고 다음 리스너에 `HumanFeedbackResult`를 전달합니다: + +```python Code +@start() +@human_feedback(message="이 분석에 대해 어떻게 생각하시나요?") +def analyze_data(self): + return "분석 결과: 매출 15% 증가, 비용 8% 감소" + +@listen(analyze_data) +def handle_feedback(self, result): + # result는 HumanFeedbackResult입니다 + print(f"분석: {result.output}") + print(f"피드백: {result.feedback}") +``` + +### emit을 사용한 라우팅 + +`emit`을 지정하면, 데코레이터는 라우터가 됩니다. 인간의 자유 형식 피드백이 LLM에 의해 해석되어 지정된 outcome 중 하나로 매핑됩니다: + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback + +class ReviewFlow(Flow): + @start() + def generate_content(self): + return "블로그 게시물 초안 내용..." + + @human_feedback( + message="이 콘텐츠의 출판을 승인하시겠습니까?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "블로그 게시물 초안 내용..." + + @listen("approved") + def publish(self, result): + print(f"출판 중! 사용자 의견: {result.feedback}") + + @listen("rejected") + def discard(self, result): + print(f"폐기됨. 이유: {result.feedback}") +``` + +사용자가 "더 자세한 내용이 필요합니다"와 같이 말하면, LLM이 이를 `"needs_revision"`으로 매핑하고, `or_()`를 통해 `review_content`가 다시 트리거됩니다 — 수정 루프가 생성됩니다. outcome이 `"approved"` 또는 `"rejected"`가 될 때까지 루프가 계속됩니다. + + +LLM은 가능한 경우 구조화된 출력(function calling)을 사용하여 응답이 지정된 outcome 중 하나임을 보장합니다. 이로 인해 라우팅이 신뢰할 수 있고 예측 가능해집니다. + + + +`@start()` 메서드는 flow 시작 시 한 번만 실행됩니다. 수정 루프가 필요한 경우, start 메서드를 review 메서드와 분리하고 review 메서드에 `@listen(or_("trigger", "revision_outcome"))`를 사용하여 self-loop을 활성화하세요. + + +## HumanFeedbackResult + +`HumanFeedbackResult` 데이터클래스는 인간 피드백 상호작용에 대한 모든 정보를 포함합니다: + +```python Code +from crewai.flow.human_feedback import HumanFeedbackResult + +@dataclass +class HumanFeedbackResult: + output: Any # 인간에게 표시된 원래 메서드 출력 + feedback: str # 인간의 원시 피드백 텍스트 + outcome: str | None # 매핑된 outcome (emit이 지정된 경우) + timestamp: datetime # 피드백이 수신된 시간 + method_name: str # 데코레이터된 메서드의 이름 + metadata: dict # 데코레이터에 전달된 모든 메타데이터 +``` + +### 리스너에서 접근하기 + +`emit`이 있는 `@human_feedback` 메서드에 의해 리스너가 트리거되면, `HumanFeedbackResult`를 받습니다: + +```python Code +@listen("approved") +def on_approval(self, result: HumanFeedbackResult): + print(f"원래 출력: {result.output}") + print(f"사용자 피드백: {result.feedback}") + print(f"Outcome: {result.outcome}") # "approved" + print(f"수신 시간: {result.timestamp}") +``` + +## 피드백 히스토리 접근하기 + +`Flow` 클래스는 인간 피드백에 접근하기 위한 두 가지 속성을 제공합니다: + +### last_human_feedback + +가장 최근의 `HumanFeedbackResult`를 반환합니다: + +```python Code +@listen(some_method) +def check_feedback(self): + if self.last_human_feedback: + print(f"마지막 피드백: {self.last_human_feedback.feedback}") +``` + +### human_feedback_history + +Flow 동안 수집된 모든 `HumanFeedbackResult` 객체의 리스트입니다: + +```python Code +@listen(final_step) +def summarize(self): + print(f"수집된 총 피드백: {len(self.human_feedback_history)}") + for i, fb in enumerate(self.human_feedback_history): + print(f"{i+1}. {fb.method_name}: {fb.outcome or '라우팅 없음'}") +``` + + +각 `HumanFeedbackResult`는 `human_feedback_history`에 추가되므로, 여러 피드백 단계가 서로 덮어쓰지 않습니다. 이 리스트를 사용하여 Flow 동안 수집된 모든 피드백에 접근하세요. + + +## 완전한 예제: 콘텐츠 승인 워크플로우 + +콘텐츠 검토 및 승인 워크플로우를 구현하는 전체 예제입니다: + + + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult +from pydantic import BaseModel + + +class ContentState(BaseModel): + draft: str = "" + revision_count: int = 0 + status: str = "pending" + + +class ContentApprovalFlow(Flow[ContentState]): + """콘텐츠를 생성하고 승인될 때까지 반복하는 Flow.""" + + @start() + def generate_draft(self): + self.state.draft = "# AI 안전\n\nAI 안전에 대한 초안..." + return self.state.draft + + @human_feedback( + message="이 초안을 검토해 주세요. 승인, 거부 또는 변경이 필요한 사항을 설명해 주세요:", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_draft", "needs_revision")) + def review_draft(self): + self.state.revision_count += 1 + return f"{self.state.draft} (v{self.state.revision_count})" + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + self.state.status = "published" + print(f"콘텐츠 승인 및 게시! 리뷰어 의견: {result.feedback}") + return "published" + + @listen("rejected") + def handle_rejection(self, result: HumanFeedbackResult): + self.state.status = "rejected" + print(f"콘텐츠 거부됨. 이유: {result.feedback}") + return "rejected" + + +flow = ContentApprovalFlow() +result = flow.kickoff() +print(f"\nFlow 완료. 상태: {flow.state.status}, 검토 횟수: {flow.state.revision_count}") +``` + +```text Output +================================================== +OUTPUT FOR REVIEW: +================================================== +# AI 안전 + +AI 안전에 대한 초안... (v1) +================================================== + +이 초안을 검토해 주세요. 승인, 거부 또는 변경이 필요한 사항을 설명해 주세요: +(Press Enter to skip, or type your feedback) + +Your feedback: 더 자세한 내용이 필요합니다 + +================================================== +OUTPUT FOR REVIEW: +================================================== +# AI 안전 + +AI 안전에 대한 초안... (v2) +================================================== + +이 초안을 검토해 주세요. 승인, 거부 또는 변경이 필요한 사항을 설명해 주세요: +(Press Enter to skip, or type your feedback) + +Your feedback: 좋아 보입니다, 승인! + +콘텐츠 승인 및 게시! 리뷰어 의견: 좋아 보입니다, 승인! + +Flow 완료. 상태: published, 검토 횟수: 2 +``` + + + +## 다른 데코레이터와 결합하기 + +`@human_feedback` 데코레이터는 `@start()`, `@listen()`, `or_()`와 함께 작동합니다. 데코레이터 순서는 두 가지 모두 동작합니다—프레임워크가 양방향으로 속성을 전파합니다—하지만 권장 패턴은 다음과 같습니다: + +```python Code +# Flow 시작 시 일회성 검토 (self-loop 없음) +@start() +@human_feedback(message="이것을 검토해 주세요:", emit=["approved", "rejected"], llm="gpt-4o-mini") +def my_start_method(self): + return "content" + +# 리스너에서 선형 검토 (self-loop 없음) +@listen(other_method) +@human_feedback(message="이것도 검토해 주세요:", emit=["good", "bad"], llm="gpt-4o-mini") +def my_listener(self, data): + return f"processed: {data}" + +# Self-loop: 수정을 위해 반복할 수 있는 검토 +@human_feedback(message="승인 또는 수정 요청?", emit=["approved", "revise"], llm="gpt-4o-mini") +@listen(or_("upstream_method", "revise")) +def review_with_loop(self): + return "content for review" +``` + +### Self-loop 패턴 + +수정 루프를 만들려면 `or_()`를 사용하여 검토 메서드가 **상위 트리거**와 **자체 수정 outcome**을 모두 리스닝해야 합니다: + +```python Code +@start() +def generate(self): + return "initial draft" + +@human_feedback( + message="승인하시겠습니까, 아니면 변경을 요청하시겠습니까?", + emit=["revise", "approved"], + llm="gpt-4o-mini", + default_outcome="approved", +) +@listen(or_("generate", "revise")) +def review(self): + return "content" + +@listen("approved") +def publish(self): + return "published" +``` + +outcome이 `"revise"`이면 flow가 `review`로 다시 라우팅됩니다 (`or_()`를 통해 `"revise"`를 리스닝하기 때문). outcome이 `"approved"`이면 flow가 `publish`로 계속됩니다. flow 엔진이 라우터를 "한 번만 실행" 규칙에서 제외하여 각 루프 반복마다 재실행할 수 있기 때문에 이 패턴이 동작합니다. + +### 체인된 라우터 + +한 라우터의 outcome으로 트리거된 리스너가 그 자체로 라우터가 될 수 있습니다: + +```python Code +@start() +@human_feedback(message="첫 번째 검토:", emit=["approved", "rejected"], llm="gpt-4o-mini") +def draft(self): + return "draft content" + +@listen("approved") +@human_feedback(message="최종 검토:", emit=["publish", "revise"], llm="gpt-4o-mini") +def final_review(self, prev): + return "final content" + +@listen("publish") +def on_publish(self, prev): + return "published" +``` + +### 제한 사항 + +- **`@start()` 메서드는 한 번만 실행**: `@start()` 메서드는 self-loop할 수 없습니다. 수정 주기가 필요하면 별도의 `@start()` 메서드를 진입점으로 사용하고 `@listen()` 메서드에 `@human_feedback`를 배치하세요. +- **동일 메서드에 `@start()` + `@listen()` 불가**: 이는 Flow 프레임워크 제약입니다. 메서드는 시작점이거나 리스너여야 하며, 둘 다일 수 없습니다. + +## 모범 사례 + +### 1. 명확한 요청 메시지 작성 + +`message` 매개변수는 인간이 보는 것입니다. 실행 가능하게 만드세요: + +```python Code +# ✅ 좋음 - 명확하고 실행 가능 +@human_feedback(message="이 요약이 핵심 포인트를 정확하게 캡처했나요? '예'로 답하거나 무엇이 빠졌는지 설명해 주세요:") + +# ❌ 나쁨 - 모호함 +@human_feedback(message="이것을 검토해 주세요:") +``` + +### 2. 의미 있는 Outcome 선택 + +`emit`을 사용할 때, 인간의 응답에 자연스럽게 매핑되는 outcome을 선택하세요: + +```python Code +# ✅ 좋음 - 자연어 outcome +emit=["approved", "rejected", "needs_more_detail"] + +# ❌ 나쁨 - 기술적이거나 불명확 +emit=["state_1", "state_2", "state_3"] +``` + +### 3. 항상 기본 Outcome 제공 + +사용자가 입력 없이 Enter를 누르는 경우를 처리하기 위해 `default_outcome`을 사용하세요: + +```python Code +@human_feedback( + message="승인하시겠습니까? (수정 요청하려면 Enter 누르세요)", + emit=["approved", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", # 안전한 기본값 +) +``` + +### 4. 감사 추적을 위한 피드백 히스토리 사용 + +감사 로그를 생성하기 위해 `human_feedback_history`에 접근하세요: + +```python Code +@listen(final_step) +def create_audit_log(self): + log = [] + for fb in self.human_feedback_history: + log.append({ + "step": fb.method_name, + "outcome": fb.outcome, + "feedback": fb.feedback, + "timestamp": fb.timestamp.isoformat(), + }) + return log +``` + +### 5. 라우팅된 피드백과 라우팅되지 않은 피드백 모두 처리 + +Flow를 설계할 때, 라우팅이 필요한지 고려하세요: + +| 시나리오 | 사용 | +|----------|------| +| 간단한 검토, 피드백 텍스트만 필요 | `emit` 없음 | +| 응답에 따라 다른 경로로 분기 필요 | `emit` 사용 | +| 승인/거부/수정이 있는 승인 게이트 | `emit` 사용 | +| 로깅만을 위한 코멘트 수집 | `emit` 없음 | + +## 비동기 인간 피드백 (논블로킹) + +기본적으로 `@human_feedback`은 콘솔 입력을 기다리며 실행을 차단합니다. 프로덕션 애플리케이션에서는 Slack, 이메일, 웹훅 또는 API와 같은 외부 시스템과 통합되는 **비동기/논블로킹** 피드백이 필요할 수 있습니다. + +### Provider 추상화 + +커스텀 피드백 수집 전략을 지정하려면 `provider` 매개변수를 사용하세요: + +```python Code +from crewai.flow import Flow, start, human_feedback, HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext + +class WebhookProvider(HumanFeedbackProvider): + """웹훅 콜백을 기다리며 Flow를 일시 중지하는 Provider.""" + + def __init__(self, webhook_url: str): + self.webhook_url = webhook_url + + def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str: + # 외부 시스템에 알림 (예: Slack 메시지 전송, 티켓 생성) + self.send_notification(context) + + # 실행 일시 중지 - 프레임워크가 자동으로 영속성 처리 + raise HumanFeedbackPending( + context=context, + callback_info={"webhook_url": f"{self.webhook_url}/{context.flow_id}"} + ) + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="이 콘텐츠를 검토해 주세요:", + emit=["approved", "rejected"], + llm="gpt-4o-mini", + provider=WebhookProvider("https://myapp.com/api"), + ) + def generate_content(self): + return "AI가 생성한 콘텐츠..." + + @listen("approved") + def publish(self, result): + return "출판됨!" +``` + + +Flow 프레임워크는 `HumanFeedbackPending`이 발생하면 **자동으로 상태를 영속화**합니다. Provider는 외부 시스템에 알리고 예외를 발생시키기만 하면 됩니다—수동 영속성 호출이 필요하지 않습니다. + + +### 일시 중지된 Flow 처리 + +비동기 provider를 사용하면 `kickoff()`는 예외를 발생시키는 대신 `HumanFeedbackPending` 객체를 반환합니다: + +```python Code +flow = ReviewFlow() +result = flow.kickoff() + +if isinstance(result, HumanFeedbackPending): + # Flow가 일시 중지됨, 상태가 자동으로 영속화됨 + print(f"피드백 대기 중: {result.callback_info['webhook_url']}") + print(f"Flow ID: {result.context.flow_id}") +else: + # 정상 완료 + print(f"Flow 완료: {result}") +``` + +### 일시 중지된 Flow 재개 + +피드백이 도착하면 (예: 웹훅을 통해) Flow를 재개합니다: + +```python Code +# 동기 핸들러: +def handle_feedback_webhook(flow_id: str, feedback: str): + flow = ReviewFlow.from_pending(flow_id) + result = flow.resume(feedback) + return result + +# 비동기 핸들러 (FastAPI, aiohttp 등): +async def handle_feedback_webhook(flow_id: str, feedback: str): + flow = ReviewFlow.from_pending(flow_id) + result = await flow.resume_async(feedback) + return result +``` + +### 주요 타입 + +| 타입 | 설명 | +|------|------| +| `HumanFeedbackProvider` | 커스텀 피드백 provider를 위한 프로토콜 | +| `PendingFeedbackContext` | 일시 중지된 Flow를 재개하는 데 필요한 모든 정보 포함 | +| `HumanFeedbackPending` | Flow가 피드백을 위해 일시 중지되면 `kickoff()`에서 반환됨 | +| `ConsoleProvider` | 기본 블로킹 콘솔 입력 provider | + +### PendingFeedbackContext + +컨텍스트는 재개에 필요한 모든 것을 포함합니다: + +```python Code +@dataclass +class PendingFeedbackContext: + flow_id: str # 이 Flow 실행의 고유 식별자 + flow_class: str # 정규화된 클래스 이름 + method_name: str # 피드백을 트리거한 메서드 + method_output: Any # 인간에게 표시된 출력 + message: str # 요청 메시지 + emit: list[str] | None # 라우팅을 위한 가능한 outcome + default_outcome: str | None + metadata: dict # 커스텀 메타데이터 + llm: str | None # outcome 매핑을 위한 LLM + requested_at: datetime +``` + +### 완전한 비동기 Flow 예제 + +```python Code +from crewai.flow import ( + Flow, start, listen, human_feedback, + HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext +) + +class SlackNotificationProvider(HumanFeedbackProvider): + """Slack 알림을 보내고 비동기 피드백을 위해 일시 중지하는 Provider.""" + + def __init__(self, channel: str): + self.channel = channel + + def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str: + # Slack 알림 전송 (직접 구현) + slack_thread_id = self.post_to_slack( + channel=self.channel, + message=f"검토 필요:\n\n{context.method_output}\n\n{context.message}", + ) + + # 실행 일시 중지 - 프레임워크가 자동으로 영속성 처리 + raise HumanFeedbackPending( + context=context, + callback_info={ + "slack_channel": self.channel, + "thread_id": slack_thread_id, + } + ) + +class ContentPipeline(Flow): + @start() + @human_feedback( + message="이 콘텐츠의 출판을 승인하시겠습니까?", + emit=["approved", "rejected"], + llm="gpt-4o-mini", + default_outcome="rejected", + provider=SlackNotificationProvider("#content-reviews"), + ) + def generate_content(self): + return "AI가 생성한 블로그 게시물 콘텐츠..." + + @listen("approved") + def publish(self, result): + print(f"출판 중! 검토자 의견: {result.feedback}") + return {"status": "published"} + + @listen("rejected") + def archive(self, result): + print(f"보관됨. 이유: {result.feedback}") + return {"status": "archived"} + + +# Flow 시작 (Slack 응답을 기다리며 일시 중지) +def start_content_pipeline(): + flow = ContentPipeline() + result = flow.kickoff() + + if isinstance(result, HumanFeedbackPending): + return {"status": "pending", "flow_id": result.context.flow_id} + + return result + + +# Slack 웹훅이 실행될 때 재개 (동기 핸들러) +def on_slack_feedback(flow_id: str, slack_message: str): + flow = ContentPipeline.from_pending(flow_id) + result = flow.resume(slack_message) + return result + + +# 핸들러가 비동기인 경우 (FastAPI, aiohttp, Slack Bolt 비동기 등) +async def on_slack_feedback_async(flow_id: str, slack_message: str): + flow = ContentPipeline.from_pending(flow_id) + result = await flow.resume_async(slack_message) + return result +``` + + +비동기 웹 프레임워크(FastAPI, aiohttp, Slack Bolt 비동기 모드)를 사용하는 경우 `flow.resume()` 대신 `await flow.resume_async()`를 사용하세요. 실행 중인 이벤트 루프 내에서 `resume()`을 호출하면 `RuntimeError`가 발생합니다. + + +### 비동기 피드백 모범 사례 + +1. **반환 타입 확인**: `kickoff()`는 일시 중지되면 `HumanFeedbackPending`을 반환합니다—try/except가 필요하지 않습니다 +2. **올바른 resume 메서드 사용**: 동기 코드에서는 `resume()`, 비동기 코드에서는 `await resume_async()` 사용 +3. **콜백 정보 저장**: `callback_info`를 사용하여 웹훅 URL, 티켓 ID 등을 저장 +4. **멱등성 구현**: 안전을 위해 resume 핸들러는 멱등해야 합니다 +5. **자동 영속성**: `HumanFeedbackPending`이 발생하면 상태가 자동으로 저장되며 기본적으로 `SQLiteFlowPersistence` 사용 +6. **커스텀 영속성**: 필요한 경우 `from_pending()`에 커스텀 영속성 인스턴스 전달 + +## 피드백에서 학습하기 + +`learn=True` 매개변수는 인간 검토자와 메모리 시스템 간의 피드백 루프를 활성화합니다. 활성화되면 시스템은 과거 인간의 수정 사항에서 학습하여 출력을 점진적으로 개선합니다. + +### 작동 방식 + +1. **피드백 후**: LLM이 출력 + 피드백에서 일반화 가능한 교훈을 추출하고 `source="hitl"`로 메모리에 저장합니다. 피드백이 단순한 승인(예: "좋아 보입니다")인 경우 아무것도 저장하지 않습니다. +2. **다음 검토 전**: 과거 HITL 교훈을 메모리에서 불러와 LLM이 인간이 보기 전에 출력을 개선하는 데 적용합니다. + +시간이 지남에 따라 각 수정 사항이 향후 검토에 반영되므로 인간은 점진적으로 더 나은 사전 검토된 출력을 보게 됩니다. + +### 예제 + +```python Code +class ArticleReviewFlow(Flow): + @start() + def generate_article(self): + return self.crew.kickoff(inputs={"topic": "AI Safety"}).raw + + @human_feedback( + message="이 글 초안을 검토해 주세요:", + emit=["approved", "needs_revision"], + llm="gpt-4o-mini", + learn=True, + ) + @listen(or_("generate_article", "needs_revision")) + def review_article(self): + return self.last_human_feedback.output if self.last_human_feedback else "article draft" + + @listen("approved") + def publish(self): + print(f"Publishing: {self.last_human_feedback.output}") +``` + +**첫 번째 실행**: 인간이 원시 출력을 보고 "사실에 대한 주장에는 항상 인용을 포함하세요."라고 말합니다. 교훈이 추출되어 메모리에 저장됩니다. + +**두 번째 실행**: 시스템이 인용 교훈을 불러와 출력을 사전 검토하여 인용을 추가한 후 개선된 버전을 표시합니다. 인간의 역할이 "모든 것을 수정"에서 "시스템이 놓친 것을 찾기"로 전환됩니다. + +### 구성 + +| 매개변수 | 기본값 | 설명 | +|-----------|--------|------| +| `learn` | `False` | HITL 학습 활성화 | +| `learn_limit` | `5` | 사전 검토를 위해 불러올 최대 과거 교훈 수 | + +### 주요 설계 결정 + +- **모든 것에 동일한 LLM 사용**: 데코레이터의 `llm` 매개변수는 outcome 매핑, 교훈 추출, 사전 검토에 공유됩니다. 여러 모델을 구성할 필요가 없습니다. +- **구조화된 출력**: 추출과 사전 검토 모두 LLM이 지원하는 경우 Pydantic 모델과 함께 function calling을 사용하고, 그렇지 않으면 텍스트 파싱으로 폴백합니다. +- **논블로킹 저장**: 교훈은 백그라운드 스레드에서 실행되는 `remember_many()`를 통해 저장됩니다 -- Flow는 즉시 계속됩니다. +- **우아한 저하**: 추출 중 LLM이 실패하면 아무것도 저장하지 않습니다. 사전 검토 중 실패하면 원시 출력이 표시됩니다. 어느 쪽의 실패도 Flow를 차단하지 않습니다. +- **범위/카테고리 불필요**: 교훈을 저장할 때 `source`만 전달됩니다. 인코딩 파이프라인이 범위, 카테고리, 중요도를 자동으로 추론합니다. + + +`learn=True`는 Flow에 메모리가 사용 가능해야 합니다. Flow는 기본적으로 자동으로 메모리를 얻지만, `_skip_auto_memory`로 비활성화한 경우 HITL 학습은 조용히 건너뜁니다. + + + +## 관련 문서 + +- [Flow 개요](/ko/concepts/flows) - CrewAI Flow에 대해 알아보기 +- [Flow 상태 관리](/ko/guides/flows/mastering-flow-state) - Flow에서 상태 관리하기 +- [Flow 영속성](/ko/concepts/flows#persistence) - Flow 상태 영속화 +- [@router를 사용한 라우팅](/ko/concepts/flows#router) - 조건부 라우팅에 대해 더 알아보기 +- [실행 시 인간 입력](/ko/learn/human-input-on-execution) - 태스크 수준 인간 입력 +- [메모리](/ko/concepts/memory) - HITL 학습에서 사용되는 통합 메모리 시스템 diff --git a/docs/v1.15.1/ko/learn/human-in-the-loop.mdx b/docs/v1.15.1/ko/learn/human-in-the-loop.mdx new file mode 100644 index 000000000..fe9c1d145 --- /dev/null +++ b/docs/v1.15.1/ko/learn/human-in-the-loop.mdx @@ -0,0 +1,120 @@ +--- +title: "Human-in-the-Loop (HITL) 워크플로우" +description: "CrewAI에서 Human-in-the-Loop 워크플로우를 구현하여 의사결정을 향상시키는 방법을 알아보세요" +icon: "user-check" +mode: "wide" +--- + +휴먼 인 더 루프(HITL, Human-in-the-Loop)는 인공지능과 인간의 전문 지식을 결합하여 의사결정을 강화하고 작업 결과를 향상시키는 강력한 접근 방식입니다. CrewAI는 필요에 따라 HITL을 구현하는 여러 가지 방법을 제공합니다. + +## HITL 접근 방식 선택 + +CrewAI는 human-in-the-loop 워크플로우를 구현하기 위한 두 가지 주요 접근 방식을 제공합니다: + +| 접근 방식 | 적합한 용도 | 통합 | 버전 | +|----------|----------|-------------|---------| +| **Flow 기반** (`@human_feedback` 데코레이터) | 로컬 개발, 콘솔 기반 검토, 동기식 워크플로우 | [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) | **1.8.0+** | +| **Webhook 기반** (Enterprise) | 프로덕션 배포, 비동기 워크플로우, 외부 통합 (Slack, Teams 등) | 이 가이드 | - | + + +Flow를 구축하면서 피드백을 기반으로 라우팅하는 인간 검토 단계를 추가하려면 `@human_feedback` 데코레이터에 대한 [Flow에서 인간 피드백](/ko/learn/human-feedback-in-flows) 가이드를 참조하세요. + + +## Webhook 기반 HITL 워크플로우 설정 + + + + human input이 활성화된 상태로 작업을 설정하세요: + + Crew Human Input + + + + + crew를 시작할 때, human input을 위한 webhook URL을 포함하세요: + + Crew Webhook URL + + + + + crew가 human input이 필요한 작업을 완료하면, 다음 내용을 포함하는 webhook 알림을 받게 됩니다: + - 실행 ID + - 작업 ID + - 작업 출력 + + + + 시스템이 `Pending Human Input` 상태에서 일시정지됩니다. 작업 출력을 신중하게 검토하세요. + + + + 다음 정보를 포함하여 crew의 resume endpoint를 호출하세요: + + Crew Resume Endpoint + + + + **중요: Webhook URL을 다시 제공해야 합니다**: + kickoff 호출에서 사용한 것과 동일한 webhook URL(`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`)을 resume 호출에서 **반드시** 제공해야 합니다. Webhook 설정은 kickoff에서 자동으로 전달되지 **않으므로**, 작업 완료, 에이전트 단계, crew 완료에 대한 알림을 계속 받으려면 resume 요청에 명시적으로 포함해야 합니다. + + + Webhook을 포함한 resume 호출 예시: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "훌륭한 작업입니다! 더 자세한 내용을 추가해주세요.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **피드백이 작업 실행에 미치는 영향**: + 피드백의 전체 내용이 추가 컨텍스트로서 이후 작업 실행에 통합되므로, 피드백 제공 시 신중을 기하는 것이 매우 중요합니다. + + 즉: + - 피드백에 포함된 모든 정보가 작업의 컨텍스트의 일부가 됩니다. + - 관련 없는 세부 정보는 작업에 부정적인 영향을 미칠 수 있습니다. + - 간결하고 관련성 높은 피드백이 작업의 집중력과 효율성을 유지하는 데 도움이 됩니다. + - 제출 전에 피드백을 항상 꼼꼼히 검토하여 작업 실행을 긍정적으로 이끌 수 있는 정보만 포함되어 있는지 확인하세요. + + + 부정적인 피드백을 제공할 경우: + - crew는 피드백에서 얻은 추가 컨텍스트로 작업을 재시도합니다. + - 추가 검토를 위한 또 다른 webhook 알림을 받게 됩니다. + - 만족할 때까지 4-6단계를 반복하세요. + + + + 긍정적인 피드백을 제출하면 실행이 다음 단계로 진행됩니다. + + + +## 모범 사례 + +- **구체적으로 작성하세요**: 해당 작업에 직접적으로 관련된 명확하고 실행 가능한 피드백을 제공하세요 +- **관련성을 유지하세요**: 작업 수행 개선에 도움이 되는 정보만 포함하세요 +- **시기적절하게 응답하세요**: 워크플로우 지연을 방지하기 위해 HITL 프롬프트에 신속하게 응답하세요 +- **신중하게 검토하세요**: 제출 전 피드백을 다시 확인하여 정확성을 확보하세요 + +## 일반적인 사용 사례 + +HITL 워크플로우는 다음과 같은 경우에 특히 유용합니다: +- 품질 보증 및 검증 +- 복잡한 의사결정 시나리오 +- 민감하거나 고위험 작업 +- 인간의 판단이 필요한 창의적 과제 +- 컴플라이언스 및 규제 검토 + +## Enterprise 기능 + + + CrewAI Enterprise는 플랫폼 내 검토, 응답자 할당, 권한, 에스컬레이션 정책, SLA 관리, 동적 라우팅 및 전체 분석을 갖춘 Flow용 포괄적인 HITL 관리 시스템을 제공합니다. [자세히 알아보기 →](/ko/enterprise/features/flow-hitl-management) + diff --git a/docs/v1.15.1/ko/learn/human-input-on-execution.mdx b/docs/v1.15.1/ko/learn/human-input-on-execution.mdx new file mode 100644 index 000000000..4eb4bca3c --- /dev/null +++ b/docs/v1.15.1/ko/learn/human-input-on-execution.mdx @@ -0,0 +1,99 @@ +--- +title: 실행 중 인간 입력 +description: 복잡한 의사결정 과정에서 실행 중 CrewAI와 인간 입력을 통합하고, 에이전트의 속성과 도구의 모든 기능을 활용하는 방법. +icon: user-plus +mode: "wide" +--- + +## 에이전트 실행에서의 인간 입력 + +인간 입력은 여러 에이전트 실행 시나리오에서 매우 중요하며, 에이전트가 필요할 때 추가 정보나 설명을 요청할 수 있게 해줍니다. +이 기능은 특히 복잡한 의사결정 과정이나 에이전트가 작업을 효과적으로 완료하기 위해 더 많은 세부 정보가 필요할 때 유용하게 사용됩니다. + +## CrewAI에서 인간 입력 사용하기 + +에이전트 실행에 인간 입력을 통합하려면, 태스크 정의에서 `human_input` 플래그를 설정하세요. 이 기능이 활성화되면 에이전트는 최종 답변을 제공하기 전에 사용자에게 입력을 요청합니다. +이 입력은 추가적인 컨텍스트를 제공하거나, 모호성을 해소하거나, 에이전트의 출력을 검증하는 데 사용할 수 있습니다. + +### 예시: + +```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) +``` diff --git a/docs/v1.15.1/ko/learn/kickoff-async.mdx b/docs/v1.15.1/ko/learn/kickoff-async.mdx new file mode 100644 index 000000000..46292b36e --- /dev/null +++ b/docs/v1.15.1/ko/learn/kickoff-async.mdx @@ -0,0 +1,306 @@ +--- +title: Crew 비동기 시작 +description: Crew를 비동기로 시작하기 +icon: rocket-launch +mode: "wide" +--- + +## 소개 + +CrewAI는 crew를 비동기적으로 시작할 수 있는 기능을 제공합니다. 이를 통해 crew 실행을 블로킹(blocking) 없이 시작할 수 있습니다. +이 기능은 여러 개의 crew를 동시에 실행하거나 crew가 실행되는 동안 다른 작업을 수행해야 할 때 특히 유용합니다. + +CrewAI는 비동기 실행을 위해 두 가지 접근 방식을 제공합니다: + +| 메서드 | 타입 | 설명 | +|--------|------|-------------| +| `akickoff()` | 네이티브 async | 전체 실행 체인에서 진정한 async/await 사용 | +| `kickoff_async()` | 스레드 기반 | 동기 실행을 `asyncio.to_thread`로 래핑 | + + +고동시성 워크로드의 경우 `akickoff()`가 권장됩니다. 이는 작업 실행, 메모리 작업, 지식 검색에 네이티브 async를 사용합니다. + + +## `akickoff()`를 사용한 네이티브 비동기 실행 + +`akickoff()` 메서드는 작업 실행, 메모리 작업, 지식 쿼리를 포함한 전체 실행 체인에서 async/await를 사용하여 진정한 네이티브 비동기 실행을 제공합니다. + +### 메서드 시그니처 + +```python Code +async def akickoff(self, inputs: dict) -> CrewOutput: +``` + +### 매개변수 + +- `inputs` (dict): 작업에 필요한 입력 데이터를 포함하는 딕셔너리입니다. + +### 반환 + +- `CrewOutput`: crew 실행 결과를 나타내는 객체입니다. + +### 예시: 네이티브 비동기 Crew 실행 + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# 에이전트 생성 +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 +) + +# 작업 생성 +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." +) + +# Crew 생성 +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# 네이티브 비동기 실행 +async def main(): + result = await analysis_crew.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(main()) +``` + +### 예시: 여러 네이티브 비동기 Crew + +`asyncio.gather()`를 사용하여 네이티브 async로 여러 crew를 동시에 실행: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +task_1 = Task( + description="Analyze the first dataset and calculate the average age. 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. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def main(): + results = await asyncio.gather( + crew_1.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}), + crew_2.akickoff(inputs={"ages": [20, 22, 24, 28, 30]}) + ) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(main()) +``` + +### 예시: 여러 입력에 대한 네이티브 비동기 + +`akickoff_for_each()`를 사용하여 네이티브 async로 여러 입력에 대해 crew를 동시에 실행: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +data_analysis_task = Task( + description="Analyze the dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def main(): + datasets = [ + {"ages": [25, 30, 35, 40, 45]}, + {"ages": [20, 22, 24, 28, 30]}, + {"ages": [30, 35, 40, 45, 50]} + ] + + results = await analysis_crew.akickoff_for_each(datasets) + + for i, result in enumerate(results, 1): + print(f"Dataset {i} Result:", result) + +asyncio.run(main()) +``` + +## `kickoff_async()`를 사용한 스레드 기반 비동기 + +`kickoff_async()` 메서드는 동기 `kickoff()`를 스레드로 래핑하여 비동기 실행을 제공합니다. 이는 더 간단한 비동기 통합이나 하위 호환성에 유용합니다. + +### 메서드 시그니처 + +```python Code +async def kickoff_async(self, inputs: dict) -> CrewOutput: +``` + +### 매개변수 + +- `inputs` (dict): 작업에 필요한 입력 데이터를 포함하는 딕셔너리입니다. + +### 반환 + +- `CrewOutput`: crew 실행 결과를 나타내는 객체입니다. + +### 예시: 스레드 기반 비동기 실행 + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(async_crew_execution()) +``` + +### 예시: 여러 스레드 기반 비동기 Crew + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def async_multiple_crews(): + 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]}) + + results = await asyncio.gather(result_1, result_2) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(async_multiple_crews()) +``` + +## 비동기 스트리밍 + +두 비동기 메서드 모두 crew에 `stream=True`가 설정된 경우 스트리밍을 지원합니다: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +agent = Agent( + role="Researcher", + goal="Research and summarize topics", + backstory="You are an expert researcher." +) + +task = Task( + description="Research the topic: {topic}", + agent=agent, + expected_output="A comprehensive summary of the topic." +) + +crew = Crew( + agents=[agent], + tasks=[task], + stream=True # 스트리밍 활성화 +) + +async def main(): + streaming_output = await crew.akickoff(inputs={"topic": "AI trends in 2024"}) + + # 스트리밍 청크에 대한 비동기 반복 + async for chunk in streaming_output: + print(f"Chunk: {chunk.content}") + + # 스트리밍 완료 후 최종 결과 접근 + result = streaming_output.result + print(f"Final result: {result.raw}") + +asyncio.run(main()) +``` + +## 잠재적 사용 사례 + +- **병렬 콘텐츠 생성**: 여러 개의 독립적인 crew를 비동기적으로 시작하여, 각 crew가 다른 주제에 대한 콘텐츠 생성을 담당합니다. 예를 들어, 한 crew는 AI 트렌드에 대한 기사 조사 및 초안을 작성하는 반면, 또 다른 crew는 신제품 출시와 관련된 소셜 미디어 게시물을 생성할 수 있습니다. + +- **동시 시장 조사 작업**: 여러 crew를 비동기적으로 시작하여 시장 조사를 병렬로 수행합니다. 한 crew는 업계 동향을 분석하고, 또 다른 crew는 경쟁사 전략을 조사하며, 또 다른 crew는 소비자 감정을 평가할 수 있습니다. + +- **독립적인 여행 계획 모듈**: 각각 독립적으로 여행의 다양한 측면을 계획하도록 crew를 따로 실행합니다. 한 crew는 항공편 옵션을, 다른 crew는 숙박을, 세 번째 crew는 활동 계획을 담당할 수 있습니다. + +## `akickoff()`와 `kickoff_async()` 선택하기 + +| 기능 | `akickoff()` | `kickoff_async()` | +|---------|--------------|-------------------| +| 실행 모델 | 네이티브 async/await | 스레드 기반 래퍼 | +| 작업 실행 | `aexecute_sync()`로 비동기 | 스레드 풀에서 동기 | +| 메모리 작업 | 비동기 | 스레드 풀에서 동기 | +| 지식 검색 | 비동기 | 스레드 풀에서 동기 | +| 적합한 용도 | 고동시성, I/O 바운드 워크로드 | 간단한 비동기 통합 | +| 스트리밍 지원 | 예 | 예 | diff --git a/docs/v1.15.1/ko/learn/kickoff-for-each.mdx b/docs/v1.15.1/ko/learn/kickoff-for-each.mdx new file mode 100644 index 000000000..4f10abb37 --- /dev/null +++ b/docs/v1.15.1/ko/learn/kickoff-for-each.mdx @@ -0,0 +1,54 @@ +--- +title: 각 항목에 대한 Kickoff Crew +description: 목록의 각 항목에 대한 Kickoff Crew +icon: at +mode: "wide" +--- + +## 소개 + +CrewAI는 목록의 각 항목에 대해 crew를 시작할 수 있는 기능을 제공하여, 목록의 각 항목에 대해 crew를 실행할 수 있게 합니다. +이 기능은 여러 항목에 대해 동일한 작업 세트를 수행해야 할 때 특히 유용합니다. + +## 각 항목에 대해 크루 시작하기 + +리스트의 각 항목에 대해 크루를 시작하려면 `kickoff_for_each()` 메서드를 사용하세요. +이 메서드는 리스트의 각 항목에 대해 크루를 실행하여 여러 항목을 효율적으로 처리할 수 있도록 합니다. + +아래는 리스트의 각 항목에 대해 크루를 시작하는 방법의 예시입니다: + +```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/v1.15.1/ko/learn/llm-connections.mdx b/docs/v1.15.1/ko/learn/llm-connections.mdx new file mode 100644 index 000000000..6976ab8e0 --- /dev/null +++ b/docs/v1.15.1/ko/learn/llm-connections.mdx @@ -0,0 +1,214 @@ +--- +title: 모든 LLM에 연결하기 +description: LiteLLM을 사용하여 CrewAI를 다양한 대형 언어 모델(LLM)과 통합하는 방법에 대한 종합적인 가이드로, 지원되는 제공자와 구성 옵션을 포함합니다. +icon: brain-circuit +mode: "wide" +--- + +## CrewAI를 LLM에 연결하기 + +CrewAI는 가장 인기 있는 제공자(OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock)에 대해 네이티브 SDK 통합을 통해 LLM에 연결하며, 그 외 모든 제공자에 대해서는 LiteLLM을 유연한 폴백으로 사용합니다. + + + 기본적으로 CrewAI는 `gpt-4o-mini` 모델을 사용합니다. 이는 `OPENAI_MODEL_NAME` 환경 변수에 의해 결정되며, 설정되지 않은 경우 기본값은 "gpt-4o-mini"입니다. + 본 가이드에 설명된 대로 다른 모델이나 공급자를 사용하도록 에이전트를 쉽게 설정할 수 있습니다. + + +## 지원되는 프로바이더 + +LiteLLM은 다음을 포함하되 이에 국한되지 않는 다양한 프로바이더를 지원합니다: + +- 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 +- Nebius AI Studio +- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1) +- 그리고 더 많은 프로바이더! + +지원되는 프로바이더의 전체 및 최신 목록은 [LiteLLM 프로바이더 문서](https://docs.litellm.ai/docs/providers)를 참조하세요. + + + 네이티브 통합에서 지원하지 않는 제공자를 사용하려면 LiteLLM을 프로젝트에 의존성으로 추가하세요: + ```bash + uv add 'crewai[litellm]' + ``` + 네이티브 제공자(OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock)는 자체 SDK extras를 사용합니다 — [공급자 구성 예시](/ko/concepts/llms#공급자-구성-예시)를 참조하세요. + + +## LLM 변경하기 + +CrewAI agent에서 다른 LLM을 사용하려면 여러 가지 방법이 있습니다: + + + + agent를 초기화할 때 모델 이름을 문자열로 전달하세요: + + ```python Code + from crewai import Agent + + # OpenAI의 GPT-4 사용 + 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' + ) + + # Anthropic의 Claude 사용 + claude_agent = Agent( + role='Anthropic Expert', + goal='Analyze data using Claude', + backstory="An AI assistant leveraging Anthropic's language model.", + llm='claude-2' + ) + ``` + + + + 더 자세한 설정을 위해 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 + ) + ``` + + + + +## 구성 옵션 + +에이전트를 위해 LLM을 구성할 때 다양한 매개변수를 사용할 수 있습니다: + +| 매개변수 | 유형 | 설명 | +|:----------|:-----:|:-------------| +| **model** | `str` | 사용할 모델의 이름 (예: "gpt-4", "claude-2") | +| **temperature** | `float` | 출력의 무작위성 제어 (0.0 ~ 1.0) | +| **max_tokens** | `int` | 생성할 최대 토큰 수 | +| **top_p** | `float` | 출력 다양성 제어 (0.0 ~ 1.0) | +| **frequency_penalty** | `float` | 지금까지의 텍스트에서 빈도에 따라 새로운 토큰에 패널티 부여 | +| **presence_penalty** | `float` | 지금까지의 텍스트에 이미 존재하는지에 따라 새로운 토큰에 패널티 부여 | +| **stop** | `str`, `List[str]` | 생성을 중단할 시퀀스(들) | +| **base_url** | `str` | API 엔드포인트의 기본 URL | +| **api_key** | `str` | 인증용 API 키 | + +매개변수와 그 설명의 전체 목록은 LLM 클래스 문서를 참고하십시오. + +## OpenAI 호환 LLM에 연결하기 + +OpenAI 호환 LLM에 연결하려면 환경 변수를 사용하거나 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 + + # Gemini의 OpenAI 호환 API 예시입니다. + os.environ["OPENAI_API_KEY"] = "your-gemini-key" # AIza...로 시작해야 합니다. + os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/" + os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Gemini 모델을 여기에 추가하세요. 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 + # Gemini의 OpenAI 호환 API 예시 + llm = LLM( + model="openai/gemini-2.0-flash", + base_url="https://generativelanguage.googleapis.com/v1beta/openai/", + api_key="your-gemini-key", # AIza...로 시작해야 합니다. + ) + agent = Agent(llm=llm, ...) + ``` + + + + +## Ollama와 함께 로컬 모델 사용하기 + +Ollama에서 제공하는 로컬 모델의 경우: + + + + [여기를 클릭하여 Ollama를 다운로드 및 설치하세요](https://ollama.com/download) + + + 예를 들어, `ollama pull llama3.2`를 실행하여 모델을 다운로드합니다. + + + + ```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") + ) + ``` + + + + +## 기본 API URL 변경하기 + +어떤 LLM provider든 `base_url` 파라미터를 설정하여 기본 API 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, ...) +``` + +이 기능은 OpenAI 호환 API를 사용할 때나 선택한 provider에 대해 다른 endpoint를 지정해야 할 때 특히 유용합니다. + +## 결론 + +LiteLLM을 활용함으로써 CrewAI는 다양한 LLM과의 원활한 통합을 제공합니다. 이러한 유연성 덕분에 성능, 비용 효율성 또는 로컬 배포 등 귀하의 특정 요구 사항에 가장 적합한 모델을 선택할 수 있습니다. 지원되는 모델과 구성 옵션에 대한 최신 정보는 반드시 [LiteLLM 문서](https://docs.litellm.ai/docs/)를 참고하시기 바랍니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/llm-hooks.mdx b/docs/v1.15.1/ko/learn/llm-hooks.mdx new file mode 100644 index 000000000..92a4e3cea --- /dev/null +++ b/docs/v1.15.1/ko/learn/llm-hooks.mdx @@ -0,0 +1,412 @@ +--- +title: LLM 호출 훅 +description: CrewAI에서 언어 모델 상호작용을 가로채고, 수정하고, 제어하는 LLM 호출 훅 사용 방법 배우기 +mode: "wide" +--- + +LLM 호출 훅(LLM Call Hooks)은 에이전트 실행 중 언어 모델 상호작용에 대한 세밀한 제어를 제공합니다. 이러한 훅을 사용하면 LLM 호출을 가로채고, 프롬프트를 수정하고, 응답을 변환하고, 승인 게이트를 구현하고, 사용자 정의 로깅 또는 모니터링을 추가할 수 있습니다. + +## 개요 + +LLM 훅은 두 가지 중요한 시점에 실행됩니다: +- **LLM 호출 전**: 메시지 수정, 입력 검증 또는 실행 차단 +- **LLM 호출 후**: 응답 변환, 출력 정제 또는 대화 기록 수정 + +## 훅 타입 + +### LLM 호출 전 훅 + +모든 LLM 호출 전에 실행되며, 다음을 수행할 수 있습니다: +- LLM에 전송되는 메시지 검사 및 수정 +- 조건에 따라 LLM 실행 차단 +- 속도 제한 또는 승인 게이트 구현 +- 컨텍스트 또는 시스템 메시지 추가 +- 요청 세부사항 로깅 + +**시그니처:** +```python +def before_hook(context: LLMCallHookContext) -> bool | None: + # 실행을 차단하려면 False 반환 + # 실행을 허용하려면 True 또는 None 반환 + ... +``` + +### LLM 호출 후 훅 + +모든 LLM 호출 후에 실행되며, 다음을 수행할 수 있습니다: +- LLM 응답 수정 또는 정제 +- 메타데이터 또는 서식 추가 +- 응답 세부사항 로깅 +- 대화 기록 업데이트 +- 콘텐츠 필터링 구현 + +**시그니처:** +```python +def after_hook(context: LLMCallHookContext) -> str | None: + # 수정된 응답 문자열 반환 + # 원본 응답을 유지하려면 None 반환 + ... +``` + +## LLM 훅 컨텍스트 + +`LLMCallHookContext` 객체는 실행 상태에 대한 포괄적인 액세스를 제공합니다: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # 전체 실행자 참조 + messages: list # 변경 가능한 메시지 목록 + agent: Agent # 현재 에이전트 + task: Task # 현재 작업 + crew: Crew # 크루 인스턴스 + llm: BaseLLM # LLM 인스턴스 + iterations: int # 현재 반복 횟수 + response: str | None # LLM 응답 (후 훅용) +``` + +### 메시지 수정 + +**중요:** 항상 메시지를 제자리에서 수정하세요: + +```python +# ✅ 올바름 - 제자리에서 수정 +def add_context(context: LLMCallHookContext) -> None: + context.messages.append({"role": "system", "content": "간결하게 작성하세요"}) + +# ❌ 잘못됨 - 리스트 참조를 교체 +def wrong_approach(context: LLMCallHookContext) -> None: + context.messages = [{"role": "system", "content": "간결하게 작성하세요"}] +``` + +## 등록 방법 + +### 1. 데코레이터 기반 등록 (권장) + +더 깔끔한 구문을 위해 데코레이터를 사용합니다: + +```python +from crewai.hooks import before_llm_call, after_llm_call + +@before_llm_call +def validate_iteration_count(context): + """반복 횟수를 검증합니다.""" + if context.iterations > 10: + print("⚠️ 최대 반복 횟수 초과") + return False # 실행 차단 + return None + +@after_llm_call +def sanitize_response(context): + """민감한 데이터를 제거합니다.""" + if context.response and "API_KEY" in context.response: + return context.response.replace("API_KEY", "[수정됨]") + return None +``` + +### 2. 크루 범위 훅 + +특정 크루 인스턴스에 대한 훅을 등록합니다: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_llm_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # 이 크루에만 적용됩니다 + if context.iterations == 0: + print(f"작업 시작: {context.task.description}") + return None + + @after_llm_call_crew + def log_responses(self, context): + # 크루별 응답 로깅 + print(f"응답 길이: {len(context.response)}") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## 일반적인 사용 사례 + +### 1. 반복 제한 + +```python +@before_llm_call +def limit_iterations(context: LLMCallHookContext) -> bool | None: + """무한 루프를 방지하기 위해 반복을 제한합니다.""" + max_iterations = 15 + if context.iterations > max_iterations: + print(f"⛔ 차단됨: {max_iterations}회 반복 초과") + return False # 실행 차단 + return None +``` + +### 2. 사람의 승인 게이트 + +```python +@before_llm_call +def require_approval(context: LLMCallHookContext) -> bool | None: + """특정 반복 후 승인을 요구합니다.""" + if context.iterations > 5: + response = context.request_human_input( + prompt=f"반복 {context.iterations}: LLM 호출을 승인하시겠습니까?", + default_message="승인하려면 Enter를 누르고, 차단하려면 'no'를 입력하세요:" + ) + if response.lower() == "no": + print("🚫 사용자에 의해 LLM 호출이 차단되었습니다") + return False + return None +``` + +### 3. 시스템 컨텍스트 추가 + +```python +@before_llm_call +def add_guardrails(context: LLMCallHookContext) -> None: + """모든 LLM 호출에 안전 가이드라인을 추가합니다.""" + context.messages.append({ + "role": "system", + "content": "응답이 사실에 기반하고 가능한 경우 출처를 인용하도록 하세요." + }) + return None +``` + +### 4. 응답 정제 + +```python +@after_llm_call +def sanitize_sensitive_data(context: LLMCallHookContext) -> str | None: + """민감한 데이터 패턴을 제거합니다.""" + if not context.response: + return None + + import re + sanitized = context.response + sanitized = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[주민번호-수정됨]', sanitized) + sanitized = re.sub(r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', '[카드번호-수정됨]', sanitized) + + return sanitized +``` + +### 5. 비용 추적 + +```python +import tiktoken + +@before_llm_call +def track_token_usage(context: LLMCallHookContext) -> None: + """입력 토큰을 추적합니다.""" + encoding = tiktoken.get_encoding("cl100k_base") + total_tokens = sum( + len(encoding.encode(msg.get("content", ""))) + for msg in context.messages + ) + print(f"📊 입력 토큰: ~{total_tokens}") + return None + +@after_llm_call +def track_response_tokens(context: LLMCallHookContext) -> None: + """응답 토큰을 추적합니다.""" + if context.response: + encoding = tiktoken.get_encoding("cl100k_base") + tokens = len(encoding.encode(context.response)) + print(f"📊 응답 토큰: ~{tokens}") + return None +``` + +### 6. 디버그 로깅 + +```python +@before_llm_call +def debug_request(context: LLMCallHookContext) -> None: + """LLM 요청을 디버그합니다.""" + print(f""" + 🔍 LLM 호출 디버그: + - 에이전트: {context.agent.role} + - 작업: {context.task.description[:50]}... + - 반복: {context.iterations} + - 메시지 수: {len(context.messages)} + - 마지막 메시지: {context.messages[-1] if context.messages else 'None'} + """) + return None + +@after_llm_call +def debug_response(context: LLMCallHookContext) -> None: + """LLM 응답을 디버그합니다.""" + if context.response: + print(f"✅ 응답 미리보기: {context.response[:100]}...") + return None +``` + +## 훅 관리 + +### 훅 등록 해제 + +```python +from crewai.hooks import ( + unregister_before_llm_call_hook, + unregister_after_llm_call_hook +) + +# 특정 훅 등록 해제 +def my_hook(context): + ... + +register_before_llm_call_hook(my_hook) +# 나중에... +unregister_before_llm_call_hook(my_hook) # 찾으면 True 반환 +``` + +### 훅 지우기 + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_all_llm_call_hooks +) + +# 특정 훅 타입 지우기 +count = clear_before_llm_call_hooks() +print(f"{count}개의 전(before) 훅이 지워졌습니다") + +# 모든 LLM 훅 지우기 +before_count, after_count = clear_all_llm_call_hooks() +print(f"{before_count}개의 전(before) 훅과 {after_count}개의 후(after) 훅이 지워졌습니다") +``` + +## 고급 패턴 + +### 조건부 훅 실행 + +```python +@before_llm_call +def conditional_blocking(context: LLMCallHookContext) -> bool | None: + """특정 조건에서만 차단합니다.""" + # 특정 에이전트에 대해서만 차단 + if context.agent.role == "researcher" and context.iterations > 10: + return False + + # 특정 작업에 대해서만 차단 + if "민감한" in context.task.description.lower() and context.iterations > 5: + return False + + return None +``` + +### 컨텍스트 인식 수정 + +```python +@before_llm_call +def adaptive_prompting(context: LLMCallHookContext) -> None: + """반복에 따라 다른 컨텍스트를 추가합니다.""" + if context.iterations == 0: + context.messages.append({ + "role": "system", + "content": "높은 수준의 개요부터 시작하세요." + }) + elif context.iterations > 3: + context.messages.append({ + "role": "system", + "content": "구체적인 세부사항에 집중하고 예제를 제공하세요." + }) + return None +``` + +### 훅 체이닝 + +```python +# 여러 훅은 등록 순서대로 실행됩니다 + +@before_llm_call +def first_hook(context): + print("1. 첫 번째 훅 실행됨") + return None + +@before_llm_call +def second_hook(context): + print("2. 두 번째 훅 실행됨") + return None + +@before_llm_call +def blocking_hook(context): + if context.iterations > 10: + print("3. 차단 훅 - 실행 중지") + return False # 후속 훅은 실행되지 않습니다 + print("3. 차단 훅 - 실행 허용") + return None +``` + +## 모범 사례 + +1. **훅을 집중적으로 유지**: 각 훅은 단일 책임을 가져야 합니다 +2. **무거운 계산 피하기**: 훅은 모든 LLM 호출마다 실행됩니다 +3. **오류를 우아하게 처리**: try-except를 사용하여 훅 실패로 인한 실행 중단 방지 +4. **타입 힌트 사용**: 더 나은 IDE 지원을 위해 `LLMCallHookContext` 활용 +5. **훅 동작 문서화**: 특히 차단 조건에 대해 +6. **훅을 독립적으로 테스트**: 프로덕션에서 사용하기 전에 단위 테스트 +7. **테스트에서 훅 지우기**: 테스트 실행 간 `clear_all_llm_call_hooks()` 사용 +8. **제자리에서 수정**: 항상 `context.messages`를 제자리에서 수정하고 교체하지 마세요 + +## 오류 처리 + +```python +@before_llm_call +def safe_hook(context: LLMCallHookContext) -> bool | None: + try: + # 훅 로직 + if some_condition: + return False + except Exception as e: + print(f"⚠️ 훅 오류: {e}") + # 결정: 오류 발생 시 허용 또는 차단 + return None # 오류에도 불구하고 실행 허용 +``` + +## 타입 안전성 + +```python +from crewai.hooks import LLMCallHookContext, BeforeLLMCallHookType, AfterLLMCallHookType + +# 명시적 타입 주석 +def my_before_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_after_hook(context: LLMCallHookContext) -> str | None: + return None + +# 타입 안전 등록 +register_before_llm_call_hook(my_before_hook) +register_after_llm_call_hook(my_after_hook) +``` + +## 문제 해결 + +### 훅이 실행되지 않음 +- 크루 실행 전에 훅이 등록되었는지 확인 +- 이전 훅이 `False`를 반환했는지 확인 (후속 훅 차단) +- 훅 시그니처가 예상 타입과 일치하는지 확인 + +### 메시지 수정이 지속되지 않음 +- 제자리 수정 사용: `context.messages.append()` +- 리스트를 교체하지 마세요: `context.messages = []` + +### 응답 수정이 작동하지 않음 +- 후 훅에서 수정된 문자열을 반환 +- `None`을 반환하면 원본 응답이 유지됩니다 + +## 결론 + +LLM 호출 훅은 CrewAI에서 언어 모델 상호작용을 제어하고 모니터링하는 강력한 기능을 제공합니다. 이를 사용하여 안전 가드레일, 승인 게이트, 로깅, 비용 추적 및 응답 정제를 구현하세요. 적절한 오류 처리 및 타입 안전성과 결합하면, 훅을 통해 강력하고 프로덕션 준비가 된 에이전트 시스템을 구축할 수 있습니다. + diff --git a/docs/v1.15.1/ko/learn/llm-selection-guide.mdx b/docs/v1.15.1/ko/learn/llm-selection-guide.mdx new file mode 100644 index 000000000..a67c3ba00 --- /dev/null +++ b/docs/v1.15.1/ko/learn/llm-selection-guide.mdx @@ -0,0 +1,815 @@ +--- +title: "전략적 LLM 선택 가이드" +description: "CrewAI AI 에이전트를 위한 적합한 LLM 선택 및 효과적인 작업과 에이전트 정의 작성에 대한 전략적 프레임워크" +icon: "brain-circuit" +mode: "wide" +--- + +## CrewAI의 LLM 선택 접근 방식 + +처방적인 모델 추천보다는, **사고 프레임워크**를 제안하여 특정 사용 사례, 제약 조건, 요구 사항에 따라 정보에 입각한 결정을 내릴 수 있도록 돕고자 합니다. LLM 환경은 빠르게 변화하고 있으며, 새로운 모델이 정기적으로 등장하고 기존 모델도 자주 업데이트되고 있습니다. 가장 중요한 것은 어떤 특정 모델이 제공되는지와 상관없이 평가를 위한 체계적인 접근법을 개발하는 것입니다. + + + 이 가이드는 LLM 환경이 빠르게 변화하고 있기 때문에 특정 모델 추천보다는 전략적 + 사고에 초점을 맞추고 있습니다. + + +## 빠른 결정 프레임워크 + + + + 먼저, 작업이 실제로 무엇을 요구하는지 깊이 이해하세요. 필요한 인지 복잡성, + 요구되는 추론의 깊이, 기대되는 출력 형식, 모델이 처리해야 할 맥락의 양을 + 고려합니다. 이러한 기본 분석이 이후의 모든 결정을 안내할 것입니다. + + + 요구 사항을 이해한 후, 이를 모델의 강점에 매핑하세요. 서로 다른 모델 계열은 + 작업 유형에 따라 특화되어 있습니다. 일부는 추론 및 분석에 최적화되어 있고, + 일부는 창의성이나 콘텐츠 생성, 또 다른 일부는 속도와 효율성에 최적화되어 + 있습니다. + + + 예산 제한, 지연 시간 요구사항, 데이터 프라이버시 필요성, 인프라 역량 등 실제 + 운영상의 제약 조건을 반영하세요. 이론적으로 가장 좋은 모델이 실제로는 최선의 + 선택이 아닐 수 있습니다. + + + 신뢰할 수 있고 잘 이해된 모델로 시작하여, 특정 사용 사례에서 실제 성능을 + 바탕으로 최적화하세요. 실제 결과는 이론적 벤치마크와 다를 수 있으므로, + 경험적 테스트가 매우 중요합니다. + + + +## 코어 선택 프레임워크 + +### a. Task-First Thinking + +LLM을 선택할 때 가장 중요한 단계는 실제로 여러분의 작업이 무엇을 요구하는지 이해하는 것입니다. 너무 자주 팀들은 특정 요구 사항을 면밀하게 분석하지 않고, 일반적인 평판이나 벤치마크 점수를 기반으로 모델을 선택합니다. 이런 접근 방식은 단순한 작업에 비싸고 복잡한 모델을 과도하게 적용하거나, 정교한 업무에 필요한 기능이 부족한 모델을 선택하게 만들어 결과적으로 과소 성능 문제를 야기합니다. + + + + - **Simple Tasks**는 대부분의 일상적인 AI 작업을 대표하며, 기본 명령 수행, 간단한 데이터 처리, 단순한 포맷팅 작업 등을 포함합니다. 이러한 작업은 일반적으로 명확한 입력과 출력을 가지고 있으며 모호성이 거의 없습니다. 인지적 부하는 낮고, 모델은 복잡한 추론보다는 명확한 지시에 따라 움직이면 됩니다. + + - **Complex Tasks**는 다단계 추론, 전략적 사고, 모호하거나 불완전한 정보를 처리하는 능력을 필요로 합니다. 여러 데이터 소스를 분석하거나, 포괄적 전략을 개발하거나, 더 작은 구성 요소로 분해해야 하는 문제 해결 작업 등이 이에 해당합니다. 모델은 여러 추론 단계를 거치는 동안 맥락을 유지해야 하며, 명시적으로 언급되지 않은 내용을 추론해야 할 때가 많습니다. + + - **Creative Tasks**는 새롭고, 흥미로우며, 맥락에 적합한 콘텐츠를 생성하는 데 중점을 둔 새로운 인지적 능력을 요구합니다. 여기에는 스토리텔링, 마케팅 카피 작성, 창의적 문제 해결이 포함됩니다. 모델은 뉘앙스, 톤, 대상 청중을 이해하고, 공식적이지 않고 진정성 있고 흥미로운 콘텐츠를 제작해야 합니다. + + + + + - **Structured Data** 작업은 포맷 규칙 준수의 정확성과 일관성을 요구합니다. JSON, XML, 데이터베이스 포맷 등을 다루는 경우, 모델은 구문적으로 올바른 출력을 안정적으로 생성할 수 있어야 하며, 이는 프로그램적으로 처리 가능해야 합니다. 이런 작업에는 엄격한 검증 요구 사항이 있으며 포맷 에러에 대한 허용 오차가 매우 적기 때문에, 창의성보다는 신뢰성이 더 중요합니다. + + - **Creative Content** 출력은 기술적 역량과 창의적 감각의 균형을 필요로 합니다. 모델은 대상 청중, 톤, 브랜드 보이스를 이해하고, 독자의 관심을 끌며 특정 커뮤니케이션 목표를 달성하는 콘텐츠를 제작할 수 있어야 합니다. 이 영역의 품질은 주관적인 경우가 많으며, 다양한 맥락과 목적에 맞게 글쓰기 스타일을 조정할 수 있는 모델이 필요합니다. + + - **Technical Content**는 구조화된 데이터와 창의적 콘텐츠의 중간에 위치하며, 정확성과 명확성을 모두 필요로 합니다. 문서화, 코드 생성, 기술 분석 등은 정밀하면서도 포괄적으로 작성되어야 하며, 대상이 되는 청중에게 효과적으로 전달되어야 합니다. 모델은 복잡한 기술 개념을 이해하고 이를 명확하게 설명할 수 있어야 합니다. + + + + + - **Short Context** 시나리오는 모델이 한정된 정보를 신속하게 처리해야 하는 즉각적이고 집중된 업무를 포함합니다. 이는 대체로 속도와 효율성이 심도 있는 이해보다 더 중요한 거래성 상호작용에서 주로 발생합니다. 모델은 긴 대화 내역이나 대용량 문서를 유지할 필요가 없습니다. + + - **Long Context** 요구 사항은 방대한 문서 작업, 장기간 대화, 복잡한 다중 파트 작업을 처리할 때 발생합니다. 모델은 수천 토큰에 걸쳐 일관성을 유지해야 하며, 앞선 정보를 정확히 참조할 수 있어야 합니다. 이는 문서 분석, 포괄적 연구, 정교한 대화 시스템에 매우 중요한 기능입니다. + + - **Very Long Context** 시나리오는 현재 가능한 한계를 뛰어넘는 경우로, 대규모 문서 처리, 광범위한 연구 종합, 복잡한 다중 세션 상호작용 등이 있습니다. 이러한 활용 사례는 확장된 컨텍스트 처리를 위해 특별히 설계된 모델이 필요하며, 종종 컨텍스트 길이와 처리 속도 간의 절충이 발생합니다. + + + + +### b. 모델 역량 매핑 + +모델 역량을 이해하기 위해서는 마케팅 주장이나 벤치마크 점수 너머를 바라보고, 다양한 모델 구조와 학습 접근법의 근본적인 강점과 한계를 파악해야 합니다. + + + + Reasoning 모델은 복잡하고 다단계의 사고가 필요한 작업을 위해 특별히 설계된 특수 카테고리를 나타냅니다. 이러한 모델은 문제를 신중하게 분석하거나 전략적으로 계획을 세우거나 체계적으로 문제를 분해해야 하는 경우에 뛰어납니다. 일반적으로 chain-of-thought reasoning 혹은 tree-of-thought processing과 같은 기법을 사용하여 복잡한 문제를 단계별로 해결합니다. + + Reasoning 모델의 강점은 확장된 reasoning 체인에서 논리적 일관성을 유지하고, 복잡한 문제를 관리 가능한 구성 요소로 나눌 수 있다는 점에 있습니다. 전략적 계획, 복잡한 분석, 그리고 응답 속도보다 reasoning의 질이 더 중요한 상황에서 특히 가치가 있습니다. + + 하지만 reasoning 모델은 속도와 비용 면에서 트레이드오프가 따르는 경우가 많습니다. 또한 그들의 고도화된 reasoning 역량이 필요 없는 창의적인 작업이나 간단한 작업에는 덜 적합할 수 있습니다. 체계적이고 단계적인 분석이 요구되는 진정한 복잡성이 관련된 작업에서 이러한 모델을 고려하십시오. + + + + + General purpose 모델은 LLM 선택에서 가장 균형 잡힌 접근 방식을 제공하며, 특정 영역에 극단적으로 특화되지 않으면서도 다양한 작업에 대해 견고한 성능을 제공합니다. 이러한 모델은 다양한 데이터셋으로 학습되었으며, 특정 도메인에서의 최고 성능보다는 다재다능함에 최적화되어 있습니다. + + General purpose 모델의 주요 장점은 다양한 유형의 작업에서 예측 가능한 신뢰성과 일관성입니다. 조사, 분석, 콘텐츠 제작, 데이터 처리 등 대부분의 표준 비즈니스 작업을 충분히 처리할 수 있습니다. 이로 인해 다양한 워크플로우 전반에서 일관된 성능이 필요한 팀에 매우 적합한 선택이 됩니다. + + General purpose 모델은 특정 도메인에서 특화된 대안들이 보여주는 최고 성능에는 미치지 않을 수 있지만, 운영의 단순성과 모델 관리의 복잡성 감소라는 이점이 있습니다. 신규 프로젝트의 시작점으로 가장 좋은 선택인 경우가 많으며, 팀이 구체적인 필요를 이해하고 나서 특화 모델로 최적화할 수 있습니다. + + + + + Fast and efficient 모델은 고도화된 reasoning 역량보다 속도, 비용 효율, 리소스 효율성을 우선순위에 둡니다. 이러한 모델은 빠른 응답성과 낮은 운영비용이 중요하고, 미묘한 이해나 복잡한 reasoning이 덜 요구되는 고처리량 시나리오에 최적화되어 있습니다. + + 이러한 모델은 일상적인 운영, 간단한 데이터 처리, 함수 호출, 대용량 작업 등 인지적 요구가 비교적 단순한 시나리오에서 뛰어납니다. 많은 요청을 신속하게 처리해야 하거나 예산 제약 내에서 운영되어야 하는 애플리케이션에 특히 유용합니다. + + 효율적인 모델에서 가장 중요한 고려사항은 그들의 역량이 귀하의 작업 요구와 일치하는지 확인하는 것입니다. 많은 일상적 작업은 효과적으로 처리할 수 있지만, Nuanced한 이해, 복잡한 reasoning, 혹은 고도화된 콘텐츠 생성이 필요한 작업에는 어려움을 겪을 수 있습니다. 정교함보다 속도와 비용이 더 중요한 명확하고 일상적인 작업에 가장 적합합니다. + + + + + Creative 모델은 콘텐츠 생성, 글쓰기 품질, 창의적 사고가 요구되는 작업에 특별히 최적화되어 있습니다. 이러한 모델은 뉘앙스, 톤, 스타일을 이해하면서도 자연스럽고 진정성 있게 느껴지는 매력적이고 맥락에 맞는 콘텐츠를 생성하는 데 뛰어납니다. + + Creative 모델의 강점은 다양한 대상에 맞춰 글쓰기 스타일을 조정하고, 일관된 목소리와 톤을 유지하며, 독자를 효과적으로 사로잡는 콘텐츠를 생성할 수 있다는 점입니다. 스토리텔링, 마케팅 카피, 브랜드 커뮤니케이션 등 창의성과 몰입이 주요 목적이 되는 콘텐츠 작업에서 더 우수한 성과를 보입니다. + + Creative 모델을 선택할 때는 단순한 텍스트 생성 능력뿐 아니라, 대상, 맥락, 목적에 대한 이해력도 함께 고려해야 합니다. 최상의 creative 모델은 특정 브랜드 목소리에 맞게 출력 내용을 조정하고, 다양한 대상 그룹을 타깃팅하며, 긴 콘텐츠에서도 일관성을 유지할 수 있습니다. + + + + + Open source 모델은 비용 통제, 맞춤화 가능성, 데이터 프라이버시, 배포 유연성 측면에서 독특한 이점을 제공합니다. 이러한 모델은 로컬이나 사설 인프라에서 운용이 가능하여 데이터 처리 및 모델 동작에 대해 완전한 통제권을 제공합니다. + + Open source 모델의 주요 이점으로는 토큰당 비용의 제거, 특정 용도에 맞춘 파인튜닝 가능성, 완전한 데이터 프라이버시, 외부 API 제공자에 대한 의존성 해소가 있습니다. 특히 엄격한 데이터 프라이버시 요구사항, 예산 제약, 특정 맞춤화 필요가 있는 조직에 매우 유용합니다. + + 그러나 open source 모델은 효과적으로 배포 및 유지관리하기 위해 더 많은 기술 전문성이 필요합니다. 팀에서는 인프라 비용, 모델 관리 복잡성, 지속적인 모델 업데이트 및 최적화를 위한 지속적인 노력을 고려해야 합니다. 기술적 오버헤드를 감안하면 전체 소유 비용이 클라우드 기반 대안보다 높을 수 있습니다. + + + + +## 전략적 구성 패턴 + +### a. 멀티-모델 접근 방식 + + + 동일 crew 내에서 다양한 목적에 맞는 서로 다른 모델을 사용해 성능과 비용을 모두 + 최적화할 수 있습니다. + + +가장 정교하게 구현된 CrewAI의 경우, 여러 개의 모델을 전략적으로 활용하여 각 agent의 역할과 요구 사항에 맞는 모델을 지정합니다. 이 접근 방식은 각 작업 유형에 가장 적합한 모델을 사용함으로써 성능과 비용을 모두 최적화할 수 있게 해줍니다. + +planning agent는 복잡한 전략적 사고와 다단계 분석을 처리할 수 있는 reasoning 모델을 활용할 때 이점을 얻습니다. 이 agent들은 운영의 “두뇌” 역할을 하며, 전략 수립과 다른 agent들의 작업을 조정합니다. 반면 content agent는 글의 품질과 독자 참여에 뛰어난 creative 모델을 통해 최고의 성능을 발휘합니다. 일상적인 작업과 운영을 담당하는 processing agent는 속도와 비용 효율을 우선시하는 효율적인 모델을 사용할 수 있습니다. + +**예시: Research and Analysis Crew** + +```python +from crewai import Agent, Task, Crew, LLM + +# High-capability reasoning model for strategic planning +manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1) + +# Creative model for content generation +content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7) + +# Efficient model for data processing +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, # High-capability model for complex reasoning + 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, # Creative model for engaging content + 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, # Fast, cost-effective model for routine tasks + verbose=True +) + +crew = Crew( + agents=[research_manager, content_writer, data_processor], + tasks=[...], # Your specific tasks + manager_llm=manager_llm, # Manager uses the reasoning model + verbose=True +) +``` + +성공적인 멀티-모델 구현의 핵심은 서로 다른 agent들이 어떻게 상호작용하는지를 이해하고, 모델의 역량이 agent의 책임에 부합하는지 확인하는 것입니다. 이를 위해 신중한 기획이 필요하지만, 그 결과로 산출물의 품질과 운영 효율성 모두에서 큰 개선을 이끌어낼 수 있습니다. + +### b. 구성요소별 선택 + + + + Manager LLM은 계층적 CrewAI 프로세스에서 중요한 역할을 하며, 여러 에이전트와 작업을 조정하는 중심점으로 작동합니다. 이 모델은 위임, 작업 우선순위 지정, 여러 동시 작업 간의 컨텍스트 유지에 뛰어나야 합니다. + + 효과적인 Manager LLM은 올바른 위임 결정을 내리기 위한 강력한 추론 능력, 예측 가능한 조정을 보장하는 일관된 성능, 여러 에이전트의 상태를 동시에 추적하기 위한 탁월한 컨텍스트 관리가 필요합니다. 이 모델은 다양한 에이전트의 역량과 한계를 이해하고, 효율성과 품질을 최적화하기 위해 작업 할당을 최적화해야 합니다. + + Manager LLM은 모든 작업에 관여하기 때문에 비용 고려가 특히 중요합니다. 모델은 효과적인 조정을 위한 충분한 역량을 제공하면서도, 잦은 사용에도 비용 효율적이어야 합니다. 이는 종종 가장 정교한 모델의 높은 가격 없이도 충분한 추론 능력을 제공하는 모델을 찾는 것을 의미합니다. + + + + + Function calling LLM은 모든 에이전트 간 도구 사용을 처리하므로, 외부 도구와 API에 크게 의존하는 crew에서 매우 중요합니다. 이 모델은 도구의 역량을 이해하고, 파라미터를 정확하게 추출하며, 도구 응답을 효과적으로 처리하는 데 특화되어야 합니다. + + Function calling LLM에서 가장 중요한 특성은 창의성이나 정교한 추론력보다는 정확성과 신뢰성입니다. 모델은 자연어 요청에서 올바른 파라미터를 일관되게 추출하고, 도구 응답을 적절히 처리해야 합니다. 도구 사용은 여러 번의 왕복 작업이 수반될 수 있으므로 속도도 중요합니다. + + 많은 팀들은, 창의적이거나 추론에 특화된 모델보다는, 특화된 function calling 모델이나 도구 지원이 강력한 범용 모델이 이 역할에 더 적합하다는 것을 발견합니다. 핵심은 모델이 자연어 지침과 구조화된 도구 호출 간의 간극을 신뢰성 있게 연결할 수 있도록 하는 것입니다. + + + + + 개별 에이전트는 특정 요구가 일반적인 crew 요구와 크게 다를 때, crew 단위 LLM 설정을 재정의할 수 있습니다. 이 기능을 통해 대부분의 에이전트에는 운영 단순성을 유지하면서, 미세한 최적화가 가능합니다. + + 에이전트별 재정의를 고려해야 하는 경우는 에이전트의 역할이 다른 crew 구성원과 본질적으로 다른 역량을 요구할 때입니다. 예를 들어, 창의적 글쓰기에 특화된 에이전트는 콘텐츠 생성에 최적화된 모델이 도움이 될 수 있고, 데이터 분석 에이전트는 추론에 중점을 둔 모델로 더 나은 성과를 거둘 수 있습니다. + + 에이전트별 재정의를 적용할 때의 과제는 최적화와 운영 복잡도 간의 균형을 유지하는 것입니다. 모델이 하나 추가될 때마다 배포, 모니터링, 비용 관리의 복잡성이 늘어납니다. 따라서 팀은 성능 향상 효과가 추가 복잡성을 정당화할 수 있는 에이전트에만 재정의를 집중해야 합니다. + + + + +## 작업 정의 프레임워크 + +### a. 복잡성보다 명확성에 집중하기 + +CrewAI 출력의 품질을 결정하는 데 있어 모델 선택보다 효과적인 작업 정의가 더 중요한 경우가 많습니다. 잘 정의된 작업은 명확한 방향과 맥락을 제공하여 심지어 보통 수준의 모델도 좋은 성능을 낼 수 있게 해주지만, 잘못 정의된 작업은 고도화된 모델조차 만족스럽지 않은 결과를 만들 수 있습니다. + + + + 최고의 작업 설명은 적절한 세부 정보 제공과 명확성 유지를 균형 있게 조화시킵니다. 작업의 구체적인 목표를 성공이 어떤 모습인지에 대한 모호함 없이 명확하게 정의해야 하며, 접근 방식이나 방법론을 충분히 설명하여 에이전트가 어떻게 진행해야 하는지 이해할 수 있도록 해야 합니다. + + 효과적인 작업 설명은 에이전트가 더 넓은 목적과 그들이 반드시 지켜야 할 제한사항을 이해할 수 있도록 관련 맥락 및 제약 조건을 포함합니다. 복잡한 작업을 체계적으로 실행할 수 있는 집중된 단계로 분할하여, 여러 측면이 뒤섞이고 접근하기 어려운 압도적인 목표로 제시하지 않습니다. + + 일반적인 실수로는 목표가 너무 모호하다거나, 필요한 맥락을 제공하지 않는다거나, 성공 기준이 불분명하다거나, 관련 없는 여러 작업을 하나의 설명으로 결합하는 경우가 있습니다. 목표는 단일의 명확한 목적에 집중하며, 에이전트가 성공할 수 있을 정도로 충분한 정보를 제공하는 것입니다. + + + + + 예상 산출물 가이드라인은 작업 정의와 에이전트 간의 계약 역할을 하며, 산출물이 어떤 모습이어야 하며 어떻게 평가될 것인지 명확하게 지정합니다. 이러한 가이드라인은 필요한 형식과 구조뿐만 아니라 산출물이 완전하다고 간주되기 위해 반드시 포함되어야 하는 핵심 요소도 설명해야 합니다. + + 최고의 산출물 가이드라인은 품질 지표에 대한 구체적인 예시를 제공하고, 완료 기준을 에이전트와 인간 평가자 모두가 작업의 성공적 완료 여부를 평가할 수 있을 만큼 명확하게 정의합니다. 이는 모호함을 줄이고 여러 작업 실행 간 일관된 결과를 보장하는 데 도움이 됩니다. + + 어떤 작업에나 적용할 수 있을 정도로 일반적인 산출물 설명, 에이전트가 구조를 추측해야 하는 형식 명세 누락, 평가가 어려운 불분명한 품질 기준, 에이전트가 기대치를 이해하도록 도와주는 예시 또는 템플릿 미제공 등은 피해야 합니다. + + + + +### b. 작업 순서 지정 전략 + + + + 작업이 이전 산출물에 기반을 두거나, 정보가 한 작업에서 다른 작업으로 흐르거나, 품질이 선행 작업의 완료에 의존할 때 순차적 작업 의존성이 필수적입니다. 이 접근 방식은 각 작업이 성공적으로 수행되는 데 필요한 정보와 맥락에 접근할 수 있도록 보장합니다. + + 순차적 의존성을 효과적으로 구현하기 위해서는 context 파라미터를 사용하여 관련 작업을 연쇄시키고, 작업의 진행을 통해 점진적으로 복잡성을 구축하며, 각 작업이 다음 작업에 의미 있는 입력값이 될 수 있는 산출물을 생성하도록 해야 합니다. 목표는 의존된 작업 간의 논리적 흐름을 유지하면서 불필요한 병목을 피하는 것입니다. + + 순차적 의존성은 한 작업에서 다른 작업으로 명확한 논리적 진행이 있고, 한 작업의 산출물이 다음 작업의 품질이나 실행 가능성을 실제로 향상시킬 때 가장 효과적입니다. 그러나 적절히 관리되지 않을 경우 병목 현상이 발생할 수 있으니, 반드시 진정으로 필요한 의존성과 단순히 편의상 설정된 의존성을 구분해야 합니다. + + + + + 병렬 실행은 작업 간에 상호 독립적이거나, 시간 효율성이 중요하거나, 서로 다른 전문 분야가 협업 없이 각자의 역량을 발휘할 수 있을 때 가치가 있습니다. 이 방식은 전체 실행 시간을 크게 줄일 수 있으며, 각 전문 에이전트가 자신의 강점을 동시에 발휘할 수 있습니다. + + 성공적인 병렬 실행을 위해서는 실제로 독립적으로 수행이 가능한 작업을 식별하고, 관련되지만 분리된 작업 스트림을 효과적으로 그룹화하며, 병렬로 진행된 작업을 최종 결과물로 통합해야 할 때 결과 통합을 계획해야 합니다. 핵심은 병렬 작업이 전체 품질을 저하하는 충돌이나 중복을 만들지 않도록 하는 것입니다. + + 여러 개의 독립적인 연구 스트림이나 서로 의존하지 않는 다양한 분석, 동시에 개발이 가능한 콘텐츠 생성 작업이 있을 때 병렬 실행을 고려하십시오. 다만, 자원 할당에 주의하고, 병렬 실행이 모델의 가용 용량이나 예산을 초과하지 않도록 해야 합니다. + + + + +## LLM 성능을 위한 에이전트 구성 최적화 + +### a. 역할 기반 LLM 선택 + + + 일반적인 에이전트 역할은 올바른 LLM을 선택할 수 없게 만듭니다. 구체적인 역할은 + 목표에 맞춘 모델 최적화를 가능하게 합니다. + + +에이전트 역할의 구체성은 최적의 성능을 위해 어떤 LLM의 능력이 가장 중요한지를 직접적으로 결정합니다. 이는 에이전트의 책임에 정확히 맞는 모델 강점을 연결할 수 있는 전략적 기회를 만듭니다. + +**일반 역할 vs. 구체적 역할이 LLM 선택에 미치는 영향:** + +역할을 정의할 때 에이전트가 다룰 작업에 가장 가치 있는 특정 도메인 지식, 작업 방식, 의사결정 프레임워크를 고려하세요. 역할 정의가 더 구체적이고 상황에 맞을수록 모델이 그 역할을 효과적으로 구현할 수 있습니다. + +```python +# ✅ 특정 역할 - 명확한 LLM 요구 +specific_agent = Agent( + role="SaaS Revenue Operations Analyst", # 명확한 도메인 전문성 필요 + 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") # 복잡한 분석에 적합한 reasoning 모델 +) +``` + +**역할-모델 매핑 전략:** + +- **"Research Analyst"** → 복잡한 분석을 위한 reasoning 모델 (GPT-4o, Claude Sonnet) +- **"Content Editor"** → 작문 품질을 위한 creative 모델 (Claude, GPT-4o) +- **"Data Processor"** → 구조화된 태스크를 위한 효율적인 모델 (GPT-4o-mini, Gemini Flash) +- **"API Coordinator"** → 도구 사용을 위한 function-calling 최적화 모델 (GPT-4o, Claude) + +### b. 모델 컨텍스트 증폭기로서의 백스토리 + + + 전략적으로 구성된 백스토리는 도메인 특화 컨텍스트를 제공하여 일반적인 + 프롬프트로는 달성할 수 없는 수준으로 선택한 LLM의 효율성을 획기적으로 + 높여줍니다. + + +잘 설계된 백스토리는 LLM을 단순한 범용 모델에서 전문적인 전문가로 탈바꿈시켜 줍니다. 이는 비용 최적화 관점에서 특히 중요합니다. 효율적인 모델이라도 컨텍스트가 잘 구축되면, 적절한 컨텍스트 없이 고가의 모델보다 더 뛰어난 성능을 발휘할 수 있습니다. + +**컨텍스트 기반 퍼포먼스 예시:** + +```python +# Context amplifies model effectiveness +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) # Balanced creativity with domain knowledge +) + +# This context enables Claude to perform like a domain expert +# Without it, even it would produce generic marketing advice +``` + +**LLM 성능을 높여주는 백스토리 요소:** + +- **도메인 경험**: "10년 이상의 엔터프라이즈 SaaS 영업 경력" +- **특정 전문성**: "시리즈 B+ 라운드의 기술 실사 전문" +- **업무 스타일**: "명확한 문서화와 데이터 기반 의사결정을 선호" +- **품질 기준**: "출처 인용과 분석 근거 제시를 중시" + +### c. 총체적 Agent-LLM 최적화 + +가장 효과적인 agent 구성은 역할 특이성, 백스토리 깊이, 그리고 LLM 선택 간의 시너지를 창출합니다. 각 요소는 서로를 강화하여 모델 성능을 극대화합니다. + +**최적화 프레임워크:** + +```python +# Example: Technical Documentation Agent +tech_writer = Agent( + role="API Documentation Specialist", # Specific role for clear LLM requirements + 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", # Excellent for technical writing + temperature=0.1 # Low temperature for accuracy + ), + tools=[code_analyzer_tool, api_scanner_tool], + verbose=True +) +``` + +**정렬 체크리스트:** + +- ✅ **역할 특이성**: 명확한 도메인과 책임 +- ✅ **LLM 적합도**: 모델의 강점이 역할 요구사항과 일치 +- ✅ **백스토리 깊이**: LLM이 활용할 수 있는 도메인 맥락 제공 +- ✅ **도구 통합**: 도구가 agent의 특수 기능을 지원 +- ✅ **파라미터 튜닝**: 온도 및 설정이 역할에 최적화 + +핵심은 모든 구성 선택이 LLM 선택 전략을 강화하여 성능을 극대화하면서 비용을 최적화하는 agent를 만드는 것입니다. + +## 실무 구현 체크리스트 + +전략적 프레임워크를 반복하는 대신, CrewAI에서 LLM 선택 결정을 실행하는 데 사용할 수 있는 전술적 체크리스트를 제공합니다: + + + + **검토할 사항:** + - 모든 agent가 기본적으로 동일한 LLM을 사용하고 있습니까? + - 어떤 agent가 가장 복잡한 reasoning 작업을 처리합니까? + - 어떤 agent가 주로 데이터 처리 또는 포매팅을 담당합니까? + - 도구에 크게 의존하는 agent가 있습니까? + + **Action**: 현재 agent 역할을 문서화하고 최적화 기회를 식별하세요. + + + + + **기본값 설정:** + ```python + # crew에 신뢰할 수 있는 기본값으로 시작합니다 + default_crew_llm = LLM(model="gpt-4o-mini") # 비용 효율적인 기준점 + + crew = Crew( + agents=[...], + tasks=[...], + memory=True + ) + ``` + + **Action**: 개별 agent 최적화 전에 crew의 기본 LLM을 설정하세요. + + + + + **핵심 agent 식별 및 업그레이드:** + ```python + # Manager 또는 coordination agent + manager_agent = Agent( + role="Project Manager", + llm=LLM(model="gemini-2.5-flash-preview-05-20"), # 조율을 위한 프리미엄 + # ... 나머지 설정 + ) + + # Creative 또는 고객 대응 agent + content_agent = Agent( + role="Content Creator", + llm=LLM(model="claude-3-5-sonnet"), # 글쓰기에 최적 + # ... 나머지 설정 + ) + ``` + + **Action**: 복잡도의 80%를 처리하는 agent 20%를 업그레이드하세요. + + + + + **agent를 프로덕션에 배포한 후:** + - [CrewAI AMP platform](https://app.crewai.com)을 활용하여 모델 선택을 A/B 테스트하세요 + - 실제 입력으로 여러 번 반복 테스트하여 일관성과 성능을 측정하세요 + - 최적화된 셋업 전반의 비용과 성능을 비교하세요 + - 팀과 결과를 공유하여 협업 의사결정을 지원하세요 + + **Action**: 테스트 플랫폼을 활용해 추측이 아닌 데이터 기반 검증을 실행하세요. + + + + +### 다양한 모델 유형을 사용할 시기 + + + + reasoning 모델은 진정한 다단계 논리적 사고, 전략적 계획 수립, 또는 체계적인 분석이 필요한 고수준의 의사결정이 요구되는 작업에서 필수적입니다. 이러한 모델은 문제를 구성 요소로 분해하고 체계적으로 분석해야 할 때, 단순한 패턴 매칭이나 지시 사항 이행만으로는 해결할 수 없는 경우에 뛰어난 성능을 발휘합니다. + + 예를 들어, 비즈니스 전략 개발, 여러 출처에서 인사이트를 도출해야 하는 복잡한 데이터 분석, 각 단계가 이전 분석을 기반으로 해야 하는 다단계 문제 해결, 다양한 변수 및 이들의 상호작용을 고려해야 하는 전략적 계획 수립 업무에 reasoning 모델을 고려해 보세요. + + 그러나 reasoning 모델은 일반적으로 더 높은 비용과 느린 응답 시간을 수반하므로, 복잡한 사고가 필요한 작업에서 실질적인 가치를 제공할 때에만 사용하는 것이 좋으며, 복잡한 reasoning이 필요하지 않은 단순한 작업에는 권장되지 않습니다. + + + + + creative 모델은 콘텐츠 생성이 주요 결과물이고 콘텐츠의 품질, 스타일, 참여도가 성공에 직접적으로 영향을 미칠 때 유용합니다. 이 모델들은 글의 질과 스타일이 매우 중요하거나, 창의적인 아이디어 창출 또는 브레인스토밍이 필요하거나, 브랜드의 목소리와 톤이 중요한 경우에 특히 뛰어납니다. + + creative 모델은 블로그 포스트 작성 및 기사 생성, 독자를 끌어들이고 설득해야 하는 마케팅 카피, 창의적인 스토리텔링 및 내러티브 개발, 목소리와 톤이 중요한 브랜드 커뮤니케이션 등에 적합합니다. 이 모델은 일반 목적 모델보다 뉘앙스와 맥락을 더 잘 이해할 수 있습니다. + + creative 모델은 정밀성과 사실적 정확성이 스타일이나 참여도보다 더 중요한 기술적 또는 분석적 작업에는 덜 적합할 수 있습니다. 결과물의 창의적·의사소통적 측면이 성공의 주요 요인일 때 사용하는 것이 가장 좋습니다. + + + + + efficient 모델은 빠른 속도와 비용 최적화가 우선순위인 고빈도, 반복 작업에 이상적입니다. 이러한 모델은 작업의 매개변수가 명확하고 잘 정의되어 있으며, 복잡한 reasoning이나 창의적인 능력이 필요하지 않을 때 가장 잘 작동합니다. + + efficient 모델은 데이터 처리 및 변환 작업, 단순한 서식 지정 및 정리 작업, 정밀성이 중요하고 복잡함보다는 정확성이 필요한 함수 호출 및 도구 사용, 1회 작업당 비용이 중대한 고볼륨 작업에 적합합니다. + + efficient 모델에서는 해당 모델의 역량이 작업 요구 사항과 일치하는지 확인하는 것이 핵심입니다. 다양한 반복 작업을 효과적으로 처리할 수 있지만, 뉘앙스 이해, 복잡한 reasoning, 고도화된 콘텐츠 생성이 필요한 작업에서는 한계가 있을 수 있습니다. + + + + + open source 모델은 예산 제약이 크거나, 데이터 프라이버시 요구 사항이 있거나, 맞춤화가 중요하거나, 운영·컴플라이언스 목적상 로컬 배포가 필요한 경우에 매력적인 선택이 됩니다. + + 예를 들어, 데이터 프라이버시가 최우선인 사내 도구, 외부 API를 사용할 수 없는 프라이버시 민감형 애플리케이션, 토큰 단위 가격이 부담스러운 비용 최적화 배포, 모델 수정 또는 파인튜닝이 필요한 상황에서 open source 모델을 고려해 보세요. + + 단, open source 모델은 효과적으로 배포하고 유지하기 위해 더 많은 기술 전문성이 요구됩니다. 인프라, 기술적 오버헤드, 지속적인 유지보수를 포함한 전체 소유 비용을 종합적으로 평가해야 합니다. + + + + +## CrewAI 모델 선택에서 흔히 발생하는 실수 + + + + **문제점**: 각 agent의 역할과 책임과 상관없이 모든 agent에 동일한 LLM을 사용하는 것. 대부분 기본적으로 선택되는 접근 방식이지만, 최적의 결과가 나오지 않는 경우가 많음. + + **실제 예시**: 전략 기획 매니저와 데이터 추출 agent 모두에게 GPT-4o를 사용하는 경우. 매니저는 높은 추론 성능이 필요해 프리미엄 모델이 적합하나, 데이터 추출 업무는 저렴한 GPT-4o-mini만으로도 충분한 성능을 낼 수 있음. + + **CrewAI 솔루션**: agent별 LLM 설정을 활용해, agent의 역할에 맞는 모델 역량을 매칭: + ```python + # 전략 agent는 프리미엄 모델 사용 + manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o")) + + # 처리 agent는 효율적인 모델 사용 + processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini")) + ``` + + + + + **문제점**: CrewAI의 LLM 계층 구조(crew LLM, manager LLM, agent LLM)를 이해하지 못해 설정이 충돌하거나 적절히 조정되지 않음. + + **실제 예시**: crew에는 Claude를, agent에는 GPT 모델을 설정해 일관성 없는 동작과 불필요한 모델 전환 오버헤드가 발생하는 경우. + + **CrewAI 솔루션**: LLM 계층 구조를 전략적으로 설계: + ```python + crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + manager_llm=LLM(model="gpt-4o"), # crew 조정용 + process=Process.hierarchical # manager_llm 사용 시 + ) + + # agent는 특별히 지정하지 않으면 crew LLM을 상속받음 + agent1 = Agent(llm=LLM(model="claude-3-5-sonnet")) # 특정 요구에 따라 오버라이드 + ``` + + + + + **문제점**: 기능 위주(함수 호출, 툴 활용 등) CrewAI workflow에서 필요한 함수 호출 성능을 무시한 채, 일반적인 모델 특성(예: 창의성)만을 보고 모델을 선택하는 실수. + + **실제 예시**: 주로 API 호출, 검색 툴, 구조화 데이터 처리가 필요한 agent에 창의성 위주의 모델을 선택해, 도구 파라미터 추출과 신뢰성 있는 함수 호출에 실패하는 경우. + + **CrewAI 솔루션**: 도구 중심 agent는 함수 호출 성능 위주로 모델을 선택: + ```python + # 다양한 도구를 사용하는 agent의 경우 + tool_agent = Agent( + role="API Integration Specialist", + tools=[search_tool, api_tool, data_tool], + llm=LLM(model="gpt-4o"), # 함수 호출에 우수 + # OR + llm=LLM(model="claude-3-5-sonnet") # 도구 사용에 강점 + ) + ``` + + + + + **문제점**: 실제 CrewAI workflow 및 업무 테스트 없이 이론상 성능만으로 복잡하게 모델을 선정하고 구성하는 실수. + + **실제 예시**: 업무 유형별로 복잡한 모델 전환 로직을 구현하지만, 실제 성능 향상이 운영 복잡성을 정당화하지 못하는 경우. + + **CrewAI 솔루션**: 단순한 구조로 시작해서, 실제 성능 데이터를 바탕으로 점진적으로 최적화: + ```python + # 이렇게 시작 + crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini")) + + # 성능을 테스트하고, 필요에 따라 특정 agent만 최적화 + # Enterprise 플랫폼 테스트를 통해 개선 사항 검증 + ``` + + + + + **문제점**: 모델의 컨텍스트 윈도(window)와 CrewAI의 메모리, agent 간 컨텍스트 공유 방식을 고려하지 않는 실수. + + **실제 예시**: 여러 차례 반복되는 업무나 agent 간 활발한 소통이 필요한 crew에 대화 내역을 오래 유지해야 하는데, 짧은 컨텍스트 모델을 사용한 경우. + + **CrewAI 솔루션**: crew의 소통 패턴에 맞춰 컨텍스트 처리 능력을 갖춘 모델을 선택. + + + + +## 테스트 및 반복 전략 + + + + 신뢰할 수 있고, 잘 알려져 있으며, 널리 지원되는 범용 모델로 시작하세요. + 이것은 최적화된 특수한 필요에 집중하기 전에 귀하의 특정 요구사항과 성능 + 기대치를 이해할 수 있는 안정적인 기초를 제공합니다. + + + 일반적인 벤치마크에만 의존하지 말고, 귀하의 특정 사용 사례와 비즈니스 요구에 + 부합하는 지표를 개발하세요. 이론적 성능 지표가 아니라 성공에 직접적으로 + 영향을 미치는 결과 측정에 집중하세요. + + + 이론적 고려사항이나 일반적인 권장사항이 아니라, 귀하의 특정 상황에서 관찰된 + 성능에 따라 모델을 변경하세요. 실제 성능은 벤치마크 결과나 일반적인 평판과는 + 크게 다를 수 있습니다. + + + 모델 비용, 개발 시간, 유지 보수 오버헤드, 운영 복잡성 등 소유에 드는 전체 + 비용을 평가하세요. 토큰당 가장 저렴한 모델이 모든 요소를 고려했을 때 반드시 + 가장 비용 효율적이지는 않을 수 있습니다. + + + + + 먼저 귀하의 요구사항을 이해하는 데 집중한 후, 그 요구와 가장 잘 맞는 모델을 + 선택하세요. 최상의 LLM 선택은 운영상의 제약 조건 내에서 꾸준히 원하는 결과를 + 제공하는 것입니다. + + +### 엔터프라이즈급 모델 검증 + +LLM 선택을 최적화하고자 하는 팀을 위해 **CrewAI AMP 플랫폼**은 기본적인 CLI 테스트를 훨씬 능가하는 정교한 테스트 기능을 제공합니다. 이 플랫폼은 데이터 기반의 LLM 전략 의사결정을 지원하는 종합적인 모델 평가를 가능하게 합니다. + + + ![엔터프라이즈 테스트 인터페이스](/images/enterprise/enterprise-testing.png) + + +**고급 테스트 기능:** + +- **다중 모델 비교**: 동일한 작업과 입력에 대해 여러 LLM을 동시에 테스트할 수 있습니다. GPT-4o, Claude, Llama, Groq, Cerebras 및 기타 선도적인 모델의 성능을 병렬로 비교하여 특정 사용 사례에 가장 적합한 모델을 식별할 수 있습니다. + +- **통계적 엄밀성**: 일관된 입력값으로 여러 번 테스트를 구성하여 신뢰성과 성능 편차를 측정할 수 있습니다. 이를 통해 단순히 잘하는 모델이 아닌, 여러 번 실행해도 안정적으로 동작하는 모델을 식별할 수 있습니다. + +- **실제 환경 검증**: 합성 벤치마크가 아닌 실제 crew 입력값과 시나리오를 사용할 수 있습니다. 플랫폼을 통해 산업 환경, 회사 정보, 실제 사용 사례 등 특정 맥락에 맞는 테스트가 가능하여 보다 정확한 평가가 이뤄집니다. + +- **종합 분석 도구**: 테스트한 모든 모델의 세부 성능 지표, 실행 시간, 비용 분석을 확인할 수 있습니다. 이로써 모델의 일반적인 평판이나 이론적 능력에 기대지 않고 데이터 기반으로 의사결정을 내릴 수 있습니다. + +- **팀 협업**: 팀 내에서 테스트 결과와 모델 성능 데이터를 공유할 수 있어, 협업적 의사결정과 프로젝트 전반에서 일관된 모델 선택 전략을 수립할 수 있습니다. + +지금 [app.crewai.com](https://app.crewai.com)에서 시작하세요! + + + Enterprise 플랫폼은 모델 선택을 단순한 추측이 아닌 데이터 기반 프로세스로 + 혁신하여, 본 가이드의 원칙을 실제 사용 사례와 요구 사항에 맞게 검증할 수 + 있도록 해줍니다. + + +## 주요 원칙 요약 + + + + 이론적 능력이나 일반적인 평판이 아니라, 작업에 실제로 필요한 것에 따라 모델을 선택하세요. + + +{" "} + + 최적의 성능을 위해 모델의 강점을 agent의 역할 및 책임과 일치시키세요. + + +{" "} + + 관련 구성 요소와 워크플로 전반에 걸쳐 일관된 모델 선택 전략을 유지하세요. + + +{" "} + + 벤치마크에만 의존하지 말고 실제 사용을 통해 선택을 검증하세요. + + +{" "} + + 단순하게 시작하고 실제 성능과 필요에 따라 최적화하세요. + + + + 성능 요구사항과 비용 및 복잡성 제약을 균형 있게 맞추세요. + + + + + 기억하세요: 최고의 LLM 선택이란 운영상의 제약 내에서 일관되게 필요한 결과를 + 제공하는 모델입니다. 먼저 요구사항을 정확히 이해하는 데 집중한 후, 그에 가장 + 잘 맞는 모델을 선택하세요. + + +## 현재 모델 현황 (2025년 6월) + + + **특정 시점의 스냅샷**: 아래 모델 순위는 2025년 6월 기준으로, [LMSys + Arena](https://arena.lmsys.org/), [Artificial + Analysis](https://artificialanalysis.ai/) 및 기타 주요 벤치마크에서 집계된 + 최신 리더보드 결과입니다. LLM의 성능, 가용성, 가격은 빠르게 변동됩니다. 항상 + 귀하의 특정 사용 사례와 데이터로 직접 평가를 진행하시기 바랍니다. + + +### 카테고리별 주요 모델 + +아래 표는 다양한 카테고리에서 현재 최고의 성능을 보이는 대표적인 모델들을 보여주며, CrewAI 에이전트에 적합한 모델 선택에 대한 가이드를 제공합니다: + + + 이 표와 지표는 각 카테고리에서 선별된 주요 모델을 보여주기 위한 것으로, 전체를 + 포괄하지 않습니다. 여기 소개되지 않은 훌륭한 모델들도 많이 존재합니다. 이 표의 + 목적은 완전한 목록을 제공하는 것이 아니라, 어떤 능력을 갖춘 모델을 찾아야 + 하는지 예시를 제시하는 것입니다. + + + + + **매니저 LLM 및 복잡한 분석에 최적** + + | Model | Intelligence Score | Cost ($/M tokens) | Speed | Best Use in CrewAI | + |:------|:------------------|:------------------|:------|:------------------| + | **o3** | 70 | $17.50 | 빠름 | 복잡한 멀티 에이전트 조정용 매니저 LLM | + | **Gemini 2.5 Pro** | 69 | $3.44 | 빠름 | 전략 기획 에이전트, 연구 조정 | + | **DeepSeek R1** | 68 | $0.96 | 보통 | 예산을 중시하는 팀을 위한 비용 효율적 reasoning | + | **Claude 4 Sonnet** | 53 | $6.00 | 빠름 | 세밀한 이해가 필요한 분석 에이전트 | + | **Qwen3 235B (Reasoning)** | 62 | $2.63 | 보통 | reasoning 작업을 위한 오픈소스 대안 | + + 이 모델들은 다단계 reasoning에 뛰어나며, 전략을 개발하거나 다른 에이전트를 조정하거나 복잡한 정보를 분석해야 하는 에이전트에 이상적입니다. + + + + + **개발 및 도구 중심의 워크플로우에 최적** + + | Model | Coding Performance | Tool Use Score | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:------------------|:---------------|:------------------|:------------------| + | **Claude 4 Sonnet** | 우수 | 72.7% | $6.00 | 주력 코딩 에이전트, 기술 문서화 | + | **Claude 4 Opus** | 우수 | 72.5% | $30.00 | 복잡한 소프트웨어 아키텍처, 코드 리뷰 | + | **DeepSeek V3** | 매우 좋음 | 높음 | $0.48 | 일상적 개발을 위한 비용 효율적 코딩 | + | **Qwen2.5 Coder 32B** | 매우 좋음 | 보통 | $0.15 | 예산 친화적 코딩 에이전트 | + | **Llama 3.1 405B** | 좋음 | 81.1% | $3.50 | 도구 사용이 많은 워크플로우를 위한 function calling LLM | + + 이 모델들은 코드 생성, 디버깅, 기술 문제 해결에 최적화되어 있어, 개발 중심 팀에 적합합니다. + + + + + **대량 처리 및 실시간 애플리케이션에 최적** + + | Model | Speed (tokens/s) | Latency (TTFT) | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:-----------------|:---------------|:------------------|:------------------| + | **Llama 4 Scout** | 2,600 | 0.33s | $0.27 | 대량 처리 에이전트 | + | **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | 실시간 응답 에이전트 | + | **DeepSeek R1 Distill** | 383 | 가변 | $0.04 | 비용 최적화 고속 처리 | + | **Llama 3.3 70B** | 2,500 | 0.52s | $0.60 | 균형 잡힌 속도와 기능 | + | **Nova Micro** | 높음 | 0.30s | $0.04 | 단순·빠른 작업 처리 | + + 이 모델들은 속도와 효율을 우선시하며, 일상적 운영 또는 신속한 응답이 필요한 에이전트에게 최적입니다. **팁**: 이러한 모델을 Groq와 같은 빠른 추론 제공자와 함께 사용하면 더욱 우수한 성능을 낼 수 있습니다. 특히 Llama와 같은 오픈소스 모델에 적합합니다. + + + + + **일반 팀을 위한 최고의 다목적 모델** + + | Model | Overall Score | Versatility | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:--------------|:------------|:------------------|:------------------| + | **GPT-4.1** | 53 | 탁월 | $3.50 | 범용 팀 LLM | + | **Claude 3.7 Sonnet** | 48 | 매우 좋음 | $6.00 | 균형 잡힌 reasoning 및 창의력 | + | **Gemini 2.0 Flash** | 48 | 좋음 | $0.17 | 비용 효율적인 범용 용도 | + | **Llama 4 Maverick** | 51 | 좋음 | $0.37 | 오픈소스 범용 모델 | + | **Qwen3 32B** | 44 | 좋음 | $1.23 | 예산 친화적 다재다능성 | + + 이 모델들은 다양한 측면에서 우수한 성능을 제공하며, 여러 작업이 혼합된 팀에 적합합니다. + + + + +### 현재 모델을 위한 선택 프레임워크 + + + + **퍼포먼스가 우선 순위일 때**: 매니저 LLM 또는 중요한 에이전트 역할에는 **o3**, **Gemini 2.5 Pro**, **Claude 4 Sonnet**과 같은 최상위 모델을 사용하세요. 이 모델들은 복잡한 reasoning 및 coordination에 탁월하지만 비용이 더 높습니다. + + **전략**: 프리미엄 모델이 전략적 사고를 담당하고, 효율적인 모델이 일상적 operation을 처리하는 멀티 모델 접근법을 구현하세요. + + + + + **예산이 주요 제약일 때**: **DeepSeek R1**, **Llama 4 Scout**, **Gemini 2.0 Flash**와 같은 모델에 집중하세요. 이 모델들은 훨씬 낮은 비용으로 강력한 퍼포먼스를 제공합니다. + + **전략**: 대부분의 에이전트에는 비용 효율이 높은 모델을 사용하고, 가장 중요한 decision-making 역할에만 프리미엄 모델을 남겨두세요. + + + + + **특정 도메인 전문성이 필요할 때**: 주된 사용 사례에 최적화된 모델을 선택하세요. 코딩에는 **Claude 4** 시리즈, 리서치에는 **Gemini 2.5 Pro**, function calling에는 **Llama 405B**를 사용하세요. + + **전략**: crew의 주요 기능에 따라 모델을 선택해, 핵심 역량이 모델의 강점과 일치하도록 하세요. + + + + + **데이터 민감한 operation의 경우**: 로컬에서 배포 가능하면서 경쟁력 있는 퍼포먼스를 유지하는 오픈 소스 모델인 **Llama 4** 시리즈, **DeepSeek V3**, **Qwen3** 등을 고려하세요. + + **전략**: 사설 인프라에 오픈 소스 모델을 배포하여, 데이터 제어를 위해 필요한 퍼포먼스 손실을 감수하세요. + + + + +### 모델 선택을 위한 주요 고려사항 + +- **성능 동향**: 현재 시장에서는 reasoning에 초점을 맞춘 모델(o3, Gemini 2.5 Pro)과 균형 잡힌 모델(Claude 4, GPT-4.1) 간의 치열한 경쟁이 있습니다. DeepSeek R1과 같은 특화 모델은 우수한 비용-성능 비율을 제공합니다. + +- **속도와 지능 간의 트레이드오프**: Llama 4 Scout와 같은 모델은 합리적인 지능을 유지하면서도 빠른 속도(2,600 tokens/s)를 우선시하며, o3와 같은 모델은 속도와 가격을 희생해 reasoning 능력을 극대화합니다. + +- **오픈 소스의 실효성**: 오픈 소스와 독점 모델 간의 격차가 계속 좁혀지고 있으며, Llama 4 Maverick 및 DeepSeek V3와 같은 모델이 매력적인 가격대에서 경쟁력 있는 성능을 제공합니다. 특히 빠른 추론을 제공하는 업체들은 오픈 소스 모델과 함께 탁월한 속도-비용 비율을 제공하는 경우가 많아 독점 모델보다 우위에 서기도 합니다. + + + **테스트는 필수입니다**: 리더보드 순위는 일반적인 가이드라인을 제공하지만, + 귀하의 특정 사용 사례, 프롬프트 스타일, 평가 기준에 따라 결과가 달라질 수 + 있습니다. 최종 결정을 내리기 전에 반드시 실제 작업과 데이터로 후보 모델을 + 테스트해 보세요. + + +### 실질적인 구현 전략 + + + + 여러 차원에서 우수한 성능을 제공하며 실제 환경에서 광범위하게 검증된 **GPT-4.1**, **Claude 3.7 Sonnet**, **Gemini 2.0 Flash**와 같은 잘 알려진 모델부터 시작하십시오. + + + + crew에 코드 작성, reasoning, 속도 등 특정 요구가 있는지 확인하고, 이러한 + 요구에 부합하는 **Claude 4 Sonnet**(개발용) 또는 **o3**(복잡한 분석용)과 같은 + 특화 모델을 고려하십시오. 속도가 중요한 애플리케이션의 경우, 모델 선택과 + 더불어 **Groq**와 같은 빠른 추론 제공자를 고려할 수 있습니다. + + + + 각 에이전트의 역할에 따라 다양한 모델을 사용하세요. 관리자와 복잡한 작업에는 + 고성능 모델을, 일상적 운영에는 효율적인 모델을 적용합니다. + + + + 사용 사례와 관련된 성능 지표를 추적하고, 새로운 모델이 출시되거나 가격이 변동될 때 모델 선택을 조정할 준비를 하십시오. + + diff --git a/docs/v1.15.1/ko/learn/multimodal-agents.mdx b/docs/v1.15.1/ko/learn/multimodal-agents.mdx new file mode 100644 index 000000000..5f4c36b8c --- /dev/null +++ b/docs/v1.15.1/ko/learn/multimodal-agents.mdx @@ -0,0 +1,141 @@ +--- +title: 멀티모달 에이전트 사용하기 +description: CrewAI 프레임워크 내에서 이미지 및 기타 비텍스트 콘텐츠를 처리하기 위해 에이전트에서 멀티모달 기능을 활성화하고 사용하는 방법을 알아보세요. +icon: video +mode: "wide" +--- + +## 멀티모달 에이전트 사용하기 + +CrewAI는 텍스트뿐만 아니라 이미지와 같은 비텍스트 콘텐츠도 처리할 수 있는 멀티모달 에이전트를 지원합니다. 이 가이드에서는 에이전트에서 멀티모달 기능을 활성화하고 사용하는 방법을 안내합니다. + +### 멀티모달 기능 활성화 + +멀티모달 에이전트를 생성하려면, 에이전트를 초기화할 때 `multimodal` 파라미터를 `True`로 설정하면 됩니다: + +```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 +) +``` + +`multimodal=True`로 설정하면, 에이전트는 자동으로 비텍스트 콘텐츠를 처리하는 데 필요한 도구들(예: `AddImageTool`)과 함께 구성됩니다. + +### 이미지 작업하기 + +멀티모달 에이전트는 이미지를 처리할 수 있는 `AddImageTool`이 사전 구성되어 포함되어 있습니다. 이 도구를 수동으로 추가할 필요가 없으며, 멀티모달 기능을 활성화하면 자동으로 포함됩니다. + +아래는 멀티모달 에이전트를 사용하여 이미지를 분석하는 방법을 보여주는 전체 예제입니다: + +```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() +``` + +### 컨텍스트를 활용한 고급 사용법 + +멀티모달 agent를 위한 task를 생성할 때 추가적인 컨텍스트나 이미지에 대한 구체적인 질문을 제공할 수 있습니다. task 설명에는 agent가 집중해야 할 특정 측면을 포함할 수 있습니다. + +```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() +``` + +### 도구 세부 정보 + +멀티모달 에이전트를 사용할 때, `AddImageTool`은 다음 스키마로 자동 구성됩니다: + +```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 +``` + +멀티모달 에이전트는 내장 도구를 통해 자동으로 이미지 처리를 수행하므로 다음과 같은 작업이 가능합니다: +- URL 또는 로컬 파일 경로를 통해 이미지 접근 +- 선택적 컨텍스트나 구체적인 질문을 포함하여 이미지 내용 처리 +- 시각적 정보와 작업 요구사항에 따른 분석 및 인사이트 제공 + +### 모범 사례 + +멀티모달 에이전트를 사용할 때 다음의 모범 사례를 염두에 두세요: + +1. **이미지 접근성** + - 에이전트가 접근할 수 있는 URL을 통해 이미지를 제공해야 합니다. + - 로컬 이미지는 임시로 호스팅하거나 절대 파일 경로를 사용하는 것을 고려하세요. + - 작업을 실행하기 전에 이미지 URL이 유효하고 접근 가능한지 확인하세요. + +2. **작업 설명** + - 에이전트가 이미지의 어떤 부분을 분석하기를 원하는지 구체적으로 명시하세요. + - 작업 설명에 명확한 질문이나 요구사항을 포함하세요. + - 집중된 분석이 필요한 경우 선택적인 `action` 파라미터 사용을 고려하세요. + +3. **리소스 관리** + - 이미지 처리는 텍스트 전용 작업보다 더 많은 컴퓨팅 자원을 필요로 할 수 있습니다. + - 일부 언어 모델은 이미지 데이터를 base64로 인코딩해야 할 수 있습니다. + - 성능 최적화를 위해 여러 이미지를 일괄 처리하는 방법을 고려하세요. + +4. **환경 설정** + - 이미지 처리를 위한 필수 의존성이 환경에 설치되어 있는지 확인하세요. + - 사용하는 언어 모델이 멀티모달 기능을 지원하는지 확인하세요. + - 설정을 검증하기 위해 작은 이미지를 먼저 테스트하세요. + +5. **오류 처리** + - 이미지 로딩 실패에 대한 적절한 오류 처리를 구현하세요. + - 이미지 처리 실패 시를 대비한 예비 전략을 마련하세요. + - 디버깅을 위해 이미지 처리 작업을 모니터링하고 로그를 남기세요. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/overview.mdx b/docs/v1.15.1/ko/learn/overview.mdx new file mode 100644 index 000000000..0568222ce --- /dev/null +++ b/docs/v1.15.1/ko/learn/overview.mdx @@ -0,0 +1,159 @@ +--- +title: "개요" +description: "포괄적인 가이드와 튜토리얼을 통해 CrewAI 애플리케이션을 빌드하고, 맞춤화하며, 최적화하는 방법을 알아보세요." +icon: "face-smile" +mode: "wide" +--- + +## CrewAI 배우기 + +이 섹션은 CrewAI를 마스터하는 데 도움이 되는 종합적인 가이드와 튜토리얼을 제공합니다. 기본 개념부터 고급 기술까지 다루며, 이제 막 시작하는 분이든 기존 구현을 최적화하려는 분이든, 이 자료들은 강력한 AI 에이전트 워크플로우를 구축하는 모든 측면을 안내해 드립니다. + +## 시작하기 안내 + +### 핵심 개념 + + + 구조화된 워크플로우를 위해 작업을 순차적으로 실행하는 방법을 학습합니다. + + + + 매니저 에이전트가 워크플로우를 감독하며 계층적으로 작업을 실행합니다. + + + + 결과에 따라 조건부로 작업을 실행하여 동적인 워크플로우를 만듭니다. + + + + 향상된 성능과 동시성을 위해 crew를 비동기로 실행합니다. + + + +### 에이전트 개발 + + + 에이전트의 동작 방식, 역할, 역량을 커스터마이즈하는 방법을 배워보세요. + + + + 코드 작성, 실행, 디버깅을 자동으로 수행할 수 있는 에이전트를 구축하세요. + + + + 텍스트, 이미지, 기타 미디어 유형을 처리할 수 있는 에이전트를 만들어보세요. + + + + 복잡한 계층적 워크플로우를 위한 커스텀 매니저 에이전트를 구현하세요. + + + +## 고급 기능 + +### 워크플로 제어 + + + 에이전트 워크플로에 인간의 감독과 개입을 통합하세요. + + + + 작업 실행 중에 인간의 입력을 허용하여 동적인 의사결정을 지원합니다. + + + + 이전 crew 실행으로부터 작업을 다시 실행하고 재개하세요. + + + + 서로 다른 입력으로 crew를 효율적으로 여러 번 실행하세요. + + + +### 맞춤화 및 통합 + + + CrewAI와 커스텀 언어 모델 및 공급자를 통합하세요. + + + + 다양한 LLM 공급자에 대한 연결을 구성하고 관리하세요. + + + + 에이전트의 기능을 확장할 수 있는 커스텀 도구를 빌드하세요. + + + + 더 깔끔하고 유지 관리하기 쉬운 코드를 위해 Python 주석을 사용하세요. + + + +## 특수화된 애플리케이션 + +### 콘텐츠 & 미디어 + + + 에이전트와의 DALL-E 통합을 사용하여 이미지를 생성하세요. + + + + 기존 에이전트와 모델을 CrewAI 워크플로우에 통합하세요. + + + +### 도구 관리 + + + 도구를 구성하여 출력값을 작업 결과로 직접 반환하도록 합니다. + + + +## 학습 경로 추천 + +### 초보자를 위한 안내 +1. 기본 워크플로 실행을 이해하려면 **Sequential Process**로 시작하세요. +2. 효과적인 에이전트 구성을 만들기 위해 **Customizing Agents**를 학습하세요. +3. 기능 확장을 위해 **Create Custom Tools**을(를) 탐색하세요. +4. 인터랙티브 워크플로를 위해 **Human in the Loop**을(를) 시도해 보세요. + +### 중급 사용자를 위한 안내 +1. 복잡한 다중 에이전트 시스템을 위해 **계층적 프로세스** 마스터하기 +2. 동적 워크플로우를 위해 **조건부 태스크** 구현하기 +3. 성능 최적화를 위해 **비동기 시작** 사용하기 +4. 특화된 모델을 위해 **커스텀 LLM** 통합하기 + +### 고급 사용자용 +1. 복잡한 미디어 처리를 위한 **멀티모달 에이전트** 빌드 +2. 정교한 오케스트레이션을 위한 **커스텀 매니저 에이전트** 생성 +3. 하이브리드 시스템을 위한 **BYOA(Bring Your Own Agent)** 구현 +4. 견고한 오류 복구를 위한 **리플레이 태스크** 사용 + +## 모범 사례 + +### 개발 +- **간단하게 시작하세요**: 복잡성을 추가하기 전에 기본적인 순차 워크플로우부터 시작하세요 +- **점진적으로 테스트하세요**: 더 큰 시스템에 통합하기 전에 각 구성 요소를 테스트하세요 +- **애노테이션 사용**: 더 깔끔하고 유지보수가 쉬운 코드를 위해 Python 애노테이션을 활용하세요 +- **커스텀 도구**: 다양한 agent에서 공유할 수 있는 재사용 가능한 도구를 만드세요 + +### 운영 환경 +- **오류 처리**: 강력한 오류 처리 및 복구 메커니즘 구현 +- **성능**: 비동기 실행을 사용하고 더 나은 성능을 위해 LLM 호출 최적화 +- **모니터링**: 에이전트 성능 추적을 위해 가시성 도구 통합 +- **인간 감독**: 중요한 의사결정을 위한 인간 점검 지점 포함 + +### 최적화 +- **리소스 관리**: 토큰 사용량과 API 비용을 모니터링하고 최적화합니다. +- **워크플로우 설계**: 불필요한 LLM 호출을 최소화하는 워크플로우를 설계합니다. +- **도구 효율성**: 최소한의 오버헤드로 최대 가치를 제공하는 효율적인 도구를 만듭니다. +- **반복적 개선**: 피드백과 메트릭을 활용하여 에이전트 성능을 지속적으로 개선합니다. + +## 도움 받기 + +- **문서**: 각 가이드에는 자세한 예시와 설명이 포함되어 있습니다 +- **커뮤니티**: 토론과 지원을 위해 [CrewAI 포럼](https://community.crewai.com)에 참여하세요 +- **예제**: 완전한 작동 구현을 보려면 예제 섹션을 확인하세요 +- **지원**: 기술 지원이 필요하면 [support@crewai.com](mailto:support@crewai.com)으로 문의하세요 + +현재 필요에 맞는 가이드부터 시작하고, 기본 사항에 익숙해지면 점차 더 고급 주제를 탐색해보세요. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/v1.15.1/ko/learn/replay-tasks-from-latest-crew-kickoff.mdx new file mode 100644 index 000000000..1ae9eae33 --- /dev/null +++ b/docs/v1.15.1/ko/learn/replay-tasks-from-latest-crew-kickoff.mdx @@ -0,0 +1,79 @@ +--- +title: 최신 Crew Kickoff에서 작업 다시 실행하기 +description: 최신 crew.kickoff(...)에서 작업을 다시 실행합니다. +icon: arrow-right +mode: "wide" +--- + +## 소개 + +CrewAI는 최신 crew 킥오프에서 지정된 태스크를 다시 실행할 수 있는 기능을 제공합니다. 이 기능은 킥오프를 완료한 후 특정 태스크를 다시 시도하고 싶거나 데이터를 다시 가져올 필요 없이 이미 에이전트들이 킥오프 실행에서 컨텍스트를 저장한 경우, 원하는 태스크만 다시 실행(Replay)하면 될 때 특히 유용합니다. + + + 태스크를 다시 실행하기 전에 반드시 `crew.kickoff()`을 실행해야 합니다. + 현재는 최신 킥오프만 지원되므로, `kickoff_for_each`를 사용하는 경우에도 가장 최근의 crew 실행만 다시 실행할 수 있습니다. + + +다음은 태스크에서 다시 실행하는 방법의 예시입니다: + +### CLI를 사용하여 특정 Task에서 재실행하기 + +재실행 기능을 사용하려면 다음 단계를 따르세요: + + + + + + 최신 kickoff task_id를 확인하려면 아래를 사용하세요: + + ```shell + crewai log-tasks-outputs + ``` + + 재실행할 `task_id`를 확인했다면, 아래를 사용하세요: + + ```shell + crewai replay -t + ``` + + + + + 개발 환경에 `crewai`가 정상적으로 설치 및 구성되어 있는지 확인하세요. + + +### 작업에서 프로그래밍 방식으로 리플레이하기 + +작업에서 프로그래밍 방식으로 리플레이하려면 다음 단계를 따르세요: + + + + 리플레이 프로세스를 위한 `task_id`와 입력 파라미터를 지정합니다. + + + 잠재적인 오류를 처리하기 위해 try-except 블록 내에서 리플레이 명령을 실행합니다. + + ```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}") + ``` + + + + +## 결론 + +위의 개선 사항과 세부적인 기능으로 CrewAI에서 특정 작업을 재실행하는 것이 더욱 효율적이고 견고해졌습니다. +이러한 기능을 최대한 활용하려면 명령어와 단계를 정확하게 따라주시기 바랍니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/sequential-process.mdx b/docs/v1.15.1/ko/learn/sequential-process.mdx new file mode 100644 index 000000000..e8760c7c5 --- /dev/null +++ b/docs/v1.15.1/ko/learn/sequential-process.mdx @@ -0,0 +1,128 @@ +--- +title: 순차 프로세스 +description: CrewAI 프로젝트에서 작업 실행을 위한 순차 프로세스를 활용하는 방법에 대한 종합 가이드입니다. +icon: forward +mode: "wide" +--- + +## 소개 + +CrewAI는 순차적 및 계층적 프로세스를 모두 지원하는 구조화된 방식으로 작업을 실행할 수 있는 유연한 프레임워크를 제공합니다. +이 가이드에서는 효율적인 작업 실행과 프로젝트 완수를 보장하기 위해 이러한 프로세스를 효과적으로 구현하는 방법을 설명합니다. + +## 순차적 프로세스 개요 + +순차적 프로세스는 작업이 선형적인 진행 방식으로 하나씩 차례로 실행되도록 보장합니다. +이 접근 방식은 특정 순서로 작업이 완료되어야 하는 프로젝트에 이상적입니다. + +### 주요 기능 + +- **선형 작업 흐름**: 미리 정해진 순서대로 작업을 처리하여 체계적인 진행을 보장합니다. +- **단순성**: 명확하고 단계별 작업이 있는 프로젝트에 가장 적합합니다. +- **쉬운 모니터링**: 작업 완료 및 프로젝트 진행 상황을 쉽게 추적할 수 있습니다. + +## 순차적 프로세스 구현하기 + +순차적 프로세스를 사용하려면 crew를 구성하고 수행되어야 하는 순서대로 작업을 정의하세요. + +```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 +``` + +### 참고: + +순차적 프로세스의 각 작업에는 **반드시** 에이전트가 할당되어야 합니다. 모든 `Task`에 `agent` 파라미터가 포함되어 있는지 확인하세요. + +### 워크플로우 실행 + +1. **초기 작업**: 순차적인 프로세스에서 첫 번째 agent가 자신의 작업을 완료하고 완료 신호를 보냅니다. +2. **이후 작업들**: agent들은 프로세스 유형에 따라 작업을 수행하며, 이전 작업의 결과나 지침이 실행을 안내합니다. +3. **완료**: 최종 작업이 실행되면 프로세스가 종료되어 프로젝트가 완료됩니다. + +## 고급 기능 + +### 작업 위임 + +순차적 프로세스에서, 에이전트가 `allow_delegation`이 `True`로 설정되어 있으면 해당 에이전트는 crew 내의 다른 에이전트에게 작업을 위임할 수 있습니다. +이 기능은 crew에 여러 에이전트가 있을 때 자동으로 설정됩니다. + +### 비동기 실행 + +작업은 비동기로 실행될 수 있어, 적절할 때 병렬 처리가 가능합니다. +비동기 작업을 생성하려면 작업을 정의할 때 `async_execution=True`로 설정하세요. + +### 메모리 및 캐싱 + +CrewAI는 메모리와 캐싱 기능을 모두 지원합니다: + +- **메모리**: Crew를 생성할 때 `memory=True`로 설정하면 활성화됩니다. 이를 통해 에이전트가 작업 간 정보를 유지할 수 있습니다. +- **캐싱**: 기본적으로 캐싱이 활성화되어 있습니다. 비활성화하려면 `cache=False`로 설정하세요. + +### 콜백 + +콜백은 작업(task) 수준과 단계(step) 수준 모두에서 설정할 수 있습니다: + +- `task_callback`: 각 작업이 완료된 후 실행됩니다. +- `step_callback`: 에이전트의 각 단계 실행 후에 실행됩니다. + +### 사용량 메트릭 + +CrewAI는 모든 task와 agent 전반에 걸쳐 토큰 사용량을 추적합니다. 이 메트릭은 실행 후에 확인할 수 있습니다. + +## 순차적 프로세스를 위한 모범 사례 + +1. **순서가 중요함**: 각 작업이 이전 작업을 기반으로 쌓일 수 있도록 논리적인 순서로 작업을 배열하세요. +2. **명확한 작업 설명**: 각 작업에 대해 에이전트를 효과적으로 안내할 수 있도록 상세한 설명을 제공하세요. +3. **적절한 에이전트 선정**: 각 작업의 요구사항에 맞게 에이전트의 역량과 역할을 매칭하세요. +4. **컨텍스트 활용**: 이전 작업에서 얻은 컨텍스트를 다음 작업에 활용하세요. + +이 업데이트된 문서는 코드베이스의 최신 변경 사항을 정확하게 반영하고, 새로운 기능 및 설정을 어떻게 활용할 수 있는지 명확하게 설명합니다. +내용이 간단하고 명확하여 쉽게 이해할 수 있도록 구성되었습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/streaming-crew-execution.mdx b/docs/v1.15.1/ko/learn/streaming-crew-execution.mdx new file mode 100644 index 000000000..db2ce1c0c --- /dev/null +++ b/docs/v1.15.1/ko/learn/streaming-crew-execution.mdx @@ -0,0 +1,384 @@ +--- +title: 스트리밍 Crew 실행 +description: CrewAI crew 실행에서 실시간 출력을 스트리밍하기 +icon: wave-pulse +mode: "wide" +--- + +## 소개 + +CrewAI는 crew 실행 중 실시간 출력을 스트리밍하는 기능을 제공하여, 전체 프로세스가 완료될 때까지 기다리지 않고 결과가 생성되는 대로 표시할 수 있습니다. 이 기능은 대화형 애플리케이션을 구축하거나, 사용자 피드백을 제공하거나, 장시간 실행되는 프로세스를 모니터링할 때 특히 유용합니다. + +## 스트리밍 작동 방식 + +스트리밍이 활성화되면 CrewAI는 LLM 응답과 도구 호출을 실시간으로 캡처하여, 어떤 task와 agent가 실행 중인지에 대한 컨텍스트를 포함한 구조화된 청크로 패키징합니다. 이러한 청크를 실시간으로 반복 처리하고 실행이 완료되면 최종 결과에 접근할 수 있습니다. + +## 스트리밍 활성화 + +스트리밍을 활성화하려면 crew를 생성할 때 `stream` 파라미터를 `True`로 설정하세요: + +```python Code +from crewai import Agent, Crew, Task + +# 에이전트와 태스크 생성 +researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information on topics", + backstory="You are an experienced researcher with excellent analytical skills.", +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A detailed report on recent AI advancements", + agent=researcher, +) + +# 스트리밍 활성화 +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True # 스트리밍 출력 활성화 +) +``` + +## 동기 스트리밍 + +스트리밍이 활성화된 crew에서 `kickoff()`를 호출하면, 청크가 도착할 때마다 반복 처리할 수 있는 `CrewStreamingOutput` 객체가 반환됩니다: + +```python Code +# 스트리밍 실행 시작 +streaming = crew.kickoff(inputs={"topic": "artificial intelligence"}) + +# 청크가 도착할 때마다 반복 +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# 스트리밍 완료 후 최종 결과 접근 +result = streaming.result +print(f"\n\n최종 출력: {result.raw}") +``` + +### 스트림 청크 정보 + +각 청크는 실행에 대한 풍부한 컨텍스트를 제공합니다: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +for chunk in streaming: + print(f"Task: {chunk.task_name} (인덱스 {chunk.task_index})") + print(f"Agent: {chunk.agent_role}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT 또는 TOOL_CALL + if chunk.tool_call: + print(f"Tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +### 스트리밍 결과 접근 + +`CrewStreamingOutput` 객체는 여러 유용한 속성을 제공합니다: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +# 청크 반복 및 수집 +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# 반복 완료 후 +print(f"\n완료됨: {streaming.is_completed}") +print(f"전체 텍스트: {streaming.get_full_text()}") +print(f"전체 청크 수: {len(streaming.chunks)}") +print(f"최종 결과: {streaming.result.raw}") +``` + +## 비동기 스트리밍 + +비동기 애플리케이션의 경우, 비동기 반복과 함께 `akickoff()`(네이티브 async) 또는 `kickoff_async()`(스레드 기반)를 사용할 수 있습니다: + +### `akickoff()`를 사용한 네이티브 Async + +`akickoff()` 메서드는 전체 체인에서 진정한 네이티브 async 실행을 제공합니다: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # 네이티브 async 스트리밍 시작 + streaming = await crew.akickoff(inputs={"topic": "AI"}) + + # 청크에 대한 비동기 반복 + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # 최종 결과 접근 + result = streaming.result + print(f"\n\n최종 출력: {result.raw}") + +asyncio.run(stream_crew()) +``` + +### `kickoff_async()`를 사용한 스레드 기반 Async + +더 간단한 async 통합이나 하위 호환성을 위해: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # 스레드 기반 async 스트리밍 시작 + streaming = await crew.kickoff_async(inputs={"topic": "AI"}) + + # 청크에 대한 비동기 반복 + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # 최종 결과 접근 + result = streaming.result + print(f"\n\n최종 출력: {result.raw}") + +asyncio.run(stream_crew()) +``` + + +고동시성 워크로드의 경우, 태스크 실행, 메모리 작업, 지식 검색에 네이티브 async를 사용하는 `akickoff()`가 권장됩니다. 자세한 내용은 [Crew 비동기 시작](/ko/learn/kickoff-async) 가이드를 참조하세요. + + +## kickoff_for_each를 사용한 스트리밍 + +`kickoff_for_each()`로 여러 입력에 대해 crew를 실행할 때, 동기 또는 비동기 여부에 따라 스트리밍이 다르게 작동합니다: + +### 동기 kickoff_for_each + +동기 `kickoff_for_each()`를 사용하면, 각 입력에 대해 하나씩 `CrewStreamingOutput` 객체의 리스트가 반환됩니다: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} +] + +# 스트리밍 출력 리스트 반환 +streaming_outputs = crew.kickoff_for_each(inputs=inputs_list) + +# 각 스트리밍 출력에 대해 반복 +for i, streaming in enumerate(streaming_outputs): + print(f"\n=== 입력 {i + 1} ===") + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\n\n결과 {i + 1}: {result.raw}") +``` + +### 비동기 kickoff_for_each_async + +비동기 `kickoff_for_each_async()`를 사용하면, 모든 crew의 청크가 동시에 도착하는 대로 반환하는 단일 `CrewStreamingOutput`이 반환됩니다: + +```python Code +import asyncio + +async def stream_multiple_crews(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} + ] + + # 모든 crew에 대한 단일 스트리밍 출력 반환 + streaming = await crew.kickoff_for_each_async(inputs=inputs_list) + + # 모든 crew의 청크가 생성되는 대로 도착 + async for chunk in streaming: + print(f"[{chunk.task_name}] {chunk.content}", end="", flush=True) + + # 모든 결과 접근 + results = streaming.results # CrewOutput 객체 리스트 + for i, result in enumerate(results): + print(f"\n\n결과 {i + 1}: {result.raw}") + +asyncio.run(stream_multiple_crews()) +``` + +## 스트림 청크 타입 + +청크는 `chunk_type` 필드로 표시되는 다양한 타입을 가질 수 있습니다: + +### TEXT 청크 + +LLM 응답의 표준 텍스트 콘텐츠: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### TOOL_CALL 청크 + +수행 중인 도구 호출에 대한 정보: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL: + print(f"\n도구 호출: {chunk.tool_call.tool_name}") + print(f"인자: {chunk.tool_call.arguments}") +``` + +## 실용적인 예시: 스트리밍을 사용한 UI 구축 + +다음은 스트리밍을 사용한 대화형 애플리케이션을 구축하는 방법을 보여주는 완전한 예시입니다: + +```python Code +import asyncio +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +async def interactive_research(): + # 스트리밍이 활성화된 crew 생성 + researcher = Agent( + role="Research Analyst", + goal="Provide detailed analysis on any topic", + backstory="You are an expert researcher with broad knowledge.", + ) + + task = Task( + description="Research and analyze: {topic}", + expected_output="A comprehensive analysis with key insights", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True, + verbose=False + ) + + # 사용자 입력 받기 + topic = input("연구할 주제를 입력하세요: ") + + print(f"\n{'='*60}") + print(f"연구 중: {topic}") + print(f"{'='*60}\n") + + # 스트리밍 실행 시작 + streaming = await crew.kickoff_async(inputs={"topic": topic}) + + current_task = "" + async for chunk in streaming: + # 태스크 전환 표시 + if chunk.task_name != current_task: + current_task = chunk.task_name + print(f"\n[{chunk.agent_role}] 작업 중: {chunk.task_name}") + print("-" * 60) + + # 텍스트 청크 표시 + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # 도구 호출 표시 + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 도구 사용: {chunk.tool_call.tool_name}") + + # 최종 결과 표시 + result = streaming.result + print(f"\n\n{'='*60}") + print("분석 완료!") + print(f"{'='*60}") + print(f"\n토큰 사용량: {result.token_usage}") + +asyncio.run(interactive_research()) +``` + +## 사용 사례 + +스트리밍은 다음과 같은 경우에 특히 유용합니다: + +- **대화형 애플리케이션**: 에이전트가 작업하는 동안 사용자에게 실시간 피드백 제공 +- **장시간 실행 태스크**: 연구, 분석 또는 콘텐츠 생성의 진행 상황 표시 +- **디버깅 및 모니터링**: 에이전트 동작과 의사 결정을 실시간으로 관찰 +- **사용자 경험**: 점진적인 결과를 표시하여 체감 지연 시간 감소 +- **라이브 대시보드**: crew 실행 상태를 표시하는 모니터링 인터페이스 구축 + +## 취소 및 리소스 정리 + +`CrewStreamingOutput`은 소비자가 연결을 끊을 때 진행 중인 작업을 즉시 중단하는 정상적인 취소를 지원합니다. + +### 비동기 컨텍스트 매니저 + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### 명시적 취소 + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # 비동기 + # streaming.close() # 동기 버전 +``` + +취소 후 `streaming.is_cancelled`와 `streaming.is_completed`는 모두 `True`입니다. `aclose()`와 `close()` 모두 멱등성을 가집니다. + +## 중요 사항 + +- 스트리밍은 crew의 모든 에이전트에 대해 자동으로 LLM 스트리밍을 활성화합니다 +- `.result` 속성에 접근하기 전에 모든 청크를 반복해야 합니다 +- 스트리밍을 사용하는 `kickoff_for_each_async()`의 경우, 모든 출력을 가져오려면 `.results`(복수형)를 사용하세요 +- 스트리밍은 최소한의 오버헤드를 추가하며 실제로 체감 성능을 향상시킬 수 있습니다 +- 각 청크는 풍부한 UI를 위한 전체 컨텍스트(태스크, 에이전트, 청크 타입)를 포함합니다 + +## 오류 처리 + +스트리밍 실행 중 오류 처리: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\n성공: {result.raw}") + +except Exception as e: + print(f"\n스트리밍 중 오류 발생: {e}") + if streaming.is_completed: + print("스트리밍은 완료되었지만 오류가 발생했습니다") +``` + +스트리밍을 활용하면 CrewAI로 더 반응성이 좋고 대화형인 애플리케이션을 구축하여 사용자에게 에이전트 실행과 결과에 대한 실시간 가시성을 제공할 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/learn/tool-hooks.mdx b/docs/v1.15.1/ko/learn/tool-hooks.mdx new file mode 100644 index 000000000..672070cef --- /dev/null +++ b/docs/v1.15.1/ko/learn/tool-hooks.mdx @@ -0,0 +1,498 @@ +--- +title: 도구 호출 훅 +description: CrewAI에서 도구 실행을 가로채고, 수정하고, 제어하는 도구 호출 훅 사용 방법 배우기 +mode: "wide" +--- + +도구 호출 훅(Tool Call Hooks)은 에이전트 작업 중 도구 실행에 대한 세밀한 제어를 제공합니다. 이러한 훅을 사용하면 도구 호출을 가로채고, 입력을 수정하고, 출력을 변환하고, 안전 검사를 구현하고, 포괄적인 로깅 또는 모니터링을 추가할 수 있습니다. + +## 개요 + +도구 훅은 두 가지 중요한 시점에 실행됩니다: +- **도구 호출 전**: 입력 수정, 매개변수 검증 또는 실행 차단 +- **도구 호출 후**: 결과 변환, 출력 정제 또는 실행 세부사항 로깅 + +## 훅 타입 + +### 도구 호출 전 훅 + +모든 도구 실행 전에 실행되며, 다음을 수행할 수 있습니다: +- 도구 입력 검사 및 수정 +- 조건에 따라 도구 실행 차단 +- 위험한 작업에 대한 승인 게이트 구현 +- 매개변수 검증 +- 도구 호출 로깅 + +**시그니처:** +```python +def before_hook(context: ToolCallHookContext) -> bool | None: + # 실행을 차단하려면 False 반환 + # 실행을 허용하려면 True 또는 None 반환 + ... +``` + +### 도구 호출 후 훅 + +모든 도구 실행 후에 실행되며, 다음을 수행할 수 있습니다: +- 도구 결과 수정 또는 정제 +- 메타데이터 또는 서식 추가 +- 실행 결과 로깅 +- 결과 검증 구현 +- 출력 형식 변환 + +**시그니처:** +```python +def after_hook(context: ToolCallHookContext) -> str | None: + # 수정된 결과 문자열 반환 + # 원본 결과를 유지하려면 None 반환 + ... +``` + +## 도구 훅 컨텍스트 + +`ToolCallHookContext` 객체는 도구 실행 상태에 대한 포괄적인 액세스를 제공합니다: + +```python +class ToolCallHookContext: + tool_name: str # 호출되는 도구의 이름 + tool_input: dict[str, Any] # 변경 가능한 도구 입력 매개변수 + tool: CrewStructuredTool # 도구 인스턴스 참조 + agent: Agent | BaseAgent | None # 도구를 실행하는 에이전트 + task: Task | None # 현재 작업 + crew: Crew | None # 크루 인스턴스 + tool_result: str | None # 도구 결과 (후 훅용) +``` + +### 도구 입력 수정 + +**중요:** 항상 도구 입력을 제자리에서 수정하세요: + +```python +# ✅ 올바름 - 제자리에서 수정 +def sanitize_input(context: ToolCallHookContext) -> None: + context.tool_input['query'] = context.tool_input['query'].lower() + +# ❌ 잘못됨 - 딕셔너리 참조를 교체 +def wrong_approach(context: ToolCallHookContext) -> None: + context.tool_input = {'query': 'new query'} +``` + +## 등록 방법 + +### 1. 데코레이터 기반 등록 (권장) + +더 깔끔한 구문을 위해 데코레이터를 사용합니다: + +```python +from crewai.hooks import before_tool_call, after_tool_call + +@before_tool_call +def block_dangerous_tools(context): + """위험한 도구를 차단합니다.""" + dangerous_tools = ['delete_database', 'drop_table', 'rm_rf'] + if context.tool_name in dangerous_tools: + print(f"⛔ 위험한 도구 차단됨: {context.tool_name}") + return False # 실행 차단 + return None + +@after_tool_call +def sanitize_results(context): + """결과를 정제합니다.""" + if context.tool_result and "password" in context.tool_result.lower(): + return context.tool_result.replace("password", "[수정됨]") + return None +``` + +### 2. 크루 범위 훅 + +특정 크루 인스턴스에 대한 훅을 등록합니다: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_tool_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_tool_call_crew + def validate_tool_inputs(self, context): + # 이 크루에만 적용됩니다 + if context.tool_name == "web_search": + if not context.tool_input.get('query'): + print("❌ 잘못된 검색 쿼리") + return False + return None + + @after_tool_call_crew + def log_tool_results(self, context): + # 크루별 도구 로깅 + print(f"✅ {context.tool_name} 완료됨") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## 일반적인 사용 사례 + +### 1. 안전 가드레일 + +```python +@before_tool_call +def safety_check(context: ToolCallHookContext) -> bool | None: + """해를 끼칠 수 있는 도구를 차단합니다.""" + destructive_tools = [ + 'delete_file', + 'drop_table', + 'remove_user', + 'system_shutdown' + ] + + if context.tool_name in destructive_tools: + print(f"🛑 파괴적인 도구 차단됨: {context.tool_name}") + return False + + # 민감한 작업에 대해 경고 + sensitive_tools = ['send_email', 'post_to_social_media', 'charge_payment'] + if context.tool_name in sensitive_tools: + print(f"⚠️ 민감한 도구 실행 중: {context.tool_name}") + + return None +``` + +### 2. 사람의 승인 게이트 + +```python +@before_tool_call +def require_approval_for_actions(context: ToolCallHookContext) -> bool | None: + """특정 작업에 대한 승인을 요구합니다.""" + approval_required = [ + 'send_email', + 'make_purchase', + 'delete_file', + 'post_message' + ] + + if context.tool_name in approval_required: + response = context.request_human_input( + prompt=f"{context.tool_name}을(를) 승인하시겠습니까?", + default_message=f"입력: {context.tool_input}\n승인하려면 'yes'를 입력하세요:" + ) + + if response.lower() != 'yes': + print(f"❌ 도구 실행 거부됨: {context.tool_name}") + return False + + return None +``` + +### 3. 입력 검증 및 정제 + +```python +@before_tool_call +def validate_and_sanitize_inputs(context: ToolCallHookContext) -> bool | None: + """입력을 검증하고 정제합니다.""" + # 검색 쿼리 검증 + if context.tool_name == 'web_search': + query = context.tool_input.get('query', '') + if len(query) < 3: + print("❌ 검색 쿼리가 너무 짧습니다") + return False + + # 쿼리 정제 + context.tool_input['query'] = query.strip().lower() + + # 파일 경로 검증 + if context.tool_name == 'read_file': + path = context.tool_input.get('path', '') + if '..' in path or path.startswith('/'): + print("❌ 잘못된 파일 경로") + return False + + return None +``` + +### 4. 결과 정제 + +```python +@after_tool_call +def sanitize_sensitive_data(context: ToolCallHookContext) -> str | None: + """민감한 데이터를 정제합니다.""" + if not context.tool_result: + return None + + import re + result = context.tool_result + + # API 키 제거 + result = re.sub( + r'(api[_-]?key|token)["\']?\s*[:=]\s*["\']?[\w-]+', + r'\1: [수정됨]', + result, + flags=re.IGNORECASE + ) + + # 이메일 주소 제거 + result = re.sub( + r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '[이메일-수정됨]', + result + ) + + # 신용카드 번호 제거 + result = re.sub( + r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', + '[카드-수정됨]', + result + ) + + return result +``` + +### 5. 도구 사용 분석 + +```python +import time +from collections import defaultdict + +tool_stats = defaultdict(lambda: {'count': 0, 'total_time': 0, 'failures': 0}) + +@before_tool_call +def start_timer(context: ToolCallHookContext) -> None: + context.tool_input['_start_time'] = time.time() + return None + +@after_tool_call +def track_tool_usage(context: ToolCallHookContext) -> None: + start_time = context.tool_input.get('_start_time', time.time()) + duration = time.time() - start_time + + tool_stats[context.tool_name]['count'] += 1 + tool_stats[context.tool_name]['total_time'] += duration + + if not context.tool_result or 'error' in context.tool_result.lower(): + tool_stats[context.tool_name]['failures'] += 1 + + print(f""" + 📊 {context.tool_name} 도구 통계: + - 실행 횟수: {tool_stats[context.tool_name]['count']} + - 평균 시간: {tool_stats[context.tool_name]['total_time'] / tool_stats[context.tool_name]['count']:.2f}초 + - 실패: {tool_stats[context.tool_name]['failures']} + """) + + return None +``` + +### 6. 속도 제한 + +```python +from collections import defaultdict +from datetime import datetime, timedelta + +tool_call_history = defaultdict(list) + +@before_tool_call +def rate_limit_tools(context: ToolCallHookContext) -> bool | None: + """도구 호출 속도를 제한합니다.""" + tool_name = context.tool_name + now = datetime.now() + + # 오래된 항목 정리 (1분 이상 된 것) + tool_call_history[tool_name] = [ + call_time for call_time in tool_call_history[tool_name] + if now - call_time < timedelta(minutes=1) + ] + + # 속도 제한 확인 (분당 최대 10회 호출) + if len(tool_call_history[tool_name]) >= 10: + print(f"🚫 {tool_name}에 대한 속도 제한 초과") + return False + + # 이 호출 기록 + tool_call_history[tool_name].append(now) + return None +``` + +### 7. 디버그 로깅 + +```python +@before_tool_call +def debug_tool_call(context: ToolCallHookContext) -> None: + """도구 호출을 디버그합니다.""" + print(f""" + 🔍 도구 호출 디버그: + - 도구: {context.tool_name} + - 에이전트: {context.agent.role if context.agent else '알 수 없음'} + - 작업: {context.task.description[:50] if context.task else '알 수 없음'}... + - 입력: {context.tool_input} + """) + return None + +@after_tool_call +def debug_tool_result(context: ToolCallHookContext) -> None: + """도구 결과를 디버그합니다.""" + if context.tool_result: + result_preview = context.tool_result[:200] + print(f"✅ 결과 미리보기: {result_preview}...") + else: + print("⚠️ 반환된 결과 없음") + return None +``` + +## 훅 관리 + +### 훅 등록 해제 + +```python +from crewai.hooks import ( + unregister_before_tool_call_hook, + unregister_after_tool_call_hook +) + +# 특정 훅 등록 해제 +def my_hook(context): + ... + +register_before_tool_call_hook(my_hook) +# 나중에... +success = unregister_before_tool_call_hook(my_hook) +print(f"등록 해제됨: {success}") +``` + +### 훅 지우기 + +```python +from crewai.hooks import ( + clear_before_tool_call_hooks, + clear_after_tool_call_hooks, + clear_all_tool_call_hooks +) + +# 특정 훅 타입 지우기 +count = clear_before_tool_call_hooks() +print(f"{count}개의 전(before) 훅이 지워졌습니다") + +# 모든 도구 훅 지우기 +before_count, after_count = clear_all_tool_call_hooks() +print(f"{before_count}개의 전(before) 훅과 {after_count}개의 후(after) 훅이 지워졌습니다") +``` + +## 고급 패턴 + +### 조건부 훅 실행 + +```python +@before_tool_call +def conditional_blocking(context: ToolCallHookContext) -> bool | None: + """특정 조건에서만 차단합니다.""" + # 특정 에이전트에 대해서만 차단 + if context.agent and context.agent.role == "junior_agent": + if context.tool_name in ['delete_file', 'send_email']: + print(f"❌ 주니어 에이전트는 {context.tool_name}을(를) 사용할 수 없습니다") + return False + + # 특정 작업 중에만 차단 + if context.task and "민감한" in context.task.description.lower(): + if context.tool_name == 'web_search': + print("❌ 민감한 작업에서는 웹 검색이 차단됩니다") + return False + + return None +``` + +### 컨텍스트 인식 입력 수정 + +```python +@before_tool_call +def enhance_tool_inputs(context: ToolCallHookContext) -> None: + """에이전트 역할에 따라 컨텍스트를 추가합니다.""" + # 에이전트 역할에 따라 컨텍스트 추가 + if context.agent and context.agent.role == "researcher": + if context.tool_name == 'web_search': + # 연구원에 대한 도메인 제한 추가 + context.tool_input['domains'] = ['edu', 'gov', 'org'] + + # 작업에 따라 컨텍스트 추가 + if context.task and "긴급" in context.task.description.lower(): + if context.tool_name == 'send_email': + context.tool_input['priority'] = 'high' + + return None +``` + +## 모범 사례 + +1. **훅을 집중적으로 유지**: 각 훅은 단일 책임을 가져야 합니다 +2. **무거운 계산 피하기**: 훅은 모든 도구 호출마다 실행됩니다 +3. **오류를 우아하게 처리**: try-except를 사용하여 훅 실패 방지 +4. **타입 힌트 사용**: 더 나은 IDE 지원을 위해 `ToolCallHookContext` 활용 +5. **차단 조건 문서화**: 도구가 차단되는 시기/이유를 명확히 하세요 +6. **훅을 독립적으로 테스트**: 프로덕션에서 사용하기 전에 단위 테스트 +7. **테스트에서 훅 지우기**: 테스트 실행 간 `clear_all_tool_call_hooks()` 사용 +8. **제자리에서 수정**: 항상 `context.tool_input`을 제자리에서 수정하고 교체하지 마세요 +9. **중요한 결정 로깅**: 특히 도구 실행을 차단할 때 +10. **성능 고려**: 가능한 경우 비용이 많이 드는 검증을 캐시 + +## 오류 처리 + +```python +@before_tool_call +def safe_validation(context: ToolCallHookContext) -> bool | None: + try: + # 검증 로직 + if not validate_input(context.tool_input): + return False + except Exception as e: + print(f"⚠️ 훅 오류: {e}") + # 결정: 오류 발생 시 허용 또는 차단 + return None # 오류에도 불구하고 실행 허용 +``` + +## 타입 안전성 + +```python +from crewai.hooks import ToolCallHookContext, BeforeToolCallHookType, AfterToolCallHookType + +# 명시적 타입 주석 +def my_before_hook(context: ToolCallHookContext) -> bool | None: + return None + +def my_after_hook(context: ToolCallHookContext) -> str | None: + return None + +# 타입 안전 등록 +register_before_tool_call_hook(my_before_hook) +register_after_tool_call_hook(my_after_hook) +``` + +## 문제 해결 + +### 훅이 실행되지 않음 +- 크루 실행 전에 훅이 등록되었는지 확인 +- 이전 훅이 `False`를 반환했는지 확인 (실행 및 후속 훅 차단) +- 훅 시그니처가 예상 타입과 일치하는지 확인 + +### 입력 수정이 작동하지 않음 +- 제자리 수정 사용: `context.tool_input['key'] = value` +- 딕셔너리를 교체하지 마세요: `context.tool_input = {}` + +### 결과 수정이 작동하지 않음 +- 후 훅에서 수정된 문자열을 반환 +- `None`을 반환하면 원본 결과가 유지됩니다 +- 도구가 실제로 결과를 반환했는지 확인 + +### 도구가 예기치 않게 차단됨 +- 차단 조건에 대한 모든 전(before) 훅 확인 +- 훅 실행 순서 확인 +- 어떤 훅이 차단하는지 식별하기 위해 디버그 로깅 추가 + +## 결론 + +도구 호출 훅은 CrewAI에서 도구 실행을 제어하고 모니터링하는 강력한 기능을 제공합니다. 이를 사용하여 안전 가드레일, 승인 게이트, 입력 검증, 결과 정제, 로깅 및 분석을 구현하세요. 적절한 오류 처리 및 타입 안전성과 결합하면, 훅을 통해 포괄적인 관찰성을 갖춘 안전하고 프로덕션 준비가 된 에이전트 시스템을 구축할 수 있습니다. + diff --git a/docs/v1.15.1/ko/learn/using-annotations.mdx b/docs/v1.15.1/ko/learn/using-annotations.mdx new file mode 100644 index 000000000..e397a5b9b --- /dev/null +++ b/docs/v1.15.1/ko/learn/using-annotations.mdx @@ -0,0 +1,155 @@ +--- +title: "crew.py에서 어노테이션 사용하기" +description: "CrewAI에서 에이전트, 태스크, 컴포넌트를 올바르게 구조화하기 위해 어노테이션을 사용하는 방법을 알아보세요." +icon: "at" +mode: "wide" +--- + +이 가이드는 클래식 `crew.py` 파일에서 **agent**, **task**, 및 기타 구성 요소를 올바르게 참조하기 위해 어노테이션을 사용하는 방법을 설명합니다. + + +`crewai create crew `으로 만든 새 프로젝트는 JSON-first이며 `crew.jsonc`와 `agents/*.jsonc`를 사용합니다. 이 가이드는 `crewai create crew --classic`으로 만든 클래식 프로젝트, 기존 Python/YAML 프로젝트 마이그레이션, 또는 Python 데코레이터 제어가 필요한 경우에 사용하세요. + + +## 소개 + +CrewAI 프레임워크에서 어노테이션은 클래스와 메소드를 데코레이트하는 데 사용되며, crew의 다양한 컴포넌트에 메타데이터와 기능을 제공합니다. 클래식 Python/YAML 프로젝트에서는 `config/agents.yaml`, `config/tasks.yaml`을 로드하고 `Crew` 객체를 반환하는 코드를 구조화합니다. + +## 사용 가능한 어노테이션 + +CrewAI 프레임워크는 다음과 같은 어노테이션을 제공합니다: + +- `@CrewBase`: 메인 crew 클래스를 데코레이트할 때 사용합니다. +- `@agent`: Agent 객체를 정의하고 반환하는 메서드를 데코레이트합니다. +- `@task`: Task 객체를 정의하고 반환하는 메서드를 데코레이트합니다. +- `@crew`: Crew 객체를 생성하고 반환하는 메서드를 데코레이트합니다. +- `@llm`: Language Model 객체를 초기화하고 반환하는 메서드를 데코레이트합니다. +- `@tool`: Tool 객체를 초기화하고 반환하는 메서드를 데코레이트합니다. +- `@callback`: 콜백 메서드를 정의할 때 사용합니다. +- `@output_json`: JSON 데이터를 출력하는 메서드에 사용합니다. +- `@output_pydantic`: Pydantic 모델을 출력하는 메서드에 사용합니다. +- `@cache_handler`: 캐시 처리 메서드를 정의할 때 사용합니다. + +## 사용 예시 + +이러한 주석을 어떻게 사용하는지 예제를 통해 살펴보겠습니다: + +### 1. Crew Base 클래스 + +```python +@CrewBase +class LinkedinProfileCrew(): + """LinkedinProfile crew""" + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' +``` + +`@CrewBase` 어노테이션은 메인 crew 클래스를 데코레이트하는 데 사용됩니다. 이 클래스는 일반적으로 agent, task, 그리고 crew 자체를 생성하기 위한 구성과 메서드를 포함합니다. + + +`@CrewBase`는 단순히 클래스를 등록하는 것 이상을 처리합니다. + +- **구성 부트스트래핑:** 클래스 파일과 동일한 경로에서 `agents_config`와 `tasks_config`(기본값은 각각 `config/agents.yaml`, `config/tasks.yaml`)을 찾아 인스턴스화 시점에 불러오며, 파일이 없으면 빈 딕셔너리로 안전하게 대체합니다. +- **데코레이터 오케스트레이션:** `@agent`, `@task`, `@before_kickoff`, `@after_kickoff`로 표시된 메서드를 메모이즈하여 crew마다 한 번만 인스턴스화하고 선언 순서를 보장합니다. +- **후크 연결:** 보존된 킥오프 훅을 `@crew` 메서드가 반환하는 `Crew` 객체에 자동으로 연결하여 `.kickoff()` 호출 전후에 실행되도록 합니다. +- **MCP 연동:** 클래스에 `mcp_server_params`가 정의되어 있으면 `get_mcp_tools()`가 MCP 서버 어댑터를 지연 생성해 도구를 로드하고, 내부 after-kickoff 훅이 킥오프 종료 후 어댑터를 정리합니다. 어댑터 구성 방법은 [MCP 개요](/ko/mcp/overview)를 참고하세요. + + +### 2. 도구 정의 + +```python +@tool +def myLinkedInProfileTool(self): + return LinkedInProfileTool() +``` + +`@tool` 애너테이션은 도구 객체를 반환하는 메서드를 데코레이터할 때 사용됩니다. 이러한 도구들은 에이전트가 특정 작업을 수행할 때 사용할 수 있습니다. + +### 3. 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") +``` + +`@llm` 애노테이션은 Language Model 객체를 초기화하고 반환하는 메서드를 데코레이팅하는 데 사용됩니다. 이러한 LLM은 에이전트가 자연어 처리 작업을 수행할 때 사용됩니다. + +### 4. 에이전트 정의 + +```python +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'] + ) +``` + +`@agent` 어노테이션은 에이전트 객체를 정의하고 반환하는 메서드를 데코레이트할 때 사용됩니다. + +### 5. Task 정의 + +```python +@task +def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_linkedin_task'], + agent=self.researcher() + ) +``` + +`@task` 어노테이션은 Task 객체를 정의하고 반환하는 메서드를 데코레이트하는 데 사용됩니다. 이러한 메서드는 task 구성과 해당 task를 담당하는 agent를 지정합니다. + +### 6. Crew 생성 + +```python +@crew +def crew(self) -> Crew: + """Creates the LinkedinProfile crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +`@crew` 어노테이션은 `Crew` 객체를 생성하고 반환하는 메서드를 데코레이션하는 데 사용됩니다. 이 메서드는 모든 구성 요소(agents와 tasks)를 기능적인 crew로 조합합니다. + +## 클래식 YAML 구성 + +클래식 프로젝트에서 에이전트 구성은 일반적으로 YAML 파일에 저장됩니다. 아래는 연구원 에이전트에 대한 `agents.yaml` 파일 예시입니다. + +```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 +``` + +이 YAML 구성은 `LinkedinProfileCrew` 클래스에 정의된 연구원 에이전트에 해당합니다. 구성에는 에이전트의 역할, 목표, 배경 이야기와 사용하는 LLM 및 도구와 같은 기타 속성이 명시되어 있습니다. + +YAML 파일의 `llm`과 `tools`가 Python 클래스에서 `@llm` 및 `@tool`로 데코레이션된 메서드와 어떻게 대응되는지 주목하세요. + +## 모범 사례 + +- **일관성 있는 명명**: 메서드에 대해 명확하고 일관성 있는 명명 규칙을 사용하세요. 예를 들어, agent 메서드는 역할에 따라 이름을 지정할 수 있습니다(예: researcher, reporting_analyst). +- **환경 변수**: API 키와 같은 민감한 정보를 위해 환경 변수를 사용하세요. +- **유연성**: agent와 task를 쉽게 추가 및 제거할 수 있도록 crew를 유연하게 설계하세요. +- **YAML-코드 일치**: 클래식 프로젝트에서는 YAML 파일의 이름과 구조가 Python 코드의 데코레이터가 적용된 메서드와 정확히 일치하는지 확인하세요. + +이 지침을 따르고 어노테이션을 올바르게 사용하면 클래식 crew를 구조적이고 유지보수하기 쉽게 유지할 수 있습니다. 새 crew에는 [Crews](/ko/concepts/crews)의 JSON-first 구조를 권장합니다. diff --git a/docs/v1.15.1/ko/mcp/dsl-integration.mdx b/docs/v1.15.1/ko/mcp/dsl-integration.mdx new file mode 100644 index 000000000..33eb6f81e --- /dev/null +++ b/docs/v1.15.1/ko/mcp/dsl-integration.mdx @@ -0,0 +1,234 @@ +--- +title: MCP DSL 통합 +description: CrewAI의 간단한 DSL 구문을 사용하여 mcps 필드로 MCP 서버를 에이전트와 직접 통합하는 방법을 알아보세요. +icon: code +mode: "wide" +--- + +## 개요 + +CrewAI의 MCP DSL(Domain Specific Language) 통합은 에이전트를 MCP(Model Context Protocol) 서버에 연결하는 **가장 간단한 방법**을 제공합니다. 에이전트에 `mcps` 필드만 추가하면 CrewAI가 모든 복잡성을 자동으로 처리합니다. + + + 이는 대부분의 MCP 사용 사례에 **권장되는 접근 방식**입니다. 수동 연결 관리가 + 필요한 고급 시나리오의 경우 + [MCPServerAdapter](/ko/mcp/overview#advanced-mcpserveradapter)를 참조하세요. + + +## 기본 사용법 + +`mcps` 필드를 사용하여 에이전트에 MCP 서버를 추가하세요: + +```python +from crewai import Agent + +agent = Agent( + role="연구 보조원", + goal="연구 및 분석 업무 지원", + backstory="고급 연구 도구에 접근할 수 있는 전문가 보조원", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=research" + ] +) + +# MCP 도구들이 이제 자동으로 사용 가능합니다! +# 수동 연결 관리나 도구 구성이 필요 없습니다 +``` + +## 지원되는 참조 형식 + +### 외부 MCP 원격 서버 + +```python +# 기본 HTTPS 서버 +"https://api.example.com/mcp" + +# 인증이 포함된 서버 +"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" + +# 사용자 정의 경로가 있는 서버 +"https://services.company.com/api/v1/mcp" +``` + +### 특정 도구 선택 + +`#` 구문을 사용하여 서버에서 특정 도구를 선택하세요: + +```python +# 날씨 서버에서 예보 도구만 가져오기 +"https://weather.api.com/mcp#get_forecast" + +# Exa에서 검색 도구만 가져오기 +"https://mcp.exa.ai/mcp?api_key=your_key#web_search_exa" +``` + +### 연결된 MCP 통합 + +CrewAI 카탈로그에서 MCP 서버를 연결하거나 직접 가져올 수 있습니다. 계정에 연결한 후 슬러그로 참조하세요: + +```python +# 모든 도구가 포함된 연결된 MCP +"snowflake" + +# 연결된 MCP의 특정 도구 +"stripe#list_invoices" + +# 여러 연결된 MCP +mcps=[ + "snowflake", + "stripe", + "github" +] +``` + +## 완전한 예제 + +다음은 여러 MCP 서버를 사용하는 완전한 예제입니다: + +```python +from crewai import Agent, Task, Crew, Process + +# 다중 MCP 소스를 가진 에이전트 생성 +multi_source_agent = Agent( + role="다중 소스 연구 분석가", + goal="다중 데이터 소스를 사용한 종합적인 연구 수행", + backstory="""웹 검색, 날씨 데이터, 금융 정보, + 학술 연구 도구에 접근할 수 있는 전문가 연구원""", + mcps=[ + # 외부 MCP 서버 + "https://mcp.exa.ai/mcp?api_key=your_exa_key&profile=research", + "https://weather.api.com/mcp#get_current_conditions", + + # 카탈로그에서 연결된 MCP + "snowflake", + "stripe#list_invoices", + "github#search_repositories" + ] +) + +# 종합적인 연구 작업 생성 +research_task = Task( + description="""AI 에이전트가 비즈니스 생산성에 미치는 영향을 연구하세요. + 원격 근무에 대한 현재 날씨 영향, 금융 시장 트렌드, + AI 에이전트 프레임워크에 대한 최근 학술 발표를 포함하세요.""", + expected_output="""다음을 다루는 종합 보고서: + 1. AI 에이전트 비즈니스 영향 분석 + 2. 원격 근무를 위한 날씨 고려사항 + 3. AI 관련 금융 시장 트렌드 + 4. 학술 연구 인용 및 통찰 + 5. 경쟁 환경 분석""", + agent=multi_source_agent +) + +# crew 생성 및 실행 +research_crew = Crew( + agents=[multi_source_agent], + tasks=[research_task], + process=Process.sequential, + verbose=True +) + +result = research_crew.kickoff() +print(f"{len(multi_source_agent.mcps)}개의 MCP 데이터 소스로 연구 완료") +``` + +## 주요 기능 + +- 🔄 **자동 도구 발견**: 도구들이 자동으로 발견되고 통합됩니다 +- 🏷️ **이름 충돌 방지**: 서버 이름이 도구 이름에 접두사로 붙습니다 +- ⚡ **성능 최적화**: 스키마 캐싱과 온디맨드 연결 +- 🛡️ **오류 복원력**: 사용할 수 없는 서버의 우아한 처리 +- ⏱️ **타임아웃 보호**: 내장 타임아웃으로 연결 중단 방지 +- 📊 **투명한 통합**: 기존 CrewAI 기능과 완벽한 연동 + +## 오류 처리 + +MCP DSL 통합은 복원력 있게 설계되었습니다: + +```python +agent = Agent( + role="복원력 있는 에이전트", + goal="서버 문제에도 불구하고 작업 계속", + backstory="장애를 우아하게 처리하는 에이전트", + mcps=[ + "https://reliable-server.com/mcp", # 작동할 것 + "https://unreachable-server.com/mcp", # 우아하게 건너뛸 것 + "https://slow-server.com/mcp", # 우아하게 타임아웃될 것 + "snowflake" # 카탈로그에서 연결된 MCP + ] +) +# 에이전트는 작동하는 서버의 도구를 사용하고 실패한 서버에 대한 경고를 로그에 남깁니다 +``` + +## 성능 기능 + +### 자동 캐싱 + +도구 스키마는 성능 향상을 위해 5분간 캐시됩니다: + +```python +# 첫 번째 에이전트 생성 - 서버에서 도구 발견 +agent1 = Agent(role="첫 번째", goal="테스트", backstory="테스트", + mcps=["https://api.example.com/mcp"]) + +# 두 번째 에이전트 생성 (5분 이내) - 캐시된 도구 스키마 사용 +agent2 = Agent(role="두 번째", goal="테스트", backstory="테스트", + mcps=["https://api.example.com/mcp"]) # 훨씬 빠릅니다! +``` + +### 온디맨드 연결 + +도구 연결은 실제로 사용될 때만 설정됩니다: + +```python +# 에이전트 생성은 빠름 - 아직 MCP 연결을 만들지 않음 +agent = Agent( + role="온디맨드 에이전트", + goal="도구를 효율적으로 사용", + backstory="필요할 때만 연결하는 효율적인 에이전트", + mcps=["https://api.example.com/mcp"] +) + +# MCP 연결은 도구가 실제로 실행될 때만 만들어집니다 +# 이는 연결 오버헤드를 최소화하고 시작 성능을 개선합니다 +``` + +## 모범 사례 + +### 1. 가능하면 특정 도구 사용 + +```python +# 좋음 - 필요한 도구만 가져오기 +mcps=["https://weather.api.com/mcp#get_forecast"] + +# 덜 효율적 - 서버의 모든 도구 가져오기 +mcps=["https://weather.api.com/mcp"] +``` + +### 2. 인증을 안전하게 처리 + +```python +import os + +# 환경 변수에 API 키 저장 +exa_key = os.getenv("EXA_API_KEY") +exa_profile = os.getenv("EXA_PROFILE") + +agent = Agent( + role="안전한 에이전트", + goal="MCP 도구를 안전하게 사용", + backstory="보안을 고려하는 에이전트", + mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"] +) +``` + +### 3. 서버 장애 계획 + +```python +# 항상 백업 옵션 포함 +mcps=[ + "https://primary-api.com/mcp", # 주요 선택 + "https://backup-api.com/mcp", # 백업 옵션 + "snowflake" # 연결된 MCP 폴백 +] +``` diff --git a/docs/v1.15.1/ko/mcp/multiple-servers.mdx b/docs/v1.15.1/ko/mcp/multiple-servers.mdx new file mode 100644 index 000000000..dfd85a7f7 --- /dev/null +++ b/docs/v1.15.1/ko/mcp/multiple-servers.mdx @@ -0,0 +1,65 @@ +--- +title: 여러 MCP 서버에 연결하기 +description: CrewAI에서 MCPServerAdapter를 사용하여 여러 MCP 서버에 동시에 연결하고 해당 도구를 집계하는 방법을 알아봅니다. +icon: layer-group +mode: "wide" +--- + +## 개요 + +`crewai-tools`의 `MCPServerAdapter`는 여러 MCP 서버에 동시에 연결할 수 있게 해줍니다. 이는 에이전트가 서로 다른 서비스나 환경에 분산된 도구에 접근해야 할 때 유용합니다. 어댑터는 지정된 모든 서버에서 도구를 집계하여 CrewAI 에이전트가 사용할 수 있게 합니다. + +## 구성 + +여러 서버에 연결하려면 서버 파라미터 딕셔너리의 리스트를 `MCPServerAdapter`에 제공합니다. 리스트에 있는 각 딕셔너리는 하나의 MCP 서버에 대한 파라미터를 정의해야 합니다. + +각 서버에 대해 지원되는 transport 타입은 `stdio`, `sse`, 그리고 `streamable-http`입니다. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # Needed for Stdio example + +# 여러 MCP 서버의 파라미터 정의 +server_params_list = [ + # Streamable HTTP 서버 + { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" + }, + # SSE 서버 + { + "url": "http://localhost:8000/sse", + "transport": "sse" + }, + # StdIO 서버 + 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.") + +``` + +## 연결 관리 + +컨텍스트 매니저(`with` 문)를 사용할 때, `MCPServerAdapter`는 구성된 MCP 서버와의 모든 연결의 라이프사이클(시작 및 종료)을 관리합니다. 이를 통해 리소스 관리를 단순화하고, 컨텍스트를 종료할 때 모든 연결이 적절하게 닫히도록 보장할 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/mcp/overview.mdx b/docs/v1.15.1/ko/mcp/overview.mdx new file mode 100644 index 000000000..22687080b --- /dev/null +++ b/docs/v1.15.1/ko/mcp/overview.mdx @@ -0,0 +1,341 @@ +--- +title: "CrewAI에서 MCP 서버를 도구로 활용하기" +description: "`crewai-tools` 라이브러리를 사용하여 MCP 서버를 CrewAI agent에 도구로 통합하는 방법을 알아봅니다." +icon: plug +mode: "wide" +--- + +## 개요 + +[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP)는 AI 에이전트가 MCP 서버로 알려진 외부 서비스와 통신함으로써 LLM에 컨텍스트를 제공할 수 있도록 표준화된 방식을 제공합니다. + +CrewAI는 MCP 통합을 위한 **두 가지 접근 방식**을 제공합니다: + +### 🚀 **새로운 기능: 간단한 DSL 통합** (권장) + +에이전트에 `mcps` 필드를 직접 사용하여 완벽한 MCP 도구 통합을 구현하세요: + +```python +from crewai import Agent + +agent = Agent( + role="연구 분석가", + goal="정보를 연구하고 분석", + backstory="외부 도구에 접근할 수 있는 전문가 연구원", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key", # 외부 MCP 서버 + "https://api.weather.com/mcp#get_forecast", # 서버의 특정 도구 + "snowflake", # 카탈로그에서 연결된 MCP + "stripe#list_invoices" # 연결된 MCP의 특정 도구 + ] +) +# MCP 도구들이 이제 자동으로 에이전트에서 사용 가능합니다! +``` + +### 🔧 **고급: MCPServerAdapter** (복잡한 시나리오용) + +수동 연결 관리가 필요한 고급 사용 사례의 경우 `crewai-tools` 라이브러리는 `MCPServerAdapter` 클래스를 제공합니다. + +현재 다음과 같은 전송 메커니즘을 지원합니다: + +- **HTTPS**: 원격 서버용 (HTTPS를 통한 보안 통신) +- **Server-Sent Events (SSE)**: 원격 서버용 (서버에서 클라이언트로의 일방향, 실시간 데이터 스트리밍, HTTP 기반) +- **Streamable HTTP**: 원격 서버용 (유연하며 잠재적으로 양방향 통신이 가능, 주로 SSE를 활용한 서버-클라이언트 스트림 제공, HTTP 기반) + +## 비디오 튜토리얼 + +CrewAI와 MCP 통합에 대한 종합적인 안내를 위해 이 비디오 튜토리얼을 시청하세요: + + + +## 설치 + +`crewai-tools`와 함께 MCP를 사용하기 전에, 아래 명령어를 통해 `mcp` 추가 `crewai-tools` 종속성을 설치해야 합니다: + +```shell +uv pip install 'crewai-tools[mcp]' +``` + +## 주요 개념 및 시작하기 + +`crewai-tools`의 `MCPServerAdapter` 클래스는 MCP 서버에 연결하고 해당 도구들을 CrewAI 에이전트에서 사용할 수 있도록 하는 기본 방법입니다. 다양한 전송 메커니즘을 지원하며 연결 관리를 간소화합니다. + +파이썬 컨텍스트 매니저(`with` 문)를 사용하는 것이 `MCPServerAdapter`를 위한 **권장 방법**입니다. 이를 통해 MCP 서버와의 연결 시작 및 종료가 자동으로 처리됩니다. + +## 연결 구성 + +`MCPServerAdapter`는 연결 동작을 맞춤화할 수 있는 여러 구성 옵션을 지원합니다: + +- **`connect_timeout`** (선택 사항): MCP 서버에 연결을 설정하기 위해 대기할 최대 시간(초 단위)입니다. 명시하지 않으면 기본값은 30초입니다. 응답 시간이 가변적인 원격 서버에 특히 유용합니다. + +```python +# 사용자 지정 연결 타임아웃 예시 +with MCPServerAdapter(server_params, connect_timeout=60) as tools: + # 60초 이내에 연결이 설정되지 않으면 타임아웃 발생 + pass +``` + +```python +from crewai import Agent +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # Stdio 서버용 + +# 예시 server_params (서버 유형에 따라 하나 선택): +# 1. Stdio 서버: +server_params=StdioServerParameters( + command="python3", + args=["servers/your_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +# 2. SSE 서버: +server_params = { + "url": "http://localhost:8000/sse", + "transport": "sse" +} + +# 3. 스트림 가능 HTTP 서버: +server_params = { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" +} + +# 예시 사용법 (server_params 설정 후 주석 해제 및 적용): +with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + my_agent = Agent( + role="MCP Tool User", + goal="MCP 서버의 도구를 활용합니다.", + backstory="나는 MCP 서버에 연결하여 해당 도구를 사용할 수 있습니다.", + tools=mcp_tools, # 불러온 도구를 Agent에 전달 + reasoning=True, + verbose=True + ) + # ... 나머지 crew 설정 ... +``` + +이 일반적인 패턴은 도구를 통합하는 방법을 보여줍니다. 각 transport에 맞춘 구체적인 예시는 아래의 상세 가이드를 참고하세요. + +## 필터링 도구 + +도구를 필터링하는 방법에는 두 가지가 있습니다: + +1. 딕셔너리 스타일의 인덱싱을 사용하여 특정 도구에 접근하기. +2. 도구 이름 목록을 `MCPServerAdapter` 생성자에 전달하기. + +### 딕셔너리 스타일 인덱싱을 사용하여 특정 도구에 접근하기 + +```python +with MCPServerAdapter(server_params, connect_timeout=60) 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"]], # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +### `MCPServerAdapter` 생성자에 도구 이름의 리스트를 전달하세요. + +```python +with MCPServerAdapter(server_params, "tool_name", connect_timeout=60) 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, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +## CrewBase와 함께 사용하기 + +CrewBase 클래스 내에서 MCPServer 도구를 사용하려면 `get_mcp_tools` 메서드를 사용하세요. 서버 구성은 `mcp_server_params` 속성을 통해 제공되어야 합니다. 단일 구성 또는 여러 서버 구성을 리스트 형태로 전달할 수 있습니다. + +```python +@CrewBase +class CrewWithMCP: + # ... 에이전트 및 작업 구성 파일 정의 ... + + mcp_server_params = [ + # 스트리머블 HTTP 서버 + { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" + }, + # SSE 서버 + { + "url": "http://localhost:8000/sse", + "transport": "sse" + }, + # 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()) # 모든 사용 가능한 도구 가져오기 + + # ... 나머지 crew 설정 ... +``` + + +`@CrewBase`로 데코레이션된 클래스에서는 어댑터 수명 주기가 자동으로 관리됩니다. + +- `get_mcp_tools()`가 처음 호출될 때 공유 `MCPServerAdapter`가 지연 생성되며 crew 내 모든 에이전트가 이를 재사용합니다. +- `.kickoff()`가 끝나면 `@CrewBase`가 주입한 after-kickoff 훅이 어댑터를 종료하므로 별도의 정리 코드가 필요 없습니다. +- `mcp_server_params`를 지정하지 않으면 `get_mcp_tools()`는 빈 리스트를 반환하여 MCP 설정 여부와 상관없이 동일한 코드 경로를 사용할 수 있습니다. + +따라서 여러 에이전트에서 `get_mcp_tools()`를 호출하거나 환경에 따라 MCP 사용을 토글하더라도 안전하게 동작합니다. + + + +### 연결 타임아웃 구성 + +`mcp_connect_timeout` 클래스 속성을 설정하여 MCP 서버의 연결 타임아웃을 구성할 수 있습니다. 타임아웃을 지정하지 않으면 기본값으로 30초가 사용됩니다. + +```python +@CrewBase +class CrewWithMCP: + mcp_server_params = [...] + mcp_connect_timeout = 60 # 모든 MCP 연결에 60초 타임아웃 + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +```python +@CrewBase +class CrewWithDefaultTimeout: + mcp_server_params = [...] + # mcp_connect_timeout 지정하지 않음 - 기본 30초 사용 + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +### 도구 필터링 + +`get_mcp_tools` 메서드에 도구 이름의 리스트를 전달하여, 에이전트에 제공되는 도구를 필터링할 수 있습니다. + +```python +@agent +def another_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # 특정 도구만 가져오기 + ) +``` + +타임아웃 구성은 crew 내의 모든 MCP 도구 호출에 적용됩니다: + +```python +@CrewBase +class CrewWithCustomTimeout: + mcp_server_params = [...] + mcp_connect_timeout = 90 # 모든 MCP 연결에 90초 타임아웃 + + @agent + def filtered_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # 사용자 지정 타임아웃으로 특정 도구 + ) +``` + +## MCP 통합 탐색 + + + + 표준 입력/출력을 통해 로컬 MCP 서버에 연결합니다. 스크립트와 로컬 실행 + 파일에 이상적입니다. + + + 실시간 데이터 스트리밍을 위해 Server-Sent Events를 사용하여 원격 MCP 서버와 + 통합합니다. + + + 유연한 스트림 가능한 HTTP를 활용하여 원격 MCP 서버와 안정적으로 통신할 수 + 있습니다. + + + 하나의 어댑터를 사용하여 여러 MCP 서버의 도구를 동시에 통합할 수 있습니다. + + + 에이전트를 안전하게 보호하기 위한 MCP 통합의 중요한 보안 모범 사례를 + 검토하세요. + + + +CrewAI와의 MCP 통합에 대한 전체 데모와 예제를 보려면 이 저장소를 확인하세요! 👇 + + + CrewAI MCP 데모 + + +## MCP와 함께 안전하게 사용하기 + + + 항상 MCP 서버를 사용하기 전에 해당 서버를 신뢰할 수 있는지 확인하세요. + + +#### 보안 경고: DNS 리바인딩 공격 + +SSE 전송은 적절하게 보안되지 않은 경우 DNS 리바인딩 공격에 취약할 수 있습니다. +이를 방지하려면 다음을 수행하세요: + +1. **항상 Origin 헤더를 검증**하여 들어오는 SSE 연결이 예상한 소스에서 오는지 확인합니다. +2. **서버를 모든 네트워크 인터페이스**(0.0.0.0)에 바인딩하는 것을 피하고, 로컬에서 실행할 때는 localhost(127.0.0.1)에만 바인딩합니다. +3. **모든 SSE 연결에 대해 적절한 인증을 구현**합니다. + +이러한 보호 조치가 없으면 공격자가 원격 웹사이트에서 로컬 MCP 서버와 상호작용하기 위해 DNS 리바인딩을 사용할 수 있습니다. + +자세한 내용은 [Anthropic의 MCP 전송 보안 문서](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)를 참고하세요. + +### 제한 사항 + +- **지원되는 프리미티브**: 현재 `MCPServerAdapter`는 주로 MCP `tools`를 어댑팅하는 기능을 지원합니다. 다른 MCP 프리미티브(예: `prompts` 또는 `resources`)는 현재 이 어댑터를 통해 CrewAI 컴포넌트로 직접 통합되어 있지 않습니다. +- **출력 처리**: 어댑터는 일반적으로 MCP tool의 주요 텍스트 출력(예: `.content[0].text`)을 처리합니다. 복잡하거나 멀티모달 출력의 경우 이 패턴에 맞지 않으면 별도의 커스텀 처리가 필요할 수 있습니다. diff --git a/docs/v1.15.1/ko/mcp/security.mdx b/docs/v1.15.1/ko/mcp/security.mdx new file mode 100644 index 000000000..dd32747f5 --- /dev/null +++ b/docs/v1.15.1/ko/mcp/security.mdx @@ -0,0 +1,166 @@ +--- +title: MCP 보안 고려사항 +description: MCP 서버를 CrewAI agent와 통합할 때 중요한 보안 모범 사례에 대해 알아보세요. +icon: lock +mode: "wide" +--- + +## 개요 + + +MCP 보안에서 가장 중요한 측면은 **신뢰**입니다. 신뢰할 수 있다고 확신하는 MCP 서버에만 CrewAI 에이전트를 **연결해야 합니다**. + + +CrewAI 에이전트에 MCP(Model Context Protocol) 서버와 같은 외부 서비스를 통합할 때 보안이 가장 중요합니다. +MCP 서버는 노출한 도구를 기반으로 코드를 실행하거나 데이터에 접근하거나 다른 시스템과 상호작용할 수 있습니다. +응용 프로그램과 데이터를 보호하기 위해 그 영향력을 이해하고 모범 사례를 따르는 것이 매우 중요합니다. + +### 위험 + +- 에이전트가 실행 중인 머신에서 임의의 코드를 실행할 수 있습니다(특히 서버가 실행되는 명령어를 제어할 수 있는 `Stdio` 전송 방식을 사용할 경우). +- 에이전트나 그 환경에서 민감한 데이터가 노출될 수 있습니다. +- 예기치 않은 방식으로 에이전트의 동작이 조작되어, 본인 동의 없이 API 호출이 이루어질 수 있습니다. +- 정교한 프롬프트 인젝션 기법(아래 참조)을 통해 에이전트의 reasoning 프로세스가 탈취될 수 있습니다. + +### 1. MCP 서버 신뢰하기 + + +**신뢰할 수 있는 MCP 서버에만 연결하십시오.** + + +`MCPServerAdapter`를 MCP 서버에 연결하도록 구성하기 전에 다음을 반드시 확인하십시오: +- **서버 운영자는 누구입니까?** 신뢰할 수 있는 잘 알려진 서비스이거나 여러분이 직접 제어하는 내부 서버입니까? +- **어떤 도구를 노출합니까?** 도구의 기능을 이해해야 합니다. 공격자가 제어권을 얻거나 서버 자체가 악의적이라면 이 도구들이 오용될 수 있습니까? +- **어떤 데이터를 접근하거나 처리합니까?** MCP 서버에 전송되거나 처리될 수 있는 민감한 정보가 있는지 반드시 파악하십시오. + +특히 에이전트가 민감한 작업이나 데이터를 처리하는 경우, 알 수 없거나 검증되지 않은 MCP 서버에는 연결하지 마십시오. + +### 2. Tool Metadata를 통한 보안 프롬프트 인젝션: "Model Control Protocol"의 위험성 + +중요하면서도 미묘한 위험 중 하나는 툴 메타데이터를 통한 프롬프트 인젝션 가능성입니다. 그 과정은 다음과 같습니다: + +1. CrewAI 에이전트가 MCP 서버에 연결하면, 일반적으로 사용 가능한 툴 목록을 요청합니다. +2. MCP 서버는 각 툴에 대한 메타데이터를 이름, 설명, 파라미터 설명과 함께 응답합니다. +3. 에이전트의 언더라이잉 Language Model(LLM)은 해당 메타데이터를 활용해 언제, 어떻게 툴을 사용할지 이해합니다. 이 메타데이터는 LLM의 시스템 프롬프트나 컨텍스트에 포함되는 경우가 많습니다. +4. 악의적인 MCP 서버는 툴의 메타데이터(이름, 설명 등)에 숨겨진 또는 노골적인 명령어를 삽입할 수 있습니다. 이러한 명령은 프롬프트 인젝션으로 동작하여, LLM에게 특정 방식으로 동작하라고 지시하거나, 민감한 정보를 공개하게 하거나, 악의적인 행동을 수행하게 만들 수 있습니다. + +**중요하게도, 이 공격은 에이전트가 해당 툴을 실제로 *사용*하지 않더라도 단순히 악성 서버에 연결해 툴 목록을 조회하는 것만으로도 발생할 수 있습니다.** 악의적인 메타데이터에 노출되는 것만으로도 에이전트의 행동이 손상될 수 있습니다. + +**완화 방안:** + +* **신뢰되지 않은 서버에 대한 극도의 주의:** 반복합니다. *완전히 신뢰하지 않는 MCP 서버에는 절대 연결하지 마십시오.* 메타데이터 인젝션의 위험성 때문에 이 점이 매우 중요합니다. + +### Stdio 전송 보안 + +Stdio(표준 입력/출력) 전송은 일반적으로 CrewAI 애플리케이션과 동일한 머신에서 실행되는 로컬 MCP 서버에 사용됩니다. + +- **프로세스 격리**: 기본적으로 네트워크에 노출되지 않아 일반적으로 더 안전하지만, `StdioServerParameters`로 실행되는 스크립트나 명령어가 신뢰할 수 있는 소스에서 왔으며 적절한 파일 시스템 권한을 가지고 있는지 확인해야 합니다. 악의적인 Stdio 서버 스크립트는 여전히 로컬 시스템에 피해를 줄 수 있습니다. +- **입력값 정제**: Stdio 서버 스크립트가 에이전트 상호작용에서 파생된 복잡한 입력을 받는 경우, 스크립트 자체에서 이러한 입력값을 정제하여 명령어 삽입이나 스크립트 논리 내 다른 취약점이 발생하지 않도록 해야 합니다. +- **리소스 제한**: 로컬 Stdio 서버 프로세스는 로컬 자원(CPU, 메모리)을 소모하므로, 반드시 정상적으로 동작하는지, 시스템 자원을 소모하지 않는지 주의 깊게 관리해야 합니다. + +### 혼동된 대리인(Confused Deputy) 공격 + +[혼동된 대리인 문제(Confused Deputy Problem)](https://en.wikipedia.org/wiki/Confused_deputy_problem)는 고전적인 보안 취약점으로, MCP 통합에서 특히 MCP 서버가 다른 서드파티 서비스(예: Google Calendar, GitHub)와 OAuth 2.0을 통한 인증을 할 때 프록시 역할을 할 경우 나타날 수 있습니다. + +**시나리오:** + +1. MCP 서버(여기서는 `MCP-Proxy`라고 부르겠습니다)가 에이전트가 `ThirdPartyAPI`와 상호작용할 수 있도록 허용합니다. +2. `MCP-Proxy`는 `ThirdPartyAPI`의 인증 서버와 통신할 때 자체의 단일 고정 `client_id`를 사용합니다. +3. 사용자(즉, 여러분)는 정당하게 `MCP-Proxy`가 여러분을 대신해 `ThirdPartyAPI`에 접근할 수 있도록 승인합니다. 이 과정에서 `ThirdPartyAPI`의 인증 서버는 여러분의 브라우저에 `MCP-Proxy`의 `client_id`에 대한 동의 쿠키를 설정할 수 있습니다. +4. 공격자는 악의적인 링크를 만듭니다. 이 링크는 `MCP-Proxy`와의 OAuth 플로우를 시작하지만, `ThirdPartyAPI`의 인증 서버를 속이도록 설계되어 있습니다. +5. 여러분이 이 링크를 클릭하고, `ThirdPartyAPI`의 인증 서버가 이미 존재하는 `MCP-Proxy`의 `client_id`에 대한 동의 쿠키를 확인하면, 다시 동의를 묻지 않고 *건너뛰기* 할 수 있습니다. +6. 그러면 `MCP-Proxy`가 (공격자에게) 인증 코드를 전달하도록 속거나, 공격자가 여러분을 가장해 `MCP-Proxy`에 사용할 수 있는 MCP 인증 코드를 받게 될 수 있습니다. + +**대응 방안(주로 MCP 서버 개발자용):** + +* 다운스트림 서비스를 위해 정적 client ID를 사용하는 MCP 프록시 서버는 **각 클라이언트 애플리케이션 또는 에이전트별**로 명시적인 사용자 동의를 반드시 받아야 합니다. 이 동의는 서드파티 서비스와의 OAuth 플로우 시작 *이전*에 이루어져야 하며, `MCP-Proxy` 자체가 동의 화면을 표시하도록 해야 합니다. + +**CrewAI 사용자 주의사항:** + +* MCP 서버가 여러 번 OAuth 인증을 위해 리디렉션하는 경우, 특히 예상치 않거나 요청된 권한이 과도하게 넓다면 주의해야 합니다. +* 자신과 프록시할 수 있는 서드파티 서비스의 구분을 명확하게 하는 MCP 서버를 선호하는 것이 좋습니다. + +### 원격 전송 보안 (SSE & Streamable HTTP) + +Server-Sent Events(SSE) 또는 Streamable HTTP를 통해 원격 MCP 서버에 연결할 때, 표준 웹 보안 관행이 필수적입니다. + +### SSE 보안 고려사항 + +### a. DNS 리바인딩 공격 (특히 SSE의 경우) + + +**DNS 리바인딩 공격으로부터 보호하세요.** + + +DNS 리바인딩은 공격자가 제어하는 웹사이트가 동일 출처 정책(same-origin policy)을 우회하여 사용자의 로컬 네트워크(예: `localhost`) 또는 인트라넷에 있는 서버에 요청을 보낼 수 있도록 합니다. 이는 MCP 서버를 로컬(예: 개발용)로 실행하고 브라우저와 유사한 환경에서 agent를 사용하는 경우(일반적인 CrewAI 백엔드 구성에서는 드물지만) 또는 MCP 서버가 내부 네트워크상에 있을 경우 특히 위험할 수 있습니다. + +**MCP 서버 구현자를 위한 대응 전략:** +- **`Origin` 및 `Host` 헤더 검증**: MCP 서버(특히 SSE 서버)는 `Origin` 및/또는 `Host` HTTP 헤더를 검증하여 요청이 예상되는 도메인/클라이언트로부터 오는지 확인해야 합니다. +- **`localhost`(127.0.0.1)로 바인딩**: 개발을 위해 MCP 서버를 로컬에서 실행할 때는 `0.0.0.0` 대신 `127.0.0.1`로 바인딩하세요. 이를 통해 네트워크의 다른 기기에서 접근하지 못하도록 막을 수 있습니다. +- **인증(Authentication)**: MCP 서버가 공개된 익명 접근을 목적으로 하지 않는 한 모든 연결에 대해 인증을 요구하세요. + +### b. HTTPS 사용 + +- **전송 중 데이터 암호화**: 원격 MCP 서버의 URL에는 항상 HTTPS(HTTP Secure)를 사용하세요. 이는 CrewAI 애플리케이션과 MCP 서버 간의 통신을 암호화하여 도청 및 중간자 공격으로부터 보호합니다. `MCPServerAdapter`는 URL에 제공된 스킴(`http` 또는 `https`)을 그대로 따릅니다. + +### c. 토큰 패스스루(Token Passthrough) (안티 패턴) + +이 문제는 주로 MCP 서버 개발자들에게 해당되지만, 이를 이해하는 것은 안전한 서버를 선택하는 데 도움이 됩니다. + +"토큰 패스스루"란, MCP 서버가 CrewAI agent로부터 받은 액세스 토큰(예를 들어 `ServiceA`를 위한 토큰일 수도 있음)을 별도의 적절한 검증 없이 다른 하위 API(`ServiceB`)로 그대로 전달하는 것을 의미합니다. 특히, `ServiceB`(또는 MCP 서버 자체)는 명시적으로 *자신들을 위해* 발급된 토큰만 받아야 합니다(즉, 토큰 내의 'audience' 클레임이 해당 서버/서비스와 일치해야 함). + +**위험성:** + +* MCP 서버나 하위 API의 보안 제어(예 : 속도 제한, 세밀한 권한 부여 등)를 우회할 수 있습니다. +* 감사 추적 및 책임성을 저해할 수 있습니다. +* 탈취된 토큰의 악용을 허용할 수 있습니다. + +**대응 방안 (MCP 서버 개발자용):** + +* MCP 서버는 **명시적으로 자신을 위해 발급된 토큰만** 받아야 합니다. 토큰의 audience 클레임을 반드시 검증해야 합니다. + +**CrewAI 사용자에게 미치는 영향:** + +* 사용자가 직접적으로 제어할 수는 없지만, 보안 모범 사례를 준수하는 잘 설계된 MCP 서버에 연결하는 것이 중요함을 강조합니다. + +#### 인증 및 인가 + +- **신원 확인**: MCP 서버가 민감한 도구 또는 비공개 데이터에 대한 액세스를 제공하는 경우, 클라이언트(귀하의 CrewAI 애플리케이션)의 신원을 확인하기 위해 강력한 인증 메커니즘을 반드시 구현해야 합니다. 이는 API 키, OAuth 토큰 또는 기타 표준 방법을 포함할 수 있습니다. +- **최소 권한 원칙**: `MCPServerAdapter`에서 사용하는 자격 증명(있는 경우)은 필요한 도구에 접근하는 데 꼭 필요한 권한만 가지고 있도록 해야 합니다. + +### d. 입력 검증 및 정제 + +- **입력 검증은 매우 중요합니다**: MCP 서버는 에이전트로부터 받은 모든 입력을 처리하거나 도구에 전달하기 *전에* 철저하게 검증해야 합니다. 이는 많은 일반적인 취약점에 대한 1차 방어선입니다: + - **명령어 삽입:** 도구가 입력을 기반으로 셸 명령, SQL 쿼리 또는 기타 해석형 언어 문장을 구성하는 경우, 서버는 악의적 명령어 주입 및 실행을 방지하기 위해 이 입력을 꼼꼼하게 정제해야 합니다. + - **경로 탐색:** 도구가 입력 매개변수에 따라 파일에 접근하는 경우, 서버는 미허가 파일 또는 디렉터리에 접근하지 못하도록 이 경로를 검증 및 정제해야 합니다(예: `../` 시퀀스 차단). + - **데이터 타입 및 범위 검사:** 서버는 입력 데이터가 기대하는 데이터 타입(예: 문자열, 숫자, 불리언)에 부합하는지, 허용 범위 내에 있거나 정의된 형식(예: URL에 대한 정규식)에 맞는지 확인해야 합니다. + - **JSON 스키마 검증:** 모든 도구 매개변수는 정의된 JSON 스키마에 엄격하게 맞춰 검증되어야 합니다. 이를 통해 잘못된 요청을 조기에 차단할 수 있습니다. +- **클라이언트 측 인지**: 서버 측 검증이 가장 중요하지만, CrewAI 사용자는 특히 신뢰도가 낮은 또는 새로운 MCP 서버와 상호작용할 때 자신의 에이전트가 MCP 도구에 전달하도록 설계된 데이터에 각별히 유의해야 합니다. + +### e. 속도 제한 및 리소스 관리 + +- **오용 방지**: MCP 서버는 악의적(서비스 거부 공격 등)이든 비의도적(예: 잘못 구성된 agent가 과도한 요청을 보내는 경우)이든 오용을 방지하기 위해 속도 제한을 구현해야 합니다. +- **클라이언트 측 재시도**: 일시적인 네트워크 문제나 서버의 속도 제한이 예상될 경우, CrewAI 작업에서 합리적인 재시도 로직을 구현하되, 서버 부하를 가중시킬 수 있는 과도한 재시도는 피해야 합니다. + +## 4. 보안 MCP 서버 구현 권장 사항 (개발자용) + +CrewAI 에이전트가 연결할 수 있는 MCP 서버를 개발하고 있다면, 위의 내용에 추가하여 다음과 같은 모범 사례를 고려하세요: + +- **안전한 코딩 관행 준수**: 선택한 언어 및 프레임워크에 대한 표준 안전 코딩 원칙(예: OWASP Top 10)을 준수하세요. +- **최소 권한 원칙**: MCP 서버를 실행하는 프로세스(특히 `Stdio`의 경우)는 작업에 필요한 최소 권한만 보유하도록 하세요. 툴 자체도 자신의 기능 수행에 필요한 최소한의 권한만으로 동작해야 합니다. +- **종속성 관리**: 운영 체제 패키지, 언어 런타임, 써드파티 라이브러리 등 모든 서버 측 종속성을 최신 상태로 유지하여 알려진 취약점을 패치하세요. 취약한 종속성을 스캔하는 도구를 사용하세요. +- **안전한 기본값**: 서버와 그 도구를 기본적으로 안전하게 설계하세요. 예를 들어, 위험할 수 있는 기능은 기본적으로 꺼져 있거나 명확한 경고와 함께 명시적으로 opt-in 하도록 해야 합니다. +- **툴에 대한 접근 제어**: 인증 및 권한이 부여된 에이전트 또는 사용자만 특정 툴(특히 강력하거나 민감하거나 비용이 발생하는 툴)에 접근할 수 있도록 강력한 메커니즘을 구현하세요. +- **안전한 오류 처리**: 서버는 클라이언트에게 상세한 내부 오류 메시지, 스택 트레이스 또는 디버깅 정보를 노출해서는 안 됩니다. 이러한 정보는 내부 동작이나 잠재적 취약점을 드러낼 수 있습니다. 오류는 서버 측에서 진단을 목적으로 포괄적으로 기록하세요. +- **포괄적인 로깅 및 모니터링**: 보안 관련 이벤트(예: 인증 시도, 툴 호출, 오류, 권한 변경)에 대해 상세하게 로깅하세요. 이런 로그를 모니터링하여 의심스러운 활동이나 악용 패턴을 파악하세요. +- **MCP 인증 사양 준수**: 인증 및 권한 부여를 구현할 경우, [MCP Authorization specification](https://modelcontextprotocol.io/specification/draft/basic/authorization) 및 관련 [OAuth 2.0 security best practices](https://datatracker.ietf.org/doc/html/rfc9700)를 엄격히 준수하세요. +- **정기적인 보안 감사**: MCP 서버가 민감한 데이터를 처리하거나, 중요한 작업을 수행하거나, 대외적으로 노출된 경우 자격을 갖춘 전문가의 정기적인 보안 감사를 고려하세요. + +## 5. 추가 참고 자료 + +MCP 보안에 대한 자세한 내용은 공식 문서를 참고하세요: +- **[MCP 전송 보안](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)** + +이러한 보안 고려사항을 이해하고 모범 사례를 구현하면 CrewAI 프로젝트에서 MCP 서버의 강력한 기능을 안전하게 활용할 수 있습니다. +여기서 다루는 내용이 모든 것을 포괄하는 것은 아니지만, 가장 일반적이고 중요한 보안 문제들을 포함하고 있습니다. +위협은 계속 진화하기 때문에 지속적으로 정보를 확인하고 그에 맞춰 보안 조치를 조정하는 것이 중요합니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/mcp/sse.mdx b/docs/v1.15.1/ko/mcp/sse.mdx new file mode 100644 index 000000000..12b153612 --- /dev/null +++ b/docs/v1.15.1/ko/mcp/sse.mdx @@ -0,0 +1,151 @@ +--- +title: SSE 트랜스포트 +description: 서버 전송 이벤트(SSE)를 사용하여 CrewAI를 원격 MCP 서버에 연결하여 실시간 통신을 구현하는 방법을 알아보세요. +icon: wifi +mode: "wide" +--- + +## 개요 + +Server-Sent Events(SSE)는 웹 서버가 하나의 장기 실행 HTTP 연결을 통해 클라이언트에 업데이트를 전송할 수 있는 표준 방식을 제공합니다. MCP의 맥락에서 SSE는 원격 서버가 데이터(예: tool 응답)를 실시간으로 CrewAI 애플리케이션에 스트리밍하는 데 사용됩니다. + +## 주요 개념 + +- **원격 서버**: SSE는 원격에 호스팅된 MCP 서버에 적합합니다. +- **단방향 스트림**: 일반적으로 SSE는 서버에서 클라이언트로의 단방향 통신 채널입니다. +- **`MCPServerAdapter` 구성**: SSE의 경우, 서버의 URL을 제공하고 전송 유형을 지정해야 합니다. + +## SSE를 통한 연결 + +SSE 기반 MCP 서버에 연결하려면 연결 수명 주기를 관리하는 두 가지 주요 접근 방식을 사용할 수 있습니다. + +### 1. 완전 관리형 연결(권장) + +Python 컨텍스트 매니저(`with` 문)를 사용하는 것이 권장되는 접근 방식입니다. 이 방법은 SSE MCP 서버에 대한 연결의 생성과 종료를 자동으로 처리합니다. + +```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.") + +``` + + +`"http://localhost:8000/sse"`를 실제 SSE MCP 서버의 URL로 교체하십시오. + + +### 2. 수동 연결 라이프사이클 + +더 세밀한 제어가 필요한 경우, `MCPServerAdapter`의 연결 라이프사이클을 수동으로 관리할 수 있습니다. + + +연결이 종료되고 리소스가 해제되도록 반드시 `mcp_server_adapter.stop()`을 호출해야 합니다. `try...finally` 블록을 사용하는 것을 강력히 권장합니다. + + +```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.") + +``` + +## SSE를 위한 보안 고려사항 + + +**DNS 리바인딩 공격**: SSE 전송 방식은 MCP 서버가 적절하게 보안 조치되지 않은 경우 DNS 리바인딩 공격에 취약할 수 있습니다. 이로 인해 악의적인 웹사이트가 로컬 또는 인트라넷 기반 MCP 서버와 상호 작용할 수 있습니다. + + +이 위험을 완화하려면: +- MCP 서버 구현에서는 들어오는 SSE 연결의 **`Origin` 헤더를 검증**해야 합니다. +- 개발 환경에서 로컬 SSE MCP 서버를 실행할 때에는 모든 네트워크 인터페이스(`0.0.0.0`)가 아닌, **`localhost`(`127.0.0.1`)에만 바인딩**해야 합니다. +- 민감한 도구나 데이터를 노출하는 SSE 연결에는 **적절한 인증**을 구현해야 합니다. + +보안 모범 사례에 대한 포괄적인 개요는 [보안 고려사항](./security.mdx) 페이지와 공식 [MCP 전송 보안 문서](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)를 참고하시기 바랍니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/mcp/stdio.mdx b/docs/v1.15.1/ko/mcp/stdio.mdx new file mode 100644 index 000000000..b15e731b0 --- /dev/null +++ b/docs/v1.15.1/ko/mcp/stdio.mdx @@ -0,0 +1,135 @@ +--- +title: Stdio 전송 +description: Stdio(표준 입력/출력) 전송 메커니즘을 사용하여 CrewAI를 로컬 MCP 서버에 연결하는 방법을 알아보세요. +icon: server +mode: "wide" +--- + +## 개요 + +Stdio(표준 입력/출력) 트랜스포트는 `MCPServerAdapter`를 로컬 MCP 서버에 연결하기 위해 설계되었습니다. 이 MCP 서버는 표준 입력 및 출력 스트림을 통해 통신합니다. 이는 일반적으로 MCP 서버가 CrewAI 애플리케이션과 동일한 머신에서 실행되는 스크립트나 실행 파일일 때 사용됩니다. + +## 주요 개념 + +- **로컬 실행**: Stdio 전송은 MCP 서버를 위한 로컬에서 실행 중인 프로세스를 관리합니다. +- **`StdioServerParameters`**: `mcp` 라이브러리의 이 클래스는 Stdio 서버를 실행하기 위한 명령어, 인수, 환경 변수를 구성하는 데 사용됩니다. + +## Stdio를 통한 연결 + +연결 수명 주기를 관리하기 위한 두 가지 주요 접근 방식으로 Stdio 기반 MCP 서버에 연결할 수 있습니다. + +### 1. 완전 관리형 연결(권장) + +Python 컨텍스트 관리자(`with` 문)를 사용하는 것이 권장되는 방법입니다. 이 방식은 MCP 서버 프로세스의 시작과 컨텍스트 종료 시 자동 종료를 처리합니다. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +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]}") + + # Example: Using the tools from the Stdio MCP server in a CrewAI Agent + 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. 수동 연결 라이프사이클 + +Stdio MCP 서버 프로세스가 시작되고 중지되는 시점을 더 세밀하게 제어해야 하는 경우, `MCPServerAdapter`의 라이프사이클을 수동으로 관리할 수 있습니다. + + +서버 프로세스가 종료되고 자원이 해제되도록 **반드시** `mcp_server_adapter.stop()`을 호출해야 합니다. `try...finally` 블록을 사용하는 것을 강력히 추천합니다. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +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() # Manually start the connection and server process + tools = mcp_server_adapter.tools + print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}") + + # Example: Using the tools with your Agent, Task, Crew setup + 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() # Actual inputs depend on your tool + 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: # Check if connected before stopping + print("Stopping Stdio MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: # If adapter exists but not connected (e.g. start failed) + print("Stdio MCP server adapter was not connected. No stop needed or start failed.") + +``` + +플레이스홀더 경로 및 명령어를 실제 Stdio 서버 정보로 교체해야 합니다. `StdioServerParameters`의 `env` 파라미터는 +서버 프로세스용 환경 변수를 설정할 때 사용할 수 있습니다. 이는 서버의 동작을 구성하거나 필요한 경로(예: `PYTHONPATH`)를 제공하는 데 유용할 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/mcp/streamable-http.mdx b/docs/v1.15.1/ko/mcp/streamable-http.mdx new file mode 100644 index 000000000..b6293ef82 --- /dev/null +++ b/docs/v1.15.1/ko/mcp/streamable-http.mdx @@ -0,0 +1,136 @@ +--- +title: 스트리머블 HTTP 전송 +description: 유연한 스트리머블 HTTP 전송을 사용하여 CrewAI를 원격 MCP 서버에 연결하는 방법을 알아보세요. +icon: globe +mode: "wide" +--- + +## 개요 + +Streamable HTTP 전송은 원격 MCP 서버에 연결할 수 있는 유연한 방법을 제공합니다. 이는 종종 HTTP를 기반으로 구축되며, 요청-응답 및 스트리밍을 포함한 다양한 통신 패턴을 지원할 수 있습니다. 때때로 더 넓은 HTTP 상호작용 내에서 서버-클라이언트 스트림을 위해 Server-Sent Events(SSE)를 활용하기도 합니다. + +## 주요 개념 + +- **원격 서버**: 원격에 호스팅된 MCP 서버용으로 설계되었습니다. +- **유연성**: 단순 SSE보다 더 복잡한 상호작용 패턴을 지원할 수 있으며, 서버가 구현한 경우 양방향 통신도 가능할 수 있습니다. +- **`MCPServerAdapter` 구성**: MCP 통신을 위한 서버의 기본 URL을 제공하고, 전송 유형으로 `"streamable-http"`를 지정해야 합니다. + +## 스트리머블 HTTP를 통한 연결 + +Streamable HTTP MCP 서버와의 연결 라이프사이클을 관리하는 주요 방법에는 두 가지가 있습니다: + +### 1. 완전히 관리되는 연결(추천) + +추천되는 방법은 Python 컨텍스트 매니저(`with` 문)을 사용하는 것으로, 연결의 설정과 해제를 자동으로 처리합니다. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8001/mcp", # 실제 Streamable HTTP 서버 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.") + +``` +**참고:** `"http://localhost:8001/mcp"`은 실제 사용 중인 Streamable HTTP MCP 서버의 URL로 교체해야 합니다. + +### 2. 수동 연결 라이프사이클 + +보다 명시적인 제어가 필요한 시나리오에서는 `MCPServerAdapter` 연결을 직접 관리할 수 있습니다. + + +연결을 종료하고 리소스를 해제하려면 작업이 끝난 후 반드시 `mcp_server_adapter.stop()`을 호출하는 것이 **매우 중요**합니다. 이를 보장하는 가장 안전한 방법은 `try...finally` 블록을 사용하는 것입니다. + + +```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.") +``` + +## 보안 고려사항 + +Streamable HTTP 전송을 사용할 때는 일반적인 웹 보안 모범 사례가 매우 중요합니다: +- **HTTPS 사용**: 데이터 전송을 암호화하기 위해 항상 MCP 서버 URL에 HTTPS(HTTP Secure)를 사용하는 것이 좋습니다. +- **인증**: MCP 서버가 민감한 도구나 데이터를 노출하는 경우 강력한 인증 메커니즘을 구현하세요. +- **입력 검증**: MCP 서버가 모든 수신 요청과 매개변수를 반드시 검증하도록 하십시오. + +MCP 통합 보안에 대한 종합적인 안내는 [보안 고려사항](./security.mdx) 페이지와 공식 [MCP 전송 보안 문서](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)를 참고하시기 바랍니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/arize-phoenix.mdx b/docs/v1.15.1/ko/observability/arize-phoenix.mdx new file mode 100644 index 000000000..340652963 --- /dev/null +++ b/docs/v1.15.1/ko/observability/arize-phoenix.mdx @@ -0,0 +1,150 @@ +--- +title: Arize Phoenix +description: OpenTelemetry 및 OpenInference가 포함된 CrewAI용 Arize Phoenix 통합 +icon: magnifying-glass-chart +mode: "wide" +--- + +# Arize Phoenix 통합 + +이 가이드는 [OpenInference](https://github.com/openinference/openinference) SDK를 통해 OpenTelemetry를 사용하여 **Arize Phoenix**를 **CrewAI**와 통합하는 방법을 보여줍니다. 이 가이드를 완료하면 CrewAI agent를 추적하고 agent를 쉽게 디버그할 수 있습니다. + +> **Arize Phoenix란?** [Arize Phoenix](https://phoenix.arize.com)는 AI 애플리케이션을 위한 추적 및 평가 기능을 제공하는 LLM 가시성(observability) 플랫폼입니다. + +[![Phoenix와의 통합 영상 데모 보기](https://storage.googleapis.com/arize-assets/fixtures/setup_crewai.png)](https://www.youtube.com/watch?v=Yc5q3l6F7Ww) + +## 시작하기 + +CrewAI를 사용하고 OpenInference를 통해 OpenTelemetry와 Arize Phoenix를 연동하는 간단한 예제를 단계별로 안내합니다. + +이 가이드는 [Google Colab](https://colab.research.google.com/github/Arize-ai/phoenix/blob/main/tutorials/tracing/crewai_tracing_tutorial.ipynb)에서도 확인하실 수 있습니다. + +### 1단계: 의존성 설치 + +```bash +pip install openinference-instrumentation-crewai crewai crewai-tools arize-phoenix-otel +``` + +### 2단계: 환경 변수 설정 + +Phoenix Cloud API 키를 설정하고 OpenTelemetry를 구성하여 추적 정보를 Phoenix로 전송합니다. Phoenix Cloud는 Arize Phoenix의 호스팅 버전이지만, 이 통합을 사용하는 데 필수는 아닙니다. + +무료 Serper API 키는 [여기](https://serper.dev/)에서 받을 수 있습니다. + +```python +import os +from getpass import getpass + +# Get your Phoenix Cloud credentials +PHOENIX_API_KEY = getpass("🔑 Enter your Phoenix Cloud API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") +SERPER_API_KEY = getpass("🔑 Enter your Serper API key: ") + +# Set environment variables +os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={PHOENIX_API_KEY}" +os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com" # Phoenix Cloud, change this to your own endpoint if you are using a self-hosted instance +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +os.environ["SERPER_API_KEY"] = SERPER_API_KEY +``` + +### 3단계: Phoenix와 함께 OpenTelemetry 초기화하기 + +OpenInference OpenTelemetry 계측 SDK를 초기화하여 트레이스를 수집하고 Phoenix로 전송합니다. + +```python +from phoenix.otel import register + +tracer_provider = register( + project_name="crewai-tracing-demo", + auto_instrument=True, +) +``` + +### 4단계: CrewAI 애플리케이션 생성하기 + +두 명의 에이전트가 협력하여 AI 발전에 관한 블로그 글을 조사하고 작성하는 CrewAI 애플리케이션을 만들어 보겠습니다. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool +from openinference.instrumentation.crewai import CrewAIInstrumentor +from phoenix.otel import register + +# crew에 대한 모니터링 설정 +tracer_provider = register( + endpoint="http://localhost:6006/v1/traces") +CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider) +search_tool = SerperDevTool() + +# 역할과 목표가 설정된 에이전트 정의 +researcher = Agent( + role="Senior Research Analyst", + goal="AI 및 데이터 과학의 최첨단 발전 사항 발견", + backstory="""당신은 최고 수준의 기술 싱크탱크에서 근무합니다. + 새로운 트렌드를 식별하는 데 전문성이 있습니다. + 복잡한 데이터를 분석하고 실행 가능한 인사이트로 제시하는 데 뛰어납니다.""", + verbose=True, + allow_delegation=False, + # 원하는 모델을 지정할 수 있는 optional llm 속성을 전달할 수 있습니다. + # llm=ChatOpenAI(model_name="gpt-3.5", temperature=0.7), + tools=[search_tool], +) +writer = Agent( + role="Tech Content Strategist", + goal="기술 발전에 대한 매력적인 콘텐츠 작성", + backstory="""당신은 통찰력 있고 흥미로운 기사로 유명한 콘텐츠 전략가입니다. + 복잡한 개념을 매력적인 스토리로 전환합니다.""", + verbose=True, + allow_delegation=True, +) + +# 에이전트를 위한 task 생성 +task1 = Task( + description="""2024년 AI 분야의 최신 발전 상황에 대한 포괄적인 분석을 수행하세요. + 주요 트렌드, 획기적 기술, 산업에 미칠 잠재적 영향을 식별하세요.""", + expected_output="주요 내용을 불릿 포인트로 정리한 전체 분석 보고서", + agent=researcher, +) + +task2 = Task( + description="""제공된 인사이트를 활용하여 + 가장 중요한 AI 발전 내용을 강조하는 흥미로운 블로그 글을 작성하세요. + 글은 정보성 있고, 기술에 밝은 독자를 대상으로 하면서 읽기 쉽게 써야 합니다. + 멋지게 들리도록 쓰되, 복잡한 단어는 피하여 AI처럼 들리지 않게 하세요.""", + expected_output="최소 4개의 단락으로 구성된 전체 블로그 글", + agent=writer, +) + +# 순차 프로세스 방식으로 crew 인스턴스화 +crew = Crew( + agents=[researcher, writer], tasks=[task1, task2], verbose=1, process=Process.sequential +) + +# crew에게 작업 시작 지시! +result = crew.kickoff() + +print("######################") +print(result) +``` + +### 5단계: Phoenix에서 트레이스 보기 + +에이전트를 실행한 후, Phoenix에서 CrewAI 애플리케이션에 의해 생성된 트레이스를 볼 수 있습니다. 에이전트 상호작용과 LLM 호출의 상세한 단계가 표시되어 AI 에이전트를 디버깅하고 최적화하는 데 도움이 됩니다. + +Phoenix Cloud 계정에 로그인한 다음 `project_name` 파라미터에서 지정한 프로젝트로 이동하세요. 모든 에이전트 상호작용, 도구 사용 및 LLM 호출이 포함된 트레이스의 타임라인 보기를 확인할 수 있습니다. + +![Phoenix에서 에이전트 상호작용을 보여주는 예시 트레이스](https://storage.googleapis.com/arize-assets/fixtures/crewai_traces.png) + +### 버전 호환성 정보 +- Python 3.8+ +- CrewAI >= 0.86.0 +- Arize Phoenix >= 7.0.1 +- OpenTelemetry SDK >= 1.31.0 + +### 참고 자료 +- [Phoenix 문서](https://docs.arize.com/phoenix/) - Phoenix 플랫폼 개요. +- [CrewAI 문서](https://docs.crewai.com/) - CrewAI 프레임워크 개요. +- [OpenTelemetry 문서](https://opentelemetry.io/docs/) - OpenTelemetry 가이드 +- [OpenInference GitHub](https://github.com/openinference/openinference) - OpenInference SDK 소스 코드. \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/braintrust.mdx b/docs/v1.15.1/ko/observability/braintrust.mdx new file mode 100644 index 000000000..7a0349f8e --- /dev/null +++ b/docs/v1.15.1/ko/observability/braintrust.mdx @@ -0,0 +1,236 @@ +--- +title: Braintrust +description: OpenTelemetry 추적 및 평가를 포함한 CrewAI용 Braintrust 통합 +icon: magnifying-glass-chart +mode: "wide" +--- + +# Braintrust 통합 + +이 가이드는 **Braintrust**를 **CrewAI**와 OpenTelemetry를 사용하여 포괄적인 추적 및 평가와 함께 통합하는 방법을 보여줍니다. 이 가이드를 완료하면 CrewAI agent를 추적하고, 성능을 모니터링하며, Braintrust의 강력한 관찰성 플랫폼을 사용하여 출력을 평가할 수 있습니다. + +> **Braintrust란?** [Braintrust](https://www.braintrust.dev)는 내장된 실험 추적 및 성능 분석을 통해 AI 애플리케이션에 대한 포괄적인 추적, 평가 및 모니터링을 제공하는 AI 평가 및 관찰성 플랫폼입니다. + +## 시작하기 + +CrewAI를 사용하고 포괄적인 관찰성 및 평가를 위해 OpenTelemetry를 통해 Braintrust와 통합하는 간단한 예제를 단계별로 안내합니다. + +### 1단계: 의존성 설치 + +```bash +uv add braintrust[otel] crewai crewai-tools opentelemetry-instrumentation-openai opentelemetry-instrumentation-crewai python-dotenv +``` + +### 2단계: 환경 변수 설정 + +Braintrust API 키를 설정하고 추적을 Braintrust로 전송하도록 OpenTelemetry를 구성합니다. Braintrust API 키와 OpenAI API 키가 필요합니다. + +```python +import os +from getpass import getpass + +# Braintrust 자격 증명 가져오기 +BRAINTRUST_API_KEY = getpass("🔑 Braintrust API 키를 입력하세요: ") + +# 서비스용 API 키 가져오기 +OPENAI_API_KEY = getpass("🔑 OpenAI API 키를 입력하세요: ") + +# 환경 변수 설정 +os.environ["BRAINTRUST_API_KEY"] = BRAINTRUST_API_KEY +os.environ["BRAINTRUST_PARENT"] = "project_name:crewai-demo" +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +``` + +### 3단계: Braintrust와 함께 OpenTelemetry 초기화하기 + +추적을 캡처하고 Braintrust로 전송하기 시작하도록 Braintrust OpenTelemetry 계측을 초기화합니다. + +```python +import os +from typing import Any, Dict + +from braintrust.otel import BraintrustSpanProcessor +from crewai import Agent, Crew, Task +from crewai.llm import LLM +from opentelemetry import trace +from opentelemetry.instrumentation.crewai import CrewAIInstrumentor +from opentelemetry.instrumentation.openai import OpenAIInstrumentor +from opentelemetry.sdk.trace import TracerProvider + +def setup_tracing() -> None: + """Braintrust와 함께 OpenTelemetry 추적 설정.""" + current_provider = trace.get_tracer_provider() + if isinstance(current_provider, TracerProvider): + provider = current_provider + else: + provider = TracerProvider() + trace.set_tracer_provider(provider) + + provider.add_span_processor(BraintrustSpanProcessor()) + CrewAIInstrumentor().instrument(tracer_provider=provider) + OpenAIInstrumentor().instrument(tracer_provider=provider) + + +setup_tracing() +``` + +### 4단계: CrewAI 애플리케이션 생성하기 + +포괄적인 추적이 활성화된 CrewAI 애플리케이션을 생성합니다. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +def create_crew() -> Crew: + """포괄적인 추적을 위한 다중 agent가 있는 crew 생성.""" + llm = LLM(model="gpt-4o-mini") + search_tool = SerperDevTool() + + # 특정 역할을 가진 agent 정의 + researcher = Agent( + role="시니어 연구 분석가", + goal="AI 및 데이터 과학의 최첨단 발전 사항 발견", + backstory="""당신은 최고 수준의 기술 싱크탱크에서 근무합니다. + 새로운 트렌드를 식별하는 데 전문성이 있습니다. + 복잡한 데이터를 분석하고 실행 가능한 인사이트로 제시하는 데 뛰어납니다.""", + verbose=True, + allow_delegation=False, + llm=llm, + tools=[search_tool], + ) + + writer = Agent( + role="기술 콘텐츠 전략가", + goal="기술 발전에 대한 매력적인 콘텐츠 작성", + backstory="""당신은 통찰력 있고 흥미로운 기사로 유명한 콘텐츠 전략가입니다. + 복잡한 개념을 매력적인 스토리로 전환합니다.""", + verbose=True, + allow_delegation=True, + llm=llm, + ) + + # agent를 위한 작업 생성 + research_task = Task( + description="""{topic} 분야의 최신 발전 상황에 대한 포괄적인 분석을 수행하세요. + 주요 트렌드, 획기적 기술, 산업에 미칠 잠재적 영향을 식별하세요.""", + expected_output="주요 내용을 불릿 포인트로 정리한 전체 분석 보고서", + agent=researcher, + ) + + writing_task = Task( + description="""제공된 인사이트를 활용하여 + 가장 중요한 {topic} 발전 내용을 강조하는 흥미로운 블로그 글을 작성하세요. + 글은 정보성 있고, 기술에 밝은 독자를 대상으로 하면서 읽기 쉽게 써야 합니다. + 멋지게 들리도록 쓰되, 복잡한 단어는 피하여 AI처럼 들리지 않게 하세요.""", + expected_output="최소 4개의 단락으로 구성된 전체 블로그 글", + agent=writer, + context=[research_task], + ) + + # 순차 프로세스 방식으로 crew 인스턴스화 + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential + ) + + return crew + +def run_crew(): + """crew를 실행하고 결과 반환.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": "AI 발전"}) + return result + +# crew 실행 +if __name__ == "__main__": + # 이 모듈에서 계측이 이미 초기화됨 + result = run_crew() + print(result) +``` + +### 5단계: Braintrust에서 추적 보기 + +crew를 실행한 후, Braintrust에서 다양한 관점으로 포괄적인 추적을 볼 수 있습니다: + + + + + Braintrust Trace View + + + + + + Braintrust Timeline View + + + + + + Braintrust Thread View + + + + +### 6단계: SDK를 통한 평가 (실험) + +Braintrust의 Eval SDK를 사용하여 평가를 실행할 수도 있습니다. 이는 버전을 비교하거나 출력을 오프라인으로 점수화하는 데 유용합니다. 아래는 위에서 생성한 crew를 사용하는 Python 예제입니다: + +```python +from braintrust import Eval +from autoevals import Levenshtein + +def evaluate_crew_task(input_data): + """crew를 평가하기 위해 감싸는 작업 함수.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": input_data["topic"]}) + return str(result) + +Eval( + "AI 연구 Crew", # 프로젝트 이름 + { + "data": lambda: [ + {"topic": "artificial intelligence trends 2024"}, + {"topic": "machine learning breakthroughs"}, + {"topic": "AI ethics and governance"}, + ], + "task": evaluate_crew_task, + "scores": [Levenshtein], + }, +) +``` + +API 키를 설정하고 실행: + +```bash +export BRAINTRUST_API_KEY="YOUR_API_KEY" +braintrust eval eval_crew.py +``` + +자세한 내용은 [Braintrust Eval SDK 가이드](https://www.braintrust.dev/docs/start/eval-sdk)를 참조하세요. + +### Braintrust 통합의 주요 기능 + +- **포괄적인 추적**: 모든 agent 상호작용, 도구 사용 및 LLM 호출 추적 +- **성능 모니터링**: 실행 시간, 토큰 사용량 및 성공률 모니터링 +- **실험 추적**: 다른 crew 구성 및 모델 비교 +- **자동화된 평가**: crew 출력에 대한 사용자 정의 평가 메트릭 설정 +- **오류 추적**: crew 실행 전반에 걸친 실패 모니터링 및 디버깅 +- **비용 분석**: 토큰 사용량 및 관련 비용 추적 + +### 버전 호환성 정보 +- Python 3.8+ +- CrewAI >= 0.86.0 +- Braintrust >= 0.1.0 +- OpenTelemetry SDK >= 1.31.0 + +### 참고 자료 +- [Braintrust 문서](https://www.braintrust.dev/docs) - Braintrust 플랫폼 개요 +- [Braintrust CrewAI 통합](https://www.braintrust.dev/docs/integrations/crew-ai) - 공식 CrewAI 통합 가이드 +- [Braintrust Eval SDK](https://www.braintrust.dev/docs/start/eval-sdk) - SDK를 통한 실험 실행 +- [CrewAI 문서](https://docs.crewai.com/) - CrewAI 프레임워크 개요 +- [OpenTelemetry 문서](https://opentelemetry.io/docs/) - OpenTelemetry 가이드 +- [Braintrust GitHub](https://github.com/braintrustdata/braintrust) - Braintrust SDK 소스 코드 diff --git a/docs/v1.15.1/ko/observability/datadog.mdx b/docs/v1.15.1/ko/observability/datadog.mdx new file mode 100644 index 000000000..38bc778ce --- /dev/null +++ b/docs/v1.15.1/ko/observability/datadog.mdx @@ -0,0 +1,109 @@ +--- +title: Datadog 통합 +description: Datadog을 CrewAI와 통합하여 LLM Observability 트레이스들을 Datadog에 제출하는 방법을 알아보세요. +icon: dog +mode: "wide" +--- + +# Datadog을 CrewAI와 통합하기 + +이 가이드에서는 Datadog 자동 계측을 사용하여 **Datadog**을 **CrewAI**와 통합하는 방법을 보여드립니다. 이 가이드가 끝나면 LLM Observability 트레이스를 Datadog에 제출하고 CrewAI 에이전트 실행을 Datadog LLM Observability의 에이전트 실행 보기에서 볼 수 있게 됩니다. + +## Datadog LLM Observability란 무엇인가요? + +[Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/)는 AI 엔지니어, 데이터 과학자, 애플리케이션 개발자가 LLM 애플리케이션을 신속하게 개발, 평가, 모니터링할 수 있도록 도와줍니다. 구조화된 실험, AI 에이전트 전반의 엔드투엔드 추적, 평가를 통해 결과물 품질, 성능, 비용, 전반적인 위험을 확실하게 개선할 수 있습니다. + +## 시작하기 + +### 설치 종속성 + +```shell +pip install ddtrace crewai crewai-tools +``` + +### 환경 변수 설정하기 + +Datadog API 키가 없는 경우, [계정 만들기](https://www.datadoghq.com/) 및 [API 키 받기](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys)를 할 수 있습니다. + +또한 다음 환경 변수에 ML 애플리케이션 이름을 지정해야 합니다. ML 애플리케이션은 특정 LLM 기반 애플리케이션과 관련된 LLM Observability 트레이스의 그룹입니다. ML 애플리케이션 이름 제한에 대한 자세한 내용은 [ML 애플리케이션 이름 지정 가이드라인](https://docs.datadoghq.com/llm_observability/instrumentation/sdk?tab=python#application-naming-guidelines)을 참조하세요. + +```shell +export DD_API_KEY= +export DD_SITE= +export DD_LLMOBS_ENABLED=true +export DD_LLMOBS_ML_APP= +export DD_LLMOBS_AGENTLESS_ENABLED=true +export DD_APM_TRACING_ENABLED=false +``` + +또한 LLM 공급자 API 키를 설정합니다. + +```shell +export OPENAI_API_KEY= +export ANTHROPIC_API_KEY= +export GEMINI_API_KEY= +... +``` + +### 크루AI 에이전트 애플리케이션 생성하기 + +```python +# crewai_agent.py +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="작가", + goal="시를 통해 어린이들이 수학을 흥미롭고 이해하기 쉽게 설명합니다", + backstory="당신은 하이쿠를 쓰는 전문가이지만 수학은 전혀 모릅니다.", + tools=[web_rag_tool], +) + +task = Task( + description=("{곱셈}이란 무엇인가요?"), + expected_output=("답을 포함하는 하이쿠를 작성하세요."), + agent=writer +) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) + +output = crew.kickoff(dict(곱셈="2 * 2")) +``` + +### Datadog 자동 계측을 사용하여 애플리케이션 실행하기 + +[환경 변수](#환경-변수-설정하기)를 설정하면 이제 Datadog 자동 계측을 통해 애플리케이션을 실행할 수 있습니다. + +```shell +ddtrace-run python crewai_agent.py +``` + +### Datadog에서 트레이스 추적하기 + +애플리케이션을 실행한 후 왼쪽 상단 드롭다운에서 선택한 ML 애플리케이션 이름을 선택하면 [Datadog LLM Observability의 트레이스 보기](https://app.datadoghq.com/llm/traces)에서 트레이스들을 확인할 수 있습니다. + +트레이스를 클릭하면 사용된 총 토큰, LLM 호출 수, 사용된 모델, 예상 비용 등 트레이스에 대한 세부 정보가 표시됩니다. 특정 스팬(span)을 클릭하면 이러한 세부 정보의 범위가 좁혀지고 관련 입력, 출력 및 메타데이터가 표시됩니다. + + +Datadog LLM 옵저버빌리티 추적 보기 + + +또한, 트레이스의 제어 및 데이터 흐름을 보여주는 트레이스의 실행 그래프 보기를 볼 수 있으며, 이는 더 큰 에이전트로 확장하여 LLM 호출, 도구 호출 및 에이전트 상호 작용 간의 핸드오프와 관계를 보여줍니다. + + +Datadog LLM Observability 에이전트 실행 흐름 보기 + + +## 참조 + +- [Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) +- [Datadog LLM 옵저버빌리티 크루AI 자동 계측](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python#crew-ai) diff --git a/docs/v1.15.1/ko/observability/galileo.mdx b/docs/v1.15.1/ko/observability/galileo.mdx new file mode 100644 index 000000000..f82b82574 --- /dev/null +++ b/docs/v1.15.1/ko/observability/galileo.mdx @@ -0,0 +1,115 @@ +--- +title: Galileo 갈릴레오 +description: CrewAI 추적 및 평가를 위한 Galileo 통합 +icon: telescope +mode: "wide" +--- + +## 개요 + +이 가이드는 **Galileo**를 **CrewAI**와 통합하는 방법을 보여줍니다. +포괄적인 추적 및 평가 엔지니어링을 위한 것입니다. +이 가이드가 끝나면 CrewAI 에이전트를 추적할 수 있게 됩니다. +성과를 모니터링하고 행동을 평가합니다. +Galileo의 강력한 관측 플랫폼. + +> **갈릴레오(Galileo)란 무엇인가요?**[Galileo](https://galileo.ai/)는 AI 평가 및 관찰 가능성입니다. +엔드투엔드 추적, 평가, +AI 애플리케이션 모니터링. 이를 통해 팀은 실제 사실을 포착할 수 있습니다. +견고한 가드레일을 만들고 체계적인 실험을 실행하세요. +내장된 실험 추적 및 성능 분석으로 신뢰성 보장 +AI 수명주기 전반에 걸쳐 투명성과 지속적인 개선을 제공합니다. + +## 시작하기 + +이 튜토리얼은 [CrewAI 빠른 시작](/ko/quickstart.mdx)을 따르며 추가하는 방법을 보여줍니다. +갈릴레오의 [CrewAIEventListener](https://v2docs.galileo.ai/sdk-api/python/reference/handlers/crewai/handler), +이벤트 핸들러. +자세한 내용은 갈릴레오 문서를 참고하세요. +[CrewAI 애플리케이션에 Galileo 추가](https://v2docs.galileo.ai/how-to-guides/third-party-integrations/add-galileo-to-crewai/add-galileo-to-crewai) +방법 안내. + +> **참고**이 튜토리얼에서는 [CrewAI 빠른 시작](/ko/quickstart.mdx)을 완료했다고 가정합니다. +완전한 포괄적인 예제를 원한다면 Galileo +[CrewAI SDK 예제 저장소](https://github.com/rungalileo/sdk-examples/tree/main/python/agent/crew-ai). + +### 1단계: 종속성 설치 + +앱에 필요한 종속성을 설치합니다. +원하는 방법으로 가상 환경을 생성하고, +그런 다음 다음을 사용하여 해당 환경 내에 종속성을 설치하십시오. +선호하는 도구: + +```bash +uv add galileo +``` + +### 2단계: [CrewAI 빠른 시작](/ko/quickstart.mdx)에서 .env 파일에 추가 + +```bash +# Your Galileo API key +GALILEO_API_KEY="your-galileo-api-key" + +# Your Galileo project name +GALILEO_PROJECT="your-galileo-project-name" + +# The name of the Log stream you want to use for logging +GALILEO_LOG_STREAM="your-galileo-log-stream " +``` + +### 3단계: Galileo 이벤트 리스너 추가 + +Galileo로 로깅을 활성화하려면 `CrewAIEventListener`의 인스턴스를 생성해야 합니다. +다음을 통해 Galileo CrewAI 핸들러 패키지를 가져옵니다. +main.py 파일 상단에 다음 코드를 추가하세요. + +```python +from galileo.handlers.crewai.handler import CrewAIEventListener +``` + +실행 함수 시작 시 이벤트 리스너를 생성합니다. + +```python +def run(): + # Create the event listener + CrewAIEventListener() + # The rest of your existing code goes here +``` + +리스너 인스턴스를 생성하면 자동으로 +CrewAI에 등록되었습니다. + +### 4단계: Crew Agent 실행 + +CrewAI CLI를 사용하여 Crew Agent를 실행하세요. + +```bash +crewai run +``` + +### 5단계: Galileo에서 추적 보기 + +승무원 에이전트가 완료되면 흔적이 플러시되어 Galileo에 나타납니다. + +![Galileo trace view](/images/galileo-trace-veiw.png) + +## 갈릴레오 통합 이해 + +Galileo는 이벤트 리스너를 등록하여 CrewAI와 통합됩니다. +승무원 실행 이벤트(예: 에이전트 작업, 도구 호출, 모델 응답)를 캡처합니다. +관찰 가능성과 평가를 위해 이를 갈릴레오에 전달합니다. + +### 이벤트 리스너 이해 + +`CrewAIEventListener()` 인스턴스를 생성하는 것이 전부입니다. +CrewAI 실행을 위해 Galileo를 활성화하는 데 필요합니다. 인스턴스화되면 리스너는 다음을 수행합니다. + +-CrewAI에 자동으로 등록됩니다. +-환경 변수에서 Galileo 구성을 읽습니다. +-모든 실행 데이터를 Galileo 프로젝트 및 다음에서 지정한 로그 스트림에 기록합니다. + `GALILEO_PROJECT` 및 `GALILEO_LOG_STREAM` + +추가 구성이나 코드 변경이 필요하지 않습니다. +이 실행의 모든 데이터는 Galileo 프로젝트에 기록되며 +환경 구성에 따라 지정된 로그 스트림 +(예: GALILEO_PROJECT 및 GALILEO_LOG_STREAM) diff --git a/docs/v1.15.1/ko/observability/langdb.mdx b/docs/v1.15.1/ko/observability/langdb.mdx new file mode 100644 index 000000000..6a5442f49 --- /dev/null +++ b/docs/v1.15.1/ko/observability/langdb.mdx @@ -0,0 +1,285 @@ +--- +title: LangDB 통합 +description: LangDB AI Gateway로 CrewAI 워크플로우를 관리, 보안, 최적화하세요—350개 이상의 모델 액세스, 자동 라우팅, 비용 최적화, 완전한 가시성을 제공합니다. +icon: database +mode: "wide" +--- + +# 소개 + +[LangDB AI Gateway](https://langdb.ai)는 여러 대형 언어 모델과의 연결을 지원하는 OpenAI 호환 API를 제공하며, 350개 이상의 언어 모델에 접근할 수 있도록 해주는 관측 플랫폼입니다. 단 한 번의 `init()` 호출로 모든 에이전트 상호작용, 작업 실행 및 LLM 호출이 캡처되어, 애플리케이션을 위한 종합적인 관측성과 프로덕션 수준의 AI 인프라를 제공합니다. + + + LangDB CrewAI trace example + + +**확인:** [실시간 추적 예시 보기](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22) + +## 기능 + +### AI 게이트웨이 기능 +- **350개 이상의 LLM 접근**: 단일 통합을 통해 모든 주요 언어 모델에 연결 +- **가상 모델**: 특정 매개변수와 라우팅 규칙으로 맞춤형 모델 구성 생성 +- **가상 MCP**: 에이전트 간 향상된 통신을 위해 MCP(Model Context Protocol) 시스템과의 호환성 및 통합 지원 +- **가드레일**: 에이전트 행동에 대한 안전 조치 및 컴플라이언스 제어 구현 + +### 가시성 및 추적 +- **자동 추적**: 단일 `init()` 호출로 모든 CrewAI 상호작용을 캡처 +- **엔드-투-엔드 가시성**: 에이전트 워크플로우를 시작부터 끝까지 모니터링 +- **도구 사용 추적**: 에이전트가 사용하는 도구와 그 결과를 추적 +- **모델 호출 모니터링**: LLM 상호작용에 대한 상세한 인사이트 제공 +- **성능 분석**: 지연 시간, 토큰 사용량 및 비용 모니터링 +- **디버깅 지원**: 문제 해결을 위한 단계별 실행 +- **실시간 모니터링**: 라이브 트레이스 및 메트릭 대시보드 + +## 설치 안내 + + + + CrewAI 기능 플래그와 함께 LangDB 클라이언트를 설치하세요: + ```bash + pip install 'pylangdb[crewai]' + ``` + + + LangDB 자격 증명을 구성하세요: + ```bash + export LANGDB_API_KEY="" + export LANGDB_PROJECT_ID="" + export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + ``` + + + CrewAI 코드를 설정하기 전에 LangDB를 임포트하고 초기화하세요: + ```python + from pylangdb.crewai import init + # Initialize LangDB + init() + ``` + + + LangDB 헤더와 함께 LLM을 설정하세요: + ```python + from crewai import Agent, Task, Crew, LLM + import os + + # Configure LLM with LangDB headers + llm = LLM( + model="openai/gpt-4o", # Replace with the model you want to use + api_key=os.getenv("LANGDB_API_KEY"), + base_url=os.getenv("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.getenv("LANGDB_PROJECT_ID")} + ) + ``` + + + +## 빠른 시작 예제 + +여기 LangDB와 CrewAI를 시작하는 간단한 예제가 있습니다: + +```python +import os +from pylangdb.crewai import init +from crewai import Agent, Task, Crew, LLM + +# Initialize LangDB before any CrewAI imports +init() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +# Define your agent +researcher = Agent( + role="Research Specialist", + goal="Research topics thoroughly", + backstory="Expert researcher with skills in finding information", + llm=create_llm("openai/gpt-4o"), # Replace with the model you want to use + verbose=True +) + +# Create a task +task = Task( + description="Research the given topic and provide a comprehensive summary", + agent=researcher, + expected_output="Detailed research summary with key findings" +) + +# Create and run the crew +crew = Crew(agents=[researcher], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## 완성된 예제: Research and Planning Agent + +이 포괄적인 예제는 연구 및 기획 기능을 갖춘 multi-agent 워크플로우를 보여줍니다. + +### 사전 준비 사항 + +```bash +pip install crewai 'pylangdb[crewai]' crewai_tools setuptools python-dotenv +``` + +### 환경 설정 + +```bash +# LangDB credentials +export LANGDB_API_KEY="" +export LANGDB_PROJECT_ID="" +export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + +# Additional API keys (optional) +export SERPER_API_KEY="" # For web search capabilities +``` + +### 전체 구현 + +```python +#!/usr/bin/env python3 + +import os +import sys +from pylangdb.crewai import init +init() # Initialize LangDB before any CrewAI imports +from dotenv import load_dotenv +from crewai import Agent, Task, Crew, Process, LLM +from crewai_tools import SerperDevTool + +load_dotenv() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +class ResearchPlanningCrew: + def researcher(self) -> Agent: + return Agent( + role="Research Specialist", + goal="Research topics thoroughly and compile comprehensive information", + backstory="Expert researcher with skills in finding and analyzing information from various sources", + tools=[SerperDevTool()], + llm=create_llm("openai/gpt-4o"), + verbose=True + ) + + def planner(self) -> Agent: + return Agent( + role="Strategic Planner", + goal="Create actionable plans based on research findings", + backstory="Strategic planner who breaks down complex challenges into executable plans", + reasoning=True, + max_reasoning_attempts=3, + llm=create_llm("openai/anthropic/claude-3.7-sonnet"), + verbose=True + ) + + def research_task(self) -> Task: + return Task( + description="Research the topic thoroughly and compile comprehensive information", + agent=self.researcher(), + expected_output="Comprehensive research report with key findings and insights" + ) + + def planning_task(self) -> Task: + return Task( + description="Create a strategic plan based on the research findings", + agent=self.planner(), + expected_output="Strategic execution plan with phases, goals, and actionable steps", + context=[self.research_task()] + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.researcher(), self.planner()], + tasks=[self.research_task(), self.planning_task()], + verbose=True, + process=Process.sequential + ) + +def main(): + topic = sys.argv[1] if len(sys.argv) > 1 else "Artificial Intelligence in Healthcare" + + crew_instance = ResearchPlanningCrew() + + # Update task descriptions with the specific topic + crew_instance.research_task().description = f"Research {topic} thoroughly and compile comprehensive information" + crew_instance.planning_task().description = f"Create a strategic plan for {topic} based on the research findings" + + result = crew_instance.crew().kickoff() + print(result) + +if __name__ == "__main__": + main() +``` + +### 예제 실행하기 + +```bash +python main.py "Sustainable Energy Solutions" +``` + +## LangDB에서 트레이스 보기 + +CrewAI 애플리케이션을 실행한 후, LangDB 대시보드에서 자세한 트레이스를 확인할 수 있습니다: + + + LangDB 트레이스 대시보드에서 CrewAI 워크플로우 표시 + + +### 볼 수 있는 내용 + +- **에이전트 상호작용**: 에이전트 대화 및 작업 인계의 전체 흐름 +- **도구 사용**: 호출된 도구, 입력값 및 출력값 +- **모델 호출**: 프롬프트 및 응답과 함께하는 상세 LLM 상호작용 +- **성능 지표**: 지연 시간, 토큰 사용량, 비용 추적 +- **실행 타임라인**: 전체 워크플로우의 단계별 보기 + +## 문제 해결 + +### 일반적인 문제 + +- **추적이 나타나지 않음**: `init()`이 CrewAI 임포트 이전에 호출되었는지 확인하세요 +- **인증 오류**: LangDB API 키와 프로젝트 ID를 확인하세요 + +## 리소스 + + + + 공식 LangDB 문서 및 가이드 + + + AI 에이전트 구축을 위한 단계별 튜토리얼 + + + CrewAI 통합 전체 예제 + + + 트레이스 및 분석 액세스 + + + 350개 이상의 사용 가능한 언어 모델 살펴보기 + + + 셀프 호스팅 옵션 및 엔터프라이즈 기능 + + + +## 다음 단계 + +이 가이드에서는 LangDB AI Gateway를 CrewAI와 통합하는 기본 사항을 다루었습니다. AI 워크플로우를 더욱 강화하려면 다음을 탐색해보세요: + +- **Virtual Models**: 라우팅 전략을 사용한 맞춤형 모델 구성 만들기 +- **Guardrails & Safety**: 콘텐츠 필터링 및 컴플라이언스 제어 구현 +- **Production Deployment**: 폴백, 재시도, 로드 밸런싱 구성 + +보다 고급 기능 및 사용 사례에 대해서는 [LangDB Documentation](https://docs.langdb.ai)을 방문하거나, [Model Catalog](https://app.langdb.ai/models)를 탐색하여 사용 가능한 모든 모델을 확인해 보세요. \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/langfuse.mdx b/docs/v1.15.1/ko/observability/langfuse.mdx new file mode 100644 index 000000000..ceefceaee --- /dev/null +++ b/docs/v1.15.1/ko/observability/langfuse.mdx @@ -0,0 +1,110 @@ +--- +title: Langfuse 통합 +description: OpenLit을 사용하여 OpenTelemetry를 통해 CrewAI와 Langfuse를 통합하는 방법을 알아보세요 +icon: vials +mode: "wide" +--- + +# Langfuse와 CrewAI 통합하기 + +이 노트북은 **OpenLit** SDK를 통해 OpenTelemetry를 사용하여 **Langfuse**를 **CrewAI**와 통합하는 방법을 보여줍니다. 이 노트북을 마치면 Langfuse를 사용해 CrewAI 애플리케이션을 추적하여 가시성과 디버깅을 향상시킬 수 있습니다. + +> **Langfuse란 무엇인가요?** [Langfuse](https://langfuse.com)는 오픈 소스 LLM 엔지니어링 플랫폼입니다. 이는 LLM 애플리케이션을 위한 추적 및 모니터링 기능을 제공하며, 개발자들이 AI 시스템을 디버그, 분석 및 최적화하는 데 도움을 줍니다. Langfuse는 네이티브 통합, OpenTelemetry, API/SDK를 통해 다양한 도구 및 프레임워크와 연동됩니다. + +[![Langfuse Overview Video](https://github.com/user-attachments/assets/3926b288-ff61-4b95-8aa1-45d041c70866)](https://langfuse.com/watch-demo) + +## 시작하기 + +CrewAI를 사용하고 OpenLit을 통해 OpenTelemetry로 Langfuse와 통합하는 간단한 예제를 함께 살펴보겠습니다. + +### 1단계: 의존성 설치 + +```python +%pip install langfuse openlit crewai crewai_tools +``` + +### 2단계: 환경 변수 설정 + +Langfuse API 키를 설정하고 OpenTelemetry 내보내기 설정을 구성하여 trace를 Langfuse로 전송합니다. Langfuse OpenTelemetry 엔드포인트 `/api/public/otel` 및 인증과 관련된 자세한 내용은 [Langfuse OpenTelemetry 문서](https://langfuse.com/docs/opentelemetry/get-started)를 참고하십시오. + + +```python +import os + +# 프로젝트에 대한 키를 프로젝트 설정 페이지에서 확인하세요: 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" # 🇪🇺 EU 지역 +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US 지역 + + +# OpenAI 키 +os.environ["OPENAI_API_KEY"] = "sk-proj-..." +``` +환경 변수를 설정하면 이제 Langfuse 클라이언트를 초기화할 수 있습니다. get_client()는 환경 변수에 제공된 자격 증명을 사용하여 Langfuse 클라이언트를 초기화합니다. + +```python +from langfuse import get_client + +langfuse = get_client() + +# 연결 확인 +if langfuse.auth_check(): + print("Langfuse 클라이언트가 인증되었으며 준비되었습니다!") +else: + print("인증에 실패했습니다. 자격 증명과 호스트를 확인하세요.") +``` + +### 3단계: OpenLit 초기화 + +OpenLit OpenTelemetry 계측 SDK를 초기화하여 OpenTelemetry 추적을 수집하기 시작합니다. + +```python +import openlit + +openlit.init() +``` + +### 4단계: 간단한 CrewAI 애플리케이션 만들기 + +여러 에이전트가 협력하여 사용자의 질문에 답하는 간단한 CrewAI 애플리케이션을 만들어보겠습니다. + + +```python +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], + ) + +task = Task(description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) +``` + +### 5단계: Langfuse에서 트레이스 확인하기 + +에이전트를 실행한 후 [Langfuse](https://cloud.langfuse.com)에서 CrewAI 애플리케이션에서 생성된 트레이스를 확인할 수 있습니다. 여기서 LLM 상호작용의 자세한 단계들을 볼 수 있으며, 이를 통해 AI 에이전트의 디버깅 및 최적화에 도움이 됩니다. + +![Langfuse의 CrewAI 예시 트레이스](https://langfuse.com/images/cookbook/integration_crewai/crewai-example-trace.png) + +_[Langfuse의 공개 예시 트레이스](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/e2cf380ffc8d47d28da98f136140642b?timestamp=2025-02-05T15%3A12%3A02.717Z&observation=3b32338ee6a5d9af)_ + +## 참고 자료 + +- [Langfuse OpenTelemetry 문서](https://langfuse.com/docs/opentelemetry/get-started) \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/langtrace.mdx b/docs/v1.15.1/ko/observability/langtrace.mdx new file mode 100644 index 000000000..05848d586 --- /dev/null +++ b/docs/v1.15.1/ko/observability/langtrace.mdx @@ -0,0 +1,73 @@ +--- +title: Langtrace 연동 +description: 외부 가시성 도구인 Langtrace를 사용하여 CrewAI 에이전트의 비용, 지연 시간 및 성능을 모니터링하는 방법. +icon: chart-line +mode: "wide" +--- + +# Langtrace 개요 + +Langtrace는 대형 언어 모델(LLM), LLM 프레임워크, 벡터 데이터베이스에 대한 관측 가능성과 평가를 설정할 수 있도록 도와주는 오픈소스 외부 도구입니다. +Langtrace는 CrewAI에 직접 내장되어 있지는 않지만, CrewAI와 함께 사용하여 CrewAI 에이전트의 비용, 지연 시간, 성능에 대해 깊이 있는 가시성을 확보할 수 있습니다. +이 통합을 통해 하이퍼파라미터를 기록하고, 성능 회귀를 모니터링하며, 에이전트의 지속적인 개선을 위한 프로세스를 수립할 수 있습니다. + +![에이전트 세션 실행 시리즈 개요](/images/langtrace1.png) +![에이전트 트레이스 개요](/images/langtrace2.png) +![상세한 llm 트레이스 개요](/images/langtrace3.png) + +## 설정 지침 + + + + [https://langtrace.ai/signup](https://langtrace.ai/signup)에서 가입하세요. + + + 프로젝트 유형을 `CrewAI`로 설정하고 API 키를 생성하세요. + + + 다음 명령어를 사용하세요: + + ```bash + pip install langtrace-python-sdk + ``` + + + 스크립트의 시작 부분, CrewAI를 임포트하기 전에 Langtrace를 임포트하고 초기화하세요: + + ```python + from langtrace_python_sdk import langtrace + langtrace.init(api_key='') + + # 이제 CrewAI 모듈을 임포트하세요 + from crewai import Agent, Task, Crew + ``` + + + +### 기능 및 CrewAI에의 적용 + +1. **LLM 토큰 및 비용 추적** + + - 각 CrewAI 에이전트 상호작용에 대한 토큰 사용량과 관련 비용을 모니터링합니다. + +2. **실행 단계에 대한 추적 그래프** + + - CrewAI 작업의 실행 흐름을 시각화하며, 지연 시간과 로그를 포함합니다. + - 에이전트 워크플로우의 병목 지점을 파악하는 데 유용합니다. + +3. **수동 주석을 통한 데이터셋 큐레이션** + + - 미래의 학습 또는 평가를 위해 CrewAI 작업 출력으로부터 데이터셋을 생성합니다. + +4. **프롬프트 버전 관리 및 관리** + + - CrewAI 에이전트에서 사용된 다양한 프롬프트 버전을 추적합니다. + - A/B 테스트 및 에이전트 성능 최적화에 유용합니다. + +5. **프롬프트 플레이그라운드 및 모델 비교** + + - 배포 전에 CrewAI 에이전트에 사용할 다양한 프롬프트와 모델을 테스트 및 비교합니다. + +6. **테스트 및 평가** + + - CrewAI 에이전트 및 작업에 대한 자동화된 테스트를 설정합니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/maxim.mdx b/docs/v1.15.1/ko/observability/maxim.mdx new file mode 100644 index 000000000..2db649824 --- /dev/null +++ b/docs/v1.15.1/ko/observability/maxim.mdx @@ -0,0 +1,227 @@ +--- +title: "Maxim Integration" +description: "에이전트 모니터링, 평가 및 가시성 시작" +icon: "infinity" +mode: "wide" +--- + +# Maxim 개요 + +Maxim AI는 귀하의 CrewAI 애플리케이션을 위한 포괄적인 에이전트 모니터링, 평가 및 가시성을 제공합니다. Maxim의 원라인 통합을 통해 에이전트 상호작용, 성능 지표 등을 손쉽게 추적하고 분석할 수 있습니다. + +## 특징 + +### 프롬프트 관리 + +Maxim의 프롬프트 관리 기능을 통해 CrewAI 에이전트를 위한 프롬프트를 생성, 조직, 최적화할 수 있습니다. 지침을 하드코딩하는 대신, Maxim의 SDK를 활용하여 버전 관리가 되는 프롬프트를 동적으로 가져오고 적용하세요. + + + + 플레이그라운드를 통해 프롬프트를 생성, 정제, 실험 및 배포할 수 있습니다. 폴더와 버전을 활용하여 프롬프트를 정리하고, 도구 및 컨텍스트를 연결하여 실제 사례로 실험해 보며, 맞춤형 로직을 기반으로 배포할 수 있습니다. + + [**모델 구성**](https://www.getmaxim.ai/docs/introduction/quickstart/setting-up-workspace#add-model-api-keys)을 통해 여러 모델을 손쉽게 실험하고, 프롬프트 플레이그라운드 상단 드롭다운에서 원하는 모델을 선택하세요. + + + + + 팀이 AI 애플리케이션을 개발할 때, 실험의 중요한 부분은 프롬프트 구조를 반복적으로 개선하는 것입니다. 효과적으로 협업하고 변경 사항을 명확히 정리할 수 있도록 Maxim은 프롬프트 버전 관리와 버전 간 비교 실행을 지원합니다. + + + + + AI 애플리케이션을 발전시켜 나가면서 프롬프트를 반복 개선하기 위해서는 모델, 프롬프트 구조 등 다양한 요소로 실험이 필요합니다. 버전 간 비교 및 변화에 대한 정보에 기반한 결정을 위해, 비교 플레이그라운드는 결과를 나란히 볼 수 있게 해줍니다. + + ## **프롬프트 비교를 왜 사용해야 하나요?** + + 프롬프트 비교는 여러 개의 단일 프롬프트를 하나의 뷰에서 볼 수 있도록 하여 다양한 워크플로에 streamlined 접근을 제공합니다: + + 1. **모델 비교**: 동일한 프롬프트에서 서로 다른 모델의 성능을 평가합니다. + 2. **프롬프트 최적화**: 여러 버전의 프롬프트를 비교하여 가장 효과적인 구성을 식별합니다. + 3. **교차 모델 일관성**: 동일한 프롬프트에 대해 여러 모델에서 일관된 출력을 보장합니다. + 4. **성능 벤치마킹**: 다양한 모델과 프롬프트에 대해 지연 시간, 비용, 토큰 수 등의 지표를 분석합니다. + + + +### 관찰 가능성 & 평가 + +Maxim AI는 CrewAI 에이전트에 대한 포괄적인 관찰 가능성과 평가 기능을 제공하여, 각 실행 과정에서 무슨 일이 일어나고 있는지 정확히 파악할 수 있도록 지원합니다. + + + + 에이전트의 전체 라이프사이클(도구 호출, 에이전트 궤적, 결정 플로우 등)을 손쉽게 추적할 수 있습니다. + + + + + 전체 트레이스 또는 개별 노드에 대해 상세 평가를 실행할 수 있으며, 다음 기능을 지원합니다: + + - 다중 단계 상호작용 및 세분화된 트레이스 분석 + - 세션 수준 평가 + - 실제 환경 시뮬레이션 테스트 + + + + + +

+ 필터 및 샘플링을 기준으로 UI에서 캡처된 로그를 자동으로 평가할 수 있습니다. +

+ + +

+ 로그의 품질을 평가하고, 사람의 평가 또는 등급을 이용해 로그를 검토할 수 있습니다. +

+ + +

+ 트레이스 또는 로그의 모든 컴포넌트를 평가하여 에이전트의 행동에 대한 통찰을 얻을 수 있습니다. +

+ + + --- + + + **오류**, **비용, 토큰 사용량, 사용자 피드백, 지연 시간**에 임계값을 설정하고, Slack 또는 PagerDuty를 통해 실시간 알림을 받아보세요. + + + + + 시간 경과에 따른 트레이스, 사용량 측정지표, 지연 시간 및 오류율을 손쉽게 시각화할 수 있습니다. + + + + + +## 시작하기 + +### 사전 준비 사항 + +- Python 버전 \>=3.10 +- Maxim 계정 ([여기에서 가입](https://getmaxim.ai/)) +- Maxim API 키 생성 +- CrewAI 프로젝트 + +### 설치 + +Maxim SDK를 pip을 통해 설치하세요: + +```python +pip install maxim-py +``` + +또는 `requirements.txt`에 추가하세요: + +``` +maxim-py +``` + +### 기본 설정 + +### 1. 환경 변수 설정 + +```python +### Environment Variables Setup + +# Create a `.env` file in your project root: + +# Maxim API Configuration +MAXIM_API_KEY=your_api_key_here +MAXIM_LOG_REPO_ID=your_repo_id_here +``` + +### 2. 필수 패키지 임포트하기 + +```python +from crewai import Agent, Task, Crew, Process +from maxim import Maxim +from maxim.logger.crewai import instrument_crewai +``` + +### 3. API 키로 Maxim 초기화하기 + +```python {8} +# Instrument CrewAI with just one line +instrument_crewai(Maxim().logger()) +``` + +### 4. 일반적으로 CrewAI 애플리케이션 생성 및 실행하기 + +```python +# Create your agent +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 +) + +# Define the task +research_task = Task( + description="Research the latest AI advancements...", + expected_output="", + agent=researcher +) + +# Configure and run the crew +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True +) + +try: + result = crew.kickoff() +finally: + maxim.cleanup() # Ensure cleanup happens even if errors occur +``` + +이제 끝입니다! 모든 CrewAI 에이전트 상호작용이 Maxim 대시보드에 기록되고 확인할 수 있습니다. + +간단한 참고를 위해 이 Google Colab Notebook을 확인하세요 - [Notebook](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing) + +## 트레이스 보기 + +CrewAI 애플리케이션을 실행한 후: + +1. [Maxim 대시보드](https://app.getmaxim.ai/login)에 로그인하세요. +2. 리포지토리로 이동하세요. +3. 다음을 포함한 에이전트 트레이스를 상세하게 확인할 수 있습니다: + - 에이전트 대화 내역 + - 도구 사용 패턴 + - 성능 지표 + - 비용 분석 + + + +## 문제 해결 + +### 흔한 문제 + +- **추적(trace)가 나타나지 않음**: API 키와 저장소 ID가 올바른지 확인하세요. +- crew를 실행하기 **_전에_** 반드시 **`instrument_crewai()`를 호출**했는지 확인하세요. 이 함수가 로깅 훅(logging hook)을 올바르게 초기화합니다. +- 내부 오류를 드러내기 위해 `instrument_crewai()` 호출 시 `debug=True`로 설정하세요: + + ```python + instrument_crewai(logger, debug=True) + ``` +- 에이전트에서 상세 로그를 캡처하기 위해 `verbose=True`로 설정하세요: + + ```python + agent = CrewAgent(..., verbose=True) + ``` +- `instrument_crewai()`가 에이전트를 생성하거나 실행하기 **전에** 호출되는지 다시 한 번 확인하세요. 너무 당연해 보일 수 있지만, 자주 발생하는 실수입니다. + +## 리소스 + + + + 공식 CrewAI 문서 + + + 공식 Maxim 문서 + + + Maxim Github + + \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/mlflow.mdx b/docs/v1.15.1/ko/observability/mlflow.mdx new file mode 100644 index 000000000..10edb565e --- /dev/null +++ b/docs/v1.15.1/ko/observability/mlflow.mdx @@ -0,0 +1,206 @@ +--- +title: MLflow 통합 +description: MLflow를 사용하여 에이전트 모니터링을 빠르게 시작하세요. +icon: bars-staggered +mode: "wide" +--- + +# MLflow 개요 + +[MLflow](https://mlflow.org/)는 머신러닝 실무자와 팀이 머신러닝 프로세스의 복잡성을 관리할 수 있도록 돕는 오픈소스 플랫폼입니다. + +MLflow는 귀하의 생성형 AI 애플리케이션에서 서비스 실행에 대한 상세 정보를 캡처하여 LLM 가시성을 향상시키는 트레이싱 기능을 제공합니다. +트레이싱은 요청의 각 중간 단계에 관련된 입력값, 출력값, 메타데이터를 기록하는 방법을 제공하여, 버그 및 예기치 않은 동작의 원인을 쉽게 찾아낼 수 있게 합니다. + +![MLflow crewAI 트레이싱 사용 개요](/images/mlflow-tracing.gif) + +### 기능 + +- **트레이싱 대시보드**: crewAI 에이전트의 활동을 입력값, 출력값, 스팬의 메타데이터와 함께 자세한 대시보드로 모니터링할 수 있습니다. +- **자동 트레이싱**: 완전 자동화된 crewAI 통합 기능으로, `mlflow.crewai.autolog()`를 실행하여 활성화할 수 있습니다. +- **약간의 노력만으로 수동 추적 계측**: 데코레이터, 함수 래퍼, 컨텍스트 매니저 등 MLflow의 고수준 fluent API를 통해 추적 계측을 커스터마이즈할 수 있습니다. +- **OpenTelemetry 호환성**: MLflow Tracing은 OpenTelemetry Collector로 트레이스를 내보내는 것을 지원하며, 이를 통해 Jaeger, Zipkin, AWS X-Ray 등 다양한 백엔드로 트레이스를 내보낼 수 있습니다. +- **에이전트 패키징 및 배포**: crewAI 에이전트를 다양한 배포 대상으로 추론 서버에 패키징 및 배포할 수 있습니다. +- **LLM을 안전하게 호스팅**: 여러 공급자의 LLM을 MFflow 게이트웨이를 통해 하나의 통합 엔드포인트에서 호스팅할 수 있습니다. +- **평가**: 편리한 API `mlflow.evaluate()`를 사용하여 다양한 지표로 crewAI 에이전트를 평가할 수 있습니다. + +## 설치 안내 + + + + ```shell + # crewAI 연동은 mlflow>=2.19.0 에서 사용할 수 있습니다. + pip install mlflow + ``` + + + ```shell + # 이 과정은 선택 사항이지만, MLflow 추적 서버를 사용하면 더 나은 시각화와 더 많은 기능을 사용할 수 있습니다. + mlflow server + ``` + + + 다음 두 줄을 애플리케이션 코드에 추가하세요: + + ```python + import mlflow + + mlflow.crewai.autolog() + + # 선택 사항: 추적 서버를 사용하는 경우 tracking URI와 experiment 이름을 설정할 수 있습니다. + mlflow.set_tracking_uri("http://localhost:5000") + mlflow.set_experiment("CrewAI") + ``` + + CrewAI Agents 추적 예시 사용법: + + ```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) + ``` + 더 많은 설정 및 사용 예시는 [MLflow Tracing 문서](https://mlflow.org/docs/latest/llms/tracing/index.html)를 참고하세요. + + + 이제 crewAI agents의 추적 정보가 MLflow에서 캡처됩니다. + MLflow 추적 서버에 접속하여 추적 내역을 확인하고 에이전트의 인사이트를 얻으세요. + + 브라우저에서 `127.0.0.1:5000`을 열어 MLflow 추적 서버에 접속하세요. + + MLflow tracing example with crewai + + + diff --git a/docs/v1.15.1/ko/observability/neatlogs.mdx b/docs/v1.15.1/ko/observability/neatlogs.mdx new file mode 100644 index 000000000..c01704823 --- /dev/null +++ b/docs/v1.15.1/ko/observability/neatlogs.mdx @@ -0,0 +1,129 @@ +--- +title: Neatlogs 통합 +description: CrewAI agent 실행을 이해하고, 디버그하며, 공유하기 +icon: magnifying-glass-chart +mode: "wide" +--- + +# 소개 + +Neatlogs는 **에이전트가 무엇을 했는지**, **이유는 무엇인지**, 그리고 **공유하는 방법**을 확인할 수 있도록 도와줍니다. + +모든 단계를 캡처합니다: 생각, 도구 호출, 응답, 평가 등. 원시 로그는 없습니다. 명확하고 구조화된 추적만 제공합니다. 디버깅과 협업에 탁월합니다. + +## 왜 Neatlogs를 사용해야 하나요? + +CrewAI 에이전트는 여러 도구와 추론 단계를 사용합니다. 문제가 발생했을 때, 단순한 오류만으로는 충분하지 않습니다 — 맥락이 필요합니다. + +Neatlogs를 사용하면 다음과 같은 이점이 있습니다: + +- 전체 의사 결정 경로를 따라갈 수 있습니다 +- 단계마다 직접 피드백을 남길 수 있습니다 +- AI 어시스턴트와 함께 트레이스에 대해 채팅할 수 있습니다 +- 실행 결과를 공개적으로 공유해 피드백을 받을 수 있습니다 +- 인사이트를 업무로 전환할 수 있습니다 + +모두 한 곳에서 가능합니다. + +트레이스를 손쉽게 관리하세요 + +![Traces](/images/neatlogs-1.png) +![Trace Response](/images/neatlogs-2.png) + +CrewAI 트레이스를 보기 위한 최고의 UX. 원하는 곳 어디든 댓글을 남기세요. AI를 활용해 디버깅할 수 있습니다. + +![Trace Details](/images/neatlogs-3.png) +![Ai Chat Bot With A Trace](/images/neatlogs-4.png) +![Comments Drawer](/images/neatlogs-5.png) + +## 핵심 기능 + +- **Trace Viewer**: 사고, 도구, 결정을 순서대로 추적 +- **인라인 댓글**: 모든 trace 단계에서 팀원을 태그 +- **피드백 및 평가**: 출력물을 올바름 또는 틀림으로 표시 +- **오류 하이라이팅**: API/도구 실패 자동 감지 +- **작업 전환**: 댓글을 할당된 작업으로 변환 +- **Ask the Trace (AI)**: Neatlogs AI 봇과 trace에서 채팅 +- **공개 공유**: trace 링크를 커뮤니티에 게시 + +## CrewAI로 빠른 설정하기 + + + + [neatlogs.com](https://neatlogs.com/?utm_source=crewAI-docs)에 방문하여 프로젝트를 생성하고, API 키를 복사하세요. + + + ```bash + pip install neatlogs + ``` + (최신 버전 0.8.0, Python 3.8+; MIT 라이선스) + + + Crew 에이전트를 시작하기 전에 다음을 추가하세요: + + ```python + import neatlogs + neatlogs.init("YOUR_PROJECT_API_KEY") + ``` + + 에이전트는 평소와 같이 실행됩니다. Neatlogs가 모든 것을 자동으로 캡처합니다. + + + + +## 내부 구조 + +GitHub에 따르면, Neatlogs는: + +- 생각, 도구 호출, 응답, 오류, 그리고 토큰 통계를 캡처합니다 +- AI 기반 작업 생성과 견고한 평가 워크플로우를 지원합니다 + +이 모든 것이 단 두 줄의 코드로 가능합니다. + +## 작동하는 모습을 살펴보기 + +### 🔍 전체 데모 (4 분) + + + +### ⚙️ CrewAI 통합 (30초) + + + +## 링크 & 지원 + +- 📘 [Neatlogs 문서](https://docs.neatlogs.com/) +- 🔐 [대시보드 & API 키](https://app.neatlogs.com/) +- 🐦 [트위터 팔로우](https://twitter.com/neatlogs) +- 📧 문의: hello@neatlogs.com +- 🛠 [GitHub SDK](https://github.com/NeatLogs/neatlogs) + +## TL;DR + +아래와 같이: + +```bash +pip install neatlogs + +import neatlogs +neatlogs.init("YOUR_API_KEY") + +You can now capture, understand, share, and act on your CrewAI agent runs in seconds. +No setup overhead. Full trace transparency. Full team collaboration. +``` + +이제 몇 초 만에 CrewAI agent 실행을 캡처, 이해, 공유하고 바로 조치할 수 있습니다. +별도의 설정이 필요하지 않습니다. 완전한 트레이스 투명성. 전체 팀 협업 지원. diff --git a/docs/v1.15.1/ko/observability/openlit.mdx b/docs/v1.15.1/ko/observability/openlit.mdx new file mode 100644 index 000000000..68ecdd55e --- /dev/null +++ b/docs/v1.15.1/ko/observability/openlit.mdx @@ -0,0 +1,181 @@ +--- +title: OpenLIT 통합 +description: OpenTelemetry와 함께 단 한 줄의 코드로 에이전트를 신속하게 모니터링을 시작하세요. +icon: magnifying-glass-chart +mode: "wide" +--- + +# OpenLIT 개요 + +[OpenLIT](https://github.com/openlit/openlit?src=crewai-docs)은 오픈 소스 도구로, 단 **한** 줄의 코드만으로 AI 에이전트, LLM, VectorDB, GPU의 성능을 간편하게 모니터링할 수 있습니다. + +OpenTelemetry-기반의 트레이싱 및 메트릭을 제공하여 비용, 지연 시간, 상호작용, 작업 시퀀스와 같은 주요 파라미터를 추적할 수 있습니다. +이 설정을 통해 하이퍼파라미터를 추적하고 성능 문제를 모니터링하며, 시간이 지남에 따라 에이전트를 개선하고 미세 조정할 방법을 찾을 수 있습니다. + + + 비용 및 토큰을 포함한 에이전트 사용 개요 + 에이전트 otel 트레이스 및 메트릭 개요 + 에이전트 트레이스 상세 개요 + + +### 기능 + +- **분석 대시보드**: 에이전트의 상태와 성능을 모니터링할 수 있는 대시보드를 통해 지표, 비용, 사용자 상호작용을 자세히 추적할 수 있습니다. +- **OpenTelemetry-네이티브 가시성 SDK**: Grafana, DataDog 등 기존 가시성 도구로 추적 및 지표를 전송할 수 있는 벤더 중립적 SDK를 제공합니다. +- **커스텀 및 파인튜닝 모델 비용 추적**: 정확한 예산 책정을 위해 커스텀 가격 파일을 사용하여 특정 모델의 비용 추정치를 맞춤화할 수 있습니다. +- **예외 모니터링 대시보드**: 모니터링 대시보드를 통해 일반적인 예외 및 오류를 추적하여 문제를 신속하게 찾아내고 해결할 수 있습니다. +- **컴플라이언스 및 보안**: 욕설 및 PII 유출과 같은 잠재적인 위협을 탐지합니다. +- **프롬프트 인젝션 탐지**: 잠재적인 코드 인젝션 및 비밀 유출을 식별합니다. +- **API 키 및 비밀 관리**: LLM API 키와 비밀을 중앙에서 안전하게 관리하여 안전하지 않은 관행을 방지합니다. +- **프롬프트 관리**: PromptHub을 사용하여 에이전트 프롬프트를 관리 및 버전 관리하고, 모든 에이전트에서 일관되고 쉽게 접근할 수 있습니다. +- **모델 플레이그라운드**: 배포 전에 CrewAI 에이전트에 사용할 다양한 모델을 테스트하고 비교할 수 있습니다. + +## 설치 안내 + + + + + + ```shell + git clone git@github.com:openlit/openlit.git + ``` + + + [OpenLIT 저장소](https://github.com/openlit/openlit)의 루트 디렉토리에서 아래 명령어를 실행하세요: + ```shell + docker compose up -d + ``` + + + + + ```shell + pip install openlit + ``` + + + 아래 두 줄을 애플리케이션 코드에 추가하세요: + + + ```python + import openlit + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + ``` + + CrewAI Agent 모니터링 예제: + + ```python + from crewai import Agent, Task, Crew, Process + import openlit + + openlit.init(disable_metrics=True) + # 에이전트 정의 + 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' + ) + + + # 작업 정의 + 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.", + ) + + # 매니저 에이전트 정의 + 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' + ) + + # 커스텀 매니저로 crew 인스턴스화 + crew = Crew( + agents=[researcher], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, + ) + + # crew 작업 시작 + result = crew.kickoff() + + print(result) + ``` + + + + 아래 두 줄을 애플리케이션 코드에 추가하세요: + ```python + import openlit + + openlit.init() + ``` + + OTEL export endpoint를 설정하려면 다음 명령어를 실행하세요: + ```shell + export OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318" + ``` + + CrewAI Async Agent 모니터링 예제: + + ```python + import asyncio + from crewai import Crew, Agent, Task + import openlit + + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + + # 코드 실행이 활성화된 에이전트 생성 + 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" + ) + + # 코드 실행이 필요한 작업 생성 + 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.", + ) + + # crew 생성 후 작업 추가 + analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] + ) + + # crew를 비동기적으로 kickoff 하는 함수 + async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + + # 비동기 함수 실행 + asyncio.run(async_crew_execution()) + ``` + + + 더 고급 설정 및 사용 사례는 OpenLIT [Python SDK 저장소](https://github.com/openlit/openlit/tree/main/sdk/python)를 참고하세요. + + + 이제 에이전트 관찰 데이터가 수집되어 OpenLIT으로 전송되고 있으므로, 다음 단계는 이 데이터를 시각화하고 분석하여 에이전트의 성능, 행동 및 개선이 필요한 영역에 대한 인사이트를 얻는 것입니다. + + 브라우저에서 `127.0.0.1:3000`으로 접속하여 바로 시작할 수 있습니다. 기본 자격 증명으로 로그인 가능합니다 + - **이메일**: `user@openlit.io` + - **비밀번호**: `openlituser` + + + 비용 및 토큰을 포함한 에이전트 사용 개요 + 에이전트 otel trace 및 메트릭 개요 + + + + \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/opik.mdx b/docs/v1.15.1/ko/observability/opik.mdx new file mode 100644 index 000000000..cbc891bf7 --- /dev/null +++ b/docs/v1.15.1/ko/observability/opik.mdx @@ -0,0 +1,131 @@ +--- +title: Opik 통합 +description: Comet Opik을 사용하여 CrewAI 애플리케이션을 포괄적인 트레이싱, 자동 평가, 프로덕션 준비 대시보드로 디버그, 평가 및 모니터링하는 방법을 알아보세요. +icon: meteor +mode: "wide" +--- + +# Opik 개요 + +[Comet Opik](https://www.comet.com/docs/opik/)을(를) 사용하여, 포괄적인 트레이싱, 자동 평가, 프로덕션 준비가 된 대시보드를 통해 LLM 애플리케이션, RAG 시스템, 에이전트 워크플로우를 디버깅, 평가 및 모니터링할 수 있습니다. + + + CrewAI와 함께하는 Opik 에이전트 모니터링 예시 + + +Opik은 CrewAI 애플리케이션 개발의 모든 단계에서 포괄적인 지원을 제공합니다: + +- **로그 트레이스 및 스팬**: 개발 및 프로덕션 시스템에서 LLM 호출과 애플리케이션 로직을 자동으로 추적하여 디버깅 및 분석이 가능합니다. 프로젝트 간 응답을 수동 또는 프로그램적으로 주석 달고, 조회하고, 비교할 수 있습니다. +- **LLM 애플리케이션 성능 평가**: 사용자 지정 테스트 세트로 평가하고, 내장된 평가 지표를 실행하거나 SDK 또는 UI에서 사용자만의 지표를 정의할 수 있습니다. +- **CI/CD 파이프라인 내 테스트**: PyTest 기반의 Opik LLM 단위 테스트로 신뢰할 수 있는 성능 기준선을 설정하세요. 프로덕션에서 연속 모니터링을 위한 온라인 평가도 실행할 수 있습니다. +- **프로덕션 데이터 모니터링 및 분석**: 프로덕션에서 보지 못한 데이터에 대한 모델의 성능을 이해하고, 새로운 개발 반복을 위한 데이터 세트를 생성할 수 있습니다. + +## 설치 + +Comet은 호스팅된 Opik 플랫폼을 제공하거나, 로컬에서 플랫폼을 실행할 수도 있습니다. + +호스팅 버전을 사용하려면 [무료 Comet 계정 만들기](https://www.comet.com/signup?utm_medium=github&utm_source=crewai_docs) 후 API 키를 발급받으세요. + +Opik 플랫폼을 로컬에서 실행하려면, [설치 가이드](https://www.comet.com/docs/opik/self-host/overview/)에서 자세한 정보를 확인하세요. + +이 가이드에서는 CrewAI의 빠른 시작 예제를 사용합니다. + + + + ```shell + pip install crewai crewai-tools opik --upgrade + ``` + + + ```python + import opik + opik.configure(use_local=False) + ``` + + + 먼저, LLM 제공업체의 API 키를 환경 변수로 설정합니다: + + ```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: ") + ``` + + + 첫 번째 단계는 프로젝트를 만드는 것입니다. 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, + ) + + ``` + + 이제 Opik의 추적기를 임포트하고 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) + ``` + CrewAI 애플리케이션을 실행한 후에는 Opik 앱에서 다음을 확인할 수 있습니다: + - LLM 추적, span, 메타데이터 + - 에이전트 상호작용 및 태스크 실행 흐름 + - 지연 시간, 토큰 사용량 등의 성능 지표 + - 평가 지표(내장형 또는 사용자 정의) + + + +## 리소스 + +- [🦉 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/v1.15.1/ko/observability/overview.mdx b/docs/v1.15.1/ko/observability/overview.mdx new file mode 100644 index 000000000..32f71e2cc --- /dev/null +++ b/docs/v1.15.1/ko/observability/overview.mdx @@ -0,0 +1,120 @@ +--- +title: "개요" +description: "포괄적인 관측 도구로 CrewAI agent를 모니터링, 평가 및 최적화하세요" +icon: "face-smile" +mode: "wide" +--- + +## CrewAI를 위한 관측 가능성 + +관측 가능성은 CrewAI 에이전트의 성능을 이해하고, 병목 현상을 식별하며, 프로덕션 환경에서 신뢰할 수 있는 운영을 보장하는 데 매우 중요합니다. 이 섹션에서는 에이전트 워크플로우에 대한 모니터링, 평가, 최적화 기능을 제공하는 다양한 도구와 플랫폼을 다룹니다. + +## 관측 가능성이 중요한 이유 + +- **성능 모니터링**: 에이전트 실행 시간, 토큰 사용량, 자원 소비량 추적 +- **품질 보증**: 다양한 시나리오에서 출력 품질과 일관성 평가 +- **디버깅**: 에이전트 동작 및 태스크 실행에서의 문제 식별 및 해결 +- **비용 관리**: LLM API 사용량 및 관련 비용 모니터링 +- **지속적인 개선**: 시간 경과에 따른 에이전트 성능 최적화를 위한 인사이트 수집 + +## 사용 가능한 Observability 도구 + +### 모니터링 & 트레이싱 플랫폼 + + + + + 자동 에이전트 상호작용 캡처를 포함한 CrewAI 워크플로의 엔드-투-엔드 트레이싱. + + + + 비용 추적 및 성능 분석 기능이 포함된 OpenTelemetry 네이티브 모니터링. + + + + 트레이싱 및 평가 기능을 갖춘 머신러닝 라이프사이클 관리. + + + + 상세한 트레이싱과 분석을 제공하는 LLM 엔지니어링 플랫폼. + + + + LLM 및 에이전트 프레임워크를 위한 오픈소스 관측성 지원. + + + + 모니터링 및 문제 해결을 위한 AI 관측성 플랫폼. + + + + 종합적인 모니터링 및 신뢰성 기능을 갖춘 AI 게이트웨이. + + + + 포괄적인 트레이싱을 통한 LLM 애플리케이션 디버깅, 평가, 모니터링. + + + + AI 애플리케이션의 추적 및 평가를 위한 Weights & Biases 플랫폼. + + + +### 평가 및 품질 보증 + + + + LLM 출력 및 에이전트 행동에 대한 종합 평가 플랫폼입니다. + + + +## 주요 관측성 메트릭스 + +### 성능 지표 +- **실행 시간**: 에이전트가 작업을 완료하는 데 걸리는 시간 +- **토큰 사용량**: LLM 호출 시 소비된 입력/출력 토큰 +- **API 지연 시간**: 외부 서비스의 응답 시간 +- **성공률**: 성공적으로 완료된 작업의 비율 + +### 품질 지표 +- **출력 정확성**: 에이전트 응답의 정확성 +- **일관성**: 유사한 입력에 대한 신뢰성 +- **관련성**: 출력이 기대 결과와 얼마나 잘 일치하는지 +- **안전성**: 콘텐츠 정책 및 가이드라인 준수 + +### 비용 지표 +- **API 비용**: LLM 제공자 사용에 따른 지출 +- **리소스 활용**: 컴퓨팅 및 메모리 사용량 +- **작업당 비용**: 에이전트 운영의 경제적 효율성 +- **예산 추적**: 지출 한도 대비 모니터링 + +## 시작하기 + +1. **도구 선택하기**: 필요에 맞는 Observability 플랫폼을 선택하세요 +2. **코드 계측하기**: CrewAI 애플리케이션에 모니터링을 추가하세요 +3. **대시보드 설정하기**: 주요 지표에 대한 시각화를 구성하세요 +4. **알림 정의하기**: 중요한 이벤트에 대한 알림을 생성하세요 +5. **기준선 설정하기**: 비교를 위한 초기 성능을 측정하세요 +6. **반복 및 개선**: 인사이트를 활용하여 에이전트를 최적화하세요 + +## 모범 사례 + +### 개발 단계 +- 에이전트 행동을 이해하기 위해 상세 트레이싱 사용 +- 개발 초기에 평가 지표 구현 +- 테스트 중 리소스 사용량 모니터링 +- 자동화된 품질 검사 설정 + +### 운영 단계 +- 포괄적인 모니터링 및 알림 구현 +- 시간 경과에 따른 성능 추이 추적 +- 이상 현상 및 성능 저하 모니터링 +- 비용 가시성 및 통제 유지 + +### 지속적인 개선 +- 정기적인 성과 리뷰 및 최적화 +- 다양한 에이전트 구성의 A/B 테스트 +- 품질 향상을 위한 피드백 루프 +- 교훈 문서화 + +사용 사례, 인프라, 모니터링 요구 사항에 가장 적합한 observability 도구를 선택하여 CrewAI 에이전트가 신뢰성 있고 효율적으로 작동하도록 하세요. \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/patronus-evaluation.mdx b/docs/v1.15.1/ko/observability/patronus-evaluation.mdx new file mode 100644 index 000000000..23e037ad6 --- /dev/null +++ b/docs/v1.15.1/ko/observability/patronus-evaluation.mdx @@ -0,0 +1,206 @@ +--- +title: Patronus AI 평가 +description: Patronus AI의 종합 평가 플랫폼을 사용하여 CrewAI 에이전트의 성능과 LLM 출력 및 에이전트 행동을 모니터링하고 평가합니다. +icon: shield-check +mode: "wide" +--- + +# Patronus AI 평가 + +## 개요 + +[Patronus AI](https://patronus.ai)는 CrewAI 에이전트를 위한 종합적인 평가 및 모니터링 기능을 제공하여, 모델 출력, 에이전트 동작, 전체 시스템 성능을 평가할 수 있게 해줍니다. 이 통합을 통해 품질과 신뢰성을 유지하기 위한 지속적인 평가 워크플로우를 프로덕션 환경에 구현할 수 있습니다. + +## 주요 기능 + +- **자동 평가**: 에이전트 출력 및 행동의 실시간 평가 +- **맞춤 기준**: 사용 사례에 맞게 특정 평가 기준 정의 +- **성능 모니터링**: 에이전트 성능 지표를 시간에 따라 추적 +- **품질 보증**: 다양한 시나리오에서 일관된 출력 품질 보장 +- **안전성 및 준수**: 잠재적인 문제 및 정책 위반 모니터링 + +## 평가 도구 + +Patronus는 다양한 사용 사례를 위한 세 가지 주요 평가 도구를 제공합니다: + +1. **PatronusEvalTool**: 에이전트가 평가 작업에 가장 적합한 평가자와 기준을 선택할 수 있도록 합니다. +2. **PatronusPredefinedCriteriaEvalTool**: 사용자가 지정한 미리 정의된 평가자와 기준을 사용합니다. +3. **PatronusLocalEvaluatorTool**: 사용자가 정의한 커스텀 함수 평가자를 사용합니다. + +## 설치 + +이 도구들을 사용하려면 Patronus 패키지를 설치해야 합니다: + +```shell +uv add patronus +``` + +또한 Patronus API 키를 환경 변수로 설정해야 합니다: + +```shell +export PATRONUS_API_KEY="your_patronus_api_key" +``` + +## 시작 단계 + +Patronus 평가 도구를 효과적으로 사용하려면 다음 단계를 따르세요: + +1. **Patronus 설치**: 위의 명령어를 사용하여 Patronus 패키지를 설치합니다. +2. **API 키 설정**: Patronus API 키를 환경 변수로 설정합니다. +3. **적합한 도구 선택**: 필요에 따라 적절한 Patronus 평가 도구를 선택합니다. +4. **도구 구성**: 필요한 파라미터로 도구를 구성합니다. + +## 예시 + +### PatronusEvalTool 사용하기 + +다음 예제는 에이전트가 가장 적합한 평가자와 평가 기준을 선택할 수 있도록 해주는 `PatronusEvalTool`의 사용 방법을 보여줍니다: + +```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() +``` + +### PatronusPredefinedCriteriaEvalTool 사용하기 + +다음 예제는 미리 정의된 evaluator와 criteria를 사용하는 `PatronusPredefinedCriteriaEvalTool`의 사용 방법을 보여줍니다: + +```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() +``` + +### PatronusLocalEvaluatorTool 사용하기 + +다음 예시는 커스텀 함수 평가자를 사용하는 `PatronusLocalEvaluatorTool`의 사용 방법을 보여줍니다: + +```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() +``` + +## 파라미터 + +### PatronusEvalTool + +`PatronusEvalTool`은(는) 초기화 시에 어떠한 매개변수도 필요로 하지 않습니다. Patronus API에서 사용 가능한 평가자와 기준을 자동으로 가져옵니다. + +### PatronusPredefinedCriteriaEvalTool + +`PatronusPredefinedCriteriaEvalTool`은(는) 초기화 시 다음과 같은 파라미터를 받습니다: + +- **evaluators**: 필수. 사용할 evaluator와 criteria가 포함된 딕셔너리의 리스트입니다. 예시: `[{"evaluator": "judge", "criteria": "contains-code"}]`. + +### PatronusLocalEvaluatorTool + +`PatronusLocalEvaluatorTool`은(는) 초기화 시 다음과 같은 파라미터를 허용합니다: + +- **patronus_client**: 필수. Patronus 클라이언트 인스턴스입니다. +- **evaluator**: 선택 사항. 사용할 등록된 로컬 evaluator의 이름입니다. 기본값은 빈 문자열입니다. +- **evaluated_model_gold_answer**: 선택 사항. 평가에 사용할 gold answer입니다. 기본값은 빈 문자열입니다. + +## 사용법 + +Patronus 평가 도구를 사용할 때, 모델 입력, 출력 및 컨텍스트를 제공하면 도구가 Patronus API로부터 평가 결과를 반환합니다. + +`PatronusEvalTool` 및 `PatronusPredefinedCriteriaEvalTool`을 호출할 때는 다음과 같은 매개변수가 필요합니다: + +- **evaluated_model_input**: 에이전트의 작업 설명(간단한 텍스트). +- **evaluated_model_output**: 에이전트의 작업 결과. +- **evaluated_model_retrieved_context**: 에이전트의 컨텍스트. + +`PatronusLocalEvaluatorTool`의 경우에도 동일한 매개변수가 필요하지만, 평가자와 정답은 초기화 시에 지정합니다. + +## 결론 + +Patronus 평가 도구는 Patronus AI 플랫폼을 사용하여 모델 입력 및 출력을 평가하고 점수를 매길 수 있는 강력한 방법을 제공합니다. 에이전트가 자신의 출력 또는 다른 에이전트의 출력을 평가할 수 있도록 함으로써, 이러한 도구는 CrewAI 워크플로의 품질과 신뢰성을 향상시키는 데 도움을 줄 수 있습니다. \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/portkey.mdx b/docs/v1.15.1/ko/observability/portkey.mdx new file mode 100644 index 000000000..019cb35ea --- /dev/null +++ b/docs/v1.15.1/ko/observability/portkey.mdx @@ -0,0 +1,821 @@ +--- +title: Portkey 통합 +description: CrewAI에서 Portkey를 사용하는 방법 +icon: key +mode: "wide" +--- + +Portkey CrewAI 헤더 이미지 + +## 소개 + +Portkey는 CrewAI에 프로덕션 적합성을 위한 기능을 추가하여 실험적인 agent crew를 다음과 같이 견고한 시스템으로 전환합니다. + +- **모든 agent 단계, 도구 사용, 상호작용에 대한 완전한 관찰 가능성** +- **내장된 신뢰성**: 폴백, 재시도, 로드 밸런싱 기능 제공 +- **AI 비용 관리**를 위한 비용 추적 및 최적화 +- **단일 통합을 통한 200개 이상의 LLM 접근** +- **agent의 행동을 안전하고 규정 준수로 유지하는 가드레일** +- **일관된 agent 성능을 위한 버전 관리되는 prompt** + +### 설치 및 설정 + + + +```bash +pip install -U crewai portkey-ai +``` + + + +[Portkey 대시보드](https://app.portkey.ai/)에서 예산/속도 제한을 선택적으로 설정하여 Portkey API 키를 생성하세요. 이 키에는 신뢰성, 캐싱 등 여러 가지 구성을 추가로 적용할 수 있습니다. 자세한 내용은 추후 설명합니다. + + + +통합은 매우 간단합니다. CrewAI 설정의 LLM 구성을 다음과 같이 업데이트하기만 하면 됩니다: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Portkey 통합으로 LLM 인스턴스 생성 +gpt_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", # Virtual key를 사용하므로 이 값은 단순한 placeholder입니다. + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_LLM_VIRTUAL_KEY", + trace_id="unique-trace-id", # 요청 추적을 위한 선택 사항 + ) +) + +#Crew Agents에서 다음처럼 사용하세요: + + @agent + def lead_market_analyst(self) -> Agent: + return Agent( + config=self.agents_config['lead_market_analyst'], + verbose=True, + memory=False, + llm=gpt_llm + ) + +``` + + +**Virtual Key란?** Portkey의 Virtual Key는 LLM 제공업체의 API 키(OpenAI, Anthropic 등)를 암호화된 금고에 안전하게 저장합니다. 이를 통해 키 교체 및 예산 관리를 더 쉽게 할 수 있습니다. [Virtual Key에 대해 자세히 알아보기](https://portkey.ai/docs/product/ai-gateway/virtual-keys). + + + + +## 프로덕션 기능 + +### 1. 향상된 가시성 + +Portkey는 CrewAI agent에 대한 종합적인 가시성을 제공하여 각 실행 중에 어떤 일이 일어나고 있는지 정확히 이해할 수 있게 도와줍니다. + + + + + + + +Traces는 crew의 실행을 계층적으로 보여주며, LLM 호출, 도구 호출, 상태 전환의 순서를 확인할 수 있습니다. + +```python +# Portkey에서 계층적 추적을 활성화하려면 trace_id를 추가하세요 +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" # 고유한 trace ID 추가 + ) +) +``` + + + + + + + +Portkey는 LLM과의 모든 상호작용을 로그로 남깁니다. 여기에는 다음이 포함됩니다: + +- 전체 요청 및 응답 페이로드 +- 지연 시간 및 토큰 사용량 지표 +- 비용 계산 +- 도구 호출 및 함수 실행 + +모든 로그는 메타데이터, trace ID, 모델 등으로 필터링할 수 있어 특정 crew 실행을 쉽게 디버깅할 수 있습니다. + + + + + + + +Portkey는 사용자가 다음을 할 수 있도록 지원하는 내장 대시보드를 제공합니다: + +- 모든 crew 실행에서 비용 및 토큰 사용량 추적 +- 지연 시간, 성공률과 같은 성능 지표 분석 +- agent workflow의 병목 지점 식별 +- 서로 다른 crew 구성 및 LLM 비교 + +사용자는 모든 지표를 사용자 정의 메타데이터별로 필터링 및 세분화하여 특정 crew 유형, 사용자 그룹 또는 사용 사례를 분석할 수 있습니다. + + + + + Analytics with metadata filters + + +CrewAI LLM 구성에 사용자 정의 메타데이터를 추가하여 강력한 필터링 및 세분화를 활성화할 수 있습니다: + +```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", # 사용자 분석을 위한 특수 _user 필드 + "request_source": "mobile_app" + } + ) +) +``` + +이 메타데이터는 Portkey 대시보드에서 로그, trace, 지표를 필터링하는 데 사용될 수 있으며, 특정 crew 실행, 사용자 또는 환경을 분석할 수 있습니다. + + + +### 2. 신뢰성 - Crew를 원활하게 운영하세요 + +프로덕션에서 crew를 운영할 때, API 속도 제한, 네트워크 이슈 또는 공급자 장애와 같이 문제가 발생할 수 있습니다. Portkey의 신뢰성 기능은 문제가 발생해도 에이전트가 원활하게 동작하도록 보장합니다. + +Portkey Config를 사용하여 CrewAI 설정에서 페일오버를 간단하게 활성화할 수 있습니다: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with fallback configuration +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 this LLM configuration with your agents +``` + +이 설정은 GPT-4o 요청이 실패할 경우 자동으로 Claude를 시도하여 crew가 계속 운영될 수 있도록 보장합니다. + + + + 일시적인 실패를 자동으로 처리합니다. LLM 호출에 실패하면 Portkey가 지정된 횟수만큼 동일한 요청을 재시도합니다. 속도 제한이나 네트워크 장애에서 완벽하게 사용할 수 있습니다. + + + 에이전트가 멈추는 것을 방지합니다. 타임아웃을 설정하여 요구되는 시간 내에 응답을 받거나(혹은 우아하게 실패할 수 있도록) 합니다. + + + 다양한 요청을 다양한 공급자에게 보낼 수 있습니다. 복잡한 reasoning은 GPT-4로, 창의적인 작업은 Claude로, 빠른 응답은 Gemini로 필요에 따라 라우팅하세요. + + + 기본 공급자가 실패해도 계속 운영됩니다. 백업 공급자로 자동으로 전환되어 가용성을 유지합니다. + + + 여러 API 키 또는 공급자에 요청을 분산시킵니다. 대량 crew 운영 및 속도 제한 내에서 작업할 때 유용합니다. + + + +### 3. CrewAI에서의 프롬프트 사용 + +Portkey의 Prompt Engineering Studio는 CrewAI 에이전트에서 사용하는 프롬프트를 생성, 관리, 최적화하도록 도와줍니다. 프롬프트나 지시문을 하드코딩하는 대신 Portkey의 프롬프트 렌더링 API를 사용하여 버전 관리된 프롬프트를 동적으로 가져와 적용할 수 있습니다. + + +![Prompt Playground Interface](https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/refs/heads/main/CrewAI%20Portkey%20Docs.webp) + + + + +Prompt Playground는 여러분의 AI 애플리케이션을 위해 완벽한 프롬프트를 비교, 테스트, 배포할 수 있는 공간입니다. 이곳은 다양한 모델을 실험하고, 변수들을 테스트하며, 출력값을 비교하고, 배포 전에 프롬프트 엔지니어링 전략을 다듬을 수 있는 곳입니다. 이를 통해 다음과 같은 작업이 가능합니다: + +1. 에이전트에서 사용하기 전에 프롬프트를 반복적으로 개발 +2. 다양한 변수와 모델로 프롬프트 테스트 +3. 서로 다른 프롬프트 버전의 출력값 비교 +4. 팀원들과 프롬프트 개발 협업 + +이 시각적 환경을 통해 CrewAI 에이전트 워크플로우의 각 단계에 효과적인 프롬프트를 쉽게 작성할 수 있습니다. + + + +Prompt Render API를 통해 모든 파라미터가 구성된 프롬프트 템플릿을 가져올 수 있습니다: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL, Portkey + +# Initialize Portkey admin client +portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY") + +# Retrieve prompt using the 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"] + + +# Set up LLM with Portkey integration +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" + ) +) + +# Create agent using the rendered prompt +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory=backstory_agent, # Use the rendered prompt + verbose=True, + llm=portkey_llm +) +``` + + + +다음과 같은 작업을 수행할 수 있습니다: +- 동일한 프롬프트의 여러 버전을 생성 +- 버전 간의 성능 비교 +- 필요시 이전 버전으로 롤백 +- 코드에서 사용할 버전을 지정: + +```python +# Use a specific prompt version +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID@version_number", + variables={ + "agent_role": "Senior Research Scientist", + "agent_goal": "Discover groundbreaking insights" + } +) +``` + + + +Portkey 프롬프트는 손쉬운 변수 치환을 위해 머스태시(Mustache) 스타일의 템플릿을 사용합니다: + +``` +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}}. +``` + +렌더링할 때는 변수를 간단하게 전달하면 됩니다: + +```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" + } +) +``` + + + + + Portkey의 프롬프트 관리 기능에 대해 더 알아보기 + + +### 4. 안전한 Crew를 위한 가드레일 + +가드레일은 CrewAI agent가 모든 상황에서 안전하게 작동하고 적절하게 응답하도록 보장합니다. + +**가드레일을 사용하는 이유는 무엇인가요?** + +CrewAI agent는 다양한 실패 모드를 경험할 수 있습니다: +- 유해하거나 부적절한 콘텐츠 생성 +- PII와 같은 민감 정보 유출 +- 잘못된 정보의 환각 +- 잘못된 형식의 출력 생성 + +Portkey의 가드레일은 입력과 출력 모두에 대한 보호를 추가합니다. + +**가드레일 구현하기** + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with 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"] + } + ) +) + +# Create agent with guardrailed LLM +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 +) +``` + +Portkey의 가드레일은 다음을 수행할 수 있습니다: +- 입력 및 출력의 PII 감지 및 마스킹 +- 유해하거나 부적절한 콘텐츠 필터링 +- 응답 형식을 스키마에 따라 검증 +- 근거 자료와 비교하여 환각 여부 확인 +- 맞춤형 비즈니스 로직 및 규칙 적용 + + + Portkey의 가드레일 기능을 탐색하여 agent의 안전성을 높여보세요 + + +### 5. 메타데이터로 사용자 추적 + +Portkey의 메타데이터 시스템을 사용하여 CrewAI 에이전트를 통해 개별 사용자를 추적할 수 있습니다. + +**Portkey에서의 메타데이터란?** + +메타데이터를 사용하면 각 요청에 사용자 지정 데이터를 연결할 수 있어 필터링, 세분화, 분석이 가능합니다. 특별한 `_user` 필드는 사용자 추적을 위해 특별히 설계되었습니다. + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# 사용자 추적이 설정된 LLM 구성 +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", # 사용자 분석을 위한 특별 _user 필드 + "user_tier": "premium", + "user_company": "Acme Corp", + "session_id": "abc-123" + } + ) +) + +# 추적된 LLM으로 에이전트 생성 +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 +) +``` + +**사용자별로 분석 필터링** + +메타데이터가 설정되어 있으면, 사용자별로 분석을 필터링하고 사용자 단위의 성능 지표를 분석할 수 있습니다: + + + + + +이를 통해 다음이 가능합니다: +- 사용자별 비용 추적 및 예산 관리 +- 개인화된 사용자 분석 +- 팀 또는 조직 단위의 지표 +- 환경별 모니터링(스테이징 vs. 프로덕션) + + + 맞춤형 메타데이터를 활용하여 분석 기능을 향상시키는 방법을 살펴보세요 + + +### 6. 효율적인 Crews를 위한 캐싱 + +캐싱을 구현하여 CrewAI agent를 보다 효율적이고 비용 효율적으로 만드세요: + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with simple caching +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" + } + } + ) +) + +# Create agent with cached LLM +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 +) +``` + +Simple 캐싱은 입력 프롬프트에 대한 정확한 일치 항목을 수행하며, 동일한 요청을 캐시에 저장하여 중복된 모델 실행을 방지합니다. + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with semantic caching +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" + } + } + ) +) + +# Create agent with semantically cached LLM +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 +) +``` + +Semantic 캐싱은 입력 요청 간의 맥락적 유사성을 고려하여, 의미적으로 유사한 입력에 대한 응답을 캐시에 저장합니다. + + + +### 7. 모델 상호 운용성 + +CrewAI는 여러 LLM 제공업체를 지원하며, Portkey는 통합 인터페이스를 통해 200개 이상의 LLM에 대한 액세스를 제공함으로써 이 기능을 확장합니다. 코어 에이전트 로직을 변경하지 않고도 다양한 모델 간에 쉽게 전환할 수 있습니다: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Set up LLMs with different providers +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" + ) +) + +# Choose which LLM to use for each agent based on your needs +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 for Anthropic +) +``` + +Portkey는 다음을 포함한 제공업체의 LLM에 액세스를 제공합니다: + +- OpenAI (GPT-4o, GPT-4 Turbo 등) +- Anthropic (Claude 3.5 Sonnet, Claude 3 Opus 등) +- Mistral AI (Mistral Large, Mistral Medium 등) +- Google Vertex AI (Gemini 1.5 Pro 등) +- Cohere (Command, Command-R 등) +- AWS Bedrock (Claude, Titan 등) +- 로컬/프라이빗 모델 + + + Portkey에서 지원하는 전체 LLM 제공업체 목록 보기 + + +## CrewAI를 위한 엔터프라이즈 거버넌스 설정 + +**엔터프라이즈 거버넌스가 필요한 이유** +조직 내에서 CrewAI를 사용하는 경우, 여러 거버넌스 측면을 고려해야 합니다: +- **비용 관리**: 팀별 AI 사용 비용 통제 및 추적 +- **접근 제어**: 특정 팀이 특정 모델을 사용할 수 있도록 관리 +- **사용 분석**: 조직 전반에서 AI 사용 현황 파악 +- **보안 및 컴플라이언스**: 엔터프라이즈 수준의 보안 기준 유지 +- **신뢰성**: 모든 사용자에게 일관된 서비스 제공 보장 + +Portkey는 이러한 엔터프라이즈 요구를 해결하는 종합적인 거버넌스 계층을 추가합니다. 이제 이러한 컨트롤을 단계별로 구현해보겠습니다. + + + +Virtual Key는 Portkey의 안전한 LLM 공급자 API 키 관리 방식입니다. 주요 제어 기능을 제공합니다: +- API 사용에 대한 예산 제한 +- 속도 제한(Rate limiting) 기능 +- 안전한 API 키 저장 + +Virtual Key를 생성하려면: +Portkey 앱에서 [Virtual Keys](https://app.portkey.ai/virtual-keys)로 이동하세요. Virtual Key ID를 저장하고 복사하세요. + + + + + + +Virtual Key ID를 저장하세요. 다음 단계에서 필요합니다. + + + + +Portkey에서 Config는 요청 라우팅 방식을 정의하며, 고급 라우팅·폴백·재시도 등 기능을 제공합니다. + +Config를 생성하려면: +1. Portkey 대시보드의 [Configs](https://app.portkey.ai/configs)로 이동 +2. 아래와 같은 새 config 생성: + ```json + { + "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1", + "override_params": { + "model": "gpt-4o" // 선호하는 모델명 + } + } + ``` +3. Config 이름을 저장하고 다음 단계에 사용하세요. + + + + + + + +이제 Portkey API 키를 생성하고, 2단계에서 만든 config에 연결하세요: + +1. Portkey의 [API Keys](https://app.portkey.ai/api-keys)로 이동해 새 API 키 생성 +2. `2단계`에서 만든 config 선택 +3. API 키를 생성 및 저장 + + + + + + + +Portkey API 키와 config를 설정한 후, 이를 CrewAI agent에 연결하세요: + +```python +from crewai import Agent, LLM +from portkey_ai import PORTKEY_GATEWAY_URL + +# API 키로 LLM 구성 +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="YOUR_PORTKEY_API_KEY" +) + +# Portkey가 적용된 LLM으로 agent 생성 +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 +) +``` + + + + + + +### 1단계: 예산 통제 및 속도 제한 구현 + +Virtual Keys를 사용하면 팀/부서 수준에서 LLM 접근을 세밀하게 제어할 수 있습니다. 이를 통해 다음과 같은 이점이 있습니다: +- [예산 한도](https://portkey.ai/docs/product/ai-gateway/virtual-keys/budget-limits) 설정 +- 속도 제한을 통해 예기치 않은 사용량 급증 방지 +- 부서별 지출 추적 + +#### 부서별 제어 설정하기: +1. Portkey 대시보드에서 [Virtual Keys](https://app.portkey.ai/virtual-keys)로 이동하세요. +2. 각 부서마다 예산 한도와 속도 제한이 포함된 새로운 Virtual Key를 생성하세요. +3. 부서별 한도를 구성하세요. + + + + + + + + +### 단계 2: 모델 접근 규칙 정의 + +AI 사용이 확장됨에 따라, 각 팀이 특정 모델에 접근할 수 있도록 제어하는 것이 중요해집니다. Portkey Configs는 다음과 같은 기능을 제공하여 이러한 제어 계층을 지원합니다: + +#### 접근 제어 기능: +- **모델 제한**: 특정 모델에 대한 액세스 제한 +- **데이터 보호**: 민감한 데이터에 대한 가드레일 구현 +- **신뢰성 제어**: 폴백 및 재시도 로직 추가 + +#### 예시 구성: +다음은 OpenAI, 특히 GPT-4o로 요청을 라우팅하는 기본 구성입니다: + +```json +{ + "strategy": { + "mode": "single" + }, + "targets": [ + { + "virtual_key": "YOUR_OPENAI_VIRTUAL_KEY", + "override_params": { + "model": "gpt-4o" + } + } + ] +} +``` + +Portkey 대시보드에서 [구성 페이지](https://app.portkey.ai/configs)에서 자신의 구성을 생성하세요. + + +구성은 언제든지 업데이트하여 실행 중인 애플리케이션에 영향을 주지 않고 제어를 조정할 수 있습니다. + + + + +### 3단계: 액세스 제어 구현 + +사용자별 API 키를 생성하면 자동으로 다음을 수행합니다: +- 가상 키를 활용하여 사용자/팀별 사용량 추적 +- 요청 라우팅을 위한 적절한 구성 적용 +- 로그를 필터링하기 위한 관련 메타데이터 수집 +- 액세스 권한 적용 + +[Portkey App](https://app.portkey.ai/)를 통해 API 키를 생성하세요 + +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"] +) +``` + +자세한 키 관리 방법은 [Portkey 문서](https://portkey.ai/docs)를 참조하세요. + + + +### 4단계: 배포 및 모니터링 +팀원들에게 API 키를 배포한 후, 엔터프라이즈 준비가 완료된 CrewAI 설정이 준비됩니다. 이제 각 팀원은 지정된 API 키로 적절한 액세스 수준 및 예산 제어와 함께 사용할 수 있습니다. + +Portkey 대시보드에서 사용량 모니터링: +- 부서별 비용 추적 +- 모델 사용 패턴 +- 요청량 +- 오류율 + + + + + + +### 엔터프라이즈 기능이 이제 사용 가능합니다 +**귀하의 CrewAI 통합에는 이제 다음과 같은 기능이 포함됩니다:** +- 부서별 예산 관리 +- 모델 접근 거버넌스 +- 사용량 추적 및 귀속 +- 보안 가드레일 +- 신뢰성 기능 + + +## 자주 묻는 질문 + + + + Portkey는 종합적인 가시성(트레이스, 로그, 메트릭), 신뢰성 기능(폴백, 재시도, 캐싱) 및 통합 인터페이스를 통한 200개 이상의 LLM 접속을 통해 CrewAI에 프로덕션 환경에 적합한 기능을 추가합니다. 이를 통해 에이전트 애플리케이션을 더 쉽게 디버깅, 최적화, 확장할 수 있습니다. + + + + 네! Portkey는 기존 CrewAI 애플리케이션과 매끄럽게 통합됩니다. LLM 구성 코드를 Portkey가 적용된 버전으로 업데이트하기만 하면 됩니다. 나머지 에이전트 및 crew 코드는 변경하지 않아도 됩니다. + + + + Portkey는 에이전트, 도구, human-in-the-loop 워크플로우, 모든 태스크 프로세스 유형(순차적, 계층적 등)을 포함하여 모든 CrewAI 기능을 지원합니다. 프레임워크의 기능에 제한을 두지 않으면서 가시성과 신뢰성을 추가합니다. + + + + 네, Portkey를 사용하면 crew 내 여러 에이전트에 일관된 `trace_id`를 적용하여 전체 워크플로우를 추적할 수 있습니다. 특히 여러 에이전트가 포함된 복잡한 crew에서 전체 실행 경로를 파악할 때 유용합니다. + + + + Portkey를 통해 LLM 구성에 사용자 지정 메타데이터를 추가할 수 있으며, 이를 필터링에 활용할 수 있습니다. `crew_name`, `crew_type`, `session_id`와 같은 필드를 추가해 손쉽게 특정 crew 실행을 찾아 분석할 수 있습니다. + + + + 네! Portkey는 다양한 LLM 제공업체에 대해 사용자의 API 키를 사용합니다. API 키를 가상 키로 안전하게 저장하여, 코드 변경 없이 쉽게 키를 관리하고 교체할 수 있습니다. + + + + +## 자료 + + + +

공식 CrewAI 문서

+ + +

이 통합 구현에 대한 맞춤형 안내를 받아보세요

+ + \ No newline at end of file diff --git a/docs/v1.15.1/ko/observability/tracing.mdx b/docs/v1.15.1/ko/observability/tracing.mdx new file mode 100644 index 000000000..eae6188f6 --- /dev/null +++ b/docs/v1.15.1/ko/observability/tracing.mdx @@ -0,0 +1,214 @@ +--- +title: CrewAI Tracing +description: CrewAI AMP 플랫폼을 사용한 CrewAI Crews 및 Flows의 내장 추적 +icon: magnifying-glass-chart +mode: "wide" +--- + +# CrewAI 내장 추적 (Built-in Tracing) + +CrewAI는 Crews와 Flows를 실시간으로 모니터링하고 디버깅할 수 있는 내장 추적 기능을 제공합니다. 이 가이드는 CrewAI의 통합 관측 가능성 플랫폼을 사용하여 **Crews**와 **Flows** 모두에 대한 추적을 활성화하는 방법을 보여줍니다. + +> **CrewAI Tracing이란?** CrewAI의 내장 추적은 agent 결정, 작업 실행 타임라인, 도구 사용, LLM 호출을 포함한 AI agent에 대한 포괄적인 관측 가능성을 제공하며, 모두 [CrewAI AMP 플랫폼](https://app.crewai.com)을 통해 액세스할 수 있습니다. + +![CrewAI Tracing Interface](/images/crewai-tracing.png) + +## 사전 요구 사항 + +CrewAI 추적을 사용하기 전에 다음이 필요합니다: + +1. **CrewAI AMP 계정**: [app.crewai.com](https://app.crewai.com)에서 무료 계정에 가입하세요 +2. **CLI 인증**: CrewAI CLI를 사용하여 로컬 환경을 인증하세요 + +```bash +crewai login +``` + +## 설정 지침 + +### 1단계: CrewAI AMP 계정 생성 + +[app.crewai.com](https://app.crewai.com)을 방문하여 무료 계정을 만드세요. 이를 통해 추적, 메트릭을 보고 crews를 관리할 수 있는 CrewAI AMP 플랫폼에 액세스할 수 있습니다. + +### 2단계: CrewAI CLI 설치 및 인증 + +아직 설치하지 않았다면 CLI 도구와 함께 CrewAI를 설치하세요: + +```bash +uv add 'crewai[tools]' +``` + +그런 다음 CrewAI AMP 계정으로 CLI를 인증하세요: + +```bash +crewai login +``` + +이 명령은 다음을 수행합니다: + +1. 브라우저에서 인증 페이지를 엽니다 +2. 장치 코드를 입력하라는 메시지를 표시합니다 +3. CrewAI AMP 계정으로 로컬 환경을 인증합니다 +4. 로컬 개발을 위한 추적 기능을 활성화합니다 + +### 3단계: Crew에서 추적 활성화 + +`tracing` 매개변수를 `True`로 설정하여 Crew에 대한 추적을 활성화할 수 있습니다: + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +# Define your agents +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, + tools=[SerperDevTool()], +) + +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, +) + +# Create tasks for your agents +research_task = 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, +) + +writing_task = 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.\"\"\", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Enable tracing in your crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + tracing=True, # Enable built-in tracing + verbose=True +) + +# Execute your crew +result = crew.kickoff() +``` + +### 4단계: Flow에서 추적 활성화 + +마찬가지로 CrewAI Flows에 대한 추적을 활성화할 수 있습니다: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class ExampleFlow(Flow[ExampleState]): + def __init__(self): + super().__init__(tracing=True) # Enable tracing for the flow + + @start() + def first_method(self): + print("Starting the flow") + self.state.counter = 1 + self.state.message = "Flow started" + return "continue" + + @listen("continue") + def second_method(self): + print("Continuing the flow") + self.state.counter += 1 + self.state.message = "Flow continued" + return "finish" + + @listen("finish") + def final_method(self): + print("Finishing the flow") + self.state.counter += 1 + self.state.message = "Flow completed" + +# Create and run the flow with tracing enabled +flow = ExampleFlow(tracing=True) +result = flow.kickoff() +``` + +### 5단계: CrewAI AMP 대시보드에서 추적 보기 + +crew 또는 flow를 실행한 후 CrewAI AMP 대시보드에서 CrewAI 애플리케이션이 생성한 추적을 볼 수 있습니다. agent 상호 작용, 도구 사용 및 LLM 호출의 세부 단계를 볼 수 있습니다. +아래 링크를 클릭하여 추적을 보거나 대시보드의 추적 탭으로 이동하세요 [여기](https://app.crewai.com/crewai_plus/trace_batches) +![CrewAI Tracing Interface](/images/view-traces.png) + +### 대안: 환경 변수 구성 + +환경 변수를 설정하여 전역적으로 추적을 활성화할 수도 있습니다: + +```bash +export CREWAI_TRACING_ENABLED=true +``` + +또는 `.env` 파일에 추가하세요: + +```env +CREWAI_TRACING_ENABLED=true +``` + +이 환경 변수가 설정되면 `tracing=True`를 명시적으로 설정하지 않아도 모든 Crews와 Flows에 자동으로 추적이 활성화됩니다. + +## 추적 보기 + +### CrewAI AMP 대시보드 액세스 + +1. [app.crewai.com](https://app.crewai.com)을 방문하여 계정에 로그인하세요 +2. 프로젝트 대시보드로 이동하세요 +3. **Traces** 탭을 클릭하여 실행 세부 정보를 확인하세요 + +### 추적에서 볼 수 있는 내용 + +CrewAI 추적은 다음에 대한 포괄적인 가시성을 제공합니다: + +- **Agent 결정**: agent가 작업을 통해 어떻게 추론하고 결정을 내리는지 확인하세요 +- **작업 실행 타임라인**: 작업 시퀀스 및 종속성의 시각적 표현 +- **도구 사용**: 어떤 도구가 호출되고 그 결과를 모니터링하세요 +- **LLM 호출**: 프롬프트 및 응답을 포함한 모든 언어 모델 상호 작용을 추적하세요 +- **성능 메트릭**: 실행 시간, 토큰 사용량 및 비용 +- **오류 추적**: 세부 오류 정보 및 스택 추적 + +### 추적 기능 + +- **실행 타임라인**: 실행의 다양한 단계를 클릭하여 확인하세요 +- **세부 로그**: 디버깅을 위한 포괄적인 로그에 액세스하세요 +- **성능 분석**: 실행 패턴을 분석하고 성능을 최적화하세요 +- **내보내기 기능**: 추가 분석을 위해 추적을 다운로드하세요 + +### 인증 문제 + +인증 문제가 발생하는 경우: + +1. 로그인되어 있는지 확인하세요: `crewai login` +2. 인터넷 연결을 확인하세요 +3. [app.crewai.com](https://app.crewai.com)에서 계정을 확인하세요 + +### 추적이 나타나지 않음 + +대시보드에 추적이 표시되지 않는 경우: + +1. Crew/Flow에서 `tracing=True`가 설정되어 있는지 확인하세요 +2. 환경 변수를 사용하는 경우 `CREWAI_TRACING_ENABLED=true`인지 확인하세요 +3. `crewai login`으로 인증되었는지 확인하세요 +4. crew/flow가 실제로 실행되고 있는지 확인하세요 diff --git a/docs/v1.15.1/ko/observability/truefoundry.mdx b/docs/v1.15.1/ko/observability/truefoundry.mdx new file mode 100644 index 000000000..5d89a337c --- /dev/null +++ b/docs/v1.15.1/ko/observability/truefoundry.mdx @@ -0,0 +1,147 @@ +--- +title: TrueFoundry Integration +icon: chart-line +mode: "wide" +--- + +TrueFoundry provides an enterprise-ready [AI Gateway](https://www.truefoundry.com/ai-gateway) which can integrate with agentic frameworks like CrewAI and provides governance and observability for your AI Applications. TrueFoundry AI Gateway serves as a unified interface for LLM access, providing: + +- **Unified API Access**: Connect to 250+ LLMs (OpenAI, Claude, Gemini, Groq, Mistral) through one API +- **Low Latency**: Sub-3ms internal latency with intelligent routing and load balancing +- **Enterprise Security**: SOC 2, HIPAA, GDPR compliance with RBAC and audit logging +- **Quota and cost management**: Token-based quotas, rate limiting, and comprehensive usage tracking +- **Observability**: Full request/response logging, metrics, and traces with customizable retention + +## How TrueFoundry Integrates with CrewAI + + +### Installation & Setup + + + +```bash +pip install crewai +``` + + + +1. Sign up for a [TrueFoundry account](https://www.truefoundry.com/register) +2. Follow the steps here in [Quick start](https://docs.truefoundry.com/gateway/quick-start) + + + +![TrueFoundry Code Configuration](/images/new-code-snippet.png) + +```python +from crewai import LLM + +# Create an LLM instance with TrueFoundry AI Gateway +truefoundry_llm = LLM( + model="openai-main/gpt-4o", # Similarly, you can call any model from any provider + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Use in your CrewAI agents +from crewai import Agent + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + llm=truefoundry_llm, + verbose=True + ) +``` + + + +### Complete CrewAI Example + +```python +from crewai import Agent, Task, Crew, LLM + +# Configure LLM with TrueFoundry +llm = LLM( + model="openai-main/gpt-4o", + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Create agents +researcher = Agent( + role='Research Analyst', + goal='Conduct detailed market research', + backstory='Expert market analyst with attention to detail', + llm=llm, + verbose=True +) + +writer = Agent( + role='Content Writer', + goal='Create comprehensive reports', + backstory='Experienced technical writer', + llm=llm, + verbose=True +) + +# Create tasks +research_task = Task( + description='Research AI market trends for 2024', + agent=researcher, + expected_output='Comprehensive research summary' +) + +writing_task = Task( + description='Create a market research report', + agent=writer, + expected_output='Well-structured report with insights', + context=[research_task] +) + +# Create and execute crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +result = crew.kickoff() +``` + +### Observability and Governance + +Monitor your CrewAI agents through TrueFoundry's metrics tab: +![TrueFoundry metrics](/images/gateway-metrics.png) + +With Truefoundry's AI gateway, you can monitor and analyze: + +- **Performance Metrics**: Track key latency metrics like Request Latency, Time to First Token (TTFS), and Inter-Token Latency (ITL) with P99, P90, and P50 percentiles +- **Cost and Token Usage**: Gain visibility into your application's costs with detailed breakdowns of input/output tokens and the associated expenses for each model +- **Usage Patterns**: Understand how your application is being used with detailed analytics on user activity, model distribution, and team-based usage +- **Rate limit and Load balancing**: You can set up rate limiting, load balancing and fallback for your models + +## Tracing + +For a more detailed understanding on tracing, please see [getting-started-tracing](https://docs.truefoundry.com/docs/tracing/tracing-getting-started).For tracing, you can add the Traceloop SDK: +For tracing, you can add the Traceloop SDK: + +```bash +pip install traceloop-sdk +``` + +```python +from traceloop.sdk import Traceloop + +# Initialize enhanced tracing +Traceloop.init( + api_endpoint="https://your-truefoundry-endpoint/api/tracing", + headers={ + "Authorization": f"Bearer {your_truefoundry_pat_token}", + "TFY-Tracing-Project": "your_project_name", + }, +) +``` + +This provides additional trace correlation across your entire CrewAI workflow. +![TrueFoundry CrewAI Tracing](/images/tracing_crewai.png) diff --git a/docs/v1.15.1/ko/observability/weave.mdx b/docs/v1.15.1/ko/observability/weave.mdx new file mode 100644 index 000000000..195fd403f --- /dev/null +++ b/docs/v1.15.1/ko/observability/weave.mdx @@ -0,0 +1,125 @@ +--- +title: Weave 통합 +description: Weights & Biases(W&B) Weave를 사용하여 CrewAI 애플리케이션을 추적, 실험, 평가 및 개선하는 방법을 알아보세요. +icon: radar +mode: "wide" +--- + +# Weave 개요 + +[Weights & Biases (W&B) Weave](https://weave-docs.wandb.ai/)는 LLM 기반 애플리케이션을 추적, 실험, 평가, 배포 및 개선하기 위한 프레임워크입니다. + +![W&B Weave CrewAI 트레이싱 사용 개요](/images/weave-tracing.gif) + +Weave는 CrewAI 애플리케이션 개발의 모든 단계에서 포괄적인 지원을 제공합니다: + +- **트레이싱 및 모니터링**: LLM 호출과 애플리케이션 로직을 자동으로 추적하여 프로덕션 시스템을 디버그하고 분석 +- **체계적인 반복**: prompt, 데이터셋, 모델을 개선하고 반복 +- **평가**: 맞춤형 또는 사전 구축된 스코어러를 사용하여 agent 성능을 체계적으로 평가하고 향상 +- **가드레일**: 콘텐츠 모더레이션과 prompt 안전성을 위한 사전 및 사후 보호조치로 agent를 보호 + +Weave는 CrewAI 애플리케이션의 트레이스를 자동으로 캡처하여 agent의 성능, 상호 작용 및 실행 흐름을 모니터링하고 분석할 수 있게 해줍니다. 이를 통해 더 나은 평가 데이터셋을 구축하고 agent 워크플로우를 최적화할 수 있습니다. + +## 설치 안내 + + + + ```shell + pip install crewai weave + ``` + + + [Weights & Biases 계정](https://wandb.ai)에 가입하세요. 아직 계정이 없다면 가입이 필요합니다. 트레이스와 메트릭을 확인하려면 계정이 필요합니다. + + + 다음 코드를 애플리케이션에 추가하세요: + + ```python + import weave + + # 프로젝트 이름으로 Weave를 초기화 + weave.init(project_name="crewai_demo") + ``` + + 초기화 후, Weave는 트레이스와 메트릭을 확인할 수 있는 URL을 제공합니다. + + + ```python + from crewai import Agent, Task, Crew, LLM, Process + + # 결정론적 출력을 위해 temperature를 0으로 설정하여 LLM 생성 + llm = LLM(model="gpt-4o", temperature=0) + + # 에이전트 생성 + 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, + ) + + # 작업 생성 + 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 + ) + + # 크루 생성 + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential, + ) + + # 크루 실행 + result = crew.kickoff(inputs={"topic": "AI in material science"}) + print(result) + ``` + + + CrewAI 애플리케이션 실행 후, 초기화 시 제공된 Weave URL에 방문하여 다음 항목을 확인할 수 있습니다: + - LLM 호출 및 그 메타데이터 + - 에이전트 상호작용 및 작업 실행 흐름 + - 대기 시간 및 토큰 사용량과 같은 성능 메트릭 + - 실행 중 발생한 오류 또는 이슈 + + + Weave tracing example with CrewAI + + + + +## 특징 + +- Weave는 모든 CrewAI 작업을 자동으로 캡처합니다: agent 상호작용 및 태스크 실행; 메타데이터와 토큰 사용량을 포함한 LLM 호출; 도구 사용 및 결과. +- 이 통합은 모든 CrewAI 실행 메서드를 지원합니다: `kickoff()`, `kickoff_for_each()`, `kickoff_async()`, 그리고 `kickoff_for_each_async()`. +- 모든 [crewAI-tools](https://github.com/crewAIInc/crewAI-tools) 작업의 자동 추적. +- 데코레이터 패칭(`@start`, `@listen`, `@router`, `@or_`, `@and_`)을 통한 flow 기능 지원. +- `@weave.op()`과 함께 CrewAI `Task`에 전달된 커스텀 guardrails 추적. + +지원되는 항목에 대한 자세한 정보는 [Weave CrewAI 문서](https://weave-docs.wandb.ai/guides/integrations/crewai/#getting-started-with-flow)를 참조하세요. + +## 자료 + +- [📘 Weave 문서](https://weave-docs.wandb.ai) +- [📊 예시 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/v1.15.1/ko/quickstart.mdx b/docs/v1.15.1/ko/quickstart.mdx new file mode 100644 index 000000000..4fb54568f --- /dev/null +++ b/docs/v1.15.1/ko/quickstart.mdx @@ -0,0 +1,257 @@ +--- +title: 퀵스타트 +description: 몇 분 안에 첫 CrewAI Flow를 만듭니다 — 오케스트레이션, 상태, 그리고 실제 보고서를 만드는 에이전트 crew까지. +icon: rocket +mode: "wide" +--- + +### 영상: 코딩 에이전트 스킬을 활용한 CrewAI Agents & Flows 구축 + +코딩 에이전트 스킬(Claude Code, Codex 등)을 설치하여 CrewAI로 코딩 에이전트를 빠르게 시작하세요. + +`npx skills add crewaiinc/skills` 명령어로 설치할 수 있습니다 + + + +이 가이드에서는 **Flow**를 만들어 연구 주제를 정하고, **에이전트 한 명으로 구성된 crew**(웹 검색을 쓰는 연구원)를 실행한 뒤, 디스크에 **Markdown 보고서**를 남깁니다. Flow는 프로덕션 앱을 구성하는 권장 방식으로, **상태**와 **실행 순서**를 담당하고 **에이전트**는 crew 단계 안에서 실제 작업을 수행합니다. + +CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/installation)를 따르세요. + +## 사전 요건 + +- Python 환경과 CrewAI CLI([설치](/ko/installation) 참고) +- 올바른 API 키로 설정한 LLM — [LLM](/ko/concepts/llms#setting-up-your-llm) 참고 +- 이 튜토리얼의 웹 검색용 [Serper.dev](https://serper.dev/) API 키(`SERPER_API_KEY`) + +## 첫 번째 Flow 만들기 + + + + 터미널에서 Flow 프로젝트를 생성합니다(폴더 이름은 밑줄 형식입니다. 예: `latest_ai_flow`). + + + ```shell Terminal + crewai create flow latest-ai-flow + cd latest_ai_flow + ``` + + + 이렇게 하면 `src/latest_ai_flow/` 아래에 Flow 앱이 만들어지고, 다음 단계에서 **단일 에이전트** 연구 crew로 바꿀 시작용 crew가 `crews/content_crew/`에 포함됩니다. + + + + `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc`를 만듭니다(`agents/` 디렉터리가 없으면 생성). `{topic}` 같은 변수는 `crew.kickoff(inputs=...)`로 채워집니다. + + ```jsonc agents/researcher.jsonc + { + "role": "{topic} 시니어 데이터 리서처", + "goal": "{topic} 분야의 최신 동향을 파악한다", + "backstory": "당신은 가장 관련성 높은 정보를 찾아 명확하게 전달하는 연구원입니다.", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true + } + } + ``` + + + + + `src/latest_ai_flow/crews/content_crew/crew.jsonc`를 만듭니다: + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "{topic}에 대해 철저히 조사하세요. 웹 검색으로 최신이고 신뢰할 수 있는 정보를 찾으세요.", + "expected_output": "마크다운 보고서로, 주요 트렌드·주목할 도구나 기업·시사점 등으로 섹션을 나누세요. 분량은 약 800~1200단어. 문서 전체를 코드 펜스로 감싸지 마세요.", + "agent": "researcher", + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true + } + ``` + + + + + 생성된 `content_crew.py`를 `crew.jsonc`를 `Crew`로 바꾸는 작은 loader로 교체합니다. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py + from pathlib import Path + + from crewai.project import load_crew + + + def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) + ``` + + + + + crew를 Flow에 연결합니다: `@start()` 단계에서 주제를 **상태**에 넣고, `@listen` 단계에서 crew를 실행합니다. 작업의 `output_file`은 그대로 `output/report.md`에 씁니다. + + ```python main.py + # src/latest_ai_flow/main.py + from pydantic import BaseModel + + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"주제: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = kickoff_content_crew(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("연구 crew 실행 완료.") + + @listen(run_research) + def summarize(self): + print("보고서 경로: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() + ``` + + + 패키지 이름이 `latest_ai_flow`가 아니면 `kickoff_content_crew` import 경로를 프로젝트 모듈 경로에 맞게 바꾸세요. + + + + + 프로젝트 루트의 `.env`에 다음을 설정합니다. + + - `SERPER_API_KEY` — [Serper.dev](https://serper.dev/)에서 발급 + - 모델 제공자 키 — [LLM 설정](/ko/concepts/llms#setting-up-your-llm) 참고 + + + + + ```shell Terminal + crewai install + crewai run + ``` + + + `crewai run`은 프로젝트에 정의된 Flow 진입점을 실행합니다(crew와 동일한 명령이며, `pyproject.toml`의 프로젝트 유형은 `"flow"`입니다). + + + + Flow와 crew 로그가 출력되어야 합니다. 생성된 보고서는 **`output/report.md`**에서 확인하세요(발췌): + + + ```markdown output/report.md + # AI 에이전트: 최신 동향과 전망 + + ## 요약 + … + + ## 주요 트렌드 + - **도구 사용과 오케스트레이션** — … + - **엔터프라이즈 도입** — … + + ## 시사점 + … + ``` + + + 실제 파일은 더 길고 실시간 검색 결과를 반영합니다. + + + +## 한 번에 이해하기 + +1. **Flow** — `LatestAiFlow`는 `prepare_topic` → `run_research` → `summarize` 순으로 실행됩니다. 상태(`topic`, `report`)는 Flow에 있습니다. +2. **Crew** — `kickoff_content_crew`가 `crew.jsonc`를 로드하고 에이전트 한 명·작업 하나로 실행합니다. 연구원이 **Serper**로 웹을 검색하고 구조화된 보고서를 씁니다. +3. **결과물** — 작업의 `output_file`이 `output/report.md`에 보고서를 씁니다. + +Flow 패턴(라우팅, 지속성, human-in-the-loop)을 더 보려면 [첫 Flow 만들기](/ko/guides/flows/first-flow)와 [Flows](/ko/concepts/flows)를 참고하세요. Flow 없이 crew만 쓰려면 [Crews](/ko/concepts/crews)를, 작업 없이 단일 `Agent`의 `kickoff()`만 쓰려면 [Agents](/ko/concepts/agents#direct-agent-interaction-with-kickoff)를 참고하세요. + + +에이전트 crew와 저장된 보고서까지 이어진 Flow를 완성했습니다. 이제 단계·crew·도구를 더해 확장할 수 있습니다. + + +### 이름 일치 + +`crew.jsonc`의 이름은 파일과 참조에 맞아야 합니다: + +- `agents: ["researcher"]`는 `agents/researcher.jsonc`를 로드합니다. +- `tasks[].agent: "researcher"`는 해당 태스크를 그 에이전트에 배정합니다. + +## 배포 + +로컬에서 정상 실행되고 프로젝트가 **GitHub** 저장소에 있으면 Flow를 **[CrewAI AMP](https://app.crewai.com)**에 올릴 수 있습니다. 프로젝트 루트에서: + + +```bash 인증 +crewai login +``` + +```bash 배포 생성 +crewai deploy create +``` + +```bash 상태 및 로그 +crewai deploy status +crewai deploy logs +``` + +```bash 코드 변경 후 반영 +crewai deploy push +``` + +```bash 배포 목록 또는 삭제 +crewai deploy list +crewai deploy remove +``` + + + + 첫 배포는 보통 **약 1분** 정도 걸립니다. 전체 사전 요건과 웹 UI 절차는 [AMP에 배포](/ko/enterprise/guides/deploy-to-amp)를 참고하세요. + + + + + AMP 배포 단계별 안내(CLI 및 대시보드). + + + 아이디어를 나누고 프로젝트를 공유하며 다른 CrewAI 개발자와 소통하세요. + + diff --git a/docs/v1.15.1/ko/skills.mdx b/docs/v1.15.1/ko/skills.mdx new file mode 100644 index 000000000..f39e7f592 --- /dev/null +++ b/docs/v1.15.1/ko/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: skills.sh의 공식 레지스트리에서 crewaiinc/skills를 설치하세요. Claude Code, Cursor, Codex 등을 위한 Flow, Crew, 문서 연동 스킬. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**한 번의 명령으로 코딩 에이전트에 CrewAI 컨텍스트를 제공하세요.** + +CrewAI **Skills**는 **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**에 게시됩니다. `crewaiinc/skills`의 공식 레지스트리로, 개별 스킬(예: **design-agent**, **getting-started**, **design-task**, **ask-docs**), 설치 수, 감사 정보를 확인할 수 있습니다. Claude Code, Cursor, Codex 같은 코딩 에이전트에게 Flow 구성, Crew 설정, 도구 사용, CrewAI 패턴을 가르칩니다. 아래를 실행하거나 에이전트에 붙여 넣으세요. + +```shell Terminal +npx skills add crewaiinc/skills +``` + +에이전트 워크플로에 스킬 팩이 추가되어 세션마다 프레임워크를 다시 설명하지 않아도 CrewAI 관례를 적용할 수 있습니다. 소스와 이슈는 [GitHub](https://github.com/crewAIInc/skills)에서 관리합니다. + +## 에이전트가 얻는 것 + +- **Flows** — CrewAI 방식의 상태ful 앱, 단계, crew kickoff +- **Crew & 에이전트** — JSON-first 패턴(`crew.jsonc`, `agents/*.jsonc`), 역할, 작업, 위임 +- **도구 & 통합** — 검색, API, 일반적인 CrewAI 도구 연결 +- **프로젝트 구조** — CLI 스캐폴드 및 저장소 관례와 정렬 +- **최신 패턴** — 스킬이 현재 CrewAI 문서 및 권장 사항을 반영 + +## 이 사이트에서 더 알아보기 + + + + CrewAI와 `AGENTS.md`, 코딩 에이전트 워크플로 사용법. + + + 첫 Flow와 crew를 처음부터 끝까지 구축합니다. + + + CrewAI CLI와 Python 패키지를 설치합니다. + + + `crewaiinc/skills` 공식 목록—스킬, 설치 수, 감사. + + + 스킬 팩 소스, 업데이트, 이슈. + + + +### 영상: 코딩 에이전트 스킬과 CrewAI + + + +### 11. Chaves de API + +Ao executar o comando `crewai create crew`, o CLI mostrará provedores de LLM disponíveis e depois a seleção de modelo para o provedor escolhido. O modelo selecionado é salvo no `.env` gerado, e cada agente JSONC pode definir seu próprio `llm`. + +Após selecionar um provedor de LLM, será solicitado que você informe as chaves de API. + +#### Provedores iniciais de chave de API + +Inicialmente, o CLI solicitará as chaves de API para os seguintes serviços: + +- OpenAI +- Groq +- Anthropic +- Google Gemini +- SambaNova + +Ao selecionar um provedor, o CLI solicitará que você insira sua chave de API. + +#### Outras opções + +Se você selecionar a opção 6, será possível escolher de uma lista de provedores suportados pelo LiteLLM. + +Ao escolher um provedor, o CLI solicitará que você informe o nome da chave e a chave de API. + +Veja o seguinte link para o nome de chave de cada provedor: + +- [LiteLLM Providers](https://docs.litellm.ai/docs/providers) + +### 12. Gerenciamento de Configuração + +Gerencie as configurações do CLI para CrewAI. + +```shell Terminal +crewai config [COMANDO] [OPÇÕES] +``` + +#### Comandos: + +- `list`: Exibir todos os parâmetros de configuração do CLI + +```shell Terminal +crewai config list +``` + +- `set`: Definir um parâmetro de configuração do CLI + +```shell Terminal +crewai config set +``` + +- `reset`: Redefinir todos os parâmetros de configuração do CLI para valores padrão + +```shell Terminal +crewai config reset +``` + +#### Parâmetros de Configuração Disponíveis + +- `enterprise_base_url`: URL base da instância CrewAI AMP +- `oauth2_provider`: Provedor OAuth2 usado para autenticação (ex: workos, okta, auth0) +- `oauth2_audience`: Valor de audiência OAuth2, tipicamente usado para identificar a API ou recurso de destino +- `oauth2_client_id`: ID do cliente OAuth2 emitido pelo provedor, usado durante solicitações de autenticação +- `oauth2_domain`: Domínio do provedor OAuth2 (ex: sua-org.auth0.com) usado para emissão de tokens + +#### Exemplos + +Exibir configuração atual: + +```shell Terminal +crewai config list +``` + +Exemplo de saída: + +| Parâmetro | Valor | Descrição | +| :------------------ | :--------------------- | :------------------------------------------------------------- | +| enterprise_base_url | https://app.crewai.com | URL base da instância CrewAI AMP | +| org_name | Not set | Nome da organização atualmente ativa | +| org_uuid | Not set | UUID da organização atualmente ativa | +| oauth2_provider | workos | Provedor OAuth2 (ex.: workos, okta, auth0) | +| oauth2_audience | client_01YYY | Audience usada para identificar a API/recurso de destino | +| oauth2_client_id | client_01XXX | Client ID OAuth2 emitido pelo provedor (usado na autenticação) | +| oauth2_domain | login.crewai.com | Domínio do provedor OAuth2 (ex.: your-org.auth0.com) | + +Definir a URL base do enterprise: + +```shell Terminal +crewai config set enterprise_base_url https://minha-empresa.crewai.com +``` + +Definir provedor OAuth2: + +```shell Terminal +crewai config set oauth2_provider auth0 +``` + +Definir domínio OAuth2: + +```shell Terminal +crewai config set oauth2_domain minha-empresa.auth0.com +``` + +Redefinir todas as configurações para padrões: + +```shell Terminal +crewai config reset +``` + + + As configurações são armazenadas em `~/.config/crewai/settings.json`. Algumas + configurações como nome da organização e UUID são somente leitura e + gerenciadas através de comandos de autenticação e organização. Configurações + relacionadas ao repositório de ferramentas são ocultas e não podem ser + definidas diretamente pelo usuário. + diff --git a/docs/v1.15.1/pt-BR/concepts/collaboration.mdx b/docs/v1.15.1/pt-BR/concepts/collaboration.mdx new file mode 100644 index 000000000..6dbf6d3ac --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/collaboration.mdx @@ -0,0 +1,361 @@ +--- +title: Colaboração +description: Como permitir que agentes trabalhem juntos, deleguem tarefas e se comuniquem de forma eficaz em equipes CrewAI. +icon: screen-users +mode: "wide" +--- + +## Visão Geral + +A colaboração no CrewAI permite que agentes trabalhem juntos como uma equipe, delegando tarefas e fazendo perguntas para aproveitar a expertise uns dos outros. Quando `allow_delegation=True`, os agentes automaticamente têm acesso a poderosas ferramentas de colaboração. + +## Guia Rápido: Habilite a Colaboração + +```python +from crewai import Agent, Crew, Task + +# Enable collaboration for agents +researcher = Agent( + role="Especialista em Pesquisa", + goal="Realizar pesquisas aprofundadas sobre qualquer tema", + backstory="Pesquisador especialista com acesso a diversas fontes", + allow_delegation=True, # 🔑 Configuração chave para colaboração + verbose=True +) + +writer = Agent( + role="Redator de Conteúdo", + goal="Criar conteúdo envolvente com base em pesquisas", + backstory="Redator habilidoso que transforma pesquisas em conteúdo atraente", + allow_delegation=True, # 🔑 Permite fazer perguntas a outros agentes + verbose=True +) + +# Agents can now collaborate automatically +crew = Crew( + agents=[researcher, writer], + tasks=[...], + verbose=True +) +``` + +## Como Funciona a Colaboração entre Agentes + +Quando `allow_delegation=True`, o CrewAI automaticamente fornece aos agentes duas ferramentas poderosas: + +### 1. **Ferramenta de Delegação de Trabalho** +Permite que agentes designem tarefas para colegas com expertise específica. + +```python +# Agent automatically gets this tool: +# Delegate work to coworker(task: str, context: str, coworker: str) +``` + +### 2. **Ferramenta de Fazer Pergunta** +Permite que agentes façam perguntas específicas para obter informações de colegas. + +```python +# Agent automatically gets this tool: +# Ask question to coworker(question: str, context: str, coworker: str) +``` + +## Colaboração em Ação + +Veja um exemplo completo onde agentes colaboram em uma tarefa de criação de conteúdo: + +```python +from crewai import Agent, Crew, Task, Process + +# Create collaborative agents +researcher = Agent( + role="Especialista em Pesquisa", + goal="Realizar pesquisas aprofundadas sobre qualquer tema", + backstory="Pesquisador especialista com acesso a diversas fontes", + allow_delegation=True, + verbose=True +) + +writer = Agent( + role="Redator de Conteúdo", + goal="Criar conteúdo envolvente com base em pesquisas", + backstory="Redator habilidoso que transforma pesquisas em conteúdo atraente", + allow_delegation=True, + verbose=True +) + +editor = Agent( + role="Content Editor", + goal="Ensure content quality and consistency", + backstory="""You're an experienced editor with an eye for detail, + ensuring content meets high standards for clarity and accuracy.""", + allow_delegation=True, + verbose=True +) + +# Create a task that encourages collaboration +article_task = Task( + description="""Escreva um artigo abrangente de 1000 palavras sobre 'O Futuro da IA na Saúde'. + +O artigo deve incluir: +- Aplicações atuais de IA na saúde +- Tendências e tecnologias emergentes +- Desafios potenciais e considerações éticas +- Previsões de especialistas para os próximos 5 anos + +Colabore com seus colegas para garantir precisão e qualidade.""", + expected_output="Um artigo bem pesquisado, envolvente, com 1000 palavras, estrutura adequada e citações", + agent=writer # O redator lidera, mas pode delegar pesquisa ao pesquisador +) + +# Create collaborative crew +crew = Crew( + agents=[researcher, writer, editor], + tasks=[article_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff() +``` + +## Padrões de Colaboração + +### Padrão 1: Pesquisa → Redação → Edição +```python +research_task = Task( + description="Pesquise os últimos avanços em computação quântica", + expected_output="Resumo abrangente da pesquisa com principais descobertas e fontes", + agent=researcher +) + +writing_task = Task( + description="Escreva um artigo com base nos achados da pesquisa", + expected_output="Artigo envolvente de 800 palavras sobre computação quântica", + agent=writer, + context=[research_task] # Recebe a saída da pesquisa como contexto +) + +editing_task = Task( + description="Edite e revise o artigo para publicação", + expected_output="Artigo pronto para publicação, com clareza e fluidez aprimoradas", + agent=editor, + context=[writing_task] # Recebe o rascunho do artigo como contexto +) +``` + +### Padrão 2: Tarefa Única Colaborativa +```python +collaborative_task = Task( + description="""Crie uma estratégia de marketing para um novo produto de IA. + +Redator: Foque em mensagens e estratégia de conteúdo +Pesquisador: Forneça análise de mercado e insights de concorrentes + +Trabalhem juntos para criar uma estratégia abrangente.""", + expected_output="Estratégia de marketing completa com embasamento em pesquisa", + agent=writer # Agente líder, mas pode delegar ao pesquisador +) +``` + +## Colaboração Hierárquica + +Para projetos complexos, utilize um processo hierárquico com um agente gerente: + +```python +from crewai import Agent, Crew, Task, Process + +# Manager agent coordinates the team +manager = Agent( + role="Gerente de Projetos", + goal="Coordenar esforços da equipe e garantir o sucesso do projeto", + backstory="Gerente de projetos experiente, habilidoso em delegação e controle de qualidade", + allow_delegation=True, + verbose=True +) + +# Specialist agents +researcher = Agent( + role="Pesquisador", + goal="Fornecer pesquisa e análise precisas", + backstory="Pesquisador especialista com habilidades analíticas profundas", + allow_delegation=False, # Especialistas focam em sua expertise + verbose=True +) + +writer = Agent( + role="Redator", + goal="Criar conteúdo envolvente", + backstory="Redator habilidoso que cria conteúdo atraente", + allow_delegation=False, + verbose=True +) + +# Manager-led task +project_task = Task( + description="Crie um relatório de análise de mercado completo com recomendações", + expected_output="Resumo executivo, análise detalhada e recomendações estratégicas", + agent=manager # O gerente delega para especialistas +) + +# Hierarchical crew +crew = Crew( + agents=[manager, researcher, writer], + tasks=[project_task], + process=Process.hierarchical, # Manager coordinates everything + manager_llm="gpt-4o", # Specify LLM for manager + verbose=True +) +``` + +## Melhores Práticas para Colaboração + +### 1. **Definição Clara de Papéis** +```python +# ✅ Bom: papéis específicos e complementares +researcher = Agent(role="Market Research Analyst", ...) +writer = Agent(role="Technical Content Writer", ...) + +# ❌ Evite: Papéis sobrepostos ou vagos +agent1 = Agent(role="General Assistant", ...) +agent2 = Agent(role="Helper", ...) +``` + +### 2. **Delegação Estratégica Habilitada** +```python +# ✅ Habilite delegação para coordenadores e generalistas +lead_agent = Agent( + role="Content Lead", + allow_delegation=True, # Can delegate to specialists + ... +) + +# ✅ Desative para especialistas focados (opcional) +specialist_agent = Agent( + role="Data Analyst", + allow_delegation=False, # Focuses on core expertise + ... +) +``` + +### 3. **Compartilhamento de Contexto** +```python +# ✅ Use o parâmetro context para dependências entre tarefas +writing_task = Task( + description="Write article based on research", + agent=writer, + context=[research_task], # Shares research results + ... +) +``` + +### 4. **Descrições Claras de Tarefas** +```python +# ✅ Descrições específicas e acionáveis +Task( + description="""Research competitors in the AI chatbot space. + Focus on: pricing models, key features, target markets. + Provide data in a structured format.""", + ... +) + +# ❌ Descrições vagas que não orientam a colaboração +Task(description="Do some research about chatbots", ...) +``` + +## Solução de Problemas em Colaboração + +### Problema: Agentes Não Colaboram +**Sintomas:** Agentes trabalham isoladamente, sem ocorrer delegação +```python +# ✅ Solução: Certifique-se que a delegação está habilitada +agent = Agent( + role="...", + allow_delegation=True, # This is required! + ... +) +``` + +### Problema: Troca Excessiva de Perguntas +**Sintomas:** Agentes fazem perguntas em excesso, progresso lento +```python +# ✅ Solução: Forneça melhor contexto e papéis específicos +Task( + description="""Write a technical blog post about machine learning. + + Context: Target audience is software developers with basic ML knowledge. + Length: 1200 words + Include: code examples, practical applications, best practices + + If you need specific technical details, delegate research to the researcher.""", + ... +) +``` + +### Problema: Loops de Delegação +**Sintomas:** Agentes delegam tarefas repetidamente uns para os outros indefinidamente +```python +# ✅ Solução: Hierarquia e responsabilidades bem definidas +manager = Agent(role="Manager", allow_delegation=True) +specialist1 = Agent(role="Specialist A", allow_delegation=False) # No re-delegation +specialist2 = Agent(role="Specialist B", allow_delegation=False) +``` + +## Recursos Avançados de Colaboração + +### Regras Personalizadas de Colaboração +```python +# Set specific collaboration guidelines in agent backstory +agent = Agent( + role="Senior Developer", + backstory="""You lead development projects and coordinate with team members. + + Collaboration guidelines: + - Delegate research tasks to the Research Analyst + - Ask the Designer for UI/UX guidance + - Consult the QA Engineer for testing strategies + - Only escalate blocking issues to the Project Manager""", + allow_delegation=True +) +``` + +### Monitoramento da Colaboração +```python +def track_collaboration(output): + """Track collaboration patterns""" + if "Delegate work to coworker" in output.raw: + print("🤝 Delegation occurred") + if "Ask question to coworker" in output.raw: + print("❓ Question asked") + +crew = Crew( + agents=[...], + tasks=[...], + step_callback=track_collaboration, # Monitor collaboration + verbose=True +) +``` + +## Memória e Aprendizado + +Permita que agentes se lembrem de colaborações passadas: + +```python +agent = Agent( + role="Content Lead", + memory=True, # Remembers past interactions + allow_delegation=True, + verbose=True +) +``` + +Com a memória ativada, os agentes aprendem com colaborações anteriores e aprimoram suas decisões de delegação ao longo do tempo. + +## Próximos Passos + +- **Teste os exemplos**: Comece pelo exemplo básico de colaboração +- **Experimente diferentes papéis**: Teste combinações variadas de papéis de agentes +- **Monitore as interações**: Use `verbose=True` para ver a colaboração em ação +- **Otimize descrições de tarefas**: Tarefas claras geram melhor colaboração +- **Escale**: Experimente processos hierárquicos para projetos complexos + +A colaboração transforma agentes de IA individuais em equipes poderosas capazes de enfrentar desafios complexos e multifacetados juntos. \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/concepts/crews.mdx b/docs/v1.15.1/pt-BR/concepts/crews.mdx new file mode 100644 index 000000000..bb8298cde --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/crews.mdx @@ -0,0 +1,458 @@ +--- +title: Crews +description: Compreendendo e utilizando crews no framework crewAI com atributos e funcionalidades abrangentes. +icon: people-group +mode: "wide" +--- + +## Visão Geral + +Uma crew no crewAI representa um grupo colaborativo de agentes trabalhando em conjunto para alcançar um conjunto de tarefas. Cada crew define a estratégia de execução de tarefas, colaboração entre agentes e o fluxo de trabalho geral. + +## Atributos de Crew + +| Atributo | Parâmetros | Descrição | +| :------------------------------------ | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Tasks** | `tasks` | Uma lista de tasks atribuídas à crew. | +| **Agents** | `agents` | Uma lista de agentes que fazem parte da crew. | +| **Process** _(opcional)_ | `process` | O fluxo de processo (por exemplo, sequencial, hierárquico) seguido pela crew. O padrão é `sequential`. | +| **Verbose** _(opcional)_ | `verbose` | O nível de verbosidade para logging durante a execução. O padrão é `False`. | +| **Manager LLM** _(opcional)_ | `manager_llm` | O modelo de linguagem utilizado pelo agente gerenciador em um processo hierárquico. **Obrigatório ao usar um processo hierárquico.** | +| **Function Calling LLM** _(opcional)_ | `function_calling_llm` | Se definido, a crew utilizará este LLM para invocar funções das ferramentas para todos os agentes da crew. Cada agente pode ter seu próprio LLM, que substitui o LLM da crew para chamadas de função. | +| **Config** _(opcional)_ | `config` | Configurações opcionais para a crew, no formato `Json` ou `Dict[str, Any]`. | +| **Max RPM** _(opcional)_ | `max_rpm` | Número máximo de requisições por minuto que a crew respeita durante a execução. O padrão é `None`. | +| **Memory** _(opcional)_ | `memory` | Utilizada para armazenar memórias de execução (curto prazo, longo prazo, memória de entidade). | | +| **Cache** _(opcional)_ | `cache` | Especifica se deve usar cache para armazenar os resultados da execução de ferramentas. O padrão é `True`. | +| **Embedder** _(opcional)_ | `embedder` | Configuração do embedder a ser utilizado pela crew. Atualmente mais usado por memory. O padrão é `{"provider": "openai"}`. | +| **Step Callback** _(opcional)_ | `step_callback` | Uma função chamada após cada etapa de cada agente. Pode ser usada para registrar as ações do agente ou executar outras operações; não sobrescreve o `step_callback` específico do agente. | +| **Task Callback** _(opcional)_ | `task_callback` | Uma função chamada após a conclusão de cada tarefa. Útil para monitoramento ou para operações adicionais pós-execução da task. | +| **Share Crew** _(opcional)_ | `share_crew` | Se deseja compartilhar as informações completas da crew e execução com a equipe do crewAI para melhorar a biblioteca e nos permitir treinar modelos. | +| **Output Log File** _(opcional)_ | `output_log_file` | Defina como True para salvar logs como logs.txt no diretório atual ou forneça um caminho de arquivo. Os logs estarão em formato JSON se o nome terminar com .json, caso contrário .txt. O padrão é `None`. | +| **Manager Agent** _(opcional)_ | `manager_agent` | `manager` define um agente customizado que será utilizado como gerente. | +| **Prompt File** _(opcional)_ | `prompt_file` | Caminho para o arquivo JSON de prompt a ser utilizado pela crew. | +| **Planning** *(opcional)* | `planning` | Adiciona habilidade de planejamento à Crew. Quando ativado, antes de cada iteração, todos os dados da Crew são enviados a um AgentPlanner que planejará as tasks e este plano será adicionado à descrição de cada task. | +| **Planning LLM** *(opcional)* | `planning_llm` | O modelo de linguagem usado pelo AgentPlanner em um processo de planejamento. | +| **Knowledge Sources** _(opcional)_ | `knowledge_sources` | Fontes de conhecimento disponíveis no nível da crew, acessíveis a todos os agentes. | +| **Stream** _(opcional)_ | `stream` | Habilita saída em streaming para receber atualizações em tempo real durante a execução da crew. Retorna um objeto `CrewStreamingOutput` que pode ser iterado para chunks. O padrão é `False`. | + + +**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 principais de criar crews no CrewAI: utilizando **configuração JSONC (recomendada para novas crews)** ou definindo a crew **em código** para projetos clássicos e casos avançados. + +### Configuração JSONC (Recomendado) + +Novos projetos criados com `crewai create crew ` usam `crew.jsonc` para configurações da crew e tarefas, além de um arquivo por agente em `agents/`. `crewai run` detecta `crew.jsonc` ou `crew.json`, carrega os agentes referenciados, pergunta por placeholders ausentes e inicia a crew. + +```jsonc crew.jsonc +{ + "name": "Market Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research", + "description": "Research {topic} and collect the most relevant facts.", + "expected_output": "Structured research notes about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis", + "description": "Analyze the research and write a concise report.", + "expected_output": "A markdown report with findings and recommendations.", + "agent": "analyst", + "context": ["research"], + "output_file": "output/report.md" + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "AI Agents" + } +} +``` + +Cada string em `agents` resolve primeiro para `agents/.jsonc` e depois para `agents/.json`. Para crews hierárquicas, use `"process": "hierarchical"` com `manager_llm` ou `manager_agent`. + + +Execute projetos JSON apenas de fontes confiáveis. Ferramentas `custom:` e referências `{"python": "module.attribute"}` executam código Python local quando a crew é carregada. + + +### Configuração YAML Clássica + +Projetos clássicos criados com `crewai create crew --classic` usam `crew.py`, `config/agents.yaml`, `config/tasks.yaml` e os decorators `@CrewBase`, `@agent`, `@task` e `@crew`. + +Essa abordagem continua suportada para projetos existentes em Python/YAML e para equipes que precisam de controle explícito via decorators. + +Após criar um projeto clássico, você pode definir sua crew em uma classe que herda de `CrewBase` e utiliza decorators para definir agentes, tarefas e a própria crew. + +#### Exemplo de Classe Crew com Decorators + +```python code +from crewai import Agent, Crew, Task, Process +from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class YourCrewName: + """Descrição da sua crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + # Caminhos para seus arquivos de configuração YAML + # Para um exemplo de agente e tarefa definidos em YAML, confira: + # - Task: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended + # - Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' + + @before_kickoff + def prepare_inputs(self, inputs): + # Modifique inputs antes da crew iniciar + inputs['additional_data'] = "Alguma informação extra" + return inputs + + @after_kickoff + def process_output(self, output): + # Modifique a saída após a crew finalizar + output.raw += "\nProcessado após kickoff." + return output + + @agent + def agent_one(self) -> Agent: + return Agent( + config=self.agents_config['agent_one'], # type: ignore[index] + verbose=True + ) + + @agent + def agent_two(self) -> Agent: + return Agent( + config=self.agents_config['agent_two'], # type: ignore[index] + verbose=True + ) + + @task + def task_one(self) -> Task: + return Task( + config=self.tasks_config['task_one'] # type: ignore[index] + ) + + @task + def task_two(self) -> Task: + return Task( + config=self.tasks_config['task_two'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, # Coletado automaticamente pelo decorator @agent + tasks=self.tasks, # Coletado automaticamente pelo decorator @task + process=Process.sequential, + verbose=True, + ) +``` + +Como executar o código acima: + +```python code +YourCrewName().crew().kickoff(inputs={"any": "input here"}) +``` + + +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="Analista de Dados", + goal="Analisar tendências de dados no mercado brasileiro", + backstory="Analista experiente com formação em economia", + verbose=True, + tools=[YourCustomTool()] + ) + + def agent_two(self) -> Agent: + return Agent( + role="Pesquisador de Mercado", + goal="Coletar informações sobre a dinâmica do mercado nacional", + backstory="Pesquisador dedicado com olhar atento aos detalhes", + verbose=True + ) + + def task_one(self) -> Task: + return Task( + description="Coletar dados recentes do mercado brasileiro e identificar tendências.", + expected_output="Um relatório resumido com as principais tendências do mercado.", + agent=self.agent_one() + ) + + def task_two(self) -> Task: + return Task( + description="Pesquisar fatores que afetam a dinâmica do mercado nacional.", + expected_output="Uma análise dos fatores que influenciam o mercado.", + agent=self.agent_two() + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.agent_one(), self.agent_two()], + tasks=[self.task_one(), self.task_two()], + process=Process.sequential, + verbose=True + ) +``` +Como executar o código acima: + +```python code +YourCrewName().crew().kickoff(inputs={}) +``` + +Neste exemplo: + +- Agentes e tarefas são definidos diretamente dentro da classe, sem decorators. +- Criamos e gerenciamos manualmente a lista de agentes e tasks. +- Essa abordagem fornece mais controle, mas pode ser menos sustentável para projetos maiores. + +## Saída da Crew + +A saída de uma crew no framework CrewAI é encapsulada na classe `CrewOutput`. +Essa classe fornece uma forma estruturada de acessar os resultados da execução da crew, incluindo vários formatos como string bruta, JSON e modelos Pydantic. +O `CrewOutput` inclui os resultados da tarefa final, uso de tokens e as saídas das tasks individuais. + +### Atributos do Crew Output + +| Atributo | Parâmetros | Tipo | Descrição | +| :--------------- | :------------- | :------------------------ | :------------------------------------------------------------------------------------------------ | +| **Raw** | `raw` | `str` | A saída bruta da crew. Este é o formato padrão da saída. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | Um objeto modelo Pydantic representando a saída estruturada da crew. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]`| Um dicionário representando a saída da crew em formato JSON. | +| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | Uma lista de objetos `TaskOutput`, cada um representando a saída de uma task na crew. | +| **Token Usage** | `token_usage` | `Dict[str, Any]` | Um resumo do uso de tokens, oferecendo informações sobre a performance do modelo de linguagem. | + +### Métodos e Propriedades do Crew Output + +| Método/Propriedade | Descrição | +| :----------------- | :------------------------------------------------------------------------------------------------- | +| **json** | Retorna a representação em string JSON da saída da crew caso o formato seja JSON. | +| **to_dict** | Converte as saídas JSON e Pydantic em um dicionário. | +| **__str__** | Retorna a representação em string do resultado da crew, priorizando Pydantic, depois JSON, depois raw.| + +### Acessando a Saída da Crew + +Após executar uma crew, sua saída pode ser acessada pelo atributo `output` do objeto `Crew`. A classe `CrewOutput` oferece várias formas de interagir com esta saída. + +#### Exemplo + +```python Code +# Execução de exemplo da crew +crew = Crew( + agents=[research_agent, writer_agent], + tasks=[research_task, write_article_task], + verbose=True +) + +crew_output = crew.kickoff() + +# Acessando a saída da crew +print(f"Raw Output: {crew_output.raw}") +if crew_output.json_dict: + print(f"JSON Output: {json.dumps(crew_output.json_dict, indent=2)}") +if crew_output.pydantic: + print(f"Pydantic Output: {crew_output.pydantic}") +print(f"Tasks Output: {crew_output.tasks_output}") +print(f"Token Usage: {crew_output.token_usage}") +``` + +## Acessando Logs da Crew + +Você pode visualizar o log em tempo real da execução da crew, definindo `output_log_file` como `True(Boolean)` ou um `file_name(str)`. Suporta logging de eventos como tanto `file_name.txt` quanto `file_name.json`. +Se for `True(Boolean)`, salvará como `logs.txt`. + +Caso `output_log_file` seja `False(Boolean)` ou `None`, os logs não serão gerados. + +```python Code +# Salvar logs da crew +crew = Crew(output_log_file = True) # Logs serão salvos como logs.txt +crew = Crew(output_log_file = file_name) # Logs serão salvos como file_name.txt +crew = Crew(output_log_file = file_name.txt) # Logs serão salvos como file_name.txt +crew = Crew(output_log_file = file_name.json) # Logs serão salvos como file_name.json +``` + +## Utilização de Memória + +As crews podem utilizar memória (curto prazo, longo prazo e memória de entidade) para potencializar sua execução e aprendizado ao longo do tempo. Este recurso permite que as crews armazenem e recuperem memórias de execução, auxiliando na tomada de decisão e nas estratégias de execução de tasks. + +## Utilização de Cache + +Caches podem ser utilizados para armazenar resultados de execuções de ferramentas, tornando o processo mais eficiente ao evitar a reexecução de tasks idênticas. + +## Métricas de Uso da Crew + +Após a execução da crew, você pode acessar o atributo `usage_metrics` para visualizar as métricas de uso do modelo de linguagem (LLM) para todas as tasks executadas pela crew. Isso fornece insights sobre eficiência operacional e oportunidades de melhoria. + +```python Code +# Acessar as métricas de uso da crew +crew = Crew(agents=[agent1, agent2], tasks=[task1, task2]) +crew.kickoff() +print(crew.usage_metrics) +``` + +## Processo de Execução da Crew + +- **Sequential Process**: As tasks são executadas uma após a outra, permitindo um fluxo de trabalho linear. +- **Hierarchical Process**: Um agente gerente coordena a crew, delegando tarefas e validando resultados antes de prosseguir. **Nota**: Um `manager_llm` ou `manager_agent` é necessário para este processo e é essencial para validar o fluxo. + +### Iniciando uma Crew + +Uma vez que sua crew esteja montada, inicie o workflow com o método `kickoff()`. Isso inicia a execução conforme o fluxo de processo definido. + +```python Code +# Iniciar execução das tasks da crew +result = my_crew.kickoff() +print(result) +``` + +### Diferentes Formas de Iniciar uma Crew + +Assim que sua crew estiver definida, inicie o fluxo de trabalho com o método kickoff apropriado. O CrewAI oferece vários métodos para melhor controle do processo. + +#### Métodos Síncronos + +- `kickoff()`: Inicia o processo de execução seguindo o fluxo definido. +- `kickoff_for_each()`: Executa tasks sequencialmente para cada evento de entrada ou item da coleção fornecida. + +#### Métodos Assíncronos + +O CrewAI oferece duas abordagens para execução assíncrona: + +| Método | Tipo | Descrição | +|--------|------|-------------| +| `akickoff()` | Async nativo | Async/await verdadeiro em toda a cadeia de execução | +| `akickoff_for_each()` | Async nativo | Execução async nativa para cada entrada em uma lista | +| `kickoff_async()` | Baseado em thread | Envolve execução síncrona em `asyncio.to_thread` | +| `kickoff_for_each_async()` | Baseado em thread | Async baseado em thread para cada entrada em uma lista | + + +Para cargas de trabalho de alta concorrência, `akickoff()` e `akickoff_for_each()` são recomendados pois usam async nativo para execução de tasks, operações de memória e recuperação de conhecimento. + + +```python Code +# Iniciar execução das tasks da crew +result = my_crew.kickoff() +print(result) + +# Exemplo com kickoff_for_each +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +results = my_crew.kickoff_for_each(inputs=inputs_array) +for result in results: + print(result) + +# Exemplo usando async nativo com akickoff +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.akickoff(inputs=inputs) +print(async_result) + +# Exemplo usando async nativo com akickoff_for_each +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +async_results = await my_crew.akickoff_for_each(inputs=inputs_array) +for async_result in async_results: + print(async_result) + +# Exemplo usando kickoff_async baseado em thread +inputs = {'topic': 'AI in healthcare'} +async_result = await my_crew.kickoff_async(inputs=inputs) +print(async_result) + +# Exemplo usando kickoff_for_each_async baseado em thread +inputs_array = [{'topic': 'AI in healthcare'}, {'topic': 'AI in finance'}] +async_results = await my_crew.kickoff_for_each_async(inputs=inputs_array) +for async_result in async_results: + print(async_result) +``` + +Esses métodos fornecem flexibilidade para gerenciar e executar tasks dentro de sua crew, permitindo fluxos de trabalho síncronos e assíncronos de acordo com sua necessidade. Para exemplos detalhados de async, consulte o guia [Inicie uma Crew de Forma Assíncrona](/pt-BR/learn/kickoff-async). + +### Streaming na Execução da Crew + +Para visibilidade em tempo real da execução da crew, você pode habilitar streaming para receber saída conforme é gerada: + +```python Code +# Habilitar streaming +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +# Iterar sobre saída em streaming +streaming = crew.kickoff(inputs={"topic": "AI"}) +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Acessar resultado final +result = streaming.result +``` + +Saiba mais sobre streaming no guia [Streaming na Execução da Crew](/pt-BR/learn/streaming-crew-execution). + +### Repetindo Execução a partir de uma Task Específica + +Agora é possível reiniciar a execução a partir de uma task específica usando o comando CLI `replay`. + +O recurso de replay no CrewAI permite reexecutar a partir de uma task específica através da interface de linha de comando (CLI). Rodando o comando `crewai replay -t `, 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/v1.15.1/pt-BR/concepts/event-listener.mdx b/docs/v1.15.1/pt-BR/concepts/event-listener.mdx new file mode 100644 index 000000000..85cb201a8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/event-listener.mdx @@ -0,0 +1,414 @@ +--- +title: "Listeners de Evento" +description: "Acesse eventos do CrewAI para criar integrações e monitoramento personalizados" +icon: spinner +mode: "wide" +--- + +## Visão Geral + +O CrewAI oferece um sistema de eventos poderoso que permite escutar e reagir a diversos eventos que ocorrem durante a execução do seu Crew. Esse recurso possibilita a criação de integrações personalizadas, soluções de monitoramento, sistemas de log ou qualquer outra funcionalidade que precise ser acionada com base nos eventos internos do CrewAI. + +## Como Funciona + +O CrewAI utiliza uma arquitetura de event bus para emitir eventos ao longo do ciclo de vida da execução. O sistema de eventos é construído a partir dos seguintes componentes: + +1. **CrewAIEventsBus**: Um event bus singleton que gerencia o registro e emissão de eventos +2. **BaseEvent**: Classe base para todos os eventos do sistema +3. **BaseEventListener**: Classe base abstrata para criar listeners de evento personalizados + +Quando ações específicas ocorrem no CrewAI (como a inicialização de um Crew, um Agent concluindo uma tarefa ou o uso de uma ferramenta), o sistema emite os eventos correspondentes. Você pode registrar handlers para esses eventos para executar código personalizado quando eles acontecerem. + + +O CrewAI AMP fornece o recurso Prompt Tracing, que aproveita o sistema de eventos para rastrear, armazenar e visualizar todos os prompts, respostas e metadados associados. Isso proporciona poderosas capacidades de depuração e transparência nas operações dos seus agentes. + +![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.events import ( + CrewKickoffStartedEvent, + CrewKickoffCompletedEvent, + AgentExecutionCompletedEvent, +) +from crewai.events import BaseEventListener + +class MeuListenerPersonalizado(BaseEventListener): + def __init__(self): + super().__init__() + + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def ao_iniciar_crew(source, event): + print(f"Crew '{event.crew_name}' iniciou a execução!") + + @crewai_event_bus.on(CrewKickoffCompletedEvent) + def ao_finalizar_crew(source, event): + print(f"Crew '{event.crew_name}' finalizou a execução!") + print(f"Saída: {event.output}") + + @crewai_event_bus.on(AgentExecutionCompletedEvent) + def ao_finalizar_execucao_agente(source, event): + print(f"Agente '{event.agent.role}' concluiu a tarefa") + print(f"Saída: {event.output}") +``` + +## Registrando Corretamente Seu Listener + +Apenas definir sua classe de listener não é suficiente. É necessário criar uma instância dela e garantir que ela seja importada na sua aplicação. Isso garante que: + +1. Os event handlers estejam registrados no event bus +2. A instância do listener permaneça em memória (não seja coletada pelo garbage collector) +3. O listener esteja ativo quando os eventos forem emitidos + +### Opção 1: Importar e Instanciar no Seu Crew ou Implementação de Flow + +O mais importante é criar uma instância do seu listener no arquivo onde seu Crew ou Flow está definido e executado: + +#### Para Aplicações Baseadas em Crew + +Crie e importe seu listener no início do arquivo de implementação do seu Crew: + +```python +# No seu arquivo crew.py +from crewai import Agent, Crew, Task +from my_listeners import MyCustomListener + +# Crie uma instância do seu listener +my_listener = MyCustomListener() + +class MyCustomCrew: + # Sua implementação do crew... + + def crew(self): + return Crew( + agents=[...], + tasks=[...], + # ... + ) +``` + +#### Para Aplicações Baseadas em Flow + +Crie e importe seu listener no início do arquivo de implementação do seu Flow: + +```python +# Em seu arquivo main.py ou flow.py +from crewai.flow import Flow, listen, start +from my_listeners import MyCustomListener + +# Crie uma instância do seu listener +my_listener = MyCustomListener() + +class MyCustomFlow(Flow): + # Sua implementação do flow... + + @start() + def first_step(self): + # ... +``` + +Isso assegura que seu listener será carregado e estará ativo quando seu Crew ou Flow for executado. + +### Opção 2: Criar um Pacote para Seus Listeners + +Para uma abordagem mais estruturada, especialmente se houver múltiplos listeners: + +1. Crie um pacote para seus listeners: + +``` +my_project/ + ├── listeners/ + │ ├── __init__.py + │ ├── my_custom_listener.py + │ └── another_listener.py +``` + +2. Em `my_custom_listener.py`, defina sua classe de listener e crie uma instância: + +```python +# my_custom_listener.py +from crewai.events import BaseEventListener +# ... importe events ... + +class MyCustomListener(BaseEventListener): + # ... implementação ... + +# Crie uma instância do seu listener +my_custom_listener = MyCustomListener() +``` + +3. Em `__init__.py`, importe as instâncias dos listeners para garantir seu carregamento: + +```python +# __init__.py +from .my_custom_listener import my_custom_listener +from .another_listener import another_listener + +# Opcionalmente exporte-os se precisar acessá-los em outros lugares +__all__ = ['my_custom_listener', 'another_listener'] +``` + +4. Importe seu pacote de listeners no arquivo do seu Crew ou Flow: + +```python +# No seu arquivo crew.py ou flow.py +import my_project.listeners # Isso carrega todos os seus listeners + +class MyCustomCrew: + # Sua implementação do crew... +``` + +É assim que listeners de eventos de terceiros são registrados no código do CrewAI. + +## Tipos de Eventos Disponíveis + +O CrewAI fornece uma ampla variedade de eventos para escuta: + +### Eventos de Crew + +- **CrewKickoffStartedEvent**: Emitido quando um Crew inicia a execução +- **CrewKickoffCompletedEvent**: Emitido quando um Crew conclui a execução +- **CrewKickoffFailedEvent**: Emitido quando um Crew falha ao concluir a execução +- **CrewTestStartedEvent**: Emitido ao iniciar o teste de um Crew +- **CrewTestCompletedEvent**: Emitido ao concluir o teste de um Crew +- **CrewTestFailedEvent**: Emitido ao falhar no teste de um Crew +- **CrewTrainStartedEvent**: Emitido ao iniciar o treinamento de um Crew +- **CrewTrainCompletedEvent**: Emitido ao concluir o treinamento de um Crew +- **CrewTrainFailedEvent**: Emitido ao falhar no treinamento de um Crew +- **CrewTestResultEvent**: Emitido quando um resultado de teste de Crew está disponível. Contém a pontuação de qualidade, duração da execução e modelo utilizado. + +### Eventos de Agent + +- **AgentExecutionStartedEvent**: Emitido quando um Agent inicia a execução de uma tarefa +- **AgentExecutionCompletedEvent**: Emitido quando um Agent conclui a execução de uma tarefa +- **AgentExecutionErrorEvent**: Emitido quando um Agent encontra um erro durante a execução +- **LiteAgentExecutionStartedEvent**: Emitido quando um LiteAgent inicia a execução. Contém as informações do agente, ferramentas e mensagens. +- **LiteAgentExecutionCompletedEvent**: Emitido quando um LiteAgent conclui a execução. Contém as informações do agente e a saída. +- **LiteAgentExecutionErrorEvent**: Emitido quando um LiteAgent encontra um erro durante a execução. Contém as informações do agente e a mensagem de erro. +- **AgentEvaluationStartedEvent**: Emitido quando uma avaliação de agente é iniciada. Contém o ID do agente, papel do agente, ID da tarefa opcional e número da iteração. +- **AgentEvaluationCompletedEvent**: Emitido quando uma avaliação de agente é concluída. Contém o ID do agente, papel do agente, ID da tarefa opcional, número da iteração, categoria da métrica e pontuação. +- **AgentEvaluationFailedEvent**: Emitido quando uma avaliação de agente falha. Contém o ID do agente, papel do agente, ID da tarefa opcional, número da iteração e mensagem de erro. + +### Eventos de Task + +- **TaskStartedEvent**: Emitido ao iniciar a execução de uma Task +- **TaskCompletedEvent**: Emitido ao concluir a execução de uma Task +- **TaskFailedEvent**: Emitido ao falhar na execução de uma Task +- **TaskEvaluationEvent**: Emitido quando uma Task é avaliada + +### Eventos de Uso de Ferramentas + +- **ToolUsageStartedEvent**: Emitido ao iniciar a execução de uma ferramenta +- **ToolUsageFinishedEvent**: Emitido ao concluir a execução de uma ferramenta +- **ToolUsageErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta +- **ToolValidateInputErrorEvent**: Emitido ao ocorrer erro de validação de entrada na ferramenta +- **ToolExecutionErrorEvent**: Emitido quando ocorre erro na execução de uma ferramenta +- **ToolSelectionErrorEvent**: Emitido ao ocorrer erro na seleção de uma ferramenta + +### Eventos de MCP + +- **MCPConnectionStartedEvent**: Emitido ao iniciar a conexão com um servidor MCP. Contém o nome do servidor, URL, tipo de transporte, timeout de conexão e se é uma tentativa de reconexão. +- **MCPConnectionCompletedEvent**: Emitido ao conectar com sucesso a um servidor MCP. Contém o nome do servidor, duração da conexão em milissegundos e se foi uma reconexão. +- **MCPConnectionFailedEvent**: Emitido quando a conexão com um servidor MCP falha. Contém o nome do servidor, mensagem de erro e tipo de erro (`timeout`, `authentication`, `network`, etc.). +- **MCPToolExecutionStartedEvent**: Emitido ao iniciar a execução de uma ferramenta MCP. Contém o nome do servidor, nome da ferramenta e argumentos da ferramenta. +- **MCPToolExecutionCompletedEvent**: Emitido quando a execução de uma ferramenta MCP é concluída com sucesso. Contém o nome do servidor, nome da ferramenta, resultado e duração da execução em milissegundos. +- **MCPToolExecutionFailedEvent**: Emitido quando a execução de uma ferramenta MCP falha. Contém o nome do servidor, nome da ferramenta, mensagem de erro e tipo de erro (`timeout`, `validation`, `server_error`, etc.). +- **MCPConfigFetchFailedEvent**: Emitido quando a obtenção da configuração de um servidor MCP falha (ex.: o MCP não está conectado na sua conta, erro de API ou falha de conexão após a configuração ser obtida). Contém o slug, mensagem de erro e tipo de erro (`not_connected`, `api_error`, `connection_failed`). + +### Eventos de Knowledge + +- **KnowledgeRetrievalStartedEvent**: Emitido ao iniciar recuperação de conhecimento +- **KnowledgeRetrievalCompletedEvent**: Emitido ao concluir recuperação de conhecimento +- **KnowledgeQueryStartedEvent**: Emitido ao iniciar consulta de conhecimento +- **KnowledgeQueryCompletedEvent**: Emitido ao concluir consulta de conhecimento +- **KnowledgeQueryFailedEvent**: Emitido ao falhar consulta de conhecimento +- **KnowledgeSearchQueryFailedEvent**: Emitido ao falhar consulta de busca de conhecimento + +### Eventos de Guardrail do LLM + +- **LLMGuardrailStartedEvent**: Emitido ao iniciar validação dos guardrails. Contém detalhes do guardrail aplicado e tentativas. +- **LLMGuardrailCompletedEvent**: Emitido ao concluir validação dos guardrails. Contém detalhes sobre sucesso/falha na validação, resultados e mensagens de erro, se houver. +- **LLMGuardrailFailedEvent**: Emitido quando a validação do guardrail falha. Contém a mensagem de erro e o número de tentativas. + +### Eventos de Flow + +- **FlowCreatedEvent**: Emitido ao criar um Flow +- **FlowStartedEvent**: Emitido ao iniciar a execução de um Flow +- **FlowFinishedEvent**: Emitido ao concluir a execução de um Flow +- **FlowPausedEvent**: Emitido quando um Flow é pausado aguardando feedback humano. Contém o nome do flow, ID do flow, nome do método, estado atual, mensagem exibida ao solicitar feedback e lista opcional de resultados possíveis para roteamento. +- **FlowPlotEvent**: Emitido ao plotar um Flow +- **MethodExecutionStartedEvent**: Emitido ao iniciar a execução de um método do Flow +- **MethodExecutionFinishedEvent**: Emitido ao concluir a execução de um método do Flow +- **MethodExecutionFailedEvent**: Emitido ao falhar na execução de um método do Flow +- **MethodExecutionPausedEvent**: Emitido quando um método do Flow é pausado aguardando feedback humano. Contém o nome do flow, nome do método, estado atual, ID do flow, mensagem exibida ao solicitar feedback e lista opcional de resultados possíveis para roteamento. + +### Eventos de Human In The Loop + +- **FlowInputRequestedEvent**: Emitido quando um Flow solicita entrada do usuário via `Flow.ask()`. Contém o nome do flow, nome do método, a pergunta ou prompt exibido ao usuário e metadados opcionais (ex.: ID do usuário, canal, contexto da sessão). +- **FlowInputReceivedEvent**: Emitido quando a entrada do usuário é recebida após `Flow.ask()`. Contém o nome do flow, nome do método, a pergunta original, a resposta do usuário (ou `None` se expirou), metadados opcionais da solicitação e metadados opcionais da resposta do provedor (ex.: quem respondeu, ID do thread, timestamps). +- **HumanFeedbackRequestedEvent**: Emitido quando um método decorado com `@human_feedback` requer entrada de um revisor humano. Contém o nome do flow, nome do método, a saída do método exibida ao humano para revisão, a mensagem exibida ao solicitar feedback e lista opcional de resultados possíveis para roteamento. +- **HumanFeedbackReceivedEvent**: Emitido quando um humano fornece feedback em resposta a um método decorado com `@human_feedback`. Contém o nome do flow, nome do método, o texto bruto do feedback fornecido pelo humano e a string de resultado consolidada (se emit foi especificado). + +### Eventos de LLM + +- **LLMCallStartedEvent**: Emitido ao iniciar uma chamada LLM +- **LLMCallCompletedEvent**: Emitido ao concluir uma chamada LLM +- **LLMCallFailedEvent**: Emitido ao falhar uma chamada LLM +- **LLMStreamChunkEvent**: Emitido para cada chunk recebido durante respostas em streaming do LLM +- **LLMThinkingChunkEvent**: Emitido quando um chunk de pensamento/raciocínio é recebido de um modelo de pensamento. Contém o texto do chunk e ID de resposta opcional. + +### Eventos de Memória + +- **MemoryQueryStartedEvent**: Emitido quando uma consulta de memória é iniciada. Contém a consulta, limite e threshold de pontuação opcional. +- **MemoryQueryCompletedEvent**: Emitido quando uma consulta de memória é concluída com sucesso. Contém a consulta, resultados, limite, threshold de pontuação e tempo de execução da consulta. +- **MemoryQueryFailedEvent**: Emitido quando uma consulta de memória falha. Contém a consulta, limite, threshold de pontuação e mensagem de erro. +- **MemorySaveStartedEvent**: Emitido quando uma operação de salvamento de memória é iniciada. Contém o valor a ser salvo, metadados e papel do agente opcional. +- **MemorySaveCompletedEvent**: Emitido quando uma operação de salvamento de memória é concluída com sucesso. Contém o valor salvo, metadados, papel do agente e tempo de salvamento. +- **MemorySaveFailedEvent**: Emitido quando uma operação de salvamento de memória falha. Contém o valor, metadados, papel do agente e mensagem de erro. +- **MemoryRetrievalStartedEvent**: Emitido quando a recuperação de memória para um prompt de tarefa é iniciada. Contém o ID da tarefa opcional. +- **MemoryRetrievalCompletedEvent**: Emitido quando a recuperação de memória para um prompt de tarefa é concluída com sucesso. Contém o ID da tarefa, conteúdo da memória e tempo de execução da recuperação. +- **MemoryRetrievalFailedEvent**: Emitido quando a recuperação de memória para um prompt de tarefa falha. Contém o ID da tarefa opcional e mensagem de erro. + +### Eventos de Raciocínio + +- **AgentReasoningStartedEvent**: Emitido quando um agente começa a raciocinar sobre uma tarefa. Contém o papel do agente, ID da tarefa e número da tentativa. +- **AgentReasoningCompletedEvent**: Emitido quando um agente finaliza seu processo de raciocínio. Contém o papel do agente, ID da tarefa, o plano produzido e se o agente está pronto para prosseguir. +- **AgentReasoningFailedEvent**: Emitido quando o processo de raciocínio falha. Contém o papel do agente, ID da tarefa e mensagem de erro. + +### Eventos de Observação + +- **StepObservationStartedEvent**: Emitido quando o Planner começa a observar o resultado de um passo. Disparado após cada execução de passo, antes da chamada LLM de observação. Contém o papel do agente, número do passo e descrição do passo. +- **StepObservationCompletedEvent**: Emitido quando o Planner finaliza a observação do resultado de um passo. Contém se o passo foi concluído com sucesso, informações-chave aprendidas, se o plano restante ainda é válido, se é necessário um replanejamento completo e refinamentos sugeridos. +- **StepObservationFailedEvent**: Emitido quando a chamada LLM de observação falha. O sistema continua o plano por padrão. Contém a mensagem de erro. +- **PlanRefinementEvent**: Emitido quando o Planner refina descrições de passos futuros sem replanejamento completo. Contém o número de passos refinados e os refinamentos aplicados. +- **PlanReplanTriggeredEvent**: Emitido quando o Planner dispara um replanejamento completo porque o plano restante foi considerado fundamentalmente incorreto. Contém o motivo do replanejamento, contagem de replanejamentos e número de passos concluídos preservados. +- **GoalAchievedEarlyEvent**: Emitido quando o Planner detecta que o objetivo foi alcançado antecipadamente e os passos restantes serão ignorados. Contém o número de passos restantes e passos concluídos. + +### Eventos A2A (Agent-to-Agent) + +#### Eventos de Delegação + +- **A2ADelegationStartedEvent**: Emitido quando a delegação A2A é iniciada. Contém a URL do endpoint, descrição da tarefa, ID do agente, ID do contexto, se é multiturn, número do turno, metadados do agent card, versão do protocolo, informações do provedor e ID da skill opcional. +- **A2ADelegationCompletedEvent**: Emitido quando a delegação A2A é concluída. Contém o status de conclusão (`completed`, `input_required`, `failed`, etc.), resultado, mensagem de erro, ID do contexto e metadados do agent card. +- **A2AParallelDelegationStartedEvent**: Emitido quando a delegação paralela para múltiplos agentes A2A é iniciada. Contém a lista de endpoints e a descrição da tarefa. +- **A2AParallelDelegationCompletedEvent**: Emitido quando a delegação paralela para múltiplos agentes A2A é concluída. Contém a lista de endpoints, contagem de sucessos, contagem de falhas e resumo dos resultados. + +#### Eventos de Conversação + +- **A2AConversationStartedEvent**: Emitido uma vez no início de uma conversação multiturn A2A, antes da primeira troca de mensagens. Contém o ID do agente, endpoint, ID do contexto, metadados do agent card, versão do protocolo e informações do provedor. +- **A2AMessageSentEvent**: Emitido quando uma mensagem é enviada ao agente A2A. Contém o conteúdo da mensagem, número do turno, ID do contexto, ID da mensagem e se é multiturn. +- **A2AResponseReceivedEvent**: Emitido quando uma resposta é recebida do agente A2A. Contém o conteúdo da resposta, número do turno, ID do contexto, ID da mensagem, status e se é a resposta final. +- **A2AConversationCompletedEvent**: Emitido uma vez ao final de uma conversação multiturn A2A. Contém o status final (`completed` ou `failed`), resultado final, mensagem de erro, ID do contexto e número total de turnos. + +#### Eventos de Streaming + +- **A2AStreamingStartedEvent**: Emitido quando o modo streaming é iniciado para delegação A2A. Contém o ID da tarefa, ID do contexto, endpoint, número do turno e se é multiturn. +- **A2AStreamingChunkEvent**: Emitido quando um chunk de streaming é recebido. Contém o texto do chunk, índice do chunk, se é o chunk final, ID da tarefa, ID do contexto e número do turno. + +#### Eventos de Polling e Push Notification + +- **A2APollingStartedEvent**: Emitido quando o modo polling é iniciado para delegação A2A. Contém o ID da tarefa, ID do contexto, intervalo de polling em segundos e endpoint. +- **A2APollingStatusEvent**: Emitido em cada iteração de polling. Contém o ID da tarefa, ID do contexto, estado atual da tarefa, segundos decorridos e contagem de polls. +- **A2APushNotificationRegisteredEvent**: Emitido quando um callback de push notification é registrado. Contém o ID da tarefa, ID do contexto, URL do callback e endpoint. +- **A2APushNotificationReceivedEvent**: Emitido quando uma push notification é recebida do agente A2A remoto. Contém o ID da tarefa, ID do contexto e estado atual. +- **A2APushNotificationSentEvent**: Emitido quando uma push notification é enviada para uma URL de callback. Contém o ID da tarefa, ID do contexto, URL do callback, estado, se a entrega foi bem-sucedida e mensagem de erro opcional. +- **A2APushNotificationTimeoutEvent**: Emitido quando a espera por push notification expira. Contém o ID da tarefa, ID do contexto e duração do timeout em segundos. + +#### Eventos de Conexão e Autenticação + +- **A2AAgentCardFetchedEvent**: Emitido quando um agent card é obtido com sucesso. Contém o endpoint, nome do agente, metadados do agent card, versão do protocolo, informações do provedor, se foi do cache e tempo de busca em milissegundos. +- **A2AAuthenticationFailedEvent**: Emitido quando a autenticação com um agente A2A falha. Contém o endpoint, tipo de autenticação tentada (ex.: `bearer`, `oauth2`, `api_key`), mensagem de erro e código de status HTTP. +- **A2AConnectionErrorEvent**: Emitido quando ocorre um erro de conexão durante a comunicação A2A. Contém o endpoint, mensagem de erro, tipo de erro (ex.: `timeout`, `connection_refused`, `dns_error`), código de status HTTP e a operação sendo tentada. +- **A2ATransportNegotiatedEvent**: Emitido quando o protocolo de transporte é negociado com um agente A2A. Contém o transporte negociado, URL negociada, fonte de seleção (`client_preferred`, `server_preferred`, `fallback`) e transportes suportados pelo cliente/servidor. +- **A2AContentTypeNegotiatedEvent**: Emitido quando os tipos de conteúdo são negociados com um agente A2A. Contém os modos de entrada/saída do cliente/servidor, modos de entrada/saída negociados e se a negociação foi bem-sucedida. + +#### Eventos de Artefatos + +- **A2AArtifactReceivedEvent**: Emitido quando um artefato é recebido de um agente A2A remoto. Contém o ID da tarefa, ID do artefato, nome do artefato, descrição, tipo MIME, tamanho em bytes e se o conteúdo deve ser concatenado. + +#### Eventos de Tarefa do Servidor + +- **A2AServerTaskStartedEvent**: Emitido quando a execução de uma tarefa do servidor A2A é iniciada. Contém o ID da tarefa e ID do contexto. +- **A2AServerTaskCompletedEvent**: Emitido quando a execução de uma tarefa do servidor A2A é concluída. Contém o ID da tarefa, ID do contexto e resultado. +- **A2AServerTaskCanceledEvent**: Emitido quando a execução de uma tarefa do servidor A2A é cancelada. Contém o ID da tarefa e ID do contexto. +- **A2AServerTaskFailedEvent**: Emitido quando a execução de uma tarefa do servidor A2A falha. Contém o ID da tarefa, ID do contexto e mensagem de erro. + +#### Eventos de Ciclo de Vida do Contexto + +- **A2AContextCreatedEvent**: Emitido quando um contexto A2A é criado. Contextos agrupam tarefas relacionadas em uma conversação ou workflow. Contém o ID do contexto e timestamp de criação. +- **A2AContextExpiredEvent**: Emitido quando um contexto A2A expira devido ao TTL. Contém o ID do contexto, timestamp de criação, idade em segundos e contagem de tarefas. +- **A2AContextIdleEvent**: Emitido quando um contexto A2A fica inativo (sem atividade pelo threshold configurado). Contém o ID do contexto, tempo de inatividade em segundos e contagem de tarefas. +- **A2AContextCompletedEvent**: Emitido quando todas as tarefas em um contexto A2A são concluídas. Contém o ID do contexto, total de tarefas e duração em segundos. +- **A2AContextPrunedEvent**: Emitido quando um contexto A2A é podado (deletado). Contém o ID do contexto, contagem de tarefas e idade em segundos. + +## Estrutura dos Handlers de Evento + +Cada handler de evento recebe dois parâmetros: + +1. **source**: O objeto que emitiu o evento +2. **event**: A instância do evento, contendo dados específicos do evento + +A estrutura do objeto de evento depende do tipo do evento, mas todos herdam de `BaseEvent` e incluem: + +- **timestamp**: O horário em que o evento foi emitido +- **type**: Identificador do tipo do evento + +Campos adicionais variam pelo tipo de evento. Por exemplo, `CrewKickoffCompletedEvent` inclui os campos `crew_name` e `output`. + +## Uso Avançado: Handlers Escopados + +Para lidar temporariamente com eventos (útil para testes ou operações específicas), você pode usar o context manager `scoped_handlers`: + +```python +from crewai.events import crewai_event_bus, CrewKickoffStartedEvent + +with crewai_event_bus.scoped_handlers(): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def temp_handler(source, event): + print("Este handler só existe neste contexto") + + # Faça algo que emita eventos + +# Fora do contexto, o handler temporário é removido +``` + +## Casos de Uso + +Listeners de evento podem ser usados para várias finalidades: + +1. **Log e Monitoramento**: Monitore a execução do seu Crew e registre eventos importantes +2. **Analytics**: Colete dados sobre o desempenho e comportamento do seu Crew +3. **Depuração**: Configure listeners temporários para debugar problemas específicos +4. **Integração**: Conecte o CrewAI a sistemas externos como plataformas de monitoramento, bancos de dados ou serviços de notificação +5. **Comportamento Personalizado**: Dispare ações personalizadas com base em eventos específicos + +## Boas Práticas + +1. **Mantenha Handlers Leves**: Handlers de eventos devem ser leves e evitar operações bloqueantes +2. **Tratamento de Erros**: Implemente tratamento de erros adequado nos event handlers para evitar que exceções afetem a execução principal +3. **Limpeza**: Se seu listener alocar recursos, garanta o devido fechamento/liberação +4. **Escuta Seletiva**: Escute apenas eventos que realmente precisa tratar +5. **Testes**: Teste seus listeners de evento isoladamente para garantir que se comportam conforme esperado + +Aproveitando o sistema de eventos do CrewAI, é possível estender a funcionalidade e integrá-lo facilmente à sua infraestrutura existente. diff --git a/docs/v1.15.1/pt-BR/concepts/files.mdx b/docs/v1.15.1/pt-BR/concepts/files.mdx new file mode 100644 index 000000000..cc2f4f3ca --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/files.mdx @@ -0,0 +1,267 @@ +--- +title: Arquivos +description: Passe imagens, PDFs, áudio, vídeo e arquivos de texto para seus agentes para processamento multimodal. +icon: file-image +--- + +## Visão Geral + +O CrewAI suporta entradas de arquivos multimodais nativos, permitindo que você passe imagens, PDFs, áudio, vídeo e arquivos de texto diretamente para seus agentes. Os arquivos são formatados automaticamente para os requisitos da API de cada provedor LLM. + + +O suporte a arquivos requer o pacote opcional `crewai-files`. Instale com: + +```bash +uv add 'crewai[file-processing]' +``` + + + +A API de processamento de arquivos está atualmente em acesso antecipado. + + +## Tipos de Arquivo + +O CrewAI suporta cinco tipos de arquivo específicos mais uma classe genérica `File` que detecta automaticamente o tipo: + +| Tipo | Classe | Casos de Uso | +|:-----|:------|:----------| +| **Imagem** | `ImageFile` | Fotos, capturas de tela, diagramas, gráficos | +| **PDF** | `PDFFile` | Documentos, relatórios, artigos | +| **Áudio** | `AudioFile` | Gravações de voz, podcasts, reuniões | +| **Vídeo** | `VideoFile` | Gravações de tela, apresentações | +| **Texto** | `TextFile` | Arquivos de código, logs, arquivos de dados | +| **Genérico** | `File` | Detecta automaticamente o tipo do conteúdo | + +```python +from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile + +image = ImageFile(source="screenshot.png") +pdf = PDFFile(source="report.pdf") +audio = AudioFile(source="meeting.mp3") +video = VideoFile(source="demo.mp4") +text = TextFile(source="data.csv") + +file = File(source="document.pdf") +``` + +## Fontes de Arquivo + +O parâmetro `source` aceita múltiplos tipos de entrada e detecta automaticamente o handler apropriado: + +### De Caminho + +```python +from crewai_files import ImageFile + +image = ImageFile(source="./images/chart.png") +``` + +### De URL + +```python +from crewai_files import ImageFile + +image = ImageFile(source="https://example.com/image.png") +``` + +### De Bytes + +```python +from crewai_files import ImageFile, FileBytes + +image_bytes = download_image_from_api() +image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png")) +image = ImageFile(source=image_bytes) +``` + +## Usando Arquivos + +Arquivos podem ser passados em múltiplos níveis, com níveis mais específicos tendo precedência. + +### Com Crews + +Passe arquivos ao iniciar uma crew: + +```python +from crewai import Crew +from crewai_files import ImageFile + +crew = Crew(agents=[analyst], tasks=[analysis_task]) + +result = crew.kickoff( + inputs={"topic": "Q4 Sales"}, + input_files={ + "chart": ImageFile(source="sales_chart.png"), + "report": PDFFile(source="quarterly_report.pdf"), + } +) +``` + +### Com Tasks + +Anexe arquivos a tasks específicas: + +```python +from crewai import Task +from crewai_files import ImageFile + +task = Task( + description="Analise o gráfico de vendas e identifique tendências em {chart}", + expected_output="Um resumo das principais tendências", + input_files={ + "chart": ImageFile(source="sales_chart.png"), + } +) +``` + +### Com Flows + +Passe arquivos para flows, que automaticamente herdam para crews: + +```python +from crewai.flow.flow import Flow, start +from crewai_files import ImageFile + +class AnalysisFlow(Flow): + @start() + def analyze(self): + return self.analysis_crew.kickoff() + +flow = AnalysisFlow() +result = flow.kickoff( + input_files={"image": ImageFile(source="data.png")} +) +``` + +### Com Agentes Standalone + +Passe arquivos diretamente no kickoff do agente: + +```python +from crewai import Agent +from crewai_files import ImageFile + +agent = Agent( + role="Image Analyst", + goal="Analyze images", + backstory="Expert at visual analysis", + llm="gpt-4o", +) + +result = agent.kickoff( + messages="What's in this image?", + input_files={"photo": ImageFile(source="photo.jpg")}, +) +``` + +## Precedência de Arquivos + +Quando arquivos são passados em múltiplos níveis, níveis mais específicos sobrescrevem os mais amplos: + +``` +Flow input_files < Crew input_files < Task input_files +``` + +Por exemplo, se tanto Flow quanto Task definem um arquivo chamado `"chart"`, a versão da Task é usada. + +## Suporte por Provedor + +Diferentes provedores suportam diferentes tipos de arquivo. O CrewAI formata automaticamente os arquivos para a API de cada provedor. + +| Provedor | Imagem | PDF | Áudio | Vídeo | Texto | +|:---------|:-----:|:---:|:-----:|:-----:|:----:| +| **OpenAI** (API completions) | ✓ | | | | | +| **OpenAI** (API responses) | ✓ | ✓ | ✓ | | | +| **Anthropic** (claude-3.x) | ✓ | ✓ | | | | +| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ | +| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | | +| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | | + + +Os modelos Google Gemini suportam todos os tipos de arquivo incluindo vídeo (até 1 hora, 2GB). Use Gemini quando precisar processar conteúdo de vídeo. + + + +Se você passar um tipo de arquivo que o provedor não suporta (ex: vídeo para OpenAI), você receberá um `UnsupportedFileTypeError`. Escolha seu provedor baseado nos tipos de arquivo que você precisa processar. + + +## Como os Arquivos São Enviados + +O CrewAI escolhe automaticamente o método ideal para enviar arquivos para cada provedor: + +| Método | Descrição | Usado Quando | +|:-------|:------------|:----------| +| **Base64 Inline** | Arquivo embutido diretamente na requisição | Arquivos pequenos (< 5MB tipicamente) | +| **API de Upload de Arquivo** | Arquivo enviado separadamente, referenciado por ID | Arquivos grandes que excedem o limite | +| **Referência por URL** | URL direta passada para o modelo | Fonte do arquivo já é uma URL | + +### Métodos de Transmissão por Provedor + +| Provedor | Base64 Inline | API de Upload | Referências URL | +|:---------|:-------------:|:---------------:|:--------------:| +| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ | +| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ | +| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ | +| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) | +| **Azure OpenAI** | ✓ | | ✓ | + + +Você não precisa gerenciar isso. O CrewAI usa automaticamente o método mais eficiente baseado no tamanho do arquivo e nas capacidades do provedor. Provedores sem APIs de upload de arquivo usam base64 inline para todos os arquivos. + + +## Modos de Tratamento de Arquivo + +Controle como os arquivos são processados quando excedem os limites do provedor: + +```python +from crewai_files import ImageFile, PDFFile + +image = ImageFile(source="large.png", mode="strict") +image = ImageFile(source="large.png", mode="auto") +image = ImageFile(source="large.png", mode="warn") +pdf = PDFFile(source="large.pdf", mode="chunk") +``` + +## Restrições por Provedor + +Cada provedor tem limites específicos para tamanhos e dimensões de arquivo: + +### OpenAI +- **Imagens**: Máx 20 MB, até 10 imagens por requisição +- **PDFs**: Máx 32 MB, até 100 páginas +- **Áudio**: Máx 25 MB, até 25 minutos + +### Anthropic +- **Imagens**: Máx 5 MB, máx 8000x8000 pixels, até 100 imagens +- **PDFs**: Máx 32 MB, até 100 páginas + +### Google Gemini +- **Imagens**: Máx 100 MB +- **PDFs**: Máx 50 MB +- **Áudio**: Máx 100 MB, até 9,5 horas +- **Vídeo**: Máx 2 GB, até 1 hora + +### AWS Bedrock +- **Imagens**: Máx 4,5 MB, máx 8000x8000 pixels +- **PDFs**: Máx 3,75 MB, até 100 páginas + +## Referenciando Arquivos em Prompts + +Use o nome da chave do arquivo nas descrições das suas tasks para referenciar arquivos: + +```python +task = Task( + description=""" + Analise os materiais fornecidos: + 1. Revise o gráfico em {sales_chart} + 2. Faça referência cruzada com dados em {quarterly_report} + 3. Resuma as principais descobertas + """, + expected_output="Resumo da análise com insights principais", + input_files={ + "sales_chart": ImageFile(source="chart.png"), + "quarterly_report": PDFFile(source="report.pdf"), + } +) +``` diff --git a/docs/v1.15.1/pt-BR/concepts/flows.mdx b/docs/v1.15.1/pt-BR/concepts/flows.mdx new file mode 100644 index 000000000..8879edca8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/flows.mdx @@ -0,0 +1,1055 @@ +--- +title: Flows +description: Saiba como criar e gerenciar fluxos de trabalho de IA usando CrewAI Flows. +icon: arrow-progress +mode: "wide" +--- + +## 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 + +from crewai.flow.flow import Flow, listen, start +from dotenv import load_dotenv +from litellm import completion + +load_dotenv() + +class ExampleFlow(Flow): + model = "gpt-4o-mini" + + @start() + def generate_city(self): + print("Starting flow") + # Cada estado do flow recebe automaticamente um ID único + print(f"Flow State ID: {self.state['id']}") + + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": "Return the name of a random city in the world.", + }, + ], + ) + + random_city = response["choices"][0]["message"]["content"] + # Armazena a cidade no nosso estado + self.state["city"] = random_city + print(f"Random City: {random_city}") + + return random_city + + @listen(generate_city) + def generate_fun_fact(self, random_city): + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": f"Tell me a fun fact about {random_city}", + }, + ], + ) + + fun_fact = response["choices"][0]["message"]["content"] + # Armazena a curiosidade no nosso estado + self.state["fun_fact"] = fun_fact + return fun_fact + + + +flow = ExampleFlow() +flow.plot() +result = flow.kickoff() + +print(f"Generated fun fact: {result}") +``` + +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 + @listen("generate_city") + def generate_fun_fact(self, random_city): + # Implementação + ``` + +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 + @listen(generate_city) + def generate_fun_fact(self, random_city): + # Implementação + ``` + +### 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 +from crewai.flow.flow import Flow, listen, start + +class OutputExampleFlow(Flow): + @start() + def first_method(self): + return "Output from first_method" + + @listen(first_method) + def second_method(self, first_output): + return f"Second method received: {first_output}" + + +flow = OutputExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() + +print("---- Final Output ----") +print(final_output) +``` + +```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 +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class StateExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + self.state.message = "Hello from first_method" + self.state.counter += 1 + + @listen(first_method) + def second_method(self): + self.state.message += " - updated by second_method" + self.state.counter += 1 + return self.state.message + +flow = StateExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() +print(f"Final Output: {final_output}") +print("Final State:") +print(flow.state) +``` + +```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. + +## Métricas de Uso do Flow + +Após a execução de um Flow, você pode acessar a propriedade `usage_metrics` para visualizar o consumo agregado de tokens em **todas as chamadas de LLM** realizadas durante a execução — incluindo chamadas das Crews orquestradas pelo Flow, chamadas dentro de tools de Agents, e invocações diretas de `LLM.call(...)` feitas a partir de métodos do Flow. Esse é o equivalente, do lado do SDK, ao total exibido na interface do CrewAI Enterprise. + +```python Code +from crewai import LLM +from crewai.flow.flow import Flow, listen, start + +class UsageMetricsFlow(Flow): + @start() + def run_first_crew(self): + self.state.first_result = FirstCrew().crew().kickoff() + + @listen(run_first_crew) + def call_llm_directly(self): + # Chamada direta de LLM — também contabilizada por flow.usage_metrics + llm = LLM(model="openai/gpt-4o-mini") + self.state.summary = llm.call("Resuma os principais pontos.") + + @listen(call_llm_directly) + def run_second_crew(self): + self.state.second_result = SecondCrew().crew().kickoff() + +flow = UsageMetricsFlow() +flow.kickoff() + +print(flow.usage_metrics) +# UsageMetrics(total_tokens=8579, prompt_tokens=6210, completion_tokens=2369, +# cached_prompt_tokens=0, reasoning_tokens=0, +# cache_creation_tokens=0, successful_requests=5) +``` + + + `flow.usage_metrics` **não** é o mesmo que `flow.kickoff().token_usage`. Este + último retorna apenas o `CrewOutput.token_usage` do **último** método + `@listen` que retornou um `CrewOutput`, ou seja, reflete somente a Crew + final e ignora completamente as Crews anteriores e quaisquer chamadas + diretas de `LLM.call(...)`. Use `flow.usage_metrics` sempre que precisar do + rollup **completo** de tokens da execução do Flow. + + +Cada campo do [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado representa a soma de todas as chamadas de LLM feitas em uma única invocação de `flow.kickoff()`. Os contadores são resetados a cada novo `kickoff()` (e em cada iteração de `kickoff_for_each`), de modo que execuções sucessivas não duplicam o total. A propriedade é segura para ser lida em qualquer momento após o `kickoff()`; lê-la durante a execução retorna o total parcial acumulado até aquele instante. + +## 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 +from crewai.flow.flow import Flow, listen, start + +class UnstructuredExampleFlow(Flow): + + @start() + def first_method(self): + # O estado inclui automaticamente um campo 'id' + print(f"State ID: {self.state['id']}") + self.state['counter'] = 0 + self.state['message'] = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated" + + @listen(second_method) + def third_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = UnstructuredExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +![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 +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + + +class ExampleState(BaseModel): + # Nota: o campo 'id' é adicionado automaticamente a todos os estados + counter: int = 0 + message: str = "" + + +class StructuredExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + # Acesse o ID gerado automaticamente, se necessário + print(f"State ID: {self.state.id}") + self.state.message = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state.counter += 1 + self.state.message += " - updated" + + @listen(second_method) + def third_method(self): + self.state.counter += 1 + self.state.message += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = StructuredExampleFlow() +flow.kickoff() +``` + +![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 +@persist # Usa SQLiteFlowPersistence por padrão +class MyFlow(Flow[MyState]): + @start() + def initialize_flow(self): + # Este método terá seu estado persistido automaticamente + self.state.counter = 1 + print("Initialized flow. State ID:", self.state.id) + + @listen(initialize_flow) + def next_step(self): + # O estado (incluindo self.state.id) é recarregado automaticamente + self.state.counter += 1 + print("Flow state is persisted. Counter:", self.state.counter) +``` + +### Persistência no Nível de Método + +Para um controle mais granular, você pode aplicar @persist em métodos específicos: + +```python +class AnotherFlow(Flow[dict]): + @persist # Persiste apenas o estado deste método + @start() + def begin(self): + if "runs" not in self.state: + self.state["runs"] = 0 + self.state["runs"] += 1 + print("Method-level persisted runs:", self.state["runs"]) +``` + +### Forking de Estado Persistido + +`@persist` suporta dois modos distintos de hidratação em `kickoff` / `kickoff_async`: + +- `kickoff(inputs={"id": })` — **resume**: carrega o snapshot mais recente do UUID informado e continua escrevendo sob o mesmo `flow_uuid`. O histórico se estende. +- `kickoff(restore_from_state_id=)` — **fork**: carrega o snapshot mais recente do UUID informado, hidrata o estado da nova execução a partir dele, e atribui um novo `state.id` (auto-gerado, ou `inputs["id"]` se fixado). As escritas do `@persist` da nova execução vão para o novo `state.id`; o histórico do flow de origem é preservado. + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + print(f"[id={self.state.id}] counter={self.state.counter}") + +# Execução 1: estado novo, counter 0 -> 1, persistido sob flow_1.state.id +flow_1 = CounterFlow() +flow_1.kickoff() + +# Fork: hidrata do snapshot mais recente de flow_1, mas usa um state.id NOVO +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# flow_2.state.counter começa em 1 (hidratado), e step() incrementa para 2. +# flow_2.state.id != flow_1.state.id; o histórico de flow_1 não é alterado. +``` + +Se o `restore_from_state_id` informado não corresponder a nenhum estado persistido, o kickoff retorna silenciosamente ao comportamento padrão — o mesmo comportamento do `inputs["id"]` quando não encontrado. Combinar `restore_from_state_id` com `from_checkpoint` lança um `ValueError`; escolha uma única fonte de hidratação. Fixar `inputs["id"]` durante o fork compartilha uma chave de persistência com outro flow — geralmente você quer apenas `restore_from_state_id`. + +### 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 +from crewai.flow.flow import Flow, listen, or_, start + +class OrExampleFlow(Flow): + + @start() + def start_method(self): + return "Hello from the start method" + + @listen(start_method) + def second_method(self): + return "Hello from the second method" + + @listen(or_(start_method, second_method)) + def logger(self, result): + print(f"Logger: {result}") + + + +flow = OrExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```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 +from crewai.flow.flow import Flow, and_, listen, start + +class AndExampleFlow(Flow): + + @start() + def start_method(self): + self.state["greeting"] = "Hello from the start method" + + @listen(start_method) + def second_method(self): + self.state["joke"] = "What do computers eat? Microchips." + + @listen(and_(start_method, second_method)) + def logger(self): + print("---- Logger ----") + print(self.state) + +flow = AndExampleFlow() +flow.plot() +flow.kickoff() +``` + +```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 +import random +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + success_flag: bool = False + +class RouterFlow(Flow[ExampleState]): + + @start() + def start_method(self): + print("Starting the structured flow") + random_boolean = random.choice([True, False]) + self.state.success_flag = random_boolean + + @router(start_method) + def second_method(self): + if self.state.success_flag: + return "success" + else: + return "failed" + + @listen("success") + def third_method(self): + print("Third method running") + + @listen("failed") + def fourth_method(self): + print("Fourth method running") + + +flow = RouterFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```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`. + +### Human in the Loop (feedback humano) + + +O decorador `@human_feedback` requer **CrewAI versão 1.8.0 ou superior**. + + +O decorador `@human_feedback` permite fluxos de trabalho human-in-the-loop, pausando a execução do flow para coletar feedback de um humano. Isso é útil para portões de aprovação, revisão de qualidade e pontos de decisão que requerem julgamento humano. + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="Você aprova este conteúdo?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + def generate_content(self): + return "Conteúdo para revisão..." + + @listen("approved") + def on_approval(self, result: HumanFeedbackResult): + print(f"Aprovado! Feedback: {result.feedback}") + + @listen("rejected") + def on_rejection(self, result: HumanFeedbackResult): + print(f"Rejeitado. Motivo: {result.feedback}") +``` + +Quando `emit` é especificado, o feedback livre do humano é interpretado por um LLM e mapeado para um dos outcomes especificados, que então dispara o decorador `@listen` correspondente. + +Você também pode usar `@human_feedback` sem roteamento para simplesmente coletar feedback: + +```python Code +@start() +@human_feedback(message="Algum comentário sobre esta saída?") +def my_method(self): + return "Saída para revisão" + +@listen(my_method) +def next_step(self, result: HumanFeedbackResult): + # Acesse o feedback via result.feedback + # Acesse a saída original via result.output + pass +``` + +Acesse todo o feedback coletado durante um flow via `self.last_human_feedback` (mais recente) ou `self.human_feedback_history` (todo o feedback em uma lista). + +Para um guia completo sobre feedback humano em flows, incluindo feedback assíncrono/não-bloqueante com providers customizados (Slack, webhooks, etc.), veja [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows). + +## 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 +import asyncio +from typing import Any, Dict, List + +from crewai_tools import SerperDevTool +from pydantic import BaseModel, Field + +from crewai.agent import Agent +from crewai.flow.flow import Flow, listen, start + + +# Define um formato de saída estruturado +class MarketAnalysis(BaseModel): + key_trends: List[str] = Field(description="List of identified market trends") + market_size: str = Field(description="Estimated market size") + competitors: List[str] = Field(description="Major competitors in the space") + + +# Define o estado do flow +class MarketResearchState(BaseModel): + product: str = "" + analysis: MarketAnalysis | None = None + + +# Cria uma classe de flow +class MarketResearchFlow(Flow[MarketResearchState]): + @start() + def initialize_research(self) -> Dict[str, Any]: + print(f"Starting market research for {self.state.product}") + return {"product": self.state.product} + + @listen(initialize_research) + async def analyze_market(self) -> Dict[str, Any]: + # Cria um agente para pesquisa de mercado + analyst = Agent( + role="Market Research Analyst", + goal=f"Analyze the market for {self.state.product}", + backstory="You are an experienced market analyst with expertise in " + "identifying market trends and opportunities.", + tools=[SerperDevTool()], + verbose=True, + ) + + # Define a consulta de pesquisa + query = f""" + Research the market for {self.state.product}. Include: + 1. Key market trends + 2. Market size + 3. Major competitors + + Format your response according to the specified structure. + """ + + # Executa a análise com formato de saída estruturado + result = await analyst.kickoff_async(query, response_format=MarketAnalysis) + if result.pydantic: + print("result", result.pydantic) + else: + print("result", result) + + # Retorna a análise para atualizar o estado + return {"analysis": result.pydantic} + + @listen(analyze_market) + def present_results(self, analysis) -> None: + print("\nMarket Analysis Results") + print("=====================") + + if isinstance(analysis, dict): + # Se recebemos um dict com a chave 'analysis', extrai o objeto de análise real + market_analysis = analysis.get("analysis") + else: + market_analysis = analysis + + if market_analysis and isinstance(market_analysis, MarketAnalysis): + print("\nKey Market Trends:") + for trend in market_analysis.key_trends: + print(f"- {trend}") + + print(f"\nMarket Size: {market_analysis.market_size}") + + print("\nMajor Competitors:") + for competitor in market_analysis.competitors: + print(f"- {competitor}") + else: + print("No structured analysis data available.") + print("Raw analysis:", analysis) + + +# Exemplo de uso +async def run_flow(): + flow = MarketResearchFlow() + flow.plot("MarketResearchFlowPlot") + result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"}) + return result + + +# Executa o flow +if __name__ == "__main__": + asyncio.run(run_flow()) +``` + +![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. A crew embutida inicial usa a estrutura clássica Python/YAML; novas crews independentes criadas com `crewai create crew` usam a estrutura JSON-first. + +### 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 clássicas embutidas. + +Para crews embutidas JSON-first, use uma pasta com `crew.jsonc` e `agents/*.jsonc`: + +```text +crews/ +└── research_crew/ + ├── agents/ + │ └── researcher.jsonc + └── crew.jsonc +``` + +Depois carregue a crew em uma etapa do Flow: + +```python +from pathlib import Path +from crewai.project import load_crew + +crew, default_inputs = load_crew( + Path(__file__).parent / "crews" / "research_crew" / "crew.jsonc" +) +result = crew.kickoff(inputs={**default_inputs, "topic": "AI Agents"}) +``` + +### 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 +#!/usr/bin/env python +from random import randint + +from pydantic import BaseModel +from crewai.flow.flow import Flow, listen, start +from .crews.poem_crew.poem_crew import PoemCrew + +class PoemState(BaseModel): + sentence_count: int = 1 + poem: str = "" + +class PoemFlow(Flow[PoemState]): + + @start() + def generate_sentence_count(self): + print("Generating sentence count") + self.state.sentence_count = randint(1, 5) + + @listen(generate_sentence_count) + def generate_poem(self): + print("Generating poem") + result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count}) + + print("Poem generated", result.raw) + self.state.poem = result.raw + + @listen(generate_poem) + def save_poem(self): + print("Saving poem") + with open("poem.txt", "w") as f: + f.write(self.state.poem) + +def kickoff(): + poem_flow = PoemFlow() + poem_flow.kickoff() + + +def plot(): + poem_flow = PoemFlow() + poem_flow.plot("PoemFlowPlot") + +if __name__ == "__main__": + kickoff() + plot() +``` + +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 run +``` + +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 +# Considerando que você já tem uma instância do flow +flow.plot("my_flow_plot") +``` + +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 +# Exemplo de execução de flow em português +flow = ExemploFlow() +resultado = 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. + +O comando legado `crewai flow kickoff` está deprecated. Use `crewai run` para crews e flows. diff --git a/docs/v1.15.1/pt-BR/concepts/knowledge.mdx b/docs/v1.15.1/pt-BR/concepts/knowledge.mdx new file mode 100644 index 000000000..eabe22fab --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/knowledge.mdx @@ -0,0 +1,1060 @@ +--- +title: Knowledge +description: O que é knowledge em CrewAI e como usá-lo. +icon: book +mode: "wide" +--- + +## 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="Sobre o Usuário", + goal="Você sabe tudo sobre o usuário.", + backstory="Você é mestre em entender pessoas e suas preferências.", + verbose=True, + allow_delegation=False, + llm=llm, +) + +task = Task( + description="Responda às seguintes perguntas sobre o usuário: {question}", + expected_output="Uma resposta para a pergunta.", + 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="Sobre artigos", + goal="Você sabe tudo sobre os artigos.", + backstory="Você é mestre em entender artigos e seus conteúdos.", + verbose=True, + allow_delegation=False, + llm=llm, +) + +task = Task( + description="Responda às seguintes perguntas sobre os artigos: {question}", + expected_output="Uma resposta para a pergunta.", + 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="Especialista Técnico", + goal="Fornecer expertise técnica", + backstory="Especialista em domínios técnicos especializados", + knowledge_sources=[specialist_knowledge] # Conhecimento específico do agente +) + +task = Task( + description="Responda perguntas técnicas", + agent=specialist_agent, + expected_output="Resposta técnica" +) + +# 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., "Especialista Técnico" + +# 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 +# ├── Especialista Técnico/ # 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="Especialista", + 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="Especialista Técnico", + goal="Fornecer expertise técnica", + backstory="Especialista em domínios técnicos especializados", + knowledge_sources=[specialist_knowledge] # Conhecimento específico do agente +) + +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.events import ( + KnowledgeRetrievalStartedEvent, + KnowledgeRetrievalCompletedEvent, + 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](/pt-BR/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/v1.15.1/pt-BR/concepts/llms.mdx b/docs/v1.15.1/pt-BR/concepts/llms.mdx new file mode 100644 index 000000000..b7299050f --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/llms.mdx @@ -0,0 +1,1086 @@ +--- +title: 'LLMs' +description: 'Um guia abrangente para configurar e usar Modelos de Linguagem de Grande Escala (LLMs) em seus projetos CrewAI' +icon: 'microchip-ai' +mode: "wide" +--- + +## 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="openai/gpt-4", + temperature=0.8, + max_tokens=150, + top_p=0.9, + frequency_penalty=0.1, + presence_penalty=0.1, + response_format={"type":"json"}, + stop=["FIM"], + seed=42 + ) + ``` + + + 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 + + + + + + O CrewAI oferece integrações nativas via SDK para OpenAI, Anthropic, Google (Gemini API), Azure, AWS Bedrock e Snowflake Cortex — sem necessidade de instalação extra além dos extras específicos do provedor (ex.: `uv add "crewai[openai]"`). + + Todos os outros provedores são alimentados pelo **LiteLLM**. Se você planeja usar algum deles, adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + +## 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", + temperature=0.8, + max_tokens=150, + top_p=0.9, + frequency_penalty=0.1, + presence_penalty=0.1, + stop=["FIM"], + 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 | + + **Responses API:** + + A OpenAI oferece duas APIs: Chat Completions (padrão) e a nova Responses API. A Responses API foi projetada desde o início com suporte multimodal nativo—texto, imagens, áudio e chamadas de função são todos cidadãos de primeira classe. Ela oferece melhor performance com modelos de raciocínio e suporta recursos adicionais como auto-encadeamento e ferramentas integradas. + + ```python Code + from crewai import LLM + + # Usar Responses API em vez de Chat Completions + llm = LLM( + model="openai/gpt-4o", + api="responses", # Habilitar Responses API + store=True, # Armazenar respostas para multi-turno (opcional) + auto_chain=True, # Auto-encadeamento para modelos de raciocínio (opcional) + ) + ``` + + **Parâmetros da Responses API:** + - `api`: Defina como `"responses"` para usar a Responses API (padrão: `"completions"`) + - `instructions`: Instruções de nível de sistema (apenas Responses API) + - `store`: Se deve armazenar respostas para conversas multi-turno + - `previous_response_id`: ID da resposta anterior para multi-turno + - `include`: Dados adicionais para incluir na resposta (ex: `["reasoning.encrypted_content"]`) + - `builtin_tools`: Lista de ferramentas integradas da OpenAI: `"web_search"`, `"file_search"`, `"code_interpreter"`, `"computer_use"` + - `parse_tool_outputs`: Retornar `ResponsesAPIResult` estruturado com saídas de ferramentas integradas parseadas + - `auto_chain`: Rastrear e usar automaticamente IDs de resposta para conversas multi-turno + - `auto_chain_reasoning`: Rastrear itens de raciocínio criptografados para conformidade ZDR (Zero Data Retention) + + + Use a Responses API para novos projetos, especialmente ao trabalhar com modelos de raciocínio (o1, o3, o4) ou quando precisar de suporte multimodal nativo para [arquivos](/pt-BR/concepts/files). + + + + + 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=["FIM"], + 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 | + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + O CrewAI oferece integração nativa com a API REST do Snowflake Cortex pelo endpoint Chat Completions compatível com OpenAI. Isso evita fallback para LiteLLM em modelos `snowflake/...`. Atualmente, o Snowflake Cortex no CrewAI oferece suporte apenas a Chat Completions, então use o modo `api` padrão e não defina `api="responses"`. + + ```toml Code + # Obrigatório + SNOWFLAKE_PAT= + SNOWFLAKE_ACCOUNT_URL=https://.snowflakecomputing.com + + # Configuração alternativa da conta + SNOWFLAKE_ACCOUNT= + ``` + + **Uso básico:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/openai-gpt-4.1", + temperature=0.7, + max_completion_tokens=1024, + ) + ``` + + **Modelos Claude no Cortex:** + ```python Code + from crewai import LLM + + llm = LLM( + model="snowflake/claude-sonnet-4-5", + max_completion_tokens=1024, + stream=True, + ) + ``` + + **Variáveis de ambiente suportadas:** + - `SNOWFLAKE_PAT`, `SNOWFLAKE_TOKEN` ou `SNOWFLAKE_JWT`: token usado como credencial Bearer + - `SNOWFLAKE_ACCOUNT_URL`: URL completa da conta Snowflake + - `SNOWFLAKE_ACCOUNT`, `SNOWFLAKE_ACCOUNT_ID` ou `SNOWFLAKE_ACCOUNT_IDENTIFIER`: identificador da conta usado para montar a URL + + As requisições REST do Snowflake usam a role padrão do usuário. Garanta que essa role tenha `SNOWFLAKE.CORTEX_USER` ou `SNOWFLAKE.CORTEX_REST_API_USER`. Parâmetros de banco de dados, schema, warehouse e role explícita não são exigidos pelo endpoint Cortex REST Chat Completions. + + **Recursos:** + - Seleção nativa com `model="snowflake/"` + - Chat Completions com e sem streaming apenas; `api="responses"` não é compatível + - Rastreamento de uso de tokens + - Chamadas de função para modelos OpenAI e Claude hospedados no Snowflake + - Remoção automática de prefill final de assistant inválido para modelos Claude no Snowflake + + + + ```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 + # Para API Gemini (uma das seguintes) + GOOGLE_API_KEY= + GEMINI_API_KEY= + + # Para Vertex AI Express mode (autenticação por chave de API) + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + + # Para Vertex AI com conta de serviço + GOOGLE_CLOUD_PROJECT= + GOOGLE_CLOUD_LOCATION= # Padrão: us-central1 + ``` + + **Uso Básico:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7, + ) + ``` + + **Vertex AI Express Mode (Autenticação por Chave de API):** + + O Vertex AI Express mode permite usar o Vertex AI com autenticação simples por chave de API, em vez de credenciais de conta de serviço. Esta é a maneira mais rápida de começar com o Vertex AI. + + Para habilitar o Express mode, defina ambas as variáveis de ambiente no seu arquivo `.env`: + ```toml .env + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + ``` + + Em seguida, use o LLM normalmente: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7 + ) + ``` + + + Para obter uma chave de API do Express mode: + - Novos usuários do Google Cloud: Obtenha uma [chave de API do Express mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey) + - Usuários existentes do Google Cloud: Obtenha uma [chave de API do Google Cloud vinculada a uma conta de serviço](https://cloud.google.com/docs/authentication/api-keys) + + Para mais detalhes, consulte a [documentação do Vertex AI Express mode](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey). + + + ### 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-1.5-pro-latest", # or vertex_ai/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 | + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + ```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/" + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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 + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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.| + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + + 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 + ) + + # ... + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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 | + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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" + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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" + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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 + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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/" + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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" + ) + ``` + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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 | + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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 + + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 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 + + + **Nota:** Este provedor usa o LiteLLM. Adicione-o como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + + + +## 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.events import ( + LLMStreamChunkEvent + ) + from crewai.events 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](/pt-BR/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 + ``` + + diff --git a/docs/v1.15.1/pt-BR/concepts/memory.mdx b/docs/v1.15.1/pt-BR/concepts/memory.mdx new file mode 100644 index 000000000..3931ed6ab --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/memory.mdx @@ -0,0 +1,878 @@ +--- +title: Memória +description: Aproveitando o sistema de memória unificado no CrewAI para aprimorar as capacidades dos agentes. +icon: database +mode: "wide" +--- + +## Visão Geral + +O CrewAI oferece um **sistema de memória unificado** -- uma única classe `Memory` que substitui memórias de curto prazo, longo prazo, entidades e externa por uma API inteligente. A memória usa um LLM para analisar o conteúdo ao salvar (inferindo escopo, categorias e importância) e suporta recall com profundidade adaptativa e pontuação composta que combina similaridade semântica, recência e importância. + +Você pode usar a memória de quatro formas: **standalone** (scripts, notebooks), **com Crews**, **com Agentes** ou **dentro de Flows**. + +## Início Rápido + +```python +from crewai import Memory + +memory = Memory() + +# Armazenar -- o LLM infere escopo, categorias e importância +memory.remember("Decidimos usar PostgreSQL para o banco de dados de usuários.") + +# Recuperar -- resultados ranqueados por pontuação composta (semântica + recência + importância) +matches = memory.recall("Qual banco de dados escolhemos?") +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Ajustar pontuação para um projeto dinâmico +memory = Memory(recency_weight=0.5, recency_half_life_days=7) + +# Esquecer +memory.forget(scope="/project/old") + +# Explorar a árvore de escopos auto-organizada +print(memory.tree()) +print(memory.info("/")) +``` + +## Quatro Formas de Usar Memória + +### Standalone + +Use memória em scripts, notebooks, ferramentas CLI ou como base de conhecimento independente -- sem agentes ou crews necessários. + +```python +from crewai import Memory + +memory = Memory() + +# Construir conhecimento +memory.remember("O limite da API é 1000 requisições por minuto.") +memory.remember("Nosso ambiente de staging usa a porta 8080.") +memory.remember("A equipe concordou em usar feature flags para todos os novos lançamentos.") + +# Depois, recupere o que precisar +matches = memory.recall("Quais são nossos limites de API?", limit=5) +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Extrair fatos atômicos de um texto mais longo +raw = """Notas da reunião: Decidimos migrar do MySQL para PostgreSQL +no próximo trimestre. O orçamento é de $50k. Sarah liderará a migração.""" + +facts = memory.extract_memories(raw) +# ["Migração de MySQL para PostgreSQL planejada para o próximo trimestre", +# "Orçamento da migração de banco de dados é $50k", +# "Sarah liderará a migração do banco de dados"] + +for fact in facts: + memory.remember(fact) +``` + +### Com Crews + +Passe `memory=True` para configurações padrão, ou passe uma instância `Memory` configurada para comportamento customizado. + +```python +from crewai import Crew, Agent, Task, Process, Memory + +# Opção 1: Memória padrão +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + memory=True, + verbose=True, +) + +# Opção 2: Memória customizada com pontuação ajustada +memory = Memory( + recency_weight=0.4, + semantic_weight=0.4, + importance_weight=0.2, + recency_half_life_days=14, +) +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + memory=memory, +) +``` + +Quando `memory=True`, a crew cria um `Memory()` padrão e repassa a configuração de `embedder` da crew automaticamente. Todos os agentes compartilham a memória da crew, a menos que um agente tenha sua própria. + +Após cada tarefa, a crew extrai automaticamente fatos discretos da saída da tarefa e os armazena. Antes de cada tarefa, o agente recupera contexto relevante da memória e o injeta no prompt da tarefa. + +### Com Agentes + +Agentes podem usar a memória compartilhada da crew (padrão) ou receber uma visão com escopo para contexto privado. + +```python +from crewai import Agent, Memory + +memory = Memory() + +# Pesquisador recebe um escopo privado -- só vê /agent/researcher +researcher = Agent( + role="Researcher", + goal="Encontrar e analisar informações", + backstory="Pesquisador experiente com atenção aos detalhes", + memory=memory.scope("/agent/researcher"), +) + +# Escritor usa memória compartilhada da crew (sem memória própria) +writer = Agent( + role="Writer", + goal="Produzir conteúdo claro e bem estruturado", + backstory="Escritor técnico experiente", + # memory não definido -- usa crew._memory quando a crew tem memória habilitada +) +``` + +Esse padrão dá ao pesquisador descobertas privadas enquanto o escritor lê da memória compartilhada da crew. + +### Com Flows + +Todo Flow possui memória integrada. Use `self.remember()`, `self.recall()` e `self.extract_memories()` dentro de qualquer método do flow. + +```python +from crewai.flow.flow import Flow, listen, start + +class ResearchFlow(Flow): + @start() + def gather_data(self): + findings = "PostgreSQL suporta 10k conexões simultâneas. MySQL limita a 5k." + self.remember(findings, scope="/research/databases") + return findings + + @listen(gather_data) + def write_report(self, findings): + # Recuperar pesquisas anteriores para fornecer contexto + past = self.recall("benchmarks de performance de banco de dados") + context = "\n".join(f"- {m.record.content}" for m in past) + return f"Relatório:\nNovas descobertas: {findings}\nContexto anterior:\n{context}" +``` + +Veja a [documentação de Flows](/concepts/flows) para mais informações sobre memória em Flows. + + +## Escopos Hierárquicos + +### O Que São Escopos + +As memórias são organizadas em uma árvore hierárquica de escopos, similar a um sistema de arquivos. Cada escopo é um caminho como `/`, `/project/alpha` ou `/agent/researcher/findings`. + +``` +/ + /company + /company/engineering + /company/product + /project + /project/alpha + /project/beta + /agent + /agent/researcher + /agent/writer +``` + +Escopos fornecem **memória dependente de contexto** -- quando você faz recall dentro de um escopo, busca apenas naquela ramificação da árvore, melhorando tanto a precisão quanto o desempenho. + +### Como a Inferência de Escopo Funciona + +Quando você chama `remember()` sem especificar um escopo, o LLM analisa o conteúdo e a árvore de escopos existente, e sugere o melhor posicionamento. Se nenhum escopo existente é adequado, ele cria um novo. Com o tempo, a árvore de escopos cresce organicamente a partir do conteúdo -- você não precisa projetar um esquema antecipadamente. + +```python +memory = Memory() + +# LLM infere escopo a partir do conteúdo +memory.remember("Escolhemos PostgreSQL para o banco de dados de usuários.") +# -> pode ser colocado em /project/decisions ou /engineering/database + +# Você também pode especificar o escopo explicitamente +memory.remember("Velocidade do sprint é 42 pontos", scope="/team/metrics") +``` + +### Visualizando a Árvore de Escopos + +```python +print(memory.tree()) +# / (15 records) +# /project (8 records) +# /project/alpha (5 records) +# /project/beta (3 records) +# /agent (7 records) +# /agent/researcher (4 records) +# /agent/writer (3 records) + +print(memory.info("/project/alpha")) +# ScopeInfo(path='/project/alpha', record_count=5, +# categories=['architecture', 'database'], +# oldest_record=datetime(...), newest_record=datetime(...), +# child_scopes=[]) +``` + +### MemoryScope: Visões de Subárvore + +Um `MemoryScope` restringe todas as operações a uma ramificação da árvore. O agente ou código que o utiliza só pode ver e escrever dentro daquela subárvore. + +```python +memory = Memory() + +# Criar um escopo para um agente específico +agent_memory = memory.scope("/agent/researcher") + +# Tudo é relativo a /agent/researcher +agent_memory.remember("Encontrados três papers relevantes sobre memória de LLM.") +# -> armazenado em /agent/researcher + +agent_memory.recall("papers relevantes") +# -> busca apenas em /agent/researcher + +# Restringir ainda mais com subscope +project_memory = agent_memory.subscope("project-alpha") +# -> /agent/researcher/project-alpha +``` + +### Boas Práticas para Design de Escopos + +- **Comece plano, deixe o LLM organizar.** Não projete demais sua hierarquia de escopos antecipadamente. Comece com `memory.remember(content)` e deixe a inferência de escopo do LLM criar estrutura conforme o conteúdo se acumula. + +- **Use padrões `/{tipo_entidade}/{identificador}`.** Hierarquias naturais emergem de padrões como `/project/alpha`, `/agent/researcher`, `/company/engineering`, `/customer/acme-corp`. + +- **Escopo por preocupação, não por tipo de dado.** Use `/project/alpha/decisions` em vez de `/decisions/project/alpha`. Isso mantém conteúdo relacionado junto. + +- **Mantenha profundidade rasa (2-3 níveis).** Escopos profundamente aninhados ficam muito esparsos. `/project/alpha/architecture` é bom; `/project/alpha/architecture/decisions/databases/postgresql` é demais. + +- **Use escopos explícitos quando souber, deixe o LLM inferir quando não souber.** Se está armazenando uma decisão de projeto conhecida, passe `scope="/project/alpha/decisions"`. Se está armazenando saída livre de um agente, omita o escopo e deixe o LLM decidir. + +### Exemplos de Casos de Uso + +**Equipe multi-projeto:** +```python +memory = Memory() +# Cada projeto recebe sua própria ramificação +memory.remember("Usando arquitetura de microsserviços", scope="/project/alpha/architecture") +memory.remember("API GraphQL para apps cliente", scope="/project/beta/api") + +# Recall em todos os projetos +memory.recall("decisões de design de API") + +# Ou dentro de um projeto específico +memory.recall("design de API", scope="/project/beta") +``` + +**Contexto privado por agente com conhecimento compartilhado:** +```python +memory = Memory() + +# Pesquisador tem descobertas privadas +researcher_memory = memory.scope("/agent/researcher") + +# Escritor pode ler de seu próprio escopo e do conhecimento compartilhado da empresa +writer_view = memory.slice( + scopes=["/agent/writer", "/company/knowledge"], + read_only=True, +) +``` + +**Suporte ao cliente (contexto por cliente):** +```python +memory = Memory() + +# Cada cliente recebe contexto isolado +memory.remember("Prefere comunicação por email", scope="/customer/acme-corp") +memory.remember("Plano enterprise, 50 licenças", scope="/customer/acme-corp") + +# Docs de produto compartilhados são acessíveis a todos os agentes +memory.remember("Limite de taxa é 1000 req/min no plano enterprise", scope="/product/docs") +``` + + +## Fatias de Memória (Memory Slices) + +### O Que São Fatias + +Um `MemorySlice` é uma visão sobre múltiplos escopos, possivelmente disjuntos. Diferente de um escopo (que restringe a uma subárvore), uma fatia permite recall de várias ramificações simultaneamente. + +### Quando Usar Fatias vs Escopos + +- **Escopo**: Use quando um agente ou bloco de código deve ser restrito a uma única subárvore. Exemplo: um agente que só vê `/agent/researcher`. +- **Fatia**: Use quando precisar combinar contexto de múltiplas ramificações. Exemplo: um agente que lê de seu próprio escopo mais conhecimento compartilhado da empresa. + +### Fatias Somente Leitura + +O padrão mais comum: dar a um agente acesso de leitura a múltiplas ramificações sem permitir que ele escreva em áreas compartilhadas. + +```python +memory = Memory() + +# Agente pode fazer recall de seu próprio escopo E do conhecimento da empresa, +# mas não pode escrever no conhecimento da empresa +agent_view = memory.slice( + scopes=["/agent/researcher", "/company/knowledge"], + read_only=True, +) + +matches = agent_view.recall("políticas de segurança da empresa", limit=5) +# Busca em /agent/researcher e /company/knowledge, mescla e ranqueia resultados + +agent_view.remember("nova descoberta") # Levanta PermissionError (somente leitura) +``` + +### Fatias de Leitura e Escrita + +Quando somente leitura está desabilitado, você pode escrever em qualquer um dos escopos incluídos, mas deve especificar qual escopo explicitamente. + +```python +view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False) + +# Deve especificar escopo ao escrever +view.remember("Decisão entre equipes", scope="/team/alpha", categories=["decisions"]) +``` + + +## Pontuação Composta + +Os resultados do recall são ranqueados por uma combinação ponderada de três sinais: + +``` +composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance +``` + +Onde: +- **similarity** = `1 / (1 + distance)` do índice vetorial (0 a 1) +- **decay** = `0.5^(age_days / half_life_days)` -- decaimento exponencial (1.0 para hoje, 0.5 na meia-vida) +- **importance** = pontuação de importância do registro (0 a 1), definida no momento da codificação + +Configure diretamente no construtor do `Memory`: + +```python +# Retrospectiva de sprint: favorecer memórias recentes, meia-vida curta +memory = Memory( + recency_weight=0.5, + semantic_weight=0.3, + importance_weight=0.2, + recency_half_life_days=7, +) + +# Base de conhecimento de arquitetura: favorecer memórias importantes, meia-vida longa +memory = Memory( + recency_weight=0.1, + semantic_weight=0.5, + importance_weight=0.4, + recency_half_life_days=180, +) +``` + +Cada `MemoryMatch` inclui uma lista `match_reasons` para que você possa ver por que um resultado ficou na posição que ficou (ex.: `["semantic", "recency", "importance"]`). + + +## Camada de Análise LLM + +A memória usa o LLM de três formas: + +1. **Ao salvar** -- Quando você omite escopo, categorias ou importância, o LLM analisa o conteúdo e sugere escopo, categorias, importância e metadados (entidades, datas, tópicos). +2. **Ao fazer recall** -- Para recall profundo/automático, o LLM analisa a consulta (palavras-chave, dicas temporais, escopos sugeridos, complexidade) para guiar a recuperação. +3. **Extrair memórias** -- `extract_memories(content)` quebra texto bruto (ex.: saída de tarefa) em afirmações de memória discretas. Os agentes usam isso antes de chamar `remember()` em cada afirmação para que fatos atômicos sejam armazenados em vez de um bloco grande. + +Toda análise degrada graciosamente em caso de falha do LLM -- veja [Comportamento em Caso de Falha](#comportamento-em-caso-de-falha). + + +## Consolidação de Memória + +Ao salvar novo conteúdo, o pipeline de codificação verifica automaticamente registros similares existentes no armazenamento. Se a similaridade estiver acima de `consolidation_threshold` (padrão 0.85), o LLM decide o que fazer: + +- **keep** -- O registro existente ainda é preciso e não é redundante. +- **update** -- O registro existente deve ser atualizado com novas informações (o LLM fornece o conteúdo mesclado). +- **delete** -- O registro existente está desatualizado, substituído ou contradito. +- **insert_new** -- Se o novo conteúdo também deve ser inserido como um registro separado. + +Isso evita o acúmulo de duplicatas. Por exemplo, se você salvar "CrewAI garante operação confiável" três vezes, a consolidação reconhece as duplicatas e mantém apenas um registro. + +### Dedup Intra-batch + +Ao usar `remember_many()`, os itens dentro do mesmo batch são comparados entre si antes de atingir o armazenamento. Se dois itens tiverem similaridade de cosseno >= `batch_dedup_threshold` (padrão 0.98), o posterior é silenciosamente descartado. Isso captura duplicatas exatas ou quase exatas dentro de um único batch sem chamadas ao LLM (pura matemática vetorial). + +```python +# Apenas 2 registros são armazenados (o terceiro é quase duplicata do primeiro) +memory.remember_many([ + "CrewAI supports complex workflows.", + "Python is a great language.", + "CrewAI supports complex workflows.", # descartado pelo dedup intra-batch +]) +``` + + +## Saves Não-Bloqueantes + +`remember_many()` é **não-bloqueante** -- ele envia o pipeline de codificação para uma thread em background e retorna imediatamente. Isso significa que o agente pode continuar para a próxima tarefa enquanto as memórias estão sendo salvas. + +```python +# Retorna imediatamente -- save acontece em background +memory.remember_many(["Fato A.", "Fato B.", "Fato C."]) + +# recall() espera automaticamente saves pendentes antes de buscar +matches = memory.recall("fatos") # vê todos os 3 registros +``` + +### Barreira de Leitura + +Cada chamada `recall()` executa automaticamente `drain_writes()` antes de buscar, garantindo que a consulta sempre veja os registros mais recentes persistidos. Isso é transparente -- você nunca precisa pensar nisso. + +### Encerramento da Crew + +Quando uma crew termina, `kickoff()` drena todos os saves de memória pendentes em seu bloco `finally`, então nenhum save é perdido mesmo que a crew complete enquanto saves em background estão em andamento. + +### Uso Standalone + +Para scripts ou notebooks onde não há ciclo de vida de crew, chame `drain_writes()` ou `close()` explicitamente: + +```python +memory = Memory() +memory.remember_many(["Fato A.", "Fato B."]) + +# Opção 1: Esperar saves pendentes +memory.drain_writes() + +# Opção 2: Drenar e encerrar o pool de background +memory.close() +``` + + +## Origem e Privacidade + +Cada registro de memória pode carregar uma tag `source` para rastreamento de procedência e uma flag `private` para controle de acesso. + +### Rastreamento de Origem + +O parâmetro `source` identifica de onde uma memória veio: + +```python +# Marcar memórias com sua origem +memory.remember("Usuário prefere modo escuro", source="user:alice") +memory.remember("Configuração do sistema atualizada", source="admin") +memory.remember("Agente encontrou um bug", source="agent:debugger") + +# Recuperar apenas memórias de uma origem específica +matches = memory.recall("preferências do usuário", source="user:alice") +``` + +### Memórias Privadas + +Memórias privadas só são visíveis no recall quando o `source` corresponde: + +```python +# Armazenar uma memória privada +memory.remember("A chave de API da Alice é sk-...", source="user:alice", private=True) + +# Este recall vê a memória privada (source corresponde) +matches = memory.recall("chave de API", source="user:alice") + +# Este recall NÃO a vê (source diferente) +matches = memory.recall("chave de API", source="user:bob") + +# Acesso admin: ver todos os registros privados independente do source +matches = memory.recall("chave de API", include_private=True) +``` + +Isso é particularmente útil em implantações multi-usuário ou corporativas onde memórias de diferentes usuários devem ser isoladas. + + +## RecallFlow (Recall Profundo) + +`recall()` suporta duas profundidades: + +- **`depth="shallow"`** -- Busca vetorial direta com pontuação composta. Rápido (~200ms), sem chamadas ao LLM. +- **`depth="deep"` (padrão)** -- Executa um RecallFlow em múltiplas etapas: análise da consulta, seleção de escopo, busca vetorial paralela, roteamento baseado em confiança e exploração recursiva opcional quando a confiança é baixa. + +**Pulo inteligente do LLM**: Consultas com menos de `query_analysis_threshold` (padrão 200 caracteres) pulam a análise de consulta do LLM inteiramente, mesmo no modo deep. Consultas curtas como "Qual banco de dados usamos?" já são boas frases de busca -- a análise do LLM agrega pouco valor. Isso economiza ~1-3s por recall para consultas curtas típicas. Apenas consultas mais longas (ex.: descrições completas de tarefas) passam pela destilação do LLM em sub-consultas direcionadas. + +```python +# Shallow: busca vetorial pura, sem LLM +matches = memory.recall("O que decidimos?", limit=10, depth="shallow") + +# Deep (padrão): recuperação inteligente com análise LLM para consultas longas +matches = memory.recall( + "Resuma todas as decisões de arquitetura deste trimestre", + limit=10, + depth="deep", +) +``` + +Os limiares de confiança que controlam o roteador do RecallFlow são configuráveis: + +```python +memory = Memory( + confidence_threshold_high=0.9, # Só sintetizar quando muito confiante + confidence_threshold_low=0.4, # Explorar mais profundamente de forma mais agressiva + exploration_budget=2, # Permitir até 2 rodadas de exploração + query_analysis_threshold=200, # Pular LLM para consultas menores que isso +) +``` + + +## Configuração de Embedder + +A memória precisa de um modelo de embedding para converter texto em vetores para busca semântica. Você pode configurar de três formas. + +### Passando Diretamente para o Memory + +```python +from crewai import Memory + +# Como um dict de configuração +memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}) + +# Como um callable pré-construído +from crewai.rag.embeddings.factory import build_embedder +embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}) +memory = Memory(embedder=embedder) +``` + +### Via Configuração de Embedder da Crew + +Quando usar `memory=True`, a configuração de `embedder` da crew é repassada: + +```python +from crewai import Crew + +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}, +) +``` + +### Exemplos por Provedor + + + +```python +memory = Memory(embedder={ + "provider": "openai", + "config": { + "model_name": "text-embedding-3-small", + # "api_key": "sk-...", # ou defina OPENAI_API_KEY + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "ollama", + "config": { + "model_name": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "azure", + "config": { + "deployment_id": "your-embedding-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com", + "api_version": "2024-02-01", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-generativeai", + "config": { + "model_name": "gemini-embedding-001", + # "api_key": "...", # ou defina GOOGLE_API_KEY + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-vertex", + "config": { + "model_name": "gemini-embedding-001", + "project_id": "your-gcp-project-id", + "location": "us-central1", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "cohere", + "config": { + "model_name": "embed-english-v3.0", + # "api_key": "...", # ou defina COHERE_API_KEY + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "voyageai", + "config": { + "model": "voyage-3", + # "api_key": "...", # ou defina VOYAGE_API_KEY + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "amazon-bedrock", + "config": { + "model_name": "amazon.titan-embed-text-v1", + # Usa credenciais AWS padrão (sessão boto3) + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "huggingface", + "config": { + "model_name": "sentence-transformers/all-MiniLM-L6-v2", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "jina", + "config": { + "model_name": "jina-embeddings-v2-base-en", + # "api_key": "...", # ou defina JINA_API_KEY + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "watsonx", + "config": { + "model_id": "ibm/slate-30m-english-rtrvr", + "api_key": "your-watsonx-api-key", + "project_id": "your-project-id", + "url": "https://us-south.ml.cloud.ibm.com", + }, +}) +``` + + + +```python +# Passe qualquer callable que receba uma lista de strings e retorne uma lista de vetores +def my_embedder(texts: list[str]) -> list[list[float]]: + # Sua lógica de embedding aqui + return [[0.1, 0.2, ...] for _ in texts] + +memory = Memory(embedder=my_embedder) +``` + + + +### Referência de Provedores + +| Provedor | Chave | Modelo Típico | Notas | +| :--- | :--- | :--- | :--- | +| OpenAI | `openai` | `text-embedding-3-small` | Padrão. Defina `OPENAI_API_KEY`. | +| Ollama | `ollama` | `mxbai-embed-large` | Local, sem API key. | +| Azure OpenAI | `azure` | `text-embedding-ada-002` | Requer `deployment_id`. | +| Google AI | `google-generativeai` | `gemini-embedding-001` | Defina `GOOGLE_API_KEY`. | +| Google Vertex | `google-vertex` | `gemini-embedding-001` | Requer `project_id`. | +| Cohere | `cohere` | `embed-english-v3.0` | Forte suporte multilíngue. | +| VoyageAI | `voyageai` | `voyage-3` | Otimizado para retrieval. | +| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | Usa credenciais boto3. | +| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | Sentence-transformers local. | +| Jina | `jina` | `jina-embeddings-v2-base-en` | Defina `JINA_API_KEY`. | +| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | Requer `project_id`. | +| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | Local, sem API key. | +| Custom | `custom` | -- | Requer `embedding_callable`. | + + +## Configuração de LLM + +A memória usa um LLM para análise de save (inferência de escopo, categorias e importância), decisões de consolidação e análise de consulta no recall profundo. Você pode configurar qual modelo usar. + +```python +from crewai import Memory, LLM + +# Padrão: gpt-4o-mini +memory = Memory() + +# Usar um modelo OpenAI diferente +memory = Memory(llm="gpt-4o") + +# Usar Anthropic +memory = Memory(llm="anthropic/claude-3-haiku-20240307") + +# Usar Ollama para análise totalmente local/privada +memory = Memory(llm="ollama/llama3.2") + +# Usar Google Gemini +memory = Memory(llm="gemini/gemini-2.0-flash") + +# Passar uma instância LLM pré-configurada com configurações customizadas +llm = LLM(model="gpt-4o", temperature=0) +memory = Memory(llm=llm) +``` + +O LLM é inicializado **lazily** -- ele só é criado quando necessário pela primeira vez. Isso significa que `Memory()` nunca falha no momento da construção, mesmo que chaves de API não estejam definidas. Erros só aparecem quando o LLM é realmente chamado (ex.: ao salvar sem escopo/categorias explícitos, ou durante recall profundo). + +Para operação totalmente offline/privada, use um modelo local tanto para o LLM quanto para o embedder: + +```python +memory = Memory( + llm="ollama/llama3.2", + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) +``` + + +## Backend de Armazenamento + +- **Padrão**: LanceDB, armazenado em `./.crewai/memory` (ou `$CREWAI_STORAGE_DIR/memory` se a variável de ambiente estiver definida, ou o caminho que você passar como `storage="path/to/dir"`). +- **Backend customizado**: Implemente o protocolo `StorageBackend` (veja `crewai.memory.storage.backend`) e passe uma instância para `Memory(storage=your_backend)`. + + +## Descoberta + +Inspecione a hierarquia de escopos, categorias e registros: + +```python +memory.tree() # Árvore formatada de escopos e contagem de registros +memory.tree("/project", max_depth=2) # Visão de subárvore +memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest +memory.list_scopes("/") # Escopos filhos imediatos +memory.list_categories() # Nomes e contagens de categorias +memory.list_records(scope="/project/alpha", limit=20) # Registros em um escopo, mais recentes primeiro +``` + + +## Comportamento em Caso de Falha + +Se o LLM falhar durante a análise (erro de rede, limite de taxa, resposta inválida), a memória degrada graciosamente: + +- **Análise de save** -- Um aviso é registrado e a memória ainda é armazenada com escopo padrão `/`, categorias vazias e importância `0.5`. +- **Extrair memórias** -- O conteúdo completo é armazenado como uma única memória para que nada seja descartado. +- **Análise de consulta** -- O recall usa fallback para seleção simples de escopo e busca vetorial, então você ainda obtém resultados. + +Nenhuma exceção é levantada para essas falhas de análise; apenas falhas de armazenamento ou do embedder irão levantar. + + +## Nota sobre Privacidade + +O conteúdo da memória é enviado ao LLM configurado para análise (escopo/categorias/importância no save, análise de consulta e recall profundo opcional). Para dados sensíveis, use um LLM local (ex.: Ollama) ou garanta que seu provedor atenda aos requisitos de conformidade. + + +## Eventos de Memória + +Todas as operações de memória emitem eventos com `source_type="unified_memory"`. Você pode escutar para timing, erros e conteúdo. + +| Evento | Descrição | Propriedades Principais | +| :---- | :---------- | :------------- | +| **MemoryQueryStartedEvent** | Consulta inicia | `query`, `limit` | +| **MemoryQueryCompletedEvent** | Consulta bem-sucedida | `query`, `results`, `query_time_ms` | +| **MemoryQueryFailedEvent** | Consulta falha | `query`, `error` | +| **MemorySaveStartedEvent** | Save inicia | `value`, `metadata` | +| **MemorySaveCompletedEvent** | Save bem-sucedido | `value`, `save_time_ms` | +| **MemorySaveFailedEvent** | Save falha | `value`, `error` | +| **MemoryRetrievalStartedEvent** | Retrieval do agente inicia | `task_id` | +| **MemoryRetrievalCompletedEvent** | Retrieval do agente completo | `task_id`, `memory_content`, `retrieval_time_ms` | + +Exemplo: monitorar tempo de consulta: + +```python +from crewai.events import BaseEventListener, MemoryQueryCompletedEvent + +class MemoryMonitor(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(MemoryQueryCompletedEvent) + def on_done(source, event): + if getattr(event, "source_type", None) == "unified_memory": + print(f"Query '{event.query}' completou em {event.query_time_ms:.0f}ms") +``` + + +## Solução de Problemas + +**Memória não persiste?** +- Garanta que o caminho de armazenamento seja gravável (padrão `./.crewai/memory`). Passe `storage="./your_path"` para usar outro diretório, ou defina a variável de ambiente `CREWAI_STORAGE_DIR`. +- Ao usar uma crew, confirme que `memory=True` ou `memory=Memory(...)` está definido. + +**Recall lento?** +- Use `depth="shallow"` para contexto rotineiro do agente. Reserve `depth="deep"` para consultas complexas. +- Aumente `query_analysis_threshold` para pular a análise do LLM em mais consultas. + +**Erros de análise LLM nos logs?** +- A memória ainda salva/recupera com padrões seguros. Verifique chaves de API, limites de taxa e disponibilidade do modelo se quiser análise LLM completa. + +**Erros de save em background nos logs?** +- Os saves de memória rodam em uma thread em background. Erros são emitidos como `MemorySaveFailedEvent` mas não derrubam o agente. Verifique os logs para a causa raiz (geralmente problemas de conexão com LLM ou embedder). + +**Conflitos de escrita concorrente?** +- As operações do LanceDB são serializadas com um lock compartilhado e reexecutadas automaticamente em caso de conflito. Isso lida com múltiplas instâncias `Memory` apontando para o mesmo banco de dados (ex.: memória do agente + memória da crew). Nenhuma ação necessária. + +**Navegar na memória pelo terminal:** +```bash +crewai memory # Abre o navegador TUI +crewai memory --storage-path ./my_memory # Apontar para um diretório específico +``` + +**Resetar memória (ex.: para testes):** +```python +crew.reset_memories(command_type="memory") # Reseta memória unificada +# Ou em uma instância Memory: +memory.reset() # Todos os escopos +memory.reset(scope="/project/old") # Apenas essa subárvore +``` + + +## Referência de Configuração + +Toda a configuração é passada como argumentos nomeados para `Memory(...)`. Cada parâmetro tem um padrão sensato. + +| Parâmetro | Padrão | Descrição | +| :--- | :--- | :--- | +| `llm` | `"gpt-4o-mini"` | LLM para análise (nome do modelo ou instância `BaseLLM`). | +| `storage` | `"lancedb"` | Backend de armazenamento (`"lancedb"`, string de caminho ou instância `StorageBackend`). | +| `embedder` | `None` (OpenAI padrão) | Embedder (dict de config, callable ou `None` para OpenAI padrão). | +| `recency_weight` | `0.3` | Peso da recência na pontuação composta. | +| `semantic_weight` | `0.5` | Peso da similaridade semântica na pontuação composta. | +| `importance_weight` | `0.2` | Peso da importância na pontuação composta. | +| `recency_half_life_days` | `30` | Dias para a pontuação de recência cair pela metade (decaimento exponencial). | +| `consolidation_threshold` | `0.85` | Similaridade acima da qual a consolidação é ativada no save. Defina `1.0` para desativar. | +| `consolidation_limit` | `5` | Máx. de registros existentes para comparar durante consolidação. | +| `default_importance` | `0.5` | Importância atribuída quando não fornecida e a análise LLM é pulada. | +| `batch_dedup_threshold` | `0.98` | Similaridade de cosseno para descartar quase-duplicatas dentro de um batch `remember_many()`. | +| `confidence_threshold_high` | `0.8` | Confiança de recall acima da qual resultados são retornados diretamente. | +| `confidence_threshold_low` | `0.5` | Confiança de recall abaixo da qual exploração mais profunda é ativada. | +| `complex_query_threshold` | `0.7` | Para consultas complexas, explorar mais profundamente abaixo desta confiança. | +| `exploration_budget` | `1` | Número de rodadas de exploração por LLM durante recall profundo. | +| `query_analysis_threshold` | `200` | Consultas menores que isso (em caracteres) pulam análise LLM durante recall profundo. | diff --git a/docs/v1.15.1/pt-BR/concepts/planning.mdx b/docs/v1.15.1/pt-BR/concepts/planning.mdx new file mode 100644 index 000000000..c4e511da7 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/planning.mdx @@ -0,0 +1,153 @@ +--- +title: Planejamento +description: Aprenda como adicionar planejamento à sua CrewAI Crew e melhorar sua performance. +icon: ruler-combined +mode: "wide" +--- + +## Visão geral + +O recurso de planejamento no CrewAI permite que você adicione capacidade de planejamento à sua crew. Quando ativado, antes de cada iteração da Crew, todas as informações da Crew são enviadas para um AgentPlanner que irá planejar as tarefas passo a passo, e este plano será adicionado à descrição de cada tarefa. + +### Usando o recurso de Planejamento + +Começar a usar o recurso de planejamento é muito simples, o único passo necessário é adicionar `planning=True` à sua Crew: + + +```python Code +from crewai import Crew, Agent, Task, Process + +# Monte sua crew com capacidades de planejamento +minha_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, +) +``` + + +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/v1.15.1/pt-BR/concepts/processes.mdx b/docs/v1.15.1/pt-BR/concepts/processes.mdx new file mode 100644 index 000000000..c92f34c8f --- /dev/null +++ b/docs/v1.15.1/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 +mode: "wide" +--- + +## 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. + +## O Papel dos Processos no Trabalho em Equipe +Os processos permitem que agentes individuais atuem como uma unidade coesa, otimizando seus esforços para atingir objetivos comuns com eficiência e coerência. + +## Atribuindo Processos a uma Crew +Para atribuir um processo a uma crew, especifique o tipo de processo ao criar a crew para definir a estratégia de execução. Para um processo hierárquico, garanta a definição de `manager_llm` ou `manager_agent` para o agente gerente. + +```python +from crewai import Crew, Process + +# Exemplo: Criando uma crew com processo sequencial +crew = Crew( + agents=meus_agentes, + tasks=minhas_tarefas, + process=Process.sequential +) + +# Exemplo: Criando uma crew com processo hierárquico +# Certifique-se de fornecer um manager_llm ou manager_agent +crew = Crew( + agents=meus_agentes, + tasks=minhas_tarefas, + process=Process.hierarchical, + manager_llm="gpt-4o" + # ou + # manager_agent=meu_agente_gerente +) +``` +**Nota:** Certifique-se de que `meus_agentes` e `minhas_tarefas` estejam definidos antes de criar o objeto `Crew`, e para o processo hierárquico, é necessário também fornecer o `manager_llm` ou `manager_agent`. + +## Processo Sequencial + +Este método reflete fluxos de trabalho dinâmicos de equipes, progredindo nas tarefas de maneira cuidadosa e sistemática. A execução das tarefas segue a ordem preestabelecida na lista de tarefas, com a saída de uma tarefa servindo de contexto para a próxima. + +Para personalizar o contexto das tarefas, utilize o parâmetro `context` na classe `Task` para especificar as saídas que devem ser usadas como contexto para as tarefas subsequentes. + +## Processo Hierárquico + +Emulando uma hierarquia corporativa, o CrewAI permite especificar um agente gerente personalizado ou criar um automaticamente, exigindo a especificação de um modelo de linguagem de gerente (`manager_llm`). Esse agente supervisiona a execução das tarefas, incluindo planejamento, delegação e validação. As tarefas não são pré-atribuídas; o gerente aloca tarefas aos agentes com base em suas capacidades, revisa as saídas e avalia a conclusão das tarefas. + +## Classe Process: Visão Detalhada + +A classe `Process` é implementada como uma enumeração (`Enum`), garantindo segurança de tipo e restringindo os valores de processos aos tipos definidos (`sequential`, `hierarchical`). + +## Conclusão + +A colaboração estruturada possibilitada pelos processos dentro do CrewAI é fundamental para permitir o trabalho em equipe sistemático entre agentes. +Esta documentação foi atualizada para refletir os mais recentes recursos e melhorias, garantindo que os usuários tenham acesso às informações mais atuais e abrangentes. \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/concepts/production-architecture.mdx b/docs/v1.15.1/pt-BR/concepts/production-architecture.mdx new file mode 100644 index 000000000..87b001e97 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/production-architecture.mdx @@ -0,0 +1,162 @@ +--- +title: Arquitetura de Produção +description: Melhores práticas para construir aplicações de IA prontas para produção com CrewAI +icon: server +mode: "wide" +--- + +# A Mentalidade Flow-First + +Ao construir aplicações de IA de produção com CrewAI, **recomendamos começar com um Flow**. + +Embora seja possível executar Crews ou Agentes individuais, envolvê-los em um Flow fornece a estrutura necessária para uma aplicação robusta e escalável. + +## Por que Flows? + +1. **Gerenciamento de Estado**: Flows fornecem uma maneira integrada de gerenciar o estado em diferentes etapas da sua aplicação. Isso é crucial para passar dados entre Crews, manter o contexto e lidar com entradas do usuário. +2. **Controle**: Flows permitem definir caminhos de execução precisos, incluindo loops, condicionais e lógica de ramificação. Isso é essencial para lidar com casos extremos e garantir que sua aplicação se comporte de maneira previsível. +3. **Observabilidade**: Flows fornecem uma estrutura clara que facilita o rastreamento da execução, a depuração de problemas e o monitoramento do desempenho. Recomendamos o uso do [CrewAI Tracing](/pt-BR/observability/tracing) para insights detalhados. Basta executar `crewai login` para habilitar recursos de observabilidade gratuitos. + +## A Arquitetura + +Uma aplicação CrewAI de produção típica se parece com isso: + +```mermaid +graph TD + Start((Início)) --> Flow[Orquestrador de Flow] + Flow --> State{Gerenciamento de Estado} + State --> Step1[Etapa 1: Coleta de Dados] + Step1 --> Crew1[Crew de Pesquisa] + Crew1 --> State + State --> Step2{Verificação de Condição} + Step2 -- "Válido" --> Step3[Etapa 3: Execução] + Step3 --> Crew2[Crew de Ação] + Step2 -- "Inválido" --> End((Fim)) + Crew2 --> End +``` + +### 1. A Classe Flow +Sua classe `Flow` é o ponto de entrada. Ela define o esquema de estado e os métodos que executam sua lógica. + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class AppState(BaseModel): + user_input: str = "" + research_results: str = "" + final_report: str = "" + +class ProductionFlow(Flow[AppState]): + @start() + def gather_input(self): + # ... lógica para obter entrada ... + pass + + @listen(gather_input) + def run_research_crew(self): + # ... acionar um Crew ... + pass +``` + +### 2. Gerenciamento de Estado +Use modelos Pydantic para definir seu estado. Isso garante a segurança de tipos e deixa claro quais dados estão disponíveis em cada etapa. + +- **Mantenha o mínimo**: Armazene apenas o que você precisa persistir entre as etapas. +- **Use dados estruturados**: Evite dicionários não estruturados quando possível. + +### 3. Crews como Unidades de Trabalho +Delegue tarefas complexas para Crews. Um Crew deve ser focado em um objetivo específico (por exemplo, "Pesquisar um tópico", "Escrever uma postagem no blog"). + +- **Não superengendre Crews**: Mantenha-os focados. +- **Passe o estado explicitamente**: Passe os dados necessários do estado do Flow para as entradas do Crew. + +```python + @listen(gather_input) + def run_research_crew(self): + crew = ResearchCrew() + result = crew.kickoff(inputs={"topic": self.state.user_input}) + self.state.research_results = result.raw +``` + +## Primitivas de Controle + +Aproveite as primitivas de controle do CrewAI para adicionar robustez e controle aos seus Crews. + +### 1. Task Guardrails +Use [Task Guardrails](/pt-BR/concepts/tasks#task-guardrails) para validar as saídas das tarefas antes que sejam aceitas. Isso garante que seus agentes produzam resultados de alta qualidade. + +```python +def validate_content(result: TaskOutput) -> Tuple[bool, Any]: + if len(result.raw) < 100: + return (False, "Content is too short. Please expand.") + return (True, result.raw) + +task = Task( + ..., + guardrail=validate_content +) +``` + +### 2. Saídas Estruturadas +Sempre use saídas estruturadas (`output_pydantic` ou `output_json`) ao passar dados entre tarefas ou para sua aplicação. Isso evita erros de análise e garante a segurança de tipos. + +```python +class ResearchResult(BaseModel): + summary: str + sources: List[str] + +task = Task( + ..., + output_pydantic=ResearchResult +) +``` + +### 3. LLM Hooks +Use [LLM Hooks](/pt-BR/learn/llm-hooks) para inspecionar ou modificar mensagens antes que elas sejam enviadas para o LLM, ou para higienizar respostas. + +```python +@before_llm_call +def log_request(context): + print(f"Agent {context.agent.role} is calling the LLM...") +``` + +## Padrões de Implantação + +Ao implantar seu Flow, considere o seguinte: + +### CrewAI Enterprise +A maneira mais fácil de implantar seu Flow é usando o CrewAI Enterprise. Ele lida com a infraestrutura, autenticação e monitoramento para você. + +Confira o [Guia de Implantação](/pt-BR/enterprise/guides/deploy-to-amp) para começar. + +```bash +crewai deploy create +``` + +### Execução Assíncrona +Para tarefas de longa duração, use `kickoff_async` para evitar bloquear sua API. + +### Persistência +Use o decorador `@persist` para salvar o estado do seu Flow em um banco de dados. Isso permite retomar a execução se o processo falhar ou se você precisar esperar pela entrada humana. + +```python +@persist +class ProductionFlow(Flow[AppState]): + # ... +``` + +Por padrão, `@persist` retoma um flow quando `kickoff(inputs={"id": })` é informado, estendendo o mesmo histórico do `flow_uuid`. Para **forkar** um flow persistido em uma nova linhagem — hidratar o estado a partir de uma execução anterior mas escrever sob um novo `state.id` — passe `restore_from_state_id`: + +```python +flow.kickoff(restore_from_state_id="") +``` + +A nova execução recebe um novo `state.id` (auto-gerado, ou `inputs["id"]` se fixado), então suas escritas do `@persist` não estendem o histórico da origem. Combinar com `from_checkpoint` lança um `ValueError`; escolha uma única fonte de hidratação. + +## Resumo + +- **Comece com um Flow.** +- **Defina um Estado claro.** +- **Use Crews para tarefas complexas.** +- **Implante com uma API e persistência.** diff --git a/docs/v1.15.1/pt-BR/concepts/reasoning.mdx b/docs/v1.15.1/pt-BR/concepts/reasoning.mdx new file mode 100644 index 000000000..e9e2d0f88 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/reasoning.mdx @@ -0,0 +1,148 @@ +--- +title: Reasoning +description: "Aprenda como habilitar e usar o reasoning do agente para aprimorar a execução de tarefas." +icon: brain +mode: "wide" +--- + +## Visão Geral + +O reasoning do agente é um recurso que permite que agentes reflitam sobre uma tarefa e criem um plano antes da execução. Isso ajuda os agentes a abordarem tarefas de forma mais metódica e garante que estejam preparados para realizar o trabalho atribuído. + +## Uso + +Para habilitar o reasoning para um agente, basta definir `reasoning=True` ao criar o agente: + +```python +from crewai import Agent + +analista = Agent( + role="Analista de Dados", + goal="Analisar dados e fornecer insights", + backstory="Você é um analista de dados especialista.", + reasoning=True, + max_reasoning_attempts=3 # Opcional: Defina um limite de tentativas de reasoning +) +``` + +## Como Funciona + +Quando o reasoning está habilitado, antes de executar uma tarefa, o agente irá: + +1. Refletir sobre a tarefa e criar um plano detalhado +2. Avaliar se está pronto para executar a tarefa +3. Refinar o plano conforme necessário até estar pronto ou até o limite de max_reasoning_attempts ser atingido +4. Inserir o plano de reasoning na descrição da tarefa antes da execução + +Esse processo ajuda o agente a dividir tarefas complexas em etapas gerenciáveis e identificar potenciais desafios antes de começar. + +## Opções de Configuração + + + 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 +analista = Agent( + role="Analista de Dados", + goal="Analisar dados e fornecer insights", + backstory="Você é um analista de dados especialista.", + reasoning=True, + max_reasoning_attempts=3 # Opcional: Defina um limite de tentativas de reasoning +) + +# Create a task +analysis_task = Task( + description="Analise os dados de vendas fornecidos e identifique as principais tendências.", + expected_output="Um relatório destacando as 3 principais tendências de vendas.", + agent=analista +) + +# Create a crew and run the task +crew = Crew(agents=[analista], tasks=[analysis_task]) +result = crew.kickoff() + +print(result) +``` + +## Tratamento de Erros + +O processo de reasoning foi projetado para ser robusto, com tratamento de erros integrado. Se ocorrer um erro durante o reasoning, o agente prosseguirá com a execução da tarefa sem o plano de reasoning. Isso garante que as tarefas ainda possam ser executadas mesmo que o processo de reasoning falhe. + +Veja como lidar com possíveis erros no seu código: + +```python +from crewai import Agent, Task +import logging + +# Set up logging to capture any reasoning errors +logging.basicConfig(level=logging.INFO) + +# Create an agent with reasoning enabled +agent = Agent( + role="Analista de Dados", + goal="Analisar dados e fornecer insights", + reasoning=True, + max_reasoning_attempts=3 +) + +# Create a task +task = Task( + description="Analise os dados de vendas fornecidos e identifique as principais tendências.", + expected_output="Um relatório destacando as 3 principais tendências de vendas.", + agent=agent +) + +# Execute the task +# If an error occurs during reasoning, it will be logged and execution will continue +result = agent.execute_task(task) +``` + +## Exemplo de Saída de reasoning + +Veja um exemplo de como pode ser um plano de reasoning para uma tarefa de análise de dados: + +``` +Task: Analise os dados de vendas fornecidos e identifique as principais tendências. + +Reasoning Plan: +I'll analyze the sales data to identify the top 3 trends. + +1. Understanding of the task: + I need to analyze sales data to identify key trends that would be valuable for business decision-making. + +2. Key steps I'll take: + - First, I'll examine the data structure to understand what fields are available + - Then I'll perform exploratory data analysis to identify patterns + - Next, I'll analyze sales by time periods to identify temporal trends + - I'll also analyze sales by product categories and customer segments + - Finally, I'll identify the top 3 most significant trends + +3. Approach to challenges: + - If the data has missing values, I'll decide whether to fill or filter them + - If the data has outliers, I'll investigate whether they're valid data points or errors + - If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns + +4. Use of available tools: + - I'll use data analysis tools to explore and visualize the data + - I'll use statistical tools to identify significant patterns + - I'll use knowledge retrieval to access relevant information about sales analysis + +5. Expected outcome: + A concise report highlighting the top 3 sales trends with supporting evidence from the data. + +READY: I am ready to execute the task. +``` + +Esse plano de reasoning ajuda o agente a organizar sua abordagem para a tarefa, considerar possíveis desafios e garantir que entregará o resultado esperado. diff --git a/docs/v1.15.1/pt-BR/concepts/skills.mdx b/docs/v1.15.1/pt-BR/concepts/skills.mdx new file mode 100644 index 000000000..0f530390f --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/skills.mdx @@ -0,0 +1,306 @@ +--- +title: Skills +description: Pacotes de skills baseados em sistema de arquivos que injetam expertise de domínio e instruções nos prompts dos agentes. +icon: bolt +mode: "wide" +--- + +## Visão Geral + +Skills são diretórios autocontidos que fornecem aos agentes **instruções, diretrizes e material de referência específicos de domínio**. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown. + +Quando ativada, as instruções de uma skill são injetadas diretamente no prompt da tarefa do agente — dando ao agente expertise sem exigir alterações de código. + + +**Skills NÃO são ferramentas.** Este é o ponto de confusão mais comum. + +- **Skills** injetam *instruções e contexto* no prompt do agente. Elas dizem ao agente *como pensar* sobre um problema. +- **Ferramentas** dão ao agente *funções chamáveis* para tomar ações (buscar, ler arquivos, chamar APIs). + +Frequentemente você precisa de **ambos**: skills para expertise, ferramentas para ação. Eles são configurados independentemente e se complementam. + + +--- + +## Início Rápido + +### 1. Crie um Diretório de Skill + +``` +skills/ +└── code-review/ + ├── SKILL.md # Obrigatório — instruções + ├── references/ # Opcional — documentos de referência + │ └── style-guide.md + └── scripts/ # Opcional — scripts executáveis +``` + +### 2. Escreva seu SKILL.md + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## Diretrizes de Code Review + +Ao revisar código, siga esta checklist: + +1. **Segurança**: Verifique vulnerabilidades de injeção, bypasses de autenticação e exposição de dados +2. **Performance**: Procure por queries N+1, alocações desnecessárias e chamadas bloqueantes +3. **Legibilidade**: Garanta nomenclatura clara, comentários apropriados e estilo consistente +4. **Testes**: Verifique cobertura adequada de testes para novas funcionalidades + +### Níveis de Severidade +- **Crítico**: Vulnerabilidades de segurança, riscos de perda de dados → bloquear merge +- **Major**: Problemas de performance, erros de lógica → solicitar alterações +- **Minor**: Questões de estilo, sugestões de nomenclatura → aprovar com comentários +``` + +### 3. Anexe a um Agente + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # Injeta diretrizes de revisão + tools=[GithubSearchTool(), FileReadTool()], # Permite ao agente ler código +) +``` + +O agente agora tem tanto **expertise** (da skill) quanto **capacidades** (das ferramentas). + +--- + +## Skills + Ferramentas: Trabalhando Juntos + +Aqui estão padrões comuns mostrando como skills e ferramentas se complementam: + +### Padrão 1: Apenas Skills (Expertise de Domínio, Sem Ações Necessárias) + +Use quando o agente precisa de instruções específicas mas não precisa chamar serviços externos: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # Diretrizes e templates de escrita + # Sem ferramentas necessárias — agente escreve baseado no contexto fornecido +) +``` + +### Padrão 2: Apenas Ferramentas (Ações, Sem Expertise Especial) + +Use quando o agente precisa tomar ações mas não precisa de instruções específicas de domínio: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # Pode buscar e extrair dados + # Sem skills necessárias — pesquisa geral não precisa de diretrizes especiais +) +``` + +### Padrão 3: Skills + Ferramentas (Expertise E Ações) + +O padrão mais comum no mundo real. A skill fornece *como* abordar o trabalho; ferramentas fornecem *o que* o agente pode fazer: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # Metodologia e checklists de auditoria + tools=[ + SerperDevTool(), # Pesquisar vulnerabilidades conhecidas + FileReadTool(), # Ler arquivos de configuração + CodeInterpreterTool(), # Executar scripts de análise + ], +) +``` + +### Padrão 4: Skills + MCPs + +Skills funcionam junto com servidores MCP da mesma forma que com ferramentas: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # Metodologia de análise + mcps=["https://data-warehouse.example.com/sse"], # Acesso remoto a dados +) +``` + +### Padrão 5: Skills + Apps + +Skills podem guiar como um agente usa integrações de plataforma: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # Templates de resposta e regras de escalação + apps=["gmail", "zendesk"], # Pode enviar emails e atualizar tickets +) +``` + +--- + +## Skills no Nível do Crew + +Skills podem ser definidas no crew para aplicar a **todos os agentes**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # Todos os agentes recebem essas skills +) +``` + +Skills no nível do agente têm prioridade — se a mesma skill é descoberta em ambos os níveis, a versão do agente é usada. + +--- + +## Formato do SKILL.md + +```markdown +--- +name: my-skill +description: Descrição curta do que esta skill faz e quando usá-la. +license: Apache-2.0 # opcional +compatibility: crewai>=0.1.0 # opcional +metadata: # opcional + author: your-name + version: "1.0" +allowed-tools: web-search file-read # opcional, experimental +--- + +Instruções para o agente vão aqui. Este corpo em markdown é injetado +no prompt do agente quando a skill é ativada. +``` + +### Campos do Frontmatter + +| Campo | Obrigatório | Descrição | +| :-------------- | :---------- | :----------------------------------------------------------------------- | +| `name` | Sim | 1–64 chars. Alfanumérico minúsculo e hifens. Deve corresponder ao nome do diretório. | +| `description` | Sim | 1–1024 chars. Descreve o que a skill faz e quando usá-la. | +| `license` | Não | Nome da licença ou referência a um arquivo de licença incluído. | +| `compatibility` | Não | Máx 500 chars. Requisitos de ambiente (produtos, pacotes, rede). | +| `metadata` | Não | Mapeamento arbitrário de chave-valor string. | +| `allowed-tools` | Não | Lista de ferramentas pré-aprovadas delimitada por espaços. Experimental. | + +--- + +## Estrutura de Diretório + +``` +my-skill/ +├── SKILL.md # Obrigatório — frontmatter + instruções +├── scripts/ # Opcional — scripts executáveis +├── references/ # Opcional — documentos de referência +└── assets/ # Opcional — arquivos estáticos (configs, dados) +``` + +O nome do diretório deve corresponder ao campo `name` no `SKILL.md`. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente. + +--- + +## Skills Pré-carregadas + +Para mais controle, você pode descobrir e ativar skills programaticamente: + +```python +from pathlib import Path +from crewai.skills import discover_skills, activate_skill + +# Descobrir todas as skills em um diretório +skills = discover_skills(Path("./skills")) + +# Ativá-las (carrega o corpo completo do SKILL.md) +activated = [activate_skill(s) for s in skills] + +# Passar para um agente +agent = Agent( + role="Researcher", + goal="Find relevant information", + backstory="An expert researcher.", + skills=activated, +) +``` + +--- + +## Como as Skills São Carregadas + +Skills usam **divulgação progressiva** — carregando apenas o necessário em cada estágio: + +| Estágio | O que é carregado | Quando | +| :--------- | :------------------------------------ | :------------------ | +| Descoberta | Nome, descrição, campos do frontmatter | `discover_skills()` | +| Ativação | Texto completo do corpo do SKILL.md | `activate_skill()` | + +Durante a execução normal do agente (passando caminhos de diretório via `skills=["./skills"]`), skills são automaticamente descobertas e ativadas. O carregamento progressivo só importa quando usando a API programática. + +--- + +## Skills vs Knowledge + +Tanto skills quanto knowledge modificam o prompt do agente, mas servem propósitos diferentes: + +| Aspecto | Skills | Knowledge | +| :--- | :--- | :--- | +| **O que fornece** | Instruções, procedimentos, diretrizes | Fatos, dados, informações | +| **Como é armazenado** | Arquivos Markdown (SKILL.md) | Embarcado em banco vetorial (ChromaDB) | +| **Como é recuperado** | Corpo inteiro injetado no prompt | Busca semântica encontra trechos relevantes | +| **Melhor para** | Metodologia, checklists, guias de estilo | Documentos da empresa, info de produto, dados de referência | +| **Definido via** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**Regra prática:** Se o agente precisa seguir um *processo*, use uma skill. Se o agente precisa consultar *dados*, use knowledge. + +--- + +## Perguntas Frequentes + + + + Depende do seu caso de uso. Skills e ferramentas são **independentes** — você pode usar qualquer um, ambos ou nenhum. + + - **Apenas skills**: Quando o agente precisa de expertise mas não de ações externas (ex: escrever com diretrizes de estilo) + - **Apenas ferramentas**: Quando o agente precisa de ações mas não de metodologia especial (ex: busca simples na web) + - **Ambos**: Quando o agente precisa de expertise E ações (ex: auditoria de segurança com checklists específicas E capacidade de escanear código) + + + + **Não.** O campo `allowed-tools` no SKILL.md é apenas metadado experimental — ele não provisiona nem injeta nenhuma ferramenta. Você deve sempre definir ferramentas separadamente via `tools=[]`, `mcps=[]` ou `apps=[]`. + + + + A skill no nível do agente tem prioridade. Skills são deduplicadas por nome — as skills do agente são processadas primeiro, então se o mesmo nome de skill aparece em ambos os níveis, a versão do agente é usada. + + + + Há um aviso suave em 50.000 caracteres, mas sem limite rígido. Mantenha skills focadas e concisas para melhores resultados — injeções de prompt muito grandes podem diluir a atenção do agente. + + diff --git a/docs/v1.15.1/pt-BR/concepts/tasks.mdx b/docs/v1.15.1/pt-BR/concepts/tasks.mdx new file mode 100644 index 000000000..29a012083 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/tasks.mdx @@ -0,0 +1,1105 @@ +--- +title: Tarefas +description: Guia detalhado sobre como gerenciar e criar tarefas dentro do framework CrewAI. +icon: list-check +mode: "wide" +--- + +## 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 AMP 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. | +| **Criar Diretório** _(opcional)_ | `create_directory` | `Optional[bool]` | Se deve criar o diretório para output_file caso não exista. O padrão é True. | +| **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. | +| **Guardrail** _(opcional)_ | `guardrail` | `Optional[Callable]` | Função para validar a saída da tarefa antes de prosseguir para a próxima tarefa. | +| **Max Tentativas Guardrail** _(opcional)_ | `guardrail_max_retries` | `Optional[int]` | Número máximo de tentativas quando a validação do guardrail falha. Padrão é 3. | + +## Criando Tarefas + +Existem duas formas comuns de criar tarefas no CrewAI: usando **configuração JSONC (recomendado para novas crews)** ou definindo-as **diretamente no código**. + +### Configuração JSONC (Recomendado) + +Novos projetos criados com `crewai create crew ` definem tarefas no `crew.jsonc`. + +````jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "reporting_analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research about {topic}.", + "expected_output": "A list of the most relevant information about {topic}.", + "agent": "researcher" + }, + { + "name": "reporting_task", + "description": "Review the research and expand it into a detailed report.", + "expected_output": "A polished markdown report.", + "agent": "reporting_analyst", + "context": ["research_task"], + "markdown": true, + "output_file": "report.md" + } + ], + "inputs": { + "topic": "AI Agents" + } +} +```` + +Cada tarefa precisa de `description` e `expected_output`. O valor de `agent` deve corresponder a um agente listado em `agents`. `context` referencia nomes de tarefas anteriores; referências futuras são rejeitadas. Campos comuns incluem `name`, `agent`, `context`, `output_file`, `tools`, `human_input`, `async_execution`, `guardrail`, `guardrails`, `markdown`, `output_json`, `output_pydantic` e `response_model`. + +### Configuração YAML Clássica + +Projetos clássicos criados com `crewai create crew --classic` usam `config/tasks.yaml` e uma classe `@CrewBase` em `crew.py`. + +A configuração YAML continua suportada para projetos existentes em Python/YAML e para equipes que preferem definir tarefas a partir de uma classe `@CrewBase`. + +Após criar um projeto clássico, navegue até o arquivo `src//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//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. + +Guardrails são implementados como funções Python que contêm lógica de validação customizada, proporcionando controle total sobre o processo de validação e garantindo resultados confiáveis e determinísticos. + +### Guardrails Baseados em Função + +Para adicionar um guardrail baseado em função 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")` + +### 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"ERRO_DE_VALIDACAO: {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, + guardrail_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 +) +``` + +```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, + guardrail_max_retries=5 # Sobrescreve o limite padrão de tentativas +) +``` + +## Criando Diretórios ao Salvar Arquivos + +O parâmetro `create_directory` controla se o CrewAI deve criar automaticamente diretórios ao salvar saídas de tarefas em arquivos. Este recurso é particularmente útil para organizar outputs e garantir que os caminhos de arquivos estejam estruturados corretamente, especialmente ao trabalhar com hierarquias de projetos complexas. + +### Comportamento Padrão + +Por padrão, `create_directory=True`, o que significa que o CrewAI criará automaticamente qualquer diretório ausente no caminho do arquivo de saída: + +```python Code +# Comportamento padrão - diretórios são criados automaticamente +report_task = Task( + description='Gerar um relatório abrangente de análise de mercado', + expected_output='Uma análise detalhada de mercado com gráficos e insights', + agent=analyst_agent, + output_file='reports/2025/market_analysis.md', # Cria 'reports/2025/' se não existir + markdown=True +) +``` + +### Desabilitando a Criação de Diretórios + +Se você quiser evitar a criação automática de diretórios e garantir que o diretório já exista, defina `create_directory=False`: + +```python Code +# Modo estrito - o diretório já deve existir +strict_output_task = Task( + description='Salvar dados críticos que requerem infraestrutura existente', + expected_output='Dados salvos em localização pré-configurada', + agent=data_agent, + output_file='secure/vault/critical_data.json', + create_directory=False # Gerará RuntimeError se 'secure/vault/' não existir +) +``` + +### Configuração YAML + +Você também pode configurar este comportamento em suas definições de tarefas YAML: + +```yaml tasks.yaml +analysis_task: + description: > + Gerar análise financeira trimestral + expected_output: > + Um relatório financeiro abrangente com insights trimestrais + agent: financial_analyst + output_file: reports/quarterly/q4_2024_analysis.pdf + create_directory: true # Criar automaticamente o diretório 'reports/quarterly/' + +audit_task: + description: > + Realizar auditoria de conformidade e salvar no diretório de auditoria existente + expected_output: > + Um relatório de auditoria de conformidade + agent: auditor + output_file: audit/compliance_report.md + create_directory: false # O diretório já deve existir +``` + +### Casos de Uso + +**Criação Automática de Diretórios (`create_directory=True`):** + +- Ambientes de desenvolvimento e prototipagem +- Geração dinâmica de relatórios com pastas baseadas em datas +- Fluxos de trabalho automatizados onde a estrutura de diretórios pode variar +- Aplicações multi-tenant com pastas específicas do usuário + +**Gerenciamento Manual de Diretórios (`create_directory=False`):** + +- Ambientes de produção com controles rígidos do sistema de arquivos +- Aplicações sensíveis à segurança onde diretórios devem ser pré-configurados +- Sistemas com requisitos específicos de permissão +- Ambientes de conformidade onde a criação de diretórios é auditada + +### Tratamento de Erros + +Quando `create_directory=False` e o diretório não existe, o CrewAI gerará um `RuntimeError`: + +```python Code +try: + result = crew.kickoff() +except RuntimeError as e: + # Tratar erro de diretório ausente + print(f"Falha na criação do diretório: {e}") + # Criar diretório manualmente ou usar local alternativo +``` + +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/v1.15.1/pt-BR/concepts/testing.mdx b/docs/v1.15.1/pt-BR/concepts/testing.mdx new file mode 100644 index 000000000..8277757e0 --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/testing.mdx @@ -0,0 +1,49 @@ +--- +title: Testes +description: Saiba como testar sua CrewAI Crew e avaliar seu desempenho. +icon: vial +mode: "wide" +--- + +## Visão Geral + +Testar é uma parte crucial do processo de desenvolvimento, sendo essencial para garantir que sua crew está performando conforme o esperado. Com o crewAI, você pode facilmente testar sua crew e avaliar seu desempenho utilizando as funcionalidades de teste integradas. + +### Utilizando o Recurso de Teste + +Adicionamos o comando de CLI `crewai test` para facilitar o teste da sua crew. Esse comando executará sua crew por um número especificado de iterações e fornecerá métricas de desempenho detalhadas. Os parâmetros são `n_iterations` e `model`, ambos opcionais e com valores padrão de 2 e `gpt-4o-mini`, respectivamente. Por enquanto, o único provedor disponível é a OpenAI. + +```bash +crewai test +``` + +Se quiser rodar mais iterações ou utilizar um modelo diferente, você pode especificar os parâmetros assim: + +```bash +crewai test --n_iterations 5 --model gpt-4o +``` + +ou usando as formas abreviadas: + +```bash +crewai test -n 5 -m gpt-4o +``` + +Ao executar o comando `crewai test`, a crew será executada pelo número especificado de iterações, e as métricas de desempenho serão exibidas ao final da execução. + +Uma tabela de pontuações ao final mostrará o desempenho da crew em relação às seguintes métricas: + +
**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/v1.15.1/pt-BR/concepts/tools.mdx b/docs/v1.15.1/pt-BR/concepts/tools.mdx new file mode 100644 index 000000000..da7e6f24a --- /dev/null +++ b/docs/v1.15.1/pt-BR/concepts/tools.mdx @@ -0,0 +1,292 @@ +--- +title: Ferramentas +description: Compreendendo e aproveitando ferramentas dentro do framework CrewAI para colaboração e execução de tarefas por agentes. +icon: screwdriver-wrench +mode: "wide" +--- + +## Visão geral + +As ferramentas do CrewAI capacitam agentes com habilidades que vão desde busca na web e análise de dados até colaboração e delegação de tarefas entre colegas de trabalho. +Esta documentação descreve como criar, integrar e aproveitar essas ferramentas dentro do framework CrewAI, incluindo um novo foco em ferramentas de colaboração. + + + Ferramentas dão aos agentes **funções chamáveis** para tomar ações. Elas funcionam junto com [MCPs](/pt-BR/mcp/overview) (servidores de ferramentas remotos), [Apps](/pt-BR/concepts/agent-capabilities) (integrações com plataformas), [Skills](/pt-BR/concepts/skills) (expertise de domínio) e [Knowledge](/pt-BR/concepts/knowledge) (fatos recuperados). Veja a visão geral de [Capacidades do Agente](/pt-BR/concepts/agent-capabilities) para entender quando usar cada um. + + +## 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 AMP oferece um Repositório de Ferramentas abrangente, com integrações pré-construídas para sistemas empresariais e APIs comuns. Implemente agentes com ferramentas corporativas em minutos em vez de dias. + +O Repositório de Ferramentas Empresariais inclui: + +- Conectores pré-construídos para sistemas empresariais populares +- Interface para criação de ferramentas personalizadas +- Controle de versão e funcionalidades de compartilhamento +- Recursos de segurança e conformidade + + +## Características Principais das Ferramentas + +- **Utilidade**: Desenvolvidas para tarefas como busca web, análise de dados, geração de conteúdo e colaboração entre agentes. +- **Integração**: Potencializa as habilidades dos agentes ao integrar ferramentas de forma transparente ao seu fluxo de trabalho. +- **Personalização**: Oferece flexibilidade para desenvolver ferramentas personalizadas ou utilizar existentes, atendendo necessidades específicas dos agentes. +- **Tratamento de Erros**: Incorpora mecanismos robustos de tratamento de erros para garantir operação sem interrupções. +- **Mecanismo de Cache**: Possui cache inteligente para otimizar desempenho e reduzir operações redundantes. +- **Suporte Assíncrono**: Suporta ferramentas síncronas e assíncronas, permitindo operações não bloqueantes. + +## Utilizando Ferramentas CrewAI + +Para aprimorar as capacidades de seus agentes com as ferramentas do CrewAI, comece instalando nosso pacote extra de ferramentas: + +```bash +pip install 'crewai[tools]' +``` + +Aqui está um exemplo demonstrando seu uso: + +```python Code +import os +from crewai import Agent, Task, Crew +# Importando ferramentas do crewAI +from crewai_tools import ( + DirectoryReadTool, + FileReadTool, + SerperDevTool, + WebsiteSearchTool +) + +# Configure as chaves de API +os.environ["SERPER_API_KEY"] = "Your Key" # chave da API serper.dev +os.environ["OPENAI_API_KEY"] = "Your Key" + +# Instanciar as ferramentas +docs_tool = DirectoryReadTool(directory='./blog-posts') +file_tool = FileReadTool() +search_tool = SerperDevTool() +web_rag_tool = WebsiteSearchTool() + +# Criar agentes +researcher = Agent( + role='Analista de Mercado', + goal='Fornecer análise de mercado atualizada da indústria de IA', + backstory='Analista especialista com olhar atento para tendências de mercado.', + tools=[search_tool, web_rag_tool], + verbose=True +) + +writer = Agent( + role='Redator de Conteúdo', + goal='Criar posts de blog envolventes sobre a indústria de IA', + backstory='Redator habilidoso com paixão por tecnologia.', + tools=[docs_tool, file_tool], + verbose=True +) + +# Definir tarefas +research = Task( + description='Research the latest trends in the AI industry and provide a summary.', + expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.', + agent=researcher +) + +write = Task( + description='Write an engaging blog post about the AI industry, based on the research analyst's summary. Draw inspiration from the latest blog posts in the directory.', + expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.', + agent=writer, + output_file='blog-posts/new_post.md' # O post final do blog será salvo aqui +) + +# Montar um crew com o planejamento habilitado +crew = Crew( + agents=[researcher, writer], + tasks=[research, write], + verbose=True, + planning=True, # Habilitar o recurso de planejamento +) + +# Executar tarefas +crew.kickoff() +``` + +## Ferramentas CrewAI Disponíveis + +- **Tratamento de Erros**: Todas as ferramentas são construídas com capacidades de tratamento de erros, permitindo que os agentes administrem exceções de forma adequada e prossigam com suas tarefas. +- **Mecanismo de Cache**: Todas as ferramentas suportam cache, possibilitando que agentes reutilizem de forma eficiente resultados obtidos anteriormente, reduzindo a carga em recursos externos e acelerando o tempo de execução. Também é possível definir controles mais precisos sobre o mecanismo de cache usando o atributo `cache_function` na ferramenta. + +Aqui está uma lista das ferramentas disponíveis e suas descrições: + +| Ferramenta | Descrição | +| :------------------------------- | :--------------------------------------------------------------------------------------------------- | +| **ApifyActorsTool** | Ferramenta que integra Apify Actors aos seus fluxos de trabalho para web scraping e automação. | +| **BrowserbaseLoadTool** | Ferramenta para interação e extração de dados de navegadores web. | +| **CodeDocsSearchTool** | Uma ferramenta RAG otimizada para busca em documentações de código e documentos técnicos. | +| **CodeInterpreterTool** | Ferramenta para interpretar código Python. | +| **ComposioTool** | Permite o uso de ferramentas Composio. | +| **CSVSearchTool** | Ferramenta RAG projetada para busca em arquivos CSV, ideal para dados estruturados. | +| **DALL-E Tool** | Ferramenta para gerar imagens utilizando a API do DALL-E. | +| **DirectorySearchTool** | Ferramenta RAG para busca em diretórios, útil para navegação em sistemas de arquivos. | +| **DOCXSearchTool** | Ferramenta RAG voltada para busca em documentos DOCX, ideal para processar arquivos Word. | +| **DirectoryReadTool** | Facilita a leitura e processamento de estruturas de diretórios e seus conteúdos. | +| **ExaSearchTool** | Ferramenta projetada para buscas exaustivas em diversas fontes de dados. | +| **FileReadTool** | Permite a leitura e extração de dados de arquivos, suportando diversos formatos. | +| **FirecrawlSearchTool** | Ferramenta para buscar páginas web usando Firecrawl e retornar os resultados. | +| **FirecrawlCrawlWebsiteTool** | Ferramenta para rastrear páginas web utilizando o Firecrawl. | +| **FirecrawlScrapeWebsiteTool** | Ferramenta para extrair o conteúdo de URLs usando Firecrawl. | +| **GithubSearchTool** | Ferramenta RAG para buscar em repositórios GitHub, útil para pesquisa de código e documentação. | +| **SerperDevTool** | Ferramenta especializada para finalidades de desenvolvimento, com funcionalidades em evolução. | +| **TXTSearchTool** | Ferramenta RAG voltada para busca em arquivos de texto (.txt), adaptada para dados não estruturados. | +| **JSONSearchTool** | Ferramenta RAG para busca em arquivos JSON, voltada ao manuseio de dados estruturados. | +| **LlamaIndexTool** | Permite o uso das ferramentas LlamaIndex. | +| **MDXSearchTool** | Ferramenta RAG para busca em arquivos Markdown (MDX), útil para documentação. | +| **PDFSearchTool** | Ferramenta RAG para busca em documentos PDF, ideal para processar documentos digitalizados. | +| **PGSearchTool** | Ferramenta RAG otimizada para busca em bancos de dados PostgreSQL, adequada para consultas. | +| **Vision Tool** | Ferramenta para gerar imagens utilizando a API do DALL-E. | +| **RagTool** | Ferramenta RAG de uso geral, capaz de lidar com diferentes fontes e tipos de dados. | +| **ScrapeElementFromWebsiteTool** | Permite extrair elementos específicos de sites, útil para extração de dados direcionada. | +| **ScrapeWebsiteTool** | Facilita o scraping de sites inteiros, ideal para coleta abrangente de dados. | +| **WebsiteSearchTool** | Ferramenta RAG para busca em conteúdos de sites, otimizada para extração de dados web. | +| **XMLSearchTool** | Ferramenta RAG para busca em arquivos XML, adequada para formatos de dados estruturados. | +| **YoutubeChannelSearchTool** | Ferramenta RAG para busca em canais do YouTube, útil para análise de conteúdo em vídeo. | +| **YoutubeVideoSearchTool** | Ferramenta RAG para busca em vídeos do YouTube, ideal para extração de dados de vídeo. | + +## Criando suas próprias Ferramentas + + + 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. diff --git a/docs/v1.15.1/pt-BR/concepts/training.mdx b/docs/v1.15.1/pt-BR/concepts/training.mdx new file mode 100644 index 000000000..85e405fe8 --- /dev/null +++ b/docs/v1.15.1/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 +mode: "wide" +--- + +## Visão Geral + +O recurso de treinamento no CrewAI permite que você treine seus agentes de IA usando a interface de linha de comando (CLI). +Ao executar o comando `crewai train -n `, 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_iteracoes = 2 +entradas = {"topic": "Treinamento CrewAI"} +nome_arquivo = "seu_modelo.pkl" + +try: + SuaCrew().crew().train( + n_iterations=n_iteracoes, + inputs=entradas, + filename=nome_arquivo + ) +except Exception as e: + raise Exception(f"Ocorreu um erro ao treinar a crew: {e}") +``` + +### Pontos Importantes + +- **Requisito de Número Inteiro Positivo:** Certifique-se de que o número de iterações (`n_iterations`) seja um inteiro positivo. O código lançará um `ValueError` se essa condição não for atendida. +- **Requisito de Nome de Arquivo:** Certifique-se de que o nome do arquivo termine com `.pkl`. O código lançará um `ValueError` se essa condição não for atendida. +- **Tratamento de Erros:** O código trata erros de subprocessos e exceções inesperadas, fornecendo mensagens de erro ao usuário. + +É importante observar que o processo de treinamento pode levar algum tempo, dependendo da complexidade dos seus agentes e também exigirá seu feedback em cada iteração. + +Uma vez concluído o treinamento, seus agentes estarão equipados com capacidades e conhecimentos aprimorados, prontos para enfrentar tarefas complexas e fornecer insights mais consistentes e valiosos. + +Lembre-se de atualizar e treinar seus agentes regularmente para garantir que permaneçam atualizados com as últimas informações e avanços na área. + +Bom treinamento com o CrewAI! 🚀 \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/monitoring.mdx b/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/monitoring.mdx new file mode 100644 index 000000000..f578423d6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/monitoring.mdx @@ -0,0 +1,112 @@ +--- +title: "Observe suas Automações" +description: "Acompanhe a saúde da frota, o consumo de LLM e o comportamento por automação a partir da aba Automações." +sidebarTitle: "Monitoramento" +icon: "gauge" +mode: "wide" +--- + + + **Navegação da Documentação do ACP (Beta)** + + - [Visão Geral](/pt-BR/enterprise/features/agent-control-plane/overview) + - **Monitoramento** *(você está aqui)* + - [Regras](/pt-BR/enterprise/features/agent-control-plane/rules) + + +## Visão Geral + +A aba **Automações** é a visão de operações somente leitura do [Agent Control Plane](/pt-BR/enterprise/features/agent-control-plane/overview). Ela combina dois cards de métricas, um sankey interativo e duas sub-tabelas — **Automações** e **Consumo** — nas quais você pode buscar, filtrar e ordenar. + + + ![Visão geral do Agent Control Plane](/images/enterprise/acp-overview-automations-sankey.png) + + +Todos os gráficos e tabelas respeitam o seletor **Últimas 24 horas / Última Semana / Últimos 30 dias** no canto superior direito. As variações comparam a janela selecionada com a janela anterior de mesma duração. + + + As linhas só mostram dados de deployments em **crewAI v1.13 ou superior** — deployments mais antigos aparecem no banner *"We've detected N other automations that we can't display"* abaixo do sankey e não contribuem com nenhuma métrica até que sejam atualizados e re-implantados. Veja [Visão Geral — Requisitos](/pt-BR/enterprise/features/agent-control-plane/overview#requisitos). + + +## Dashboard + +O topo da página tem dois cards de métricas e um sankey interativo. Clicar em qualquer um dos cards alterna o sankey entre dois modos: + +- **Modo Saúde** — `Total de Automações → buckets de status (Critical / Warning / Healthy)`. Clique em um bucket para filtrar a tabela Automações para esses deployments. +- **Modo Consumo** — `Provedores de Modelo → Automações → Custo Total`. Clique em um provedor para filtrar a tabela Consumo para esse provedor. + +| Card | O que mostra | +|------|---------------| +| **Automações** | Automações `active` (e total), total de `errors` na janela, `active executions` no momento (e total na janela), com variação em relação ao período anterior. | +| **Consumo** | `cost` total e `tokens used`, com variação de custo em relação ao período anterior. | + + + ![Visão geral com o sankey de consumo](/images/enterprise/acp-overview-consumption-sankey.png) + + +## Tabela de Automações + +A sub-aba **Automações** é o detalhamento por deployment da saúde da frota. Cada linha é uma crew ou flow implantada. + + + ![Tabela de automações com o detalhamento de status de saúde](/images/enterprise/acp-automations-table.png) + + +| Coluna | O que mostra | +|--------|---------------| +| **Automação** | Nome do deployment e quaisquer tags atribuídas a ele (ex.: `production`, `financial`). | +| **Última execução** | Tempo decorrido desde a execução mais recente. | +| **Health Status Breakdown** | Barra empilhada com percentuais de `Critical` / `Warning` / `Healthy` para as execuções na janela. | +| **Executions with Errors** | Total de execuções com falha na janela. | +| **PII detection applied** | `Yes` se houver configuração de PII por deployment ou uma [regra de PII](/pt-BR/enterprise/features/agent-control-plane/rules) correspondente ativa. | +| **Executions** | Total de execuções na janela. | +| **Last updated** | Quando o deployment foi re-implantado pela última vez. | +| **Crew Version** | A versão do `crewai` reportada pelo deployment. Um ícone de informação ao lado de versões abaixo de `1.13` indica linhas que não conseguem contribuir com métricas. | + +Busque por nome, filtre por `Status` (`Healthy` / `Warning` / `Critical`) e ordene por qualquer cabeçalho de coluna. Clique no nome de um deployment para abrir o **painel da Automação**. + +## Tabela de Consumo + +A sub-aba **Consumo** é o detalhamento por deployment de gasto com LLM e uso de tokens. + + + ![Tabela de consumo detalhada por provedor de LLM](/images/enterprise/acp-consumption-table.png) + + +| Coluna | O que mostra | +|--------|---------------| +| **Automação** | Nome do deployment. | +| **Última execução** | Tempo decorrido desde a execução mais recente. | +| **Tokens used** | Uma linha por provedor de LLM usado por esta automação, com variação em relação ao período anterior. | +| **Cost** | Custo por provedor de LLM, com variação em relação ao período anterior. | +| **Total cost** | Soma entre todos os provedores, com a variação. | +| **Executions** | Total de execuções na janela. | +| **Last updated** | Quando o deployment foi re-implantado pela última vez. | +| **Crew Version** | A versão do `crewai` reportada pelo deployment. | + +Filtre por **LLM provider** e ordene por `Cost`, `Executions` ou `Last run`. + + + **Células vazias (`—` ou `$0.00`) normalmente significam que o deployment está abaixo do crewAI v1.13.** Na captura acima, *Automation F* (`1.7.0`) e *Automation I* (`1.12.2`) mostram valores em branco para tokens e custo — suas execuções ainda rodam, mas não emitem a telemetria a nível de provedor que alimenta esta tabela. Atualize e re-implante essas crews para começar a coletar dados de consumo. + + +## Relacionados + + + + O que é o ACP, requisitos, planos suportados e RBAC. + + + Aplique regras de PII Redaction em nível de organização em muitas automações. + + + Aprofunde em uma única execução para ver o raciocínio do agente, chamadas de ferramentas e uso de tokens. + + + Implante uma crew em uma versão do crewAI que suporta o Agent Control Plane. + + + + + Entre em contato com nosso time de suporte para ajudar a interpretar métricas no Agent Control Plane. + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/overview.mdx b/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/overview.mdx new file mode 100644 index 000000000..750309bac --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/overview.mdx @@ -0,0 +1,82 @@ +--- +title: Visão Geral do Agent Control Plane +description: "Hub único de operações para automações ao vivo — saúde da frota, consumo de LLM e políticas em nível de organização em um só lugar." +sidebarTitle: Visão Geral +icon: "book-open" +--- + + + **Navegação da Documentação do ACP (Beta)** + + - **Visão Geral** *(você está aqui)* + - [Monitoramento](/pt-BR/enterprise/features/agent-control-plane/monitoring) + - [Regras](/pt-BR/enterprise/features/agent-control-plane/rules) + + +## Visão Geral + +O **Agent Control Plane** (ACP) é o hub de operações para tudo que você tem rodando no CrewAI AMP. É uma tela única — dividida nas abas **Automações** e **Regras** — que permite à sua equipe: + +- Monitorar a **saúde** de cada automação ao vivo (crew ou flow), com detalhamentos `Critical` / `Warning` / `Healthy` e contagem de execuções. +- Acompanhar o **consumo de LLM** — tokens e custo — por automação, por provedor e por modelo, com a variação em relação ao período anterior. +- Aprofundar em qualquer automação ou provedor de modelo para ver gráficos de série temporal e detalhamentos por provedor. +- Aplicar **Regras** em nível de organização (hoje: PII Redaction) em muitas automações de uma só vez, em vez de editar cada deployment individualmente. + + + ![Visão geral do Agent Control Plane](/images/enterprise/acp-overview-automations-sankey.png) + + + + O Agent Control Plane está atualmente marcado como **Beta** na CrewAI Platform. + + +As duas abas respondem a duas perguntas distintas: + +- **Automações** — *"Como minha frota está se comportando agora e quanto está me custando?"* Veja [Monitoramento](/pt-BR/enterprise/features/agent-control-plane/monitoring). +- **Regras** — *"Como aplico uma política (por exemplo, PII redaction) em muitos deployments sem precisar reimplantar cada um?"* Veja [Regras](/pt-BR/enterprise/features/agent-control-plane/rules). + +## Requisitos + + + **crewAI v1.13 ou superior** é necessário para que uma automação preencha qualquer dado nesta página — saúde, execuções, erros, tokens e custo passam por telemetria que foi habilitada em `crewai==1.13`. Deployments mais antigos aparecem no banner *"We've detected N other automations that we can't display"* e não contribuem com nenhum dado até que sejam atualizados e re-implantados. + + + + **Plano Enterprise ou Ultra** é necessário para criar ou editar [Regras](/pt-BR/enterprise/features/agent-control-plane/rules). Organizações em planos inferiores ainda podem abrir a aba Regras e visualizar regras existentes, mas o editor é renderizado em modo somente leitura, com um selo "Enterprise" de bloqueio e o alerta *"PII Redaction rules require an Enterprise plan."* O Monitoramento (a aba Automações) está disponível em todos os planos em que o recurso esteja habilitado. + + +- O recurso **Agent Control Plane** precisa estar habilitado para sua organização. Se você não o vê na barra lateral, peça ao owner da conta para solicitar a habilitação. +- Dentro do ACP, o [RBAC](/pt-BR/enterprise/features/rbac) controla o acesso: `read` para visualizar o dashboard e as regras, `manage` para criar, editar, ligar/desligar ou excluir regras. +- Todos os gráficos e tabelas podem ser ajustados para **Últimas 24 horas**, **Última Semana** ou **Últimos 30 dias** usando o seletor de tempo no canto superior direito. As variações (`↑ 8 vs ontem`, `↓ $20.57 vs ontem`, etc.) comparam a janela selecionada com a janela anterior de mesma duração. + +## O que você pode fazer aqui + + + + Acompanhe a saúde da frota e o gasto com LLM com cards de métricas, um sankey interativo, tabelas por automação e painéis laterais de detalhamento para qualquer automação ou provedor. + + + Aplique políticas de PII Redaction em nível de organização, com escopo por ferramentas e tags. As mudanças entram em vigor na próxima execução — sem necessidade de re-implantação. + + + +## Relacionados + + + + Aprofunde em uma única execução para ver o raciocínio do agente, chamadas de ferramentas e uso de tokens. + + + Gerencie quem pode ler o Agent Control Plane e quem pode editar regras. + + + Catálogo de entidades e configuração de PII por deployment, referenciados pelas Regras. + + + Implante uma crew em uma versão do crewAI que suporta o Agent Control Plane. + + + + + Entre em contato com nosso time de suporte para interpretar métricas ou desenhar regras. + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/rules.mdx b/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/rules.mdx new file mode 100644 index 000000000..7d00fec86 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/agent-control-plane/rules.mdx @@ -0,0 +1,122 @@ +--- +title: "Configure as Regras" +description: "Aplique políticas em nível de organização em muitas automações a partir de um único lugar." +sidebarTitle: "Regras" +icon: "shield-check" +mode: "wide" +--- + + + **Navegação da Documentação do ACP (Beta)** + + - [Visão Geral](/pt-BR/enterprise/features/agent-control-plane/overview) + - [Monitoramento](/pt-BR/enterprise/features/agent-control-plane/monitoring) + - **Regras** *(você está aqui)* + + +## Visão Geral + +As Regras permitem aplicar políticas — hoje: **PII Redaction** — em muitas automações de uma só vez, em vez de configurar cada deployment individualmente. Abra a aba **Regras** no [Agent Control Plane](/pt-BR/enterprise/features/agent-control-plane/overview) para gerenciá-las. + + + ![Lista de regras](/images/enterprise/acp-rules-list.png) + + +Cada card de regra mostra o nome, a descrição, o **escopo** ao qual a regra se aplica (ferramentas e tags selecionadas) e a contagem de **automações engajadas** — deployments que atualmente correspondem ao escopo. O toggle à direita ativa ou desativa a regra sem excluí-la. + +## Requisitos + + + **Plano Enterprise ou Ultra** é necessário para criar ou editar regras de PII Redaction. Organizações em planos inferiores ainda podem abrir a aba Regras e visualizar regras existentes, mas o editor é renderizado em modo somente leitura, com um selo "Enterprise" de bloqueio e o alerta *"PII Redaction rules require an Enterprise plan."* — entre em contato com o owner da sua conta ou com vendas para fazer upgrade. + + +- O recurso **Agent Control Plane** precisa estar habilitado para sua organização. Veja [Visão Geral — Requisitos](/pt-BR/enterprise/features/agent-control-plane/overview#requisitos). +- A permissão `manage` no [RBAC](/pt-BR/enterprise/features/rbac) sobre o Agent Control Plane é necessária para criar, editar, ligar/desligar ou excluir regras. A permissão `read` é suficiente para visualizá-las. +- Todas as mudanças de regras são versionadas para auditoria. + +## Tipos de regra disponíveis + +| Tipo | O que faz | +|------|---------------| +| **PII Redaction** | Aplica PII redaction às execuções de cada automação correspondente, usando o mesmo catálogo de entidades e recognizers customizados documentados em [PII Redaction para Traces](/pt-BR/enterprise/features/pii-trace-redactions). | + +Mais tipos de regras serão adicionados ao longo do tempo. + +## Criando uma regra + + + Painel lateral de edição de regra com condições e tipo de máscara de PII + + + + + Clique em **+ Create new** no canto superior direito da aba Regras, ou em **View Details** em um card de regra existente. + + + + Dê à regra um nome claro (ex.: *Mask PII (CC)*) e uma descrição explicando quando ela se aplica. Ambos aparecem no card da regra e no modal de Automações Engajadas. + + + + Hoje só **PII Redaction** está disponível. + + + + As condições decidem quais automações a regra engaja. Ambas são opcionais e usam a semântica de **igualdade de conjuntos**: + + - **Tools** — apenas automações cujo conjunto de ferramentas **corresponde exatamente** às ferramentas selecionadas serão engajadas. Selecione entre apps do Studio, MCPs, ferramentas OSS e ferramentas do Tool Repository. + - **Automations** — apenas automações cujo conjunto de tags **corresponde exatamente** às tags selecionadas serão engajadas. + + Deixar um seletor vazio significa "sem filtro nesta dimensão". Deixar ambos vazios significa que a regra se aplica a **todas** as automações da organização. + + + + Marque cada tipo de entidade que deseja cobrir e escolha **Mask** (substitui pelo rótulo da entidade, ex.: ``) ou **Redact** (remove o texto correspondente por completo). Veja [PII Redaction para Traces](/pt-BR/enterprise/features/pii-trace-redactions) para o catálogo completo de entidades e como adicionar recognizers customizados em nível de organização. + + + + A regra se aplica a **futuras** execuções de cada automação engajada assim que você salva. Nenhuma re-implantação é necessária. + + + +## Automações engajadas + +Clique em **Engaged N automations** em qualquer card de regra para ver exatamente quais deployments a regra está correspondendo no momento, junto com a última execução de cada um. + + + ![Modal de automações engajadas](/images/enterprise/acp-rules-engaged-modal.png) + + +Esta é a forma mais rápida de validar o escopo de uma regra antes de habilitá-la — por exemplo, para confirmar que uma regra com escopo na tag `production` não está acidentalmente correspondendo a um deployment de staging. + +## Regras em nível de organização vs configurações por deployment + +A PII Redaction pode ser configurada em dois lugares: + +- **Por deployment** — em **Settings → PII Protection** em cada deployment individual ([guia](/pt-BR/enterprise/features/pii-trace-redactions)) +- **Em nível de organização** — como uma Regra nesta página + +Quando o escopo de uma regra habilitada em nível de organização corresponde a um deployment, a configuração de entidades da regra **sobrescreve** as configurações de PII pertencentes ao deployment para as execuções daquele deployment — a regra se torna a fonte única da verdade enquanto está vinculada. Desabilite ou desvincule a regra (ou altere o escopo para que ela não corresponda mais) e o deployment volta às suas próprias configurações de PII Protection. + +Prefira regras em nível de organização quando quiser impor uma política consistente em muitos deployments; reserve a configuração por deployment para exceções pontuais. + +## Relacionados + + + + O que é o ACP, requisitos, planos suportados e RBAC. + + + Acompanhe automações e consumo de LLM em toda a sua frota. + + + Catálogo de entidades, recognizers customizados e configuração por deployment. + + + Gerencie quem pode criar ou editar regras. + + + + + Entre em contato com nosso time de suporte para ajudar a desenhar regras para a sua organização. + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/agent-repositories.mdx b/docs/v1.15.1/pt-BR/enterprise/features/agent-repositories.mdx new file mode 100644 index 000000000..89e8c8fae --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/agent-repositories.mdx @@ -0,0 +1,156 @@ +--- +title: 'Repositórios de Agentes' +description: 'Aprenda a usar Repositórios de Agentes para compartilhar e reutilizar seus agentes entre equipes e projetos' +icon: 'database' +mode: "wide" +--- + +Repositórios de Agentes permitem que usuários do enterprise armazenem, compartilhem e reutilizem definições de agentes entre equipes e projetos. Esse recurso possibilita manter uma biblioteca centralizada de agentes padronizados, promovendo consistência e reduzindo a duplicidade de esforços. + +## Benefícios dos Repositórios de Agentes + +- **Padronização**: Mantenha definições de agentes consistentes em toda a sua organização +- **Reutilização**: Crie um agente uma vez e use-o em vários crews e projetos +- **Governança**: Implemente políticas organizacionais para configurações de agentes +- **Colaboração**: Permita que equipes compartilhem e evoluam o trabalho umas das outras + +## Usando Repositórios de Agentes + +### Pré-requisitos + +1. Você deve ter uma conta na CrewAI, experimente o [plano gratuito](https://app.crewai.com). +2. Você precisa estar autenticado usando o CLI da CrewAI. +3. Se você tiver mais de uma organização, garanta que alternou para a organização correta usando o comando do CLI: + +```bash +crewai org switch +``` + +### Criando e gerenciando agentes em repositórios + +Para criar e gerenciar agentes em repositórios, utilize o Painel do Enterprise. + +### Carregando agentes de repositórios + +Você pode carregar agentes de repositórios no seu código usando o parâmetro `from_repository`: + +```python +from crewai import Agent + +# Crie um agente carregando-o de um repositório +# O agente é carregado com todas as suas configurações predefinidas +researcher = Agent( + from_repository="market-research-agent" +) + +``` + +### Sobrescrevendo configurações do repositório + +Você pode sobrescrever configurações específicas do repositório informando-as na configuração do agente: + +```python +researcher = Agent( + from_repository="market-research-agent", + goal="Pesquisar as tendências mais recentes em desenvolvimento de IA", # Sobrescreve o goal do repositório + verbose=True # Adiciona uma configuração que não está no repositório +) +``` + +### Exemplo: criando um Crew com agentes do repositório + +```python +from crewai import Crew, Agent, Task + +# Carregue agentes dos repositórios +researcher = Agent( + from_repository="market-research-agent" +) + +writer = Agent( + from_repository="content-writer-agent" +) + +# Crie tarefas +research_task = Task( + description="Pesquise as tendências mais recentes em IA", + agent=researcher +) + +writing_task = Task( + description="Escreva um relatório abrangente com base na pesquisa", + agent=writer +) + +# Crie o crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +# Execute o crew +result = crew.kickoff() +``` + +### Exemplo: usando `kickoff()` com agentes do repositório + +Você também pode usar agentes de repositório diretamente com o método `kickoff()` para interações mais simples: + +```python +from crewai import Agent +from pydantic import BaseModel +from typing import List + +# Defina um formato de saída estruturado +class MarketAnalysis(BaseModel): + key_trends: List[str] + opportunities: List[str] + recommendation: str + +# Carregue um agente do repositório +analyst = Agent( + from_repository="market-analyst-agent", + verbose=True +) + +# Obtenha uma resposta livre (texto) +result = analyst.kickoff("Analise o mercado de IA em 2025") +print(result.raw) # Acessa a resposta bruta + +# Obtenha saída estruturada +structured_result = analyst.kickoff( + "Forneça uma análise estruturada do mercado de IA em 2025", + response_format=MarketAnalysis +) + +# Acesse os dados estruturados +print(f"Principais Tendências: {structured_result.pydantic.key_trends}") +print(f"Recomendação: {structured_result.pydantic.recommendation}") +``` + +## Boas práticas + +1. **Convenção de nomes**: Use nomes claros e descritivos para seus agentes de repositório +2. **Documentação**: Inclua descrições abrangentes para cada agente +3. **Gestão de ferramentas**: Garanta que as ferramentas referenciadas pelos agentes do repositório estejam disponíveis no seu ambiente +4. **Controle de acesso**: Gerencie permissões para que apenas membros autorizados possam modificar agentes do repositório + +## Gerenciamento de organização + +Para alternar entre organizações ou ver sua organização atual, use o CLI da CrewAI: + +```bash +# Ver organização atual +crewai org current + +# Alternar para outra organização +crewai org switch + +# Listar todas as organizações disponíveis +crewai org list +``` + + +Ao carregar agentes de repositórios, você deve estar autenticado e ter alternado para a organização correta. Se você receber erros, verifique seu status de autenticação e as configurações de organização usando os comandos do CLI acima. + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/automations.mdx b/docs/v1.15.1/pt-BR/enterprise/features/automations.mdx new file mode 100644 index 000000000..7aad2dd88 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/automations.mdx @@ -0,0 +1,103 @@ +--- +title: "Automações" +description: "Gerencie, implante e monitore seus crews (automações) em um só lugar." +icon: "rocket" +mode: "wide" +--- + +## Visão geral + +Automações é o hub operacional para seus crews implantados. Use para implantar via GitHub ou arquivo ZIP, gerenciar variáveis de ambiente, reimplantar quando necessário e monitorar o status de cada automação. + + + ![Visão Geral de Automações](/images/enterprise/automations-overview.png) + + +## Métodos de implantação + +### Implantar via GitHub + +Use para projetos versionados e implantação contínua. + + + + Clique em Configure GitHub e autorize o acesso. + + + Escolha o Repositório e a Branch que deseja implantar. + + + Ative Automatically deploy new commits para publicar a cada push. + + + Adicione segredos individualmente ou use Bulk View para múltiplas variáveis. + + + Clique em Deploy para criar sua automação. + + + + + ![Implantação via GitHub](/images/enterprise/deploy-from-github.png) + + +### Implantar via ZIP + +Envie rapidamente sem Git — faça upload de um pacote ZIP do projeto. + + + + Selecione o arquivo ZIP do seu computador. + + + Informe as variáveis necessárias. + + + Clique em Deploy para criar sua automação. + + + + + ![Implantação via ZIP](/images/enterprise/deploy-from-zip.png) + + +## Painel de Automações + +A tabela lista todas as automações com detalhes chave: + +- **CREW**: Nome da automação +- **STATUS**: Online / Failed / In Progress +- **URL**: Endpoint para kickoff/status +- **TOKEN**: Token da automação +- **ACTIONS**: Re‑deploy, delete e outros + +Use os controles no canto superior direito para filtrar e pesquisar: + +- Pesquisar por nome +- Filtrar por Status +- Filtrar por Source (GitHub / Studio / ZIP) + +Após implantar, você pode ver os detalhes da automação e usar o menu **Options** para `chat with this crew`, `Export React Component` e `Export as MCP`. + + + ![Tabela de Automações](/images/enterprise/automations-table.png) + + +## Boas práticas + +- Prefira implantações via GitHub para controle de versão e CI/CD +- Use re‑deploy para avançar após mudanças de código/config ou habilite auto‑deploy a cada push + +## Relacionados + + + + Implante um Crew via GitHub ou arquivo ZIP. + + + Dispare automações por webhooks ou API. + + + Transmita eventos e atualizações em tempo real. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/crew-studio.mdx b/docs/v1.15.1/pt-BR/enterprise/features/crew-studio.mdx new file mode 100644 index 000000000..30e28a6d6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/crew-studio.mdx @@ -0,0 +1,88 @@ +--- +title: "Crew Studio" +description: "Crie novas automações com assistência de IA, editor visual e testes integrados." +icon: "pencil" +mode: "wide" +--- + +## Visão geral + +O Crew Studio é um espaço interativo com assistência de IA para criar novas automações do zero usando linguagem natural e um editor visual de fluxo de trabalho. + + + ![Visão Geral do Crew Studio](/images/enterprise/crew-studio-overview.png) + + +## Criação baseada em prompts + +- Descreva a automação desejada; a IA gera agentes, tarefas e ferramentas. +- Use entrada por voz pelo ícone de microfone se preferir. +- Comece com prompts prontos para casos comuns. + + + ![Construtor de Prompt](/images/enterprise/crew-studio-prompt.png) + + +## Editor Visual + +O canvas reflete o fluxo como nós e arestas com três painéis de suporte que permitem configurar o fluxo sem escrever código ("vibe coding AI Agents"): + +- **AI Thoughts (esquerda)**: raciocínio em tempo real enquanto o fluxo é projetado +- **Canvas (centro)**: agentes e tarefas como nós conectados +- **Resources (direita)**: componentes de arrastar‑e‑soltar (agentes, tarefas, ferramentas) + +Você pode arrastar e soltar agentes, tarefas e ferramentas no canvas ou usar a seção de chat para construir os agentes. Ambos compartilham estado e podem ser usados de forma intercambiável. + + + ![Canvas Visual](/images/enterprise/crew-studio-canvas.png) + + +## Execução & Depuração + +Alterne para a visão Execution para executar e observar o fluxo: + +- Linha do tempo de eventos +- Logs detalhados (Details, Messages, Raw Data) +- Execuções locais antes de publicar + + + ![Visão de Execução](/images/enterprise/crew-studio-execution.png) + + +## Publicar & Exportar + +- Publish para implantar uma automação +- Download do código‑fonte como ZIP para desenvolvimento local + + + ![Publicar & Download](/images/enterprise/crew-studio-publish.png) + + +Após publicar, você pode visualizar os detalhes da automação e usar o menu **Options** para `chat with this crew`, `Export React Component` e `Export as MCP`. + + + ![Automação Publicada](/images/enterprise/crew-studio-published.png) + + +## Boas práticas + +- Itere rapidamente no Studio; publique apenas quando estiver estável +- Restrinja permissões das ferramentas ao mínimo necessário +- Use Traces para validar comportamento e desempenho + +## Relacionados + + + + Habilite o Crew Studio. + + + Crie um Crew. + + + Implante um Crew via GitHub ou ZIP. + + + Exporte um componente React. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/flow-hitl-management.mdx b/docs/v1.15.1/pt-BR/enterprise/features/flow-hitl-management.mdx new file mode 100644 index 000000000..d1f05e55f --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/flow-hitl-management.mdx @@ -0,0 +1,558 @@ +--- +title: "Gerenciamento HITL para Flows" +description: "Revisão humana de nível empresarial para Flows com notificações por email, regras de roteamento e capacidades de resposta automática" +icon: "users-gear" +mode: "wide" +--- + + +Os recursos de gerenciamento HITL para Flows requerem o decorador `@human_feedback`, disponível no **CrewAI versão 1.8.0 ou superior**. Estes recursos aplicam-se especificamente a **Flows**, não a Crews. + + +O CrewAI Enterprise oferece um sistema abrangente de gerenciamento Human-in-the-Loop (HITL) para Flows que transforma fluxos de trabalho de IA em processos colaborativos humano-IA. A plataforma usa uma **arquitetura email-first** que permite que qualquer pessoa com um endereço de email responda a solicitações de revisão—sem necessidade de conta na plataforma. + +## Visão Geral + + + + Respondentes podem responder diretamente aos emails de notificação para fornecer feedback + + + Direcione solicitações para emails específicos com base em padrões de método ou estado do flow + + + Configure respostas automáticas de fallback quando nenhum humano responder a tempo + + + +### Principais Benefícios + +- **Modelo mental simples**: Endereços de email são universais; não é necessário gerenciar usuários ou funções da plataforma +- **Respondentes externos**: Qualquer pessoa com email pode responder, mesmo não sendo usuário da plataforma +- **Atribuição dinâmica**: Obtenha o email do responsável diretamente do estado do flow (ex: `sales_rep_email`) +- **Configuração reduzida**: Menos configurações para definir, tempo mais rápido para gerar valor +- **Email como canal principal**: A maioria dos usuários prefere responder via email do que fazer login em um dashboard + +## Configurando Pontos de Revisão Humana em Flows + +Configure checkpoints de revisão humana em seus Flows usando o decorador `@human_feedback`. Quando a execução atinge um ponto de revisão, o sistema pausa, notifica o responsável via email e aguarda uma resposta. + +```python +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ContentApprovalFlow(Flow): + @start() + def generate_content(self): + return "Texto de marketing gerado para campanha Q1..." + + @human_feedback( + message="Por favor, revise este conteúdo para conformidade com a marca:", + emit=["approved", "rejected", "needs_revision"], + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Texto de marketing para revisão..." + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + print(f"Publicando conteúdo aprovado. Notas do revisor: {result.feedback}") + + @listen("rejected") + def archive_content(self, result: HumanFeedbackResult): + print(f"Conteúdo rejeitado. Motivo: {result.feedback}") +``` + +Para detalhes completos de implementação, consulte o guia [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows). + +### Parâmetros do Decorador + +| Parâmetro | Tipo | Descrição | +|-----------|------|-----------| +| `message` | `str` | A mensagem exibida para o revisor humano | +| `emit` | `list[str]` | Opções de resposta válidas (exibidas como botões na UI) | + +## Configuração da Plataforma + +Acesse a configuração HITL em: **Deployment** → **Settings** → **Human in the Loop Configuration** + + + Configurações HITL + + +### Notificações por Email + +Toggle para ativar ou desativar notificações por email para solicitações HITL. + +| Configuração | Padrão | Descrição | +|--------------|--------|-----------| +| Notificações por Email | Ativado | Enviar emails quando feedback for solicitado | + + +Quando desativado, os respondentes devem usar a UI do dashboard ou você deve configurar webhooks para sistemas de notificação personalizados. + + +### Meta de SLA + +Defina um tempo de resposta alvo para fins de rastreamento e métricas. + +| Configuração | Descrição | +|--------------|-----------| +| Meta de SLA (minutos) | Tempo de resposta alvo. Usado para métricas do dashboard e rastreamento de SLA | + +Deixe vazio para desativar o rastreamento de SLA. + +## Notificações e Respostas por Email + +O sistema HITL usa uma arquitetura email-first onde os respondentes podem responder diretamente aos emails de notificação. + +### Como Funcionam as Respostas por Email + + + + Quando uma solicitação HITL é criada, um email é enviado ao respondente atribuído com o conteúdo e contexto da revisão. + + + O email inclui um endereço reply-to especial com um token assinado para autenticação. + + + O respondente simplesmente responde ao email com seu feedback—nenhum login necessário. + + + A plataforma recebe a resposta, verifica o token assinado e corresponde o email do remetente. + + + O feedback é registrado e o flow continua com a entrada humana. + + + +### Formato de Resposta + +Respondentes podem responder com: + +- **Opção emit**: Se a resposta corresponder a uma opção `emit` (ex: "approved"), ela é usada diretamente +- **Texto livre**: Qualquer resposta de texto é passada para o flow como feedback +- **Texto simples**: A primeira linha do corpo da resposta é usada como feedback + +### Emails de Confirmação + +Após processar uma resposta, o respondente recebe um email de confirmação indicando se o feedback foi enviado com sucesso ou se ocorreu um erro. + +### Segurança do Token de Email + +- Tokens são assinados criptograficamente para segurança +- Tokens expiram após 7 dias +- Email do remetente deve corresponder ao email autorizado do token +- Emails de confirmação/erro são enviados após o processamento + +## Regras de Roteamento + +Direcione solicitações HITL para endereços de email específicos com base em padrões de método. + + + Configuração de Regras de Roteamento HITL + + +### Estrutura da Regra + +```json +{ + "name": "Aprovações para Financeiro", + "match": { + "method_name": "approve_*" + }, + "assign_to_email": "financeiro@empresa.com", + "assign_from_input": "manager_email" +} +``` + +### Padrões de Correspondência + +| Padrão | Descrição | Exemplo de Correspondência | +|--------|-----------|---------------------------| +| `approve_*` | Wildcard (qualquer caractere) | `approve_payment`, `approve_vendor` | +| `review_?` | Caractere único | `review_a`, `review_1` | +| `validate_payment` | Correspondência exata | apenas `validate_payment` | + +### Prioridade de Atribuição + +1. **Atribuição dinâmica** (`assign_from_input`): Se configurado, obtém email do estado do flow +2. **Email estático** (`assign_to_email`): Fallback para email configurado +3. **Criador do deployment**: Se nenhuma regra corresponder, o email do criador do deployment é usado + +### Exemplo de Atribuição Dinâmica + +Se seu estado do flow contém `{"sales_rep_email": "alice@empresa.com"}`, configure: + +```json +{ + "name": "Direcionar para Representante de Vendas", + "match": { + "method_name": "review_*" + }, + "assign_from_input": "sales_rep_email" +} +``` + +A solicitação será atribuída automaticamente para `alice@empresa.com`. + + +**Caso de Uso**: Obtenha o responsável do seu CRM, banco de dados ou etapa anterior do flow para direcionar revisões dinamicamente para a pessoa certa. + + +## Resposta Automática + +Responda automaticamente a solicitações HITL se nenhum humano responder dentro do timeout. Isso garante que os flows não fiquem travados indefinidamente. + +### Configuração + +| Configuração | Descrição | +|--------------|-----------| +| Ativado | Toggle para ativar resposta automática | +| Timeout (minutos) | Tempo de espera antes de responder automaticamente | +| Resultado Padrão | O valor da resposta (deve corresponder a uma opção `emit`) | + + + Configuração de Resposta Automática HITL + + +### Casos de Uso + +- **Conformidade com SLA**: Garante que flows não fiquem travados indefinidamente +- **Aprovação padrão**: Aprove automaticamente solicitações de baixo risco após timeout +- **Degradação graciosa**: Continue com um padrão seguro quando revisores não estiverem disponíveis + + +Use resposta automática com cuidado. Ative apenas para revisões não críticas onde uma resposta padrão é aceitável. + + +## Processo de Revisão + +### Interface do Dashboard + +A interface de revisão HITL oferece uma experiência limpa e focada para revisores: + +- **Renderização Markdown**: Formatação rica para conteúdo de revisão com destaque de sintaxe +- **Painel de Contexto**: Visualize estado do flow, histórico de execução e informações relacionadas +- **Entrada de Feedback**: Forneça feedback detalhado e comentários com sua decisão +- **Ações Rápidas**: Botões de opção emit com um clique com comentários opcionais + + + Lista de Solicitações HITL Pendentes + + +### Métodos de Resposta + +Revisores podem responder por três canais: + +| Método | Descrição | +|--------|-----------| +| **Resposta por Email** | Responda diretamente ao email de notificação | +| **Dashboard** | Use a UI do dashboard Enterprise | +| **API/Webhook** | Resposta programática via API | + +### Histórico e Trilha de Auditoria + +Toda interação HITL é rastreada com uma linha do tempo completa: + +- Histórico de decisões (aprovar/rejeitar/revisar) +- Identidade do revisor e timestamp +- Feedback e comentários fornecidos +- Método de resposta (email/dashboard/API) +- Métricas de tempo de resposta + +## Análise e Monitoramento + +Acompanhe o desempenho HITL com análises abrangentes. + +### Dashboard de Desempenho + + + Dashboard de Métricas HITL + + + + + Monitore tempos de resposta médios e medianos por revisor ou flow. + + + Analise padrões de volume de revisão para otimizar capacidade da equipe. + + + Visualize taxas de aprovação/rejeição em diferentes tipos de revisão. + + + Acompanhe a porcentagem de revisões concluídas dentro das metas de SLA. + + + +### Auditoria e Conformidade + +Capacidades de auditoria prontas para empresas para requisitos regulatórios: + +- Histórico completo de decisões com timestamps +- Verificação de identidade do revisor +- Logs de auditoria imutáveis +- Capacidades de exportação para relatórios de conformidade + +## Casos de Uso Comuns + + + + **Caso de Uso**: Automação de questionários de segurança internos com validação humana + + - IA gera respostas para questionários de segurança + - Equipe de segurança revisa e valida precisão via email + - Respostas aprovadas são compiladas na submissão final + - Trilha de auditoria completa para conformidade + + + + **Caso de Uso**: Conteúdo de marketing que requer revisão legal/marca + + - IA gera texto de marketing ou conteúdo de mídia social + - Roteie para email da equipe de marca para revisão de voz/tom + - Publicação automática após aprovação + + + + **Caso de Uso**: Relatórios de despesas, termos de contrato, alocações de orçamento + + - IA pré-processa e categoriza solicitações financeiras + - Roteie com base em limites de valor usando atribuição dinâmica + - Mantenha trilha de auditoria completa para conformidade financeira + + + + **Caso de Uso**: Direcione revisões para proprietários de conta do seu CRM + + - Flow obtém email do proprietário da conta do CRM + - Armazene email no estado do flow (ex: `account_owner_email`) + - Use `assign_from_input` para direcionar automaticamente para a pessoa certa + + + + **Caso de Uso**: Validação de saída de IA antes da entrega ao cliente + + - IA gera conteúdo ou respostas voltadas ao cliente + - Equipe de QA revisa via notificação por email + - Loops de feedback melhoram desempenho da IA ao longo do tempo + + + +## API de Webhooks + +Quando seus Flows pausam para feedback humano, você pode configurar webhooks para enviar dados da solicitação para sua própria aplicação. Isso permite: + +- Construir UIs de aprovação personalizadas +- Integrar com ferramentas internas (Jira, ServiceNow, dashboards personalizados) +- Rotear aprovações para sistemas de terceiros +- Notificações em apps mobile +- Sistemas de decisão automatizados + + + Configuração de Webhook HITL + + +### Configurando Webhooks + + + + Vá para **Deployment** → **Settings** → **Human in the Loop** + + + Clique para expandir a configuração de **Webhooks** + + + Digite sua URL de webhook (deve ser HTTPS em produção) + + + Clique em **Salvar Configuração** para ativar + + + +Você pode configurar múltiplos webhooks. Cada webhook ativo recebe todos os eventos HITL. + +### Eventos de Webhook + +Seu endpoint receberá requisições HTTP POST para estes eventos: + +| Tipo de Evento | Quando é Disparado | +|----------------|-------------------| +| `new_request` | Um flow pausa e solicita feedback humano | + +### Payload do Webhook + +Todos os webhooks recebem um payload JSON com esta estrutura: + +```json +{ + "event": "new_request", + "request": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "flow_id": "flow_abc123", + "method_name": "review_article", + "message": "Por favor, revise este artigo para publicação.", + "emit_options": ["approved", "rejected", "request_changes"], + "state": { + "article_id": 12345, + "author": "john@example.com", + "category": "technology" + }, + "metadata": {}, + "created_at": "2026-01-14T12:00:00Z" + }, + "deployment": { + "id": 456, + "name": "Content Review Flow", + "organization_id": 789 + }, + "callback_url": "https://api.crewai.com/...", + "assigned_to_email": "reviewer@company.com" +} +``` + +### Respondendo a Solicitações + +Para enviar feedback, **faça POST para a `callback_url`** incluída no payload do webhook. + +```http +POST {callback_url} +Content-Type: application/json + +{ + "feedback": "Aprovado. Ótimo artigo!", + "source": "my_custom_app" +} +``` + +### Segurança + + +Todas as requisições de webhook são assinadas criptograficamente usando HMAC-SHA256 para garantir autenticidade e prevenir adulteração. + + +#### Segurança do Webhook + +- **Assinaturas HMAC-SHA256**: Todo webhook inclui uma assinatura criptográfica +- **Secrets por webhook**: Cada webhook tem seu próprio secret de assinatura único +- **Criptografado em repouso**: Os secrets de assinatura são criptografados no nosso banco de dados +- **Verificação de timestamp**: Previne ataques de replay + +#### Headers de Assinatura + +Cada requisição de webhook inclui estes headers: + +| Header | Descrição | +|--------|-----------| +| `X-Signature` | Assinatura HMAC-SHA256: `sha256=` | +| `X-Timestamp` | Timestamp Unix de quando a requisição foi assinada | + +#### Verificação + +Verifique computando: + +```python +import hmac +import hashlib + +expected = hmac.new( + signing_secret.encode(), + f"{timestamp}.{payload}".encode(), + hashlib.sha256 +).hexdigest() + +if hmac.compare_digest(expected, signature): + # Assinatura válida +``` + +### Tratamento de Erros + +Seu endpoint de webhook deve retornar um código de status 2xx para confirmar o recebimento: + +| Sua Resposta | Nosso Comportamento | +|--------------|---------------------| +| 2xx | Webhook entregue com sucesso | +| 4xx/5xx | Registrado como falha, sem retry | +| Timeout (30s) | Registrado como falha, sem retry | + +## Segurança e RBAC + +### Acesso ao Dashboard + +O acesso HITL é controlado no nível do deployment: + +| Permissão | Capacidade | +|-----------|------------| +| `manage_human_feedback` | Configurar settings HITL, ver todas as solicitações | +| `respond_to_human_feedback` | Responder a solicitações, ver solicitações atribuídas | + +### Autorização de Resposta por Email + +Para respostas por email: +1. O token reply-to codifica o email autorizado +2. Email do remetente deve corresponder ao email do token +3. Token não deve estar expirado (padrão 7 dias) +4. Solicitação ainda deve estar pendente + +### Trilha de Auditoria + +Todas as ações HITL são registradas: +- Criação de solicitação +- Mudanças de atribuição +- Submissão de resposta (com fonte: dashboard/email/API) +- Status de retomada do flow + +## Solução de Problemas + +### Emails Não Enviando + +1. Verifique se "Notificações por Email" está ativado na configuração +2. Verifique se as regras de roteamento correspondem ao nome do método +3. Verifique se o email do responsável é válido +4. Verifique o fallback do criador do deployment se nenhuma regra de roteamento corresponder + +### Respostas de Email Não Processando + +1. Verifique se o token não expirou (padrão 7 dias) +2. Verifique se o email do remetente corresponde ao email atribuído +3. Garanta que a solicitação ainda está pendente (não respondida ainda) + +### Flow Não Retomando + +1. Verifique o status da solicitação no dashboard +2. Verifique se a URL de callback está acessível +3. Garanta que o deployment ainda está rodando + +## Melhores Práticas + + +**Comece Simples**: Comece com notificações por email para o criador do deployment, depois adicione regras de roteamento conforme seus fluxos de trabalho amadurecem. + + +1. **Use Atribuição Dinâmica**: Obtenha emails de responsáveis do seu estado do flow para roteamento flexível. + +2. **Configure Resposta Automática**: Defina um fallback para revisões não críticas para evitar que flows fiquem travados. + +3. **Monitore Tempos de Resposta**: Use análises para identificar gargalos e otimizar seu processo de revisão. + +4. **Mantenha Mensagens de Revisão Claras**: Escreva mensagens claras e acionáveis no decorador `@human_feedback`. + +5. **Teste o Fluxo de Email**: Envie solicitações de teste para verificar a entrega de email antes de ir para produção. + +## Recursos Relacionados + + + + Guia de implementação para o decorador `@human_feedback` + + + Guia passo a passo para configurar workflows HITL + + + Configure controle de acesso baseado em função para sua organização + + + Configure notificações de eventos em tempo real + + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/hallucination-guardrail.mdx b/docs/v1.15.1/pt-BR/enterprise/features/hallucination-guardrail.mdx new file mode 100644 index 000000000..c1b57fbc3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/hallucination-guardrail.mdx @@ -0,0 +1,251 @@ +--- +title: Proteção contra Alucinações +description: "Previna e detecte alucinações de IA nas suas tarefas do CrewAI" +icon: "shield-check" +mode: "wide" +--- + +## Visão Geral + +A Proteção contra Alucinações é um recurso empresarial que valida o conteúdo gerado por IA para garantir que esteja fundamentado em fatos e não contenha alucinações. Ela analisa as saídas das tarefas em relação ao contexto de referência e fornece feedback detalhado quando é detectado conteúdo potencialmente alucinado. + +## O que são Alucinações? + +Alucinações em IA ocorrem quando modelos de linguagem geram conteúdos que parecem plausíveis, mas estão factualmente incorretos ou não são suportados pelo contexto fornecido. A Proteção contra Alucinações ajuda a prevenir esses problemas por meio de: + +- Comparação das saídas com o contexto de referência +- Avaliação da fidelidade ao material de origem +- Fornecimento de feedback detalhado sobre conteúdo problemático +- Suporte a limiares personalizados para rigor da validação + +## Uso Básico + +### Configurando a Proteção + +```python +from crewai.tasks.hallucination_guardrail import HallucinationGuardrail +from crewai import LLM + +# Uso básico - utiliza o expected_output da tarefa como contexto +protecao = HallucinationGuardrail( + llm=LLM(model="gpt-4o-mini") +) + +# Com contexto de referência explícito +protecao_com_contexto = HallucinationGuardrail( + context="IA ajuda em várias tarefas, incluindo análise e geração.", + llm=LLM(model="gpt-4o-mini") +) +``` + +### Adicionando às Tarefas + +```python +from crewai import Task + +# Crie sua tarefa com a proteção +minha_tarefa = Task( + description="Escreva um resumo sobre as capacidades da IA", + expected_output="Um resumo factual baseado no contexto fornecido", + agent=meu_agente, + guardrail=protecao # Adiciona a proteção para validar a saída +) +``` + +## Configuração Avançada + +### Validação com Limiar Personalizado + +Para validação mais rigorosa, é possível definir um limiar de fidelidade personalizado (escala de 0-10): + +```python +# Proteção rigorosa exigindo alta pontuação de fidelidade +protecao_rigorosa = HallucinationGuardrail( + context="Computação quântica utiliza qubits que existem em estados de superposição.", + llm=LLM(model="gpt-4o-mini"), + threshold=8.0 # Requer pontuação >= 8 para validar +) +``` + +### Incluindo Contexto da Resposta de Ferramentas + +Se sua tarefa utiliza ferramentas, você pode incluir as respostas das ferramentas para validação mais precisa: + +```python +# Proteção com contexto de resposta da ferramenta +protecao_clima = HallucinationGuardrail( + context="Informações meteorológicas atuais para o local solicitado", + llm=LLM(model="gpt-4o-mini"), + tool_response="API do Clima retornou: Temperatura 22°C, Umidade 65%, Céu limpo" +) +``` + +## Como Funciona + +### Processo de Validação + +1. **Análise de Contexto**: A proteção compara a saída da tarefa com o contexto de referência fornecido +2. **Pontuação de Fidelidade**: Usa um avaliador interno para atribuir uma pontuação de fidelidade (0-10) +3. **Determinação do Veredito**: Determina se o conteúdo é fiel ou contém alucinações +4. **Verificação de Limiar**: Se um limiar personalizado for definido, valida contra essa pontuação +5. **Geração de Feedback**: Fornece motivos detalhados caso a validação falhe + +### Lógica de Validação + +- **Modo Padrão**: Utiliza validação baseada em veredito (FIÉL vs ALUCINADO) +- **Modo com Limiar**: Requer que a pontuação de fidelidade atinja ou supere o limiar especificado +- **Tratamento de Erros**: Lida com erros de avaliação de forma elegante e fornece feedback informativo + +## Resultados da Proteção + +A proteção retorna resultados estruturados indicando o status da validação: + +```python +# Exemplo de estrutura de resultado da proteção +{ + "valid": False, + "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context." +} +``` + +### Propriedades do Resultado + +- **valid**: Booleano indicando se a saída passou na validação +- **feedback**: Explicação detalhada quando a validação falha, incluindo: + - Pontuação de fidelidade + - Classificação do veredito + - Motivos específicos para a falha + +## Integração com o Sistema de Tarefas + +### Validação Automática + +Quando uma proteção é adicionada à tarefa, ela valida automaticamente a saída antes da tarefa ser marcada como concluída: + +```python +# Fluxo de validação de saída da tarefa +task_output = meu_agente.execute_task(minha_tarefa) +resultado_validacao = protecao(task_output) + +if resultado_validacao.valid: + # Tarefa concluída com sucesso + return task_output +else: + # Tarefa falha com feedback de validação + raise ValidationError(resultado_validacao.feedback) +``` + +### Rastreamento de Eventos + +A proteção se integra ao sistema de eventos do CrewAI para fornecer observabilidade: + +- **Validação Iniciada**: Quando a avaliação da proteção começa +- **Validação Concluída**: Quando a avaliação termina com resultados +- **Falha na Validação**: Quando ocorrem erros técnicos durante a avaliação + +## Melhores Práticas + +### Diretrizes para o Contexto + + + + Inclua todas as informações factuais relevantes nas quais a IA deve basear sua saída: + + ```python + contexto = """ + Empresa XYZ foi fundada em 2020 e é especializada em soluções de energia renovável. + Possui 150 funcionários e faturou R$ 50 milhões em 2023. + Seus principais produtos incluem painéis solares e turbinas eólicas. + """ + ``` + + + + Inclua apenas informações diretamente relacionadas à tarefa para evitar confusão: + + ```python + # Bom: Contexto focado + contexto = "O clima atual em Nova York é 18°C com chuva leve." + + # Evite: Informações irrelevantes + contexto = "The weather is 18°C. The city has 8 million people. Traffic is heavy." + ``` + + + + 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/v1.15.1/pt-BR/enterprise/features/marketplace.mdx b/docs/v1.15.1/pt-BR/enterprise/features/marketplace.mdx new file mode 100644 index 000000000..fa06188d2 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/marketplace.mdx @@ -0,0 +1,45 @@ +--- +title: "Marketplace" +description: "Descubra, instale e governe ativos reutilizáveis para seus crews enterprise." +icon: "store" +mode: "wide" +--- + +## Visão geral + +O Marketplace oferece uma superfície curada para descobrir integrações, ferramentas internas e ativos reutilizáveis que aceleram o desenvolvimento de crews. + + + ![Marketplace Visão Geral](/images/enterprise/marketplace-overview.png) + + +## Descoberta + +- Navegue por categoria e capacidade +- Pesquise por nome ou palavra‑chave + +## Instalar & Habilitar + +- Instalação com um clique para ativos aprovados +- Habilite ou desabilite por crew conforme necessário +- Configure variáveis de ambiente e escopos necessários + + + ![Instalar & Configurar](/images/enterprise/marketplace-install.png) + + +Você também pode baixar templates diretamente do marketplace clicando em `Download` para usar localmente ou personalizar conforme necessário. + +## Relacionados + + + + Conecte apps externos e gerencie ferramentas internas que seus agentes podem usar. + + + Publique e instale ferramentas para ampliar as capacidades dos seus crews. + + + Armazene, compartilhe e reutilize definições de agentes entre equipes e projetos. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/merged-step-card.mdx b/docs/v1.15.1/pt-BR/enterprise/features/merged-step-card.mdx new file mode 100644 index 000000000..3ca6cee60 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/merged-step-card.mdx @@ -0,0 +1,82 @@ +--- +title: Um Card por Etapa +description: "Cada etapa no canvas do Studio é um único card que combina a tarefa e o agente que a executa." +icon: "layer-group" +mode: "wide" +--- + +## Visão geral + +No canvas do Studio, cada etapa de trabalho é representada por um **único card**. O card combina dois elementos que antes ficavam em nós separados: + +- **A tarefa** — o que fazer (nome, descrição, saída esperada e formato da resposta). +- **O agente** — quem faz (o agente atribuído, seu modelo e suas ferramentas). + +Um agente não é um participante independente do seu fluxo de trabalho — ele é um atributo da tarefa: *qual agente executa este trabalho.* Colocar a tarefa e seu agente em um único card torna essa relação explícita e transforma sua automação em uma única cadeia de unidades de trabalho, da esquerda para a direita, mais fácil de ler em uma olhada. + + + ![Cards de etapa unificados no canvas](/images/enterprise/merged-step-card-canvas.png) + + +## No canvas + +Cada card recolhido mostra: + +- O **nome e a descrição da tarefa** no topo. +- Um **rodapé resumindo o agente atribuído** — avatar, nome, modelo e ferramentas. + +Não há nó de agente separado nem aresta vertical de agente → tarefa. Suas etapas se conectam diretamente umas às outras na ordem em que são executadas. + +## No editor + +Abra um card para editá-lo. A visão expandida é o mesmo card em um estado detalhado — não uma tela diferente — organizada em duas seções claramente identificadas. + + + ![Editor de etapa expandido](/images/enterprise/merged-step-card-editor.png) + + +### A tarefa — o que fazer + +Aberta por padrão, já que é o que você costuma editar: + +- **Nome** +- **Descrição** +- **Saída Esperada** +- **Formato da Resposta** — exibido aqui porque controla exatamente o que as etapas seguintes (como o roteamento) leem desta etapa. + +### O agente — quem faz + +O agente atribuído é mostrado como um resumo — **nome, modelo e ferramentas em linha**. Sua configuração mais detalhada é preservada por trás de duas seções recolhíveis: + +- **Papel, objetivo e história** +- **Configurações do agente** — raciocínio, máximo de tentativas de raciocínio, permitir delegação, máximo de iterações e configurações de LLM. + + + A configuração completa de um agente — Papel, Objetivo, História, Modelo, Ferramentas, Configurações de LLM e todo o bloco de Configurações do agente — fica por trás das seções recolhíveis **Papel, objetivo e história** e **Configurações do agente**, organizada pela frequência com que você a edita. + + +## Trocar vs. editar o agente + +Há duas maneiras distintas de trabalhar com o agente em um card, e elas fazem coisas diferentes: + +- **Trocar** reatribui *qual* agente executa esta tarefa. Use o controle **Trocar** para escolher um agente diferente deste projeto, selecionar um do seu Repositório de Agentes ou criar um novo agente. Isso tem escopo limitado à tarefa. +- **Editar** o agente — abrindo **Papel, objetivo e história** ou **Configurações do agente** — altera o agente *em si*. + + + ![Painel de troca de agente](/images/enterprise/merged-step-card-swap-agent.png) + + + + **Os agentes são reutilizáveis e compartilhados.** O mesmo agente pode executar mais de uma tarefa em todo o seu projeto. Editar o papel, a história ou as configurações de um agente atualiza esse agente **em todos os lugares onde ele é usado** — não apenas no card que você abriu. Se quiser que uma alteração se aplique a apenas uma etapa, **Troque** por um agente diferente em vez de editar o agente compartilhado. + + +## Relacionados + + + + Crie automações com assistência de IA e um editor visual. + + + Gerencie e reutilize agentes em suas automações. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/pii-trace-redactions.mdx b/docs/v1.15.1/pt-BR/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..d52cc7b9f --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: Redação de PII para Traces +description: "Redija automaticamente dados sensíveis de traces de execução de crews e flows" +icon: "lock" +mode: "wide" +--- + +## Visão Geral + +A Redação de PII é um recurso do CrewAI AMP que detecta e mascara automaticamente Informações de Identificação Pessoal (PII) nos traces de execução de crews e flows. Isso garante que dados sensíveis como números de cartão de crédito, CPF, endereços de e-mail e nomes não sejam expostos nos traces do CrewAI AMP. Você também pode criar reconhecedores personalizados para proteger dados específicos da sua organização. + + + + A Redação de PII está disponível no plano Enterprise. + A implantação deve ser versão 1.8.0 ou superior. + + + + + ![Visão Geral da Redação de PII](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## Por Que a Redação de PII é Importante + +Ao executar agentes de IA em produção, informações sensíveis frequentemente fluem através das suas crews: + +- Dados de clientes de integrações CRM +- Informações financeiras de processadores de pagamento +- Detalhes pessoais de envios de formulários +- Dados internos de funcionários + +Sem a redação adequada, esses dados aparecem nos traces, tornando a conformidade com regulamentações como LGPD, HIPAA e PCI-DSS desafiadora. A Redação de PII resolve isso mascarando automaticamente dados sensíveis antes de serem armazenados nos traces. + +## Como Funciona + +1. **Detectar** - Escanear dados de eventos de trace para padrões de PII conhecidos +2. **Classificar** - Identificar o tipo de dado sensível (cartão de crédito, CPF, e-mail, etc.) +3. **Mascarar/Redigir** - Substituir os dados sensíveis por valores mascarados com base na sua configuração + +``` +Original: "Entre em contato com john.doe@company.com ou ligue para 555-123-4567" +Redigido: "Entre em contato com ou ligue para " +``` + +## Habilitando a Redação de PII + + + Você deve estar no plano Enterprise e sua implantação deve ser versão 1.8.0 ou superior para usar este recurso. + + + + + No painel do CrewAI AMP, selecione sua crew implantada e vá para uma de suas implantações/automações, depois navegue até **Settings** → **PII Protection**. + + + + Ative **PII Redaction for Traces**. Isso habilitará a varredura automática e redação de dados de trace. + + + Você precisa habilitar manualmente a Redação de PII para cada implantação. + + + + ![Habilitar Redação de PII](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + Selecione quais tipos de PII detectar e redigir. Cada entidade pode ser habilitada ou desabilitada individualmente. + + + ![Configurar Entidades](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + Salve sua configuração. A redação de PII estará ativa em todas as execuções subsequentes da crew, sem necessidade de reimplantação. + + + +## Tipos de Entidade Suportados + +O CrewAI suporta os seguintes tipos de entidade PII, organizados por categoria. + +### Entidades Globais + +| Entidade | Descrição | Exemplo | +|----------|-----------|---------| +| `CREDIT_CARD` | Números de cartão de crédito/débito | "4111-1111-1111-1111" | +| `CRYPTO` | Endereços de carteira de criptomoedas | "bc1qxy2kgd..." | +| `DATE_TIME` | Datas e horários | "15 de janeiro de 2024" | +| `EMAIL_ADDRESS` | Endereços de e-mail | "john@example.com" | +| `IBAN_CODE` | Números de conta bancária internacional | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | Endereços IPv4 e IPv6 | "192.168.1.1" | +| `LOCATION` | Localizações geográficas | "São Paulo" | +| `MEDICAL_LICENSE` | Números de licença médica | "CRM12345" | +| `NRP` | Nacionalidades, grupos religiosos ou políticos | - | +| `PERSON` | Nomes pessoais | "João Silva" | +| `PHONE_NUMBER` | Números de telefone em vários formatos | "+55 (11) 98765-4321" | +| `URL` | URLs da web | "https://example.com" | + +### Entidades Específicas dos EUA + +| Entidade | Descrição | Exemplo | +|----------|-----------|---------| +| `US_BANK_NUMBER` | Números de conta bancária dos EUA | "1234567890" | +| `US_DRIVER_LICENSE` | Números de carteira de motorista dos EUA | "D1234567" | +| `US_ITIN` | Número de Identificação de Contribuinte Individual | "900-70-0000" | +| `US_PASSPORT` | Números de passaporte dos EUA | "123456789" | +| `US_SSN` | Números de Seguro Social | "123-45-6789" | + +## Ações de Redação + +Para cada entidade habilitada, você pode configurar como os dados são redigidos: + +| Ação | Descrição | Exemplo de Saída | +|------|-----------|------------------| +| `mask` | Substituir pelo rótulo do tipo de entidade | `` | +| `redact` | Remover completamente o texto | *(vazio)* | + +## Reconhecedores Personalizados + +Além das entidades integradas, você pode criar **reconhecedores personalizados** para detectar padrões de PII específicos da sua organização. + + + ![Reconhecedores Personalizados](/images/enterprise/pii_mask_recognizer.png) + + +### Tipos de Reconhecedores + +Você tem duas opções para reconhecedores personalizados: + +| Tipo | Melhor Para | Exemplo de Caso de Uso | +|------|-------------|------------------------| +| **Baseado em Padrão (Regex)** | Dados estruturados com formatos previsíveis | Valores de salário, IDs de funcionários, códigos de projeto | +| **Lista de Negação** | Correspondências exatas de strings | Nomes de empresas, codinomes internos, termos específicos | + +### Criando um Reconhecedor Personalizado + + + + Vá para **Settings** da Organização → **Organization** → **Add Recognizer**. + + + + + ![Configurar Reconhecedor](/images/enterprise/pii_mask_recognizer_create.png) + + + Configure os seguintes campos: + - **Name**: Um nome descritivo para o reconhecedor + - **Entity Type**: O rótulo da entidade que aparecerá na saída redigida (ex.: `EMPLOYEE_ID`, `SALARY`) + - **Type**: Escolha entre Padrão Regex ou Lista de Negação + - **Pattern/Values**: Padrão regex ou lista de strings para corresponder + - **Confidence Threshold**: Pontuação mínima (0.0-1.0) necessária para uma correspondência acionar a redação. Valores mais altos (ex.: 0.8) reduzem falsos positivos, mas podem perder algumas correspondências. Valores mais baixos (ex.: 0.5) capturam mais correspondências, mas podem redigir em excesso. O padrão é 0.8. + - **Context Words** (opcional): Palavras que aumentam a confiança de detecção quando encontradas próximas + + + + Salve o reconhecedor. Ele estará disponível para habilitar em suas implantações. + + + +### Entendendo os Tipos de Entidade + +O **Entity Type** determina como o conteúdo correspondido aparece nos traces redigidos: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +Entrada: "Salário do funcionário: $50,000" +Saída: "Salário do funcionário " +``` + +### Usando Palavras de Contexto + +Palavras de contexto melhoram a precisão aumentando a confiança quando termos específicos aparecem próximos ao padrão correspondido: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +Quando "project" ou "code" aparece próximo a "PRJ-1234", o reconhecedor tem maior confiança de que é uma correspondência verdadeira, reduzindo falsos positivos. + + +## Visualizando Traces Redigidos + +Uma vez que a redação de PII está habilitada, seus traces mostrarão valores redigidos no lugar de dados sensíveis: + +``` +Task Output: "Cliente fez o pedido #12345. +E-mail de contato: , telefone: . +Pagamento processado para cartão terminando em ." +``` + +Os valores redigidos são claramente marcados com colchetes angulares e o rótulo do tipo de entidade (ex.: ``), facilitando entender quais dados foram protegidos enquanto ainda permite depurar e monitorar o comportamento da crew. + + + +## Melhores Práticas + +### Considerações de Desempenho + + + + Cada entidade habilitada adiciona sobrecarga de processamento. Habilite apenas entidades relevantes para seus dados. + + + + Para reconhecedores personalizados, use padrões específicos para reduzir falsos positivos e melhorar o desempenho. Padrões regex são melhores para identificar padrões específicos nos traces como salário, ID de funcionário, código de projeto, etc. Reconhecedores de lista de negação são melhores para identificar strings exatas nos traces como nomes de empresas, codinomes internos, etc. + + + + Palavras de contexto melhoram a precisão acionando a detecção apenas quando o texto circundante corresponde. + + + +## Solução de Problemas + + + **Possíveis Causas:** + - Tipo de entidade não habilitado na configuração + - Padrão não corresponde ao formato dos dados + - Reconhecedor personalizado tem erros de sintaxe + + **Soluções:** + - Verifique se a entidade está habilitada em Settings → Security + - Teste padrões regex com dados de amostra + - Verifique logs para erros de configuração + + + + **Possíveis Causas:** + - Tipos de entidade muito amplos habilitados (ex.: `DATE_TIME` captura datas em todos os lugares) + - Padrões de reconhecedor personalizado são muito gerais + + **Soluções:** + - Desabilite entidades que causam falsos positivos + - Torne padrões personalizados mais específicos + - Adicione palavras de contexto para melhorar a precisão + + + + **Possíveis Causas:** + - Muitas entidades habilitadas + - Entidades baseadas em NLP (`PERSON`, `LOCATION`, `NRP`) são computacionalmente caras pois usam modelos de machine learning + + **Soluções:** + - Habilite apenas entidades que você realmente precisa + - Considere usar alternativas baseadas em padrão quando possível + - Monitore tempos de processamento de trace no painel + + +--- + +## Exemplo Prático: Correspondência de Padrão de Salário + +Este exemplo demonstra como criar um reconhecedor personalizado para detectar e mascarar informações de salário em seus traces. + +### Caso de Uso + +Sua crew processa dados de funcionários ou financeiros que incluem informações de salário em formatos como: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +Você deseja mascarar automaticamente esses valores para proteger dados sensíveis de remuneração. + +### Configuração + + + ![Configuração do Reconhecedor de Salário](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| Campo | Valor | +|-------|-------| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### Análise do Padrão Regex + +| Componente do Padrão | Significado | +|----------------------|-------------| +| `salary:` | Corresponde ao texto literal "salary:" | +| `\s*` | Corresponde a zero ou mais caracteres de espaço em branco | +| `\$` | Corresponde ao sinal de dólar (escapado) | +| `\s*` | Corresponde a zero ou mais caracteres de espaço em branco após $ | +| `\d{1,3}` | Corresponde a 1-3 dígitos (ex.: "1", "50", "125") | +| `(,\d{3})*` | Corresponde a milhares separados por vírgula (ex.: ",000", ",500,000") | +| `(\.\d{2})?` | Opcionalmente corresponde a centavos (ex.: ".00", ".50") | + +### Resultados de Exemplo + +``` +Original: "Registro do funcionário mostra salary: $125,000.00 anualmente" +Redigido: "Registro do funcionário mostra anualmente" + +Original: "Salário base salary:$50,000 com potencial de bônus" +Redigido: "Salário base com potencial de bônus" +``` + + + Adicionar palavras de contexto como "salary", "compensation", "pay", "wage" e "income" ajuda a aumentar a confiança de detecção quando esses termos aparecem próximos ao padrão correspondido, reduzindo falsos positivos. + + +### Habilite o Reconhecedor para Suas Implantações + + + Criar um reconhecedor personalizado no nível da organização não o habilita automaticamente para suas implantações. Você deve habilitar manualmente cada reconhecedor para cada implantação onde deseja aplicá-lo. + + +Após criar seu reconhecedor personalizado, habilite-o para cada implantação: + + + + Vá para sua implantação/automação e abra **Settings** → **PII Protection**. + + + + Em **Mask Recognizers**, você verá os reconhecedores definidos pela sua organização. Marque a caixa ao lado dos reconhecedores que deseja habilitar. + + + ![Habilitar Reconhecedor Personalizado](/images/enterprise/pii_mask_recognizers_options.png) + + + + + Salve suas alterações. O reconhecedor estará ativo em todas as execuções subsequentes para esta implantação. + + + + + Repita este processo para cada implantação onde você precisa do reconhecedor personalizado. Isso oferece controle granular sobre quais reconhecedores estão ativos em diferentes ambientes (ex.: desenvolvimento vs. produção). + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/rbac.mdx b/docs/v1.15.1/pt-BR/enterprise/features/rbac.mdx new file mode 100644 index 000000000..fef6ec44a --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/rbac.mdx @@ -0,0 +1,255 @@ +--- +title: "Controle de Acesso Baseado em Funções (RBAC)" +description: "Controle o acesso a crews, ferramentas e dados com funções, escopos e permissões granulares." +icon: "shield" +mode: "wide" +--- + +## Visão Geral + +O RBAC no CrewAI AMP permite gerenciamento de acesso seguro e escalável através de duas camadas: + +1. **Permissões de funcionalidade** — controlam o que cada função pode fazer na plataforma (gerenciar, ler ou sem acesso) +2. **Permissões em nível de entidade** — acesso granular em automações individuais, variáveis de ambiente, conexões LLM e repositórios Git + + + Visão geral de RBAC no CrewAI AMP + + +## Usuários e Funções + +Cada membro da sua workspace CrewAI recebe uma função, que determina seu acesso aos diversos recursos. + +Você pode: + +- Usar funções pré-definidas (Owner, Member) +- Criar funções personalizadas com permissões específicas +- Atribuir funções a qualquer momento no painel de configurações + +A configuração de usuários e funções é feita em Settings → Roles. + + + + Vá em Settings → Roles no CrewAI AMP. + + + Use uma função pré-definida (Owner, Member) ou clique em{" "} + Create role para criar uma personalizada. + + + Selecione os usuários e atribua a função. Você pode alterar depois. + + + +### Funções Pré-definidas + +| Função | Descrição | +| :--------- | :------------------------------------------------------------------------ | +| **Owner** | Acesso total a todas as funcionalidades e configurações. Não pode ser restrito. | +| **Member** | Acesso de leitura à maioria das funcionalidades, acesso de gerenciamento a variáveis de ambiente, conexões LLM e projetos Studio. Não pode modificar configurações da organização ou padrões. | + +### Resumo de configuração + +| Área | Onde configurar | Opções | +| :------------------------ | :--------------------------------- | :--------------------------------------------------- | +| Usuários & Funções | Settings → Roles | Pré-definidas: Owner, Member; Funções personalizadas | +| Visibilidade da automação | Automation → Settings → Visibility | Private; Lista de usuários/funções | + +--- + +## Matriz de Permissões de Funcionalidades + +Cada função possui um nível de permissão para cada área de funcionalidade. Os três níveis são: + +- **Manage** — acesso total de leitura/escrita (criar, editar, excluir) +- **Read** — acesso somente leitura +- **No access** — funcionalidade oculta/inacessível + +| Funcionalidade | Owner | Member (padrão) | Níveis disponíveis | Descrição | +| :------------------------ | :------ | :--------------- | :------------------------ | :-------------------------------------------------------------- | +| `usage_dashboards` | Manage | Read | Manage / Read / No access | Visualizar métricas e análises de uso | +| `crews_dashboards` | Manage | Read | Manage / Read / No access | Visualizar dashboards de deploy, acessar detalhes de automações | +| `invitations` | Manage | Read | Manage / Read / No access | Convidar novos membros para a organização | +| `training_ui` | Manage | Read | Manage / Read / No access | Acessar interfaces de treinamento/fine-tuning | +| `tools` | Manage | Read | Manage / Read / No access | Criar e gerenciar ferramentas | +| `agents` | Manage | Read | Manage / Read / No access | Criar e gerenciar agentes | +| `environment_variables` | Manage | Manage | Manage / No access | Criar e gerenciar variáveis de ambiente | +| `llm_connections` | Manage | Manage | Manage / No access | Configurar conexões de provedores LLM | +| `default_settings` | Manage | No access | Manage / No access | Modificar configurações padrão da organização | +| `organization_settings` | Manage | No access | Manage / No access | Gerenciar cobrança, planos e configuração da organização | +| `studio_projects` | Manage | Manage | Manage / No access | Criar e editar projetos no Studio | + + + Ao criar uma função personalizada, a maioria das funcionalidades pode ser definida como **Manage**, **Read** ou **No access**. No entanto, `environment_variables`, `llm_connections`, `default_settings`, `organization_settings` e `studio_projects` suportam apenas **Manage** ou **No access** — não há opção somente leitura para essas funcionalidades. + + +--- + +## Deploy via GitHub ou Zip + +Uma das perguntas mais comuns sobre RBAC é: _"Quais permissões um membro da equipe precisa para fazer deploy?"_ + +### Deploy via GitHub + +Para fazer deploy de uma automação a partir de um repositório GitHub, o usuário precisa de: + +1. **`crews_dashboards`**: pelo menos `Read` — necessário para acessar o dashboard de automações onde os deploys são criados +2. **Acesso ao repositório Git** (se RBAC em nível de entidade para repositórios Git estiver habilitado): a função do usuário deve ter acesso ao repositório Git específico via permissões de entidade +3. **`studio_projects`: `Manage`** — se estiver construindo o crew no Studio antes do deploy + +### Deploy via Zip + +Para fazer deploy de uma automação via upload de arquivo Zip, o usuário precisa de: + +1. **`crews_dashboards`**: pelo menos `Read` — necessário para acessar o dashboard de automações +2. **Deploys via Zip habilitados**: a organização não deve ter desabilitado deploys via Zip nas configurações da organização + +### Referência Rápida: Permissões Mínimas para Deploy + +| Ação | Permissões de funcionalidade necessárias | Requisitos adicionais | +| :------------------------- | :--------------------------------------- | :------------------------------------------------ | +| Deploy via GitHub | `crews_dashboards: Read` | Acesso à entidade do repositório Git (se habilitado) | +| Deploy via Zip | `crews_dashboards: Read` | Deploys via Zip devem estar habilitados na organização | +| Construir no Studio | `studio_projects: Manage` | — | +| Configurar chaves LLM | `llm_connections: Manage` | — | +| Definir variáveis de ambiente | `environment_variables: Manage` | Acesso em nível de entidade (se habilitado) | + +--- + +## Controle de Acesso em Nível de Automação (Permissões de Entidade) + +Além das funções em nível de organização, o CrewAI suporta permissões granulares em nível de entidade que restringem o acesso a recursos individuais. + +### Visibilidade da Automação + +Automações suportam configurações de visibilidade que restringem acesso por usuário ou função. Útil para: + +- Manter automações sensíveis ou experimentais privadas +- Gerenciar visibilidade em equipes grandes ou colaboradores externos +- Testar automações em contexto isolado + +Deploys podem ser configurados como privados, significando que apenas usuários e funções na whitelist poderão interagir com eles. + +Configure em Automation → Settings → aba Visibility. + + + + Acesse Automation → Settings → Visibility. + + + Selecione Private para restringir o acesso. O owner da organização + mantém acesso sempre. + + + Adicione usuários e funções que poderão ver, executar e acessar + logs/métricas/configurações. + + + Salve e confirme que não listados não conseguem ver ou executar a automação. + + + +### Resultado de acesso no modo Private + +| Ação | Owner | Usuário/função na whitelist | Não listado | +| :-------------------------- | :---- | :-------------------------- | :---------- | +| Ver automação | ✓ | ✓ | ✗ | +| Executar/API | ✓ | ✓ | ✗ | +| Logs/métricas/configurações | ✓ | ✓ | ✗ | + + + O owner sempre possui acesso. Em modo privado, somente usuários/funções na + whitelist têm permissão. + + + + Configuração de visibilidade no CrewAI AMP + + +### Tipos de Permissão de Deploy + +Ao conceder acesso em nível de entidade a uma automação específica, você pode atribuir estes tipos de permissão: + +| Permissão | O que permite | +| :------------------- | :-------------------------------------------------- | +| `run` | Executar a automação e usar sua API | +| `traces` | Visualizar traces de execução e logs | +| `manage_settings` | Editar, reimplantar, reverter ou excluir a automação | +| `human_in_the_loop` | Responder a solicitações human-in-the-loop (HITL) | +| `full_access` | Todos os anteriores | + +### RBAC em Nível de Entidade para Outros Recursos + +Quando o RBAC em nível de entidade está habilitado, o acesso a estes recursos também pode ser controlado por usuário ou função: + +| Recurso | Controlado por | Descrição | +| :--------------------- | :------------------------------------- | :------------------------------------------------------------- | +| Variáveis de ambiente | Flag de funcionalidade RBAC de entidade | Restringir quais funções/usuários podem ver ou gerenciar variáveis específicas | +| Conexões LLM | Flag de funcionalidade RBAC de entidade | Restringir acesso a configurações de provedores LLM específicos | +| Repositórios Git | Configuração RBAC de repositórios Git | Restringir quais funções/usuários podem acessar repositórios conectados específicos | + +--- + +## Padrões Comuns de Funções + +Embora o CrewAI venha com as funções Owner e Member, a maioria das equipes se beneficia da criação de funções personalizadas. Aqui estão os padrões comuns: + +### Função Developer + +Uma função para membros da equipe que constroem e fazem deploy de automações, mas não gerenciam configurações da organização. + +| Funcionalidade | Permissão | +| :------------------------ | :--------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Manage | +| `invitations` | Read | +| `training_ui` | Read | +| `tools` | Manage | +| `agents` | Manage | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | Manage | + +### Função Viewer / Stakeholder + +Uma função para stakeholders não técnicos que precisam monitorar automações e visualizar resultados. + +| Funcionalidade | Permissão | +| :------------------------ | :--------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Read | +| `invitations` | No access | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | No access | +| `llm_connections` | No access | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | No access | + +### Função Ops / Platform Admin + +Uma função para operadores de plataforma que gerenciam configurações de infraestrutura, mas podem não construir agentes. + +| Funcionalidade | Permissão | +| :------------------------ | :--------- | +| `usage_dashboards` | Manage | +| `crews_dashboards` | Manage | +| `invitations` | Manage | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | Manage | +| `organization_settings` | Read | +| `studio_projects` | No access | + +--- + + + Fale com o nosso time para suporte em configuração de RBAC. + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/aws-workload-identity.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/aws-workload-identity.mdx new file mode 100644 index 000000000..44795ae63 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/aws-workload-identity.mdx @@ -0,0 +1,321 @@ +--- +title: AWS Workload Identity (Federação OIDC) +description: Configure o AWS Secrets Manager via Workload Identity para acesso a segredos consciente de rotação e sem credenciais +sidebarTitle: Com Workload Identity +icon: "id-badge" +--- + +## Visão Geral + +Este guia configura o AWS Secrets Manager como provedor de segredos usando **Workload Identity Federation**: a CrewAI Platform emite tokens OIDC de curta duração, os troca por credenciais AWS via STS e lê seus segredos — sem que uma chave de acesso AWS de longa duração seja armazenada em lugar algum. + + +**Por que este caminho:** os segredos são resolvidos no momento de execução da automação, então **valores rotacionados se propagam para o próximo kickoff sem novo deploy**. Se você só precisa de credenciais estáticas e não se importa com a propagação de rotação, veja o guia mais simples [AWS — chaves estáticas / AssumeRole](/pt-BR/enterprise/features/secrets-manager/aws). + + +### Como funciona em runtime + +1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform. +2. O worker chama `sts:AssumeRoleWithWebIdentity` no role IAM que você configurou abaixo, apresentando o JWT. +3. O AWS STS valida o JWT contra o issuer OIDC público da CrewAI Platform (então sua instalação da plataforma deve ser acessível a partir da AWS), depois retorna credenciais AWS de curta duração. +4. O worker usa essas credenciais para chamar `secretsmanager:GetSecretValue`. +5. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação. + +Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação. + +## Pré-requisitos + + +Antes de começar, certifique-se de que você tem: + +- A imagem do pod de automação deve incluir o runtime da CrewAI versão `1.14.5` ou superior. +- Uma conta AWS com permissão para criar provedores IAM OIDC, roles IAM e políticas IAM. +- A região AWS onde seus segredos vivem (ou viverão), ex. `us-east-1`. +- Uma organização na CrewAI Platform onde seu usuário tem as permissões `workload_identity_configs: manage` e `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac). +- **O UUID da sua organização CrewAI.** Encontre-o na página de configurações da organização na CrewAI Platform — a trust policy no Passo 3 vincula o role IAM a esta organização específica. +- **Sua instalação da CrewAI Platform deve ser acessível a partir da AWS via HTTPS** para que o AWS STS possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet (ou que a AWS tem alcance de rede até ele via VPC peering / equivalente). + + +## Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform + +Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em `https:///.well-known/openid-configuration`. O campo `issuer` nesse documento é a URL que a AWS registrará como provedor OIDC confiável. + +Abra a URL em um navegador (substituindo `` pelo seu hostname real, ex. `app.crewai.com`): + +``` +https:///.well-known/openid-configuration +``` + +Você deverá ver um JSON contendo: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +Anote o valor exato de `issuer` — você o usará no Passo 3. + + +Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações `OIDC_PRIVATE_KEY` e `OIDC_ISSUER`. + + +## Passo 2 — Registrar a CrewAI Platform como um IAM OIDC Identity Provider + +Abra o [console IAM → Identity providers](https://console.aws.amazon.com/iam/home#/identity_providers) e clique em **Add provider**. + +- **Provider type:** OpenID Connect. +- **Provider URL:** o valor de `issuer` do Passo 1 (ex. `https://app.crewai.com`). +- **Audience:** `sts.amazonaws.com` + +Clique em **Add provider**. + +Ou via CLI: + +```bash +aws iam create-open-id-connect-provider \ + --url "https://" \ + --client-id-list "sts.amazonaws.com" \ + --thumbprint-list "$(echo | openssl s_client -servername -connect :443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')" +``` + +Copie o **OpenIDConnectProviderArn** da saída (ou o ARN do provedor no console). Você o usará no Passo 3. + + +A AWS não valida de fato o thumbprint para chamadas STS WebIdentity — ela sempre re-busca o JWKS no momento da validação — mas a API requer que o campo esteja presente. + + +{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */} +{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */} + +## Passo 3 — Criar o Role IAM + +Salve como `trust-policy.json`, substituindo ``, `` (o host do issuer **sem** `https://` ou `http://`, ex. `app.crewai.com`) e `` (dos Pré-requisitos): + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "arn:aws:iam:::oidc-provider/" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + ":aud": "sts.amazonaws.com", + ":sub": "organization:" + } + } + } + ] +} +``` + +Crie o role: + +```bash +aws iam create-role \ + --role-name crewai-secrets-reader \ + --assume-role-policy-document file://trust-policy.json +``` + +Copie o **Role Arn** da saída — esse é seu `aws_role_arn`. Você o colará na CrewAI Platform no Passo 6. + + +As duas condições escopam a confiança com precisão: `aud` restringe a assunção a tokens com a audience do AWS STS, e `sub` escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos. A CrewAI Platform sempre define ambas as claims nos tokens de workload identity da AWS. + + +{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */} + +## Passo 4 — Criar e anexar a política IAM para acesso ao Secrets Manager + KMS + +Salve como `secrets-policy.json`, substituindo os placeholders pelo ID da sua conta, região, prefixo do nome do segredo e o(s) ARN(s) da chave KMS que criptografa(m) esses segredos: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerListForUI", + "Effect": "Allow", + "Action": "secretsmanager:ListSecrets", + "Resource": "*" + }, + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:GetSecretValue" + ], + "Resource": "arn:aws:secretsmanager:::secret:-*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:Decrypt" + ], + "Resource": "arn:aws:kms:::key/" + } + ] +} +``` + +`SecretsManagerListForUI` alimenta o **autocomplete de Secret Name** no formulário de Environment Variables e o botão **Test Connection** na credencial. `secretsmanager:ListSecrets` só aceita `Resource: "*"` — é escopado por conta na camada IAM. + +Anexe a política ao role usando a CLI (política inline, mais simples) ou a UI do console; para ambientes que reutilizam as mesmas permissões em vários roles, use a aba **Managed policy** para uma política nomeada e reutilizável. + + + + ```bash + aws iam put-role-policy \ + --role-name crewai-secrets-reader \ + --policy-name SecretsManagerRead \ + --policy-document file://secrets-policy.json + ``` + + Isso anexa a política **inline** ao role. Políticas inline são vinculadas ao role e não podem ser reutilizadas em outros roles. + + + + ```bash + POLICY_ARN=$(aws iam create-policy \ + --policy-name CrewAISecretsReader \ + --policy-document file://secrets-policy.json \ + --query 'Policy.Arn' --output text) + + aws iam attach-role-policy \ + --role-name crewai-secrets-reader \ + --policy-arn "$POLICY_ARN" + ``` + + Uma política gerenciada é um recurso IAM autônomo que você pode anexar a vários roles. + + + + 1. Abra o [console IAM → Roles](https://console.aws.amazon.com/iam/home#/roles) e selecione **crewai-secrets-reader**. + 2. Na aba **Permissions**, clique em **Add permissions** → **Create inline policy**. + 3. Mude para o editor **JSON** e cole o conteúdo de `secrets-policy.json`. + 4. Clique em **Next**, dê um nome à política (ex. `SecretsManagerRead`) e clique em **Create policy**. + + Para criar uma política gerenciada reutilizável, use **IAM → Policies → Create policy** e depois anexe-a ao role pela aba **Permissions** do role. + + {/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */} + + + +## Passo 5 — Criar Pelo Menos Um Segredo na AWS + +Se você ainda não tem um segredo para testar, crie um agora: + +```bash +aws secretsmanager create-secret \ + --region \ + --name crewai-test-keyword \ + --secret-string "hello from aws" +``` + +Ou pelo [console do AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**. + +{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */} + +## Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform + +Na CrewAI Platform, navegue até **Settings** → **Workload Identity** e clique em **Add Workload Identity Config**. + +{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */} +{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */} + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `aws-prod`. +- **Cloud Provider:** `AWS`. +- **AWS Role ARN:** o **Role Arn** do Passo 3. +- **AWS Region:** a região onde seus segredos vivem, ex. `us-east-1`. +- (Opcional) Marque **Set as default for AWS** se você quiser que esta config WI seja a padrão selecionada ao criar uma credencial de segredo baseada em AWS. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */} +{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */} + +## Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI + +Navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**. + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `aws-prod-wi`. +- **Provider:** `AWS Secrets Manager`. +- **Authentication Method:** `Workload Identity` (em vez de chaves estáticas / AssumeRole). +- **Workload Identity Configuration:** selecione a config que você criou no Passo 6 (ex. `aws-prod`). +- (Opcional) Marque **Set as default credential for this provider**. + +O formulário pedirá apenas a **AWS Region** sob Workload Identity — os campos de credencial estática (Access Key ID, Secret Access Key, Role ARN, External ID) estão intencionalmente ocultos porque não se aplicam a este caminho; o ARN do role vem da config WI vinculada. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */} + +## Passo 8 — Testar a Conexão + +Depois de salvar a credencial, clique em **Test Connection**. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT, troca-o com o AWS STS via `sts:AssumeRoleWithWebIdentity` e confirma que as credenciais resultantes podem chamar `sts:GetCallerIdentity` contra o role assumido. Um resultado verde significa que o vínculo de federação está saudável. + +Um Test Connection bem-sucedido prova que a trust policy, o registro do provedor OIDC e a condição de audience estão todos conectados corretamente. Ele **não** prova que o IAM por segredo está correto — `secretsmanager:GetSecretValue` em um ARN de segredo específico é exercitado separadamente quando uma variável de ambiente é resolvida no kickoff. Veja [Solução de Problemas](#troubleshooting) para modos de falha de handshake. + +## Passo 9 — Referenciar o Segredo em uma Variável de Ambiente + +Agora referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para os campos do formulário e o comportamento. + +A única diferença entre env vars apoiadas por WI e por chaves estáticas é **quando** o segredo é lido: + +- **Apoiado por WI:** o valor do segredo é lido de forma fresca a cada kickoff de automação. +- **Apoiado por chaves estáticas:** o valor do segredo é lido no momento do deploy e incorporado à imagem do deployment. + +## Passo 10 — Verificar a Rotação + +Após o deployment estar rodando, rotacione o segredo na AWS: + +```bash +aws secretsmanager update-secret \ + --region \ + --secret-id crewai-test-keyword \ + --secret-string "rotated value" +``` + +Dispare um novo kickoff de automação. O ambiente do kickoff verá `"rotated value"` — sem novo deploy, sem reinício de worker, sem esperar TTL. + +Para confirmar nos logs (se você tiver acesso ao worker), procure por: + +``` +Workload identity config '' (aws): N secret(s) resolved +``` + +Esta linha aparece para cada kickoff e indica uma chamada `GetSecretValue` fresca contra a AWS. + +## Solução de Problemas + +| Sintoma | Causa provável | +|---|---| +| Test Connection falha com erro de handshake | A chamada `sts:AssumeRoleWithWebIdentity` foi rejeitada. Verifique se o ARN do principal federado da trust policy referencia `oidc-provider/` (host **sem** `https://` ou `http://`, sem barra final), se a condição de audience é exatamente `sts.amazonaws.com`, se a condição `sub` corresponde ao UUID da sua organização CrewAI e se a URL de discovery OIDC da plataforma é acessível a partir da AWS pela internet pública. | +| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | O AWS STS não consegue acessar o host da sua CrewAI Platform para buscar o JWKS. Confirme que o host é acessível pela internet a partir da AWS, que a URL de discovery OIDC retorna 200 e que o endpoint JWKS é acessível. | +| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | Trust policy incompatível. Reconfira o Passo 3: o ARN do principal federado deve incluir `oidc-provider/` (host **sem** `https://` ou `http://`, sem barra final), a condição de audience deve ser exatamente `sts.amazonaws.com` e a condição `sub` deve ser igual a `organization:`. | +| Autocomplete de Secret Name mostra `AccessDenied: secretsmanager:ListSecrets` | O role está sem `secretsmanager:ListSecrets` com `Resource: "*"`. Adicione a declaração `SecretsManagerListForUI` do Passo 4. | +| Kickoff falha ao resolver um segredo mesmo que o Test Connection passe | O vínculo WI está saudável, mas o IAM escopado por recurso está ausente no segredo que falha. Audite as permissões `secretsmanager:GetSecretValue` e `kms:Decrypt` do role para o ARN específico desse segredo e chave KMS. | +| `RegionDisabledException` / nenhum segredo encontrado | A região na Workload Identity Config não corresponde a onde o segredo vive. Reconfira o Passo 6. | +| Valor rotacionado não é pego no próximo kickoff | Confirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy. | + +### Links de Referência + +- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html) +- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html) +- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) + +## Próximos Passos + +- [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage) +- Para multi-cloud, veja também [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) e [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity). diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/aws.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/aws.mdx new file mode 100644 index 000000000..ca2d83836 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/aws.mdx @@ -0,0 +1,295 @@ +--- +title: AWS Secrets Manager (Credenciais Estáticas) +description: Configure o AWS Secrets Manager como provedor de segredos para a CrewAI Platform usando chaves de acesso estáticas ou AssumeRole +sidebarTitle: Com Credenciais Estáticas +icon: "key" +--- + +## Visão Geral + +Este guia o orienta na configuração do AWS Secrets Manager como provedor de segredos para sua organização na CrewAI Platform, usando **credenciais estáticas** (chaves de acesso, opcionalmente com AssumeRole). Ao final, a CrewAI Platform poderá ler segredos armazenados na sua conta AWS e injetá-los como valores de variáveis de ambiente em runtime. + + +Este guia cobre o caminho de **credenciais estáticas** — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação (sem novo deploy), veja [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity). + + + +Este guia cobre a configuração do lado da AWS e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage). + + +## Pré-requisitos + + +Antes de começar, certifique-se de que você tem: + +- Uma conta AWS com permissão para criar usuários IAM, políticas gerenciadas pelo cliente e (opcionalmente) papéis IAM. +- A região AWS onde seus segredos vivem (ou viverão), por exemplo `us-east-1`. +- Uma organização na CrewAI Platform onde seu usuário tem a permissão `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## Escolha um Método de Autenticação + +A CrewAI Platform suporta duas formas para que a plataforma se autentique no AWS Secrets Manager. Escolha uma antes de começar — os passos abaixo diferem dependendo do que você escolher. + +| Método | Quando usar | Trade-offs | +|---|---|---| +| **Chaves de acesso estáticas** | Começar rápido, deployments single-account | Configuração mais simples; chaves de acesso devem ser rotacionadas manualmente | +| **AssumeRole** | Cross-account, hardening de produção | Credenciais de curta duração; suporta External ID; requer papel IAM extra | + +O restante deste guia usa abas nos Passos 3–5 para que você possa seguir o caminho que corresponde à sua escolha. + +## Passo 1 — Criar um Usuário IAM + +Abra o [console IAM](https://console.aws.amazon.com/iam/), navegue até **Users**, depois clique em **Create user**. + +- Nome sugerido: `crewai-secrets-reader`. +- Deixe **Provide user access to the AWS Management Console** desmarcado — este principal é usado programaticamente pela CrewAI Platform, não por humanos. +- Clique em **Next**. + +Na página **Set permissions**, deixe a seleção padrão. Você anexará a política no Passo 3. + +Clique em **Next**, revise e clique em **Create user**. + +Para detalhes completos, veja a documentação da AWS: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html). + +{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */} + +## Passo 2 — Criar a Política IAM + +A CrewAI Platform precisa de acesso somente leitura ao AWS Secrets Manager e permissão para descriptografar segredos via KMS. Crie uma política gerenciada pelo cliente com o seguinte JSON. + +No console IAM, navegue até **Policies**, depois clique em **Create policy**. + +Escolha a aba **JSON** e substitua o conteúdo por: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "SecretsManagerRead", + "Effect": "Allow", + "Action": [ + "secretsmanager:ListSecrets", + "secretsmanager:GetSecretValue", + "secretsmanager:DescribeSecret" + ], + "Resource": "*" + }, + { + "Sid": "KMSDecrypt", + "Effect": "Allow", + "Action": [ + "kms:DescribeKey", + "kms:Decrypt" + ], + "Resource": "*" + } + ] +} +``` + +Clique em **Next**, então na página **Review and create**: + +- **Policy name:** `CrewAISecretsManagerRead` +- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform` + +Clique em **Create policy**. + + +A política acima concede `*` em `Resource` para simplicidade. Em produção, restrinja o `Resource` aos ARNs dos segredos específicos que a CrewAI Platform deve acessar e restrinja `kms:Decrypt` aos ARNs das chaves KMS específicas que criptografam esses segredos. Veja a [orientação da AWS sobre menor privilégio](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html). + + +{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */} +{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */} + +## Passo 3 — Anexar a Política + + + + 1. No console IAM, navegue até **Users** e clique no usuário que você criou no Passo 1. + 2. Na aba **Permissions**, clique em **Add permissions** → **Attach policies directly**. + 3. Procure por `CrewAISecretsManagerRead`, selecione-a e clique em **Next**. + 4. Clique em **Add permissions**. + + {/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */} + + + + Com AssumeRole, a política é anexada a um **role** IAM separado (não diretamente ao usuário). O usuário do Passo 1 só precisa de permissão para chamar `sts:AssumeRole` nesse role. + + **Criar o role:** + + 1. No console IAM, navegue até **Roles** e clique em **Create role**. + 2. **Trusted entity type:** AWS account. Escolha **This account** (ou **Another AWS account** para setups cross-account, depois informe o ID da conta AWS que hospeda o usuário IAM do Passo 1). + 3. (Recomendado) Marque **Require external ID** e digite um valor que você mesmo gera — este é um segredo compartilhado que você colará na CrewAI Platform no Passo 5. + 4. Clique em **Next**. + 5. Anexe a política `CrewAISecretsManagerRead`. + 6. Clique em **Next**, nomeie o role como `CrewAISecretsManagerRole` e clique em **Create role**. + + **Permitir que o usuário IAM assuma o role:** + + 1. Abra o role que você acabou de criar e copie seu **ARN**. + 2. No console IAM, navegue até **Users**, clique no usuário do Passo 1 e na aba **Permissions** clique em **Add permissions** → **Create inline policy**. + 3. Na aba **JSON**, cole o seguinte (substitua `ROLE_ARN_FROM_ABOVE`): + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "ROLE_ARN_FROM_ABOVE" + } + ] + } + ``` + + 4. Nomeie a política como `CrewAIAssumeSecretsRole` e clique em **Create policy**. + + {/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */} + {/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */} + + + +## Passo 4 — Obter Credenciais + + + + 1. No console IAM, abra o usuário do Passo 1. + 2. Clique na aba **Security credentials**. + 3. Em **Access keys**, clique em **Create access key**. + 4. Selecione **Application running outside AWS** (ou **Other**) como caso de uso. Clique em **Next**. + 5. (Opcional) Adicione uma tag de descrição. Clique em **Create access key**. + 6. Clique em **Show** para revelar a secret access key, então copie tanto o **Access key ID** quanto a **Secret access key**, ou clique em **Download .csv file**. + + + A secret access key é mostrada apenas uma vez. Se você fechar esta página sem copiá-la, precisará excluir a chave e criar uma nova. + + + Para detalhes completos, veja a documentação da AWS: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). + + {/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */} + {/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */} + + + + Mesmo com AssumeRole, a CrewAI Platform ainda precisa de uma chave de acesso para o usuário IAM — ela usa essas chaves como identidade chamadora para realizar a chamada `sts:AssumeRole`. + + 1. Crie uma access key para o usuário exatamente como descrito na aba **Chaves de acesso estáticas** acima. + 2. Abra o role que você criou no Passo 3 e copie: + - O **Role ARN** (do resumo do role). + - O **External ID** que você configurou (se houver) — você definiu isso no Passo 3, então certifique-se de tê-lo à mão. + + {/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */} + + + +## Passo 5 — Adicionar a Credencial na CrewAI Platform + +Na CrewAI Platform, navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} +{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */} + + + + Preencha o formulário: + + - **Name:** Um nome descritivo, ex. `aws-prod`. + - **Provider:** `AWS Secrets Manager`. + - **Region:** A região AWS onde seus segredos vivem, ex. `us-east-1`. Deve corresponder à região dos segredos que você quer ler. + - **Access Key ID:** O valor do Passo 4. + - **Secret Access Key:** O valor do Passo 4. + - (Opcional) Marque **Set as default credential for this provider**. A credencial padrão é usada por variáveis de ambiente que referenciam segredos AWS sem especificar uma credencial explicitamente. + + Deixe **Role ARN** e **External ID** em branco. + + Clique em **Create**. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */} + + + + Preencha o formulário: + + - **Name:** Um nome descritivo, ex. `aws-prod-assumerole`. + - **Provider:** `AWS Secrets Manager`. + - **Region:** A região AWS onde seus segredos vivem. + - **Access Key ID:** A access key do usuário IAM do Passo 4 (usada para chamar o STS). + - **Secret Access Key:** A secret access key do usuário IAM do Passo 4. + - **Role ARN:** O Role ARN que você copiou no Passo 4. + - **External ID:** O External ID que você definiu na trust policy do role (omita se não houver). + - (Opcional) Marque **Set as default credential for this provider**. + + Clique em **Create**. + + {/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */} + + + + +**Como os dois modos se comportam em runtime:** + +- Com apenas **chaves de acesso estáticas**, a CrewAI Platform chama o AWS Secrets Manager diretamente usando as chaves que você forneceu. +- Quando um **Role ARN** está definido, a CrewAI Platform primeiro chama `sts:AssumeRole` com as chaves de acesso fornecidas (e External ID se configurado), depois usa as credenciais de curta duração retornadas pelo STS para ler seus segredos. + + +{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */} + +## Passo 6 — Criar Pelo Menos Um Segredo na AWS + +Se você ainda não tem segredos no AWS Secrets Manager, crie um agora para que possa verificar a conexão no Passo 7. + +No [console do AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/), clique em **Store a new secret**. + +- **Secret type:** Escolha **Other type of secret**. +- **Key/value pairs** — ou: + - Informe um ou mais pares chave/valor (recomendado para segredos estruturados), ou + - Use a aba **Plaintext** para um único valor de string. +- **Encryption key:** Use `aws/secretsmanager` (a chave gerenciada pela AWS) a menos que você tenha um requisito específico de chave KMS. + +Clique em **Next**, então informe: + +- **Secret name:** Um nome único, ex. `crewai/openai-api-key`. +- **Description (optional):** Uma nota curta sobre o propósito do segredo. + +Clique em **Next** pelos passos de rotação e revisão, depois clique em **Store**. + + +**Sintaxe de referência por chave JSON.** Se você armazenar um segredo com múltiplos pares chave/valor (um objeto JSON), a CrewAI Platform pode extrair um campo específico usando a sintaxe `secret-name#json_key` em referências de variáveis de ambiente. Por exemplo, um segredo chamado `database-credentials` com `{"username": "...", "password": "..."}` pode ser referenciado como `database-credentials#password`. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para detalhes. + + +Para detalhes completos, veja a documentação da AWS: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html). + +{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */} +{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */} + +## Passo 7 — Testar a Conexão + +De volta à CrewAI Platform, na página **Secret Provider Credentials**, encontre a credencial que você acabou de criar e clique em **Test Connection**. + +Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar na AWS e ler segredos da sua conta. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */} + +Se o teste falhar, verifique as causas mais comuns: + +| Sintoma | Causa provável | +|---|---| +| `AccessDenied` em `secretsmanager:ListSecrets` | Política não anexada, ou usuário errado. Reconfira o Passo 3. | +| `AccessDenied` em `kms:Decrypt` | Falta a declaração `KMSDecrypt`, ou seus segredos usam uma chave KMS gerenciada pelo cliente não coberta por `Resource: "*"`. | +| `InvalidClientTokenId` / `SignatureDoesNotMatch` | Access key ID ou secret access key errados. Reconfira os Passos 4 e 5. | +| `RegionDisabledException` / nenhum segredo encontrado | A **Region** da credencial não corresponde a onde seus segredos realmente vivem. | +| `AccessDenied` em `sts:AssumeRole` (apenas AssumeRole) | Política inline `sts:AssumeRole` ausente no usuário IAM, ou a trust policy do role não permite este principal, ou o External ID não corresponde. | +| Teste passa imediatamente após criar o usuário IAM, mas falha da próxima vez | Credenciais IAM às vezes levam um ou dois minutos para se propagar globalmente. Tente novamente. | + +## Próximos Passos + +Agora que a AWS está conectada, vá para [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage) para: + +- Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager. +- Referenciar seus segredos AWS a partir de variáveis de ambiente da CrewAI Platform. + +Se você quiser segredos **conscientes de rotação** que se propagam sem novo deploy, mude para [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) — mesmo cofre de segredos, sem credenciais estáticas, segredos buscados por kickoff. diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/azure-workload-identity.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/azure-workload-identity.mdx new file mode 100644 index 000000000..ebdc97af6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/azure-workload-identity.mdx @@ -0,0 +1,275 @@ +--- +title: Azure Workload Identity Federation +description: Configure o Azure Key Vault via Microsoft Entra Workload Identity Federation para acesso a segredos consciente de rotação e sem credenciais +sidebarTitle: Com Workload Identity +icon: "id-badge" +--- + +## Visão Geral + +Este guia configura o Azure Key Vault como provedor de segredos usando **Microsoft Entra Workload Identity Federation**: a CrewAI Platform emite tokens OIDC de curta duração, os troca por um token de acesso do Entra via Microsoft identity platform e lê seus segredos — sem nenhum client secret armazenado em lugar algum. + + +**Por que este caminho:** os segredos são resolvidos no momento de execução da automação, então **valores rotacionados se propagam para o próximo kickoff sem novo deploy**. Se você só precisa de credenciais estáticas, veja o guia mais simples [Azure Key Vault — client secret](/pt-BR/enterprise/features/secrets-manager/azure). + + +### Como funciona em runtime + +1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform. +2. O worker apresenta o JWT ao Microsoft Entra em `https://login.microsoftonline.com//oauth2/v2.0/token` como um `client_assertion` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`), referenciando o App Registration cujo **Federated Identity Credential** corresponde ao issuer + subject do JWT. +3. O Entra valida o JWT contra o documento de discovery OIDC e JWKS da sua plataforma, então retorna um token de acesso de curta duração com escopo `https://vault.azure.net/.default`. +4. O worker chama o Azure Key Vault para ler o segredo. +5. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação. + +Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação. + +## Pré-requisitos + + +Antes de começar, certifique-se de que você tem: + +- A imagem do pod de automação deve incluir o runtime da CrewAI versão `1.14.5` ou superior. +- Uma subscription Azure e um tenant Microsoft Entra que você possa gerenciar. +- Permissão no tenant para criar App Registrations e adicionar Federated Identity Credentials. +- Um Key Vault usando **Azure RBAC** para autorização (não o modelo legado de access-policy). +- Uma organização na CrewAI Platform onde seu usuário tem as permissões `workload_identity_configs: manage` e `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac). +- **Sua instalação da CrewAI Platform deve ser acessível a partir do Microsoft Entra via HTTPS** para que o Entra possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet. + + +## Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform + +Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em `https:///.well-known/openid-configuration`. O campo `issuer` ali é a URL que o Microsoft Entra registrará como issuer de federação confiável. + +Abra a URL em um navegador: + +``` +https:///.well-known/openid-configuration +``` + +Você deverá ver um JSON contendo: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +Anote o valor exato de `issuer` — você o usará no Passo 3. + + +Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações `OIDC_PRIVATE_KEY` e `OIDC_ISSUER`. + + +## Passo 2 — Criar um App Registration + +No [portal Microsoft Entra](https://entra.microsoft.com), navegue até **App registrations** e clique em **New registration**. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- Deixe **Redirect URI** em branco. + +Clique em **Register**. Anote o **Application (client) ID** e o **Directory (tenant) ID** no blade de visão geral do App — você os usará no Passo 6. + +{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */} + +## Passo 3 — Adicionar um Federated Identity Credential + +O Federated Identity Credential diz ao Microsoft Entra: *confie em JWTs emitidos por este issuer, com este subject, quando forem apresentados como client assertion para este App Registration.* + +No App Registration, navegue até **Certificates & secrets** → **Federated credentials** → **Add credential**. + +- **Federated credential scenario:** `Other issuer`. +- **Issuer:** a URL do issuer da CrewAI Platform do Passo 1, ex. `https://`. +- **Subject identifier:** `organization:` — exatamente o valor da claim `sub` do JWT. Encontre o UUID da sua org nas configurações de organização da CrewAI Platform. Isso escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos. +- **Name:** qualquer label descritivo, ex. `crewai-org-prod`. +- **Audience:** `api://AzureADTokenExchange`. Esta é a audience fixa que o Microsoft Entra requer para federated credentials e é o que a CrewAI Platform define na claim `aud` do JWT. + +Clique em **Add**. + + +**Isolamento por organização.** O subject identifier (`organization:`) restringe o federated credential aos tokens de uma organização CrewAI específica. Se múltiplas organizações CrewAI devem compartilhar um App Registration, adicione um Federated Identity Credential por organização (cada um com o UUID da org). + + +Para detalhes completos, veja a documentação da Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust). + +{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */} + +## Passo 4 — Conceder ao App Registration Acesso ao Key Vault + +Conceda ao App Registration **Key Vault Secrets User** no vault de destino — o mesmo papel que você usaria para o caminho de credenciais estáticas. Use a nível de vault (mais simples) ou por segredo (menor privilégio). + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + O escopo a nível de vault concede a permissão `secrets/list` da qual o **autocomplete de Secret Name** no formulário de env-var da CrewAI Platform depende. Escolha esta aba se você quer que o autocomplete funcione. + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */} + + + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + Vínculos por segredo desabilitam o **autocomplete de Secret Name** no formulário de env-var da CrewAI Platform (o autocomplete requer `secrets/list`, que é escopado apenas por vault). Digite o nome completo do segredo. + + {/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */} + + + + Para uma atribuição **a nível de vault**: + + 1. Abra seu Key Vault no portal Azure. + 2. Clique em **Access control (IAM)** → **Add** → **Add role assignment**. + 3. Selecione o papel **Key Vault Secrets User** → **Next**. + 4. Clique em **Select members**, procure pelo App Registration `crewai-secrets-reader`, clique em **Select**. + 5. Clique em **Review + assign**. + + Para uma atribuição **por segredo**, use o mesmo fluxo, mas comece em **Objects** → **Secrets** → selecione o segredo → seu próprio painel **Access control (IAM)**. Vínculos por segredo desabilitam o autocomplete (veja a aba Por segredo acima). + + + +## Passo 5 — Criar Pelo Menos Um Segredo no Key Vault + +Se você ainda não tem um segredo para testar, crie um via Azure CLI: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + +Ou via portal Azure: + +1. Abra seu Key Vault e navegue até **Objects** → **Secrets**. +2. Clique em **Generate/Import**. +3. **Upload options:** `Manual`. **Name:** o nome do segredo (ex. `openai-api-key`). **Secret value:** cole o valor. +4. Clique em **Create**. + + +**Convenções de nome de segredo.** Nomes de segredos do Azure Key Vault não podem conter underscores. A CrewAI Platform converte automaticamente underscores em hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`), então você pode manter nomes de env-var no estilo underscore — mas o segredo subjacente no Key Vault deve usar hífens. + + +## Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform + +Na CrewAI Platform, navegue até **Settings** → **Workload Identity** e clique em **Add Workload Identity Config**. + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `azure-prod`. +- **Cloud Provider:** `Azure`. +- **Tenant ID:** seu **Directory (tenant) ID** do Microsoft Entra do Passo 2. +- **Client ID:** o **Application (client) ID** do seu App Registration do Passo 2. +- (Opcional) Marque **Set as default for Azure** se você quiser que esta seja a config WI padrão selecionada ao criar uma credencial de segredo baseada em Azure. + +A **Audience** é fixa em `api://AzureADTokenExchange` — o Microsoft Entra requer exatamente essa audience para federated credentials, então nenhum campo Audience é mostrado no formulário. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */} +{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */} + +## Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI + +Navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**. + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `azure-prod-wi`. +- **Provider:** `Azure Key Vault`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** selecione a config que você criou no Passo 6. +- **Key Vault URL:** o hostname DNS do vault, ex. `https://my-vault.vault.azure.net`. +- (Opcional) Marque **Set as default credential for this provider**. + +O formulário pedirá apenas a **Key Vault URL** sob Workload Identity — os campos de credencial estática (Tenant ID, Client ID, Client Secret) estão intencionalmente ocultos porque não se aplicam a este caminho; tenant + client vêm da config WI vinculada. + +Clique em **Create**. + + +**Um App Registration, muitos vaults.** A Key Vault URL fica na credencial, não na config WI. Então um App Registration (e uma config WI) pode servir múltiplos Key Vaults — basta criar uma Secret Provider Credential por vault, todas vinculadas à mesma config WI. + + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */} + +## Passo 8 — Testar a Conexão + +Depois de salvar a credencial, clique em **Test Connection**. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT, apresenta-o ao Microsoft Entra como um `client_assertion` federado, e confirma que o Entra retorna um token de acesso escopado para o vault. Um resultado verde significa que o vínculo de federação está saudável. + +Um Test Connection bem-sucedido prova que o issuer, subject e audience do Federated Identity Credential correspondem todos, e que o App Registration é acessível. Ele **não** prova que o RBAC por segredo do Key Vault está correto — `getSecret` contra um segredo específico é exercitado separadamente quando uma variável de ambiente é resolvida no kickoff. Veja [Solução de Problemas](#troubleshooting) para modos de falha de handshake. + +## Passo 9 — Referenciar o Segredo em uma Variável de Ambiente + +Referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para os campos do formulário e o comportamento. + +## Passo 10 — Verificar a Rotação + +Após o deployment estar rodando, rotacione o segredo no Key Vault: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "rotated value" +``` + +Dispare um novo kickoff de automação. O ambiente do kickoff verá `"rotated value"` — sem novo deploy, sem reinício de worker, sem espera de TTL. + +Para confirmar nos logs do worker, procure por: + +``` +Workload identity config '' (azure): N secret(s) resolved +``` + +Esta linha aparece para cada kickoff e indica uma chamada `getSecret` fresca contra o Azure Key Vault. + +Para uma verificação de ponta a ponta baseada em fingerprint, veja [Verificar Rotação de Ponta a Ponta](/pt-BR/enterprise/features/secrets-manager/verify-rotation). + +## Solução de Problemas + +| Sintoma | Causa provável | +|---|---| +| Test Connection falha com erro de handshake | O `client_assertion` federado foi rejeitado pelo Microsoft Entra. Verifique se o **Issuer** do Federated Identity Credential corresponde exatamente ao valor `issuer` da plataforma, se **Subject** é `organization:` (correspondendo à claim `sub` do JWT), se **Audience** é `api://AzureADTokenExchange` e se a URL de discovery OIDC da plataforma é acessível a partir do Entra pela internet pública. | +| `AADSTS70021: No matching federated identity record found for presented assertion` | O **Issuer** + **Subject** + **Audience** do Federated Identity Credential não correspondem todos exatamente ao JWT. Reconfira o Passo 3: subject deve ser `organization:` (correspondendo à claim `sub` do JWT), audience deve ser `api://AzureADTokenExchange`. | +| `AADSTS700024: Client assertion is not within its valid time range` | O relógio do host da CrewAI Platform está significativamente fora do tempo real. Verifique o NTP no host. | +| `AADSTS50013: Assertion failed signature validation` | O Microsoft Entra não conseguiu verificar a assinatura do JWT. Confirme que `https:///oauth2/jwks` é acessível pela internet pública e serve um JWKS válido. | +| Autocomplete de Secret Name mostra `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` | O papel **Key Vault Secrets User** do App Registration está escopado a um único segredo. Conceda o papel no escopo do vault para que a ação de plano de dados `list` seja permitida. Veja o Passo 4. | +| Kickoff falha ao resolver um segredo mesmo que o Test Connection passe | O vínculo WI está saudável, mas o RBAC por segredo do Key Vault está ausente no segredo que falha. Audite **Key Vault Secrets User** naquele segredo específico (ou estenda a atribuição de papel ao escopo do vault). | +| `Forbidden — request was not authorized` (vault usando access policies legadas) | O vault não foi alternado para Azure RBAC. Sob **Access configuration** do vault, defina o modelo de permissão para **Azure role-based access control** e reconceda o papel do Passo 4. | +| `azure_vault_url is required for Azure secret resolution` (logs do worker) | A Secret Provider Credential está sem a **Key Vault URL**. Reconfira o Passo 7. | +| Valor rotacionado não é pego no próximo kickoff | Confirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy. | + +### Links de Referência + +- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation) +- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust) +- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide) + +## Próximos Passos + +- [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage) +- Para multi-cloud, a configuração equivalente para AWS está em [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) e a equivalente para GCP em [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity). + +## Referência de Screenshots + +Os placeholders acima mapeiam para: + +- `01-register-app.png` — formulário "Register an application" do portal Azure preenchido com `crewai-secrets-reader`. +- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, com **Other issuer**, a URL do issuer da plataforma, subject `organization:`, audience `api://AzureADTokenExchange`. +- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, com **Key Vault Secrets User** e o App Registration selecionado. +- `04-per-secret-rbac.png` — mesmo formulário, mas no escopo IAM de um único segredo (caminho alternativo de menor privilégio). +- `05-amp-add-wi-config-azure.png` — formulário "Add Workload Identity Config" da CrewAI Platform com Cloud Provider = Azure, Tenant ID, Client ID preenchidos. +- `06-amp-wi-list-with-azure.png` — página de listagem do Workload Identity após criação, mostrando linhas para AWS, GCP e a nova config Azure. +- `07-amp-add-credential-azure-wi.png` — formulário "Add Secret Provider Credential" com Provider = Azure Key Vault, Auth = Workload Identity, a config WI escolhida e Key Vault URL preenchida. diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/azure.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/azure.mdx new file mode 100644 index 000000000..324858a29 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/azure.mdx @@ -0,0 +1,196 @@ +--- +title: Azure Key Vault +description: Configure o Azure Key Vault como provedor de segredos para a CrewAI Platform, de ponta a ponta +sidebarTitle: Com Credenciais Estáticas +icon: "key" +--- + +## Visão Geral + +Este guia o orienta na configuração do Azure Key Vault como provedor de segredos para sua organização na CrewAI Platform, usando um **Microsoft Entra App Registration com client secret**. Ao final, a CrewAI Platform poderá ler segredos armazenados no seu Azure Key Vault e injetá-los como valores de variáveis de ambiente em runtime. + + +Este guia cobre o caminho de **credenciais estáticas** — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação, veja [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity). + + + +Este guia cobre a configuração do lado Azure e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage). + + +## Pré-requisitos + + +Antes de começar, certifique-se de que você tem: + +- Uma subscription Azure com permissão para criar App Registrations no Microsoft Entra e para conceder atribuições de papéis em recursos do Key Vault. +- Um Key Vault usando **Azure RBAC** para autorização (não o modelo legado de access-policy). Se o seu vault ainda usa access policies, mude-o para RBAC sob o blade **Access configuration** do vault. +- Uma organização na CrewAI Platform onde seu usuário tem a permissão `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## Passo 1 — Criar um App Registration + +O App Registration é a identidade do lado Microsoft Entra como a qual a CrewAI Platform irá se autenticar. + +No [portal Microsoft Entra](https://entra.microsoft.com), navegue até **App registrations** e clique em **New registration**. + +- **Name:** `crewai-secrets-reader` +- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`. +- Deixe **Redirect URI** em branco. + +Clique em **Register**. Anote o **Application (client) ID** e o **Directory (tenant) ID** no blade de visão geral do App — você colará ambos na CrewAI Platform no Passo 4. + +Para detalhes completos, veja a documentação da Microsoft: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). + +{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */} + +## Passo 2 — Criar um Client Secret + +No App Registration, navegue até **Certificates & secrets** → **Client secrets** → **New client secret**. + +- **Description:** `crewai-platform` +- **Expires:** escolha uma duração que corresponda à sua política de rotação (a Microsoft limita isso em 24 meses). + +Clique em **Add**. Copie a coluna **Value** imediatamente — ela nunca pode ser re-exibida depois que você sair da página. + + +Client secrets são credenciais estáticas de longa duração. Armazene o valor com segurança (em um gerenciador de senhas ou no seu próprio cofre de segredos) e rotacione-o antes da expiração. Para eliminar credenciais estáticas completamente, use [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity). + + +{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */} + +## Passo 3 — Conceder ao App Registration Acesso ao Key Vault + +A CrewAI Platform precisa de acesso de leitura aos segredos no seu Key Vault. Use um de dois escopos — **a nível de vault** para simplicidade, ou **por segredo** para menor privilégio. + + + + No [console do Key Vault](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults), abra o vault de destino, depois navegue até **Access control (IAM)** → **Add** → **Add role assignment**. + + - **Role:** **Key Vault Secrets User** + - **Assign access to:** User, group, or service principal + - **Members:** procure e selecione seu App Registration (`crewai-secrets-reader`). + + Clique em **Review + assign**. + + Ou via Azure CLI: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault show --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */} + + + + Conceda o papel a nível de um segredo individual. Repita para cada segredo que a CrewAI Platform deve acessar: + + ```bash + az role assignment create \ + --assignee \ + --role "Key Vault Secrets User" \ + --scope $(az keyvault secret show --vault-name --name --query id -o tsv) + ``` + + {/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */} + + + + +O papel **Key Vault Secrets User** permite ler valores de segredos, mas não listar todos os segredos no vault. O autocomplete de nome de segredo da CrewAI Platform também chama `list` — essa permissão está incluída no papel no escopo de vault, mas **não** no escopo por segredo. Com vínculos por segredo, o autocomplete não sugerirá segredos; digite o nome completo do segredo. + + +## Passo 4 — Adicionar a Credencial na CrewAI Platform + +Na CrewAI Platform, navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `azure-prod`. +- **Provider:** `Azure Key Vault`. +- **Key Vault URL:** o hostname DNS do vault, ex. `https://my-vault.vault.azure.net`. +- **Tenant ID:** seu **Directory (tenant) ID** do Microsoft Entra do Passo 1. +- **Client ID:** o **Application (client) ID** do seu App Registration do Passo 1. +- **Client Secret:** o **Value** que você copiou no Passo 2. +- (Opcional) Marque **Set as default credential for this provider**. A credencial padrão é usada por variáveis de ambiente que referenciam segredos Azure sem especificar uma credencial explicitamente. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */} + +## Passo 5 — Criar Pelo Menos Um Segredo no Azure Key Vault + +Se você ainda não tem segredos no Key Vault, crie um agora para que possa verificar a conexão no Passo 6. + +No console do Key Vault, navegue até **Objects** → **Secrets** → **Generate/Import**. + +- **Upload options:** `Manual` +- **Name:** ex. `openai-api-key` +- **Secret value:** cole o valor do seu segredo +- Deixe o resto nos padrões. + +Clique em **Create**. + +Ou via Azure CLI: + +```bash +az keyvault secret set \ + --vault-name \ + --name openai-api-key \ + --value "sk-your-actual-key" +``` + + +**Convenções de nome de segredo.** Nomes de segredos do Azure Key Vault não podem conter underscores. A CrewAI Platform converte automaticamente underscores em hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`), então você pode manter nomes de env-var no estilo underscore — mas o segredo subjacente no Key Vault deve usar hífens. + + + +**Sintaxe de referência por chave JSON.** O Key Vault trata valores de segredos como strings opacas. Se o valor do seu segredo for um objeto JSON, a CrewAI Platform pode extrair um único campo usando a sintaxe `secret-name#json_key` (ex. `database-credentials#password`). Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para detalhes. + + +Para detalhes completos, veja a documentação da Microsoft: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli). + +{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */} + +## Passo 6 — Testar a Conexão + +De volta à CrewAI Platform, na página **Secret Provider Credentials**, encontre a credencial que você acabou de criar e clique em **Test Connection**. + +Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar no Microsoft Entra e ler segredos do seu vault. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */} + +Se o teste falhar, verifique as causas mais comuns: + +| Sintoma | Causa provável | +|---|---| +| `AADSTS7000215: Invalid client secret provided` | O **Client Secret** colado está errado ou expirado. Recrie o segredo (Passo 2) e atualize a credencial. | +| `AADSTS700016: Application not found in the directory` | O **Tenant ID** ou **Client ID** não corresponde ao App Registration. Reconfira o Passo 4. | +| `Forbidden — caller does not have permission` | O App Registration está sem o papel **Key Vault Secrets User** no vault (ou por segredo). Reconfira o Passo 3. | +| `Vault not found` / erros de DNS | A **Key Vault URL** está errada, ou seu vault tem endpoints privados que bloqueiam acesso público. Confirme que o host responde a `curl https://.vault.azure.net/secrets?api-version=7.4`. | +| `Forbidden — request was not authorized` (vault usando access policies legadas) | O vault não foi alternado para Azure RBAC. Sob **Access configuration** do vault, defina o modelo de permissão para **Azure role-based access control** e reconceda o papel do Passo 3. | + +## Próximos Passos + +Agora que o Azure Key Vault está conectado, vá para [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage) para: + +- Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager. +- Referenciar seus segredos Azure a partir de variáveis de ambiente da CrewAI Platform. + +Se você quiser segredos **conscientes de rotação** que se propagam sem novo deploy, mude para [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity) — mesmo vault, sem client secret para rotacionar, segredos buscados por kickoff. + +## Referência de Screenshots + +Os placeholders acima mapeiam para: + +- `01-register-app.png` — formulário "Register an application" do portal Azure preenchido com `crewai-secrets-reader`. +- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, com a linha do segredo recém-criado visível (coluna Value destacada antes de ser mascarada). +- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, com **Key Vault Secrets User** escolhido e o App Registration selecionado como membro. +- `04-per-secret-rbac.png` — mesmo painel, mas escopado para um único recurso de segredo (caminho alternativo de menor privilégio). +- `05-amp-add-credential-form-azure.png` — formulário "Add Secret Provider Credential" da CrewAI Platform: Provider = Azure Key Vault, todos os cinco campos preenchidos. +- `06-create-secret.png` — painel "Create a secret" do Azure Key Vault com `openai-api-key` e um valor colado. +- `07-test-connection-success.png` — toast de sucesso / estado da linha na CrewAI Platform após clicar em **Test Connection** na credencial. diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity.mdx new file mode 100644 index 000000000..dcbe9670c --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity.mdx @@ -0,0 +1,273 @@ +--- +title: GCP Workload Identity Federation +description: Configure o Google Cloud Secret Manager via Workload Identity Federation para acesso a segredos consciente de rotação e sem credenciais +sidebarTitle: Com Workload Identity +icon: "id-badge" +--- + +## Visão Geral + +Este guia configura o Google Cloud Secret Manager como provedor de segredos usando **Workload Identity Federation**: a CrewAI Platform emite tokens OIDC de curta duração, os troca por credenciais Google Cloud via Security Token Service e lê seus segredos — sem que uma chave de service account de longa duração seja armazenada em lugar algum. + + +**Por que este caminho:** os segredos são resolvidos no momento de execução da automação, então **valores rotacionados se propagam para o próximo kickoff sem novo deploy**. Se você só precisa de credenciais estáticas, veja o guia mais simples [GCP — chave de service account](/pt-BR/enterprise/features/secrets-manager/gcp). + + +### Como funciona em runtime + +1. O worker do deployment solicita um JWT OIDC fresco à CrewAI Platform. +2. O worker troca o JWT por uma credencial Google federada via [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest), referenciando o Workload Identity Pool Provider que você configurou abaixo. +3. O worker chama `secretmanager.googleapis.com:accessSecretVersion` para ler o segredo, usando a credencial federada diretamente (o principal federado detém `roles/secretmanager.secretAccessor` — veja Passo 4). +4. O valor obtido é injetado como valor da variável de ambiente para aquele kickoff de automação. + +Tokens OIDC subject são cacheados por ~1 hora para evitar reemissão a cada kickoff. Valores de segredos são buscados frescos a cada kickoff independentemente do estado do cache OIDC, e é isso que torna este caminho consciente de rotação. + +## Pré-requisitos + + +Antes de começar, certifique-se de que você tem: + +- A imagem do pod de automação deve incluir o runtime da CrewAI versão `1.14.5` ou superior. +- Um projeto Google Cloud com as APIs **Secret Manager**, **Security Token Service** e **IAM Credentials** habilitadas. Habilite-as via console ou: + + ```bash + gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \ + --project= + ``` + +- Permissão no projeto para criar Workload Identity Pools, papéis IAM, service accounts e (se necessário) segredos. +- Uma organização na CrewAI Platform onde seu usuário tem as permissões `workload_identity_configs: manage` e `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac). +- **Sua instalação da CrewAI Platform deve ser acessível a partir do Google Cloud via HTTPS** para que o GCP STS possa buscar o documento de discovery OIDC e o JWKS durante a validação do token. Confirme com o administrador da sua plataforma que o host é acessível pela internet. + + +## Passo 1 — Encontre a URL do Issuer OIDC da Sua CrewAI Platform + +Sua instalação da CrewAI Platform publica um documento de discovery OpenID Connect em `https:///.well-known/openid-configuration`. O campo `issuer` ali é a URL que o Google registrará como provedor OIDC confiável. + +Abra a URL em um navegador: + +``` +https:///.well-known/openid-configuration +``` + +Você deverá ver um JSON contendo: + +```json +{ + "issuer": "https://", + "jwks_uri": "https:///oauth2/jwks", + ... +} +``` + +Anote o valor exato de `issuer` — você o usará no Passo 3. + + +Se a URL retornar 404 ou 503, contate o administrador da sua plataforma. O issuer OIDC requer uma chave de assinatura privada configurada no momento da instalação. Veja o guia de instalação da plataforma para as configurações `OIDC_PRIVATE_KEY` e `OIDC_ISSUER`. + + +## Passo 2 — Criar um Workload Identity Pool + +Um Workload Identity Pool é um container do lado Google Cloud para identidades externas confiáveis. Você registrará a CrewAI Platform como um provedor dentro desse pool. + +```bash +gcloud iam workload-identity-pools create crewai-pool \ + --project= \ + --location=global \ + --display-name="CrewAI Platform" +``` + +Ou no [console Workload Identity Pools](https://console.cloud.google.com/iam-admin/workload-identity-pools), clique em **Create Pool**. + +{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */} + +## Passo 3 — Adicionar a CrewAI Platform como um Provedor OIDC no Pool + +```bash +gcloud iam workload-identity-pools providers create-oidc crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --display-name="CrewAI Platform OIDC" \ + --issuer-uri="https://" \ + --attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \ + --attribute-condition="assertion.organization_id != ''" +``` + +O `--attribute-mapping` diz ao Google como mapear claims do JWT para atributos do Google: +- `google.subject` é o identificador do principal — mapeamos para a claim `sub` do JWT, que a CrewAI Platform define como `organization:`. +- `attribute.organization` é um atributo customizado — mapeamos para a claim `organization_id` do JWT para que você possa referenciá-la em vínculos IAM mais tarde. + +O `--attribute-condition` é uma verificação de defesa em profundidade que rejeita tokens sem uma claim `organization_id`. + +Obtenha o **nome do recurso do provedor** (você precisará dele para a audience e vínculos IAM): + +```bash +gcloud iam workload-identity-pools providers describe crewai-provider \ + --project= \ + --location=global \ + --workload-identity-pool=crewai-pool \ + --format="value(name)" +``` + +A saída se parece com: + +``` +projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider +``` + +Este é seu valor de **Workload Identity Provider** para a CrewAI Platform no Passo 6. A CrewAI Platform automaticamente computa a audience OIDC como `//iam.googleapis.com/` ao emitir tokens. + +{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */} + +## Passo 4 — Conceder Acesso ao Secret Manager ao Principal Federado + +Vincule ambos os papéis do Secret Manager no escopo do projeto ao principal federado — um papel habilita o autocomplete de Secret Name no formulário de env-var, o outro permite ler valores de segredos no kickoff da automação. Ambos são necessários para que o recurso funcione de ponta a ponta. + +```bash +PRINCIPAL_SET="principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools/crewai-pool/attribute.organization/" + +# Necessário para o autocomplete de Secret Name (chama secretmanager.secrets.list) +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.viewer" + +# Necessário para ler valores de segredos no kickoff +gcloud projects add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" +``` + +Substitua `` pelo número numérico do projeto (`gcloud projects describe --format='value(projectNumber)'`) e `` pelo UUID da organização CrewAI Platform que deve ter permissão para ler seus segredos. Você pode encontrar o UUID da org na UI da plataforma na página de configurações da organização, ou via API. Isso escopa a federação a uma organização CrewAI específica — apenas tokens emitidos para as automações dessa org são aceitos. + +Ou via console Google Cloud: + +1. Abra **IAM & Admin** → **IAM** do seu projeto. +2. Clique em **GRANT ACCESS**. +3. **New principals:** cole a string completa `principalSet://...attribute.organization/`. +4. Atribua o papel **Secret Manager Viewer** (`roles/secretmanager.viewer`). +5. Clique em **SAVE**. +6. Clique em **GRANT ACCESS** novamente e repita com o papel **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + +**Isolamento por organização.** O padrão `principalSet://...attribute.organization/` restringe o acesso aos tokens de uma organização específica. Se você tiver várias organizações CrewAI compartilhando um projeto Google Cloud, repita ambos os vínculos por organização com o UUID correto — ou use uma condição de atributo menos restritiva se o isolamento não for necessário. + + + +**Escopando `secretAccessor` por segredo (opcional).** Se você preferir não conceder `roles/secretmanager.secretAccessor` em nível de projeto, omita o segundo vínculo acima e vincule por segredo: + +```bash +gcloud secrets add-iam-policy-binding \ + --member="$PRINCIPAL_SET" \ + --role="roles/secretmanager.secretAccessor" \ + --project= +``` + +Mantenha `roles/secretmanager.viewer` no escopo de projeto de qualquer forma — `secretmanager.secrets.list` (do qual o autocomplete depende) não pode ser concedido por segredo. + + +## Passo 5 — Criar Pelo Menos Um Segredo no GCP + +Se você ainda não tem um segredo para testar, crie um via CLI `gcloud`: + +```bash +echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \ + --data-file=- \ + --project= \ + --replication-policy=automatic +``` + +Ou via [console Secret Manager](https://console.cloud.google.com/security/secret-manager): + +1. Abra **Secret Manager** no seu projeto GCP. +2. Clique em **+ CREATE SECRET**. +3. **Name:** `crewai-test-keyword`. **Secret value:** cole seu valor. +4. Clique em **CREATE SECRET**. + +## Passo 6 — Adicionar uma Configuração de Workload Identity na CrewAI Platform + +Na CrewAI Platform, navegue até **Settings** → **Workload Identity** e clique em **Add Workload Identity Config**. + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `gcp-prod`. +- **Cloud Provider:** `GCP`. +- **Workload Identity Provider:** o nome do recurso do provedor do Passo 3, ex. `projects//locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`. +- (Opcional) Alterne **Default Configuration** se você quiser que esta seja a config WI padrão selecionada ao criar uma credencial de segredo baseada em GCP. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */} +{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */} + +## Passo 7 — Adicionar uma Credencial de Provedor de Segredos Vinculada à Config WI + +Navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**. + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `gcp-prod-wi`. +- **Provider:** `Google Cloud Secret Manager`. +- **Authentication Method:** `Workload Identity`. +- **Workload Identity Configuration:** selecione a config que você criou no Passo 6. +- **Project ID:** o ID do seu projeto GCP (o mesmo projeto dono dos segredos). +- (Opcional) Marque **Set as default credential for this provider**. + +O formulário pedirá apenas o **Project ID** sob Workload Identity — o campo **Service Account JSON** está intencionalmente oculto porque não se aplica a este caminho; a identidade federada vem da config WI vinculada. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */} + +## Passo 8 — Testar a Conexão + +Depois de salvar a credencial, clique em **Test Connection**. Para credenciais workload-identity isso verifica o handshake OIDC: a CrewAI Platform emite um JWT e o troca via Security Token Service por um token de acesso Google federado. Um resultado verde significa que o vínculo de federação está saudável. + +Um Test Connection bem-sucedido prova que o Workload Identity Pool, provedor OIDC, mapeamento de atributos e condição de atributo estão todos conectados corretamente. Ele **não** prova que o IAM do Secret Manager está correto — `secretmanager.secrets.list` e `secretmanager.versions.access` são exercitados separadamente quando o autocomplete de Secret Name carrega ou quando uma variável de ambiente é resolvida no kickoff. Veja [Solução de Problemas](#troubleshooting) para modos de falha de handshake. + +## Passo 9 — Referenciar o Segredo em uma Variável de Ambiente + +Referencie o segredo em uma automação, exatamente como você faria para qualquer outra env var apoiada pelo Secrets Manager. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para os campos do formulário e o comportamento. + +## Passo 10 — Verificar a Rotação + +Após o deployment estar rodando, rotacione o segredo no GCP adicionando uma nova versão (o Secret Manager sempre lê a versão habilitada mais recente por padrão): + +```bash +echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \ + --data-file=- \ + --project= +``` + +Dispare um novo kickoff de automação. O ambiente do kickoff verá `"rotated value"` — sem novo deploy, sem reinício de worker, sem espera de TTL. + +Para confirmar nos logs do worker, procure por: + +``` +Workload identity config '' (gcp): N secret(s) resolved +``` + +Esta linha aparece para cada kickoff e indica uma chamada `accessSecretVersion` fresca contra o GCP. + +## Solução de Problemas + +| Sintoma | Causa provável | +|---|---| +| Test Connection falha com erro de handshake | A troca de tokens STS foi rejeitada. Verifique se o Workload Identity Pool existe, se o issuer do provedor OIDC corresponde ao valor `issuer` da plataforma e se a condição de atributo aceita as claims do JWT. Confirme que a URL de discovery OIDC da plataforma é acessível a partir do GCP pela internet pública. | +| `Could not refresh access token: invalid_target` | A claim de audience não corresponde à audience esperada do Workload Identity Provider. A CrewAI Platform define a audience automaticamente; se você a customizou, certifique-se de que corresponde a `//iam.googleapis.com/`. | +| `Failed to fetch JWKS from issuer` | O GCP STS não consegue acessar o host da sua CrewAI Platform. Confirme que o host é acessível pela internet e que `/.well-known/openid-configuration` retorna 200. | +| `Attribute condition rejected token` | A condição de atributo do provedor OIDC (Passo 3) requer `organization_id`. A CrewAI Platform sempre define essa claim, então isso geralmente significa um pool/provedor mal configurado. Reconfira a condição de atributo do provedor. | +| Autocomplete de Secret Name mostra `PERMISSION_DENIED: secretmanager.secrets.list` | O principal federado está sem `roles/secretmanager.viewer` no escopo de projeto. A permissão `secretmanager.secrets.list` é escopada apenas por projeto e não pode ser concedida por segredo. Veja o Passo 4. | +| Kickoff falha ao resolver um segredo mesmo que o Test Connection passe | O vínculo WI está saudável, mas `secretmanager.versions.access` está ausente no segredo que falha. Audite `roles/secretmanager.secretAccessor` (escopado por projeto, ou por segredo se você escopou dessa forma no Passo 4). | +| Valor rotacionado não é pego no próximo kickoff | Confirme que a env var na automação está referenciando uma credencial baseada em Workload Identity (não uma credencial de chaves estáticas). O caminho estático incorpora valores à imagem do deploy. | + +### Links de Referência + +- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation) +- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) +- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control) + +## Próximos Passos + +- [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage) +- Para multi-cloud, veja também [AWS Workload Identity (Federação OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) e [Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity). diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp.mdx new file mode 100644 index 000000000..f5cca5fcf --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/gcp.mdx @@ -0,0 +1,189 @@ +--- +title: Google Cloud Secret Manager +description: Configure o Google Cloud Secret Manager como provedor de segredos para a CrewAI Platform, de ponta a ponta +sidebarTitle: Com Credenciais Estáticas +icon: "key" +--- + +## Visão Geral + +Este guia o orienta na configuração do Google Cloud Secret Manager como provedor de segredos para sua organização na CrewAI Platform, usando **credenciais de service account**. Ao final, a CrewAI Platform poderá ler segredos armazenados no seu projeto Google Cloud e injetá-los como valores de variáveis de ambiente em runtime. + + +Este guia cobre o caminho de **credenciais estáticas** — segredos são resolvidos no momento do deploy e incorporados à imagem do deployment. Valores rotacionados exigem um novo deploy. Se você quiser segredos conscientes de rotação que se atualizam a cada kickoff de automação, veja [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity). + + + +Este guia cobre a configuração do lado GCP e a configuração da credencial na CrewAI Platform. Para então referenciar um segredo a partir de uma variável de ambiente, veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage). + + +## Pré-requisitos + + +Antes de começar, certifique-se de que você tem: + +- Um projeto Google Cloud com a **Secret Manager API** habilitada. Habilite-a no [console APIs & Services](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com) ou via `gcloud`: + + ```bash + gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID + ``` + +- Permissão no projeto para criar service accounts, conceder papéis IAM e (se necessário) criar segredos. +- Uma organização na CrewAI Platform onde seu usuário tem a permissão `secret_providers: manage`. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac). + + +## Passo 1 — Criar uma Service Account + +Uma service account é a identidade do lado GCP como a qual a CrewAI Platform irá se autenticar. + +No [console IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts), clique em **Create Service Account**. + +- **Service account name:** `crewai-secrets-reader` +- **Service account ID:** preenchido automaticamente a partir do nome (ex. `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`) +- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform" + +Clique em **Create and Continue**. Pule as concessões opcionais nesta tela — você anexará o papel no Passo 2. Clique em **Done**. + +Para detalhes completos, veja a documentação GCP: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create). + +{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */} + +## Passo 2 — Conceder Acesso ao Secret Manager + +A CrewAI Platform precisa de permissão para listar e ler segredos no seu projeto. Use um de dois escopos — **a nível de projeto** para simplicidade ou **por segredo** para menor privilégio. + + + + No [console IAM](https://console.cloud.google.com/iam-admin/iam), clique em **Grant Access** e: + + - **New principals:** o email da service account do Passo 1. + - **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`). + + Clique em **Save**. + + Ou via `gcloud`: + + ```bash + gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" + ``` + + {/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */} + + + + Conceda o papel apenas nos segredos específicos que a CrewAI Platform deve acessar. Repita para cada segredo: + + ```bash + gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \ + --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/secretmanager.secretAccessor" \ + --project=YOUR_PROJECT_ID + ``` + + Ou no console: abra cada segredo no [Secret Manager](https://console.cloud.google.com/security/secret-manager), clique em **Permissions** no painel à direita e conceda **Secret Manager Secret Accessor** à service account. + + {/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */} + + + + +O papel `roles/secretmanager.secretAccessor` concede acesso somente leitura aos valores de segredos. A CrewAI Platform também chama `secretmanager.secrets.list` para a experiência de autocomplete no formulário de env-var — essa permissão está incluída no papel no escopo de projeto, mas **não** no escopo por segredo. Com vínculos por segredo, o autocomplete não sugerirá segredos; você precisará digitar o nome completo do segredo. + + +## Passo 3 — Criar uma Chave de Service Account + +Abra a service account do Passo 1 no [console IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts). + +- Clique na aba **Keys**. +- Clique em **Add Key** → **Create new key**. +- **Key type:** JSON. +- Clique em **Create**. O navegador baixa um arquivo JSON — mantenha-o seguro; não pode ser baixado novamente. + +Ou via `gcloud`: + +```bash +gcloud iam service-accounts keys create ./crewai-secrets-reader.json \ + --iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com +``` + + +A chave de service account é uma credencial estática de longa duração. Armazene-a com segurança (em um gerenciador de senhas ou no seu próprio cofre de segredos) e rotacione-a em uma cadência regular. Para eliminar credenciais estáticas completamente, use [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity). + + +{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */} + +## Passo 4 — Adicionar a Credencial na CrewAI Platform + +Na CrewAI Platform, navegue até **Settings** → **Secret Provider Credentials** e clique em **Add Credential**. + +{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */} + +Preencha o formulário: + +- **Name:** Um nome descritivo, ex. `gcp-prod`. +- **Provider:** `Google Cloud Secret Manager`. +- **Project ID:** O ID do seu projeto GCP (ex. `my-crewai-prod`). +- **Service Account JSON:** Cole o conteúdo inteiro do arquivo JSON que você baixou no Passo 3. +- (Opcional) Marque **Set as default credential for this provider**. A credencial padrão é usada por variáveis de ambiente que referenciam segredos GCP sem especificar uma credencial explicitamente. + +Clique em **Create**. + +{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */} + +## Passo 5 — Criar Pelo Menos Um Segredo no GCP + +Se você ainda não tem segredos no GCP Secret Manager, crie um agora para que possa verificar a conexão no Passo 6. + +No [console Secret Manager](https://console.cloud.google.com/security/secret-manager), clique em **Create secret**. + +- **Name:** Um nome único, ex. `openai-api-key`. +- **Secret value:** Cole um valor bruto ou faça upload de um arquivo. +- Deixe as configurações de rotação, replicação e outras em seus padrões a menos que tenha um requisito específico. + +Clique em **Create secret**. + +Ou via `gcloud`: + +```bash +echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \ + --data-file=- \ + --project=YOUR_PROJECT_ID \ + --replication-policy=automatic +``` + + +**Sintaxe de referência por chave JSON.** O GCP Secret Manager trata valores de segredos como blobs opacos. Se o valor do seu segredo for uma string JSON, a CrewAI Platform pode extrair um único campo usando a sintaxe `secret-name#json_key` (ex. `database-credentials#password`). Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) para detalhes. + + +Para detalhes completos, veja a documentação GCP: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart). + +{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */} + +## Passo 6 — Testar a Conexão + +De volta à CrewAI Platform, na página **Secret Provider Credentials**, encontre a credencial que você acabou de criar e clique em **Test Connection**. + +Um toast de sucesso confirma que a CrewAI Platform consegue se autenticar no GCP e ler segredos do seu projeto. + +{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */} + +Se o teste falhar, verifique as causas mais comuns: + +| Sintoma | Causa provável | +|---|---| +| `PERMISSION_DENIED` ao listar segredos | A service account está sem `roles/secretmanager.secretAccessor`, ou você escopou por segredo (`list` não é concedido). Reconfira o Passo 2. | +| `PERMISSION_DENIED` em `secretmanager.secrets.access` | Mesmo que acima, mas para um segredo específico. Confirme que a service account tem o papel accessor no segredo em questão. | +| `unauthorized_client` / `invalid_grant` | O JSON de Service Account colado é inválido, expirado ou pertence a uma service account excluída. Recrie a chave (Passo 3) e cole novamente. | +| `Project ID does not match` | O campo Project ID na CrewAI Platform não corresponde ao projeto dono da service account / segredos. Reconfira o Passo 4. | +| `API not enabled` | Secret Manager API não está habilitada no projeto. Veja Pré-requisitos. | + +## Próximos Passos + +Agora que o GCP está conectado, vá para [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage) para: + +- Conceder aos membros da organização as permissões corretas para usar (ou gerenciar) o Secrets Manager. +- Referenciar seus segredos GCP a partir de variáveis de ambiente da CrewAI Platform. + +Se você quiser segredos **conscientes de rotação** que se propagam sem novo deploy, mude para [GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) — mesmo cofre de segredos, sem credenciais estáticas, segredos buscados por kickoff. diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/overview.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/overview.mdx new file mode 100644 index 000000000..e09d97bd5 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/overview.mdx @@ -0,0 +1,96 @@ +--- +title: Visão Geral do Secrets Manager +description: Conecte cofres de segredos externos à CrewAI Platform e referencie segredos gerenciados a partir de variáveis de ambiente +sidebarTitle: Visão Geral +icon: "book-open" +--- + +## Visão Geral + +O recurso Secrets Manager permite que sua organização conecte um cofre de segredos externo — AWS Secrets Manager, Google Cloud Secret Manager ou Azure Key Vault — e referencie esses segredos diretamente a partir de variáveis de ambiente nas suas automações e crews. Em vez de colar valores em texto puro na plataforma, você armazena um conjunto de credenciais por provedor e se refere aos segredos pelo nome. + +Isso oferece a você: + +- **Armazenamento centralizado** — gerencie segredos no seu provedor em vez de editar a configuração da CrewAI Platform. A CrewAI Platform não mantém nenhuma cópia em texto puro do valor do segredo. +- **Exposição reduzida** — valores sensíveis nunca ficam em texto puro na sua configuração da CrewAI Platform. +- **Auditabilidade cloud-native** — o log de auditoria do seu provedor registra cada leitura de segredo. + + +O Secrets Manager (tanto o caminho de credenciais estáticas quanto o de Workload Identity) requer o runtime da CrewAI versão `1.14.5` ou superior na imagem do pod de automação. + + +## Dois Caminhos: Credenciais Estáticas vs Workload Identity + +Existem duas formas de conectar a CrewAI Platform ao cofre de segredos da sua nuvem. **Eles diferem significativamente no comportamento de rotação**, então escolha com base em quão frequentemente seus segredos são rotacionados e quão rigorosa é a sua postura de segurança. + +| Aspecto | Credenciais Estáticas | Workload Identity (Federação OIDC) | +|---|---|---| +| **Autenticação** | Chaves de acesso de longa duração / JSON de service account armazenados na CrewAI Platform | Tokens de curta duração emitidos por processo worker; nenhuma credencial estática armazenada em lugar algum | +| **Propagação de rotação** | Resolvida no momento do deploy e **incorporada à imagem do contêiner do deployment** — valores rotacionados exigem um novo deploy | Resolvida no **momento da execução da automação** — valores rotacionados se propagam para o próximo kickoff sem novo deploy | +| **Esforço de configuração** | Menor — cole chaves / faça upload do JSON da service account | Maior — registre a CrewAI Platform como um provedor OIDC na sua nuvem, configure políticas de confiança | +| **Melhor para** | Começar rápido, segredos rotacionados raramente, deployments single-account | Produção, segredos rotacionados frequentemente, ambientes guiados por compliance que proíbem credenciais de longa duração | + + +**Ambos os caminhos usam o mesmo fluxo de UI** para referenciar segredos em variáveis de ambiente (veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage)). A diferença está inteiramente em como a plataforma se autentica na sua nuvem e em quando lê o valor do segredo. + + +### Escolha seu guia de configuração + +| Provedor | Credenciais Estáticas | Workload Identity | +|---|---|---| +| AWS Secrets Manager | [AWS — chaves estáticas / AssumeRole](/pt-BR/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) | +| Google Cloud Secret Manager | [GCP — chave de service account](/pt-BR/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) | +| Azure Key Vault | [Azure — client secret](/pt-BR/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity) | + + +As interfaces de Secrets Manager e Workload Identity estão atualmente marcadas como **Beta** na CrewAI Platform. + + +## Como Tudo se Encaixa + +Configurar o Secrets Manager é um fluxo de três passos que envolve tanto o seu provedor de nuvem quanto a CrewAI Platform: + +1. **Um admin configura uma credencial de provedor.** Este é o trabalho do lado da nuvem — e o trabalho difere dependendo de qual caminho (credenciais estáticas ou Workload Identity) você escolher. Os guias específicos por provedor cobrem isso de ponta a ponta. +2. **Um admin (ou um membro autorizado) referencia um segredo em uma variável de ambiente.** Na página de Variáveis de Ambiente, o usuário escolhe uma credencial de provedor e seleciona o nome do segredo. Veja [Usando o Secrets Manager](/pt-BR/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables). +3. **A automação recebe o valor resolvido em runtime.** Quando um crew ou automação executa, a CrewAI Platform busca o segredo do seu provedor e o injeta como o valor da variável de ambiente. Com Workload Identity, essa busca acontece a cada kickoff (consciente de rotação). Com credenciais estáticas, essa busca acontece no momento do deploy e o valor é incorporado à imagem do deployment. + +## Visibilidade & Escopo + + +Variáveis de ambiente atreladas a WI seguem o mesmo modelo de atribuição das variáveis de ambiente em texto puro: uma automação resolve apenas as variáveis atreladas a WI explicitamente atribuídas a ela. Atribua uma variável atrelada a WI a uma automação pela página de Variáveis de Ambiente dessa automação; variáveis definidas no nível da organização ou em um projeto Studio não são resolvidas em kickoff até que você as atribua. + + + +A fase de busca de segredos é executada em todo kickoff, mas só realiza trabalho quando há variáveis de ambiente atreladas a WI atribuídas ao deployment. Para cada variável atribuída, o runtime resolve o valor a partir do seu provedor de nuvem em todo kickoff de crew, flow, training, test ou checkpoint-restore e o grava no ambiente do processo. Sem nada atribuído, a fase é um no-op. Caso contrário, o custo é proporcional ao número de variáveis atribuídas: uma pequena latência adicional por kickoff mais uma entrada no audit log do lado da nuvem por variável. + + + +No nível das *configurações* de Workload Identity, o escopo ainda é abrangente a toda a organização hoje. Toda automação na organização é inicializada com base em todas as configurações de Workload Identity que a organização registrou, e hoje você não pode vincular uma configuração específica de Workload Identity a uma automação específica. Escopo por automação para Workload Identity está no roadmap. Até lá, registre apenas configurações de Workload Identity que toda automação da sua organização tenha permissão de usar. + + +## Permissões + +Duas features da CrewAI Platform controlam o acesso ao Secrets Manager: + +- `secret_providers` — controla quem pode visualizar ou gerenciar credenciais de provedor. +- `environment_variables` — controla quem pode criar e editar variáveis de ambiente (incluindo aquelas que referenciam segredos). + +Uma terceira feature controla a configuração do Workload Identity: + +- `workload_identity_configs` — controla quem pode visualizar ou gerenciar configurações de Workload Identity. Necessário apenas se você estiver usando o caminho Workload Identity. + +Owners sempre têm acesso total. Members **não** recebem acesso a `secret_providers` ou `workload_identity_configs` por padrão e precisam receber permissão por meio de um papel customizado. Veja [Permissões (RBAC)](/pt-BR/enterprise/features/secrets-manager/usage#permissions-rbac) para a matriz completa e instruções passo a passo. + +## Próximos Passos + +Escolha seu caminho: + +- **Credenciais estáticas** (mais simples, requer novo deploy na rotação): + - [Configurar AWS Secrets Manager](/pt-BR/enterprise/features/secrets-manager/aws) + - [Configurar Google Cloud Secret Manager](/pt-BR/enterprise/features/secrets-manager/gcp) + - [Configurar Azure Key Vault](/pt-BR/enterprise/features/secrets-manager/azure) +- **Workload Identity** (consciente de rotação, sem novo deploy): + - [Configurar AWS Workload Identity](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) + - [Configurar GCP Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) + - [Configurar Azure Workload Identity Federation](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity) +- Em seguida: [Use segredos em variáveis de ambiente e gerencie permissões](/pt-BR/enterprise/features/secrets-manager/usage) diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/usage.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/usage.mdx new file mode 100644 index 000000000..332cf1732 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/usage.mdx @@ -0,0 +1,137 @@ +--- +title: Usando o Secrets Manager +description: Gerencie permissões e referencie segredos gerenciados a partir de variáveis de ambiente na CrewAI Platform +sidebarTitle: Uso e Permissões +icon: "list-check" +--- + +## Visão Geral + +Este guia é agnóstico em relação ao provedor. Ele assume que você (ou outro admin) já configurou pelo menos uma Credencial de Provedor de Segredos. Escolha seu guia de configuração com base no caminho que deseja: + +- Credenciais estáticas: [AWS](/pt-BR/enterprise/features/secrets-manager/aws) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp) +- Workload Identity (consciente de rotação): [AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) + +Use este guia para: + +- Conceder as permissões corretas aos membros da organização. +- Referenciar segredos a partir de variáveis de ambiente nas suas automações. +- Verificar se tudo é resolvido corretamente em runtime. + +## Permissões (RBAC) + +Três features da CrewAI Platform são relevantes ao trabalhar com o Secrets Manager: + +- `secret_providers` — controla o acesso à página **Secret Provider Credentials**. +- `workload_identity_configs` — controla o acesso à página **Workload Identity** (relevante apenas se você usar o caminho WI). +- `environment_variables` — controla quem pode criar ou editar variáveis de ambiente. + +Cada feature tem dois níveis de ação: `read` e `manage`. Conceder `manage` implica automaticamente em `read`. + +### O que Conceder + +| Objetivo | `secret_providers` | `workload_identity_configs` | `environment_variables` | +|---|---|---|---| +| Usar credenciais estáticas existentes em variáveis de ambiente (sem edição de provedor) | `read` | — | `manage` | +| Criar, editar ou excluir credenciais estáticas | `manage` | — | `manage` | +| Usar credenciais existentes baseadas em Workload Identity em env vars | `read` | — | `manage` | +| Criar, editar ou excluir configs de Workload Identity (e credenciais que as referenciam) | `manage` | `manage` | `manage` | + + +**Owners** automaticamente têm acesso total a todas as features. O papel padrão **Member** intencionalmente exclui `secret_providers` e `workload_identity_configs` — admins devem incluir explicitamente os membros por meio de um papel customizado. + + +### Como Atribuir + +1. Na CrewAI Platform, navegue até **Settings** → **Roles**. Nesta página você pode criar novos papéis, editar as permissões de cada papel e atribuir papéis aos membros existentes da organização. + + {/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */} + {/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */} + +2. Clique em **Create Role** para criar um novo papel ou abra um papel existente para editar suas permissões. + +3. No editor de permissões do papel, alterne as features relevantes conforme a tabela acima: + + - `secret_providers`: escolha **read** se este papel só precisa usar credenciais existentes, ou **manage** se também deve ser capaz de criar, editar e excluir credenciais. + - `environment_variables`: escolha **manage** para que o papel possa criar variáveis de ambiente que referenciam segredos. + + {/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */} + {/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */} + +4. Salve o papel. + +5. Atribua o papel aos membros relevantes pela mesma página de Roles (ou pela lista de Membros da organização). + + {/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */} + +## Referenciando Segredos em Variáveis de Ambiente + +Uma vez que uma credencial de provedor exista e seu papel tenha as permissões corretas, você pode referenciar segredos gerenciados a partir de qualquer variável de ambiente. + +Na CrewAI Platform, navegue até **Environment Variables** e clique em **Add Environment Variables**. + +{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */} + +Preencha o formulário: + +- **Key** — o nome da variável de ambiente. Deve começar com uma letra ou underscore e conter apenas letras, números e underscores. Convencionalmente em maiúsculas, ex. `OPENAI_API_KEY`. + +- **Value Source** — escolha de onde vem o valor: + - **Direct Value** — um valor em texto puro que você digita. Use isto quando não quiser envolver um provedor. + - **Use AWS default** (ou o equivalente para o seu provedor) — usa a credencial atualmente marcada como padrão para aquele tipo de provedor. + - **A specific named credential** — selecione a credencial pelo nome. Use isto se você tiver múltiplas credenciais para o mesmo provedor (por exemplo, `aws-prod` e `aws-staging`) e quiser escolher uma explicitamente. + + {/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */} + +- **Secret Name** — o nome do segredo no seu provedor. Uma vez que uma credencial é selecionada, este campo oferece autocomplete: comece a digitar e a CrewAI Platform consulta seu provedor por nomes de segredos correspondentes. + + Use a sintaxe `secret-name#json_key` para extrair um único campo de um segredo estruturado (JSON). Por exemplo, dado um segredo `database-credentials` com valor `{"username": "...", "password": "..."}`, referencie `database-credentials#password` para injetar apenas a senha. + + {/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */} + + + **Nota sobre Azure Key Vault:** Nomes de segredos do Azure não podem conter underscores. A CrewAI Platform converte automaticamente underscores no seu campo `Secret Name` para hífens ao chamar o Azure (ex.: `db_password` é enviado como `db-password`). + + +Clique em **Create** para salvar a variável. + +{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */} + + +Ao editar uma variável de ambiente existente, deixar o campo **Value** em branco preserva o valor atual. Isto é intencional — permite que você altere outros campos (como o nome do segredo ou a credencial) sem precisar digitar o valor novamente. + + +## Verificando se Funciona + +Para verificar de ponta a ponta: + +1. Referencie a variável de ambiente em uma automação, crew ou deployment exatamente como você faria com qualquer outra variável de ambiente. +2. Faça o deploy da automação. +3. Dispare uma execução e confirme que ela é concluída com sucesso. + +### O comportamento de rotação depende do caminho da credencial + +| Caminho da credencial | Quando o segredo é lido | O que a rotação requer | +|---|---|---| +| **Credenciais estáticas** (chaves de acesso AWS, JSON de service account GCP) | No **momento do deploy** — o valor é incorporado à imagem do deployment | Fazer novo deploy da automação após rotacionar o segredo | +| **Workload Identity** (federação OIDC, AWS ou GCP) | A **cada kickoff de automação** — o valor é buscado de forma fresca da sua nuvem | Nada — o próximo kickoff após a rotação verá o novo valor | + + +**Se você precisa de segredos conscientes de rotação** (sem novo deploy na rotação), use o caminho Workload Identity: [AWS WI](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) ou [GCP WI](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity). O trade-off é mais esforço de configuração inicial (registrar a CrewAI Platform como provedor OIDC na sua nuvem), mas operações mais simples no longo prazo. + + +Se o deploy ou a execução falhar com um erro relacionado ao seu segredo, verifique as causas mais comuns: + +| Sintoma | Causa provável | +|---|---| +| `no credential found` | A variável de ambiente referencia um provedor, mas nenhuma credencial específica foi selecionada e não há credencial padrão definida para aquele tipo de provedor. Selecione uma credencial explicitamente na variável, ou marque uma credencial como padrão na página **Secret Provider Credentials**. | +| `secret not found` | Erro de digitação no **Secret Name**, ou o segredo não existe na conta/região do provedor para a qual a credencial aponta. Reconfira ambos. | +| Automação executa com o valor antigo após rotação (caminho de credenciais estáticas) | O valor anterior está incorporado à imagem do contêiner do deployment. Faça novo deploy da automação para pegar o valor rotacionado. Para evitar isso completamente, mude a credencial para o caminho Workload Identity. | +| Automação executa com o valor antigo após rotação (caminho Workload Identity) | Confirme que a env var referencia uma credencial baseada em WI (não uma de chaves estáticas). Com WI, o próximo kickoff após a rotação deve ver o novo valor. Se não vir, verifique se o segredo foi realmente atualizado na sua nuvem (ex.: `aws secretsmanager get-secret-value`). | +| `JSON key not found` | Ao usar `secret-name#json_key`, o segredo subjacente deve ser um objeto JSON válido contendo essa chave. Verifique lendo o segredo diretamente no seu provedor. | + +## Próximos Passos + +- [Voltar à visão geral do Secrets Manager](/pt-BR/enterprise/features/secrets-manager/overview) +- Credenciais estáticas: [AWS](/pt-BR/enterprise/features/secrets-manager/aws) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp) +- Workload Identity (consciente de rotação): [AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) diff --git a/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/verify-rotation.mdx b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/verify-rotation.mdx new file mode 100644 index 000000000..216ee243f --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/secrets-manager/verify-rotation.mdx @@ -0,0 +1,261 @@ +--- +title: Verificar Rotação +description: Um crew de exemplo autocontido que prova que a rotação de segredos se propaga para deployments em execução sem novo deploy. +sidebarTitle: Verificar Rotação +icon: "arrows-rotate" +--- + +## Visão Geral + +Este guia mostra como verificar que **um segredo rotacionado no seu provedor de nuvem é pego no próprio kickoff de automação seguinte** — sem novo deploy, sem reinício de worker. É relevante apenas quando você configurou uma credencial baseada em Workload Identity ([AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity)). Deployments com credenciais estáticas exigem um novo deploy após a rotação; nada a verificar aqui. + +A receita abaixo usa um crew minúsculo e autocontido com uma ferramenta, um agente, uma tarefa. O prompt do crew nunca referencia o valor do segredo — em vez disso, uma ferramenta o lê de `os.environ` e reporta um fingerprint SHA-256 do que ela vê. Rotacione o segredo no seu provedor de nuvem, dispare novamente e o fingerprint muda. + + +Por que um fingerprint, não o valor bruto? Colocar segredos brutos na saída do LLM e em trace logs é um vetor de vazamento. O fingerprint é suficiente para confirmar "o valor mudou" sem escrever o valor real em nenhum lugar observável. + + +## Pré-requisitos + +Antes de executar esta verificação: + +- Uma Secret Provider Credential baseada em WI está configurada ([AWS](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/pt-BR/enterprise/features/secrets-manager/azure-workload-identity)). +- Uma variável de ambiente no seu deployment com `Secret = true`, chave `API_KEY` (ou qualquer nome que preferir — ajuste a ferramenta abaixo para corresponder), referenciando um segredo no seu provedor de nuvem. +- Uma forma de atualizar o valor do segredo no seu provedor de nuvem (acesso à CLI ou ao console da nuvem). +- Uma forma de disparar o deployment via HTTP (curl, Postman ou a aba **Run** na CrewAI Platform). + +## Passo 1 — Estruturar um Crew de Verificação + +Crie um projeto de crew clássico porque este exemplo conecta uma ferramenta Python via `crew.py`: + +```bash +crewai create crew rotation_verifier --classic --skip_provider +cd rotation_verifier +``` + +## Passo 2 — Adicionar a Ferramenta de Echo de Credencial + +Substitua `src/rotation_verifier/tools/custom_tool.py` por uma ferramenta que lê a env var apoiada pelo segredo e retorna um fingerprint: + +```python src/rotation_verifier/tools/credential_echo_tool.py +"""Tool that verifies a runtime-injected secret without leaking the value. + +Reads the secret-backed env var (populated by the workload-identity +secrets manager at kickoff time) and returns a stable fingerprint. Never +echo raw credential values into LLM output or logs in production code — +the fingerprint alone is sufficient to confirm rotation worked. +""" + +from __future__ import annotations + +import hashlib +import os + +from crewai.tools import BaseTool + + +# Match the deployment environment variable's `key` field. +ENV_VAR_NAME = "API_KEY" + + +class CredentialEchoTool(BaseTool): + name: str = "credential_echo" + description: str = ( + "Read the API credential from the worker's environment and return a " + "fingerprint summary. Use this exactly once when asked to verify the " + "current credential. Takes no arguments." + ) + + def _run(self) -> str: + value = os.environ.get(ENV_VAR_NAME) + if not value: + return ( + f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-" + "identity secret fetch did not run, or the deployment is " + "missing the secret-backed env var." + ) + fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12] + return f"Authenticated. credential.fingerprint=sha256:{fingerprint}" +``` + +## Passo 3 — Substituir as Configs Padrão de Agente e Task + +O crew tem um agente e uma tarefa — ambos com descrições que **nunca** mencionam o valor do segredo, para que as chaves de tarefa permaneçam estáveis entre rotações. + +```yaml src/rotation_verifier/config/agents.yaml +credential_checker: + role: > + Credential Verifier + goal: > + Confirm that the workload-identity-backed secret reached this worker + process and report a fingerprint of the current value. + backstory: > + You are a no-nonsense reliability engineer responsible for verifying + that secrets fetched at runtime via workload identity are present + and fresh. You always use the credential_echo tool exactly once and + report the result verbatim — you never make up values. +``` + +```yaml src/rotation_verifier/config/tasks.yaml +verify_credential_task: + description: > + Use the credential_echo tool to read the runtime-injected credential + and produce a one-line confirmation. The current year is {current_year} + (use it only in the timestamp; do not transform the credential output). + expected_output: > + A single line in the form: + "[{current_year}] " + agent: credential_checker +``` + +## Passo 4 — Conectar a Classe do Crew + +```python src/rotation_verifier/crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent + +from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool + + +@CrewBase +class RotationVerifierCrew(): + """Single-task crew that verifies a workload-identity-backed secret + was successfully fetched at runtime. + + Rotate the underlying secret in the cloud provider, kickoff again, and + the credential fingerprint in the agent's report changes — without any + re-deploy, worker restart, or input change. The crew prompt itself + never references the secret value. + """ + + agents: list[BaseAgent] + tasks: list[Task] + + @agent + def credential_checker(self) -> Agent: + return Agent( + config=self.agents_config["credential_checker"], + tools=[CredentialEchoTool()], + verbose=True, + ) + + @task + def verify_credential_task(self) -> Task: + return Task(config=self.tasks_config["verify_credential_task"]) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +## Passo 5 — Fazer Deploy e Configurar a Env Var do Segredo + +Faça deploy deste crew na CrewAI Platform exatamente como você faria com qualquer outro crew. Em seguida, na página **Environment Variables** do deployment: + +- **Key:** `API_KEY` (deve corresponder a `ENV_VAR_NAME` na ferramenta) +- **Value Source:** a credencial baseada em WI que você configurou em [AWS WI](/pt-BR/enterprise/features/secrets-manager/aws-workload-identity) ou [GCP WI](/pt-BR/enterprise/features/secrets-manager/gcp-workload-identity) +- **Secret Name:** o nome do segredo no Secret Manager do seu provedor de nuvem + +{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */} + +## Passo 6 — Executar o Primeiro Kickoff + +Substitua `` e `` por valores da aba **Run** do seu deployment. + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +Quando o kickoff for concluído (alguns segundos), verifique a saída do agente. Você verá: + +``` +[2026] Authenticated. credential.fingerprint=sha256:004421b993c9 +``` + +Anote o fingerprint. Esse hash está unicamente vinculado a qualquer valor de segredo que esteja atualmente no seu provedor de nuvem. + +## Passo 7 — Rotacionar o Segredo no Seu Provedor de Nuvem + + + + ```bash + aws secretsmanager update-secret \ + --region \ + --secret-id \ + --secret-string "rotated value" + ``` + + + + Adicione uma nova versão (o Secret Manager sempre lê `latest`): + + ```bash + echo -n "rotated value" | gcloud secrets versions add \ + --data-file=- \ + --project= + ``` + + + + ```bash + az keyvault secret set \ + --vault-name \ + --name \ + --value "rotated value" + ``` + + + +## Passo 8 — Executar um Segundo Kickoff e Comparar + +```bash +curl -m 60 \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -X POST https:///kickoff \ + -d '{"inputs":{"current_year":"2026"}}' +``` + +A saída do agente agora mostra um **fingerprint diferente**: + +``` +[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72 +``` + +Isso prova que a rotação foi pega pelo deployment em execução sem novo deploy, reinício de worker ou outra ação do operador. + +## O que Isso Verifica — e o que Não Verifica + +**Verifica:** +- A emissão de tokens OIDC do WI a partir da CrewAI Platform funciona. +- A confiança do lado da nuvem (provedor IAM OIDC para AWS, Workload Identity Pool para GCP, Federated Identity Credential para Azure) aceita o token. +- A identidade do lado da nuvem (IAM Role / GCP service account / Entra App Registration) tem acesso para ler o segredo. +- O valor do segredo chega ao `os.environ` do processo worker no momento do kickoff. +- Rotações subsequentes se propagam para o próximo kickoff. + +**Não verifica:** +- Que seus crews de produção reais lidam com a rotação graciosamente — ex., tarefas de longa duração que leem a env var uma vez na inicialização continuarão usando o valor antigo até que a tarefa termine. Planeje conforme: leia segredos no ponto de uso, não no momento do import do módulo. + +## Por que Não Referenciar o Segredo Diretamente no Prompt? + +Uma demonstração de aparência mais simples colocaria o valor do segredo diretamente em uma descrição de tarefa (ex.: "Research about `{api_key}`") e inspecionaria o prompt. **Não faça isso.** Duas razões: + +1. **Isso vaza o segredo para traces de chamadas LLM e logs do lado do provedor.** Qualquer um com acesso a traces pode lê-lo. +2. **Isso muda a descrição da tarefa a cada kickoff.** A CrewAI Platform identifica tarefas por um hash MD5 da descrição; um valor rotativo significa que o hash muda por kickoff, o que quebra o mapeamento deploy-time → runtime das tarefas. Sintoma: os registros de tarefa aparecem como `pending_run` indefinidamente, ou apenas algumas das tarefas de um crew multi-task se registram. + +O padrão baseado em ferramenta neste guia contorna ambas as questões: o prompt é estático, a ferramenta lê a env var em runtime e apenas um fingerprint do valor chega ao LLM. + +## Próximos Passos + +- [Voltar à visão geral do Secrets Manager](/pt-BR/enterprise/features/secrets-manager/overview) +- Uma vez verificado, descarte o crew de verificação. Crews reais devem seguir o mesmo padrão: segredos acessados via `os.environ` dentro de uma ferramenta, nunca substituídos em prompts. diff --git a/docs/v1.15.1/pt-BR/enterprise/features/tools-and-integrations.mdx b/docs/v1.15.1/pt-BR/enterprise/features/tools-and-integrations.mdx new file mode 100644 index 000000000..89082b880 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/tools-and-integrations.mdx @@ -0,0 +1,257 @@ +--- +title: "Ferramentas & Integrações" +description: "Conecte apps externos e gerencie ferramentas internas que seus agentes podem usar." +icon: "wrench" +mode: "wide" +--- + +## Visão geral + +Ferramentas & Integrações é o hub central para conectar aplicações de terceiros e gerenciar ferramentas internas que seus agentes podem usar em tempo de execução. + + + ![Ferramentas & Integrações](/images/enterprise/crew_connectors.png) + + +## Explorar + + + + +## Aplicativos para Agentes (Integrações) + +Conecte aplicações empresariais (por exemplo, Gmail, Google Drive, HubSpot, Slack) via OAuth para habilitar ações de agentes. + +{" "} + + + Clique em Conectar no app desejado e conclua o OAuth. + + + Ajuste escopos, gatilhos e ações disponíveis conforme necessário. + + + Os serviços conectados ficam disponíveis como ferramentas para seus agentes. + + + +{" "} +![Aplicativos](/images/enterprise/agent-apps.png) + +### Conectar sua conta + +1. Acesse Integrações +2. Clique em Conectar no serviço desejado +3. Conclua o fluxo OAuth e conceda os escopos +4. Copie seu Token Enterprise em Configurações de Integração + +{" "} + + ![Token Enterprise](/images/enterprise/enterprise_action_auth_token.png) + + +### Instalar ferramentas de integração + +Para usar as integrações localmente, instale a versão mais recente do pacote `crewai-tools`. + +```bash +uv add crewai-tools +``` + +### Configuração de variável de ambiente + +{" "} + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +### Exemplo de uso + +{" "} + + Use a nova abordagem simplificada para integrar aplicativos empresariais. + Simplesmente especifique o aplicativo e suas ações diretamente na configuração + do Agent. + + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Gmail +email_agent = Agent( + role="Gerente de Email", + goal="Gerenciar e organizar comunicações por email", + backstory="Assistente de IA especializado em gestão de emails", + apps=['gmail', 'gmail/send_email'] # Usando nome canônico 'gmail' +) + +email_task = Task( + description="Criar e enviar follow-up para john@example.com sobre a atualização do projeto", + agent=email_agent, + expected_output="Confirmação de envio do email com sucesso" +) + +crew = Crew(agents=[email_agent], tasks=[email_task]) +crew.kickoff() +``` + +### Filtrando ferramentas + +```python +from crewai import Agent, Task, Crew + +# Crie agente com ações específicas do Gmail apenas +gmail_agent = Agent( + role="Gerente de Gmail", + goal="Gerenciar comunicações e notificações no Gmail", + backstory="Assistente de IA para coordenação de emails", + apps=['gmail/fetch_emails'] # Usando nome canônico com ação específica +) + +notification_task = Task( + description="Encontrar o email de john@example.com", + agent=gmail_agent, + expected_output="Email encontrado de john@example.com" +) + +crew = Crew(agents=[gmail_agent], tasks=[notification_task]) +``` + +Em um crew implantado, você pode especificar quais ações ficam disponíveis em cada integração na página de configurações do serviço. + +{" "} + + ![Filtrar Ações](/images/enterprise/filtering_enterprise_action_tools.png) + + +### Implantações com escopo (organizações multiusuário) + +Você pode escopar cada integração para um usuário específico (por exemplo, usar a conta Gmail de um usuário). + +{" "} + + Útil quando diferentes equipes/usuários precisam manter o acesso a dados + isolado. + + +Use `user_bearer_token` para escopar a autenticação ao usuário solicitante. Se o usuário não estiver logado, o crew não usará integrações conectadas; caso contrário, usa o token padrão configurado na implantação. + +{" "} +![Token de Usuário](/images/enterprise/user_bearer_token.png) + +{" "} +
+### Catálogo + +#### Comunicação & Colaboração + +- Gmail — Gerenciamento de emails e rascunhos +- Slack — Notificações e alertas do workspace +- Microsoft — Integração com Office 365 e Teams + +#### Gestão de Projetos + +- Jira — Rastreamento de issues e projetos +- ClickUp — Gestão de tarefas e produtividade +- Asana — Coordenação de tarefas de equipe +- Notion — Páginas e bancos de dados +- Linear — Gestão de bugs e projetos de software +- GitHub — Repositórios e issues + +#### CRM + +- Salesforce — Contas e oportunidades +- HubSpot — Pipeline de vendas e contatos +- Zendesk — Tickets de suporte + +#### Negócios & Finanças + +- Stripe — Pagamentos e clientes +- Shopify — E‑commerce e produtos + +#### Produtividade & Armazenamento + +- Google Sheets — Sincronização de planilhas +- Google Calendar — Eventos e agenda +- Box — Armazenamento de arquivos + +…e mais por vir! + + + + +## Ferramentas Internas + +Crie ferramentas localmente, publique no Repositório de Ferramentas da CrewAI AMP e use nos seus agentes. + +{" "} + + Antes de executar os comandos abaixo, faça login na sua conta CrewAI AMP: + ```bash crewai login ``` + + +{" "} + + ![Ferramenta Interna](/images/enterprise/tools-integrations-internal.png) + + +{" "} + + + Criar uma nova ferramenta localmente. ```bash crewai tool create your-tool``` + + + Publicar a ferramenta no Repositório de Ferramentas. ```bash crewai tool + publish ``` + + + Instalar a ferramenta do Repositório de Ferramentas. ```bash crewai tool + install your-tool ``` + + + +Gerenciar: + +- Nome e descrição +- Visibilidade (Privado / Público) +- Variáveis de ambiente necessárias +- Histórico de versões e downloads +- Acesso por equipe e função + +{" "} + + ![Configurações de Ferramenta](/images/enterprise/tool-configs.png) + + + + + +## Relacionados + + + + Publique e instale ferramentas para ampliar as capacidades dos seus crews. + + + Automatize fluxos e integre com plataformas e serviços externos. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/traces.mdx b/docs/v1.15.1/pt-BR/enterprise/features/traces.mdx new file mode 100644 index 000000000..8906eb9b8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/traces.mdx @@ -0,0 +1,138 @@ +--- +title: Traces +description: "Usando Traces para monitorar seus Crews" +icon: "timeline" +mode: "wide" +--- + +## Visão Geral + +Traces fornecem visibilidade abrangente sobre as execuções dos seus crews, ajudando você a monitorar o desempenho, depurar problemas e otimizar os fluxos de trabalho dos seus agentes de IA. + +## O que são Traces? + +Traces no CrewAI AMP são registros detalhados de execução que capturam todos os aspectos da operação do seu crew, desde as entradas iniciais até as saídas finais. Eles registram: + +- Pensamentos e raciocínio do agente +- Detalhes da execução das tarefas +- Uso de ferramentas e resultados +- Métricas de consumo de tokens +- Tempos de execução +- Estimativas de custo + +![Traces Overview](/images/enterprise/traces-overview.png) + +## Acessando os Traces + + + + No seu painel do CrewAI AMP, 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 AMP. + diff --git a/docs/v1.15.1/pt-BR/enterprise/features/webhook-streaming.mdx b/docs/v1.15.1/pt-BR/enterprise/features/webhook-streaming.mdx new file mode 100644 index 000000000..d19ba6370 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/features/webhook-streaming.mdx @@ -0,0 +1,87 @@ +--- +title: Webhook Streaming +description: "Usando Webhook Streaming para transmitir eventos para o seu webhook" +icon: "webhook" +mode: "wide" +--- + +## Visão Geral + +O Enterprise Event Streaming permite que você receba atualizações em tempo real via webhook sobre suas crews e flows implantados no CrewAI AMP, como chamadas de modelo, uso de ferramentas e etapas do flow. + +## Uso + +Ao utilizar a API Kickoff, inclua um objeto `webhooks` em sua requisição, por exemplo: + +# Exemplo de uso da API Kickoff com webhooks + +```json +{ + "inputs": { "foo": "bar" }, + "webhooks": { + "events": ["crew_kickoff_started", "llm_call_started"], + "url": "https://seu.endpoint/webhook", + "realtime": false, + "authentication": { + "strategy": "bearer", + "token": "meu-token-secreto" + } + } +} +``` + +Se `realtime` estiver definido como `true`, cada evento será entregue individualmente e imediatamente, com impacto no desempenho da crew/flow. + +## Formato do Webhook + +Cada webhook envia uma lista de eventos: + +# Exemplo de evento enviado pelo webhook + +```json +{ + "events": [ + { + "id": "id-do-evento", + "execution_id": "id-da-execucao-do-crew", + "timestamp": "2025-02-16T10:58:44.965Z", + "type": "llm_call_started", + "data": { + "model": "gpt-4", + "messages": [ + { "role": "system", "content": "Você é um assistente." }, + { "role": "user", "content": "Resuma este artigo." } + ] + } + } + ] +} +``` + +A estrutura do objeto `data` varia conforme o tipo de evento. Consulte a [lista de eventos](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) no GitHub. + +Como as requisições são enviadas via HTTP, a ordem dos eventos não pode ser garantida. Caso precise de ordenação, utilize o campo `timestamp`. + +## Eventos Suportados + +O CrewAI oferece suporte a eventos do sistema e eventos personalizados no Enterprise Event Streaming. Esses eventos são enviados para o endpoint do seu webhook configurado durante a execução das crews e flows. + +- `crew_kickoff_started` +- `crew_step_started` +- `crew_step_completed` +- `crew_execution_completed` +- `llm_call_started` +- `llm_call_completed` +- `tool_usage_started` +- `tool_usage_completed` +- `crew_test_failed` +- _...e outros_ + +Os nomes dos eventos correspondem ao event bus interno. Veja o [código fonte no GitHub](https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events) para a lista completa. + +Você pode emitir seus próprios eventos personalizados, e eles serão entregues através do webhook stream juntamente com os eventos do sistema. + + + Entre em contato com nossa equipe de suporte para assistência com integração + de webhook ou solução de problemas. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/automation-triggers.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/automation-triggers.mdx new file mode 100644 index 000000000..85f866875 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/automation-triggers.mdx @@ -0,0 +1,291 @@ +--- +title: "Visão Geral de Triggers" +description: "Entenda como os triggers da CrewAI AMP funcionam, como gerenciá-los e onde encontrar playbooks específicos de integração" +icon: "bolt" +mode: "wide" +--- + +Os triggers da CrewAI AMP conectam suas automações a eventos em tempo real nas ferramentas que sua equipe já usa. Em vez de fazer polling ou depender de execuções manuais, os triggers escutam mudanças — novos e‑mails, atualizações de calendário, alterações no CRM — e iniciam imediatamente a crew ou flow que você definiu. + + + +### Playbooks de Integração + +Os guias abaixo explicam, em detalhe, como habilitar e testar cada integração: + + + + Dispare crews quando novos e‑mails chegarem ou threads forem atualizadas. + + +{" "} + + + Reaja a eventos de calendário criados, atualizados ou cancelados. + + + +{" "} + + + Monitore uploads, edições e exclusões de arquivos no Drive. + + + +{" "} + + + Automatize respostas a novos e‑mails ou eventos removidos no Outlook. + + + +{" "} + + + Audite atividade e compartilhamentos de arquivos no OneDrive. + + + +{" "} + + + Inicie workflows quando novos chats forem criados no Teams. + + + +{" "} + + + Execute automações a partir de workflows e eventos de ciclo de vida no + HubSpot. + + + +{" "} + + + Conecte processos do Salesforce às suas crews para automação de CRM. + + + +{" "} + + + Dispare crews diretamente de comandos slash no Slack. + + + + + Integre a CrewAI com milhares de apps suportados pelo Zapier. + + + +## Capacidades dos Triggers + +Com triggers você pode: + +- **Responder em tempo real** – Executar workflows automaticamente quando condições forem atendidas +- **Integrar com sistemas externos** – Conectar Gmail, Outlook, OneDrive, JIRA, Slack, Stripe e muito mais +- **Escalar automações** – Lidar com alto volume de eventos sem intervenção manual +- **Manter contexto** – Acessar dados do trigger dentro das suas crews e flows + +## Gerenciando Triggers + +### Visualizando Triggers Disponíveis + +1. Abra sua automação no painel da CrewAI +2. Clique na aba **Triggers** para listar todas as integrações disponíveis + + + Lista de triggers disponíveis + + +### Habilitando e Desabilitando + +Cada trigger possui uma chave de ativação: + + + Alternância de trigger habilitado + + +- **Habilitado (azul)** – Executa a automação quando o evento ocorrer +- **Desabilitado (cinza)** – Ignora eventos + +As alterações são aplicadas imediatamente. + +### Monitorando Execuções + +Use a lista de execuções para acompanhar histórico, status e payloads: + + + Lista de execuções acionadas por triggers + + +## Construindo Automações Orientadas por Trigger + +### Checklist de Configuração + +Antes de ativar em produção, confirme que você: + +- Conectou a integração em **Tools & Integrations** e concluiu OAuth ou configuração de API +- Habilitou o trigger na automação correta +- Definiu variáveis de ambiente necessárias (tokens, IDs de tenant, segredos) +- Criou tarefas que analisam o payload no primeiro passo da crew/flow +- Decidiu se usará `allow_crewai_trigger_context` para injetar contexto automaticamente +- Configurou monitoramento (webhooks, históricos da CrewAI, alertas externos) + +### Testando Triggers Localmente com CLI + +A CLI da CrewAI fornece comandos poderosos para ajudá-lo a desenvolver e testar automações orientadas por triggers sem fazer deploy para produção. + +#### Listar Triggers Disponíveis + +Visualize todos os triggers disponíveis para suas integrações conectadas: + +```bash +crewai triggers list +``` + +Este comando exibe todos os triggers disponíveis baseados nas suas integrações conectadas, mostrando: + +- Nome da integração e status de conexão +- Tipos de triggers disponíveis +- Nomes e descrições dos triggers + +#### Simular Execução de Trigger + +Teste sua crew com payloads realistas de triggers antes do deployment: + +```bash +crewai triggers run +``` + +Por exemplo: + +```bash +crewai triggers run microsoft_onedrive/file_changed +``` + +Este comando: + +- Executa sua crew localmente +- Passa um payload de trigger completo e realista +- Simula exatamente como sua crew será chamada em produção + + + **Notas Importantes de Desenvolvimento:** + - Use `crewai triggers run ` para simular execução de trigger durante o desenvolvimento + - Usar `crewai run` NÃO simulará chamadas de trigger e não passará o payload do trigger + - Após o deployment, sua crew será executada com o payload real do trigger + - Se sua crew espera parâmetros que não estão no payload do trigger, a execução pode falhar + + +### Triggers com Crews + +Suas definições de crew funcionam naturalmente com triggers; basta ter uma tarefa que processe o payload recebido: + +```python +@CrewBase +class MinhaCrewAutomatizada: + @agent + def pesquisador(self) -> Agent: + return Agent( + config=self.agents_config['pesquisador'], + ) + + @task + def analisar_payload_trigger(self) -> Task: + return Task( + config=self.tasks_config['analisar_payload_trigger'], + agent=self.pesquisador(), + ) + + @task + def analisar_conteudo_trigger(self) -> Task: + return Task( + config=self.tasks_config['analisar_dados_trigger'], + agent=self.pesquisador(), + ) +``` + +### Integração com Flows + +Flows oferecem controle adicional sobre o uso do payload: + +#### Acessando o Payload + +Todos os métodos `@start()` podem receber `crewai_trigger_payload`: + +```python +from crewai.flow import Flow, start, listen + +class MeuFlowAutomatizado(Flow): + @start() + def lidar_com_trigger(self, crewai_trigger_payload: dict = None): + if crewai_trigger_payload: + trigger_id = crewai_trigger_payload.get('id') + dados_evento = crewai_trigger_payload.get('payload', {}) + self.state.trigger_id = trigger_id + self.state.trigger_type = dados_evento + return dados_evento + return None + + @listen(lidar_com_trigger) + def processar_dados(self, dados_trigger): + # ... processa o trigger +``` + +#### Acionando Crews a partir de Flows + +```python +@start() +def delegar_para_crew(self, crewai_trigger_payload: dict = None): + crew = MinhaCrewEspecializada() + resultado = crew.crew().kickoff( + inputs={ + 'parametro_personalizado': "valor_personalizado", + 'crewai_trigger_payload': crewai_trigger_payload + }, + ) + return resultado +``` + +## Solução de Problemas + +**Trigger não dispara:** + +- Verifique se o trigger está habilitado na aba Triggers do seu deployment +- Confira o status da conexão em Tools & Integrations +- Garanta que todas as variáveis de ambiente necessárias estão configuradas + +**Falhas de execução:** + +- Consulte os logs de execução para detalhes do erro +- Use `crewai triggers run ` para testar localmente e ver a estrutura exata do payload +- Verifique se sua crew pode processar o parâmetro `crewai_trigger_payload` +- Garanta que sua crew não espera parâmetros que não estão incluídos no payload do trigger + +**Problemas de desenvolvimento:** + +- Sempre teste com `crewai triggers run ` antes de fazer deploy para ver o payload completo +- Lembre-se que `crewai run` NÃO simula chamadas de trigger—use `crewai triggers run` em vez disso +- Use `crewai triggers list` para verificar quais triggers estão disponíveis para suas integrações conectadas +- Após o deployment, sua crew receberá o payload real do trigger, então teste minuciosamente localmente primeiro + +Os triggers transformam suas implantações CrewAI em sistemas orientados por eventos, integrando-se perfeitamente aos processos e ferramentas já usados pelo seu time. diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/azure-openai-setup.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/azure-openai-setup.mdx new file mode 100644 index 000000000..b234df95d --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/azure-openai-setup.mdx @@ -0,0 +1,54 @@ +--- +title: "Configuração do Azure OpenAI" +description: "Configure o Azure OpenAI com o Crew Studio para conexões empresariais de LLM" +icon: "microsoft" +mode: "wide" +--- + +Este guia orienta você na conexão do Azure OpenAI com o Crew Studio para operações de IA empresarial sem interrupções. + +## Processo de Configuração + + + + 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 AMP > LLM Connections`. Dê um nome à sua LLM Connection, selecione Azure como provedor e escolha o mesmo modelo que você selecionou no Azure. + 5. Na mesma página, adicione as variáveis de ambiente do passo 3: + - Uma chamada `AZURE_DEPLOYMENT_TARGET_URL` (usando o Target URI). A URL deve ser parecida com: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview + - Outra chamada `AZURE_API_KEY` (usando a Key). + 6. Clique em `Add Connection` para salvar sua LLM Connection. + + + + 7. Em `CrewAI AMP > 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 diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/build-crew.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/build-crew.mdx new file mode 100644 index 000000000..9d2f86e4b --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/build-crew.mdx @@ -0,0 +1,48 @@ +--- +title: "Build Crew" +description: "Uma Crew é um grupo de agentes que trabalham juntos para completar uma tarefa." +icon: "people-arrows" +mode: "wide" +--- + +## Visão Geral + +[CrewAI AMP](https://app.crewai.com) simplifica o processo de **criação**, **implantação** e **gerenciamento** dos seus agentes de IA em ambientes de produção. + +## Primeiros Passos + + + +### 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/v1.15.1/pt-BR/enterprise/guides/capture_telemetry_logs.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/capture_telemetry_logs.mdx new file mode 100644 index 000000000..d370a90d3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/capture_telemetry_logs.mdx @@ -0,0 +1,57 @@ +--- +title: "Exportação OpenTelemetry" +description: "Exporte traces e logs das suas implantações CrewAI AMP para seu próprio coletor OpenTelemetry" +icon: "magnifying-glass-chart" +mode: "wide" +--- + +O CrewAI AMP pode exportar **traces** e **logs** do OpenTelemetry das suas implantações diretamente para seu próprio coletor. Isso permite que você monitore o desempenho dos agentes, rastreie chamadas de LLM e depure problemas usando sua stack de observabilidade existente. + +Os dados de telemetria seguem as [convenções semânticas GenAI do OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/) além de atributos adicionais específicos do CrewAI. + + +OpenTelemetry é o **caminho de observabilidade recomendado** — neutro em relação a fornecedores, funciona com qualquer backend compatível com OTLP (Grafana, Honeycomb, NewRelic, seu próprio coletor). Se você usa especificamente o Datadog, veja o guia dedicado [Integração com Datadog](./datadog), que cobre tanto o caminho do Datadog Agent quanto o ingest OTLP do Datadog. + + +## Pré-requisitos + + + + Sua organização deve ter uma conta CrewAI AMP ativa. + + + Você precisa de um endpoint de coletor compatível com OpenTelemetry (por exemplo, seu próprio OTel Collector, Datadog, Grafana ou qualquer backend compatível com OTLP). + + + +## Configurando um coletor + +1. No CrewAI AMP, vá para **Settings** > **OpenTelemetry Collectors**. +2. Clique em **Add Collector**. +3. Selecione uma integração: + - **OpenTelemetry Traces** e **OpenTelemetry Logs** — exporte para qualquer coletor ou backend compatível com OTLP. + - **Datadog** — envie traces diretamente para a ingestão OTLP do Datadog, sem precisar de um coletor separado ou do Datadog Agent. +4. Configure a conexão. Os campos dependem da integração selecionada: + + + + **OpenTelemetry Traces** e **OpenTelemetry Logs** são integrações separadas que compartilham os mesmos campos — escolha a que corresponde ao sinal que você quer exportar. + + - **Endpoint** — O endpoint OTLP do seu coletor (por exemplo, `https://otel-collector.example.com:4317`). + - **Service Name** — Um nome para identificar este serviço na sua plataforma de observabilidade. + - **Custom Headers** *(opcional)* — Adicione headers de autenticação ou roteamento como pares chave-valor. + - **Certificate** *(opcional)* — Forneça um certificado TLS se o seu coletor exigir um. + + ![Configuração do coletor OpenTelemetry](/images/crewai-otel-collector-opentelemetry.png) + + + Para configurar o Datadog, veja o guia dedicado [Integração com Datadog](./datadog) — ele cobre tanto o caminho do Datadog Agent (recomendado, mais barato para volumes altos de log) quanto o ingest OTLP do Datadog, com os passos completos de configuração do coletor. + + + +5. *(opcional)* Clique em **Test Connection** para verificar se o CrewAI consegue acessar o endpoint com as credenciais fornecidas. +6. Clique em **Save**. + + + Você pode adicionar múltiplos coletores — por exemplo, um para traces e outro para logs, ou enviar para diferentes backends para diferentes propósitos. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/custom-mcp-server.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/custom-mcp-server.mdx new file mode 100644 index 000000000..cb24baed8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/custom-mcp-server.mdx @@ -0,0 +1,136 @@ +--- +title: "Servidores MCP Personalizados" +description: "Conecte seus próprios servidores MCP ao CrewAI AMP com acesso público, autenticação por token ou OAuth 2.0" +icon: "plug" +mode: "wide" +--- + +O CrewAI AMP suporta a conexão com qualquer servidor MCP que implemente o [Model Context Protocol](https://modelcontextprotocol.io/). Você pode conectar servidores públicos que não exigem autenticação, servidores protegidos por chave de API ou token bearer, e servidores que utilizam OAuth 2.0 para acesso delegado seguro. + +## Pré-requisitos + + + + Você precisa de uma conta ativa no [CrewAI AMP](https://app.crewai.com). + + + A URL do servidor MCP que você deseja conectar. O servidor deve ser acessível pela internet e suportar transporte Streamable HTTP. + + + +## Adicionando um Servidor MCP Personalizado + + + + Navegue até **Tools & Integrations** no menu lateral esquerdo do CrewAI AMP e selecione a aba **Connections**. + + + + Clique no botão **Add Custom MCP Server**. Um diálogo aparecerá com o formulário de configuração. + + + + - **Name** (obrigatório): Um nome descritivo para seu servidor MCP (ex.: "Meu Servidor de Ferramentas Internas"). + - **Description**: Um resumo opcional do que este servidor MCP fornece. + - **Server URL** (obrigatório): A URL completa do endpoint do seu servidor MCP (ex.: `https://my-server.example.com/mcp`). + + + + Selecione um dos três métodos de autenticação disponíveis com base em como seu servidor MCP está protegido. Veja as seções abaixo para detalhes sobre cada método. + + + + Se seu servidor MCP requer headers adicionais em cada requisição (ex.: identificadores de tenant ou headers de roteamento), clique em **+ Add Header** e forneça o nome e valor do header. Você pode adicionar múltiplos headers personalizados. + + + + Clique em **Create MCP Server** para salvar a conexão. Seu servidor MCP personalizado aparecerá na lista de Connections e suas ferramentas estarão disponíveis para uso nas suas crews. + + + +## Métodos de Autenticação + +### Sem Autenticação + +Escolha esta opção quando seu servidor MCP é publicamente acessível e não requer nenhuma credencial. Isso é comum para servidores open-source ou servidores internos rodando atrás de uma VPN. + +### Token de Autenticação + +Use este método quando seu servidor MCP é protegido por uma chave de API ou token bearer. + + + Servidor MCP Personalizado com Token de Autenticação + + +| Campo | Obrigatório | Descrição | +|-------|-------------|-----------| +| **Header Name** | Sim | O nome do header HTTP que carrega o token (ex.: `X-API-Key`, `Authorization`). | +| **Value** | Sim | Sua chave de API ou token bearer. | +| **Add to** | Não | Onde anexar a credencial — **Header** (padrão) ou **Query parameter**. | + + +Se seu servidor espera um token `Bearer` no header `Authorization`, defina o Header Name como `Authorization` e o Value como `Bearer `. + + +### OAuth 2.0 + +Use este método para servidores MCP que requerem autorização OAuth 2.0. O CrewAI gerenciará todo o fluxo OAuth, incluindo a renovação de tokens. + + + Servidor MCP Personalizado com OAuth 2.0 + + +| Campo | Obrigatório | Descrição | +|-------|-------------|-----------| +| **Redirect URI** | — | Preenchido automaticamente e somente leitura. Copie esta URI e registre-a como URI de redirecionamento autorizada no seu provedor OAuth. | +| **Authorization Endpoint** | Sim | A URL para onde os usuários são enviados para autorizar o acesso (ex.: `https://auth.example.com/oauth/authorize`). | +| **Token Endpoint** | Sim | A URL usada para trocar o código de autorização por um token de acesso (ex.: `https://auth.example.com/oauth/token`). | +| **Client ID** | Sim | O Client ID OAuth emitido pelo seu provedor. | +| **Client Secret** | Não | O Client Secret OAuth. Não é necessário para clientes públicos usando PKCE. | +| **Scopes** | Não | Lista de escopos separados por espaço a solicitar (ex.: `read write`). | +| **Token Auth Method** | Não | Como as credenciais do cliente são enviadas ao trocar tokens — **Standard (POST body)** ou **Basic Auth (header)**. Padrão é Standard. | +| **PKCE Supported** | Não | Ative se seu provedor OAuth suporta Proof Key for Code Exchange. Recomendado para maior segurança. | + + +**Discover OAuth Config**: Se seu provedor OAuth suporta OpenID Connect Discovery, clique no link **Discover OAuth Config** para preencher automaticamente os endpoints de autorização e token a partir da URL `/.well-known/openid-configuration` do provedor. + + +#### Configurando OAuth 2.0 Passo a Passo + + + + Copie a **Redirect URI** exibida no formulário e adicione-a como URI de redirecionamento autorizada nas configurações do seu provedor OAuth. + + + + Preencha o **Authorization Endpoint**, **Token Endpoint**, **Client ID** e, opcionalmente, o **Client Secret** e **Scopes**. + + + + Selecione o **Token Auth Method** apropriado. A maioria dos provedores usa o padrão **Standard (POST body)**. Alguns provedores mais antigos requerem **Basic Auth (header)**. + + + + Marque **PKCE Supported** se seu provedor suporta. O PKCE adiciona uma camada extra de segurança ao fluxo de código de autorização e é recomendado para todas as novas integrações. + + + + Clique em **Create MCP Server**. Você será redirecionado ao seu provedor OAuth para autorizar o acesso. Uma vez autorizado, o CrewAI armazenará os tokens e os renovará automaticamente conforme necessário. + + + +## Usando Seu Servidor MCP Personalizado + +Uma vez conectado, as ferramentas do seu servidor MCP personalizado aparecem junto com as conexões integradas na página **Tools & Integrations**. Você pode: + +- **Atribuir ferramentas a agentes** nas suas crews, assim como qualquer outra ferramenta CrewAI. +- **Gerenciar visibilidade** para controlar quais membros da equipe podem usar o servidor. +- **Editar ou remover** a conexão a qualquer momento na lista de Connections. + + +Se seu servidor MCP ficar inacessível ou as credenciais expirarem, as chamadas de ferramentas usando esse servidor falharão. Certifique-se de que a URL do servidor seja estável e as credenciais estejam atualizadas. + + + + Entre em contato com nossa equipe de suporte para assistência com configuração ou resolução de problemas de servidores MCP personalizados. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/datadog.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/datadog.mdx new file mode 100644 index 000000000..391c11eac --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/datadog.mdx @@ -0,0 +1,295 @@ +--- +title: "Integração com Datadog" +description: "Monitore implantações CrewAI AMP auto-hospedadas no Datadog via Datadog Agent ou ingest OTLP do Datadog — ambos os caminhos entregam as mesmas facetas estruturadas para importar o dashboard de operações pronto." +icon: "dog" +mode: "wide" +--- + + +**Tradução em andamento** — conteúdo exibido em inglês. + + +CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes. + + +For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs). + + +## Choose a path + +CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure. + + + + The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. With `CREWAI_LOG_FORMAT=json` set, each log event ships as a single billable line with structured attributes. + + **Setup:** + 1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`). + 2. Set `CREWAI_LOG_FORMAT=json` as an **automation environment variable** in CrewAI AMP (open your automation → **Settings → Environment Variables**) so each log event is a single line instead of a multi-line traceback. AMP propagates the value to every container in the deployment (API + workers) — don't set it on the container or host directly. See [Enabling JSON output](#enabling-json-output) below for the AMP UI walkthrough and the [log schema reference](#log-schema-reference) for the full field contract. + 3. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion). + + **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale. + + + CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend. + + **Setup:** + 1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**. + 2. Configure the connection: + - **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/): + - `otlp.datadoghq.com` (US1) + - `otlp.us3.datadoghq.com` (US3) + - `otlp.us5.datadoghq.com` (US5) + - `otlp.datadoghq.eu` (EU1) + - `otlp.ap1.datadoghq.com` (AP1) + - **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + 3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list. + 4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step. + + ![Datadog collector configuration](/images/crewai-otel-collector-datadog.png) + + **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup. + + + +Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice. + +## Log schema reference + + +This schema applies to the **Datadog Agent path** — stdout JSON logs produced when `CREWAI_LOG_FORMAT=json` is set. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs). + + +When `CREWAI_LOG_FORMAT=json` is set, every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines. + +### Why JSON output + + + + Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field. + + + Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration. + + + Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces. + + + The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed. + + + +### Enabling JSON output + +`CREWAI_LOG_FORMAT=json` must be set as an **automation environment variable** in CrewAI AMP — it is **not** a container, host, or Docker setting. Open your automation in AMP, click the **Settings** icon, and add the variable under the **Environment Variables** section. AMP applies the value to every container in the deployment (API + workers) on the next restart. See [Update Your Crew](./update-crew) for the full UI walkthrough with screenshots. + +```shell +CREWAI_LOG_FORMAT=json +``` + +Restart the deployment to pick up the change. Every log line on stdout from that point on is a single JSON object. + + + The default value is `text`, which preserves the legacy human-readable line format byte-for-byte. Setting any value other than `json` falls back to text mode. There is no migration step — the variable is read at process start and the format switches immediately. + + +### Example events + +A single info-level log inside an active automation kickoff: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:23.482914Z", + "level": "INFO", + "logger": "crewai_enterprise.utilities.pii_redaction", + "crewai_version": "1.14.7", + "msg": "PII tracking state reset (engines preserved)", + "automation_id": "12", + "task_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow" +} +``` + +An error with a Python exception is collapsed into a single event with the traceback as a string: + +```json +{ + "schema": "v1", + "ts": "2026-06-17T16:14:31.218450Z", + "level": "ERROR", + "logger": "api.tasks.flow_run_task", + "crewai_version": "1.14.7", + "msg": "Flow execution failed", + "automation_id": "12", + "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711", + "automation_name": "research_flow", + "exception": { + "type": "ValueError", + "message": "Topic cannot be empty", + "stacktrace": "Traceback (most recent call last):\n File \"/app/flow.py\", line 42, in summarize\n ...\nValueError: Topic cannot be empty\n" + } +} +``` + +The same error in legacy text mode would have produced ~25 separate log events (one per traceback line) — all of which the backend would bill and index individually. + +### Schema v1 fields + +Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded. + +| Field | Type | Always present | Source | +|-------|------|----------------|--------| +| `schema` | string | Yes | Constant `"v1"`. Increment indicates a breaking schema change. | +| `ts` | string (ISO-8601 UTC, microseconds) | Yes | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`. | +| `level` | string | Yes | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. | +| `logger` | string | Yes | Dotted logger name, e.g. `api.tasks.flow_run_task`. | +| `crewai_version` | string | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`. | +| `msg` | string | Yes | Rendered log message (after `%`-formatting / `{}`-formatting). | +| `automation_id` | string | When `CREWAI_PLUS_ID` env var is set | Numeric deployment ID (AMP provisions this on every container). | +| `task_id` | string | On Celery worker logs | Celery task UUID, or `"no-task"` for non-task contexts. | +| `kickoff_id` | string | Inside an automation kickoff | UUID of the current kickoff. | +| `execution_id` | string | Inside an automation kickoff | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. | +| `automation_name` | string | Inside an automation kickoff | Human-readable automation/flow name, e.g. `"research_flow"`. | +| `trace_id` | string (32-hex) | Inside a recording OpenTelemetry span | Hex trace ID. Omitted when no span is active. | +| `span_id` | string (16-hex) | Inside a recording OpenTelemetry span | Hex span ID. Omitted when no span is active. | +| `exception` | object | When the log record has `exc_info` | `{type, message, stacktrace}` — full traceback as a single escaped string. | + + + Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable. + + +### Stability promise + +The `schema` field declares the contract. Within `v1`, CrewAI commits to: + +- **Never removing a field** that customers may have built queries or dashboards against. +- **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle. +- **Adding new fields** at any time. Consumers should ignore unknown top-level keys. + +When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate. + +## Prerequisite: promote facets + +Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account. + + + + Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event. + + + Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**. + + - `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id` + - `crewai_version`, `model_id` + - `exception.type`, `exception.message` + + Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard. + + + +## Import the dashboard + + + + Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/edge/en/enterprise/guides/datadog_dashboard.json) to your machine. + + + Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**. + + + Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**. + + Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range. + + + + + Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI. + + +## What you get + +The dashboard is organized into four sections plus a placeholder for a custom drill-down widget: + +| Section | Widgets | Useful for | +|---------|---------|------------| +| **Header** | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%). | +| **Throughput** | Executions per Hour by Automation (top 10, stacked bars) | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume. | +| **Errors** | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting. | +| **Cost** | Total Tokens per Hour by Model (input + output, stacked area) | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. | +| **Drill-Down** | _(empty placeholder)_ | See [Customization](#customize) for adding a recent-errors log stream here. | + +Three template variables at the top of the dashboard re-scope every widget at once: + +- **`$automation`** — filter to a single automation by name. +- **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior). +- **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account). + +## Verify ingestion + +Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path: + + + + Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated. + + If nothing appears, confirm `CREWAI_LOG_FORMAT=json` is set under your automation's **Environment Variables** in AMP, the deployment was restarted after the change, and the Datadog Agent is tailing container stdout. + + + Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets). + + If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved. + + + +## Customize + +The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing. + +### Add a Recent Errors log stream + +The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures: + +1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group. +2. Drag in a **Log Stream** widget. +3. Set the filter query to `status:error $automation $version $service`. +4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`. +5. Sort by most recent, limit to 25 entries. + +Clicking any row jumps to Logs Explorer with the same filter pre-applied. + +### Add p95 latency + +Logs don't include execution duration by default. Two ways to add a latency widget: + +- **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration. +- **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM. + +### Re-scope to multiple deployments + +The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +|---------|--------------|-----| +| All widgets show "No data" | Facets aren't promoted | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field. | +| Error Rate widget shows `NaN` | No executions in the time window | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets. | +| Throughput chart is flat at the same value | Logs aren't reaching Datadog | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path). | +| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work | The `crewai_version` field was added alongside JSON output. Older deployments running text mode (or older AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. | +| Template variables don't filter widgets | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`. | + +## Next steps + + + + Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends. + + + Reference for customizing widget queries against the structured facets above. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/deploy-to-amp.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/deploy-to-amp.mdx new file mode 100644 index 000000000..f6e9acf09 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/deploy-to-amp.mdx @@ -0,0 +1,450 @@ +--- +title: "Deploy para AMP" +description: "Implante seu Crew ou Flow no CrewAI AMP" +icon: "rocket" +mode: "wide" +--- + + + Depois de criar um Crew ou Flow localmente (ou pelo Crew Studio), o próximo passo é + implantá-lo na plataforma CrewAI AMP. Este guia cobre múltiplos métodos de + implantação para ajudá-lo a escolher a melhor abordagem para o seu fluxo de trabalho. + + +## Pré-requisitos + + + + Você deve ter um Crew ou Flow funcionando localmente com sucesso. + Siga nosso [guia de preparação](/pt-BR/enterprise/guides/prepare-for-deployment) para verificar a estrutura do seu projeto. + + + Seu código deve estar em um repositório do GitHub (para o método de integração com GitHub). + + + + + **Crews vs Flows**: Ambos os tipos de projeto podem ser implantados como "automações" no CrewAI AMP. + O processo de implantação é o mesmo, mas eles têm estruturas de projeto diferentes. + Veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment) para detalhes. + + +## Opção 1: Implantar Usando o CrewAI CLI + +A CLI fornece a maneira mais rápida de implantar Crews ou Flows desenvolvidos localmente na plataforma AMP. +A CLI detecta automaticamente o tipo do seu projeto a partir do `pyproject.toml` e faz o build adequadamente. + + + + 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 AMP: + + ```bash + # Se já possui uma conta CrewAI AMP, ou deseja criar uma: + crewai login + ``` + + Ao executar qualquer um dos comandos, a CLI irá: + 1. Exibir uma URL e um código de dispositivo único + 2. Abrir seu navegador para a página de autenticação + 3. Solicitar a confirmação do dispositivo + 4. Completar o processo de autenticação + + Após a autenticação bem-sucedida, você verá uma mensagem de confirmação no terminal! + + + + + + 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 cerca de 1 minuto. + + + + + +## 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 ou Flows diretamente pela interface web do CrewAI AMP conectando sua conta do GitHub. Esta abordagem não requer utilizar a CLI na sua máquina local. A plataforma detecta automaticamente o tipo do seu projeto e trata o build adequadamente. + + + + + +Você precisa enviar seu crew para um repositório do GitHub. Caso ainda não tenha criado um crew, você pode [seguir este tutorial](/pt-BR/quickstart). + + + + + + 1. Faça login em [CrewAI AMP](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) + + + + Se seu Crew ou Flow estiver dentro de uma subpasta de monorepo, expanda + **Advanced** e defina um diretório de trabalho antes de implantar. Consulte + [Implantações em Monorepo](/pt-BR/enterprise/guides/monorepo-deployments). + + + + + + + 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) + + + + Usando pacotes Python privados? Você também precisará adicionar suas credenciais de registro aqui. + Consulte [Registros de Pacotes Privados](/pt-BR/enterprise/guides/private-package-registry) para as variáveis necessárias. + + + + + + + 1. Clique no botão "Deploy" para iniciar o processo de implantação + 2. Você pode monitorar o progresso pela barra de progresso + 3. A primeira implantação geralmente demora cerca de 1 minuto + + + ![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 + + + + + +## Opção 3: Reimplantar Usando API (Integração CI/CD) + +Para implantações automatizadas em pipelines CI/CD, você pode usar a API do CrewAI para acionar reimplantações de crews existentes. Isso é particularmente útil para GitHub Actions, Jenkins ou outros workflows de automação. + + + + + Navegue até as configurações da sua conta CrewAI AMP para gerar um token de API: + + 1. Acesse [app.crewai.com](https://app.crewai.com) + 2. Clique em **Settings** → **Account** → **Personal Access Token** + 3. Gere um novo token e copie-o com segurança + 4. Armazene este token como um secret no seu sistema CI/CD + + + + + + Localize o identificador único do seu crew implantado: + + 1. Acesse **Automations** no seu dashboard CrewAI AMP + 2. Selecione sua automação/crew existente + 3. Clique em **Additional Details** + 4. Copie o **UUID** - este identifica sua implantação específica do crew + + + + + + Use o endpoint da API de Deploy para acionar uma reimplantação: + + ```bash + curl -i -X POST \ + -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \ + https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy + + # HTTP/2 200 + # content-type: application/json + # + # { + # "uuid": "your-automation-uuid", + # "status": "Deploy Enqueued", + # "public_url": "https://your-crew-deployment.crewai.com", + # "token": "your-bearer-token" + # } + ``` + + + Se sua automação foi criada originalmente conectada ao Git, a API automaticamente puxará as últimas alterações do seu repositório antes de reimplantar. + + + + + + + Aqui está um workflow do GitHub Actions com gatilhos de implantação mais complexos: + + ```yaml + name: Deploy CrewAI Automation + + on: + push: + branches: [ main ] + pull_request: + types: [ labeled ] + release: + types: [ published ] + + jobs: + deploy: + runs-on: ubuntu-latest + if: | + (github.event_name == 'push' && github.ref == 'refs/heads/main') || + (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) || + (github.event_name == 'release') + steps: + - name: Trigger CrewAI Redeployment + run: | + curl -X POST \ + -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \ + https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy + ``` + + + Adicione `CREWAI_PAT` e `CREWAI_AUTOMATION_UUID` como secrets do repositório. Para implantações de PR, adicione um label "deploy" para acionar o workflow. + + + + + + +## Interaja com Sua Automação Implantada + +Após a implantação, você pode acessar seu crew através de: + +1. **REST API**: A plataforma gera um endpoint HTTPS exclusivo com estas rotas principais: + + - `/inputs`: Lista os parâmetros de entrada requeridos + - `/kickoff`: Inicia uma execução com os inputs fornecidos + - `/status/{kickoff_id}`: Consulta o status da execução + +2. **Interface Web**: Acesse [app.crewai.com](https://app.crewai.com) para visualizar: + - **Aba Status**: Informações da implantação, detalhes do endpoint da API e token de autenticação + - **Aba Run**: Visualização da estrutura do seu crew + - **Aba Executions**: Histórico de todas as execuções + - **Aba Metrics**: Análises de desempenho + - **Aba Traces**: Insights detalhados das execuções + +### Dispare uma Execução + +No dashboard Enterprise, você pode: + +1. Clicar no nome do seu crew para abrir seus detalhes +2. Selecionar "Trigger Crew" na interface de gerenciamento +3. Inserir os inputs necessários no modal exibido +4. Monitorar o progresso à medida que a execução avança pelo pipeline + +### Monitoramento e Análises + +A plataforma Enterprise oferece recursos abrangentes de observabilidade: + +- **Gestão das Execuções**: Acompanhe execuções ativas e concluídas +- **Traces**: Quebra detalhada de cada execução +- **Métricas**: Uso de tokens, tempos de execução e custos +- **Visualização em Linha do Tempo**: Representação visual das sequências de tarefas + +### Funcionalidades Avançadas + +A plataforma Enterprise também oferece: + +- **Gerenciamento de Variáveis de Ambiente**: Armazene e gerencie com segurança as chaves de API +- **Conexões com LLM**: Configure integrações com diversos provedores de LLM +- **Repositório Custom Tools**: Crie, compartilhe e instale ferramentas +- **Crew Studio**: Monte crews via interface de chat sem escrever código + +## Solução de Problemas em Falhas de Implantação + +Se sua implantação falhar, verifique estes problemas comuns: + +### Falhas de Build + +#### Arquivo uv.lock Ausente + +**Sintoma**: Build falha no início com erros de resolução de dependências + +**Solução**: Gere e faça commit do arquivo lock: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + + + O arquivo `uv.lock` é obrigatório para todas as implantações. Sem ele, a plataforma + não consegue instalar suas dependências de forma confiável. + + +#### Estrutura de Projeto Incorreta + +**Sintoma**: Erros "Could not find entry point" ou "Module not found" + +**Solução**: Verifique se seu projeto corresponde à estrutura esperada: + +- **Crews JSON-first**: Mantenha `crew.jsonc` ou `crew.json` e `agents/` na raiz do projeto +- **Crews clássicas**: Use `src/project_name/main.py` com uma função de entrada `run()` +- **Flows**: Use `src/project_name/main.py` com uma função de entrada `kickoff()` + +Veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment) para diagramas de estrutura detalhados. + +#### Decorador CrewBase Ausente em uma Crew Clássica + +**Sintoma**: Erros "Crew not found", "Config not found" ou erros de configuração de agent/task + +**Solução**: Para crews clássicas Python/YAML, certifique-se de que todas as classes crew usam o decorador `@CrewBase`. Crews JSON-first não precisam desse decorador. + +```python +from crewai.project import CrewBase, agent, crew, task + +@CrewBase # Este decorador é OBRIGATÓRIO +class YourCrew(): + """Descrição do seu crew""" + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + # ... resto da definição do crew +``` + + + Isso se aplica a classes crew Python clássicas, incluindo crews clássicas embutidas em projetos Flow. + Crews JSON-first são validadas a partir de `crew.jsonc` e `agents/`. + + +#### Tipo Incorreto no pyproject.toml + +**Sintoma**: Build tem sucesso mas falha em runtime, ou comportamento inesperado + +**Solução**: Verifique se a seção `[tool.crewai]` corresponde ao tipo do seu projeto: + +```toml +# Para projetos Crew: +[tool.crewai] +type = "crew" + +# Para projetos Flow: +[tool.crewai] +type = "flow" +``` + +### Falhas de Runtime + +#### Falhas de Conexão com LLM + +**Sintoma**: Erros de chave API, "model not found" ou falhas de autenticação + +**Solução**: +1. Verifique se a chave API do seu provedor LLM está corretamente definida nas variáveis de ambiente +2. Certifique-se de que os nomes das variáveis de ambiente correspondem ao que seu código espera +3. Teste localmente com exatamente as mesmas variáveis de ambiente antes de implantar + +#### Erros de Execução do Crew + +**Sintoma**: Crew inicia mas falha durante a execução + +**Solução**: +1. Verifique os logs de execução no dashboard AMP (aba Traces) +2. Verifique se todas as ferramentas têm as chaves API necessárias configuradas +3. Para crews JSON-first, valide `crew.jsonc` e os arquivos referenciados em `agents/` +4. Para crews clássicas, verifique se `agents.yaml` e `tasks.yaml` são válidos + + + Entre em contato com nossa equipe de suporte para ajuda com questões de + implantação ou dúvidas sobre a plataforma AMP. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/enable-crew-studio.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/enable-crew-studio.mdx new file mode 100644 index 000000000..37d63915a --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/enable-crew-studio.mdx @@ -0,0 +1,179 @@ +--- +title: "Ativar Crew Studio" +description: "Ativando o Crew Studio no CrewAI AMP" +icon: "comments" +mode: "wide" +--- + + + 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 AMP + +## 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 AMP 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 AMP. + + + + 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 AMP + - 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 AMP. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/gmail-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/gmail-trigger.mdx new file mode 100644 index 000000000..f5a2115c1 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/gmail-trigger.mdx @@ -0,0 +1,97 @@ +--- +title: "Gmail Trigger" +description: "Trigger automations when Gmail events occur (e.g., new emails, labels)." +icon: "envelope" +mode: "wide" +--- + +## Overview + +Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter. + + + Make sure Gmail is connected in Tools & Integrations and the trigger is + enabled for your deployment. + + +## Enabling the Gmail Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Gmail** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Process new emails + +When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload. + +```python +@CrewBase +class GmailProcessingCrew: + @agent + def parser(self) -> Agent: + return Agent( + config=self.agents_config['parser'], + ) + + @task + def parse_gmail_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_gmail_payload'], + agent=self.parser(), + ) + + @task + def act_on_email(self) -> Task: + return Task( + config=self.tasks_config['act_on_email'], + agent=self.parser(), + ) +``` + +The Gmail payload will be available via the standard context mechanisms. + +### Testando Localmente + +Teste sua integração de trigger do Gmail localmente usando a CLI da CrewAI: + +```bash +# Visualize todos os triggers disponíveis +crewai triggers list + +# Simule um trigger do Gmail com payload realista +crewai triggers run gmail/new_email_received +``` + +O comando `crewai triggers run` executará sua crew com um payload completo do Gmail, permitindo que você teste sua lógica de parsing antes do deployment. + + + Use `crewai triggers run gmail/new_email_received` (não `crewai run`) para + simular execução de trigger durante o desenvolvimento. Após o deployment, sua + crew receberá automaticamente o payload do trigger. + + +## Monitoring Executions + +Track history and performance of triggered runs: + + + List of executions triggered by automation + + +## Troubleshooting + +- Ensure Gmail is connected in Tools & Integrations +- Verify the Gmail Trigger is enabled on the Triggers tab +- Teste localmente com `crewai triggers run gmail/new_email_received` para ver a estrutura exata do payload +- Check the execution logs and confirm the payload is passed as `crewai_trigger_payload` +- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/google-calendar-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/google-calendar-trigger.mdx new file mode 100644 index 000000000..852d3a2a8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/google-calendar-trigger.mdx @@ -0,0 +1,83 @@ +--- +title: "Google Calendar Trigger" +description: "Kick off crews when Google Calendar events are created, updated, or cancelled" +icon: "calendar" +mode: "wide" +--- + +## Overview + +Use the Google Calendar trigger to launch automations whenever calendar events change. Common use cases include briefing a team before a meeting, notifying stakeholders when a critical event is cancelled, or summarizing daily schedules. + + + Make sure Google Calendar is connected in **Tools & Integrations** and enabled + for the deployment you want to automate. + + +## Enabling the Google Calendar Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Google Calendar** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize meeting details + +The snippet below mirrors the `calendar-event-crew.py` example in the trigger repository. It parses the payload, analyses the attendees and timing, and produces a meeting brief for downstream tools. + +```python +from calendar_event_crew import GoogleCalendarEventTrigger + +crew = GoogleCalendarEventTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": calendar_payload, +}) +print(result.raw) +``` + +Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields. + +## Testando Localmente + +Teste sua integração de trigger do Google Calendar localmente usando a CLI da CrewAI: + +```bash +# Visualize todos os triggers disponíveis +crewai triggers list + +# Simule um trigger do Google Calendar com payload realista +crewai triggers run google_calendar/event_changed +``` + +O comando `crewai triggers run` executará sua crew com um payload completo do Calendar, permitindo que você teste sua lógica de parsing antes do deployment. + + + Use `crewai triggers run google_calendar/event_changed` (não `crewai run`) + para simular execução de trigger durante o desenvolvimento. Após o deployment, + sua crew receberá automaticamente o payload do trigger. + + +## Monitoring Executions + +The **Executions** list in the deployment dashboard tracks every triggered run and surfaces payload metadata, output summaries, and errors. + + + List of executions triggered by automation + + +## Troubleshooting + +- Ensure the correct Google account is connected and the trigger is enabled +- Teste localmente com `crewai triggers run google_calendar/event_changed` para ver a estrutura exata do payload +- Confirm your workflow handles all-day events (payloads use `start.date` and `end.date` instead of timestamps) +- Check execution logs if reminders or attendee arrays are missing—calendar permissions can limit fields in the payload +- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/google-drive-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/google-drive-trigger.mdx new file mode 100644 index 000000000..90f8f4ff8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/google-drive-trigger.mdx @@ -0,0 +1,80 @@ +--- +title: "Google Drive Trigger" +description: "Respond to Google Drive file events with automated crews" +icon: "folder" +mode: "wide" +--- + +## Overview + +Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change. + + + Connect Google Drive in **Tools & Integrations** and confirm the trigger is + enabled for the automation you want to monitor. + + +## Enabling the Google Drive Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Google Drive** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize file activity + +The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary. + +```python +from drive_file_crew import GoogleDriveFileTrigger + +crew = GoogleDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": drive_payload, +}) +``` + +## Testando Localmente + +Teste sua integração de trigger do Google Drive localmente usando a CLI da CrewAI: + +```bash +# Visualize todos os triggers disponíveis +crewai triggers list + +# Simule um trigger do Google Drive com payload realista +crewai triggers run google_drive/file_changed +``` + +O comando `crewai triggers run` executará sua crew com um payload completo do Drive, permitindo que você teste sua lógica de parsing antes do deployment. + + + Use `crewai triggers run google_drive/file_changed` (não `crewai run`) para + simular execução de trigger durante o desenvolvimento. Após o deployment, sua + crew receberá automaticamente o payload do trigger. + + +## Monitoring Executions + +Track history and performance of triggered runs with the **Executions** list in the deployment dashboard. + + + List of executions triggered by automation + + +## Troubleshooting + +- Verify Google Drive is connected and the trigger toggle is enabled +- Teste localmente com `crewai triggers run google_drive/file_changed` para ver a estrutura exata do payload +- If a payload is missing permission data, ensure the connected account has access to the file or folder +- The trigger sends file IDs only; use the Drive API if you need to fetch binary content during the crew run +- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/hubspot-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/hubspot-trigger.mdx new file mode 100644 index 000000000..8bc1a1340 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/hubspot-trigger.mdx @@ -0,0 +1,65 @@ +--- +title: "Gatilho HubSpot" +description: "Acione crews do CrewAI diretamente a partir de Workflows do HubSpot" +icon: "hubspot" +mode: "wide" +--- + +Este guia fornece um processo passo a passo para configurar gatilhos do HubSpot para o CrewAI AMP, permitindo iniciar crews diretamente a partir de Workflows do HubSpot. + +## Pré-requisitos + +- Uma conta CrewAI AMP +- Uma conta HubSpot com o recurso de [Workflows do HubSpot](https://knowledge.hubspot.com/workflows/create-workflows) + +## Etapas de Configuração + + + + - Faça login na sua `Conta CrewAI AMP > Triggers` - Selecione `HubSpot` na + lista de gatilhos disponíveis - Escolha a conta HubSpot que deseja conectar + ao CrewAI AMP - Siga as instruções na tela para autorizar o acesso do CrewAI + AMP à sua conta HubSpot - Uma mensagem de confirmação aparecerá assim que o + HubSpot estiver conectado com sucesso ao CrewAI AMP + + + - 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). diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/human-in-the-loop.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/human-in-the-loop.mdx new file mode 100644 index 000000000..7d853d1e4 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/human-in-the-loop.mdx @@ -0,0 +1,157 @@ +--- +title: "Workflows HITL" +description: "Aprenda como implementar workflows Human-In-The-Loop no CrewAI para decisões aprimoradas" +icon: "user-check" +mode: "wide" +--- + +Human-In-The-Loop (HITL) é uma abordagem poderosa que combina inteligência artificial com expertise humana para aprimorar a tomada de decisão e melhorar os resultados das tarefas. Este guia mostra como implementar HITL dentro do CrewAI Enterprise. + +## Abordagens HITL no CrewAI + +CrewAI oferece duas abordagens para implementar workflows human-in-the-loop: + +| Abordagem | Melhor Para | Versão | +|----------|----------|---------| +| **Baseada em Flow** (decorador `@human_feedback`) | Produção com UI Enterprise, workflows email-first, recursos completos da plataforma | **1.8.0+** | +| **Baseada em Webhook** | Integrações customizadas, sistemas externos (Slack, Teams, etc.), configurações legadas | Todas as versões | + +## HITL Baseado em Flow com Plataforma Enterprise + + +O decorador `@human_feedback` requer **CrewAI versão 1.8.0 ou superior**. + + +Ao usar o decorador `@human_feedback` em seus Flows, o CrewAI Enterprise oferece um **sistema HITL email-first** que permite que qualquer pessoa com um endereço de email responda a solicitações de revisão: + + + + Respondentes recebem notificações por email e podem responder diretamente—nenhum login necessário. + + + Revise e responda a solicitações HITL no dashboard Enterprise quando preferir. + + + Direcione solicitações para emails específicos com base em padrões de método ou obtenha do estado do flow. + + + Configure respostas automáticas de fallback quando nenhum humano responder dentro do timeout. + + + +### Principais Benefícios + +- **Respondentes externos**: Qualquer pessoa com email pode responder, mesmo não sendo usuário da plataforma +- **Atribuição dinâmica**: Obtenha o email do responsável do estado do flow (ex: `account_owner_email`) +- **Configuração simples**: Roteamento baseado em email é mais fácil de configurar do que gerenciamento de usuários/funções +- **Fallback do criador do deployment**: Se nenhuma regra de roteamento corresponder, o criador do deployment é notificado + + +Para detalhes de implementação do decorador `@human_feedback`, consulte o guia [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows). + + +## Configurando Workflows HITL Baseados em Webhook + +Para integrações customizadas com sistemas externos como Slack, Microsoft Teams ou suas próprias aplicações, você pode usar a abordagem baseada em webhook: + + + + 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 + + + + **Crítico: URLs de Webhook Devem Ser Fornecidas Novamente**: + Você **deve** fornecer as mesmas URLs de webhook (`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`) na chamada de resume que você usou na chamada de kickoff. As configurações de webhook **NÃO** são automaticamente transferidas do kickoff - elas devem ser explicitamente incluídas na solicitação de resume para continuar recebendo notificações de conclusão de tarefa, etapas do agente e conclusão do crew. + + + Exemplo de chamada resume com webhooks: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "Ótimo trabalho! Por favor, adicione mais detalhes.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **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 + +## Saiba Mais + + + + Explore os recursos completos da plataforma HITL para Flows, incluindo notificações por email, regras de roteamento, resposta automática e análises. + + + Guia de implementação para o decorador `@human_feedback` em seus Flows. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/kickoff-crew.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/kickoff-crew.mdx new file mode 100644 index 000000000..b5a0a1049 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/kickoff-crew.mdx @@ -0,0 +1,178 @@ +--- +title: "Kickoff Crew" +description: "Inicie um Crew no CrewAI AMP" +icon: "flag-checkered" +mode: "wide" +--- + +## Visão Geral + +Uma vez que você tenha implantado seu crew na plataforma CrewAI AMP, é possível iniciar execuções pela interface web ou pela API. Este guia aborda ambos os métodos. + +## Método 1: Usando a Interface Web + +### Passo 1: Navegue até seu Crew Implantado + +1. Faça login no [CrewAI AMP](https://app.crewai.com) +2. Clique no nome do crew na sua lista de projetos +3. Você será direcionado para a página de detalhes do crew + +![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 AMP. + +### Autenticação + +Todas as requisições à API exigem um bearer token para autenticação: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +Seu bearer token está disponível na aba Status na página de detalhes do seu crew. + +### Verificando o Status do Crew + +Antes de executar operações, você pode verificar se seu crew está funcionando corretamente: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +Uma resposta de sucesso trará uma mensagem indicando que o crew está operacional: + +``` +Healthy% +``` + +### Passo 1: Recuperar Entradas Necessárias + +Primeiro, descubra quais entradas seu crew exige: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +A resposta será um objeto JSON contendo um array de parâmetros de entrada obrigatórios, por exemplo: + +```json +{ "inputs": ["topic", "current_year"] } +``` + +Este exemplo mostra que este crew em particular requer dois inputs: `topic` e `current_year`. + +### Passo 2: Iniciar Execução + +Inicie a execução fornecendo os inputs obrigatórios: + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +A resposta incluirá um `kickoff_id` que você precisará para o acompanhamento: + +```json +{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" } +``` + +### Passo 3: Verificar Status da Execução + +Acompanhe o progresso da execução usando o kickoff_id: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv +``` + +## Gerenciando Execuções + +### Execuções de Longa Duração + +Para execuções que possam demandar mais tempo: + +1. Considere implementar um mecanismo de polling para verificar status periodicamente +2. Utilize webhooks (se disponíveis) para notificação quando a execução for concluída +3. Implemente tratamento de erros para possíveis timeouts + +### Contexto da Execução + +O contexto da execução inclui: + +- Inputs fornecidos no momento do kickoff +- Variáveis de ambiente configuradas durante o deploy +- Qualquer estado mantido entre as tarefas + +### Depuração de Execuções com Falha + +Se uma execução falhar: + +1. Verifique a aba "Executions" para logs detalhados +2. Avalie a aba "Traces" para detalhes passo a passo da execução +3. Procure por respostas LLM e uso de ferramentas nos detalhes do trace + + + Entre em contato com nossa equipe de suporte para obter ajuda com problemas de + execução ou dúvidas sobre a plataforma Enterprise. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/microsoft-teams-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/microsoft-teams-trigger.mdx new file mode 100644 index 000000000..7c3c6182f --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/microsoft-teams-trigger.mdx @@ -0,0 +1,70 @@ +--- +title: "Microsoft Teams Trigger" +description: "Kick off crews from Microsoft Teams chat activity" +icon: "microsoft" +mode: "wide" +--- + +## Overview + +Use the Microsoft Teams trigger to start automations whenever a new chat is created. Common patterns include summarizing inbound requests, routing urgent messages to support teams, or creating follow-up tasks in other systems. + + + Confirm Microsoft Teams is connected under **Tools & Integrations** and + enabled in the **Triggers** tab for your deployment. + + +## Enabling the Microsoft Teams Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Microsoft Teams** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize a new chat thread + +```python +from teams_chat_created_crew import MicrosoftTeamsChatTrigger + +crew = MicrosoftTeamsChatTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": teams_payload, +}) +print(result.raw) +``` + +The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team. + +## Testando Localmente + +Teste sua integração de trigger do Microsoft Teams localmente usando a CLI da CrewAI: + +```bash +# Visualize todos os triggers disponíveis +crewai triggers list + +# Simule um trigger do Microsoft Teams com payload realista +crewai triggers run microsoft_teams/teams_message_created +``` + +O comando `crewai triggers run` executará sua crew com um payload completo do Teams, permitindo que você teste sua lógica de parsing antes do deployment. + + + Use `crewai triggers run microsoft_teams/teams_message_created` (não `crewai + run`) para simular execução de trigger durante o desenvolvimento. Após o + deployment, sua crew receberá automaticamente o payload do trigger. + + +## Troubleshooting + +- Ensure the Teams connection is active; it must be refreshed if the tenant revokes permissions +- Teste localmente com `crewai triggers run microsoft_teams/teams_message_created` para ver a estrutura exata do payload +- Confirm the webhook subscription in Microsoft 365 is still valid if payloads stop arriving +- Review execution logs for payload shape mismatches—Graph notifications may omit fields when a chat is private or restricted +- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/monorepo-deployments.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/monorepo-deployments.mdx new file mode 100644 index 000000000..5e25a7dcd --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/monorepo-deployments.mdx @@ -0,0 +1,234 @@ +--- +title: "Implantações em Monorepo" +description: "Implante um Crew ou Flow a partir de uma subpasta em um repositório maior" +icon: "folder-tree" +mode: "wide" +--- + + + Use um diretório de trabalho quando seu Crew ou Flow estiver dentro de um + repositório maior. O CrewAI AMP valida, faz o build e executa a automação a + partir dessa subpasta em vez da raiz do repositório. + + +## Quando Usar + +Implantações em monorepo são úteis quando um repositório contém múltiplas +automações, pacotes compartilhados ou outro código de aplicação: + +```text +company-ai/ +|-- uv.lock +|-- packages/ +| `-- shared_tools/ +`-- crews/ + |-- support_agent/ + | |-- pyproject.toml + | |-- crew.jsonc + | `-- agents/ + | `-- support_agent.jsonc + `-- research_flow/ + |-- pyproject.toml + `-- src/ + `-- research_flow/ + `-- main.py +``` + +Para implantar `support_agent`, defina o diretório de trabalho como: + +```text +crews/support_agent +``` + +O AMP ainda baixa ou recebe o repositório inteiro, mas trata a pasta +selecionada como a raiz do projeto da automação. + +## O Que o Diretório de Trabalho Controla + +Quando um diretório de trabalho é definido, o AMP usa essa pasta para: + +- Validação do projeto, incluindo `pyproject.toml`, arquivos de crew JSON e qualquer ponto de entrada clássico de Crew ou Flow +- Instalação de dependências com `uv` +- O diretório de trabalho do processo em execução +- A variável de ambiente `CREW_ROOT_DIR` + +Deixar o campo vazio mantém o comportamento existente e usa a raiz do +repositório. + +## Fontes Suportadas + +Você pode definir um diretório de trabalho ao criar uma implantação a partir de: + +- Um repositório GitHub conectado +- Um repositório Git configurado no AMP +- Um upload de ZIP + + + Configure diretórios de trabalho na interface web do AMP. O fluxo + `crewai deploy create` da CLI não solicita esse campo. + + +Você também pode adicionar ou alterar o diretório de trabalho de uma implantação +existente pela página **Settings** da implantação. A alteração passa a valer no +próximo deploy. + + + Diretórios de trabalho e auto-deploy não podem ser usados juntos. Se uma + implantação tiver um diretório de trabalho, o auto-deploy fica desabilitado + para ela. Desative o auto-deploy antes de definir um diretório de trabalho. + + +## Configurar uma Nova Implantação + + + + No CrewAI AMP, crie uma nova implantação e escolha sua fonte: GitHub, Git + Repository ou upload de ZIP. + + + + Escolha o repositório e a branch que contêm seu monorepo, ou envie um ZIP + cuja raiz contenha os arquivos do monorepo. + + + + Expanda a seção **Advanced** no formulário de deploy. + + + + Informe o caminho da raiz do repositório até o projeto Crew ou Flow: + + ```text + crews/support_agent + ``` + + Não inclua uma barra inicial. + + + + Adicione as variáveis de ambiente necessárias e inicie a implantação. + + + +## Configurar uma Implantação Existente + + + + Acesse sua automação no AMP e abra **Settings**. + + + + Se o auto-deploy estiver habilitado, desative-o primeiro. O campo de + diretório de trabalho fica indisponível enquanto o auto-deploy está ativo. + + + + Em **Basic settings**, informe o caminho da subpasta, como: + + ```text + crews/support_agent + ``` + + + + Salve a configuração e reimplante a automação. O novo diretório de trabalho + será usado no próximo deploy. + + + +## Regras de Caminho + +O diretório de trabalho deve ser um caminho relativo dentro da raiz do +repositório ou do ZIP. + +| Regra | Exemplo | +|-------|---------| +| Use um caminho relativo | `crews/support_agent` | +| Não comece com `/` | `/crews/support_agent` é inválido | +| Não use segmentos de caminho `.` ou `..` | `crews/../support_agent` é inválido | +| Use apenas letras, números, hifens, underscores, pontos e barras | `crews/support agent` é inválido | +| Mantenha o caminho com 255 caracteres ou menos | Caminhos maiores são rejeitados | + +O AMP remove espaços em branco no início e no fim, reduz barras repetidas e +remove barras finais. Um valor em branco usa a raiz do repositório. + +## Arquivos Lock e Workspaces UV + +A pasta selecionada deve conter o `pyproject.toml` e os arquivos exigidos pelo +tipo de projeto: + +- Crew JSON-first: `crew.jsonc` ou `crew.json`, além de `agents/` +- Crew clássico ou Flow: `src/` com o ponto de entrada Python esperado + +Um arquivo `uv.lock` ou `poetry.lock` pode ficar na pasta selecionada ou na raiz +do repositório. + +Isso oferece suporte aos dois layouts comuns de arquivo lock: + + + + ```text + company-ai/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- uv.lock + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + ```text + company-ai/ + |-- uv.lock + |-- packages/ + | `-- shared_tools/ + `-- crews/ + `-- support_agent/ + |-- pyproject.toml + |-- crew.jsonc + `-- agents/ + `-- support_agent.jsonc + ``` + + + + + Se sua automação importar pacotes compartilhados de outro lugar do monorepo, + declare esses pacotes no `pyproject.toml` usando configuração de workspace, + caminho ou source do UV. O AMP executa a automação a partir da pasta + selecionada, então o código compartilhado deve ser instalado como dependência + em vez de depender da raiz do repositório no Python path. + + +## Solução de Problemas + +### Diretório de Trabalho Não Encontrado + +Verifique se o caminho é relativo à raiz do repositório ou do ZIP. Para uploads +de ZIP, o conteúdo do ZIP deve incluir exatamente o caminho informado como +diretório de trabalho. + +### pyproject.toml Ausente + +O diretório de trabalho deve apontar para a pasta do projeto Crew ou Flow, não +apenas para uma pasta pai que contém vários projetos. + +### uv.lock ou poetry.lock Ausente + +Faça commit de um arquivo lock na pasta do projeto selecionada ou na raiz do +repositório. Para workspaces UV, manter `uv.lock` na raiz do workspace é +suportado. + +### Auto-Deploy Indisponível + +O auto-deploy fica desabilitado enquanto um diretório de trabalho está definido. +Use reimplantações manuais ou acione reimplantações a partir de CI/CD com a API +do AMP. + + + Continue com o guia de implantação depois de escolher o diretório de trabalho + do monorepo. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/onedrive-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/onedrive-trigger.mdx new file mode 100644 index 000000000..a5e81cf88 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/onedrive-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "OneDrive Trigger" +description: "Automate responses to OneDrive file activity" +icon: "cloud" +mode: "wide" +--- + +## Overview + +Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata. + + + Connect OneDrive in **Tools & Integrations** and toggle the trigger on for + your deployment. + + +## Enabling the OneDrive Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **OneDrive** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Audit file permissions + +```python +from onedrive_file_crew import OneDriveFileTrigger + +crew = OneDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": onedrive_payload, +}) +``` + +The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary. + +## Testando Localmente + +Teste sua integração de trigger do OneDrive localmente usando a CLI da CrewAI: + +```bash +# Visualize todos os triggers disponíveis +crewai triggers list + +# Simule um trigger do OneDrive com payload realista +crewai triggers run microsoft_onedrive/file_changed +``` + +O comando `crewai triggers run` executará sua crew com um payload completo do OneDrive, permitindo que você teste sua lógica de parsing antes do deployment. + + + Use `crewai triggers run microsoft_onedrive/file_changed` (não `crewai run`) + para simular execução de trigger durante o desenvolvimento. Após o deployment, + sua crew receberá automaticamente o payload do trigger. + + +## Troubleshooting + +- Ensure the connected account has permission to read the file metadata included in the webhook +- Teste localmente com `crewai triggers run microsoft_onedrive/file_changed` para ver a estrutura exata do payload +- If the trigger fires but the payload is missing `permissions`, confirm the site-level sharing settings allow Graph to return this field +- For large tenants, filter notifications upstream so the crew only runs on relevant directories +- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/outlook-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/outlook-trigger.mdx new file mode 100644 index 000000000..e373685c2 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/outlook-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "Outlook Trigger" +description: "Launch automations from Outlook emails and calendar updates" +icon: "microsoft" +mode: "wide" +--- + +## Overview + +Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations. + + + Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled + for your deployment. + + +## Enabling the Outlook Trigger + +1. Open your deployment in CrewAI AMP +2. Go to the **Triggers** tab +3. Locate **Outlook** and switch the toggle to enable + + + Enable or disable triggers with toggle + + +## Example: Summarize a new email + +```python +from outlook_message_crew import OutlookMessageTrigger + +crew = OutlookMessageTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": outlook_payload, +}) +``` + +The crew extracts sender details, subject, body preview, and attachments before generating a structured response. + +## Testando Localmente + +Teste sua integração de trigger do Outlook localmente usando a CLI da CrewAI: + +```bash +# Visualize todos os triggers disponíveis +crewai triggers list + +# Simule um trigger do Outlook com payload realista +crewai triggers run microsoft_outlook/email_received +``` + +O comando `crewai triggers run` executará sua crew com um payload completo do Outlook, permitindo que você teste sua lógica de parsing antes do deployment. + + + Use `crewai triggers run microsoft_outlook/email_received` (não `crewai run`) + para simular execução de trigger durante o desenvolvimento. Após o deployment, + sua crew receberá automaticamente o payload do trigger. + + +## Troubleshooting + +- Verify the Outlook connector is still authorized; the subscription must be renewed periodically +- Teste localmente com `crewai triggers run microsoft_outlook/email_received` para ver a estrutura exata do payload +- If attachments are missing, confirm the webhook subscription includes the `includeResourceData` flag +- Review execution logs when events fail to match—cancellation payloads lack attendee lists by design and the crew should account for that +- Lembre-se: use `crewai triggers run` (não `crewai run`) para simular execução de trigger diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/prepare-for-deployment.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/prepare-for-deployment.mdx new file mode 100644 index 000000000..623c609fb --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/prepare-for-deployment.mdx @@ -0,0 +1,345 @@ +--- +title: "Preparar para Implantação" +description: "Certifique-se de que seu Crew ou Flow está pronto para implantação no CrewAI AMP" +icon: "clipboard-check" +mode: "wide" +--- + + + Antes de implantar no CrewAI AMP, é crucial verificar se seu projeto está estruturado corretamente. + Tanto Crews quanto Flows podem ser implantados como "automações", mas eles têm estruturas de projeto + e requisitos diferentes que devem ser atendidos para uma implantação bem-sucedida. + + +## Entendendo Automações + +No CrewAI AMP, **automações** é o termo geral para projetos de IA Agêntica implantáveis. Uma automação pode ser: + +- **Um Crew**: Uma equipe independente de agentes de IA trabalhando juntos em tarefas +- **Um Flow**: Um workflow orquestrado que pode combinar múltiplos crews, chamadas diretas de LLM e lógica procedural + +Entender qual tipo você está implantando é essencial porque eles têm estruturas de projeto e pontos de entrada diferentes. + +## Crews vs Flows: Principais Diferenças + + + + Equipes independentes de agentes de IA. Novas crews são JSON-first com `crew.jsonc` e `agents/`; crews clássicas ainda podem usar `crew.py`. + + + Workflows orquestrados com crews embutidos em uma pasta `crews/`. Ideal para processos complexos de múltiplas etapas. + + + +| Aspecto | Crew | Flow | +|---------|------|------| +| **Estrutura do projeto** | Raiz do projeto com `crew.jsonc` e `agents/` | `src/project_name/` com pasta `crews/` | +| **Localização da lógica principal** | `crew.jsonc` (clássico: `src/project_name/crew.py`) | `src/project_name/main.py` (classe Flow) | +| **Função de ponto de entrada** | Carregada a partir de `crew.jsonc` (clássico: `run()` em `main.py`) | `kickoff()` em `main.py` | +| **Tipo no pyproject.toml** | `type = "crew"` | `type = "flow"` | +| **Comando CLI de criação** | `crewai create crew name` | `crewai create flow name` | +| **Localização da configuração** | `crew.jsonc`, `agents/`, `tools/` opcional | `src/project_name/crews/crew_name/config/` ou pastas de crew JSON embutidas | +| **Pode conter outros crews** | Não | Sim (na pasta `crews/`) | + +## Referência de Estrutura de Projeto + +### Estrutura de Projeto Crew + +Quando você executa `crewai create crew my_crew`, recebe a estrutura JSON-first: + +``` +my_crew/ +├── .gitignore +├── pyproject.toml # Deve ter type = "crew" +├── README.md +├── .env +├── uv.lock # OBRIGATÓRIO para implantação +├── crew.jsonc # Configurações, tarefas, processo e inputs +├── agents/ +│ └── researcher.jsonc # Definições de agentes +├── tools/ # Ferramentas custom: opcionais +├── knowledge/ +└── skills/ +``` + + + Para crews JSON-first, mantenha `crew.jsonc`, `agents/`, `tools/`, `knowledge/` e `skills/` + na raiz do projeto. Colocá-los dentro de `src/` impede que `crewai run` e a validação de + implantação encontrem a definição da crew. + + + + Projetos clássicos criados com `crewai create crew my_crew --classic` usam a estrutura antiga + `src/project_name/crew.py`, `src/project_name/config/agents.yaml` e + `src/project_name/config/tasks.yaml`. Essa estrutura continua suportada para crews Python com decorators. + + +### Estrutura de Projeto Flow + +Quando você executa `crewai create flow my_flow`, você obtém esta estrutura: + +``` +my_flow/ +├── .gitignore +├── pyproject.toml # Deve ter type = "flow" +├── README.md +├── .env +├── uv.lock # OBRIGATÓRIO para implantação +└── src/ + └── my_flow/ + ├── __init__.py + ├── main.py # Ponto de entrada com função kickoff() + classe Flow + ├── crews/ # Pasta de crews embutidos + │ └── poem_crew/ + │ ├── __init__.py + │ ├── poem_crew.py # Crew com decorador @CrewBase + │ └── config/ + │ ├── agents.yaml + │ └── tasks.yaml + └── tools/ + ├── __init__.py + └── custom_tool.py +``` + + + Crews independentes JSON-first usam arquivos JSON na raiz do projeto. Flows ainda usam + `src/project_name/` e podem conter crews embutidas clássicas ou pastas de crew JSON carregadas com + `crewai.project.load_crew`. + + +## Checklist Pré-Implantação + +Use este checklist para verificar se seu projeto está pronto para implantação. + +### 1. Verificar Configuração do pyproject.toml + +Seu `pyproject.toml` deve incluir a seção `[tool.crewai]` correta: + + + + ```toml + [tool.crewai] + type = "crew" + ``` + + + ```toml + [tool.crewai] + type = "flow" + ``` + + + + + Se o `type` não corresponder à estrutura do seu projeto, o build falhará ou + a automação não funcionará corretamente. + + +### 2. Garantir que o Arquivo uv.lock Existe + +CrewAI usa `uv` para gerenciamento de dependências. O arquivo `uv.lock` garante builds reproduzíveis e é **obrigatório** para implantação. + +```bash +# Gerar ou atualizar o arquivo lock +uv lock + +# Verificar se existe +ls -la uv.lock +``` + +Se o arquivo não existir, execute `uv lock` e faça commit no seu repositório: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + +### 3. Validar a Definição da Crew + + + + Crews JSON-first precisam ter `crew.jsonc` ou `crew.json` na raiz do projeto. + O array `agents` deve apontar para arquivos em `agents/`, e cada task deve referenciar + um nome de agent válido. + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "Research {topic}.", + "expected_output": "A concise report.", + "agent": "researcher" + } + ], + "inputs": { + "topic": "AI Agents" + } + } + ``` + + Ferramentas customizadas são referenciadas como `"custom:"` e devem existir em + `tools/.py` com uma subclasse de `BaseTool`. + + + Crews clássicas e crews Python embutidas em Flows devem usar o decorador `@CrewBase`. + + ```python + from crewai import Agent, Crew, Process, Task + from crewai.project import CrewBase, agent, crew, task + from crewai.agents.agent_builder.base_agent import BaseAgent + from typing import List + + @CrewBase + class MyCrew(): + """Descrição do meu crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + @task + def my_task(self) -> Task: + return Task( + config=self.tasks_config['my_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) + ``` + + + +### 4. Verificar Pontos de Entrada do Projeto + +Crews JSON-first independentes não precisam de um `src/project_name/main.py` escrito manualmente; +`crewai run` e o empacotamento de implantação carregam `crew.jsonc` diretamente. Crews clássicas e Flows usam pontos de entrada Python: + + + + Execute localmente a partir da raiz do projeto: + + ```bash + crewai run + ``` + + + O ponto de entrada usa uma função `run()`: + + ```python + # src/my_crew/main.py + from my_crew.crew import MyCrew + + def run(): + """Executa o crew.""" + inputs = {'topic': 'AI in Healthcare'} + result = MyCrew().crew().kickoff(inputs=inputs) + return result + + if __name__ == "__main__": + run() + ``` + + + O ponto de entrada usa uma função `kickoff()` com uma classe Flow: + + ```python + # src/my_flow/main.py + from crewai.flow import Flow, listen, start + from my_flow.crews.poem_crew.poem_crew import PoemCrew + + class MyFlow(Flow): + @start() + def begin(self): + # Lógica do Flow aqui + result = PoemCrew().crew().kickoff(inputs={...}) + return result + + def kickoff(): + """Executa o flow.""" + MyFlow().kickoff() + + if __name__ == "__main__": + kickoff() + ``` + + + +### 5. Preparar Variáveis de Ambiente + +Antes da implantação, certifique-se de ter: + +1. **Chaves de API de LLM** prontas (OpenAI, Anthropic, Google, etc.) +2. **Chaves de API de ferramentas** se estiver usando ferramentas externas (Serper, etc.) + + + Se seu projeto depende de pacotes de um **registro PyPI privado**, você também precisará configurar + credenciais de autenticação do registro como variáveis de ambiente. Consulte o guia + [Registros de Pacotes Privados](/pt-BR/enterprise/guides/private-package-registry) para mais detalhes. + + + + Teste seu projeto localmente com as mesmas variáveis de ambiente antes de implantar + para detectar problemas de configuração antecipadamente. + + +## Comandos de Validação Rápida + +Execute estes comandos a partir da raiz do seu projeto para verificar rapidamente sua configuração: + +```bash +# 1. Verificar tipo do projeto no pyproject.toml +grep -A2 "\[tool.crewai\]" pyproject.toml + +# 2. Verificar se uv.lock existe +ls -la uv.lock || echo "ERRO: uv.lock ausente! Execute 'uv lock'" + +# 3. Para crews JSON-first, verificar crew.jsonc e agents/ +([ -f crew.jsonc ] || [ -f crew.json ]) || echo "Nenhum crew.jsonc ou crew.json encontrado" +test -d agents || echo "Nenhum diretório agents/ encontrado" + +# 4. Para Crews clássicas - verificar se crew.py existe +ls -la src/*/crew.py 2>/dev/null || echo "Nenhum crew.py (esperado para Crews)" + +# 5. Para Flows - verificar se pasta crews/ existe +ls -la src/*/crews/ 2>/dev/null || echo "Nenhuma pasta crews/ (esperado para Flows)" + +# 6. Para crews Python clássicas - verificar uso do CrewBase +grep -r "@CrewBase" . --include="*.py" +``` + +## Erros Comuns de Configuração + +| Erro | Sintoma | Correção | +|------|---------|----------| +| `uv.lock` ausente | Build falha durante resolução de dependências | Execute `uv lock` e faça commit | +| `type` errado no pyproject.toml | Build bem-sucedido mas falha em runtime | Altere para o tipo correto | +| `crew.jsonc` ou `agents/` ausente em uma crew JSON-first | Definição da crew não encontrada | Mantenha `crew.jsonc` e `agents/` na raiz do projeto | +| Decorador `@CrewBase` ausente em uma crew clássica | Erros "Config not found" | Adicione o decorador a todas as classes crew clássicas | +| Arquivos clássicos na raiz ao invés de `src/` | Ponto de entrada não encontrado | Mova arquivos Python clássicos para `src/project_name/` | +| `run()` ou `kickoff()` ausente | Não é possível iniciar automação | Adicione a função de entrada correta | + +## Próximos Passos + +Uma vez que seu projeto passar por todos os itens do checklist, você está pronto para implantar: + + + Siga o guia de implantação para implantar seu Crew ou Flow no CrewAI AMP usando + a CLI, interface web ou integração CI/CD. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/private-package-registry.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/private-package-registry.mdx new file mode 100644 index 000000000..3950ead8d --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/private-package-registry.mdx @@ -0,0 +1,263 @@ +--- +title: "Registros de Pacotes Privados" +description: "Instale pacotes Python privados de registros PyPI autenticados no CrewAI AMP" +icon: "lock" +mode: "wide" +--- + + + Este guia aborda como configurar seu projeto CrewAI para instalar pacotes Python + de registros PyPI privados (Azure DevOps Artifacts, GitHub Packages, GitLab, AWS CodeArtifact, etc.) + ao implantar no CrewAI AMP. + + +## Quando Você Precisa Disso + +Se seu projeto depende de pacotes Python internos ou proprietários hospedados em um registro privado +em vez do PyPI público, você precisará: + +1. Informar ao UV **onde** encontrar o pacote (uma URL de index) +2. Informar ao UV **quais** pacotes vêm desse index (um mapeamento de source) +3. Fornecer **credenciais** para que o UV possa autenticar durante a instalação + +O CrewAI AMP usa [UV](https://docs.astral.sh/uv/) para resolução e instalação de dependências. +O UV suporta registros privados autenticados por meio da configuração do `pyproject.toml` combinada +com variáveis de ambiente para credenciais. + +## Passo 1: Configurar o pyproject.toml + +Três elementos trabalham juntos no seu `pyproject.toml`: + +### 1a. Declarar a dependência + +Adicione o pacote privado ao seu `[project.dependencies]` como qualquer outra dependência: + +```toml +[project] +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] +``` + +### 1b. Definir o index + +Registre seu registro privado como um index nomeado em `[[tool.uv.index]]`: + +```toml +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true +``` + + + O campo `name` é importante — o UV o utiliza para construir os nomes das variáveis de ambiente + para autenticação (veja o [Passo 2](#passo-2-configurar-credenciais-de-autenticação) abaixo). + + Definir `explicit = true` significa que o UV não consultará esse index para todos os pacotes — apenas + os que você mapear explicitamente em `[tool.uv.sources]`. Isso evita consultas desnecessárias + ao seu registro privado e protege contra ataques de confusão de dependências. + + +### 1c. Mapear o pacote para o index + +Informe ao UV quais pacotes devem ser resolvidos a partir do seu index privado usando `[tool.uv.sources]`: + +```toml +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +### Exemplo completo + +```toml +[project] +name = "my-crew-project" +version = "0.1.0" +requires-python = ">=3.10,<=3.13" +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] + +[tool.crewai] +type = "crew" + +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true + +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +Após atualizar o `pyproject.toml`, regenere seu arquivo lock: + +```bash +uv lock +``` + + + Sempre faça commit do `uv.lock` atualizado junto com as alterações no `pyproject.toml`. + O arquivo lock é obrigatório para implantação — veja [Preparar para Implantação](/pt-BR/enterprise/guides/prepare-for-deployment). + + +## Passo 2: Configurar Credenciais de Autenticação + +O UV autentica em indexes privados usando variáveis de ambiente que seguem uma convenção de nomenclatura +baseada no nome do index que você definiu no `pyproject.toml`: + +``` +UV_INDEX_{UPPER_NAME}_USERNAME +UV_INDEX_{UPPER_NAME}_PASSWORD +``` + +Onde `{UPPER_NAME}` é o nome do seu index convertido para **maiúsculas** com **hifens substituídos por underscores**. + +Por exemplo, um index chamado `my-private-registry` usa: + +| Variável | Valor | +|----------|-------| +| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | Seu nome de usuário ou nome do token do registro | +| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | Sua senha ou token/PAT do registro | + + + Essas variáveis de ambiente **devem** ser adicionadas pelas configurações de **Variáveis de Ambiente** do CrewAI AMP — + globalmente ou no nível da implantação. Elas não podem ser definidas em arquivos `.env` ou codificadas no seu projeto. + + Veja [Configurar Variáveis de Ambiente no AMP](#configurar-variáveis-de-ambiente-no-amp) abaixo. + + +## Referência de Provedores de Registro + +A tabela abaixo mostra o formato da URL de index e os valores de credenciais para provedores de registro comuns. +Substitua os valores de exemplo pelos detalhes reais da sua organização e feed. + +| Provedor | URL do Index | Usuário | Senha | +|----------|-------------|---------|-------| +| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | Qualquer string não vazia (ex: `token`) | Personal Access Token (PAT) com escopo Packaging Read | +| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | Nome de usuário do GitHub | Personal Access Token (classic) com escopo `read:packages` | +| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project ou Personal Access Token com escopo `read_api` | +| **AWS CodeArtifact** | Use a URL de `aws codeartifact get-repository-endpoint` | `aws` | Token de `aws codeartifact get-authorization-token` | +| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | Chave de conta de serviço codificada em Base64 | +| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | Nome de usuário ou email | Chave API ou token de identidade | +| **Auto-hospedado (devpi, Nexus, etc.)** | URL da API simple do seu registro | Nome de usuário do registro | Senha do registro | + + + Para **AWS CodeArtifact**, o token de autorização expira periodicamente. + Você precisará atualizar o valor de `UV_INDEX_*_PASSWORD` quando ele expirar. + Considere automatizar isso no seu pipeline de CI/CD. + + +## Configurar Variáveis de Ambiente no AMP + +As credenciais do registro privado devem ser configuradas como variáveis de ambiente no CrewAI AMP. +Você tem duas opções: + + + + 1. Faça login no [CrewAI AMP](https://app.crewai.com) + 2. Navegue até sua automação + 3. Abra a aba **Environment Variables** + 4. Adicione cada variável (`UV_INDEX_*_USERNAME` e `UV_INDEX_*_PASSWORD`) com seu valor + + Veja o passo [Deploy para AMP — Definir Variáveis de Ambiente](/pt-BR/enterprise/guides/deploy-to-amp#definir-as-variáveis-de-ambiente) para detalhes. + + + Adicione as variáveis ao seu arquivo `.env` local antes de executar `crewai deploy create`. + A CLI as transferirá com segurança para a plataforma: + + ```bash + # .env + OPENAI_API_KEY=sk-... + UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token + UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here + ``` + + ```bash + crewai deploy create + ``` + + + + + **Nunca** faça commit de credenciais no seu repositório. Use variáveis de ambiente do AMP para todos os segredos. + O arquivo `.env` deve estar listado no `.gitignore`. + + +Para atualizar credenciais em uma implantação existente, veja [Atualizar Seu Crew — Variáveis de Ambiente](/pt-BR/enterprise/guides/update-crew). + +## Como Tudo se Conecta + +Quando o CrewAI AMP faz o build da sua automação, o fluxo de resolução funciona assim: + + + + O AMP busca seu repositório e lê o `pyproject.toml` e o `uv.lock`. + + + O UV lê `[tool.uv.sources]` para determinar de qual index cada pacote deve vir. + + + Para cada index privado, o UV busca `UV_INDEX_{NAME}_USERNAME` e `UV_INDEX_{NAME}_PASSWORD` + nas variáveis de ambiente que você configurou no AMP. + + + O UV baixa e instala todos os pacotes — tanto públicos (do PyPI) quanto privados (do seu registro). + + + Seu crew ou flow inicia com todas as dependências disponíveis. + + + +## Solução de Problemas + +### Erros de Autenticação Durante o Build + +**Sintoma**: Build falha com `401 Unauthorized` ou `403 Forbidden` ao resolver um pacote privado. + +**Verifique**: +- Os nomes das variáveis de ambiente `UV_INDEX_*` correspondem exatamente ao nome do seu index (maiúsculas, hifens -> underscores) +- As credenciais estão definidas nas variáveis de ambiente do AMP, não apenas em um `.env` local +- Seu token/PAT tem as permissões de leitura necessárias para o feed de pacotes +- O token não expirou (especialmente relevante para AWS CodeArtifact) + +### Pacote Não Encontrado + +**Sintoma**: `No matching distribution found for my-private-package`. + +**Verifique**: +- A URL do index no `pyproject.toml` termina com `/simple/` +- A entrada `[tool.uv.sources]` mapeia o nome correto do pacote para o nome correto do index +- O pacote está realmente publicado no seu registro privado +- Execute `uv lock` localmente com as mesmas credenciais para verificar se a resolução funciona + +### Conflitos no Arquivo Lock + +**Sintoma**: `uv lock` falha ou produz resultados inesperados após adicionar um index privado. + +**Solução**: Defina as credenciais localmente e regenere: + +```bash +export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token +export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat +uv lock +``` + +Em seguida, faça commit do `uv.lock` atualizado. + +## Guias Relacionados + + + + Verifique a estrutura do projeto e as dependências antes de implantar. + + + Implante seu crew ou flow e configure variáveis de ambiente. + + + Atualize variáveis de ambiente e envie alterações para uma implantação em execução. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/react-component-export.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/react-component-export.mdx new file mode 100644 index 000000000..49b4c19cb --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/react-component-export.mdx @@ -0,0 +1,112 @@ +--- +title: "Exportação de Componentes React" +description: "Aprenda como exportar e integrar componentes React do CrewAI AMP em suas aplicações" +icon: "react" +mode: "wide" +--- + +Este guia explica como exportar crews do CrewAI AMP como componentes React e integrá-los às suas próprias aplicações. + +## Exportando um Componente React + + + + 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 diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/salesforce-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/salesforce-trigger.mdx new file mode 100644 index 000000000..229923e88 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/salesforce-trigger.mdx @@ -0,0 +1,50 @@ +--- +title: "Trigger Salesforce" +description: "Dispare equipes CrewAI a partir de fluxos de trabalho do Salesforce para automação de CRM" +icon: "salesforce" +mode: "wide" +--- + +A CrewAI AMP pode ser acionada a partir do Salesforce para automatizar fluxos de trabalho de gestão de relacionamento com o cliente e aprimorar suas operações de vendas. + +## Visão Geral + +O Salesforce é uma das principais plataformas de gestão de relacionamento com o cliente (CRM), que ajuda empresas a otimizar operações de vendas, atendimento e marketing. Ao configurar triggers da CrewAI a partir do Salesforce, você pode: + +- Automatizar a classificação e qualificação de leads +- Gerar materiais de vendas personalizados +- Aprimorar o atendimento ao cliente com respostas baseadas em IA +- Otimizar análise e relatórios de dados + +## Demonstração + + + +## Primeiros Passos + +Para configurar triggers no Salesforce: + +1. **Contato com o Suporte**: Entre em contato com o suporte da CrewAI AMP para obter assistência na configuração dos triggers no Salesforce +2. **Revisar Requisitos**: Certifique-se de possuir as permissões necessárias no Salesforce e acesso à API +3. **Configurar Conexão**: Trabalhe com a equipe de suporte para estabelecer a conexão entre a CrewAI e sua instância do Salesforce +4. **Testar Triggers**: Verifique se os triggers funcionam corretamente para os seus casos de uso específicos + +## Casos de Uso + +Cenários comuns de uso de triggers Salesforce + CrewAI incluem: + +- **Processamento de Leads**: Analisar e classificar leads recebidos automaticamente +- **Geração de Propostas**: Criar propostas personalizadas com base nos dados das oportunidades +- **Insights de Clientes**: Gerar relatórios de análise a partir do histórico de interações com clientes +- **Automação de Follow-up**: Criar mensagens de follow-up e recomendações personalizadas + +## Próximos Passos + +Para instruções detalhadas de configuração e opções avançadas, entre em contato com o suporte da CrewAI AMP, que pode fornecer orientações personalizadas para o seu ambiente Salesforce e necessidades de negócio. diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/slack-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/slack-trigger.mdx new file mode 100644 index 000000000..5a6e68895 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/slack-trigger.mdx @@ -0,0 +1,62 @@ +--- +title: "Slack Trigger" +description: "Acione crews do CrewAI diretamente do Slack usando comandos de barra" +icon: "slack" +mode: "wide" +--- + +Este guia explica como iniciar um crew diretamente do Slack usando triggers do CrewAI. + +## Pré-requisitos + +- Trigger do CrewAI para Slack instalado e conectado ao seu workspace do Slack +- Pelo menos um crew configurado no CrewAI + +## Etapas de Configuração + + + + 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/v1.15.1/pt-BR/enterprise/guides/team-management.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/team-management.mdx new file mode 100644 index 000000000..b92956541 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/team-management.mdx @@ -0,0 +1,106 @@ +--- +title: "Gestão de Equipes" +description: "Aprenda como convidar e gerenciar membros da equipe em sua organização CrewAI AMP" +icon: "users" +mode: "wide" +--- + +Como administrador de uma conta CrewAI AMP, você pode facilmente convidar novos membros para sua organização. Este guia irá orientá-lo passo a passo pelo processo. + +## Convidando Membros da Equipe + + + + - Faça login na sua conta CrewAI AMP - Procure o ícone de engrenagem (⚙️) no + canto superior direito do painel - Clique no ícone de engrenagem para + acessar a página de **Configurações**: + + 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 AMP - Procure o ícone de engrenagem (⚙️) no + canto superior direito do painel - Clique no ícone de engrenagem para + acessar a página de **Configurações**: + + 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 AMP. diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/tool-repository.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/tool-repository.mdx new file mode 100644 index 000000000..d925d5485 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/tool-repository.mdx @@ -0,0 +1,109 @@ +--- +title: Repositório de Ferramentas +description: "Usando o Repositório de Ferramentas para gerenciar suas ferramentas" +icon: "toolbox" +mode: "wide" +--- + +## Visão geral + +O Repositório de Ferramentas é um gerenciador de pacotes para ferramentas da CrewAI. Ele permite que usuários publiquem, instalem e gerenciem ferramentas que se integram com crews e flows da CrewAI. + +As ferramentas podem ser: + +- **Privadas**: acessíveis apenas dentro da sua organização (padrão) +- **Públicas**: acessíveis a todos os usuários CrewAI se publicadas com a flag `--public` + +O repositório não é um sistema de controle de versões. Use Git para rastrear mudanças no código e permitir colaboração. + +## Pré-requisitos + +Antes de usar o Repositório de Ferramentas, certifique-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) +- [CrewAI CLI](/pt-BR/concepts/cli#cli) instalada +- uv>=0.5.0 instalado. Veja [como atualizar](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv) +- [Git](https://git-scm.com) instalado e configurado +- Permissões de acesso para publicar ou instalar ferramentas em sua organização CrewAI AMP + +## Instalando ferramentas + +Para instalar uma ferramenta: + +```bash +crewai tool install +``` + +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](/pt-BR/concepts/tools#creating-your-own-tools). + +## Atualizando ferramentas + +Para atualizar uma ferramenta publicada: + +1. Modifique a ferramenta localmente +2. Atualize a versão no `pyproject.toml` (por exemplo, de `0.1.0` para `0.1.1`) +3. Faça o commit das alterações e publique + +```bash +git commit -m "Atualizar versão para 0.1.1" +crewai tool publish +``` + +## Excluindo ferramentas + +Para excluir uma ferramenta: + +1. Acesse o [CrewAI AMP](https://app.crewai.com) +2. Navegue até **Ferramentas** +3. Selecione a ferramenta +4. Clique em **Excluir** + + + 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 AMP > 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/training-crews.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/training-crews.mdx new file mode 100644 index 000000000..d6626a2f5 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/training-crews.mdx @@ -0,0 +1,132 @@ +--- +title: "Treinamento de Crews" +description: "Treine seus crews implantados diretamente da plataforma CrewAI AMP para melhorar o desempenho dos agentes ao longo do tempo" +icon: "dumbbell" +mode: "wide" +--- + +O treinamento permite que você melhore o desempenho do crew executando sessões de treinamento iterativas diretamente da aba **Training** no CrewAI AMP. A plataforma usa o **modo de auto-treinamento** — ela gerencia o processo iterativo automaticamente, diferente do treinamento via CLI que requer feedback humano interativo por iteração. + +Após a conclusão do treinamento, o CrewAI avalia as saídas dos agentes e consolida o feedback em sugestões acionáveis para cada agente. Essas sugestões são então aplicadas às execuções futuras do crew para melhorar a qualidade das saídas. + + + Para detalhes sobre como o treinamento do CrewAI funciona internamente, consulte a página [Conceitos de Treinamento](/pt-BR/concepts/training). + + +## Pré-requisitos + + + + Você precisa de uma conta CrewAI AMP com uma implantação ativa em status **Ready** (tipo Crew). + + + Sua conta deve ter permissão de execução para a implantação que deseja treinar. + + + +## Como treinar um crew + + + + Navegue até **Deployments**, clique na sua implantação e selecione a aba **Training**. + + + + Forneça um **Training Name** — este será o nome do arquivo `.pkl` usado para armazenar os resultados do treinamento. Por exemplo, "Expert Mode Training" produz `expert_mode_training.pkl`. + + + + Insira os campos de entrada do crew. Estas são as mesmas entradas que você forneceria para um kickoff normal — elas são carregadas dinamicamente com base na configuração do seu crew. + + + + Clique em **Train Crew**. O botão muda para "Training..." com um spinner enquanto o processo é executado. + + Por trás dos panos: + - Um registro de treinamento é criado para sua implantação + - A plataforma chama o endpoint de auto-treinamento da implantação + - O crew executa suas iterações automaticamente — nenhum feedback manual é necessário + + + + O painel **Current Training Status** exibe: + - **Status** — Estado atual da execução do treinamento + - **Nº Iterations** — Número de iterações de treinamento configuradas + - **Filename** — O arquivo `.pkl` sendo gerado + - **Started At** — Quando o treinamento começou + - **Training Inputs** — As entradas que você forneceu + + + +## Entendendo os resultados do treinamento + +Uma vez que o treinamento for concluído, você verá cards de resultado por agente com as seguintes informações: + +- **Agent Role** — O nome/função do agente no seu crew +- **Final Quality** — Uma pontuação de 0 a 10 avaliando a qualidade da saída do agente +- **Final Summary** — Um resumo do desempenho do agente durante o treinamento +- **Suggestions** — Recomendações acionáveis para melhorar o comportamento do agente + +### Editando sugestões + +Você pode refinar as sugestões para qualquer agente: + + + + No card de resultado de qualquer agente, clique no botão **Edit** ao lado das sugestões. + + + + Atualize o texto das sugestões para refletir melhor as melhorias que você deseja. + + + + Clique em **Save**. As sugestões editadas são sincronizadas de volta à implantação e usadas em todas as execuções futuras. + + + +## Usando dados de treinamento + +Para aplicar os resultados do treinamento ao seu crew: + +1. Anote o **Training Filename** (o arquivo `.pkl`) da sua sessão de treinamento concluída. +2. Especifique este nome de arquivo na configuração de kickoff ou execução da sua implantação. +3. O crew carrega automaticamente o arquivo de treinamento e aplica as sugestões armazenadas a cada agente. + +Isso significa que os agentes se beneficiam do feedback gerado durante o treinamento em cada execução subsequente. + +## Treinamentos anteriores + +A parte inferior da aba Training exibe um **histórico de todas as sessões de treinamento anteriores** da implantação. Use isso para revisar execuções de treinamento anteriores, comparar resultados ou selecionar um arquivo de treinamento diferente para usar. + +## Tratamento de erros + +Se uma execução de treinamento falhar, o painel de status mostra um estado de erro junto com uma mensagem descrevendo o que deu errado. + +Causas comuns de falhas de treinamento: +- **Runtime da implantação não atualizado** — Certifique-se de que sua implantação está executando a versão mais recente +- **Erros de execução do crew** — Problemas na lógica de tarefas do crew ou configuração do agente +- **Problemas de rede** — Problemas de conectividade entre a plataforma e a implantação + +## Limitações + + + Tenha estas restrições em mente ao planejar seu fluxo de trabalho de treinamento: + - **Um treinamento ativo por vez** por implantação — aguarde a execução atual terminar antes de iniciar outra + - **Apenas modo de auto-treinamento** — a plataforma não suporta feedback interativo por iteração como o CLI + - **Dados de treinamento são específicos da implantação** — os resultados do treinamento estão vinculados à instância e versão específicas da implantação + + +## Recursos relacionados + + + + Aprenda como o treinamento do CrewAI funciona internamente. + + + Execute seu crew implantado a partir da plataforma AMP. + + + Faça a implantação do seu crew e deixe-o pronto para treinamento. + + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/update-crew.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/update-crew.mdx new file mode 100644 index 000000000..8ecf0d91b --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/update-crew.mdx @@ -0,0 +1,93 @@ +--- +title: "Atualizar Crew" +description: "Atualizando uma Crew no CrewAI AMP" +icon: "pencil" +mode: "wide" +--- + + + Após implantar sua crew no CrewAI AMP, pode ser necessário fazer atualizações + no código, configurações de segurança ou configuração. Este guia explica como + realizar essas operações de atualização comuns. + + +## Por que atualizar sua Crew? + +Por padrão, o CrewAI não irá buscar atualizações do GitHub automaticamente, então você precisará acionar manualmente as atualizações, a menos que tenha marcado a opção `Auto-update` ao implantar sua crew. + +Há várias razões para querer atualizar sua implantação de crew: + +- Você deseja atualizar o código com o commit mais recente que enviou para o GitHub +- Você deseja redefinir o bearer token por motivos de segurança +- Você deseja atualizar variáveis de ambiente + +## 1. Atualizando o código da sua Crew para o último commit + +Quando você fizer push de novos commits no seu repositório do GitHub e quiser atualizar sua implantação: + +1. Navegue até sua crew na plataforma CrewAI AMP +2. Clique no botão `Re-deploy` na página de detalhes da sua crew + +![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 AMP +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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/webhook-automation.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/webhook-automation.mdx new file mode 100644 index 000000000..1eedfd5f5 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/webhook-automation.mdx @@ -0,0 +1,126 @@ +--- +title: "Automação com Webhook" +description: "Automatize fluxos de trabalho do CrewAI AMP usando webhooks com plataformas como ActivePieces, Zapier e Make.com" +icon: "webhook" +mode: "wide" +--- + +O CrewAI AMP permite que você automatize seu fluxo de trabalho usando webhooks. Este artigo irá guiá-lo no processo de configuração e uso de webhooks para iniciar a execução do crew, com foco na integração com o ActivePieces, uma plataforma de automação de fluxos de trabalho semelhante ao Zapier e Make.com. + +## Configurando Webhooks + + + + - Navegue até o painel do CrewAI AMP + - 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 AMP + - 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 + +**Nota:** Qualquer objeto `meta` fornecido na sua requisição de kickoff será incluído em todos os payloads de webhook, permitindo rastrear requisições e manter contexto durante todo o ciclo de vida da execução do crew. + + + + `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." + ] + } + } + ``` + + + diff --git a/docs/v1.15.1/pt-BR/enterprise/guides/zapier-trigger.mdx b/docs/v1.15.1/pt-BR/enterprise/guides/zapier-trigger.mdx new file mode 100644 index 000000000..70f562998 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/guides/zapier-trigger.mdx @@ -0,0 +1,105 @@ +--- +title: "Trigger Zapier" +description: "Dispare crews do CrewAI a partir de fluxos de trabalho no Zapier para automatizar fluxos multiaplicativos" +icon: "bolt" +mode: "wide" +--- + +Este guia irá conduzi-lo pelo processo de configuração de triggers no Zapier para o CrewAI AMP, permitindo automatizar fluxos de trabalho entre CrewAI AMP e outros aplicativos. + +## Pré-requisitos + +- Uma conta CrewAI AMP +- Uma conta Zapier +- Uma conta Slack (para este exemplo específico) + +## Configuração Passo a Passo + + + + - 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 AMP. + - 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 AMP. + - 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 AMP 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 AMP estejam corretamente mapeadas a partir da mensagem do Slack. +- Teste seu Zap cuidadosamente antes de ativá-lo para identificar possíveis problemas. +- Considere adicionar etapas de tratamento de erros para gerenciar possíveis falhas no fluxo. + +Seguindo estes passos, você terá configurado com sucesso triggers no Zapier para o CrewAI AMP, permitindo fluxos de trabalho automatizados disparados por mensagens no Slack e resultando em notificações por e-mail com a saída do CrewAI AMP. diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/asana.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/asana.mdx new file mode 100644 index 000000000..8a0f45ffa --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/asana.mdx @@ -0,0 +1,265 @@ +--- +title: Integração com Asana +description: "Coordenação de tarefas e projetos em equipe com a integração Asana para CrewAI." +icon: "circle" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem tarefas, projetos e a coordenação da equipe através do Asana. Crie tarefas, atualize o status de projetos, gerencie atribuições e otimize o fluxo de trabalho da sua equipe com automação baseada em IA. + +## Pré-requisitos + +Antes de usar a integração com o Asana, assegure-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Asana com as permissões apropriadas +- Sua conta Asana conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Asana + +### 1. Conecte sua Conta Asana + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Asana** na seção Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de tarefas e projetos +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Create an agent with Asana capabilities +asana_agent = Agent( + role="Project Manager", + goal="Manage tasks and projects in Asana efficiently", + backstory="An AI assistant specialized in project management and task coordination.", + apps=['asana'] +) + +# Task to create a new project +create_project_task = Task( + description="Create a new project called 'Q1 Marketing Campaign' in the Marketing workspace", + agent=asana_agent, + expected_output="Confirmation that the project was created successfully with project ID" +) + +# Run the task +crew = Crew( + agents=[asana_agent], + tasks=[create_project_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Asana + +```python + +task_manager_agent = Agent( + role="Task Manager", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and management.", + apps=['asana'] +) + +# Task to create and assign a task +task_management = Task( + description="Create a task called 'Review quarterly reports' and assign it to the appropriate team member", + agent=task_manager_agent, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_manager_agent], + tasks=[task_management] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Projetos + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate project activities and track progress", + backstory="An experienced project coordinator who ensures projects run smoothly.", + apps=['asana'] +) + +# Complex task involving multiple Asana operations +coordination_task = Task( + description=""" + 1. Get all active projects in the workspace + 2. For each project, get the list of incomplete tasks + 3. Create a summary report task in the 'Management Reports' project + 4. Add comments to overdue tasks to request status updates + """, + agent=project_coordinator, + expected_output="Summary report created and status update requests sent for overdue tasks" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/box.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/box.mdx new file mode 100644 index 000000000..ca76beb1c --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/box.mdx @@ -0,0 +1,260 @@ +--- +title: Integração com Box +description: "Armazenamento de arquivos e gerenciamento de documentos com a integração do Box para CrewAI." +icon: "box" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem arquivos, pastas e documentos através do Box. Faça upload de arquivos, organize estruturas de pastas, pesquise conteúdos e otimize o gerenciamento de documentos da sua equipe com automação alimentada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o Box, assegure-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Box com as permissões apropriadas +- Sua conta Box conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Box + +### 1. Conecte sua conta Box + +1. Acesse [Integrações do CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Box** na seção de Integrações de Autenticação +3. Clique em **Conectar** e conclua o fluxo de OAuth +4. Conceda as permissões necessárias para gerenciamento de arquivos e pastas +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o pacote necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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 + +# Create an agent with Box capabilities +box_agent = Agent( + role="Document Manager", + goal="Manage files and folders in Box efficiently", + backstory="An AI assistant specialized in document management and file organization.", + apps=['box'] +) + +# Task to create a folder structure +create_structure_task = Task( + description="Create a folder called 'Project Files' in the root directory and upload a document from URL", + agent=box_agent, + expected_output="Folder created and file uploaded successfully" +) + +# Run the task +crew = Crew( + agents=[box_agent], + tasks=[create_structure_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Box + +```python + +file_organizer_agent = Agent( + role="File Organizer", + goal="Organize and manage file storage efficiently", + backstory="An AI assistant that focuses on file organization and storage management.", + apps=['box'] +) + +# Task to organize files +organization_task = Task( + description="Create a folder structure for the marketing team and organize existing files", + agent=file_organizer_agent, + expected_output="Folder structure created and files organized" +) + +crew = Crew( + agents=[file_organizer_agent], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Arquivos + +```python +from crewai import Agent, Task, Crew + +file_manager = Agent( + role="File Manager", + goal="Maintain organized file structure and manage document lifecycle", + backstory="An experienced file manager who ensures documents are properly organized and accessible.", + apps=['box'] +) + +# Complex task involving multiple Box operations +management_task = Task( + description=""" + 1. List all files in the root folder + 2. Create monthly archive folders for the current year + 3. Move old files to appropriate archive folders + 4. Generate a summary report of the file organization + """, + agent=file_manager, + expected_output="Files organized into archive structure with summary report" +) + +crew = Crew( + agents=[file_manager], + tasks=[management_task] +) + +crew.kickoff() +``` diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/clickup.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/clickup.mdx new file mode 100644 index 000000000..93c011514 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/clickup.mdx @@ -0,0 +1,300 @@ +--- +title: Integração com ClickUp +description: "Gerenciamento de tarefas e produtividade com integração ClickUp para CrewAI." +icon: "list-check" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem tarefas, projetos e fluxos de produtividade por meio do ClickUp. Crie e atualize tarefas, organize projetos, gerencie a designação de equipes e otimize o gerenciamento da sua produtividade com automação impulsionada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o ClickUp, certifique-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta ClickUp com as permissões apropriadas +- Sua conta ClickUp conectada pela [Página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o ClickUp + +### 1. Conecte sua Conta ClickUp + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **ClickUp** na seção Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de tarefas e projetos +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Create an agent with ClickUp capabilities +clickup_agent = Agent( + role="Task Manager", + goal="Manage tasks and projects in ClickUp efficiently", + backstory="An AI assistant specialized in task management and productivity coordination.", + apps=['clickup'] +) + +# Task to create a new task +create_task = Task( + description="Create a task called 'Review Q1 Reports' in the Marketing list with high priority", + agent=clickup_agent, + expected_output="Task created successfully with task ID" +) + +# Run the task +crew = Crew( + agents=[clickup_agent], + tasks=[create_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do ClickUp + +```python + +task_coordinator = Agent( + role="Task Coordinator", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and status management.", + apps=['clickup'] +) + +# Task to manage task workflow +task_workflow = Task( + description="Create a task for project planning and assign it to the development team", + agent=task_coordinator, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_coordinator], + tasks=[task_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento Avançado de Projetos + +```python +from crewai import Agent, Task, Crew + +project_manager = Agent( + role="Project Manager", + goal="Coordinate project activities and track team productivity", + backstory="An experienced project manager who ensures projects are delivered on time.", + apps=['clickup'] +) + +# Complex task involving multiple ClickUp operations +project_coordination = Task( + description=""" + 1. Get all open tasks in the current space + 2. Identify overdue tasks and update their status + 3. Create a weekly report task summarizing project progress + 4. Assign the report task to the team lead + """, + agent=project_manager, + expected_output="Project status updated and weekly report task created and assigned" +) + +crew = Crew( + agents=[project_manager], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### Busca e Gerenciamento de Tarefas + +```python +from crewai import Agent, Task, Crew + +task_analyst = Agent( + role="Task Analyst", + goal="Analyze task patterns and optimize team productivity", + backstory="An AI assistant that analyzes task data to improve team efficiency.", + apps=['clickup'] +) + +# Task to analyze and optimize task distribution +task_analysis = Task( + description=""" + Search for all tasks assigned to team members in the last 30 days, + analyze completion patterns, and create optimization recommendations + """, + agent=task_analyst, + expected_output="Task analysis report with optimization recommendations" +) + +crew = Crew( + agents=[task_analyst], + tasks=[task_analysis] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nossa equipe de suporte para auxílio na configuração ou + solução de problemas da integração com ClickUp. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/databricks.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/databricks.mdx new file mode 100644 index 000000000..58d552407 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/databricks.mdx @@ -0,0 +1,123 @@ +--- +title: Integração com Databricks +description: "Conecte agentes CrewAI ao Databricks Genie, SQL, Unity Catalog Functions e Vector Search por meio dos servidores MCP gerenciados do Databricks." +icon: "layer-group" +mode: "wide" +--- + +## Visão geral + +Conecte seus agentes CrewAI diretamente ao seu workspace do Databricks por meio dos [servidores MCP gerenciados do Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). A integração com o Databricks permite que seus agentes façam perguntas em linguagem natural com o **Genie**, executem **SQL** governado, chamem **Unity Catalog Functions** e recuperem documentos com o **Vector Search** — tudo sem escrever ou hospedar qualquer código de conector, e com as permissões do Unity Catalog aplicadas em cada chamada. + +Nos bastidores, a integração com o Databricks é um wrapper gerenciado sobre o suporte a [Servidores MCP personalizados](/pt-BR/enterprise/guides/custom-mcp-server) do CrewAI. O Databricks expõe cada recurso como seu próprio endpoint do [Model Context Protocol](https://modelcontextprotocol.io/), e o CrewAI se conecta a eles com segurança em seu nome. Como cada servidor é adicionado separadamente, você pode habilitar exatamente os recursos de que suas crews precisam. + +## Principais recursos + + + + Faça perguntas em linguagem natural e obtenha respostas fundamentadas em seus dados com o [Genie](https://docs.databricks.com/aws/en/genie/), que consulta Genie Spaces e o Unity Catalog e fornece links de volta para a interface do Databricks. + + + Execute SQL governado nos seus warehouses do Databricks para consultar, transformar e criar pipelines de dados diretamente a partir dos seus agentes. + + + Invoque [funções do Unity Catalog](https://docs.databricks.com/aws/en/udf/unity-catalog) para executar SQL predefinido e lógica de negócio personalizada como ferramentas governadas e reutilizáveis. + + + Recupere documentos relevantes para fluxos de RAG e de conhecimento a partir de índices do [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) usando similaridade semântica. + + + +Todos os servidores são executados por trás do Unity AI Gateway e aplicam os controles de acesso do Unity Catalog, de modo que seus agentes só enxergam os dados e as ferramentas que têm permissão para usar. + +## Pré-requisitos + +Antes de usar a integração com o Databricks, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Um workspace do Databricks com os recursos que você deseja expor (Genie Spaces, warehouses SQL, funções do Unity Catalog ou índices do Vector Search) +- [Privilégios apropriados do Unity Catalog](https://docs.databricks.com/aws/en/data-governance/unity-catalog) nos objetos subjacentes +- O hostname do seu workspace do Databricks (ex.: `your-workspace.cloud.databricks.com`) + +## Servidores MCP gerenciados do Databricks + +O Databricks publica um servidor MCP gerenciado separado para cada recurso. O CrewAI os expõe como conexões individuais, cada uma configurada com o host do seu workspace e os identificadores relevantes do Unity Catalog. Os endpoints seguem estes padrões: + +| Servidor | O que faz | Padrão de URL MCP | +|----------|-----------|-------------------| +| **Genie** | Perguntas e respostas em linguagem natural sobre um Genie Space | `https:///api/2.0/mcp/genie/{genie_space_id}` | +| **Databricks SQL** | Executa SQL nos seus warehouses | `https:///api/2.0/mcp/sql` | +| **Unity Catalog Functions** | Executa funções UC registradas | `https:///api/2.0/mcp/functions/{catalog}/{schema}` | +| **Vector Search** | Consulta um índice do Vector Search | `https:///api/2.0/mcp/vector-search/{catalog}/{schema}` | + + +Você não precisa construir essas URLs manualmente — o CrewAI cria cada endpoint a partir do host do workspace e dos identificadores (Genie Space ID, ou catalog/schema) que você fornece ao configurar a conexão. Para a especificação completa e os detalhes mais recentes dos endpoints, consulte a [documentação de MCP gerenciado do Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). + + +## Conectando o Databricks no CrewAI AMP + + + Configurar um servidor MCP gerenciado do Databricks no CrewAI AMP + + +Cada recurso do Databricks — **Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions** e **Databricks Vector Search** — aparece como seu próprio servidor MCP no grupo Databricks da página **Tools & Integrations**. Configure os que você precisar: + + + + Navegue até **Tools & Integrations** na barra lateral esquerda do CrewAI AMP e localize o grupo **Databricks** na lista de Connections. Você verá os servidores Genie, SQL, Unity Catalog Functions e Vector Search listados abaixo dele. + + + + Clique em **Configure** ao lado do recurso que deseja habilitar e forneça os detalhes da conexão: + + - **Workspace Host** — o hostname do seu workspace do Databricks (ex.: `my-workspace.cloud.databricks.com`). + - **Genie** — o **Genie Space ID** a ser consultado. + - **Unity Catalog Functions** — o **catalog** e o **schema** que contêm suas funções. + - **Vector Search** — o **catalog** e o **schema** que contêm seu índice. + - **Databricks SQL** — sem identificadores adicionais; as consultas são executadas nos warehouses SQL do seu workspace. + + + + Selecione como o CrewAI se autentica no Databricks. **OAuth** é recomendado. + + - **Use OAuth** — Conecte-se com segurança usando OAuth 2.0. Cada usuário se autentica individualmente, e o Databricks emite tokens com escopo para o recurso (`genie`, `sql`, `unity-catalog` ou `vector-search`). O CrewAI gerencia o fluxo de autorização e renova os tokens automaticamente. + - **Use personal access token** — Autentique-se com um [token de acesso pessoal do Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/pat). Use uma identidade com privilégios mínimos para limitar a exposição. + + + + Conclua a autenticação. Uma vez conectado, as ferramentas do servidor ficam disponíveis para suas crews. Repita para qualquer outro recurso do Databricks que você queira habilitar. + + + + +Como cada recurso é uma conexão separada, você pode combiná-los livremente — por exemplo, habilitar Genie e Vector Search para uma crew de pesquisa e reservar SQL e Unity Catalog Functions para uma crew de engenharia de dados. As configurações de visibilidade permitem controlar quais membros da equipe podem usar cada um. + + +## Usando as ferramentas do Databricks nas suas crews + +Uma vez conectado, as ferramentas que cada servidor MCP expõe aparecem junto às conexões integradas na página **Tools & Integrations**. Você pode: + +- **Atribuir ferramentas aos agentes** nas suas crews, como qualquer outra ferramenta do CrewAI. +- **Gerenciar a visibilidade** para controlar quais membros da equipe podem usar cada conexão. +- **Editar ou remover** qualquer conexão a qualquer momento na lista de Connections. + +Seus agentes agora podem pedir respostas fundamentadas ao Genie, executar SQL nos seus warehouses, chamar funções do Unity Catalog e pesquisar índices do Vector Search — com os resultados retornando automaticamente ao raciocínio deles. + + +O Databricks aplica governança por meio do Unity Catalog e do Unity AI Gateway: um usuário só pode descobrir e invocar ferramentas que a identidade do seu workspace tem permissão para usar. Se uma chamada de ferramenta falhar, confirme se o usuário (ou a identidade do token) que está conectando tem os privilégios necessários do Unity Catalog no Genie Space, warehouse, função ou índice. Algumas consultas do Genie e do SQL são executadas de forma assíncrona e podem levar um momento para retornar resultados. + + +## Saiba mais + + + + Documentação oficial do Databricks para os servidores MCP gerenciados Genie, SQL, Unity Catalog Functions e Vector Search. + + + Saiba como o CrewAI se conecta a qualquer servidor MCP, a base sobre a qual a integração com o Databricks é construída. + + + + + Entre em contato com nossa equipe de suporte para obter ajuda com a configuração da integração com o Databricks ou com a solução de problemas. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/github.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/github.mdx new file mode 100644 index 000000000..4ef8731f2 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/github.mdx @@ -0,0 +1,312 @@ +--- +title: Integração com GitHub +description: "Gerenciamento de repositórios e issues com a integração do GitHub para CrewAI." +icon: "github" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem repositórios, issues e releases através do GitHub. Crie e atualize issues, gerencie releases, acompanhe o desenvolvimento do projeto e otimize seu fluxo de trabalho de desenvolvimento de software com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração do GitHub, assegure-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta GitHub com permissões adequadas no repositório +- Conta do GitHub conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com GitHub + +### 1. Conecte sua conta GitHub + +1. Acesse [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **GitHub** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de repositório e issues +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o pacote necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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 + +# Create an agent with GitHub capabilities +github_agent = Agent( + role="Repository Manager", + goal="Manage GitHub repositories, issues, and releases efficiently", + backstory="An AI assistant specialized in repository management and issue tracking.", + apps=['github'] +) + +# Task to create a new issue +create_issue_task = Task( + description="Create a bug report issue for the login functionality in the main repository", + agent=github_agent, + expected_output="Issue created successfully with issue number" +) + +# Run the task +crew = Crew( + agents=[github_agent], + tasks=[create_issue_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas GitHub Específicas + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage GitHub issues efficiently", + backstory="An AI assistant that focuses on issue tracking and management.", + apps=['github'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and assign it to the development team", + agent=issue_manager, + expected_output="Feature request issue created and assigned successfully" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento de Releases + +```python +from crewai import Agent, Task, Crew + +release_manager = Agent( + role="Release Manager", + goal="Manage software releases and versioning", + backstory="An experienced release manager who handles version control and release processes.", + apps=['github'] +) + +# Task to create a new release +release_task = Task( + description=""" + Create a new release v2.1.0 for the project with: + - Auto-generated release notes + - Target the main branch + - Include a description of new features and bug fixes + """, + agent=release_manager, + expected_output="Release v2.1.0 created successfully with release notes" +) + +crew = Crew( + agents=[release_manager], + tasks=[release_task] +) + +crew.kickoff() +``` + +### Acompanhamento e Gerenciamento de Issues + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Track and coordinate project issues and development progress", + backstory="An AI assistant that helps coordinate development work and track project progress.", + apps=['github'] +) + +# Complex task involving multiple GitHub operations +coordination_task = Task( + description=""" + 1. Search for all open issues assigned to the current milestone + 2. Identify overdue issues and update their priority labels + 3. Create a weekly progress report issue + 4. Lock resolved issues that have been inactive for 30 days + """, + agent=project_coordinator, + expected_output="Project coordination completed with progress report and issue management" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### Obtendo Ajuda + + + 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/gmail.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/gmail.mdx new file mode 100644 index 000000000..6e13e8967 --- /dev/null +++ b/docs/v1.15.1/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" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem e-mails, contatos e rascunhos através do Gmail. Envie e-mails, pesquise mensagens, gerencie contatos, crie rascunhos e otimize suas comunicações por e-mail com automação impulsionada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Gmail, certifique-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta do Gmail com as permissões adequadas +- Conectou sua conta do Gmail através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Gmail + +### 1. Conecte sua Conta do Gmail + +1. Navegue até [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Gmail** na seção de Integrações de Autenticação +3. Clique em **Conectar** e conclua o fluxo OAuth +4. Conceda as permissões necessárias para o gerenciamento de e-mail e contato +5. Copie seu Token Empresarial em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Create an agent with Gmail capabilities +gmail_agent = Agent( + role="Email Manager", + goal="Manage email communications and contacts efficiently", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail'] +) + +# Task to send a follow-up email +send_email_task = Task( + description="Send a follow-up email to john@example.com about the project update meeting", + agent=gmail_agent, + expected_output="Email sent successfully with confirmation" +) + +# Run the task +crew = Crew( + agents=[gmail_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Gmail + +```python + +email_coordinator = Agent( + role="Email Coordinator", + goal="Coordinate email communications and manage drafts", + backstory="An AI assistant that focuses on email coordination and draft management.", + apps=['gmail'] +) + +# Task to prepare and send emails +email_coordination = Task( + description="Search for emails from the marketing team, create a summary draft, and send it to stakeholders", + agent=email_coordinator, + expected_output="Summary email sent to stakeholders" +) + +crew = Crew( + agents=[email_coordinator], + tasks=[email_coordination] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos + +```python +from crewai import Agent, Task, Crew + +contact_manager = Agent( + role="Contact Manager", + goal="Manage and organize email contacts efficiently", + backstory="An experienced contact manager who maintains organized contact databases.", + apps=['gmail'] +) + +# Task to manage contacts +contact_task = Task( + description=""" + 1. Search for contacts from the 'example.com' domain + 2. Create new contacts for recent email senders not in the contact list + 3. Update contact information with recent interaction data + """, + agent=contact_manager, + expected_output="Contact database updated with new contacts and recent interactions" +) + +crew = Crew( + agents=[contact_manager], + tasks=[contact_task] +) + +crew.kickoff() +``` + +### Pesquisa e Análise de E-mails + +```python +from crewai import Agent, Task, Crew + +email_analyst = Agent( + role="Email Analyst", + goal="Analyze email patterns and provide insights", + backstory="An AI assistant that analyzes email data to provide actionable insights.", + apps=['gmail'] +) + +# Task to analyze email patterns +analysis_task = Task( + description=""" + Search for all unread emails from the last 7 days, + categorize them by sender domain, + and create a summary report of communication patterns + """, + agent=email_analyst, + expected_output="Email analysis report with communication patterns and recommendations" +) + +crew = Crew( + agents=[email_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Fluxos de Trabalho Automatizados de E-mail + +```python +from crewai import Agent, Task, Crew + +workflow_manager = Agent( + role="Email Workflow Manager", + goal="Automate email workflows and responses", + backstory="An AI assistant that manages automated email workflows and responses.", + apps=['gmail'] +) + +# Complex task involving multiple Gmail operations +workflow_task = Task( + description=""" + 1. Search for emails with 'urgent' in the subject from the last 24 hours + 2. Create draft responses for each urgent email + 3. Send automated acknowledgment emails to senders + 4. Create a summary report of urgent items requiring attention + """, + agent=workflow_manager, + expected_output="Urgent emails processed with automated responses and summary report" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nosso time de suporte para obter assistência na + configuração ou solução de problemas da integração Gmail. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/google_calendar.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/google_calendar.mdx new file mode 100644 index 000000000..1bc7352b4 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/google_calendar.mdx @@ -0,0 +1,405 @@ +--- +title: Integração com Google Calendar +description: "Gerenciamento de eventos e agendas com integração ao Google Calendar para o CrewAI." +icon: "calendar" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem eventos de calendário, agendas e disponibilidade através do Google Calendar. Crie e atualize eventos, gerencie participantes, verifique disponibilidade e otimize seu fluxo de agendamento com automação potencializada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Google Calendar, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Calendar +- Sua conta Google conectada pela [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com Google Calendar + +### 1. Conecte sua Conta Google + +1. Acesse [Integrações do CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Google Calendar** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso ao calendário e contatos +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Obter ferramentas empresariais (as ferramentas do Google Calendar serão incluídas) + +# Criar um agente com capacidades do Google Calendar +calendar_agent = Agent( + role="Schedule Manager", + goal="Gerenciar eventos de calendário e agendamento de maneira eficiente", + backstory="Um assistente de IA especializado em gerenciamento de agendas e coordenação de horários.", + apps=['google_calendar'] +) + +# Tarefa de criação de reunião +create_meeting_task = Task( + description="Crie uma reunião diária de equipe amanhã às 9h com o time de desenvolvimento", + agent=calendar_agent, + expected_output="Reunião criada com sucesso com link do Google Meet" +) + +# Executar a tarefa +crew = Crew( + agents=[calendar_agent], + tasks=[create_meeting_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Calendário + +```python + +# Obter apenas ferramentas específicas do Google Calendar + actions_list=["google_calendar/create_event", "google_calendar/view_events", "google_calendar/get_availability"] +) + +meeting_coordinator = Agent( + role="Meeting Coordinator", + goal="Coordenar reuniões e verificar disponibilidade", + backstory="Um assistente de IA que foca em agendamento de reuniões e gerenciamento de disponibilidade.", + apps=['google_calendar'] +) + +# Tarefa para agendar reunião com verificação de disponibilidade +schedule_meeting = Task( + description="Verifique a disponibilidade para a próxima semana e agende uma reunião de revisão do projeto com os stakeholders", + agent=meeting_coordinator, + expected_output="Reunião agendada após verificação da disponibilidade de todos os participantes" +) + +crew = Crew( + agents=[meeting_coordinator], + tasks=[schedule_meeting] +) + +crew.kickoff() +``` + +### Gerenciamento e Atualização de Eventos + +```python +from crewai import Agent, Task, Crew + +event_manager = Agent( + role="Event Manager", + goal="Gerenciar e atualizar eventos de calendário de forma eficiente", + backstory="Um experiente gestor de eventos responsável pela logística e atualizações dos eventos.", + apps=['google_calendar'] +) + +# Tarefa para gerenciar atualizações de eventos +event_management = Task( + description=""" + 1. Liste todos os eventos desta semana + 2. Atualize os eventos que precisarem de alteração de local para incluir links de videoconferência + 3. Envie convites de calendário para novos membros do time para reuniões recorrentes + """, + agent=event_manager, + expected_output="Eventos semanais atualizados com os locais corretos e novos participantes incluídos" +) + +crew = Crew( + agents=[event_manager], + tasks=[event_management] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos e Disponibilidade + +```python +from crewai import Agent, Task, Crew + +availability_coordinator = Agent( + role="Availability Coordinator", + goal="Coordenar disponibilidade e gerenciar contatos para agendamento", + backstory="Um assistente de IA que se especializa em gerenciamento de disponibilidade e coordenação de contatos.", + apps=['google_calendar'] +) + +# Tarefa de coordenação de disponibilidade +availability_task = Task( + description=""" + 1. Pesquise contatos no departamento de engenharia + 2. Verifique a disponibilidade de todos os engenheiros para a próxima sexta-feira à tarde + 3. Crie uma reunião de equipe no primeiro intervalo de 2 horas disponível + 4. Inclua o link do Google Meet e envie convites + """, + agent=availability_coordinator, + expected_output="Reunião agendada com base na disponibilidade com todos os engenheiros convidados" +) + +crew = Crew( + agents=[availability_coordinator], + tasks=[availability_task] +) + +crew.kickoff() +``` + +### Workflows de Agendamento Automatizado + +```python +from crewai import Agent, Task, Crew + +scheduling_automator = Agent( + role="Scheduling Automator", + goal="Automatizar workflows de agendamento e gerenciamento de calendários", + backstory="Um assistente de IA que automatiza cenários complexos de agendamento e workflows de agenda.", + apps=['google_calendar'] +) + +# Tarefa de automação de agendamento complexo +automation_task = Task( + description=""" + 1. Liste todos os eventos futuros das próximas duas semanas + 2. Identifique conflitos de agendamento ou reuniões consecutivas + 3. Sugira horários ótimos de reunião verificando as disponibilidades + 4. Crie intervalos entre reuniões quando necessário + 5. Atualize a descrição dos eventos com pautas e links de reunião + """, + agent=scheduling_automator, + expected_output="Calendário otimizado com conflitos resolvidos, intervalos e detalhes das reuniões atualizados" +) + +crew = Crew( + agents=[scheduling_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Google possui as permissões necessárias para acessar o calendário +- Verifique se a conexão OAuth inclui todos os escopos necessários para a API do Google Calendar +- Confirme se as configurações de compartilhamento do calendário permitem o nível de acesso necessário + +**Problemas na Criação de Eventos** + +- Verifique se os formatos de horário estão corretos (ISO8601 ou timestamps Unix) +- Assegure-se de que os endereços de e-mail dos participantes estão corretamente formatados +- Verifique se o calendário de destino existe e está acessível +- Confirme se os fusos horários estão especificados corretamente + +**Disponibilidade e Conflitos de Horário** + +- Use formato ISO adequado para os intervalos de horário ao verificar disponibilidade +- Certifique-se de que os fusos horários estão consistentes em todas as operações +- Verifique se os IDs dos calendários estão corretos ao consultar múltiplos calendários + +**Pesquisa de Contatos e Pessoas** + +- Assegure-se de que os termos de pesquisa estão devidamente formatados +- Verifique se as permissões para acesso ao diretório foram concedidas +- Certifique-se de que as informações de contato estão atualizadas e acessíveis + +**Atualização e Exclusão de Eventos** + +- Verifique se os IDs dos eventos estão corretos e se os eventos existem +- Assegure-se de que você possui permissões de edição para os eventos +- Verifique se a propriedade do calendário permite modificações + +### Obtendo Ajuda + + + 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/google_contacts.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/google_contacts.mdx new file mode 100644 index 000000000..fd1a3f629 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/google_contacts.mdx @@ -0,0 +1,341 @@ +--- +title: Integração Google Contacts +description: "Gerenciamento de contatos e diretório com integração Google Contacts para CrewAI." +icon: "address-book" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem informações de contatos e diretório através do Google Contacts. Acesse contatos pessoais, pesquise pessoas no diretório, crie e atualize informações de contato, e gerencie grupos de contatos com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Google Contacts, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Contacts +- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Google Contacts + +### 1. Conecte sua Conta Google + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Google Contacts** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a contatos e diretório +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Recuperar contatos do usuário do Google Contacts. + + **Parâmetros:** + - `pageSize` (integer, opcional): Número de contatos a retornar (máx 1000). Mínimo: 1, Máximo: 1000 + - `pageToken` (string, opcional): O token da página a recuperar. + - `personFields` (string, opcional): Campos a incluir (ex: 'names,emailAddresses,phoneNumbers'). Padrão: names,emailAddresses,phoneNumbers + - `requestSyncToken` (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false + - `sortOrder` (string, opcional): A ordem na qual as conexões devem ser classificadas. Opções: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING + + + + + **Descrição:** Pesquisar por contatos usando uma string de consulta. + + **Parâmetros:** + - `query` (string, obrigatório): String de consulta de pesquisa + - `readMask` (string, obrigatório): Campos a ler (ex: 'names,emailAddresses,phoneNumbers') + - `pageSize` (integer, opcional): Número de resultados a retornar. Mínimo: 1, Máximo: 30 + - `pageToken` (string, opcional): Token especificando qual página de resultado retornar. + - `sources` (array, opcional): As fontes para pesquisar. Opções: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. Padrão: READ_SOURCE_TYPE_CONTACT + + + + + **Descrição:** Listar pessoas no diretório do usuário autenticado. + + **Parâmetros:** + - `sources` (array, obrigatório): Fontes de diretório para pesquisar. Opções: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. Padrão: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE + - `pageSize` (integer, opcional): Número de pessoas a retornar. Mínimo: 1, Máximo: 1000 + - `pageToken` (string, opcional): Token especificando qual página de resultado retornar. + - `readMask` (string, opcional): Campos a ler (ex: 'names,emailAddresses') + - `requestSyncToken` (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false + - `mergeSources` (array, opcional): Dados adicionais para mesclar nas respostas de pessoas do diretório. Opções: CONTACT + + + + + **Descrição:** Pesquisar por pessoas no diretório. + + **Parâmetros:** + - `query` (string, obrigatório): Consulta de pesquisa + - `sources` (string, obrigatório): Fontes de diretório (use 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE') + - `pageSize` (integer, opcional): Número de resultados a retornar + - `readMask` (string, opcional): Campos a ler + + + + + **Descrição:** Listar outros contatos (não nos contatos pessoais do usuário). + + **Parâmetros:** + - `pageSize` (integer, opcional): Número de contatos a retornar. Mínimo: 1, Máximo: 1000 + - `pageToken` (string, opcional): Token especificando qual página de resultado retornar. + - `readMask` (string, opcional): Campos a ler + - `requestSyncToken` (boolean, opcional): Se a resposta deve incluir um token de sincronização. Padrão: false + + + + + **Descrição:** Pesquisar outros contatos. + + **Parâmetros:** + - `query` (string, obrigatório): Consulta de pesquisa + - `readMask` (string, obrigatório): Campos a ler (ex: 'names,emailAddresses') + - `pageSize` (integer, opcional): Número de resultados + + + + + **Descrição:** Obter informações de contato de uma única pessoa por nome do recurso. + + **Parâmetros:** + - `resourceName` (string, obrigatório): O nome do recurso da pessoa a obter (ex: 'people/c123456789') + - `personFields` (string, opcional): Campos a incluir (ex: 'names,emailAddresses,phoneNumbers'). Padrão: names,emailAddresses,phoneNumbers + + + + + **Descrição:** Criar um novo contato no catálogo de endereços do usuário. + + **Parâmetros:** + - `names` (array, opcional): Nomes da pessoa. Cada item é um objeto com `givenName` (string), `familyName` (string), `displayName` (string). + - `emailAddresses` (array, opcional): Endereços de email. Cada item é um objeto com `value` (string, endereço de email) e `type` (string, 'home', 'work', 'other', padrão 'other'). + - `phoneNumbers` (array, opcional): Números de telefone. Cada item é um objeto com `value` (string, número de telefone) e `type` (string, 'home', 'work', 'mobile', 'other', padrão 'other'). + - `addresses` (array, opcional): Endereços postais. Cada item é um objeto com `formattedValue` (string, endereço formatado) e `type` (string, 'home', 'work', 'other', padrão 'other'). + - `organizations` (array, opcional): Organizações/empresas. Cada item é um objeto com `name` (string, nome da organização), `title` (string, cargo) e `type` (string, 'work', 'other', padrão 'work'). + + + + + **Descrição:** Atualizar informações de um contato existente. + + **Parâmetros:** + - `resourceName` (string, obrigatório): O nome do recurso da pessoa a atualizar (ex: 'people/c123456789'). + - `updatePersonFields` (string, obrigatório): Campos a atualizar (ex: 'names,emailAddresses,phoneNumbers'). + - `names` (array, opcional): Nomes da pessoa. Cada item é um objeto com `givenName` (string), `familyName` (string), `displayName` (string). + - `emailAddresses` (array, opcional): Endereços de email. Cada item é um objeto com `value` (string, endereço de email) e `type` (string, 'home', 'work', 'other'). + - `phoneNumbers` (array, opcional): Números de telefone. Cada item é um objeto com `value` (string, número de telefone) e `type` (string, 'home', 'work', 'mobile', 'other'). + + + + + **Descrição:** Excluir um contato do catálogo de endereços do usuário. + + **Parâmetros:** + - `resourceName` (string, obrigatório): O nome do recurso da pessoa a excluir (ex: 'people/c123456789'). + + + + + **Descrição:** Obter informações sobre várias pessoas em uma única solicitação. + + **Parâmetros:** + - `resourceNames` (array, obrigatório): Nomes de recursos das pessoas a obter (máx 200 itens). + - `personFields` (string, opcional): Campos a incluir (ex: 'names,emailAddresses,phoneNumbers'). Padrão: names,emailAddresses,phoneNumbers + + + + + **Descrição:** Listar os grupos de contatos (rótulos) do usuário. + + **Parâmetros:** + - `pageSize` (integer, opcional): Número de grupos de contatos a retornar. Mínimo: 1, Máximo: 1000 + - `pageToken` (string, opcional): Token especificando qual página de resultado retornar. + - `groupFields` (string, opcional): Campos a incluir (ex: 'name,memberCount,clientData'). Padrão: name,memberCount + + + + + **Descrição:** Obter um grupo de contatos específico por nome do recurso. + + **Parâmetros:** + - `resourceName` (string, obrigatório): O nome do recurso do grupo de contatos (ex: 'contactGroups/myContactGroup'). + - `maxMembers` (integer, opcional): Número máximo de membros a incluir. Mínimo: 0, Máximo: 20000 + - `groupFields` (string, opcional): Campos a incluir (ex: 'name,memberCount,clientData'). Padrão: name,memberCount + + + + + **Descrição:** Criar um novo grupo de contatos (rótulo). + + **Parâmetros:** + - `name` (string, obrigatório): O nome do grupo de contatos. + - `clientData` (array, opcional): Dados específicos do cliente. Cada item é um objeto com `key` (string) e `value` (string). + + + + + **Descrição:** Atualizar informações de um grupo de contatos. + + **Parâmetros:** + - `resourceName` (string, obrigatório): O nome do recurso do grupo de contatos (ex: 'contactGroups/myContactGroup'). + - `name` (string, obrigatório): O nome do grupo de contatos. + - `clientData` (array, opcional): Dados específicos do cliente. Cada item é um objeto com `key` (string) e `value` (string). + + + + + **Descrição:** Excluir um grupo de contatos. + + **Parâmetros:** + - `resourceName` (string, obrigatório): O nome do recurso do grupo de contatos a excluir (ex: 'contactGroups/myContactGroup'). + - `deleteContacts` (boolean, opcional): Se os contatos do grupo também devem ser excluídos. Padrão: false + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Google Contacts + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Google Contacts +contacts_agent = Agent( + role="Gerenciador de Contatos", + goal="Gerenciar Google Contacts de forma eficiente", + backstory="Um assistente IA especializado em gerenciamento e organização de contatos.", + apps=['google_contacts'] # Todas as ações do Google Contacts estarão disponíveis +) + +# Tarefa para criar um novo contato +create_contact_task = Task( + description="Criar um novo contato chamado 'João Silva' com email 'joao.silva@exemplo.com' e telefone '11-98765-4321'", + agent=contacts_agent, + expected_output="Novo contato criado com sucesso" +) + +# Execute a tarefa +crew = Crew( + agents=[contacts_agent], + tasks=[create_contact_task] +) + +crew.kickoff() +``` + +### Pesquisando e Listando Contatos + +```python +from crewai import Agent, Task, Crew + +# Crie um agente focado em pesquisar contatos +search_agent = Agent( + role="Pesquisador de Contatos", + goal="Encontrar e recuperar informações de contato", + backstory="Um assistente IA habilidoso em pesquisar e listar contatos.", + apps=['google_contacts/search_contacts', 'google_contacts/get_contacts'] +) + +# Tarefa para pesquisar contatos +search_task = Task( + description="Pesquisar por contatos chamados 'Maria' e listar seus endereços de email e números de telefone.", + agent=search_agent, + expected_output="Lista de contatos correspondentes a 'Maria' com seus detalhes de email e telefone." +) + +crew = Crew( + agents=[search_agent], + tasks=[search_task] +) + +crew.kickoff() +``` + +### Gerenciando Grupos de Contatos + +```python +from crewai import Agent, Task, Crew + +# Crie um agente para gerenciar grupos de contatos +group_manager = Agent( + role="Organizador de Grupos de Contatos", + goal="Organizar contatos em grupos e gerenciar membros dos grupos", + backstory="Um assistente IA especializado em criar e gerenciar grupos do Google Contacts.", + apps=['google_contacts/create_contact_group', 'google_contacts/list_contact_groups'] +) + +# Tarefa para criar um novo grupo de contatos +create_group_task = Task( + description="Criar um novo grupo de contatos chamado 'Equipe de Marketing' e listar todos os grupos existentes.", + agent=group_manager, + expected_output="Novo grupo de contatos 'Equipe de Marketing' criado e lista de todos os grupos retornada." +) + +crew = Crew( + agents=[group_manager], + tasks=[create_group_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso a contatos e diretório. +- Verifique se a conexão OAuth inclui todos os escopos necessários para a API Google People. + +**Problemas de Criação/Atualização de Contatos** + +- Certifique-se de que campos obrigatórios como `email` sejam fornecidos para criação de contatos. +- Verifique se o `resourceName` está correto ao atualizar ou excluir contatos. +- Confirme se o formato dos dados para `names`, `emailAddresses`, `phoneNumbers`, etc., corresponde às especificações da API. + +**Problemas de Pesquisa e Filtro** + +- Certifique-se de que os parâmetros de `query` e `readMask` estejam especificados corretamente para `search_contacts` e `search_other_contacts`. +- Para pesquisas de diretório, certifique-se de que `sources` esteja definido corretamente (ex: 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE'). + +**Gerenciamento de Grupos de Contatos** + +- Ao criar um grupo de contatos, certifique-se de que o `name` seja fornecido. +- Para `get_contact_group`, certifique-se de que o `resourceName` esteja correto. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Google Contacts. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/google_docs.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/google_docs.mdx new file mode 100644 index 000000000..f5eb98194 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/google_docs.mdx @@ -0,0 +1,550 @@ +--- +title: Integração Google Docs +description: "Criação e edição de documentos com integração Google Docs para CrewAI." +icon: "file-lines" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes criem, editem e gerenciem documentos do Google Docs com manipulação de texto e formatação. Automatize a criação de documentos, insira e substitua texto, gerencie intervalos de conteúdo e simplifique seus fluxos de trabalho de documentos com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Google Docs, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Docs +- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Google Docs + +### 1. Conecte sua Conta Google + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Google Docs** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a documentos +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Criar um novo documento do Google. + + **Parâmetros:** + - `title` (string, opcional): O título para o novo documento. + + + + + **Descrição:** Obter o conteúdo e metadados de um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a recuperar. + - `includeTabsContent` (boolean, opcional): Se deve incluir conteúdo de abas. Padrão: false + - `suggestionsViewMode` (string, opcional): O modo de visualização de sugestões a aplicar ao documento. Opções: DEFAULT_FOR_CURRENT_ACCESS, PREVIEW_SUGGESTIONS_ACCEPTED, PREVIEW_WITHOUT_SUGGESTIONS. Padrão: DEFAULT_FOR_CURRENT_ACCESS + + + + + **Descrição:** Aplicar uma ou mais atualizações a um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a atualizar. + - `requests` (array, obrigatório): Uma lista de atualizações a aplicar ao documento. Cada item é um objeto representando uma solicitação. + - `writeControl` (object, opcional): Fornece controle sobre como as solicitações de escrita são executadas. Contém `requiredRevisionId` (string) e `targetRevisionId` (string). + + + + + **Descrição:** Inserir texto em um documento do Google em um local específico. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a atualizar. + - `text` (string, obrigatório): O texto a inserir. + - `index` (integer, opcional): O índice baseado em zero onde inserir o texto. Padrão: 1 + + + + + **Descrição:** Substituir todas as instâncias de texto em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a atualizar. + - `containsText` (string, obrigatório): O texto a encontrar e substituir. + - `replaceText` (string, obrigatório): O texto para substituir. + - `matchCase` (boolean, opcional): Se a pesquisa deve respeitar maiúsculas e minúsculas. Padrão: false + + + + + **Descrição:** Excluir conteúdo de um intervalo específico em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a atualizar. + - `startIndex` (integer, obrigatório): O índice inicial do intervalo a excluir. + - `endIndex` (integer, obrigatório): O índice final do intervalo a excluir. + + + + + **Descrição:** Inserir uma quebra de página em um local específico em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a atualizar. + - `index` (integer, opcional): O índice baseado em zero onde inserir a quebra de página. Padrão: 1 + + + + + **Descrição:** Criar um intervalo nomeado em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento a atualizar. + - `name` (string, obrigatório): O nome para o intervalo nomeado. + - `startIndex` (integer, obrigatório): O índice inicial do intervalo. + - `endIndex` (integer, obrigatório): O índice final do intervalo. + + + + + **Descrição:** Criar um novo documento do Google com conteúdo em uma única ação. + + **Parâmetros:** + - `title` (string, obrigatório): O título para o novo documento. Aparece no topo do documento e no Google Drive. + - `content` (string, opcional): O conteúdo de texto a inserir no documento. Use `\n` para novos parágrafos. + + + + + **Descrição:** Adicionar texto ao final de um documento do Google. Insere automaticamente no final do documento sem necessidade de especificar um índice. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento obtido da resposta de create_document ou URL. + - `text` (string, obrigatório): Texto a adicionar ao final do documento. Use `\n` para novos parágrafos. + + + + + **Descrição:** Aplicar ou remover formatação de negrito em texto de um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a formatar. + - `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo). + - `bold` (boolean, obrigatório): Defina `true` para aplicar negrito, `false` para remover negrito. + + + + + **Descrição:** Aplicar ou remover formatação de itálico em texto de um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a formatar. + - `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo). + - `italic` (boolean, obrigatório): Defina `true` para aplicar itálico, `false` para remover itálico. + + + + + **Descrição:** Adicionar ou remover formatação de sublinhado em texto de um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a formatar. + - `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo). + - `underline` (boolean, obrigatório): Defina `true` para sublinhar, `false` para remover sublinhado. + + + + + **Descrição:** Adicionar ou remover formatação de tachado em texto de um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a formatar. + - `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo). + - `strikethrough` (boolean, obrigatório): Defina `true` para adicionar tachado, `false` para remover. + + + + + **Descrição:** Alterar o tamanho da fonte do texto em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a formatar. + - `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo). + - `fontSize` (number, obrigatório): Tamanho da fonte em pontos. Tamanhos comuns: 10, 11, 12, 14, 16, 18, 24, 36. + + + + + **Descrição:** Alterar a cor do texto usando valores RGB (escala 0-1) em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a formatar. + - `endIndex` (integer, obrigatório): Posição final do texto a formatar (exclusivo). + - `red` (number, obrigatório): Componente vermelho (0-1). Exemplo: `1` para vermelho total. + - `green` (number, obrigatório): Componente verde (0-1). Exemplo: `0.5` para metade verde. + - `blue` (number, obrigatório): Componente azul (0-1). Exemplo: `0` para sem azul. + + + + + **Descrição:** Transformar texto existente em um hyperlink clicável em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do texto a transformar em link. + - `endIndex` (integer, obrigatório): Posição final do texto a transformar em link (exclusivo). + - `url` (string, obrigatório): A URL para a qual o link deve apontar. Exemplo: `"https://example.com"`. + + + + + **Descrição:** Aplicar um estilo de título ou parágrafo a um intervalo de texto em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do(s) parágrafo(s) a estilizar. + - `endIndex` (integer, obrigatório): Posição final do(s) parágrafo(s) a estilizar. + - `style` (string, obrigatório): O estilo a aplicar. Opções: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`. + + + + + **Descrição:** Definir o alinhamento de texto para parágrafos em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do(s) parágrafo(s) a alinhar. + - `endIndex` (integer, obrigatório): Posição final do(s) parágrafo(s) a alinhar. + - `alignment` (string, obrigatório): Alinhamento do texto. Opções: `START` (esquerda), `CENTER`, `END` (direita), `JUSTIFIED`. + + + + + **Descrição:** Definir o espaçamento entre linhas para parágrafos em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial do(s) parágrafo(s). + - `endIndex` (integer, obrigatório): Posição final do(s) parágrafo(s). + - `lineSpacing` (number, obrigatório): Espaçamento entre linhas como porcentagem. `100` = simples, `115` = 1.15x, `150` = 1.5x, `200` = duplo. + + + + + **Descrição:** Converter parágrafos em uma lista com marcadores ou numerada em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial dos parágrafos a converter em lista. + - `endIndex` (integer, obrigatório): Posição final dos parágrafos a converter em lista. + - `bulletPreset` (string, obrigatório): Estilo de marcadores/numeração. Opções: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`. + + + + + **Descrição:** Remover marcadores ou numeração de parágrafos em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `startIndex` (integer, obrigatório): Posição inicial dos parágrafos de lista. + - `endIndex` (integer, obrigatório): Posição final dos parágrafos de lista. + + + + + **Descrição:** Inserir uma tabela com conteúdo em um documento do Google em uma única ação. Forneça o conteúdo como um array 2D. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `rows` (integer, obrigatório): Número de linhas na tabela. + - `columns` (integer, obrigatório): Número de colunas na tabela. + - `index` (integer, opcional): Posição para inserir a tabela. Se não fornecido, a tabela é inserida no final do documento. + - `content` (array, obrigatório): Conteúdo da tabela como um array 2D. Cada array interno é uma linha. Exemplo: `[["Ano", "Receita"], ["2023", "$43B"], ["2024", "$45B"]]`. + + + + + **Descrição:** Inserir uma nova linha acima ou abaixo de uma célula de referência em uma tabela existente. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. Obtenha de get_document. + - `rowIndex` (integer, obrigatório): Índice da linha (baseado em 0) da célula de referência. + - `columnIndex` (integer, opcional): Índice da coluna (baseado em 0) da célula de referência. Padrão: `0`. + - `insertBelow` (boolean, opcional): Se `true`, insere abaixo da linha de referência. Se `false`, insere acima. Padrão: `true`. + + + + + **Descrição:** Inserir uma nova coluna à esquerda ou à direita de uma célula de referência em uma tabela existente. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. + - `rowIndex` (integer, opcional): Índice da linha (baseado em 0) da célula de referência. Padrão: `0`. + - `columnIndex` (integer, obrigatório): Índice da coluna (baseado em 0) da célula de referência. + - `insertRight` (boolean, opcional): Se `true`, insere à direita. Se `false`, insere à esquerda. Padrão: `true`. + + + + + **Descrição:** Excluir uma linha de uma tabela existente em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. + - `rowIndex` (integer, obrigatório): Índice da linha (baseado em 0) a excluir. + - `columnIndex` (integer, opcional): Índice da coluna (baseado em 0) de qualquer célula na linha. Padrão: `0`. + + + + + **Descrição:** Excluir uma coluna de uma tabela existente em um documento do Google. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. + - `rowIndex` (integer, opcional): Índice da linha (baseado em 0) de qualquer célula na coluna. Padrão: `0`. + - `columnIndex` (integer, obrigatório): Índice da coluna (baseado em 0) a excluir. + + + + + **Descrição:** Mesclar um intervalo de células de tabela em uma única célula. O conteúdo de todas as células é preservado. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. + - `rowIndex` (integer, obrigatório): Índice da linha inicial (baseado em 0) para a mesclagem. + - `columnIndex` (integer, obrigatório): Índice da coluna inicial (baseado em 0) para a mesclagem. + - `rowSpan` (integer, obrigatório): Número de linhas a mesclar. + - `columnSpan` (integer, obrigatório): Número de colunas a mesclar. + + + + + **Descrição:** Desfazer a mesclagem de células de tabela previamente mescladas, retornando-as a células individuais. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `tableStartIndex` (integer, obrigatório): O índice inicial da tabela. + - `rowIndex` (integer, obrigatório): Índice da linha (baseado em 0) da célula mesclada. + - `columnIndex` (integer, obrigatório): Índice da coluna (baseado em 0) da célula mesclada. + - `rowSpan` (integer, obrigatório): Número de linhas que a célula mesclada abrange. + - `columnSpan` (integer, obrigatório): Número de colunas que a célula mesclada abrange. + + + + + **Descrição:** Inserir uma imagem de uma URL pública em um documento do Google. A imagem deve ser publicamente acessível, ter menos de 50MB e estar no formato PNG/JPEG/GIF. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `uri` (string, obrigatório): URL pública da imagem. Deve ser acessível sem autenticação. + - `index` (integer, opcional): Posição para inserir a imagem. Se não fornecido, a imagem é inserida no final do documento. Padrão: `1`. + + + + + **Descrição:** Inserir uma quebra de seção para criar seções de documento com formatação diferente. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `index` (integer, obrigatório): Posição para inserir a quebra de seção. + - `sectionType` (string, obrigatório): O tipo de quebra de seção. Opções: `CONTINUOUS` (permanece na mesma página), `NEXT_PAGE` (inicia uma nova página). + + + + + **Descrição:** Criar um cabeçalho para o documento. Retorna um headerId que pode ser usado com insert_text para adicionar conteúdo ao cabeçalho. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `type` (string, opcional): Tipo de cabeçalho. Opções: `DEFAULT`. Padrão: `DEFAULT`. + + + + + **Descrição:** Criar um rodapé para o documento. Retorna um footerId que pode ser usado com insert_text para adicionar conteúdo ao rodapé. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `type` (string, opcional): Tipo de rodapé. Opções: `DEFAULT`. Padrão: `DEFAULT`. + + + + + **Descrição:** Excluir um cabeçalho do documento. Use get_document para encontrar o headerId. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `headerId` (string, obrigatório): O ID do cabeçalho a excluir. Obtenha da resposta de get_document. + + + + + **Descrição:** Excluir um rodapé do documento. Use get_document para encontrar o footerId. + + **Parâmetros:** + - `documentId` (string, obrigatório): O ID do documento. + - `footerId` (string, obrigatório): O ID do rodapé a excluir. Obtenha da resposta de get_document. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Google Docs + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Google Docs +docs_agent = Agent( + role="Criador de Documentos", + goal="Criar e gerenciar documentos do Google Docs de forma eficiente", + backstory="Um assistente IA especializado em criação e edição de documentos do Google Docs.", + apps=['google_docs'] # Todas as ações do Google Docs estarão disponíveis +) + +# Tarefa para criar um novo documento +create_doc_task = Task( + description="Criar um novo documento do Google intitulado 'Relatório de Status do Projeto'", + agent=docs_agent, + expected_output="Novo documento do Google 'Relatório de Status do Projeto' criado com sucesso" +) + +# Execute a tarefa +crew = Crew( + agents=[docs_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +### Edição de Texto e Gerenciamento de Conteúdo + +```python +from crewai import Agent, Task, Crew + +# Crie um agente focado em edição de texto +text_editor = Agent( + role="Editor de Documentos", + goal="Editar e atualizar conteúdo em documentos do Google Docs", + backstory="Um assistente IA habilidoso em edição precisa de texto e gerenciamento de conteúdo.", + apps=['google_docs/insert_text', 'google_docs/replace_text', 'google_docs/delete_content_range'] +) + +# Tarefa para editar conteúdo do documento +edit_content_task = Task( + description="No documento 'your_document_id', inserir o texto 'Resumo Executivo: ' no início, depois substituir todas as instâncias de 'TODO' por 'CONCLUÍDO'.", + agent=text_editor, + expected_output="Documento atualizado com novo texto inserido e itens TODO substituídos." +) + +crew = Crew( + agents=[text_editor], + tasks=[edit_content_task] +) + +crew.kickoff() +``` + +### Operações Avançadas de Documentos + +```python +from crewai import Agent, Task, Crew + +# Crie um agente para operações avançadas de documentos +document_formatter = Agent( + role="Formatador de Documentos", + goal="Aplicar formatação avançada e estrutura a documentos do Google", + backstory="Um assistente IA que lida com formatação complexa de documentos e organização.", + apps=['google_docs/batch_update', 'google_docs/insert_page_break', 'google_docs/create_named_range'] +) + +# Tarefa para formatar documento +format_doc_task = Task( + description="No documento 'your_document_id', inserir uma quebra de página na posição 100, criar um intervalo nomeado chamado 'Introdução' para caracteres 1-50, e aplicar atualizações de formatação em lote.", + agent=document_formatter, + expected_output="Documento formatado com quebra de página, intervalo nomeado e estilo aplicado." +) + +crew = Crew( + agents=[document_formatter], + tasks=[format_doc_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso ao Google Docs. +- Verifique se a conexão OAuth inclui todos os escopos necessários (`https://www.googleapis.com/auth/documents`). + +**Problemas de ID do Documento** + +- Verifique novamente os IDs dos documentos para correção. +- Certifique-se de que o documento existe e está acessível à sua conta. +- IDs de documentos podem ser encontrados na URL do Google Docs. + +**Inserção de Texto e Operações de Intervalo** + +- Ao usar `insert_text` ou `delete_content_range`, certifique-se de que as posições de índice sejam válidas. +- Lembre-se de que o Google Docs usa indexação baseada em zero. +- O documento deve ter conteúdo nas posições de índice especificadas. + +**Formatação de Solicitação de Atualização em Lote** + +- Ao usar `batch_update`, certifique-se de que o array `requests` esteja formatado corretamente de acordo com a documentação da API do Google Docs. +- Atualizações complexas requerem estruturas JSON específicas para cada tipo de solicitação. + +**Operações de Substituição de Texto** + +- Para `replace_text`, certifique-se de que o parâmetro `containsText` corresponda exatamente ao texto que você deseja substituir. +- Use o parâmetro `matchCase` para controlar a sensibilidade a maiúsculas e minúsculas. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Google Docs. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/google_drive.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/google_drive.mdx new file mode 100644 index 000000000..c47d6abc3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/google_drive.mdx @@ -0,0 +1,70 @@ +--- +title: Integração Google Drive +description: "Gerenciamento de arquivos e pastas com integração Google Drive para CrewAI." +icon: "google" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes acessem e gerenciem arquivos e pastas no Google Drive. Faça upload, download, organize conteúdo, crie links de compartilhamento e simplifique seus fluxos de trabalho de armazenamento em nuvem com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Google Drive, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Drive +- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Google Drive + +### 1. Conecte sua Conta Google + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Google Drive** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a arquivos +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + +Para informações detalhadas sobre parâmetros e uso, consulte a [documentação em inglês](../../../en/enterprise/integrations/google_drive). + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso ao Google Drive. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Google Drive. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/google_sheets.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/google_sheets.mdx new file mode 100644 index 000000000..aa3809a60 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/google_sheets.mdx @@ -0,0 +1,327 @@ +--- +title: Integração com Google Sheets +description: "Sincronização de dados de planilhas com a integração do Google Sheets para CrewAI." +icon: "google" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem dados de planilhas por meio do Google Sheets. Leia linhas, crie novos registros, atualize dados existentes e otimize os fluxos de trabalho de gerenciamento de dados com automação alimentada por IA. Perfeito para acompanhamento de dados, relatórios e gestão colaborativa de informações. + +## Pré-requisitos + +Antes de utilizar a integração com o Google Sheets, certifique-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Sheets +- Sua conta Google conectada pela [página de integrações](https://app.crewai.com/crewai_plus/connectors) +- Planilhas com cabeçalhos de coluna adequados para operações com dados + +## Configurando a Integração com Google Sheets + +### 1. Conecte sua Conta Google + +1. Acesse [Integrações do CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Localize **Google Sheets** na seção Integrações de Autenticação +3. Clique em **Conectar** e conclua o fluxo OAuth +4. Conceda as permissões necessárias para acesso à planilha +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Obtenha as ferramentas enterprise (ferramentas Google Sheets incluídas) + +# Crie um agente com capacidades para Google Sheets +sheets_agent = Agent( + role="Data Manager", + goal="Gerenciar dados de planilha e rastrear informações de maneira eficiente", + backstory="Um assistente de IA especializado em gestão de dados e operações em planilhas.", + apps=['google_sheets'] +) + +# Tarefa para adicionar novos dados a uma planilha +data_entry_task = Task( + description="Adicionar novo registro de cliente na planilha de banco de dados de clientes com nome, e-mail e data de cadastro", + agent=sheets_agent, + expected_output="Novo registro de cliente adicionado com sucesso à planilha" +) + +# Execute a tarefa +crew = Crew( + agents=[sheets_agent], + tasks=[data_entry_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Google Sheets + +```python + +# Obtenha apenas ferramentas específicas do Google Sheets + actions_list=["google_sheets/get_values", "google_sheets/update_values"] +) + +data_collector = Agent( + role="Data Collector", + goal="Coletar e organizar dados em planilhas", + backstory="Um assistente de IA dedicado à coleta e organização de dados.", + apps=['google_sheets'] +) + +# Tarefa para coletar e organizar dados +data_collection = Task( + description="Recuperar dados atuais de inventário e adicionar novos produtos à planilha de inventário", + agent=data_collector, + expected_output="Dados de inventário recuperados e novos produtos adicionados com sucesso" +) + +crew = Crew( + agents=[data_collector], + tasks=[data_collection] +) + +crew.kickoff() +``` + +### Análise de Dados e Geração de Relatórios + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Data Analyst", + goal="Analisar dados de planilhas e gerar insights", + backstory="Um analista de dados experiente que extrai insights dos dados de planilhas.", + apps=['google_sheets'] +) + +# Tarefa para analisar dados e criar relatórios +analysis_task = Task( + description=""" + 1. Recuperar todos os dados de vendas da planilha do mês atual + 2. Analisar os dados em busca de tendências e padrões + 3. Criar um relatório resumo em uma nova linha com os principais indicadores + """, + agent=data_analyst, + expected_output="Dados de vendas analisados e relatório resumo criado com os principais insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Atualizações Automatizadas de Dados + +```python +from crewai import Agent, Task, Crew + +data_updater = Agent( + role="Data Updater", + goal="Atualizar e manter dados de planilhas automaticamente", + backstory="Um assistente de IA que mantém a precisão dos dados e atualiza registros automaticamente.", + apps=['google_sheets'] +) + +# Tarefa para atualizar dados com base em condições +update_task = Task( + description=""" + 1. Encontrar todos os pedidos pendentes na planilha de pedidos + 2. Atualizar o status para 'processing' + 3. Adicionar um registro de data/hora da atualização do status + 4. Registrar as alterações em uma planilha de acompanhamento separada + """, + agent=data_updater, + expected_output="Todos os pedidos pendentes atualizados para o status processing com registros de data/hora" +) + +crew = Crew( + agents=[data_updater], + tasks=[update_task] +) + +crew.kickoff() +``` + +### Fluxo de Trabalho Complexo com Dados + +```python +from crewai import Agent, Task, Crew + +workflow_manager = Agent( + role="Data Workflow Manager", + goal="Gerenciar fluxos de dados complexos entre várias planilhas", + backstory="Um assistente de IA que orquestra operações complexas de dados entre várias planilhas.", + apps=['google_sheets'] +) + +# Tarefa de workflow complexa +workflow_task = Task( + description=""" + 1. Obter todos os dados de clientes da planilha principal de clientes + 2. Criar registros de resumo mensal para clientes ativos + 3. Atualizar o status de clientes com base na atividade nos últimos 30 dias + 4. Gerar um relatório mensal com métricas dos clientes + 5. Arquivar registros de clientes inativos em uma planilha separada + """, + agent=workflow_manager, + expected_output="Workflow mensal de clientes concluído com atualizações de status e relatórios gerados" +) + +crew = Crew( + agents=[workflow_manager], + tasks=[workflow_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** + +- Certifique-se de que sua conta Google tem acesso de edição às planilhas alvo +- Verifique se a conexão OAuth inclui os escopos necessários para a API do Google Sheets +- Confira se as planilhas estão compartilhadas com a conta autenticada + +**Problemas de Estrutura da Planilha** + +- Certifique-se de que as worksheets têm cabeçalhos de coluna antes de criar ou atualizar linhas +- Verifique se os nomes das colunas em `additionalFields` correspondem exatamente aos cabeçalhos +- Confirme que a worksheet especificada existe na planilha + +**Problemas de Tipo e Formato de Dados** + +- Garanta que os valores dos dados estejam no formato esperado para cada coluna +- Utilize formatos de data adequados nas colunas de data (recomenda-se ISO) +- Verifique se valores numéricos estão devidamente formatados para colunas numéricas + +**Problemas com Fórmulas de Filtro** + +- Certifique-se de que as fórmulas de filtro seguem a estrutura JSON correta para forma normal disjuntiva +- Use nomes de campos válidos, correspondendo exatamente aos cabeçalhos das colunas +- Teste filtros simples antes de criar consultas com múltiplas condições +- Verifique se os tipos de operadores correspondem aos tipos de dados das colunas + +**Limites de Linhas e Performance** + +- Fique atento aos limites de linhas ao usar `GOOGLE_SHEETS_GET_ROW` +- Considere paginação para grandes volumes de dados +- Use filtros específicos para reduzir a quantidade de dados processados + +**Operações de Atualização** + +- Certifique-se de que as condições de filtro identifiquem corretamente as linhas a serem atualizadas +- Teste condições de filtro com pequenos conjuntos de dados antes de grandes atualizações +- Verifique se todos os campos obrigatórios estão incluídos nas operações de atualização + +### Obtendo Ajuda + + + 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/google_slides.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/google_slides.mdx new file mode 100644 index 000000000..c185e12ec --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/google_slides.mdx @@ -0,0 +1,403 @@ +--- +title: Integração Google Slides +description: "Criação e gerenciamento de apresentações com integração Google Slides para CrewAI." +icon: "chart-bar" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes criem, editem e gerenciem apresentações do Google Slides. Crie apresentações, atualize conteúdo, importe dados do Google Sheets, gerencie páginas e miniaturas, e simplifique seus fluxos de trabalho de apresentações com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Google Slides, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Google com acesso ao Google Slides +- Conectado sua conta Google através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Google Slides + +### 1. Conecte sua Conta Google + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Google Slides** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a apresentações, planilhas e drive +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Cria uma apresentação em branco sem conteúdo. + + **Parâmetros:** + - `title` (string, obrigatório): O título da apresentação. + + + + + **Descrição:** Obter metadados leves de uma apresentação (título, número de slides, IDs dos slides). Use isso primeiro antes de recuperar o conteúdo completo. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação a ser recuperada. + + + + + **Descrição:** Extrair todo o conteúdo de texto de uma apresentação. Retorna IDs dos slides e texto de formas e tabelas apenas (sem formatação). + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + + + + + **Descrição:** Recupera uma apresentação por ID. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação a ser recuperada. + - `fields` (string, opcional): Os campos a incluir na resposta. Use isso para melhorar o desempenho retornando apenas os dados necessários. + + + + + **Descrição:** Aplica atualizações, adiciona conteúdo ou remove conteúdo de uma apresentação. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação a ser atualizada. + - `requests` (array, obrigatório): Uma lista de atualizações a aplicar à apresentação. Cada item é um objeto representando uma solicitação. + - `writeControl` (object, opcional): Fornece controle sobre como as solicitações de escrita são executadas. Contém `requiredRevisionId` (string). + + + + + **Descrição:** Extrair conteúdo de texto de um único slide. Retorna apenas texto de formas e tabelas (sem formatação ou estilo). + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `pageObjectId` (string, obrigatório): O ID do slide/página para obter o texto. + + + + + **Descrição:** Recupera uma página específica por seu ID. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `pageObjectId` (string, obrigatório): O ID da página a ser recuperada. + + + + + **Descrição:** Gera uma miniatura da página. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `pageObjectId` (string, obrigatório): O ID da página para geração de miniatura. + + + + + **Descrição:** Adicionar um slide em branco adicional a uma apresentação. Novas apresentações já possuem um slide em branco - verifique get_presentation_metadata primeiro. Para slides com áreas de título/corpo, use create_slide_with_layout. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `insertionIndex` (integer, opcional): Onde inserir o slide (baseado em 0). Se omitido, adiciona no final. + + + + + **Descrição:** Criar um slide com layout predefinido contendo áreas de espaço reservado para título, corpo, etc. Melhor que create_slide para conteúdo estruturado. Após criar, use get_page para encontrar os IDs de espaço reservado, depois insira texto neles. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `layout` (string, obrigatório): Tipo de layout. Um de: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. TITLE_AND_BODY é melhor para título+descrição. TITLE para slides apenas com título. SECTION_HEADER para divisores de seção. + - `insertionIndex` (integer, opcional): Onde inserir (baseado em 0). Se omitido, adiciona no final. + + + + + **Descrição:** Criar uma caixa de texto em um slide com conteúdo. Use para títulos, descrições, parágrafos - não para tabelas. Opcionalmente especifique posição (x, y) e tamanho (width, height) em unidades EMU (914400 EMU = 1 polegada). + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do slide para adicionar a caixa de texto. + - `text` (string, obrigatório): O conteúdo de texto da caixa de texto. + - `x` (integer, opcional): Posição X em EMU (914400 = 1 polegada). Padrão: 914400 (1 polegada da esquerda). + - `y` (integer, opcional): Posição Y em EMU (914400 = 1 polegada). Padrão: 914400 (1 polegada do topo). + - `width` (integer, opcional): Largura em EMU. Padrão: 7315200 (~8 polegadas). + - `height` (integer, opcional): Altura em EMU. Padrão: 914400 (~1 polegada). + + + + + **Descrição:** Remover um slide de uma apresentação. Use get_presentation primeiro para encontrar o ID do slide. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do objeto do slide a excluir. Obtenha de get_presentation. + + + + + **Descrição:** Criar uma cópia de um slide existente. A duplicata é inserida imediatamente após o original. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do objeto do slide a duplicar. Obtenha de get_presentation. + + + + + **Descrição:** Reordenar slides movendo-os para uma nova posição. Os IDs dos slides devem estar na ordem atual da apresentação (sem duplicatas). + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideIds` (array de strings, obrigatório): Array de IDs dos slides a mover. Obrigatoriamente na ordem atual da apresentação. + - `insertionIndex` (integer, obrigatório): Posição de destino (baseado em 0). 0 = início, número de slides = final. + + + + + **Descrição:** Incorporar um vídeo do YouTube em um slide. O ID do vídeo é o valor após "v=" nas URLs do YouTube (ex: para youtube.com/watch?v=abc123, use "abc123"). + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do slide para adicionar o vídeo. Obtenha de get_presentation. + - `videoId` (string, obrigatório): O ID do vídeo do YouTube (o valor após v= na URL). + + + + + **Descrição:** Incorporar um vídeo do Google Drive em um slide. O ID do arquivo pode ser encontrado na URL do arquivo no Drive. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do slide para adicionar o vídeo. Obtenha de get_presentation. + - `fileId` (string, obrigatório): O ID do arquivo do Google Drive do vídeo. + + + + + **Descrição:** Definir uma imagem de fundo para um slide. A URL da imagem deve ser publicamente acessível. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do slide para definir o fundo. Obtenha de get_presentation. + - `imageUrl` (string, obrigatório): URL publicamente acessível da imagem a usar como fundo. + + + + + **Descrição:** Criar uma tabela vazia em um slide. Para criar uma tabela com conteúdo, use create_table_with_content. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do slide para adicionar a tabela. Obtenha de get_presentation. + - `rows` (integer, obrigatório): Número de linhas na tabela. + - `columns` (integer, obrigatório): Número de colunas na tabela. + + + + + **Descrição:** Criar uma tabela com conteúdo em uma única ação. Forneça o conteúdo como uma matriz 2D onde cada array interno é uma linha. Exemplo: [["Cabeçalho1", "Cabeçalho2"], ["Linha1Col1", "Linha1Col2"]]. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `slideId` (string, obrigatório): O ID do slide para adicionar a tabela. Obtenha de get_presentation. + - `rows` (integer, obrigatório): Número de linhas na tabela. + - `columns` (integer, obrigatório): Número de colunas na tabela. + - `content` (array, obrigatório): Conteúdo da tabela como matriz 2D. Cada array interno é uma linha. Exemplo: [["Ano", "Receita"], ["2023", "$10M"]]. + + + + + **Descrição:** Importa dados de uma planilha do Google para uma apresentação. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `sheetId` (string, obrigatório): O ID da planilha do Google para importar. + - `dataRange` (string, obrigatório): O intervalo de dados a importar da planilha. + + + + + **Descrição:** Faz upload de um arquivo para o Google Drive associado à apresentação. + + **Parâmetros:** + - `file` (string, obrigatório): Os dados do arquivo a fazer upload. + - `presentationId` (string, obrigatório): O ID da apresentação para vincular o arquivo carregado. + + + + + **Descrição:** Vincula um arquivo no Google Drive a uma apresentação. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação. + - `fileId` (string, obrigatório): O ID do arquivo a vincular. + + + + + **Descrição:** Lista todas as apresentações acessíveis ao usuário. + + **Parâmetros:** + - `pageSize` (integer, opcional): O número de apresentações a retornar por página. + - `pageToken` (string, opcional): Um token para paginação. + + + + + **Descrição:** Exclui uma apresentação por ID. + + **Parâmetros:** + - `presentationId` (string, obrigatório): O ID da apresentação a ser excluída. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Google Slides + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Google Slides +slides_agent = Agent( + role="Criador de Apresentações", + goal="Criar e gerenciar apresentações do Google Slides de forma eficiente", + backstory="Um assistente IA especializado em design de apresentações e gerenciamento de conteúdo.", + apps=['google_slides'] # Todas as ações do Google Slides estarão disponíveis +) + +# Tarefa para criar uma nova apresentação +create_presentation_task = Task( + description="Criar uma nova apresentação em branco intitulada 'Relatório de Vendas Trimestral'", + agent=slides_agent, + expected_output="Nova apresentação 'Relatório de Vendas Trimestral' criada com sucesso" +) + +# Execute a tarefa +crew = Crew( + agents=[slides_agent], + tasks=[create_presentation_task] +) + +crew.kickoff() +``` + +### Atualizando Conteúdo da Apresentação + +```python +from crewai import Agent, Task, Crew + +# Crie um agente focado em atualizar apresentações +updater_agent = Agent( + role="Atualizador de Apresentações", + goal="Atualizar e modificar apresentações existentes do Google Slides", + backstory="Um assistente IA habilidoso em fazer atualizações precisas no conteúdo de apresentações.", + apps=['google_slides/batch_update_presentation'] +) + +# Tarefa para atualizar uma apresentação +update_presentation_task = Task( + description="Atualizar a apresentação com ID 'your_presentation_id' para adicionar uma nova caixa de texto no primeiro slide com o conteúdo 'Destaques Principais'.", + agent=updater_agent, + expected_output="Apresentação atualizada com novo conteúdo." +) + +crew = Crew( + agents=[updater_agent], + tasks=[update_presentation_task] +) + +crew.kickoff() +``` + +### Importando Dados e Gerenciando Arquivos + +```python +from crewai import Agent, Task, Crew + +# Crie um agente para importação de dados e gerenciamento de arquivos +data_presenter = Agent( + role="Apresentador de Dados", + goal="Importar dados para apresentações e gerenciar arquivos vinculados", + backstory="Um assistente IA que integra dados de várias fontes em apresentações.", + apps=['google_slides/import_data_from_sheet', 'google_slides/upload_file_to_drive'] +) + +# Tarefa para importar dados de uma planilha +import_data_task = Task( + description="Importar dados da planilha do Google 'your_sheet_id' intervalo 'A1:C10' para a apresentação 'your_presentation_id'.", + agent=data_presenter, + expected_output="Dados importados da planilha do Google para a apresentação." +) + +crew = Crew( + agents=[data_presenter], + tasks=[import_data_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Google tenha as permissões necessárias para acesso ao Google Slides e Google Drive. +- Verifique se a conexão OAuth inclui todos os escopos necessários. + +**Problemas de ID de Apresentação/Página** + +- Verifique novamente os IDs de apresentação e IDs de objeto de página para correção. +- Certifique-se de que a apresentação ou página existe e está acessível. + +**Formatação de Solicitação de Atualização em Lote** + +- Ao usar `batch_update_presentation`, certifique-se de que o array `requests` esteja formatado corretamente de acordo com a documentação da API do Google Slides. +- Atualizações complexas frequentemente requerem estruturas JSON específicas para cada tipo de solicitação (ex: `createText`, `insertShape`). + +**Problemas de Upload/Vinculação de Arquivos** + +- Certifique-se de que o conteúdo do `file` esteja fornecido corretamente para `upload_file_to_drive`. +- Verifique se o `fileId` está correto ao vincular arquivos a uma apresentação. +- Verifique as permissões do Google Drive para acesso a arquivos. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Google Slides. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/hubspot.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/hubspot.mdx new file mode 100644 index 000000000..16999abdd --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/hubspot.mdx @@ -0,0 +1,618 @@ +--- +title: "Integração com HubSpot" +description: "Gerencie empresas e contatos no HubSpot com o CrewAI." +icon: "briefcase" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem empresas e contatos dentro do HubSpot. Crie novos registros e otimize seus processos de CRM com automação baseada em IA. + +## Pré-requisitos + +Antes de utilizar a integração com o HubSpot, certifique-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa. +- Uma conta HubSpot com permissões adequadas. +- Sua conta HubSpot conectada pela [página de Integrações](https://app.crewai.com/crewai_plus/connectors). + +## Configurando a Integração com o HubSpot + +### 1. Conecte Sua Conta HubSpot + +1. Navegue até [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors). +2. Encontre **HubSpot** na seção de Integrações de Autenticação. +3. Clique em **Conectar** e complete o fluxo OAuth. +4. Conceda as permissões necessárias para gerenciamento de empresas e contatos. +5. Copie o seu Token Enterprise nas [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Obtenha as ferramentas enterprise (ferramentas HubSpot incluídas) + +# Crie um agente com capacidades HubSpot +hubspot_agent = Agent( + role="CRM Manager", + goal="Manage company and contact records in HubSpot", + backstory="An AI assistant specialized in CRM management.", + apps=['hubspot'] +) + +# Task para criar nova empresa +create_company_task = Task( + description="Create a new company in HubSpot with name 'Innovate Corp' and domain 'innovatecorp.com'.", + agent=hubspot_agent, + expected_output="Company created successfully with confirmation" +) + +# Execute a tarefa +crew = Crew( + agents=[hubspot_agent], + tasks=[create_company_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas HubSpot Específicas + +```python + +# Obtenha somente a ferramenta para criar contatos + actions_list=["hubspot/create_contact"] +) + +contact_creator = Agent( + role="Contact Creator", + goal="Create new contacts in HubSpot", + backstory="An AI assistant that focuses on creating new contact entries in the CRM.", + apps=['hubspot'] +) + +# Task para criar contato +create_contact = Task( + description="Create a new contact for 'John Doe' with email 'john.doe@example.com'.", + agent=contact_creator, + expected_output="Contact created successfully in HubSpot." +) + +crew = Crew( + agents=[contact_creator], + tasks=[create_contact] +) + +crew.kickoff() +``` + +### Gerenciamento de Contatos + +```python +from crewai import Agent, Task, Crew + +crm_manager = Agent( + role="CRM Manager", + goal="Manage and organize HubSpot contacts efficiently.", + backstory="An experienced CRM manager who maintains an organized contact database.", + apps=['hubspot'] +) + +# Task para gerenciar contatos +contact_task = Task( + description="Create a new contact for 'Jane Smith' at 'Global Tech Inc.' with email 'jane.smith@globaltech.com'.", + agent=crm_manager, + expected_output="Contact database updated with the new contact." +) + +crew = Crew( + agents=[crm_manager], + tasks=[contact_task] +) + +crew.kickoff() +``` + +### Precisa de Ajuda? + + + Entre em contato com nossa equipe de suporte para assistência na configuração + ou solução de problemas com a integração HubSpot. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/jira.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/jira.mdx new file mode 100644 index 000000000..7a5f7b856 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/jira.mdx @@ -0,0 +1,392 @@ +--- +title: Integração com Jira +description: "Rastreamento de problemas e gestão de projetos com a integração Jira para CrewAI." +icon: "bug" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem problemas, projetos e fluxos de trabalho pelo Jira. Crie e atualize issues, acompanhe o progresso de projetos, gerencie atribuições e otimize sua gestão de projetos com automação potencializada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Jira, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Jira com permissões adequadas para o projeto +- Sua conta Jira conectada pela [Página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Jira + +### 1. Conectar Sua Conta Jira + +1. Acesse [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Jira** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo do OAuth +4. Conceda as permissões necessárias para gestão de issues e projetos +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instalar o Pacote Necessário + +```bash +uv add crewai-tools +``` + +## Ações Disponíveis + + + + **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 + +# Obtenha as ferramentas enterprise (incluirá ferramentas do Jira) + +# Criação de um agente com capacidades Jira +jira_agent = Agent( + role="Issue Manager", + goal="Gerenciar issues do Jira e acompanhar o progresso do projeto de forma eficiente", + backstory="Um assistente de IA especializado em rastreamento de issues e gestão de projetos.", + apps=['jira'] +) + +# Tarefa para criar um relatório de bug +create_bug_task = Task( + description="Criar um relatório de bug para a funcionalidade de login com alta prioridade e designar para o time de desenvolvimento", + agent=jira_agent, + expected_output="Bug report creado com sucesso e chave da issue" +) + +# Executar a tarefa +crew = Crew( + agents=[jira_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Jira Específicas + +```python + +# Obtenha apenas ferramentas Jira específicas + actions_list=["jira/create_issue", "jira/update_issue", "jira/search_by_jql"] +) + +issue_coordinator = Agent( + role="Issue Coordinator", + goal="Criar e gerenciar issues Jira de forma eficiente", + backstory="Um assistente de IA focado na criação e gestão de issues.", + apps=['jira'] +) + +# Tarefa para gerenciar workflow de issues +issue_workflow = Task( + description="Criar uma issue de solicitação de feature e atualizar o status de issues relacionadas", + agent=issue_coordinator, + expected_output="Feature request criada e issues relacionadas atualizadas" +) + +crew = Crew( + agents=[issue_coordinator], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Análise e Relatórios de Projeto + +```python +from crewai import Agent, Task, Crew + +project_analyst = Agent( + role="Project Analyst", + goal="Analisar dados de projetos e gerar insights a partir do Jira", + backstory="Um analista de projetos experiente que extrai insights de dados de gestão de projetos.", + apps=['jira'] +) + +# Tarefa para analisar status do projeto +analysis_task = Task( + description=""" + 1. Obtenha todos os projetos e seus tipos de issues + 2. Busque todas as issues abertas entre projetos + 3. Analise distribuição de issues por status e responsável + 4. Crie uma issue de relatório de resumo com os achados + """, + agent=project_analyst, + expected_output="Análise do projeto completa com relatório de resumo criado" +) + +crew = Crew( + agents=[project_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### Gestão Automatizada de Issues + +```python +from crewai import Agent, Task, Crew + +automation_manager = Agent( + role="Automation Manager", + goal="Automatizar gestão de issues e processos de workflow", + backstory="Um assistente de IA que automatiza tarefas repetitivas de gestão de issues.", + apps=['jira'] +) + +# Tarefa para automatizar gestão de issues +automation_task = Task( + description=""" + 1. Buscar todas as issues não atribuídas usando JQL + 2. Obter responsáveis disponíveis de cada projeto + 3. Atribuir issues automaticamente com base na carga de trabalho e especialidade + 4. Atualizar prioridades das issues baseando-se na idade e tipo + 5. Criar issues semanais de planejamento de sprint + """, + agent=automation_manager, + expected_output="Issues atribuídas automaticamente e issues de planejamento de sprint criadas" +) + +crew = Crew( + agents=[automation_manager], + tasks=[automation_task] +) + +crew.kickoff() +``` + +### Operações Avançadas Baseadas em Schema + +```python +from crewai import Agent, Task, Crew + +schema_specialist = Agent( + role="Schema Specialist", + goal="Executar operações complexas no Jira usando schemas dinâmicos", + backstory="Um assistente de IA que manipula schemas dinâmicos e tipos de issues customizadas do Jira.", + apps=['jira'] +) + +# Tarefa usando operações baseadas em schema +schema_task = Task( + description=""" + 1. Obtenha todos os projetos e seus tipos personalizados de issues + 2. Para cada tipo personalizado, descreva o schema de ação + 3. Crie issues usando schema dinâmico para campos complexos customizados + 4. Atualize issues com valores de campos personalizados a partir de regras de negócio + """, + agent=schema_specialist, + expected_output="Issues customizadas criadas e atualizadas utilizando schemas dinâmicos" +) + +crew = Crew( + agents=[schema_specialist], + tasks=[schema_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** + +- Certifique-se de que sua conta Jira tem as permissões necessárias nos projetos alvo +- Verifique se a conexão OAuth inclui os escopos necessários da API Jira +- Confira se você possui permissões de criar/editar issues nos projetos especificados + +**Chaves de Projeto ou Issue Inválidas** + +- Confira o formato das chaves dos projetos e issues (ex: "PROJ-123") +- Verifique se os projetos existem e são acessíveis pela sua conta +- Certifique-se de que chaves de issues referenciam issues existentes + +**Problemas de Tipo ou Status de Issue** + +- Use JIRA_GET_ISSUE_TYPES_BY_PROJECT para obter tipos válidos de issue para um projeto +- Use JIRA_GET_ISSUE_STATUS_BY_PROJECT para obter status válidos +- Certifique-se de que tipos e status de issue estão disponíveis no projeto alvo + +**Problemas com Queries JQL** + +- Teste as queries JQL na busca de issues do Jira antes de utilizar em chamadas de API +- Certifique-se de que os nomes dos campos em JQL estejam corretos e existam em sua instância do Jira +- Use a sintaxe correta de JQL para queries complexas + +**Problemas com Campos Customizados e Schemas** + +- Use JIRA_DESCRIBE_ACTION_SCHEMA para obter o schema correto para tipos de issues complexas +- Certifique-se de que os IDs dos campos customizados estão corretos (ex: "customfield_10001") +- Verifique se esses campos estão disponíveis no projeto e tipo de issue alvo + +**Problemas de Fórmulas de Filtro** + +- Garanta que as fórmulas de filtro sigam a estrutura JSON correta para forma normal disjuntiva +- Use apenas campos válidos conforme configuração do seu Jira +- Teste filtros simples antes de construir queries complexas com múltiplas condições + +### Obtenha Ajuda + + + Entre em contato com nosso time de suporte para obter assistência na + configuração ou solução de problemas da integração Jira. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/linear.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/linear.mdx new file mode 100644 index 000000000..5a6f63b3f --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/linear.mdx @@ -0,0 +1,470 @@ +--- +title: Integração com o Linear +description: "Acompanhamento de projetos de software e rastreamento de bugs com a integração Linear para CrewAI." +icon: "list-check" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem issues, projetos e fluxos de trabalho de desenvolvimento através do Linear. Crie e atualize issues, gerencie cronogramas de projetos, organize equipes e otimize seu processo de desenvolvimento de software com automação impulsionada por IA. + +## Pré-requisitos + +Antes de utilizar a integração com o Linear, certifique-se de que você possui: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com uma assinatura ativa +- Uma conta Linear com permissões apropriadas no workspace +- Conectou sua conta Linear através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Linear + +### 1. Conecte sua Conta Linear + +1. Navegue até [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Linear** na seção Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para gerenciamento de issues e projetos +5. Copie seu Token Empresarial em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Obtenha ferramentas empresariais (ferramentas do Linear serão incluídas) + +# Crie um agente com funcionalidades do Linear +linear_agent = Agent( + role="Development Manager", + goal="Gerenciar issues do Linear e acompanhar o progresso do desenvolvimento de forma eficiente", + backstory="Um assistente de IA especializado em gerenciamento de projetos de desenvolvimento de software.", + apps=['linear'] +) + +# Tarefa para criar um relatório de bug +create_bug_task = Task( + description="Crie um relatório de bug de alta prioridade para o sistema de autenticação e atribua à equipe de backend", + agent=linear_agent, + expected_output="Bug report criado com sucesso com ID da issue" +) + +# Execute a tarefa +crew = Crew( + agents=[linear_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Lineares Específicas + +```python + +# Obtenha apenas ferramentas lineares específicas + actions_list=["linear/create_issue", "linear/update_issue", "linear/search_issue"] +) + +issue_manager = Agent( + role="Issue Manager", + goal="Criar e gerenciar issues no Linear de forma eficiente", + backstory="Um assistente de IA focado na criação e no gerenciamento do ciclo de vida de issues.", + apps=['linear'] +) + +# Tarefa para gerenciar fluxo de issues +issue_workflow = Task( + description="Crie uma issue de solicitação de recurso e atualize os status das issues relacionadas para refletir o progresso atual", + agent=issue_manager, + expected_output="Solicitação de recurso criada e issues relacionadas atualizadas" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento de Projetos e Equipes + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordenar projetos e equipes no Linear de forma eficiente", + backstory="Um coordenador de projetos experiente que gerencia ciclos de desenvolvimento e fluxos de trabalho de equipe.", + apps=['linear'] +) + +# Tarefa para coordenar a configuração de projeto +project_coordination = Task( + description=""" + 1. Pesquise por equipes de engenharia no Linear + 2. Crie um novo projeto para o desenvolvimento de recursos do Q2 + 3. Associe o projeto às equipes relevantes + 4. Crie marcos iniciais do projeto como issues + """, + agent=project_coordinator, + expected_output="Projeto Q2 criado com equipes atribuídas e marcos iniciais estabelecidos" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### Hierarquia de Issues e Gerenciamento de Sub-tarefas + +```python +from crewai import Agent, Task, Crew + +task_organizer = Agent( + role="Task Organizer", + goal="Organizar issues complexas em sub-tarefas gerenciáveis", + backstory="Um assistente de IA que divide trabalhos de desenvolvimento complexos em sub-tarefas organizadas.", + apps=['linear'] +) + +# Tarefa para criar hierarquia de issues +hierarchy_task = Task( + description=""" + 1. Pesquise por issues de recursos grandes que precisam ser divididos + 2. Para cada issue complexa, crie sub-issues para diferentes componentes + 3. Atualize as issues principais com descrições adequadas e links para sub-issues + 4. Atribua sub-issues aos membros apropriados da equipe com base na especialidade + """, + agent=task_organizer, + expected_output="Issues complexas divididas em sub-tarefas gerenciáveis com atribuições corretas" +) + +crew = Crew( + agents=[task_organizer], + tasks=[hierarchy_task] +) + +crew.kickoff() +``` + +### Fluxo de Trabalho de Desenvolvimento Automatizado + +```python +from crewai import Agent, Task, Crew + +workflow_automator = Agent( + role="Workflow Automator", + goal="Automatizar processos de fluxo de trabalho de desenvolvimento no Linear", + backstory="Um assistente de IA que automatiza tarefas repetitivas de fluxo de trabalho de desenvolvimento.", + apps=['linear'] +) + +# Tarefa de automação de workflow complexa +automation_task = Task( + description=""" + 1. Pesquise por issues que estejam em progresso há mais de 7 dias + 2. Atualize suas prioridades com base nas datas de vencimento e importância do projeto + 3. Crie issues semanais de planejamento de sprint para cada equipe + 4. Arquive issues concluídas do ciclo anterior + 5. Gere relatórios de status do projeto como novas issues + """, + agent=workflow_automator, + expected_output="Fluxo de desenvolvimento automatizado com prioridades atualizadas, planejamento de sprint e relatórios de status" +) + +crew = Crew( + agents=[workflow_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** + +- Certifique-se de que sua conta Linear possui as permissões necessárias no workspace de destino +- Verifique se a conexão OAuth inclui os escopos requeridos pela API do Linear +- Confirme se você tem permissões para criar/editar issues e projetos no workspace + +**IDs e Referências Inválidas** + +- Verifique os IDs de equipes, IDs de issues e IDs de projetos para garantir o formato UUID correto +- Assegure que as entidades referenciadas (equipes, projetos, ciclos) existem e estão acessíveis +- Verifique se os identificadores de issues seguem o formato correto (ex: "ABC-1") + +**Problemas de Associação entre Equipe e Projeto** + +- Use LINEAR_SEARCH_TEAMS para obter IDs de equipe válidos antes de criar issues ou projetos +- Certifique-se de que as equipes existem e estão ativas no seu workspace +- Verifique se os IDs das equipes estão devidamente formatados como UUIDs + +**Problemas com Status e Prioridade das Issues** + +- Verifique se os IDs de status referenciam estados de workflow válidos para a equipe +- Certifique-se de que os valores de prioridade estão dentro do intervalo válido para sua configuração do Linear +- Confirme que campos personalizados e labels existem antes de referenciá-los + +**Problemas com Formato de Data e Hora** + +- Use o formato ISO 8601 para datas de vencimento e timestamps +- Certifique-se de que os fusos horários estão corretos para cálculos de datas de vencimento +- Verifique se os valores de data são válidos e posteriores à data atual para datas de vencimento + +**Problemas de Pesquisa e Filtros** + +- Garanta que as consultas de busca estejam formatadas corretamente e não estejam vazias +- Utilize nomes de campos válidos nas fórmulas de filtro: `title`, `number`, `project`, `createdAt` +- Teste filtros simples antes de montar consultas complexas com múltiplas condições +- Verifique se os tipos de operadores correspondem aos tipos de dados dos campos filtrados + +**Problemas na Criação de Sub-issues** + +- Certifique-se de que os IDs das issues pai são válidos e acessíveis +- Verifique se o ID da equipe para as sub-issues corresponde ou é compatível com o da issue pai +- Assegure-se de que as issues pai não estejam arquivadas ou excluídas + +### Obtendo Ajuda + + + 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_excel.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_excel.mdx new file mode 100644 index 000000000..a053c8ba6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_excel.mdx @@ -0,0 +1,289 @@ +--- +title: Integração Microsoft Excel +description: "Gerenciamento de pastas de trabalho e dados com integração Microsoft Excel para CrewAI." +icon: "table" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes criem e gerenciem pastas de trabalho, planilhas, tabelas e gráficos do Excel no OneDrive ou SharePoint. Manipule intervalos de dados, crie visualizações, gerencie tabelas e simplifique seus fluxos de trabalho de planilhas com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Microsoft Excel, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Microsoft 365 com acesso ao Excel e OneDrive/SharePoint +- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Microsoft Excel + +### 1. Conecte sua Conta Microsoft + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Microsoft Excel** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a arquivos e pastas de trabalho do Excel +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Criar uma nova pasta de trabalho do Excel no OneDrive ou SharePoint. + + **Parâmetros:** + - `file_path` (string, obrigatório): Caminho onde criar a pasta de trabalho (ex: 'MinhaPastaDeTrabalho.xlsx') + - `worksheets` (array, opcional): Planilhas iniciais para criar. Cada item é um objeto com `name` (string, nome da planilha). + + + + + **Descrição:** Obter todas as pastas de trabalho do Excel do OneDrive ou SharePoint. + + **Parâmetros:** + - `select` (string, opcional): Selecionar propriedades específicas para retornar. + - `filter` (string, opcional): Filtrar resultados usando sintaxe OData. + - `expand` (string, opcional): Expandir recursos relacionados inline. + - `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999). + - `orderby` (string, opcional): Ordenar resultados por propriedades especificadas. + + + + + **Descrição:** Obter todas as planilhas em uma pasta de trabalho do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `select` (string, opcional): Selecionar propriedades específicas para retornar (ex: 'id,name,position'). + - `filter` (string, opcional): Filtrar resultados usando sintaxe OData. + - `expand` (string, opcional): Expandir recursos relacionados inline. + - `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999). + - `orderby` (string, opcional): Ordenar resultados por propriedades especificadas. + + + + + **Descrição:** Criar uma nova planilha em uma pasta de trabalho do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `name` (string, obrigatório): Nome da nova planilha. + + + + + **Descrição:** Obter dados de um intervalo específico em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `range` (string, obrigatório): Endereço do intervalo (ex: 'A1:C10'). + + + + + **Descrição:** Atualizar dados em um intervalo específico em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `range` (string, obrigatório): Endereço do intervalo (ex: 'A1:C10'). + - `values` (array, obrigatório): Array 2D de valores para definir no intervalo. Cada array interno representa uma linha, e elementos podem ser string, number ou integer. + + + + + **Descrição:** Criar uma tabela em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `range` (string, obrigatório): Intervalo para a tabela (ex: 'A1:D10'). + - `has_headers` (boolean, opcional): Se a primeira linha contém cabeçalhos. Padrão: true. + + + + + **Descrição:** Obter todas as tabelas em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + + + + + **Descrição:** Adicionar uma nova linha a uma tabela do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `table_name` (string, obrigatório): Nome da tabela. + - `values` (array, obrigatório): Array de valores para a nova linha. Elementos podem ser string, number ou integer. + + + + + **Descrição:** Obter dados de uma tabela específica em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `table_name` (string, obrigatório): Nome da tabela. + + + + + **Descrição:** Criar um gráfico em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `chart_type` (string, obrigatório): Tipo de gráfico (ex: 'ColumnClustered', 'Line', 'Pie'). + - `source_data` (string, obrigatório): Intervalo de dados para o gráfico (ex: 'A1:B10'). + - `series_by` (string, opcional): Como interpretar os dados ('Auto', 'Columns' ou 'Rows'). Padrão: 'Auto'. + + + + + **Descrição:** Obter o valor de uma única célula em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `row` (integer, obrigatório): Número da linha (baseado em 0). + - `column` (integer, obrigatório): Número da coluna (baseado em 0). + + + + + **Descrição:** Obter o intervalo usado de uma planilha do Excel (contém todos os dados). + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + + + + + **Descrição:** Obter os metadados do intervalo usado (apenas dimensões, sem dados) de uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + + + + + **Descrição:** Obter todos os gráficos em uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + + + + + **Descrição:** Excluir uma planilha de uma pasta de trabalho do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha a excluir. + + + + + **Descrição:** Excluir uma tabela de uma planilha do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + - `worksheet_name` (string, obrigatório): Nome da planilha. + - `table_name` (string, obrigatório): Nome da tabela a excluir. + + + + + **Descrição:** Obter todos os intervalos nomeados em uma pasta de trabalho do Excel. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do arquivo Excel. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Microsoft Excel + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Microsoft Excel +excel_agent = Agent( + role="Gerenciador de Dados Excel", + goal="Gerenciar pastas de trabalho e dados do Excel de forma eficiente", + backstory="Um assistente IA especializado em operações do Microsoft Excel e manipulação de dados.", + apps=['microsoft_excel'] # Todas as ações do Excel estarão disponíveis +) + +# Tarefa para criar uma nova pasta de trabalho +create_workbook_task = Task( + description="Criar uma nova pasta de trabalho do Excel chamada 'RelatorioMensal.xlsx' com uma planilha inicial chamada 'DadosVendas'.", + agent=excel_agent, + expected_output="Nova pasta de trabalho 'RelatorioMensal.xlsx' criada com planilha 'DadosVendas'." +) + +# Execute a tarefa +crew = Crew( + agents=[excel_agent], + tasks=[create_workbook_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a arquivos (ex: `Files.Read.All`, `Files.ReadWrite.All`). +- Verifique se a conexão OAuth inclui todos os escopos necessários. + +**Problemas de Criação de Arquivos** + +- Ao criar pastas de trabalho, certifique-se de que o `file_path` termine com extensão `.xlsx`. +- Verifique se você tem permissões de escrita no local de destino (OneDrive/SharePoint). + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Microsoft Excel. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_onedrive.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_onedrive.mdx new file mode 100644 index 000000000..b23ae1c1d --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_onedrive.mdx @@ -0,0 +1,249 @@ +--- +title: Integração Microsoft OneDrive +description: "Gerenciamento de arquivos e pastas com integração Microsoft OneDrive para CrewAI." +icon: "cloud" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes façam upload, download e gerenciem arquivos e pastas no Microsoft OneDrive. Automatize operações de arquivos, organize conteúdo, crie links de compartilhamento e simplifique seus fluxos de trabalho de armazenamento em nuvem com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Microsoft OneDrive, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Microsoft com acesso ao OneDrive +- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Microsoft OneDrive + +### 1. Conecte sua Conta Microsoft + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Microsoft OneDrive** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a arquivos +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Listar arquivos e pastas no OneDrive. + + **Parâmetros:** + - `top` (integer, opcional): Número de itens a recuperar (máx 1000). Padrão: 50. + - `orderby` (string, opcional): Ordenar por campo (ex: "name asc", "lastModifiedDateTime desc"). Padrão: "name asc". + - `filter` (string, opcional): Expressão de filtro OData. + + + + + **Descrição:** Obter informações sobre um arquivo ou pasta específica. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo ou pasta. + + + + + **Descrição:** Baixar um arquivo do OneDrive. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo a baixar. + + + + + **Descrição:** Fazer upload de um arquivo para o OneDrive. + + **Parâmetros:** + - `file_name` (string, obrigatório): Nome do arquivo a fazer upload. + - `content` (string, obrigatório): Conteúdo do arquivo codificado em Base64. + + + + + **Descrição:** Criar uma nova pasta no OneDrive. + + **Parâmetros:** + - `folder_name` (string, obrigatório): Nome da pasta a criar. + + + + + **Descrição:** Excluir um arquivo ou pasta do OneDrive. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo ou pasta a excluir. + + + + + **Descrição:** Copiar um arquivo ou pasta no OneDrive. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo ou pasta a copiar. + - `parent_id` (string, opcional): O ID da pasta de destino (opcional, padrão para raiz). + - `new_name` (string, opcional): Novo nome para o item copiado (opcional). + + + + + **Descrição:** Mover um arquivo ou pasta no OneDrive. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo ou pasta a mover. + - `parent_id` (string, obrigatório): O ID da pasta de destino. + - `new_name` (string, opcional): Novo nome para o item (opcional). + + + + + **Descrição:** Pesquisar arquivos e pastas no OneDrive. + + **Parâmetros:** + - `query` (string, obrigatório): String de consulta de pesquisa. + - `top` (integer, opcional): Número de resultados a retornar (máx 1000). Padrão: 50. + + + + + **Descrição:** Criar um link de compartilhamento para um arquivo ou pasta. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo ou pasta a compartilhar. + - `type` (string, opcional): Tipo de link de compartilhamento. Opções: view, edit, embed. Padrão: view. + - `scope` (string, opcional): Escopo do link de compartilhamento. Opções: anonymous, organization. Padrão: anonymous. + + + + + **Descrição:** Obter miniaturas para um arquivo. + + **Parâmetros:** + - `item_id` (string, obrigatório): O ID do arquivo. + + + + + **Descrição:** Listar arquivos e pastas em um caminho específico do OneDrive. + + **Parâmetros:** + - `folder_path` (string, obrigatório): O caminho da pasta (ex: 'Documents/Reports'). + - `top` (integer, opcional): Número de itens a recuperar (máx 1000). Padrão: 50. + - `orderby` (string, opcional): Ordenar por campo (ex: "name asc", "lastModifiedDateTime desc"). Padrão: "name asc". + + + + + **Descrição:** Obter arquivos acessados recentemente no OneDrive. + + **Parâmetros:** + - `top` (integer, opcional): Número de itens a recuperar (máx 200). Padrão: 25. + + + + + **Descrição:** Obter arquivos e pastas compartilhados com o usuário. + + **Parâmetros:** + - `top` (integer, opcional): Número de itens a recuperar (máx 200). Padrão: 50. + - `orderby` (string, opcional): Ordenar por campo. Padrão: "name asc". + + + + + **Descrição:** Obter informações sobre um arquivo ou pasta específica pelo caminho. + + **Parâmetros:** + - `file_path` (string, obrigatório): O caminho do arquivo ou pasta (ex: 'Documents/report.docx'). + + + + + **Descrição:** Baixar um arquivo do OneDrive pelo seu caminho. + + **Parâmetros:** + - `file_path` (string, obrigatório): O caminho do arquivo (ex: 'Documents/report.docx'). + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Microsoft OneDrive + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Microsoft OneDrive +onedrive_agent = Agent( + role="Gerenciador de Arquivos", + goal="Gerenciar arquivos e pastas no OneDrive de forma eficiente", + backstory="Um assistente IA especializado em operações de arquivos do Microsoft OneDrive e organização.", + apps=['microsoft_onedrive'] # Todas as ações do OneDrive estarão disponíveis +) + +# Tarefa para listar arquivos e criar pasta +organize_files_task = Task( + description="Listar todos os arquivos no diretório raiz do meu OneDrive e criar uma nova pasta chamada 'Documentos do Projeto'.", + agent=onedrive_agent, + expected_output="Lista de arquivos exibida e nova pasta 'Documentos do Projeto' criada." +) + +# Execute a tarefa +crew = Crew( + agents=[onedrive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a arquivos (ex: `Files.Read`, `Files.ReadWrite`). +- Verifique se a conexão OAuth inclui todos os escopos necessários. + +**Problemas de Upload de Arquivos** + +- Certifique-se de que `file_name` e `content` sejam fornecidos para uploads de arquivos. +- O conteúdo deve ser codificado em Base64 para arquivos binários. +- Verifique se você tem permissões de escrita no OneDrive. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Microsoft OneDrive. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_outlook.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_outlook.mdx new file mode 100644 index 000000000..a872d1997 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_outlook.mdx @@ -0,0 +1,255 @@ +--- +title: Integração Microsoft Outlook +description: "Gerenciamento de email, calendário e contatos com integração Microsoft Outlook para CrewAI." +icon: "envelope" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes acessem e gerenciem emails, eventos de calendário e contatos do Outlook. Envie emails, recupere mensagens, gerencie eventos de calendário e organize contatos com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Microsoft Outlook, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Microsoft com acesso ao Outlook +- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Microsoft Outlook + +### 1. Conecte sua Conta Microsoft + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Microsoft Outlook** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a email, calendário e contatos +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Obter mensagens de email da caixa de correio do usuário. + + **Parâmetros:** + - `top` (integer, opcional): Número de mensagens a recuperar (máx 1000). Padrão: 10. + - `filter` (string, opcional): Expressão de filtro OData (ex: "isRead eq false"). + - `search` (string, opcional): String de consulta de pesquisa. + - `orderby` (string, opcional): Ordenar por campo (ex: "receivedDateTime desc"). Padrão: "receivedDateTime desc". + - `select` (string, opcional): Selecionar propriedades específicas para retornar. + - `expand` (string, opcional): Expandir recursos relacionados inline. + + + + + **Descrição:** Enviar uma mensagem de email. + + **Parâmetros:** + - `to_recipients` (array, obrigatório): Array de endereços de email dos destinatários. + - `cc_recipients` (array, opcional): Array de endereços de email dos destinatários em cópia. + - `bcc_recipients` (array, opcional): Array de endereços de email dos destinatários em cópia oculta. + - `subject` (string, obrigatório): Assunto do email. + - `body` (string, obrigatório): Conteúdo do corpo do email. + - `body_type` (string, opcional): Tipo de conteúdo do corpo. Opções: Text, HTML. Padrão: HTML. + - `importance` (string, opcional): Nível de importância da mensagem. Opções: low, normal, high. Padrão: normal. + - `reply_to` (array, opcional): Array de endereços de email para resposta. + - `save_to_sent_items` (boolean, opcional): Se deve salvar a mensagem na pasta Itens Enviados. Padrão: true. + + + + + **Descrição:** Obter eventos de calendário do calendário do usuário. + + **Parâmetros:** + - `top` (integer, opcional): Número de eventos a recuperar (máx 1000). Padrão: 10. + - `skip` (integer, opcional): Número de eventos a pular. Padrão: 0. + - `filter` (string, opcional): Expressão de filtro OData (ex: "start/dateTime ge '2024-01-01T00:00:00Z'"). + - `orderby` (string, opcional): Ordenar por campo (ex: "start/dateTime asc"). Padrão: "start/dateTime asc". + + + + + **Descrição:** Criar um novo evento de calendário. + + **Parâmetros:** + - `subject` (string, obrigatório): Assunto/título do evento. + - `body` (string, opcional): Corpo/descrição do evento. + - `start_datetime` (string, obrigatório): Data e hora de início no formato ISO 8601 (ex: '2024-01-20T10:00:00'). + - `end_datetime` (string, obrigatório): Data e hora de término no formato ISO 8601. + - `timezone` (string, opcional): Fuso horário (ex: 'Pacific Standard Time'). Padrão: UTC. + - `location` (string, opcional): Local do evento. + - `attendees` (array, opcional): Array de endereços de email dos participantes. + + + + + **Descrição:** Obter contatos do catálogo de endereços do usuário. + + **Parâmetros:** + - `top` (integer, opcional): Número de contatos a recuperar (máx 1000). Padrão: 10. + - `skip` (integer, opcional): Número de contatos a pular. Padrão: 0. + - `filter` (string, opcional): Expressão de filtro OData. + - `orderby` (string, opcional): Ordenar por campo (ex: "displayName asc"). Padrão: "displayName asc". + + + + + **Descrição:** Criar um novo contato no catálogo de endereços do usuário. + + **Parâmetros:** + - `displayName` (string, obrigatório): Nome de exibição do contato. + - `givenName` (string, opcional): Primeiro nome do contato. + - `surname` (string, opcional): Sobrenome do contato. + - `emailAddresses` (array, opcional): Array de endereços de email. Cada item é um objeto com `address` (string) e `name` (string). + - `businessPhones` (array, opcional): Array de números de telefone comerciais. + - `homePhones` (array, opcional): Array de números de telefone residenciais. + - `jobTitle` (string, opcional): Cargo do contato. + - `companyName` (string, opcional): Nome da empresa do contato. + + + + + **Descrição:** Obter uma mensagem de email específica por ID. + + **Parâmetros:** + - `message_id` (string, obrigatório): O identificador único da mensagem. Obter pela ação get_messages. + - `select` (string, opcional): Lista separada por vírgulas de propriedades a retornar. Exemplo: "id,subject,body,from,receivedDateTime". Padrão: "id,subject,body,from,toRecipients,receivedDateTime". + + + + + **Descrição:** Responder a uma mensagem de email. + + **Parâmetros:** + - `message_id` (string, obrigatório): O identificador único da mensagem a responder. Obter pela ação get_messages. + - `comment` (string, obrigatório): O conteúdo da mensagem de resposta. Pode ser texto simples ou HTML. A mensagem original será citada abaixo deste conteúdo. + + + + + **Descrição:** Encaminhar uma mensagem de email. + + **Parâmetros:** + - `message_id` (string, obrigatório): O identificador único da mensagem a encaminhar. Obter pela ação get_messages. + - `to_recipients` (array, obrigatório): Array de endereços de email dos destinatários. Exemplo: ["john@example.com", "jane@example.com"]. + - `comment` (string, opcional): Mensagem opcional a incluir acima do conteúdo encaminhado. Pode ser texto simples ou HTML. + + + + + **Descrição:** Marcar uma mensagem como lida ou não lida. + + **Parâmetros:** + - `message_id` (string, obrigatório): O identificador único da mensagem. Obter pela ação get_messages. + - `is_read` (boolean, obrigatório): Definir como true para marcar como lida, false para marcar como não lida. + + + + + **Descrição:** Excluir uma mensagem de email. + + **Parâmetros:** + - `message_id` (string, obrigatório): O identificador único da mensagem a excluir. Obter pela ação get_messages. + + + + + **Descrição:** Atualizar um evento de calendário existente. + + **Parâmetros:** + - `event_id` (string, obrigatório): O identificador único do evento. Obter pela ação get_calendar_events. + - `subject` (string, opcional): Novo assunto/título do evento. + - `start_time` (string, opcional): Nova hora de início no formato ISO 8601 (ex: "2024-01-20T10:00:00"). OBRIGATÓRIO: Também deve fornecer start_timezone ao usar este campo. + - `start_timezone` (string, opcional): Fuso horário da hora de início. OBRIGATÓRIO ao atualizar start_time. Exemplos: "Pacific Standard Time", "Eastern Standard Time", "UTC". + - `end_time` (string, opcional): Nova hora de término no formato ISO 8601. OBRIGATÓRIO: Também deve fornecer end_timezone ao usar este campo. + - `end_timezone` (string, opcional): Fuso horário da hora de término. OBRIGATÓRIO ao atualizar end_time. Exemplos: "Pacific Standard Time", "Eastern Standard Time", "UTC". + - `location` (string, opcional): Novo local do evento. + - `body` (string, opcional): Novo corpo/descrição do evento. Suporta formatação HTML. + + + + + **Descrição:** Excluir um evento de calendário. + + **Parâmetros:** + - `event_id` (string, obrigatório): O identificador único do evento a excluir. Obter pela ação get_calendar_events. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Microsoft Outlook + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Microsoft Outlook +outlook_agent = Agent( + role="Assistente de Email", + goal="Gerenciar emails, eventos de calendário e contatos de forma eficiente", + backstory="Um assistente IA especializado em operações do Microsoft Outlook e gerenciamento de comunicação.", + apps=['microsoft_outlook'] # Todas as ações do Outlook estarão disponíveis +) + +# Tarefa para enviar um email +send_email_task = Task( + description="Enviar um email para 'colega@exemplo.com' com assunto 'Atualização do Projeto' e corpo 'Olá, aqui está a última atualização do projeto. Atenciosamente.'", + agent=outlook_agent, + expected_output="Email enviado com sucesso para colega@exemplo.com" +) + +# Execute a tarefa +crew = Crew( + agents=[outlook_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a email, calendário e contatos. +- Escopos necessários incluem: `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`. + +**Problemas de Envio de Email** + +- Certifique-se de que `to_recipients`, `subject` e `body` sejam fornecidos para `send_email`. +- Verifique se os endereços de email estão formatados corretamente. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Microsoft Outlook. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_sharepoint.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_sharepoint.mdx new file mode 100644 index 000000000..0f5968421 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_sharepoint.mdx @@ -0,0 +1,524 @@ +--- +title: Integração Microsoft SharePoint +description: "Gerenciamento de sites, listas e documentos com integração Microsoft SharePoint para CrewAI." +icon: "folder-tree" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes acessem e gerenciem sites, listas e bibliotecas de documentos do SharePoint. Recupere informações do site, gerencie itens de lista, faça upload e organize arquivos, e simplifique seus fluxos de trabalho do SharePoint com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Microsoft SharePoint, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Microsoft com acesso ao SharePoint +- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Microsoft SharePoint + +### 1. Conecte sua Conta Microsoft + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Microsoft SharePoint** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a sites e arquivos do SharePoint +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Obter todos os sites do SharePoint aos quais o usuário tem acesso. + + **Parâmetros:** + - `search` (string, opcional): Consulta de pesquisa para filtrar sites. + - `select` (string, opcional): Selecionar propriedades específicas para retornar (ex: 'displayName,id,webUrl'). + - `filter` (string, opcional): Filtrar resultados usando sintaxe OData. + - `expand` (string, opcional): Expandir recursos relacionados inline. + - `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999). + - `skip` (integer, opcional): Número de itens a pular (mín 0). + - `orderby` (string, opcional): Ordenar resultados por propriedades especificadas (ex: 'displayName desc'). + + + + + **Descrição:** Obter informações sobre um site específico do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `select` (string, opcional): Selecionar propriedades específicas para retornar (ex: 'displayName,id,webUrl,drives'). + - `expand` (string, opcional): Expandir recursos relacionados inline (ex: 'drives,lists'). + + + + + **Descrição:** Listar todas as bibliotecas de documentos (drives) em um site do SharePoint. Use isto para descobrir bibliotecas disponíveis antes de usar operações de arquivo. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `top` (integer, opcional): Número máximo de drives a retornar por página (1-999). Padrão: 100 + - `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados. + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'id,name,webUrl,driveType'). + + + + + **Descrição:** Obter todas as listas em um site do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + + + + + **Descrição:** Obter informações sobre uma lista específica. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `list_id` (string, obrigatório): O ID da lista. + + + + + **Descrição:** Obter itens de uma lista do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `list_id` (string, obrigatório): O ID da lista. + - `expand` (string, opcional): Expandir dados relacionados (ex: 'fields'). + + + + + **Descrição:** Criar um novo item em uma lista do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `list_id` (string, obrigatório): O ID da lista. + - `fields` (object, obrigatório): Os valores de campo para o novo item. + + + + + **Descrição:** Atualizar um item em uma lista do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `list_id` (string, obrigatório): O ID da lista. + - `item_id` (string, obrigatório): O ID do item a atualizar. + - `fields` (object, obrigatório): Os valores de campo a atualizar. + + + + + **Descrição:** Excluir um item de uma lista do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `list_id` (string, obrigatório): O ID da lista. + - `item_id` (string, obrigatório): O ID do item a excluir. + + + + + **Descrição:** Fazer upload de um arquivo para uma biblioteca de documentos do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O ID do site do SharePoint. + - `file_path` (string, obrigatório): O caminho onde fazer upload do arquivo (ex: 'pasta/nomeDoArquivo.txt'). + - `content` (string, obrigatório): O conteúdo do arquivo a fazer upload. + + + + + **Descrição:** Recuperar arquivos e pastas de uma biblioteca de documentos do SharePoint. Por padrão, lista a pasta raiz, mas você pode navegar em subpastas fornecendo um folder_id. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `folder_id` (string, opcional): O ID da pasta para listar o conteúdo. Use 'root' para a pasta raiz, ou forneça um ID de pasta de uma chamada anterior de list_files. Padrão: 'root' + - `top` (integer, opcional): Número máximo de itens a retornar por página (1-1000). Padrão: 50 + - `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados. + - `orderby` (string, opcional): Ordem de classificação dos resultados (ex: 'name asc', 'size desc', 'lastModifiedDateTime desc'). Padrão: 'name asc' + - `filter` (string, opcional): Filtro OData para restringir resultados (ex: 'file ne null' apenas para arquivos, 'folder ne null' apenas para pastas). + - `select` (string, opcional): Lista de campos separados por vírgula para retornar (ex: 'id,name,size,folder,file,webUrl,lastModifiedDateTime'). + + + + + **Descrição:** Excluir um arquivo ou pasta de uma biblioteca de documentos do SharePoint. Para pastas, todo o conteúdo é excluído recursivamente. Os itens são movidos para a lixeira do site. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo ou pasta a excluir. Obtenha de list_files. + + + + + **Descrição:** Listar arquivos e pastas em uma pasta de biblioteca de documentos do SharePoint pelo caminho. Mais eficiente do que múltiplas chamadas list_files para navegação profunda. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `folder_path` (string, obrigatório): O caminho completo para a pasta sem barras iniciais/finais (ex: 'Documents', 'Reports/2024/Q1'). + - `top` (integer, opcional): Número máximo de itens a retornar por página (1-1000). Padrão: 50 + - `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados. + - `orderby` (string, opcional): Ordem de classificação dos resultados (ex: 'name asc', 'size desc'). Padrão: 'name asc' + - `select` (string, opcional): Lista de campos separados por vírgula para retornar (ex: 'id,name,size,folder,file,webUrl,lastModifiedDateTime'). + + + + + **Descrição:** Baixar conteúdo bruto de um arquivo de uma biblioteca de documentos do SharePoint. Use apenas para arquivos de texto simples (.txt, .csv, .json). Para arquivos Excel, use as ações específicas de Excel. Para arquivos Word, use get_word_document_content. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo a baixar. Obtenha de list_files ou list_files_by_path. + + + + + **Descrição:** Recuperar metadados detalhados de um arquivo ou pasta específico em uma biblioteca de documentos do SharePoint, incluindo nome, tamanho, datas de criação/modificação e informações do autor. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo ou pasta. Obtenha de list_files ou list_files_by_path. + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'id,name,size,createdDateTime,lastModifiedDateTime,webUrl,createdBy,lastModifiedBy'). + + + + + **Descrição:** Criar uma nova pasta em uma biblioteca de documentos do SharePoint. Por padrão, cria a pasta na raiz; use parent_id para criar subpastas. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `folder_name` (string, obrigatório): Nome para a nova pasta. Não pode conter: \ / : * ? " < > | + - `parent_id` (string, opcional): O ID da pasta pai. Use 'root' para a raiz da biblioteca de documentos, ou forneça um ID de pasta de list_files. Padrão: 'root' + + + + + **Descrição:** Pesquisar arquivos e pastas em uma biblioteca de documentos do SharePoint por palavras-chave. Pesquisa nomes de arquivos, nomes de pastas e conteúdo de arquivos para documentos Office. Não use curingas ou caracteres especiais. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `query` (string, obrigatório): Palavras-chave de pesquisa (ex: 'relatório', 'orçamento 2024'). Curingas como *.txt não são suportados. + - `top` (integer, opcional): Número máximo de resultados a retornar por página (1-1000). Padrão: 50 + - `skip_token` (string, opcional): Token de paginação de uma resposta anterior para buscar a próxima página de resultados. + - `select` (string, opcional): Lista de campos separados por vírgula para retornar (ex: 'id,name,size,folder,file,webUrl,lastModifiedDateTime'). + + + + + **Descrição:** Copiar um arquivo ou pasta para um novo local dentro do SharePoint. O item original permanece inalterado. A operação de cópia é assíncrona para arquivos grandes. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo ou pasta a copiar. Obtenha de list_files ou search_files. + - `destination_folder_id` (string, obrigatório): O ID da pasta de destino. Use 'root' para a pasta raiz, ou um ID de pasta de list_files. + - `new_name` (string, opcional): Novo nome para a cópia. Se não fornecido, o nome original é usado. + + + + + **Descrição:** Mover um arquivo ou pasta para um novo local dentro do SharePoint. O item é removido de sua localização original. Para pastas, todo o conteúdo é movido também. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo ou pasta a mover. Obtenha de list_files ou search_files. + - `destination_folder_id` (string, obrigatório): O ID da pasta de destino. Use 'root' para a pasta raiz, ou um ID de pasta de list_files. + - `new_name` (string, opcional): Novo nome para o item movido. Se não fornecido, o nome original é mantido. + + + + + **Descrição:** Listar todas as planilhas (abas) em uma pasta de trabalho Excel armazenada em uma biblioteca de documentos do SharePoint. Use o nome da planilha retornado com outras ações de Excel. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'id,name,position,visibility'). + - `filter` (string, opcional): Expressão de filtro OData (ex: "visibility eq 'Visible'" para excluir planilhas ocultas). + - `top` (integer, opcional): Número máximo de planilhas a retornar. Mínimo: 1, Máximo: 999 + - `orderby` (string, opcional): Ordem de classificação (ex: 'position asc' para retornar planilhas na ordem das abas). + + + + + **Descrição:** Criar uma nova planilha (aba) em uma pasta de trabalho Excel armazenada em uma biblioteca de documentos do SharePoint. A nova planilha é adicionada no final da lista de abas. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `name` (string, obrigatório): Nome para a nova planilha. Máximo de 31 caracteres. Não pode conter: \ / * ? : [ ]. Deve ser único na pasta de trabalho. + + + + + **Descrição:** Recuperar valores de células de um intervalo específico em uma planilha Excel armazenada no SharePoint. Para ler todos os dados sem saber as dimensões, use get_excel_used_range em vez disso. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha (aba) para leitura. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas. + - `range` (string, obrigatório): Intervalo de células em notação A1 (ex: 'A1:C10', 'A:C', '1:5', 'A1'). + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text'). + + + + + **Descrição:** Escrever valores em um intervalo específico em uma planilha Excel armazenada no SharePoint. Sobrescreve o conteúdo existente das células. As dimensões do array de valores devem corresponder exatamente às dimensões do intervalo. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha (aba) a atualizar. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas. + - `range` (string, obrigatório): Intervalo de células em notação A1 onde os valores serão escritos (ex: 'A1:C3' para um bloco 3x3). + - `values` (array, obrigatório): Array 2D de valores (linhas contendo células). Exemplo para A1:B2: [["Cabeçalho1", "Cabeçalho2"], ["Valor1", "Valor2"]]. Use null para limpar uma célula. + + + + + **Descrição:** Retornar apenas os metadados (endereço e dimensões) do intervalo utilizado em uma planilha, sem os valores reais das células. Ideal para arquivos grandes para entender o tamanho da planilha antes de ler dados em blocos. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha (aba) para leitura. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas. + + + + + **Descrição:** Recuperar todas as células contendo dados em uma planilha armazenada no SharePoint. Não use para arquivos maiores que 2MB. Para arquivos grandes, use get_excel_used_range_metadata primeiro, depois get_excel_range_data para ler em blocos menores. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha (aba) para leitura. Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas. + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text,rowCount,columnCount'). + + + + + **Descrição:** Recuperar o valor de uma única célula por índice de linha e coluna de um arquivo Excel no SharePoint. Os índices são baseados em 0 (linha 0 = linha 1 do Excel, coluna 0 = coluna A). + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha (aba). Obtenha de get_excel_worksheets. Sensível a maiúsculas e minúsculas. + - `row` (integer, obrigatório): Índice de linha baseado em 0 (linha 0 = linha 1 do Excel). Intervalo válido: 0-1048575 + - `column` (integer, obrigatório): Índice de coluna baseado em 0 (coluna 0 = A, coluna 1 = B). Intervalo válido: 0-16383 + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text'). + + + + + **Descrição:** Converter um intervalo de células em uma tabela Excel formatada com recursos de filtragem, classificação e dados estruturados. Tabelas habilitam add_excel_table_row para adicionar dados. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha contendo o intervalo de dados. Obtenha de get_excel_worksheets. + - `range` (string, obrigatório): Intervalo de células para converter em tabela, incluindo cabeçalhos e dados (ex: 'A1:D10' onde A1:D1 contém cabeçalhos de coluna). + - `has_headers` (boolean, opcional): Defina como true se a primeira linha contém cabeçalhos de coluna. Padrão: true + + + + + **Descrição:** Listar todas as tabelas em uma planilha Excel específica armazenada no SharePoint. Retorna propriedades da tabela incluindo id, name, showHeaders e showTotals. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha para obter tabelas. Obtenha de get_excel_worksheets. + + + + + **Descrição:** Adicionar uma nova linha ao final de uma tabela Excel em um arquivo do SharePoint. O array de valores deve ter o mesmo número de elementos que o número de colunas da tabela. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha contendo a tabela. Obtenha de get_excel_worksheets. + - `table_name` (string, obrigatório): Nome da tabela para adicionar a linha (ex: 'Table1'). Obtenha de get_excel_tables. Sensível a maiúsculas e minúsculas. + - `values` (array, obrigatório): Array de valores de células para a nova linha, um por coluna na ordem da tabela (ex: ["João Silva", "joao@exemplo.com", 25]). + + + + + **Descrição:** Obter todas as linhas de uma tabela Excel em um arquivo do SharePoint como um intervalo de dados. Mais fácil do que get_excel_range_data ao trabalhar com tabelas estruturadas, pois não é necessário saber o intervalo exato. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha contendo a tabela. Obtenha de get_excel_worksheets. + - `table_name` (string, obrigatório): Nome da tabela para obter dados (ex: 'Table1'). Obtenha de get_excel_tables. Sensível a maiúsculas e minúsculas. + - `select` (string, opcional): Lista de propriedades separadas por vírgula para retornar (ex: 'address,values,formulas,numberFormat,text'). + + + + + **Descrição:** Criar uma visualização de gráfico em uma planilha Excel armazenada no SharePoint a partir de um intervalo de dados. O gráfico é incorporado na planilha. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha onde o gráfico será criado. Obtenha de get_excel_worksheets. + - `chart_type` (string, obrigatório): Tipo de gráfico (ex: 'ColumnClustered', 'ColumnStacked', 'Line', 'LineMarkers', 'Pie', 'Bar', 'BarClustered', 'Area', 'Scatter', 'Doughnut'). + - `source_data` (string, obrigatório): Intervalo de dados para o gráfico em notação A1, incluindo cabeçalhos (ex: 'A1:B10'). + - `series_by` (string, opcional): Como as séries de dados são organizadas: 'Auto', 'Columns' ou 'Rows'. Padrão: 'Auto' + + + + + **Descrição:** Listar todos os gráficos incorporados em uma planilha Excel armazenada no SharePoint. Retorna propriedades do gráfico incluindo id, name, chartType, height, width e position. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha para listar gráficos. Obtenha de get_excel_worksheets. + + + + + **Descrição:** Remover permanentemente uma planilha (aba) e todo seu conteúdo de uma pasta de trabalho Excel armazenada no SharePoint. Não pode ser desfeito. Uma pasta de trabalho deve ter pelo menos uma planilha. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha a excluir. Sensível a maiúsculas e minúsculas. Todos os dados, tabelas e gráficos nesta planilha serão permanentemente removidos. + + + + + **Descrição:** Remover uma tabela de uma planilha Excel no SharePoint. Isto exclui a estrutura da tabela (filtragem, formatação, recursos de tabela) mas preserva os dados subjacentes das células. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + - `worksheet_name` (string, obrigatório): Nome da planilha contendo a tabela. Obtenha de get_excel_worksheets. + - `table_name` (string, obrigatório): Nome da tabela a excluir (ex: 'Table1'). Obtenha de get_excel_tables. Os dados nas células permanecerão após a exclusão da tabela. + + + + + **Descrição:** Recuperar todos os intervalos nomeados definidos em uma pasta de trabalho Excel armazenada no SharePoint. Intervalos nomeados são rótulos definidos pelo usuário para intervalos de células (ex: 'DadosVendas' para A1:D100). + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do arquivo Excel no SharePoint. Obtenha de list_files ou search_files. + + + + + **Descrição:** Baixar e extrair conteúdo de texto de um documento Word (.docx) armazenado em uma biblioteca de documentos do SharePoint. Esta é a maneira recomendada de ler documentos Word do SharePoint. + + **Parâmetros:** + - `site_id` (string, obrigatório): O identificador completo do site SharePoint obtido de get_sites. + - `drive_id` (string, obrigatório): O ID da biblioteca de documentos. Chame get_drives primeiro para obter IDs de drive válidos. + - `item_id` (string, obrigatório): O identificador único do documento Word (.docx) no SharePoint. Obtenha de list_files ou search_files. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Microsoft SharePoint + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Microsoft SharePoint +sharepoint_agent = Agent( + role="Gerenciador SharePoint", + goal="Gerenciar sites, listas e documentos do SharePoint de forma eficiente", + backstory="Um assistente IA especializado em administração do Microsoft SharePoint e gerenciamento de conteúdo.", + apps=['microsoft_sharepoint'] # Todas as ações do SharePoint estarão disponíveis +) + +# Tarefa para obter todos os sites +get_sites_task = Task( + description="Listar todos os sites do SharePoint aos quais tenho acesso.", + agent=sharepoint_agent, + expected_output="Uma lista de sites do SharePoint com seus nomes de exibição e URLs." +) + +# Execute a tarefa +crew = Crew( + agents=[sharepoint_agent], + tasks=[get_sites_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso ao SharePoint (ex: `Sites.Read.All`, `Sites.ReadWrite.All`). +- Verifique se a conexão OAuth inclui todos os escopos necessários. + +**Problemas de ID de Site/Lista/Item** + +- Verifique novamente os IDs de site, lista e item para correção. +- Certifique-se de que os recursos referenciados existem e estão acessíveis. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Microsoft SharePoint. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_teams.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_teams.mdx new file mode 100644 index 000000000..b8d5548f7 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_teams.mdx @@ -0,0 +1,242 @@ +--- +title: Integração Microsoft Teams +description: "Colaboração em equipe e comunicação com integração Microsoft Teams para CrewAI." +icon: "users" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes acessem dados do Teams, enviem mensagens, criem reuniões e gerenciem canais. Automatize a comunicação da equipe, agende reuniões, recupere mensagens e simplifique seus fluxos de trabalho de colaboração com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Microsoft Teams, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Microsoft com acesso ao Teams +- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Microsoft Teams + +### 1. Conecte sua Conta Microsoft + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Microsoft Teams** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso ao Teams +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Obter todas as equipes das quais o usuário é membro. + + **Parâmetros:** + - Nenhum parâmetro necessário. + + + + + **Descrição:** Obter canais em uma equipe específica. + + **Parâmetros:** + - `team_id` (string, obrigatório): O ID da equipe. + + + + + **Descrição:** Enviar uma mensagem para um canal do Teams. + + **Parâmetros:** + - `team_id` (string, obrigatório): O ID da equipe. + - `channel_id` (string, obrigatório): O ID do canal. + - `message` (string, obrigatório): O conteúdo da mensagem. + - `content_type` (string, opcional): Tipo de conteúdo (html ou text). Opções: html, text. Padrão: text. + + + + + **Descrição:** Obter mensagens de um canal do Teams. + + **Parâmetros:** + - `team_id` (string, obrigatório): O ID da equipe. + - `channel_id` (string, obrigatório): O ID do canal. + - `top` (integer, opcional): Número de mensagens a recuperar (máx 50). Padrão: 20. + + + + + **Descrição:** Criar uma reunião do Teams. + + **Parâmetros:** + - `subject` (string, obrigatório): Assunto/título da reunião. + - `startDateTime` (string, obrigatório): Hora de início da reunião (formato ISO 8601 com fuso horário). + - `endDateTime` (string, obrigatório): Hora de término da reunião (formato ISO 8601 com fuso horário). + + + + + **Descrição:** Pesquisar reuniões online por URL de participação na web. + + **Parâmetros:** + - `join_web_url` (string, obrigatório): A URL de participação na web da reunião a pesquisar. + + + + + **Descrição:** Pesquisar reuniões online por ID externo da reunião. + + **Parâmetros:** + - `join_meeting_id` (string, obrigatório): O ID da reunião (código numérico) que os participantes usam para entrar. É o joinMeetingId exibido nos convites da reunião, não o meeting id da API Graph. + + + + + **Descrição:** Obter detalhes de uma reunião online específica. + + **Parâmetros:** + - `meeting_id` (string, obrigatório): O ID da reunião na API Graph (string alfanumérica longa). Obter pelas ações create_meeting ou search_online_meetings. Diferente do joinMeetingId numérico. + + + + + **Descrição:** Obter membros de uma equipe específica. + + **Parâmetros:** + - `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams. + - `top` (integer, opcional): Número máximo de membros a recuperar por página (1-999). Padrão: 100. + - `skip_token` (string, opcional): Token de paginação de uma resposta anterior. Quando a resposta incluir @odata.nextLink, extraia o valor do parâmetro $skiptoken e passe aqui para obter a próxima página de resultados. + + + + + **Descrição:** Criar um novo canal em uma equipe. + + **Parâmetros:** + - `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams. + - `display_name` (string, obrigatório): Nome do canal exibido no Teams. Deve ser único na equipe. Máx 50 caracteres. + - `description` (string, opcional): Descrição opcional explicando o propósito do canal. Visível nos detalhes do canal. Máx 1024 caracteres. + - `membership_type` (string, opcional): Visibilidade do canal. Opções: standard, private. "standard" = visível para todos os membros da equipe, "private" = visível apenas para membros adicionados especificamente. Padrão: standard. + + + + + **Descrição:** Obter respostas a uma mensagem específica em um canal. + + **Parâmetros:** + - `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams. + - `channel_id` (string, obrigatório): O identificador único do canal. Obter pela ação get_channels. + - `message_id` (string, obrigatório): O identificador único da mensagem pai. Obter pela ação get_messages. + - `top` (integer, opcional): Número máximo de respostas a recuperar por página (1-50). Padrão: 50. + - `skip_token` (string, opcional): Token de paginação de uma resposta anterior. Quando a resposta incluir @odata.nextLink, extraia o valor do parâmetro $skiptoken e passe aqui para obter a próxima página de resultados. + + + + + **Descrição:** Responder a uma mensagem em um canal do Teams. + + **Parâmetros:** + - `team_id` (string, obrigatório): O identificador único da equipe. Obter pela ação get_teams. + - `channel_id` (string, obrigatório): O identificador único do canal. Obter pela ação get_channels. + - `message_id` (string, obrigatório): O identificador único da mensagem a responder. Obter pela ação get_messages. + - `message` (string, obrigatório): O conteúdo da resposta. Para HTML, inclua tags de formatação. Para texto, use apenas texto simples. + - `content_type` (string, opcional): Formato do conteúdo. Opções: html, text. "text" para texto simples, "html" para texto rico com formatação. Padrão: text. + + + + + **Descrição:** Atualizar uma reunião online existente. + + **Parâmetros:** + - `meeting_id` (string, obrigatório): O identificador único da reunião. Obter pelas ações create_meeting ou search_online_meetings. + - `subject` (string, opcional): Novo título da reunião. + - `startDateTime` (string, opcional): Nova hora de início no formato ISO 8601 com fuso horário. Exemplo: "2024-01-20T10:00:00-08:00". + - `endDateTime` (string, opcional): Nova hora de término no formato ISO 8601 com fuso horário. + + + + + **Descrição:** Excluir uma reunião online. + + **Parâmetros:** + - `meeting_id` (string, obrigatório): O identificador único da reunião a excluir. Obter pelas ações create_meeting ou search_online_meetings. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Microsoft Teams + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Microsoft Teams +teams_agent = Agent( + role="Coordenador do Teams", + goal="Gerenciar comunicação e reuniões do Teams de forma eficiente", + backstory="Um assistente IA especializado em operações do Microsoft Teams e colaboração em equipe.", + apps=['microsoft_teams'] # Todas as ações do Teams estarão disponíveis +) + +# Tarefa para listar equipes e canais +explore_teams_task = Task( + description="Listar todas as equipes das quais sou membro e depois obter os canais da primeira equipe.", + agent=teams_agent, + expected_output="Lista de equipes e canais exibida." +) + +# Execute a tarefa +crew = Crew( + agents=[teams_agent], + tasks=[explore_teams_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso ao Teams. +- Escopos necessários incluem: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `OnlineMeetings.ReadWrite`, `OnlineMeetings.Read`. + +**Acesso a Equipes e Canais** + +- Certifique-se de que você é membro das equipes que está tentando acessar. +- Verifique novamente os IDs de equipe e canal para correção. + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Microsoft Teams. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_word.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_word.mdx new file mode 100644 index 000000000..ec29fe409 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/microsoft_word.mdx @@ -0,0 +1,172 @@ +--- +title: Integração Microsoft Word +description: "Criação e gerenciamento de documentos com integração Microsoft Word para CrewAI." +icon: "file-word" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes criem, leiam e gerenciem documentos do Word e arquivos de texto no OneDrive ou SharePoint. Automatize a criação de documentos, recupere conteúdo, gerencie propriedades de documentos e simplifique seus fluxos de trabalho de documentos com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração Microsoft Word, certifique-se de ter: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Microsoft com acesso ao Word e OneDrive/SharePoint +- Conectado sua conta Microsoft através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração Microsoft Word + +### 1. Conecte sua Conta Microsoft + +1. Navegue para [Integrações CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Microsoft Word** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo OAuth +4. Conceda as permissões necessárias para acesso a arquivos +5. Copie seu Token Enterprise das [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **Descrição:** Obter todos os documentos do Word do OneDrive ou SharePoint. + + **Parâmetros:** + - `select` (string, opcional): Selecionar propriedades específicas para retornar. + - `filter` (string, opcional): Filtrar resultados usando sintaxe OData. + - `expand` (string, opcional): Expandir recursos relacionados inline. + - `top` (integer, opcional): Número de itens a retornar (mín 1, máx 999). + - `orderby` (string, opcional): Ordenar resultados por propriedades especificadas. + + + + + **Descrição:** Criar um documento de texto (.txt) com conteúdo. RECOMENDADO para criação de conteúdo programático que precisa ser legível e editável. + + **Parâmetros:** + - `file_name` (string, obrigatório): Nome do documento de texto (deve terminar com .txt). + - `content` (string, opcional): Conteúdo de texto para o documento. Padrão: "Este é um novo documento de texto criado via API." + + + + + **Descrição:** Obter o conteúdo de um documento (funciona melhor com arquivos de texto). + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do documento. + + + + + **Descrição:** Obter propriedades e metadados de um documento. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do documento. + + + + + **Descrição:** Excluir um documento. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do documento a excluir. + + + + + **Descrição:** Copiar um documento para um novo local no OneDrive. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do documento a copiar. + - `name` (string, opcional): Novo nome para o documento copiado. + - `parent_id` (string, opcional): O ID da pasta de destino (padrão: raiz). + + + + + **Descrição:** Mover um documento para um novo local no OneDrive. + + **Parâmetros:** + - `file_id` (string, obrigatório): O ID do documento a mover. + - `parent_id` (string, obrigatório): O ID da pasta de destino. + - `name` (string, opcional): Novo nome para o documento movido. + + + + +## Exemplos de Uso + +### Configuração Básica do Agente Microsoft Word + +```python +from crewai import Agent, Task, Crew + +# Crie um agente com capacidades do Microsoft Word +word_agent = Agent( + role="Gerenciador de Documentos", + goal="Gerenciar documentos do Word e arquivos de texto de forma eficiente", + backstory="Um assistente IA especializado em operações de documentos do Microsoft Word e gerenciamento de conteúdo.", + apps=['microsoft_word'] # Todas as ações do Word estarão disponíveis +) + +# Tarefa para criar um novo documento de texto +create_doc_task = Task( + description="Criar um novo documento de texto chamado 'notas_reuniao.txt' com conteúdo 'Notas da Reunião de Janeiro de 2024: Pontos-chave de discussão e itens de ação.'", + agent=word_agent, + expected_output="Novo documento de texto 'notas_reuniao.txt' criado com sucesso." +) + +# Execute a tarefa +crew = Crew( + agents=[word_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Autenticação** + +- Certifique-se de que sua conta Microsoft tenha as permissões necessárias para acesso a arquivos (ex: `Files.Read.All`, `Files.ReadWrite.All`). +- Verifique se a conexão OAuth inclui todos os escopos necessários. + +**Problemas de Criação de Arquivos** + +- Ao criar documentos de texto, certifique-se de que o `file_name` termine com extensão `.txt`. +- Verifique se você tem permissões de escrita no local de destino (OneDrive/SharePoint). + +### Obtendo Ajuda + + + Entre em contato com nossa equipe de suporte para assistência com configuração + ou solução de problemas da integração Microsoft Word. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/notion.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/notion.mdx new file mode 100644 index 000000000..d61df08f0 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/notion.mdx @@ -0,0 +1,517 @@ +--- +title: Integração com o Notion +description: "Gerenciamento de páginas e bancos de dados com integração do Notion para o CrewAI." +icon: "book" +mode: "wide" +--- + +## Visão Geral + +Permita que seus agentes gerenciem páginas, bancos de dados e conteúdos através do Notion. Crie e atualize páginas, gerencie blocos de conteúdo, organize bases de conhecimento e otimize seus fluxos de documentação com automação alimentada por IA. + +## Pré-requisitos + +Antes de usar a integração com o Notion, certifique-se de que você tem: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Notion com permissões adequadas no workspace +- Sua conta Notion conectada através da [página de Integrações](https://app.crewai.com/crewai_plus/connectors) + +## Configurando a Integração com o Notion + +### 1. Conecte sua Conta Notion + +1. Acesse [Integrações do CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. Procure por **Notion** na seção de Integrações de Autenticação +3. Clique em **Conectar** e complete o fluxo de OAuth +4. Conceda as permissões necessárias para gerenciamento de páginas e bancos de dados +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## Ações Disponíveis + + + + **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 + +# Create an agent with Notion capabilities +notion_agent = Agent( + role="Documentation Manager", + goal="Manage documentation and knowledge base in Notion efficiently", + backstory="An AI assistant specialized in content management and documentation.", + apps=['notion'] +) + +# Task to create a meeting notes page +create_notes_task = Task( + description="Create a new meeting notes page in the team database with today's date and agenda items", + agent=notion_agent, + expected_output="Meeting notes page created successfully with structured content" +) + +# Run the task +crew = Crew( + agents=[notion_agent], + tasks=[create_notes_task] +) + +crew.kickoff() +``` + +### Filtrando Ferramentas Específicas do Notion + +```python + +content_manager = Agent( + role="Content Manager", + goal="Create and manage content pages efficiently", + backstory="An AI assistant that focuses on content creation and management.", + apps=['notion'] +) + +# Task to manage content workflow +content_workflow = Task( + description="Create a new project documentation page and add structured content blocks for requirements and specifications", + agent=content_manager, + expected_output="Project documentation created with organized content sections" +) + +crew = Crew( + agents=[content_manager], + tasks=[content_workflow] +) + +crew.kickoff() +``` + +### Gerenciamento de Base de Conhecimento + +```python +from crewai import Agent, Task, Crew + +knowledge_curator = Agent( + role="Knowledge Curator", + goal="Curate and organize knowledge base content in Notion", + backstory="An experienced knowledge manager who organizes and maintains comprehensive documentation.", + apps=['notion'] +) + +# Task to curate knowledge base +curation_task = Task( + description=""" + 1. Search for existing documentation pages related to our new product feature + 2. Create a comprehensive feature documentation page with proper structure + 3. Add code examples, images, and links to related resources + 4. Update existing pages with cross-references to the new documentation + """, + agent=knowledge_curator, + expected_output="Feature documentation created and integrated with existing knowledge base" +) + +crew = Crew( + agents=[knowledge_curator], + tasks=[curation_task] +) + +crew.kickoff() +``` + +### Estrutura e Organização de Conteúdo + +```python +from crewai import Agent, Task, Crew + +content_organizer = Agent( + role="Content Organizer", + goal="Organize and structure content blocks for optimal readability", + backstory="An AI assistant that specializes in content structure and user experience.", + apps=['notion'] +) + +# Task to organize content structure +organization_task = Task( + description=""" + 1. Get content from existing project pages + 2. Analyze the structure and identify improvement opportunities + 3. Update content blocks to use proper headings, tables, and formatting + 4. Add table of contents and improve navigation between related pages + 5. Create templates for future documentation consistency + """, + agent=content_organizer, + expected_output="Content reorganized with improved structure and navigation" +) + +crew = Crew( + agents=[content_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### Fluxos de Trabalho de Documentação Automatizados + +```python +from crewai import Agent, Task, Crew + +doc_automator = Agent( + role="Documentation Automator", + goal="Automate documentation workflows and maintenance", + backstory="An AI assistant that automates repetitive documentation tasks.", + apps=['notion'] +) + +# Complex documentation automation task +automation_task = Task( + description=""" + 1. Search for pages that haven't been updated in the last 30 days + 2. Review and update outdated content blocks + 3. Create weekly team update pages with consistent formatting + 4. Add status indicators and progress tracking to project pages + 5. Generate monthly documentation health reports + 6. Archive completed project pages and organize them in archive sections + """, + agent=doc_automator, + expected_output="Documentation automated with updated content, weekly reports, and organized archives" +) + +crew = Crew( + agents=[doc_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## Solução de Problemas + +### Problemas Comuns + +**Erros de Permissão** + +- Certifique-se de que sua conta Notion possui acesso de edição ao workspace desejado +- Verifique se a conexão OAuth inclui os escopos necessários para a API do Notion +- Confira se as páginas e bancos de dados estão compartilhados com a integração autenticada + +**IDs de Página e Bloco Inválidos** + +- Revise os IDs de página e bloco para garantir que estejam no formato UUID correto +- Garanta que as páginas e blocos referenciados existem e são acessíveis +- Verifique se os IDs da página ou banco de dados pai são válidos ao criar novas páginas + +**Problemas com Schema de Propriedades** + +- Assegure que as propriedades da página correspondem ao schema do banco de dados ao criar páginas em bancos de dados +- Verifique se os nomes e tipos das propriedades estão corretos para o banco de dados alvo +- Confirme que as propriedades obrigatórias estão incluídas ao criar ou atualizar páginas + +**Estrutura dos Blocos de Conteúdo** + +- Assegure que o conteúdo dos blocos segue as especificações de rich text do Notion +- Verifique se estruturas aninhadas de blocos estão devidamente formatadas +- Confira se URLs de mídias são acessíveis e estão corretamente formatadas + +**Problemas de Pesquisa e Filtros** + +- Certifique-se de que as queries de pesquisa estão devidamente formatadas e não estão vazias +- Use nomes de campos válidos em fórmulas de filtro: `query`, `filter.value`, `direction`, `page_size` +- Teste pesquisas simples antes de construir condições de filtro mais complexas + +**Relacionamentos Pai-Filho** + +- Verifique se a página ou banco de dados pai existe antes de criar páginas filhas +- Assegure que existam permissões apropriadas para o container pai +- Confirme que os schemas do banco permitem definir as propriedades desejadas + +**Rich Text e Conteúdo de Mídia** + +- Assegure que URLs para imagens externas, PDFs e bookmarks sejam acessíveis +- Verifique se a formatação rich text segue as especificações da API do Notion +- Confira se os tipos de linguagem nos blocos de código são suportados pelo Notion + +**Operações de Arquivamento e Exclusão** + +- Entenda a diferença entre arquivar (reversível) e excluir (permanente) +- Certifique-se de ter permissões para arquivar ou excluir o conteúdo desejado +- Tenha cuidado com operações em massa que possam afetar múltiplas páginas ou blocos + +### Obtendo Ajuda + + + Entre em contato com nosso time de suporte para auxílio na configuração ou + solução de problemas com a integração Notion. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/salesforce.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/salesforce.mdx new file mode 100644 index 000000000..4bbda3ece --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/salesforce.mdx @@ -0,0 +1,739 @@ +--- +title: Integração com Salesforce +description: "Automação de vendas e CRM com integração Salesforce para CrewAI." +icon: "salesforce" +mode: "wide" +--- + +## 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 AMP](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) + + + O Salesforce exige uma **instalação única feita por um administrador** do + pacote CrewAI na sua organização antes que qualquer usuário possa se + conectar. Isso é uma exigência da plataforma Salesforce para todas as + integrações baseadas em ExternalClientApp a partir da release Spring '26 — + não é uma etapa específica da CrewAI. O fluxo Connect Salesforce na CrewAI + AMP guia você por esta etapa na primeira vez. + + +## Configurando a Integração Salesforce + +### 1. Conecte sua Conta Salesforce + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/unified_tools). +2. Encontre **Salesforce** na seção Integrações de Autenticação. +3. Clique em **Conectar**. + +O que acontece em seguida depende de o administrador Salesforce já ter +instalado o pacote CrewAI na sua organização: + +- **Pacote já instalado:** você será levado diretamente à tela de consentimento + OAuth do Salesforce — aprove e a conexão estará feita. +- **Pacote ainda não instalado:** você verá uma página **Install CrewAI in + Salesforce**. Siga as etapas de instalação única abaixo e, depois, volte à + CrewAI AMP e clique em **Conectar** novamente. + +4. Conceda as permissões necessárias para gerenciamento de CRM e vendas. +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations). + +#### Instalação única pelo administrador (apenas admin Salesforce) + +Na primeira vez que alguém na sua organização clica em **Connect Salesforce**, +a CrewAI redireciona para uma página de instalação que aponta para o pacote +gerenciado CrewAI. Um administrador Salesforce precisa instalá-lo uma única +vez para toda a organização. + +1. Na página de instalação dentro da CrewAI, clique em **Install in + Salesforce**. (Você também pode compartilhar a URL dessa página com seu + administrador — o link de instalação funciona para qualquer pessoa que o + abra.) +2. Entre no Salesforce como administrador. Para sandboxes, troque + `login.salesforce.com` por `test.salesforce.com` na URL antes de abrir. +3. Escolha **Install for All Users**, confirme o aviso sobre aplicativos de + terceiros e clique em **Install**. +4. No Setup do Salesforce, busque **External Client App Manager** → **CrewAI + App** → abra a aba **Policies** → **Edit** e configure: + - **Permitted Users:** All users may self-authorize + - **IP Relaxation:** Relax IP restrictions + - **Refresh Token Policy:** Refresh token is valid until revoked +5. Salve. +6. Volte à CrewAI AMP e clique em **Connect Salesforce** novamente. Desta vez + o OAuth será concluído. + + + **Não é administrador Salesforce?** Encaminhe a URL da página de instalação + (ou o link de instalação em si) para o seu administrador e peça que ele + conclua as etapas acima. Quando ele terminar, volte à CrewAI AMP e clique + em **Conectar** novamente. + + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## 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 + +# Obtenha ferramentas enterprise (ferramentas Salesforce serão incluídas) + +# 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.", + apps=['salesforce'] +) + +# 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 + +# Obtenha apenas ferramentas Salesforce específicas + 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.", + apps=['salesforce'] +) + +# 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 + +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.", + apps=['salesforce'] +) + +# 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 + +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.", + apps=['salesforce'] +) + +# 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/shopify.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/shopify.mdx new file mode 100644 index 000000000..d7c919d1a --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/shopify.mdx @@ -0,0 +1,408 @@ +--- +title: Integração com Shopify +description: "Gestão de e-commerce e loja online com integração do Shopify para CrewAI." +icon: "shopify" +mode: "wide" +--- + +## 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 AMP](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) + +## Configurando a Integração Shopify + +### 1. Conecte sua Loja Shopify + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Shopify** 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 loja e produtos +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## 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 + +# 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.", + apps=['shopify'] +) + +# 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 + +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.", + apps=['shopify'] +) + +# 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 + +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.", + apps=['shopify'] +) + +# 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 + +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.", + apps=['shopify'] +) + +# 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/slack.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/slack.mdx new file mode 100644 index 000000000..c295bb288 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/slack.mdx @@ -0,0 +1,314 @@ +--- +title: Integração com Slack +description: "Comunicação e colaboração em equipe com a integração Slack para CrewAI." +icon: "slack" +mode: "wide" +--- + +## 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 AMP](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) + +## Configurando a Integração Slack + +### 1. Conecte seu Workspace do Slack + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Slack** 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 comunicação em equipe +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## 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 + +# 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.", + apps=['slack'] +) + +# 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 + +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.", + apps=['slack'] +) + +# 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 + +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.", + apps=['slack'] +) + +# 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 + +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.", + apps=['slack'] +) + +# 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. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/snowflake.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/snowflake.mdx new file mode 100644 index 000000000..f8d4d0516 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/snowflake.mdx @@ -0,0 +1,134 @@ +--- +title: Integração com Snowflake +description: "Conecte agentes CrewAI ao Snowflake Cortex Analyst, Cortex Search e execução SQL através do servidor MCP gerenciado pelo Snowflake." +icon: "snowflake" +mode: "wide" +--- + +## Visão Geral + +Conecte seus agentes CrewAI diretamente aos seus dados no Snowflake através do [servidor MCP gerenciado pelo Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). A integração com o Snowflake permite que seus agentes consultem dados estruturados com **Cortex Analyst**, pesquisem dados não estruturados com **Cortex Search** e executem SQL governado nos seus warehouses — tudo sem escrever ou hospedar nenhum código de conector. + +Internamente, a integração com o Snowflake é um wrapper gerenciado em torno do suporte a [Custom MCP Server](/pt-BR/enterprise/guides/custom-mcp-server) do CrewAI. O Snowflake expõe suas capacidades de Cortex AI através de um endpoint [Model Context Protocol](https://modelcontextprotocol.io/), e o CrewAI se conecta a ele de forma segura em seu nome. Qualquer ferramenta que você exponha no lado do Snowflake — Cortex Analyst, Cortex Search, execução SQL, Cortex Agents ou suas próprias ferramentas personalizadas — fica disponível para suas crews. + +## Capacidades Principais + + + + Faça perguntas em linguagem natural e deixe o [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) gerar e executar SQL nos seus dados **estruturados** usando modelos semânticos ricos. + + + Recupere dados **não estruturados** relevantes para fluxos de trabalho de RAG e conhecimento com o [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview), o serviço de busca totalmente gerenciado do Snowflake. + + + Execute consultas SQL governadas diretamente nos seus warehouses Snowflake, com modo somente leitura configurável, timeouts e seleção de warehouse. + + + +Como a integração expõe quaisquer ferramentas que seu servidor MCP publica, você também pode expor **Cortex Agents** e **ferramentas personalizadas** (funções definidas pelo usuário e stored procedures) para seus agentes CrewAI. + +## Pré-requisitos + +Antes de usar a integração com o Snowflake, certifique-se de que você tenha: + +- Uma conta [CrewAI AMP](https://app.crewai.com) com assinatura ativa +- Uma conta Snowflake com acesso aos recursos de Cortex AI +- Um [servidor MCP gerenciado pelo Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) configurado com as ferramentas que você deseja expor +- Privilégios Snowflake apropriados (USAGE/SELECT) no servidor MCP e seus objetos subjacentes + +## Configurando o Servidor Snowflake MCP + +O servidor MCP gerenciado pelo Snowflake é executado dentro da sua conta Snowflake e define quais ferramentas estão disponíveis para clientes externos como o CrewAI. Crie um com o comando [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server), listando os serviços Cortex Search, visualizações semânticas do Cortex Analyst e ferramentas SQL que você deseja expor. + +```sql +CREATE MCP SERVER my_mcp_server + FROM SPECIFICATION $$ + tools: + - name: "sales_analyst" + type: "CORTEX_ANALYST" + identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view" + description: "Answer questions about sales metrics" + - name: "docs_search" + type: "CORTEX_SEARCH_SERVICE_QUERY" + identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search" + description: "Search internal support documentation" + - name: "run_sql" + type: "SQL_EXECUTION" + description: "Execute read-only SQL queries" + $$; +``` + + +O endpoint MCP segue o formato `https:///api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}`. O CrewAI constrói esta URL automaticamente a partir do **URL da Conta**, **Banco de Dados**, **Schema** e **Nome do Servidor MCP** que você fornece ao configurar a integração. + + +Para a especificação completa — incluindo Cortex Agents, ferramentas personalizadas, limites de tamanho de resposta e opções de governança — consulte a [documentação do servidor MCP gerenciado pelo Snowflake](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). + +## Conectando o Snowflake no CrewAI AMP + + + Configurar integração Snowflake no CrewAI AMP + + + + + Navegue até **Ferramentas e Integrações** na barra lateral esquerda do CrewAI AMP, encontre **Snowflake** na lista de aplicações e abra seu painel de configuração. + + + + Preencha os campos de conexão que o CrewAI usa para acessar seu servidor Snowflake MCP: + + | Campo | Obrigatório | Descrição | + |-------|-------------|-----------| + | **Nome** | Sim | Um nome descritivo para esta conexão (padrão: `Snowflake`). | + | **Descrição** | Não | Um resumo opcional do que esta conexão fornece. | + | **URL da Conta** | Sim | A URL da sua conta Snowflake, ex.: `xy12345.us-east-1.snowflakecomputing.com`. | + | **Banco de Dados** | Sim | O banco de dados que contém seu servidor MCP (ex.: `MY_DATABASE`). | + | **Schema** | Sim | O schema que contém seu servidor MCP (ex.: `MY_SCHEMA`). | + | **Nome do Servidor MCP** | Sim | O nome do objeto de servidor MCP que você criou no Snowflake (ex.: `MY_MCP_SERVER`). | + + + + Selecione como o CrewAI se autentica no Snowflake. **OAuth** é recomendado. + + - **Usar OAuth** — Conecte-se de forma segura usando OAuth 2.0 para autenticação baseada em tokens sem compartilhar suas credenciais. O CrewAI gerencia todo o fluxo de autorização e renova os tokens automaticamente. Copie o **URI de Redirecionamento** mostrado no formulário (`https://oauth.crewai.com/oauth/add`) e registre-o como um URI de redirecionamento autorizado na sua [integração de segurança OAuth](https://docs.snowflake.com/en/user-guide/oauth-custom) do Snowflake. + - **Usar token de acesso pessoal** — Autentique usando um [token de acesso programático](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) gerado nas configurações da sua conta Snowflake. Atribua uma role com privilégios mínimos ao token para limitar a exposição. + + + + Clique em **Autenticar**. Para OAuth, você será redirecionado ao Snowflake para autorizar o acesso. Após autenticado, o servidor Snowflake aparece na sua lista de Conexões e suas ferramentas ficam disponíveis para suas crews. + + + + +Com OAuth, cada usuário se autentica individualmente e as consultas são executadas com seu `DEFAULT_ROLE` do Snowflake. Certifique-se de que os usuários que se conectam tenham uma role e warehouse padrão definidos (`ALTER USER SET DEFAULT_ROLE = '' DEFAULT_WAREHOUSE = ''`) para que as ferramentas Cortex Analyst e SQL tenham capacidade de computação para execução. + + +## Usando Ferramentas Snowflake nas Suas Crews + +Uma vez conectado, as ferramentas que seu servidor MCP expõe aparecem junto com as conexões integradas na página **Ferramentas e Integrações**. Você pode: + +- **Atribuir ferramentas a agentes** nas suas crews como qualquer outra ferramenta CrewAI. +- **Gerenciar visibilidade** para controlar quais membros do time podem usar a conexão. +- **Editar ou remover** a conexão a qualquer momento na lista de Conexões. + +Seus agentes agora podem solicitar métricas ao Cortex Analyst, executar Cortex Search nos seus documentos e executar SQL — com os resultados fluindo automaticamente para o raciocínio deles. + + +O Snowflake impõe governança no servidor MCP: o controle de acesso baseado em roles determina quais ferramentas um usuário pode descobrir e invocar, e limites se aplicam ao tamanho da resposta, contagem de ferramentas (máximo de 50 por servidor) e profundidade de recursão. Se uma chamada de ferramenta falhar, confirme que a role do usuário conectado possui os privilégios necessários no servidor MCP e seus objetos subjacentes. + + +## Saiba Mais + + + + Documentação oficial do Snowflake para criar e governar o servidor MCP. + + + Saiba como o CrewAI se conecta a qualquer servidor MCP, a base sobre a qual a integração Snowflake é construída. + + + + + Entre em contato com nossa equipe de suporte para obter ajuda com a integração Snowflake ou solução de problemas. + diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/stripe.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/stripe.mdx new file mode 100644 index 000000000..d8ee50ba1 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/stripe.mdx @@ -0,0 +1,327 @@ +--- +title: Integração Stripe +description: "Processamento de pagamentos e gerenciamento de assinaturas com integração Stripe para CrewAI." +icon: "stripe" +mode: "wide" +--- + +## 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 AMP](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) + +## Configurando a Integração Stripe + +### 1. Conecte sua Conta Stripe + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Stripe** 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 processamento de pagamentos +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## 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 + +# 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.", + apps=['stripe'] +) + +# 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 + +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.", + apps=['stripe'] +) + +# 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 + +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.", + apps=['stripe'] +) + +# 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 + +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.", + apps=['stripe'] +) + +# 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. diff --git a/docs/v1.15.1/pt-BR/enterprise/integrations/zendesk.mdx b/docs/v1.15.1/pt-BR/enterprise/integrations/zendesk.mdx new file mode 100644 index 000000000..db22e1b93 --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/integrations/zendesk.mdx @@ -0,0 +1,371 @@ +--- +title: Integração com Zendesk +description: "Gestão de suporte ao cliente e helpdesk com integração Zendesk para CrewAI." +icon: "headset" +mode: "wide" +--- + +## 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 AMP](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) + +## Configurando a Integração Zendesk + +### 1. Conecte sua Conta Zendesk + +1. Acesse [CrewAI AMP Integrações](https://app.crewai.com/crewai_plus/connectors) +2. Encontre **Zendesk** 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 tickets e usuários +5. Copie seu Token Enterprise em [Configurações de Integração](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. Instale o Pacote Necessário + +```bash +uv add crewai-tools +``` + +### 3. Configuração de variável de ambiente + + + Para usar integrações com `Agent(apps=[])`, você deve definir a variável de + ambiente `CREWAI_PLATFORM_INTEGRATION_TOKEN` com seu Enterprise Token. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="seu_enterprise_token" +``` + +Ou adicione ao seu arquivo `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=seu_enterprise_token +``` + +## 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 + +# Obtenha as ferramentas enterprise (as ferramentas Zendesk serão incluídas) + +# 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.", + apps=['zendesk'] +) + +# 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 + +# Obtenha apenas ferramentas Zendesk específicas + 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.", + apps=['zendesk'] +) + +# 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 + +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.", + apps=['zendesk'] +) + +# 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 + +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.", + apps=['zendesk'] +) + +# 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() +``` diff --git a/docs/v1.15.1/pt-BR/enterprise/introduction.mdx b/docs/v1.15.1/pt-BR/enterprise/introduction.mdx new file mode 100644 index 000000000..ef8a484fa --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/introduction.mdx @@ -0,0 +1,102 @@ +--- +title: "CrewAI AMP" +description: "Implemente, monitore e escale seus fluxos de trabalho de agentes de IA" +icon: "globe" +mode: "wide" +--- + +## Introdução + +CrewAI AMP(Agent Management Platform) fornece uma plataforma para implementar, monitorar e escalar seus crews e agentes em um ambiente de produção. + + + CrewAI AMP Dashboard + + +CrewAI AMP 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-to-amp) ou clique no botão abaixo para começar. diff --git a/docs/v1.15.1/pt-BR/enterprise/resources/frequently-asked-questions.mdx b/docs/v1.15.1/pt-BR/enterprise/resources/frequently-asked-questions.mdx new file mode 100644 index 000000000..245f9a35b --- /dev/null +++ b/docs/v1.15.1/pt-BR/enterprise/resources/frequently-asked-questions.mdx @@ -0,0 +1,152 @@ +--- +title: FAQs +description: "Perguntas frequentes sobre CrewAI AMP" +icon: "circle-question" +mode: "wide" +--- + + + + 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/enterprise/guides/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/v1.15.1/pt-BR/examples/cookbooks.mdx b/docs/v1.15.1/pt-BR/examples/cookbooks.mdx new file mode 100644 index 000000000..7057621a1 --- /dev/null +++ b/docs/v1.15.1/pt-BR/examples/cookbooks.mdx @@ -0,0 +1,23 @@ +--- +title: CrewAI Cookbooks +description: Quickstarts e notebooks focados em recursos para aprender padrões rapidamente. +icon: book +mode: "wide" +--- + +## Quickstarts & Demos + + + + Demos e projetos pequenos que mostram capacidades específicas do CrewAI. + + + Notebooks interativos para aprendizado prático. + + + + +Use Cookbooks para aprender um padrão rapidamente e, em seguida, avance para os Exemplos completos para implementações de produção. + + + diff --git a/docs/v1.15.1/pt-BR/examples/example.mdx b/docs/v1.15.1/pt-BR/examples/example.mdx new file mode 100644 index 000000000..9e30069b3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/examples/example.mdx @@ -0,0 +1,86 @@ +--- +title: Exemplos CrewAI +description: Explore exemplos organizados por Crews, Flows, Integrações e Notebooks. +icon: rocket-launch +mode: "wide" +--- + +## Crews + + + + Planejamento de campanhas com múltiplos agentes. + + + Planejamento de viagens personalizadas. + + + Correspondência de CV para vagas com busca vetorial. + + + Criação automatizada de descrições de vagas. + + + Equipe multiagente que projeta e constrói jogos em Python. + + + Prospecção e avaliação de candidatos. + + + Lista completa de exemplos de crews. + + + +## Flows + + + + Geração de conteúdo com roteamento. + + + Monitoramento e respostas de e‑mail. + + + Qualificação de leads com revisão humana. + + + Processamento de notas com integrações. + + + Fluxos de autoaperfeiçoamento iterativo. + + + Geração paralela de capítulos. + + + Lista completa de exemplos de flows. + + + +## Integrações + + + + Integração com o framework LangGraph. + + + Usando CrewAI com Azure OpenAI. + + + Integrações com o ecossistema NVIDIA. + + + Todos os exemplos de integrações. + + + +## Notebooks + + + + Simple QA Crew + Flow. + + + Exemplos interativos para aprendizado e experimentação. + + \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/guides/advanced/customizing-prompts.mdx b/docs/v1.15.1/pt-BR/guides/advanced/customizing-prompts.mdx new file mode 100644 index 000000000..ad1d7b096 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/advanced/customizing-prompts.mdx @@ -0,0 +1,331 @@ +--- +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 +mode: "wide" +--- + +## 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 +) +``` + + +`agent.i18n` é mantido apenas para compatibilidade retroativa e está obsoleto. Para customização de prompts em tempo de execução, passe `prompt_file` para `Crew`. Para acesso programático aos slices de prompt, use diretamente o utilitário de i18n: + + +```python +from crewai.utilities.i18n import get_i18n + +i18n = get_i18n("custom_prompts.json") +format_slice = i18n.slice("format") +tool_prompt = i18n.tools("ask_question") +``` + +#### 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: + +Para código que precisa ler slices de prompt diretamente, use `crewai.utilities.i18n.get_i18n()` com o mesmo arquivo de prompts em vez de ler `agent.i18n`. + +### 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/v1.15.1/pt-BR/guides/advanced/fingerprinting.mdx b/docs/v1.15.1/pt-BR/guides/advanced/fingerprinting.mdx new file mode 100644 index 000000000..20f082d18 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/advanced/fingerprinting.mdx @@ -0,0 +1,134 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/guides/agents/crafting-effective-agents.mdx b/docs/v1.15.1/pt-BR/guides/agents/crafting-effective-agents.mdx new file mode 100644 index 000000000..b80fd6fe5 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/agents/crafting-effective-agents.mdx @@ -0,0 +1,453 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/guides/coding-tools/agents-md.mdx b/docs/v1.15.1/pt-BR/guides/coding-tools/agents-md.mdx new file mode 100644 index 000000000..771fd807b --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/coding-tools/agents-md.mdx @@ -0,0 +1,61 @@ +--- +title: Ferramentas de Codificação +description: Use o AGENTS.md para guiar agentes de codificação e IDEs em seus projetos CrewAI. +icon: terminal +mode: "wide" +--- + +## Por que AGENTS.md + +`AGENTS.md` é um arquivo de instruções leve e local do repositório que fornece aos agentes de codificação orientações consistentes e específicas do projeto. Mantenha-o na raiz do projeto e trate-o como a fonte da verdade para como você deseja que os assistentes trabalhem: convenções, comandos, notas de arquitetura e proteções. + +## Criar um Projeto com o CLI + +Use o CLI do CrewAI para criar a estrutura de um projeto, e o `AGENTS.md` será automaticamente adicionado na raiz. + +```bash +# Crew +crewai create crew my_crew + +# Flow +crewai create flow my_flow + +# Tool repository +crewai tool create my_tool +``` + +## Configuração de Ferramentas: Direcione Assistentes para o AGENTS.md + +### Codex + +O Codex pode ser guiado por arquivos `AGENTS.md` colocados no seu repositório. Use-os para fornecer contexto persistente do projeto, como convenções, comandos e expectativas de fluxo de trabalho. + +### Claude Code + +O Claude Code armazena a memória do projeto em `CLAUDE.md`. Você pode inicializá-lo com `/init` e editá-lo usando `/memory`. O Claude Code também suporta importações dentro do `CLAUDE.md`, então você pode adicionar uma única linha como `@AGENTS.md` para incluir as instruções compartilhadas sem duplicá-las. + +Você pode simplesmente usar: + +```bash +mv AGENTS.md CLAUDE.md +``` + +### Gemini CLI e Google Antigravity + +O Gemini CLI e o Antigravity carregam um arquivo de contexto do projeto (padrão: `GEMINI.md`) da raiz do repositório e diretórios pais. Você pode configurá-lo para ler o `AGENTS.md` em vez disso (ou além) definindo `context.fileName` nas configurações do Gemini CLI. Por exemplo, defina apenas para `AGENTS.md`, ou inclua tanto `AGENTS.md` quanto `GEMINI.md` se quiser manter o formato de cada ferramenta. + +Você pode simplesmente usar: + +```bash +mv AGENTS.md GEMINI.md +``` + +### Cursor + +O Cursor suporta `AGENTS.md` como arquivo de instruções do projeto. Coloque-o na raiz do projeto para fornecer orientação ao assistente de codificação do Cursor. + +### Windsurf + +O Claude Code fornece uma integração oficial com o Windsurf. Se você usa o Claude Code dentro do Windsurf, siga a orientação do Claude Code acima e importe o `AGENTS.md` a partir do `CLAUDE.md`. + +Se você está usando o assistente nativo do Windsurf, configure o recurso de regras ou instruções do projeto (se disponível) para ler o `AGENTS.md` ou cole o conteúdo diretamente. diff --git a/docs/v1.15.1/pt-BR/guides/coding-tools/build-with-ai.mdx b/docs/v1.15.1/pt-BR/guides/coding-tools/build-with-ai.mdx new file mode 100644 index 000000000..3e03160b5 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/coding-tools/build-with-ai.mdx @@ -0,0 +1,214 @@ +--- +title: "Construa com IA" +description: "Tudo o que agentes de codificação com IA precisam para criar, implantar e escalar com CrewAI — skills, documentação legível por máquina, implantação e recursos enterprise." +icon: robot +mode: "wide" +--- + +# Construa com IA + +O CrewAI é nativo de IA. Esta página reúne o que um agente de codificação com IA precisa para construir com CrewAI — seja Claude Code, Codex, Cursor, Gemini CLI ou qualquer outro assistente que ajude um desenvolvedor a entregar crews e flows. + +### Agentes de codificação compatíveis + + + + + + + + + + + Esta página serve para humanos e para assistentes de IA. Se você é um agente de codificação, comece por **Skills** para obter contexto do CrewAI e depois use **llms.txt** para acesso completo à documentação. + + +--- + +## 1. Skills — ensine CrewAI ao seu agente + +**Skills** são pacotes de instruções que dão aos agentes de codificação conhecimento profundo do CrewAI — como estruturar Flows, configurar Crews, usar ferramentas e seguir convenções do framework. + + + + Anthropic + As skills do CrewAI estão no **plugin marketplace do Claude Code** — o mesmo canal usado por empresas líderes em IA: + ```shell + /plugin marketplace add crewAIInc/skills + /plugin install crewai-skills@crewai-plugins + /reload-plugins + ``` + + Quatro skills são ativadas automaticamente quando você faz perguntas relevantes sobre CrewAI: + + | Skill | Quando é usada | + |-------|----------------| + | `getting-started` | Novos projetos, escolha entre `LLM.call()` / `Agent` / `Crew` / `Flow`, arquivos `crew.jsonc` / `main.py` | + | `design-agent` | Configurar agentes — papel, objetivo, história, ferramentas, LLMs, memória, guardrails | + | `design-task` | Descrever tarefas, dependências, saída estruturada (`output_pydantic`, `output_json`), revisão humana | + | `ask-docs` | Consultar o [servidor MCP da documentação CrewAI](https://docs.crewai.com/mcp) em tempo real para detalhes de API | + + + Funciona com Claude Code, Codex, Cursor, Gemini CLI ou qualquer agente de codificação: + ```shell + npx skills add crewaiinc/skills + ``` + Obtido do [registro skills.sh](https://skills.sh/crewaiinc/skills). + + + + + + Use um dos métodos acima — o plugin marketplace do Claude Code ou `npx skills add`. Ambos instalam o pacote oficial [crewAIInc/skills](https://github.com/crewAIInc/skills). + + + O pacote ensina ao seu agente: + - **Flows** — apps com estado, passos e disparo de crews + - **Crews e agentes** — padrões JSON-first (`crew.jsonc`, `agents/*.jsonc`), papéis, tarefas, delegação + - **Ferramentas e integrações** — busca, APIs, servidores MCP e ferramentas comuns do CrewAI + - **Estrutura do projeto** — scaffolds da CLI e convenções de repositório + - **Padrões atualizados** — alinhado à documentação e às melhores práticas atuais do CrewAI + + + Seu agente pode estruturar e construir projetos CrewAI sem você precisar reexplicar o framework a cada sessão. + + + + + + Como skills funcionam em agentes CrewAI — injeção, ativação e padrões. + + + Visão geral do pacote crewAIInc/skills e do que ele inclui. + + + Configure o AGENTS.md para Claude Code, Codex, Cursor e Gemini CLI. + + + Listagem oficial — skills, estatísticas de instalação e auditorias. + + + +--- + +## 2. llms.txt — documentação legível por máquina + +O CrewAI publica um arquivo `llms.txt` que dá aos assistentes de IA acesso direto à documentação completa em formato legível por máquinas. + +``` +https://docs.crewai.com/llms.txt +``` + + + + [`llms.txt`](https://llmstxt.org/) é um padrão emergente para tornar a documentação consumível por grandes modelos de linguagem. Em vez de fazer scraping de HTML, seu agente pode buscar um único arquivo de texto estruturado com o conteúdo necessário. + + O `llms.txt` do CrewAI **já está no ar** — seu agente pode usar agora. + + + Indique ao agente de codificação a URL quando precisar da referência do CrewAI: + + ``` + Fetch https://docs.crewai.com/llms.txt for CrewAI documentation. + ``` + + Muitos agentes (Claude Code, Cursor etc.) conseguem buscar URLs diretamente. O arquivo contém documentação estruturada sobre conceitos, APIs e guias do CrewAI. + + + - **Sem scraping** — conteúdo limpo e estruturado em uma requisição + - **Sempre atualizado** — servido diretamente de docs.crewai.com + - **Otimizado para LLMs** — formatado para janelas de contexto, não para navegadores + - **Complementa as skills** — skills ensinam padrões; llms.txt fornece referência + + + +--- + +## 3. Implantação enterprise + +Do crew local à produção no **CrewAI AMP** (Agent Management Platform) em minutos. + + + + Estruture e teste seu crew ou flow: + ```bash + crewai create crew my_crew + cd my_crew + crewai run + ``` + + + Garanta que a estrutura do projeto está pronta: + ```bash + crewai deploy --prepare + ``` + Veja o [guia de preparação](/pt-BR/enterprise/guides/prepare-for-deployment) para detalhes de estrutura e requisitos. + + + Envie para a plataforma CrewAI AMP: + ```bash + crewai deploy + ``` + Também é possível implantar pela [integração com GitHub](/pt-BR/enterprise/guides/deploy-to-amp) ou pelo [Crew Studio](/pt-BR/enterprise/guides/enable-crew-studio). + + + O crew implantado recebe um endpoint REST. Integre em qualquer aplicação: + ```bash + curl -X POST https://app.crewai.com/api/v1/crews//kickoff \ + -H "Authorization: Bearer $CREWAI_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"inputs": {"topic": "AI agents"}}' + ``` + + + + + + Guia completo de implantação — CLI, GitHub e Crew Studio. + + + Visão da plataforma — o que o AMP oferece para crews em produção. + + + +--- + +## 4. Recursos enterprise + +O CrewAI AMP foi feito para equipes em produção. Além da implantação, você obtém: + + + + Traces de execução, logs e métricas de desempenho para cada execução de crew. Monitore decisões de agentes, chamadas de ferramentas e conclusão de tarefas em tempo real. + + + Interface no-code/low-code para criar, personalizar e implantar crews visualmente — exporte para código ou implante direto. + + + Transmita eventos em tempo real das execuções para seus sistemas. Integre com Slack, Zapier ou qualquer consumidor de webhook. + + + SSO, RBAC e controles em nível de organização. Gerencie quem pode criar, implantar e acessar crews. + + + Publique e compartilhe ferramentas customizadas na organização. Instale ferramentas da comunidade a partir do registro. + + + Execute o CrewAI AMP na sua infraestrutura. Capacidades completas da plataforma com residência de dados e controles de conformidade. + + + + + + Para equipes que precisam levar fluxos de agentes de IA do protótipo à produção — com observabilidade, controles de acesso e infraestrutura escalável. De startups a grandes empresas, o AMP cuida da complexidade operacional para você focar nos agentes. + + + - **Nuvem (app.crewai.com)** — gerenciada pela CrewAI, caminho mais rápido para produção + - **Factory (self-hosted)** — na sua infraestrutura para controle total dos dados + - **Híbrido** — combine nuvem e self-hosted conforme a sensibilidade dos dados + + + + + Cadastre-se e leve seu primeiro crew à produção. + diff --git a/docs/v1.15.1/pt-BR/guides/concepts/evaluating-use-cases.mdx b/docs/v1.15.1/pt-BR/guides/concepts/evaluating-use-cases.mdx new file mode 100644 index 000000000..6d6e31f83 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/concepts/evaluating-use-cases.mdx @@ -0,0 +1,504 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/guides/crews/first-crew.mdx b/docs/v1.15.1/pt-BR/guides/crews/first-crew.mdx new file mode 100644 index 000000000..6325ff528 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/crews/first-crew.mdx @@ -0,0 +1,142 @@ +--- +title: Crie sua primeira Crew +description: Tutorial passo a passo para criar uma equipe colaborativa de IA com configuração JSON-first. +icon: users-gear +mode: "wide" +--- + +## Crie uma Crew de Pesquisa + +Neste guia, você criará uma crew com dois agentes que pesquisa um tópico e escreve um relatório em markdown. Novos projetos de crew são JSON-first: agentes ficam em `agents/*.jsonc`, tarefas e configurações ficam em `crew.jsonc`, e `crewai run` carrega essa definição diretamente. + +### Pré-requisitos + +Antes de começar: + +1. Instale o CrewAI seguindo o [guia de instalação](/pt-BR/installation) +2. Configure sua chave de LLM seguindo o [guia de LLMs](/pt-BR/concepts/llms#setting-up-your-llm) +3. Tenha uma chave [Serper.dev](https://serper.dev/) se quiser usar busca web + +## Etapa 1: Criar uma nova Crew + +```bash +crewai create crew research_crew +cd research_crew +``` + +Estrutura criada: + +```text +research_crew/ +├── .gitignore +├── .env +├── agents/ +│ └── researcher.jsonc +├── crew.jsonc +├── knowledge/ +├── pyproject.toml +├── README.md +├── skills/ +└── tools/ +``` + + +Precisa do layout antigo com `crew.py`, `config/agents.yaml` e `config/tasks.yaml`? Use `crewai create crew research_crew --classic`. + + +## Etapa 2: Definir os agentes + +Substitua o arquivo gerado `agents/researcher.jsonc` e adicione `agents/analyst.jsonc`. Os nomes dos arquivos são os nomes referenciados em `crew.jsonc`. + +```jsonc agents/researcher.jsonc +{ + "role": "Senior Research Specialist for {topic}", + "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.", + "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.", + // Substitua pelo seu modelo, por exemplo "openai/gpt-4o". + "llm": "provider/model-id", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +```jsonc agents/analyst.jsonc +{ + "role": "Report Analyst for {topic}", + "goal": "Turn research findings into a clear, well-structured report.", + "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.", + // Substitua pelo seu modelo, por exemplo "openai/gpt-4o". + "llm": "provider/model-id", + "settings": { + "verbose": true, + "allow_delegation": false + } +} +``` + +Substitua `provider/model-id` pelo modelo usado, como `openai/gpt-4o`, `anthropic/claude-sonnet-4-6` ou `gemini/gemini-2.0-flash-001`. + +## Etapa 3: Definir tarefas e configurações + +Substitua `crew.jsonc` por: + +```jsonc crew.jsonc +{ + "name": "Research Crew", + "agents": ["researcher", "analyst"], + "tasks": [ + { + "name": "research_task", + "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.", + "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.", + "agent": "researcher" + }, + { + "name": "analysis_task", + "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.", + "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.", + "agent": "analyst", + "context": ["research_task"], + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true, + "memory": true, + "inputs": { + "topic": "Artificial Intelligence in Healthcare" + } +} +``` + +`context` aponta para tarefas anteriores, então o analista recebe a saída da pesquisa. `inputs` define valores padrão para `{topic}`; se um valor faltar, `crewai run` perguntará no terminal. + +## Etapa 4: Variáveis de ambiente + +Edite `.env`: + +```sh +SERPER_API_KEY=your_serper_api_key +# Adicione também a chave do seu provedor de modelo. +``` + +## Etapa 5: Instalar e executar + +```bash +crewai install +crewai run +``` + +Quando a execução terminar, abra `output/report.md`. + + +Execute projetos JSON crew apenas de fontes confiáveis. Ferramentas `custom:` e referências `{"python": "module.attribute"}` executam Python local ao carregar a crew. + + + +Você criou uma crew JSON-first funcional que pesquisa um tópico e escreve um relatório. + diff --git a/docs/v1.15.1/pt-BR/guides/flows/conversational-flows.mdx b/docs/v1.15.1/pt-BR/guides/flows/conversational-flows.mdx new file mode 100644 index 000000000..10ffdcbd6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/flows/conversational-flows.mdx @@ -0,0 +1,475 @@ +--- +title: Flows Conversacionais +description: Crie apps de chat multi-turno com kickoff por turno, histórico de mensagens, roteamento de intenção, tracing e pontes WebSocket. +icon: comments +mode: "wide" +--- + +## Visão geral + +Apps conversacionais tratam cada linha do usuário como uma **nova execução do flow** com o **mesmo id de sessão**. A CrewAI oferece helpers para histórico de mensagens, classificação opcional de intenção, tracing adiado, pontes para UI e um REPL local `flow.chat()` para flows conversacionais. + +| Conceito | Implementação | +|---------|----------------| +| Id de sessão | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` | +| Linha do usuário | `handle_turn(message)` acrescenta em `state.messages` antes do grafo rodar | +| Fim do turno | `FlowFinished` só para **esta execução**; o chat segue no próximo `handle_turn` | +| Trace da sessão | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` | + +## APIs de turno + +Use **`flow.handle_turn(message, session_id=...)`** para cada mensagem de usuário em REST, WebSocket, testes e UIs customizadas. Use **`flow.chat()`** quando quiser um loop de chat local no terminal para um `Flow` conversacional. + +`Flow.kickoff()` não aceita os argumentos nomeados `user_message=` ou `session_id=`. Para flows conversacionais, `handle_turn()` guarda a mensagem pendente e chama `kickoff(inputs={"id": session_id})` internamente. + +| API | Uso | +|-----|-----| +| `handle_turn(message, session_id=...)` | Wrapper ergonômico de um turno para `Flow` conversacional | +| `chat()` | REPL local no terminal para `Flow` conversacional | +| `kickoff(inputs={...})` | Execução avançada do flow sem tratamento de turno conversacional | +| `ask()` | Prompt bloqueante **dentro** de um passo (wizard, esclarecimento) | +| `@human_feedback` | Aprovar/rejeitar **saída de um passo** — não a próxima linha do chat | +| `ChatSession.handle_turn(...)` | Camada de transporte sobre `handle_turn` (SSE / WebSocket) | + +## Início rápido + +```python +from uuid import uuid4 + +from crewai import Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, +) + + +@ConversationConfig(defer_trace_finalization=True) +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context): + message = (self.state.current_user_message or "").lower() + if "pedido" in message or "order" in message: + return "order" + if "tchau" in message or "goodbye" in message: + return "goodbye" + return "help" + + @listen("order") + def handle_order(self): + reply = "Seu pedido está a caminho." + self.append_assistant_message(reply) + return reply + + @listen("help") + def handle_help(self): + reply = "Como posso ajudar?" + self.append_assistant_message(reply) + return reply + + @listen("goodbye") + def handle_goodbye(self): + reply = "Até logo!" + self.append_assistant_message(reply) + return reply + + +session_id = str(uuid4()) +flow = SupportFlow() + +try: + flow.handle_turn("Onde está meu pedido?", session_id=session_id) + flow.handle_turn("E as devoluções?", session_id=session_id) +finally: + flow.finalize_session_traces() # um link de trace para o chat inteiro +``` + +## Ciclo de vida do turno + +Cada `handle_turn` executa este pipeline: + +1. **`_configure_conversational_kickoff`** — mescla `session_id` / `user_message` em `inputs`, aplica `ConversationalConfig`, habilita tracing adiado quando configurado. +2. **Restauração de estado** — se `inputs["id"]` existe e `@persist` está configurado, carrega o snapshot mais recente. +3. **`FlowStarted`** — emitido apenas no primeiro turno da sessão adiada. +4. **`prepare_conversational_turn`** — acrescenta a mensagem do usuário em `state.messages`, define `last_user_message`, limpa `last_intent`, classifica opcionalmente quando `intents` / `default_intents` + `intent_llm` estão definidos. +5. **Execução do grafo** — `@start` → `@router` → handlers `@listen`. +6. **Fim da execução** — `flow_finished` por turno e finalização de trace são **ignorados** com adiamento; `Agent.kickoff()` / crews aninhados também não fecham o batch pai. + +Os handlers devem chamar **`append_assistant_message(reply)`** para que o próximo turno inclua a resposta do assistente. A linha do usuário já é salva por `handle_turn` — não acrescente de novo nos handlers. + +## `ConversationalConfig` (padrões em nível de classe) + +Defina na subclasse de `Flow` como `conversational_config: ClassVar[ConversationalConfig | None]`. + +| Campo | Padrão | Propósito | +|-------|---------|-----------| +| `default_intents` | `None` | Rótulos de outcome para classificação automática antes do kickoff | +| `intent_llm` | `None` | Modelo para classificação (obrigatório quando há intents) | +| `interactive_prompt` | `"You: "` | Prompt para `kickoff(interactive=True)` | +| `interactive_timeout` | `None` | Timeout por linha no modo interativo | +| `exit_commands` | `exit`, `quit` | Palavras que encerram o modo interativo | +| `defer_trace_finalization` | `True` | Manter um batch de trace aberto entre turnos | + +Sobrescreva por kickoff com `intents=` e `intent_llm=`. + +## `ChatState` (formato persistido recomendado) + +```python +from crewai.flow import ChatState + + +class MyChatState(ChatState): + # Herdados: id, messages, last_user_message, last_intent, session_ready + research_turn_count: int = 0 + custom_flag: bool = False +``` + +| Campo | Função | +|-------|--------| +| `id` | UUID da sessão (igual a `session_id` / `inputs["id"]`) | +| `messages` | `list` de `{role, content}` para histórico de LLM | +| `last_user_message` | Última linha do usuário neste turno | +| `last_intent` | Rótulo de rota após classificação (se usado) | +| `session_ready` | Flag de bootstrap único (permissões, caches, etc.) | + +`ConversationalInputs` é um `TypedDict` para `kickoff(inputs={...})`: `id`, `user_message`, `last_intent`. + +## API conversacional em `Flow` + +### Parâmetros de `kickoff` / `kickoff_async` + +| Parâmetro | Propósito | +|-----------|-----------| +| `user_message` | Texto deste turno (ou `{"role": "user", "content": "..."}`) | +| `session_id` | UUID da conversa → `inputs["id"]` / `state.id` | +| `intents` | Rótulos de outcome para `classify_intent` antes do kickoff | +| `intent_llm` | LLM para classificação (obrigatório com `intents`) | +| `interactive` | Loop CLI via `ask()` (só demos locais) | +| `interactive_prompt` | Prompt no modo interativo | +| `interactive_timeout` | Timeout de `ask()` por linha | +| `exit_commands` | Palavras que encerram o modo interativo | +| `inputs` | Campos extras de estado (mesclados com chaves conversacionais) | +| `restore_from_state_id` | Hidratação fork de outro flow persistido | + +### Atributos de instância + +| Atributo | Propósito | +|-----------|-----------| +| `conversational_config` | Padrões `ConversationalConfig` em nível de classe | +| `defer_trace_finalization` | Flag de instância; definida automaticamente a partir do config no kickoff | +| `suppress_flow_events` | Oculta painéis Rich no console; **tracing ainda registra** eventos | +| `stream` | Habilita streaming; use com `ChatSession.handle_turn(..., stream=True)` | + +### Métodos e propriedades + +| Nome | Descrição | +|------|-------------| +| `append_message(role, content, **extra)` | Acrescenta em `state.messages` (roles: `user`, `assistant`, `system`, `tool`) | +| `conversation_messages` | Histórico somente leitura para chamadas LLM | +| `classify_intent(text, outcomes, *, llm, context=None)` | Mapeia texto a um outcome (mesma lógica de `@human_feedback`) | +| `receive_user_message(text, *, outcomes=None, llm=None)` | Acrescenta mensagem do usuário; opcionalmente define `last_intent` | +| `finalize_session_traces()` | Emite `flow_finished` adiado e finaliza o batch de trace da sessão | +| `_should_defer_trace_finalization()` | Se este flow adia finalização de trace por turno | +| `input_history` | Trilha de auditoria de prompts e respostas de `ask()` | + +### Helpers do módulo (`crewai.flow.conversation`) + +Importáveis para testes ou orquestração customizada: + +| Função | Descrição | +|----------|-------------| +| `normalize_kickoff_inputs(inputs, user_message=..., session_id=...)` | Mescla kwargs conversacionais em `inputs` | +| `get_conversation_messages(flow)` | Lê mensagens do estado ou buffer interno | +| `append_message(flow, role, content, **extra)` | Igual ao método de instância | +| `prepare_conversational_turn(flow, ...)` | Hidratação do turno (geralmente chamado pelo kickoff) | +| `receive_user_message(flow, text, ...)` | Igual ao método de instância | +| `set_state_field(flow, name, value)` | Define campo em estado dict ou Pydantic | +| `get_conversational_config(flow)` | Lê `conversational_config` da classe | +| `input_history_to_messages(entries)` | Converte `input_history` para formato de mensagens LLM | + +## Padrões de roteamento de intenção + +### A. Pré-classificar via `ConversationalConfig` (mais simples) + +Defina `default_intents` e `intent_llm`. Cada kickoff classifica antes do `@router`; leia `self.state.last_intent` em `route()`. + +### B. Classificar dentro do `@router` (prompts mais ricos) + +Defina `default_intents=None` para o kickoff só acrescentar a mensagem. Em `route()`, chame `classify_intent` com prompt ou descrições customizadas: + +```python +@router(bootstrap) +def route(self): + intent = self.classify_intent( + self._routing_prompt(self.state.last_user_message), + ("GREETING", "ORDER", "RESEARCH", "GOODBYE"), + llm=self.conversational_config.intent_llm or "gpt-4o-mini", + ) + self.state.last_intent = intent + return intent +``` + +Use **`@listen("RESEARCH")`** (ou similar) para passos com `Agent.kickoff()` e ferramentas — não `LLM.call()` puro — quando precisar de pesquisa web ou uso multi-etapa de tools. + +## Quando o flow termina mas o usuário continua conversando + +`FlowFinished` significa que **esta execução do grafo** terminou. A conversa segue com outro `kickoff` e o mesmo `session_id`. `@persist` restaura `messages`, flags e contexto. + +**Padrão de persistência:** prefira `@persist` em um **único passo terminal** (por exemplo `finalize`) em vez de na classe `Flow` inteira. Persist em nível de classe salva após cada método; `load_state` usa a linha mais recente, que pode ser snapshot no meio da execução e perder atualizações dos handlers no mesmo turno. + +Não use `@human_feedback` para linhas de chat de follow-up, a menos que um humano precise aprovar uma saída específica antes de exibi-la. + +## `Flow` conversacional (experimental) + + + **Funcionalidade experimental.** A superfície do `Flow` conversacional + (`conversational = True`, `handle_turn`, `ConversationConfig`, + `RouterConfig`, `ConversationState`, o grafo embutido + helpers) vive em + `crewai.experimental` e pode mudar de formato antes de graduar. Fixe a + versão do CrewAI se depende de comportamento específico e acompanhe o + changelog para mudanças quebradoras. Feedback / issues bem-vindos. + + +Habilite o grafo conversacional definindo `conversational = True` em uma subclasse de `Flow`. O `Flow` base passa a expor um grafo embutido `@start` / `@router` / `converse_turn` / `end_conversation`, gerencia `state.messages`, dirige o LLM de roteamento e mantém o batch de trace aberto entre os turnos. Você escreve as **rotas customizadas**; o framework cuida do resto. + +Use isto quando quiser um chat multi-turno com router LLM e handlers por rota sem cablar o ciclo de vida na mão. Use `Flow[ChatState]` (o padrão de mais baixo nível acima) quando precisar de controle total. + +### Exemplo rápido + +```python +from crewai import LLM, Flow +from crewai.flow import listen +from crewai.experimental.conversational import ( + ConversationConfig, + ConversationState, + RouterConfig, +) + + +ROUTER_LLM = LLM(model="gpt-4o-mini") + + +@ConversationConfig( + system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.", + llm=ROUTER_LLM, + router=RouterConfig(), # rotas + descrições auto-descobertas pelos handlers @listen +) +class SupportFlow(Flow[ConversationState]): + conversational = True + + @listen("INTERNET_SEARCH") + def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... + self.append_assistant_message(reply) + return reply + + @listen("CREWAI_DOCS") + def handle_crewai_docs(self) -> str: + """Look up the CrewAI documentation for framework/API questions.""" + ... + self.append_assistant_message(reply) + return reply + + +flow = SupportFlow() +try: + flow.handle_turn("O que você pode fazer?") # roteia para converse (built-in) + flow.handle_turn("Pesquise na web por notícias de IA.") # roteia para INTERNET_SEARCH + flow.handle_turn("Resuma o primeiro resultado.") # volta para converse +finally: + flow.finalize_session_traces() +``` + +Para um chat local no terminal, use `chat()`: + +```python +def kickoff() -> None: + SupportFlow().chat() +``` + +`chat()` envolve `handle_turn()` em um REPL, sai com `exit` / `quit`, ignora linhas em branco por padrão e chama `finalize_session_traces()` quando a sessão termina. + +### `ConversationConfig` + +Decorador de classe que anexa os defaults de chat por classe. + +| Campo | Padrão | Propósito | +|-------|--------|-----------| +| `system_prompt` | `slices.conversational_system_prompt` (i18n) | System message usado pelo `converse_turn` embutido. Passe `""` para desativar totalmente. | +| `llm` | `None` | LLM de conversa (usado pelo `converse_turn` e como fallback do router). | +| `router` | `None` | `RouterConfig` para roteamento por LLM. Sem ele, o flow sempre cai em `converse`. | +| `answer_from_history_prompt` | padrão do framework | System message para a rota opcional `answer_from_history`. | +| `answer_from_history_llm` | `None` | Habilita o atalho `answer_from_history` quando definido. | +| `intent_llm` | `None` | LLM para o caminho legado `intents=`/`default_intents`. | +| `default_intents` | `None` | Labels de outcome para pré-classificação legada. | +| `visible_agent_outputs` | `None` | `"all"` ou lista de nomes de agentes cujos `append_agent_result()` devem virar mensagens públicas. | +| `defer_trace_finalization` | `True` | Mantém um único batch de trace aberto entre chamadas de `handle_turn()`. | + +### `RouterConfig` e o catálogo de rotas auto-gerado + +```python +RouterConfig( + prompt="Enquadramento de domínio opcional (política, voz, persona).", + response_format=MyRoute, # opcional; auto-gerado caso contrário + llm=ROUTER_LLM, # usa ConversationConfig.llm como fallback + routes=["INTERNET_SEARCH", "CREWAI_DOCS"], # opcional; inferido dos listeners + route_descriptions={ + "INTERNET_SEARCH": "Sobrescreve a docstring só desta rota.", + }, + default_intent="converse", # usado quando a chamada ao LLM falha ou não há LLM + fallback_intent="converse", # usado quando o LLM retorna rota inválida + intent_field="intent", +) +``` + +O prompt do router é montado automaticamente. Para cada rota o framework escolhe a descrição nesta precedência: + +1. `RouterConfig.route_descriptions[label]` — override explícito. +2. `Flow.builtin_route_descriptions[label]` — texto canônico do framework para `converse`, `end`, `answer_from_history` (otimizado para o LLM de routing). +3. Primeira linha não vazia da docstring do handler `@listen(label)`. +4. Vazio (a rota aparece no catálogo sem descrição). + +Na prática, **adicionar uma rota é `@listen("X")` + uma docstring de uma linha**: + +```python +@listen("INTERNET_SEARCH") +def handle_internet_search(self) -> str: + """Fresh web research, current news, real-time lookups.""" + ... +``` + +…e o LLM de routing vê: + +``` +Routes: +- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions. +- INTERNET_SEARCH: Fresh web research, current news, real-time lookups. +- converse: Ordinary chat, follow-ups, summaries, clarifications… +- end: User signals the conversation is finished (goodbye, exit, done). +``` + +`RouterConfig.prompt` é para **enquadramento de domínio** (persona do assistente, regras de negócio, voz). O catálogo de rotas é auto-gerado — não liste rotas em `prompt`; elas vão sair de sincronia assim que você adicionar um handler. + +### Rotas embutidas + +| Rota | Handler | Propósito | +|------|---------|-----------| +| `converse` | `converse_turn` | Handler de chat padrão. Chama `ConversationConfig.llm` com o system prompt + histórico canônico. | +| `end` | `end_conversation` | Define `state.ended = True` e emite uma resposta de encerramento. | +| `answer_from_history` | `answer_from_history_turn` | Opcional. Cai aqui quando `ConversationConfig.answer_from_history_llm` está definido e a mensagem pode ser respondida só pelo histórico. | + +Você pode sobrescrever qualquer uma definindo um handler com o mesmo nome na subclasse. + +### Semântica de `handle_turn()` + +`flow.handle_turn(message)` roda um turno: + +1. Reseta o tracking por execução (`_completed_methods`, `_method_outputs`) para o grafo re-rodar — sem isso, chamadas repetidas de `kickoff` na mesma instância dariam curto-circuito no turno 2+ porque `Flow.kickoff_async` trata `inputs={"id": ...}` como restauração de checkpoint. +2. Anexa a mensagem do usuário em `state.messages`, define `current_user_message` / `last_user_message`. `last_intent` é **preservado do turno anterior** para que o LLM de routing possa usá-lo como sinal. +3. Roda `conversation_start` → `route_conversation` → o handler `@listen` escolhido. +4. O router grava sua decisão em `state.last_intent` (visível para o contexto de routing do próximo turno). +5. Se seu handler retornou uma string e ainda não chamou `append_assistant_message`, `handle_turn` anexa para você. + +Chame `handle_turn()` para mensagens de chat. Chamar `kickoff(inputs={"id": ...})` diretamente executa o grafo sem aplicar o wrapper de turno conversacional. + +### `chat()` para REPLs locais + +`flow.chat()` é o wrapper de terminal pronto para uso em cima de `handle_turn()`: + +```python +flow = SupportFlow() +flow.chat() +``` + +Ele cobre o loop local comum: + +1. Solicita uma mensagem do usuário. +2. Para com `exit` / `quit`, `EOFError` ou `KeyboardInterrupt`. +3. Chama `handle_turn(message, session_id=...)`. +4. Imprime o resultado do assistente. +5. Finaliza traces de sessão adiados em um bloco `finally`. + +Customize o comportamento do terminal com I/O injetável: + +```python +flow.chat( + session_id="demo-session", + prompt="You: ", + assistant_prefix="Assistant: ", + exit_commands=("exit", "quit", "bye"), +) +``` + +Para apps web, workers em background, testes e transportes customizados, continue usando `handle_turn()` diretamente. + +### Comportamento customizado do router + +Para rodar efeitos colaterais (setup de event bus, telemetria) em toda decisão de routing, sobrescreva `route_turn`: + +```python +class SupportFlow(Flow[ConversationState]): + conversational = True + + def route_turn(self, context: dict[str, Any]) -> str | None: + self.event_bus = MyBus(self) + return super().route_turn(context) +``` + +Para ignorar o router LLM e escolher uma rota programaticamente, retorne uma string de `route_turn`; retornar `None` cai no `_route_with_config(...)`. + +### `append_assistant_message` e `append_agent_result` + +Dentro de um handler `@listen(label)`, escolha: + +- `self.append_assistant_message(text)` — adiciona um turno de assistente visível ao usuário em `state.messages`. O `converse_turn` do próximo turno vai vê-lo. +- `self.append_agent_result(agent_name, result, visibility="private")` — registra um evento estruturado em `state.events` e uma thread em `state.agent_threads[agent_name]`. Visibilidade pública também chama `append_assistant_message` automaticamente. Use resultados privados para trabalho de bastidor que não deve poluir o histórico canônico. + +`ConversationConfig.visible_agent_outputs` pode promover globalmente os resultados privados de agentes específicos para públicos (`"all"` ou lista de nomes). + +## Tracing entre turnos + +Com `defer_trace_finalization=True` (padrão em `ConversationalConfig`): + +- **Um batch de trace** para toda a sessão de chat. +- **`flow_started`** só no primeiro turno; **`flow_finished`** uma vez em `finalize_session_traces()`. +- **`kickoff` por turno** não exibe “Trace batch finalized”. +- **Trabalho aninhado** (`Agent.kickoff()`, crews, tools Exa) acrescenta ao batch **pai**; flows internos de `AgentExecutor` não fecham o batch da sessão cedo. + +```python +flow.chat(session_id=session_id) +``` + +`flow.chat()` chama `finalize_session_traces()` para você. Quando você controla o loop com `handle_turn()` ou `kickoff(...)`, chame `finalize_session_traces()` quando a sessão terminar. + +`suppress_flow_events=True` só oculta painéis do console; eventos de trace e método ainda são emitidos. + +### Ciclo de vida de trace do `Flow` conversacional + +O [`Flow` conversacional](#flow-conversacional-experimental) experimental usa o mesmo ciclo de vida de tracing: `defer_trace_finalization` é `True` por padrão, então cada `handle_turn()` mantém o trace da sessão aberto. Sempre finalize ao fim da sessão — envolva seu loop em `try/finally` e chame `flow.finalize_session_traces()` na saída. Sem isso, o batch fica aberto e a última conversa pode nunca ser exportada. + +## Streaming + +Defina `stream = True` na classe `Flow`. `kickoff(...)` então emitirá `assistant_delta` (e eventos relacionados) pelo event bus padrão. + +## Imports + +```python +from crewai.flow import ( + ChatState, + ConversationalConfig, + ConversationalInputs, + Flow, + listen, + persist, + router, + start, +) +``` + +## Veja também + +- [Dominando o Gerenciamento de Estado em Flows](/pt-BR/guides/flows/mastering-flow-state) — persistência, estado Pydantic, `@persist` +- [Construa Seu Primeiro Flow](/pt-BR/guides/flows/first-flow) — fundamentos de flow +- Demo: `lib/crewai/runner_conversational_flow_simple.py` — REPL mínimo com `RESEARCH` + agente Exa diff --git a/docs/v1.15.1/pt-BR/guides/flows/first-flow.mdx b/docs/v1.15.1/pt-BR/guides/flows/first-flow.mdx new file mode 100644 index 000000000..0ff1ba5d6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/flows/first-flow.mdx @@ -0,0 +1,550 @@ +--- +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 +mode: "wide" +--- + +## 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. A crew inicial embutida usa o layout clássico Python/YAML. Para usar uma crew JSON-first dentro de um Flow, crie `crew.jsonc` e `agents/*.jsonc` na pasta da crew e carregue com `crewai.project.load_crew`, como mostrado em [Flows](/pt-BR/concepts/flows#building-your-crews). + +``` +guide_creator_flow/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +└── src/ + └── guide_creator_flow/ + ├── __init__.py + ├── 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 `src/guide_creator_flow/main.py` +- Crews especializados no diretório `src/guide_creator_flow/crews` +- Ferramentas customizadas no diretório `src/guide_creator_flow/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 configurar o crew de redatores com JSONC. Vamos definir dois agentes especializados - um escritor e um revisor - que colaboram para criar conteúdo de alta qualidade para o guia. + +1. Crie `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`: + +```jsonc +{ + "role": "Educational Content Writer", + "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.", + "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +2. Crie `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`: + +```jsonc +{ + "role": "Educational Content Reviewer and Editor", + "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.", + "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.", + "llm": "provider/model-id", + "settings": { + "verbose": true + } +} +``` + +Substitua `provider/model-id` pelo modelo que você usa, como `openai/gpt-4o`, `gemini/gemini-2.0-flash-001` ou `anthropic/claude-sonnet-4-6`. + +3. Crie `src/guide_creator_flow/crews/content_crew/crew.jsonc`: + +```jsonc +{ + "name": "Content Crew", + "agents": ["content_writer", "content_reviewer"], + "tasks": [ + { + "name": "write_section_task", + "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}", + "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.", + "agent": "content_writer", + "markdown": true + }, + { + "name": "review_section_task", + "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.", + "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.", + "agent": "content_reviewer", + "context": ["write_section_task"], + "markdown": true + } + ], + "process": "sequential", + "verbose": true +} +``` + +O campo `context` permite que o revisor use a saída do escritor. + +4. Substitua `src/guide_creator_flow/crews/content_crew/content_crew.py` por um pequeno loader: + +```python +from pathlib import Path + +from crewai.project import load_crew + + +def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) +``` + +Esse loader transforma `crew.jsonc` em uma `Crew` em runtime. Embora essa crew possa funcionar de forma independente, no nosso flow ela será orquestrada 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 +#!/usr/bin/env python +import json +import os +from typing import List, Dict +from pydantic import BaseModel, Field +from crewai import LLM +from crewai.flow.flow import Flow, listen, start +from guide_creator_flow.crews.content_crew.content_crew import kickoff_content_crew + +# Definir nossos modelos para dados estruturados +class Section(BaseModel): + title: str = Field(description="Title of the section") + description: str = Field(description="Brief description of what the section should cover") + +class GuideOutline(BaseModel): + title: str = Field(description="Title of the guide") + introduction: str = Field(description="Introduction to the topic") + target_audience: str = Field(description="Description of the target audience") + sections: List[Section] = Field(description="List of sections in the guide") + conclusion: str = Field(description="Conclusion or summary of the guide") + +# Definir o estado do nosso flow +class GuideCreatorState(BaseModel): + topic: str = "" + audience_level: str = "" + guide_outline: GuideOutline = None + sections_content: Dict[str, str] = {} + +class GuideCreatorFlow(Flow[GuideCreatorState]): + """Flow para criar um guia abrangente sobre qualquer tópico""" + + @start() + def get_user_input(self): + """Obter entrada do usuário sobre o tópico e público do guia""" + print("\n=== Create Your Comprehensive Guide ===\n") + + # Obter entrada do usuário + self.state.topic = input("What topic would you like to create a guide for? ") + + # Obter nível do público com validação + while True: + audience = input("Who is your target audience? (beginner/intermediate/advanced) ").lower() + if audience in ["beginner", "intermediate", "advanced"]: + self.state.audience_level = audience + break + print("Please enter 'beginner', 'intermediate', or 'advanced'") + + print(f"\nCreating a guide on {self.state.topic} for {self.state.audience_level} audience...\n") + return self.state + + @listen(get_user_input) + def create_guide_outline(self, state): + """Criar um esboço estruturado para o guia usando uma chamada direta ao LLM""" + print("Creating guide outline...") + + # Inicializar o LLM + llm = LLM(model="openai/gpt-4o-mini", response_format=GuideOutline) + + # Criar as mensagens para o esboço + messages = [ + {"role": "system", "content": "You are a helpful assistant designed to output JSON."}, + {"role": "user", "content": f""" + Create a detailed outline for a comprehensive guide on "{state.topic}" for {state.audience_level} level learners. + + The outline should include: + 1. A compelling title for the guide + 2. An introduction to the topic + 3. 4-6 main sections that cover the most important aspects of the topic + 4. A conclusion or summary + + For each section, provide a clear title and a brief description of what it should cover. + """} + ] + + # Fazer a chamada ao LLM com formato de resposta JSON + response = llm.call(messages=messages) + + # Analisar a resposta JSON + outline_dict = json.loads(response) + self.state.guide_outline = GuideOutline(**outline_dict) + + # Garantir que o diretório de saída exista antes de salvar + os.makedirs("output", exist_ok=True) + + # Salvar o esboço em um arquivo + with open("output/guide_outline.json", "w") as f: + json.dump(outline_dict, f, indent=2) + + print(f"Guide outline created with {len(self.state.guide_outline.sections)} sections") + return self.state.guide_outline + + @listen(create_guide_outline) + def write_and_compile_guide(self, outline): + """Escrever todas as seções e compilar o guia""" + print("Writing guide sections and compiling...") + completed_sections = [] + + # Processar seções uma por uma para manter o fluxo de contexto + for section in outline.sections: + print(f"Processing section: {section.title}") + + # Construir contexto a partir das seções anteriores + previous_sections_text = "" + if completed_sections: + previous_sections_text = "# Previously Written Sections\n\n" + for title in completed_sections: + previous_sections_text += f"## {title}\n\n" + previous_sections_text += self.state.sections_content.get(title, "") + "\n\n" + else: + previous_sections_text = "No previous sections written yet." + + # Executar a crew de conteúdo para esta seção + result = kickoff_content_crew(inputs={ + "section_title": section.title, + "section_description": section.description, + "audience_level": self.state.audience_level, + "previous_sections": previous_sections_text, + "draft_content": "" + }) + + # Armazenar o conteúdo + self.state.sections_content[section.title] = result.raw + completed_sections.append(section.title) + print(f"Section completed: {section.title}") + + # Compilar o guia final + guide_content = f"# {outline.title}\n\n" + guide_content += f"## Introduction\n\n{outline.introduction}\n\n" + + # Adicionar cada seção em ordem + for section in outline.sections: + section_content = self.state.sections_content.get(section.title, "") + guide_content += f"\n\n{section_content}\n\n" + + # Adicionar conclusão + guide_content += f"## Conclusion\n\n{outline.conclusion}\n\n" + + # Salvar o guia + with open("output/complete_guide.md", "w") as f: + f.write(guide_content) + + print("\nComplete guide compiled and saved to output/complete_guide.md") + return "Guide creation completed successfully" + +def kickoff(): + """Executar o flow criador de guias""" + GuideCreatorFlow().kickoff() + print("\n=== Flow Complete ===") + print("Your comprehensive guide is ready in the output directory.") + print("Open output/complete_guide.md to view it.") + +def plot(): + """Gerar uma visualização do flow""" + flow = GuideCreatorFlow() + flow.plot("guide_creator_flow") + print("Flow visualization saved to guide_creator_flow.html") + +if __name__ == "__main__": + kickoff() +``` + +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 run +``` + +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 = kickoff_content_crew(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 +6. Criar apps de chat multi-turn com [Flows conversacionais](/pt-BR/guides/flows/conversational-flows) (`kickoff` por mensagem, `ChatSession`, tracing adiado) + + +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/v1.15.1/pt-BR/guides/flows/inputs-id-deprecation.mdx b/docs/v1.15.1/pt-BR/guides/flows/inputs-id-deprecation.mdx new file mode 100644 index 000000000..3e17d5640 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/flows/inputs-id-deprecation.mdx @@ -0,0 +1,142 @@ +--- +title: "Migrando de inputs.id para restore_from_state_id" +description: "Mover fluxos @persist da hidratação obsoleta inputs.id para o campo suportado restore_from_state_id" +icon: "arrow-right-arrow-left" +--- + + + Passar `id` dentro de `inputs` para hidratar um fluxo `@persist` é **obsoleto** e + programado para remoção em uma versão futura. A substituição, `restore_from_state_id`, + está disponível no CrewAI **v1.14.5 e posterior** — os passos abaixo se aplicam uma vez que você + faça a atualização. + + +## Visão Geral + +A maneira documentada de hidratar um fluxo `@persist` de uma execução anterior é passar +o UUID dessa execução como `inputs.id`. O CrewAI agora expõe um campo dedicado, +`restore_from_state_id`, que realiza a mesma hidratação sem sobrecarregar a +carga útil de `inputs` — e sem acoplar a chave de hidratação à identidade da nova execução. + +## Migração + +Se você atualmente inicia um fluxo `@persist` com `inputs={"id": ...}`: + +```python +# Obsoleto +flow = CounterFlow() +flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}) +``` + +Mude para `restore_from_state_id`: + +```python +# Suportado +flow = CounterFlow() +flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv") +``` + +Os dois modos têm semânticas de linhagem diferentes: + +- `inputs={"id": }` (obsoleto) — **retomar**: as gravações são feitas sob o id fornecido, + estendendo a mesma história de `flow_uuid`. +- `restore_from_state_id=` — **dividir**: hidrata o estado a partir de um snapshot, então + grava sob um novo `state.id`. A história do fluxo de origem é preservada. + +Para a maioria dos cenários de produção — reexecutar um fluxo hidratado de um estado anterior — criar um fork +é o que você deseja. Veja [Dominando o Estado do Fluxo](/pt-BR/guides/flows/mastering-flow-state) +para o modelo mental completo. + +Se você iniciar seu fluxo pela API REST do CrewAI AMP, veja [AMP](#amp) abaixo para a +migração equivalente da carga útil. + +## Por que estamos descontinuando `inputs.id` para `@persist`? + +`inputs.id` é atualmente a maneira documentada de retomar um fluxo `@persist` de uma +execução anterior. O problema é que o mesmo UUID faz duas funções ao mesmo tempo: + +1. **Seleciona qual snapshot o `@persist` usa para hidratar** — carrega o estado salvo + sob aquele UUID. +2. **Torna-se o ID de Execução do Fluxo da nova execução** (`state.id` no SDK; + apresentado como `flow_id` em alguns contextos) — cada gravação `@persist` a partir desta + inicialização também cai sob aquele mesmo UUID. + +Esse papel duplo é a causa raiz dos problemas que este guia descreve. Como o +UUID fornecido também é o id da nova execução, duas inicializações que passam o mesmo +`inputs.id` não são duas execuções distintas — elas compartilham um id, compartilham um registro +de persistência e (no AMP) compartilham uma linha na lista de execuções. Não há como dizer +"hidratar a partir deste snapshot, mas registrar esta execução separadamente" sem dividir as +duas responsabilidades. + +`restore_from_state_id` é essa divisão. Ele informa ao `@persist` de qual snapshot hidratar, +enquanto deixa a nova execução livre para receber um novo `state.id`. A +fonte de hidratação e a execução registrada não são mais o mesmo UUID — que é o que +a maioria dos cenários de produção realmente deseja. + +## Cronograma de remoção + +`inputs.id` para hidratação `@persist` está programado para remoção em uma versão futura do +CrewAI. Não há um corte imediato — fluxos existentes continuam a funcionar — mas +uma vez que você atualize para v1.14.5 ou posterior, novo código deve usar `restore_from_state_id`, e +fluxos existentes devem migrar na próxima oportunidade conveniente. + +## AMP + +Se você implantar seu fluxo no CrewAI AMP, a migração se estende à carga útil de inicialização +enviada para sua Crew implantada, e os sintomas visíveis de reutilização de `inputs.id` aparecem +no painel de controle de implantação. As duas subseções abaixo cobrem ambos. + +### Migrando a carga útil de inicialização + +Se você atualmente inicia um fluxo implantado incorporando `id` em `inputs`: + +```bash +# Obsoleto +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +Mova o UUID para o campo `restoreFromStateId` de nível superior: + +```bash +# Suportado +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{ + "inputs": {"topic": "AI Agent Frameworks"}, + "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv" + }' \ + https://your-crew-url.crewai.com/kickoff +``` + +`restoreFromStateId` fica ao lado de `inputs` na carga útil de inicialização, não dentro dela. O +objeto `inputs` agora carrega apenas valores que seu fluxo realmente consome. + +### O que acontece quando `inputs.id` é reutilizado + +Quando o AMP recebe um kickoff para um fluxo cujo `inputs.id` corresponde a uma execução +existente, ele resolve para o registro existente em vez de criar um novo. A partir +do painel de controle de implantação, você verá: + +- **Status da execução** — o status da nova execução sobrescreve o status da execução anterior. Uma + execução finalizada pode voltar para `running`, ou uma execução `completed` pode mudar para + `error` se a nova inicialização falhar — de qualquer forma, o painel não reflete mais + a execução original. +- **Rastros** — Os OTel traces se acumulam entre as inicializações porque compartilham o mesmo + id de execução; os traces da execução anterior são substituídos ou misturados + com os da nova execução. Uma reprodução passo a passo não corresponde mais a uma única execução. +- **Lista de execuções** — kickoffs que deveriam aparecer como linhas separadas colapsam em + uma única entrada, ocultando o histórico. + +Migrar para `restoreFromStateId` mantém cada kickoff como sua própria execução — com +seu próprio status, traces e entrada na lista — enquanto ainda hidrata o estado de uma +execução anterior. + + + Entre em contato com nossa equipe de suporte se você não tiver certeza de qual modo seu fluxo precisa ou se encontrar problemas + durante a migração. + diff --git a/docs/v1.15.1/pt-BR/guides/flows/mastering-flow-state.mdx b/docs/v1.15.1/pt-BR/guides/flows/mastering-flow-state.mdx new file mode 100644 index 000000000..1d3e6ee42 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/flows/mastering-flow-state.mdx @@ -0,0 +1,815 @@ +--- +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 +mode: "wide" +--- + +## 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 + +Para chat multi-turn (`kickoff` por linha do usuário, `ChatState`, roteamento por intenção, tracing adiado e `ChatSession`), veja [Flows conversacionais](/pt-BR/guides/flows/conversational-flows). + +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 +from crewai.flow.flow import Flow, listen, start + +class UnstructuredStateFlow(Flow): + @start() + def initialize_data(self): + print("Initializing flow data") + # Adiciona pares chave-valor ao estado + self.state["user_name"] = "Alex" + self.state["preferences"] = { + "theme": "dark", + "language": "English" + } + self.state["items"] = [] + + # O estado do flow recebe automaticamente um ID único + print(f"Flow ID: {self.state['id']}") + + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + print(f"Previous step returned: {previous_result}") + + # Acessa e modifica o estado + user = self.state["user_name"] + print(f"Processing data for {user}") + + # Adiciona itens a uma lista no estado + self.state["items"].append("item1") + self.state["items"].append("item2") + + # Adiciona um novo par chave-valor + self.state["processed"] = True + + return "Processed" + + @listen(process_data) + def generate_summary(self, previous_result): + # Acessa múltiplos valores do estado + user = self.state["user_name"] + theme = self.state["preferences"]["theme"] + items = self.state["items"] + processed = self.state.get("processed", False) + + summary = f"User {user} has {len(items)} items with {theme} theme. " + summary += "Data is processed." if processed else "Data is not processed." + + return summary + +# Executa o flow +flow = UnstructuredStateFlow() +result = flow.kickoff() +print(f"Final result: {result}") +print(f"Final state: {flow.state}") +``` + +### 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 +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel, Field +from typing import List, Dict, Optional + +# Define o modelo de estado +class UserPreferences(BaseModel): + theme: str = "light" + language: str = "English" + +class AppState(BaseModel): + user_name: str = "" + preferences: UserPreferences = UserPreferences() + items: List[str] = [] + processed: bool = False + completion_percentage: float = 0.0 + +# Cria um flow com estado tipado +class StructuredStateFlow(Flow[AppState]): + @start() + def initialize_data(self): + print("Initializing flow data") + # Define valores do estado (com checagem de tipo) + self.state.user_name = "Taylor" + self.state.preferences.theme = "dark" + + # O campo ID está disponível automaticamente + print(f"Flow ID: {self.state.id}") + + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + print(f"Processing data for {self.state.user_name}") + + # Modifica o estado (com checagem de tipo) + self.state.items.append("item1") + self.state.items.append("item2") + self.state.processed = True + self.state.completion_percentage = 50.0 + + return "Processed" + + @listen(process_data) + def generate_summary(self, previous_result): + # Acessa o estado (com autocompletar) + summary = f"User {self.state.user_name} has {len(self.state.items)} items " + summary += f"with {self.state.preferences.theme} theme. " + summary += "Data is processed." if self.state.processed else "Data is not processed." + summary += f" Completion: {self.state.completion_percentage}%" + + return summary + +# Executa o flow +flow = StructuredStateFlow() +result = flow.kickoff() +print(f"Final result: {result}") +print(f"Final state: {flow.state}") +``` + +### 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 +from crewai.flow.flow import Flow, listen, start + +class DataPassingFlow(Flow): + @start() + def generate_data(self): + # Este valor de retorno será passado para os métodos listeners + return "Generated data" + + @listen(generate_data) + def process_data(self, data_from_previous_step): + print(f"Received: {data_from_previous_step}") + # Você pode modificar os dados e repassá-los adiante + processed_data = f"{data_from_previous_step} - processed" + # Também atualiza o estado + self.state["last_processed"] = processed_data + return processed_data + + @listen(process_data) + def finalize_data(self, processed_data): + print(f"Received processed data: {processed_data}") + # Acessa tanto os dados passados quanto o estado + last_processed = self.state.get("last_processed", "") + return f"Final: {processed_data} (from state: {last_processed})" +``` + +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 +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + value: int = 0 + +@persist() # Aplica à classe inteira do flow +class PersistentCounterFlow(Flow[CounterState]): + @start() + def increment(self): + self.state.value += 1 + print(f"Incremented to {self.state.value}") + return self.state.value + + @listen(increment) + def double(self, value): + self.state.value = value * 2 + print(f"Doubled to {self.state.value}") + return self.state.value + +# Primeira execução +flow1 = PersistentCounterFlow() +result1 = flow1.kickoff() +print(f"First run result: {result1}") + +# Segunda execução - passa o ID para carregar o estado persistido +flow2 = PersistentCounterFlow() +result2 = flow2.kickoff(inputs={"id": flow1.state.id}) +print(f"Second run result: {result2}") # Será maior devido ao estado persistido +``` + +#### Persistência em Nível de Método + +Para mais controle, você pode aplicar `@persist()` em métodos específicos: + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist + +class SelectivePersistFlow(Flow): + @start() + def first_step(self): + self.state["count"] = 1 + return "First step" + + @persist() # Persiste apenas após este método + @listen(first_step) + def important_step(self, prev_result): + self.state["count"] += 1 + self.state["important_data"] = "This will be persisted" + return "Important step completed" + + @listen(important_step) + def final_step(self, prev_result): + self.state["count"] += 1 + return f"Complete with count {self.state['count']}" +``` + +#### Forking de Estado Persistido + +`@persist` suporta dois modos distintos de hidratação em `kickoff` / `kickoff_async`. Use **resume** (`inputs["id"]`) para continuar a mesma linhagem; use **fork** (`restore_from_state_id`) para iniciar uma nova linhagem a partir de um snapshot: + +| | `state.id` após o kickoff | Escritas do `@persist` vão para | +|---|---|---| +| `inputs["id"]` (resume) | id informado | id informado (estende o histórico) | +| `restore_from_state_id` (fork) | id novo, ou `inputs["id"]` se fixado | id novo (origem preservada) | + +```python +from crewai.flow.flow import Flow, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + id: str = "" + counter: int = 0 + +@persist +class CounterFlow(Flow[CounterState]): + @start() + def step(self): + self.state.counter += 1 + +# Execução 1: estado novo, counter 0 -> 1 +flow_1 = CounterFlow() +flow_1.kickoff() + +# Fork: hidrata do snapshot mais recente de flow_1, mas escreve sob um state.id NOVO +flow_2 = CounterFlow() +flow_2.kickoff(restore_from_state_id=flow_1.state.id) +# flow_2 começa com counter=1 (hidratado), e step() incrementa para 2. +# O histórico do flow_uuid de flow_1 não é alterado. +``` + +Notas sobre o comportamento: + +- `restore_from_state_id` não encontrado na persistência → o kickoff retorna silenciosamente ao comportamento padrão (espelha o comportamento de `inputs["id"]` quando não encontrado). Nenhuma exceção é lançada. +- Combinar `restore_from_state_id` com `from_checkpoint` lança um `ValueError` — eles miram sistemas de estado diferentes (`@persist` vs. Checkpointing) e não podem ser combinados. +- `restore_from_state_id=None` (padrão) é byte-idêntico a um kickoff sem o parâmetro. +- Fixar `inputs["id"]` durante o fork significa que a nova execução compartilha uma chave de persistência com outro flow — geralmente você quer apenas `restore_from_state_id`. + +## 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 +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class PaymentState(BaseModel): + amount: float = 0.0 + is_approved: bool = False + retry_count: int = 0 + +class PaymentFlow(Flow[PaymentState]): + @start() + def process_payment(self): + # Simula o processamento do pagamento + self.state.amount = 100.0 + self.state.is_approved = self.state.amount < 1000 + return "Payment processed" + + @router(process_payment) + def check_approval(self, previous_result): + if self.state.is_approved: + return "approved" + elif self.state.retry_count < 3: + return "retry" + else: + return "rejected" + + @listen("approved") + def handle_approval(self): + return f"Payment of ${self.state.amount} approved!" + + @listen("retry") + def handle_retry(self): + self.state.retry_count += 1 + print(f"Retrying payment (attempt {self.state.retry_count})...") + # Aqui poderia ser implementada a lógica de retry + return "Retry initiated" + + @listen("rejected") + def handle_rejection(self): + return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries." +``` + +### Manipulações Complexas de Estado + +Para transformar estados complexos, você pode criar métodos dedicados: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel +from typing import List, Dict + +class UserData(BaseModel): + name: str + active: bool = True + login_count: int = 0 + +class ComplexState(BaseModel): + users: Dict[str, UserData] = {} + active_user_count: int = 0 + +class TransformationFlow(Flow[ComplexState]): + @start() + def initialize(self): + # Adiciona alguns usuários + self.add_user("alice", "Alice") + self.add_user("bob", "Bob") + self.add_user("charlie", "Charlie") + return "Initialized" + + @listen(initialize) + def process_users(self, _): + # Incrementa contagens de login + for user_id in self.state.users: + self.increment_login(user_id) + + # Desativa um usuário + self.deactivate_user("bob") + + # Atualiza a contagem de ativos + self.update_active_count() + + return f"Processed {len(self.state.users)} users" + + # Métodos auxiliares para transformações de estado + def add_user(self, user_id: str, name: str): + self.state.users[user_id] = UserData(name=name) + self.update_active_count() + + def increment_login(self, user_id: str): + if user_id in self.state.users: + self.state.users[user_id].login_count += 1 + + def deactivate_user(self, user_id: str): + if user_id in self.state.users: + self.state.users[user_id].active = False + self.update_active_count() + + def update_active_count(self): + self.state.active_user_count = sum( + 1 for user in self.state.users.values() if user.active + ) +``` + +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 +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + +class ResearchState(BaseModel): + topic: str = "" + depth: str = "medium" + results: str = "" + +class ResearchFlow(Flow[ResearchState]): + @start() + def get_parameters(self): + # Em uma aplicação real, isso pode vir da entrada do usuário + self.state.topic = "Artificial Intelligence Ethics" + self.state.depth = "deep" + return "Parameters set" + + @listen(get_parameters) + def execute_research(self, _): + # Cria os agentes + researcher = Agent( + role="Research Specialist", + goal=f"Research {self.state.topic} in {self.state.depth} detail", + backstory="You are an expert researcher with a talent for finding accurate information." + ) + + writer = Agent( + role="Content Writer", + goal="Transform research into clear, engaging content", + backstory="You excel at communicating complex ideas clearly and concisely." + ) + + # Cria as tarefas + research_task = Task( + description=f"Research {self.state.topic} with {self.state.depth} analysis", + expected_output="Comprehensive research notes in markdown format", + agent=researcher + ) + + writing_task = Task( + description=f"Create a summary on {self.state.topic} based on the research", + expected_output="Well-written article in markdown format", + agent=writer, + context=[research_task] + ) + + # Cria e executa a crew + research_crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + verbose=True + ) + + # Executa a crew e armazena o resultado no estado + result = research_crew.kickoff() + self.state.results = result.raw + + return "Research completed" + + @listen(execute_research) + def summarize_results(self, _): + # Acessa os resultados armazenados + result_length = len(self.state.results) + return f"Research on {self.state.topic} completed with {result_length} characters of results." +``` + +### 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 +@listen(execute_crew) +def process_crew_results(self, _): + # Faz parsing dos resultados brutos (assumindo saída em JSON) + import json + try: + results_dict = json.loads(self.state.raw_results) + self.state.processed_results = { + "title": results_dict.get("title", ""), + "main_points": results_dict.get("main_points", []), + "conclusion": results_dict.get("conclusion", "") + } + return "Results processed successfully" + except json.JSONDecodeError: + self.state.error = "Failed to parse crew results as JSON" + return "Error processing results" +``` + +## Boas Práticas para Gerenciamento de Estado + +### 1. Mantenha o Estado Focado + +Projete seu estado para conter somente o necessário: + +```python +# Abrangente demais +class BloatedState(BaseModel): + user_data: Dict = {} + system_settings: Dict = {} + temporary_calculations: List = [] + debug_info: Dict = {} + # ...muitos outros campos + +# Melhor: estado focado +class FocusedState(BaseModel): + user_id: str + preferences: Dict[str, str] + completion_status: Dict[str, bool] +``` + +### 2. Use Estado Estruturado em Flows Complexos + +À medida que seus flows evoluem em complexidade, o estado estruturado se torna cada vez mais valioso: + +```python +# Flow simples pode usar estado não estruturado +class SimpleGreetingFlow(Flow): + @start() + def greet(self): + self.state["name"] = "World" + return f"Hello, {self.state['name']}!" + +# Flow complexo se beneficia de estado estruturado +class UserRegistrationState(BaseModel): + username: str + email: str + verification_status: bool = False + registration_date: datetime = Field(default_factory=datetime.now) + last_login: Optional[datetime] = None + +class RegistrationFlow(Flow[UserRegistrationState]): + # Métodos com acesso ao estado fortemente tipado +``` + +### 3. Documente Transições de Estado + +Para flows complexos, documente como o estado muda ao longo da execução: + +```python +@start() +def initialize_order(self): + """ + Initialize order state with empty values. + + State before: {} + State after: {order_id: str, items: [], status: 'new'} + """ + self.state.order_id = str(uuid.uuid4()) + self.state.items = [] + self.state.status = "new" + return "Order initialized" +``` + +### 4. Trate Erros de Estado de Forma Elegante + +Implemente tratamento de erros ao acessar o estado: + +```python +@listen(previous_step) +def process_data(self, _): + try: + # Tenta acessar um valor que pode não existir + user_preference = self.state.preferences.get("theme", "default") + except (AttributeError, KeyError): + # Trata o erro de forma elegante + self.state.errors = self.state.get("errors", []) + self.state.errors.append("Failed to access preferences") + user_preference = "default" + + return f"Used preference: {user_preference}" +``` + +### 5. Use o Estado Para Acompanhar o Progresso + +Aproveite o estado para monitorar o progresso em flows de longa duração: + +```python +class ProgressTrackingFlow(Flow): + @start() + def initialize(self): + self.state["total_steps"] = 3 + self.state["current_step"] = 0 + self.state["progress"] = 0.0 + self.update_progress() + return "Initialized" + + def update_progress(self): + """Helper method to calculate and update progress""" + if self.state.get("total_steps", 0) > 0: + self.state["progress"] = (self.state.get("current_step", 0) / + self.state["total_steps"]) * 100 + print(f"Progress: {self.state['progress']:.1f}%") + + @listen(initialize) + def step_one(self, _): + # Realiza o trabalho... + self.state["current_step"] = 1 + self.update_progress() + return "Step 1 complete" + + # Etapas adicionais... +``` + +### 6. Prefira Operações Imutáveis Quando Possível + +Especialmente com estado estruturado, prefira operações imutáveis para maior clareza: + +```python +# Em vez de modificar listas no local: +self.state.items.append(new_item) # Operação mutável + +# Considere criar um novo estado: +from pydantic import BaseModel +from typing import List + +class ItemState(BaseModel): + items: List[str] = [] + +class ImmutableFlow(Flow[ItemState]): + @start() + def add_item(self): + # Cria uma nova lista com o item adicionado + self.state.items = [*self.state.items, "new item"] + return "Item added" +``` + +## Depurando o Estado do Flow + +### Logando Alterações no Estado + +Ao desenvolver, adicione logs para acompanhar mudanças no estado: + +```python +import logging +logging.basicConfig(level=logging.INFO) + +class LoggingFlow(Flow): + def log_state(self, step_name): + logging.info(f"State after {step_name}: {self.state}") + + @start() + def initialize(self): + self.state["counter"] = 0 + self.log_state("initialize") + return "Initialized" + + @listen(initialize) + def increment(self, _): + self.state["counter"] += 1 + self.log_state("increment") + return f"Incremented to {self.state['counter']}" +``` + +### Visualizando o Estado + +Você pode adicionar métodos para visualizar seu estado durante o debug: + +```python +def visualize_state(self): + """Create a simple visualization of the current state""" + import json + from rich.console import Console + from rich.panel import Panel + + console = Console() + + if hasattr(self.state, "model_dump"): + # Pydantic v2 + state_dict = self.state.model_dump() + elif hasattr(self.state, "dict"): + # Pydantic v1 + state_dict = self.state.dict() + else: + # Estado não estruturado + state_dict = dict(self.state) + + # Remove o id para uma saída mais limpa + if "id" in state_dict: + state_dict.pop("id") + + state_json = json.dumps(state_dict, indent=2, default=str) + console.print(Panel(state_json, title="Current Flow State")) +``` + +## 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/v1.15.1/pt-BR/guides/migration/migrating-from-langgraph.mdx b/docs/v1.15.1/pt-BR/guides/migration/migrating-from-langgraph.mdx new file mode 100644 index 000000000..4889c91f6 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/migration/migrating-from-langgraph.mdx @@ -0,0 +1,518 @@ +--- +title: "Migrando do LangGraph para o CrewAI: um guia prático para engenheiros" +description: Se você já construiu com LangGraph, saiba como portar rapidamente seus projetos para o CrewAI +icon: switch +mode: "wide" +--- + +Você construiu agentes com LangGraph. Já lutou com o `StateGraph`, ligou arestas condicionais e depurou dicionários de estado às 2 da manhã. Funciona — mas, em algum momento, você começou a se perguntar se existe um caminho melhor para produção. + +Existe. **CrewAI Flows** entrega o mesmo poder — orquestração orientada a eventos, roteamento condicional, estado compartilhado — com muito menos boilerplate e um modelo mental que se alinha a como você realmente pensa sobre fluxos de trabalho de IA em múltiplas etapas. + +Este artigo apresenta os conceitos principais lado a lado, mostra comparações reais de código e demonstra por que o CrewAI Flows é o framework que você vai querer usar a seguir. + +--- + +## A Mudança de Modelo Mental + +LangGraph pede que você pense em **grafos**: nós, arestas e dicionários de estado. Todo workflow é um grafo direcionado em que você conecta explicitamente as transições entre as etapas de computação. É poderoso, mas a abstração traz overhead — especialmente quando o seu fluxo é fundamentalmente sequencial com alguns pontos de decisão. + +CrewAI Flows pede que você pense em **eventos**: métodos que iniciam, métodos que escutam resultados e métodos que roteiam a execução. A topologia do workflow emerge de anotações com decorators, em vez de construção explícita do grafo. Isso não é apenas açúcar sintático — muda como você projeta, lê e mantém seus pipelines. + +Veja o mapeamento principal: + +| Conceito no LangGraph | Equivalente no CrewAI Flows | +| --- | --- | +| `StateGraph` class | `Flow` class | +| `add_node()` | Methods decorated with `@start`, `@listen` | +| `add_edge()` / `add_conditional_edges()` | `@listen()` / `@router()` decorators | +| `TypedDict` state | Pydantic `BaseModel` state | +| `START` / `END` constants | `@start()` decorator / natural method return | +| `graph.compile()` | `flow.kickoff()` | +| Checkpointer / persistence | Built-in memory (LanceDB-backed) | + +Vamos ver como isso fica na prática. + +--- + +## Demo 1: Um Pipeline Sequencial Simples + +Imagine que você está construindo um pipeline que recebe um tema, pesquisa, escreve um resumo e formata a saída. Veja como cada framework lida com isso. + +### Abordagem com LangGraph + +```python +from typing import TypedDict +from langgraph.graph import StateGraph, START, END + +class ResearchState(TypedDict): + topic: str + raw_research: str + summary: str + formatted_output: str + +def research_topic(state: ResearchState) -> dict: + # Call an LLM or search API + result = llm.invoke(f"Research the topic: {state['topic']}") + return {"raw_research": result} + +def write_summary(state: ResearchState) -> dict: + result = llm.invoke( + f"Summarize this research:\n{state['raw_research']}" + ) + return {"summary": result} + +def format_output(state: ResearchState) -> dict: + result = llm.invoke( + f"Format this summary as a polished article section:\n{state['summary']}" + ) + return {"formatted_output": result} + +# Build the graph +graph = StateGraph(ResearchState) +graph.add_node("research", research_topic) +graph.add_node("summarize", write_summary) +graph.add_node("format", format_output) + +graph.add_edge(START, "research") +graph.add_edge("research", "summarize") +graph.add_edge("summarize", "format") +graph.add_edge("format", END) + +# Compile and run +app = graph.compile() +result = app.invoke({"topic": "quantum computing advances in 2026"}) +print(result["formatted_output"]) +``` + +Você define funções, registra-as como nós e conecta manualmente cada transição. Para uma sequência simples como essa, há muita cerimônia. + +### Abordagem com CrewAI Flows + +```python +from crewai import LLM, Agent, Crew, Process, Task +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class ResearchState(BaseModel): + topic: str = "" + raw_research: str = "" + summary: str = "" + formatted_output: str = "" + +class ResearchFlow(Flow[ResearchState]): + @start() + def research_topic(self): + # Option 1: Direct LLM call + result = llm.call(f"Research the topic: {self.state.topic}") + self.state.raw_research = result + return result + + @listen(research_topic) + def write_summary(self, research_output): + # Option 2: A single agent + summarizer = Agent( + role="Research Summarizer", + goal="Produce concise, accurate summaries of research content", + backstory="You are an expert at distilling complex research into clear, " + "digestible summaries.", + llm=llm, + verbose=True, + ) + result = summarizer.kickoff( + f"Summarize this research:\n{self.state.raw_research}" + ) + self.state.summary = str(result) + return self.state.summary + + @listen(write_summary) + def format_output(self, summary_output): + # Option 3: a complete crew (with one or more agents) + formatter = Agent( + role="Content Formatter", + goal="Transform research summaries into polished, publication-ready article sections", + backstory="You are a skilled editor with expertise in structuring and " + "presenting technical content for a general audience.", + llm=llm, + verbose=True, + ) + format_task = Task( + description=f"Format this summary as a polished article section:\n{self.state.summary}", + expected_output="A well-structured, polished article section ready for publication.", + agent=formatter, + ) + crew = Crew( + agents=[formatter], + tasks=[format_task], + process=Process.sequential, + verbose=True, + ) + result = crew.kickoff() + self.state.formatted_output = str(result) + return self.state.formatted_output + +# Run the flow +flow = ResearchFlow() +flow.state.topic = "quantum computing advances in 2026" +result = flow.kickoff() +print(flow.state.formatted_output) + +``` + +Repare a diferença: nada de construção de grafo, de ligação de arestas, nem de etapa de compilação. A ordem de execução é declarada exatamente onde a lógica vive. `@start()` marca o ponto de entrada, e `@listen(method_name)` encadeia as etapas. O estado é um modelo Pydantic de verdade, com segurança de tipos, validação e auto-complete na IDE. + +--- + +## Demo 2: Roteamento Condicional + +Aqui é que fica interessante. Digamos que você está construindo um pipeline de conteúdo que roteia para diferentes caminhos de processamento com base no tipo de conteúdo detectado. + +### Abordagem com LangGraph + +```python +from typing import TypedDict, Literal +from langgraph.graph import StateGraph, START, END + +class ContentState(TypedDict): + input_text: str + content_type: str + result: str + +def classify_content(state: ContentState) -> dict: + content_type = llm.invoke( + f"Classify this content as 'technical', 'creative', or 'business':\n{state['input_text']}" + ) + return {"content_type": content_type.strip().lower()} + +def process_technical(state: ContentState) -> dict: + result = llm.invoke(f"Process as technical doc:\n{state['input_text']}") + return {"result": result} + +def process_creative(state: ContentState) -> dict: + result = llm.invoke(f"Process as creative writing:\n{state['input_text']}") + return {"result": result} + +def process_business(state: ContentState) -> dict: + result = llm.invoke(f"Process as business content:\n{state['input_text']}") + return {"result": result} + +# Routing function +def route_content(state: ContentState) -> Literal["technical", "creative", "business"]: + return state["content_type"] + +# Build the graph +graph = StateGraph(ContentState) +graph.add_node("classify", classify_content) +graph.add_node("technical", process_technical) +graph.add_node("creative", process_creative) +graph.add_node("business", process_business) + +graph.add_edge(START, "classify") +graph.add_conditional_edges( + "classify", + route_content, + { + "technical": "technical", + "creative": "creative", + "business": "business", + } +) +graph.add_edge("technical", END) +graph.add_edge("creative", END) +graph.add_edge("business", END) + +app = graph.compile() +result = app.invoke({"input_text": "Explain how TCP handshakes work"}) +``` + +Você precisa de uma função de roteamento separada, de um mapeamento explícito de arestas condicionais e de arestas de término para cada ramificação. A lógica de roteamento fica desacoplada do nó que produz a decisão. + +### Abordagem com CrewAI Flows + +```python +from crewai import LLM, Agent +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class ContentState(BaseModel): + input_text: str = "" + content_type: str = "" + result: str = "" + +class ContentFlow(Flow[ContentState]): + @start() + def classify_content(self): + self.state.content_type = ( + llm.call( + f"Classify this content as 'technical', 'creative', or 'business':\n" + f"{self.state.input_text}" + ) + .strip() + .lower() + ) + return self.state.content_type + + @router(classify_content) + def route_content(self, classification): + if classification == "technical": + return "process_technical" + elif classification == "creative": + return "process_creative" + else: + return "process_business" + + @listen("process_technical") + def handle_technical(self): + agent = Agent( + role="Technical Writer", + goal="Produce clear, accurate technical documentation", + backstory="You are an expert technical writer who specializes in " + "explaining complex technical concepts precisely.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as technical doc:\n{self.state.input_text}") + ) + + @listen("process_creative") + def handle_creative(self): + agent = Agent( + role="Creative Writer", + goal="Craft engaging and imaginative creative content", + backstory="You are a talented creative writer with a flair for " + "compelling storytelling and vivid expression.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as creative writing:\n{self.state.input_text}") + ) + + @listen("process_business") + def handle_business(self): + agent = Agent( + role="Business Writer", + goal="Produce professional, results-oriented business content", + backstory="You are an experienced business writer who communicates " + "strategy and value clearly to professional audiences.", + llm=llm, + verbose=True, + ) + self.state.result = str( + agent.kickoff(f"Process as business content:\n{self.state.input_text}") + ) + +flow = ContentFlow() +flow.state.input_text = "Explain how TCP handshakes work" +flow.kickoff() +print(flow.state.result) + +``` + +O decorator `@router()` transforma um método em um ponto de decisão. Ele retorna uma string que corresponde a um listener — sem dicionários de mapeamento, sem funções de roteamento separadas. A lógica de ramificação parece um `if` em Python porque *é* um. + +--- + +## Demo 3: Integrando Crews de Agentes de IA em Flows + +É aqui que o verdadeiro poder do CrewAI aparece. Flows não servem apenas para encadear chamadas de LLM — elas orquestram **Crews** completas de agentes autônomos. Isso é algo para o qual o LangGraph simplesmente não tem um equivalente nativo. + +```python +from crewai import Agent, Task, Crew +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ArticleState(BaseModel): + topic: str = "" + research: str = "" + draft: str = "" + final_article: str = "" + +class ArticleFlow(Flow[ArticleState]): + + @start() + def run_research_crew(self): + """A full Crew of agents handles research.""" + researcher = Agent( + role="Senior Research Analyst", + goal=f"Produce comprehensive research on: {self.state.topic}", + backstory="You're a veteran analyst known for thorough, " + "well-sourced research reports.", + llm="gpt-4o" + ) + + research_task = Task( + description=f"Research '{self.state.topic}' thoroughly. " + "Cover key trends, data points, and expert opinions.", + expected_output="A detailed research brief with sources.", + agent=researcher + ) + + crew = Crew(agents=[researcher], tasks=[research_task]) + result = crew.kickoff() + self.state.research = result.raw + return result.raw + + @listen(run_research_crew) + def run_writing_crew(self, research_output): + """A different Crew handles writing.""" + writer = Agent( + role="Technical Writer", + goal="Write a compelling article based on provided research.", + backstory="You turn complex research into engaging, clear prose.", + llm="gpt-4o" + ) + + editor = Agent( + role="Senior Editor", + goal="Review and polish articles for publication quality.", + backstory="20 years of editorial experience at top tech publications.", + llm="gpt-4o" + ) + + write_task = Task( + description=f"Write an article based on this research:\n{self.state.research}", + expected_output="A well-structured draft article.", + agent=writer + ) + + edit_task = Task( + description="Review, fact-check, and polish the draft article.", + expected_output="A publication-ready article.", + agent=editor + ) + + crew = Crew(agents=[writer, editor], tasks=[write_task, edit_task]) + result = crew.kickoff() + self.state.final_article = result.raw + return result.raw + +# Run the full pipeline +flow = ArticleFlow() +flow.state.topic = "The Future of Edge AI" +flow.kickoff() +print(flow.state.final_article) +``` + +Este é o insight-chave: **Flows fornecem a camada de orquestração, e Crews fornecem a camada de inteligência.** Cada etapa em um Flow pode subir uma equipe completa de agentes colaborativos, cada um com seus próprios papéis, objetivos e ferramentas. Você obtém fluxo de controle estruturado e previsível *e* colaboração autônoma de agentes — o melhor dos dois mundos. + +No LangGraph, alcançar algo similar significa implementar manualmente protocolos de comunicação entre agentes, loops de chamada de ferramentas e lógica de delegação dentro das funções dos nós. É possível, mas é encanamento que você constrói do zero todas as vezes. + +--- + +## Demo 4: Execução Paralela e Sincronização + +Pipelines do mundo real frequentemente precisam dividir o trabalho e juntar os resultados. O CrewAI Flows lida com isso de forma elegante com os operadores `and_` e `or_`. + +```python +from crewai import LLM +from crewai.flow.flow import Flow, and_, listen, start +from pydantic import BaseModel + +llm = LLM(model="openai/gpt-5.2") + +class AnalysisState(BaseModel): + topic: str = "" + market_data: str = "" + tech_analysis: str = "" + competitor_intel: str = "" + final_report: str = "" + +class ParallelAnalysisFlow(Flow[AnalysisState]): + @start() + def start_method(self): + pass + + @listen(start_method) + def gather_market_data(self): + # Your agentic or deterministic code + pass + + @listen(start_method) + def run_tech_analysis(self): + # Your agentic or deterministic code + pass + + @listen(start_method) + def gather_competitor_intel(self): + # Your agentic or deterministic code + pass + + @listen(and_(gather_market_data, run_tech_analysis, gather_competitor_intel)) + def synthesize_report(self): + # Your agentic or deterministic code + pass + +flow = ParallelAnalysisFlow() +flow.state.topic = "AI-powered developer tools" +flow.kickoff() + +``` + +Vários decorators `@start()` disparam em paralelo. O combinador `and_()` no decorator `@listen` garante que `synthesize_report` só execute depois que *todos os três* métodos upstream forem concluídos. Também existe `or_()` para quando você quer prosseguir assim que *qualquer* tarefa upstream terminar. + +No LangGraph, você precisaria construir um padrão fan-out/fan-in com ramificações paralelas, um nó de sincronização e uma mesclagem de estado cuidadosa — tudo conectado explicitamente por arestas. + +--- + +## Por que CrewAI Flows em Produção + +Além de uma sintaxe mais limpa, Flows entrega várias vantagens críticas para produção: + +**Persistência de estado integrada.** O estado do Flow é respaldado pelo LanceDB, o que significa que seus workflows podem sobreviver a falhas, ser retomados e acumular conhecimento entre execuções. No LangGraph, você precisa configurar um checkpointer separado. + +**Gerenciamento de estado com segurança de tipos.** Modelos Pydantic oferecem validação, serialização e suporte de IDE prontos para uso. Estados `TypedDict` do LangGraph não validam em runtime. + +**Orquestração de agentes de primeira classe.** Crews são um primitivo nativo. Você define agentes com papéis, objetivos, histórias e ferramentas — e eles colaboram de forma autônoma dentro do envelope estruturado de um Flow. Não é preciso reinventar a coordenação multiagente. + +**Modelo mental mais simples.** Decorators declaram intenção. `@start` significa "comece aqui". `@listen(x)` significa "execute depois de x". `@router(x)` significa "decida para onde ir depois de x". O código lê como o workflow que ele descreve. + +**Integração com CLI.** Execute flows com `crewai run`. Sem etapa de compilação separada, sem serialização de grafo. Seu Flow é uma classe Python, e ele roda como tal. + +--- + +## Cheat Sheet de Migração + +Se você está com uma base de código LangGraph e quer migrar para o CrewAI Flows, aqui vai um guia prático de conversão: + +1. **Mapeie seu estado.** Converta seu `TypedDict` para um `BaseModel` do Pydantic. Adicione valores padrão para todos os campos. +2. **Converta nós em métodos.** Cada função de `add_node` vira um método na sua subclasse de `Flow`. Substitua leituras `state["field"]` por `self.state.field`. +3. **Substitua arestas por decorators.** `add_edge(START, "first_node")` vira `@start()` no primeiro método. A sequência `add_edge("a", "b")` vira `@listen(a)` no método `b`. +4. **Substitua arestas condicionais por `@router`.** A função de roteamento e o mapeamento do `add_conditional_edges()` viram um único método `@router()` que retorna a string de rota. +5. **Troque compile + invoke por kickoff.** Remova `graph.compile()`. Chame `flow.kickoff()`. +6. **Considere onde as Crews se encaixam.** Qualquer nó com lógica complexa de agentes em múltiplas etapas é um candidato a extração para uma Crew. É aqui que você verá a maior melhoria de qualidade. + +--- + +## Primeiros Passos + +Instale o CrewAI e crie o scaffold de um novo projeto Flow: + +```bash +pip install crewai +crewai create flow my_first_flow +cd my_first_flow +``` + +Isso gera uma estrutura de projeto com uma classe Flow pronta para edição, arquivos de configuração e um `pyproject.toml` com `type = "flow"` já definido. Execute com: + +```bash +crewai run +``` + +A partir daí, adicione seus agentes, conecte seus listeners e publique. + +--- + +## Considerações Finais + +O LangGraph ensinou ao ecossistema que workflows de IA precisam de estrutura. Essa foi uma lição importante. Mas o CrewAI Flows pega essa lição e a entrega de um jeito mais rápido de escrever, mais fácil de ler e mais poderoso em produção — especialmente quando seus workflows envolvem múltiplos agentes colaborando. + +Se você está construindo algo além de uma cadeia de agente único, dê uma olhada séria no Flows. O modelo baseado em decorators, a integração nativa com Crews e o gerenciamento de estado embutido significam menos tempo com encanamento e mais tempo nos problemas que importam. + +Comece com `crewai create flow`. Você não vai olhar para trás. diff --git a/docs/v1.15.1/pt-BR/guides/migration/upgrading-crewai.mdx b/docs/v1.15.1/pt-BR/guides/migration/upgrading-crewai.mdx new file mode 100644 index 000000000..0c7472d0a --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/migration/upgrading-crewai.mdx @@ -0,0 +1,190 @@ +--- +title: "Atualizando o CrewAI" +description: "Como atualizar o CrewAI no seu projeto e adaptar-se a breaking changes entre versões." +icon: "arrow-up-circle" +--- + +## Visão Geral + +Os lançamentos do CrewAI trazem novos recursos regularmente. Este guia mostra os passos práticos para manter sua instalação atualizada — tanto a CLI quanto o ambiente virtual do seu projeto. + +Se você está começando do zero, veja [Instalação](/pt-BR/installation). Se está vindo de outro framework, veja [Migrando do LangGraph](/pt-BR/guides/migration/migrating-from-langgraph). + +--- + +## As Duas Coisas Que Você Pode Querer Atualizar + +O CrewAI vive em dois lugares na sua máquina, e cada um se atualiza de forma independente: + +| O quê | Como é instalado | Como atualizar | +|---|---|---| +| A **CLI global `crewai`** | `uv tool install crewai` | `uv tool install crewai --upgrade` | +| O **venv do projeto** (onde seu código roda) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` e depois `crewai install` | + +Esses dois podem — e frequentemente ficam — fora de sincronia. Rodar `crewai --version` mostra a versão da CLI. Rodar `uv pip show crewai` dentro do seu projeto mostra a versão do venv. Se forem diferentes, isso é normal; o que importa para o código em execução é a versão do venv. + +## Por Que `crewai install` Sozinho Não Atualiza + +`crewai install` é um wrapper fino em torno de `uv sync`. Ele instala exatamente o que o arquivo `uv.lock` atual diz — ele **não** muda nenhuma restrição de versão. + +Se seu `pyproject.toml` diz `crewai>=1.11.1` e o lock file resolveu para `1.11.1`, executar `crewai install` vai te manter em `1.11.1` para sempre, mesmo que `1.14.4` esteja disponível. + +Para realmente atualizar, você precisa: + +1. Atualizar a restrição de versão em `pyproject.toml` +2. Re-resolver o lock file +3. Sincronizar o venv + +`uv add` faz os três de uma vez só. + +## Como Atualizar Seu Projeto + +```bash +# Aumenta a restrição e re-resolve o lock em um único comando +uv add "crewai[tools]>=1.14.4" + +# Sincroniza o venv (crewai install chama uv sync por baixo dos panos) +crewai install + +# Verifica +uv pip show crewai +# → Version: 1.14.4 +``` + +Substitua `[tools]` por quaisquer extras que seu projeto utilize (ex.: `[tools,anthropic]`). Verifique a lista de `dependencies` do seu `pyproject.toml` se estiver em dúvida. + + + `uv add` atualiza tanto `pyproject.toml` **quanto** `uv.lock` atomicamente. Se você editar `pyproject.toml` manualmente, ainda precisa rodar `uv lock --upgrade-package crewai` para re-resolver o lock file antes que `crewai install` pegue a nova versão. + + +## Atualizando a CLI Global + +A CLI global é separada do seu projeto. Atualize com: + +```bash +uv tool install crewai --upgrade +``` + +Se seu shell avisar sobre o `PATH` após a atualização, recarregue-o: + +```bash +uv tool update-shell +``` + +Isso **não** mexe no venv do seu projeto — você ainda precisa de `uv add` + `crewai install` dentro do projeto. + +## Verifique Se Ambos Estão em Sincronia + +```bash +# Versão da CLI global +crewai --version + +# Versão do venv do projeto +uv pip show crewai | grep Version +``` + +Eles não precisam coincidir — mas a versão do venv do projeto é o que importa para o comportamento em runtime. + + + CrewAI requer `Python >=3.10, <3.14`. Se o `uv` foi instalado contra um interpretador mais antigo, recrie o venv do projeto com uma versão suportada do Python antes de rodar `crewai install`. + + +--- + +## Breaking Changes e Notas de Migração + +A maioria das atualizações requer apenas pequenos ajustes. As áreas abaixo são as que quebram silenciosamente ou com tracebacks confusos. + +### Caminhos de import: tools e `BaseTool` + +O caminho canônico para tools é `crewai.tools`. Caminhos antigos ainda aparecem em tutoriais, mas devem ser atualizados. + +```python +# Antes +from crewai_tools import BaseTool +from crewai.agents.tools import tool + +# Depois +from crewai.tools import BaseTool, tool +``` + +O decorador `@tool` e a subclasse `BaseTool` ambos vivem em `crewai.tools`. `AgentFinish` e outros símbolos internos do agente não fazem mais parte da superfície pública — se você os estava importando, mude para event listeners ou callbacks de `Task`. + +### Mudanças de parâmetros em `Agent` + +```python +from crewai import Agent + +agent = Agent( + role="Researcher", + goal="Find authoritative sources on {topic}", + backstory="You are a careful, source-driven researcher.", + llm="gpt-4o-mini", # nome do modelo como string OU um objeto LLM + verbose=True, # bool, não um nível inteiro + max_iter=15, # default mudou entre versões — defina explicitamente + allow_delegation=False, +) +``` + +- `llm` aceita tanto um nome de modelo como string (resolvido pelo provedor configurado) quanto um objeto `LLM` para controle granular. +- `verbose` é um `bool` puro. Passar um inteiro não alterna mais níveis de log. +- Os defaults de `max_iter` mudaram entre releases. Se seu agente para silenciosamente de iterar após a primeira chamada de tool, defina `max_iter` explicitamente. + +### Parâmetros de `Crew` + +```python +from crewai import Crew, Process + +crew = Crew( + agents=[...], + tasks=[...], + process=Process.sequential, # ou Process.hierarchical + memory=True, + cache=True, + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}}, +) +``` + +- `process=Process.hierarchical` requer ou `manager_llm=` ou `manager_agent=`. Sem um deles, o kickoff lança erro na validação. +- `memory=True` com um provedor de embedding não-default precisa de um dicionário `embedder` — veja [Configuração de memória e embedder](#memory-embedder-config) abaixo. + +### Saída estruturada de `Task` + +Use `output_pydantic`, `output_json` ou `output_file` para forçar o resultado de uma task em um formato tipado: + +```python +from pydantic import BaseModel +from crewai import Task + +class Article(BaseModel): + title: str + body: str + +write = Task( + description="Write an article about {topic}", + expected_output="A short article with a title and body", + agent=writer, + output_pydantic=Article, # a classe, NÃO uma instância + output_file="output/article.md", +) +``` + +`output_pydantic` recebe a **classe** em si. Passar `Article(title="", body="")` é um erro comum e falha com um erro de validação confuso. + +### Configuração de memória e embedder {#memory-embedder-config} + +Se `memory=True` e você não está usando os embeddings padrão da OpenAI, é preciso passar um `embedder`: + +```python +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={ + "provider": "ollama", + "config": {"model": "nomic-embed-text"}, + }, +) +``` + +Defina as credenciais do provedor relevante (`OPENAI_API_KEY`, `OLLAMA_HOST`, etc.) no seu arquivo `.env`. Os caminhos de armazenamento de memória são locais ao projeto por default — apague o diretório de memória do projeto se trocar de embedder, já que dimensões diferentes não se misturam. diff --git a/docs/v1.15.1/pt-BR/guides/tools/publish-custom-tools.mdx b/docs/v1.15.1/pt-BR/guides/tools/publish-custom-tools.mdx new file mode 100644 index 000000000..1a56ee8e2 --- /dev/null +++ b/docs/v1.15.1/pt-BR/guides/tools/publish-custom-tools.mdx @@ -0,0 +1,244 @@ +--- +title: Publicar Ferramentas Personalizadas +description: Como construir, empacotar e publicar suas próprias ferramentas compatíveis com CrewAI no PyPI para que qualquer usuário do CrewAI possa instalá-las e usá-las. +icon: box-open +mode: "wide" +--- + +## Visão Geral + +O sistema de ferramentas do CrewAI foi projetado para ser extensível. Se você construiu uma ferramenta que pode beneficiar outros, pode empacotá-la como uma biblioteca Python independente, publicá-la no PyPI e disponibilizá-la para qualquer usuário do CrewAI — sem necessidade de PR para o repositório do CrewAI. + +Este guia percorre todo o processo: implementação do contrato de ferramentas, estruturação do pacote e publicação no PyPI. + + +Se você precisa apenas de uma ferramenta personalizada para seu próprio projeto, consulte o guia [Criar Ferramentas Personalizadas](/pt-BR/learn/create-custom-tools). + + +## O Contrato de Ferramentas + +Toda ferramenta CrewAI deve satisfazer uma das duas interfaces: + +### Opção 1: Subclassificar `BaseTool` + +Subclassifique `crewai.tools.BaseTool` e implemente o método `_run`. Defina `name`, `description` e, opcionalmente, um `args_schema` para validação de entrada. + +```python +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + + +class GeolocateInput(BaseModel): + """Esquema de entrada para GeolocateTool.""" + address: str = Field(..., description="O endereço para geolocalizar.") + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converte um endereço em coordenadas de latitude/longitude." + args_schema: type[BaseModel] = GeolocateInput + + def _run(self, address: str) -> str: + # Sua implementação aqui + return f"40.7128, -74.0060" +``` + +### Opção 2: Usar o Decorador `@tool` + +Para ferramentas mais simples, o decorador `@tool` transforma uma função em uma ferramenta CrewAI. A função **deve** ter uma docstring (usada como descrição da ferramenta) e anotações de tipo. + +```python +from crewai.tools import tool + + +@tool("Geolocate") +def geolocate(address: str) -> str: + """Converte um endereço em coordenadas de latitude/longitude.""" + return "40.7128, -74.0060" +``` + +### Requisitos Essenciais + +Independentemente da abordagem escolhida, sua ferramenta deve: + +- Ter um **`name`** — um identificador curto e descritivo. +- Ter uma **`description`** — informa ao agente quando e como usar a ferramenta. Isso afeta diretamente a qualidade do uso da ferramenta pelo agente, então seja claro e específico. +- Implementar **`_run`** (BaseTool) ou fornecer um **corpo de função** (@tool) — a lógica de execução síncrona. +- Usar **anotações de tipo** em todos os parâmetros e valores de retorno. +- Retornar um resultado em **string** (ou algo que possa ser convertido de forma significativa). + +### Opcional: Suporte Assíncrono + +Se sua ferramenta realiza operações de I/O, implemente `_arun` para execução assíncrona: + +```python +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converte um endereço em coordenadas de latitude/longitude." + + def _run(self, address: str) -> str: + # Implementação síncrona + ... + + async def _arun(self, address: str) -> str: + # Implementação assíncrona + ... +``` + +### Opcional: Validação de Entrada com `args_schema` + +Defina um modelo Pydantic como seu `args_schema` para obter validação automática de entrada e mensagens de erro claras. Se não fornecer um, o CrewAI irá inferi-lo da assinatura do seu método `_run`. + +```python +from pydantic import BaseModel, Field + + +class TranslateInput(BaseModel): + """Esquema de entrada para TranslateTool.""" + text: str = Field(..., description="O texto a ser traduzido.") + target_language: str = Field( + default="en", + description="Código de idioma ISO 639-1 para o idioma de destino.", + ) +``` + +Esquemas explícitos são recomendados para ferramentas publicadas — produzem melhor comportamento do agente e documentação mais clara para seus usuários. + +### Opcional: Variáveis de Ambiente + +Se sua ferramenta requer chaves de API ou outra configuração, declare-as com `env_vars` para que os usuários saibam o que configurar: + +```python +from crewai.tools import BaseTool, EnvVar + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converte um endereço em coordenadas de latitude/longitude." + env_vars: list[EnvVar] = [ + EnvVar( + name="GEOCODING_API_KEY", + description="Chave de API para o serviço de geocodificação.", + required=True, + ), + ] + + def _run(self, address: str) -> str: + ... +``` + +## Estrutura do Pacote + +Estruture seu projeto como um pacote Python padrão. Layout recomendado: + +``` +crewai-geolocate/ +├── pyproject.toml +├── LICENSE +├── README.md +└── src/ + └── crewai_geolocate/ + ├── __init__.py + └── tools.py +``` + +### `pyproject.toml` + +```toml +[project] +name = "crewai-geolocate" +version = "0.1.0" +description = "Uma ferramenta CrewAI para geolocalizar endereços." +requires-python = ">=3.10" +dependencies = [ + "crewai", +] + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" +``` + +Declare `crewai` como dependência para que os usuários obtenham automaticamente uma versão compatível. + +### `__init__.py` + +Re-exporte suas classes de ferramenta para que os usuários possam importá-las diretamente: + +```python +from crewai_geolocate.tools import GeolocateTool + +__all__ = ["GeolocateTool"] +``` + +### Convenções de Nomenclatura + +- **Nome do pacote**: Use o prefixo `crewai-` (ex.: `crewai-geolocate`). Isso torna sua ferramenta fácil de encontrar no PyPI. +- **Nome do módulo**: Use underscores (ex.: `crewai_geolocate`). +- **Nome da classe da ferramenta**: Use PascalCase terminando em `Tool` (ex.: `GeolocateTool`). + +## Testando sua Ferramenta + +Antes de publicar, verifique se sua ferramenta funciona dentro de uma crew: + +```python +from crewai import Agent, Crew, Task +from crewai_geolocate import GeolocateTool + +agent = Agent( + role="Analista de Localização", + goal="Encontrar coordenadas para os endereços fornecidos.", + backstory="Um especialista em dados geoespaciais.", + tools=[GeolocateTool()], +) + +task = Task( + description="Encontre as coordenadas de 1600 Pennsylvania Avenue, Washington, DC.", + expected_output="A latitude e longitude do endereço.", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## Publicando no PyPI + +Quando sua ferramenta estiver testada e pronta: + +```bash +# Construir o pacote +uv build + +# Publicar no PyPI +uv publish +``` + +Se é sua primeira vez publicando, você precisará de uma [conta no PyPI](https://pypi.org/account/register/) e um [token de API](https://pypi.org/help/#apitoken). + +### Após a Publicação + +Os usuários podem instalar sua ferramenta com: + +```bash +pip install crewai-geolocate +``` + +Ou com uv: + +```bash +uv add crewai-geolocate +``` + +E então usá-la em suas crews: + +```python +from crewai_geolocate import GeolocateTool + +agent = Agent( + role="Analista de Localização", + tools=[GeolocateTool()], + # ... +) +``` diff --git a/docs/v1.15.1/pt-BR/index.mdx b/docs/v1.15.1/pt-BR/index.mdx new file mode 100644 index 000000000..2996f415a --- /dev/null +++ b/docs/v1.15.1/pt-BR/index.mdx @@ -0,0 +1,102 @@ +--- +title: "CrewAI Documentação" +description: "Construa agentes colaborativos, crews e flows — prontos para produção desde o primeiro dia." +icon: "house" +mode: "wide" +--- + +
+ CrewAI +
+

Construa sistemas multiagentes com confiança

+

+ Crie agentes, orquestre crews e automatize flows com guardrails, memória, conhecimento e observabilidade integrados. +

+
+ + +
+ +
+ + + + Visão geral dos conceitos da CrewAI, arquitetura e casos de uso para agentes, crews e flows. + + + Instale com `uv`, configure chaves de API e prepare o CLI para desenvolvimento local. + + + Crie sua primeira crew em poucos minutos. Aprenda o runtime, a estrutura do projeto e o loop de desenvolvimento. + + + +## Fundamentos + + + + Modele agentes com ferramentas, memória, conhecimento e saídas estruturadas. Inclui templates e boas práticas. + + + Orquestre start/listen/router, gerencie estado, persista execuções e retome processos longos. + + + Defina processos sequenciais, hierárquicos ou híbridos com guardrails, callbacks e intervenção humana. + + + +## Jornada Enterprise + + + + Gerencie ambientes, faça deploy seguro e monitore execuções ao vivo diretamente no console Enterprise. + + + Conecte Gmail, Slack, Salesforce e muito mais. Injete payloads dos triggers em crews e flows automaticamente. + + + Convide integrantes, configure RBAC e controle o acesso às automations em produção. + + + +## Novidades + + + + Guia unificado para Gmail, Drive, Outlook, Teams, OneDrive, HubSpot e outros — com payloads e crews de exemplo. + + + Chame automations CrewAI existentes ou agentes do Amazon Bedrock diretamente das suas crews. + + + + + Acesse os examples e cookbooks para implementações completas envolvendo agentes, flows e automations Enterprise. + + +## Conecte-se + + + + Se a CrewAI acelera seu trabalho, deixe uma estrela e compartilhe seus projetos com a comunidade. + + + Tire dúvidas, divulgue workflows e solicite recursos junto a outros builders. + + diff --git a/docs/v1.15.1/pt-BR/installation.mdx b/docs/v1.15.1/pt-BR/installation.mdx new file mode 100644 index 000000000..3ee8bb1b7 --- /dev/null +++ b/docs/v1.15.1/pt-BR/installation.mdx @@ -0,0 +1,216 @@ +--- +title: Instalação +description: Comece a usar o CrewAI - Instale, configure e crie seu primeiro crew de IA +icon: wrench +mode: "wide" +--- + +### Assista: Construindo Agents e Flows CrewAI com Coding Agent Skills + +Instale nossas coding agent skills (Claude Code, Codex, ...) para colocar seus agentes de código para funcionar rapidamente com o CrewAI. + +Você pode instalar com `npx skills add crewaiinc/skills` + + + +## 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 + +`crewai create crew` agora cria um projeto de crew JSON-first. Os agentes ficam em `agents/*.jsonc`, as tarefas e configurações da crew ficam em `crew.jsonc`, e `crewai run` carrega essa definição JSON diretamente. + + + + - Execute o comando CLI do `crewai`: + ```shell + crewai create crew + ``` + + - Isso criará um novo projeto com a seguinte estrutura: + + ``` + my_project/ + ├── .gitignore + ├── .env + ├── agents/ + │ └── researcher.jsonc + ├── crew.jsonc + ├── knowledge/ + ├── pyproject.toml + ├── README.md + ├── skills/ + └── tools/ + ``` + + + - Se você precisar do scaffold antigo em Python/YAML com `crew.py`, `config/agents.yaml` e `config/tasks.yaml`, execute: + ```shell + crewai create crew --classic + ``` + + + + + - Seu projeto conterá estes arquivos essenciais: + | Arquivo | Finalidade | + | --- | --- | + | `crew.jsonc` | Configure a crew, a ordem das tarefas, o processo e os inputs padrão | + | `agents/*.jsonc` | Defina o papel, objetivo, backstory, LLM, ferramentas e comportamento de cada agente | + | `.env` | Armazene chaves de API e variáveis de ambiente | + | `tools/` | Arquivos Python opcionais para ferramentas `custom:` | + | `knowledge/` | Arquivos opcionais de conhecimento para agentes | + | `skills/` | Arquivos opcionais de skills aplicadas à crew | + + - Comece editando `crew.jsonc` e os arquivos em `agents/` para definir o comportamento da crew. + - Use valores `{placeholder}` nos textos de agentes e tarefas e defina padrões em `crew.jsonc` dentro de `inputs`. Ao executar `crewai run`, a CLI pergunta por valores que estiverem faltando. + - 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 AMP (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 o guia rápido para gerar um Flow, executar um crew com um agente e produzir um relatório. + + + Conecte-se com outros desenvolvedores, obtenha ajuda e compartilhe suas + experiências com o CrewAI. + + diff --git a/docs/v1.15.1/pt-BR/introduction.mdx b/docs/v1.15.1/pt-BR/introduction.mdx new file mode 100644 index 000000000..788e2b123 --- /dev/null +++ b/docs/v1.15.1/pt-BR/introduction.mdx @@ -0,0 +1,152 @@ +--- +title: Introdução +description: Construa equipes de agentes de IA que trabalham juntas para resolver tarefas complexas +icon: handshake +mode: "wide" +--- + +# O que é CrewAI? + +**CrewAI é o principal framework open-source para orquestrar agentes de IA autônomos e construir fluxos de trabalho complexos.** + +Ele capacita desenvolvedores a construir sistemas multi-agente prontos para produção, combinando a inteligência colaborativa dos **Crews** com o controle preciso dos **Flows**. + +- **[Flows do CrewAI](/pt-BR/guides/flows/first-flow)**: A espinha dorsal da sua aplicação de IA. Flows permitem criar fluxos de trabalho estruturados e orientados a eventos que gerenciam estado e controlam a execução. Eles fornecem a estrutura para seus agentes de IA trabalharem. +- **[Crews do CrewAI](/pt-BR/guides/crews/first-crew)**: As unidades de trabalho dentro do seu Flow. Crews são equipes de agentes autônomos que colaboram para resolver tarefas específicas delegadas a eles pelo Flow. + +Com mais de 100.000 desenvolvedores certificados em nossos cursos comunitários, o CrewAI é o padrão para automação de IA pronta para empresas. + +### Assista: Construindo Agents e Flows CrewAI com Coding Agent Skills + +Instale nossas coding agent skills (Claude Code, Codex, ...) para colocar seus agentes de código para funcionar rapidamente com o CrewAI. + +Você pode instalar com `npx skills add crewaiinc/skills` + + + +## A Arquitetura do CrewAI + +A arquitetura do CrewAI foi projetada para equilibrar autonomia com controle. + +### 1. Flows: A Espinha Dorsal + + + Pense em um Flow como o "gerente" ou a "definição do processo" da sua aplicação. Ele define as etapas, a lógica e como os dados se movem através do seu sistema. + + + + Visão Geral do Framework CrewAI + + +Flows fornecem: +- **Gerenciamento de Estado**: Persistem dados através de etapas e execuções. +- **Execução Orientada a Eventos**: Acionam ações com base em eventos ou entradas externas. +- **Controle de Fluxo**: Usam lógica condicional, loops e ramificações. + +### 2. Crews: A Inteligência + + + Crews são as "equipes" que fazem o trabalho pesado. Dentro de um Flow, você pode acionar um Crew para lidar com um problema complexo que requer criatividade e colaboração. + + + + Visão Geral do Framework CrewAI + + +Crews fornecem: +- **Agentes com Funções**: Agentes especializados com objetivos e ferramentas específicas. +- **Colaboração Autônoma**: Agentes trabalham juntos para resolver tarefas. +- **Delegação de Tarefas**: Tarefas são atribuídas e executadas com base nas capacidades dos agentes. + +## Como Tudo Funciona Junto + +1. **O Flow** aciona um evento ou inicia um processo. +2. **O Flow** gerencia o estado e decide o que fazer a seguir. +3. **O Flow** delega uma tarefa complexa para um **Crew**. +4. Os agentes do **Crew** colaboram para completar a tarefa. +5. **O Crew** retorna o resultado para o **Flow**. +6. **O Flow** continua a execução com base no resultado. + +## Principais Funcionalidades + + + + Construa fluxos de trabalho confiáveis e com estado que podem lidar com processos de longa duração e lógica complexa. + + + Implante equipes de agentes que podem planejar, executar e colaborar para alcançar objetivos de alto nível. + + + Conecte seus agentes a qualquer API, banco de dados ou ferramenta local. + + + Projetado com segurança e conformidade em mente para implantações empresariais. + + + +## Quando usar Crews vs. Flows + +**A resposta curta: Use ambos.** + +Para qualquer aplicação pronta para produção, **comece com um Flow**. + +- **Use um Flow** para definir a estrutura geral, estado e lógica da sua aplicação. +- **Use um Crew** dentro de uma etapa do Flow quando precisar de uma equipe de agentes para realizar uma tarefa específica e complexa que requer autonomia. + +| Caso de Uso | Arquitetura | +| :--- | :--- | +| **Automação Simples** | Flow único com tarefas Python | +| **Pesquisa Complexa** | Flow gerenciando estado -> Crew realizando pesquisa | +| **Backend de Aplicação** | Flow lidando com requisições API -> Crew gerando conteúdo -> Flow salvando no BD | + +## 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? + + + + Aprenda a criar fluxos de trabalho estruturados e orientados por eventos com controle preciso de execução. + + + Tutorial passo a passo para criar uma equipe de IA colaborativa que trabalha junto para resolver problemas complexos. + + + + + + Comece a usar o CrewAI em seu ambiente de desenvolvimento. + + + Gere um Flow, execute um crew com um agente e produza um relatório ponta a ponta. + + + Conecte-se com outros desenvolvedores, obtenha ajuda e compartilhe suas experiências com o CrewAI. + + diff --git a/docs/v1.15.1/pt-BR/learn/before-and-after-kickoff-hooks.mdx b/docs/v1.15.1/pt-BR/learn/before-and-after-kickoff-hooks.mdx new file mode 100644 index 000000000..0855b2abb --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/before-and-after-kickoff-hooks.mdx @@ -0,0 +1,61 @@ +--- +title: Hooks Antes e Depois do Kickoff +description: Aprenda a usar hooks antes e depois do kickoff em CrewAI +mode: "wide" +--- + +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 MinhaEquipe: + @before_kickoff + def preparar_dados(self, entradas): + # Pré-processa ou modifica as entradas + entradas['processado'] = True + return entradas + +#... +``` + +Neste exemplo, a função preparar_dados 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 MinhaEquipe: + @after_kickoff + def registrar_resultados(self, resultado): + # Registra ou modifica os resultados + print("Execução da equipe concluída com resultado:", resultado) + return resultado + +# ... +``` + +Na função `registrar_resultados`, 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/v1.15.1/pt-BR/learn/bring-your-own-agent.mdx b/docs/v1.15.1/pt-BR/learn/bring-your-own-agent.mdx new file mode 100644 index 000000000..2a5d7c551 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/bring-your-own-agent.mdx @@ -0,0 +1,442 @@ +--- +title: Traga seu próprio agente +description: Aprenda como trazer seus próprios agentes que funcionam dentro de uma Crew. +icon: robots +mode: "wide" +--- + +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/v1.15.1/pt-BR/learn/coding-agents.mdx b/docs/v1.15.1/pt-BR/learn/coding-agents.mdx new file mode 100644 index 000000000..71d82da90 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/coding-agents.mdx @@ -0,0 +1,96 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/conditional-tasks.mdx b/docs/v1.15.1/pt-BR/learn/conditional-tasks.mdx new file mode 100644 index 000000000..d2f1113db --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/conditional-tasks.mdx @@ -0,0 +1,90 @@ +--- +title: Tarefas Condicionais +description: Saiba como usar tarefas condicionais em um kickoff do crewAI +icon: diagram-subtask +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/create-custom-tools.mdx b/docs/v1.15.1/pt-BR/learn/create-custom-tools.mdx new file mode 100644 index 000000000..4a09f396d --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/create-custom-tools.mdx @@ -0,0 +1,124 @@ +--- +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 +mode: "wide" +--- + +## 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. + + + **Quer publicar sua ferramenta para a comunidade?** Se você está construindo uma ferramenta que pode beneficiar outros, confira o guia [Publicar Ferramentas Personalizadas](/pt-BR/guides/tools/publish-custom-tools) para aprender como empacotar e distribuir sua ferramenta no PyPI. + + +### 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 +``` + +### Criando Ferramentas Assíncronas + +O CrewAI suporta ferramentas assíncronas para operações de I/O não bloqueantes. Isso é útil quando sua ferramenta precisa fazer requisições HTTP, consultas a banco de dados ou outras operações de I/O. + +#### Usando o Decorador `@tool` com Funções Assíncronas + +A maneira mais simples de criar uma ferramenta assíncrona é usando o decorador `@tool` com uma função async: + +```python Code +import aiohttp +from crewai.tools import tool + +@tool("Async Web Fetcher") +async def fetch_webpage(url: str) -> str: + """Fetch content from a webpage asynchronously.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +#### Subclassificando `BaseTool` com Suporte Assíncrono + +Para maior controle, herde de `BaseTool` e implemente os métodos `_run` (síncrono) e `_arun` (assíncrono): + +```python Code +import requests +import aiohttp +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class WebFetcherInput(BaseModel): + """Input schema for WebFetcher.""" + url: str = Field(..., description="The URL to fetch") + +class WebFetcherTool(BaseTool): + name: str = "Web Fetcher" + description: str = "Fetches content from a URL" + args_schema: type[BaseModel] = WebFetcherInput + + def _run(self, url: str) -> str: + """Synchronous implementation.""" + return requests.get(url).text + + async def _arun(self, url: str) -> str: + """Asynchronous implementation for non-blocking I/O.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` + +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. diff --git a/docs/v1.15.1/pt-BR/learn/custom-llm.mdx b/docs/v1.15.1/pt-BR/learn/custom-llm.mdx new file mode 100644 index 000000000..32c6a6689 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/custom-llm.mdx @@ -0,0 +1,123 @@ +--- +title: Implementação de LLM Personalizada +description: Aprenda a criar implementações personalizadas de LLM no CrewAI. +icon: code +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/custom-manager-agent.mdx b/docs/v1.15.1/pt-BR/learn/custom-manager-agent.mdx new file mode 100644 index 000000000..9acefbd05 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/custom-manager-agent.mdx @@ -0,0 +1,91 @@ +--- +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 +mode: "wide" +--- + +# 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/v1.15.1/pt-BR/learn/customizing-agents.mdx b/docs/v1.15.1/pt-BR/learn/customizing-agents.mdx new file mode 100644 index 000000000..d3df49abc --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/customizing-agents.mdx @@ -0,0 +1,107 @@ +--- +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 +mode: "wide" +--- + +## 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='Analista de Pesquisa', + goal='Fornecer análises de mercado atualizadas', + backstory='Um analista especialista com olhar atento para tendências de mercado.', + 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='Redator de Conteúdo', + goal='Escrever conteúdo envolvente sobre tendências de mercado', + backstory='Um redator experiente com expertise em análise de mercado.', + allow_delegation=True # Habilitando delegação +) +``` \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/learn/dalle-image-generation.mdx b/docs/v1.15.1/pt-BR/learn/dalle-image-generation.mdx new file mode 100644 index 000000000..51b003d72 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/dalle-image-generation.mdx @@ -0,0 +1,74 @@ +--- +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" +mode: "wide" +--- + +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/v1.15.1/pt-BR/learn/execution-hooks.mdx b/docs/v1.15.1/pt-BR/learn/execution-hooks.mdx new file mode 100644 index 000000000..0e70edfbd --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/execution-hooks.mdx @@ -0,0 +1,379 @@ +--- +title: Visão Geral dos Hooks de Execução +description: Entendendo e usando hooks de execução no CrewAI para controle fino sobre operações de agentes +mode: "wide" +--- + +Os Hooks de Execução fornecem controle fino sobre o comportamento em tempo de execução dos seus agentes CrewAI. Diferentemente dos hooks de kickoff que são executados antes e depois da execução da crew, os hooks de execução interceptam operações específicas durante a execução do agente, permitindo que você modifique comportamentos, implemente verificações de segurança e adicione monitoramento abrangente. + +## Tipos de Hooks de Execução + +O CrewAI fornece duas categorias principais de hooks de execução: + +### 1. [Hooks de Chamada LLM](/learn/llm-hooks) + +Controle e monitore interações com o modelo de linguagem: +- **Antes da Chamada LLM**: Modifique prompts, valide entradas, implemente gates de aprovação +- **Depois da Chamada LLM**: Transforme respostas, sanitize saídas, atualize histórico de conversação + +**Casos de Uso:** +- Limitação de iterações +- Rastreamento de custos e monitoramento de uso de tokens +- Sanitização de respostas e filtragem de conteúdo +- Aprovação humana para chamadas LLM +- Adição de diretrizes de segurança ou contexto +- Logging de debug e inspeção de requisição/resposta + +[Ver Documentação de Hooks LLM →](/learn/llm-hooks) + +### 2. [Hooks de Chamada de Ferramenta](/learn/tool-hooks) + +Controle e monitore execução de ferramentas: +- **Antes da Chamada de Ferramenta**: Modifique entradas, valide parâmetros, bloqueie operações perigosas +- **Depois da Chamada de Ferramenta**: Transforme resultados, sanitize saídas, registre detalhes de execução + +**Casos de Uso:** +- Guardrails de segurança para operações destrutivas +- Aprovação humana para ações sensíveis +- Validação e sanitização de entrada +- Cache de resultados e limitação de taxa +- Análise de uso de ferramentas +- Logging de debug e monitoramento + +[Ver Documentação de Hooks de Ferramenta →](/learn/tool-hooks) + +## Métodos de Registro + +### 1. Hooks Baseados em Decoradores (Recomendado) + +A maneira mais limpa e pythônica de registrar hooks: + +```python +from crewai.hooks import before_llm_call, after_llm_call, before_tool_call, after_tool_call + +@before_llm_call +def limit_iterations(context): + """Previne loops infinitos limitando iterações.""" + if context.iterations > 10: + return False # Bloquear execução + return None + +@after_llm_call +def sanitize_response(context): + """Remove dados sensíveis das respostas do LLM.""" + if "API_KEY" in context.response: + return context.response.replace("API_KEY", "[CENSURADO]") + return None + +@before_tool_call +def block_dangerous_tools(context): + """Bloqueia operações destrutivas.""" + if context.tool_name == "delete_database": + return False # Bloquear execução + return None + +@after_tool_call +def log_tool_result(context): + """Registra execução de ferramenta.""" + print(f"Ferramenta {context.tool_name} concluída") + return None +``` + +### 2. Hooks com Escopo de Crew + +Aplica hooks apenas a instâncias específicas de crew: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # Aplica-se apenas a esta crew + print(f"Chamada LLM em {self.__class__.__name__}") + return None + + @after_tool_call_crew + def log_results(self, context): + # Logging específico da crew + print(f"Resultado da ferramenta: {context.tool_result[:50]}...") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential + ) +``` + +## Fluxo de Execução de Hooks + +### Fluxo de Chamada LLM + +``` +Agente precisa chamar LLM + ↓ +[Hooks Antes da Chamada LLM Executam] + ├→ Hook 1: Validar contagem de iterações + ├→ Hook 2: Adicionar contexto de segurança + └→ Hook 3: Registrar requisição + ↓ +Se algum hook retornar False: + ├→ Bloquear chamada LLM + └→ Lançar ValueError + ↓ +Se todos os hooks retornarem True/None: + ├→ Chamada LLM prossegue + └→ Resposta gerada + ↓ +[Hooks Depois da Chamada LLM Executam] + ├→ Hook 1: Sanitizar resposta + ├→ Hook 2: Registrar resposta + └→ Hook 3: Atualizar métricas + ↓ +Resposta final retornada +``` + +### Fluxo de Chamada de Ferramenta + +``` +Agente precisa executar ferramenta + ↓ +[Hooks Antes da Chamada de Ferramenta Executam] + ├→ Hook 1: Verificar se ferramenta é permitida + ├→ Hook 2: Validar entradas + └→ Hook 3: Solicitar aprovação se necessário + ↓ +Se algum hook retornar False: + ├→ Bloquear execução da ferramenta + └→ Retornar mensagem de erro + ↓ +Se todos os hooks retornarem True/None: + ├→ Execução da ferramenta prossegue + └→ Resultado gerado + ↓ +[Hooks Depois da Chamada de Ferramenta Executam] + ├→ Hook 1: Sanitizar resultado + ├→ Hook 2: Fazer cache do resultado + └→ Hook 3: Registrar métricas + ↓ +Resultado final retornado +``` + +## Objetos de Contexto de Hook + +### LLMCallHookContext + +Fornece acesso ao estado de execução do LLM: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # Acesso completo ao executor + messages: list # Lista de mensagens mutável + agent: Agent # Agente atual + task: Task # Tarefa atual + crew: Crew # Instância da crew + llm: BaseLLM # Instância do LLM + iterations: int # Iteração atual + response: str | None # Resposta do LLM (hooks posteriores) +``` + +### ToolCallHookContext + +Fornece acesso ao estado de execução da ferramenta: + +```python +class ToolCallHookContext: + tool_name: str # Ferramenta sendo chamada + tool_input: dict # Parâmetros de entrada mutáveis + tool: CrewStructuredTool # Instância da ferramenta + agent: Agent | None # Agente executando + task: Task | None # Tarefa atual + crew: Crew | None # Instância da crew + tool_result: str | None # Resultado da ferramenta (hooks posteriores) +``` + +## Padrões Comuns + +### Segurança e Validação + +```python +@before_tool_call +def safety_check(context): + """Bloqueia operações destrutivas.""" + dangerous = ['delete_file', 'drop_table', 'system_shutdown'] + if context.tool_name in dangerous: + print(f"🛑 Bloqueado: {context.tool_name}") + return False + return None + +@before_llm_call +def iteration_limit(context): + """Previne loops infinitos.""" + if context.iterations > 15: + print("⛔ Máximo de iterações excedido") + return False + return None +``` + +### Humano no Loop + +```python +@before_tool_call +def require_approval(context): + """Requer aprovação para operações sensíveis.""" + sensitive = ['send_email', 'make_payment', 'post_message'] + + if context.tool_name in sensitive: + response = context.request_human_input( + prompt=f"Aprovar {context.tool_name}?", + default_message="Digite 'sim' para aprovar:" + ) + + if response.lower() != 'sim': + return False + + return None +``` + +### Monitoramento e Análise + +```python +from collections import defaultdict +import time + +metrics = defaultdict(lambda: {'count': 0, 'total_time': 0}) + +@before_tool_call +def start_timer(context): + context.tool_input['_start'] = time.time() + return None + +@after_tool_call +def track_metrics(context): + start = context.tool_input.get('_start', time.time()) + duration = time.time() - start + + metrics[context.tool_name]['count'] += 1 + metrics[context.tool_name]['total_time'] += duration + + return None +``` + +## Gerenciamento de Hooks + +### Limpar Todos os Hooks + +```python +from crewai.hooks import clear_all_global_hooks + +# Limpa todos os hooks de uma vez +result = clear_all_global_hooks() +print(f"Limpou {result['total']} hooks") +``` + +### Limpar Tipos Específicos de Hooks + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_before_tool_call_hooks, + clear_after_tool_call_hooks +) + +# Limpar tipos específicos +llm_before_count = clear_before_llm_call_hooks() +tool_after_count = clear_after_tool_call_hooks() +``` + +## Melhores Práticas + +### 1. Mantenha os Hooks Focados +Cada hook deve ter uma responsabilidade única e clara. + +### 2. Trate Erros Graciosamente +```python +@before_llm_call +def safe_hook(context): + try: + if some_condition: + return False + except Exception as e: + print(f"Erro no hook: {e}") + return None # Permitir execução apesar do erro +``` + +### 3. Modifique o Contexto In-Place +```python +# ✅ Correto - modificar in-place +@before_llm_call +def add_context(context): + context.messages.append({"role": "system", "content": "Seja conciso"}) + +# ❌ Errado - substitui referência +@before_llm_call +def wrong_approach(context): + context.messages = [{"role": "system", "content": "Seja conciso"}] +``` + +### 4. Use Type Hints +```python +from crewai.hooks import LLMCallHookContext, ToolCallHookContext + +def my_llm_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_tool_hook(context: ToolCallHookContext) -> str | None: + return None +``` + +### 5. Limpe em Testes +```python +import pytest +from crewai.hooks import clear_all_global_hooks + +@pytest.fixture(autouse=True) +def clean_hooks(): + """Reseta hooks antes de cada teste.""" + yield + clear_all_global_hooks() +``` + +## Quando Usar Qual Hook + +### Use Hooks LLM Quando: +- Implementar limites de iteração +- Adicionar contexto ou diretrizes de segurança aos prompts +- Rastrear uso de tokens e custos +- Sanitizar ou transformar respostas +- Implementar gates de aprovação para chamadas LLM +- Fazer debug de interações de prompt/resposta + +### Use Hooks de Ferramenta Quando: +- Bloquear operações perigosas ou destrutivas +- Validar entradas de ferramenta antes da execução +- Implementar gates de aprovação para ações sensíveis +- Fazer cache de resultados de ferramenta +- Rastrear uso e performance de ferramentas +- Sanitizar saídas de ferramenta +- Limitar taxa de chamadas de ferramenta + +### Use Ambos Quando: +Construir sistemas abrangentes de observabilidade, segurança ou aprovação que precisam monitorar todas as operações do agente. + +## Documentação Relacionada + +- [Hooks de Chamada LLM →](/learn/llm-hooks) - Documentação detalhada de hooks LLM +- [Hooks de Chamada de Ferramenta →](/learn/tool-hooks) - Documentação detalhada de hooks de ferramenta +- [Hooks Antes e Depois do Kickoff →](/learn/before-and-after-kickoff-hooks) - Hooks do ciclo de vida da crew +- [Humano no Loop →](/learn/human-in-the-loop) - Padrões de entrada humana + +## Conclusão + +Os Hooks de Execução fornecem controle poderoso sobre o comportamento em tempo de execução do agente. Use-os para implementar guardrails de segurança, fluxos de trabalho de aprovação, monitoramento abrangente e lógica de negócio personalizada. Combinados com tratamento adequado de erros, segurança de tipos e considerações de performance, os hooks permitem sistemas de agentes seguros, prontos para produção e observáveis. diff --git a/docs/v1.15.1/pt-BR/learn/force-tool-output-as-result.mdx b/docs/v1.15.1/pt-BR/learn/force-tool-output-as-result.mdx new file mode 100644 index 000000000..c053c3448 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/force-tool-output-as-result.mdx @@ -0,0 +1,51 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/hierarchical-process.mdx b/docs/v1.15.1/pt-BR/learn/hierarchical-process.mdx new file mode 100644 index 000000000..d7985f5d2 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/hierarchical-process.mdx @@ -0,0 +1,112 @@ +--- +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 +mode: "wide" +--- + +## 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](/pt-BR/learn/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/v1.15.1/pt-BR/learn/human-feedback-in-flows.mdx b/docs/v1.15.1/pt-BR/learn/human-feedback-in-flows.mdx new file mode 100644 index 000000000..ad4d068cd --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/human-feedback-in-flows.mdx @@ -0,0 +1,697 @@ +--- +title: Feedback Humano em Flows +description: Aprenda como integrar feedback humano diretamente nos seus CrewAI Flows usando o decorador @human_feedback +icon: user-check +mode: "wide" +--- + +## Visão Geral + + +O decorador `@human_feedback` requer **CrewAI versão 1.8.0 ou superior**. Certifique-se de atualizar sua instalação antes de usar este recurso. + + +O decorador `@human_feedback` permite fluxos de trabalho human-in-the-loop (HITL) diretamente nos CrewAI Flows. Ele permite pausar a execução do flow, apresentar a saída para um humano revisar, coletar seu feedback e, opcionalmente, rotear para diferentes listeners com base no resultado do feedback. + +Isso é particularmente valioso para: + +- **Garantia de qualidade**: Revisar conteúdo gerado por IA antes de ser usado downstream +- **Portões de decisão**: Deixar humanos tomarem decisões críticas em fluxos automatizados +- **Fluxos de aprovação**: Implementar padrões de aprovar/rejeitar/revisar +- **Refinamento interativo**: Coletar feedback para melhorar saídas iterativamente + +```mermaid +flowchart LR + A[Método do Flow] --> B[Saída Gerada] + B --> C[Humano Revisa] + C --> D{Feedback} + D -->|emit especificado| E[LLM Mapeia para Outcome] + D -->|sem emit| F[HumanFeedbackResult] + E --> G["@listen('approved')"] + E --> H["@listen('rejected')"] + F --> I[Próximo Listener] +``` + +## Início Rápido + +Aqui está a maneira mais simples de adicionar feedback humano a um flow: + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback + +class SimpleReviewFlow(Flow): + @start() + @human_feedback(message="Por favor, revise este conteúdo:") + def generate_content(self): + return "Este é um conteúdo gerado por IA que precisa de revisão." + + @listen(generate_content) + def process_feedback(self, result): + print(f"Conteúdo: {result.output}") + print(f"Humano disse: {result.feedback}") + +flow = SimpleReviewFlow() +flow.kickoff() +``` + +Quando este flow é executado, ele irá: +1. Executar `generate_content` e retornar a string +2. Exibir a saída para o usuário com a mensagem de solicitação +3. Aguardar o usuário digitar o feedback (ou pressionar Enter para pular) +4. Passar um objeto `HumanFeedbackResult` para `process_feedback` + +## O Decorador @human_feedback + +### Parâmetros + +| Parâmetro | Tipo | Obrigatório | Descrição | +|-----------|------|-------------|-----------| +| `message` | `str` | Sim | A mensagem mostrada ao humano junto com a saída do método | +| `emit` | `Sequence[str]` | Não | Lista de possíveis outcomes. O feedback é mapeado para um destes, que dispara decoradores `@listen` | +| `llm` | `str \| BaseLLM` | Quando `emit` especificado | LLM usado para interpretar o feedback e mapear para um outcome | +| `default_outcome` | `str` | Não | Outcome a usar se nenhum feedback for fornecido. Deve estar em `emit` | +| `metadata` | `dict` | Não | Dados adicionais para integrações enterprise | +| `provider` | `HumanFeedbackProvider` | Não | Provider customizado para feedback assíncrono/não-bloqueante. Veja [Feedback Humano Assíncrono](#feedback-humano-assíncrono-não-bloqueante) | +| `learn` | `bool` | Não | Habilitar aprendizado HITL: destila lições do feedback e pré-revisa saídas futuras. Padrão `False`. Veja [Aprendendo com Feedback](#aprendendo-com-feedback) | +| `learn_limit` | `int` | Não | Máximo de lições passadas para recuperar na pré-revisão. Padrão `5` | + +### Uso Básico (Sem Roteamento) + +Quando você não especifica `emit`, o decorador simplesmente coleta o feedback e passa um `HumanFeedbackResult` para o próximo listener: + +```python Code +@start() +@human_feedback(message="O que você acha desta análise?") +def analyze_data(self): + return "Resultados da análise: Receita aumentou 15%, custos diminuíram 8%" + +@listen(analyze_data) +def handle_feedback(self, result): + # result é um HumanFeedbackResult + print(f"Análise: {result.output}") + print(f"Feedback: {result.feedback}") +``` + +### Roteamento com emit + +Quando você especifica `emit`, o decorador se torna um roteador. O feedback livre do humano é interpretado por um LLM e mapeado para um dos outcomes especificados: + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback + +class ReviewFlow(Flow): + @start() + def generate_content(self): + return "Rascunho do post do blog aqui..." + + @human_feedback( + message="Você aprova este conteúdo para publicação?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Rascunho do post do blog aqui..." + + @listen("approved") + def publish(self, result): + print(f"Publicando! Usuário disse: {result.feedback}") + + @listen("rejected") + def discard(self, result): + print(f"Descartando. Motivo: {result.feedback}") +``` + +Quando o humano diz algo como "precisa de mais detalhes", o LLM mapeia para `"needs_revision"`, que dispara `review_content` novamente via `or_()` — criando um loop de revisão. O loop continua até que o outcome seja `"approved"` ou `"rejected"`. + + +O LLM usa saídas estruturadas (function calling) quando disponível para garantir que a resposta seja um dos seus outcomes especificados. Isso torna o roteamento confiável e previsível. + + + +Um método `@start()` só executa uma vez no início do flow. Se você precisa de um loop de revisão, separe o método start do método de revisão e use `@listen(or_("trigger", "revision_outcome"))` no método de revisão para habilitar o self-loop. + + +## HumanFeedbackResult + +O dataclass `HumanFeedbackResult` contém todas as informações sobre uma interação de feedback humano: + +```python Code +from crewai.flow.human_feedback import HumanFeedbackResult + +@dataclass +class HumanFeedbackResult: + output: Any # A saída original do método mostrada ao humano + feedback: str # O texto bruto do feedback do humano + outcome: str | None # O outcome mapeado (se emit foi especificado) + timestamp: datetime # Quando o feedback foi recebido + method_name: str # Nome do método decorado + metadata: dict # Qualquer metadata passado ao decorador +``` + +### Acessando em Listeners + +Quando um listener é disparado por um método `@human_feedback` com `emit`, ele recebe o `HumanFeedbackResult`: + +```python Code +@listen("approved") +def on_approval(self, result: HumanFeedbackResult): + print(f"Saída original: {result.output}") + print(f"Feedback do usuário: {result.feedback}") + print(f"Outcome: {result.outcome}") # "approved" + print(f"Recebido em: {result.timestamp}") +``` + +## Acessando o Histórico de Feedback + +A classe `Flow` fornece dois atributos para acessar o feedback humano: + +### last_human_feedback + +Retorna o `HumanFeedbackResult` mais recente: + +```python Code +@listen(some_method) +def check_feedback(self): + if self.last_human_feedback: + print(f"Último feedback: {self.last_human_feedback.feedback}") +``` + +### human_feedback_history + +Uma lista de todos os objetos `HumanFeedbackResult` coletados durante o flow: + +```python Code +@listen(final_step) +def summarize(self): + print(f"Total de feedbacks coletados: {len(self.human_feedback_history)}") + for i, fb in enumerate(self.human_feedback_history): + print(f"{i+1}. {fb.method_name}: {fb.outcome or 'sem roteamento'}") +``` + + +Cada `HumanFeedbackResult` é adicionado a `human_feedback_history`, então múltiplos passos de feedback não sobrescrevem uns aos outros. Use esta lista para acessar todo o feedback coletado durante o flow. + + +## Exemplo Completo: Fluxo de Aprovação de Conteúdo + +Aqui está um exemplo completo implementando um fluxo de revisão e aprovação de conteúdo: + + + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult +from pydantic import BaseModel + + +class ContentState(BaseModel): + draft: str = "" + revision_count: int = 0 + status: str = "pending" + + +class ContentApprovalFlow(Flow[ContentState]): + """Um flow que gera conteúdo e faz loop até o humano aprovar.""" + + @start() + def generate_draft(self): + self.state.draft = "# IA Segura\n\nEste é um rascunho sobre IA Segura..." + return self.state.draft + + @human_feedback( + message="Por favor, revise este rascunho. Aprove, rejeite ou descreva o que precisa mudar:", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_draft", "needs_revision")) + def review_draft(self): + self.state.revision_count += 1 + return f"{self.state.draft} (v{self.state.revision_count})" + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + self.state.status = "published" + print(f"Conteúdo aprovado e publicado! Revisor disse: {result.feedback}") + return "published" + + @listen("rejected") + def handle_rejection(self, result: HumanFeedbackResult): + self.state.status = "rejected" + print(f"Conteúdo rejeitado. Motivo: {result.feedback}") + return "rejected" + + +flow = ContentApprovalFlow() +result = flow.kickoff() +print(f"\nFlow finalizado. Status: {flow.state.status}, Revisões: {flow.state.revision_count}") +``` + +```text Output +================================================== +OUTPUT FOR REVIEW: +================================================== +# IA Segura + +Este é um rascunho sobre IA Segura... (v1) +================================================== + +Por favor, revise este rascunho. Aprove, rejeite ou descreva o que precisa mudar: +(Press Enter to skip, or type your feedback) + +Your feedback: Preciso de mais detalhes sobre segurança em IA. + +================================================== +OUTPUT FOR REVIEW: +================================================== +# IA Segura + +Este é um rascunho sobre IA Segura... (v2) +================================================== + +Por favor, revise este rascunho. Aprove, rejeite ou descreva o que precisa mudar: +(Press Enter to skip, or type your feedback) + +Your feedback: Parece bom, aprovado! + +Conteúdo aprovado e publicado! Revisor disse: Parece bom, aprovado! + +Flow finalizado. Status: published, Revisões: 2 +``` + + + +## Combinando com Outros Decoradores + +O decorador `@human_feedback` funciona com `@start()`, `@listen()` e `or_()`. Ambas as ordens de decoradores funcionam — o framework propaga atributos em ambas as direções — mas os padrões recomendados são: + +```python Code +# Revisão única no início do flow (sem self-loop) +@start() +@human_feedback(message="Revise isto:", emit=["approved", "rejected"], llm="gpt-4o-mini") +def my_start_method(self): + return "content" + +# Revisão linear em um listener (sem self-loop) +@listen(other_method) +@human_feedback(message="Revise isto também:", emit=["good", "bad"], llm="gpt-4o-mini") +def my_listener(self, data): + return f"processed: {data}" + +# Self-loop: revisão que pode voltar para revisões +@human_feedback(message="Aprovar ou revisar?", emit=["approved", "revise"], llm="gpt-4o-mini") +@listen(or_("upstream_method", "revise")) +def review_with_loop(self): + return "content for review" +``` + +### Padrão de self-loop + +Para criar um loop de revisão, o método de revisão deve escutar **ambos** um gatilho upstream e seu próprio outcome de revisão usando `or_()`: + +```python Code +@start() +def generate(self): + return "initial draft" + +@human_feedback( + message="Aprovar ou solicitar alterações?", + emit=["revise", "approved"], + llm="gpt-4o-mini", + default_outcome="approved", +) +@listen(or_("generate", "revise")) +def review(self): + return "content" + +@listen("approved") +def publish(self): + return "published" +``` + +Quando o outcome é `"revise"`, o flow roteia de volta para `review` (porque ele escuta `"revise"` via `or_()`). Quando o outcome é `"approved"`, o flow continua para `publish`. Isso funciona porque o engine de flow isenta roteadores da regra "fire once", permitindo que eles re-executem em cada iteração do loop. + +### Roteadores encadeados + +Um listener disparado pelo outcome de um roteador pode ser ele mesmo um roteador: + +```python Code +@start() +@human_feedback(message="Primeira revisão:", emit=["approved", "rejected"], llm="gpt-4o-mini") +def draft(self): + return "draft content" + +@listen("approved") +@human_feedback(message="Revisão final:", emit=["publish", "revise"], llm="gpt-4o-mini") +def final_review(self, prev): + return "final content" + +@listen("publish") +def on_publish(self, prev): + return "published" +``` + +### Limitações + +- **Métodos `@start()` executam uma vez**: Um método `@start()` não pode fazer self-loop. Se você precisa de um ciclo de revisão, use um método `@start()` separado como ponto de entrada e coloque o `@human_feedback` em um método `@listen()`. +- **Sem `@start()` + `@listen()` no mesmo método**: Esta é uma restrição do framework de Flow. Um método é ou um ponto de início ou um listener, não ambos. + +## Melhores Práticas + +### 1. Escreva Mensagens de Solicitação Claras + +O parâmetro `message` é o que o humano vê. Torne-o acionável: + +```python Code +# ✅ Bom - claro e acionável +@human_feedback(message="Este resumo captura com precisão os pontos-chave? Responda 'sim' ou explique o que está faltando:") + +# ❌ Ruim - vago +@human_feedback(message="Revise isto:") +``` + +### 2. Escolha Outcomes Significativos + +Ao usar `emit`, escolha outcomes que mapeiem naturalmente para respostas humanas: + +```python Code +# ✅ Bom - outcomes em linguagem natural +emit=["approved", "rejected", "needs_more_detail"] + +# ❌ Ruim - técnico ou pouco claro +emit=["state_1", "state_2", "state_3"] +``` + +### 3. Sempre Forneça um Outcome Padrão + +Use `default_outcome` para lidar com casos onde usuários pressionam Enter sem digitar: + +```python Code +@human_feedback( + message="Aprovar? (pressione Enter para solicitar revisão)", + emit=["approved", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", # Padrão seguro +) +``` + +### 4. Use o Histórico de Feedback para Trilhas de Auditoria + +Acesse `human_feedback_history` para criar logs de auditoria: + +```python Code +@listen(final_step) +def create_audit_log(self): + log = [] + for fb in self.human_feedback_history: + log.append({ + "step": fb.method_name, + "outcome": fb.outcome, + "feedback": fb.feedback, + "timestamp": fb.timestamp.isoformat(), + }) + return log +``` + +### 5. Trate Feedback Roteado e Não Roteado + +Ao projetar flows, considere se você precisa de roteamento: + +| Cenário | Use | +|---------|-----| +| Revisão simples, só precisa do texto do feedback | Sem `emit` | +| Precisa ramificar para caminhos diferentes baseado na resposta | Use `emit` | +| Portões de aprovação com aprovar/rejeitar/revisar | Use `emit` | +| Coletando comentários apenas para logging | Sem `emit` | + +## Feedback Humano Assíncrono (Não-Bloqueante - Human in the loop) + +Por padrão, `@human_feedback` bloqueia a execução aguardando entrada no console. Para aplicações de produção, você pode precisar de feedback **assíncrono/não-bloqueante** que se integre com sistemas externos como Slack, email, webhooks ou APIs. + +### A Abstração de Provider + +Use o parâmetro `provider` para especificar uma estratégia customizada de coleta de feedback: + +```python Code +from crewai.flow import Flow, start, human_feedback, HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext + +class WebhookProvider(HumanFeedbackProvider): + """Provider que pausa o flow e aguarda callback de webhook.""" + + def __init__(self, webhook_url: str): + self.webhook_url = webhook_url + + def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str: + # Notifica sistema externo (ex: envia mensagem Slack, cria ticket) + self.send_notification(context) + + # Pausa execução - framework cuida da persistência automaticamente + raise HumanFeedbackPending( + context=context, + callback_info={"webhook_url": f"{self.webhook_url}/{context.flow_id}"} + ) + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="Revise este conteúdo:", + emit=["approved", "rejected"], + llm="gpt-4o-mini", + provider=WebhookProvider("https://myapp.com/api"), + ) + def generate_content(self): + return "Conteúdo gerado por IA..." + + @listen("approved") + def publish(self, result): + return "Publicado!" +``` + + +O framework de flow **persiste automaticamente o estado** quando `HumanFeedbackPending` é lançado. Seu provider só precisa notificar o sistema externo e lançar a exceção—não são necessárias chamadas manuais de persistência. + + +### Tratando Flows Pausados + +Ao usar um provider assíncrono, `kickoff()` retorna um objeto `HumanFeedbackPending` em vez de lançar uma exceção: + +```python Code +flow = ReviewFlow() +result = flow.kickoff() + +if isinstance(result, HumanFeedbackPending): + # Flow está pausado, estado é automaticamente persistido + print(f"Aguardando feedback em: {result.callback_info['webhook_url']}") + print(f"Flow ID: {result.context.flow_id}") +else: + # Conclusão normal + print(f"Flow concluído: {result}") +``` + +### Retomando um Flow Pausado + +Quando o feedback chega (ex: via webhook), retome o flow: + +```python Code +# Handler síncrono: +def handle_feedback_webhook(flow_id: str, feedback: str): + flow = ReviewFlow.from_pending(flow_id) + result = flow.resume(feedback) + return result + +# Handler assíncrono (FastAPI, aiohttp, etc.): +async def handle_feedback_webhook(flow_id: str, feedback: str): + flow = ReviewFlow.from_pending(flow_id) + result = await flow.resume_async(feedback) + return result +``` + +### Tipos Principais + +| Tipo | Descrição | +|------|-----------| +| `HumanFeedbackProvider` | Protocolo para providers de feedback customizados | +| `PendingFeedbackContext` | Contém todas as informações necessárias para retomar um flow pausado | +| `HumanFeedbackPending` | Retornado por `kickoff()` quando o flow está pausado para feedback | +| `ConsoleProvider` | Provider padrão de entrada bloqueante no console | + +### PendingFeedbackContext + +O contexto contém tudo necessário para retomar: + +```python Code +@dataclass +class PendingFeedbackContext: + flow_id: str # Identificador único desta execução de flow + flow_class: str # Nome qualificado completo da classe + method_name: str # Método que disparou o feedback + method_output: Any # Saída mostrada ao humano + message: str # A mensagem de solicitação + emit: list[str] | None # Outcomes possíveis para roteamento + default_outcome: str | None + metadata: dict # Metadata customizado + llm: str | None # LLM para mapeamento de outcome + requested_at: datetime +``` + +### Exemplo Completo de Flow Assíncrono + +```python Code +from crewai.flow import ( + Flow, start, listen, human_feedback, + HumanFeedbackProvider, HumanFeedbackPending, PendingFeedbackContext +) + +class SlackNotificationProvider(HumanFeedbackProvider): + """Provider que envia notificações Slack e pausa para feedback assíncrono.""" + + def __init__(self, channel: str): + self.channel = channel + + def request_feedback(self, context: PendingFeedbackContext, flow: Flow) -> str: + # Envia notificação Slack (implemente você mesmo) + slack_thread_id = self.post_to_slack( + channel=self.channel, + message=f"Revisão necessária:\n\n{context.method_output}\n\n{context.message}", + ) + + # Pausa execução - framework cuida da persistência automaticamente + raise HumanFeedbackPending( + context=context, + callback_info={ + "slack_channel": self.channel, + "thread_id": slack_thread_id, + } + ) + +class ContentPipeline(Flow): + @start() + @human_feedback( + message="Aprova este conteúdo para publicação?", + emit=["approved", "rejected"], + llm="gpt-4o-mini", + default_outcome="rejected", + provider=SlackNotificationProvider("#content-reviews"), + ) + def generate_content(self): + return "Conteúdo de blog post gerado por IA..." + + @listen("approved") + def publish(self, result): + print(f"Publicando! Revisor disse: {result.feedback}") + return {"status": "published"} + + @listen("rejected") + def archive(self, result): + print(f"Arquivado. Motivo: {result.feedback}") + return {"status": "archived"} + + +# Iniciando o flow (vai pausar e aguardar resposta do Slack) +def start_content_pipeline(): + flow = ContentPipeline() + result = flow.kickoff() + + if isinstance(result, HumanFeedbackPending): + return {"status": "pending", "flow_id": result.context.flow_id} + + return result + + +# Retomando quando webhook do Slack dispara (handler síncrono) +def on_slack_feedback(flow_id: str, slack_message: str): + flow = ContentPipeline.from_pending(flow_id) + result = flow.resume(slack_message) + return result + + +# Se seu handler é assíncrono (FastAPI, aiohttp, Slack Bolt async, etc.) +async def on_slack_feedback_async(flow_id: str, slack_message: str): + flow = ContentPipeline.from_pending(flow_id) + result = await flow.resume_async(slack_message) + return result +``` + + +Se você está usando um framework web assíncrono (FastAPI, aiohttp, Slack Bolt modo async), use `await flow.resume_async()` em vez de `flow.resume()`. Chamar `resume()` de dentro de um event loop em execução vai lançar um `RuntimeError`. + + +### Melhores Práticas para Feedback Assíncrono + +1. **Verifique o tipo de retorno**: `kickoff()` retorna `HumanFeedbackPending` quando pausado—não precisa de try/except +2. **Use o método resume correto**: Use `resume()` em código síncrono, `await resume_async()` em código assíncrono +3. **Armazene informações de callback**: Use `callback_info` para armazenar URLs de webhook, IDs de tickets, etc. +4. **Implemente idempotência**: Seu handler de resume deve ser idempotente por segurança +5. **Persistência automática**: O estado é automaticamente salvo quando `HumanFeedbackPending` é lançado e usa `SQLiteFlowPersistence` por padrão +6. **Persistência customizada**: Passe uma instância de persistência customizada para `from_pending()` se necessário + +## Aprendendo com Feedback + +O parâmetro `learn=True` habilita um ciclo de feedback entre revisores humanos e o sistema de memória. Quando habilitado, o sistema melhora progressivamente suas saídas aprendendo com correções humanas anteriores. + +### Como Funciona + +1. **Após o feedback**: O LLM extrai lições generalizáveis da saída + feedback e as armazena na memória com `source="hitl"`. Se o feedback for apenas aprovação (ex: "parece bom"), nada é armazenado. +2. **Antes da próxima revisão**: Lições HITL passadas são recuperadas da memória e aplicadas pelo LLM para melhorar a saída antes que o humano a veja. + +Com o tempo, o humano vê saídas pré-revisadas progressivamente melhores porque cada correção informa revisões futuras. + +### Exemplo + +```python Code +class ArticleReviewFlow(Flow): + @start() + def generate_article(self): + return self.crew.kickoff(inputs={"topic": "AI Safety"}).raw + + @human_feedback( + message="Revise este rascunho do artigo:", + emit=["approved", "needs_revision"], + llm="gpt-4o-mini", + learn=True, # enable HITL learning + ) + @listen(or_("generate_article", "needs_revision")) + def review_article(self): + return self.last_human_feedback.output if self.last_human_feedback else "article draft" + + @listen("approved") + def publish(self): + print(f"Publishing: {self.last_human_feedback.output}") +``` + +**Primeira execução**: O humano vê a saída bruta e diz "Sempre inclua citações para afirmações factuais." A lição é destilada e armazenada na memória. + +**Segunda execução**: O sistema recupera a lição sobre citações, pré-revisa a saída para adicionar citações e então mostra a versão melhorada. O trabalho do humano muda de "corrigir tudo" para "identificar o que o sistema deixou passar." + +### Configuração + +| Parâmetro | Padrão | Descrição | +|-----------|--------|-----------| +| `learn` | `False` | Habilitar aprendizado HITL | +| `learn_limit` | `5` | Máximo de lições passadas para recuperar na pré-revisão | + +### Decisões de Design Principais + +- **Mesmo LLM para tudo**: O parâmetro `llm` no decorador é compartilhado pelo mapeamento de outcome, destilação de lições e pré-revisão. Não é necessário configurar múltiplos modelos. +- **Saída estruturada**: Tanto a destilação quanto a pré-revisão usam function calling com modelos Pydantic quando o LLM suporta, com fallback para parsing de texto caso contrário. +- **Armazenamento não-bloqueante**: Lições são armazenadas via `remember_many()` que executa em uma thread em segundo plano -- o flow continua imediatamente. +- **Degradação graciosa**: Se o LLM falhar durante a destilação, nada é armazenado. Se falhar durante a pré-revisão, a saída bruta é mostrada. Nenhuma falha bloqueia o flow. +- **Sem escopo/categorias necessários**: Ao armazenar lições, apenas `source` é passado. O pipeline de codificação infere escopo, categorias e importância automaticamente. + + +`learn=True` requer que o Flow tenha memória disponível. Flows obtêm memória automaticamente por padrão, mas se você a desabilitou com `_skip_auto_memory`, o aprendizado HITL será silenciosamente ignorado. + + + +## Documentação Relacionada + +- [Visão Geral de Flows](/pt-BR/concepts/flows) - Aprenda sobre CrewAI Flows +- [Gerenciamento de Estado em Flows](/pt-BR/guides/flows/mastering-flow-state) - Gerenciando estado em flows +- [Persistência de Flows](/pt-BR/concepts/flows#persistence) - Persistindo estado de flows +- [Roteamento com @router](/pt-BR/concepts/flows#router) - Mais sobre roteamento condicional +- [Input Humano na Execução](/pt-BR/learn/human-input-on-execution) - Input humano no nível de task +- [Memória](/pt-BR/concepts/memory) - O sistema unificado de memória usado pelo aprendizado HITL diff --git a/docs/v1.15.1/pt-BR/learn/human-in-the-loop.mdx b/docs/v1.15.1/pt-BR/learn/human-in-the-loop.mdx new file mode 100644 index 000000000..d56fa1167 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/human-in-the-loop.mdx @@ -0,0 +1,120 @@ +--- +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" +mode: "wide" +--- + +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. CrewAI oferece várias maneiras de implementar HITL dependendo das suas necessidades. + +## Escolhendo Sua Abordagem HITL + +CrewAI oferece duas abordagens principais para implementar workflows human-in-the-loop: + +| Abordagem | Melhor Para | Integração | Versão | +|----------|----------|-------------|---------| +| **Baseada em Flow** (decorador `@human_feedback`) | Desenvolvimento local, revisão via console, workflows síncronos | [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows) | **1.8.0+** | +| **Baseada em Webhook** (Enterprise) | Deployments em produção, workflows assíncronos, integrações externas (Slack, Teams, etc.) | Este guia | - | + + +Se você está construindo flows e deseja adicionar etapas de revisão humana com roteamento baseado em feedback, confira o guia [Feedback Humano em Flows](/pt-BR/learn/human-feedback-in-flows) para o decorador `@human_feedback`. + + +## Configurando Workflows HITL Baseados em Webhook + + + + 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 + + + + **Crítico: URLs de Webhook Devem Ser Fornecidas Novamente**: + Você **deve** fornecer as mesmas URLs de webhook (`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`) na chamada de resume que você usou na chamada de kickoff. As configurações de webhook **NÃO** são automaticamente transferidas do kickoff - elas devem ser explicitamente incluídas na solicitação de resume para continuar recebendo notificações de conclusão de tarefa, etapas do agente e conclusão do crew. + + + Exemplo de chamada resume com webhooks: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "Ótimo trabalho! Por favor, adicione mais detalhes.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **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 + +## Recursos Enterprise + + + O CrewAI Enterprise oferece um sistema abrangente de gerenciamento HITL para Flows com revisão na plataforma, atribuição de respondentes, permissões, políticas de escalação, gerenciamento de SLA, roteamento dinâmico e análises completas. [Saiba mais →](/pt-BR/enterprise/features/flow-hitl-management) + diff --git a/docs/v1.15.1/pt-BR/learn/human-input-on-execution.mdx b/docs/v1.15.1/pt-BR/learn/human-input-on-execution.mdx new file mode 100644 index 000000000..44305127d --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/human-input-on-execution.mdx @@ -0,0 +1,99 @@ +--- +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-plus +mode: "wide" +--- + +## 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) +``` diff --git a/docs/v1.15.1/pt-BR/learn/kickoff-async.mdx b/docs/v1.15.1/pt-BR/learn/kickoff-async.mdx new file mode 100644 index 000000000..c1bf0e93c --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/kickoff-async.mdx @@ -0,0 +1,306 @@ +--- +title: Inicie uma Crew de Forma Assíncrona +description: Inicie uma Crew de Forma Assíncrona +icon: rocket-launch +mode: "wide" +--- + +## 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. + +O CrewAI oferece duas abordagens para execução assíncrona: + +| Método | Tipo | Descrição | +|--------|------|-------------| +| `akickoff()` | Async nativo | Async/await verdadeiro em toda a cadeia de execução | +| `kickoff_async()` | Baseado em thread | Envolve execução síncrona em `asyncio.to_thread` | + + +Para cargas de trabalho de alta concorrência, `akickoff()` é recomendado pois usa async nativo para execução de tasks, operações de memória e recuperação de conhecimento. + + +## Execução Async Nativa com `akickoff()` + +O método `akickoff()` fornece execução async nativa verdadeira, usando async/await em toda a cadeia de execução, incluindo execução de tasks, operações de memória e consultas de conhecimento. + +### Assinatura do Método + +```python Code +async def akickoff(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. + +### Exemplo: Execução Async Nativa de Crew + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# Criar um agente +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 +) + +# Criar uma tarefa +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." +) + +# Criar uma crew +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# Execução async nativa +async def main(): + result = await analysis_crew.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(main()) +``` + +### Exemplo: Múltiplas Crews Async Nativas + +Execute múltiplas crews concorrentemente usando `asyncio.gather()` com async nativo: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +task_1 = Task( + description="Analyze the first dataset and calculate the average age. 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. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def main(): + results = await asyncio.gather( + crew_1.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}), + crew_2.akickoff(inputs={"ages": [20, 22, 24, 28, 30]}) + ) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(main()) +``` + +### Exemplo: Async Nativo para Múltiplas Entradas + +Use `akickoff_for_each()` para executar sua crew contra múltiplas entradas concorrentemente com async nativo: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +data_analysis_task = Task( + description="Analyze the dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def main(): + datasets = [ + {"ages": [25, 30, 35, 40, 45]}, + {"ages": [20, 22, 24, 28, 30]}, + {"ages": [30, 35, 40, 45, 50]} + ] + + results = await analysis_crew.akickoff_for_each(datasets) + + for i, result in enumerate(results, 1): + print(f"Dataset {i} Result:", result) + +asyncio.run(main()) +``` + +## Async Baseado em Thread com `kickoff_async()` + +O método `kickoff_async()` fornece execução async envolvendo o `kickoff()` síncrono em uma thread. Isso é útil para integração async mais simples ou compatibilidade retroativa. + +### Assinatura do Método + +```python Code +async 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. + +### Exemplo: Execução Async Baseada em Thread + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(async_crew_execution()) +``` + +### Exemplo: Múltiplas Crews Async Baseadas em Thread + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +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 +) + +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." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def async_multiple_crews(): + 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]}) + + results = await asyncio.gather(result_1, result_2) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(async_multiple_crews()) +``` + +## Streaming Assíncrono + +Ambos os métodos async suportam streaming quando `stream=True` está definido na crew: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +agent = Agent( + role="Researcher", + goal="Research and summarize topics", + backstory="You are an expert researcher." +) + +task = Task( + description="Research the topic: {topic}", + agent=agent, + expected_output="A comprehensive summary of the topic." +) + +crew = Crew( + agents=[agent], + tasks=[task], + stream=True # Habilitar streaming +) + +async def main(): + streaming_output = await crew.akickoff(inputs={"topic": "AI trends in 2024"}) + + # Iteração async sobre chunks de streaming + async for chunk in streaming_output: + print(f"Chunk: {chunk.content}") + + # Acessar resultado final após streaming completar + result = streaming_output.result + print(f"Final result: {result.raw}") + +asyncio.run(main()) +``` + +## 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. + +- **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. + +- **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. + +## Escolhendo entre `akickoff()` e `kickoff_async()` + +| Recurso | `akickoff()` | `kickoff_async()` | +|---------|--------------|-------------------| +| Modelo de execução | Async/await nativo | Wrapper baseado em thread | +| Execução de tasks | Async com `aexecute_sync()` | Síncrono em thread pool | +| Operações de memória | Async | Síncrono em thread pool | +| Recuperação de conhecimento | Async | Síncrono em thread pool | +| Melhor para | Alta concorrência, cargas I/O-bound | Integração async simples | +| Suporte a streaming | Sim | Sim | diff --git a/docs/v1.15.1/pt-BR/learn/kickoff-for-each.mdx b/docs/v1.15.1/pt-BR/learn/kickoff-for-each.mdx new file mode 100644 index 000000000..698ae0f8c --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/kickoff-for-each.mdx @@ -0,0 +1,54 @@ +--- +title: Kickoff Crew para Cada +description: Kickoff Crew para Cada Item em uma Lista +icon: at +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/llm-connections.mdx b/docs/v1.15.1/pt-BR/learn/llm-connections.mdx new file mode 100644 index 000000000..6c09e7c97 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/llm-connections.mdx @@ -0,0 +1,213 @@ +--- +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 +mode: "wide" +--- + +## Conecte o CrewAI a LLMs + +O CrewAI conecta-se a LLMs por meio de integrações nativas via SDK para os provedores mais populares (OpenAI, Anthropic, Google Gemini, Azure e AWS Bedrock), e usa o LiteLLM como alternativa flexível para todos os demais provedores. + + + 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). + + + Para usar qualquer provedor não coberto por uma integração nativa, adicione o LiteLLM como dependência ao seu projeto: + ```bash + uv add 'crewai[litellm]' + ``` + Provedores nativos (OpenAI, Anthropic, Google Gemini, Azure, AWS Bedrock) usam seus próprios extras de SDK — consulte os [Exemplos de Configuração de Provedores](/pt-BR/concepts/llms#exemplos-de-configuração-de-provedores). + + +## 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/v1.15.1/pt-BR/learn/llm-hooks.mdx b/docs/v1.15.1/pt-BR/learn/llm-hooks.mdx new file mode 100644 index 000000000..9122d0d32 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/llm-hooks.mdx @@ -0,0 +1,388 @@ +--- +title: Hooks de Chamada LLM +description: Aprenda a usar hooks de chamada LLM para interceptar, modificar e controlar interações com modelos de linguagem no CrewAI +mode: "wide" +--- + +Os Hooks de Chamada LLM fornecem controle fino sobre interações com modelos de linguagem durante a execução do agente. Esses hooks permitem interceptar chamadas LLM, modificar prompts, transformar respostas, implementar gates de aprovação e adicionar logging ou monitoramento personalizado. + +## Visão Geral + +Os hooks LLM são executados em dois pontos críticos: +- **Antes da Chamada LLM**: Modificar mensagens, validar entradas ou bloquear execução +- **Depois da Chamada LLM**: Transformar respostas, sanitizar saídas ou modificar histórico de conversação + +## Tipos de Hook + +### Hooks Antes da Chamada LLM + +Executados antes de cada chamada LLM, esses hooks podem: +- Inspecionar e modificar mensagens enviadas ao LLM +- Bloquear execução LLM com base em condições +- Implementar limitação de taxa ou gates de aprovação +- Adicionar contexto ou mensagens do sistema +- Registrar detalhes da requisição + +**Assinatura:** +```python +def before_hook(context: LLMCallHookContext) -> bool | None: + # Retorne False para bloquear execução + # Retorne True ou None para permitir execução + ... +``` + +### Hooks Depois da Chamada LLM + +Executados depois de cada chamada LLM, esses hooks podem: +- Modificar ou sanitizar respostas do LLM +- Adicionar metadados ou formatação +- Registrar detalhes da resposta +- Atualizar histórico de conversação +- Implementar filtragem de conteúdo + +**Assinatura:** +```python +def after_hook(context: LLMCallHookContext) -> str | None: + # Retorne string de resposta modificada + # Retorne None para manter resposta original + ... +``` + +## Contexto do Hook LLM + +O objeto `LLMCallHookContext` fornece acesso abrangente ao estado de execução: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # Referência completa ao executor + messages: list # Lista de mensagens mutável + agent: Agent # Agente atual + task: Task # Tarefa atual + crew: Crew # Instância da crew + llm: BaseLLM # Instância do LLM + iterations: int # Contagem de iteração atual + response: str | None # Resposta do LLM (apenas hooks posteriores) +``` + +### Modificando Mensagens + +**Importante:** Sempre modifique mensagens in-place: + +```python +# ✅ Correto - modificar in-place +def add_context(context: LLMCallHookContext) -> None: + context.messages.append({"role": "system", "content": "Seja conciso"}) + +# ❌ Errado - substitui referência da lista +def wrong_approach(context: LLMCallHookContext) -> None: + context.messages = [{"role": "system", "content": "Seja conciso"}] +``` + +## Métodos de Registro + +### 1. Registro Baseado em Decoradores (Recomendado) + +Use decoradores para sintaxe mais limpa: + +```python +from crewai.hooks import before_llm_call, after_llm_call + +@before_llm_call +def validate_iteration_count(context): + """Valida a contagem de iterações.""" + if context.iterations > 10: + print("⚠️ Máximo de iterações excedido") + return False # Bloquear execução + return None + +@after_llm_call +def sanitize_response(context): + """Remove dados sensíveis.""" + if context.response and "API_KEY" in context.response: + return context.response.replace("API_KEY", "[CENSURADO]") + return None +``` + +### 2. Hooks com Escopo de Crew + +Registre hooks para uma instância específica de crew: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_llm_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # Aplica-se apenas a esta crew + if context.iterations == 0: + print(f"Iniciando tarefa: {context.task.description}") + return None + + @after_llm_call_crew + def log_responses(self, context): + # Logging específico da crew + print(f"Comprimento da resposta: {len(context.response)}") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## Casos de Uso Comuns + +### 1. Limitação de Iterações + +```python +@before_llm_call +def limit_iterations(context: LLMCallHookContext) -> bool | None: + """Previne loops infinitos limitando iterações.""" + max_iterations = 15 + if context.iterations > max_iterations: + print(f"⛔ Bloqueado: Excedeu {max_iterations} iterações") + return False # Bloquear execução + return None +``` + +### 2. Gate de Aprovação Humana + +```python +@before_llm_call +def require_approval(context: LLMCallHookContext) -> bool | None: + """Requer aprovação após certas iterações.""" + if context.iterations > 5: + response = context.request_human_input( + prompt=f"Iteração {context.iterations}: Aprovar chamada LLM?", + default_message="Pressione Enter para aprovar, ou digite 'não' para bloquear:" + ) + if response.lower() == "não": + print("🚫 Chamada LLM bloqueada pelo usuário") + return False + return None +``` + +### 3. Adicionando Contexto do Sistema + +```python +@before_llm_call +def add_guardrails(context: LLMCallHookContext) -> None: + """Adiciona diretrizes de segurança a cada chamada LLM.""" + context.messages.append({ + "role": "system", + "content": "Garanta que as respostas sejam factuais e cite fontes quando possível." + }) + return None +``` + +### 4. Sanitização de Resposta + +```python +@after_llm_call +def sanitize_sensitive_data(context: LLMCallHookContext) -> str | None: + """Remove padrões sensíveis.""" + if not context.response: + return None + + import re + sanitized = context.response + sanitized = re.sub(r'\b\d{3}\.\d{3}\.\d{3}-\d{2}\b', '[CPF-CENSURADO]', sanitized) + sanitized = re.sub(r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', '[CARTÃO-CENSURADO]', sanitized) + + return sanitized +``` + +### 5. Rastreamento de Custos + +```python +import tiktoken + +@before_llm_call +def track_token_usage(context: LLMCallHookContext) -> None: + """Rastreia tokens de entrada.""" + encoding = tiktoken.get_encoding("cl100k_base") + total_tokens = sum( + len(encoding.encode(msg.get("content", ""))) + for msg in context.messages + ) + print(f"📊 Tokens de entrada: ~{total_tokens}") + return None + +@after_llm_call +def track_response_tokens(context: LLMCallHookContext) -> None: + """Rastreia tokens de resposta.""" + if context.response: + encoding = tiktoken.get_encoding("cl100k_base") + tokens = len(encoding.encode(context.response)) + print(f"📊 Tokens de resposta: ~{tokens}") + return None +``` + +### 6. Logging de Debug + +```python +@before_llm_call +def debug_request(context: LLMCallHookContext) -> None: + """Debug de requisição LLM.""" + print(f""" + 🔍 Debug de Chamada LLM: + - Agente: {context.agent.role} + - Tarefa: {context.task.description[:50]}... + - Iteração: {context.iterations} + - Contagem de Mensagens: {len(context.messages)} + - Última Mensagem: {context.messages[-1] if context.messages else 'Nenhuma'} + """) + return None + +@after_llm_call +def debug_response(context: LLMCallHookContext) -> None: + """Debug de resposta LLM.""" + if context.response: + print(f"✅ Preview da Resposta: {context.response[:100]}...") + return None +``` + +## Gerenciamento de Hooks + +### Desregistrando Hooks + +```python +from crewai.hooks import ( + unregister_before_llm_call_hook, + unregister_after_llm_call_hook +) + +# Desregistrar hook específico +def my_hook(context): + ... + +register_before_llm_call_hook(my_hook) +# Mais tarde... +unregister_before_llm_call_hook(my_hook) # Retorna True se encontrado +``` + +### Limpando Hooks + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_all_llm_call_hooks +) + +# Limpar tipo específico de hook +count = clear_before_llm_call_hooks() +print(f"Limpou {count} hooks antes") + +# Limpar todos os hooks LLM +before_count, after_count = clear_all_llm_call_hooks() +print(f"Limpou {before_count} hooks antes e {after_count} hooks depois") +``` + +## Padrões Avançados + +### Execução Condicional de Hook + +```python +@before_llm_call +def conditional_blocking(context: LLMCallHookContext) -> bool | None: + """Bloqueia apenas em condições específicas.""" + # Bloquear apenas para agentes específicos + if context.agent.role == "researcher" and context.iterations > 10: + return False + + # Bloquear apenas para tarefas específicas + if "sensível" in context.task.description.lower() and context.iterations > 5: + return False + + return None +``` + +### Modificações com Consciência de Contexto + +```python +@before_llm_call +def adaptive_prompting(context: LLMCallHookContext) -> None: + """Adiciona contexto diferente baseado na iteração.""" + if context.iterations == 0: + context.messages.append({ + "role": "system", + "content": "Comece com uma visão geral de alto nível." + }) + elif context.iterations > 3: + context.messages.append({ + "role": "system", + "content": "Foque em detalhes específicos e forneça exemplos." + }) + return None +``` + +## Melhores Práticas + +1. **Mantenha Hooks Focados**: Cada hook deve ter uma responsabilidade única +2. **Evite Computação Pesada**: Hooks executam em cada chamada LLM +3. **Trate Erros Graciosamente**: Use try-except para prevenir falhas de hooks +4. **Use Type Hints**: Aproveite `LLMCallHookContext` para melhor suporte IDE +5. **Documente Comportamento do Hook**: Especialmente para condições de bloqueio +6. **Teste Hooks Independentemente**: Teste unitário de hooks antes de usar em produção +7. **Limpe Hooks em Testes**: Use `clear_all_llm_call_hooks()` entre execuções de teste +8. **Modifique In-Place**: Sempre modifique `context.messages` in-place, nunca substitua + +## Tratamento de Erros + +```python +@before_llm_call +def safe_hook(context: LLMCallHookContext) -> bool | None: + try: + # Sua lógica de hook + if some_condition: + return False + except Exception as e: + print(f"⚠️ Erro no hook: {e}") + # Decida: permitir ou bloquear em erro + return None # Permitir execução apesar do erro +``` + +## Segurança de Tipos + +```python +from crewai.hooks import LLMCallHookContext, BeforeLLMCallHookType, AfterLLMCallHookType + +# Anotações de tipo explícitas +def my_before_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_after_hook(context: LLMCallHookContext) -> str | None: + return None + +# Registro type-safe +register_before_llm_call_hook(my_before_hook) +register_after_llm_call_hook(my_after_hook) +``` + +## Solução de Problemas + +### Hook Não Está Executando +- Verifique se o hook está registrado antes da execução da crew +- Verifique se hook anterior retornou `False` (bloqueia hooks subsequentes) +- Garanta que assinatura do hook corresponda ao tipo esperado + +### Modificações de Mensagem Não Persistem +- Use modificações in-place: `context.messages.append()` +- Não substitua a lista: `context.messages = []` + +### Modificações de Resposta Não Funcionam +- Retorne a string modificada dos hooks posteriores +- Retornar `None` mantém a resposta original + +## Conclusão + +Os Hooks de Chamada LLM fornecem capacidades poderosas para controlar e monitorar interações com modelos de linguagem no CrewAI. Use-os para implementar guardrails de segurança, gates de aprovação, logging, rastreamento de custos e sanitização de respostas. Combinados com tratamento adequado de erros e segurança de tipos, os hooks permitem sistemas de agentes robustos e prontos para produção. + diff --git a/docs/v1.15.1/pt-BR/learn/llm-selection-guide.mdx b/docs/v1.15.1/pt-BR/learn/llm-selection-guide.mdx new file mode 100644 index 000000000..01587c37e --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/llm-selection-guide.mdx @@ -0,0 +1,815 @@ +--- +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" +mode: "wide" +--- + +## 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 AMP 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 AMP** 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. + + diff --git a/docs/v1.15.1/pt-BR/learn/multimodal-agents.mdx b/docs/v1.15.1/pt-BR/learn/multimodal-agents.mdx new file mode 100644 index 000000000..cf238a2bd --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/multimodal-agents.mdx @@ -0,0 +1,141 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/overview.mdx b/docs/v1.15.1/pt-BR/learn/overview.mdx new file mode 100644 index 000000000..cf9716542 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/overview.mdx @@ -0,0 +1,159 @@ +--- +title: "Visão Geral" +description: "Aprenda como construir, personalizar e otimizar suas aplicações CrewAI com guias e tutoriais completos" +icon: "face-smile" +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/v1.15.1/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx new file mode 100644 index 000000000..624a991d4 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/replay-tasks-from-latest-crew-kickoff.mdx @@ -0,0 +1,79 @@ +--- +title: Reexecutar Tarefas a partir do Último Crew Kickoff +description: Reexecute tarefas a partir do último crew.kickoff(...) +icon: arrow-right +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/sequential-process.mdx b/docs/v1.15.1/pt-BR/learn/sequential-process.mdx new file mode 100644 index 000000000..92851d31a --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/sequential-process.mdx @@ -0,0 +1,128 @@ +--- +title: Processos Sequenciais +description: Um guia abrangente para utilizar os processos sequenciais na execução de tarefas em projetos CrewAI. +icon: forward +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/learn/streaming-crew-execution.mdx b/docs/v1.15.1/pt-BR/learn/streaming-crew-execution.mdx new file mode 100644 index 000000000..4a3df07ef --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/streaming-crew-execution.mdx @@ -0,0 +1,384 @@ +--- +title: Streaming na Execução da Crew +description: Transmita saída em tempo real da execução da sua crew no CrewAI +icon: wave-pulse +mode: "wide" +--- + +## Introdução + +O CrewAI fornece a capacidade de transmitir saída em tempo real durante a execução da crew, permitindo que você exiba resultados conforme são gerados, em vez de esperar que todo o processo seja concluído. Este recurso é particularmente útil para construir aplicações interativas, fornecer feedback ao usuário e monitorar processos de longa duração. + +## Como o Streaming Funciona + +Quando o streaming está ativado, o CrewAI captura respostas do LLM e chamadas de ferramentas conforme acontecem, empacotando-as em chunks estruturados que incluem contexto sobre qual task e agent está executando. Você pode iterar sobre esses chunks em tempo real e acessar o resultado final quando a execução for concluída. + +## Ativando o Streaming + +Para ativar o streaming, defina o parâmetro `stream` como `True` ao criar sua crew: + +```python Code +from crewai import Agent, Crew, Task + +# Crie seus agentes e tasks +researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information on topics", + backstory="You are an experienced researcher with excellent analytical skills.", +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A detailed report on recent AI advancements", + agent=researcher, +) + +# Ativar streaming +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True # Ativar saída em streaming +) +``` + +## Streaming Síncrono + +Quando você chama `kickoff()` em uma crew com streaming ativado, ele retorna um objeto `CrewStreamingOutput` que você pode iterar para receber chunks conforme chegam: + +```python Code +# Iniciar execução com streaming +streaming = crew.kickoff(inputs={"topic": "artificial intelligence"}) + +# Iterar sobre chunks conforme chegam +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Acessar o resultado final após o streaming completar +result = streaming.result +print(f"\n\nSaída final: {result.raw}") +``` + +### Informações do Chunk de Stream + +Cada chunk fornece contexto rico sobre a execução: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +for chunk in streaming: + print(f"Task: {chunk.task_name} (índice {chunk.task_index})") + print(f"Agent: {chunk.agent_role}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT ou TOOL_CALL + if chunk.tool_call: + print(f"Tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +### Acessando Resultados do Streaming + +O objeto `CrewStreamingOutput` fornece várias propriedades úteis: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +# Iterar e coletar chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Após a iteração completar +print(f"\nCompletado: {streaming.is_completed}") +print(f"Texto completo: {streaming.get_full_text()}") +print(f"Todos os chunks: {len(streaming.chunks)}") +print(f"Resultado final: {streaming.result.raw}") +``` + +## Streaming Assíncrono + +Para aplicações assíncronas, você pode usar `akickoff()` (async nativo) ou `kickoff_async()` (baseado em threads) com iteração assíncrona: + +### Async Nativo com `akickoff()` + +O método `akickoff()` fornece execução async nativa verdadeira em toda a cadeia: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Iniciar streaming async nativo + streaming = await crew.akickoff(inputs={"topic": "AI"}) + + # Iteração assíncrona sobre chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Acessar resultado final + result = streaming.result + print(f"\n\nSaída final: {result.raw}") + +asyncio.run(stream_crew()) +``` + +### Async Baseado em Threads com `kickoff_async()` + +Para integração async mais simples ou compatibilidade retroativa: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Iniciar streaming async baseado em threads + streaming = await crew.kickoff_async(inputs={"topic": "AI"}) + + # Iteração assíncrona sobre chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Acessar resultado final + result = streaming.result + print(f"\n\nSaída final: {result.raw}") + +asyncio.run(stream_crew()) +``` + + +Para cargas de trabalho de alta concorrência, `akickoff()` é recomendado pois usa async nativo para execução de tasks, operações de memória e recuperação de conhecimento. Consulte o guia [Iniciar Crew de Forma Assíncrona](/pt-BR/learn/kickoff-async) para mais detalhes. + + +## Streaming com kickoff_for_each + +Ao executar uma crew para múltiplas entradas com `kickoff_for_each()`, o streaming funciona de forma diferente dependendo se você usa síncrono ou assíncrono: + +### kickoff_for_each Síncrono + +Com `kickoff_for_each()` síncrono, você obtém uma lista de objetos `CrewStreamingOutput`, um para cada entrada: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} +] + +# Retorna lista de saídas de streaming +streaming_outputs = crew.kickoff_for_each(inputs=inputs_list) + +# Iterar sobre cada saída de streaming +for i, streaming in enumerate(streaming_outputs): + print(f"\n=== Entrada {i + 1} ===") + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\n\nResultado {i + 1}: {result.raw}") +``` + +### kickoff_for_each_async Assíncrono + +Com `kickoff_for_each_async()` assíncrono, você obtém um único `CrewStreamingOutput` que produz chunks de todas as crews conforme chegam concorrentemente: + +```python Code +import asyncio + +async def stream_multiple_crews(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} + ] + + # Retorna saída de streaming única para todas as crews + streaming = await crew.kickoff_for_each_async(inputs=inputs_list) + + # Chunks de todas as crews chegam conforme são gerados + async for chunk in streaming: + print(f"[{chunk.task_name}] {chunk.content}", end="", flush=True) + + # Acessar todos os resultados + results = streaming.results # Lista de objetos CrewOutput + for i, result in enumerate(results): + print(f"\n\nResultado {i + 1}: {result.raw}") + +asyncio.run(stream_multiple_crews()) +``` + +## Tipos de Chunk de Stream + +Chunks podem ser de diferentes tipos, indicados pelo campo `chunk_type`: + +### Chunks TEXT + +Conteúdo de texto padrão de respostas do LLM: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### Chunks TOOL_CALL + +Informações sobre chamadas de ferramentas sendo feitas: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL: + print(f"\nChamando ferramenta: {chunk.tool_call.tool_name}") + print(f"Argumentos: {chunk.tool_call.arguments}") +``` + +## Exemplo Prático: Construindo uma UI com Streaming + +Aqui está um exemplo completo mostrando como construir uma aplicação interativa com streaming: + +```python Code +import asyncio +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +async def interactive_research(): + # Criar crew com streaming ativado + researcher = Agent( + role="Research Analyst", + goal="Provide detailed analysis on any topic", + backstory="You are an expert researcher with broad knowledge.", + ) + + task = Task( + description="Research and analyze: {topic}", + expected_output="A comprehensive analysis with key insights", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True, + verbose=False + ) + + # Obter entrada do usuário + topic = input("Digite um tópico para pesquisar: ") + + print(f"\n{'='*60}") + print(f"Pesquisando: {topic}") + print(f"{'='*60}\n") + + # Iniciar execução com streaming + streaming = await crew.kickoff_async(inputs={"topic": topic}) + + current_task = "" + async for chunk in streaming: + # Mostrar transições de task + if chunk.task_name != current_task: + current_task = chunk.task_name + print(f"\n[{chunk.agent_role}] Trabalhando em: {chunk.task_name}") + print("-" * 60) + + # Exibir chunks de texto + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Exibir chamadas de ferramentas + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Usando ferramenta: {chunk.tool_call.tool_name}") + + # Mostrar resultado final + result = streaming.result + print(f"\n\n{'='*60}") + print("Análise Completa!") + print(f"{'='*60}") + print(f"\nUso de Tokens: {result.token_usage}") + +asyncio.run(interactive_research()) +``` + +## Casos de Uso + +O streaming é particularmente valioso para: + +- **Aplicações Interativas**: Fornecer feedback em tempo real aos usuários enquanto os agentes trabalham +- **Tasks de Longa Duração**: Mostrar progresso para pesquisa, análise ou geração de conteúdo +- **Depuração e Monitoramento**: Observar comportamento e tomada de decisão dos agentes em tempo real +- **Experiência do Usuário**: Reduzir latência percebida mostrando resultados incrementais +- **Dashboards ao Vivo**: Construir interfaces de monitoramento que exibem status de execução da crew + +## Cancelamento e Limpeza de Recursos + +`CrewStreamingOutput` suporta cancelamento gracioso para que o trabalho em andamento pare imediatamente quando o consumidor desconecta. + +### Gerenciador de Contexto Assíncrono + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### Cancelamento Explícito + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # assíncrono + # streaming.close() # equivalente síncrono +``` + +Após o cancelamento, `streaming.is_cancelled` e `streaming.is_completed` são ambos `True`. Tanto `aclose()` quanto `close()` são idempotentes. + +## Notas Importantes + +- O streaming ativa automaticamente o streaming do LLM para todos os agentes na crew +- Você deve iterar através de todos os chunks antes de acessar a propriedade `.result` +- Para `kickoff_for_each_async()` com streaming, use `.results` (plural) para obter todas as saídas +- O streaming adiciona overhead mínimo e pode realmente melhorar a performance percebida +- Cada chunk inclui contexto completo (task, agente, tipo de chunk) para UIs ricas + +## Tratamento de Erros + +Trate erros durante a execução com streaming: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSucesso: {result.raw}") + +except Exception as e: + print(f"\nErro durante o streaming: {e}") + if streaming.is_completed: + print("O streaming foi completado mas ocorreu um erro") +``` + +Ao aproveitar o streaming, você pode construir aplicações mais responsivas e interativas com o CrewAI, fornecendo aos usuários visibilidade em tempo real da execução dos agentes e resultados. \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/learn/tool-hooks.mdx b/docs/v1.15.1/pt-BR/learn/tool-hooks.mdx new file mode 100644 index 000000000..aa3b954df --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/tool-hooks.mdx @@ -0,0 +1,498 @@ +--- +title: Hooks de Chamada de Ferramenta +description: Aprenda a usar hooks de chamada de ferramenta para interceptar, modificar e controlar execução de ferramentas no CrewAI +mode: "wide" +--- + +Os Hooks de Chamada de Ferramenta fornecem controle fino sobre a execução de ferramentas durante operações do agente. Esses hooks permitem interceptar chamadas de ferramenta, modificar entradas, transformar saídas, implementar verificações de segurança e adicionar logging ou monitoramento abrangente. + +## Visão Geral + +Os hooks de ferramenta são executados em dois pontos críticos: +- **Antes da Chamada de Ferramenta**: Modificar entradas, validar parâmetros ou bloquear execução +- **Depois da Chamada de Ferramenta**: Transformar resultados, sanitizar saídas ou registrar detalhes de execução + +## Tipos de Hook + +### Hooks Antes da Chamada de Ferramenta + +Executados antes de cada execução de ferramenta, esses hooks podem: +- Inspecionar e modificar entradas de ferramenta +- Bloquear execução de ferramenta com base em condições +- Implementar gates de aprovação para operações perigosas +- Validar parâmetros +- Registrar invocações de ferramenta + +**Assinatura:** +```python +def before_hook(context: ToolCallHookContext) -> bool | None: + # Retorne False para bloquear execução + # Retorne True ou None para permitir execução + ... +``` + +### Hooks Depois da Chamada de Ferramenta + +Executados depois de cada execução de ferramenta, esses hooks podem: +- Modificar ou sanitizar resultados de ferramenta +- Adicionar metadados ou formatação +- Registrar resultados de execução +- Implementar validação de resultado +- Transformar formatos de saída + +**Assinatura:** +```python +def after_hook(context: ToolCallHookContext) -> str | None: + # Retorne string de resultado modificado + # Retorne None para manter resultado original + ... +``` + +## Contexto do Hook de Ferramenta + +O objeto `ToolCallHookContext` fornece acesso abrangente ao estado de execução da ferramenta: + +```python +class ToolCallHookContext: + tool_name: str # Nome da ferramenta sendo chamada + tool_input: dict[str, Any] # Parâmetros de entrada mutáveis da ferramenta + tool: CrewStructuredTool # Referência da instância da ferramenta + agent: Agent | BaseAgent | None # Agente executando a ferramenta + task: Task | None # Tarefa atual + crew: Crew | None # Instância da crew + tool_result: str | None # Resultado da ferramenta (apenas hooks posteriores) +``` + +### Modificando Entradas de Ferramenta + +**Importante:** Sempre modifique entradas de ferramenta in-place: + +```python +# ✅ Correto - modificar in-place +def sanitize_input(context: ToolCallHookContext) -> None: + context.tool_input['query'] = context.tool_input['query'].lower() + +# ❌ Errado - substitui referência do dict +def wrong_approach(context: ToolCallHookContext) -> None: + context.tool_input = {'query': 'nova consulta'} +``` + +## Métodos de Registro + +### 1. Registro Baseado em Decoradores (Recomendado) + +Use decoradores para sintaxe mais limpa: + +```python +from crewai.hooks import before_tool_call, after_tool_call + +@before_tool_call +def block_dangerous_tools(context): + """Bloqueia ferramentas perigosas.""" + dangerous_tools = ['delete_database', 'drop_table', 'rm_rf'] + if context.tool_name in dangerous_tools: + print(f"⛔ Ferramenta perigosa bloqueada: {context.tool_name}") + return False # Bloquear execução + return None + +@after_tool_call +def sanitize_results(context): + """Sanitiza resultados.""" + if context.tool_result and "password" in context.tool_result.lower(): + return context.tool_result.replace("password", "[CENSURADO]") + return None +``` + +### 2. Hooks com Escopo de Crew + +Registre hooks para uma instância específica de crew: + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_tool_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_tool_call_crew + def validate_tool_inputs(self, context): + # Aplica-se apenas a esta crew + if context.tool_name == "web_search": + if not context.tool_input.get('query'): + print("❌ Consulta de busca inválida") + return False + return None + + @after_tool_call_crew + def log_tool_results(self, context): + # Logging de ferramenta específico da crew + print(f"✅ {context.tool_name} concluída") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## Casos de Uso Comuns + +### 1. Guardrails de Segurança + +```python +@before_tool_call +def safety_check(context: ToolCallHookContext) -> bool | None: + """Bloqueia ferramentas que podem causar danos.""" + destructive_tools = [ + 'delete_file', + 'drop_table', + 'remove_user', + 'system_shutdown' + ] + + if context.tool_name in destructive_tools: + print(f"🛑 Ferramenta destrutiva bloqueada: {context.tool_name}") + return False + + # Avisar em operações sensíveis + sensitive_tools = ['send_email', 'post_to_social_media', 'charge_payment'] + if context.tool_name in sensitive_tools: + print(f"⚠️ Executando ferramenta sensível: {context.tool_name}") + + return None +``` + +### 2. Gate de Aprovação Humana + +```python +@before_tool_call +def require_approval_for_actions(context: ToolCallHookContext) -> bool | None: + """Requer aprovação para ações específicas.""" + approval_required = [ + 'send_email', + 'make_purchase', + 'delete_file', + 'post_message' + ] + + if context.tool_name in approval_required: + response = context.request_human_input( + prompt=f"Aprovar {context.tool_name}?", + default_message=f"Entrada: {context.tool_input}\nDigite 'sim' para aprovar:" + ) + + if response.lower() != 'sim': + print(f"❌ Execução de ferramenta negada: {context.tool_name}") + return False + + return None +``` + +### 3. Validação e Sanitização de Entrada + +```python +@before_tool_call +def validate_and_sanitize_inputs(context: ToolCallHookContext) -> bool | None: + """Valida e sanitiza entradas.""" + # Validar consultas de busca + if context.tool_name == 'web_search': + query = context.tool_input.get('query', '') + if len(query) < 3: + print("❌ Consulta de busca muito curta") + return False + + # Sanitizar consulta + context.tool_input['query'] = query.strip().lower() + + # Validar caminhos de arquivo + if context.tool_name == 'read_file': + path = context.tool_input.get('path', '') + if '..' in path or path.startswith('/'): + print("❌ Caminho de arquivo inválido") + return False + + return None +``` + +### 4. Sanitização de Resultado + +```python +@after_tool_call +def sanitize_sensitive_data(context: ToolCallHookContext) -> str | None: + """Sanitiza dados sensíveis.""" + if not context.tool_result: + return None + + import re + result = context.tool_result + + # Remover chaves de API + result = re.sub( + r'(api[_-]?key|token)["\']?\s*[:=]\s*["\']?[\w-]+', + r'\1: [CENSURADO]', + result, + flags=re.IGNORECASE + ) + + # Remover endereços de email + result = re.sub( + r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '[EMAIL-CENSURADO]', + result + ) + + # Remover números de cartão de crédito + result = re.sub( + r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', + '[CARTÃO-CENSURADO]', + result + ) + + return result +``` + +### 5. Análise de Uso de Ferramenta + +```python +import time +from collections import defaultdict + +tool_stats = defaultdict(lambda: {'count': 0, 'total_time': 0, 'failures': 0}) + +@before_tool_call +def start_timer(context: ToolCallHookContext) -> None: + context.tool_input['_start_time'] = time.time() + return None + +@after_tool_call +def track_tool_usage(context: ToolCallHookContext) -> None: + start_time = context.tool_input.get('_start_time', time.time()) + duration = time.time() - start_time + + tool_stats[context.tool_name]['count'] += 1 + tool_stats[context.tool_name]['total_time'] += duration + + if not context.tool_result or 'error' in context.tool_result.lower(): + tool_stats[context.tool_name]['failures'] += 1 + + print(f""" + 📊 Estatísticas da Ferramenta {context.tool_name}: + - Execuções: {tool_stats[context.tool_name]['count']} + - Tempo Médio: {tool_stats[context.tool_name]['total_time'] / tool_stats[context.tool_name]['count']:.2f}s + - Falhas: {tool_stats[context.tool_name]['failures']} + """) + + return None +``` + +### 6. Limitação de Taxa + +```python +from collections import defaultdict +from datetime import datetime, timedelta + +tool_call_history = defaultdict(list) + +@before_tool_call +def rate_limit_tools(context: ToolCallHookContext) -> bool | None: + """Limita taxa de chamadas de ferramenta.""" + tool_name = context.tool_name + now = datetime.now() + + # Limpar entradas antigas (mais antigas que 1 minuto) + tool_call_history[tool_name] = [ + call_time for call_time in tool_call_history[tool_name] + if now - call_time < timedelta(minutes=1) + ] + + # Verificar limite de taxa (máximo 10 chamadas por minuto) + if len(tool_call_history[tool_name]) >= 10: + print(f"🚫 Limite de taxa excedido para {tool_name}") + return False + + # Registrar esta chamada + tool_call_history[tool_name].append(now) + return None +``` + +### 7. Logging de Debug + +```python +@before_tool_call +def debug_tool_call(context: ToolCallHookContext) -> None: + """Debug de chamada de ferramenta.""" + print(f""" + 🔍 Debug de Chamada de Ferramenta: + - Ferramenta: {context.tool_name} + - Agente: {context.agent.role if context.agent else 'Desconhecido'} + - Tarefa: {context.task.description[:50] if context.task else 'Desconhecida'}... + - Entrada: {context.tool_input} + """) + return None + +@after_tool_call +def debug_tool_result(context: ToolCallHookContext) -> None: + """Debug de resultado de ferramenta.""" + if context.tool_result: + result_preview = context.tool_result[:200] + print(f"✅ Preview do Resultado: {result_preview}...") + else: + print("⚠️ Nenhum resultado retornado") + return None +``` + +## Gerenciamento de Hooks + +### Desregistrando Hooks + +```python +from crewai.hooks import ( + unregister_before_tool_call_hook, + unregister_after_tool_call_hook +) + +# Desregistrar hook específico +def my_hook(context): + ... + +register_before_tool_call_hook(my_hook) +# Mais tarde... +success = unregister_before_tool_call_hook(my_hook) +print(f"Desregistrado: {success}") +``` + +### Limpando Hooks + +```python +from crewai.hooks import ( + clear_before_tool_call_hooks, + clear_after_tool_call_hooks, + clear_all_tool_call_hooks +) + +# Limpar tipo específico de hook +count = clear_before_tool_call_hooks() +print(f"Limpou {count} hooks antes") + +# Limpar todos os hooks de ferramenta +before_count, after_count = clear_all_tool_call_hooks() +print(f"Limpou {before_count} hooks antes e {after_count} hooks depois") +``` + +## Padrões Avançados + +### Execução Condicional de Hook + +```python +@before_tool_call +def conditional_blocking(context: ToolCallHookContext) -> bool | None: + """Bloqueia apenas em condições específicas.""" + # Bloquear apenas para agentes específicos + if context.agent and context.agent.role == "junior_agent": + if context.tool_name in ['delete_file', 'send_email']: + print(f"❌ Agentes júnior não podem usar {context.tool_name}") + return False + + # Bloquear apenas durante tarefas específicas + if context.task and "sensível" in context.task.description.lower(): + if context.tool_name == 'web_search': + print("❌ Busca na web bloqueada para tarefas sensíveis") + return False + + return None +``` + +### Modificação de Entrada com Consciência de Contexto + +```python +@before_tool_call +def enhance_tool_inputs(context: ToolCallHookContext) -> None: + """Adiciona contexto baseado no papel do agente.""" + # Adicionar contexto baseado no papel do agente + if context.agent and context.agent.role == "researcher": + if context.tool_name == 'web_search': + # Adicionar restrições de domínio para pesquisadores + context.tool_input['domains'] = ['edu', 'gov', 'org'] + + # Adicionar contexto baseado na tarefa + if context.task and "urgente" in context.task.description.lower(): + if context.tool_name == 'send_email': + context.tool_input['priority'] = 'high' + + return None +``` + +## Melhores Práticas + +1. **Mantenha Hooks Focados**: Cada hook deve ter uma responsabilidade única +2. **Evite Computação Pesada**: Hooks executam em cada chamada de ferramenta +3. **Trate Erros Graciosamente**: Use try-except para prevenir falhas de hooks +4. **Use Type Hints**: Aproveite `ToolCallHookContext` para melhor suporte IDE +5. **Documente Condições de Bloqueio**: Deixe claro quando/por que ferramentas são bloqueadas +6. **Teste Hooks Independentemente**: Teste unitário de hooks antes de usar em produção +7. **Limpe Hooks em Testes**: Use `clear_all_tool_call_hooks()` entre execuções de teste +8. **Modifique In-Place**: Sempre modifique `context.tool_input` in-place, nunca substitua +9. **Registre Decisões Importantes**: Especialmente ao bloquear execução de ferramenta +10. **Considere Performance**: Cache validações caras quando possível + +## Tratamento de Erros + +```python +@before_tool_call +def safe_validation(context: ToolCallHookContext) -> bool | None: + try: + # Sua lógica de validação + if not validate_input(context.tool_input): + return False + except Exception as e: + print(f"⚠️ Erro no hook: {e}") + # Decida: permitir ou bloquear em erro + return None # Permitir execução apesar do erro +``` + +## Segurança de Tipos + +```python +from crewai.hooks import ToolCallHookContext, BeforeToolCallHookType, AfterToolCallHookType + +# Anotações de tipo explícitas +def my_before_hook(context: ToolCallHookContext) -> bool | None: + return None + +def my_after_hook(context: ToolCallHookContext) -> str | None: + return None + +# Registro type-safe +register_before_tool_call_hook(my_before_hook) +register_after_tool_call_hook(my_after_hook) +``` + +## Solução de Problemas + +### Hook Não Está Executando +- Verifique se hook está registrado antes da execução da crew +- Verifique se hook anterior retornou `False` (bloqueia execução e hooks subsequentes) +- Garanta que assinatura do hook corresponda ao tipo esperado + +### Modificações de Entrada Não Funcionam +- Use modificações in-place: `context.tool_input['key'] = value` +- Não substitua o dict: `context.tool_input = {}` + +### Modificações de Resultado Não Funcionam +- Retorne a string modificada dos hooks posteriores +- Retornar `None` mantém o resultado original +- Garanta que a ferramenta realmente retornou um resultado + +### Ferramenta Bloqueada Inesperadamente +- Verifique todos os hooks antes por condições de bloqueio +- Verifique ordem de execução do hook +- Adicione logging de debug para identificar qual hook está bloqueando + +## Conclusão + +Os Hooks de Chamada de Ferramenta fornecem capacidades poderosas para controlar e monitorar execução de ferramentas no CrewAI. Use-os para implementar guardrails de segurança, gates de aprovação, validação de entrada, sanitização de resultado, logging e análise. Combinados com tratamento adequado de erros e segurança de tipos, os hooks permitem sistemas de agentes seguros e prontos para produção com observabilidade abrangente. + diff --git a/docs/v1.15.1/pt-BR/learn/using-annotations.mdx b/docs/v1.15.1/pt-BR/learn/using-annotations.mdx new file mode 100644 index 000000000..1bb936f35 --- /dev/null +++ b/docs/v1.15.1/pt-BR/learn/using-annotations.mdx @@ -0,0 +1,155 @@ +--- +title: "Usando Anotações no crew.py" +description: "Aprenda como usar anotações para estruturar corretamente agentes, tarefas e componentes no CrewAI" +icon: "at" +mode: "wide" +--- + +Este guia explica como utilizar anotações para referenciar corretamente **agentes**, **tarefas** e outros componentes em um arquivo `crew.py` clássico. + + +Novos projetos criados com `crewai create crew ` são JSON-first e usam `crew.jsonc` com `agents/*.jsonc`. Use este guia ao trabalhar em um projeto clássico criado com `crewai create crew --classic`, ao migrar um projeto Python/YAML existente ou quando precisar de controle via decorators em Python. + + +## 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. Em projetos clássicos Python/YAML, elas organizam o código que carrega `config/agents.yaml`, `config/tasks.yaml` e retorna o objeto `Crew`. + +## 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. + + +`@CrewBase` faz bem mais do que registrar a classe: + +- **Inicialização de configuração:** busca `agents_config` e `tasks_config` (padrões `config/agents.yaml` e `config/tasks.yaml`) ao lado do arquivo da classe, carrega esses YAMLs na inicialização e utiliza dicionários vazios quando os arquivos não existem. +- **Orquestração de decoradores:** mantém versões memoizadas dos métodos marcados com `@agent`, `@task`, `@before_kickoff` e `@after_kickoff` para que sejam instanciados uma única vez por crew e respeitem a ordem de declaração. +- **Encadeamento de hooks:** conecta automaticamente os hooks preservados ao objeto `Crew` retornado pelo método `@crew`, garantindo que executem antes e depois de `.kickoff()`. +- **Integração MCP:** quando a classe define `mcp_server_params`, `get_mcp_tools()` cria sob demanda um adaptador MCP, carrega as ferramentas declaradas e um hook interno pós-kickoff encerra o adaptador. Consulte a [visão geral de MCP](/pt-BR/mcp/overview) para detalhes de configuração. + + +### 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 Clássica + +Em projetos clássicos, 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**: Em projetos clássicos, 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á manter crews clássicos bem estruturados. Para novas crews, prefira a estrutura JSON-first em [Crews](/pt-BR/concepts/crews). diff --git a/docs/v1.15.1/pt-BR/mcp/dsl-integration.mdx b/docs/v1.15.1/pt-BR/mcp/dsl-integration.mdx new file mode 100644 index 000000000..ec036e420 --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/dsl-integration.mdx @@ -0,0 +1,234 @@ +--- +title: Integração DSL MCP +description: Aprenda a usar a sintaxe DSL simples do CrewAI para integrar servidores MCP diretamente com seus agentes usando o campo mcps. +icon: code +mode: "wide" +--- + +## Visão Geral + +A integração DSL (Domain Specific Language) MCP do CrewAI oferece a **forma mais simples** de conectar seus agentes aos servidores MCP (Model Context Protocol). Basta adicionar um campo `mcps` ao seu agente e o CrewAI cuida de toda a complexidade automaticamente. + + + Esta é a **abordagem recomendada** para a maioria dos casos de uso de MCP. + Para cenários avançados que requerem gerenciamento manual de conexão, veja + [MCPServerAdapter](/pt-BR/mcp/overview#advanced-mcpserveradapter). + + +## Uso Básico + +Adicione servidores MCP ao seu agente usando o campo `mcps`: + +```python +from crewai import Agent + +agent = Agent( + role="Assistente de Pesquisa", + goal="Ajudar com tarefas de pesquisa e análise", + backstory="Assistente especialista com acesso a ferramentas avançadas de pesquisa", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=sua_chave&profile=pesquisa" + ] +) + +# As ferramentas MCP agora estão automaticamente disponíveis! +# Não é necessário gerenciamento manual de conexão ou configuração de ferramentas +``` + +## Formatos de Referência Suportados + +### Servidores MCP Remotos Externos + +```python +# Servidor HTTPS básico +"https://api.example.com/mcp" + +# Servidor com autenticação +"https://mcp.exa.ai/mcp?api_key=sua_chave&profile=seu_perfil" + +# Servidor com caminho personalizado +"https://services.company.com/api/v1/mcp" +``` + +### Seleção de Ferramentas Específicas + +Use a sintaxe `#` para selecionar ferramentas específicas de um servidor: + +```python +# Obter apenas a ferramenta de previsão do servidor meteorológico +"https://weather.api.com/mcp#get_forecast" + +# Obter apenas a ferramenta de busca do Exa +"https://mcp.exa.ai/mcp?api_key=sua_chave#web_search_exa" +``` + +### Integrações MCP Conectadas + +Conecte servidores MCP do catálogo CrewAI ou traga os seus próprios. Uma vez conectados em sua conta, referencie-os pelo slug: + +```python +# MCP conectado com todas as ferramentas +"snowflake" + +# Ferramenta específica de um MCP conectado +"stripe#list_invoices" + +# Múltiplos MCPs conectados +mcps=[ + "snowflake", + "stripe", + "github" +] +``` + +## Exemplo Completo + +Aqui está um exemplo completo usando múltiplos servidores MCP: + +```python +from crewai import Agent, Task, Crew, Process + +# Criar agente com múltiplas fontes MCP +agente_multi_fonte = Agent( + role="Analista de Pesquisa Multi-Fonte", + goal="Conduzir pesquisa abrangente usando múltiplas fontes de dados", + backstory="""Pesquisador especialista com acesso a busca web, dados meteorológicos, + informações financeiras e ferramentas de pesquisa acadêmica""", + mcps=[ + # Servidores MCP externos + "https://mcp.exa.ai/mcp?api_key=sua_chave_exa&profile=pesquisa", + "https://weather.api.com/mcp#get_current_conditions", + + # MCPs conectados do catálogo + "snowflake", + "stripe#list_invoices", + "github#search_repositories" + ] +) + +# Criar tarefa de pesquisa abrangente +tarefa_pesquisa = Task( + description="""Pesquisar o impacto dos agentes de IA na produtividade empresarial. + Incluir impactos climáticos atuais no trabalho remoto, tendências do mercado financeiro, + e publicações acadêmicas recentes sobre frameworks de agentes de IA.""", + expected_output="""Relatório abrangente cobrindo: + 1. Análise do impacto dos agentes de IA nos negócios + 2. Considerações climáticas para trabalho remoto + 3. Tendências do mercado financeiro relacionadas à IA + 4. Citações e insights de pesquisa acadêmica + 5. Análise do cenário competitivo""", + agent=agente_multi_fonte +) + +# Criar e executar crew +crew_pesquisa = Crew( + agents=[agente_multi_fonte], + tasks=[tarefa_pesquisa], + process=Process.sequential, + verbose=True +) + +resultado = crew_pesquisa.kickoff() +print(f"Pesquisa concluída com {len(agente_multi_fonte.mcps)} fontes de dados MCP") +``` + +## Recursos Principais + +- 🔄 **Descoberta Automática de Ferramentas**: Ferramentas são descobertas e integradas automaticamente +- 🏷️ **Prevenção de Colisão de Nomes**: Nomes de servidor são prefixados aos nomes das ferramentas +- ⚡ **Otimizado para Performance**: Conexões sob demanda com cache de esquemas +- 🛡️ **Resiliência a Erros**: Tratamento gracioso de servidores indisponíveis +- ⏱️ **Proteção por Timeout**: Timeouts integrados previnem conexões travadas +- 📊 **Integração Transparente**: Funciona perfeitamente com recursos existentes do CrewAI + +## Tratamento de Erros + +A integração DSL MCP é projetada para ser resiliente: + +```python +agente = Agent( + role="Agente Resiliente", + goal="Continuar trabalhando apesar de problemas no servidor", + backstory="Agente que lida graciosamente com falhas", + mcps=[ + "https://servidor-confiavel.com/mcp", # Vai funcionar + "https://servidor-inalcancavel.com/mcp", # Será ignorado graciosamente + "https://servidor-lento.com/mcp", # Timeout gracioso + "snowflake" # MCP conectado do catálogo + ] +) +# O agente usará ferramentas de servidores funcionais e registrará avisos para os que falharem +``` + +## Recursos de Performance + +### Cache Automático + +Esquemas de ferramentas são cacheados por 5 minutos para melhorar a performance: + +```python +# Primeira criação de agente - descobre ferramentas do servidor +agente1 = Agent(role="Primeiro", goal="Teste", backstory="Teste", + mcps=["https://api.example.com/mcp"]) + +# Segunda criação de agente (dentro de 5 minutos) - usa esquemas cacheados +agente2 = Agent(role="Segundo", goal="Teste", backstory="Teste", + mcps=["https://api.example.com/mcp"]) # Muito mais rápido! +``` + +### Conexões Sob Demanda + +Conexões de ferramentas são estabelecidas apenas quando as ferramentas são realmente usadas: + +```python +# Criação do agente é rápida - nenhuma conexão MCP feita ainda +agente = Agent( + role="Agente Sob Demanda", + goal="Usar ferramentas eficientemente", + backstory="Agente eficiente que conecta apenas quando necessário", + mcps=["https://api.example.com/mcp"] +) + +# Conexão MCP é feita apenas quando uma ferramenta é realmente executada +# Isso minimiza o overhead de conexão e melhora a performance de inicialização +``` + +## Melhores Práticas + +### 1. Use Ferramentas Específicas Quando Possível + +```python +# Bom - obter apenas as ferramentas necessárias +mcps=["https://weather.api.com/mcp#get_forecast"] + +# Menos eficiente - obter todas as ferramentas do servidor +mcps=["https://weather.api.com/mcp"] +``` + +### 2. Lidar com Autenticação de Forma Segura + +```python +import os + +# Armazenar chaves API em variáveis de ambiente +exa_key = os.getenv("EXA_API_KEY") +exa_profile = os.getenv("EXA_PROFILE") + +agente = Agent( + role="Agente Seguro", + goal="Usar ferramentas MCP com segurança", + backstory="Agente consciente da segurança", + mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"] +) +``` + +### 3. Planejar para Falhas de Servidor + +```python +# Sempre incluir opções de backup +mcps=[ + "https://api-principal.com/mcp", # Escolha principal + "https://api-backup.com/mcp", # Opção de backup + "snowflake" # Fallback MCP conectado +] +``` diff --git a/docs/v1.15.1/pt-BR/mcp/multiple-servers.mdx b/docs/v1.15.1/pt-BR/mcp/multiple-servers.mdx new file mode 100644 index 000000000..911a1603e --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/multiple-servers.mdx @@ -0,0 +1,65 @@ +--- +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 +mode: "wide" +--- + +## 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]}") + + agente_multiservidor = Agent( + role="Assistente Versátil", + goal="Utilizar ferramentas de servidores MCP locais Stdio, remotos SSE e remotos HTTP.", + backstory="Um agente de IA capaz de aproveitar um conjunto diversificado de ferramentas de múltiplas fontes.", + tools=aggregated_tools, # Todas as ferramentas estão disponíveis aqui + 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/v1.15.1/pt-BR/mcp/overview.mdx b/docs/v1.15.1/pt-BR/mcp/overview.mdx new file mode 100644 index 000000000..4fc1bdab0 --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/overview.mdx @@ -0,0 +1,329 @@ +--- +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 +mode: "wide" +--- + +## 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. + +O CrewAI oferece **duas abordagens** para integração MCP: + +### 🚀 **Novo: Integração DSL Simples** (Recomendado) + +Use o campo `mcps` diretamente nos agentes para integração perfeita de ferramentas MCP: + +```python +from crewai import Agent + +agent = Agent( + role="Analista de Pesquisa", + goal="Pesquisar e analisar informações", + backstory="Pesquisador especialista com acesso a ferramentas externas", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=sua_chave", # Servidor MCP externo + "https://api.weather.com/mcp#get_forecast", # Ferramenta específica do servidor + "snowflake", # MCP conectado do catálogo + "stripe#list_invoices" # Ferramenta específica de MCP conectado + ] +) +# Ferramentas MCP agora estão automaticamente disponíveis para seu agente! +``` + +### 🔧 **Avançado: MCPServerAdapter** (Para Cenários Complexos) + +Para casos de uso avançados que requerem gerenciamento manual de conexão, a biblioteca `crewai-tools` fornece a classe `MCPServerAdapter`. + +Atualmente, suportamos os seguintes mecanismos de transporte: + +- **HTTPS**: para servidores remotos (comunicação segura via HTTPS) +- **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. + +## Configuração de Conexão + +O `MCPServerAdapter` suporta várias opções de configuração para personalizar o comportamento da conexão: + +- **`connect_timeout`** (opcional): Tempo máximo em segundos para aguardar o estabelecimento de uma conexão com o servidor MCP. O padrão é 30 segundos se não especificado. Isso é particularmente útil para servidores remotos que podem ter tempos de resposta variáveis. + +```python +# Exemplo com timeout personalizado para conexão +with MCPServerAdapter(server_params, connect_timeout=60) as tools: + # A conexão terá timeout após 60 segundos se não estabelecida + pass +``` + +```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, connect_timeout=60) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + meu_agente = Agent( + role="Usuário de Ferramentas MCP", + goal="Utilizar ferramentas de um servidor MCP.", + backstory="Posso conectar a servidores MCP e usar suas ferramentas.", + 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, connect_timeout=60) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + meu_agente = Agent( + role="Usuário de Ferramentas MCP", + goal="Utilizar ferramentas de um servidor MCP.", + backstory="Posso conectar a servidores MCP e usar suas ferramentas.", + 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 `get_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()) # obter todas as ferramentas disponíveis + + # ... restante da configuração do seu crew ... +``` + + +Quando uma classe é decorada com `@CrewBase`, o ciclo de vida do adaptador é controlado automaticamente: + +- A primeira chamada a `get_mcp_tools()` cria de forma preguiçosa um `MCPServerAdapter` compartilhado que é reutilizado por todos os agentes do crew. +- Após a conclusão de `.kickoff()`, um hook pós-kickoff injetado por `@CrewBase` encerra o adaptador, dispensando qualquer limpeza manual. +- Se `mcp_server_params` não estiver definido, `get_mcp_tools()` retorna uma lista vazia, permitindo manter o mesmo fluxo de código com ou sem MCP configurado. + +Assim, é seguro chamar `get_mcp_tools()` em vários agentes ou habilitar/desabilitar MCP dependendo do ambiente. + + + +### Configuração de Timeout de Conexão + +Você pode configurar o timeout de conexão para servidores MCP definindo o atributo de classe `mcp_connect_timeout`. Se nenhum timeout for especificado, o padrão é 30 segundos. + +```python +@CrewBase +class CrewWithMCP: + mcp_server_params = [...] + mcp_connect_timeout = 60 # timeout de 60 segundos para todas as conexões MCP + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +```python +@CrewBase +class CrewWithDefaultTimeout: + mcp_server_params = [...] + # Nenhum mcp_connect_timeout especificado - usa padrão de 30 segundos + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +### Filtragem de Ferramentas + +Você pode filtrar quais ferramentas estão disponíveis para seu agente passando uma lista de nomes de ferramentas para o método `get_mcp_tools`. + +```python +@agent +def another_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # obter ferramentas específicas + ) +``` + +A configuração de timeout se aplica a todas as chamadas de ferramentas MCP dentro do crew: + +```python +@CrewBase +class CrewWithCustomTimeout: + mcp_server_params = [...] + mcp_connect_timeout = 90 # timeout de 90 segundos para todas as conexões MCP + + @agent + def filtered_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # ferramentas específicas com timeout personalizado + ) +``` + +## 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/v1.15.1/pt-BR/mcp/security.mdx b/docs/v1.15.1/pt-BR/mcp/security.mdx new file mode 100644 index 000000000..c62f1d9bc --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/security.mdx @@ -0,0 +1,166 @@ +--- +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 +mode: "wide" +--- + +## 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/v1.15.1/pt-BR/mcp/sse.mdx b/docs/v1.15.1/pt-BR/mcp/sse.mdx new file mode 100644 index 000000000..c44006fb3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/sse.mdx @@ -0,0 +1,151 @@ +--- +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 +mode: "wide" +--- + +## 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 + agente_sse = Agent( + role="Usuário de Serviço Remoto", + goal="Utilizar uma ferramenta fornecida por um servidor MCP remoto via SSE.", + backstory="Um agente de IA que conecta a serviços externos via SSE.", + tools=tools, + reasoning=True, + verbose=True, + ) + + sse_task = Task( + description="Buscar atualizações em tempo real das ações 'AAPL' usando uma ferramenta SSE.", + expected_output="O preço mais recente da ação AAPL.", + agent=agente_sse, + markdown=True + ) + + sse_crew = Crew( + agents=[agente_sse], + 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="Analista Remoto de Dados", + goal="Analisar dados obtidos de um servidor MCP remoto SSE usando gerenciamento manual de conexão.", + backstory="Um agente de IA especializado em gerenciar conexões SSE explicitamente.", + tools=tools, + verbose=True + ) + + analysis_task = Task( + description="Buscar e analisar as tendências mais recentes de atividade de usuários do servidor SSE.", + expected_output="Um relatório resumido das tendências de atividade dos usuários.", + 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/v1.15.1/pt-BR/mcp/stdio.mdx b/docs/v1.15.1/pt-BR/mcp/stdio.mdx new file mode 100644 index 000000000..e2b4adf8b --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/stdio.mdx @@ -0,0 +1,134 @@ +--- +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 +mode: "wide" +--- + +## 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 + pesquisador_local = Agent( + role="Processador Local de Dados", + goal="Processar dados usando uma ferramenta local baseada em Stdio.", + backstory="Uma IA que utiliza scripts locais via MCP para tarefas especializadas.", + tools=tools, + reasoning=True, + verbose=True, + ) + + processing_task = Task( + description="Processar o arquivo de dados de entrada 'data.txt' e resumir seu conteúdo.", + expected_output="Um resumo dos dados processados.", + agent=pesquisador_local, + markdown=True + ) + + data_crew = Crew( + agents=[pesquisador_local], + 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="Executor Local de Tarefas", + goal="Executar uma tarefa local específica usando uma ferramenta Stdio gerenciada manualmente.", + backstory="Uma IA proficiente em controlar processos locais via MCP.", + tools=tools, + verbose=True + ) + + manual_task = Task( + description="Executar o comando 'perform_analysis' via ferramenta Stdio.", + expected_output="Resultados da análise.", + 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/v1.15.1/pt-BR/mcp/streamable-http.mdx b/docs/v1.15.1/pt-BR/mcp/streamable-http.mdx new file mode 100644 index 000000000..7884968d7 --- /dev/null +++ b/docs/v1.15.1/pt-BR/mcp/streamable-http.mdx @@ -0,0 +1,136 @@ +--- +title: Transporte HTTP Streamable +description: Saiba como conectar o CrewAI a servidores MCP remotos usando o transporte HTTP Streamable flexível. +icon: globe +mode: "wide" +--- + +## 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]}") + + agente_http = Agent( + role="Integrador de Serviços HTTP", + goal="Utilizar ferramentas de um servidor MCP remoto via Streamable HTTP.", + backstory="Um agente de IA especializado em interagir com serviços web complexos.", + tools=tools, + verbose=True, + ) + + http_task = Task( + description="Realizar uma consulta de dados complexa usando uma ferramenta do servidor Streamable HTTP.", + expected_output="O resultado da consulta de dados complexa.", + agent=agente_http, + ) + + http_crew = Crew( + agents=[agente_http], + 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="Usuário Avançado de Serviços Web", + goal="Interagir com um servidor MCP usando conexões HTTP Streamable gerenciadas manualmente.", + backstory="Um especialista em IA em ajustar integrações baseadas em HTTP.", + tools=tools, + verbose=True + ) + + data_processing_task = Task( + description="Enviar dados para processamento e recuperar resultados via Streamable HTTP.", + expected_output="Dados processados ou confirmação.", + 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/v1.15.1/pt-BR/observability/arize-phoenix.mdx b/docs/v1.15.1/pt-BR/observability/arize-phoenix.mdx new file mode 100644 index 000000000..df1402054 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/arize-phoenix.mdx @@ -0,0 +1,145 @@ +--- +title: Arize Phoenix +description: Integração do Arize Phoenix para CrewAI com OpenTelemetry e OpenInference +icon: magnifying-glass-chart +mode: "wide" +--- + +# 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 +pesquisador = Agent( + role="Analista Sênior de Pesquisa", + goal="Descobrir os avanços mais recentes em IA e ciência de dados", + backstory=""" +Você trabalha em um importante think tank de tecnologia. Sua especialidade é identificar tendências emergentes. Você tem habilidade para dissecar dados complexos e apresentar insights acionáveis. +""", + verbose=True, + allow_delegation=False, + tools=[search_tool], +) +writer = Agent( + role="Estrategista de Conteúdo Técnico", + goal="Criar conteúdo envolvente sobre avanços tecnológicos", + backstory="Você é um Estrategista de Conteúdo renomado, conhecido por seus artigos perspicazes e envolventes. Você transforma conceitos complexos em narrativas atraentes.", + verbose=True, + allow_delegation=True, +) + +# Crie tarefas para seus agentes +task1 = Task( + description="Realize uma análise abrangente dos avanços mais recentes em IA em 2024. Identifique tendências-chave, tecnologias inovadoras e impactos potenciais na indústria.", + expected_output="Relatório analítico completo em tópicos", + agent=pesquisador, +) + +task2 = Task( + description="Utilizando os insights fornecidos, desenvolva um blog envolvente destacando os avanços mais significativos em IA. O post deve ser informativo e acessível, voltado para um público técnico. Dê um tom interessante, evite palavras complexas para não soar como IA.", + expected_output="Post de blog completo com pelo menos 4 parágrafos", + agent=writer, +) + +# Instancie seu crew com um processo sequencial +crew = Crew( + agents=[pesquisador, 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/v1.15.1/pt-BR/observability/braintrust.mdx b/docs/v1.15.1/pt-BR/observability/braintrust.mdx new file mode 100644 index 000000000..c0a19cfa3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/braintrust.mdx @@ -0,0 +1,237 @@ +--- +title: Braintrust +description: Integração do Braintrust para CrewAI com rastreamento OpenTelemetry e avaliação +icon: magnifying-glass-chart +mode: "wide" +--- + +# Integração Braintrust + +Este guia demonstra como integrar o **Braintrust** com **CrewAI** usando OpenTelemetry para rastreamento e avaliação abrangentes. Ao final deste guia, você poderá rastrear seus agentes CrewAI, monitorar seu desempenho e avaliar suas saídas usando a poderosa plataforma de observabilidade do Braintrust. + +> **O que é Braintrust?** [Braintrust](https://www.braintrust.dev) é uma plataforma de avaliação e observabilidade de IA que fornece rastreamento, avaliação e monitoramento abrangentes para aplicações de IA com rastreamento de experimentos e análises de desempenho integrados. + +## Começar + +Vamos percorrer um exemplo simples de uso do CrewAI e integração com Braintrust via OpenTelemetry para observabilidade e avaliação abrangentes. + +### Passo 1: Instalar Dependências + +```bash +uv add braintrust[otel] crewai crewai-tools opentelemetry-instrumentation-openai opentelemetry-instrumentation-crewai python-dotenv +``` + +### Passo 2: Configurar Variáveis de Ambiente + +Configure as chaves de API do Braintrust e configure o OpenTelemetry para enviar rastreamentos para o Braintrust. Você precisará de uma chave de API do Braintrust e sua chave de API do OpenAI. + +```python +import os +from getpass import getpass + +# Obter suas credenciais do Braintrust +BRAINTRUST_API_KEY = getpass("🔑 Digite sua Chave de API do Braintrust: ") + +# Obter chaves de API para serviços +OPENAI_API_KEY = getpass("🔑 Digite sua chave de API do OpenAI: ") + +# Configurar variáveis de ambiente +os.environ["BRAINTRUST_API_KEY"] = BRAINTRUST_API_KEY +os.environ["BRAINTRUST_PARENT"] = "project_name:crewai-demo" +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +``` + +### Passo 3: Inicializar OpenTelemetry com Braintrust + +Inicialize a instrumentação OpenTelemetry do Braintrust para começar a capturar rastreamentos e enviá-los para o Braintrust. + +```python +import os +from typing import Any, Dict + +from braintrust.otel import BraintrustSpanProcessor +from crewai import Agent, Crew, Task +from crewai.llm import LLM +from opentelemetry import trace +from opentelemetry.instrumentation.crewai import CrewAIInstrumentor +from opentelemetry.instrumentation.openai import OpenAIInstrumentor +from opentelemetry.sdk.trace import TracerProvider + +def setup_tracing() -> None: + """Configurar rastreamento OpenTelemetry com Braintrust.""" + current_provider = trace.get_tracer_provider() + if isinstance(current_provider, TracerProvider): + provider = current_provider + else: + provider = TracerProvider() + trace.set_tracer_provider(provider) + + provider.add_span_processor(BraintrustSpanProcessor()) + CrewAIInstrumentor().instrument(tracer_provider=provider) + OpenAIInstrumentor().instrument(tracer_provider=provider) + + +setup_tracing() +``` + +### Passo 4: Criar uma Aplicação CrewAI + +Vamos criar uma aplicação CrewAI onde dois agentes colaboram para pesquisar e escrever um post de blog sobre avanços em IA, com rastreamento abrangente habilitado. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +def create_crew() -> Crew: + """Criar uma crew com múltiplos agentes para rastreamento abrangente.""" + llm = LLM(model="gpt-4o-mini") + search_tool = SerperDevTool() + + # Definir agentes com papéis específicos + researcher = Agent( + role="Analista de Pesquisa Sênior", + goal="Descobrir desenvolvimentos de ponta em IA e ciência de dados", + backstory="""Você trabalha em um think tank de tecnologia líder. + Sua especialidade está em identificar tendências emergentes. + Você tem talento para dissecar dados complexos e apresentar insights acionáveis.""", + verbose=True, + allow_delegation=False, + llm=llm, + tools=[search_tool], + ) + + writer = Agent( + role="Estrategista de Conteúdo Tecnológico", + goal="Criar conteúdo envolvente sobre avanços tecnológicos", + backstory="""Você é um Estrategista de Conteúdo renomado, conhecido por seus artigos perspicazes e envolventes. + Você transforma conceitos complexos em narrativas convincentes.""", + verbose=True, + allow_delegation=True, + llm=llm, + ) + + # Criar tarefas para seus agentes + research_task = Task( + description="""Realize uma análise abrangente dos últimos avanços em {topic}. + Identifique tendências principais, tecnologias revolucionárias e impactos potenciais na indústria.""", + expected_output="Relatório de análise completo em pontos de bala", + agent=researcher, + ) + + writing_task = Task( + description="""Usando os insights fornecidos, desenvolva um post de blog envolvente + que destaque os avanços mais significativos em {topic}. + Seu post deve ser informativo, mas acessível, atendendo a um público conhecedor de tecnologia. + Faça soar legal, evite palavras complexas para não soar como IA.""", + expected_output="Post de blog completo de pelo menos 4 parágrafos", + agent=writer, + context=[research_task], + ) + + # Instanciar sua crew com um processo sequencial + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential + ) + + return crew + +def run_crew(): + """Executar a crew e retornar resultados.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": "desenvolvimentos em IA"}) + return result + +# Executar sua crew +if __name__ == "__main__": + # A instrumentação já foi inicializada acima neste módulo + result = run_crew() + print(result) +``` + +### Passo 5: Visualizar Rastreamentos no Braintrust + +Após executar sua crew, você pode visualizar rastreamentos abrangentes no Braintrust através de diferentes perspectivas: + + + + + Visualização de Rastreamento Braintrust + + + + + + Visualização de Linha do Tempo Braintrust + + + + + + Visualização de Thread Braintrust + + + + +### Passo 6: Avaliar via SDK (Experimentos) + +Você também pode executar avaliações usando o Eval SDK do Braintrust. Isso é útil para comparar versões ou pontuar saídas offline. Abaixo está um exemplo em Python usando a classe `Eval` com a crew que criamos acima: + +```python +# eval_crew.py +from braintrust import Eval +from autoevals import Levenshtein + +def evaluate_crew_task(input_data): + """Função de tarefa que envolve nossa crew para avaliação.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": input_data["topic"]}) + return str(result) + +Eval( + "Crew de Pesquisa em IA", # Nome do projeto + { + "data": lambda: [ + {"topic": "tendências de inteligência artificial 2024"}, + {"topic": "avanços em aprendizado de máquina"}, + {"topic": "ética e governança de IA"}, + ], + "task": evaluate_crew_task, + "scores": [Levenshtein], + }, +) +``` + +Configure sua chave de API e execute: + +```bash +export BRAINTRUST_API_KEY="YOUR_API_KEY" +braintrust eval eval_crew.py +``` + +Veja o [guia do Eval SDK do Braintrust](https://www.braintrust.dev/docs/start/eval-sdk) para mais detalhes. + +### Principais Recursos da Integração Braintrust + +- **Rastreamento Abrangente**: Rastreie todas as interações de agentes, uso de ferramentas e chamadas LLM +- **Monitoramento de Desempenho**: Monitore tempos de execução, uso de tokens e taxas de sucesso +- **Rastreamento de Experimentos**: Compare diferentes configurações de crew e modelos +- **Avaliação Automatizada**: Configure métricas de avaliação personalizadas para saídas de crew +- **Rastreamento de Erros**: Monitore e depure falhas em suas execuções de crew +- **Análise de Custos**: Rastreie uso de tokens e custos associados + +### Informações de Compatibilidade de Versão +- Python 3.8+ +- CrewAI >= 0.86.0 +- Braintrust >= 0.1.0 +- OpenTelemetry SDK >= 1.31.0 + +### Referências +- [Documentação Braintrust](https://www.braintrust.dev/docs) - Visão geral da plataforma Braintrust +- [Integração CrewAI Braintrust](https://www.braintrust.dev/docs/integrations/crew-ai) - Guia oficial de integração CrewAI +- [Eval SDK Braintrust](https://www.braintrust.dev/docs/start/eval-sdk) - Execute experimentos via SDK +- [Documentação CrewAI](https://docs.crewai.com/) - Visão geral do framework CrewAI +- [Documentação OpenTelemetry](https://opentelemetry.io/docs/) - Guia OpenTelemetry +- [GitHub Braintrust](https://github.com/braintrustdata/braintrust) - Código fonte do SDK Braintrust diff --git a/docs/v1.15.1/pt-BR/observability/datadog.mdx b/docs/v1.15.1/pt-BR/observability/datadog.mdx new file mode 100644 index 000000000..a357fea83 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/datadog.mdx @@ -0,0 +1,108 @@ +--- +title: Integração Datadog +description: Saiba como integrar o Datadog com o CrewAI para enviar os rastros de observabilidade do LLM para o Datadog. +icon: dog +mode: "wide" +--- + +# Integrar o Datadog com a CrewAI + +Este guia demonstrará como integrar o **Datadog** com o **CrewAI** usando a instrumentação automática do Datadog. Ao final deste guia, você poderá enviar rastreamentos do LLM Observability para o Datadog e visualizar as execuções do agente CrewAI no Agentic Execution View do Datadog LLM Observability. + +## O que é o Datadog LLM Observability? + +O [Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) ajuda os engenheiros de IA, cientistas de dados e desenvolvedores de aplicativos a desenvolver, avaliar e monitorar rapidamente os aplicativos LLM. Melhore com confiança a qualidade dos resultados, o desempenho, os custos e o risco geral com experimentos estruturados, rastreamento de ponta a ponta em agentes de IA e avaliações. + +## Primeiros passos + +### Instalar dependências + +```shell +pip install ddtrace crewai crewai-tools +``` + +### Definir variáveis de ambiente + +Se você não tiver uma chave de API da Datadog, poderá [criar uma conta](https://www.datadoghq.com/) e [obter sua chave de API](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + +Você também precisará especificar um nome de aplicativo de ML nas seguintes variáveis de ambiente. Um aplicativo de ML é um agrupamento de rastros de observabilidade do LLM associados a um aplicativo específico baseado em LLM. Consulte [ML Application Naming Guidelines](https://docs.datadoghq.com/llm_observability/instrumentation/sdk?tab=python#application-naming-guidelines) para obter mais informações sobre as limitações dos nomes de aplicativos do ML. + +```shell +export DD_API_KEY= +export DD_SITE= +export DD_LLMOBS_ENABLED=true +export DD_LLMOBS_ML_APP= +export DD_LLMOBS_AGENTLESS_ENABLED=true +export DD_APM_TRACING_ENABLED=false +``` + +Além disso, configure todas as chaves de API do provedor LLM + +```shell +export OPENAI_API_KEY= +export ANTHROPIC_API_KEY= +export GEMINI_API_KEY= +... +``` + +### Criar um aplicativo agente CrewAI + +```python +# crewai_agent.py +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 por meio da poesia", + backstory="Você é um especialista em escrever haikus, 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 +) + +output = crew.kickoff(dict(multiplicação="2 * 2")) +``` + +### Executar o aplicativo com a instrumentação automática do Datadog + +Com as [variáveis de ambiente](#definir-variáveis-de-ambiente) definidas, agora você pode executar o aplicativo com a instrumentação automática do Datadog. + +```shell +ddtrace-run python crewai_agent.py +``` + +### Visualizar os rastros no Datadog + +Depois de executar o aplicativo, você pode visualizar os traços na [Datadog LLM Observability's Traces View](https://app.datadoghq.com/llm/traces), selecionando o nome do aplicativo de ML que você escolheu no menu suspenso superior esquerdo. + +Ao clicar em um rastreamento, você verá os detalhes do rastreamento, incluindo o total de tokens usados, o número de chamadas LLM, os modelos usados e o custo estimado. Clicar em um intervalo específico reduzirá esses detalhes e mostrará a entrada, a saída e os metadados relacionados. + + +Visualização do rastreamento de observabilidade do Datadog LLM + +Além disso, você pode visualizar a visualização do gráfico de execução do rastreamento, que mostra o controle e o fluxo de dados do rastreamento, que será dimensionado com agentes maiores para mostrar transferências e relacionamentos entre chamadas LLM, chamadas de ferramentas e interações de agentes. + + +Visualização do fluxo de execução do agente de observabilidade do Datadog LLM + + +## Referências + +- [Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) +- [Datadog LLM Observability CrewAI Auto-Instrumentation](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python#crew-ai) diff --git a/docs/v1.15.1/pt-BR/observability/galileo.mdx b/docs/v1.15.1/pt-BR/observability/galileo.mdx new file mode 100644 index 000000000..4296e35fb --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/galileo.mdx @@ -0,0 +1,115 @@ +--- +title: Galileo Galileu +description: Integração Galileo para rastreamento e avaliação CrewAI +icon: telescope +mode: "wide" +--- + +## Visão geral + +Este guia demonstra como integrar o **Galileo**com o **CrewAI** +para rastreamento abrangente e engenharia de avaliação. +Ao final deste guia, você será capaz de rastrear seus agentes CrewAI, +monitorar seu desempenho e avaliar seu comportamento com +A poderosa plataforma de observabilidade do Galileo. + +> **O que é Galileo?**[Galileo](https://galileo.ai/) é avaliação e observabilidade de IA +plataforma que oferece rastreamento, avaliação e +e monitoramento de aplicações de IA. Ele permite que as equipes capturem a verdade, +criar grades de proteção robustas e realizar experimentos sistemáticos com +rastreamento de experimentos integrado e análise de desempenho -garantindo confiabilidade, +transparência e melhoria contínua em todo o ciclo de vida da IA. + +## Primeiros passos + +Este tutorial segue o [CrewAI Quickstart](pt-BR/quickstart) e mostra como adicionar +[CrewAIEventListener] do Galileo(https://v2docs.galileo.ai/sdk-api/python/reference/handlers/crewai/handler), +um manipulador de eventos. +Para mais informações, consulte Galileu +[Adicionar Galileo a um aplicativo CrewAI](https://v2docs.galileo.ai/how-to-guides/third-party-integrations/add-galileo-to-crewai/add-galileo-to-crewai) +guia prático. + +> **Observação**Este tutorial pressupõe que você concluiu o [CrewAI Quickstart](pt-BR/quickstart). +Se você quiser um exemplo completo e abrangente, consulte o Galileo +[Repositório de exemplo SDK da CrewAI](https://github.com/rungalileo/sdk-examples/tree/main/python/agent/crew-ai). + +### Etapa 1: instalar dependências + +Instale as dependências necessárias para seu aplicativo. +Crie um ambiente virtual usando seu método preferido, +em seguida, instale dependências dentro desse ambiente usando seu +ferramenta preferida: + +```bash +uv add galileo +``` + +### Etapa 2: adicione ao arquivo .env do [CrewAI Quickstart](/pt-BR/quickstart) + +```bash +# Your Galileo API key +GALILEO_API_KEY="your-galileo-api-key" + +# Your Galileo project name +GALILEO_PROJECT="your-galileo-project-name" + +# The name of the Log stream you want to use for logging +GALILEO_LOG_STREAM="your-galileo-log-stream " +``` + +### Etapa 3: adicionar o ouvinte de eventos Galileo + +Para habilitar o registro com Galileo, você precisa criar uma instância do `CrewAIEventListener`. +Importe o pacote manipulador Galileo CrewAI por +adicionando o seguinte código no topo do seu arquivo main.py: + +```python +from galileo.handlers.crewai.handler import CrewAIEventListener +``` + +No início da sua função run, crie o ouvinte de evento: + +```python +def run(): + # Create the event listener + CrewAIEventListener() + # The rest of your existing code goes here +``` + +Quando você cria a instância do listener, ela é automaticamente +registrado na CrewAI. + +### Etapa 4: administre sua Crew + +Administre sua Crew com o CrewAI CLI: + +```bash +crewai run +``` + +### Passo 5: Visualize os traços no Galileo + +Assim que sua tripulação terminar, os rastros serão eliminados e aparecerão no Galileo. + +![Galileo trace view](/images/galileo-trace-veiw.png) + +## Compreendendo a integração do Galileo + +Galileo se integra ao CrewAI registrando um ouvinte de evento +que captura eventos de execução da tripulação (por exemplo, ações do agente, chamadas de ferramentas, respostas do modelo) +e os encaminha ao Galileo para observabilidade e avaliação. + +### Compreendendo o ouvinte de eventos + +Criar uma instância `CrewAIEventListener()` é tudo o que você precisa +necessário para habilitar o Galileo para uma execução do CrewAI. Quando instanciado, o ouvinte: + +-Registra-se automaticamente no CrewAI +-Lê a configuração do Galileo a partir de variáveis de ambiente +-Registra todos os dados de execução no projeto Galileo e fluxo de log especificado por + `GALILEO_PROJECT` e `GALILEO_LOG_STREAM` + +Nenhuma configuração adicional ou alterações de código são necessárias. +Todos os dados desta execução são registados no projecto Galileo e +fluxo de log especificado pela configuração do seu ambiente +(por exemplo, GALILEO_PROJECT e GALILEO_LOG_STREAM). diff --git a/docs/v1.15.1/pt-BR/observability/langdb.mdx b/docs/v1.15.1/pt-BR/observability/langdb.mdx new file mode 100644 index 000000000..86b2aea82 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/langdb.mdx @@ -0,0 +1,287 @@ +--- +title: Integração LangDB +description: Governe, proteja e otimize seus fluxos de trabalho CrewAI com LangDB AI Gateway—acesse mais de 350 modelos, roteamento automático, otimização de custos e observabilidade completa. +icon: database +mode: "wide" +--- + +# Introdução + +[LangDB AI Gateway](https://langdb.ai) fornece APIs compatíveis com OpenAI para conectar com múltiplos Modelos de Linguagem Grandes e serve como uma plataforma de observabilidade que torna effortless rastrear fluxos de trabalho CrewAI de ponta a ponta, proporcionando acesso a mais de 350 modelos de linguagem. Com uma única chamada `init()`, todas as interações de agentes, execuções de tarefas e chamadas LLM são capturadas, fornecendo observabilidade abrangente e infraestrutura de IA pronta para produção para suas aplicações. + + + Exemplo de rastreamento CrewAI LangDB + + +**Confira:** [Ver o exemplo de trace ao vivo](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22) + +## Recursos + +### Capacidades do AI Gateway +- **Acesso a mais de 350 LLMs**: Conecte-se a todos os principais modelos de linguagem através de uma única integração +- **Modelos Virtuais**: Crie configurações de modelo personalizadas com parâmetros específicos e regras de roteamento +- **MCP Virtual**: Habilite compatibilidade e integração com sistemas MCP (Model Context Protocol) para comunicação aprimorada de agentes +- **Guardrails**: Implemente medidas de segurança e controles de conformidade para comportamento de agentes + +### Observabilidade e Rastreamento +- **Rastreamento Automático**: Uma única chamada `init()` captura todas as interações CrewAI +- **Visibilidade Ponta a Ponta**: Monitore fluxos de trabalho de agentes do início ao fim +- **Rastreamento de Uso de Ferramentas**: Rastreie quais ferramentas os agentes usam e seus resultados +- **Monitoramento de Chamadas de Modelo**: Insights detalhados sobre interações LLM +- **Análise de Performance**: Monitore latência, uso de tokens e custos +- **Suporte a Depuração**: Execução passo a passo para solução de problemas +- **Monitoramento em Tempo Real**: Dashboard de traces e métricas ao vivo + +## Instruções de Configuração + + + + Instale o cliente LangDB com flag de recurso CrewAI: + ```bash + pip install 'pylangdb[crewai]' + ``` + + + Configure suas credenciais LangDB: + ```bash + export LANGDB_API_KEY="" + export LANGDB_PROJECT_ID="" + export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + ``` + + + Importe e inicialize LangDB antes de configurar seu código CrewAI: + ```python + from pylangdb.crewai import init + # Inicializar LangDB + init() + ``` + + + Configure seu LLM com cabeçalhos LangDB: + ```python + from crewai import Agent, Task, Crew, LLM + import os + + # Configurar LLM com cabeçalhos LangDB + llm = LLM( + model="openai/gpt-4o", # Substitua pelo modelo que você quer usar + api_key=os.getenv("LANGDB_API_KEY"), + base_url=os.getenv("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.getenv("LANGDB_PROJECT_ID")} + ) + ``` + + + +## Exemplo de Início Rápido + +Aqui está um exemplo simples para começar com LangDB e CrewAI: + +```python +import os +from pylangdb.crewai import init +from crewai import Agent, Task, Crew, LLM + +# Inicializar LangDB antes de qualquer importação CrewAI +init() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +# Defina seu agente +researcher = Agent( + role="Especialista em Pesquisa", + goal="Pesquisar tópicos minuciosamente", + backstory="Pesquisador especialista com habilidades em encontrar informações", + llm=create_llm("openai/gpt-4o"), # Substitua pelo modelo que você quer usar + verbose=True +) + +# Criar uma tarefa +task = Task( + description="Pesquise o tópico dado e forneça um resumo abrangente", + agent=researcher, + expected_output="Resumo de pesquisa detalhado com principais descobertas" +) + +# Criar e executar a equipe +crew = Crew(agents=[researcher], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## Exemplo Completo: Agente de Pesquisa e Planejamento + +Este exemplo abrangente demonstra um fluxo de trabalho multi-agente com capacidades de pesquisa e planejamento. + +### Pré-requisitos + +```bash +pip install crewai 'pylangdb[crewai]' crewai_tools setuptools python-dotenv +``` + +### Configuração do Ambiente + +```bash +# Credenciais LangDB +export LANGDB_API_KEY="" +export LANGDB_PROJECT_ID="" +export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + +# Chaves API adicionais (opcional) +export SERPER_API_KEY="" # Para capacidades de busca na web +``` + +### Implementação Completa + +```python +#!/usr/bin/env python3 + +import os +import sys +from pylangdb.crewai import init +init() # Inicializar LangDB antes de qualquer importação CrewAI +from dotenv import load_dotenv +from crewai import Agent, Task, Crew, Process, LLM +from crewai_tools import SerperDevTool + +load_dotenv() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +class ResearchPlanningCrew: + def researcher(self) -> Agent: + return Agent( + role="Especialista em Pesquisa", + goal="Pesquisar tópicos minuciosamente e compilar informações abrangentes", + backstory="Pesquisador especialista com habilidades em encontrar e analisar informações de várias fontes", + tools=[SerperDevTool()], + llm=create_llm("openai/gpt-4o"), + verbose=True + ) + + def planner(self) -> Agent: + return Agent( + role="Planejador Estratégico", + goal="Criar planos acionáveis baseados em descobertas de pesquisa", + backstory="Planejador estratégico que divide desafios complexos em planos executáveis", + reasoning=True, + max_reasoning_attempts=3, + llm=create_llm("openai/anthropic/claude-3.7-sonnet"), + verbose=True + ) + + def research_task(self) -> Task: + return Task( + description="Pesquise o tópico minuciosamente e compile informações abrangentes", + agent=self.researcher(), + expected_output="Relatório de pesquisa abrangente com principais descobertas e insights" + ) + + def planning_task(self) -> Task: + return Task( + description="Crie um plano estratégico baseado nas descobertas da pesquisa", + agent=self.planner(), + expected_output="Plano de execução estratégica com fases, objetivos e etapas acionáveis", + context=[self.research_task()] + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.researcher(), self.planner()], + tasks=[self.research_task(), self.planning_task()], + verbose=True, + process=Process.sequential + ) + +def main(): + topic = sys.argv[1] if len(sys.argv) > 1 else "Inteligência Artificial na Saúde" + + crew_instance = ResearchPlanningCrew() + + # Atualizar descrições de tarefas com o tópico específico + crew_instance.research_task().description = f"Pesquise {topic} minuciosamente e compile informações abrangentes" + crew_instance.planning_task().description = f"Crie um plano estratégico para {topic} baseado nas descobertas da pesquisa" + + result = crew_instance.crew().kickoff() + print(result) + +if __name__ == "__main__": + main() +``` + +### Executando o Exemplo + +```bash +python main.py "Soluções de Energia Sustentável" +``` + +## Visualizando Traces no LangDB + +Após executar sua aplicação CrewAI, você pode visualizar traces detalhados no dashboard LangDB: + + + Dashboard de trace LangDB mostrando fluxo de trabalho CrewAI + + +### O Que Você Verá + +- **Interações de Agentes**: Fluxo completo de conversas de agentes e transferências de tarefas +- **Uso de Ferramentas**: Quais ferramentas foram chamadas, suas entradas e saídas +- **Chamadas de Modelo**: Interações LLM detalhadas com prompts e respostas +- **Métricas de Performance**: Rastreamento de latência, uso de tokens e custos +- **Linha do Tempo de Execução**: Visualização passo a passo de todo o fluxo de trabalho + + +## Solução de Problemas + +### Problemas Comuns + +- **Nenhum trace aparecendo**: Certifique-se de que `init()` seja chamado antes de qualquer importação CrewAI +- **Erros de autenticação**: Verifique sua chave API LangDB e ID do projeto + + +## Recursos + + + + Documentação oficial e guias LangDB + + + Tutoriais passo a passo para construir agentes de IA + + + Exemplos completos de integração CrewAI + + + Acesse seus traces e análises + + + Navegue por mais de 350 modelos de linguagem disponíveis + + + Opções auto-hospedadas e capacidades empresariais + + + +## Próximos Passos + +Este guia cobriu o básico da integração do LangDB AI Gateway com CrewAI. Para aprimorar ainda mais seus fluxos de trabalho de IA, explore: + +- **Modelos Virtuais**: Crie configurações de modelo personalizadas com estratégias de roteamento +- **Guardrails e Segurança**: Implemente filtragem de conteúdo e controles de conformidade +- **Implantação em Produção**: Configure fallbacks, tentativas e balanceamento de carga + +Para recursos mais avançados e casos de uso, visite a [Documentação LangDB](https://docs.langdb.ai) ou explore o [Catálogo de Modelos](https://app.langdb.ai/models) para descobrir todos os modelos disponíveis. \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/observability/langfuse.mdx b/docs/v1.15.1/pt-BR/observability/langfuse.mdx new file mode 100644 index 000000000..5381a9e96 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/langfuse.mdx @@ -0,0 +1,108 @@ +--- +title: Integração Langfuse +description: Saiba como integrar o Langfuse ao CrewAI via OpenTelemetry usando OpenLit +icon: vials +mode: "wide" +--- + +# 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() + +escritor = Agent( + role="Escritor", + 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], +) + +tarefa = Task(description=("O que é {multiplicação}?"), + expected_output=("Componha um haicai que inclua a resposta."), + agent=escritor) + +equipe = Crew( + agents=[escritor], + tasks=[tarefa], + 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/v1.15.1/pt-BR/observability/langtrace.mdx b/docs/v1.15.1/pt-BR/observability/langtrace.mdx new file mode 100644 index 000000000..470c42933 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/langtrace.mdx @@ -0,0 +1,73 @@ +--- +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 +mode: "wide" +--- + +# 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/v1.15.1/pt-BR/observability/maxim.mdx b/docs/v1.15.1/pt-BR/observability/maxim.mdx new file mode 100644 index 000000000..d3b121813 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/maxim.mdx @@ -0,0 +1,149 @@ +--- +title: Integração Maxim +description: Inicie o monitoramento, avaliação e observabilidade de agentes +icon: bars-staggered +mode: "wide" +--- + +# 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 +pesquisador = Agent( + role='Pesquisador Sênior', + goal='Descobrir os avanços mais recentes em IA', + backstory="Você é um pesquisador especialista em um think tank de tecnologia...", + verbose=True, + llm=llm +) + +# Defina a tarefa +research_task = Task( + description="Pesquise os avanços mais recentes em IA...", + expected_output="", + agent=pesquisador +) + +# Configure e execute a crew +crew = Crew( + agents=[pesquisador], + 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/v1.15.1/pt-BR/observability/mlflow.mdx b/docs/v1.15.1/pt-BR/observability/mlflow.mdx new file mode 100644 index 000000000..83a89c0f0 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/mlflow.mdx @@ -0,0 +1,186 @@ +--- +title: Integração com MLflow +description: Comece rapidamente a monitorar seus Agents com MLflow. +icon: bars-staggered +mode: "wide" +--- + +# 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): + especialista_cidades = Agent( + role="Especialista em Seleção de Cidades", + goal="Selecionar a melhor cidade com base no clima, estação e preços", + backstory="Especialista em analisar dados de viagem para escolher destinos ideais", + tools=[search_tool], + verbose=True, + ) + + def local_expert(self): + especialista_local = Agent( + role="Especialista Local nesta cidade", + goal="Fornecer as MELHORES informações sobre a cidade selecionada", + backstory="Um guia local experiente com amplo conhecimento sobre a cidade, suas atrações e costumes", + tools=[search_tool], + verbose=True, + ) + + + class TripTasks: + def identify_task(self, agent, origin, cities, interests, range): + return Task( + description=dedent( + f""" + Analise e selecione a melhor cidade para a viagem com base em critérios específicos como padrões climáticos, eventos sazonais e custos de viagem. Esta tarefa envolve comparar várias cidades, considerando fatores como condições climáticas atuais, eventos culturais ou sazonais e despesas gerais de viagem. + Sua resposta final deve ser um relatório detalhado sobre a cidade escolhida e tudo o que você descobriu sobre ela, incluindo custos reais de voo, previsão do tempo e atrações. + + Saindo de: {origin} + Opções de cidades: {cities} + Data da viagem: {range} + Interesses do viajante: {interests} + """ + ), + agent=agent, + expected_output="Relatório detalhado sobre a cidade escolhida incluindo custos de voo, previsão do tempo e atrações", + ) + + def gather_task(self, agent, origin, interests, range): + return Task( + description=dedent( + f""" + Como especialista local nesta cidade, você deve compilar um guia aprofundado para alguém que está viajando para lá e quer ter a MELHOR viagem possível! + Reúna informações sobre principais atrações, costumes locais, eventos especiais e recomendações de atividades diárias. + Encontre os melhores lugares para ir, aqueles que só um local conhece. + Este guia deve fornecer uma visão abrangente do que a cidade tem a oferecer, incluindo joias escondidas, pontos culturais, marcos imperdíveis, previsão do tempo e custos gerais. + A resposta final deve ser um guia completo da cidade, rico em insights culturais e dicas práticas, adaptado para aprimorar a experiência de viagem. + + Data da viagem: {range} + Saindo de: {origin} + Interesses do viajante: {interests} + """ + ), + agent=agent, + expected_output="Guia completo da cidade incluindo joias escondidas, pontos culturais e dicas práticas", + ) + + + 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("Resultado da equipe:", 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/v1.15.1/pt-BR/observability/neatlogs.mdx b/docs/v1.15.1/pt-BR/observability/neatlogs.mdx new file mode 100644 index 000000000..24b17cfce --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/neatlogs.mdx @@ -0,0 +1,134 @@ +--- +title: Neatlogs Integration +description: Understand, debug, and share your CrewAI agent runs +icon: magnifying-glass-chart +mode: "wide" +--- + +# Introduction + +Neatlogs helps you **see what your agent did**, **why**, and **share it**. + +It captures every step: thoughts, tool calls, responses, evaluations. No raw logs. Just clear, structured traces. Great for debugging and collaboration. + +## Why use Neatlogs? + +CrewAI agents use multiple tools and reasoning steps. When something goes wrong, you need context — not just errors. + +Neatlogs lets you: + +- Follow the full decision path +- Add feedback directly on steps +- Chat with the trace using AI assistant +- Share runs publicly for feedback +- Turn insights into tasks + +All in one place. + +Manage your traces effortlessly + +![Traces](/images/neatlogs-1.png) +![Trace Response](/images/neatlogs-2.png) + +The best UX to view a CrewAI trace. Post comments anywhere you want. Use AI to debug. + +![Trace Details](/images/neatlogs-3.png) +![Ai Chat Bot With A Trace](/images/neatlogs-4.png) +![Comments Drawer](/images/neatlogs-5.png) + +## Core Features + +- **Trace Viewer**: Track thoughts, tools, and decisions in sequence +- **Inline Comments**: Tag teammates on any trace step +- **Feedback & Evaluation**: Mark outputs as correct or incorrect +- **Error Highlighting**: Automatic flagging of API/tool failures +- **Task Conversion**: Convert comments into assigned tasks +- **Ask the Trace (AI)**: Chat with your trace using Neatlogs AI bot +- **Public Sharing**: Publish trace links to your community + +## Quick Setup with CrewAI + + + + Visit [neatlogs.com](https://neatlogs.com/?utm_source=crewAI-docs), create a project, copy the API key. + + + ```bash + pip install neatlogs + ``` + (Latest version 0.8.0, Python 3.8+; MIT license) + + + Before starting Crew agents, add: + + ```python + import neatlogs + neatlogs.init("YOUR_PROJECT_API_KEY") + ``` + + Agents run as usual. Neatlogs captures everything automatically. + + + + + + +## Under the Hood + +According to GitHub, Neatlogs: + +- Captures thoughts, tool calls, responses, errors, and token stats +- Supports AI-powered task generation and robust evaluation workflows + +All with just two lines of code. + + + +## Watch It Work + +### 🔍 Full Demo (4 min) + + + +### ⚙️ CrewAI Integration (30 s) + + + + + +## Links & Support + +- 📘 [Neatlogs Docs](https://docs.neatlogs.com/) +- 🔐 [Dashboard & API Key](https://app.neatlogs.com/) +- 🐦 [Follow on Twitter](https://twitter.com/neatlogs) +- 📧 Contact: hello@neatlogs.com +- 🛠 [GitHub SDK](https://github.com/NeatLogs/neatlogs) + + + +## TL;DR + +With just: + +```bash +pip install neatlogs + +import neatlogs +neatlogs.init("YOUR_API_KEY") + +You can now capture, understand, share, and act on your CrewAI agent runs in seconds. +No setup overhead. Full trace transparency. Full team collaboration. +``` diff --git a/docs/v1.15.1/pt-BR/observability/openlit.mdx b/docs/v1.15.1/pt-BR/observability/openlit.mdx new file mode 100644 index 000000000..0d69ae20d --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/openlit.mdx @@ -0,0 +1,181 @@ +--- +title: Integração OpenLIT +description: Comece a monitorar seus Agentes rapidamente com apenas uma linha de código usando OpenTelemetry. +icon: magnifying-glass-chart +mode: "wide" +--- + +# 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 + pesquisador = Agent( + role="Pesquisador", + goal="Realizar pesquisas e análises aprofundadas sobre IA e agentes de IA", + backstory="Você é um pesquisador especialista em tecnologia, engenharia de software, IA e startups. Trabalha como freelancer e está atualmente pesquisando para um novo cliente.", + allow_delegation=False, + llm='command-r' + ) + + + # Definir sua task + task = Task( + description="Gere uma lista com 5 ideias interessantes para um artigo e escreva um parágrafo cativante para cada ideia, mostrando o potencial de um artigo completo sobre o tema. Retorne a lista de ideias com seus parágrafos e suas anotações.", + expected_output="5 tópicos, cada um com um parágrafo e notas complementares.", + ) + + # Definir o agente gerente + gerente = Agent( + role="Gerente de Projeto", + goal="Gerenciar eficientemente a equipe e garantir a conclusão de tarefas de alta qualidade", + backstory="Você é um gerente de projetos experiente, habilidoso em supervisionar projetos complexos e guiar equipes para o sucesso. Sua função é coordenar os esforços dos membros da equipe, garantindo que cada tarefa seja concluída no prazo e com o mais alto padrão.", + allow_delegation=True, + llm='command-r' + ) + + # Instanciar sua crew com um manager personalizado + crew = Crew( + agents=[pesquisador], + tasks=[task], + manager_agent=gerente, + 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="Analista de Dados Python", + goal="Analisar dados e fornecer insights usando Python", + backstory="Você é um analista de dados experiente com fortes habilidades em Python.", + allow_code_execution=True, + llm="command-r" + ) + + # Criar uma task que exige execução de código + data_analysis_task = Task( + description="Analise o conjunto de dados fornecido e calcule a idade média dos participantes. Idades: {ages}", + agent=coding_agent, + expected_output="5 tópicos, cada um com um parágrafo e notas complementares.", + ) + + # 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/v1.15.1/pt-BR/observability/opik.mdx b/docs/v1.15.1/pt-BR/observability/opik.mdx new file mode 100644 index 000000000..5f2a2ef84 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/opik.mdx @@ -0,0 +1,130 @@ +--- +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 +mode: "wide" +--- + +# 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 NomeDaEquipe: + def agente_um(self) -> Agent: + return Agent( + role="Analista de Dados", + goal="Analisar tendências de dados no mercado", + backstory="Analista de dados experiente com formação em economia", + verbose=True, + ) + + def agente_dois(self) -> Agent: + return Agent( + role="Pesquisador de Mercado", + goal="Coletar informações sobre a dinâmica do mercado", + backstory="Pesquisador dedicado com olhar atento para detalhes", + verbose=True, + ) + + def tarefa_um(self) -> Task: + return Task( + name="Tarefa de Coleta de Dados", + description="Coletar dados recentes do mercado e identificar tendências.", + expected_output="Um relatório resumindo as principais tendências do mercado.", + agent=self.agente_um(), + ) + + def tarefa_dois(self) -> Task: + return Task( + name="Tarefa de Pesquisa de Mercado", + description="Pesquisar fatores que afetam a dinâmica do mercado.", + expected_output="Uma análise dos fatores que influenciam o mercado.", + agent=self.agente_dois(), + ) + + def equipe(self) -> Crew: + return Crew( + agents=[self.agente_um(), self.agente_dois()], + tasks=[self.tarefa_um(), self.tarefa_dois()], + 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 = NomeDaEquipe().equipe() + 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/v1.15.1/pt-BR/observability/overview.mdx b/docs/v1.15.1/pt-BR/observability/overview.mdx new file mode 100644 index 000000000..e3776ba01 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/overview.mdx @@ -0,0 +1,120 @@ +--- +title: "Visão Geral" +description: "Monitore, avalie e otimize seus agentes CrewAI com ferramentas de observabilidade abrangentes" +icon: "face-smile" +mode: "wide" +--- + +## 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 + + + + + Rastreamento ponta a ponta para fluxos de trabalho CrewAI com captura automática de interações 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/v1.15.1/pt-BR/observability/patronus-evaluation.mdx b/docs/v1.15.1/pt-BR/observability/patronus-evaluation.mdx new file mode 100644 index 000000000..c5e831c58 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/patronus-evaluation.mdx @@ -0,0 +1,206 @@ +--- +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 +mode: "wide" +--- + +# 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="Agente de Programação", + goal="Gerar código de alta qualidade e verificar se a saída é código", + backstory="Um programador experiente que pode gerar código Python de alta qualidade.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate and evaluate code +generate_code_task = Task( + description="Crie um programa simples para gerar os N primeiros números da sequência de Fibonacci. Selecione o avaliador e os critérios mais apropriados para avaliar sua saída.", + expected_output="Programa que gera os N primeiros números da sequência de Fibonacci.", + 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="Agente de Programação", + goal="Gerar código de alta qualidade", + backstory="Um programador experiente que pode gerar código Python de alta qualidade.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate code +generate_code_task = Task( + description="Crie um programa simples para gerar os N primeiros números da sequência de Fibonacci.", + expected_output="Programa que gera os N primeiros números da sequência de Fibonacci.", + 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="Agente de Programação", + goal="Gerar código de alta qualidade", + backstory="Um programador experiente que pode gerar código Python de alta qualidade.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate code +generate_code_task = Task( + description="Crie um programa simples para gerar os N primeiros números da sequência de Fibonacci.", + expected_output="Programa que gera os N primeiros números da sequência de Fibonacci.", + 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/v1.15.1/pt-BR/observability/portkey.mdx b/docs/v1.15.1/pt-BR/observability/portkey.mdx new file mode 100644 index 000000000..9e54136f5 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/portkey.mdx @@ -0,0 +1,823 @@ +--- +title: Integração com Portkey +description: Como usar Portkey com CrewAI +icon: key +mode: "wide" +--- + +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 do [Portkey App](https://app.portkey.ai/) + + 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 a [documentação Portkey](https://portkey.ai/docs). + + + + ### 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/v1.15.1/pt-BR/observability/tracing.mdx b/docs/v1.15.1/pt-BR/observability/tracing.mdx new file mode 100644 index 000000000..ba6c1b40a --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/tracing.mdx @@ -0,0 +1,214 @@ +--- +title: CrewAI Tracing +description: Rastreamento integrado para Crews e Flows do CrewAI com a plataforma CrewAI AMP +icon: magnifying-glass-chart +mode: "wide" +--- + +# Rastreamento Integrado do CrewAI + +O CrewAI fornece recursos de rastreamento integrados que permitem monitorar e depurar seus Crews e Flows em tempo real. Este guia demonstra como habilitar o rastreamento para **Crews** e **Flows** usando a plataforma de observabilidade integrada do CrewAI. + +> **O que é o CrewAI Tracing?** O rastreamento integrado do CrewAI fornece observabilidade abrangente para seus agentes de IA, incluindo decisões de agentes, cronogramas de execução de tarefas, uso de ferramentas e chamadas de LLM - tudo acessível através da [plataforma CrewAI AMP](https://app.crewai.com). + +![CrewAI Tracing Interface](/images/crewai-tracing.png) + +## Pré-requisitos + +Antes de usar o rastreamento do CrewAI, você precisa: + +1. **Conta CrewAI AMP**: Cadastre-se para uma conta gratuita em [app.crewai.com](https://app.crewai.com) +2. **Autenticação CLI**: Use a CLI do CrewAI para autenticar seu ambiente local + +```bash +crewai login +``` + +## Instruções de Configuração + +### Passo 1: Crie sua Conta CrewAI AMP + +Visite [app.crewai.com](https://app.crewai.com) e crie sua conta gratuita. Isso lhe dará acesso à plataforma CrewAI AMP, onde você pode visualizar rastreamentos, métricas e gerenciar seus crews. + +### Passo 2: Instale a CLI do CrewAI e Autentique + +Se você ainda não o fez, instale o CrewAI com as ferramentas CLI: + +```bash +uv add crewai[tools] +``` + +Em seguida, autentique sua CLI com sua conta CrewAI AMP: + +```bash +crewai login +``` + +Este comando irá: + +1. Abrir seu navegador na página de autenticação +2. Solicitar que você insira um código de dispositivo +3. Autenticar seu ambiente local com sua conta CrewAI AMP +4. Habilitar recursos de rastreamento para seu desenvolvimento local + +### Passo 3: Habilite o Rastreamento em seu Crew + +Você pode habilitar o rastreamento para seu Crew definindo o parâmetro `tracing` como `True`: + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +# Define your agents +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, + tools=[SerperDevTool()], +) + +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, +) + +# Create tasks for your agents +research_task = 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, +) + +writing_task = 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.\"\"\", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Enable tracing in your crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + tracing=True, # Enable built-in tracing + verbose=True +) + +# Execute your crew +result = crew.kickoff() +``` + +### Passo 4: Habilite o Rastreamento em seu Flow + +Da mesma forma, você pode habilitar o rastreamento para Flows do CrewAI: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class ExampleFlow(Flow[ExampleState]): + def __init__(self): + super().__init__(tracing=True) # Enable tracing for the flow + + @start() + def first_method(self): + print("Starting the flow") + self.state.counter = 1 + self.state.message = "Flow started" + return "continue" + + @listen("continue") + def second_method(self): + print("Continuing the flow") + self.state.counter += 1 + self.state.message = "Flow continued" + return "finish" + + @listen("finish") + def final_method(self): + print("Finishing the flow") + self.state.counter += 1 + self.state.message = "Flow completed" + +# Create and run the flow with tracing enabled +flow = ExampleFlow(tracing=True) +result = flow.kickoff() +``` + +### Passo 5: Visualize os Rastreamentos no Painel CrewAI AMP + +Após executar o crew ou flow, você pode visualizar os rastreamentos gerados pela sua aplicação CrewAI no painel CrewAI AMP. Você verá etapas detalhadas das interações dos agentes, usos de ferramentas e chamadas de LLM. +Basta clicar no link abaixo para visualizar os rastreamentos ou ir para a aba de rastreamentos no painel [aqui](https://app.crewai.com/crewai_plus/trace_batches) +![CrewAI Tracing Interface](/images/view-traces.png) + +### Alternativa: Configuração de Variável de Ambiente + +Você também pode habilitar o rastreamento globalmente definindo uma variável de ambiente: + +```bash +export CREWAI_TRACING_ENABLED=true +``` + +Ou adicione-a ao seu arquivo `.env`: + +```env +CREWAI_TRACING_ENABLED=true +``` + +Quando esta variável de ambiente estiver definida, todos os Crews e Flows terão automaticamente o rastreamento habilitado, mesmo sem definir explicitamente `tracing=True`. + +## Visualizando seus Rastreamentos + +### Acesse o Painel CrewAI AMP + +1. Visite [app.crewai.com](https://app.crewai.com) e faça login em sua conta +2. Navegue até o painel do seu projeto +3. Clique na aba **Traces** para visualizar os detalhes de execução + +### O que Você Verá nos Rastreamentos + +O rastreamento do CrewAI fornece visibilidade abrangente sobre: + +- **Decisões dos Agentes**: Veja como os agentes raciocinam através das tarefas e tomam decisões +- **Cronograma de Execução de Tarefas**: Representação visual de sequências e dependências de tarefas +- **Uso de Ferramentas**: Monitore quais ferramentas são chamadas e seus resultados +- **Chamadas de LLM**: Rastreie todas as interações do modelo de linguagem, incluindo prompts e respostas +- **Métricas de Desempenho**: Tempos de execução, uso de tokens e custos +- **Rastreamento de Erros**: Informações detalhadas de erros e rastreamentos de pilha + +### Recursos de Rastreamento + +- **Cronograma de Execução**: Clique através de diferentes estágios de execução +- **Logs Detalhados**: Acesse logs abrangentes para depuração +- **Análise de Desempenho**: Analise padrões de execução e otimize o desempenho +- **Capacidades de Exportação**: Baixe rastreamentos para análise adicional + +### Problemas de Autenticação + +Se você encontrar problemas de autenticação: + +1. Certifique-se de estar logado: `crewai login` +2. Verifique sua conexão com a internet +3. Verifique sua conta em [app.crewai.com](https://app.crewai.com) + +### Rastreamentos Não Aparecem + +Se os rastreamentos não estiverem aparecendo no painel: + +1. Confirme que `tracing=True` está definido em seu Crew/Flow +2. Verifique se `CREWAI_TRACING_ENABLED=true` se estiver usando variáveis de ambiente +3. Certifique-se de estar autenticado com `crewai login` +4. Verifique se seu crew/flow está realmente executando diff --git a/docs/v1.15.1/pt-BR/observability/truefoundry.mdx b/docs/v1.15.1/pt-BR/observability/truefoundry.mdx new file mode 100644 index 000000000..f48cb42e8 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/truefoundry.mdx @@ -0,0 +1,146 @@ +--- +title: Integração com a TrueFoundry +icon: chart-line +mode: "wide" +--- + +A TrueFoundry fornece um [AI Gateway](https://www.truefoundry.com/ai-gateway) pronto para uso empresarial, que pode ser usado para governança e observabilidade em frameworks agentivos como o CrewAI. O AI Gateway da TrueFoundry funciona como uma interface unificada para acesso a LLMs, oferecendo: + +- **Acesso unificado à API**: Conecte-se a 250+ LLMs (OpenAI, Claude, Gemini, Groq, Mistral) por meio de uma única API +- **Baixa latência**: Latência interna abaixo de 3 ms com roteamento inteligente e balanceamento de carga +- **Segurança corporativa**: Conformidade com SOC 2, HIPAA e GDPR, com RBAC e auditoria de logs +- **Gestão de cotas e custos**: Cotas baseadas em tokens, rate limiting e rastreamento abrangente de uso +- **Observabilidade**: Registro completo de requisições/respostas, métricas e traces com retenção personalizável + +## Como a TrueFoundry se integra ao CrewAI + + +### Instalação e configuração + + + +```bash +pip install crewai +``` + + + +1. Crie uma conta na [TrueFoundry](https://www.truefoundry.com/register) +2. Siga os passos do [Início rápido](https://docs.truefoundry.com/gateway/quick-start) + + + +![Configuração de código da TrueFoundry](/images/new-code-snippet.png) + +```python +from crewai import LLM + +# Criar uma instância de LLM com o AI Gateway da TrueFoundry +truefoundry_llm = LLM( + model="openai-main/gpt-4o", # Da mesma forma, você pode chamar qualquer modelo de qualquer provedor + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Usar nos seus agentes do CrewAI +from crewai import Agent + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + llm=truefoundry_llm, + verbose=True + ) +``` + + + +### Exemplo completo do CrewAI + +```python +from crewai import Agent, Task, Crew, LLM + +# Configurar o LLM com a TrueFoundry +llm = LLM( + model="openai-main/gpt-4o", + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Criar agentes +researcher = Agent( + role='Analista de Pesquisa', + goal='Conduzir pesquisa de mercado detalhada', + backstory='Analista de mercado especialista com atenção aos detalhes', + llm=llm, + verbose=True +) + +writer = Agent( + role='Redator de Conteúdo', + goal='Criar relatórios abrangentes', + backstory='Redator técnico experiente', + llm=llm, + verbose=True +) + +# Criar tarefas +research_task = Task( + description='Pesquisar tendências do mercado de IA para 2024', + agent=researcher, + expected_output='Resumo de pesquisa abrangente' +) + +writing_task = Task( + description='Criar um relatório de pesquisa de mercado', + agent=writer, + expected_output='Relatório bem estruturado com insights', + context=[research_task] +) + +# Criar e executar a crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +result = crew.kickoff() +``` + +### Observabilidade e governança + +Monitore seus agentes do CrewAI pela aba de métricas da TrueFoundry: +![Métricas da TrueFoundry](/images/gateway-metrics.png) + +Com o AI Gateway da TrueFoundry, você pode monitorar e analisar: + +- **Métricas de desempenho**: Acompanhe métricas-chave de latência como Latência da Requisição, Tempo até o Primeiro Token (TTFS) e Latência entre Tokens (ITL), com percentis P99, P90 e P50 +- **Custos e uso de tokens**: Tenha visibilidade dos custos da sua aplicação com detalhamento de tokens de entrada/saída e das despesas associadas a cada modelo +- **Padrões de uso**: Entenda como sua aplicação está sendo utilizada com análises detalhadas sobre atividade de usuários, distribuição de modelos e uso por equipe +- **Limite de taxa e balanceamento de carga**: Você pode configurar rate limiting, balanceamento de carga e fallback para seus modelos + +## Rastreamento + +Para uma compreensão mais detalhada sobre rastreamento, consulte [getting-started-tracing](https://docs.truefoundry.com/docs/tracing/tracing-getting-started). Para rastreamento, você pode adicionar o SDK do Traceloop: + +```bash +pip install traceloop-sdk +``` + +```python +from traceloop.sdk import Traceloop + +# Inicializar rastreamento avançado +Traceloop.init( + api_endpoint="https://your-truefoundry-endpoint/api/tracing", + headers={ + "Authorization": f"Bearer {your_truefoundry_pat_token}", + "TFY-Tracing-Project": "your_project_name", + }, +) +``` + +Isso oferece correlação adicional de rastreamentos em todo o seu fluxo de trabalho com o CrewAI. +![Rastreamento do CrewAI na TrueFoundry](/images/tracing_crewai.png) \ No newline at end of file diff --git a/docs/v1.15.1/pt-BR/observability/weave.mdx b/docs/v1.15.1/pt-BR/observability/weave.mdx new file mode 100644 index 000000000..a3ed92a26 --- /dev/null +++ b/docs/v1.15.1/pt-BR/observability/weave.mdx @@ -0,0 +1,125 @@ +--- +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 +mode: "wide" +--- + +# 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 + pesquisador = Agent( + role='Analista de Pesquisa', + goal='Encontrar e analisar as melhores oportunidades de investimento', + backstory='Especialista em análise financeira e pesquisa de mercado', + llm=llm, + verbose=True, + allow_delegation=False, + ) + + redator = Agent( + role='Redator de Relatórios', + goal='Escrever relatórios de investimento claros e concisos', + backstory='Experiente na criação de relatórios financeiros detalhados', + llm=llm, + verbose=True, + allow_delegation=False, + ) + + # Crie as tarefas + pesquisa = Task( + description='Pesquisa aprofundada sobre o {tema}', + expected_output='Dados de mercado abrangentes incluindo principais players, tamanho de mercado e tendências de crescimento.', + agent=pesquisador + ) + + redacao = Task( + description='Escreva um relatório detalhado com base na pesquisa', + expected_output='O relatório deve ser fácil de ler e entender. Use tópicos quando aplicável.', + agent=redator + ) + + # Crie o crew + equipe = Crew( + agents=[pesquisador, redator], + tasks=[pesquisa, redacao], + verbose=True, + process=Process.sequential, + ) + + # Execute o crew + resultado = equipe.kickoff(inputs={"tema": "IA em ciência dos materiais"}) + print(resultado) + ``` + + + 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/v1.15.1/pt-BR/quickstart.mdx b/docs/v1.15.1/pt-BR/quickstart.mdx new file mode 100644 index 000000000..0d241e095 --- /dev/null +++ b/docs/v1.15.1/pt-BR/quickstart.mdx @@ -0,0 +1,257 @@ +--- +title: Guia Rápido +description: Crie seu primeiro Flow CrewAI em minutos — orquestração, estado e um crew com um agente que gera um relatório real. +icon: rocket +mode: "wide" +--- + +### Assista: Construindo Agents e Flows CrewAI com Coding Agent Skills + +Instale nossas coding agent skills (Claude Code, Codex, ...) para colocar seus agentes de código para funcionar rapidamente com o CrewAI. + +Você pode instalar com `npx skills add crewaiinc/skills` + + + +Neste guia você vai **criar um Flow** que define um tópico de pesquisa, executa um **crew com um agente** (um pesquisador com busca na web) e termina com um **relatório em Markdown** no disco. Flows são a forma recomendada de estruturar apps em produção: eles controlam **estado** e **ordem de execução**, enquanto os **agentes** fazem o trabalho dentro da etapa do crew. + +Se ainda não instalou o CrewAI, siga primeiro o [guia de instalação](/pt-BR/installation). + +## Pré-requisitos + +- Ambiente Python e a CLI do CrewAI (veja [instalação](/pt-BR/installation)) +- Um LLM configurado com as chaves corretas — veja [LLMs](/pt-BR/concepts/llms#setting-up-your-llm) +- Uma chave de API do [Serper.dev](https://serper.dev/) (`SERPER_API_KEY`) para busca na web neste tutorial + +## Construa seu primeiro Flow + + + + No terminal, gere um projeto Flow (o nome da pasta usa sublinhados, ex.: `latest_ai_flow`): + + + ```shell Terminal + crewai create flow latest-ai-flow + cd latest_ai_flow + ``` + + + Isso cria um app Flow em `src/latest_ai_flow/`, incluindo um crew inicial em `crews/content_crew/` que você substituirá por um crew de pesquisa **com um único agente** nos próximos passos. + + + + Crie `src/latest_ai_flow/crews/content_crew/agents/researcher.jsonc` (crie o diretório `agents/` se necessário). Variáveis como `{topic}` são preenchidas a partir de `crew.kickoff(inputs=...)`. + + ```jsonc agents/researcher.jsonc + { + "role": "Pesquisador(a) Sênior de Dados em {topic}", + "goal": "Descobrir os desenvolvimentos mais recentes em {topic}", + "backstory": "Você é um pesquisador experiente que encontra as informações mais relevantes e apresenta tudo com clareza.", + "tools": ["SerperDevTool"], + "settings": { + "verbose": true + } + } + ``` + + + + + Crie `src/latest_ai_flow/crews/content_crew/crew.jsonc`: + + ```jsonc crew.jsonc + { + "name": "Research Crew", + "agents": ["researcher"], + "tasks": [ + { + "name": "research_task", + "description": "Faça uma pesquisa aprofundada sobre {topic}. Use busca na web para obter informações recentes e confiáveis.", + "expected_output": "Um relatório em markdown com seções claras: tendências principais, ferramentas ou empresas relevantes e implicações. Entre 800 e 1200 palavras. Sem cercas de código em volta do documento inteiro.", + "agent": "researcher", + "output_file": "output/report.md", + "markdown": true + } + ], + "process": "sequential", + "verbose": true + } + ``` + + + + + Substitua o `content_crew.py` gerado por um pequeno loader que transforma `crew.jsonc` em uma `Crew`. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py + from pathlib import Path + + from crewai.project import load_crew + + + def kickoff_content_crew(inputs: dict): + crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc")) + return crew.kickoff(inputs={**default_inputs, **inputs}) + ``` + + + + + Conecte o crew a um Flow: um passo `@start()` define o tópico no **estado** e um `@listen` executa o crew. O `output_file` da tarefa continua gravando `output/report.md`. + + ```python main.py + # src/latest_ai_flow/main.py + from pydantic import BaseModel + + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import kickoff_content_crew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"Tópico: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = kickoff_content_crew(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("Crew de pesquisa concluído.") + + @listen(run_research) + def summarize(self): + print("Relatório em: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() + ``` + + + Se o nome do pacote não for `latest_ai_flow`, ajuste o import de `kickoff_content_crew` para o caminho de módulo do seu projeto. + + + + + Na raiz do projeto, no arquivo `.env`, defina: + + - `SERPER_API_KEY` — obtida em [Serper.dev](https://serper.dev/) + - As chaves do provedor de modelo conforme necessário — veja [configuração de LLM](/pt-BR/concepts/llms#setting-up-your-llm) + + + + + ```shell Terminal + crewai install + crewai run + ``` + + + O `crewai run` executa o ponto de entrada do Flow definido no projeto (o mesmo comando dos crews; o tipo do projeto é `"flow"` no `pyproject.toml`). + + + + Você deve ver logs do Flow e do crew. Abra **`output/report.md`** para o relatório gerado (trecho): + + + ```markdown output/report.md + # Agentes de IA: panorama e tendências recentes + + ## Resumo executivo + … + + ## Principais tendências + - **Uso de ferramentas e orquestração** — … + - **Adoção empresarial** — … + + ## Implicações + … + ``` + + + O arquivo real será mais longo e refletirá resultados de busca ao vivo. + + + +## Como isso se encaixa + +1. **Flow** — `LatestAiFlow` executa `prepare_topic`, depois `run_research`, depois `summarize`. O estado (`topic`, `report`) fica no Flow. +2. **Crew** — `kickoff_content_crew` carrega `crew.jsonc` e executa uma tarefa com um agente: o pesquisador usa **Serper** na web e escreve o relatório. +3. **Artefato** — O `output_file` da tarefa grava o relatório em `output/report.md`. + +Para ir além em Flows (roteamento, persistência, human-in-the-loop), veja [Construa seu primeiro Flow](/pt-BR/guides/flows/first-flow) e [Flows](/pt-BR/concepts/flows). Para crews sem Flow, veja [Crews](/pt-BR/concepts/crews). Para um único `Agent` com `kickoff()` sem tarefas, veja [Agents](/pt-BR/concepts/agents#direct-agent-interaction-with-kickoff). + + +Você tem um Flow ponta a ponta com um crew de agente e um relatório salvo — uma base sólida para novas etapas, crews ou ferramentas. + + +### Consistência de nomes + +Os nomes em `crew.jsonc` devem coincidir com os arquivos e referências: + +- `agents: ["researcher"]` carrega `agents/researcher.jsonc` +- `tasks[].agent: "researcher"` atribui a tarefa a esse agente + +## Implantação + +Envie seu Flow para o **[CrewAI AMP](https://app.crewai.com)** quando rodar localmente e o projeto estiver em um repositório **GitHub**. Na raiz do projeto: + + +```bash Autenticar +crewai login +``` + +```bash Criar implantação +crewai deploy create +``` + +```bash Status e logs +crewai deploy status +crewai deploy logs +``` + +```bash Enviar atualizações após mudanças no código +crewai deploy push +``` + +```bash Listar ou remover implantações +crewai deploy list +crewai deploy remove +``` + + + + A primeira implantação costuma levar **cerca de 1 minuto**. Pré-requisitos completos e fluxo na interface web estão em [Implantar no AMP](/pt-BR/enterprise/guides/deploy-to-amp). + + + + + AMP passo a passo (CLI e painel). + + + Troque ideias, compartilhe projetos e conecte-se com outros desenvolvedores CrewAI. + + diff --git a/docs/v1.15.1/pt-BR/skills.mdx b/docs/v1.15.1/pt-BR/skills.mdx new file mode 100644 index 000000000..ef492dee3 --- /dev/null +++ b/docs/v1.15.1/pt-BR/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: Instale crewaiinc/skills pelo registro oficial em skills.sh—Flows, Crews e agentes alinhados à documentação para Claude Code, Cursor, Codex e outros. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**Dê ao seu agente de código o contexto do CrewAI em um comando.** + +As **Skills** do CrewAI são publicadas em **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**—o registro oficial de `crewaiinc/skills`, com cada skill (por exemplo **design-agent**, **getting-started**, **design-task** e **ask-docs**), estatísticas de instalação e auditorias. Ensinam agentes de código—como Claude Code, Cursor e Codex—a estruturar Flows, configurar Crews, usar ferramentas e seguir os padrões do CrewAI. Execute o comando abaixo (ou cole no seu agente). + +```shell Terminal +npx skills add crewaiinc/skills +``` + +Isso adiciona o pacote de skills ao fluxo do seu agente para aplicar convenções do CrewAI sem precisar reexplicar o framework a cada sessão. Código-fonte e issues ficam no [GitHub](https://github.com/crewAIInc/skills). + +## O que seu agente ganha + +- **Flows** — apps com estado, passos e kickoffs de crew no estilo CrewAI +- **Crews e agentes** — padrões JSON-first (`crew.jsonc`, `agents/*.jsonc`), papéis, tarefas e delegação +- **Ferramentas e integrações** — conectar agentes a busca, APIs e ferramentas comuns +- **Layout de projeto** — alinhar com scaffolds da CLI e convenções do repositório +- **Padrões atualizados** — skills acompanham a documentação e as práticas recomendadas + +## Saiba mais neste site + + + + Como usar `AGENTS.md` e fluxos de agente de código com o CrewAI. + + + Construa seu primeiro Flow e crew ponta a ponta. + + + Instale a CLI e o pacote Python do CrewAI. + + + Listagem oficial de `crewaiinc/skills`—skills, instalações e auditorias. + + + Fonte, atualizações e issues do pacote de skills. + + + +### Vídeo: CrewAI com coding agent skills + +