andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-07-05 15:09:22 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

feat: adopt directory-based docs versioning with Edge channel

Browse Source 
Switch docs.crewai.com from navigation-only versioning (every version
selector entry rendered the same docs/<lang>/* source files) to
Mintlify's directory-based versioning so each version selector entry
renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/*
that always reflects main HEAD for unreleased work, eliminating
pre-release leakage onto frozen release labels. External links to
canonical /<lang>/* URLs are preserved via wildcard redirects that
always land on the current default version.

Layout:
- docs/edge/<lang>/*         rolling source (you edit here)
- docs/edge/enterprise-api.*.yaml
- docs/v<X.Y.Z>/<lang>/*     frozen, immutable snapshots
- docs/v<X.Y.Z>/enterprise-api.*.yaml
- docs/images/               shared, append-only
- docs/docs.json             nav + redirects

URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for
Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard
redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links
working, and every freeze rewrites them (plus all per-section/per-page
redirects) so destinations always resolve to the current default
without depending on a second redirect hop.

Release flow integration (devtools release):
- New module crewai_devtools.docs_versioning.freeze() materialises
  docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the
  snapshot, inserts the version into every language block in
  docs.json, and refreshes all redirect destinations.
- _update_docs_and_create_pr() in cli.py now calls that freeze during
  Phase 2 of devtools release. Edge changelogs are updated first (so
  the snapshot freeze picks them up), then the snapshot is staged
  alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR
  is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z>
  — the title prefix the new CI guard reads.
- The PR still gates tag, GitHub release, PyPI publish, and the
  enterprise release as before; no new PRs are added.
- Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride
  Edge — and the docs PR title omits the [docs-freeze] prefix.
- docs_check (AI-generated docs scaffolding) writes to
  docs/edge/<lang>/* so newly-generated unreleased docs land in Edge
  and never accidentally touch a frozen snapshot.

Migration scripts (one-shot):
- scripts/docs/freeze_historical_versions.py reconstructs all 16
  historical snapshots (v1.10.0 .. v1.14.7) from git tags via
  git archive | tar, rewriting openapi: MDX refs so each snapshot
  reads its own enterprise-api YAML rather than the live one.
- scripts/docs/prefix_version_paths.py one-shot-migrates docs.json:
  rewrites every page path in 16 versioned blocks to point under
  docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags
  v1.14.7 as Latest (default), prunes pages whose target file
  doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before
  v1.12.0), and writes the wildcard + per-section redirects.
- scripts/docs/freeze_current_edge.py is now a thin CLI wrapper
  around docs_versioning.freeze for manual one-off freezes (e.g.
  retroactively snapshotting a forgotten release).

CI guards (.github/workflows/docs-snapshots.yml):
- Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose
  title contains [docs-freeze] (i.e. release-cut PRs generated by
  devtools release or the manual wrapper) may modify them.
- Images under docs/images/ are append-only since snapshots share a
  single image directory. Deleting or renaming an image breaks every
  historical snapshot that still references it.

Restored docs/images/crewai-otel-export.png from PR #3673; it was
deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference
it. Restoring instead of editing the snapshots preserves historical
rendering fidelity and validates the new append-only rule
retroactively.

Tests:
- lib/devtools/tests/test_docs_versioning.py covers the freeze: file
  copy, openapi rewrite, version insertion, default demotion, redirect
  upserts, per-section redirect rewriting, idempotency, and invalid
  inputs.

Verified locally with mintlify broken-links: 0 broken links across
the full site (Edge + 16 frozen versions, 4 locales).

AGENTS.md (repo root) is the contributor guide for the new model;
RELEASING.md is the release-cut runbook; README's Contribution
section links to both.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
2026-06-17 09:33:56 -03:00
parent 7bb9bc7e1a
commit 93dafe2637
15793 changed files with 3237032 additions and 16873 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/v1.11.0/en/api-reference/inputs.mdx Normal file
View File

@@ -0,0 +1,8 @@
---
title: "GET /inputs"
description: "Get required inputs for your crew"
openapi: "/v1.11.0/enterprise-api.en.yaml GET /inputs"
mode: "wide"
---

135
docs/v1.11.0/en/api-reference/introduction.mdx Normal file
View File

@@ -0,0 +1,135 @@
---
title: "Introduction"
description: "Complete reference for the CrewAI AMP REST API"
icon: "code"
mode: "wide"
---
# CrewAI AMP API
Welcome to the CrewAI AMP API reference. This API allows you to programmatically interact with your deployed crews, enabling integration with your applications, workflows, and services.
## Quick Start
<Steps>
<Step title="Get Your API Credentials">
Navigate to your crew's detail page in the CrewAI AMP dashboard and copy your Bearer Token from the Status tab.
</Step>
<Step title="Discover Required Inputs">
Use the `GET /inputs` endpoint to see what parameters your crew expects.
</Step>
<Step title="Start a Crew Execution">
Call `POST /kickoff` with your inputs to start the crew execution and receive
a `kickoff_id`.
</Step>
<Step title="Monitor Progress">
Use `GET /{kickoff_id}/status` to check execution status and retrieve results.
</Step>
</Steps>
## Authentication
All API requests require authentication using a Bearer token. Include your token in the `Authorization` header:
```bash
curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
https://your-crew-url.crewai.com/inputs
```
### Token Types
| Token Type | Scope | Use Case |
| :-------------------- | :------------------------ | :----------------------------------------------------------- |
| **Bearer Token** | Organization-level access | Full crew operations, ideal for server-to-server integration |
| **User Bearer Token** | User-scoped access | Limited permissions, suitable for user-specific operations |
<Tip>
You can find both token types in the Status tab of your crew's detail page in
the CrewAI AMP dashboard.
</Tip>
## Base URL
Each deployed crew has its own unique API endpoint:
```
https://your-crew-name.crewai.com
```
Replace `your-crew-name` with your actual crew's URL from the dashboard.
## Typical Workflow
1. **Discovery**: Call `GET /inputs` to understand what your crew needs
2. **Execution**: Submit inputs via `POST /kickoff` to start processing
3. **Monitoring**: Poll `GET /{kickoff_id}/status` until completion
4. **Results**: Extract the final output from the completed response
## Error Handling
The API uses standard HTTP status codes:
| Code | Meaning |
| ----- | :----------------------------------------- |
| `200` | Success |
| `400` | Bad Request - Invalid input format |
| `401` | Unauthorized - Invalid bearer token |
| `404` | Not Found - Resource doesn't exist |
| `422` | Validation Error - Missing required inputs |
| `500` | Server Error - Contact support |
## Interactive Testing
<Info>
**Why no "Send" button?** Since each CrewAI AMP user has their own unique crew
URL, we use **reference mode** instead of an interactive playground to avoid
confusion. This shows you exactly what the requests should look like without
non-functional send buttons.
</Info>
Each endpoint page shows you:
- ✅ **Exact request format** with all parameters
- ✅ **Response examples** for success and error cases
- ✅ **Code samples** in multiple languages (cURL, Python, JavaScript, etc.)
- ✅ **Authentication examples** with proper Bearer token format
### **To Test Your Actual API:**
<CardGroup cols={2}>
<Card title="Copy cURL Examples" icon="terminal">
Copy the cURL examples and replace the URL + token with your real values
</Card>
<Card title="Use Postman/Insomnia" icon="play">
Import the examples into your preferred API testing tool
</Card>
</CardGroup>
**Example workflow:**
1. **Copy this cURL example** from any endpoint page
2. **Replace `your-actual-crew-name.crewai.com`** with your real crew URL
3. **Replace the Bearer token** with your real token from the dashboard
4. **Run the request** in your terminal or API client
## Need Help?
<CardGroup cols={2}>
<Card
title="Enterprise Support"
icon="headset"
href="mailto:support@crewai.com"
>
Get help with API integration and troubleshooting
</Card>
<Card
title="Enterprise Dashboard"
icon="chart-line"
href="https://app.crewai.com"
>
Manage your crews and view execution logs
</Card>
</CardGroup>

8
docs/v1.11.0/en/api-reference/kickoff.mdx Normal file
View File

@@ -0,0 +1,8 @@
---
title: "POST /kickoff"
description: "Start a crew execution"
openapi: "/v1.11.0/enterprise-api.en.yaml POST /kickoff"
mode: "wide"
---

6
docs/v1.11.0/en/api-reference/resume.mdx Normal file
View File

@@ -0,0 +1,6 @@
---
title: "POST /resume"
description: "Resume crew execution with human feedback"
openapi: "/v1.11.0/enterprise-api.en.yaml POST /resume"
mode: "wide"
---

6
docs/v1.11.0/en/api-reference/status.mdx Normal file
View File

@@ -0,0 +1,6 @@
---
title: "GET /{kickoff_id}/status"
description: "Get execution status"
openapi: "/v1.11.0/enterprise-api.en.yaml GET /{kickoff_id}/status"
mode: "wide"
---

2767
docs/v1.11.0/en/changelog.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

740
docs/v1.11.0/en/concepts/agents.mdx Normal file
View File

@@ -0,0 +1,740 @@
---
title: Agents
description: Detailed guide on creating and managing agents within the CrewAI framework.
icon: robot
mode: "wide"
---
## Overview of an Agent
In the CrewAI framework, an `Agent` is an autonomous unit that can:
- Perform specific tasks
- Make decisions based on its role and goal
- Use tools to accomplish objectives
- Communicate and collaborate with other agents
- Maintain memory of interactions
- Delegate tasks when allowed
<Tip>
Think of an agent as a specialized team member with specific skills,
expertise, and responsibilities. For example, a `Researcher` agent might excel
at gathering and analyzing information, while a `Writer` agent might be better
at creating content.
</Tip>
<Note type="info" title="Enterprise Enhancement: Visual Agent Builder">
CrewAI AMP includes a Visual Agent Builder that simplifies agent creation and configuration without writing code. Design your agents visually and test them in real-time.
![Visual Agent Builder Screenshot](/images/enterprise/crew-studio-interface.png)
The Visual Agent Builder enables:
- Intuitive agent configuration with form-based interfaces
- Real-time testing and validation
- Template library with pre-configured agent types
- Easy customization of agent attributes and behaviors
</Note>
## Agent Attributes
| Attribute | Parameter | Type | Description |
| :-------------------------------------- | :----------------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------- |
| **Role** | `role` | `str` | Defines the agent's function and expertise within the crew. |
| **Goal** | `goal` | `str` | The individual objective that guides the agent's decision-making. |
| **Backstory** | `backstory` | `str` | Provides context and personality to the agent, enriching interactions. |
| **LLM** _(optional)_ | `llm` | `Union[str, LLM, Any]` | Language model that powers the agent. Defaults to the model specified in `OPENAI_MODEL_NAME` or "gpt-4". |
| **Tools** _(optional)_ | `tools` | `List[BaseTool]` | Capabilities or functions available to the agent. Defaults to an empty list. |
| **Function Calling LLM** _(optional)_ | `function_calling_llm` | `Optional[Any]` | Language model for tool calling, overrides crew's LLM if specified. |
| **Max Iterations** _(optional)_ | `max_iter` | `int` | Maximum iterations before the agent must provide its best answer. Default is 20. |
| **Max RPM** _(optional)_ | `max_rpm` | `Optional[int]` | Maximum requests per minute to avoid rate limits. |
| **Max Execution Time** _(optional)_ | `max_execution_time` | `Optional[int]` | Maximum time (in seconds) for task execution. |
| **Verbose** _(optional)_ | `verbose` | `bool` | Enable detailed execution logs for debugging. Default is False. |
| **Allow Delegation** _(optional)_ | `allow_delegation` | `bool` | Allow the agent to delegate tasks to other agents. Default is False. |
| **Step Callback** _(optional)_ | `step_callback` | `Optional[Any]` | Function called after each agent step, overrides crew callback. |
| **Cache** _(optional)_ | `cache` | `bool` | Enable caching for tool usage. Default is True. |
| **System Template** _(optional)_ | `system_template` | `Optional[str]` | Custom system prompt template for the agent. |
| **Prompt Template** _(optional)_ | `prompt_template` | `Optional[str]` | Custom prompt template for the agent. |
| **Response Template** _(optional)_ | `response_template` | `Optional[str]` | Custom response template for the agent. |
| **Allow Code Execution** _(optional)_ | `allow_code_execution` | `Optional[bool]` | Enable code execution for the agent. Default is False. |
| **Max Retry Limit** _(optional)_ | `max_retry_limit` | `int` | Maximum number of retries when an error occurs. Default is 2. |
| **Respect Context Window** _(optional)_ | `respect_context_window` | `bool` | Keep messages under context window size by summarizing. Default is True. |
| **Code Execution Mode** _(optional)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | Mode for code execution: 'safe' (using Docker) or 'unsafe' (direct). Default is 'safe'. |
| **Multimodal** _(optional)_ | `multimodal` | `bool` | Whether the agent supports multimodal capabilities. Default is False. |
| **Inject Date** _(optional)_ | `inject_date` | `bool` | Whether to automatically inject the current date into tasks. Default is False. |
| **Date Format** _(optional)_ | `date_format` | `str` | Format string for date when inject_date is enabled. Default is "%Y-%m-%d" (ISO format). |
| **Reasoning** _(optional)_ | `reasoning` | `bool` | Whether the agent should reflect and create a plan before executing a task. Default is False. |
| **Max Reasoning Attempts** _(optional)_ | `max_reasoning_attempts` | `Optional[int]` | Maximum number of reasoning attempts before executing the task. If None, will try until ready. |
| **Embedder** _(optional)_ | `embedder` | `Optional[Dict[str, Any]]` | Configuration for the embedder used by the agent. |
| **Knowledge Sources** _(optional)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | Knowledge sources available to the agent. |
| **Use System Prompt** _(optional)_ | `use_system_prompt` | `Optional[bool]` | Whether to use system prompt (for o1 model support). Default is True. |
## Creating Agents
There are two ways to create agents in CrewAI: using **YAML configuration (recommended)** or defining them **directly in code**.
### YAML Configuration (Recommended)
Using YAML configuration provides a cleaner, more maintainable way to define agents. We strongly recommend using this approach in your CrewAI projects.
After creating your CrewAI project as outlined in the [Installation](/en/installation) section, navigate to the `src/latest_ai_development/config/agents.yaml` file and modify the template to match your requirements.
<Note>
Variables in your YAML files (like `{topic}`) will be replaced with values from your inputs when running the crew:
```python Code
crew.kickoff(inputs={'topic': 'AI Agents'})
```
</Note>
Here's an example of how to configure agents using YAML:
```yaml agents.yaml
# src/latest_ai_development/config/agents.yaml
researcher:
role: >
{topic} Senior Data Researcher
goal: >
Uncover cutting-edge developments in {topic}
backstory: >
You're a seasoned researcher with a knack for uncovering the latest
developments in {topic}. Known for your ability to find the most relevant
information and present it in a clear and concise manner.
reporting_analyst:
role: >
{topic} Reporting Analyst
goal: >
Create detailed reports based on {topic} data analysis and research findings
backstory: >
You're a meticulous analyst with a keen eye for detail. You're known for
your ability to turn complex data into clear and concise reports, making
it easy for others to understand and act on the information you provide.
```
To use this YAML configuration in your code, create a crew class that inherits from `CrewBase`:
```python Code
# src/latest_ai_development/crew.py
from crewai import Agent, Crew, Process
from crewai.project import CrewBase, agent, crew
from crewai_tools import SerperDevTool
@CrewBase
class LatestAiDevelopmentCrew():
"""LatestAiDevelopment crew"""
agents_config = "config/agents.yaml"
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def reporting_analyst(self) -> Agent:
return Agent(
config=self.agents_config['reporting_analyst'], # type: ignore[index]
verbose=True
)
```
<Note>
The names you use in your YAML files (`agents.yaml`) should match the method
names in your Python code.
</Note>
### Direct Code Definition
You can create agents directly in code by instantiating the `Agent` class. Here's a comprehensive example showing all available parameters:
```python Code
from crewai import Agent
from crewai_tools import SerperDevTool
# Create an agent with all available parameters
agent = Agent(
role="Senior Data Scientist",
goal="Analyze and interpret complex datasets to provide actionable insights",
backstory="With over 10 years of experience in data science and machine learning, "
"you excel at finding patterns in complex datasets.",
llm="gpt-4", # Default: OPENAI_MODEL_NAME or "gpt-4"
function_calling_llm=None, # Optional: Separate LLM for tool calling
verbose=False, # Default: False
allow_delegation=False, # Default: False
max_iter=20, # Default: 20 iterations
max_rpm=None, # Optional: Rate limit for API calls
max_execution_time=None, # Optional: Maximum execution time in seconds
max_retry_limit=2, # Default: 2 retries on error
allow_code_execution=False, # Default: False
code_execution_mode="safe", # Default: "safe" (options: "safe", "unsafe")
respect_context_window=True, # Default: True
use_system_prompt=True, # Default: True
multimodal=False, # Default: False
inject_date=False, # Default: False
date_format="%Y-%m-%d", # Default: ISO format
reasoning=False, # Default: False
max_reasoning_attempts=None, # Default: None
tools=[SerperDevTool()], # Optional: List of tools
knowledge_sources=None, # Optional: List of knowledge sources
embedder=None, # Optional: Custom embedder configuration
system_template=None, # Optional: Custom system prompt template
prompt_template=None, # Optional: Custom prompt template
response_template=None, # Optional: Custom response template
step_callback=None, # Optional: Callback function for monitoring
)
```
Let's break down some key parameter combinations for common use cases:
#### Basic Research Agent
```python Code
research_agent = Agent(
role="Research Analyst",
goal="Find and summarize information about specific topics",
backstory="You are an experienced researcher with attention to detail",
tools=[SerperDevTool()],
verbose=True # Enable logging for debugging
)
```
#### Code Development Agent
```python Code
dev_agent = Agent(
role="Senior Python Developer",
goal="Write and debug Python code",
backstory="Expert Python developer with 10 years of experience",
allow_code_execution=True,
code_execution_mode="safe", # Uses Docker for safety
max_execution_time=300, # 5-minute timeout
max_retry_limit=3 # More retries for complex code tasks
)
```
#### Long-Running Analysis Agent
```python Code
analysis_agent = Agent(
role="Data Analyst",
goal="Perform deep analysis of large datasets",
backstory="Specialized in big data analysis and pattern recognition",
memory=True,
respect_context_window=True,
max_rpm=10, # Limit API calls
function_calling_llm="gpt-4o-mini" # Cheaper model for tool calls
)
```
#### Custom Template Agent
```python Code
custom_agent = Agent(
role="Customer Service Representative",
goal="Assist customers with their inquiries",
backstory="Experienced in customer support with a focus on satisfaction",
system_template="""<|start_header_id|>system<|end_header_id|>
{{ .System }}<|eot_id|>""",
prompt_template="""<|start_header_id|>user<|end_header_id|>
{{ .Prompt }}<|eot_id|>""",
response_template="""<|start_header_id|>assistant<|end_header_id|>
{{ .Response }}<|eot_id|>""",
)
```
#### Date-Aware Agent with Reasoning
```python Code
strategic_agent = Agent(
role="Market Analyst",
goal="Track market movements with precise date references and strategic planning",
backstory="Expert in time-sensitive financial analysis and strategic reporting",
inject_date=True, # Automatically inject current date into tasks
date_format="%B %d, %Y", # Format as "May 21, 2025"
reasoning=True, # Enable strategic planning
max_reasoning_attempts=2, # Limit planning iterations
verbose=True
)
```
#### Reasoning Agent
```python Code
reasoning_agent = Agent(
role="Strategic Planner",
goal="Analyze complex problems and create detailed execution plans",
backstory="Expert strategic planner who methodically breaks down complex challenges",
reasoning=True, # Enable reasoning and planning
max_reasoning_attempts=3, # Limit reasoning attempts
max_iter=30, # Allow more iterations for complex planning
verbose=True
)
```
#### Multimodal Agent
```python Code
multimodal_agent = Agent(
role="Visual Content Analyst",
goal="Analyze and process both text and visual content",
backstory="Specialized in multimodal analysis combining text and image understanding",
multimodal=True, # Enable multimodal capabilities
verbose=True
)
```
### Parameter Details
#### Critical Parameters
- `role`, `goal`, and `backstory` are required and shape the agent's behavior
- `llm` determines the language model used (default: OpenAI's GPT-4)
#### Memory and Context
- `memory`: Enable to maintain conversation history
- `respect_context_window`: Prevents token limit issues
- `knowledge_sources`: Add domain-specific knowledge bases
#### Execution Control
- `max_iter`: Maximum attempts before giving best answer
- `max_execution_time`: Timeout in seconds
- `max_rpm`: Rate limiting for API calls
- `max_retry_limit`: Retries on error
#### Code Execution
- `allow_code_execution`: Must be True to run code
- `code_execution_mode`:
- `"safe"`: Uses Docker (recommended for production)
- `"unsafe"`: Direct execution (use only in trusted environments)
<Note>
This runs a default Docker image. If you want to configure the docker image,
the checkout the Code Interpreter Tool in the tools section. Add the code
interpreter tool as a tool in the agent as a tool parameter.
</Note>
#### Advanced Features
- `multimodal`: Enable multimodal capabilities for processing text and visual content
- `reasoning`: Enable agent to reflect and create plans before executing tasks
- `inject_date`: Automatically inject current date into task descriptions
#### Templates
- `system_template`: Defines agent's core behavior
- `prompt_template`: Structures input format
- `response_template`: Formats agent responses
<Note>
When using custom templates, ensure that both `system_template` and
`prompt_template` are defined. The `response_template` is optional but
recommended for consistent output formatting.
</Note>
<Note>
When using custom templates, you can use variables like `{role}`, `{goal}`,
and `{backstory}` in your templates. These will be automatically populated
during execution.
</Note>
## Agent Tools
Agents can be equipped with various tools to enhance their capabilities. CrewAI supports tools from:
- [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools)
- [LangChain Tools](https://python.langchain.com/docs/integrations/tools)
Here's how to add tools to an agent:
```python Code
from crewai import Agent
from crewai_tools import SerperDevTool, WikipediaTools
# Create tools
search_tool = SerperDevTool()
wiki_tool = WikipediaTools()
# Add tools to agent
researcher = Agent(
role="AI Technology Researcher",
goal="Research the latest AI developments",
tools=[search_tool, wiki_tool],
verbose=True
)
```
## Agent Memory and Context
Agents can maintain memory of their interactions and use context from previous tasks. This is particularly useful for complex workflows where information needs to be retained across multiple tasks.
```python Code
from crewai import Agent
analyst = Agent(
role="Data Analyst",
goal="Analyze and remember complex data patterns",
memory=True, # Enable memory
verbose=True
)
```
<Note>
When `memory` is enabled, the agent will maintain context across multiple
interactions, improving its ability to handle complex, multi-step tasks.
</Note>
## Context Window Management
CrewAI includes sophisticated automatic context window management to handle situations where conversations exceed the language model's token limits. This powerful feature is controlled by the `respect_context_window` parameter.
### How Context Window Management Works
When an agent's conversation history grows too large for the LLM's context window, CrewAI automatically detects this situation and can either:
1. **Automatically summarize content** (when `respect_context_window=True`)
2. **Stop execution with an error** (when `respect_context_window=False`)
### Automatic Context Handling (`respect_context_window=True`)
This is the **default and recommended setting** for most use cases. When enabled, CrewAI will:
```python Code
# Agent with automatic context management (default)
smart_agent = Agent(
role="Research Analyst",
goal="Analyze large documents and datasets",
backstory="Expert at processing extensive information",
respect_context_window=True, # 🔑 Default: auto-handle context limits
verbose=True
)
```
**What happens when context limits are exceeded:**
- ⚠️ **Warning message**: `"Context length exceeded. Summarizing content to fit the model context window."`
- 🔄 **Automatic summarization**: CrewAI intelligently summarizes the conversation history
- ✅ **Continued execution**: Task execution continues seamlessly with the summarized context
- 📝 **Preserved information**: Key information is retained while reducing token count
### Strict Context Limits (`respect_context_window=False`)
When you need precise control and prefer execution to stop rather than lose any information:
```python Code
# Agent with strict context limits
strict_agent = Agent(
role="Legal Document Reviewer",
goal="Provide precise legal analysis without information loss",
backstory="Legal expert requiring complete context for accurate analysis",
respect_context_window=False, # ❌ Stop execution on context limit
verbose=True
)
```
**What happens when context limits are exceeded:**
- ❌ **Error message**: `"Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."`
- 🛑 **Execution stops**: Task execution halts immediately
- 🔧 **Manual intervention required**: You need to modify your approach
### Choosing the Right Setting
#### Use `respect_context_window=True` (Default) when:
- **Processing large documents** that might exceed context limits
- **Long-running conversations** where some summarization is acceptable
- **Research tasks** where general context is more important than exact details
- **Prototyping and development** where you want robust execution
```python Code
# Perfect for document processing
document_processor = Agent(
role="Document Analyst",
goal="Extract insights from large research papers",
backstory="Expert at analyzing extensive documentation",
respect_context_window=True, # Handle large documents gracefully
max_iter=50, # Allow more iterations for complex analysis
verbose=True
)
```
#### Use `respect_context_window=False` when:
- **Precision is critical** and information loss is unacceptable
- **Legal or medical tasks** requiring complete context
- **Code review** where missing details could introduce bugs
- **Financial analysis** where accuracy is paramount
```python Code
# Perfect for precision tasks
precision_agent = Agent(
role="Code Security Auditor",
goal="Identify security vulnerabilities in code",
backstory="Security expert requiring complete code context",
respect_context_window=False, # Prefer failure over incomplete analysis
max_retry_limit=1, # Fail fast on context issues
verbose=True
)
```
### Alternative Approaches for Large Data
When dealing with very large datasets, consider these strategies:
#### 1. Use RAG Tools
```python Code
from crewai_tools import RagTool
# Create RAG tool for large document processing
rag_tool = RagTool()
rag_agent = Agent(
role="Research Assistant",
goal="Query large knowledge bases efficiently",
backstory="Expert at using RAG tools for information retrieval",
tools=[rag_tool], # Use RAG instead of large context windows
respect_context_window=True,
verbose=True
)
```
#### 2. Use Knowledge Sources
```python Code
# Use knowledge sources instead of large prompts
knowledge_agent = Agent(
role="Knowledge Expert",
goal="Answer questions using curated knowledge",
backstory="Expert at leveraging structured knowledge sources",
knowledge_sources=[your_knowledge_sources], # Pre-processed knowledge
respect_context_window=True,
verbose=True
)
```
### Context Window Best Practices
1. **Monitor Context Usage**: Enable `verbose=True` to see context management in action
2. **Design for Efficiency**: Structure tasks to minimize context accumulation
3. **Use Appropriate Models**: Choose LLMs with context windows suitable for your tasks
4. **Test Both Settings**: Try both `True` and `False` to see which works better for your use case
5. **Combine with RAG**: Use RAG tools for very large datasets instead of relying solely on context windows
### Troubleshooting Context Issues
**If you're getting context limit errors:**
```python Code
# Quick fix: Enable automatic handling
agent.respect_context_window = True
# Better solution: Use RAG tools for large data
from crewai_tools import RagTool
agent.tools = [RagTool()]
# Alternative: Break tasks into smaller pieces
# Or use knowledge sources instead of large prompts
```
**If automatic summarization loses important information:**
```python Code
# Disable auto-summarization and use RAG instead
agent = Agent(
role="Detailed Analyst",
goal="Maintain complete information accuracy",
backstory="Expert requiring full context",
respect_context_window=False, # No summarization
tools=[RagTool()], # Use RAG for large data
verbose=True
)
```
<Note>
The context window management feature works automatically in the background.
You don't need to call any special functions - just set
`respect_context_window` to your preferred behavior and CrewAI handles the
rest!
</Note>
## Direct Agent Interaction with `kickoff()`
Agents can be used directly without going through a task or crew workflow using the `kickoff()` method. This provides a simpler way to interact with an agent when you don't need the full crew orchestration capabilities.
### How `kickoff()` Works
The `kickoff()` method allows you to send messages directly to an agent and get a response, similar to how you would interact with an LLM but with all the agent's capabilities (tools, reasoning, etc.).
```python Code
from crewai import Agent
from crewai_tools import SerperDevTool
# Create an agent
researcher = Agent(
role="AI Technology Researcher",
goal="Research the latest AI developments",
tools=[SerperDevTool()],
verbose=True
)
# Use kickoff() to interact directly with the agent
result = researcher.kickoff("What are the latest developments in language models?")
# Access the raw response
print(result.raw)
```
### Parameters and Return Values
| Parameter | Type | Description |
| :---------------- | :--------------------------------- | :------------------------------------------------------------------------ |
| `messages` | `Union[str, List[Dict[str, str]]]` | Either a string query or a list of message dictionaries with role/content |
| `response_format` | `Optional[Type[Any]]` | Optional Pydantic model for structured output |
The method returns a `LiteAgentOutput` object with the following properties:
- `raw`: String containing the raw output text
- `pydantic`: Parsed Pydantic model (if a `response_format` was provided)
- `agent_role`: Role of the agent that produced the output
- `usage_metrics`: Token usage metrics for the execution
### Structured Output
You can get structured output by providing a Pydantic model as the `response_format`:
```python Code
from pydantic import BaseModel
from typing import List
class ResearchFindings(BaseModel):
main_points: List[str]
key_technologies: List[str]
future_predictions: str
# Get structured output
result = researcher.kickoff(
"Summarize the latest developments in AI for 2025",
response_format=ResearchFindings
)
# Access structured data
print(result.pydantic.main_points)
print(result.pydantic.future_predictions)
```
### Multiple Messages
You can also provide a conversation history as a list of message dictionaries:
```python Code
messages = [
{"role": "user", "content": "I need information about large language models"},
{"role": "assistant", "content": "I'd be happy to help with that! What specifically would you like to know?"},
{"role": "user", "content": "What are the latest developments in 2025?"}
]
result = researcher.kickoff(messages)
```
### Async Support
An asynchronous version is available via `kickoff_async()` with the same parameters:
```python Code
import asyncio
async def main():
result = await researcher.kickoff_async("What are the latest developments in AI?")
print(result.raw)
asyncio.run(main())
```
<Note>
The `kickoff()` method uses a `LiteAgent` internally, which provides a simpler
execution flow while preserving all of the agent's configuration (role, goal,
backstory, tools, etc.).
</Note>
## Important Considerations and Best Practices
### Security and Code Execution
- When using `allow_code_execution`, be cautious with user input and always validate it
- Use `code_execution_mode: "safe"` (Docker) in production environments
- Consider setting appropriate `max_execution_time` limits to prevent infinite loops
### Performance Optimization
- Use `respect_context_window: true` to prevent token limit issues
- Set appropriate `max_rpm` to avoid rate limiting
- Enable `cache: true` to improve performance for repetitive tasks
- Adjust `max_iter` and `max_retry_limit` based on task complexity
### Memory and Context Management
- Leverage `knowledge_sources` for domain-specific information
- Configure `embedder` when using custom embedding models
- Use custom templates (`system_template`, `prompt_template`, `response_template`) for fine-grained control over agent behavior
### Advanced Features
- Enable `reasoning: true` for agents that need to plan and reflect before executing complex tasks
- Set appropriate `max_reasoning_attempts` to control planning iterations (None for unlimited attempts)
- Use `inject_date: true` to provide agents with current date awareness for time-sensitive tasks
- Customize the date format with `date_format` using standard Python datetime format codes
- Enable `multimodal: true` for agents that need to process both text and visual content
### Agent Collaboration
- Enable `allow_delegation: true` when agents need to work together
- Use `step_callback` to monitor and log agent interactions
- Consider using different LLMs for different purposes:
- Main `llm` for complex reasoning
- `function_calling_llm` for efficient tool usage
### Date Awareness and Reasoning
- Use `inject_date: true` to provide agents with current date awareness for time-sensitive tasks
- Customize the date format with `date_format` using standard Python datetime format codes
- Valid format codes include: %Y (year), %m (month), %d (day), %B (full month name), etc.
- Invalid date formats will be logged as warnings and will not modify the task description
- Enable `reasoning: true` for complex tasks that benefit from upfront planning and reflection
### Model Compatibility
- Set `use_system_prompt: false` for older models that don't support system messages
- Ensure your chosen `llm` supports the features you need (like function calling)
## Troubleshooting Common Issues
1. **Rate Limiting**: If you're hitting API rate limits:
- Implement appropriate `max_rpm`
- Use caching for repetitive operations
- Consider batching requests
2. **Context Window Errors**: If you're exceeding context limits:
- Enable `respect_context_window`
- Use more efficient prompts
- Clear agent memory periodically
3. **Code Execution Issues**: If code execution fails:
- Verify Docker is installed for safe mode
- Check execution permissions
- Review code sandbox settings
4. **Memory Issues**: If agent responses seem inconsistent:
- Check knowledge source configuration
- Review conversation history management
Remember that agents are most effective when configured according to their specific use case. Take time to understand your requirements and adjust these parameters accordingly.

541
docs/v1.11.0/en/concepts/cli.mdx Normal file
View File

@@ -0,0 +1,541 @@
---
title: CLI
description: Learn how to use the CrewAI CLI to interact with CrewAI.
icon: terminal
mode: "wide"
---
<Warning>
Since release 0.140.0, CrewAI AMP started a process of migrating their login
provider. As such, the authentication flow via CLI was updated. Users that use
Google to login, or that created their account after July 3rd, 2025 will be
unable to log in with older versions of the `crewai` library.
</Warning>
## Overview
The CrewAI CLI provides a set of commands to interact with CrewAI, allowing you to create, train, run, and manage crews & flows.
## Installation
To use the CrewAI CLI, make sure you have CrewAI installed:
```shell Terminal
pip install crewai
```
## Basic Usage
The basic structure of a CrewAI CLI command is:
```shell Terminal
crewai [COMMAND] [OPTIONS] [ARGUMENTS]
```
## Available Commands
### 1. Create
Create a new crew or flow.
```shell Terminal
crewai create [OPTIONS] TYPE NAME
```
- `TYPE`: Choose between "crew" or "flow"
- `NAME`: Name of the crew or flow
Example:
```shell Terminal
crewai create crew my_new_crew
crewai create flow my_new_flow
```
### 2. Version
Show the installed version of CrewAI.
```shell Terminal
crewai version [OPTIONS]
```
- `--tools`: (Optional) Show the installed version of CrewAI tools
Example:
```shell Terminal
crewai version
crewai version --tools
```
### 3. Train
Train the crew for a specified number of iterations.
```shell Terminal
crewai train [OPTIONS]
```
- `-n, --n_iterations INTEGER`: Number of iterations to train the crew (default: 5)
- `-f, --filename TEXT`: Path to a custom file for training (default: "trained_agents_data.pkl")
Example:
```shell Terminal
crewai train -n 10 -f my_training_data.pkl
```
### 4. Replay
Replay the crew execution from a specific task.
```shell Terminal
crewai replay [OPTIONS]
```
- `-t, --task_id TEXT`: Replay the crew from this task ID, including all subsequent tasks
Example:
```shell Terminal
crewai replay -t task_123456
```
### 5. Log-tasks-outputs
Retrieve your latest crew.kickoff() task outputs.
```shell Terminal
crewai log-tasks-outputs
```
### 6. Reset-memories
Reset the crew memories (long, short, entity, latest_crew_kickoff_outputs).
```shell Terminal
crewai reset-memories [OPTIONS]
```
- `-l, --long`: Reset LONG TERM memory
- `-s, --short`: Reset SHORT TERM memory
- `-e, --entities`: Reset ENTITIES memory
- `-k, --kickoff-outputs`: Reset LATEST KICKOFF TASK OUTPUTS
- `-kn, --knowledge`: Reset KNOWLEDGE storage
- `-akn, --agent-knowledge`: Reset AGENT KNOWLEDGE storage
- `-a, --all`: Reset ALL memories
Example:
```shell Terminal
crewai reset-memories --long --short
crewai reset-memories --all
```
### 7. Test
Test the crew and evaluate the results.
```shell Terminal
crewai test [OPTIONS]
```
- `-n, --n_iterations INTEGER`: Number of iterations to test the crew (default: 3)
- `-m, --model TEXT`: LLM Model to run the tests on the Crew (default: "gpt-4o-mini")
Example:
```shell Terminal
crewai test -n 5 -m gpt-3.5-turbo
```
### 8. Run
Run the crew or flow.
```shell Terminal
crewai run
```
<Note>
Starting from version 0.103.0, the `crewai run` command can be used to run
both standard crews and flows. For flows, it automatically detects the type
from pyproject.toml and runs the appropriate command. This is now the
recommended way to run both crews and flows.
</Note>
<Note>
Make sure to run these commands from the directory where your CrewAI project
is set up. Some commands may require additional configuration or setup within
your project structure.
</Note>
### 9. Chat
Starting in version `0.98.0`, when you run the `crewai chat` command, you start an interactive session with your crew. The AI assistant will guide you by asking for necessary inputs to execute the crew. Once all inputs are provided, the crew will execute its tasks.
After receiving the results, you can continue interacting with the assistant for further instructions or questions.
```shell Terminal
crewai chat
```
<Note>
Ensure you execute these commands from your CrewAI project's root directory.
</Note>
<Note>
IMPORTANT: Set the `chat_llm` property in your `crew.py` file to enable this command.
```python
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
chat_llm="gpt-4o", # LLM for chat orchestration
)
```
</Note>
### 10. Deploy
Deploy the crew or flow to [CrewAI AMP](https://app.crewai.com).
- **Authentication**: You need to be authenticated to deploy to CrewAI AMP.
You can login or create an account with:
```shell Terminal
crewai login
```
- **Create a deployment**: Once you are authenticated, you can create a deployment for your crew or flow from the root of your localproject.
```shell Terminal
crewai deploy create
```
- Reads your local project configuration.
- Prompts you to confirm the environment variables (like `OPENAI_API_KEY`, `SERPER_API_KEY`) found locally. These will be securely stored with the deployment on the Enterprise platform. Ensure your sensitive keys are correctly configured locally (e.g., in a `.env` file) before running this.
### 11. Organization Management
Manage your CrewAI AMP organizations.
```shell Terminal
crewai org [COMMAND] [OPTIONS]
```
#### Commands:
- `list`: List all organizations you belong to
```shell Terminal
crewai org list
```
- `current`: Display your currently active organization
```shell Terminal
crewai org current
```
- `switch`: Switch to a specific organization
```shell Terminal
crewai org switch <organization_id>
```
<Note>
You must be authenticated to CrewAI AMP to use these organization management
commands.
</Note>
- **Create a deployment** (continued):
- Links the deployment to the corresponding remote GitHub repository (it usually detects this automatically).
- **Deploy the Crew**: Once you are authenticated, you can deploy your crew or flow to CrewAI AMP.
```shell Terminal
crewai deploy push
```
- Initiates the deployment process on the CrewAI AMP platform.
- Upon successful initiation, it will output the Deployment created successfully! message along with the Deployment Name and a unique Deployment ID (UUID).
- **Deployment Status**: You can check the status of your deployment with:
```shell Terminal
crewai deploy status
```
This fetches the latest deployment status of your most recent deployment attempt (e.g., `Building Images for Crew`, `Deploy Enqueued`, `Online`).
- **Deployment Logs**: You can check the logs of your deployment with:
```shell Terminal
crewai deploy logs
```
This streams the deployment logs to your terminal.
- **List deployments**: You can list all your deployments with:
```shell Terminal
crewai deploy list
```
This lists all your deployments.
- **Delete a deployment**: You can delete a deployment with:
```shell Terminal
crewai deploy remove
```
This deletes the deployment from the CrewAI AMP platform.
- **Help Command**: You can get help with the CLI with:
```shell Terminal
crewai deploy --help
```
This shows the help message for the CrewAI Deploy CLI.
Watch this video tutorial for a step-by-step demonstration of deploying your crew to [CrewAI AMP](http://app.crewai.com) using the CLI.
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/3EqSV-CYDZA"
title="CrewAI Deployment Guide"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
### 11. 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 `crewai create crew` command, the CLI will show you a list of available LLM providers to choose from, followed by model selection for your chosen provider.
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 <key> <value>
```
- `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
```
<Tip>
After resetting configuration, re-run `crewai login` to authenticate again.
</Tip>
### 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
<Note>
**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.
</Note>
<Tip>
For more information about tracing, see the [Tracing
documentation](/observability/tracing).
</Tip>
<Tip>
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.
</Tip>
<Note>
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.
</Note>

363
docs/v1.11.0/en/concepts/collaboration.mdx Normal file
View File

@@ -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.

419
docs/v1.11.0/en/concepts/crews.mdx Normal file
View File

@@ -0,0 +1,419 @@
---
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`. |
<Tip>
**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.
</Tip>
## Creating Crews
There are two ways to create crews in CrewAI: using **YAML configuration (recommended)** or defining them **directly in code**.
### YAML Configuration (Recommended)
Using YAML configuration provides a cleaner, more maintainable way to define crews and is consistent with how agents and tasks are defined in CrewAI projects.
After creating your CrewAI project as outlined in the [Installation](/en/installation) section, you can define your crew in a class that inherits from `CrewBase` and uses decorators to define agents, tasks, and the crew itself.
#### Example Crew Class with Decorators
```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]
# Paths to your YAML configuration files
# To see an example agent and task defined in YAML, checkout the following:
# - Task: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended
# - Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended
agents_config = 'config/agents.yaml'
tasks_config = 'config/tasks.yaml'
@before_kickoff
def prepare_inputs(self, inputs):
# Modify inputs before the crew starts
inputs['additional_data'] = "Some extra information"
return inputs
@after_kickoff
def process_output(self, output):
# Modify output after the crew finishes
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, # Automatically collected by the @agent decorator
tasks=self.tasks, # Automatically collected by the @task decorator.
process=Process.sequential,
verbose=True,
)
```
How to run the above code:
```python code
YourCrewName().crew().kickoff(inputs={"any": "input here"})
```
<Note>
Tasks will be executed in the order they are defined.
</Note>
The `CrewBase` class, along with these decorators, automates the collection of agents and tasks, reducing the need for manual management.
#### Decorators overview from `annotations.py`
CrewAI provides several decorators in the `annotations.py` file that are used to mark methods within your crew class for special handling:
- `@CrewBase`: Marks the class as a crew base class.
- `@agent`: Denotes a method that returns an `Agent` object.
- `@task`: Denotes a method that returns a `Task` object.
- `@crew`: Denotes the method that returns the `Crew` object.
- `@before_kickoff`: (Optional) Marks a method to be executed before the crew starts.
- `@after_kickoff`: (Optional) Marks a method to be executed after the crew finishes.
These decorators help in organizing your crew's structure and automatically collecting agents and tasks without manually listing them.
### 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
```
## 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 |
<Note>
For high-concurrency workloads, `akickoff()` and `akickoff_for_each()` are recommended as they use native async for task execution, memory operations, and knowledge retrieval.
</Note>
```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 <task_id>`, 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 <task_id>
```
These commands let you replay from your latest kickoff tasks, still retaining context from previously executed tasks.

323
docs/v1.11.0/en/concepts/event-listener.mdx Normal file
View File

@@ -0,0 +1,323 @@
---
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.
<Note type="info" title="Enterprise Enhancement: Prompt Tracing">
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
</Note>
## 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
### 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
### 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.
### Flow Events
- **FlowCreatedEvent**: Emitted when a Flow is created
- **FlowStartedEvent**: Emitted when a Flow starts execution
- **FlowFinishedEvent**: Emitted when a Flow completes execution
- **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
### 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
### 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.
## 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.

267
docs/v1.11.0/en/concepts/files.mdx Normal file
View File

@@ -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.
<Note type="info" title="Optional Dependency">
File support requires the optional `crewai-files` package. Install it with:
```bash
uv add 'crewai[file-processing]'
```
</Note>
<Note type="warning" title="Early Access">
The file processing API is currently in early access.
</Note>
## 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) | ✓ | | ✓ | | |
<Note type="info" title="Gemini for Maximum File Support">
Google Gemini models support all file types including video (up to 1 hour, 2GB). Use Gemini when you need to process video content.
</Note>
<Note type="warning" title="Unsupported File Types">
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.
</Note>
## 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** | ✓ | | ✓ |
<Note type="info" title="Automatic Optimization">
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.
</Note>
## 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"),
}
)
```

1067
docs/v1.11.0/en/concepts/flows.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1097
docs/v1.11.0/en/concepts/knowledge.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1531
docs/v1.11.0/en/concepts/llms.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

878
docs/v1.11.0/en/concepts/memory.mdx Normal file
View File

@@ -0,0 +1,878 @@
---
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.
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. You can configure this in three ways.
### Passing to Memory Directly
```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)
```
### 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-small"}},
)
```
### Provider Examples
<AccordionGroup>
<Accordion title="OpenAI (default)">
```python
memory = Memory(embedder={
"provider": "openai",
"config": {
"model_name": "text-embedding-3-small",
# "api_key": "sk-...", # or set OPENAI_API_KEY env var
},
})
```
</Accordion>
<Accordion title="Ollama (local, private)">
```python
memory = Memory(embedder={
"provider": "ollama",
"config": {
"model_name": "mxbai-embed-large",
"url": "http://localhost:11434/api/embeddings",
},
})
```
</Accordion>
<Accordion title="Azure OpenAI">
```python
memory = Memory(embedder={
"provider": "azure",
"config": {
"deployment_id": "your-embedding-deployment",
"api_key": "your-azure-api-key",
"api_base": "https://your-resource.openai.azure.com",
"api_version": "2024-02-01",
},
})
```
</Accordion>
<Accordion title="Google AI">
```python
memory = Memory(embedder={
"provider": "google-generativeai",
"config": {
"model_name": "gemini-embedding-001",
# "api_key": "...", # or set GOOGLE_API_KEY env var
},
})
```
</Accordion>
<Accordion title="Google Vertex AI">
```python
memory = Memory(embedder={
"provider": "google-vertex",
"config": {
"model_name": "gemini-embedding-001",
"project_id": "your-gcp-project-id",
"location": "us-central1",
},
})
```
</Accordion>
<Accordion title="Cohere">
```python
memory = Memory(embedder={
"provider": "cohere",
"config": {
"model_name": "embed-english-v3.0",
# "api_key": "...", # or set COHERE_API_KEY env var
},
})
```
</Accordion>
<Accordion title="VoyageAI">
```python
memory = Memory(embedder={
"provider": "voyageai",
"config": {
"model": "voyage-3",
# "api_key": "...", # or set VOYAGE_API_KEY env var
},
})
```
</Accordion>
<Accordion title="AWS Bedrock">
```python
memory = Memory(embedder={
"provider": "amazon-bedrock",
"config": {
"model_name": "amazon.titan-embed-text-v1",
# Uses default AWS credentials (boto3 session)
},
})
```
</Accordion>
<Accordion title="Hugging Face">
```python
memory = Memory(embedder={
"provider": "huggingface",
"config": {
"model_name": "sentence-transformers/all-MiniLM-L6-v2",
},
})
```
</Accordion>
<Accordion title="Jina">
```python
memory = Memory(embedder={
"provider": "jina",
"config": {
"model_name": "jina-embeddings-v2-base-en",
# "api_key": "...", # or set JINA_API_KEY env var
},
})
```
</Accordion>
<Accordion title="IBM WatsonX">
```python
memory = Memory(embedder={
"provider": "watsonx",
"config": {
"model_id": "ibm/slate-30m-english-rtrvr",
"api_key": "your-watsonx-api-key",
"project_id": "your-project-id",
"url": "https://us-south.ml.cloud.ibm.com",
},
})
```
</Accordion>
<Accordion title="Custom Embedder">
```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)
```
</Accordion>
</AccordionGroup>
### Provider Reference
| Provider | Key | Typical Model | Notes |
| :--- | :--- | :--- | :--- |
| OpenAI | `openai` | `text-embedding-3-small` | Default. Set `OPENAI_API_KEY`. |
| Ollama | `ollama` | `mxbai-embed-large` | Local, no API key needed. |
| Azure OpenAI | `azure` | `text-embedding-ada-002` | 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).
**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 default) | 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. |

155
docs/v1.11.0/en/concepts/planning.mdx Normal file
View File

@@ -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:
<CodeGroup>
```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,
)
```
</CodeGroup>
From this point on, your crew will have planning enabled, and the tasks will be planned before each iteration.
<Warning>
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.
</Warning>
#### 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.
<CodeGroup>
```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 '```'.
```
</CodeGroup>

67
docs/v1.11.0/en/concepts/processes.mdx Normal file
View File

@@ -0,0 +1,67 @@
---
title: Processes
description: Detailed guide on workflow management through processes in CrewAI, with updated implementation details.
icon: bars-staggered
mode: "wide"
---
## Overview
<Tip>
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.
</Tip>
## 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.
- **Consensual Process (Planned)**: Aiming for collaborative decision-making among agents on task execution, this process type introduces a democratic approach to task management within CrewAI. It is planned for future development and is not currently implemented in the codebase.
## 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`). The consensual process is planned for future inclusion, emphasizing our commitment to continuous development and innovation.
## 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, enhancements, and the planned integration of the Consensual Process, ensuring users have access to the most current and comprehensive information.

154
docs/v1.11.0/en/concepts/production-architecture.mdx Normal file
View File

@@ -0,0 +1,154 @@
---
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]):
# ...
```
## Summary
- **Start with a Flow.**
- **Define a clear State.**
- **Use Crews for complex tasks.**
- **Deploy with an API and persistence.**

148
docs/v1.11.0/en/concepts/reasoning.mdx Normal file
View File

@@ -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
<ParamField body="reasoning" type="bool" default="False">
Enable or disable reasoning
</ParamField>
<ParamField body="max_reasoning_attempts" type="int" default="None">
Maximum number of attempts to refine the plan before proceeding with execution. If None (default), the agent will continue refining until it's ready.
</ParamField>
## 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.

1086
docs/v1.11.0/en/concepts/tasks.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

49
docs/v1.11.0/en/concepts/testing.mdx Normal file
View File

@@ -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:
<center>**Tasks Scores (1-10 Higher is better)**</center>
| 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.

287
docs/v1.11.0/en/concepts/tools.mdx Normal file
View File

@@ -0,0 +1,287 @@
---
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.
## 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.
<Note type="info" title="Enterprise Enhancement: Tools Repository">
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
</Note>
## 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.
## 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** | A tool designed for performing exhaustive searches across various data sources. |
| **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
<Tip>
Developers can craft `custom tools` tailored for their agent's needs or
utilize pre-built options.
</Tip>
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"
```
## 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
<Tip>
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.
</Tip>
```python Code
from crewai.tools import tool
@tool
def multiplication_tool(first_number: int, second_number: int) -> str:
"""Useful for when you need to multiply two numbers together."""
return first_number * second_number
def cache_func(args, result):
# 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.

197
docs/v1.11.0/en/concepts/training.mdx Normal file
View File

@@ -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 <n_iterations>`, 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 <n_iterations> -f <filename.pkl>
```
<Tip>
Replace `<n_iterations>` with the desired number of training iterations and `<filename>` with the appropriate filename ending with `.pkl`.
</Tip>
<Note>
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.
</Note>
### 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<br/>CLI: crewai train -n -f<br/>or Python: crew.train(...)"] --> B["Setup training mode<br/>- task.human_input = true<br/>- disable delegation<br/>- init training_data.pkl + trained file"]
subgraph "Iterations"
direction LR
C["Iteration i<br/>initial_output"] --> D["User human_feedback"]
D --> E["improved_output"]
E --> F["Append to training_data.pkl<br/>by agent_id and iteration"]
end
B --> C
F --> G{"More iterations?"}
G -- "Yes" --> C
G -- "No" --> H["Evaluate per agent<br/>aggregate iterations"]
H --> I["Consolidate<br/>suggestions[] + quality + final_summary"]
I --> J["Save by agent role to trained file<br/>(default: trained_agents_data.pkl)"]
J --> K["Normal (non-training) runs"]
K --> L["Auto-load suggestions<br/>from trained_agents_data.pkl"]
L --> M["Append to prompt<br/>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
<Warning>
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.
</Warning>
### Limitations of Small Models in Training Evaluation
<CardGroup cols={2}>
<Card title="JSON Output Accuracy" icon="triangle-exclamation">
Smaller models often struggle with producing valid JSON responses needed for structured training evaluations, leading to parsing errors and incomplete data.
</Card>
<Card title="Evaluation Quality" icon="chart-line">
Models under 7B parameters may provide less nuanced evaluations with limited reasoning depth compared to larger models.
</Card>
<Card title="Instruction Following" icon="list-check">
Complex training evaluation criteria may not be fully followed or considered by smaller models.
</Card>
<Card title="Consistency" icon="rotate">
Evaluations across multiple training iterations may lack consistency with smaller models.
</Card>
</CardGroup>
### Recommendations for Training
<Tabs>
<Tab title="Best Practice">
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
)
```
<Tip>
More powerful models provide higher quality feedback with better reasoning, leading to more effective training iterations.
</Tip>
</Tab>
<Tab title="Small Model Usage">
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")
```
<Warning>
While CrewAI includes optimizations for small models, expect less reliable and less nuanced evaluation results that may require more human intervention during training.
</Warning>
</Tab>
</Tabs>
### 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, either rename it to `trained_agents_data.pkl` before running, or adjust the loader in code.
- 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.

155
docs/v1.11.0/en/enterprise/features/agent-repositories.mdx Normal file
View File

@@ -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.
<Frame>
![Agent Repositories](/images/enterprise/agent-repositories.png)
</Frame>
## 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.
<Frame>
![Agent Repositories](/images/enterprise/create-agent-repository.png)
</Frame>
### 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 <org_id>
# List all available organizations
crewai org list
```
<Note>
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.
</Note>

104
docs/v1.11.0/en/enterprise/features/automations.mdx Normal file
View File

@@ -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.
<Frame>
![Automations Overview](/images/enterprise/automations-overview.png)
</Frame>
## Deployment Methods
### Deploy from GitHub
Use this for version‑controlled projects and continuous deployment.
<Steps>
<Step title="Connect GitHub">
Click <b>Configure GitHub</b> and authorize access.
</Step>
<Step title="Select Repository & Branch">
Choose the <b>Repository</b> and <b>Branch</b> you want to deploy from.
</Step>
<Step title="Enable Auto‑deploy (optional)">
Turn on <b>Automatically deploy new commits</b> to ship updates on every push.
</Step>
<Step title="Add Environment Variables">
Add secrets individually or use <b>Bulk View</b> for multiple variables.
</Step>
<Step title="Deploy">
Click <b>Deploy</b> to create your live automation.
</Step>
</Steps>
<Frame>
![GitHub Deployment](/images/enterprise/deploy-from-github.png)
</Frame>
### Deploy from ZIP
Ship quickly without Git—upload a compressed package of your project.
<Steps>
<Step title="Choose File">
Select the ZIP archive from your computer.
</Step>
<Step title="Add Environment Variables">
Provide any required variables or keys.
</Step>
<Step title="Deploy">
Click <b>Deploy</b> to create your live automation.
</Step>
</Steps>
<Frame>
![ZIP Deployment](/images/enterprise/deploy-from-zip.png)
</Frame>
## 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 <b>Status</b>
- Filter by <b>Source</b> (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`.
<Frame>
![Automations Table](/images/enterprise/automations-table.png)
</Frame>
## 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
<CardGroup cols={3}>
<Card title="Deploy a Crew" href="/en/enterprise/guides/deploy-crew" icon="rocket">
Deploy a Crew from GitHub or ZIP file.
</Card>
<Card title="Automation Triggers" href="/en/enterprise/guides/automation-triggers" icon="trigger">
Trigger automations via webhooks or API.
</Card>
<Card title="Webhook Automation" href="/en/enterprise/guides/webhook-automation" icon="webhook">
Stream real-time events and updates to your systems.
</Card>
</CardGroup>

88
docs/v1.11.0/en/enterprise/features/crew-studio.mdx Normal file
View File

@@ -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.
<Frame>
![Crew Studio Overview](/images/enterprise/crew-studio-overview.png)
</Frame>
## 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.
<Frame>
![Prompt Builder](/images/enterprise/crew-studio-prompt.png)
</Frame>
## 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)
<Frame>
![Visual Canvas](/images/enterprise/crew-studio-canvas.png)
</Frame>
## Execution & Debugging
Switch to the <b>Execution</b> view to run and observe the workflow:
- Event timeline
- Detailed logs (Details, Messages, Raw Data)
- Local test runs before publishing
<Frame>
![Execution View](/images/enterprise/crew-studio-execution.png)
</Frame>
## Publish & Export
- <b>Publish</b> to deploy a live automation
- <b>Download</b> source as a ZIP for local development or customization
<Frame>
![Publish & Download](/images/enterprise/crew-studio-publish.png)
</Frame>
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`.
<Frame>
![Published Automation](/images/enterprise/crew-studio-published.png)
</Frame>
## 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
<CardGroup cols={4}>
<Card title="Enable Crew Studio" href="/en/enterprise/guides/enable-crew-studio" icon="palette">
Enable Crew Studio.
</Card>
<Card title="Build a Crew" href="/en/enterprise/guides/build-crew" icon="paintbrush">
Build a Crew.
</Card>
<Card title="Deploy a Crew" href="/en/enterprise/guides/deploy-crew" icon="rocket">
Deploy a Crew from GitHub or ZIP file.
</Card>
<Card title="Export a React Component" href="/en/enterprise/guides/react-component-export" icon="download">
Export a React Component.
</Card>
</CardGroup>

558
docs/v1.11.0/en/enterprise/features/flow-hitl-management.mdx Normal file
View File

@@ -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"
---
<Note>
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.
</Note>
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
<CardGroup cols={3}>
<Card title="Email-First Design" icon="envelope">
Responders can reply directly to notification emails to provide feedback
</Card>
<Card title="Flexible Routing" icon="route">
Route requests to specific emails based on method patterns or flow state
</Card>
<Card title="Auto-Response" icon="clock">
Configure automatic fallback responses when no human replies in time
</Card>
</CardGroup>
### 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**
<Frame>
<img src="/images/enterprise/hitl-settings-overview.png" alt="HITL Configuration Settings" />
</Frame>
### Email Notifications
Toggle to enable or disable email notifications for HITL requests.
| Setting | Default | Description |
|---------|---------|-------------|
| Email Notifications | Enabled | Send emails when feedback is requested |
<Note>
When disabled, responders must use the dashboard UI or you must configure webhooks for custom notification systems.
</Note>
### 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
<Steps>
<Step title="Notification Sent">
When a HITL request is created, an email is sent to the assigned responder with the review content and context.
</Step>
<Step title="Reply-To Address">
The email includes a special reply-to address with a signed token for authentication.
</Step>
<Step title="User Replies">
The responder simply replies to the email with their feedback—no login required.
</Step>
<Step title="Token Validation">
The platform receives the reply, verifies the signed token, and matches the sender email.
</Step>
<Step title="Flow Resumes">
The feedback is recorded and the flow continues with the human's input.
</Step>
</Steps>
### 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.
<Frame>
<img src="/images/enterprise/hitl-settings-routing-rules.png" alt="HITL Routing Rules Configuration" />
</Frame>
### 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.
<Tip>
**Use Case**: Pull the assignee from your CRM, database, or previous flow step to dynamically route reviews to the right person.
</Tip>
## 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) |
<Frame>
<img src="/images/enterprise/hitl-settings-auto-respond.png" alt="HITL Auto-Response Configuration" />
</Frame>
### 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
<Warning>
Use auto-response carefully. Only enable it for non-critical reviews where a default response is acceptable.
</Warning>
## 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
<Frame>
<img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="HITL Pending Requests List" />
</Frame>
### 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
<Frame>
<img src="/images/enterprise/hitl-metrics.png" alt="HITL Metrics Dashboard" />
</Frame>
<CardGroup cols={2}>
<Card title="Response Times" icon="stopwatch">
Monitor average and median response times by reviewer or flow.
</Card>
<Card title="Volume Trends" icon="chart-bar">
Analyze review volume patterns to optimize team capacity.
</Card>
<Card title="Decision Distribution" icon="chart-pie">
View approval/rejection rates across different review types.
</Card>
<Card title="SLA Tracking" icon="chart-line">
Track percentage of reviews completed within SLA targets.
</Card>
</CardGroup>
### 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
<AccordionGroup>
<Accordion title="Security Reviews" icon="shield-halved">
**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
</Accordion>
<Accordion title="Content Approval" icon="file-lines">
**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
</Accordion>
<Accordion title="Financial Approvals" icon="money-bill">
**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
</Accordion>
<Accordion title="Dynamic Assignment from CRM" icon="database">
**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
</Accordion>
<Accordion title="Quality Assurance" icon="magnifying-glass">
**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
</Accordion>
</AccordionGroup>
## 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
<Frame>
<img src="/images/enterprise/hitl-settings-webhook.png" alt="HITL Webhook Configuration" />
</Frame>
### Configuring Webhooks
<Steps>
<Step title="Navigate to Settings">
Go to your **Deployment** → **Settings** → **Human in the Loop**
</Step>
<Step title="Expand Webhooks Section">
Click to expand the **Webhooks** configuration
</Step>
<Step title="Add Your Webhook URL">
Enter your webhook URL (must be HTTPS in production)
</Step>
<Step title="Save Configuration">
Click **Save Configuration** to activate
</Step>
</Steps>
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
<Info>
All webhook requests are cryptographically signed using HMAC-SHA256 to ensure authenticity and prevent tampering.
</Info>
#### 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=<hex_digest>` |
| `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
<Tip>
**Start Simple**: Begin with email notifications to deployment creator, then add routing rules as your workflows mature.
</Tip>
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
<CardGroup cols={2}>
<Card title="Human Feedback in Flows" icon="code" href="/en/learn/human-feedback-in-flows">
Implementation guide for the `@human_feedback` decorator
</Card>
<Card title="Flow HITL Workflow Guide" icon="route" href="/en/enterprise/guides/human-in-the-loop">
Step-by-step guide for setting up HITL workflows
</Card>
<Card title="RBAC Configuration" icon="shield-check" href="/en/enterprise/features/rbac">
Configure role-based access control for your organization
</Card>
<Card title="Webhook Streaming" icon="bolt" href="/en/enterprise/features/webhook-streaming">
Set up real-time event notifications
</Card>
</CardGroup>

251
docs/v1.11.0/en/enterprise/features/hallucination-guardrail.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Provide Comprehensive Context">
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.
"""
```
</Step>
<Step title="Keep Context Relevant">
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."
```
</Step>
<Step title="Update Context Regularly">
Ensure your reference context reflects current, accurate information.
</Step>
</Steps>
### Threshold Selection
<Steps>
<Step title="Start with Default Validation">
Begin without custom thresholds to understand baseline performance.
</Step>
<Step title="Adjust Based on Requirements">
- **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
</Step>
<Step title="Monitor and Iterate">
Track validation results and adjust thresholds based on false positives/negatives.
</Step>
</Steps>
## 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
<Accordion title="Validation Always Fails">
**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
</Accordion>
<Accordion title="False Positives (Valid Content Marked Invalid)">
**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
</Accordion>
<Accordion title="Evaluation Errors">
**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
</Accordion>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with hallucination guardrail configuration or troubleshooting.
</Card>

46
docs/v1.11.0/en/enterprise/features/marketplace.mdx Normal file
View File

@@ -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.
<Frame>
![Marketplace Overview](/images/enterprise/marketplace-overview.png)
</Frame>
## 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
<Frame>
![Install & Configure](/images/enterprise/marketplace-install.png)
</Frame>
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
<CardGroup cols={3}>
<Card title="Tools & Integrations" href="/en/enterprise/features/tools-and-integrations" icon="wrench">
Connect external apps and manage internal tools your agents can use.
</Card>
<Card title="Tool Repository" href="/en/enterprise/guides/tool-repository#tool-repository" icon="toolbox">
Publish and install tools to enhance your crews' capabilities.
</Card>
<Card title="Agents Repository" href="/en/enterprise/features/agent-repositories" icon="people-group">
Store, share, and reuse agent definitions across teams and projects.
</Card>
</CardGroup>

342
docs/v1.11.0/en/enterprise/features/pii-trace-redactions.mdx Normal file
View File

@@ -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.
<Info>
PII Redaction is available on the Enterprise plan.
Deployment must be version 1.8.0 or higher.
</Info>
<Frame>
![PII Redaction Overview](/images/enterprise/pii_mask_recognizer_trace_example.png)
</Frame>
## 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 <EMAIL_ADDRESS> or call <PHONE_NUMBER>"
```
## Enabling PII Redaction
<Info>
You must be on the Enterprise plan and your deployment must be version 1.8.0 or higher to use this feature.
</Info>
<Steps>
<Step title="Navigate to Crew Settings">
In the CrewAI AMP dashboard, select your deployed crew and go to one of your deployments/automations, then navigate to **Settings** → **PII Protection**.
</Step>
<Step title="Enable PII Protection">
Toggle on **PII Redaction for Traces**. This will enable automatic scanning and redaction of trace data.
<Info>
You need to manually enable PII Redaction for each deployment.
</Info>
<Frame>
![Enable PII Redaction](/images/enterprise/pii_mask_recognizer_enable.png)
</Frame>
</Step>
<Step title="Configure Entity Types">
Select which types of PII to detect and redact. Each entity can be individually enabled or disabled.
<Frame>
![Configure Entities](/images/enterprise/pii_mask_recognizer_supported_entities.png)
</Frame>
</Step>
<Step title="Save">
Save your configuration. PII redaction will be active on all subsequent crew executions, no redeployment is needed.
</Step>
</Steps>
## 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 | `<CREDIT_CARD>` |
| `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.
<Frame>
![Custom Recognizers](/images/enterprise/pii_mask_recognizer.png)
</Frame>
### 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
<Steps>
<Step title="Navigate to Custom Recognizers">
Go to your Organization **Settings** → **Organization** → **Add Recognizer**.
</Step>
<Step title="Configure the Recognizer">
<Frame>
![Configure Recognizer](/images/enterprise/pii_mask_recognizer_create.png)
</Frame>
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
</Step>
<Step title="Save">
Save the recognizer. It will be available to enable on your deployments.
</Step>
</Steps>
### 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 <SALARY>"
```
### 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 <PERSON> placed order #12345.
Contact email: <EMAIL_ADDRESS>, phone: <PHONE_NUMBER>.
Payment processed for card ending in <CREDIT_CARD>."
```
Redacted values are clearly marked with angle brackets and the entity type label (e.g., `<EMAIL_ADDRESS>`), making it easy to understand what data was protected while still allowing you to debug and monitor crew behavior.
## Best Practices
### Performance Considerations
<Steps>
<Step title="Enable Only Needed Entities">
Each enabled entity adds processing overhead. Only enable entities relevant to your data.
</Step>
<Step title="Use Specific Patterns">
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.
</Step>
<Step title="Leverage Context Words">
Context words improve accuracy by only triggering detection when surrounding text matches.
</Step>
</Steps>
## Troubleshooting
<Accordion title="PII Not Being Redacted">
**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
</Accordion>
<Accordion title="Too Much Data Being Redacted">
**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
</Accordion>
<Accordion title="Performance Issues">
**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
</Accordion>
---
## 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
<Frame>
![Salary Recognizer Configuration](/images/enterprise/pii_mask_custom_recognizer_salary.png)
</Frame>
| 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 <SALARY> annually"
Original: "Base salary:$50,000 with bonus potential"
Redacted: "Base <SALARY> with bonus potential"
```
<Tip>
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.
</Tip>
### Enable the Recognizer for Your Deployments
<Warning>
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.
</Warning>
After creating your custom recognizer, enable it for each deployment:
<Steps>
<Step title="Navigate to Your Deployment">
Go to your deployment/automation and open **Settings** → **PII Protection**.
</Step>
<Step title="Select Custom Recognizers">
Under **Mask Recognizers**, you'll see your organization-defined recognizers. Check the box next to the recognizers you want to enable.
<Frame>
![Enable Custom Recognizer](/images/enterprise/pii_mask_recognizers_options.png)
</Frame>
</Step>
<Step title="Save Configuration">
Save your changes. The recognizer will be active on all subsequent executions for this deployment.
</Step>
</Steps>
<Info>
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).
</Info>

107
docs/v1.11.0/en/enterprise/features/rbac.mdx Normal file
View File

@@ -0,0 +1,107 @@
---
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 a combination of organization‑level roles and automation‑level visibility controls.
<Frame>
<img src="/images/enterprise/users_and_roles.png" alt="RBAC overview in CrewAI AMP" />
</Frame>
## 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.
<Steps>
<Step title="Open Roles settings">
Go to <b>Settings → Roles</b> in CrewAI AMP.
</Step>
<Step title="Choose a role type">
Use a predefined role (<b>Owner</b>, <b>Member</b>) or click{" "}
<b>Create role</b> to define a custom one.
</Step>
<Step title="Assign to members">
Select users and assign the role. You can change this anytime.
</Step>
</Steps>
### 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 |
## Automation‑level Access Control
In addition to organization‑wide roles, CrewAI Automations support fine‑grained visibility settings that let you restrict access to specific automations 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:
- View the deployment
- Run it or interact with its API
- Access its logs, metrics, and settings
The organization owner always has access, regardless of visibility settings.
You can configure automation‑level access control in Automation → Settings → Visibility tab.
<Steps>
<Step title="Open Visibility tab">
Navigate to <b>Automation → Settings → Visibility</b>.
</Step>
<Step title="Set visibility">
Choose <b>Private</b> to restrict access. The organization owner always
retains access.
</Step>
<Step title="Whitelist access">
Add specific users and roles allowed to view, run, and access
logs/metrics/settings.
</Step>
<Step title="Save and verify">
Save changes, then confirm that non‑whitelisted users cannot view or run the
automation.
</Step>
</Steps>
### Private visibility: access outcomes
| Action | Owner | Whitelisted user/role | Not whitelisted |
| :--------------------------- | :---- | :-------------------- | :-------------- |
| View automation | ✓ | ✓ | ✗ |
| Run automation/API | ✓ | ✓ | ✗ |
| Access logs/metrics/settings | ✓ | ✓ | ✗ |
<Tip>
The organization owner always has access. In private mode, only whitelisted
users and roles can view, run, and access logs/metrics/settings.
</Tip>
<Frame>
<img src="/images/enterprise/visibility.png" alt="Automation Visibility settings in CrewAI AMP" />
</Frame>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with RBAC questions.
</Card>

262
docs/v1.11.0/en/enterprise/features/tools-and-integrations.mdx Normal file
View File

@@ -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.
<Frame>
![Tools & Integrations Overview](/images/enterprise/crew_connectors.png)
</Frame>
## Explore
<Tabs>
<Tab title="Integrations" icon="plug">
## Agent Apps (Integrations)
Connect enterprise‑grade applications (e.g., Gmail, Google Drive, HubSpot, Slack) via OAuth to enable agent actions.
{" "}
<Steps>
<Step title="Connect">
Click <b>Connect</b> on an app and complete OAuth.
</Step>
<Step title="Configure">
Optionally adjust scopes, triggers, and action availability.
</Step>
<Step title="Use in Agents">
Connected services become available as tools for your agents.
</Step>
</Steps>
{" "}
<Frame>![Integrations Grid](/images/enterprise/agent-apps.png)</Frame>
### Connect your Account
1. Go to <Link href="https://app.crewai.com/crewai_plus/connectors">Integrations</Link>
2. Click <b>Connect</b> on the desired service
3. Complete the OAuth flow and grant scopes
4. Copy your Enterprise Token from <Link href="https://app.crewai.com/crewai_plus/settings/integrations">Integration Settings</Link>
{" "}
<Frame>
![Enterprise Token](/images/enterprise/enterprise_action_auth_token.png)
</Frame>
### 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
{" "}
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
{" "}
<Tip>
Use the new streamlined approach to integrate enterprise apps. Simply specify
the app and its actions directly in the Agent configuration.
</Tip>
```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.
{" "}
<Frame>
![Filter Actions](/images/enterprise/filtering_enterprise_action_tools.png)
</Frame>
### 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.
{" "}
<Tip>Useful when different teams/users must keep data access separated.</Tip>
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.
{" "}
<Frame>![User Bearer Token](/images/enterprise/user_bearer_token.png)</Frame>
{" "}
<div id="catalog"></div>
### 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!
</Tab>
<Tab title="Internal Tools" icon="toolbox">
## Internal Tools
Create custom tools locally, publish them on CrewAI AMP Tool Repository and use them in your agents.
{" "}
<Tip>
Before running the commands below, make sure you log in to your CrewAI AMP
account by running this command: ```bash crewai login ```
</Tip>
{" "}
<Frame>
![Internal Tool Detail](/images/enterprise/tools-integrations-internal.png)
</Frame>
{" "}
<Steps>
<Step title="Create">
Create a new tool locally. ```bash crewai tool create your-tool ```
</Step>
<Step title="Publish">
Publish the tool to the CrewAI AMP Tool Repository. ```bash crewai tool
publish ```
</Step>
<Step title="Install">
Install the tool from the CrewAI AMP Tool Repository. ```bash crewai tool
install your-tool ```
</Step>
</Steps>
Manage:
- Name and description
- Visibility (Private / Public)
- Required environment variables
- Version history and downloads
- Team and role access
{" "}
<Frame>![Internal Tool Detail](/images/enterprise/tool-configs.png)</Frame>
</Tab>
</Tabs>
## Related
<CardGroup cols={2}>
<Card
title="Tool Repository"
href="/en/enterprise/guides/tool-repository#tool-repository"
icon="toolbox"
>
Create, publish, and version custom tools for your organization.
</Card>
<Card
title="Webhook Automation"
href="/en/enterprise/guides/webhook-automation"
icon="bolt"
>
Automate workflows and integrate with external platforms and services.
</Card>
</CardGroup>

148
docs/v1.11.0/en/enterprise/features/traces.mdx Normal file
View File

@@ -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
<Frame>![Traces Overview](/images/enterprise/traces-overview.png)</Frame>
## Accessing Traces
<Steps>
<Step title="Navigate to the Traces Tab">
Once in your CrewAI AMP dashboard, click on the **Traces** to view all execution records.
</Step>
<Step title="Select an Execution">
You'll see a list of all crew executions, sorted by date. Click on any execution to view its detailed trace.
</Step>
</Steps>
## 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
<Frame>![Execution Summary](/images/enterprise/trace-summary.png)</Frame>
### 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
<Frame>![Task List](/images/enterprise/trace-tasks.png)</Frame>
### 3. Final Output
Displays the final result produced by the crew after all tasks are completed.
<Frame>![Final Output](/images/enterprise/final-output.png)</Frame>
### 4. Execution Timeline
A visual representation of when each task started and ended, helping you identify bottlenecks or parallel execution patterns.
<Frame>![Execution Timeline](/images/enterprise/trace-timeline.png)</Frame>
### 5. Detailed Task View
When you click on a specific task in the timeline or task list, you'll see:
<Frame>![Detailed Task View](/images/enterprise/trace-detailed-task.png)</Frame>
- **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:
<Steps>
<Step title="Identify Failure Points">
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
<Frame>
![Failure Points](/images/enterprise/failure.png)
</Frame>
</Step>
<Step title="Optimize Performance">
Use execution metrics to identify performance bottlenecks:
- Tasks that took longer than expected
- Excessive token usage
- Redundant tool operations
- Unnecessary API calls
</Step>
<Step title="Improve Cost Efficiency">
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
</Step>
</Steps>
## 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.
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with trace analysis or any other
CrewAI AMP features.
</Card>

173
docs/v1.11.0/en/enterprise/features/webhook-streaming.mdx Normal file
View File

@@ -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.
<CardGroup>
<Card
title="GitHub"
icon="github"
href="https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events"
>
Full list of events
</Card>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with webhook integration or
troubleshooting.
</Card>
</CardGroup>

322
docs/v1.11.0/en/enterprise/guides/automation-triggers.mdx Normal file
View File

@@ -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.
<Frame>
![Automation Triggers Overview](/images/enterprise/crew_connectors.png)
</Frame>
### Integration Playbooks
Deep-dive guides walk through setup and sample workflows for each integration:
<CardGroup cols={2}>
<Card title="Gmail Trigger" icon="envelope">
<a href="/en/enterprise/guides/gmail-trigger">Enable crews when emails arrive or threads update.</a>
</Card>
{" "}
<Card title="Google Calendar Trigger" icon="calendar-days">
<a href="/en/enterprise/guides/google-calendar-trigger">
React to calendar events as they are created, updated, or cancelled.
</a>
</Card>
{" "}
<Card title="Google Drive Trigger" icon="folder-open">
<a href="/en/enterprise/guides/google-drive-trigger">
Handle Drive file uploads, edits, and deletions.
</a>
</Card>
{" "}
<Card title="Outlook Trigger" icon="envelope-open">
<a href="/en/enterprise/guides/outlook-trigger">
Automate responses to new Outlook messages and calendar updates.
</a>
</Card>
{" "}
<Card title="OneDrive Trigger" icon="cloud">
<a href="/en/enterprise/guides/onedrive-trigger">
Audit file activity and sharing changes in OneDrive.
</a>
</Card>
{" "}
<Card title="Microsoft Teams Trigger" icon="comments">
<a href="/en/enterprise/guides/microsoft-teams-trigger">
Kick off workflows when new Teams chats start.
</a>
</Card>
{" "}
<Card title="HubSpot Trigger" icon="hubspot">
<a href="/en/enterprise/guides/hubspot-trigger">
Launch automations from HubSpot workflows and lifecycle events.
</a>
</Card>
{" "}
<Card title="Salesforce Trigger" icon="salesforce">
<a href="/en/enterprise/guides/salesforce-trigger">
Connect Salesforce processes to CrewAI for CRM automation.
</a>
</Card>
{" "}
<Card title="Slack Trigger" icon="slack">
<a href="/en/enterprise/guides/slack-trigger">
Start crews directly from Slack slash commands.
</a>
</Card>
<Card title="Zapier Trigger" icon="bolt">
<a href="/en/enterprise/guides/zapier-trigger">Bridge CrewAI with thousands of Zapier-supported apps.</a>
</Card>
</CardGroup>
## 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
<Frame caption="Example of available automation triggers for a Gmail deployment">
<img
src="/images/enterprise/list-available-triggers.png"
alt="List of available automation triggers"
/>
</Frame>
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:
<Frame caption="Enable or disable triggers with toggle">
<img
src="/images/enterprise/trigger-selected.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
- **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:
<Frame caption="List of executions triggered by automation">
<img
src="/images/enterprise/list-executions.png"
alt="List of executions triggered by automation"
/>
</Frame>
## 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 <trigger_name>
```
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
<Warning>
**Important Development Notes:**
- Use `crewai triggers run <trigger>` 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
</Warning>
### 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.
<Note>
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
</Note>
### 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 <trigger_name>` 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 <trigger>` 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.

54
docs/v1.11.0/en/enterprise/guides/azure-openai-setup.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Access Azure AI Foundry">
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.
<Frame>
<img src="/images/enterprise/azure-openai-studio.png" alt="Azure AI Foundry" />
</Frame>
</Step>
<Step title="Configure CrewAI AMP Connection">
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.
</Step>
<Step title="Set Default Configuration">
7. In `CrewAI AMP > Settings > Defaults > Crew Studio LLM Settings`, set the new LLM Connection and model as defaults.
</Step>
<Step title="Configure Network Access">
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.
</Step>
</Steps>
## 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

48
docs/v1.11.0/en/enterprise/guides/build-crew.mdx Normal file
View File

@@ -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
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/-kSOTtYzgEw"
title="Building crews with the CrewAI CLI"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
### Installation and Setup
<Card
title="Follow Standard Installation"
icon="wrench"
href="/en/installation"
>
Follow our standard installation guide to set up CrewAI CLI and create your
first project.
</Card>
### Building Your Crew
<Card title="Quickstart Tutorial" icon="rocket" href="/en/quickstart">
Follow our quickstart guide to create your first agent crew using YAML
configuration.
</Card>
## Support and Resources
For Enterprise-specific support or questions, contact our dedicated support team at [support@crewai.com](mailto:support@crewai.com).
<Card title="Schedule a Demo" icon="calendar" href="mailto:support@crewai.com">
Book time with our team to learn more about Enterprise features and how they
can benefit your organization.
</Card>

39
docs/v1.11.0/en/enterprise/guides/capture_telemetry_logs.mdx Normal file
View File

@@ -0,0 +1,39 @@
---
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.
## Prerequisites
<CardGroup cols={2}>
<Card title="CrewAI AMP account" icon="users">
Your organization must have an active CrewAI AMP account.
</Card>
<Card title="OpenTelemetry collector" icon="server">
You need an OpenTelemetry-compatible collector endpoint (e.g., your own OTel Collector, Datadog, Grafana, or any OTLP-compatible backend).
</Card>
</CardGroup>
## Setting up a collector
1. In CrewAI AMP, go to **Settings** > **OpenTelemetry Collectors**.
2. Click **Add Collector**.
3. Select an integration type — **OpenTelemetry Traces** or **OpenTelemetry Logs**.
4. Configure the connection:
- **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.
5. Click **Save**.
<Frame>![OpenTelemetry Collector Configuration](/images/crewai-otel-collector-config.png)</Frame>
<Tip>
You can add multiple collectors — for example, one for traces and another for logs, or send to different backends for different purposes.
</Tip>

136
docs/v1.11.0/en/enterprise/guides/custom-mcp-server.mdx Normal file
View File

@@ -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
<CardGroup cols={2}>
<Card title="CrewAI AMP Account" icon="user">
You need an active [CrewAI AMP](https://app.crewai.com) account.
</Card>
<Card title="MCP Server URL" icon="link">
The URL of the MCP server you want to connect. The server must be accessible from the internet and support Streamable HTTP transport.
</Card>
</CardGroup>
## Adding a Custom MCP Server
<Steps>
<Step title="Open Tools & Integrations">
Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP, then select the **Connections** tab.
</Step>
<Step title="Start adding a Custom MCP Server">
Click the **Add Custom MCP Server** button. A dialog will appear with the configuration form.
</Step>
<Step title="Fill in the basic information">
- **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`).
</Step>
<Step title="Choose an authentication method">
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.
</Step>
<Step title="Add custom headers (optional)">
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.
</Step>
<Step title="Create the connection">
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.
</Step>
</Steps>
## 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.
<Frame>
<img src="/images/enterprise/custom-mcp-auth-token.png" alt="Custom MCP Server with Authentication Token" />
</Frame>
| 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**. |
<Tip>
If your server expects a `Bearer` token in the `Authorization` header, set the Header Name to `Authorization` and the Value to `Bearer <your-token>`.
</Tip>
### 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.
<Frame>
<img src="/images/enterprise/custom-mcp-oauth.png" alt="Custom MCP Server with OAuth 2.0" />
</Frame>
| 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. |
<Info>
**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.
</Info>
#### Setting Up OAuth 2.0 Step by Step
<Steps>
<Step title="Register the redirect URI">
Copy the **Redirect URI** shown in the form and add it as an authorized redirect URI in your OAuth provider's application settings.
</Step>
<Step title="Enter endpoints and credentials">
Fill in the **Authorization Endpoint**, **Token Endpoint**, **Client ID**, and optionally the **Client Secret** and **Scopes**.
</Step>
<Step title="Configure token exchange method">
Select the appropriate **Token Auth Method**. Most providers use the default **Standard (POST body)**. Some older providers require **Basic Auth (header)**.
</Step>
<Step title="Enable PKCE (recommended)">
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.
</Step>
<Step title="Create and authorize">
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.
</Step>
</Steps>
## 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.
<Warning>
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.
</Warning>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with custom MCP server configuration or troubleshooting.
</Card>

445
docs/v1.11.0/en/enterprise/guides/deploy-to-amp.mdx Normal file
View File

@@ -0,0 +1,445 @@
---
title: "Deploy to AMP"
description: "Deploy your Crew or Flow to CrewAI AMP"
icon: "rocket"
mode: "wide"
---
<Note>
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.
</Note>
## Prerequisites
<CardGroup cols={2}>
<Card title="Project Ready for Deployment" icon="check-circle">
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.
</Card>
<Card title="GitHub Repository" icon="github">
Your code should be in a GitHub repository (for GitHub integration
method)
</Card>
</CardGroup>
<Info>
**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.
</Info>
## 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.
<Steps>
<Step title="Install CrewAI CLI">
If you haven't already, install the CrewAI CLI:
```bash
pip install crewai[tools]
```
<Tip>
The CLI comes with the main CrewAI package, but the `[tools]` extra ensures you have all deployment dependencies.
</Tip>
</Step>
<Step title="Authenticate with the Enterprise Platform">
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!
</Step>
<Step title="Create a Deployment">
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
```
</Step>
<Step title="Monitor Deployment Progress">
Track the deployment status with:
```bash
crewai deploy status
```
For detailed logs of the build process:
```bash
crewai deploy logs
```
<Tip>
The first deployment typically takes 10-15 minutes as it builds the container images. Subsequent deployments are much faster.
</Tip>
</Step>
</Steps>
## 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 <deployment_id>
```
## 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.
<Steps>
<Step title="Pushing to GitHub">
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).
</Step>
<Step title="Connecting GitHub to CrewAI AMP">
1. Log in to [CrewAI AMP](https://app.crewai.com)
2. Click on the button "Connect GitHub"
<Frame>
![Connect GitHub Button](/images/enterprise/connect-github.png)
</Frame>
</Step>
<Step title="Select the Repository">
After connecting your GitHub account, you'll be able to select which repository to deploy:
<Frame>
![Select Repository](/images/enterprise/select-repo.png)
</Frame>
</Step>
<Step title="Set Environment Variables">
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)
<Frame>
![Set Environment Variables](/images/enterprise/set-env-variables.png)
</Frame>
<Info>
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.
</Info>
</Step>
<Step title="Deploy Your Crew">
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 10-15 minutes; subsequent deployments will be faster
<Frame>
![Deploy Progress](/images/enterprise/deploy-progress.png)
</Frame>
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
</Step>
</Steps>
## 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.
<Steps>
<Step title="Get Your Personal Access Token">
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
</Step>
<Step title="Find Your Automation UUID">
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
</Step>
<Step title="Trigger Redeployment via API">
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"
# }
```
<Info>
If your automation was first created connected to Git, the API will automatically pull the latest changes from your repository before redeploying.
</Info>
</Step>
<Step title="GitHub Actions Integration Example">
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
```
<Tip>
Add `CREWAI_PAT` and `CREWAI_AUTOMATION_UUID` as repository secrets. For PR deployments, add a "deploy" label to trigger the workflow.
</Tip>
</Step>
</Steps>
## 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
```
<Warning>
The `uv.lock` file is required for all deployments. Without it, the platform
cannot reliably install your dependencies.
</Warning>
#### Wrong Project Structure
**Symptom**: "Could not find entry point" or "Module not found" errors
**Solution**: Verify your project matches the expected structure:
- **Both Crews and Flows**: Must have entry point at `src/project_name/main.py`
- **Crews**: Use a `run()` function as entry point
- **Flows**: Use a `kickoff()` function as entry point
See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for detailed structure diagrams.
#### Missing CrewBase Decorator
**Symptom**: "Crew not found", "Config not found", or agent/task configuration errors
**Solution**: Ensure **all** crew classes use the `@CrewBase` 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
```
<Info>
This applies to standalone Crews AND crews embedded inside Flow projects.
Every crew class needs the decorator.
</Info>
#### 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. Ensure agent configurations in `agents.yaml` are valid
4. Check task configurations in `tasks.yaml` for syntax errors
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with deployment issues or questions
about the AMP platform.
</Card>

182
docs/v1.11.0/en/enterprise/guides/enable-crew-studio.mdx Normal file
View File

@@ -0,0 +1,182 @@
---
title: "Enable Crew Studio"
description: "Enabling Crew Studio on CrewAI AMP"
icon: "comments"
mode: "wide"
---
<Tip>
Crew Studio is a powerful **no-code/low-code** tool that allows you to quickly
scaffold or build Crews through a conversational interface.
</Tip>
## What is Crew Studio?
Crew Studio is an innovative way to create AI agent crews without writing code.
<Frame>
![Crew Studio Interface](/images/enterprise/crew-studio-interface.png)
</Frame>
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:
<Steps>
<Step title="Set Up LLM Connection">
Go to the **LLM Connections** tab in your CrewAI AMP dashboard and create a new LLM connection.
<Note>
Feel free to use any LLM provider you want that is supported by CrewAI.
</Note>
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
<Frame>
![LLM Connection Configuration](/images/enterprise/llm-connection-config.png)
</Frame>
</Step>
<Step title="Verify Connection Added">
Once you complete the setup, you'll see your new connection added to the list of available connections.
<Frame>
![Connection Added](/images/enterprise/connection-added.png)
</Frame>
</Step>
<Step title="Configure LLM Defaults">
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.
<Frame>
![LLM Defaults Configuration](/images/enterprise/llm-defaults.png)
</Frame>
</Step>
</Steps>
## Using Crew Studio
Now that you've configured your LLM connection and default settings, you're ready to start using Crew Studio!
<Steps>
<Step title="Access Studio">
Navigate to the **Studio** section in your CrewAI AMP dashboard.
</Step>
<Step title="Start a Conversation">
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.
</Step>
<Step title="Review Generated Crew">
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.
</Step>
<Step title="Deploy or Download">
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
</Step>
<Step title="Test Your Crew">
After deployment, test your crew with sample inputs to ensure it performs as expected.
</Step>
</Steps>
<Tip>
For best results, provide clear, detailed descriptions of what you want your
crew to accomplish. Include specific inputs and expected outputs in your
description.
</Tip>
## Example Workflow
Here's a typical workflow for creating a crew with Crew Studio:
<Steps>
<Step title="Describe Your Problem">
Start by describing your problem:
```md
I need a crew that can analyze financial news and provide investment recommendations
```
</Step>
{" "}
<Step title="Answer Questions">
Respond to clarifying questions from the Crew Assistant to refine your
requirements.
</Step>
<Step title="Review the Plan">
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
</Step>
{" "}
<Step title="Approve or Modify">
Approve the plan or request changes if necessary.
</Step>
{" "}
<Step title="Download or Deploy">
Download the code for customization or deploy directly to the platform.
</Step>
<Step title="Test and Refine">
Test your crew with sample inputs and refine as needed.
</Step>
</Steps>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Crew Studio or any other CrewAI
AMP features.
</Card>

97
docs/v1.11.0/en/enterprise/guides/gmail-trigger.mdx Normal file
View File

@@ -0,0 +1,97 @@
---
title: "Gmail Trigger"
description: "Trigger automations when Gmail events occur (e.g., new emails, labels)."
icon: "envelope"
mode: "wide"
---
## Overview
Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter.
<Tip>
Make sure Gmail is connected in Tools & Integrations and the trigger is
enabled for your deployment.
</Tip>
## Enabling the Gmail Trigger
1. Open your deployment in CrewAI AMP
2. Go to the **Triggers** tab
3. Locate **Gmail** and switch the toggle to enable
<Frame>
<img
src="/images/enterprise/trigger-selected.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
## Example: Process new emails
When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload.
```python
@CrewBase
class GmailProcessingCrew:
@agent
def parser(self) -> Agent:
return Agent(
config=self.agents_config['parser'],
)
@task
def parse_gmail_payload(self) -> Task:
return Task(
config=self.tasks_config['parse_gmail_payload'],
agent=self.parser(),
)
@task
def act_on_email(self) -> Task:
return Task(
config=self.tasks_config['act_on_email'],
agent=self.parser(),
)
```
The Gmail payload will be available via the standard context mechanisms.
### 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.
<Warning>
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.
</Warning>
## Monitoring Executions
Track history and performance of triggered runs:
<Frame>
<img
src="/images/enterprise/list-executions.png"
alt="List of executions triggered by automation"
/>
</Frame>
## Troubleshooting
- Ensure Gmail is connected in Tools & Integrations
- Verify the Gmail Trigger is enabled on the Triggers tab
- 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

83
docs/v1.11.0/en/enterprise/guides/google-calendar-trigger.mdx Normal file
View File

@@ -0,0 +1,83 @@
---
title: "Google Calendar Trigger"
description: "Kick off crews when Google Calendar events are created, updated, or cancelled"
icon: "calendar"
mode: "wide"
---
## Overview
Use the Google Calendar trigger to launch automations whenever calendar events change. Common use cases include briefing a team before a meeting, notifying stakeholders when a critical event is cancelled, or summarizing daily schedules.
<Tip>
Make sure Google Calendar is connected in **Tools & Integrations** and enabled
for the deployment you want to automate.
</Tip>
## Enabling the Google Calendar Trigger
1. Open your deployment in CrewAI AMP
2. Go to the **Triggers** tab
3. Locate **Google Calendar** and switch the toggle to enable
<Frame>
<img
src="/images/enterprise/calendar-trigger.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
## Example: Summarize meeting details
The snippet below mirrors the `calendar-event-crew.py` example in the trigger repository. It parses the payload, analyses the attendees and timing, and produces a meeting brief for downstream tools.
```python
from calendar_event_crew import GoogleCalendarEventTrigger
crew = GoogleCalendarEventTrigger().crew()
result = crew.kickoff({
"crewai_trigger_payload": calendar_payload,
})
print(result.raw)
```
Use `crewai_trigger_payload` exactly as it is delivered by the trigger so the crew can extract the proper fields.
## 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.
<Warning>
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.
</Warning>
## Monitoring Executions
The **Executions** list in the deployment dashboard tracks every triggered run and surfaces payload metadata, output summaries, and errors.
<Frame>
<img
src="/images/enterprise/list-executions.png"
alt="List of executions triggered by automation"
/>
</Frame>
## Troubleshooting
- Ensure the correct Google account is connected and the trigger is enabled
- 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

80
docs/v1.11.0/en/enterprise/guides/google-drive-trigger.mdx Normal file
View File

@@ -0,0 +1,80 @@
---
title: "Google Drive Trigger"
description: "Respond to Google Drive file events with automated crews"
icon: "folder"
mode: "wide"
---
## Overview
Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change.
<Tip>
Connect Google Drive in **Tools & Integrations** and confirm the trigger is
enabled for the automation you want to monitor.
</Tip>
## Enabling the Google Drive Trigger
1. Open your deployment in CrewAI AMP
2. Go to the **Triggers** tab
3. Locate **Google Drive** and switch the toggle to enable
<Frame>
<img
src="/images/enterprise/gdrive-trigger.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
## Example: Summarize file activity
The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary.
```python
from drive_file_crew import GoogleDriveFileTrigger
crew = GoogleDriveFileTrigger().crew()
crew.kickoff({
"crewai_trigger_payload": drive_payload,
})
```
## 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.
<Warning>
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.
</Warning>
## Monitoring Executions
Track history and performance of triggered runs with the **Executions** list in the deployment dashboard.
<Frame>
<img
src="/images/enterprise/list-executions.png"
alt="List of executions triggered by automation"
/>
</Frame>
## Troubleshooting
- Verify Google Drive is connected and the trigger toggle is enabled
- 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

61
docs/v1.11.0/en/enterprise/guides/hubspot-trigger.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Connect your HubSpot account with CrewAI AMP">
- 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
</Step>
<Step title="Create a HubSpot Workflow">
- 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
<Frame>
<img
src="/images/enterprise/hubspot-workflow-1.png"
alt="HubSpot Workflow 1"
/>
</Frame>
</Step>
<Step title="Use Crew results with other actions">
- 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
<Frame>
<img
src="/images/enterprise/hubspot-workflow-2.png"
alt="HubSpot Workflow 2"
/>
</Frame>
- Configure any additional actions as needed - Review your workflow
steps to ensure everything is set up correctly - Activate the workflow
<Frame>
<img
src="/images/enterprise/hubspot-workflow-3.png"
alt="HubSpot Workflow 3"
/>
</Frame>
</Step>
</Steps>
For more detailed information on available actions and customization options, refer to the [HubSpot Workflows Documentation](https://knowledge.hubspot.com/workflows/create-workflows).

157
docs/v1.11.0/en/enterprise/guides/human-in-the-loop.mdx Normal file
View File

@@ -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
<Note>
The `@human_feedback` decorator requires **CrewAI version 1.8.0 or higher**.
</Note>
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:
<CardGroup cols={2}>
<Card title="Email-First Design" icon="envelope">
Responders receive email notifications and can reply directly—no login required.
</Card>
<Card title="Dashboard Review" icon="desktop">
Review and respond to HITL requests in the Enterprise dashboard when preferred.
</Card>
<Card title="Flexible Routing" icon="route">
Route requests to specific emails based on method patterns or pull from flow state.
</Card>
<Card title="Auto-Response" icon="clock">
Configure automatic fallback responses when no human replies within the timeout.
</Card>
</CardGroup>
### 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
<Tip>
For implementation details on the `@human_feedback` decorator, see the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide.
</Tip>
## 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:
<Steps>
<Step title="Configure Your Task">
Set up your task with human input enabled:
<Frame>
<img src="/images/enterprise/crew-human-input.png" alt="Crew Human Input" />
</Frame>
</Step>
<Step title="Provide Webhook URL">
When kicking off your crew, include a webhook URL for human input:
<Frame>
<img src="/images/enterprise/crew-webhook-url.png" alt="Crew Webhook URL" />
</Frame>
</Step>
<Step title="Receive Webhook Notification">
Once the crew completes the task requiring human input, you'll receive a webhook notification containing:
- **Execution ID**
- **Task ID**
- **Task output**
</Step>
<Step title="Review Task Output">
The system will pause in the `Pending Human Input` state. Review the task output carefully.
</Step>
<Step title="Submit Human Feedback">
Call the resume endpoint of your crew with the following information:
<Frame>
<img src="/images/enterprise/crew-resume-endpoint.png" alt="Crew Resume Endpoint" />
</Frame>
<Warning>
**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.
</Warning>
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"
}'
```
<Warning>
**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.
</Warning>
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.
</Step>
<Step title="Handle Negative Feedback">
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.
</Step>
<Step title="Execution Continuation">
When you submit positive feedback, the execution will proceed to the next steps.
</Step>
</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
<CardGroup cols={2}>
<Card title="Flow HITL Management" icon="users-gear" href="/en/enterprise/features/flow-hitl-management">
Explore the full Enterprise Flow HITL platform capabilities including email notifications, routing rules, auto-response, and analytics.
</Card>
<Card title="Human Feedback in Flows" icon="code" href="/en/learn/human-feedback-in-flows">
Implementation guide for the `@human_feedback` decorator in your Flows.
</Card>
</CardGroup>

178
docs/v1.11.0/en/enterprise/guides/kickoff-crew.mdx Normal file
View File

@@ -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
<Frame>![Crew Dashboard](/images/enterprise/crew-dashboard.png)</Frame>
### 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
<Frame>![Kickoff Endpoint](/images/enterprise/kickoff-endpoint.png)</Frame>
#### 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
<Frame>![Run Crew](/images/enterprise/run-crew.png)</Frame>
### 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
<Frame>![Copy Task ID](/images/enterprise/copy-task-id.png)</Frame>
### 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
<Frame>![Get Status](/images/enterprise/get-status.png)</Frame>
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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with execution issues or questions
about the Enterprise platform.
</Card>

70
docs/v1.11.0/en/enterprise/guides/microsoft-teams-trigger.mdx Normal file
View File

@@ -0,0 +1,70 @@
---
title: "Microsoft Teams Trigger"
description: "Kick off crews from Microsoft Teams chat activity"
icon: "microsoft"
mode: "wide"
---
## Overview
Use the Microsoft Teams trigger to start automations whenever a new chat is created. Common patterns include summarizing inbound requests, routing urgent messages to support teams, or creating follow-up tasks in other systems.
<Tip>
Confirm Microsoft Teams is connected under **Tools & Integrations** and
enabled in the **Triggers** tab for your deployment.
</Tip>
## Enabling the Microsoft Teams Trigger
1. Open your deployment in CrewAI AMP
2. Go to the **Triggers** tab
3. Locate **Microsoft Teams** and switch the toggle to enable
<Frame caption="Microsoft Teams trigger connection">
<img
src="/images/enterprise/msteams-trigger.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
## Example: Summarize a new chat thread
```python
from teams_chat_created_crew import MicrosoftTeamsChatTrigger
crew = MicrosoftTeamsChatTrigger().crew()
result = crew.kickoff({
"crewai_trigger_payload": teams_payload,
})
print(result.raw)
```
The crew parses thread metadata (subject, created time, roster) and generates an action plan for the receiving team.
## 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.
<Warning>
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.
</Warning>
## 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

69
docs/v1.11.0/en/enterprise/guides/onedrive-trigger.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: "OneDrive Trigger"
description: "Automate responses to OneDrive file activity"
icon: "cloud"
mode: "wide"
---
## Overview
Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata.
<Tip>
Connect OneDrive in **Tools & Integrations** and toggle the trigger on for
your deployment.
</Tip>
## Enabling the OneDrive Trigger
1. Open your deployment in CrewAI AMP
2. Go to the **Triggers** tab
3. Locate **OneDrive** and switch the toggle to enable
<Frame caption="Microsoft OneDrive trigger connection">
<img
src="/images/enterprise/onedrive-trigger.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
## Example: Audit file permissions
```python
from onedrive_file_crew import OneDriveFileTrigger
crew = OneDriveFileTrigger().crew()
crew.kickoff({
"crewai_trigger_payload": onedrive_payload,
})
```
The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary.
## 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.
<Warning>
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.
</Warning>
## 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

69
docs/v1.11.0/en/enterprise/guides/outlook-trigger.mdx Normal file
View File

@@ -0,0 +1,69 @@
---
title: "Outlook Trigger"
description: "Launch automations from Outlook emails and calendar updates"
icon: "microsoft"
mode: "wide"
---
## Overview
Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations.
<Tip>
Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled
for your deployment.
</Tip>
## Enabling the Outlook Trigger
1. Open your deployment in CrewAI AMP
2. Go to the **Triggers** tab
3. Locate **Outlook** and switch the toggle to enable
<Frame caption="Microsoft Outlook trigger connection">
<img
src="/images/enterprise/outlook-trigger.png"
alt="Enable or disable triggers with toggle"
/>
</Frame>
## Example: Summarize a new email
```python
from outlook_message_crew import OutlookMessageTrigger
crew = OutlookMessageTrigger().crew()
crew.kickoff({
"crewai_trigger_payload": outlook_payload,
})
```
The crew extracts sender details, subject, body preview, and attachments before generating a structured response.
## 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.
<Warning>
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.
</Warning>
## 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

311
docs/v1.11.0/en/enterprise/guides/prepare-for-deployment.mdx Normal file
View File

@@ -0,0 +1,311 @@
---
title: "Prepare for Deployment"
description: "Ensure your Crew or Flow is ready for deployment to CrewAI AMP"
icon: "clipboard-check"
mode: "wide"
---
<Note>
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.
</Note>
## 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
<CardGroup cols={2}>
<Card title="Crew Projects" icon="users">
Standalone AI agent teams with `crew.py` defining agents and tasks. Best for focused, collaborative tasks.
</Card>
<Card title="Flow Projects" icon="diagram-project">
Orchestrated workflows with embedded crews in a `crews/` folder. Best for complex, multi-stage processes.
</Card>
</CardGroup>
| Aspect | Crew | Flow |
|--------|------|------|
| **Project structure** | `src/project_name/` with `crew.py` | `src/project_name/` with `crews/` folder |
| **Main logic location** | `src/project_name/crew.py` | `src/project_name/main.py` (Flow class) |
| **Entry point function** | `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** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` |
| **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 this structure:
```
my_crew/
├── .gitignore
├── pyproject.toml # Must have type = "crew"
├── README.md
├── .env
├── uv.lock # REQUIRED for deployment
└── src/
└── my_crew/
├── __init__.py
├── main.py # Entry point with run() function
├── crew.py # Crew class with @CrewBase decorator
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml # Agent definitions
└── tasks.yaml # Task definitions
```
<Warning>
The nested `src/project_name/` structure is critical for Crews.
Placing files at the wrong level will cause deployment failures.
</Warning>
### 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
```
<Info>
Both Crews and Flows use the `src/project_name/` structure.
The key difference is that Flows have a `crews/` folder for embedded crews,
while Crews have `crew.py` directly in the project folder.
</Info>
## 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:
<Tabs>
<Tab title="For Crews">
```toml
[tool.crewai]
type = "crew"
```
</Tab>
<Tab title="For Flows">
```toml
[tool.crewai]
type = "flow"
```
</Tab>
</Tabs>
<Warning>
If the `type` doesn't match your project structure, the build will fail or
the automation won't run correctly.
</Warning>
### 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 CrewBase Decorator Usage
**Every crew class must use the `@CrewBase` decorator.** This applies to:
- Standalone crew projects
- Crews embedded inside Flow projects
```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 # This decorator is REQUIRED
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,
)
```
<Warning>
If you forget the `@CrewBase` decorator, your deployment will fail with
errors about missing agents or tasks configurations.
</Warning>
### 4. Check Project Entry Points
Both Crews and Flows have their entry point in `src/project_name/main.py`:
<Tabs>
<Tab title="For Crews">
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()
```
</Tab>
<Tab title="For Flows">
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()
```
</Tab>
</Tabs>
### 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.)
<Info>
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.
</Info>
<Tip>
Test your project locally with the same environment variables before deploying
to catch configuration issues early.
</Tip>
## 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. Verify src/ structure exists
ls -la src/*/main.py 2>/dev/null || echo "No main.py found in src/"
# 4. For 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. 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 `@CrewBase` decorator | "Config not found" errors | Add decorator to all crew classes |
| Files at root instead of `src/` | Entry point not found | Move 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:
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
Follow the deployment guide to deploy your Crew or Flow to CrewAI AMP using
the CLI, web interface, or CI/CD integration.
</Card>

263
docs/v1.11.0/en/enterprise/guides/private-package-registry.mdx Normal file
View File

@@ -0,0 +1,263 @@
---
title: "Private Package Registries"
description: "Install private Python packages from authenticated PyPI registries in CrewAI AMP"
icon: "lock"
mode: "wide"
---
<Note>
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.
</Note>
## 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
```
<Info>
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.
</Info>
### 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
```
<Warning>
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).
</Warning>
## 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 |
<Warning>
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.
</Warning>
## 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 |
<Tip>
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.
</Tip>
## Setting Environment Variables in AMP
Private registry credentials must be configured as environment variables in CrewAI AMP.
You have two options:
<Tabs>
<Tab title="Web Interface">
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.
</Tab>
<Tab title="CLI Deployment">
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
```
</Tab>
</Tabs>
<Warning>
**Never** commit credentials to your repository. Use AMP environment variables for all secrets.
The `.env` file should be listed in `.gitignore`.
</Warning>
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:
<Steps>
<Step title="Build starts">
AMP pulls your repository and reads `pyproject.toml` and `uv.lock`.
</Step>
<Step title="UV resolves dependencies">
UV reads `[tool.uv.sources]` to determine which index each package should come from.
</Step>
<Step title="UV authenticates">
For each private index, UV looks up `UV_INDEX_{NAME}_USERNAME` and `UV_INDEX_{NAME}_PASSWORD`
from the environment variables you configured in AMP.
</Step>
<Step title="Packages install">
UV downloads and installs all packages — both public (from PyPI) and private (from your registry).
</Step>
<Step title="Automation runs">
Your crew or flow starts with all dependencies available.
</Step>
</Steps>
## 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
<CardGroup cols={3}>
<Card title="Prepare for Deployment" icon="clipboard-check" href="/en/enterprise/guides/prepare-for-deployment">
Verify project structure and dependencies before deploying.
</Card>
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
Deploy your crew or flow and configure environment variables.
</Card>
<Card title="Update Your Crew" icon="arrows-rotate" href="/en/enterprise/guides/update-crew">
Update environment variables and push changes to a running deployment.
</Card>
</CardGroup>

112
docs/v1.11.0/en/enterprise/guides/react-component-export.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Export the 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.
<Frame>
<img src="/images/enterprise/export-react-component.png" alt="Export React Component" />
</Frame>
</Step>
</Steps>
## 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.
<Steps>
<Step title="Install Node.js">
- Download and install Node.js from the official website: https://nodejs.org/
- Choose the LTS (Long Term Support) version for stability.
</Step>
<Step title="Create a new React project">
- 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
```
</Step>
<Step title="Install necessary dependencies">
```bash
npm install react-dom
```
</Step>
<Step title="Create the CrewLead component">
- Move the downloaded file `CrewLead.jsx` into the `src` folder of your project,
</Step>
<Step title="Modify your App.js to use the CrewLead component">
- Open `src/App.js`
- Replace its contents with something like this:
```jsx
import React from 'react';
import CrewLead from './CrewLead';
function App() {
return (
<div className="App">
<CrewLead baseUrl="YOUR_API_BASE_URL" bearerToken="YOUR_BEARER_TOKEN" />
</div>
);
}
export default App;
```
- Replace `YOUR_API_BASE_URL` and `YOUR_BEARER_TOKEN` with the actual values for your API.
</Step>
<Step title="Start the development server">
- 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.
</Step>
</Steps>
## Customization
You can then customise the `CrewLead.jsx` to add color, title etc
<Frame>
<img
src="/images/enterprise/customise-react-component.png"
alt="Customise React Component"
/>
</Frame>
<Frame>
<img
src="/images/enterprise/customise-react-component-2.png"
alt="Customise React Component"
/>
</Frame>
## 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

50
docs/v1.11.0/en/enterprise/guides/salesforce-trigger.mdx Normal file
View File

@@ -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
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/oJunVqjjfu4"
title="CrewAI + Salesforce trigger demo"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
## 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.

62
docs/v1.11.0/en/enterprise/guides/slack-trigger.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Ensure the CrewAI Slack trigger is set up">
In the CrewAI dashboard, navigate to the **Triggers** section.
<Frame>
<img src="/images/enterprise/slack-integration.png" alt="CrewAI Slack Integration" />
</Frame>
Verify that Slack is listed and is connected.
</Step>
<Step title="Open your Slack channel">
- 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:
<Frame>
<img src="/images/enterprise/kickoff-slack-crew.png" alt="Kickoff crew" />
</Frame>
- Press Enter or select the "**Kickoff crew**" option. A dialog box titled "**Kickoff an AI Crew**" will appear.
</Step>
<Step title="Select the crew you want to start">
- 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:
<Frame>
<img src="/images/enterprise/kickoff-slack-crew-dropdown.png" alt="Kickoff crew dropdown" />
</Frame>
- If your crew requires any inputs, click the "**Add Inputs**" button to provide them.
<Note>
The "**Add Inputs**" button is shown in the example above but is not yet clicked.
</Note>
</Step>
<Step title="Click Kickoff and wait for the crew to complete">
- Once you've selected the crew and added any necessary inputs, click "**Kickoff**" to start the crew.
<Frame>
<img src="/images/enterprise/kickoff-slack-crew-kickoff.png" alt="Kickoff crew" />
</Frame>
- The crew will start executing and you will see the results in the Slack channel.
<Frame>
<img src="/images/enterprise/kickoff-slack-crew-results.png" alt="Kickoff crew results" />
</Frame>
</Step>
</Steps>
## 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.

91
docs/v1.11.0/en/enterprise/guides/team-management.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Access the Settings Page">
- 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:
<Frame caption="Settings page">
<img src="/images/enterprise/settings-page.png" alt="Settings Page" />
</Frame>
</Step>
<Step title="Navigate to the Members Section">
- On the Settings page, you'll see a `Members` tab - Click on the `Members`
tab to access the **Members** page:
<Frame caption="Members tab">
<img src="/images/enterprise/members-tab.png" alt="Members Tab" />
</Frame>
</Step>
<Step title="Invite New Members">
- 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
</Step>
<Step title="Repeat as Needed">
- You can repeat this process to invite multiple team members - Each invited
member will receive an email invitation to join your organization
</Step>
</Steps>
## Adding Roles
You can add roles to your team members to control their access to different parts of the platform.
<Steps>
<Step title="Access the Settings Page">
- 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:
<Frame>
<img src="/images/enterprise/settings-page.png" alt="Settings Page" />
</Frame>
</Step>
<Step title="Navigate to the Members Section">
- On the Settings page, you'll see a `Roles` tab - Click on the `Roles` tab
to access the **Roles** page.
<Frame>
<img src="/images/enterprise/roles-tab.png" alt="Roles Tab" />
</Frame>
- 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.
<Frame>
<img src="/images/enterprise/add-role-modal.png" alt="Add Role Modal" />
</Frame>
</Step>
<Step title="Add Roles to Members">
- In the Members section, you'll see a list of current members (including
yourself)
<Frame>
<img
src="/images/enterprise/member-accepted-invitation.png"
alt="Member Accepted Invitation"
/>
</Frame>
- 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
<Frame>
<img src="/images/enterprise/assign-role.png" alt="Add Role to Member" />
</Frame>
</Step>
</Steps>
## 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.

154
docs/v1.11.0/en/enterprise/guides/tool-repository.mdx Normal file
View File

@@ -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 <tool-name>
```
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 <tool-name>
```
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**
<Warning>
Deletion is permanent. Deleted tools cannot be restored or re-installed.
</Warning>
## 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`
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with API integration or
troubleshooting.
</Card>

91
docs/v1.11.0/en/enterprise/guides/update-crew.mdx Normal file
View File

@@ -0,0 +1,91 @@
---
title: "Update Crew"
description: "Updating a Crew on CrewAI AMP"
icon: "pencil"
mode: "wide"
---
<Note>
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.
</Note>
## 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
<Frame>![Re-deploy Button](/images/enterprise/redeploy-button.png)</Frame>
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
<Frame>![Reset Token](/images/enterprise/reset-token.png)</Frame>
<Warning>
Resetting your bearer token will invalidate the previous token immediately.
Make sure to update any applications or scripts that are using the old token.
</Warning>
## 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
<Frame>
![Environment Variables Button](/images/enterprise/env-vars-button.png)
</Frame>
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
<Frame>
![Update Environment Variables](/images/enterprise/update-env-vars.png)
</Frame>
5. Finally, click the `Update Deployment` button at the bottom of the page to apply the changes
<Note>
Updating environment variables will trigger a new deployment, but this will
only update the environment configuration and not the code itself.
</Note>
## 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
<Tip>
If you encounter any issues after updating, you can view deployment logs in
the platform or contact support for assistance.
</Tip>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with updating your crew or
troubleshooting deployment issues.
</Card>

157
docs/v1.11.0/en/enterprise/guides/webhook-automation.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Accessing the Kickoff Interface">
- Navigate to the CrewAI AMP dashboard
- Look for the `/kickoff` section, which is used to start the crew execution
<Frame>
<img src="/images/enterprise/kickoff-interface.png" alt="Kickoff Interface" />
</Frame>
</Step>
<Step title="Configuring the JSON Content">
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)
</Step>
<Step title="Integrating with ActivePieces">
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)
<Frame>
<img src="/images/enterprise/activepieces-trigger.png" alt="ActivePieces Trigger" />
</Frame>
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`)
<Frame>
<img src="/images/enterprise/activepieces-headers.png" alt="ActivePieces Headers" />
</Frame>
- In the body, include the JSON content as configured in step 2
<Frame>
<img src="/images/enterprise/activepieces-body.png" alt="ActivePieces Body" />
</Frame>
- The crew will then kickoff at the pre-defined time.
</Step>
<Step title="Setting Up the Webhook">
1. Create a new flow in ActivePieces and name it
<Frame>
<img src="/images/enterprise/activepieces-flow.png" alt="ActivePieces Flow" />
</Frame>
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
<Frame>
<img src="/images/enterprise/activepieces-webhook.png" alt="ActivePieces Webhook" />
</Frame>
- Configure the email to use crew webhook body text
<Frame>
<img src="/images/enterprise/activepieces-email.png" alt="ActivePieces Email" />
</Frame>
</Step>
</Steps>
## 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.
<Tabs>
<Tab title="Step Webhook">
`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"
}
}
```
</Tab>
<Tab title="Task Webhook">
`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"
}
}
```
</Tab>
<Tab title="Crew Webhook">
`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"
}
}
```
</Tab>
</Tabs>

105
docs/v1.11.0/en/enterprise/guides/zapier-trigger.mdx Normal file
View File

@@ -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
<Steps>
<Step title="Set Up the Slack Trigger">
- In Zapier, create a new Zap.
<Frame>
<img src="/images/enterprise/zapier-1.png" alt="Zapier 1" />
</Frame>
</Step>
<Step title="Choose Slack as your trigger app">
<Frame>
<img src="/images/enterprise/zapier-2.png" alt="Zapier 2" />
</Frame>
- Select `New Pushed Message` as the Trigger Event.
- Connect your Slack account if you haven't already.
</Step>
<Step title="Configure the CrewAI AMP Action">
- Add a new action step to your Zap.
- Choose CrewAI+ as your action app and Kickoff as the Action Event
<Frame>
<img src="/images/enterprise/zapier-3.png" alt="Zapier 5" />
</Frame>
</Step>
<Step title="Connect your CrewAI AMP account">
- Connect your CrewAI AMP account.
- Select the appropriate Crew for your workflow.
<Frame>
<img src="/images/enterprise/zapier-4.png" alt="Zapier 6" />
</Frame>
- Configure the inputs for the Crew using the data from the Slack message.
</Step>
<Step title="Format the CrewAI AMP Output">
- Add another action step to format the text output from CrewAI AMP.
- Use Zapier's formatting tools to convert the Markdown output to HTML.
<Frame>
<img src="/images/enterprise/zapier-5.png" alt="Zapier 8" />
</Frame>
<Frame>
<img src="/images/enterprise/zapier-6.png" alt="Zapier 9" />
</Frame>
</Step>
<Step title="Send the Output via Email">
- 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.
<Frame>
<img src="/images/enterprise/zapier-7.png" alt="Zapier 7" />
</Frame>
</Step>
<Step title="Kick Off the crew from Slack">
- Enter the text in your Slack channel
<Frame>
<img src="/images/enterprise/zapier-7b.png" alt="Zapier 10" />
</Frame>
- Select the 3 ellipsis button and then chose Push to Zapier
<Frame>
<img src="/images/enterprise/zapier-8.png" alt="Zapier 11" />
</Frame>
</Step>
<Step title="Select the crew and then Push to Kick Off">
<Frame>
<img src="/images/enterprise/zapier-9.png" alt="Zapier 12" />
</Frame>
</Step>
</Steps>
## 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.

272
docs/v1.11.0/en/enterprise/integrations/asana.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="asana/create_comment">
**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.").
</Accordion>
<Accordion title="asana/create_project">
**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.").
</Accordion>
<Accordion title="asana/get_projects">
**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`
</Accordion>
<Accordion title="asana/get_project_by_id">
**Description:** Get a project by ID in Asana.
**Parameters:**
- `projectFilterId` (string, required): Project ID.
</Accordion>
<Accordion title="asana/create_task">
**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.
</Accordion>
<Accordion title="asana/update_task">
**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.
</Accordion>
<Accordion title="asana/get_tasks">
**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").
</Accordion>
<Accordion title="asana/get_tasks_by_id">
**Description:** Get a list of tasks by ID in Asana.
**Parameters:**
- `taskId` (string, required): Task ID.
</Accordion>
<Accordion title="asana/get_task_by_external_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.
</Accordion>
<Accordion title="asana/add_task_to_section">
**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").
</Accordion>
<Accordion title="asana/get_teams">
**Description:** Get a list of teams in Asana.
**Parameters:**
- `workspace` (string, required): Workspace - Returns the teams in this workspace visible to the authorized user.
</Accordion>
<Accordion title="asana/get_workspaces">
**Description:** Get a list of workspaces in Asana.
**Parameters:** None required.
</Accordion>
</AccordionGroup>
## 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()
```

281
docs/v1.11.0/en/enterprise/integrations/box.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="box/save_file">
**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").
</Accordion>
<Accordion title="box/save_file_from_object">
**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.
</Accordion>
<Accordion title="box/get_file_by_id">
**Description:** Get a file by ID in Box.
**Parameters:**
- `fileId` (string, required): File ID - The unique identifier that represents a file. (example: "12345").
</Accordion>
<Accordion title="box/list_files">
**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"
}
]
}
]
}
```
</Accordion>
<Accordion title="box/create_folder">
**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"
}
```
</Accordion>
<Accordion title="box/move_folder">
**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"
}
```
</Accordion>
<Accordion title="box/get_folder_by_id">
**Description:** Get a folder by ID in Box.
**Parameters:**
- `folderId` (string, required): Folder ID - The unique identifier that represents a folder. (example: "0").
</Accordion>
<Accordion title="box/search_folders">
**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"
}
]
}
]
}
```
</Accordion>
<Accordion title="box/delete_folder">
**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.
</Accordion>
</AccordionGroup>
## 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()
```

302
docs/v1.11.0/en/enterprise/integrations/clickup.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="clickup/search_tasks">
**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`
</Accordion>
<Accordion title="clickup/get_task_in_list">
**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.
</Accordion>
<Accordion title="clickup/create_task">
**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.
</Accordion>
<Accordion title="clickup/update_task">
**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.
</Accordion>
<Accordion title="clickup/delete_task">
**Description:** Delete a task in ClickUp.
**Parameters:**
- `taskId` (string, required): Task ID - The ID of the task to delete.
</Accordion>
<Accordion title="clickup/get_list">
**Description:** Get List information in ClickUp.
**Parameters:**
- `spaceId` (string, required): Space ID - The ID of the space containing the lists.
</Accordion>
<Accordion title="clickup/get_custom_fields_in_list">
**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.
</Accordion>
<Accordion title="clickup/get_all_fields_in_list">
**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.
</Accordion>
<Accordion title="clickup/get_space">
**Description:** Get Space information in ClickUp.
**Parameters:**
- `spaceId` (string, optional): Space ID - The ID of the space to retrieve.
</Accordion>
<Accordion title="clickup/get_folders">
**Description:** Get Folders in ClickUp.
**Parameters:**
- `spaceId` (string, required): Space ID - The ID of the space containing the folders.
</Accordion>
<Accordion title="clickup/get_member">
**Description:** Get Member information in ClickUp.
**Parameters:** None required.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with ClickUp integration setup or
troubleshooting.
</Card>

331
docs/v1.11.0/en/enterprise/integrations/github.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="github/create_issue">
**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"]`).
</Accordion>
<Accordion title="github/update_issue">
**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`
</Accordion>
<Accordion title="github/get_issue_by_number">
**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.
</Accordion>
<Accordion title="github/lock_issue">
**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`
</Accordion>
<Accordion title="github/search_issue">
**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`
</Accordion>
<Accordion title="github/create_release">
**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`
</Accordion>
<Accordion title="github/update_release">
**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`
</Accordion>
<Accordion title="github/get_release_by_id">
**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.
</Accordion>
<Accordion title="github/get_release_by_tag_name">
**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").
</Accordion>
<Accordion title="github/delete_release">
**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.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with GitHub integration setup or
troubleshooting.
</Card>

303
docs/v1.11.0/en/enterprise/integrations/gmail.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="gmail/fetch_emails">
**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)
</Accordion>
<Accordion title="gmail/send_email">
**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.
</Accordion>
<Accordion title="gmail/delete_email">
**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.
</Accordion>
<Accordion title="gmail/create_draft">
**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.
</Accordion>
<Accordion title="gmail/get_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.
</Accordion>
<Accordion title="gmail/get_attachment">
**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.
</Accordion>
<Accordion title="gmail/fetch_thread">
**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.
</Accordion>
<Accordion title="gmail/modify_thread">
**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.
</Accordion>
<Accordion title="gmail/trash_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.
</Accordion>
<Accordion title="gmail/untrash_thread">
**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.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Gmail integration setup or
troubleshooting.
</Card>

367
docs/v1.11.0/en/enterprise/integrations/google_calendar.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="google_calendar/get_availability">
**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
</Accordion>
<Accordion title="google_calendar/create_event">
**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
</Accordion>
<Accordion title="google_calendar/view_events">
**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.
</Accordion>
<Accordion title="google_calendar/update_event">
**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
</Accordion>
<Accordion title="google_calendar/delete_event">
**Description:** Delete a specified event.
**Parameters:**
- `calendarId` (string, required): Calendar ID
- `eventId` (string, required): Event ID to delete
</Accordion>
<Accordion title="google_calendar/view_calendar_list">
**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
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Google Calendar integration setup
or troubleshooting.
</Card>

494
docs/v1.11.0/en/enterprise/integrations/google_contacts.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="google_contacts/get_contacts">
**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
</Accordion>
<Accordion title="google_contacts/search_contacts">
**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
</Accordion>
<Accordion title="google_contacts/list_directory_people">
**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
</Accordion>
<Accordion title="google_contacts/search_directory_people">
**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
</Accordion>
<Accordion title="google_contacts/list_other_contacts">
**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
</Accordion>
<Accordion title="google_contacts/search_other_contacts">
**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
</Accordion>
<Accordion title="google_contacts/get_person">
**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
</Accordion>
<Accordion title="google_contacts/create_contact">
**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"
}
]
```
</Accordion>
<Accordion title="google_contacts/update_contact">
**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
</Accordion>
<Accordion title="google_contacts/delete_contact">
**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')
</Accordion>
<Accordion title="google_contacts/batch_get_people">
**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
</Accordion>
<Accordion title="google_contacts/list_contact_groups">
**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
</Accordion>
<Accordion title="google_contacts/get_contact_group">
**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
</Accordion>
<Accordion title="google_contacts/create_contact_group">
**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"
}
]
```
</Accordion>
<Accordion title="google_contacts/update_contact_group">
**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"
}
]
```
</Accordion>
<Accordion title="google_contacts/delete_contact_group">
**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
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Google Contacts integration setup
or troubleshooting.
</Card>

551
docs/v1.11.0/en/enterprise/integrations/google_docs.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="google_docs/create_document">
**Description:** Create a new Google Document.
**Parameters:**
- `title` (string, optional): The title for the new document.
</Accordion>
<Accordion title="google_docs/get_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`.
</Accordion>
<Accordion title="google_docs/batch_update">
**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).
</Accordion>
<Accordion title="google_docs/insert_text">
**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`.
</Accordion>
<Accordion title="google_docs/replace_text">
**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`.
</Accordion>
<Accordion title="google_docs/delete_content_range">
**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.
</Accordion>
<Accordion title="google_docs/insert_page_break">
**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`.
</Accordion>
<Accordion title="google_docs/create_named_range">
**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.
</Accordion>
<Accordion title="google_docs/create_document_with_content">
**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.
</Accordion>
<Accordion title="google_docs/append_text">
**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.
</Accordion>
<Accordion title="google_docs/set_text_bold">
**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.
</Accordion>
<Accordion title="google_docs/set_text_italic">
**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.
</Accordion>
<Accordion title="google_docs/set_text_underline">
**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.
</Accordion>
<Accordion title="google_docs/set_text_strikethrough">
**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.
</Accordion>
<Accordion title="google_docs/set_font_size">
**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.
</Accordion>
<Accordion title="google_docs/set_text_color">
**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.
</Accordion>
<Accordion title="google_docs/create_hyperlink">
**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"`.
</Accordion>
<Accordion title="google_docs/apply_heading_style">
**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`.
</Accordion>
<Accordion title="google_docs/set_paragraph_alignment">
**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`.
</Accordion>
<Accordion title="google_docs/set_line_spacing">
**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.
</Accordion>
<Accordion title="google_docs/create_paragraph_bullets">
**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`.
</Accordion>
<Accordion title="google_docs/delete_paragraph_bullets">
**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.
</Accordion>
<Accordion title="google_docs/insert_table_with_content">
**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"]]`.
</Accordion>
<Accordion title="google_docs/insert_table_row">
**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`.
</Accordion>
<Accordion title="google_docs/insert_table_column">
**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`.
</Accordion>
<Accordion title="google_docs/delete_table_row">
**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`.
</Accordion>
<Accordion title="google_docs/delete_table_column">
**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.
</Accordion>
<Accordion title="google_docs/merge_table_cells">
**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.
</Accordion>
<Accordion title="google_docs/unmerge_table_cells">
**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.
</Accordion>
<Accordion title="google_docs/insert_inline_image">
**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`.
</Accordion>
<Accordion title="google_docs/insert_section_break">
**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).
</Accordion>
<Accordion title="google_docs/create_header">
**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`.
</Accordion>
<Accordion title="google_docs/create_footer">
**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`.
</Accordion>
<Accordion title="google_docs/delete_header">
**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.
</Accordion>
<Accordion title="google_docs/delete_footer">
**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.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Google Docs integration setup or
troubleshooting.
</Card>

239
docs/v1.11.0/en/enterprise/integrations/google_drive.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="google_drive/get_file">
**Description:** Get a file by ID from Google Drive.
**Parameters:**
- `file_id` (string, required): The ID of the file to retrieve.
</Accordion>
<Accordion title="google_drive/list_files">
**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).
</Accordion>
<Accordion title="google_drive/upload_file">
**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.
</Accordion>
<Accordion title="google_drive/download_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).
</Accordion>
<Accordion title="google_drive/create_folder">
**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.
</Accordion>
<Accordion title="google_drive/delete_file">
**Description:** Delete a file from Google Drive.
**Parameters:**
- `file_id` (string, required): The ID of the file to delete.
</Accordion>
<Accordion title="google_drive/share_file">
**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.
</Accordion>
<Accordion title="google_drive/update_file">
**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.
</Accordion>
</AccordionGroup>
## 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()
```

369
docs/v1.11.0/en/enterprise/integrations/google_sheets.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="google_sheets/get_spreadsheet">
**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.
</Accordion>
<Accordion title="google_sheets/get_values">
**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
</Accordion>
<Accordion title="google_sheets/update_values">
**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
</Accordion>
<Accordion title="google_sheets/append_values">
**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
</Accordion>
<Accordion title="google_sheets/create_spreadsheet">
**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"
}
}
]
```
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Google Sheets integration setup
or troubleshooting.
</Card>

546
docs/v1.11.0/en/enterprise/integrations/google_slides.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="google_slides/create_blank_presentation">
**Description:** Creates a blank presentation with no content.
**Parameters:**
- `title` (string, required): The title of the presentation.
</Accordion>
<Accordion title="google_slides/get_presentation_metadata">
**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.
</Accordion>
<Accordion title="google_slides/get_presentation_text">
**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.
</Accordion>
<Accordion title="google_slides/get_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.
</Accordion>
<Accordion title="google_slides/batch_update_presentation">
**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"
}
```
</Accordion>
<Accordion title="google_slides/get_slide_text">
**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.
</Accordion>
<Accordion title="google_slides/get_page">
**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.
</Accordion>
<Accordion title="google_slides/get_thumbnail">
**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.
</Accordion>
<Accordion title="google_slides/create_slide">
**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.
</Accordion>
<Accordion title="google_slides/create_slide_with_layout">
**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.
</Accordion>
<Accordion title="google_slides/create_text_box">
**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).
</Accordion>
<Accordion title="google_slides/delete_slide">
**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.
</Accordion>
<Accordion title="google_slides/duplicate_slide">
**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.
</Accordion>
<Accordion title="google_slides/move_slides">
**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.
</Accordion>
<Accordion title="google_slides/insert_youtube_video">
**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).
</Accordion>
<Accordion title="google_slides/insert_drive_video">
**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.
</Accordion>
<Accordion title="google_slides/set_slide_background_image">
**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.
</Accordion>
<Accordion title="google_slides/create_table">
**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.
</Accordion>
<Accordion title="google_slides/create_table_with_content">
**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"]].
</Accordion>
<Accordion title="google_slides/import_data_from_sheet">
**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.
</Accordion>
<Accordion title="google_slides/upload_file_to_drive">
**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.
</Accordion>
<Accordion title="google_slides/link_file_to_presentation">
**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.
</Accordion>
<Accordion title="google_slides/get_all_presentations">
**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.
</Accordion>
<Accordion title="google_slides/delete_presentation">
**Description:** Deletes a presentation by ID.
**Parameters:**
- `presentationId` (string, required): The ID of the presentation to delete.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Google Slides integration setup
or troubleshooting.
</Card>

616
docs/v1.11.0/en/enterprise/integrations/hubspot.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="hubspot/create_company">
**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.
</Accordion>
<Accordion title="hubspot/create_contact">
**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.
</Accordion>
<Accordion title="hubspot/create_deal">
**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`.
</Accordion>
<Accordion title="hubspot/create_record_engagements">
**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`)
</Accordion>
<Accordion title="hubspot/update_company">
**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.
</Accordion>
<Accordion title="hubspot/create_record_any">
**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.
</Accordion>
<Accordion title="hubspot/update_contact">
**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.
</Accordion>
<Accordion title="hubspot/update_deal">
**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.
</Accordion>
<Accordion title="hubspot/update_record_engagements">
**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.
</Accordion>
<Accordion title="hubspot/update_record_any">
**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.
</Accordion>
<Accordion title="hubspot/list_companies">
**Description:** Get a list of company records from HubSpot.
**Parameters:**
- `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages.
</Accordion>
<Accordion title="hubspot/list_contacts">
**Description:** Get a list of contact records from HubSpot.
**Parameters:**
- `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages.
</Accordion>
<Accordion title="hubspot/list_deals">
**Description:** Get a list of deal records from HubSpot.
**Parameters:**
- `paginationParameters` (object, optional): Use `pageCursor` to fetch subsequent pages.
</Accordion>
<Accordion title="hubspot/get_records_engagements">
**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.
</Accordion>
<Accordion title="hubspot/get_records_any">
**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.
</Accordion>
<Accordion title="hubspot/get_company">
**Description:** Get a single company record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the company to retrieve.
</Accordion>
<Accordion title="hubspot/get_contact">
**Description:** Get a single contact record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the contact to retrieve.
</Accordion>
<Accordion title="hubspot/get_deal">
**Description:** Get a single deal record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the deal to retrieve.
</Accordion>
<Accordion title="hubspot/get_record_by_id_engagements">
**Description:** Get a single engagement record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the engagement to retrieve.
</Accordion>
<Accordion title="hubspot/get_record_by_id_any">
**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.
</Accordion>
<Accordion title="hubspot/search_companies">
**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.
</Accordion>
<Accordion title="hubspot/search_contacts">
**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.
</Accordion>
<Accordion title="hubspot/search_deals">
**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.
</Accordion>
<Accordion title="hubspot/search_records_engagements">
**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.
</Accordion>
<Accordion title="hubspot/search_records_any">
**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.
</Accordion>
<Accordion title="hubspot/delete_record_companies">
**Description:** Delete a company record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the company to delete.
</Accordion>
<Accordion title="hubspot/delete_record_contacts">
**Description:** Delete a contact record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the contact to delete.
</Accordion>
<Accordion title="hubspot/delete_record_deals">
**Description:** Delete a deal record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the deal to delete.
</Accordion>
<Accordion title="hubspot/delete_record_engagements">
**Description:** Delete an engagement record by its ID.
**Parameters:**
- `recordId` (string, required): The ID of the engagement to delete.
</Accordion>
<Accordion title="hubspot/delete_record_any">
**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.
</Accordion>
<Accordion title="hubspot/get_contacts_by_list_id">
**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.
</Accordion>
<Accordion title="hubspot/describe_action_schema">
**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').
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with HubSpot integration setup or
troubleshooting.
</Card>

405
docs/v1.11.0/en/enterprise/integrations/jira.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="jira/create_issue">
**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"
}
```
</Accordion>
<Accordion title="jira/update_issue">
**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.
</Accordion>
<Accordion title="jira/get_issue_by_key">
**Description:** Get an issue by key in Jira.
**Parameters:**
- `issueKey` (string, required): Issue Key (example: "TEST-1234").
</Accordion>
<Accordion title="jira/filter_issues">
**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.
</Accordion>
<Accordion title="jira/search_by_jql">
**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"
}
```
</Accordion>
<Accordion title="jira/update_issue_any">
**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.
</Accordion>
<Accordion title="jira/describe_action_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.
</Accordion>
<Accordion title="jira/get_projects">
**Description:** Get Projects in Jira.
**Parameters:**
- `paginationParameters` (object, optional): Pagination Parameters.
```json
{
"pageCursor": "cursor_string"
}
```
</Accordion>
<Accordion title="jira/get_issue_types_by_project">
**Description:** Get Issue Types by project in Jira.
**Parameters:**
- `project` (string, required): Project key.
</Accordion>
<Accordion title="jira/get_issue_types">
**Description:** Get all Issue Types in Jira.
**Parameters:** None required.
</Accordion>
<Accordion title="jira/get_issue_status_by_project">
**Description:** Get issue statuses for a given project.
**Parameters:**
- `project` (string, required): Project key.
</Accordion>
<Accordion title="jira/get_all_assignees_by_project">
**Description:** Get assignees for a given project.
**Parameters:**
- `project` (string, required): Project key.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Jira integration setup or
troubleshooting.
</Card>

466
docs/v1.11.0/en/enterprise/integrations/linear.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="linear/create_issue">
**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"]
}
```
</Accordion>
<Accordion title="linear/update_issue">
**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"]
}
```
</Accordion>
<Accordion title="linear/get_issue_by_id">
**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").
</Accordion>
<Accordion title="linear/get_issue_by_issue_identifier">
**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").
</Accordion>
<Accordion title="linear/search_issue">
**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`
</Accordion>
<Accordion title="linear/delete_issue">
**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").
</Accordion>
<Accordion title="linear/archive_issue">
**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").
</Accordion>
<Accordion title="linear/create_sub_issue">
**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"
}
```
</Accordion>
<Accordion title="linear/create_project">
**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": ""
}
```
</Accordion>
<Accordion title="linear/update_project">
**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": ""
}
```
</Accordion>
<Accordion title="linear/get_project_by_id">
**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").
</Accordion>
<Accordion title="linear/delete_project">
**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").
</Accordion>
<Accordion title="linear/search_teams">
**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`
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Linear integration setup or
troubleshooting.
</Card>

507
docs/v1.11.0/en/enterprise/integrations/microsoft_excel.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="microsoft_excel/create_workbook">
**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"
}
]
```
</Accordion>
<Accordion title="microsoft_excel/get_workbooks">
**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
</Accordion>
<Accordion title="microsoft_excel/get_worksheets">
**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
</Accordion>
<Accordion title="microsoft_excel/create_worksheet">
**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
</Accordion>
<Accordion title="microsoft_excel/get_range_data">
**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')
</Accordion>
<Accordion title="microsoft_excel/update_range_data">
**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"]
]
```
</Accordion>
<Accordion title="microsoft_excel/add_table">
**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
</Accordion>
<Accordion title="microsoft_excel/get_tables">
**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
</Accordion>
<Accordion title="microsoft_excel/add_table_row">
**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"]
```
</Accordion>
<Accordion title="microsoft_excel/get_table_data">
**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
</Accordion>
<Accordion title="microsoft_excel/create_chart">
**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
</Accordion>
<Accordion title="microsoft_excel/get_cell">
**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)
</Accordion>
<Accordion title="microsoft_excel/get_used_range">
**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
</Accordion>
<Accordion title="microsoft_excel/get_used_range_metadata">
**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
</Accordion>
<Accordion title="microsoft_excel/list_charts">
**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
</Accordion>
<Accordion title="microsoft_excel/delete_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
</Accordion>
<Accordion title="microsoft_excel/delete_table">
**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
</Accordion>
<Accordion title="microsoft_excel/list_names">
**Description:** Get all named ranges in an Excel workbook.
**Parameters:**
- `file_id` (string, required): The ID of the Excel file
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Microsoft Excel integration setup
or troubleshooting.
</Card>

329
docs/v1.11.0/en/enterprise/integrations/microsoft_onedrive.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="microsoft_onedrive/list_files">
**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.
</Accordion>
<Accordion title="microsoft_onedrive/get_file_info">
**Description:** Get information about a specific file or folder.
**Parameters:**
- `item_id` (string, required): The ID of the file or folder.
</Accordion>
<Accordion title="microsoft_onedrive/download_file">
**Description:** Download a file from OneDrive.
**Parameters:**
- `item_id` (string, required): The ID of the file to download.
</Accordion>
<Accordion title="microsoft_onedrive/upload_file">
**Description:** Upload a file to OneDrive.
**Parameters:**
- `file_name` (string, required): Name of the file to upload.
- `content` (string, required): Base64 encoded file content.
</Accordion>
<Accordion title="microsoft_onedrive/create_folder">
**Description:** Create a new folder in OneDrive.
**Parameters:**
- `folder_name` (string, required): Name of the folder to create.
</Accordion>
<Accordion title="microsoft_onedrive/delete_item">
**Description:** Delete a file or folder from OneDrive.
**Parameters:**
- `item_id` (string, required): The ID of the file or folder to delete.
</Accordion>
<Accordion title="microsoft_onedrive/copy_item">
**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).
</Accordion>
<Accordion title="microsoft_onedrive/move_item">
**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).
</Accordion>
<Accordion title="microsoft_onedrive/search_files">
**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`.
</Accordion>
<Accordion title="microsoft_onedrive/share_item">
**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`.
</Accordion>
<Accordion title="microsoft_onedrive/get_thumbnails">
**Description:** Get thumbnails for a file.
**Parameters:**
- `item_id` (string, required): The ID of the file.
</Accordion>
<Accordion title="microsoft_onedrive/list_files_by_path">
**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".
</Accordion>
<Accordion title="microsoft_onedrive/get_recent_files">
**Description:** Get recently accessed files from OneDrive.
**Parameters:**
- `top` (integer, optional): Number of items to retrieve (max 200). Default is `25`.
</Accordion>
<Accordion title="microsoft_onedrive/get_shared_with_me">
**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".
</Accordion>
<Accordion title="microsoft_onedrive/get_file_by_path">
**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').
</Accordion>
<Accordion title="microsoft_onedrive/download_file_by_path">
**Description:** Download a file from OneDrive by its path.
**Parameters:**
- `file_path` (string, required): The file path (e.g., 'Documents/report.docx').
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Microsoft OneDrive integration
setup or troubleshooting.
</Card>

330
docs/v1.11.0/en/enterprise/integrations/microsoft_outlook.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="microsoft_outlook/get_messages">
**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.
</Accordion>
<Accordion title="microsoft_outlook/send_email">
**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`.
</Accordion>
<Accordion title="microsoft_outlook/get_calendar_events">
**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".
</Accordion>
<Accordion title="microsoft_outlook/create_calendar_event">
**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.
</Accordion>
<Accordion title="microsoft_outlook/get_contacts">
**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".
</Accordion>
<Accordion title="microsoft_outlook/create_contact">
**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.
</Accordion>
<Accordion title="microsoft_outlook/get_message">
**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".
</Accordion>
<Accordion title="microsoft_outlook/reply_to_email">
**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.
</Accordion>
<Accordion title="microsoft_outlook/forward_email">
**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.
</Accordion>
<Accordion title="microsoft_outlook/mark_message_read">
**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.
</Accordion>
<Accordion title="microsoft_outlook/delete_message">
**Description:** Delete an email message.
**Parameters:**
- `message_id` (string, required): The unique identifier of the message to delete. Obtain from get_messages action.
</Accordion>
<Accordion title="microsoft_outlook/update_event">
**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.
</Accordion>
<Accordion title="microsoft_outlook/delete_event">
**Description:** Delete a calendar event.
**Parameters:**
- `event_id` (string, required): The unique identifier of the event to delete. Obtain from get_calendar_events action.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Microsoft Outlook integration
setup or troubleshooting.
</Card>

733
docs/v1.11.0/en/enterprise/integrations/microsoft_sharepoint.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="microsoft_sharepoint/get_sites">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/get_site">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/get_drives">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/get_site_lists">
**Description:** Get all lists in a SharePoint site.
**Parameters:**
- `site_id` (string, required): The ID of the SharePoint site
</Accordion>
<Accordion title="microsoft_sharepoint/get_list">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_list_items">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/create_list_item">
**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"
}
```
</Accordion>
<Accordion title="microsoft_sharepoint/update_list_item">
**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"
}
```
</Accordion>
<Accordion title="microsoft_sharepoint/delete_list_item">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/upload_file_to_library">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/list_files">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/delete_file">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/list_files_by_path">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/download_file">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_file_info">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/create_folder">
**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'
</Accordion>
<Accordion title="microsoft_sharepoint/search_files">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/copy_file">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/move_file">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_worksheets">
**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)
</Accordion>
<Accordion title="microsoft_sharepoint/create_excel_worksheet">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_range_data">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/update_excel_range_data">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_used_range_metadata">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_used_range">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_cell">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/add_excel_table">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_tables">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/add_excel_table_row">
**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])
</Accordion>
<Accordion title="microsoft_sharepoint/get_excel_table_data">
**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')
</Accordion>
<Accordion title="microsoft_sharepoint/create_excel_chart">
**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'
</Accordion>
<Accordion title="microsoft_sharepoint/list_excel_charts">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/delete_excel_worksheet">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/delete_excel_table">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/list_excel_names">
**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
</Accordion>
<Accordion title="microsoft_sharepoint/get_word_document_content">
**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
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Microsoft SharePoint integration
setup or troubleshooting.
</Card>

323
docs/v1.11.0/en/enterprise/integrations/microsoft_teams.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="microsoft_teams/get_teams">
**Description:** Get all teams the user is a member of.
**Parameters:**
- No parameters required.
</Accordion>
<Accordion title="microsoft_teams/get_channels">
**Description:** Get channels in a specific team.
**Parameters:**
- `team_id` (string, required): The ID of the team.
</Accordion>
<Accordion title="microsoft_teams/send_message">
**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`.
</Accordion>
<Accordion title="microsoft_teams/get_messages">
**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`.
</Accordion>
<Accordion title="microsoft_teams/create_meeting">
**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).
</Accordion>
<Accordion title="microsoft_teams/search_online_meetings_by_join_url">
**Description:** Search online meetings by Join Web URL.
**Parameters:**
- `join_web_url` (string, required): The join web URL of the meeting to search for.
</Accordion>
<Accordion title="microsoft_teams/search_online_meetings_by_meeting_id">
**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.
</Accordion>
<Accordion title="microsoft_teams/get_meeting">
**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.
</Accordion>
<Accordion title="microsoft_teams/get_team_members">
**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.
</Accordion>
<Accordion title="microsoft_teams/create_channel">
**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`.
</Accordion>
<Accordion title="microsoft_teams/get_message_replies">
**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.
</Accordion>
<Accordion title="microsoft_teams/reply_to_message">
**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`.
</Accordion>
<Accordion title="microsoft_teams/update_meeting">
**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.
</Accordion>
<Accordion title="microsoft_teams/delete_meeting">
**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.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Microsoft Teams integration setup
or troubleshooting.
</Card>

240
docs/v1.11.0/en/enterprise/integrations/microsoft_word.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="microsoft_word/get_documents">
**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.
</Accordion>
<Accordion title="microsoft_word/create_text_document">
**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."
</Accordion>
<Accordion title="microsoft_word/get_document_content">
**Description:** Get the content of a document (works best with text files).
**Parameters:**
- `file_id` (string, required): The ID of the document.
</Accordion>
<Accordion title="microsoft_word/get_document_properties">
**Description:** Get properties and metadata of a document.
**Parameters:**
- `file_id` (string, required): The ID of the document.
</Accordion>
<Accordion title="microsoft_word/delete_document">
**Description:** Delete a document.
**Parameters:**
- `file_id` (string, required): The ID of the document to delete.
</Accordion>
<Accordion title="microsoft_word/copy_document">
**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)
</Accordion>
<Accordion title="microsoft_word/move_document">
**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
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Microsoft Word integration setup
or troubleshooting.
</Card>

296
docs/v1.11.0/en/enterprise/integrations/notion.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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
<AccordionGroup>
<Accordion title="notion/list_users">
**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.
</Accordion>
<Accordion title="notion/get_user">
**Description:** Retrieve a specific user by ID.
**Parameters:**
- `user_id` (string, required): The ID of the user to retrieve.
</Accordion>
<Accordion title="notion/create_comment">
**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"
}
}
]
```
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Notion integration setup or
troubleshooting.
</Card>

685
docs/v1.11.0/en/enterprise/integrations/salesforce.mdx Normal file
View File

@@ -0,0 +1,685 @@
---
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)
## Setting Up Salesforce Integration
### 1. Connect Your Salesforce Account
1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Salesforce** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
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)
### 2. Install Required Package
```bash
uv add crewai-tools
```
### 3. Environment Variable Setup
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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**
<AccordionGroup>
<Accordion title="salesforce/create_record_contact">
**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
</Accordion>
<Accordion title="salesforce/create_record_lead">
**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
</Accordion>
<Accordion title="salesforce/create_record_opportunity">
**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
</Accordion>
<Accordion title="salesforce/create_record_task">
**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
</Accordion>
<Accordion title="salesforce/create_record_account">
**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
</Accordion>
<Accordion title="salesforce/create_record_any">
**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.
</Accordion>
</AccordionGroup>
### **Record Updates**
<AccordionGroup>
<Accordion title="salesforce/update_record_contact">
**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
</Accordion>
<Accordion title="salesforce/update_record_lead">
**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
</Accordion>
<Accordion title="salesforce/update_record_opportunity">
**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
</Accordion>
<Accordion title="salesforce/update_record_task">
**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
</Accordion>
<Accordion title="salesforce/update_record_account">
**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
</Accordion>
<Accordion title="salesforce/update_record_any">
**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.
</Accordion>
</AccordionGroup>
### **Record Retrieval**
<AccordionGroup>
<Accordion title="salesforce/get_record_by_id_contact">
**Description:** Get a Contact record by its ID.
**Parameters:**
- `recordId` (string, required): Record ID of the Contact
</Accordion>
<Accordion title="salesforce/get_record_by_id_lead">
**Description:** Get a Lead record by its ID.
**Parameters:**
- `recordId` (string, required): Record ID of the Lead
</Accordion>
<Accordion title="salesforce/get_record_by_id_opportunity">
**Description:** Get an Opportunity record by its ID.
**Parameters:**
- `recordId` (string, required): Record ID of the Opportunity
</Accordion>
<Accordion title="salesforce/get_record_by_id_task">
**Description:** Get a Task record by its ID.
**Parameters:**
- `recordId` (string, required): Record ID of the Task
</Accordion>
<Accordion title="salesforce/get_record_by_id_account">
**Description:** Get an Account record by its ID.
**Parameters:**
- `recordId` (string, required): Record ID of the Account
</Accordion>
<Accordion title="salesforce/get_record_by_id_any">
**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
</Accordion>
</AccordionGroup>
### **Record Search**
<AccordionGroup>
<Accordion title="salesforce/search_records_contact">
**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
</Accordion>
<Accordion title="salesforce/search_records_lead">
**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
</Accordion>
<Accordion title="salesforce/search_records_opportunity">
**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
</Accordion>
<Accordion title="salesforce/search_records_task">
**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
</Accordion>
<Accordion title="salesforce/search_records_account">
**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
</Accordion>
<Accordion title="salesforce/search_records_any">
**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
</Accordion>
</AccordionGroup>
### **List View Retrieval**
<AccordionGroup>
<Accordion title="salesforce/get_record_by_view_id_contact">
**Description:** Get Contact records from a specific List View.
**Parameters:**
- `listViewId` (string, required): List View ID
- `paginationParameters` (object, optional): Pagination settings with pageCursor
</Accordion>
<Accordion title="salesforce/get_record_by_view_id_lead">
**Description:** Get Lead records from a specific List View.
**Parameters:**
- `listViewId` (string, required): List View ID
- `paginationParameters` (object, optional): Pagination settings with pageCursor
</Accordion>
<Accordion title="salesforce/get_record_by_view_id_opportunity">
**Description:** Get Opportunity records from a specific List View.
**Parameters:**
- `listViewId` (string, required): List View ID
- `paginationParameters` (object, optional): Pagination settings with pageCursor
</Accordion>
<Accordion title="salesforce/get_record_by_view_id_task">
**Description:** Get Task records from a specific List View.
**Parameters:**
- `listViewId` (string, required): List View ID
- `paginationParameters` (object, optional): Pagination settings with pageCursor
</Accordion>
<Accordion title="salesforce/get_record_by_view_id_account">
**Description:** Get Account records from a specific List View.
**Parameters:**
- `listViewId` (string, required): List View ID
- `paginationParameters` (object, optional): Pagination settings with pageCursor
</Accordion>
<Accordion title="salesforce/get_record_by_view_id_any">
**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
</Accordion>
</AccordionGroup>
### **Custom Fields**
<AccordionGroup>
<Accordion title="salesforce/create_custom_field_contact">
**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
</Accordion>
<Accordion title="salesforce/create_custom_field_lead">
**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
</Accordion>
<Accordion title="salesforce/create_custom_field_opportunity">
**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
</Accordion>
<Accordion title="salesforce/create_custom_field_task">
**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
</Accordion>
<Accordion title="salesforce/create_custom_field_account">
**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
</Accordion>
<Accordion title="salesforce/create_custom_field_any">
**Description:** Deploy custom fields for any object type.
**Note:** This is a flexible tool for creating custom fields on custom or unknown object types.
</Accordion>
</AccordionGroup>
### **Advanced Operations**
<AccordionGroup>
<Accordion title="salesforce/write_soql_query">
**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'")
</Accordion>
<Accordion title="salesforce/create_custom_object">
**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")
</Accordion>
<Accordion title="salesforce/describe_action_schema">
**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.
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Salesforce integration setup or
troubleshooting.
</Card>

410
docs/v1.11.0/en/enterprise/integrations/shopify.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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**
<AccordionGroup>
<Accordion title="shopify/get_customers">
**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)
</Accordion>
<Accordion title="shopify/search_customers">
**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)
</Accordion>
<Accordion title="shopify/create_customer">
**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
</Accordion>
<Accordion title="shopify/update_customer">
**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
</Accordion>
</AccordionGroup>
### **Order Management**
<AccordionGroup>
<Accordion title="shopify/get_orders">
**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)
</Accordion>
<Accordion title="shopify/create_order">
**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
</Accordion>
<Accordion title="shopify/update_order">
**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
</Accordion>
<Accordion title="shopify/get_abandoned_carts">
**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)
</Accordion>
</AccordionGroup>
### **Product Management (REST API)**
<AccordionGroup>
<Accordion title="shopify/get_products">
**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)
</Accordion>
<Accordion title="shopify/create_product">
**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
</Accordion>
<Accordion title="shopify/update_product">
**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
</Accordion>
</AccordionGroup>
### **Product Management (GraphQL)**
<AccordionGroup>
<Accordion title="shopify/get_products_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
</Accordion>
<Accordion title="shopify/create_product_graphql">
**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
</Accordion>
<Accordion title="shopify/update_product_graphql">
**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
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Shopify integration setup or
troubleshooting.
</Card>

327
docs/v1.11.0/en/enterprise/integrations/slack.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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**
<AccordionGroup>
<Accordion title="slack/list_members">
**Description:** List all members in a Slack channel.
**Parameters:**
- No parameters required - retrieves all channel members
</Accordion>
<Accordion title="slack/get_user_by_email">
**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
</Accordion>
<Accordion title="slack/get_users_by_name">
**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
</Accordion>
</AccordionGroup>
### **Channel Management**
<AccordionGroup>
<Accordion title="slack/list_channels">
**Description:** List all channels in your Slack workspace.
**Parameters:**
- No parameters required - retrieves all accessible channels
</Accordion>
</AccordionGroup>
### **Messaging**
<AccordionGroup>
<Accordion title="slack/send_message">
**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)
</Accordion>
<Accordion title="slack/send_direct_message">
**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)
</Accordion>
</AccordionGroup>
### **Search & Discovery**
<AccordionGroup>
<Accordion title="slack/search_messages">
**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
</Accordion>
</AccordionGroup>
## 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
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with Slack integration setup or
troubleshooting.
</Card>

329
docs/v1.11.0/en/enterprise/integrations/stripe.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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**
<AccordionGroup>
<Accordion title="stripe/create_customer">
**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}`)
</Accordion>
<Accordion title="stripe/get_customer_by_id">
**Description:** Retrieve a specific customer by their Stripe customer ID.
**Parameters:**
- `idGetCustomer` (string, required): The Stripe customer ID to retrieve
</Accordion>
<Accordion title="stripe/get_customers">
**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)
</Accordion>
<Accordion title="stripe/update_customer">
**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
</Accordion>
</AccordionGroup>
### **Subscription Management**
<AccordionGroup>
<Accordion title="stripe/create_subscription">
**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
</Accordion>
<Accordion title="stripe/get_subscriptions">
**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)
</Accordion>
</AccordionGroup>
### **Product Management**
<AccordionGroup>
<Accordion title="stripe/create_product">
**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
</Accordion>
<Accordion title="stripe/get_product_by_id">
**Description:** Retrieve a specific product by its Stripe product ID.
**Parameters:**
- `productId` (string, required): The Stripe product ID to retrieve
</Accordion>
<Accordion title="stripe/get_products">
**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)
</Accordion>
</AccordionGroup>
### **Financial Operations**
<AccordionGroup>
<Accordion title="stripe/get_balance_transactions">
**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
</Accordion>
<Accordion title="stripe/get_plans">
**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
</Accordion>
</AccordionGroup>
## 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.

369
docs/v1.11.0/en/enterprise/integrations/zendesk.mdx Normal file
View File

@@ -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
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```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**
<AccordionGroup>
<Accordion title="zendesk/create_ticket">
**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
</Accordion>
<Accordion title="zendesk/update_ticket">
**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
</Accordion>
<Accordion title="zendesk/get_ticket_by_id">
**Description:** Retrieve a specific ticket by its ID.
**Parameters:**
- `ticketId` (string, required): The ticket ID to retrieve (e.g., "35436")
</Accordion>
<Accordion title="zendesk/add_comment_to_ticket">
**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
</Accordion>
<Accordion title="zendesk/search_tickets">
**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
</Accordion>
</AccordionGroup>
### **User Management**
<AccordionGroup>
<Accordion title="zendesk/create_user">
**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
</Accordion>
<Accordion title="zendesk/update_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
</Accordion>
<Accordion title="zendesk/get_user_by_id">
**Description:** Retrieve a specific user by their ID.
**Parameters:**
- `userId` (string, required): The user ID to retrieve
</Accordion>
<Accordion title="zendesk/search_users">
**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
</Accordion>
</AccordionGroup>
### **Administrative Tools**
<AccordionGroup>
<Accordion title="zendesk/get_ticket_fields">
**Description:** Retrieve all standard and custom fields available for tickets.
**Parameters:**
- `paginationParameters` (object, optional): Pagination settings
- `pageCursor` (string, optional): Page cursor for pagination
</Accordion>
<Accordion title="zendesk/get_ticket_audits">
**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
</Accordion>
</AccordionGroup>
## 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()
```

100
docs/v1.11.0/en/enterprise/introduction.mdx Normal file
View File

@@ -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.
<Frame>
<img
src="/images/enterprise/crewai-enterprise-dashboard.png"
alt="CrewAI AMP Dashboard"
/>
</Frame>
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
<CardGroup cols={2}>
<Card title="Crew Deployments" icon="rocket">
Deploy your crews to a managed infrastructure with a few clicks
</Card>
<Card title="API Access" icon="code">
Access your deployed crews via REST API for integration with existing
systems
</Card>
<Card title="Observability" icon="chart-line">
Monitor your crews with detailed execution traces and logs
</Card>
<Card title="Tool Repository" icon="toolbox">
Publish and install tools to enhance your crews' capabilities
</Card>
<Card title="Webhook Streaming" icon="webhook">
Stream real-time events and updates to your systems
</Card>
<Card title="Crew Studio" icon="paintbrush">
Create and customize crews using a no-code/low-code interface
</Card>
</CardGroup>
## Deployment Options
<CardGroup cols={3}>
<Card title="GitHub Integration" icon="github">
Connect directly to your GitHub repositories to deploy code
</Card>
<Card title="Crew Studio" icon="palette">
Deploy crews created through the no-code Crew Studio interface
</Card>
<Card title="CLI Deployment" icon="terminal">
Use the CrewAI CLI for more advanced deployment workflows
</Card>
</CardGroup>
## Getting Started
<Steps>
<Step title="Sign up for an account">
Create your account at [app.crewai.com](https://app.crewai.com)
<Card title="Sign Up" icon="user" href="https://app.crewai.com/signup">
Sign Up
</Card>
</Step>
<Step title="Build your first crew">
Use code or Crew Studio to build your crew
<Card
title="Build Crew"
icon="paintbrush"
href="/en/enterprise/guides/build-crew"
>
Build Crew
</Card>
</Step>
<Step title="Deploy your crew">
Deploy your crew to the Enterprise platform
<Card
title="Deploy Crew"
icon="rocket"
href="/en/enterprise/guides/deploy-crew"
>
Deploy Crew
</Card>
</Step>
<Step title="Access your crew">
Integrate with your crew via the generated API endpoints
<Card
title="API Access"
icon="code"
href="/en/enterprise/guides/kickoff-crew"
>
Use the Crew API
</Card>
</Step>
</Steps>
For detailed instructions, check out our [deployment guide](/en/enterprise/guides/deploy-crew) or click the button below to get started.

152
docs/v1.11.0/en/enterprise/resources/frequently-asked-questions.mdx Normal file
View File

@@ -0,0 +1,152 @@
---
title: FAQs
description: "Frequently asked questions about CrewAI AMP"
icon: "circle-question"
mode: "wide"
---
<AccordionGroup>
<Accordion title="How is task execution handled in the hierarchical process?">
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.
</Accordion>
<Accordion title="Where can I get the latest CrewAI documentation?">
The most up-to-date documentation for CrewAI is available on our official documentation website: https://docs.crewai.com/
<Card href="https://docs.crewai.com/" icon="books">CrewAI Docs</Card>
</Accordion>
<Accordion title="What are the key differences between Hierarchical and Sequential Processes in CrewAI?">
#### 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
</Accordion>
<Accordion title="What are the benefits of using memory in the CrewAI framework?">
- **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
</Accordion>
<Accordion title="What is the purpose of setting a maximum RPM limit for an agent?">
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.
</Accordion>
<Accordion title="What role does human input play in the execution of tasks within a CrewAI crew?">
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).
</Accordion>
<Accordion title="What advanced customization options are available for tailoring and enhancing agent behavior and capabilities in CrewAI?">
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
</Accordion>
<Accordion title="In what scenarios is human input particularly useful in agent execution?">
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
</Accordion>
<Accordion title="What are the different types of memory that are available in crewAI?">
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:
<Card href="https://docs.crewai.com/concepts/memory" icon="brain">CrewAI Memory</Card>
</Accordion>
<Accordion title="How do I use Output Pydantic in a Task?">
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:
<Steps>
<Step title="Define a Pydantic model">
```python
from pydantic import BaseModel
class User(BaseModel):
name: str
age: int
```
</Step>
<Step title="Create a task with Output Pydantic">
```python
from crewai import Task, Crew, Agent
from my_models import User
task = Task(
description="Create a user with the provided name and age",
expected_output=User, # This is the Pydantic model
agent=agent,
tools=[tool1, tool2]
)
```
</Step>
<Step title="Set the output_pydantic attribute in your agent">
```python
from crewai import Agent
from my_models import User
agent = Agent(
role='User Creator',
goal='Create users',
backstory='I am skilled in creating user accounts',
tools=[tool1, tool2],
output_pydantic=User
)
```
</Step>
</Steps>
Here's a tutorial on how to consistently get structured outputs from your agents:
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/dNpKQk5uxHw"
title="Structured outputs in CrewAI"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</Accordion>
<Accordion title="How can I create custom tools for my CrewAI 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.
<Card href="/en/learn/create-custom-tools" icon="code">CrewAI Tools Guide</Card>
</Accordion>
<Accordion title="How can you control the maximum number of requests per minute that the entire crew can perform?">
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.
</Accordion>
</AccordionGroup>

49
docs/v1.11.0/en/examples/cookbooks.mdx Normal file
View File

@@ -0,0 +1,49 @@
---
title: CrewAI Cookbooks
description: Feature-focused quickstarts and notebooks for learning patterns fast.
icon: book
mode: "wide"
---
## Quickstarts & Demos
<CardGroup cols={3}>
<Card title="Collaboration" icon="people-arrows" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Collaboration/crewai_collaboration.ipynb">
Coordinate multiple agents on shared tasks. Includes notebook with end-to-end collaboration pattern.
</Card>
<Card title="Planning" icon="timeline" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Planning/crewai_planning.ipynb">
Teach agents to reason about multi-step plans before execution using the planning toolkit.
</Card>
<Card title="Reasoning" icon="lightbulb" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Reasoning/crewai_reasoning.ipynb">
Explore self-reflection loops, critique prompts, and structured thinking patterns.
</Card>
</CardGroup>
<CardGroup cols={3}>
<Card title="Structured Guardrails" icon="shield-check" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Guardrails/task_guardrails.ipynb">
Apply task-level guardrails with retries, validation functions, and safe fallbacks.
</Card>
<Card title="Gemini Search & Grounding" icon="magnifying-glass" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Custom%20LLM/gemini_search_grounding_crewai.ipynb">
Connect CrewAI to Gemini with search grounding for factual, citation-rich outputs.
</Card>
<Card title="Gemini Video Summaries" icon="video" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Custom%20LLM/summarize_video_gemini_crewai.ipynb">
Generate video recaps using Gemini multimodal LLM and CrewAI orchestration.
</Card>
</CardGroup>
<CardGroup cols={2}>
<Card title="Browse Quickstarts" icon="bolt" href="https://github.com/crewAIInc/crewAI-quickstarts">
View all notebooks and feature demos showcasing specific CrewAI capabilities.
</Card>
<Card title="Request a cookbook" icon="message-plus" href="https://community.crewai.com">
Missing a pattern? Drop a request in the community forum and we’ll expand the library.
</Card>
</CardGroup>
<Tip>
Use Cookbooks to learn a pattern quickly, then jump to Full Examples for production‑grade implementations.
</Tip>

86
docs/v1.11.0/en/examples/example.mdx Normal file
View File

@@ -0,0 +1,86 @@
---
title: CrewAI Examples
description: Explore curated examples organized by Crews, Flows, Integrations, and Notebooks.
icon: rocket-launch
mode: "wide"
---
## Crews
<CardGroup cols={3}>
<Card title="Marketing Strategy" icon="bullhorn" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/marketing_strategy">
Multi‑agent marketing campaign planning.
</Card>
<Card title="Surprise Trip" icon="plane" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/surprise_trip">
Personalized surprise travel planning.
</Card>
<Card title="Match Profile to Positions" icon="id-card" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/match_profile_to_positions">
CV‑to‑job matching with vector search.
</Card>
<Card title="Job Posting" icon="newspaper" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/job-posting">
Automated job description creation.
</Card>
<Card title="Game Builder Crew" icon="gamepad" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/game-builder-crew">
Multi‑agent team that designs and builds Python games.
</Card>
<Card title="Recruitment" icon="user-group" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/recruitment">
Candidate sourcing and evaluation.
</Card>
<Card title="Browse all Crews" icon="users" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews">
See the full list of crew examples.
</Card>
</CardGroup>
## Flows
<CardGroup cols={3}>
<Card title="Content Creator Flow" icon="pen" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/content_creator_flow">
Multi‑crew content generation with routing.
</Card>
<Card title="Email Auto Responder" icon="envelope" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/email_auto_responder_flow">
Automated email monitoring and replies.
</Card>
<Card title="Lead Score Flow" icon="chart-line" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/lead_score_flow">
Lead qualification with human‑in‑the‑loop.
</Card>
<Card title="Meeting Assistant Flow" icon="calendar" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/meeting_assistant_flow">
Notes processing with integrations.
</Card>
<Card title="Self Evaluation Loop" icon="rotate" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/self_evaluation_loop_flow">
Iterative self‑improvement workflows.
</Card>
<Card title="Write a Book (Flows)" icon="book" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/write_a_book_with_flows">
Parallel chapter generation.
</Card>
<Card title="Browse all Flows" icon="diagram-project" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows">
See the full list of flow examples.
</Card>
</CardGroup>
## Integrations
<CardGroup cols={3}>
<Card title="CrewAI ↔ LangGraph" icon="link" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations/crewai-langgraph">
Integration with LangGraph framework.
</Card>
<Card title="Azure OpenAI" icon="cloud" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations/azure_model">
Using CrewAI with Azure OpenAI.
</Card>
<Card title="NVIDIA Models" icon="microchip" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations/nvidia_models">
NVIDIA ecosystem integrations.
</Card>
<Card title="Browse Integrations" icon="puzzle-piece" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations">
See all integration examples.
</Card>
</CardGroup>
## Notebooks
<CardGroup cols={2}>
<Card title="Simple QA Crew + Flow" icon="book" href="https://github.com/crewAIInc/crewAI-examples/tree/main/Notebooks/Simple%20QA%20Crew%20%2B%20Flow">
Simple QA Crew + Flow.
</Card>
<Card title="All Notebooks" icon="book" href="https://github.com/crewAIInc/crewAI-examples/tree/main/Notebooks">
Interactive examples for learning and experimentation.
</Card>
</CardGroup>

317
docs/v1.11.0/en/guides/advanced/customizing-prompts.mdx Normal file
View File

@@ -0,0 +1,317 @@
---
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
<Warning>
**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.
</Warning>
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
)
```
#### 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
<Tip>
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.
</Tip>
## 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:
### 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.
<Check>
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.
</Check>

134
docs/v1.11.0/en/guides/advanced/fingerprinting.mdx Normal file
View File

@@ -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 {}
```

453
docs/v1.11.0/en/guides/agents/crafting-effective-agents.mdx Normal file
View File

@@ -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.
<Check>
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.
</Check>
## 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

61
docs/v1.11.0/en/guides/coding-tools/agents-md.mdx Normal file
View File

@@ -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.

504
docs/v1.11.0/en/guides/concepts/evaluating-use-cases.mdx Normal file
View File

@@ -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:
<Frame caption="Complexity vs. Precision Matrix for CrewAI Applications">
<img src="/images/complexity_precision.png" alt="Complexity vs. Precision Matrix" />
</Frame>
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, 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()
```
### 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.
<Check>
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.
</Check>
## 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

396
docs/v1.11.0/en/guides/crews/first-crew.mdx Normal file
View File

@@ -0,0 +1,396 @@
---
title: Build Your First Crew
description: Step-by-step tutorial to create a collaborative AI team that works together to solve complex problems.
icon: users-gear
mode: "wide"
---
## Unleashing the Power of Collaborative AI
Imagine having a team of specialized AI agents working together seamlessly to solve complex problems, each contributing their unique skills to achieve a common goal. This is the power of CrewAI - a framework that enables you to create collaborative AI systems that can accomplish tasks far beyond what a single AI could achieve alone.
In this guide, we'll walk through creating a research crew that will help us research and analyze a topic, then create a comprehensive report. This practical example demonstrates how AI agents can collaborate to accomplish complex tasks, but it's just the beginning of what's possible with CrewAI.
### What You'll Build and Learn
By the end of this guide, you'll have:
1. **Created a specialized AI research team** with distinct roles and responsibilities
2. **Orchestrated collaboration** between multiple AI agents
3. **Automated a complex workflow** that involves gathering information, analysis, and report generation
4. **Built foundational skills** that you can apply to more ambitious projects
While we're building a simple research crew in this guide, the same patterns and techniques can be applied to create much more sophisticated teams for tasks like:
- Multi-stage content creation with specialized writers, editors, and fact-checkers
- Complex customer service systems with tiered support agents
- Autonomous business analysts that gather data, create visualizations, and generate insights
- Product development teams that ideate, design, and plan implementation
Let's get started building your first crew!
### 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 Project
First, let's create a new CrewAI project using the CLI. This command will set up a complete project structure with all the necessary files, allowing you to focus on defining your agents and their tasks rather than setting up boilerplate code.
```bash
crewai create crew research_crew
cd research_crew
```
This will generate a project with the basic structure needed for your crew. The CLI automatically creates:
- A project directory with the necessary files
- Configuration files for agents and tasks
- A basic crew implementation
- A main script to run the crew
<Frame caption="CrewAI Framework Overview">
<img src="/images/crews.png" alt="CrewAI Framework Overview" />
</Frame>
## Step 2: Explore the Project Structure
Let's take a moment to understand the project structure created by the CLI. CrewAI follows best practices for Python projects, making it easy to maintain and extend your code as your crews become more complex.
```
research_crew/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
└── research_crew/
├── __init__.py
├── main.py
├── crew.py
├── tools/
│ ├── custom_tool.py
│ └── __init__.py
└── config/
├── agents.yaml
└── tasks.yaml
```
This structure follows best practices for Python projects and makes it easy to organize your code. The separation of configuration files (in YAML) from implementation code (in Python) makes it easy to modify your crew's behavior without changing the underlying code.
## Step 3: Configure Your Agents
Now comes the fun part - defining your AI agents! In CrewAI, agents are specialized entities with specific roles, goals, and backstories that shape their behavior. Think of them as characters in a play, each with their own personality and purpose.
For our research crew, we'll create two agents:
1. A **researcher** who excels at finding and organizing information
2. An **analyst** who can interpret research findings and create insightful reports
Let's modify the `agents.yaml` file to define these specialized agents. Be sure
to set `llm` to the provider you are using.
```yaml
# src/research_crew/config/agents.yaml
researcher:
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 with a talent for
finding relevant information from various sources. You excel at
organizing information in a clear and structured manner, making
complex topics accessible to others.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
analyst:
role: >
Data Analyst and Report Writer for {topic}
goal: >
Analyze research findings and create a comprehensive, well-structured
report that presents insights in a clear and engaging way
backstory: >
You are a skilled analyst with a background in data interpretation
and technical writing. You have a talent for identifying patterns
and extracting meaningful insights from research data, then
communicating those insights effectively through well-crafted reports.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
Notice how each agent has a distinct role, goal, and backstory. These elements aren't just descriptive - they actively shape how the agent approaches its tasks. By crafting these carefully, you can create agents with specialized skills and perspectives that complement each other.
## Step 4: Define Your Tasks
With our agents defined, we now need to give them specific tasks to perform. Tasks in CrewAI represent the concrete work that agents will perform, with detailed instructions and expected outputs.
For our research crew, we'll define two main tasks:
1. A **research task** for gathering comprehensive information
2. An **analysis task** for creating an insightful report
Let's modify the `tasks.yaml` file:
```yaml
# src/research_crew/config/tasks.yaml
research_task:
description: >
Conduct thorough research on {topic}. Focus on:
1. Key concepts and definitions
2. Historical development and recent trends
3. Major challenges and opportunities
4. Notable applications or case studies
5. Future outlook and potential developments
Make sure to organize your findings in a structured format with clear sections.
expected_output: >
A comprehensive research document with well-organized sections covering
all the requested aspects of {topic}. Include specific facts, figures,
and examples where relevant.
agent: researcher
analysis_task:
description: >
Analyze the research findings and create a comprehensive report on {topic}.
Your report should:
1. Begin with an executive summary
2. Include all key information from the research
3. Provide insightful analysis of trends and patterns
4. Offer recommendations or future considerations
5. Be formatted in a professional, easy-to-read style with clear headings
expected_output: >
A polished, professional report on {topic} that presents the research
findings with added analysis and insights. The report should be well-structured
with an executive summary, main sections, and conclusion.
agent: analyst
context:
- research_task
output_file: output/report.md
```
Note the `context` field in the analysis task - this is a powerful feature that allows the analyst to access the output of the research task. This creates a workflow where information flows naturally between agents, just as it would in a human team.
## Step 5: Configure Your Crew
Now it's time to bring everything together by configuring our crew. The crew is the container that orchestrates how agents work together to complete tasks.
Let's modify the `crew.py` file:
```python
# src/research_crew/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ResearchCrew():
"""Research crew for comprehensive topic analysis and reporting"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def analyst(self) -> Agent:
return Agent(
config=self.agents_config['analyst'], # type: ignore[index]
verbose=True
)
@task
def research_task(self) -> Task:
return Task(
config=self.tasks_config['research_task'] # type: ignore[index]
)
@task
def analysis_task(self) -> Task:
return Task(
config=self.tasks_config['analysis_task'], # type: ignore[index]
output_file='output/report.md'
)
@crew
def crew(self) -> Crew:
"""Creates the research crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
In this code, we're:
1. Creating the researcher agent and equipping it with the SerperDevTool to search the web
2. Creating the analyst agent
3. Setting up the research and analysis tasks
4. Configuring the crew to run tasks sequentially (the analyst will wait for the researcher to finish)
This is where the magic happens - with just a few lines of code, we've defined a collaborative AI system where specialized agents work together in a coordinated process.
## Step 6: Set Up Your Main Script
Now, let's set up the main script that will run our crew. This is where we provide the specific topic we want our crew to research.
```python
#!/usr/bin/env python
# src/research_crew/main.py
import os
from research_crew.crew import ResearchCrew
# Create output directory if it doesn't exist
os.makedirs('output', exist_ok=True)
def run():
"""
Run the research crew.
"""
inputs = {
'topic': 'Artificial Intelligence in Healthcare'
}
# Create and run the crew
result = ResearchCrew().crew().kickoff(inputs=inputs)
# Print the result
print("\n\n=== FINAL REPORT ===\n\n")
print(result.raw)
print("\n\nReport has been saved to output/report.md")
if __name__ == "__main__":
run()
```
This script prepares the environment, specifies our research topic, and kicks off the crew's work. The power of CrewAI is evident in how simple this code is - all the complexity of managing multiple AI agents is handled by the framework.
## Step 7: Set Up Your Environment Variables
Create a `.env` file in your project root with your API keys:
```sh
SERPER_API_KEY=your_serper_api_key
# Add your provider's API key here too.
```
See the [LLM Setup guide](/en/concepts/llms#setting-up-your-llm) for details on configuring your provider of choice. You can get a Serper API key from [Serper.dev](https://serper.dev/).
## Step 8: Install Dependencies
Install the required dependencies using the CrewAI CLI:
```bash
crewai install
```
This command will:
1. Read the dependencies from your project configuration
2. Create a virtual environment if needed
3. Install all required packages
## Step 9: Run Your Crew
Now for the exciting moment - it's time to run your crew and see AI collaboration in action!
```bash
crewai run
```
When you run this command, you'll see your crew spring to life. The researcher will gather information about the specified topic, and the analyst will then create a comprehensive report based on that research. You'll see the agents' thought processes, actions, and outputs in real-time as they work together to complete their tasks.
## Step 10: Review the Output
Once the crew completes its work, you'll find the final report in the `output/report.md` file. The report will include:
1. An executive summary
2. Detailed information about the topic
3. Analysis and insights
4. Recommendations or future considerations
Take a moment to appreciate what you've accomplished - you've created a system where multiple AI agents collaborated on a complex task, each contributing their specialized skills to produce a result that's greater than what any single agent could achieve alone.
## Exploring Other CLI Commands
CrewAI offers several other useful CLI commands for working with crews:
```bash
# View all available commands
crewai --help
# Run the crew
crewai run
# Test the crew
crewai test
# Reset crew memories
crewai reset-memories
# Replay from a specific task
crewai replay -t <task_id>
```
## The Art of the Possible: Beyond Your First Crew
What you've built in this guide is just the beginning. The skills and patterns you've learned can be applied to create increasingly sophisticated AI systems. Here are some ways you could extend this basic research crew:
### Expanding Your Crew
You could add more specialized agents to your crew:
- A **fact-checker** to verify research findings
- A **data visualizer** to create charts and graphs
- A **domain expert** with specialized knowledge in a particular area
- A **critic** to identify weaknesses in the analysis
### Adding Tools and Capabilities
You could enhance your agents with additional tools:
- Web browsing tools for real-time research
- CSV/database tools for data analysis
- Code execution tools for data processing
- API connections to external services
### Creating More Complex Workflows
You could implement more sophisticated processes:
- Hierarchical processes where manager agents delegate to worker agents
- Iterative processes with feedback loops for refinement
- Parallel processes where multiple agents work simultaneously
- Dynamic processes that adapt based on intermediate results
### Applying to Different Domains
The same patterns can be applied to create crews for:
- **Content creation**: Writers, editors, fact-checkers, and designers working together
- **Customer service**: Triage agents, specialists, and quality control working together
- **Product development**: Researchers, designers, and planners collaborating
- **Data analysis**: Data collectors, analysts, and visualization specialists
## Next Steps
Now that you've built your first crew, you can:
1. Experiment with different agent configurations and personalities
2. Try more complex task structures and workflows
3. Implement custom tools to give your agents new capabilities
4. Apply your crew to different topics or problem domains
5. Explore [CrewAI Flows](/en/guides/flows/first-flow) for more advanced workflows with procedural programming
<Check>
Congratulations! You've successfully built your first CrewAI crew that can research and analyze any topic you provide. This foundational experience has equipped you with the skills to create increasingly sophisticated AI systems that can tackle complex, multi-stage problems through collaborative intelligence.
</Check>

623
docs/v1.11.0/en/guides/flows/first-flow.mdx Normal file
View File

@@ -0,0 +1,623 @@
---
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.
<Frame caption="CrewAI Framework Overview">
<img src="/images/flows.png" alt="CrewAI Framework Overview" />
</Frame>
## Step 2: Understanding the Project Structure
The generated project has the following structure. Take a moment to familiarize yourself with it, as understanding this structure will help you create more complex flows in the future.
```
guide_creator_flow/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
├── main.py
├── crews/
│ └── poem_crew/
│ ├── config/
│ │ ├── agents.yaml
│ │ └── tasks.yaml
│ └── poem_crew.py
└── tools/
└── custom_tool.py
```
This structure provides a clear separation between different components of your flow:
- The main flow logic in the `main.py` file
- Specialized crews in the `crews` directory
- Custom tools in the `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 modify the generated files for the content writer crew. We'll set up two specialized agents - a writer and a reviewer - that will collaborate to create high-quality content for our guide.
1. First, update the agents configuration file to define our content creation team:
Remember to set `llm` to the provider you are using.
```yaml
# src/guide_creator_flow/crews/content_crew/config/agents.yaml
content_writer:
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 with expertise in creating clear, engaging
content. You have a gift for explaining complex concepts in accessible language
and organizing information in a way that helps readers build their understanding.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
content_reviewer:
role: >
Educational Content Reviewer and Editor
goal: >
Ensure content is accurate, comprehensive, well-structured, and maintains
consistency with previously written sections
backstory: >
You are a meticulous editor with years of experience reviewing educational
content. You have an eye for detail, clarity, and coherence. You excel at
improving content while maintaining the original author's voice and ensuring
consistent quality across multiple sections.
llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude...
```
These agent definitions establish the specialized roles and perspectives that will shape how our AI agents approach content creation. Notice how each agent has a distinct purpose and expertise.
2. Next, update the tasks configuration file to define the specific writing and reviewing tasks:
```yaml
# src/guide_creator_flow/crews/content_crew/config/tasks.yaml
write_section_task:
description: >
Write a comprehensive section on the topic: "{section_title}"
Section description: {section_description}
Target audience: {audience_level} level learners
Your content should:
1. Begin with a brief introduction to the section topic
2. Explain all key concepts clearly with examples
3. Include practical applications or exercises where appropriate
4. End with a summary of key points
5. Be approximately 500-800 words in length
Format your content in Markdown with appropriate headings, lists, and emphasis.
Previously written sections:
{previous_sections}
Make sure your content maintains consistency with previously written sections
and builds upon concepts that have already been explained.
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
review_section_task:
description: >
Review and improve the following section on "{section_title}":
{draft_content}
Target audience: {audience_level} level learners
Previously written sections:
{previous_sections}
Your review should:
1. Fix any grammatical or spelling errors
2. Improve clarity and readability
3. Ensure content is comprehensive and accurate
4. Verify consistency with previously written sections
5. Enhance the structure and flow
6. Add any missing key information
Provide the improved version of the section in Markdown format.
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
```
These task definitions provide detailed instructions to our agents, ensuring they produce content that meets our quality standards. Note how the `context` parameter in the review task creates a workflow where the reviewer has access to the writer's output.
3. Now, update the crew implementation file to define how our agents and tasks work together:
```python
# src/guide_creator_flow/crews/content_crew/content_crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class ContentCrew():
"""Content writing crew"""
agents: List[BaseAgent]
tasks: List[Task]
@agent
def content_writer(self) -> Agent:
return Agent(
config=self.agents_config['content_writer'], # type: ignore[index]
verbose=True
)
@agent
def content_reviewer(self) -> Agent:
return Agent(
config=self.agents_config['content_reviewer'], # type: ignore[index]
verbose=True
)
@task
def write_section_task(self) -> Task:
return Task(
config=self.tasks_config['write_section_task'] # type: ignore[index]
)
@task
def review_section_task(self) -> Task:
return Task(
config=self.tasks_config['review_section_task'], # type: ignore[index]
context=[self.write_section_task()]
)
@crew
def crew(self) -> Crew:
"""Creates the content writing crew"""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
This crew definition establishes the relationship between our agents and tasks, setting up a sequential process where the content writer creates a draft and then the reviewer improves it. 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 ContentCrew
# 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 = ContentCrew().crew().kickoff(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 flow kickoff
```
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 = ContentCrew().crew().kickoff(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
<Check>
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.
</Check>

797
docs/v1.11.0/en/guides/flows/mastering-flow-state.mdx Normal file
View File

@@ -0,0 +1,797 @@
---
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
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 - state is automatically loaded
flow2 = PersistentCounterFlow()
result2 = flow2.kickoff()
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']}"
```
## 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.
<Check>
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.
</Check>
## 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

518
docs/v1.11.0/en/guides/migration/migrating-from-langgraph.mdx Normal file
View File

@@ -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.

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