mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-03 14:09:24 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
8
docs/edge/en/api-reference/inputs.mdx
Normal file
8
docs/edge/en/api-reference/inputs.mdx
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "GET /inputs"
|
||||
description: "Get required inputs for your crew"
|
||||
openapi: "/enterprise-api.en.yaml GET /inputs"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
|
||||
135
docs/edge/en/api-reference/introduction.mdx
Normal file
135
docs/edge/en/api-reference/introduction.mdx
Normal 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 /status/{kickoff_id}` 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 /status/{kickoff_id}` 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/edge/en/api-reference/kickoff.mdx
Normal file
8
docs/edge/en/api-reference/kickoff.mdx
Normal file
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: "POST /kickoff"
|
||||
description: "Start a crew execution"
|
||||
openapi: "/enterprise-api.en.yaml POST /kickoff"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
|
||||
6
docs/edge/en/api-reference/resume.mdx
Normal file
6
docs/edge/en/api-reference/resume.mdx
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "POST /resume"
|
||||
description: "Resume crew execution with human feedback"
|
||||
openapi: "/enterprise-api.en.yaml POST /resume"
|
||||
mode: "wide"
|
||||
---
|
||||
6
docs/edge/en/api-reference/status.mdx
Normal file
6
docs/edge/en/api-reference/status.mdx
Normal file
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "GET /status/{kickoff_id}"
|
||||
description: "Get execution status"
|
||||
openapi: "/enterprise-api.en.yaml GET /status/{kickoff_id}"
|
||||
mode: "wide"
|
||||
---
|
||||
4245
docs/edge/en/changelog.mdx
Normal file
4245
docs/edge/en/changelog.mdx
Normal file
File diff suppressed because it is too large
Load Diff
147
docs/edge/en/concepts/agent-capabilities.mdx
Normal file
147
docs/edge/en/concepts/agent-capabilities.mdx
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: "Agent Capabilities"
|
||||
description: "Understand the five ways to extend CrewAI agents: Tools, MCPs, Apps, Skills, and Knowledge."
|
||||
icon: puzzle-piece
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CrewAI agents can be extended with **five distinct capability types**, each serving a different purpose. Understanding when to use each one — and how they work together — is key to building effective agents.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Tools" icon="wrench" href="/en/concepts/tools" color="#3B82F6">
|
||||
**Callable functions** — give agents the ability to take action. Web searches, file operations, API calls, code execution.
|
||||
</Card>
|
||||
<Card title="MCP Servers" icon="plug" href="/en/mcp/overview" color="#8B5CF6">
|
||||
**Remote tool servers** — connect agents to external tool servers via the Model Context Protocol. Same effect as tools, but hosted externally.
|
||||
</Card>
|
||||
<Card title="Apps" icon="grid-2" color="#EC4899">
|
||||
**Platform integrations** — connect agents to SaaS apps (Gmail, Slack, Jira, Salesforce) via CrewAI's platform. Runs locally with a platform integration token.
|
||||
</Card>
|
||||
<Card title="Skills" icon="bolt" href="/en/concepts/skills" color="#F59E0B">
|
||||
**Domain expertise** — inject instructions, guidelines, and reference material into agent prompts. Skills tell agents *how to think*.
|
||||
</Card>
|
||||
<Card title="Knowledge" icon="book" href="/en/concepts/knowledge" color="#10B981">
|
||||
**Retrieved facts** — provide agents with data from documents, files, and URLs via semantic search (RAG). Knowledge gives agents *what to know*.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## The Key Distinction
|
||||
|
||||
The most important thing to understand: **these capabilities fall into two categories**.
|
||||
|
||||
### Action Capabilities (Tools, MCPs, Apps)
|
||||
|
||||
These give agents the ability to **do things** — call APIs, read files, search the web, send emails. At execution time, all three resolve into the same internal format (`BaseTool` instances) and appear in a unified tool list the agent can call.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, FileReadTool
|
||||
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Find and compile market data",
|
||||
backstory="Expert market analyst",
|
||||
tools=[SerperDevTool(), FileReadTool()], # Local tools
|
||||
mcps=["https://mcp.example.com/sse"], # Remote MCP server tools
|
||||
apps=["gmail", "google_sheets"], # Platform integrations
|
||||
)
|
||||
```
|
||||
|
||||
### Context Capabilities (Skills, Knowledge)
|
||||
|
||||
These modify the agent's **prompt** — injecting expertise, instructions, or retrieved data before the agent starts reasoning. They don't give agents new actions; they shape how agents think and what information they have access to.
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
|
||||
agent = Agent(
|
||||
role="Security Auditor",
|
||||
goal="Audit cloud infrastructure for vulnerabilities",
|
||||
backstory="Expert in cloud security with 10 years of experience",
|
||||
skills=["./skills/security-audit"], # Domain instructions
|
||||
knowledge_sources=[pdf_source, url_source], # Retrieved facts
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use What
|
||||
|
||||
| You need... | Use | Example |
|
||||
| :------------------------------------------------ | :---------------- | :--------------------------------------- |
|
||||
| Agent to search the web | **Tools** | `tools=[SerperDevTool()]` |
|
||||
| Agent to call a remote API via MCP | **MCPs** | `mcps=["https://api.example.com/sse"]` |
|
||||
| Agent to send emails via Gmail | **Apps** | `apps=["gmail"]` |
|
||||
| Agent to follow specific procedures | **Skills** | `skills=["./skills/code-review"]` |
|
||||
| Agent to reference company docs | **Knowledge** | `knowledge_sources=[pdf_source]` |
|
||||
| Agent to search the web AND follow review guidelines | **Tools + Skills** | Use both together |
|
||||
|
||||
---
|
||||
|
||||
## Combining Capabilities
|
||||
|
||||
In practice, agents often use **multiple capability types together**. Here's a realistic example:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
|
||||
|
||||
# A fully-equipped research agent
|
||||
researcher = Agent(
|
||||
role="Senior Research Analyst",
|
||||
goal="Produce comprehensive market analysis reports",
|
||||
backstory="Expert analyst with deep industry knowledge",
|
||||
|
||||
# ACTION: What the agent can DO
|
||||
tools=[
|
||||
SerperDevTool(), # Search the web
|
||||
FileReadTool(), # Read local files
|
||||
CodeInterpreterTool(), # Run Python code for analysis
|
||||
],
|
||||
mcps=["https://data-api.example.com/sse"], # Access remote data API
|
||||
apps=["google_sheets"], # Write to Google Sheets
|
||||
|
||||
# CONTEXT: What the agent KNOWS
|
||||
skills=["./skills/research-methodology"], # How to conduct research
|
||||
knowledge_sources=[company_docs], # Company-specific data
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison Table
|
||||
|
||||
| Feature | Tools | MCPs | Apps | Skills | Knowledge |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: |
|
||||
| **Gives agent actions** | ✅ | ✅ | ✅ | ❌ | ❌ |
|
||||
| **Modifies prompt** | ❌ | ❌ | ❌ | ✅ | ✅ |
|
||||
| **Requires code** | Yes | Config only | Config only | Markdown only | Config only |
|
||||
| **Runs locally** | Yes | Depends | Yes (with env var) | N/A | Yes |
|
||||
| **Needs API keys** | Per tool | Per server | Integration token | No | Embedder only |
|
||||
| **Set on Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` |
|
||||
| **Set on Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` |
|
||||
|
||||
---
|
||||
|
||||
## Deep Dives
|
||||
|
||||
Ready to learn more about each capability type?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Tools" icon="wrench" href="/en/concepts/tools">
|
||||
Create custom tools, use the 75+ OSS catalog, configure caching and async execution.
|
||||
</Card>
|
||||
<Card title="MCP Integration" icon="plug" href="/en/mcp/overview">
|
||||
Connect to MCP servers via stdio, SSE, or HTTP. Filter tools, configure auth.
|
||||
</Card>
|
||||
<Card title="Skills" icon="bolt" href="/en/concepts/skills">
|
||||
Build skill packages with SKILL.md, inject domain expertise, use progressive disclosure.
|
||||
</Card>
|
||||
<Card title="Knowledge" icon="book" href="/en/concepts/knowledge">
|
||||
Add knowledge from PDFs, CSVs, URLs, and more. Configure embedders and retrieval.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
720
docs/edge/en/concepts/agents.mdx
Normal file
720
docs/edge/en/concepts/agents.mdx
Normal file
@@ -0,0 +1,720 @@
|
||||
---
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 common ways to create agents in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**.
|
||||
|
||||
### JSONC Configuration (Recommended)
|
||||
|
||||
New projects created with `crewai create crew <name>` use JSON-first configuration. Each agent is defined in `agents/<agent_name>.jsonc`, and `crew.jsonc` lists which agents are part of the crew.
|
||||
|
||||
After creating your CrewAI project as outlined in the [Installation](/en/installation) section, edit the generated files in `agents/`.
|
||||
|
||||
<Note>
|
||||
Use `{placeholder}` values in `role`, `goal`, or `backstory`. Put defaults in `crew.jsonc` under `inputs`; `crewai run` prompts for any missing values.
|
||||
</Note>
|
||||
|
||||
Here's an example `agents/researcher.jsonc` file:
|
||||
|
||||
```jsonc agents/researcher.jsonc
|
||||
{
|
||||
"role": "{topic} Senior Data Researcher",
|
||||
"goal": "Uncover cutting-edge developments in {topic}",
|
||||
"backstory": "You find the most relevant information and present it clearly.",
|
||||
"llm": "openai/gpt-4o",
|
||||
"tools": ["SerperDevTool"],
|
||||
"settings": {
|
||||
"verbose": true,
|
||||
"allow_delegation": false,
|
||||
"max_iter": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then include that agent from `crew.jsonc`:
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Research Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research_task",
|
||||
"description": "Research {topic}",
|
||||
"expected_output": "A concise briefing about {topic}",
|
||||
"agent": "researcher"
|
||||
}
|
||||
],
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Agent files support any public `Agent` field. Common fields include `role`, `goal`, `backstory`, `llm`, `tools`, `function_calling_llm`, `guardrail`, `step_callback`, and `settings`. Behavior options such as `verbose`, `allow_delegation`, `max_iter`, `max_rpm`, `memory`, `cache`, `planning_config`, and `use_system_prompt` can be placed at the top level or under `settings`; values in `settings` take precedence.
|
||||
|
||||
<Note>
|
||||
JSONC supports comments and trailing commas. If both `agents/<name>.jsonc` and `agents/<name>.json` exist, CrewAI uses the JSONC file.
|
||||
</Note>
|
||||
|
||||
### Classic YAML Configuration
|
||||
|
||||
Classic projects created with `crewai create crew <name> --classic` use `config/agents.yaml` and a `@CrewBase` class in `crew.py`. This remains supported for teams that want Python decorators or existing YAML projects.
|
||||
|
||||
### 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
|
||||
|
||||
<Warning>
|
||||
`allow_code_execution` and `code_execution_mode` are deprecated. `CodeInterpreterTool` has been removed from `crewai-tools`. Use a dedicated sandbox service such as [E2B](https://e2b.dev) or [Modal](https://modal.com) for secure code execution.
|
||||
</Warning>
|
||||
|
||||
- `allow_code_execution` _(deprecated)_: Previously enabled built-in code execution via `CodeInterpreterTool`.
|
||||
- `code_execution_mode` _(deprecated)_: Previously controlled execution mode (`"safe"` for Docker, `"unsafe"` for direct execution).
|
||||
|
||||
#### 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
|
||||
|
||||
<Warning>
|
||||
`allow_code_execution` and `code_execution_mode` are deprecated and `CodeInterpreterTool` has been removed. Use a dedicated sandbox service such as [E2B](https://e2b.dev) or [Modal](https://modal.com) for secure code execution.
|
||||
</Warning>
|
||||
|
||||
### 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.
|
||||
423
docs/edge/en/concepts/checkpointing.mdx
Normal file
423
docs/edge/en/concepts/checkpointing.mdx
Normal file
@@ -0,0 +1,423 @@
|
||||
---
|
||||
title: Checkpointing
|
||||
description: Automatically save execution state so crews, flows, and agents can resume after failures.
|
||||
icon: floppy-disk
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Checkpointing saves a snapshot of execution state during a run so a crew, flow, or agent can resume after a failure or be forked into an alternate branch.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Explanation" icon="lightbulb" href="#explanation">
|
||||
How checkpointing works: events, storage, and inheritance.
|
||||
</Card>
|
||||
<Card title="Tutorial" icon="graduation-cap" href="#tutorial-resume-a-failing-crew">
|
||||
A 5-minute walkthrough: run, interrupt, resume.
|
||||
</Card>
|
||||
<Card title="How-to guides" icon="screwdriver-wrench" href="#how-to-guides">
|
||||
Task-focused recipes for common workflows.
|
||||
</Card>
|
||||
<Card title="Reference" icon="book" href="#reference">
|
||||
`CheckpointConfig`, events, providers, and CLI.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Explanation
|
||||
|
||||
### What a checkpoint is
|
||||
|
||||
A checkpoint captures everything CrewAI needs to recreate a run mid-flight: the full state of the crew, flow, or agent — configuration, agent memory and knowledge sources, task progress, intermediate outputs, internal state and attributes — alongside the kickoff inputs, the event history up to that point, and a lineage ID that ties the checkpoint to the run it came from.
|
||||
|
||||
Restoring rebuilds that state and continues. Completed tasks are skipped, memory and knowledge are rehydrated, and downstream work runs against the same outputs the original run produced. Forking does the same restore under a new lineage, so the new branch and the original run can write checkpoints side by side without overwriting each other.
|
||||
|
||||
### When checkpoints are written
|
||||
|
||||
Checkpointing is event-driven. The runtime subscribes to events you select via `on_events` and writes a checkpoint each time one fires. The default `task_completed` produces one checkpoint per finished task — a sensible tradeoff between granularity and disk use. Higher-frequency events like `llm_call_completed` are available for fine-grained recovery but write far more files.
|
||||
|
||||
### Storage
|
||||
|
||||
Two providers ship with CrewAI:
|
||||
|
||||
- `JsonProvider` writes one file per checkpoint. Human-readable and easy to inspect.
|
||||
- `SqliteProvider` writes to a single SQLite database. Better for high-frequency checkpointing.
|
||||
|
||||
Both prune oldest checkpoints when `max_checkpoints` is set.
|
||||
|
||||
<Note>
|
||||
Auto-checkpoint writes (event-driven) are best-effort: a failed write is logged and the run continues. Manual `state.checkpoint()` and `state.acheckpoint()` calls re-raise on failure.
|
||||
</Note>
|
||||
|
||||
### Inheritance model
|
||||
|
||||
`Crew`, `Flow`, and `Agent` all accept a `checkpoint` argument. Children inherit from their parent unless they set their own value or pass `False` to opt out. Enable checkpointing once on the crew and every agent participates, or selectively exclude one agent.
|
||||
|
||||
## Tutorial: Resume a failing crew
|
||||
|
||||
This walkthrough takes ~5 minutes. You will run a two-task crew, kill it midway, and resume from the saved checkpoint.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the crew with checkpointing enabled">
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
|
||||
researcher = Agent(role="Researcher", goal="Research", backstory="Expert")
|
||||
writer = Agent(role="Writer", goal="Write", backstory="Expert")
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[
|
||||
Task(description="Research AI trends", agent=researcher, expected_output="bullets"),
|
||||
Task(description="Write a summary", agent=writer, expected_output="paragraph"),
|
||||
],
|
||||
checkpoint=True,
|
||||
)
|
||||
```
|
||||
</Step>
|
||||
<Step title="Run it and interrupt after the first task">
|
||||
```python
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
Press `Ctrl+C` after the first task finishes. Look in `./.checkpoints/` — a file named `<timestamp>_<uuid>.json` is the checkpoint.
|
||||
</Step>
|
||||
<Step title="Resume from the checkpoint">
|
||||
```python
|
||||
from crewai import CheckpointConfig
|
||||
|
||||
result = crew.kickoff(
|
||||
from_checkpoint=CheckpointConfig(
|
||||
restore_from="./.checkpoints/<timestamp>_<uuid>.json",
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
The research task is skipped, the writer runs against the saved research output, and the crew finishes.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## How-to guides
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Enable checkpointing with defaults" icon="play">
|
||||
```python
|
||||
crew = Crew(agents=[...], tasks=[...], checkpoint=True)
|
||||
```
|
||||
|
||||
Writes to `./.checkpoints/` on every `task_completed`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Customize storage and frequency" icon="sliders">
|
||||
```python
|
||||
from crewai import Crew, CheckpointConfig
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./my_checkpoints",
|
||||
on_events=["task_completed", "crew_kickoff_completed"],
|
||||
max_checkpoints=5,
|
||||
),
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Choose a storage provider" icon="database">
|
||||
<CodeGroup>
|
||||
```python JsonProvider
|
||||
from crewai import Crew, CheckpointConfig
|
||||
from crewai.state import JsonProvider
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./my_checkpoints",
|
||||
provider=JsonProvider(),
|
||||
max_checkpoints=5,
|
||||
),
|
||||
)
|
||||
```
|
||||
```python SqliteProvider
|
||||
from crewai import Crew, CheckpointConfig
|
||||
from crewai.state import SqliteProvider
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./.checkpoints.db",
|
||||
provider=SqliteProvider(),
|
||||
max_checkpoints=50,
|
||||
),
|
||||
)
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
<Tip>
|
||||
SQLite enables WAL journal mode for concurrent reads. Prefer it for high-frequency checkpointing.
|
||||
</Tip>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Opt one agent out" icon="user-slash">
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[
|
||||
Agent(role="Researcher", ...),
|
||||
Agent(role="Writer", ..., checkpoint=False),
|
||||
],
|
||||
tasks=[...],
|
||||
checkpoint=True,
|
||||
)
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Fork into a new branch" icon="code-branch">
|
||||
`fork()` restores a checkpoint under a fresh lineage so the new run does not collide with the original.
|
||||
|
||||
```python
|
||||
config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
|
||||
crew = Crew.fork(config, branch="experiment-a")
|
||||
result = crew.kickoff(inputs={"strategy": "aggressive"})
|
||||
```
|
||||
|
||||
The `branch` label is optional; one is generated if omitted.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Checkpoint a Crew, Flow, or Agent" icon="cubes">
|
||||
<Tabs>
|
||||
<Tab title="Crew">
|
||||
```python
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, write_task, review_task],
|
||||
checkpoint=CheckpointConfig(location="./crew_cp"),
|
||||
)
|
||||
```
|
||||
|
||||
Default trigger: `task_completed`.
|
||||
</Tab>
|
||||
<Tab title="Flow">
|
||||
```python
|
||||
from crewai.flow.flow import Flow, start, listen
|
||||
from crewai import CheckpointConfig
|
||||
|
||||
class MyFlow(Flow):
|
||||
@start()
|
||||
def step_one(self):
|
||||
return "data"
|
||||
|
||||
@listen(step_one)
|
||||
def step_two(self, data):
|
||||
return process(data)
|
||||
|
||||
flow = MyFlow(
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./flow_cp",
|
||||
on_events=["method_execution_finished"],
|
||||
),
|
||||
)
|
||||
result = flow.kickoff()
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Agent">
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Research topics",
|
||||
backstory="Expert researcher",
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./agent_cp",
|
||||
on_events=["lite_agent_execution_completed"],
|
||||
),
|
||||
)
|
||||
result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}])
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Write a checkpoint manually" icon="code">
|
||||
Register a handler on any event and call `state.checkpoint()`.
|
||||
|
||||
<CodeGroup>
|
||||
```python Sync
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from crewai.events.event_bus import crewai_event_bus
|
||||
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from crewai.state.runtime import RuntimeState
|
||||
|
||||
|
||||
@crewai_event_bus.on(LLMCallCompletedEvent)
|
||||
def on_llm_done(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
|
||||
path = state.checkpoint("./my_checkpoints")
|
||||
print(f"Saved checkpoint: {path}")
|
||||
```
|
||||
```python Async
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from crewai.events.event_bus import crewai_event_bus
|
||||
from crewai.events.types.llm_events import LLMCallCompletedEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from crewai.state.runtime import RuntimeState
|
||||
|
||||
|
||||
@crewai_event_bus.on(LLMCallCompletedEvent)
|
||||
async def on_llm_done_async(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
|
||||
path = await state.acheckpoint("./my_checkpoints")
|
||||
print(f"Saved checkpoint: {path}")
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
A `state` argument is supplied automatically when the handler takes three parameters. See [Event Listeners](/en/concepts/event-listener) for the full event catalog.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Browse, resume, and fork from the CLI" icon="terminal">
|
||||
```bash
|
||||
crewai checkpoint
|
||||
crewai checkpoint --location ./my_checkpoints
|
||||
crewai checkpoint --location ./.checkpoints.db
|
||||
```
|
||||
|
||||
<Frame caption="Checkpoint tree — branches and forks nest under their parent.">
|
||||
<img src="/images/checkpoint-tui-tree.png" alt="Checkpoint TUI tree view" />
|
||||
</Frame>
|
||||
|
||||
The left panel groups checkpoints by branch; forks nest under their parent. Selecting a checkpoint opens the detail panel with metadata, entity state, and task progress. **Resume** continues the run; **Fork** starts a new branch.
|
||||
|
||||
<Frame caption="Overview tab — metadata, entity state, and run summary.">
|
||||
<img src="/images/checkpoint-tui-detail-overview.png" alt="Checkpoint detail overview tab" />
|
||||
</Frame>
|
||||
|
||||
The detail panel exposes two editable areas:
|
||||
|
||||
- **Inputs** — original kickoff inputs, pre-filled and editable.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/checkpoint-tui-detail-inputs.png" alt="Editable kickoff inputs" />
|
||||
</Frame>
|
||||
|
||||
- **Task outputs** — outputs of completed tasks. Editing an output and hitting **Fork** invalidates downstream tasks so they re-run against the modified context.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/checkpoint-tui-detail-tasks.png" alt="Editable task outputs" />
|
||||
</Frame>
|
||||
|
||||
<Frame caption="Fork view — confirm a new branch from the selected checkpoint.">
|
||||
<img src="/images/checkpoint-tui-details-fork.png" alt="Fork confirmation panel" />
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
Useful for "what if" exploration: fork, tweak, observe.
|
||||
</Tip>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Inspect checkpoints without the TUI" icon="magnifying-glass">
|
||||
```bash
|
||||
crewai checkpoint list ./my_checkpoints
|
||||
crewai checkpoint info ./my_checkpoints/<file>.json
|
||||
crewai checkpoint info ./.checkpoints.db
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Reference
|
||||
|
||||
### `CheckpointConfig`
|
||||
|
||||
<ParamField path="location" type="str" default='"./.checkpoints"'>
|
||||
Storage destination. A directory for `JsonProvider`, a database file path for `SqliteProvider`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="on_events" type='list[CheckpointEventType | Literal["*"]]' default='["task_completed"]'>
|
||||
Event types that trigger a checkpoint. `CheckpointEventType` is a `Literal` — your type checker will autocomplete and reject unsupported values. See [event types](#event-types) for the full list.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="provider" type="BaseProvider" default="JsonProvider()">
|
||||
Storage backend. Either `JsonProvider` or `SqliteProvider`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="max_checkpoints" type="int | None" default="None">
|
||||
Maximum checkpoints to retain. Oldest are pruned after each write.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="restore_from" type="Path | str | None" default="None">
|
||||
Checkpoint to restore from when passed via `from_checkpoint`.
|
||||
</ParamField>
|
||||
|
||||
### `checkpoint` field values
|
||||
|
||||
Accepted by `Crew`, `Flow`, and `Agent`.
|
||||
|
||||
<ParamField path="None" type="default">
|
||||
Inherit from parent.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="True" type="bool">
|
||||
Enable with defaults.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="False" type="bool">
|
||||
Explicit opt-out. Stops inheritance.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="CheckpointConfig(...)" type="CheckpointConfig">
|
||||
Custom configuration.
|
||||
</ParamField>
|
||||
|
||||
### Event types
|
||||
|
||||
`on_events` accepts any combination of `CheckpointEventType` values. The default `["task_completed"]` writes one checkpoint per finished task; `["*"]` matches every event.
|
||||
|
||||
<Warning>
|
||||
`["*"]` and high-frequency events like `llm_call_completed` write many checkpoints and can degrade performance. Pair them with `max_checkpoints`.
|
||||
</Warning>
|
||||
|
||||
<Expandable title="All supported events">
|
||||
|
||||
- **Task** — `task_started`, `task_completed`, `task_failed`, `task_evaluation`
|
||||
- **Crew** — `crew_kickoff_started`, `crew_kickoff_completed`, `crew_kickoff_failed`, `crew_train_started`, `crew_train_completed`, `crew_train_failed`, `crew_test_started`, `crew_test_completed`, `crew_test_failed`, `crew_test_result`
|
||||
- **Agent** — `agent_execution_started`, `agent_execution_completed`, `agent_execution_error`, `lite_agent_execution_started`, `lite_agent_execution_completed`, `lite_agent_execution_error`, `agent_evaluation_started`, `agent_evaluation_completed`, `agent_evaluation_failed`
|
||||
- **Flow** — `flow_created`, `flow_started`, `flow_finished`, `flow_paused`, `method_execution_started`, `method_execution_finished`, `method_execution_failed`, `method_execution_paused`, `human_feedback_requested`, `human_feedback_received`, `flow_input_requested`, `flow_input_received`
|
||||
- **LLM** — `llm_call_started`, `llm_call_completed`, `llm_call_failed`, `llm_stream_chunk`, `llm_thinking_chunk`
|
||||
- **LLM Guardrail** — `llm_guardrail_started`, `llm_guardrail_completed`, `llm_guardrail_failed`
|
||||
- **Tool** — `tool_usage_started`, `tool_usage_finished`, `tool_usage_error`, `tool_validate_input_error`, `tool_selection_error`, `tool_execution_error`
|
||||
- **Memory** — `memory_save_started`, `memory_save_completed`, `memory_save_failed`, `memory_query_started`, `memory_query_completed`, `memory_query_failed`, `memory_retrieval_started`, `memory_retrieval_completed`, `memory_retrieval_failed`
|
||||
- **Knowledge** — `knowledge_search_query_started`, `knowledge_search_query_completed`, `knowledge_query_started`, `knowledge_query_completed`, `knowledge_query_failed`, `knowledge_search_query_failed`
|
||||
- **Reasoning** — `agent_reasoning_started`, `agent_reasoning_completed`, `agent_reasoning_failed`
|
||||
- **MCP** — `mcp_connection_started`, `mcp_connection_completed`, `mcp_connection_failed`, `mcp_tool_execution_started`, `mcp_tool_execution_completed`, `mcp_tool_execution_failed`, `mcp_config_fetch_failed`
|
||||
- **Observation** — `step_observation_started`, `step_observation_completed`, `step_observation_failed`, `plan_refinement`, `plan_replan_triggered`, `goal_achieved_early`
|
||||
- **Skill** — `skill_discovery_started`, `skill_discovery_completed`, `skill_loaded`, `skill_activated`, `skill_load_failed`
|
||||
- **Logging** — `agent_logs_started`, `agent_logs_execution`
|
||||
- **A2A** — `a2a_delegation_started`, `a2a_delegation_completed`, `a2a_conversation_started`, `a2a_conversation_completed`, `a2a_message_sent`, `a2a_response_received`, `a2a_polling_started`, `a2a_polling_status`, `a2a_push_notification_registered`, `a2a_push_notification_received`, `a2a_push_notification_sent`, `a2a_push_notification_timeout`, `a2a_streaming_started`, `a2a_streaming_chunk`, `a2a_agent_card_fetched`, `a2a_authentication_failed`, `a2a_artifact_received`, `a2a_connection_error`, `a2a_server_task_started`, `a2a_server_task_completed`, `a2a_server_task_canceled`, `a2a_server_task_failed`, `a2a_parallel_delegation_started`, `a2a_parallel_delegation_completed`, `a2a_transport_negotiated`, `a2a_content_type_negotiated`, `a2a_context_created`, `a2a_context_expired`, `a2a_context_idle`, `a2a_context_completed`, `a2a_context_pruned`
|
||||
- **System signals** — `SIGTERM`, `SIGINT`, `SIGHUP`, `SIGTSTP`, `SIGCONT`
|
||||
- **Wildcard** — `"*"` matches every event.
|
||||
|
||||
</Expandable>
|
||||
|
||||
### Storage providers
|
||||
|
||||
<ParamField path="JsonProvider" type="provider">
|
||||
One file per checkpoint, named `<timestamp>_<uuid>.json` inside `location`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="SqliteProvider" type="provider">
|
||||
Single database file at `location` with WAL journaling.
|
||||
</ParamField>
|
||||
|
||||
### CLI
|
||||
|
||||
| Command | Purpose |
|
||||
|:--------|:--------|
|
||||
| `crewai checkpoint` | Launch the TUI; auto-detect storage. |
|
||||
| `crewai checkpoint --location <path>` | Launch the TUI against a specific location. |
|
||||
| `crewai checkpoint list <path>` | List checkpoints. |
|
||||
| `crewai checkpoint info <path>` | Inspect a checkpoint file or the latest entry in a SQLite database. |
|
||||
556
docs/edge/en/concepts/cli.mdx
Normal file
556
docs/edge/en/concepts/cli.mdx
Normal file
@@ -0,0 +1,556 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
By default, `crewai create crew` creates a JSON-first crew project with `crew.jsonc` and `agents/*.jsonc`. Use `crewai create crew my_new_crew --classic` only when you want the older Python/YAML scaffold with `crew.py`, `config/agents.yaml`, and `config/tasks.yaml`.
|
||||
|
||||
### 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 definition to enable this command.
|
||||
|
||||
For JSON-first crews, add it to `crew.jsonc`:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "My Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [],
|
||||
"chat_llm": "openai/gpt-4o"
|
||||
}
|
||||
```
|
||||
|
||||
For classic Python/YAML crews, set it in `crew.py`:
|
||||
|
||||
```python
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
chat_llm="gpt-4o", # LLM 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 the `crewai create crew` command, the CLI shows a list of available LLM providers, followed by model selection for your chosen provider. The selected model is saved in the generated `.env` file and each generated agent JSONC file can set its own `llm`.
|
||||
|
||||
Once you've selected an LLM provider and model, you will be prompted for API keys.
|
||||
|
||||
#### Available LLM Providers
|
||||
|
||||
Here's a list of the most popular LLM providers suggested by the CLI:
|
||||
|
||||
- OpenAI
|
||||
- Groq
|
||||
- Anthropic
|
||||
- Google Gemini
|
||||
- SambaNova
|
||||
|
||||
When you select a provider, the CLI will then show you available models for that provider and prompt you to enter your API key.
|
||||
|
||||
#### Other Options
|
||||
|
||||
If you select "other", you will be able to select from a list of LiteLLM supported providers.
|
||||
|
||||
When you select a provider, the CLI will prompt you to enter the Key name and the API key.
|
||||
|
||||
See the following link for each provider's key name:
|
||||
|
||||
- [LiteLLM Providers](https://docs.litellm.ai/docs/providers)
|
||||
|
||||
### 13. Configuration Management
|
||||
|
||||
Manage CLI configuration settings for CrewAI.
|
||||
|
||||
```shell Terminal
|
||||
crewai config [COMMAND] [OPTIONS]
|
||||
```
|
||||
|
||||
#### Commands:
|
||||
|
||||
- `list`: Display all CLI configuration parameters
|
||||
|
||||
```shell Terminal
|
||||
crewai config list
|
||||
```
|
||||
|
||||
- `set`: Set a CLI configuration parameter
|
||||
|
||||
```shell Terminal
|
||||
crewai config set <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/edge/en/concepts/collaboration.mdx
Normal file
363
docs/edge/en/concepts/collaboration.mdx
Normal 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.
|
||||
458
docs/edge/en/concepts/crews.mdx
Normal file
458
docs/edge/en/concepts/crews.mdx
Normal file
@@ -0,0 +1,458 @@
|
||||
---
|
||||
title: Crews
|
||||
description: Understanding and utilizing crews in the crewAI framework with comprehensive attributes and functionalities.
|
||||
icon: people-group
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
A crew in crewAI represents a collaborative group of agents working together to achieve a set of tasks. Each crew defines the strategy for task execution, agent collaboration, and the overall workflow.
|
||||
|
||||
## Crew Attributes
|
||||
|
||||
| Attribute | Parameters | Description |
|
||||
| :------------------------------------ | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Tasks** | `tasks` | A list of tasks assigned to the crew. |
|
||||
| **Agents** | `agents` | A list of agents that are part of the crew. |
|
||||
| **Process** _(optional)_ | `process` | The process flow (e.g., sequential, hierarchical) the crew follows. Default is `sequential`. |
|
||||
| **Verbose** _(optional)_ | `verbose` | The verbosity level for logging during execution. Defaults to `False`. |
|
||||
| **Manager LLM** _(optional)_ | `manager_llm` | The language model used by the manager agent in a hierarchical process. **Required when using a hierarchical process.** |
|
||||
| **Function Calling LLM** _(optional)_ | `function_calling_llm` | If passed, the crew will use this LLM to do function calling for tools for all agents in the crew. Each agent can have its own LLM, which overrides the crew's LLM for function calling. |
|
||||
| **Config** _(optional)_ | `config` | Optional configuration settings for the crew, in `Json` or `Dict[str, Any]` format. |
|
||||
| **Max RPM** _(optional)_ | `max_rpm` | Maximum requests per minute the crew adheres to during execution. Defaults to `None`. |
|
||||
| **Memory** _(optional)_ | `memory` | Utilized for storing execution memories (short-term, long-term, entity memory). | |
|
||||
| **Cache** _(optional)_ | `cache` | Specifies whether to use a cache for storing the results of tools' execution. Defaults to `True`. |
|
||||
| **Embedder** _(optional)_ | `embedder` | Configuration for the embedder to be used by the crew. Mostly used by memory for now. Default is `{"provider": "openai"}`. |
|
||||
| **Step Callback** _(optional)_ | `step_callback` | A function that is called after each step of every agent. This can be used to log the agent's actions or to perform other operations; it won't override the agent-specific `step_callback`. |
|
||||
| **Task Callback** _(optional)_ | `task_callback` | A function that is called after the completion of each task. Useful for monitoring or additional operations post-task execution. |
|
||||
| **Share Crew** _(optional)_ | `share_crew` | Whether you want to share the complete crew information and execution with the crewAI team to make the library better, and allow us to train models. |
|
||||
| **Output Log File** _(optional)_ | `output_log_file` | Set to True to save logs as logs.txt in the current directory or provide a file path. Logs will be in JSON format if the filename ends in .json, otherwise .txt. Defaults to `None`. |
|
||||
| **Manager Agent** _(optional)_ | `manager_agent` | `manager` sets a custom agent that will be used as a manager. |
|
||||
| **Prompt File** _(optional)_ | `prompt_file` | Path to the prompt JSON file to be used for the crew. |
|
||||
| **Planning** *(optional)* | `planning` | Adds planning ability to the Crew. When activated before each Crew iteration, all Crew data is sent to an AgentPlanner that will plan the tasks and this plan will be added to each task description. |
|
||||
| **Planning LLM** *(optional)* | `planning_llm` | The language model used by the AgentPlanner in a planning process. |
|
||||
| **Knowledge Sources** _(optional)_ | `knowledge_sources` | Knowledge sources available at the crew level, accessible to all the agents. |
|
||||
| **Stream** _(optional)_ | `stream` | Enable streaming output to receive real-time updates during crew execution. Returns a `CrewStreamingOutput` object that can be iterated for chunks. Defaults to `False`. |
|
||||
| **Chat LLM** _(optional)_ | `chat_llm` | The language model used to orchestrate `crewai chat` CLI interactions with the crew. Accepts a model name string or `LLM` instance. Defaults to `None`. |
|
||||
| **Before Kickoff Callbacks** _(optional)_ | `before_kickoff_callbacks` | A list of callable functions executed **before** the crew starts. Each callback receives and can modify the inputs dict. Distinct from the `@before_kickoff` decorator. Defaults to `[]`. |
|
||||
| **After Kickoff Callbacks** _(optional)_ | `after_kickoff_callbacks` | A list of callable functions executed **after** the crew finishes. Each callback receives and can modify the `CrewOutput`. Distinct from the `@after_kickoff` decorator. Defaults to `[]`. |
|
||||
| **Tracing** _(optional)_ | `tracing` | Controls OpenTelemetry tracing for the crew. `True` = always enable, `False` = always disable, `None` = inherit from environment / user settings. Defaults to `None`. |
|
||||
| **Skills** _(optional)_ | `skills` | A list of `Path` objects (skill search directories) or pre-loaded `Skill` objects applied to all agents in the crew. Defaults to `None`. |
|
||||
| **Security Config** _(optional)_ | `security_config` | A `SecurityConfig` instance managing crew fingerprinting and identity. Defaults to `SecurityConfig()`. |
|
||||
| **Checkpoint** _(optional)_ | `checkpoint` | Enables automatic checkpointing. Pass `True` for sensible defaults, a `CheckpointConfig` for full control, `False` to opt out, or `None` to inherit. See the [Checkpointing](#checkpointing) section below. Defaults to `None`. |
|
||||
|
||||
<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 common ways to create crews in CrewAI: using **JSONC project configuration (recommended for new crews)** or defining them **directly in code**.
|
||||
|
||||
### JSONC Configuration (Recommended)
|
||||
|
||||
New projects created with `crewai create crew <name>` use `crew.jsonc` for crew-level settings and tasks, plus one file per agent in `agents/`.
|
||||
|
||||
`crewai run` automatically detects `crew.jsonc` or `crew.json`, loads the referenced agents, prompts for missing placeholders, and kicks off the crew.
|
||||
|
||||
#### Example `crew.jsonc`
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Market Research Crew",
|
||||
"agents": ["researcher", "analyst"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research",
|
||||
"description": "Research {topic} and collect the most relevant facts.",
|
||||
"expected_output": "Structured research notes about {topic}.",
|
||||
"agent": "researcher"
|
||||
},
|
||||
{
|
||||
"name": "analysis",
|
||||
"description": "Analyze the research and write a concise report.",
|
||||
"expected_output": "A markdown report with findings and recommendations.",
|
||||
"agent": "analyst",
|
||||
"context": ["research"],
|
||||
"output_file": "output/report.md"
|
||||
}
|
||||
],
|
||||
"process": "sequential",
|
||||
"verbose": true,
|
||||
"memory": true,
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Each string in `agents` resolves to `agents/<name>.jsonc` first, then `agents/<name>.json`.
|
||||
|
||||
```jsonc agents/researcher.jsonc
|
||||
{
|
||||
"role": "{topic} Senior Researcher",
|
||||
"goal": "Find accurate and current information about {topic}.",
|
||||
"backstory": "You are a careful researcher who cites clear evidence.",
|
||||
"llm": "openai/gpt-4o",
|
||||
"tools": ["SerperDevTool"]
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Tasks run in the order they appear in `tasks` when `process` is `"sequential"`.
|
||||
</Note>
|
||||
|
||||
For hierarchical crews, set `"process": "hierarchical"` and provide either `manager_llm` or `manager_agent`. A `manager_agent` can reference an `agents/<name>.jsonc` file that is not included in the top-level `agents` list.
|
||||
|
||||
JSON crew definitions support crew-level fields such as `process`, `verbose`, `memory`, `cache`, `max_rpm`, `planning`, `planning_llm`, `manager_llm`, `manager_agent`, `function_calling_llm`, `output_log_file`, `stream`, `tracing`, `before_kickoff_callbacks`, and `after_kickoff_callbacks`.
|
||||
|
||||
Python callbacks and custom classes use `{"python": "module.attribute"}`. Custom tools use `"custom:<name>"` and load `tools/<name>.py` at runtime.
|
||||
|
||||
<Warning>
|
||||
Only run JSON crew projects from sources you trust. `custom:<name>` tools and `{"python": "module.attribute"}` references execute local Python code when the crew loads.
|
||||
</Warning>
|
||||
|
||||
### Classic Python/YAML Configuration
|
||||
|
||||
Classic projects created with `crewai create crew <name> --classic` use `crew.py`, `config/agents.yaml`, `config/tasks.yaml`, and the `@CrewBase`, `@agent`, `@task`, and `@crew` decorators. That pattern remains supported and is documented in [Using Annotations](/en/learn/using-annotations).
|
||||
|
||||
### Direct Code Definition (Alternative)
|
||||
|
||||
Alternatively, you can define the crew directly in code without using YAML configuration files.
|
||||
|
||||
```python code
|
||||
from crewai import Agent, Crew, Task, Process
|
||||
from crewai_tools import YourCustomTool
|
||||
|
||||
class YourCrewName:
|
||||
def agent_one(self) -> Agent:
|
||||
return Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data trends in the market",
|
||||
backstory="An experienced data analyst with a background in economics",
|
||||
verbose=True,
|
||||
tools=[YourCustomTool()]
|
||||
)
|
||||
|
||||
def agent_two(self) -> Agent:
|
||||
return Agent(
|
||||
role="Market Researcher",
|
||||
goal="Gather information on market dynamics",
|
||||
backstory="A diligent researcher with a keen eye for detail",
|
||||
verbose=True
|
||||
)
|
||||
|
||||
def task_one(self) -> Task:
|
||||
return Task(
|
||||
description="Collect recent market data and identify trends.",
|
||||
expected_output="A report summarizing key trends in the market.",
|
||||
agent=self.agent_one()
|
||||
)
|
||||
|
||||
def task_two(self) -> Task:
|
||||
return Task(
|
||||
description="Research factors affecting market dynamics.",
|
||||
expected_output="An analysis of factors influencing the market.",
|
||||
agent=self.agent_two()
|
||||
)
|
||||
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=[self.agent_one(), self.agent_two()],
|
||||
tasks=[self.task_one(), self.task_two()],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
How to run the above code:
|
||||
|
||||
```python code
|
||||
YourCrewName().crew().kickoff(inputs={})
|
||||
```
|
||||
|
||||
In this example:
|
||||
|
||||
- Agents and tasks are defined directly within the class without decorators.
|
||||
- We manually create and manage the list of agents and tasks.
|
||||
- This approach provides more control but can be less maintainable for larger projects.
|
||||
|
||||
## Crew Output
|
||||
|
||||
The output of a crew in the CrewAI framework is encapsulated within the `CrewOutput` class.
|
||||
This class provides a structured way to access results of the crew's execution, including various formats such as raw strings, JSON, and Pydantic models.
|
||||
The `CrewOutput` includes the results from the final task output, token usage, and individual task outputs.
|
||||
|
||||
### Crew Output Attributes
|
||||
|
||||
| Attribute | Parameters | Type | Description |
|
||||
| :--------------- | :------------- | :------------------------- | :--------------------------------------------------------------------------------------------------- |
|
||||
| **Raw** | `raw` | `str` | The raw output of the crew. This is the default format for the output. |
|
||||
| **Pydantic** | `pydantic` | `Optional[BaseModel]` | A Pydantic model object representing the structured output of the crew. |
|
||||
| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | A dictionary representing the JSON output of the crew. |
|
||||
| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | A list of `TaskOutput` objects, each representing the output of a task in the crew. |
|
||||
| **Token Usage** | `token_usage` | `Dict[str, Any]` | A summary of token usage, providing insights into the language model's performance during execution. |
|
||||
|
||||
### Crew Output Methods and Properties
|
||||
|
||||
| Method/Property | Description |
|
||||
| :-------------- | :------------------------------------------------------------------------------------------------ |
|
||||
| **json** | Returns the JSON string representation of the crew output if the output format is JSON. |
|
||||
| **to_dict** | Converts the JSON and Pydantic outputs to a dictionary. |
|
||||
| \***\*str\*\*** | Returns the string representation of the crew output, prioritizing Pydantic, then JSON, then raw. |
|
||||
|
||||
### Accessing Crew Outputs
|
||||
|
||||
Once a crew has been executed, its output can be accessed through the `output` attribute of the `Crew` object. The `CrewOutput` class provides various ways to interact with and present this output.
|
||||
|
||||
#### Example
|
||||
|
||||
```python Code
|
||||
# Example crew execution
|
||||
crew = Crew(
|
||||
agents=[research_agent, writer_agent],
|
||||
tasks=[research_task, write_article_task],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
crew_output = crew.kickoff()
|
||||
|
||||
# Accessing the crew output
|
||||
print(f"Raw Output: {crew_output.raw}")
|
||||
if crew_output.json_dict:
|
||||
print(f"JSON Output: {json.dumps(crew_output.json_dict, indent=2)}")
|
||||
if crew_output.pydantic:
|
||||
print(f"Pydantic Output: {crew_output.pydantic}")
|
||||
print(f"Tasks Output: {crew_output.tasks_output}")
|
||||
print(f"Token Usage: {crew_output.token_usage}")
|
||||
```
|
||||
|
||||
## Accessing Crew Logs
|
||||
|
||||
You can see real time log of the crew execution, by setting `output_log_file` as a `True(Boolean)` or a `file_name(str)`. Supports logging of events as both `file_name.txt` and `file_name.json`.
|
||||
In case of `True(Boolean)` will save as `logs.txt`.
|
||||
|
||||
In case of `output_log_file` is set as `False(Boolean)` or `None`, the logs will not be populated.
|
||||
|
||||
```python Code
|
||||
# Save crew logs
|
||||
crew = Crew(output_log_file = True) # Logs will be saved as logs.txt
|
||||
crew = Crew(output_log_file = file_name) # Logs will be saved as file_name.txt
|
||||
crew = Crew(output_log_file = file_name.txt) # Logs will be saved as file_name.txt
|
||||
crew = Crew(output_log_file = file_name.json) # Logs will be saved as file_name.json
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Checkpointing
|
||||
|
||||
Checkpointing lets a crew automatically save its state after key events (e.g. task completion) so that long-running or interrupted runs can be resumed exactly where they left off without re-executing completed tasks.
|
||||
|
||||
### Quick Start
|
||||
|
||||
Pass `checkpoint=True` to enable checkpointing with sensible defaults (saves to `.checkpoints/` after every task):
|
||||
|
||||
```python Code
|
||||
from crewai import Crew, Process
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, write_task],
|
||||
process=Process.sequential,
|
||||
checkpoint=True, # saves to .checkpoints/ after every task
|
||||
)
|
||||
|
||||
crew.kickoff(inputs={"topic": "AI trends"})
|
||||
```
|
||||
|
||||
### Full Control with `CheckpointConfig`
|
||||
|
||||
Use `CheckpointConfig` for fine-grained control over location, trigger events, storage backend, and retention:
|
||||
|
||||
```python Code
|
||||
from crewai import Crew, Process
|
||||
from crewai.state.checkpoint_config import CheckpointConfig
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, write_task],
|
||||
process=Process.sequential,
|
||||
checkpoint=CheckpointConfig(
|
||||
location="./.checkpoints", # directory for JSON files (default)
|
||||
on_events=["task_completed"], # trigger after each task (default)
|
||||
max_checkpoints=5, # keep only the 5 most recent checkpoints
|
||||
),
|
||||
)
|
||||
|
||||
crew.kickoff(inputs={"topic": "AI trends"})
|
||||
```
|
||||
|
||||
### Resuming from a Checkpoint
|
||||
|
||||
Use `Crew.from_checkpoint()` to restore a crew from a saved checkpoint file, then call `kickoff()` to resume:
|
||||
|
||||
```python Code
|
||||
# Resume from the most recent checkpoint
|
||||
crew = Crew.from_checkpoint(".checkpoints/latest.json")
|
||||
crew.kickoff()
|
||||
```
|
||||
|
||||
<Note>
|
||||
When restoring from a checkpoint, `checkpoint_inputs`, `checkpoint_train`, and `checkpoint_kickoff_event_id` are automatically reconstructed — you do not need to set these manually.
|
||||
</Note>
|
||||
|
||||
### `CheckpointConfig` Attributes
|
||||
|
||||
| Attribute | Type | Default | Description |
|
||||
| :----------------- | :------------------------------------- | :------------------- | :-------------------------------------------------------------------------------------------- |
|
||||
| `location` | `str` | `"./.checkpoints"` | Storage destination. For `JsonProvider` this is a directory path; for `SqliteProvider` a database file path. |
|
||||
| `on_events` | `list[str]` | `["task_completed"]` | Event types that trigger a checkpoint write. Use `["*"]` to checkpoint on every event. |
|
||||
| `provider` | `JsonProvider \| SqliteProvider` | `JsonProvider()` | Storage backend. Defaults to `JsonProvider` (plain JSON files). |
|
||||
| `max_checkpoints` | `int \| None` | `None` | Maximum checkpoints to keep. Oldest are pruned after each write. `None` keeps all. |
|
||||
|
||||
## Memory Utilization
|
||||
|
||||
Crews can utilize memory (short-term, long-term, and entity memory) to enhance their execution and learning over time. This feature allows crews to store and recall execution memories, aiding in decision-making and task execution strategies.
|
||||
|
||||
## Cache Utilization
|
||||
|
||||
Caches can be employed to store the results of tools' execution, making the process more efficient by reducing the need to re-execute identical tasks.
|
||||
|
||||
## Crew Usage Metrics
|
||||
|
||||
After the crew execution, you can access the `usage_metrics` attribute to view the language model (LLM) usage metrics for all tasks executed by the crew. This provides insights into operational efficiency and areas for improvement.
|
||||
|
||||
```python Code
|
||||
# Access the crew's usage metrics
|
||||
crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
|
||||
crew.kickoff()
|
||||
print(crew.usage_metrics)
|
||||
```
|
||||
|
||||
## Crew Execution Process
|
||||
|
||||
- **Sequential Process**: Tasks are executed one after another, allowing for a linear flow of work.
|
||||
- **Hierarchical Process**: A manager agent coordinates the crew, delegating tasks and validating outcomes before proceeding. **Note**: A `manager_llm` or `manager_agent` is required for this process and it's essential for validating the process flow.
|
||||
|
||||
### Kicking Off a Crew
|
||||
|
||||
Once your crew is assembled, initiate the workflow with the `kickoff()` method. This starts the execution process according to the defined process flow.
|
||||
|
||||
```python Code
|
||||
# Start the crew's task execution
|
||||
result = my_crew.kickoff()
|
||||
print(result)
|
||||
```
|
||||
|
||||
### Different Ways to Kick Off a Crew
|
||||
|
||||
Once your crew is assembled, initiate the workflow with the appropriate kickoff method. CrewAI provides several methods for better control over the kickoff process.
|
||||
|
||||
#### Synchronous Methods
|
||||
|
||||
- `kickoff()`: Starts the execution process according to the defined process flow.
|
||||
- `kickoff_for_each()`: Executes tasks sequentially for each provided input event or item in the collection.
|
||||
|
||||
#### Asynchronous Methods
|
||||
|
||||
CrewAI offers two approaches for async execution:
|
||||
|
||||
| Method | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| `akickoff()` | Native async | True async/await throughout the entire execution chain |
|
||||
| `akickoff_for_each()` | Native async | Native async execution for each input in a list |
|
||||
| `kickoff_async()` | Thread-based | Wraps synchronous execution in `asyncio.to_thread` |
|
||||
| `kickoff_for_each_async()` | Thread-based | Thread-based async for each input in a list |
|
||||
|
||||
<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.
|
||||
414
docs/edge/en/concepts/event-listener.mdx
Normal file
414
docs/edge/en/concepts/event-listener.mdx
Normal file
@@ -0,0 +1,414 @@
|
||||
---
|
||||
title: "Event Listeners"
|
||||
description: "Tap into CrewAI events to build custom integrations and monitoring"
|
||||
icon: spinner
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CrewAI provides a powerful event system that allows you to listen for and react to various events that occur during the execution of your Crew. This feature enables you to build custom integrations, monitoring solutions, logging systems, or any other functionality that needs to be triggered based on CrewAI's internal events.
|
||||
|
||||
## How It Works
|
||||
|
||||
CrewAI uses an event bus architecture to emit events throughout the execution lifecycle. The event system is built on the following components:
|
||||
|
||||
1. **CrewAIEventsBus**: A singleton event bus that manages event registration and emission
|
||||
2. **BaseEvent**: Base class for all events in the system
|
||||
3. **BaseEventListener**: Abstract base class for creating custom event listeners
|
||||
|
||||
When specific actions occur in CrewAI (like a Crew starting execution, an Agent completing a task, or a tool being used), the system emits corresponding events. You can register handlers for these events to execute custom code when they occur.
|
||||
|
||||
<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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
- **CrewTestResultEvent**: Emitted when a Crew test result is available. Contains the quality score, execution duration, and model used.
|
||||
|
||||
### Agent Events
|
||||
|
||||
- **AgentExecutionStartedEvent**: Emitted when an Agent starts executing a task
|
||||
- **AgentExecutionCompletedEvent**: Emitted when an Agent completes executing a task
|
||||
- **AgentExecutionErrorEvent**: Emitted when an Agent encounters an error during execution
|
||||
- **LiteAgentExecutionStartedEvent**: Emitted when a LiteAgent starts executing. Contains the agent info, tools, and messages.
|
||||
- **LiteAgentExecutionCompletedEvent**: Emitted when a LiteAgent completes execution. Contains the agent info and output.
|
||||
- **LiteAgentExecutionErrorEvent**: Emitted when a LiteAgent encounters an error during execution. Contains the agent info and error message.
|
||||
- **AgentEvaluationStartedEvent**: Emitted when an agent evaluation starts. Contains the agent ID, agent role, optional task ID, and iteration number.
|
||||
- **AgentEvaluationCompletedEvent**: Emitted when an agent evaluation completes. Contains the agent ID, agent role, optional task ID, iteration number, metric category, and score.
|
||||
- **AgentEvaluationFailedEvent**: Emitted when an agent evaluation fails. Contains the agent ID, agent role, optional task ID, iteration number, and error message.
|
||||
|
||||
### Task Events
|
||||
|
||||
- **TaskStartedEvent**: Emitted when a Task starts execution
|
||||
- **TaskCompletedEvent**: Emitted when a Task completes execution
|
||||
- **TaskFailedEvent**: Emitted when a Task fails to complete execution
|
||||
- **TaskEvaluationEvent**: Emitted when a Task is evaluated
|
||||
|
||||
### Tool Usage Events
|
||||
|
||||
- **ToolUsageStartedEvent**: Emitted when a tool execution is started
|
||||
- **ToolUsageFinishedEvent**: Emitted when a tool execution is completed
|
||||
- **ToolUsageErrorEvent**: Emitted when a tool execution encounters an error
|
||||
- **ToolValidateInputErrorEvent**: Emitted when a tool input validation encounters an error
|
||||
- **ToolExecutionErrorEvent**: Emitted when a tool execution encounters an error
|
||||
- **ToolSelectionErrorEvent**: Emitted when there's an error selecting a tool
|
||||
|
||||
### MCP Events
|
||||
|
||||
- **MCPConnectionStartedEvent**: Emitted when starting to connect to an MCP server. Contains the server name, URL, transport type, connection timeout, and whether it's a reconnection attempt.
|
||||
- **MCPConnectionCompletedEvent**: Emitted when successfully connected to an MCP server. Contains the server name, connection duration in milliseconds, and whether it was a reconnection.
|
||||
- **MCPConnectionFailedEvent**: Emitted when connection to an MCP server fails. Contains the server name, error message, and error type (`timeout`, `authentication`, `network`, etc.).
|
||||
- **MCPToolExecutionStartedEvent**: Emitted when starting to execute an MCP tool. Contains the server name, tool name, and tool arguments.
|
||||
- **MCPToolExecutionCompletedEvent**: Emitted when MCP tool execution completes successfully. Contains the server name, tool name, result, and execution duration in milliseconds.
|
||||
- **MCPToolExecutionFailedEvent**: Emitted when MCP tool execution fails. Contains the server name, tool name, error message, and error type (`timeout`, `validation`, `server_error`, etc.).
|
||||
- **MCPConfigFetchFailedEvent**: Emitted when fetching an MCP server configuration fails (e.g., the MCP is not connected in your account, API error, or connection failure after config was fetched). Contains the slug, error message, and error type (`not_connected`, `api_error`, `connection_failed`).
|
||||
|
||||
### Knowledge Events
|
||||
|
||||
- **KnowledgeRetrievalStartedEvent**: Emitted when a knowledge retrieval is started
|
||||
- **KnowledgeRetrievalCompletedEvent**: Emitted when a knowledge retrieval is completed
|
||||
- **KnowledgeQueryStartedEvent**: Emitted when a knowledge query is started
|
||||
- **KnowledgeQueryCompletedEvent**: Emitted when a knowledge query is completed
|
||||
- **KnowledgeQueryFailedEvent**: Emitted when a knowledge query fails
|
||||
- **KnowledgeSearchQueryFailedEvent**: Emitted when a knowledge search query fails
|
||||
|
||||
### LLM Guardrail Events
|
||||
|
||||
- **LLMGuardrailStartedEvent**: Emitted when a guardrail validation starts. Contains details about the guardrail being applied and retry count.
|
||||
- **LLMGuardrailCompletedEvent**: Emitted when a guardrail validation completes. Contains details about validation success/failure, results, and error messages if any.
|
||||
- **LLMGuardrailFailedEvent**: Emitted when a guardrail validation fails. Contains the error message and retry count.
|
||||
|
||||
### Flow Events
|
||||
|
||||
- **FlowCreatedEvent**: Emitted when a Flow is created
|
||||
- **FlowStartedEvent**: Emitted when a Flow starts execution
|
||||
- **FlowFinishedEvent**: Emitted when a Flow completes execution
|
||||
- **FlowPausedEvent**: Emitted when a Flow is paused waiting for human feedback. Contains the flow name, flow ID, method name, current state, message shown when requesting feedback, and optional list of possible outcomes for routing.
|
||||
- **FlowPlotEvent**: Emitted when a Flow is plotted
|
||||
- **MethodExecutionStartedEvent**: Emitted when a Flow method starts execution
|
||||
- **MethodExecutionFinishedEvent**: Emitted when a Flow method completes execution
|
||||
- **MethodExecutionFailedEvent**: Emitted when a Flow method fails to complete execution
|
||||
- **MethodExecutionPausedEvent**: Emitted when a Flow method is paused waiting for human feedback. Contains the flow name, method name, current state, flow ID, message shown when requesting feedback, and optional list of possible outcomes for routing.
|
||||
|
||||
### Human In The Loop Events
|
||||
|
||||
- **FlowInputRequestedEvent**: Emitted when a Flow requests user input via `Flow.ask()`. Contains the flow name, method name, the question or prompt being shown to the user, and optional metadata (e.g., user ID, channel, session context).
|
||||
- **FlowInputReceivedEvent**: Emitted when user input is received after `Flow.ask()`. Contains the flow name, method name, the original question, the user's response (or `None` if timed out), optional request metadata, and optional response metadata from the provider (e.g., who responded, thread ID, timestamps).
|
||||
- **HumanFeedbackRequestedEvent**: Emitted when a `@human_feedback` decorated method requires input from a human reviewer. Contains the flow name, method name, the method output shown to the human for review, the message displayed when requesting feedback, and optional list of possible outcomes for routing.
|
||||
- **HumanFeedbackReceivedEvent**: Emitted when a human provides feedback in response to a `@human_feedback` decorated method. Contains the flow name, method name, the raw text feedback provided by the human, and the collapsed outcome string (if emit was specified).
|
||||
|
||||
### LLM Events
|
||||
|
||||
- **LLMCallStartedEvent**: Emitted when an LLM call starts
|
||||
- **LLMCallCompletedEvent**: Emitted when an LLM call completes
|
||||
- **LLMCallFailedEvent**: Emitted when an LLM call fails
|
||||
- **LLMStreamChunkEvent**: Emitted for each chunk received during streaming LLM responses
|
||||
- **LLMThinkingChunkEvent**: Emitted when a thinking/reasoning chunk is received from a thinking model. Contains the chunk text and optional response ID.
|
||||
|
||||
### Memory Events
|
||||
|
||||
- **MemoryQueryStartedEvent**: Emitted when a memory query is started. Contains the query, limit, and optional score threshold.
|
||||
- **MemoryQueryCompletedEvent**: Emitted when a memory query is completed successfully. Contains the query, results, limit, score threshold, and query execution time.
|
||||
- **MemoryQueryFailedEvent**: Emitted when a memory query fails. Contains the query, limit, score threshold, and error message.
|
||||
- **MemorySaveStartedEvent**: Emitted when a memory save operation is started. Contains the value to be saved, metadata, and optional agent role.
|
||||
- **MemorySaveCompletedEvent**: Emitted when a memory save operation is completed successfully. Contains the saved value, metadata, agent role, and save execution time.
|
||||
- **MemorySaveFailedEvent**: Emitted when a memory save operation fails. Contains the value, metadata, agent role, and error message.
|
||||
- **MemoryRetrievalStartedEvent**: Emitted when memory retrieval for a task prompt starts. Contains the optional task ID.
|
||||
- **MemoryRetrievalCompletedEvent**: Emitted when memory retrieval for a task prompt completes successfully. Contains the task ID, memory content, and retrieval execution time.
|
||||
- **MemoryRetrievalFailedEvent**: Emitted when memory retrieval for a task prompt fails. Contains the optional task ID and error message.
|
||||
|
||||
### Reasoning Events
|
||||
|
||||
- **AgentReasoningStartedEvent**: Emitted when an agent starts reasoning about a task. Contains the agent role, task ID, and attempt number.
|
||||
- **AgentReasoningCompletedEvent**: Emitted when an agent finishes its reasoning process. Contains the agent role, task ID, the plan produced, and whether the agent is ready to proceed.
|
||||
- **AgentReasoningFailedEvent**: Emitted when the reasoning process fails. Contains the agent role, task ID, and error message.
|
||||
|
||||
### Observation Events
|
||||
|
||||
- **StepObservationStartedEvent**: Emitted when the Planner begins observing a step's result. Fires after every step execution, before the observation LLM call. Contains the agent role, step number, and step description.
|
||||
- **StepObservationCompletedEvent**: Emitted when the Planner finishes observing a step's result. Contains whether the step completed successfully, key information learned, whether the remaining plan is still valid, whether a full replan is needed, and suggested refinements.
|
||||
- **StepObservationFailedEvent**: Emitted when the observation LLM call itself fails. The system defaults to continuing the plan. Contains the error message.
|
||||
- **PlanRefinementEvent**: Emitted when the Planner refines upcoming step descriptions without a full replan. Contains the number of refined steps and the refinements applied.
|
||||
- **PlanReplanTriggeredEvent**: Emitted when the Planner triggers a full replan because the remaining plan was deemed fundamentally wrong. Contains the replan reason, replan count, and number of completed steps preserved.
|
||||
- **GoalAchievedEarlyEvent**: Emitted when the Planner detects the goal was achieved early and remaining steps will be skipped. Contains the number of steps remaining and steps completed.
|
||||
|
||||
### A2A (Agent-to-Agent) Events
|
||||
|
||||
#### Delegation Events
|
||||
|
||||
- **A2ADelegationStartedEvent**: Emitted when A2A delegation starts. Contains the endpoint URL, task description, agent ID, context ID, whether it's multiturn, turn number, agent card metadata, protocol version, provider info, and optional skill ID.
|
||||
- **A2ADelegationCompletedEvent**: Emitted when A2A delegation completes. Contains the completion status (`completed`, `input_required`, `failed`, etc.), result, error message, context ID, and agent card metadata.
|
||||
- **A2AParallelDelegationStartedEvent**: Emitted when parallel delegation to multiple A2A agents begins. Contains the list of endpoints and the task description.
|
||||
- **A2AParallelDelegationCompletedEvent**: Emitted when parallel delegation to multiple A2A agents completes. Contains the list of endpoints, success count, failure count, and results summary.
|
||||
|
||||
#### Conversation Events
|
||||
|
||||
- **A2AConversationStartedEvent**: Emitted once at the beginning of a multiturn A2A conversation, before the first message exchange. Contains the agent ID, endpoint, context ID, agent card metadata, protocol version, and provider info.
|
||||
- **A2AMessageSentEvent**: Emitted when a message is sent to the A2A agent. Contains the message content, turn number, context ID, message ID, and whether it's multiturn.
|
||||
- **A2AResponseReceivedEvent**: Emitted when a response is received from the A2A agent. Contains the response content, turn number, context ID, message ID, status, and whether it's the final response.
|
||||
- **A2AConversationCompletedEvent**: Emitted once at the end of a multiturn A2A conversation. Contains the final status (`completed` or `failed`), final result, error message, context ID, and total number of turns.
|
||||
|
||||
#### Streaming Events
|
||||
|
||||
- **A2AStreamingStartedEvent**: Emitted when streaming mode begins for A2A delegation. Contains the task ID, context ID, endpoint, turn number, and whether it's multiturn.
|
||||
- **A2AStreamingChunkEvent**: Emitted when a streaming chunk is received. Contains the chunk text, chunk index, whether it's the final chunk, task ID, context ID, and turn number.
|
||||
|
||||
#### Polling & Push Notification Events
|
||||
|
||||
- **A2APollingStartedEvent**: Emitted when polling mode begins for A2A delegation. Contains the task ID, context ID, polling interval in seconds, and endpoint.
|
||||
- **A2APollingStatusEvent**: Emitted on each polling iteration. Contains the task ID, context ID, current task state, elapsed seconds, and poll count.
|
||||
- **A2APushNotificationRegisteredEvent**: Emitted when a push notification callback is registered. Contains the task ID, context ID, callback URL, and endpoint.
|
||||
- **A2APushNotificationReceivedEvent**: Emitted when a push notification is received from the remote A2A agent. Contains the task ID, context ID, and current state.
|
||||
- **A2APushNotificationSentEvent**: Emitted when a push notification is sent to a callback URL. Contains the task ID, context ID, callback URL, state, whether delivery succeeded, and optional error message.
|
||||
- **A2APushNotificationTimeoutEvent**: Emitted when push notification wait times out. Contains the task ID, context ID, and timeout duration in seconds.
|
||||
|
||||
#### Connection & Authentication Events
|
||||
|
||||
- **A2AAgentCardFetchedEvent**: Emitted when an agent card is successfully fetched. Contains the endpoint, agent name, agent card metadata, protocol version, provider info, whether it was cached, and fetch time in milliseconds.
|
||||
- **A2AAuthenticationFailedEvent**: Emitted when authentication to an A2A agent fails. Contains the endpoint, auth type attempted (e.g., `bearer`, `oauth2`, `api_key`), error message, and HTTP status code.
|
||||
- **A2AConnectionErrorEvent**: Emitted when a connection error occurs during A2A communication. Contains the endpoint, error message, error type (e.g., `timeout`, `connection_refused`, `dns_error`), HTTP status code, and the operation being attempted.
|
||||
- **A2ATransportNegotiatedEvent**: Emitted when transport protocol is negotiated with an A2A agent. Contains the negotiated transport, negotiated URL, selection source (`client_preferred`, `server_preferred`, `fallback`), and client/server supported transports.
|
||||
- **A2AContentTypeNegotiatedEvent**: Emitted when content types are negotiated with an A2A agent. Contains the client/server input/output modes, negotiated input/output modes, and whether negotiation succeeded.
|
||||
|
||||
#### Artifact Events
|
||||
|
||||
- **A2AArtifactReceivedEvent**: Emitted when an artifact is received from a remote A2A agent. Contains the task ID, artifact ID, artifact name, description, MIME type, size in bytes, and whether content should be appended.
|
||||
|
||||
#### Server Task Events
|
||||
|
||||
- **A2AServerTaskStartedEvent**: Emitted when an A2A server task execution starts. Contains the task ID and context ID.
|
||||
- **A2AServerTaskCompletedEvent**: Emitted when an A2A server task execution completes. Contains the task ID, context ID, and result.
|
||||
- **A2AServerTaskCanceledEvent**: Emitted when an A2A server task execution is canceled. Contains the task ID and context ID.
|
||||
- **A2AServerTaskFailedEvent**: Emitted when an A2A server task execution fails. Contains the task ID, context ID, and error message.
|
||||
|
||||
#### Context Lifecycle Events
|
||||
|
||||
- **A2AContextCreatedEvent**: Emitted when an A2A context is created. Contexts group related tasks in a conversation or workflow. Contains the context ID and creation timestamp.
|
||||
- **A2AContextExpiredEvent**: Emitted when an A2A context expires due to TTL. Contains the context ID, creation timestamp, age in seconds, and task count.
|
||||
- **A2AContextIdleEvent**: Emitted when an A2A context becomes idle (no activity for the configured threshold). Contains the context ID, idle time in seconds, and task count.
|
||||
- **A2AContextCompletedEvent**: Emitted when all tasks in an A2A context complete. Contains the context ID, total tasks, and duration in seconds.
|
||||
- **A2AContextPrunedEvent**: Emitted when an A2A context is pruned (deleted). Contains the context ID, task count, and age in seconds.
|
||||
|
||||
## Event Handler Structure
|
||||
|
||||
Each event handler receives two parameters:
|
||||
|
||||
1. **source**: The object that emitted the event
|
||||
2. **event**: The event instance, containing event-specific data
|
||||
|
||||
The structure of the event object depends on the event type, but all events inherit from `BaseEvent` and include:
|
||||
|
||||
- **timestamp**: The time when the event was emitted
|
||||
- **type**: A string identifier for the event type
|
||||
|
||||
Additional fields vary by event type. For example, `CrewKickoffCompletedEvent` includes `crew_name` and `output` fields.
|
||||
|
||||
## Advanced Usage: Scoped Handlers
|
||||
|
||||
For temporary event handling (useful for testing or specific operations), you can use the `scoped_handlers` context manager:
|
||||
|
||||
```python
|
||||
from crewai.events import crewai_event_bus, CrewKickoffStartedEvent
|
||||
|
||||
with crewai_event_bus.scoped_handlers():
|
||||
@crewai_event_bus.on(CrewKickoffStartedEvent)
|
||||
def temp_handler(source, event):
|
||||
print("This handler only exists within this context")
|
||||
|
||||
# Do something that emits events
|
||||
|
||||
# Outside the context, the temporary handler is removed
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
Event listeners can be used for a variety of purposes:
|
||||
|
||||
1. **Logging and Monitoring**: Track the execution of your Crew and log important events
|
||||
2. **Analytics**: Collect data about your Crew's performance and behavior
|
||||
3. **Debugging**: Set up temporary listeners to debug specific issues
|
||||
4. **Integration**: Connect CrewAI with external systems like monitoring platforms, databases, or notification services
|
||||
5. **Custom Behavior**: Trigger custom actions based on specific events
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep Handlers Light**: Event handlers should be lightweight and avoid blocking operations
|
||||
2. **Error Handling**: Include proper error handling in your event handlers to prevent exceptions from affecting the main execution
|
||||
3. **Cleanup**: If your listener allocates resources, ensure they're properly cleaned up
|
||||
4. **Selective Listening**: Only listen for events you actually need to handle
|
||||
5. **Testing**: Test your event listeners in isolation to ensure they behave as expected
|
||||
|
||||
By leveraging CrewAI's event system, you can extend its functionality and integrate it seamlessly with your existing infrastructure.
|
||||
267
docs/edge/en/concepts/files.mdx
Normal file
267
docs/edge/en/concepts/files.mdx
Normal 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"),
|
||||
}
|
||||
)
|
||||
```
|
||||
1169
docs/edge/en/concepts/flows.mdx
Normal file
1169
docs/edge/en/concepts/flows.mdx
Normal file
File diff suppressed because it is too large
Load Diff
1097
docs/edge/en/concepts/knowledge.mdx
Normal file
1097
docs/edge/en/concepts/knowledge.mdx
Normal file
File diff suppressed because it is too large
Load Diff
1635
docs/edge/en/concepts/llms.mdx
Normal file
1635
docs/edge/en/concepts/llms.mdx
Normal file
File diff suppressed because it is too large
Load Diff
885
docs/edge/en/concepts/memory.mdx
Normal file
885
docs/edge/en/concepts/memory.mdx
Normal file
@@ -0,0 +1,885 @@
|
||||
---
|
||||
title: Memory
|
||||
description: Leveraging the unified memory system in CrewAI to enhance agent capabilities.
|
||||
icon: database
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CrewAI provides a **unified memory system** -- a single `Memory` class that replaces separate short-term, long-term, entity, and external memory types with one intelligent API. Memory uses an LLM to analyze content when saving (inferring scope, categories, and importance) and supports adaptive-depth recall with composite scoring that blends semantic similarity, recency, and importance.
|
||||
|
||||
You can use memory four ways: **standalone** (scripts, notebooks), **with Crews**, **with Agents**, or **inside Flows**.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# Store -- the LLM infers scope, categories, and importance
|
||||
memory.remember("We decided to use PostgreSQL for the user database.")
|
||||
|
||||
# Retrieve -- results ranked by composite score (semantic + recency + importance)
|
||||
matches = memory.recall("What database did we choose?")
|
||||
for m in matches:
|
||||
print(f"[{m.score:.2f}] {m.record.content}")
|
||||
|
||||
# Tune scoring for a fast-moving project
|
||||
memory = Memory(recency_weight=0.5, recency_half_life_days=7)
|
||||
|
||||
# Forget
|
||||
memory.forget(scope="/project/old")
|
||||
|
||||
# Explore the self-organized scope tree
|
||||
print(memory.tree())
|
||||
print(memory.info("/"))
|
||||
```
|
||||
|
||||
## Four Ways to Use Memory
|
||||
|
||||
### Standalone
|
||||
|
||||
Use memory in scripts, notebooks, CLI tools, or as a standalone knowledge base -- no agents or crews required.
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# Build up knowledge
|
||||
memory.remember("The API rate limit is 1000 requests per minute.")
|
||||
memory.remember("Our staging environment uses port 8080.")
|
||||
memory.remember("The team agreed to use feature flags for all new releases.")
|
||||
|
||||
# Later, recall what you need
|
||||
matches = memory.recall("What are our API limits?", limit=5)
|
||||
for m in matches:
|
||||
print(f"[{m.score:.2f}] {m.record.content}")
|
||||
|
||||
# Extract atomic facts from a longer text
|
||||
raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL
|
||||
next quarter. The budget is $50k. Sarah will lead the migration."""
|
||||
|
||||
facts = memory.extract_memories(raw)
|
||||
# ["Migration from MySQL to PostgreSQL planned for next quarter",
|
||||
# "Database migration budget is $50k",
|
||||
# "Sarah will lead the database migration"]
|
||||
|
||||
for fact in facts:
|
||||
memory.remember(fact)
|
||||
```
|
||||
|
||||
### With Crews
|
||||
|
||||
Pass `memory=True` for default settings, or pass a configured `Memory` instance for custom behavior.
|
||||
|
||||
```python
|
||||
from crewai import Crew, Agent, Task, Process, Memory
|
||||
|
||||
# Option 1: Default memory
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
process=Process.sequential,
|
||||
memory=True,
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
# Option 2: Custom memory with tuned scoring
|
||||
memory = Memory(
|
||||
recency_weight=0.4,
|
||||
semantic_weight=0.4,
|
||||
importance_weight=0.2,
|
||||
recency_half_life_days=14,
|
||||
)
|
||||
crew = Crew(
|
||||
agents=[researcher, writer],
|
||||
tasks=[research_task, writing_task],
|
||||
memory=memory,
|
||||
)
|
||||
```
|
||||
|
||||
When `memory=True`, the crew creates a default `Memory()` and passes the crew's `embedder` configuration through automatically. All agents in the crew share the crew's memory unless an agent has its own. Without a custom `embedder`, memory uses OpenAI `text-embedding-3-large` embeddings.
|
||||
|
||||
After each task, the crew automatically extracts discrete facts from the task output and stores them. Before each task, the agent recalls relevant context from memory and injects it into the task prompt.
|
||||
|
||||
### With Agents
|
||||
|
||||
Agents can use the crew's shared memory (default) or receive a scoped view for private context.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Memory
|
||||
|
||||
memory = Memory()
|
||||
|
||||
# Researcher gets a private scope -- only sees /agent/researcher
|
||||
researcher = Agent(
|
||||
role="Researcher",
|
||||
goal="Find and analyze information",
|
||||
backstory="Expert researcher with attention to detail",
|
||||
memory=memory.scope("/agent/researcher"),
|
||||
)
|
||||
|
||||
# Writer uses crew shared memory (no agent-level memory set)
|
||||
writer = Agent(
|
||||
role="Writer",
|
||||
goal="Produce clear, well-structured content",
|
||||
backstory="Experienced technical writer",
|
||||
# memory not set -- uses crew._memory when crew has memory enabled
|
||||
)
|
||||
```
|
||||
|
||||
This pattern gives the researcher private findings while the writer reads from the shared crew memory.
|
||||
|
||||
### With Flows
|
||||
|
||||
Every Flow has built-in memory. Use `self.remember()`, `self.recall()`, and `self.extract_memories()` inside any flow method.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
|
||||
class ResearchFlow(Flow):
|
||||
@start()
|
||||
def gather_data(self):
|
||||
findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k."
|
||||
self.remember(findings, scope="/research/databases")
|
||||
return findings
|
||||
|
||||
@listen(gather_data)
|
||||
def write_report(self, findings):
|
||||
# Recall past research to provide context
|
||||
past = self.recall("database performance benchmarks")
|
||||
context = "\n".join(f"- {m.record.content}" for m in past)
|
||||
return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}"
|
||||
```
|
||||
|
||||
See the [Flows documentation](/concepts/flows) for more on memory in Flows.
|
||||
|
||||
|
||||
## Hierarchical Scopes
|
||||
|
||||
### What Scopes Are
|
||||
|
||||
Memories are organized into a hierarchical tree of scopes, similar to a filesystem. Each scope is a path like `/`, `/project/alpha`, or `/agent/researcher/findings`.
|
||||
|
||||
```
|
||||
/
|
||||
/company
|
||||
/company/engineering
|
||||
/company/product
|
||||
/project
|
||||
/project/alpha
|
||||
/project/beta
|
||||
/agent
|
||||
/agent/researcher
|
||||
/agent/writer
|
||||
```
|
||||
|
||||
Scopes provide **context-dependent memory** -- when you recall within a scope, you only search that branch of the tree, which improves both precision and performance.
|
||||
|
||||
### How Scope Inference Works
|
||||
|
||||
When you call `remember()` without specifying a scope, the LLM analyzes the content and the existing scope tree, then suggests the best placement. If no existing scope fits, it creates a new one. Over time, the scope tree grows organically from the content itself -- you don't need to design a schema upfront.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# LLM infers scope from content
|
||||
memory.remember("We chose PostgreSQL for the user database.")
|
||||
# -> might be placed under /project/decisions or /engineering/database
|
||||
|
||||
# You can also specify scope explicitly
|
||||
memory.remember("Sprint velocity is 42 points", scope="/team/metrics")
|
||||
```
|
||||
|
||||
### Visualizing the Scope Tree
|
||||
|
||||
```python
|
||||
print(memory.tree())
|
||||
# / (15 records)
|
||||
# /project (8 records)
|
||||
# /project/alpha (5 records)
|
||||
# /project/beta (3 records)
|
||||
# /agent (7 records)
|
||||
# /agent/researcher (4 records)
|
||||
# /agent/writer (3 records)
|
||||
|
||||
print(memory.info("/project/alpha"))
|
||||
# ScopeInfo(path='/project/alpha', record_count=5,
|
||||
# categories=['architecture', 'database'],
|
||||
# oldest_record=datetime(...), newest_record=datetime(...),
|
||||
# child_scopes=[])
|
||||
```
|
||||
|
||||
### MemoryScope: Subtree Views
|
||||
|
||||
A `MemoryScope` restricts all operations to a branch of the tree. The agent or code using it can only see and write within that subtree.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Create a scope for a specific agent
|
||||
agent_memory = memory.scope("/agent/researcher")
|
||||
|
||||
# Everything is relative to /agent/researcher
|
||||
agent_memory.remember("Found three relevant papers on LLM memory.")
|
||||
# -> stored under /agent/researcher
|
||||
|
||||
agent_memory.recall("relevant papers")
|
||||
# -> searches only under /agent/researcher
|
||||
|
||||
# Narrow further with subscope
|
||||
project_memory = agent_memory.subscope("project-alpha")
|
||||
# -> /agent/researcher/project-alpha
|
||||
```
|
||||
|
||||
### Best Practices for Scope Design
|
||||
|
||||
- **Start flat, let the LLM organize.** Don't over-engineer your scope hierarchy upfront. Begin with `memory.remember(content)` and let the LLM's scope inference create structure as content accumulates.
|
||||
|
||||
- **Use `/{entity_type}/{identifier}` patterns.** Natural hierarchies emerge from patterns like `/project/alpha`, `/agent/researcher`, `/company/engineering`, `/customer/acme-corp`.
|
||||
|
||||
- **Scope by concern, not by data type.** Use `/project/alpha/decisions` rather than `/decisions/project/alpha`. This keeps related content together.
|
||||
|
||||
- **Keep depth shallow (2-3 levels).** Deeply nested scopes become too sparse. `/project/alpha/architecture` is good; `/project/alpha/architecture/decisions/databases/postgresql` is too deep.
|
||||
|
||||
- **Use explicit scopes when you know, let the LLM infer when you don't.** If you're storing a known project decision, pass `scope="/project/alpha/decisions"`. If you're storing freeform agent output, omit the scope and let the LLM figure it out.
|
||||
|
||||
### Use Case Examples
|
||||
|
||||
**Multi-project team:**
|
||||
```python
|
||||
memory = Memory()
|
||||
# Each project gets its own branch
|
||||
memory.remember("Using microservices architecture", scope="/project/alpha/architecture")
|
||||
memory.remember("GraphQL API for client apps", scope="/project/beta/api")
|
||||
|
||||
# Recall across all projects
|
||||
memory.recall("API design decisions")
|
||||
|
||||
# Or within a specific project
|
||||
memory.recall("API design", scope="/project/beta")
|
||||
```
|
||||
|
||||
**Per-agent private context with shared knowledge:**
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Researcher has private findings
|
||||
researcher_memory = memory.scope("/agent/researcher")
|
||||
|
||||
# Writer can read from both its own scope and shared company knowledge
|
||||
writer_view = memory.slice(
|
||||
scopes=["/agent/writer", "/company/knowledge"],
|
||||
read_only=True,
|
||||
)
|
||||
```
|
||||
|
||||
**Customer support (per-customer context):**
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Each customer gets isolated context
|
||||
memory.remember("Prefers email communication", scope="/customer/acme-corp")
|
||||
memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp")
|
||||
|
||||
# Shared product docs are accessible to all agents
|
||||
memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs")
|
||||
```
|
||||
|
||||
|
||||
## Memory Slices
|
||||
|
||||
### What Slices Are
|
||||
|
||||
A `MemorySlice` is a view across multiple, possibly disjoint scopes. Unlike a scope (which restricts to one subtree), a slice lets you recall from several branches simultaneously.
|
||||
|
||||
### When to Use Slices vs Scopes
|
||||
|
||||
- **Scope**: Use when an agent or code block should be restricted to a single subtree. Example: an agent that only sees `/agent/researcher`.
|
||||
- **Slice**: Use when you need to combine context from multiple branches. Example: an agent that reads from its own scope plus shared company knowledge.
|
||||
|
||||
### Read-Only Slices
|
||||
|
||||
The most common pattern: give an agent read access to multiple branches without letting it write to shared areas.
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
|
||||
# Agent can recall from its own scope AND company knowledge,
|
||||
# but cannot write to company knowledge
|
||||
agent_view = memory.slice(
|
||||
scopes=["/agent/researcher", "/company/knowledge"],
|
||||
read_only=True,
|
||||
)
|
||||
|
||||
matches = agent_view.recall("company security policies", limit=5)
|
||||
# Searches both /agent/researcher and /company/knowledge, merges and ranks results
|
||||
|
||||
agent_view.remember("new finding") # Raises PermissionError (read-only)
|
||||
```
|
||||
|
||||
### Read-Write Slices
|
||||
|
||||
When read-only is disabled, you can write to any of the included scopes, but you must specify which scope explicitly.
|
||||
|
||||
```python
|
||||
view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False)
|
||||
|
||||
# Must specify scope when writing
|
||||
view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"])
|
||||
```
|
||||
|
||||
|
||||
## Composite Scoring
|
||||
|
||||
Recall results are ranked by a weighted combination of three signals:
|
||||
|
||||
```
|
||||
composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance
|
||||
```
|
||||
|
||||
Where:
|
||||
- **similarity** = `1 / (1 + distance)` from the vector index (0 to 1)
|
||||
- **decay** = `0.5^(age_days / half_life_days)` -- exponential decay (1.0 for today, 0.5 at half-life)
|
||||
- **importance** = the record's importance score (0 to 1), set at encoding time
|
||||
|
||||
Configure these directly on the `Memory` constructor:
|
||||
|
||||
```python
|
||||
# Sprint retrospective: favor recent memories, short half-life
|
||||
memory = Memory(
|
||||
recency_weight=0.5,
|
||||
semantic_weight=0.3,
|
||||
importance_weight=0.2,
|
||||
recency_half_life_days=7,
|
||||
)
|
||||
|
||||
# Architecture knowledge base: favor important memories, long half-life
|
||||
memory = Memory(
|
||||
recency_weight=0.1,
|
||||
semantic_weight=0.5,
|
||||
importance_weight=0.4,
|
||||
recency_half_life_days=180,
|
||||
)
|
||||
```
|
||||
|
||||
Each `MemoryMatch` includes a `match_reasons` list so you can see why a result ranked where it did (e.g. `["semantic", "recency", "importance"]`).
|
||||
|
||||
|
||||
## LLM Analysis Layer
|
||||
|
||||
Memory uses the LLM in three ways:
|
||||
|
||||
1. **On save** -- When you omit scope, categories, or importance, the LLM analyzes the content and suggests scope, categories, importance, and metadata (entities, dates, topics).
|
||||
2. **On recall** -- For deep/auto recall, the LLM analyzes the query (keywords, time hints, suggested scopes, complexity) to guide retrieval.
|
||||
3. **Extract memories** -- `extract_memories(content)` breaks raw text (e.g. task output) into discrete memory statements. Agents use this before calling `remember()` on each statement so that atomic facts are stored instead of one large blob.
|
||||
|
||||
All analysis degrades gracefully on LLM failure -- see [Failure Behavior](#failure-behavior).
|
||||
|
||||
|
||||
## Memory Consolidation
|
||||
|
||||
When saving new content, the encoding pipeline automatically checks for similar existing records in storage. If the similarity is above `consolidation_threshold` (default 0.85), the LLM decides what to do:
|
||||
|
||||
- **keep** -- The existing record is still accurate and not redundant.
|
||||
- **update** -- The existing record should be updated with new information (LLM provides the merged content).
|
||||
- **delete** -- The existing record is outdated, superseded, or contradicted.
|
||||
- **insert_new** -- Whether the new content should also be inserted as a separate record.
|
||||
|
||||
This prevents duplicates from accumulating. For example, if you save "CrewAI ensures reliable operation" three times, consolidation recognizes the duplicates and keeps only one record.
|
||||
|
||||
### Intra-batch Dedup
|
||||
|
||||
When using `remember_many()`, items within the same batch are compared against each other before hitting storage. If two items have cosine similarity >= `batch_dedup_threshold` (default 0.98), the later one is silently dropped. This catches exact or near-exact duplicates within a single batch without any LLM calls (pure vector math).
|
||||
|
||||
```python
|
||||
# Only 2 records are stored (the third is a near-duplicate of the first)
|
||||
memory.remember_many([
|
||||
"CrewAI supports complex workflows.",
|
||||
"Python is a great language.",
|
||||
"CrewAI supports complex workflows.", # dropped by intra-batch dedup
|
||||
])
|
||||
```
|
||||
|
||||
|
||||
## Non-blocking Saves
|
||||
|
||||
`remember_many()` is **non-blocking** -- it submits the encoding pipeline to a background thread and returns immediately. This means the agent can continue to the next task while memories are being saved.
|
||||
|
||||
```python
|
||||
# Returns immediately -- save happens in background
|
||||
memory.remember_many(["Fact A.", "Fact B.", "Fact C."])
|
||||
|
||||
# recall() automatically waits for pending saves before searching
|
||||
matches = memory.recall("facts") # sees all 3 records
|
||||
```
|
||||
|
||||
### Read Barrier
|
||||
|
||||
Every `recall()` call automatically calls `drain_writes()` before searching, ensuring the query always sees the latest persisted records. This is transparent -- you never need to think about it.
|
||||
|
||||
### Crew Shutdown
|
||||
|
||||
When a crew finishes, `kickoff()` drains all pending memory saves in its `finally` block, so no saves are lost even if the crew completes while background saves are in flight.
|
||||
|
||||
### Standalone Usage
|
||||
|
||||
For scripts or notebooks where there's no crew lifecycle, call `drain_writes()` or `close()` explicitly:
|
||||
|
||||
```python
|
||||
memory = Memory()
|
||||
memory.remember_many(["Fact A.", "Fact B."])
|
||||
|
||||
# Option 1: Wait for pending saves
|
||||
memory.drain_writes()
|
||||
|
||||
# Option 2: Drain and shut down the background pool
|
||||
memory.close()
|
||||
```
|
||||
|
||||
|
||||
## Source and Privacy
|
||||
|
||||
Every memory record can carry a `source` tag for provenance tracking and a `private` flag for access control.
|
||||
|
||||
### Source Tracking
|
||||
|
||||
The `source` parameter identifies where a memory came from:
|
||||
|
||||
```python
|
||||
# Tag memories with their origin
|
||||
memory.remember("User prefers dark mode", source="user:alice")
|
||||
memory.remember("System config updated", source="admin")
|
||||
memory.remember("Agent found a bug", source="agent:debugger")
|
||||
|
||||
# Recall only memories from a specific source
|
||||
matches = memory.recall("user preferences", source="user:alice")
|
||||
```
|
||||
|
||||
### Private Memories
|
||||
|
||||
Private memories are only visible to recall when the `source` matches:
|
||||
|
||||
```python
|
||||
# Store a private memory
|
||||
memory.remember("Alice's API key is sk-...", source="user:alice", private=True)
|
||||
|
||||
# This recall sees the private memory (source matches)
|
||||
matches = memory.recall("API key", source="user:alice")
|
||||
|
||||
# This recall does NOT see it (different source)
|
||||
matches = memory.recall("API key", source="user:bob")
|
||||
|
||||
# Admin access: see all private records regardless of source
|
||||
matches = memory.recall("API key", include_private=True)
|
||||
```
|
||||
|
||||
This is particularly useful in multi-user or enterprise deployments where different users' memories should be isolated.
|
||||
|
||||
|
||||
## RecallFlow (Deep Recall)
|
||||
|
||||
`recall()` supports two depths:
|
||||
|
||||
- **`depth="shallow"`** -- Direct vector search with composite scoring. Fast (~200ms), no LLM calls.
|
||||
- **`depth="deep"` (default)** -- Runs a multi-step RecallFlow: query analysis, scope selection, parallel vector search, confidence-based routing, and optional recursive exploration when confidence is low.
|
||||
|
||||
**Smart LLM skip**: Queries shorter than `query_analysis_threshold` (default 200 characters) skip the LLM query analysis entirely, even in deep mode. Short queries like "What database do we use?" are already good search phrases -- the LLM analysis adds little value. This saves ~1-3s per recall for typical short queries. Only longer queries (e.g. full task descriptions) go through LLM distillation into targeted sub-queries.
|
||||
|
||||
```python
|
||||
# Shallow: pure vector search, no LLM
|
||||
matches = memory.recall("What did we decide?", limit=10, depth="shallow")
|
||||
|
||||
# Deep (default): intelligent retrieval with LLM analysis for long queries
|
||||
matches = memory.recall(
|
||||
"Summarize all architecture decisions from this quarter",
|
||||
limit=10,
|
||||
depth="deep",
|
||||
)
|
||||
```
|
||||
|
||||
The confidence thresholds that control the RecallFlow router are configurable:
|
||||
|
||||
```python
|
||||
memory = Memory(
|
||||
confidence_threshold_high=0.9, # Only synthesize when very confident
|
||||
confidence_threshold_low=0.4, # Explore deeper more aggressively
|
||||
exploration_budget=2, # Allow up to 2 exploration rounds
|
||||
query_analysis_threshold=200, # Skip LLM for queries shorter than this
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## Embedder Configuration
|
||||
|
||||
Memory needs an embedding model to convert text into vectors for semantic search. By default, `Memory()` uses OpenAI `text-embedding-3-large` embeddings, which produce 3072-dimensional vectors. Set `OPENAI_API_KEY` for the default path, or configure a custom embedder in one of three ways.
|
||||
|
||||
<Warning>
|
||||
Existing local memory stores created with 1536-dimensional embeddings, such as `text-embedding-3-small` or `text-embedding-ada-002`, may not be compatible with the `text-embedding-3-large` default. This applies to both the OpenAI and Azure OpenAI providers — Azure's default embedding model also changed from `text-embedding-ada-002` to `text-embedding-3-large`. If local testing fails with an embedding dimension mismatch, reset memory with `crewai reset-memories -m`, delete the local memory storage directory, or explicitly configure the older embedder model until you migrate.
|
||||
</Warning>
|
||||
|
||||
### Passing to Memory Directly
|
||||
|
||||
```python
|
||||
from crewai import Memory
|
||||
|
||||
# As a config dict
|
||||
memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-large"}})
|
||||
|
||||
# As a pre-built callable
|
||||
from crewai.rag.embeddings.factory import build_embedder
|
||||
embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}})
|
||||
memory = Memory(embedder=embedder)
|
||||
```
|
||||
|
||||
### Via Crew Embedder Config
|
||||
|
||||
When using `memory=True`, the crew's `embedder` config is passed through:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
crew = Crew(
|
||||
agents=[...],
|
||||
tasks=[...],
|
||||
memory=True,
|
||||
embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-large"}},
|
||||
)
|
||||
```
|
||||
|
||||
### Provider Examples
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenAI (default)">
|
||||
```python
|
||||
memory = Memory(embedder={
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model_name": "text-embedding-3-large",
|
||||
# "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-large` | Default. Set `OPENAI_API_KEY`. |
|
||||
| Ollama | `ollama` | `mxbai-embed-large` | Local, no API key needed. |
|
||||
| Azure OpenAI | `azure` | `text-embedding-3-large` | Default model. Requires `deployment_id`. |
|
||||
| Google AI | `google-generativeai` | `gemini-embedding-001` | Set `GOOGLE_API_KEY`. |
|
||||
| Google Vertex | `google-vertex` | `gemini-embedding-001` | Requires `project_id`. |
|
||||
| Cohere | `cohere` | `embed-english-v3.0` | Strong multilingual support. |
|
||||
| VoyageAI | `voyageai` | `voyage-3` | Optimized for retrieval. |
|
||||
| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | Uses boto3 credentials. |
|
||||
| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | Local sentence-transformers. |
|
||||
| Jina | `jina` | `jina-embeddings-v2-base-en` | Set `JINA_API_KEY`. |
|
||||
| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | Requires `project_id`. |
|
||||
| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | Local, no API key. |
|
||||
| Custom | `custom` | -- | Requires `embedding_callable`. |
|
||||
|
||||
|
||||
## LLM Configuration
|
||||
|
||||
Memory uses an LLM for save analysis (scope, categories, importance inference), consolidation decisions, and deep recall query analysis. You can configure which model to use.
|
||||
|
||||
```python
|
||||
from crewai import Memory, LLM
|
||||
|
||||
# Default: gpt-4o-mini
|
||||
memory = Memory()
|
||||
|
||||
# Use a different OpenAI model
|
||||
memory = Memory(llm="gpt-4o")
|
||||
|
||||
# Use Anthropic
|
||||
memory = Memory(llm="anthropic/claude-3-haiku-20240307")
|
||||
|
||||
# Use Ollama for fully local/private analysis
|
||||
memory = Memory(llm="ollama/llama3.2")
|
||||
|
||||
# Use Google Gemini
|
||||
memory = Memory(llm="gemini/gemini-2.0-flash")
|
||||
|
||||
# Pass a pre-configured LLM instance with custom settings
|
||||
llm = LLM(model="gpt-4o", temperature=0)
|
||||
memory = Memory(llm=llm)
|
||||
```
|
||||
|
||||
The LLM is initialized **lazily** -- it's only created when first needed. This means `Memory()` never fails at construction time, even if API keys aren't set. Errors only surface when the LLM is actually called (e.g. when saving without explicit scope/categories, or during deep recall).
|
||||
|
||||
For fully offline/private operation, use a local model for both the LLM and embedder:
|
||||
|
||||
```python
|
||||
memory = Memory(
|
||||
llm="ollama/llama3.2",
|
||||
embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}},
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## Storage Backend
|
||||
|
||||
- **Default**: LanceDB, stored under `./.crewai/memory` (or `$CREWAI_STORAGE_DIR/memory` if the env var is set, or the path you pass as `storage="path/to/dir"`).
|
||||
- **Custom backend**: Implement the `StorageBackend` protocol (see `crewai.memory.storage.backend`) and pass an instance to `Memory(storage=your_backend)`.
|
||||
|
||||
|
||||
## Discovery
|
||||
|
||||
Inspect the scope hierarchy, categories, and records:
|
||||
|
||||
```python
|
||||
memory.tree() # Formatted tree of scopes and record counts
|
||||
memory.tree("/project", max_depth=2) # Subtree view
|
||||
memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest
|
||||
memory.list_scopes("/") # Immediate child scopes
|
||||
memory.list_categories() # Category names and counts
|
||||
memory.list_records(scope="/project/alpha", limit=20) # Records in a scope, newest first
|
||||
```
|
||||
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
If the LLM fails during analysis (network error, rate limit, invalid response), memory degrades gracefully:
|
||||
|
||||
- **Save analysis** -- A warning is logged and the memory is still stored with default scope `/`, empty categories, and importance `0.5`.
|
||||
- **Extract memories** -- The full content is stored as a single memory so nothing is dropped.
|
||||
- **Query analysis** -- Recall falls back to simple scope selection and vector search so you still get results.
|
||||
|
||||
No exception is raised for these analysis failures; only storage or embedder failures will raise.
|
||||
|
||||
|
||||
## Privacy Note
|
||||
|
||||
Memory content is sent to the configured LLM for analysis (scope/categories/importance on save, query analysis and optional deep recall). For sensitive data, use a local LLM (e.g. Ollama) or ensure your provider meets your compliance requirements.
|
||||
|
||||
|
||||
## Memory Events
|
||||
|
||||
All memory operations emit events with `source_type="unified_memory"`. You can listen for timing, errors, and content.
|
||||
|
||||
| Event | Description | Key Properties |
|
||||
| :---- | :---------- | :------------- |
|
||||
| **MemoryQueryStartedEvent** | Query begins | `query`, `limit` |
|
||||
| **MemoryQueryCompletedEvent** | Query succeeds | `query`, `results`, `query_time_ms` |
|
||||
| **MemoryQueryFailedEvent** | Query fails | `query`, `error` |
|
||||
| **MemorySaveStartedEvent** | Save begins | `value`, `metadata` |
|
||||
| **MemorySaveCompletedEvent** | Save succeeds | `value`, `save_time_ms` |
|
||||
| **MemorySaveFailedEvent** | Save fails | `value`, `error` |
|
||||
| **MemoryRetrievalStartedEvent** | Agent retrieval starts | `task_id` |
|
||||
| **MemoryRetrievalCompletedEvent** | Agent retrieval done | `task_id`, `memory_content`, `retrieval_time_ms` |
|
||||
|
||||
Example: monitor query time:
|
||||
|
||||
```python
|
||||
from crewai.events import BaseEventListener, MemoryQueryCompletedEvent
|
||||
|
||||
class MemoryMonitor(BaseEventListener):
|
||||
def setup_listeners(self, crewai_event_bus):
|
||||
@crewai_event_bus.on(MemoryQueryCompletedEvent)
|
||||
def on_done(source, event):
|
||||
if getattr(event, "source_type", None) == "unified_memory":
|
||||
print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms")
|
||||
```
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Memory not persisting?**
|
||||
- Ensure the storage path is writable (default `./.crewai/memory`). Pass `storage="./your_path"` to use a different directory, or set the `CREWAI_STORAGE_DIR` environment variable.
|
||||
- When using a crew, confirm `memory=True` or `memory=Memory(...)` is set.
|
||||
|
||||
**Slow recall?**
|
||||
- Use `depth="shallow"` for routine agent context. Reserve `depth="deep"` for complex queries.
|
||||
- Increase `query_analysis_threshold` to skip LLM analysis for more queries.
|
||||
|
||||
**LLM analysis errors in logs?**
|
||||
- Memory still saves/recalls with safe defaults. Check API keys, rate limits, and model availability if you want full LLM analysis.
|
||||
|
||||
**Background save errors in logs?**
|
||||
- Memory saves run in a background thread. Errors are emitted as `MemorySaveFailedEvent` but don't crash the agent. Check logs for the root cause (usually LLM or embedder connection issues).
|
||||
|
||||
**Embedding dimension mismatch?**
|
||||
- Existing local memory stores may have been created with a different embedding model. The default OpenAI memory embedder is now `text-embedding-3-large` (3072 dimensions), while older stores commonly used 1536-dimensional embeddings. For local testing, run `crewai reset-memories -m`, delete the local memory storage directory, or configure the previous embedder model explicitly.
|
||||
|
||||
**Concurrent write conflicts?**
|
||||
- LanceDB operations are serialized with a shared lock and retried automatically on conflict. This handles multiple `Memory` instances pointing at the same database (e.g. agent memory + crew memory). No action needed.
|
||||
|
||||
**Browse memory from the terminal:**
|
||||
```bash
|
||||
crewai memory # Opens the TUI browser
|
||||
crewai memory --storage-path ./my_memory # Point to a specific directory
|
||||
```
|
||||
|
||||
**Reset memory (e.g. for tests):**
|
||||
```python
|
||||
crew.reset_memories(command_type="memory") # Resets unified memory
|
||||
# Or on a Memory instance:
|
||||
memory.reset() # All scopes
|
||||
memory.reset(scope="/project/old") # Only that subtree
|
||||
```
|
||||
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
All configuration is passed as keyword arguments to `Memory(...)`. Every parameter has a sensible default.
|
||||
|
||||
| Parameter | Default | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `llm` | `"gpt-4o-mini"` | LLM for analysis (model name or `BaseLLM` instance). |
|
||||
| `storage` | `"lancedb"` | Storage backend (`"lancedb"`, a path string, or a `StorageBackend` instance). |
|
||||
| `embedder` | `None` (OpenAI `text-embedding-3-large`) | Embedder (config dict, callable, or `None` for default OpenAI). |
|
||||
| `recency_weight` | `0.3` | Weight for recency in composite score. |
|
||||
| `semantic_weight` | `0.5` | Weight for semantic similarity in composite score. |
|
||||
| `importance_weight` | `0.2` | Weight for importance in composite score. |
|
||||
| `recency_half_life_days` | `30` | Days for recency score to halve (exponential decay). |
|
||||
| `consolidation_threshold` | `0.85` | Similarity above which consolidation is triggered on save. Set to `1.0` to disable. |
|
||||
| `consolidation_limit` | `5` | Max existing records to compare during consolidation. |
|
||||
| `default_importance` | `0.5` | Importance assigned when not provided and LLM analysis is skipped. |
|
||||
| `batch_dedup_threshold` | `0.98` | Cosine similarity for dropping near-duplicates within a `remember_many()` batch. |
|
||||
| `confidence_threshold_high` | `0.8` | Recall confidence above which results are returned directly. |
|
||||
| `confidence_threshold_low` | `0.5` | Recall confidence below which deeper exploration is triggered. |
|
||||
| `complex_query_threshold` | `0.7` | For complex queries, explore deeper below this confidence. |
|
||||
| `exploration_budget` | `1` | Number of LLM-driven exploration rounds during deep recall. |
|
||||
| `query_analysis_threshold` | `200` | Queries shorter than this (in characters) skip LLM analysis during deep recall. |
|
||||
155
docs/edge/en/concepts/planning.mdx
Normal file
155
docs/edge/en/concepts/planning.mdx
Normal 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>
|
||||
66
docs/edge/en/concepts/processes.mdx
Normal file
66
docs/edge/en/concepts/processes.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: Processes
|
||||
description: Detailed guide on workflow management through processes in CrewAI, with updated implementation details.
|
||||
icon: bars-staggered
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
<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.
|
||||
|
||||
## The Role of Processes in Teamwork
|
||||
Processes enable individual agents to operate as a cohesive unit, streamlining their efforts to achieve common objectives with efficiency and coherence.
|
||||
|
||||
## Assigning Processes to a Crew
|
||||
To assign a process to a crew, specify the process type upon crew creation to set the execution strategy. For a hierarchical process, ensure to define `manager_llm` or `manager_agent` for the manager agent.
|
||||
|
||||
```python
|
||||
from crewai import Crew, Process
|
||||
|
||||
# Example: Creating a crew with a sequential process
|
||||
crew = Crew(
|
||||
agents=my_agents,
|
||||
tasks=my_tasks,
|
||||
process=Process.sequential
|
||||
)
|
||||
|
||||
# Example: Creating a crew with a hierarchical process
|
||||
# Ensure to provide a manager_llm or manager_agent
|
||||
crew = Crew(
|
||||
agents=my_agents,
|
||||
tasks=my_tasks,
|
||||
process=Process.hierarchical,
|
||||
manager_llm="gpt-4o"
|
||||
# or
|
||||
# manager_agent=my_manager_agent
|
||||
)
|
||||
```
|
||||
**Note:** Ensure `my_agents` and `my_tasks` are defined prior to creating a `Crew` object, and for the hierarchical process, either `manager_llm` or `manager_agent` is also required.
|
||||
|
||||
## Sequential Process
|
||||
|
||||
This method mirrors dynamic team workflows, progressing through tasks in a thoughtful and systematic manner. Task execution follows the predefined order in the task list, with the output of one task serving as context for the next.
|
||||
|
||||
To customize task context, utilize the `context` parameter in the `Task` class to specify outputs that should be used as context for subsequent tasks.
|
||||
|
||||
## Hierarchical Process
|
||||
|
||||
Emulates a corporate hierarchy, CrewAI allows specifying a custom manager agent or automatically creates one, requiring the specification of a manager language model (`manager_llm`). This agent oversees task execution, including planning, delegation, and validation. Tasks are not pre-assigned; the manager allocates tasks to agents based on their capabilities, reviews outputs, and assesses task completion.
|
||||
|
||||
## Process Class: Detailed Overview
|
||||
|
||||
The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`).
|
||||
|
||||
## Conclusion
|
||||
|
||||
The structured collaboration facilitated by processes within CrewAI is crucial for enabling systematic teamwork among agents.
|
||||
This documentation has been updated to reflect the latest features and enhancements, ensuring users have access to the most current and comprehensive information.
|
||||
162
docs/edge/en/concepts/production-architecture.mdx
Normal file
162
docs/edge/en/concepts/production-architecture.mdx
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Production Architecture
|
||||
description: Best practices for building production-ready AI applications with CrewAI
|
||||
icon: server
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
# The Flow-First Mindset
|
||||
|
||||
When building production AI applications with CrewAI, **we recommend starting with a Flow**.
|
||||
|
||||
While it's possible to run individual Crews or Agents, wrapping them in a Flow provides the necessary structure for a robust, scalable application.
|
||||
|
||||
## Why Flows?
|
||||
|
||||
1. **State Management**: Flows provide a built-in way to manage state across different steps of your application. This is crucial for passing data between Crews, maintaining context, and handling user inputs.
|
||||
2. **Control**: Flows allow you to define precise execution paths, including loops, conditionals, and branching logic. This is essential for handling edge cases and ensuring your application behaves predictably.
|
||||
3. **Observability**: Flows provide a clear structure that makes it easier to trace execution, debug issues, and monitor performance. We recommend using [CrewAI Tracing](/en/observability/tracing) for detailed insights. Simply run `crewai login` to enable free observability features.
|
||||
|
||||
## The Architecture
|
||||
|
||||
A typical production CrewAI application looks like this:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Start((Start)) --> Flow[Flow Orchestrator]
|
||||
Flow --> State{State Management}
|
||||
State --> Step1[Step 1: Data Gathering]
|
||||
Step1 --> Crew1[Research Crew]
|
||||
Crew1 --> State
|
||||
State --> Step2{Condition Check}
|
||||
Step2 -- "Valid" --> Step3[Step 3: Execution]
|
||||
Step3 --> Crew2[Action Crew]
|
||||
Step2 -- "Invalid" --> End((End))
|
||||
Crew2 --> End
|
||||
```
|
||||
|
||||
### 1. The Flow Class
|
||||
Your `Flow` class is the entry point. It defines the state schema and the methods that execute your logic.
|
||||
|
||||
```python
|
||||
from crewai.flow.flow import Flow, listen, start
|
||||
from pydantic import BaseModel
|
||||
|
||||
class AppState(BaseModel):
|
||||
user_input: str = ""
|
||||
research_results: str = ""
|
||||
final_report: str = ""
|
||||
|
||||
class ProductionFlow(Flow[AppState]):
|
||||
@start()
|
||||
def gather_input(self):
|
||||
# ... logic to get input ...
|
||||
pass
|
||||
|
||||
@listen(gather_input)
|
||||
def run_research_crew(self):
|
||||
# ... trigger a Crew ...
|
||||
pass
|
||||
```
|
||||
|
||||
### 2. State Management
|
||||
Use Pydantic models to define your state. This ensures type safety and makes it clear what data is available at each step.
|
||||
|
||||
- **Keep it minimal**: Store only what you need to persist between steps.
|
||||
- **Use structured data**: Avoid unstructured dictionaries when possible.
|
||||
|
||||
### 3. Crews as Units of Work
|
||||
Delegate complex tasks to Crews. A Crew should be focused on a specific goal (e.g., "Research a topic", "Write a blog post").
|
||||
|
||||
- **Don't over-engineer Crews**: Keep them focused.
|
||||
- **Pass state explicitly**: Pass the necessary data from the Flow state to the Crew inputs.
|
||||
|
||||
```python
|
||||
@listen(gather_input)
|
||||
def run_research_crew(self):
|
||||
crew = ResearchCrew()
|
||||
result = crew.kickoff(inputs={"topic": self.state.user_input})
|
||||
self.state.research_results = result.raw
|
||||
```
|
||||
|
||||
## Control Primitives
|
||||
|
||||
Leverage CrewAI's control primitives to add robustness and control to your Crews.
|
||||
|
||||
### 1. Task Guardrails
|
||||
Use [Task Guardrails](/en/concepts/tasks#task-guardrails) to validate task outputs before they are accepted. This ensures that your agents produce high-quality results.
|
||||
|
||||
```python
|
||||
def validate_content(result: TaskOutput) -> Tuple[bool, Any]:
|
||||
if len(result.raw) < 100:
|
||||
return (False, "Content is too short. Please expand.")
|
||||
return (True, result.raw)
|
||||
|
||||
task = Task(
|
||||
...,
|
||||
guardrail=validate_content
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Structured Outputs
|
||||
Always use structured outputs (`output_pydantic` or `output_json`) when passing data between tasks or to your application. This prevents parsing errors and ensures type safety.
|
||||
|
||||
```python
|
||||
class ResearchResult(BaseModel):
|
||||
summary: str
|
||||
sources: List[str]
|
||||
|
||||
task = Task(
|
||||
...,
|
||||
output_pydantic=ResearchResult
|
||||
)
|
||||
```
|
||||
|
||||
### 3. LLM Hooks
|
||||
Use [LLM Hooks](/en/learn/llm-hooks) to inspect or modify messages before they are sent to the LLM, or to sanitize responses.
|
||||
|
||||
```python
|
||||
@before_llm_call
|
||||
def log_request(context):
|
||||
print(f"Agent {context.agent.role} is calling the LLM...")
|
||||
```
|
||||
|
||||
## Deployment Patterns
|
||||
|
||||
When deploying your Flow, consider the following:
|
||||
|
||||
### CrewAI Enterprise
|
||||
The easiest way to deploy your Flow is using CrewAI Enterprise. It handles the infrastructure, authentication, and monitoring for you.
|
||||
|
||||
Check out the [Deployment Guide](/en/enterprise/guides/deploy-crew) to get started.
|
||||
|
||||
```bash
|
||||
crewai deploy create
|
||||
```
|
||||
|
||||
### Async Execution
|
||||
For long-running tasks, use `kickoff_async` to avoid blocking your API.
|
||||
|
||||
### Persistence
|
||||
Use the `@persist` decorator to save the state of your Flow to a database. This allows you to resume execution if the process crashes or if you need to wait for human input.
|
||||
|
||||
```python
|
||||
@persist
|
||||
class ProductionFlow(Flow[AppState]):
|
||||
# ...
|
||||
```
|
||||
|
||||
By default, `@persist` resumes a flow when `kickoff(inputs={"id": <uuid>})` is supplied, extending the same `flow_uuid` history. To **fork** a persisted flow into a new lineage — hydrate state from a previous run but write under a fresh `state.id` — pass `restore_from_state_id`:
|
||||
|
||||
```python
|
||||
flow.kickoff(restore_from_state_id="<previous-run-state-id>")
|
||||
```
|
||||
|
||||
The new run gets a fresh `state.id` (auto-generated, or `inputs["id"]` if pinned) so its `@persist` writes don't extend the source's history. Combining with `from_checkpoint` raises a `ValueError`; pick one hydration source.
|
||||
|
||||
## Summary
|
||||
|
||||
- **Start with a Flow.**
|
||||
- **Define a clear State.**
|
||||
- **Use Crews for complex tasks.**
|
||||
- **Deploy with an API and persistence.**
|
||||
148
docs/edge/en/concepts/reasoning.mdx
Normal file
148
docs/edge/en/concepts/reasoning.mdx
Normal 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.
|
||||
306
docs/edge/en/concepts/skills.mdx
Normal file
306
docs/edge/en/concepts/skills.mdx
Normal file
@@ -0,0 +1,306 @@
|
||||
---
|
||||
title: Skills
|
||||
description: Filesystem-based skill packages that inject domain expertise and instructions into agent prompts.
|
||||
icon: bolt
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Skills are self-contained directories that provide agents with **domain-specific instructions, guidelines, and reference material**. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body.
|
||||
|
||||
When activated, a skill's instructions are injected directly into the agent's task prompt — giving the agent expertise without requiring any code changes.
|
||||
|
||||
<Note type="info" title="Skills vs Tools — The Key Distinction">
|
||||
**Skills are NOT tools.** This is the most common point of confusion.
|
||||
|
||||
- **Skills** inject *instructions and context* into the agent's prompt. They tell the agent *how to think* about a problem.
|
||||
- **Tools** give the agent *callable functions* to take action (search, read files, call APIs).
|
||||
|
||||
You often need **both**: skills for expertise, tools for action. They are configured independently and complement each other.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Create a Skill Directory
|
||||
|
||||
```
|
||||
skills/
|
||||
└── code-review/
|
||||
├── SKILL.md # Required — instructions
|
||||
├── references/ # Optional — reference docs
|
||||
│ └── style-guide.md
|
||||
└── scripts/ # Optional — executable scripts
|
||||
```
|
||||
|
||||
### 2. Write Your SKILL.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: code-review
|
||||
description: Guidelines for conducting thorough code reviews with focus on security and performance.
|
||||
metadata:
|
||||
author: your-team
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
## Code Review Guidelines
|
||||
|
||||
When reviewing code, follow this checklist:
|
||||
|
||||
1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure
|
||||
2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls
|
||||
3. **Readability**: Ensure clear naming, appropriate comments, and consistent style
|
||||
4. **Testing**: Verify adequate test coverage for new functionality
|
||||
|
||||
### Severity Levels
|
||||
- **Critical**: Security vulnerabilities, data loss risks → block merge
|
||||
- **Major**: Performance issues, logic errors → request changes
|
||||
- **Minor**: Style issues, naming suggestions → approve with comments
|
||||
```
|
||||
|
||||
### 3. Attach to an Agent
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import GithubSearchTool, FileReadTool
|
||||
|
||||
reviewer = Agent(
|
||||
role="Senior Code Reviewer",
|
||||
goal="Review pull requests for quality and security issues",
|
||||
backstory="Staff engineer with expertise in secure coding practices.",
|
||||
skills=["./skills"], # Injects review guidelines
|
||||
tools=[GithubSearchTool(), FileReadTool()], # Lets agent read code
|
||||
)
|
||||
```
|
||||
|
||||
The agent now has both **expertise** (from the skill) and **capabilities** (from the tools).
|
||||
|
||||
---
|
||||
|
||||
## Skills + Tools: Working Together
|
||||
|
||||
Here are common patterns showing how skills and tools complement each other:
|
||||
|
||||
### Pattern 1: Skills Only (Domain Expertise, No Actions Needed)
|
||||
|
||||
Use when the agent needs specific instructions but doesn't need to call external services:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Technical Writer",
|
||||
goal="Write clear API documentation",
|
||||
backstory="Expert technical writer",
|
||||
skills=["./skills/api-docs-style"], # Writing guidelines and templates
|
||||
# No tools needed — agent writes based on provided context
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 2: Tools Only (Actions, No Special Expertise)
|
||||
|
||||
Use when the agent needs to take action but doesn't need domain-specific instructions:
|
||||
|
||||
```python
|
||||
from crewai_tools import SerperDevTool, ScrapeWebsiteTool
|
||||
|
||||
agent = Agent(
|
||||
role="Web Researcher",
|
||||
goal="Find information about a topic",
|
||||
backstory="Skilled at finding information online",
|
||||
tools=[SerperDevTool(), ScrapeWebsiteTool()], # Can search and scrape
|
||||
# No skills needed — general research doesn't need special guidelines
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 3: Skills + Tools (Expertise AND Actions)
|
||||
|
||||
The most common real-world pattern. The skill provides *how* to approach the work; tools provide *what* the agent can do:
|
||||
|
||||
```python
|
||||
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
|
||||
|
||||
analyst = Agent(
|
||||
role="Security Analyst",
|
||||
goal="Audit infrastructure for vulnerabilities",
|
||||
backstory="Expert in cloud security and compliance",
|
||||
skills=["./skills/security-audit"], # Audit methodology and checklists
|
||||
tools=[
|
||||
SerperDevTool(), # Research known vulnerabilities
|
||||
FileReadTool(), # Read config files
|
||||
CodeInterpreterTool(), # Run analysis scripts
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 4: Skills + MCPs
|
||||
|
||||
Skills work alongside MCP servers the same way they work with tools:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze customer data and generate reports",
|
||||
backstory="Expert data analyst with strong statistical background",
|
||||
skills=["./skills/data-analysis"], # Analysis methodology
|
||||
mcps=["https://data-warehouse.example.com/sse"], # Remote data access
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 5: Skills + Apps
|
||||
|
||||
Skills can guide how an agent uses platform integrations:
|
||||
|
||||
```python
|
||||
agent = Agent(
|
||||
role="Customer Support Agent",
|
||||
goal="Respond to customer inquiries professionally",
|
||||
backstory="Experienced support representative",
|
||||
skills=["./skills/support-playbook"], # Response templates and escalation rules
|
||||
apps=["gmail", "zendesk"], # Can send emails and update tickets
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crew-Level Skills
|
||||
|
||||
Skills can be set on a crew to apply to **all agents**:
|
||||
|
||||
```python
|
||||
from crewai import Crew
|
||||
|
||||
crew = Crew(
|
||||
agents=[researcher, writer, reviewer],
|
||||
tasks=[research_task, write_task, review_task],
|
||||
skills=["./skills"], # All agents get these skills
|
||||
)
|
||||
```
|
||||
|
||||
Agent-level skills take priority — if the same skill is discovered at both levels, the agent's version is used.
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: Short description of what this skill does and when to use it.
|
||||
license: Apache-2.0 # optional
|
||||
compatibility: crewai>=0.1.0 # optional
|
||||
metadata: # optional
|
||||
author: your-name
|
||||
version: "1.0"
|
||||
allowed-tools: web-search file-read # optional, experimental
|
||||
---
|
||||
|
||||
Instructions for the agent go here. This markdown body is injected
|
||||
into the agent's prompt when the skill is activated.
|
||||
```
|
||||
|
||||
### Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
| :-------------- | :------- | :----------------------------------------------------------------------- |
|
||||
| `name` | Yes | 1–64 chars. Lowercase alphanumeric and hyphens. Must match directory name. |
|
||||
| `description` | Yes | 1–1024 chars. Describes what the skill does and when to use it. |
|
||||
| `license` | No | License name or reference to a bundled license file. |
|
||||
| `compatibility` | No | Max 500 chars. Environment requirements (products, packages, network). |
|
||||
| `metadata` | No | Arbitrary string key-value mapping. |
|
||||
| `allowed-tools` | No | Space-delimited list of pre-approved tools. Experimental. |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Required — frontmatter + instructions
|
||||
├── scripts/ # Optional — executable scripts
|
||||
├── references/ # Optional — reference documents
|
||||
└── assets/ # Optional — static files (configs, data)
|
||||
```
|
||||
|
||||
The directory name must match the `name` field in `SKILL.md`. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly.
|
||||
|
||||
---
|
||||
|
||||
## Pre-loading Skills
|
||||
|
||||
For more control, you can discover and activate skills programmatically:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
from crewai.skills import discover_skills, activate_skill
|
||||
|
||||
# Discover all skills in a directory
|
||||
skills = discover_skills(Path("./skills"))
|
||||
|
||||
# Activate them (loads full SKILL.md body)
|
||||
activated = [activate_skill(s) for s in skills]
|
||||
|
||||
# Pass to an agent
|
||||
agent = Agent(
|
||||
role="Researcher",
|
||||
goal="Find relevant information",
|
||||
backstory="An expert researcher.",
|
||||
skills=activated,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Skills Are Loaded
|
||||
|
||||
Skills use **progressive disclosure** — only loading what's needed at each stage:
|
||||
|
||||
| Stage | What's loaded | When |
|
||||
| :--------- | :------------------------------------ | :------------------ |
|
||||
| Discovery | Name, description, frontmatter fields | `discover_skills()` |
|
||||
| Activation | Full SKILL.md body text | `activate_skill()` |
|
||||
|
||||
During normal agent execution (passing directory paths via `skills=["./skills"]`), skills are automatically discovered and activated. The progressive loading only matters when using the programmatic API.
|
||||
|
||||
---
|
||||
|
||||
## Skills vs Knowledge
|
||||
|
||||
Both skills and knowledge modify the agent's prompt, but they serve different purposes:
|
||||
|
||||
| Aspect | Skills | Knowledge |
|
||||
| :--- | :--- | :--- |
|
||||
| **What it provides** | Instructions, procedures, guidelines | Facts, data, information |
|
||||
| **How it's stored** | Markdown files (SKILL.md) | Embedded in vector store (ChromaDB) |
|
||||
| **How it's retrieved** | Entire body injected into prompt | Semantic search finds relevant chunks |
|
||||
| **Best for** | Methodology, checklists, style guides | Company docs, product info, reference data |
|
||||
| **Set via** | `skills=["./skills"]` | `knowledge_sources=[source]` |
|
||||
|
||||
**Rule of thumb:** If the agent needs to follow a *process*, use a skill. If the agent needs to reference *data*, use knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Do I need to set skills AND tools?">
|
||||
It depends on your use case. Skills and tools are **independent** — you can use either, both, or neither.
|
||||
|
||||
- **Skills alone**: When the agent needs expertise but no external actions (e.g., writing with style guidelines)
|
||||
- **Tools alone**: When the agent needs actions but no special methodology (e.g., simple web search)
|
||||
- **Both**: When the agent needs expertise AND actions (e.g., security audit with specific checklists AND ability to scan code)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Do skills automatically provide tools?">
|
||||
**No.** The `allowed-tools` field in SKILL.md is experimental metadata only — it does not provision or inject any tools. You must always set tools separately via `tools=[]`, `mcps=[]`, or `apps=[]`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="What happens if I set the same skill on both an agent and its crew?">
|
||||
The agent-level skill takes priority. Skills are deduplicated by name — the agent's skills are processed first, so if the same skill name appears at both levels, the agent's version is used.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="How large can a SKILL.md body be?">
|
||||
There's a soft warning at 50,000 characters, but no hard limit. Keep skills focused and concise for best results — large prompt injections can dilute the agent's attention.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
1036
docs/edge/en/concepts/tasks.mdx
Normal file
1036
docs/edge/en/concepts/tasks.mdx
Normal file
File diff suppressed because it is too large
Load Diff
49
docs/edge/en/concepts/testing.mdx
Normal file
49
docs/edge/en/concepts/testing.mdx
Normal 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.
|
||||
291
docs/edge/en/concepts/tools.mdx
Normal file
291
docs/edge/en/concepts/tools.mdx
Normal file
@@ -0,0 +1,291 @@
|
||||
---
|
||||
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.
|
||||
|
||||
<Note type="info" title="Tools are one of five agent capability types">
|
||||
Tools give agents **callable functions** to take action. They work alongside [MCPs](/en/mcp/overview) (remote tool servers), [Apps](/en/concepts/agent-capabilities) (platform integrations), [Skills](/en/concepts/skills) (domain expertise), and [Knowledge](/en/concepts/knowledge) (retrieved facts). See the [Agent Capabilities](/en/concepts/agent-capabilities) overview to understand when to use each.
|
||||
</Note>
|
||||
|
||||
## 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** | Search the web with Exa, the fastest and most accurate web search API. Supports token-efficient highlights and full page content. |
|
||||
| **FileReadTool** | Enables reading and extracting data from files, supporting various file formats. |
|
||||
| **FirecrawlSearchTool** | A tool to search webpages using Firecrawl and return the results. |
|
||||
| **FirecrawlCrawlWebsiteTool** | A tool for crawling webpages using Firecrawl. |
|
||||
| **FirecrawlScrapeWebsiteTool** | A tool for scraping webpages URL using Firecrawl and returning its contents. |
|
||||
| **GithubSearchTool** | A RAG tool for searching within GitHub repositories, useful for code and documentation search. |
|
||||
| **SerperDevTool** | A specialized tool for development purposes, with specific functionalities under development. |
|
||||
| **TXTSearchTool** | A RAG tool focused on searching within text (.txt) files, suitable for unstructured data. |
|
||||
| **JSONSearchTool** | A RAG tool designed for searching within JSON files, catering to structured data handling. |
|
||||
| **LlamaIndexTool** | Enables the use of LlamaIndex tools. |
|
||||
| **MDXSearchTool** | A RAG tool tailored for searching within Markdown (MDX) files, useful for documentation. |
|
||||
| **PDFSearchTool** | A RAG tool aimed at searching within PDF documents, ideal for processing scanned documents. |
|
||||
| **PGSearchTool** | A RAG tool optimized for searching within PostgreSQL databases, suitable for database queries. |
|
||||
| **Vision Tool** | A tool for generating images using the DALL-E API. |
|
||||
| **RagTool** | A general-purpose RAG tool capable of handling various data sources and types. |
|
||||
| **ScrapeElementFromWebsiteTool** | Enables scraping specific elements from websites, useful for targeted data extraction. |
|
||||
| **ScrapeWebsiteTool** | Facilitates scraping entire websites, ideal for comprehensive data collection. |
|
||||
| **WebsiteSearchTool** | A RAG tool for searching website content, optimized for web data extraction. |
|
||||
| **XMLSearchTool** | A RAG tool designed for searching within XML files, suitable for structured data formats. |
|
||||
| **YoutubeChannelSearchTool** | A RAG tool for searching within YouTube channels, useful for video content analysis. |
|
||||
| **YoutubeVideoSearchTool** | A RAG tool aimed at searching within YouTube videos, ideal for video data extraction. |
|
||||
|
||||
## Creating your own Tools
|
||||
|
||||
<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/edge/en/concepts/training.mdx
Normal file
197
docs/edge/en/concepts/training.mdx
Normal 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, pass that path with `Crew(trained_agents_file="my_custom_trained.pkl")`, set `CREWAI_TRAINED_AGENTS_FILE`, or use `crewai run -f my_custom_trained.pkl`.
|
||||
- You can change the output filename when calling `crewai train` with `-f/--filename`. Absolute paths are supported if you want to save outside the CWD.
|
||||
|
||||
It is important to note that the training process may take some time, depending on the complexity of your agents and will also require your feedback on each iteration.
|
||||
|
||||
Once the training is complete, your agents will be equipped with enhanced capabilities and knowledge, ready to tackle complex tasks and provide more consistent and valuable insights.
|
||||
|
||||
Remember to regularly update and retrain your agents to ensure they stay up-to-date with the latest information and advancements in the field.
|
||||
227
docs/edge/en/enterprise/features/a2a.mdx
Normal file
227
docs/edge/en/enterprise/features/a2a.mdx
Normal file
@@ -0,0 +1,227 @@
|
||||
---
|
||||
title: A2A on AMP
|
||||
description: Production-grade Agent-to-Agent communication with distributed state and multi-scheme authentication
|
||||
icon: "network-wired"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Warning>
|
||||
A2A server agents on AMP are in early release. APIs may change in future versions.
|
||||
</Warning>
|
||||
|
||||
## Overview
|
||||
|
||||
CrewAI AMP extends the open-source [A2A protocol implementation](/en/learn/a2a-agent-delegation) with production infrastructure for deploying distributed agents at scale. AMP supports A2A protocol versions 0.2 and 0.3. When you deploy a crew or agent with A2A server configuration to AMP, the platform automatically provisions distributed state management, authentication, multi-transport endpoints, and lifecycle management.
|
||||
|
||||
<Note>
|
||||
For A2A protocol fundamentals, client/server configuration, and authentication schemes, see the [A2A Agent Delegation](/en/learn/a2a-agent-delegation) documentation. This page covers what AMP adds on top of the open-source implementation.
|
||||
</Note>
|
||||
|
||||
### Usage
|
||||
|
||||
Add `A2AServerConfig` to any agent in your crew and deploy to AMP. The platform detects agents with server configuration and automatically registers A2A endpoints, generates agent cards, and provisions the infrastructure described below.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Task
|
||||
from crewai.a2a import A2AServerConfig
|
||||
from crewai.a2a.auth import EnterpriseTokenAuth
|
||||
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze datasets and provide insights",
|
||||
backstory="Expert data scientist with statistical analysis skills",
|
||||
llm="gpt-4o",
|
||||
a2a=A2AServerConfig(
|
||||
auth=EnterpriseTokenAuth()
|
||||
)
|
||||
)
|
||||
|
||||
task = Task(
|
||||
description="Analyze the provided dataset",
|
||||
expected_output="Statistical summary with key insights",
|
||||
agent=agent
|
||||
)
|
||||
|
||||
crew = Crew(agents=[agent], tasks=[task])
|
||||
```
|
||||
|
||||
After [deploying to AMP](/en/enterprise/guides/deploy-to-amp), the platform registers two levels of A2A endpoints:
|
||||
|
||||
- **Crew-level**: an aggregate agent card at `/.well-known/agent-card.json` where each agent with `A2AServerConfig` is listed as a skill, with a JSON-RPC endpoint at `/a2a`
|
||||
- **Per-agent**: isolated agent cards and JSON-RPC endpoints mounted at `/a2a/agents/{role}/`, each with its own tenancy
|
||||
|
||||
Clients can interact with the crew as a whole or target a specific agent directly. To route a request to a specific agent through the crew-level endpoint, include `"target_agent"` in the message metadata with the agent's slugified role name (e.g., `"data-analyst"` for an agent with role `"Data Analyst"`). If no `target_agent` is provided, the request is handled by the first agent in the crew.
|
||||
|
||||
See [A2A Agent Delegation](/en/learn/a2a-agent-delegation#server-configuration-options) for the full list of `A2AServerConfig` options.
|
||||
|
||||
<Warning>
|
||||
Per the A2A protocol, agent cards are publicly accessible to enable discovery. This includes both the crew-level card at `/.well-known/agent-card.json` and per-agent cards at `/a2a/agents/{role}/.well-known/agent-card.json`. Do not include sensitive information in agent names, descriptions, or skill definitions.
|
||||
</Warning>
|
||||
|
||||
### File Inputs and Structured Output
|
||||
|
||||
A2A on AMP supports passing files and requesting structured output in both directions. Clients can send files as `FilePart`s and request structured responses by embedding a JSON schema in the message. Server agents receive files as `input_files` on the task, and return structured data as `DataPart`s when a schema is provided. See [File Inputs and Structured Output](/en/learn/a2a-agent-delegation#file-inputs-and-structured-output) for details.
|
||||
|
||||
### What AMP Adds
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Distributed State" icon="database">
|
||||
Persistent task, context, and result storage
|
||||
</Card>
|
||||
<Card title="Enterprise Authentication" icon="shield-halved">
|
||||
OIDC, OAuth2, mTLS, and Enterprise token validation beyond simple bearer tokens
|
||||
</Card>
|
||||
<Card title="gRPC Transport" icon="bolt">
|
||||
Full gRPC server with TLS and authentication
|
||||
</Card>
|
||||
<Card title="Context Lifecycle" icon="clock-rotate-left">
|
||||
Automatic idle detection, expiration, and cleanup of long-running conversations
|
||||
</Card>
|
||||
<Card title="Signed Webhooks" icon="signature">
|
||||
HMAC-SHA256 signed push notifications with replay protection
|
||||
</Card>
|
||||
<Card title="Multi-Transport" icon="arrows-split-up-and-left">
|
||||
REST, JSON-RPC, and gRPC endpoints served simultaneously from a single deployment
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
---
|
||||
|
||||
## Distributed State Management
|
||||
|
||||
In the open-source implementation, task and context state lives in memory on a single process. AMP replaces this with persistent, distributed stores.
|
||||
|
||||
### Storage Layers
|
||||
|
||||
| Store | Purpose |
|
||||
|---|---|
|
||||
| **Task Store** | Persists A2A task state and metadata |
|
||||
| **Context Store** | Tracks conversation context, creation time, last activity, and associated tasks |
|
||||
| **Result Store** | Caches task results for retrieval |
|
||||
| **Push Config Store** | Manages webhook subscriptions per task |
|
||||
|
||||
Multiple A2A deployments are automatically isolated from each other, preventing data collisions when sharing infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## Enterprise Authentication
|
||||
|
||||
AMP supports six authentication schemes for incoming A2A requests, configurable per deployment. Authentication works across both HTTP and gRPC transports.
|
||||
|
||||
| Scheme | Description | Use Case |
|
||||
|---|---|---|
|
||||
| **SimpleTokenAuth** | Static bearer token from `AUTH_TOKEN` env var | Development, simple deployments |
|
||||
| **EnterpriseTokenAuth** | Token verification via CrewAI PlusAPI with integration token claims | AMP-to-AMP agent communication |
|
||||
| **OIDCAuth** | OpenID Connect JWT validation with JWKS endpoint caching | Enterprise SSO integration |
|
||||
| **OAuth2ServerAuth** | OAuth2 with configurable scopes | Fine-grained access control |
|
||||
| **APIKeyServerAuth** | API key validation via header or query parameter | Third-party integrations |
|
||||
| **MTLSServerAuth** | Mutual TLS certificate-based authentication | Zero-trust environments |
|
||||
|
||||
The configured auth scheme automatically populates the agent card's `securitySchemes` and `security` fields. Clients discover authentication requirements by fetching the agent card before making requests.
|
||||
|
||||
---
|
||||
|
||||
## Extended Agent Cards
|
||||
|
||||
AMP supports role-based skill visibility through extended agent cards. Unauthenticated users see the standard agent card with public skills. Authenticated users receive an extended card with additional capabilities.
|
||||
|
||||
This enables patterns like:
|
||||
- Public agents that expose basic skills to anyone, with advanced skills available to authenticated clients
|
||||
- Internal agents that advertise different capabilities based on the caller's identity
|
||||
|
||||
---
|
||||
|
||||
## gRPC Transport
|
||||
|
||||
If enabled, AMP provides full gRPC support alongside the default JSON-RPC transport.
|
||||
|
||||
- **TLS termination** with configurable certificate and key paths
|
||||
- **gRPC reflection** for debugging with tools like `grpcurl`
|
||||
- **Authentication** using the same schemes available for HTTP
|
||||
- **Extension validation** ensuring clients support required protocol extensions
|
||||
- **Version negotiation** across A2A protocol versions 0.2 and 0.3
|
||||
|
||||
For deployments exposing multiple agents, AMP automatically allocates per-agent gRPC ports and coordinates TLS, startup, and shutdown across all servers.
|
||||
|
||||
---
|
||||
|
||||
## Context Lifecycle Management
|
||||
|
||||
AMP tracks the lifecycle of A2A conversation contexts and automatically manages cleanup.
|
||||
|
||||
### Lifecycle States
|
||||
|
||||
| State | Condition | Action |
|
||||
|---|---|---|
|
||||
| **Active** | Context has recent activity | None |
|
||||
| **Idle** | No activity for a configured period | Marked idle, event emitted |
|
||||
| **Expired** | Context exceeds its maximum lifetime | Marked expired, associated tasks cleaned up, event emitted |
|
||||
|
||||
A background cleanup task runs hourly to scan for idle and expired contexts. All state transitions emit CrewAI events that integrate with the platform's observability features.
|
||||
|
||||
---
|
||||
|
||||
## Signed Push Notifications
|
||||
|
||||
When an A2A agent sends push notifications to a client webhook, AMP signs each request with HMAC-SHA256 to ensure integrity and prevent tampering.
|
||||
|
||||
### Signature Headers
|
||||
|
||||
| Header | Purpose |
|
||||
|---|---|
|
||||
| `X-A2A-Signature` | HMAC-SHA256 signature in `sha256={hex_digest}` format |
|
||||
| `X-A2A-Signature-Timestamp` | Unix timestamp bound to the signature |
|
||||
| `X-A2A-Notification-Token` | Optional notification auth token |
|
||||
|
||||
### Security Properties
|
||||
|
||||
- **Integrity**: payload cannot be modified without invalidating the signature
|
||||
- **Replay protection**: signatures are timestamp-bound with a configurable tolerance window
|
||||
- **Retry with backoff**: failed deliveries retry with exponential backoff
|
||||
|
||||
---
|
||||
|
||||
## Distributed Event Streaming
|
||||
|
||||
In the open-source implementation, SSE streaming works within a single process. AMP propagates SSE events across instances so that clients receive updates even when the instance holding the streaming connection differs from the instance executing the task.
|
||||
|
||||
---
|
||||
|
||||
## Multi-Transport Endpoints
|
||||
|
||||
AMP serves REST and JSON-RPC by default. gRPC is available as an additional transport if enabled.
|
||||
|
||||
| Transport | Path Convention | Description |
|
||||
|---|---|---|
|
||||
| **REST** | `/v1/message:send`, `/v1/message:stream`, `/v1/tasks` | Google API conventions |
|
||||
| **JSON-RPC** | Standard A2A JSON-RPC endpoint | Default A2A protocol transport |
|
||||
| **gRPC** | Per-agent port allocation | Optional, high-performance binary protocol |
|
||||
|
||||
All active transports share the same authentication, version negotiation, and extension validation. Agent cards are generated from agent and crew metadata — roles, goals, and tools become skills and descriptions — and automatically include interfaces for each active transport. They can also be manually configured via `A2AServerConfig`.
|
||||
|
||||
---
|
||||
|
||||
## Version and Extension Negotiation
|
||||
|
||||
AMP validates A2A protocol versions and extensions at the transport layer.
|
||||
|
||||
### Version Negotiation
|
||||
|
||||
- Clients send the `A2A-Version` header with their preferred version
|
||||
- AMP validates against supported versions (0.2, 0.3) and falls back to 0.3 if unspecified
|
||||
- The negotiated version is returned in the response headers
|
||||
|
||||
### Extension Validation
|
||||
|
||||
- Clients declare supported extensions via the `X-A2A-Extensions` header
|
||||
- AMP validates that clients support all extensions the agent requires
|
||||
- Requests from clients missing required extensions receive an `UnsupportedExtensionError`
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — A2A protocol fundamentals and configuration
|
||||
- [A2UI](/en/learn/a2ui) — Interactive UI rendering over A2A
|
||||
- [Deploy to AMP](/en/enterprise/guides/deploy-to-amp) — General deployment guide
|
||||
- [Webhook Streaming](/en/enterprise/features/webhook-streaming) — Event streaming for deployed automations
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: "Watch your Automations"
|
||||
description: "Watch fleet health, LLM consumption, and per-automation behavior from the Automations tab."
|
||||
sidebarTitle: "Monitoring"
|
||||
icon: "gauge"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**ACP (Beta) Docs Navigation**
|
||||
|
||||
- [Overview](/en/enterprise/features/agent-control-plane/overview)
|
||||
- **Monitoring** *(you are here)*
|
||||
- [Rules](/en/enterprise/features/agent-control-plane/rules)
|
||||
</Info>
|
||||
|
||||
## Overview
|
||||
|
||||
The **Automations** tab is the read-only operations view of the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview). It combines two metric cards, an interactive sankey, and two sub-tables — **Automations** and **Consumption** — that you can search, filter, and sort.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
All charts and tables respect the **Last 24 hours / Last Week / Last 30 days** selector at the top right. Deltas compare the selected window against the previous one of the same length.
|
||||
|
||||
<Note>
|
||||
Rows only show data for deployments on **crewAI v1.13 or higher** — older deployments appear in the *"We've detected N other automations that we can't display"* banner under the sankey and contribute zero metrics until they're updated and re-deployed. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements).
|
||||
</Note>
|
||||
|
||||
## Dashboard
|
||||
|
||||
The header of the page has two metric cards and an interactive sankey. Clicking either card switches the sankey between two modes:
|
||||
|
||||
- **Health mode** — `Total Automations → status buckets (Critical / Warning / Healthy)`. Click a bucket to filter the Automations table to just those deployments.
|
||||
- **Consumption mode** — `Model Providers → Automations → Total Cost`. Click a provider to filter the Consumption table to that provider.
|
||||
|
||||
| Card | What it shows |
|
||||
|------|---------------|
|
||||
| **Automations** | `active` automations (and total count), total `errors` in the window, currently `active executions` (and total in the window), with a delta vs the previous period. |
|
||||
| **Consumption** | Total `cost` and `tokens used`, with a cost delta vs the previous period. |
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Automations table
|
||||
|
||||
The **Automations** sub-tab is the per-deployment breakdown of fleet health. Each row is one deployed crew or flow.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| Column | What it shows |
|
||||
|--------|---------------|
|
||||
| **Automation** | Deployment name and any tags assigned to it (e.g. `production`, `financial`). |
|
||||
| **Last execution** | Time since the most recent run. |
|
||||
| **Health Status Breakdown** | Stacked bar of `Critical` / `Warning` / `Healthy` percentages for executions in the window. |
|
||||
| **Executions with Errors** | Total failed executions in the window. |
|
||||
| **PII detection applied** | `Yes` if a per-deployment PII config or a matching [PII rule](/en/enterprise/features/agent-control-plane/rules) is active. |
|
||||
| **Executions** | Total executions in the window. |
|
||||
| **Last updated** | When the deployment was last re-deployed. |
|
||||
| **Crew Version** | The `crewai` version reported by the deployment. An info icon next to versions below `1.13` flags rows that can't contribute metrics. |
|
||||
|
||||
Search by name, filter by `Status` (`Healthy` / `Warning` / `Critical`), and sort by any column header. Click a deployment name to open the **Automation panel** (see below).
|
||||
|
||||
## Consumption table
|
||||
|
||||
The **Consumption** sub-tab is the per-deployment breakdown of LLM spend and token usage.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
| Column | What it shows |
|
||||
|--------|---------------|
|
||||
| **Automation** | Deployment name. |
|
||||
| **Last execution** | Time since the most recent run. |
|
||||
| **Tokens used** | One row per LLM provider used by this automation, with the delta vs the previous period. |
|
||||
| **Cost** | Cost per LLM provider, with the delta vs the previous period. |
|
||||
| **Total cost** | Sum across all providers, with the delta. |
|
||||
| **Executions** | Total executions in the window. |
|
||||
| **Last updated** | When the deployment was last re-deployed. |
|
||||
| **Crew Version** | The `crewai` version reported by the deployment. |
|
||||
|
||||
Filter by **LLM provider** and sort by `Cost`, `Executions`, or `Last run`.
|
||||
|
||||
<Info>
|
||||
**Empty cells (`—` or `$0.00`) usually mean the deployment is below crewAI v1.13.** In the screenshot above, *Automation F* (`1.7.0`) and *Automation I* (`1.12.2`) show blanks for tokens and cost — their executions still run, but they don't emit the provider-level telemetry that powers this table. Update and re-deploy these crews to start collecting consumption data.
|
||||
</Info>
|
||||
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent Control Plane — Overview" icon="book-open" href="/en/enterprise/features/agent-control-plane/overview">
|
||||
What ACP is, requirements, plan tiers, and RBAC.
|
||||
</Card>
|
||||
<Card title="Agent Control Plane — Rules" icon="shield-check" href="/en/enterprise/features/agent-control-plane/rules">
|
||||
Apply organization-wide PII Redaction rules across many automations.
|
||||
</Card>
|
||||
<Card title="Traces" icon="timeline" href="/en/enterprise/features/traces">
|
||||
Drill into a single execution to see agent reasoning, tool calls, and token usage.
|
||||
</Card>
|
||||
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
|
||||
Deploy a crew on a crewAI version that supports the Agent Control Plane.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
|
||||
Contact our support team for help interpreting metrics in the Agent Control Plane.
|
||||
</Card>
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Agent Control Plane Overview
|
||||
description: "Single operations hub for live automations — fleet health, LLM consumption, and organization-wide policies in one place."
|
||||
sidebarTitle: Overview
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**ACP (Beta) Docs Navigation**
|
||||
|
||||
- **Overview** *(you are here)*
|
||||
- [Monitoring](/en/enterprise/features/agent-control-plane/monitoring)
|
||||
- [Rules](/en/enterprise/features/agent-control-plane/rules)
|
||||
</Info>
|
||||
|
||||
## Overview
|
||||
|
||||
The **Agent Control Plane** (ACP) is the operations hub for everything you have running on CrewAI AMP. It is a single screen — split into **Automations** and **Rules** tabs — that lets your team:
|
||||
|
||||
- Monitor the **health** of every live automation (crew or flow), with `Critical` / `Warning` / `Healthy` breakdowns and execution counts.
|
||||
- Track **LLM consumption** — tokens and cost — per automation, per provider, and per model, with a delta vs the previous period.
|
||||
- Drill into any single automation or model provider for time-series charts and per-provider breakdowns.
|
||||
- Apply organization-wide **Rules** (today: PII Redaction) across many automations at once instead of editing each deployment individually.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Note>
|
||||
The Agent Control Plane is currently labeled **Beta** in CrewAI Platform.
|
||||
</Note>
|
||||
|
||||
The two tabs answer two different questions:
|
||||
|
||||
- **Automations** — *"How is my fleet behaving right now, and what is it costing me?"* See [Monitoring](/en/enterprise/features/agent-control-plane/monitoring).
|
||||
- **Rules** — *"How do I enforce a policy (e.g. PII redaction) across many deployments without re-deploying each one?"* See [Rules](/en/enterprise/features/agent-control-plane/rules).
|
||||
|
||||
## Requirements
|
||||
|
||||
<Warning>
|
||||
**crewAI v1.13 or higher** is required for an automation to populate any data on this page — health, executions, errors, tokens, and cost all flow through telemetry that lit up in `crewai==1.13`. Older deployments appear in the *"We've detected N other automations that we can't display"* banner and contribute zero rows until they are updated and re-deployed.
|
||||
</Warning>
|
||||
|
||||
<Warning>
|
||||
**Enterprise Plan or Ultra Plan** is required to create or edit [Rules](/en/enterprise/features/agent-control-plane/rules). Lower-tier organizations can open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* Monitoring (the Automations tab) is available on all plans where the feature is enabled.
|
||||
</Warning>
|
||||
|
||||
- The **Agent Control Plane** feature must be enabled for your organization. If you don't see it in the sidebar, ask your account owner to request enablement.
|
||||
- Inside ACP, [RBAC](/en/enterprise/features/rbac) governs access: `read` to view the dashboard and rules, `manage` to create, edit, toggle, or delete rules.
|
||||
- All charts and tables can be scoped to the **Last 24 hours**, **Last Week**, or **Last 30 days** using the time selector at the top right. Deltas (`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday`, etc.) compare the selected window against the previous one of the same length.
|
||||
|
||||
## What you can do here
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Monitoring" icon="gauge" href="/en/enterprise/features/agent-control-plane/monitoring">
|
||||
Watch fleet health and LLM spend with metric cards, an interactive sankey, per-automation tables, and drill-down side panels for any automation or provider.
|
||||
</Card>
|
||||
<Card title="Rules" icon="shield-check" href="/en/enterprise/features/agent-control-plane/rules">
|
||||
Apply organization-wide PII Redaction policies scoped by tools and tags. Changes take effect on the next execution — no re-deploy required.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Traces" icon="timeline" href="/en/enterprise/features/traces">
|
||||
Drill into a single execution to see agent reasoning, tool calls, and token usage.
|
||||
</Card>
|
||||
<Card title="RBAC" icon="users" href="/en/enterprise/features/rbac">
|
||||
Manage who can read the Agent Control Plane and who can edit rules.
|
||||
</Card>
|
||||
<Card title="PII Redaction for Traces" icon="lock" href="/en/enterprise/features/pii-trace-redactions">
|
||||
Entity catalog and per-deployment PII configuration referenced by Rules.
|
||||
</Card>
|
||||
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
|
||||
Deploy a crew on a crewAI version that supports the Agent Control Plane.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
|
||||
Contact our support team for help interpreting metrics or designing rules.
|
||||
</Card>
|
||||
122
docs/edge/en/enterprise/features/agent-control-plane/rules.mdx
Normal file
122
docs/edge/en/enterprise/features/agent-control-plane/rules.mdx
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
title: "Set up the Rules"
|
||||
description: "Apply organization-wide policies across many automations from a single place."
|
||||
sidebarTitle: "Rules"
|
||||
icon: "shield-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Info>
|
||||
**ACP (Beta) Docs Navigation**
|
||||
|
||||
- [Overview](/en/enterprise/features/agent-control-plane/overview)
|
||||
- [Monitoring](/en/enterprise/features/agent-control-plane/monitoring)
|
||||
- **Rules** *(you are here)*
|
||||
</Info>
|
||||
|
||||
## Overview
|
||||
|
||||
Rules let you apply policies — today: **PII Redaction** — across many automations at once, instead of configuring each deployment individually. Open the **Rules** tab in the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview) to manage them.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
Each rule card shows the name, description, the **scope** the rule applies to (selected tools and tags), and a count of **engaged automations** — deployments that currently match the scope. The toggle on the right enables or disables the rule without deleting it.
|
||||
|
||||
## Requirements
|
||||
|
||||
<Warning>
|
||||
**Enterprise Plan or Ultra Plan** is required to create or edit PII Redaction rules. Lower-tier organizations can still open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* — contact your account owner or sales to upgrade.
|
||||
</Warning>
|
||||
|
||||
- The **Agent Control Plane** feature must be enabled for your organization. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements).
|
||||
- The `manage` [RBAC permission](/en/enterprise/features/rbac) on Agent Control Plane is required to create, edit, toggle, or delete rules. The `read` permission is enough to view them.
|
||||
- All rule changes are versioned for auditing.
|
||||
|
||||
## Available rule types
|
||||
|
||||
| Type | What it does |
|
||||
|------|---------------|
|
||||
| **PII Redaction** | Applies PII redaction to executions of every matching automation, using the same entity catalog and custom recognizers documented in [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions). |
|
||||
|
||||
More rule types will be added over time.
|
||||
|
||||
## Creating a rule
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/acp-rules-edit-side-panel.png" alt="Rule edit side panel with conditions and PII mask type" width="450" />
|
||||
</Frame>
|
||||
|
||||
<Steps>
|
||||
<Step title="Open the editor">
|
||||
Click **+ Create new** at the top-right of the Rules tab, or **View Details** on an existing rule card.
|
||||
</Step>
|
||||
|
||||
<Step title="Name and describe the rule">
|
||||
Give the rule a clear name (e.g. *Mask PII (CC)*) and a description explaining when it applies. Both show up on the rule card and in the Engaged Automations modal.
|
||||
</Step>
|
||||
|
||||
<Step title="Pick the type">
|
||||
Today only **PII Redaction** is available.
|
||||
</Step>
|
||||
|
||||
<Step title="Set the conditions">
|
||||
Conditions decide which automations the rule engages with. Both are optional and use **set-equality** semantics:
|
||||
|
||||
- **Tools** — only automations whose tool set **exactly matches** the selected tools will engage. Picks from Studio apps, MCPs, OSS tools, and Tool Repository registry tools.
|
||||
- **Automations** — only automations whose tag set **exactly matches** the selected tags will engage.
|
||||
|
||||
Leaving a picker empty means "no filter on this dimension". Leaving both empty means the rule applies to **every** automation in the organization.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure the PII Mask Type table">
|
||||
Check each entity type you want covered and choose **Mask** (replaces with the entity label, e.g. `<CREDIT_CARD>`) or **Redact** (removes the matched text entirely). See [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions) for the full entity catalog and how to add organization-level custom recognizers.
|
||||
</Step>
|
||||
|
||||
<Step title="Save">
|
||||
The rule applies to **future** executions of every engaged automation as soon as you save. No re-deploy is needed.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Engaged automations
|
||||
|
||||
Click **Engaged N automations** on any rule card to see exactly which deployments the rule is currently matching, along with each one's last execution.
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
This is the fastest way to sanity-check a rule's scope before enabling it — for example, to confirm that a rule scoped to the `production` tag isn't accidentally matching a staging deployment.
|
||||
|
||||
## Org-wide rules vs per-deployment settings
|
||||
|
||||
PII Redaction can be configured in two places:
|
||||
|
||||
- **Per-deployment** — under **Settings → PII Protection** on each individual deployment ([guide](/en/enterprise/features/pii-trace-redactions))
|
||||
- **Org-wide** — as a Rule on this page
|
||||
|
||||
When an enabled org-wide rule's scope matches a deployment, the rule's entity configuration **overrides** the deployment-owned PII settings for that deployment's executions — the rule becomes the single source of truth while it's attached. Disable or detach the rule (or change its scope so it no longer matches) and the deployment falls back to its own PII Protection settings.
|
||||
|
||||
Prefer org-wide rules when you want to enforce a consistent policy across many deployments; reserve per-deployment configuration for one-off exceptions.
|
||||
|
||||
## Related
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Agent Control Plane — Overview" icon="book-open" href="/en/enterprise/features/agent-control-plane/overview">
|
||||
What ACP is, requirements, plan tiers, and RBAC.
|
||||
</Card>
|
||||
<Card title="Agent Control Plane — Monitoring" icon="gauge" href="/en/enterprise/features/agent-control-plane/monitoring">
|
||||
Monitor automations and LLM consumption across your fleet.
|
||||
</Card>
|
||||
<Card title="PII Redaction for Traces" icon="lock" href="/en/enterprise/features/pii-trace-redactions">
|
||||
Entity catalog, custom recognizers, and per-deployment configuration.
|
||||
</Card>
|
||||
<Card title="RBAC" icon="users" href="/en/enterprise/features/rbac">
|
||||
Manage who can create or edit rules.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
|
||||
Contact our support team for help designing rules for your organization.
|
||||
</Card>
|
||||
155
docs/edge/en/enterprise/features/agent-repositories.mdx
Normal file
155
docs/edge/en/enterprise/features/agent-repositories.mdx
Normal 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>
|
||||
|
||||
</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>
|
||||
|
||||
</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/edge/en/enterprise/features/automations.mdx
Normal file
104
docs/edge/en/enterprise/features/automations.mdx
Normal 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>
|
||||
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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/edge/en/enterprise/features/crew-studio.mdx
Normal file
88
docs/edge/en/enterprise/features/crew-studio.mdx
Normal 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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</Frame>
|
||||
|
||||
## Publish & Export
|
||||
|
||||
- <b>Publish</b> to deploy a live automation
|
||||
- <b>Download</b> source as a ZIP for local development or customization
|
||||
|
||||
<Frame>
|
||||
|
||||
</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>
|
||||
|
||||
</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/edge/en/enterprise/features/flow-hitl-management.mdx
Normal file
558
docs/edge/en/enterprise/features/flow-hitl-management.mdx
Normal 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/edge/en/enterprise/features/hallucination-guardrail.mdx
Normal file
251
docs/edge/en/enterprise/features/hallucination-guardrail.mdx
Normal 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/edge/en/enterprise/features/marketplace.mdx
Normal file
46
docs/edge/en/enterprise/features/marketplace.mdx
Normal 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>
|
||||
|
||||
</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>
|
||||
|
||||
</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/edge/en/enterprise/features/pii-trace-redactions.mdx
Normal file
342
docs/edge/en/enterprise/features/pii-trace-redactions.mdx
Normal 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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
256
docs/edge/en/enterprise/features/rbac.mdx
Normal file
256
docs/edge/en/enterprise/features/rbac.mdx
Normal file
@@ -0,0 +1,256 @@
|
||||
---
|
||||
title: "Role-Based Access Control (RBAC)"
|
||||
description: "Control access to crews, tools, and data with roles, scopes, and granular permissions."
|
||||
icon: "shield"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
RBAC in CrewAI AMP enables secure, scalable access management through two layers:
|
||||
|
||||
1. **Feature permissions** — control what each role can do across the platform (manage, read, or no access)
|
||||
2. **Entity-level permissions** — fine-grained access on individual automations, environment variables, LLM connections, and Git repositories
|
||||
|
||||
<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>
|
||||
|
||||
### Predefined Roles
|
||||
|
||||
| Role | Description |
|
||||
| :--------- | :-------------------------------------------------------------------------- |
|
||||
| **Owner** | Full access to all features and settings. Cannot be restricted. |
|
||||
| **Member** | Read access to most features, manage access to environment variables, LLM connections, and Studio projects. Cannot modify organization or default settings. |
|
||||
|
||||
### Configuration summary
|
||||
|
||||
| Area | Where to configure | Options |
|
||||
| :-------------------- | :--------------------------------- | :-------------------------------------- |
|
||||
| Users & Roles | Settings → Roles | Predefined: Owner, Member; Custom roles |
|
||||
| Automation visibility | Automation → Settings → Visibility | Private; Whitelist users/roles |
|
||||
|
||||
---
|
||||
|
||||
## Feature Permissions Matrix
|
||||
|
||||
Every role has a permission level for each feature area. The three levels are:
|
||||
|
||||
- **Manage** — full read/write access (create, edit, delete)
|
||||
- **Read** — view-only access
|
||||
- **No access** — feature is hidden/inaccessible
|
||||
|
||||
| Feature | Owner | Member (default) | Available levels | Description |
|
||||
| :------------------------ | :------ | :--------------- | :------------------------ | :-------------------------------------------------------------- |
|
||||
| `usage_dashboards` | Manage | Read | Manage / Read / No access | View usage metrics and analytics |
|
||||
| `crews_dashboards` | Manage | Read | Manage / Read / No access | View deployment dashboards, access automation details |
|
||||
| `invitations` | Manage | Read | Manage / Read / No access | Invite new members to the organization |
|
||||
| `training_ui` | Manage | Read | Manage / Read / No access | Access training/fine-tuning interfaces |
|
||||
| `tools` | Manage | Read | Manage / Read / No access | Create and manage tools |
|
||||
| `agents` | Manage | Read | Manage / Read / No access | Create and manage agents |
|
||||
| `environment_variables` | Manage | Manage | Manage / No access | Create and manage environment variables |
|
||||
| `llm_connections` | Manage | Manage | Manage / No access | Configure LLM provider connections |
|
||||
| `default_settings` | Manage | No access | Manage / No access | Modify organization-wide default settings |
|
||||
| `organization_settings` | Manage | No access | Manage / No access | Manage billing, plans, and organization configuration |
|
||||
| `studio_projects` | Manage | Manage | Manage / No access | Create and edit projects in Studio |
|
||||
|
||||
<Tip>
|
||||
When creating a custom role, most features can be set to **Manage**, **Read**, or **No access**. However, `environment_variables`, `llm_connections`, `default_settings`, `organization_settings`, and `studio_projects` only support **Manage** or **No access** — there is no read-only option for these features.
|
||||
</Tip>
|
||||
|
||||
---
|
||||
|
||||
## Deploying from GitHub or Zip
|
||||
|
||||
One of the most common RBAC questions is: _"What permissions does a team member need to deploy?"_
|
||||
|
||||
### Deploy from GitHub
|
||||
|
||||
To deploy an automation from a GitHub repository, a user needs:
|
||||
|
||||
1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard where deployments are created
|
||||
2. **Git repository access** (if entity-level RBAC for Git repositories is enabled): the user's role must be granted access to the specific Git repository via entity-level permissions
|
||||
3. **`studio_projects`: `Manage`** — if building the crew in Studio before deploying
|
||||
|
||||
### Deploy from Zip
|
||||
|
||||
To deploy an automation from a Zip file upload, a user needs:
|
||||
|
||||
1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard
|
||||
2. **Zip deployments enabled**: the organization must not have disabled zip deployments in organization settings
|
||||
|
||||
### Quick Reference: Minimum Permissions for Deployment
|
||||
|
||||
| Action | Required feature permissions | Additional requirements |
|
||||
| :------------------- | :------------------------------------ | :----------------------------------------------- |
|
||||
| Deploy from GitHub | `crews_dashboards: Read` | Git repo entity access (if Git RBAC is enabled) |
|
||||
| Deploy from Zip | `crews_dashboards: Read` | Zip deployments must be enabled at the org level |
|
||||
| Build in Studio | `studio_projects: Manage` | — |
|
||||
| Configure LLM keys | `llm_connections: Manage` | — |
|
||||
| Set environment vars | `environment_variables: Manage` | Entity-level access (if entity RBAC is enabled) |
|
||||
|
||||
---
|
||||
|
||||
## Automation‑level Access Control (Entity Permissions)
|
||||
|
||||
In addition to organization‑wide roles, CrewAI supports fine‑grained entity-level permissions that restrict access to individual resources.
|
||||
|
||||
### Automation Visibility
|
||||
|
||||
Automations support visibility settings that restrict access by user or role. This is useful for:
|
||||
|
||||
- Keeping sensitive or experimental automations private
|
||||
- Managing visibility across large teams or external collaborators
|
||||
- Testing automations in isolated contexts
|
||||
|
||||
Deployments can be configured as private, meaning only whitelisted users and roles will be able to interact with them.
|
||||
|
||||
You can configure automation‑level access control in Automation → Settings → Visibility tab.
|
||||
|
||||
<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>
|
||||
|
||||
### Deployment Permission Types
|
||||
|
||||
When granting entity-level access to a specific automation, you can assign these permission types:
|
||||
|
||||
| Permission | What it allows |
|
||||
| :------------------- | :-------------------------------------------------- |
|
||||
| `run` | Execute the automation and use its API |
|
||||
| `traces` | View execution traces and logs |
|
||||
| `manage_settings` | Edit, redeploy, rollback, or delete the automation |
|
||||
| `human_in_the_loop` | Respond to human-in-the-loop (HITL) requests |
|
||||
| `full_access` | All of the above |
|
||||
|
||||
### Entity-level RBAC for Other Resources
|
||||
|
||||
When entity-level RBAC is enabled, access to these resources can also be controlled per user or role:
|
||||
|
||||
| Resource | Controlled by | Description |
|
||||
| :--------------------- | :------------------------------- | :---------------------------------------------------- |
|
||||
| Environment variables | Entity RBAC feature flag | Restrict which roles/users can view or manage specific env vars |
|
||||
| LLM connections | Entity RBAC feature flag | Restrict access to specific LLM provider configurations |
|
||||
| Git repositories | Git repositories RBAC org setting | Restrict which roles/users can access specific connected repos |
|
||||
|
||||
---
|
||||
|
||||
## Common Role Patterns
|
||||
|
||||
While CrewAI ships with Owner and Member roles, most teams benefit from creating custom roles. Here are common patterns:
|
||||
|
||||
### Developer Role
|
||||
|
||||
A role for team members who build and deploy automations but don't manage organization settings.
|
||||
|
||||
| Feature | Permission |
|
||||
| :------------------------ | :--------- |
|
||||
| `usage_dashboards` | Read |
|
||||
| `crews_dashboards` | Manage |
|
||||
| `invitations` | Read |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Manage |
|
||||
| `agents` | Manage |
|
||||
| `environment_variables` | Manage |
|
||||
| `llm_connections` | Manage |
|
||||
| `default_settings` | No access |
|
||||
| `organization_settings` | No access |
|
||||
| `studio_projects` | Manage |
|
||||
|
||||
### Viewer / Stakeholder Role
|
||||
|
||||
A role for non-technical stakeholders who need to monitor automations and view results.
|
||||
|
||||
| Feature | Permission |
|
||||
| :------------------------ | :--------- |
|
||||
| `usage_dashboards` | Read |
|
||||
| `crews_dashboards` | Read |
|
||||
| `invitations` | No access |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Read |
|
||||
| `agents` | Read |
|
||||
| `environment_variables` | No access |
|
||||
| `llm_connections` | No access |
|
||||
| `default_settings` | No access |
|
||||
| `organization_settings` | No access |
|
||||
| `studio_projects` | No access |
|
||||
|
||||
### Ops / Platform Admin Role
|
||||
|
||||
A role for platform operators who manage infrastructure settings but may not build agents.
|
||||
|
||||
| Feature | Permission |
|
||||
| :------------------------ | :--------- |
|
||||
| `usage_dashboards` | Manage |
|
||||
| `crews_dashboards` | Manage |
|
||||
| `invitations` | Manage |
|
||||
| `training_ui` | Read |
|
||||
| `tools` | Read |
|
||||
| `agents` | Read |
|
||||
| `environment_variables` | Manage |
|
||||
| `llm_connections` | Manage |
|
||||
| `default_settings` | Manage |
|
||||
| `organization_settings` | Read |
|
||||
| `studio_projects` | No access |
|
||||
|
||||
---
|
||||
|
||||
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
|
||||
Contact our support team for assistance with RBAC questions.
|
||||
</Card>
|
||||
@@ -0,0 +1,321 @@
|
||||
---
|
||||
title: AWS Workload Identity (OIDC Federation)
|
||||
description: Configure AWS Secrets Manager via Workload Identity for rotation-aware, credential-free secret access
|
||||
sidebarTitle: With Workload Identity
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide configures AWS Secrets Manager as a secret provider using **Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for AWS credentials via STS, and reads your secrets — without a long-lived AWS access key being stored anywhere.
|
||||
|
||||
<Note>
|
||||
**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials and don't care about rotation propagation, see the simpler [AWS — static keys / AssumeRole](/en/enterprise/features/secrets-manager/aws) guide.
|
||||
</Note>
|
||||
|
||||
### How it works at runtime
|
||||
|
||||
1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform.
|
||||
2. The worker calls `sts:AssumeRoleWithWebIdentity` on the IAM role you set up below, presenting the JWT.
|
||||
3. AWS STS validates the JWT against CrewAI Platform's public OIDC issuer (so your platform installation must be reachable from AWS), then returns short-lived AWS credentials.
|
||||
4. The worker uses those credentials to call `secretsmanager:GetSecretValue`.
|
||||
5. The fetched value is injected as the environment variable's value for that automation kickoff.
|
||||
|
||||
OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Note>
|
||||
Before starting, make sure you have:
|
||||
|
||||
- The automation pod image must include CrewAI runtime version `1.14.5` or later.
|
||||
- An AWS account with permission to create IAM OIDC providers, IAM roles, and IAM policies.
|
||||
- The AWS region where your secrets live (or will live), e.g. `us-east-1`.
|
||||
- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
- **Your CrewAI organization UUID.** Find it on the organization's settings page in CrewAI Platform — the trust policy in Step 3 binds the IAM role to this specific organization.
|
||||
- **Your CrewAI Platform installation must be reachable from AWS over HTTPS** so that AWS STS can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible (or that AWS has network reach to it via VPC peering / equivalent).
|
||||
</Note>
|
||||
|
||||
## Step 1 — Find Your CrewAI Platform OIDC Issuer URL
|
||||
|
||||
Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https://<your-platform-host>/.well-known/openid-configuration`. The `issuer` field in that document is the URL AWS will register as a trusted OIDC provider.
|
||||
|
||||
Open the URL in a browser (replacing `<your-platform-host>` with your actual hostname, e.g. `app.crewai.com`):
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
You should see JSON containing:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Note the exact value of `issuer` — you'll use it in Step 3.
|
||||
|
||||
<Tip>
|
||||
If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration.
|
||||
</Tip>
|
||||
|
||||
## Step 2 — Register CrewAI Platform as an IAM OIDC Identity Provider
|
||||
|
||||
Open the [IAM → Identity providers console](https://console.aws.amazon.com/iam/home#/identity_providers) and click **Add provider**.
|
||||
|
||||
- **Provider type:** OpenID Connect.
|
||||
- **Provider URL:** the `issuer` value from Step 1 (e.g. `https://app.crewai.com`).
|
||||
- **Audience:** `sts.amazonaws.com`
|
||||
|
||||
Click **Add provider**.
|
||||
|
||||
Or via CLI:
|
||||
|
||||
```bash
|
||||
aws iam create-open-id-connect-provider \
|
||||
--url "https://<your-platform-host>" \
|
||||
--client-id-list "sts.amazonaws.com" \
|
||||
--thumbprint-list "$(echo | openssl s_client -servername <your-platform-host> -connect <your-platform-host>:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')"
|
||||
```
|
||||
|
||||
Copy the **OpenIDConnectProviderArn** from the output (or the provider's ARN from the console). You'll use it in Step 3.
|
||||
|
||||
<Note>
|
||||
AWS does not actually validate the thumbprint for STS WebIdentity calls — it always re-fetches the JWKS at validation time — but the API requires the field to be present.
|
||||
</Note>
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */}
|
||||
{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */}
|
||||
|
||||
## Step 3 — Create the IAM Role
|
||||
|
||||
Save as `trust-policy.json`, replacing `<YOUR_ACCOUNT_ID>`, `<your-platform-host>` (the issuer host **without** `https://` or `http://`, e.g. `app.crewai.com`), and `<YOUR_CREWAI_ORG_UUID>` (from the Prerequisites):
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"Federated": "arn:aws:iam::<YOUR_ACCOUNT_ID>:oidc-provider/<your-platform-host>"
|
||||
},
|
||||
"Action": "sts:AssumeRoleWithWebIdentity",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"<your-platform-host>:aud": "sts.amazonaws.com",
|
||||
"<your-platform-host>:sub": "organization:<YOUR_CREWAI_ORG_UUID>"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Create the role:
|
||||
|
||||
```bash
|
||||
aws iam create-role \
|
||||
--role-name crewai-secrets-reader \
|
||||
--assume-role-policy-document file://trust-policy.json
|
||||
```
|
||||
|
||||
Copy the **Role Arn** from the output — that's your `aws_role_arn`. You'll paste it into CrewAI Platform in Step 6.
|
||||
|
||||
<Tip>
|
||||
The two conditions scope the trust precisely: `aud` restricts assumption to tokens with the AWS STS audience, and `sub` scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted. CrewAI Platform always sets both claims on AWS workload identity tokens.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */}
|
||||
|
||||
## Step 4 — Create and attach the IAM policy for Secrets Manager + KMS access
|
||||
|
||||
Save as `secrets-policy.json`, replacing the placeholders with your account ID, region, secret-name prefix, and the KMS key ARN(s) that encrypt those secrets:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SecretsManagerListForUI",
|
||||
"Effect": "Allow",
|
||||
"Action": "secretsmanager:ListSecrets",
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "SecretsManagerRead",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"secretsmanager:GetSecretValue"
|
||||
],
|
||||
"Resource": "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME_PREFIX>-*"
|
||||
},
|
||||
{
|
||||
"Sid": "KMSDecrypt",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"kms:Decrypt"
|
||||
],
|
||||
"Resource": "arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KMS_KEY_ID>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`SecretsManagerListForUI` powers the **Secret Name autocomplete** in the Environment Variables form and the **Test Connection** button on the credential. `secretsmanager:ListSecrets` only accepts `Resource: "*"` — it is account-scoped at the IAM layer.
|
||||
|
||||
Attach the policy to the role using either the CLI (inline policy, simplest) or the console UI; for environments that reuse the same permissions across many roles, use the **Managed policy** tab for a reusable, named policy.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Inline policy (CLI)">
|
||||
```bash
|
||||
aws iam put-role-policy \
|
||||
--role-name crewai-secrets-reader \
|
||||
--policy-name SecretsManagerRead \
|
||||
--policy-document file://secrets-policy.json
|
||||
```
|
||||
|
||||
This attaches the policy **inline** to the role. Inline policies are tied to the role and cannot be reused on other roles.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Managed policy (CLI, reusable)">
|
||||
```bash
|
||||
POLICY_ARN=$(aws iam create-policy \
|
||||
--policy-name CrewAISecretsReader \
|
||||
--policy-document file://secrets-policy.json \
|
||||
--query 'Policy.Arn' --output text)
|
||||
|
||||
aws iam attach-role-policy \
|
||||
--role-name crewai-secrets-reader \
|
||||
--policy-arn "$POLICY_ARN"
|
||||
```
|
||||
|
||||
A managed policy is a standalone IAM resource you can attach to multiple roles.
|
||||
</Tab>
|
||||
|
||||
<Tab title="Console (UI)">
|
||||
1. Open the [IAM → Roles console](https://console.aws.amazon.com/iam/home#/roles) and select **crewai-secrets-reader**.
|
||||
2. On the **Permissions** tab, click **Add permissions** → **Create inline policy**.
|
||||
3. Switch to the **JSON** editor and paste the contents of `secrets-policy.json`.
|
||||
4. Click **Next**, give the policy a name (e.g. `SecretsManagerRead`), and click **Create policy**.
|
||||
|
||||
To create a reusable managed policy instead, use **IAM → Policies → Create policy** and then attach it to the role from the role's **Permissions** tab.
|
||||
|
||||
{/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Step 5 — Create at Least One Secret in AWS
|
||||
|
||||
If you don't already have a secret to test against, create one now:
|
||||
|
||||
```bash
|
||||
aws secretsmanager create-secret \
|
||||
--region <REGION> \
|
||||
--name crewai-test-keyword \
|
||||
--secret-string "hello from aws"
|
||||
```
|
||||
|
||||
Or via the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**.
|
||||
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */}
|
||||
|
||||
## Step 6 — Add a Workload Identity Configuration in CrewAI Platform
|
||||
|
||||
In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */}
|
||||
{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */}
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `aws-prod`.
|
||||
- **Cloud Provider:** `AWS`.
|
||||
- **AWS Role ARN:** the **Role Arn** from Step 3.
|
||||
- **AWS Region:** the region where your secrets live, e.g. `us-east-1`.
|
||||
- (Optional) Check **Set as default for AWS** if you'd like this WI config to be the default selected when creating an AWS-backed secret credential.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */}
|
||||
|
||||
## Step 7 — Add a Secret Provider Credential Bound to the WI Config
|
||||
|
||||
Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `aws-prod-wi`.
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Authentication Method:** `Workload Identity` (instead of static keys / AssumeRole).
|
||||
- **Workload Identity Configuration:** select the config you created in Step 6 (e.g. `aws-prod`).
|
||||
- (Optional) Check **Set as default credential for this provider**.
|
||||
|
||||
The form will only ask for **AWS Region** under Workload Identity — the static-credential fields (Access Key ID, Secret Access Key, Role ARN, External ID) are intentionally hidden because they don't apply to this path; the role ARN comes from the linked WI config.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */}
|
||||
|
||||
## Step 8 — Test the Connection
|
||||
|
||||
After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT, exchanges it with AWS STS via `sts:AssumeRoleWithWebIdentity`, and confirms the resulting credentials can call `sts:GetCallerIdentity` against the assumed role. A green result means the federation binding is healthy.
|
||||
|
||||
A successful Test Connection proves the trust policy, OIDC provider registration, and audience condition are all wired correctly. It does **not** prove per-secret IAM is correct — `secretsmanager:GetSecretValue` on a specific secret ARN is exercised separately when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes.
|
||||
|
||||
## Step 9 — Reference the Secret in an Environment Variable
|
||||
|
||||
Now reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior.
|
||||
|
||||
The only difference between WI-backed and static-keys-backed env vars is **when** the secret is read:
|
||||
|
||||
- **WI-backed:** secret value is read fresh on every automation kickoff.
|
||||
- **Static-keys-backed:** secret value is read at deploy time and baked into the deployment image.
|
||||
|
||||
## Step 10 — Verify Rotation
|
||||
|
||||
After the deployment is running, rotate the secret in AWS:
|
||||
|
||||
```bash
|
||||
aws secretsmanager update-secret \
|
||||
--region <REGION> \
|
||||
--secret-id crewai-test-keyword \
|
||||
--secret-string "rotated value"
|
||||
```
|
||||
|
||||
Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no waiting on a TTL.
|
||||
|
||||
To confirm in logs (if you have access to the worker), look for:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (aws): N secret(s) resolved
|
||||
```
|
||||
|
||||
This line appears for every kickoff and indicates a fresh `GetSecretValue` call against AWS.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| Test Connection fails with a handshake error | The `sts:AssumeRoleWithWebIdentity` call was rejected. Verify the trust policy's federated principal ARN references `oidc-provider/<your-platform-host>` (host **without** `https://` or `http://`, no trailing slash), the audience condition is exactly `sts.amazonaws.com`, the `sub` condition matches your CrewAI organization UUID, and the platform's OIDC discovery URL is reachable from AWS over the public internet. |
|
||||
| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | AWS STS can't reach your CrewAI Platform host to fetch JWKS. Confirm the host is internet-accessible from AWS, the OIDC discovery URL returns 200, and the JWKS endpoint is reachable. |
|
||||
| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | Trust policy mismatch. Re-check Step 3: the federated principal ARN must include `oidc-provider/<your-platform-host>` (host **without** `https://` or `http://`, no trailing slash), the audience condition must be exactly `sts.amazonaws.com`, and the `sub` condition must equal `organization:<YOUR_CREWAI_ORG_UUID>`. |
|
||||
| Secret Name autocomplete shows `AccessDenied: secretsmanager:ListSecrets` | The role is missing `secretsmanager:ListSecrets` with `Resource: "*"`. Add the `SecretsManagerListForUI` statement from Step 4. |
|
||||
| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but resource-scoped IAM is missing on the failing secret. Audit the role's `secretsmanager:GetSecretValue` and `kms:Decrypt` permissions for that specific secret's ARN and KMS key. |
|
||||
| `RegionDisabledException` / no secrets found | The region in the Workload Identity Config doesn't match where the secret lives. Re-check Step 6. |
|
||||
| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. |
|
||||
|
||||
### Reference Links
|
||||
|
||||
- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
|
||||
- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html)
|
||||
- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
|
||||
- For multi-cloud, see also [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) and [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
295
docs/edge/en/enterprise/features/secrets-manager/aws.mdx
Normal file
295
docs/edge/en/enterprise/features/secrets-manager/aws.mdx
Normal file
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: AWS Secrets Manager (Static Credentials)
|
||||
description: Configure AWS Secrets Manager as a secret provider for CrewAI Platform using static access keys or AssumeRole
|
||||
sidebarTitle: With Static Credentials
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide walks you through configuring AWS Secrets Manager as a secret provider for your CrewAI Platform organization, using **static credentials** (access keys, optionally with AssumeRole). By the end, CrewAI Platform will be able to read secrets stored in your AWS account and inject them as environment variable values at runtime.
|
||||
|
||||
<Note>
|
||||
This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff (no re-deploy), see [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity).
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
This guide covers the AWS-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage).
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Note>
|
||||
Before starting, make sure you have:
|
||||
|
||||
- An AWS account with permission to create IAM users, customer-managed policies, and (optionally) IAM roles.
|
||||
- The AWS region where your secrets live (or will live), for example `us-east-1`.
|
||||
- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
</Note>
|
||||
|
||||
## Choose an Authentication Method
|
||||
|
||||
CrewAI Platform supports two ways for the platform to authenticate with AWS Secrets Manager. Pick one before you begin — the steps below differ depending on which you choose.
|
||||
|
||||
| Method | When to use | Trade-offs |
|
||||
|---|---|---|
|
||||
| **Static access keys** | Getting started, single-account deployments | Simplest setup; access keys must be rotated manually |
|
||||
| **AssumeRole** | Cross-account, production hardening | Short-lived credentials; supports External ID; requires extra IAM role |
|
||||
|
||||
The rest of this guide uses tabs in Steps 3–5 so you can follow the path that matches your choice.
|
||||
|
||||
## Step 1 — Create an IAM User
|
||||
|
||||
Open the [IAM console](https://console.aws.amazon.com/iam/), navigate to **Users**, then click **Create user**.
|
||||
|
||||
- Suggested name: `crewai-secrets-reader`.
|
||||
- Leave **Provide user access to the AWS Management Console** unchecked — this principal is used programmatically by CrewAI Platform, not by humans.
|
||||
- Click **Next**.
|
||||
|
||||
On the **Set permissions** page, leave the default selection. You will attach the policy in Step 3.
|
||||
|
||||
Click **Next**, review, and click **Create user**.
|
||||
|
||||
For full details, see the AWS documentation: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */}
|
||||
|
||||
## Step 2 — Create the IAM Policy
|
||||
|
||||
CrewAI Platform needs read-only access to AWS Secrets Manager and permission to decrypt secrets via KMS. Create a customer-managed policy with the following JSON.
|
||||
|
||||
In the IAM console, navigate to **Policies**, then click **Create policy**.
|
||||
|
||||
Choose the **JSON** tab and replace the contents with:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "SecretsManagerRead",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"secretsmanager:ListSecrets",
|
||||
"secretsmanager:GetSecretValue",
|
||||
"secretsmanager:DescribeSecret"
|
||||
],
|
||||
"Resource": "*"
|
||||
},
|
||||
{
|
||||
"Sid": "KMSDecrypt",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"kms:DescribeKey",
|
||||
"kms:Decrypt"
|
||||
],
|
||||
"Resource": "*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Click **Next**, then on the **Review and create** page:
|
||||
|
||||
- **Policy name:** `CrewAISecretsManagerRead`
|
||||
- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform`
|
||||
|
||||
Click **Create policy**.
|
||||
|
||||
<Tip>
|
||||
The policy above grants `*` on `Resource` for simplicity. In production, scope the `Resource` down to the ARNs of the specific secrets CrewAI Platform should access, and scope `kms:Decrypt` to the specific KMS key ARNs that encrypt those secrets. See the [AWS guidance on least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html).
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */}
|
||||
{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */}
|
||||
|
||||
## Step 3 — Attach the Policy
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Static access keys">
|
||||
1. In the IAM console, navigate to **Users** and click the user you created in Step 1.
|
||||
2. On the **Permissions** tab, click **Add permissions** → **Attach policies directly**.
|
||||
3. Search for `CrewAISecretsManagerRead`, select it, and click **Next**.
|
||||
4. Click **Add permissions**.
|
||||
|
||||
{/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
With AssumeRole, the policy is attached to a separate IAM **role** (not directly to the user). The user from Step 1 only needs permission to call `sts:AssumeRole` on that role.
|
||||
|
||||
**Create the role:**
|
||||
|
||||
1. In the IAM console, navigate to **Roles** and click **Create role**.
|
||||
2. **Trusted entity type:** AWS account. Choose **This account** (or **Another AWS account** for cross-account setups, then enter the AWS account ID hosting the IAM user from Step 1).
|
||||
3. (Recommended) Check **Require external ID** and enter a value you generate yourself — this is a shared secret you will paste into CrewAI Platform in Step 5.
|
||||
4. Click **Next**.
|
||||
5. Attach the `CrewAISecretsManagerRead` policy.
|
||||
6. Click **Next**, name the role `CrewAISecretsManagerRole`, and click **Create role**.
|
||||
|
||||
**Allow the IAM user to assume the role:**
|
||||
|
||||
1. Open the role you just created and copy its **ARN**.
|
||||
2. In the IAM console, navigate to **Users**, click the user from Step 1, and on the **Permissions** tab click **Add permissions** → **Create inline policy**.
|
||||
3. On the **JSON** tab, paste the following (replace `ROLE_ARN_FROM_ABOVE`):
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Action": "sts:AssumeRole",
|
||||
"Resource": "ROLE_ARN_FROM_ABOVE"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
4. Name the policy `CrewAIAssumeSecretsRole` and click **Create policy**.
|
||||
|
||||
{/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */}
|
||||
{/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Step 4 — Get Credentials
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Static access keys">
|
||||
1. In the IAM console, open the user from Step 1.
|
||||
2. Click the **Security credentials** tab.
|
||||
3. Under **Access keys**, click **Create access key**.
|
||||
4. Select **Application running outside AWS** (or **Other**) as the use case. Click **Next**.
|
||||
5. (Optional) Add a description tag. Click **Create access key**.
|
||||
6. Click **Show** to reveal the secret access key, then copy both the **Access key ID** and the **Secret access key**, or click **Download .csv file**.
|
||||
|
||||
<Warning>
|
||||
The secret access key is shown only once. If you close this page without copying it, you will need to delete the key and create a new one.
|
||||
</Warning>
|
||||
|
||||
For full details, see the AWS documentation: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
|
||||
|
||||
{/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */}
|
||||
{/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
Even with AssumeRole, CrewAI Platform still needs an access key for the IAM user — it uses those keys as the calling identity to perform the `sts:AssumeRole` call.
|
||||
|
||||
1. Create an access key for the user exactly as described in the **Static access keys** tab above.
|
||||
2. Open the role you created in Step 3 and copy:
|
||||
- The **Role ARN** (from the role summary).
|
||||
- The **External ID** you configured (if any) — you set this yourself in Step 3, so make sure you have it on hand.
|
||||
|
||||
{/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Step 5 — Add the Credential in CrewAI Platform
|
||||
|
||||
In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */}
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Static access keys">
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `aws-prod`.
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Region:** The AWS region where your secrets live, e.g. `us-east-1`. This must match the region of the secrets you want to read.
|
||||
- **Access Key ID:** The value from Step 4.
|
||||
- **Secret Access Key:** The value from Step 4.
|
||||
- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference AWS secrets without specifying a credential explicitly.
|
||||
|
||||
Leave **Role ARN** and **External ID** blank.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="AssumeRole">
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `aws-prod-assumerole`.
|
||||
- **Provider:** `AWS Secrets Manager`.
|
||||
- **Region:** The AWS region where your secrets live.
|
||||
- **Access Key ID:** The IAM user's access key from Step 4 (used to call STS).
|
||||
- **Secret Access Key:** The IAM user's secret access key from Step 4.
|
||||
- **Role ARN:** The Role ARN you copied in Step 4.
|
||||
- **External ID:** The External ID you set on the role's trust policy (omit if none).
|
||||
- (Optional) Check **Set as default credential for this provider**.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
**How the two modes behave at runtime:**
|
||||
|
||||
- With **static access keys** only, CrewAI Platform calls AWS Secrets Manager directly using the keys you supplied.
|
||||
- When a **Role ARN** is set, CrewAI Platform first calls `sts:AssumeRole` with the supplied access keys (and External ID if configured), then uses the short-lived credentials returned by STS to read your secrets.
|
||||
</Note>
|
||||
|
||||
{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */}
|
||||
|
||||
## Step 6 — Create at Least One Secret in AWS
|
||||
|
||||
If you do not already have secrets in AWS Secrets Manager, create one now so you can verify the connection in Step 7.
|
||||
|
||||
In the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/), click **Store a new secret**.
|
||||
|
||||
- **Secret type:** Choose **Other type of secret**.
|
||||
- **Key/value pairs** — either:
|
||||
- Enter one or more key/value pairs (recommended for structured secrets), or
|
||||
- Use the **Plaintext** tab for a single string value.
|
||||
- **Encryption key:** Use `aws/secretsmanager` (the AWS-managed key) unless you have a specific KMS key requirement.
|
||||
|
||||
Click **Next**, then enter:
|
||||
|
||||
- **Secret name:** A unique name, e.g. `crewai/openai-api-key`.
|
||||
- **Description (optional):** A short note about what the secret is for.
|
||||
|
||||
Click **Next** through the rotation and review steps, then click **Store**.
|
||||
|
||||
<Note>
|
||||
**JSON-key reference syntax.** If you store a secret with multiple key/value pairs (a JSON object), CrewAI Platform can extract a specific field using the `secret-name#json_key` syntax in environment variable references. For example, a secret named `database-credentials` with `{"username": "...", "password": "..."}` can be referenced as `database-credentials#password`. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details.
|
||||
</Note>
|
||||
|
||||
For full details, see the AWS documentation: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
|
||||
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */}
|
||||
{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */}
|
||||
|
||||
## Step 7 — Test the Connection
|
||||
|
||||
Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**.
|
||||
|
||||
A success toast confirms that CrewAI Platform can authenticate to AWS and read secrets from your account.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */}
|
||||
|
||||
If the test fails, check the most common causes:
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| `AccessDenied` on `secretsmanager:ListSecrets` | Policy not attached, or wrong user. Re-check Step 3. |
|
||||
| `AccessDenied` on `kms:Decrypt` | Missing the `KMSDecrypt` statement, or your secrets use a customer-managed KMS key not covered by `Resource: "*"`. |
|
||||
| `InvalidClientTokenId` / `SignatureDoesNotMatch` | Wrong access key ID or secret access key. Re-check Step 4 and Step 5. |
|
||||
| `RegionDisabledException` / no secrets found | The credential's **Region** does not match where your secrets actually live. |
|
||||
| `AccessDenied` on `sts:AssumeRole` (AssumeRole only) | Inline `sts:AssumeRole` policy missing on the IAM user, or the role's trust policy does not allow this principal, or the External ID does not match. |
|
||||
| Test passes immediately after creating the IAM user, but fails next time | IAM credentials sometimes take a minute or two to propagate globally. Retry. |
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that AWS is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to:
|
||||
|
||||
- Grant org members the right permissions to use (or manage) Secrets Manager.
|
||||
- Reference your AWS secrets from CrewAI Platform environment variables.
|
||||
|
||||
If you want **rotation-aware** secrets that propagate without re-deploying, switch to [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff.
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
title: Azure Workload Identity Federation
|
||||
description: Configure Azure Key Vault via Microsoft Entra Workload Identity Federation for rotation-aware, credential-free secret access
|
||||
sidebarTitle: With Workload Identity
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide configures Azure Key Vault as a secret provider using **Microsoft Entra Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for an Entra access token via the Microsoft identity platform, and reads your secrets — without any client secret being stored anywhere.
|
||||
|
||||
<Note>
|
||||
**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials, see the simpler [Azure Key Vault — client secret](/en/enterprise/features/secrets-manager/azure) guide.
|
||||
</Note>
|
||||
|
||||
### How it works at runtime
|
||||
|
||||
1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform.
|
||||
2. The worker presents the JWT to Microsoft Entra at `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token` as a `client_assertion` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`), referencing the App Registration whose **Federated Identity Credential** matches the JWT's issuer + subject.
|
||||
3. Entra validates the JWT against your platform's OIDC discovery document and JWKS, then returns a short-lived access token scoped to `https://vault.azure.net/.default`.
|
||||
4. The worker calls Azure Key Vault to read the secret.
|
||||
5. The fetched value is injected as the environment variable's value for that automation kickoff.
|
||||
|
||||
OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Note>
|
||||
Before starting, make sure you have:
|
||||
|
||||
- The automation pod image must include CrewAI runtime version `1.14.5` or later.
|
||||
- An Azure subscription and a Microsoft Entra tenant you can manage.
|
||||
- Permission in the tenant to create App Registrations and add Federated Identity Credentials.
|
||||
- A Key Vault using **Azure RBAC** for authorization (not the legacy access-policy model).
|
||||
- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
- **Your CrewAI Platform installation must be reachable from Microsoft Entra over HTTPS** so that Entra can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible.
|
||||
</Note>
|
||||
|
||||
## Step 1 — Find Your CrewAI Platform OIDC Issuer URL
|
||||
|
||||
Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https://<your-platform-host>/.well-known/openid-configuration`. The `issuer` field there is the URL Microsoft Entra will register as a trusted federation issuer.
|
||||
|
||||
Open the URL in a browser:
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
You should see JSON containing:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Note the exact value of `issuer` — you'll use it in Step 3.
|
||||
|
||||
<Tip>
|
||||
If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration.
|
||||
</Tip>
|
||||
|
||||
## Step 2 — Create an App Registration
|
||||
|
||||
In the [Microsoft Entra portal](https://entra.microsoft.com), navigate to **App registrations** and click **New registration**.
|
||||
|
||||
- **Name:** `crewai-secrets-reader`
|
||||
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
|
||||
- Leave **Redirect URI** blank.
|
||||
|
||||
Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** on the App's overview blade — you'll use them in Step 6.
|
||||
|
||||
{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */}
|
||||
|
||||
## Step 3 — Add a Federated Identity Credential
|
||||
|
||||
The Federated Identity Credential tells Microsoft Entra: *trust JWTs minted by this issuer, with this subject, when they're presented as a client assertion for this App Registration.*
|
||||
|
||||
On the App Registration, navigate to **Certificates & secrets** → **Federated credentials** → **Add credential**.
|
||||
|
||||
- **Federated credential scenario:** `Other issuer`.
|
||||
- **Issuer:** the CrewAI Platform issuer URL from Step 1, e.g. `https://<your-platform-host>`.
|
||||
- **Subject identifier:** `organization:<YOUR_CREWAI_ORG_UUID>` — exactly the value of the JWT's `sub` claim. Find your org UUID in CrewAI Platform's organization settings. This scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted.
|
||||
- **Name:** any descriptive label, e.g. `crewai-org-prod`.
|
||||
- **Audience:** `api://AzureADTokenExchange`. This is the fixed audience Microsoft Entra requires for federated credentials and is what CrewAI Platform sets in the JWT's `aud` claim.
|
||||
|
||||
Click **Add**.
|
||||
|
||||
<Tip>
|
||||
**Per-org isolation.** The subject identifier (`organization:<UUID>`) restricts the federated credential to a specific CrewAI organization's tokens. If multiple CrewAI organizations should share one App Registration, add one Federated Identity Credential per organization (each with the org's UUID).
|
||||
</Tip>
|
||||
|
||||
For full details, see the Microsoft documentation: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust).
|
||||
|
||||
{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:<uuid>", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */}
|
||||
|
||||
## Step 4 — Grant the App Registration Access to Key Vault
|
||||
|
||||
Grant the App Registration **Key Vault Secrets User** on the target vault — the same role you'd use for the static-credentials path. Use either vault-wide (simpler) or per-secret (least privilege).
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Vault-wide (simpler)">
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
Vault-wide scope grants the `secrets/list` permission that the **Secret Name autocomplete** in CrewAI Platform's env-var form depends on. Choose this tab if you want autocomplete to work.
|
||||
|
||||
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Per-secret (least privilege)">
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
Per-secret bindings disable the **Secret Name autocomplete** in CrewAI Platform's env-var form (autocomplete requires `secrets/list`, which is vault-scoped only). Type the full secret name instead.
|
||||
|
||||
{/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Portal (UI)">
|
||||
For a **vault-wide** assignment:
|
||||
|
||||
1. Open your Key Vault in the Azure portal.
|
||||
2. Click **Access control (IAM)** → **Add** → **Add role assignment**.
|
||||
3. Select role **Key Vault Secrets User** → **Next**.
|
||||
4. Click **Select members**, search for the App Registration `crewai-secrets-reader`, click **Select**.
|
||||
5. Click **Review + assign**.
|
||||
|
||||
For a **per-secret** assignment, use the same flow but start from **Objects** → **Secrets** → select the secret → its own **Access control (IAM)** panel. Per-secret bindings disable autocomplete (see the Per-secret tab above).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Step 5 — Create at Least One Secret in Key Vault
|
||||
|
||||
If you don't already have a secret to test against, create one via the Azure CLI:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "sk-your-actual-key"
|
||||
```
|
||||
|
||||
Or via the Azure portal:
|
||||
|
||||
1. Open your Key Vault and navigate to **Objects** → **Secrets**.
|
||||
2. Click **Generate/Import**.
|
||||
3. **Upload options:** `Manual`. **Name:** the secret name (e.g. `openai-api-key`). **Secret value:** paste the value.
|
||||
4. Click **Create**.
|
||||
|
||||
<Note>
|
||||
**Secret name conventions.** Azure Key Vault secret names cannot contain underscores. CrewAI Platform automatically converts underscores to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`), so you can keep underscore-style env-var names — but the underlying secret in Key Vault must use hyphens.
|
||||
</Note>
|
||||
|
||||
## Step 6 — Add a Workload Identity Configuration in CrewAI Platform
|
||||
|
||||
In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**.
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `azure-prod`.
|
||||
- **Cloud Provider:** `Azure`.
|
||||
- **Tenant ID:** your Microsoft Entra **Directory (tenant) ID** from Step 2.
|
||||
- **Client ID:** your App Registration's **Application (client) ID** from Step 2.
|
||||
- (Optional) Check **Set as default for Azure** if you'd like this to be the default WI config selected when creating an Azure-backed secret credential.
|
||||
|
||||
The **Audience** is fixed at `api://AzureADTokenExchange` — Microsoft Entra requires this exact audience for federated credentials, so no Audience field is shown on the form.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */}
|
||||
|
||||
## Step 7 — Add a Secret Provider Credential Bound to the WI Config
|
||||
|
||||
Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `azure-prod-wi`.
|
||||
- **Provider:** `Azure Key Vault`.
|
||||
- **Authentication Method:** `Workload Identity`.
|
||||
- **Workload Identity Configuration:** select the config you created in Step 6.
|
||||
- **Key Vault URL:** the vault's DNS hostname, e.g. `https://my-vault.vault.azure.net`.
|
||||
- (Optional) Check **Set as default credential for this provider**.
|
||||
|
||||
The form will only ask for **Key Vault URL** under Workload Identity — the static-credential fields (Tenant ID, Client ID, Client Secret) are intentionally hidden because they don't apply to this path; tenant + client come from the linked WI config.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
<Tip>
|
||||
**One App Registration, many vaults.** The Key Vault URL lives on the credential, not the WI config. So one App Registration (and one WI config) can serve multiple Key Vaults — just create one Secret Provider Credential per vault, all linked to the same WI config.
|
||||
</Tip>
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */}
|
||||
|
||||
## Step 8 — Test the Connection
|
||||
|
||||
After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT, presents it to Microsoft Entra as a federated `client_assertion`, and confirms Entra returns a vault-scoped access token. A green result means the federation binding is healthy.
|
||||
|
||||
A successful Test Connection proves the Federated Identity Credential's issuer, subject, and audience all match, and that the App Registration is reachable. It does **not** prove per-secret Key Vault RBAC is correct — `getSecret` against a specific secret is exercised separately when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes.
|
||||
|
||||
## Step 9 — Reference the Secret in an Environment Variable
|
||||
|
||||
Reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior.
|
||||
|
||||
## Step 10 — Verify Rotation
|
||||
|
||||
After the deployment is running, rotate the secret in Key Vault:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "rotated value"
|
||||
```
|
||||
|
||||
Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no TTL wait.
|
||||
|
||||
To confirm in worker logs, look for:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (azure): N secret(s) resolved
|
||||
```
|
||||
|
||||
This line appears for every kickoff and indicates a fresh `getSecret` call against Azure Key Vault.
|
||||
|
||||
For an end-to-end fingerprint-based verification, see [Verify Rotation End-to-End](/en/enterprise/features/secrets-manager/verify-rotation).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| Test Connection fails with a handshake error | The federated `client_assertion` was rejected by Microsoft Entra. Verify the Federated Identity Credential's **Issuer** matches the platform's `issuer` value exactly, **Subject** is `organization:<your-org-uuid>` (matching the JWT's `sub` claim), **Audience** is `api://AzureADTokenExchange`, and the platform's OIDC discovery URL is reachable from Entra over the public internet. |
|
||||
| `AADSTS70021: No matching federated identity record found for presented assertion` | The Federated Identity Credential's **Issuer** + **Subject** + **Audience** don't all match the JWT exactly. Re-check Step 3: subject must be `organization:<your-org-uuid>` (matching the JWT's `sub` claim), audience must be `api://AzureADTokenExchange`. |
|
||||
| `AADSTS700024: Client assertion is not within its valid time range` | The CrewAI Platform host's clock is significantly skewed from real time. Check NTP on the host. |
|
||||
| `AADSTS50013: Assertion failed signature validation` | Microsoft Entra couldn't verify the JWT's signature. Confirm `https://<your-platform-host>/oauth2/jwks` is reachable from the public internet and serves a valid JWKS. |
|
||||
| Secret Name autocomplete shows `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` | The App Registration's **Key Vault Secrets User** role is scoped to a single secret. Grant the role at the vault scope so the `list` data-plane action is allowed. See Step 4. |
|
||||
| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but per-secret Key Vault RBAC is missing on the failing secret. Audit **Key Vault Secrets User** on that specific secret (or extend the role assignment to the vault scope). |
|
||||
| `Forbidden — request was not authorized` (vault using legacy access policies) | The vault hasn't been switched to Azure RBAC. Under the vault's **Access configuration**, set permission model to **Azure role-based access control** and re-grant the role from Step 4. |
|
||||
| `azure_vault_url is required for Azure secret resolution` (worker logs) | The Secret Provider Credential is missing **Key Vault URL**. Re-check Step 7. |
|
||||
| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. |
|
||||
|
||||
### Reference Links
|
||||
|
||||
- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
|
||||
- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
|
||||
- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
|
||||
- For multi-cloud, the AWS-equivalent setup is at [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) and the GCP-equivalent at [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity).
|
||||
|
||||
## Screenshot Reference
|
||||
|
||||
The placeholders above map to:
|
||||
|
||||
- `01-register-app.png` — Azure portal "Register an application" form filled with `crewai-secrets-reader`.
|
||||
- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, with **Other issuer**, the platform issuer URL, subject `organization:<uuid>`, audience `api://AzureADTokenExchange`.
|
||||
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, with **Key Vault Secrets User** and the App Registration selected.
|
||||
- `04-per-secret-rbac.png` — Same form but at a single secret's IAM scope (alternative least-privilege path).
|
||||
- `05-amp-add-wi-config-azure.png` — CrewAI Platform "Add Workload Identity Config" form with Cloud Provider = Azure, Tenant ID, Client ID populated.
|
||||
- `06-amp-wi-list-with-azure.png` — Workload Identity list page after creation, showing rows for AWS, GCP, and the new Azure config.
|
||||
- `07-amp-add-credential-azure-wi.png` — "Add Secret Provider Credential" form with Provider = Azure Key Vault, Auth = Workload Identity, the WI config picked, and Key Vault URL populated.
|
||||
196
docs/edge/en/enterprise/features/secrets-manager/azure.mdx
Normal file
196
docs/edge/en/enterprise/features/secrets-manager/azure.mdx
Normal file
@@ -0,0 +1,196 @@
|
||||
---
|
||||
title: Azure Key Vault
|
||||
description: Configure Azure Key Vault as a secret provider for CrewAI Platform, end-to-end
|
||||
sidebarTitle: With Static Credentials
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide walks you through configuring Azure Key Vault as a secret provider for your CrewAI Platform organization, using a **Microsoft Entra App Registration with a client secret**. By the end, CrewAI Platform will be able to read secrets stored in your Azure Key Vault and inject them as environment variable values at runtime.
|
||||
|
||||
<Note>
|
||||
This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff, see [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
This guide covers the Azure-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage).
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Note>
|
||||
Before starting, make sure you have:
|
||||
|
||||
- An Azure subscription with permission to create App Registrations in Microsoft Entra and to grant role assignments on Key Vault resources.
|
||||
- A Key Vault using **Azure RBAC** for authorization (not the legacy access-policy model). If your vault still uses access policies, switch it to RBAC under the vault's **Access configuration** blade.
|
||||
- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
</Note>
|
||||
|
||||
## Step 1 — Create an App Registration
|
||||
|
||||
The App Registration is the Microsoft Entra-side identity CrewAI Platform will authenticate as.
|
||||
|
||||
In the [Microsoft Entra portal](https://entra.microsoft.com), navigate to **App registrations** and click **New registration**.
|
||||
|
||||
- **Name:** `crewai-secrets-reader`
|
||||
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
|
||||
- Leave **Redirect URI** blank.
|
||||
|
||||
Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** on the App's overview blade — you'll paste both into CrewAI Platform in Step 4.
|
||||
|
||||
For full details, see the Microsoft documentation: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
|
||||
|
||||
{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */}
|
||||
|
||||
## Step 2 — Create a Client Secret
|
||||
|
||||
On the App Registration, navigate to **Certificates & secrets** → **Client secrets** → **New client secret**.
|
||||
|
||||
- **Description:** `crewai-platform`
|
||||
- **Expires:** pick a duration that matches your rotation policy (Microsoft caps this at 24 months).
|
||||
|
||||
Click **Add**. Copy the **Value** column immediately — it can never be re-displayed once you leave the page.
|
||||
|
||||
<Warning>
|
||||
Client secrets are long-lived static credentials. Store the value securely (in a password manager or your own secret store) and rotate it before expiry. To eliminate static credentials entirely, use [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) instead.
|
||||
</Warning>
|
||||
|
||||
{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */}
|
||||
|
||||
## Step 3 — Grant the App Registration Access to Key Vault
|
||||
|
||||
CrewAI Platform needs read access to secrets in your Key Vault. Use one of two scopes — **vault-wide** for simplicity, or **per-secret** for least privilege.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Vault-wide (simpler)">
|
||||
In the [Key Vault console](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults), open the target vault, then navigate to **Access control (IAM)** → **Add** → **Add role assignment**.
|
||||
|
||||
- **Role:** **Key Vault Secrets User**
|
||||
- **Assign access to:** User, group, or service principal
|
||||
- **Members:** search for and select your App Registration (`crewai-secrets-reader`).
|
||||
|
||||
Click **Review + assign**.
|
||||
|
||||
Or via the Azure CLI:
|
||||
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Per-secret (least privilege)">
|
||||
Grant the role at the level of an individual secret. Repeat for each secret CrewAI Platform should access:
|
||||
|
||||
```bash
|
||||
az role assignment create \
|
||||
--assignee <APPLICATION_CLIENT_ID> \
|
||||
--role "Key Vault Secrets User" \
|
||||
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
The **Key Vault Secrets User** role allows reading secret values but not listing all secrets in the vault. CrewAI Platform's secret-name autocomplete also calls `list` — that permission is included by the role at the vault scope, but **not** at the per-secret scope. With per-secret bindings, autocomplete won't suggest secrets; type the full secret name instead.
|
||||
</Tip>
|
||||
|
||||
## Step 4 — Add the Credential in CrewAI Platform
|
||||
|
||||
In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `azure-prod`.
|
||||
- **Provider:** `Azure Key Vault`.
|
||||
- **Key Vault URL:** the vault's DNS hostname, e.g. `https://my-vault.vault.azure.net`.
|
||||
- **Tenant ID:** your Microsoft Entra **Directory (tenant) ID** from Step 1.
|
||||
- **Client ID:** your App Registration's **Application (client) ID** from Step 1.
|
||||
- **Client Secret:** the **Value** you copied in Step 2.
|
||||
- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference Azure secrets without specifying a credential explicitly.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */}
|
||||
|
||||
## Step 5 — Create at Least One Secret in Azure Key Vault
|
||||
|
||||
If you don't already have secrets in Key Vault, create one now so you can verify the connection in Step 6.
|
||||
|
||||
In the Key Vault console, navigate to **Objects** → **Secrets** → **Generate/Import**.
|
||||
|
||||
- **Upload options:** `Manual`
|
||||
- **Name:** e.g. `openai-api-key`
|
||||
- **Secret value:** paste your secret value
|
||||
- Leave the rest at defaults.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
Or via the Azure CLI:
|
||||
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name openai-api-key \
|
||||
--value "sk-your-actual-key"
|
||||
```
|
||||
|
||||
<Note>
|
||||
**Secret name conventions.** Azure Key Vault secret names cannot contain underscores. CrewAI Platform automatically converts underscores to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`), so you can keep underscore-style env-var names — but the underlying secret in Key Vault must use hyphens.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
**JSON-key reference syntax.** Key Vault treats secret values as opaque strings. If your secret value happens to be a JSON object, CrewAI Platform can extract a single field using the `secret-name#json_key` syntax (e.g. `database-credentials#password`). See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details.
|
||||
</Note>
|
||||
|
||||
For full details, see the Microsoft documentation: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli).
|
||||
|
||||
{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */}
|
||||
|
||||
## Step 6 — Test the Connection
|
||||
|
||||
Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**.
|
||||
|
||||
A success toast confirms that CrewAI Platform can authenticate to Microsoft Entra and read secrets from your vault.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */}
|
||||
|
||||
If the test fails, check the most common causes:
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| `AADSTS7000215: Invalid client secret provided` | The pasted **Client Secret** is wrong or expired. Re-create the secret (Step 2) and update the credential. |
|
||||
| `AADSTS700016: Application not found in the directory` | The **Tenant ID** or **Client ID** doesn't match the App Registration. Re-check Step 4. |
|
||||
| `Forbidden — caller does not have permission` | The App Registration is missing the **Key Vault Secrets User** role on the vault (or per-secret). Re-check Step 3. |
|
||||
| `Vault not found` / DNS errors | The **Key Vault URL** is wrong, or your vault has private endpoints that block public access. Confirm the host responds to `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`. |
|
||||
| `Forbidden — request was not authorized` (vault using legacy access policies) | The vault hasn't been switched to Azure RBAC. Under the vault's **Access configuration**, set permission model to **Azure role-based access control** and re-grant the role from Step 3. |
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that Azure Key Vault is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to:
|
||||
|
||||
- Grant org members the right permissions to use (or manage) Secrets Manager.
|
||||
- Reference your Azure secrets from CrewAI Platform environment variables.
|
||||
|
||||
If you want **rotation-aware** secrets that propagate without re-deploying, switch to [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) — same vault, no client secret to rotate, secrets are fetched per kickoff.
|
||||
|
||||
## Screenshot Reference
|
||||
|
||||
The placeholders above map to:
|
||||
|
||||
- `01-register-app.png` — Azure portal "Register an application" form filled with `crewai-secrets-reader`.
|
||||
- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, with the freshly-created secret row visible (Value column highlighted before it gets masked).
|
||||
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, with **Key Vault Secrets User** picked and the App Registration selected as a member.
|
||||
- `04-per-secret-rbac.png` — Same panel but scoped to a single secret resource (alternative least-privilege path).
|
||||
- `05-amp-add-credential-form-azure.png` — CrewAI Platform "Add Secret Provider Credential" form: Provider = Azure Key Vault, all five fields populated.
|
||||
- `06-create-secret.png` — Azure Key Vault "Create a secret" panel with `openai-api-key` and a pasted value.
|
||||
- `07-test-connection-success.png` — CrewAI Platform success toast / row state after clicking **Test Connection** on the credential.
|
||||
@@ -0,0 +1,273 @@
|
||||
---
|
||||
title: GCP Workload Identity Federation
|
||||
description: Configure Google Cloud Secret Manager via Workload Identity Federation for rotation-aware, credential-free secret access
|
||||
sidebarTitle: With Workload Identity
|
||||
icon: "id-badge"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide configures Google Cloud Secret Manager as a secret provider using **Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for Google Cloud credentials via the Security Token Service, and reads your secrets — without a long-lived service account key being stored anywhere.
|
||||
|
||||
<Note>
|
||||
**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials, see the simpler [GCP — service account key](/en/enterprise/features/secrets-manager/gcp) guide.
|
||||
</Note>
|
||||
|
||||
### How it works at runtime
|
||||
|
||||
1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform.
|
||||
2. The worker exchanges the JWT for a federated Google credential via the [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest), referencing the Workload Identity Pool Provider you set up below.
|
||||
3. The worker calls `secretmanager.googleapis.com:accessSecretVersion` to read the secret, using the federated credential directly (the federated principal holds `roles/secretmanager.secretAccessor` — see Step 4).
|
||||
4. The fetched value is injected as the environment variable's value for that automation kickoff.
|
||||
|
||||
OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Note>
|
||||
Before starting, make sure you have:
|
||||
|
||||
- The automation pod image must include CrewAI runtime version `1.14.5` or later.
|
||||
- A Google Cloud project with the **Secret Manager API**, **Security Token Service API**, and **IAM Credentials API** enabled. Enable them via the console or:
|
||||
|
||||
```bash
|
||||
gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
- Permission in the project to create Workload Identity Pools, IAM roles, service accounts, and (if needed) secrets.
|
||||
- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
- **Your CrewAI Platform installation must be reachable from Google Cloud over HTTPS** so that GCP STS can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible.
|
||||
</Note>
|
||||
|
||||
## Step 1 — Find Your CrewAI Platform OIDC Issuer URL
|
||||
|
||||
Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https://<your-platform-host>/.well-known/openid-configuration`. The `issuer` field there is the URL Google will register as a trusted OIDC provider.
|
||||
|
||||
Open the URL in a browser:
|
||||
|
||||
```
|
||||
https://<your-platform-host>/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
You should see JSON containing:
|
||||
|
||||
```json
|
||||
{
|
||||
"issuer": "https://<your-platform-host>",
|
||||
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Note the exact value of `issuer` — you'll use it in Step 3.
|
||||
|
||||
<Tip>
|
||||
If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration.
|
||||
</Tip>
|
||||
|
||||
## Step 2 — Create a Workload Identity Pool
|
||||
|
||||
A Workload Identity Pool is a Google Cloud-side container for trusted external identities. You'll register CrewAI Platform as a provider inside this pool.
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools create crewai-pool \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--display-name="CrewAI Platform"
|
||||
```
|
||||
|
||||
Or in the [Workload Identity Pools console](https://console.cloud.google.com/iam-admin/workload-identity-pools), click **Create Pool**.
|
||||
|
||||
{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */}
|
||||
|
||||
## Step 3 — Add CrewAI Platform as an OIDC Provider in the Pool
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers create-oidc crewai-provider \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-pool \
|
||||
--display-name="CrewAI Platform OIDC" \
|
||||
--issuer-uri="https://<your-platform-host>" \
|
||||
--attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
|
||||
--attribute-condition="assertion.organization_id != ''"
|
||||
```
|
||||
|
||||
The `--attribute-mapping` tells Google how to map JWT claims into Google attributes:
|
||||
- `google.subject` is the principal identifier — we map it to the JWT's `sub` claim, which CrewAI Platform sets to `organization:<uuid>`.
|
||||
- `attribute.organization` is a custom attribute — we map it to the JWT's `organization_id` claim so you can reference it in IAM bindings later.
|
||||
|
||||
The `--attribute-condition` is a defense-in-depth check that rejects tokens missing an `organization_id` claim.
|
||||
|
||||
Get the **provider resource name** (you'll need it for the audience and IAM bindings):
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers describe crewai-provider \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-pool \
|
||||
--format="value(name)"
|
||||
```
|
||||
|
||||
Output looks like:
|
||||
|
||||
```
|
||||
projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider
|
||||
```
|
||||
|
||||
This is your **Workload Identity Provider** value for CrewAI Platform in Step 6. CrewAI Platform automatically computes the OIDC audience as `//iam.googleapis.com/<this-resource-name>` when issuing tokens.
|
||||
|
||||
{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */}
|
||||
|
||||
## Step 4 — Grant Secret Manager Access to the Federated Principal
|
||||
|
||||
Bind both Secret Manager roles at project scope to the federated principal — one role enables the Secret Name autocomplete in the env-var form, the other allows reading secret values at automation kickoff. Both are required for the feature to work end-to-end.
|
||||
|
||||
```bash
|
||||
PRINCIPAL_SET="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/attribute.organization/<YOUR_CREWAI_ORG_UUID>"
|
||||
|
||||
# Required for the Secret Name autocomplete (calls secretmanager.secrets.list)
|
||||
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.viewer"
|
||||
|
||||
# Required to read secret values at kickoff
|
||||
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.secretAccessor"
|
||||
```
|
||||
|
||||
Replace `<PROJECT_NUMBER>` with the numeric project number (`gcloud projects describe <YOUR_PROJECT_ID> --format='value(projectNumber)'`) and `<YOUR_CREWAI_ORG_UUID>` with the UUID of the CrewAI Platform organization that should be allowed to read your secrets. You can find the org UUID in the platform UI on the organization's settings page, or via the API. This scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted.
|
||||
|
||||
Or via the Google Cloud console:
|
||||
|
||||
1. Open **IAM & Admin** → **IAM** for your project.
|
||||
2. Click **GRANT ACCESS**.
|
||||
3. **New principals:** paste the full `principalSet://...attribute.organization/<YOUR_CREWAI_ORG_UUID>` string.
|
||||
4. Assign role **Secret Manager Viewer** (`roles/secretmanager.viewer`).
|
||||
5. Click **SAVE**.
|
||||
6. Click **GRANT ACCESS** again and repeat with role **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
|
||||
|
||||
<Tip>
|
||||
**Per-org isolation.** The `principalSet://...attribute.organization/<UUID>` pattern restricts access to a specific organization's tokens. If you have multiple CrewAI organizations sharing one Google Cloud project, repeat both bindings per-org with the correct UUID — or use a less restrictive attribute condition if isolation isn't needed.
|
||||
</Tip>
|
||||
|
||||
<Tip>
|
||||
**Scoping `secretAccessor` per-secret (optional).** If you'd rather not grant `roles/secretmanager.secretAccessor` project-wide, omit the second binding above and bind per-secret instead:
|
||||
|
||||
```bash
|
||||
gcloud secrets add-iam-policy-binding <SECRET_NAME> \
|
||||
--member="$PRINCIPAL_SET" \
|
||||
--role="roles/secretmanager.secretAccessor" \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
Keep `roles/secretmanager.viewer` at the project scope either way — `secretmanager.secrets.list` (which the autocomplete relies on) cannot be granted per-secret.
|
||||
</Tip>
|
||||
|
||||
## Step 5 — Create at Least One Secret in GCP
|
||||
|
||||
If you don't already have a secret to test against, create one via the `gcloud` CLI:
|
||||
|
||||
```bash
|
||||
echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID> \
|
||||
--replication-policy=automatic
|
||||
```
|
||||
|
||||
Or via the [Secret Manager console](https://console.cloud.google.com/security/secret-manager):
|
||||
|
||||
1. Open **Secret Manager** in your GCP project.
|
||||
2. Click **+ CREATE SECRET**.
|
||||
3. **Name:** `crewai-test-keyword`. **Secret value:** paste your value.
|
||||
4. Click **CREATE SECRET**.
|
||||
|
||||
## Step 6 — Add a Workload Identity Configuration in CrewAI Platform
|
||||
|
||||
In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**.
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `gcp-prod`.
|
||||
- **Cloud Provider:** `GCP`.
|
||||
- **Workload Identity Provider:** the provider resource name from Step 3, e.g. `projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`.
|
||||
- (Optional) Toggle **Default Configuration** if you'd like this to be the default WI config selected when creating a GCP-backed secret credential.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */}
|
||||
{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */}
|
||||
|
||||
## Step 7 — Add a Secret Provider Credential Bound to the WI Config
|
||||
|
||||
Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `gcp-prod-wi`.
|
||||
- **Provider:** `Google Cloud Secret Manager`.
|
||||
- **Authentication Method:** `Workload Identity`.
|
||||
- **Workload Identity Configuration:** select the config you created in Step 6.
|
||||
- **Project ID:** your GCP project ID (the same project that owns the secrets).
|
||||
- (Optional) Check **Set as default credential for this provider**.
|
||||
|
||||
The form will only ask for **Project ID** under Workload Identity — the **Service Account JSON** field is intentionally hidden because it doesn't apply to this path; the federated identity comes from the linked WI config.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */}
|
||||
|
||||
## Step 8 — Test the Connection
|
||||
|
||||
After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT and exchanges it via the Security Token Service for a federated Google access token. A green result means the federation binding is healthy.
|
||||
|
||||
A successful Test Connection proves the Workload Identity Pool, OIDC provider, attribute mapping, and attribute condition are all wired correctly. It does **not** prove Secret Manager IAM is correct — `secretmanager.secrets.list` and `secretmanager.versions.access` are exercised separately when the Secret Name autocomplete loads or when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes.
|
||||
|
||||
## Step 9 — Reference the Secret in an Environment Variable
|
||||
|
||||
Reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior.
|
||||
|
||||
## Step 10 — Verify Rotation
|
||||
|
||||
After the deployment is running, rotate the secret in GCP by adding a new version (Secret Manager always reads the latest enabled version by default):
|
||||
|
||||
```bash
|
||||
echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
|
||||
Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no TTL wait.
|
||||
|
||||
To confirm in worker logs, look for:
|
||||
|
||||
```
|
||||
Workload identity config '<id>' (gcp): N secret(s) resolved
|
||||
```
|
||||
|
||||
This line appears for every kickoff and indicates a fresh `accessSecretVersion` call against GCP.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| Test Connection fails with a handshake error | The STS token exchange was rejected. Verify the Workload Identity Pool exists, the OIDC provider's issuer matches the platform's `issuer` value, and the attribute condition accepts the JWT's claims. Confirm the platform's OIDC discovery URL is reachable from GCP over the public internet. |
|
||||
| `Could not refresh access token: invalid_target` | The audience claim doesn't match the Workload Identity Provider's expected audience. CrewAI Platform sets the audience automatically; if you customized it, ensure it matches `//iam.googleapis.com/<provider-resource-name>`. |
|
||||
| `Failed to fetch JWKS from issuer` | GCP STS can't reach your CrewAI Platform host. Confirm the host is internet-accessible and `/.well-known/openid-configuration` returns 200. |
|
||||
| `Attribute condition rejected token` | The OIDC provider's attribute condition (Step 3) requires `organization_id`. CrewAI Platform always sets this claim, so this usually means a misconfigured pool/provider. Re-check the provider's attribute condition. |
|
||||
| Secret Name autocomplete shows `PERMISSION_DENIED: secretmanager.secrets.list` | The federated principal is missing `roles/secretmanager.viewer` at project scope. The `secretmanager.secrets.list` permission is project-scoped only and cannot be granted per-secret. See Step 4. |
|
||||
| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but `secretmanager.versions.access` is missing on the failing secret. Audit `roles/secretmanager.secretAccessor` (project-scoped, or per-secret if you scoped it that way in Step 4). |
|
||||
| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. |
|
||||
|
||||
### Reference Links
|
||||
|
||||
- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation)
|
||||
- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
|
||||
- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control)
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
|
||||
- For multi-cloud, see also [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) and [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity).
|
||||
189
docs/edge/en/enterprise/features/secrets-manager/gcp.mdx
Normal file
189
docs/edge/en/enterprise/features/secrets-manager/gcp.mdx
Normal file
@@ -0,0 +1,189 @@
|
||||
---
|
||||
title: Google Cloud Secret Manager
|
||||
description: Configure Google Cloud Secret Manager as a secret provider for CrewAI Platform, end-to-end
|
||||
sidebarTitle: With Static Credentials
|
||||
icon: "key"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide walks you through configuring Google Cloud Secret Manager as a secret provider for your CrewAI Platform organization, using **service account credentials**. By the end, CrewAI Platform will be able to read secrets stored in your Google Cloud project and inject them as environment variable values at runtime.
|
||||
|
||||
<Note>
|
||||
This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff, see [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity).
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
This guide covers the GCP-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage).
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<Note>
|
||||
Before starting, make sure you have:
|
||||
|
||||
- A Google Cloud project with the **Secret Manager API** enabled. Enable it in the [APIs & Services console](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com) or via `gcloud`:
|
||||
|
||||
```bash
|
||||
gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
- Permission in the project to create service accounts, grant IAM roles, and (if needed) create secrets.
|
||||
- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
|
||||
</Note>
|
||||
|
||||
## Step 1 — Create a Service Account
|
||||
|
||||
A service account is the GCP-side identity CrewAI Platform will authenticate as.
|
||||
|
||||
In the [IAM & Admin → Service Accounts console](https://console.cloud.google.com/iam-admin/serviceaccounts), click **Create Service Account**.
|
||||
|
||||
- **Service account name:** `crewai-secrets-reader`
|
||||
- **Service account ID:** auto-fills from the name (e.g. `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`)
|
||||
- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform"
|
||||
|
||||
Click **Create and Continue**. Skip the optional grants on this screen — you'll attach the role in Step 2. Click **Done**.
|
||||
|
||||
For full details, see the GCP documentation: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
|
||||
|
||||
{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */}
|
||||
|
||||
## Step 2 — Grant Secret Manager Access
|
||||
|
||||
CrewAI Platform needs permission to list and read secrets in your project. Use one of two scopes — **project-wide** for simplicity, or **per-secret** for least privilege.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Project-wide (simpler)">
|
||||
In the [IAM console](https://console.cloud.google.com/iam-admin/iam), click **Grant Access** and:
|
||||
|
||||
- **New principals:** the service account's email from Step 1.
|
||||
- **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
|
||||
|
||||
Click **Save**.
|
||||
|
||||
Or via `gcloud`:
|
||||
|
||||
```bash
|
||||
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
|
||||
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/secretmanager.secretAccessor"
|
||||
```
|
||||
|
||||
{/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */}
|
||||
</Tab>
|
||||
|
||||
<Tab title="Per-secret (least privilege)">
|
||||
Grant the role only on the specific secrets CrewAI Platform should access. Repeat for each secret:
|
||||
|
||||
```bash
|
||||
gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \
|
||||
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/secretmanager.secretAccessor" \
|
||||
--project=YOUR_PROJECT_ID
|
||||
```
|
||||
|
||||
Or in the console: open each secret in [Secret Manager](https://console.cloud.google.com/security/secret-manager), click **Permissions** in the right panel, and grant **Secret Manager Secret Accessor** to the service account.
|
||||
|
||||
{/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */}
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
The `roles/secretmanager.secretAccessor` role grants read-only access to secret values. CrewAI Platform also calls `secretmanager.secrets.list` for the autocomplete experience in the env-var form — that permission is included in the role at the project scope, but **not** at the per-secret scope. With per-secret bindings, autocomplete won't suggest secrets; you'll need to type the full secret name.
|
||||
</Tip>
|
||||
|
||||
## Step 3 — Create a Service Account Key
|
||||
|
||||
Open the service account from Step 1 in the [IAM & Admin → Service Accounts console](https://console.cloud.google.com/iam-admin/serviceaccounts).
|
||||
|
||||
- Click the **Keys** tab.
|
||||
- Click **Add Key** → **Create new key**.
|
||||
- **Key type:** JSON.
|
||||
- Click **Create**. The browser downloads a JSON file — keep it secure; it cannot be re-downloaded.
|
||||
|
||||
Or via `gcloud`:
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
|
||||
--iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The service account key is a long-lived static credential. Store it securely (in a password manager or your own secret store) and rotate it on a regular cadence. To eliminate static credentials entirely, use [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) instead.
|
||||
</Warning>
|
||||
|
||||
{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */}
|
||||
|
||||
## Step 4 — Add the Credential in CrewAI Platform
|
||||
|
||||
In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
|
||||
|
||||
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Name:** A descriptive name, e.g. `gcp-prod`.
|
||||
- **Provider:** `Google Cloud Secret Manager`.
|
||||
- **Project ID:** Your GCP project ID (e.g. `my-crewai-prod`).
|
||||
- **Service Account JSON:** Paste the entire contents of the JSON file you downloaded in Step 3.
|
||||
- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference GCP secrets without specifying a credential explicitly.
|
||||
|
||||
Click **Create**.
|
||||
|
||||
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */}
|
||||
|
||||
## Step 5 — Create at Least One Secret in GCP
|
||||
|
||||
If you don't already have secrets in GCP Secret Manager, create one now so you can verify the connection in Step 6.
|
||||
|
||||
In the [Secret Manager console](https://console.cloud.google.com/security/secret-manager), click **Create secret**.
|
||||
|
||||
- **Name:** A unique name, e.g. `openai-api-key`.
|
||||
- **Secret value:** Either paste a raw value or upload a file.
|
||||
- Leave the rotation, replication, and other settings at their defaults unless you have a specific requirement.
|
||||
|
||||
Click **Create secret**.
|
||||
|
||||
Or via `gcloud`:
|
||||
|
||||
```bash
|
||||
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
|
||||
--data-file=- \
|
||||
--project=YOUR_PROJECT_ID \
|
||||
--replication-policy=automatic
|
||||
```
|
||||
|
||||
<Note>
|
||||
**JSON-key reference syntax.** GCP Secret Manager treats secret values as opaque blobs. If your secret value happens to be a JSON string, CrewAI Platform can extract a single field using the `secret-name#json_key` syntax (e.g. `database-credentials#password`). See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details.
|
||||
</Note>
|
||||
|
||||
For full details, see the GCP documentation: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart).
|
||||
|
||||
{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */}
|
||||
|
||||
## Step 6 — Test the Connection
|
||||
|
||||
Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**.
|
||||
|
||||
A success toast confirms that CrewAI Platform can authenticate to GCP and read secrets from your project.
|
||||
|
||||
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */}
|
||||
|
||||
If the test fails, check the most common causes:
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| `PERMISSION_DENIED` on listing secrets | Service account is missing `roles/secretmanager.secretAccessor`, or you scoped it per-secret (`list` is not granted). Re-check Step 2. |
|
||||
| `PERMISSION_DENIED` on `secretmanager.secrets.access` | Same as above, but for a specific secret. Confirm the service account has accessor role on the secret in question. |
|
||||
| `unauthorized_client` / `invalid_grant` | The pasted Service Account JSON is invalid, expired, or for a deleted service account. Re-create the key (Step 3) and re-paste. |
|
||||
| `Project ID does not match` | The Project ID field in CrewAI Platform doesn't match the project that owns the service account / secrets. Re-check Step 4. |
|
||||
| `API not enabled` | Secret Manager API isn't enabled on the project. See Prerequisites. |
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that GCP is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to:
|
||||
|
||||
- Grant org members the right permissions to use (or manage) Secrets Manager.
|
||||
- Reference your GCP secrets from CrewAI Platform environment variables.
|
||||
|
||||
If you want **rotation-aware** secrets that propagate without re-deploying, switch to [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff.
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Secrets Manager Overview
|
||||
description: Connect external secret stores to CrewAI Platform and reference managed secrets from environment variables
|
||||
sidebarTitle: Overview
|
||||
icon: "book-open"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Secrets Manager feature lets your organization connect an external secret store — AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault — and reference those secrets directly from environment variables on your automations and crews. Instead of pasting plaintext values into the platform, you store one set of credentials per provider and refer to secrets by name.
|
||||
|
||||
This gives you:
|
||||
|
||||
- **Centralized storage** — manage secrets in your provider rather than editing CrewAI Platform configuration. CrewAI Platform keeps no plaintext copy of the secret value.
|
||||
- **Reduced exposure** — sensitive values never live in plaintext in your CrewAI Platform configuration.
|
||||
- **Cloud-native auditability** — your provider's audit log records every secret read.
|
||||
|
||||
<Note>
|
||||
Secrets Manager (both the static-credentials and Workload Identity paths) requires CrewAI runtime version `1.14.5` or later in the automation pod image.
|
||||
</Note>
|
||||
|
||||
## Two Paths: Static Credentials vs Workload Identity
|
||||
|
||||
There are two ways to wire CrewAI Platform up to your cloud's secret store. **They differ significantly in rotation behavior**, so choose based on how often your secrets rotate and how strict your security posture is.
|
||||
|
||||
| Aspect | Static Credentials | Workload Identity (OIDC Federation) |
|
||||
|---|---|---|
|
||||
| **Authentication** | Long-lived access keys / service account JSON stored in CrewAI Platform | Short-lived tokens minted per worker process; no static credentials stored anywhere |
|
||||
| **Rotation propagation** | Resolved at deploy time and **baked into the deployment's container image** — rotated values require a re-deploy | Resolved at **automation execution time** — rotated values propagate to the next kickoff with no re-deploy |
|
||||
| **Setup effort** | Lower — paste keys / upload service account JSON | Higher — register CrewAI Platform as an OIDC provider in your cloud, configure trust policies |
|
||||
| **Best for** | Getting started, infrequently-rotated secrets, single-account deployments | Production, frequently-rotated secrets, compliance-driven environments that prohibit long-lived credentials |
|
||||
|
||||
<Note>
|
||||
**Both paths use the same UI flow** to reference secrets in environment variables (see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage)). The difference is entirely in how the platform authenticates to your cloud and when it reads the secret value.
|
||||
</Note>
|
||||
|
||||
### Choose your setup guide
|
||||
|
||||
| Provider | Static Credentials | Workload Identity |
|
||||
|---|---|---|
|
||||
| AWS Secrets Manager | [AWS — static keys / AssumeRole](/en/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/en/enterprise/features/secrets-manager/aws-workload-identity) |
|
||||
| Google Cloud Secret Manager | [GCP — service account key](/en/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) |
|
||||
| Azure Key Vault | [Azure — client secret](/en/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) |
|
||||
|
||||
<Note>
|
||||
The Secrets Manager and Workload Identity UIs are currently labeled **Beta** in CrewAI Platform.
|
||||
</Note>
|
||||
|
||||
## How It Fits Together
|
||||
|
||||
Setting up Secrets Manager is a three-step flow that involves both your cloud provider and CrewAI Platform:
|
||||
|
||||
1. **An admin configures a provider credential.** This is the cloud-side work — and the work differs depending on which path (static credentials or Workload Identity) you choose. Provider-specific guides cover this end to end.
|
||||
2. **An admin (or a permitted member) references a secret in an environment variable.** From the Environment Variables page, the user picks a provider credential and selects the secret name. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables).
|
||||
3. **The automation receives the resolved value at runtime.** When a crew or automation runs, CrewAI Platform fetches the secret from your provider and injects it as the environment variable's value. With Workload Identity, this fetch happens on every kickoff (rotation-aware). With static credentials, this fetch happens at deploy time and the value is baked into the deployment image.
|
||||
|
||||
## Visibility & Scope
|
||||
|
||||
<Note>
|
||||
WI-backed environment variables follow the same assignment model as plaintext environment variables: an automation resolves only the WI-backed variables explicitly assigned to it. Assign a WI-backed variable to an automation from the Environment Variables page on that automation; variables defined at the organization level or in a Studio project are not resolved at kickoff until you assign them.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
The secret-fetch stage runs on every kickoff but only does work when WI-backed environment variables are assigned to the deployment. For each assigned variable, the runtime resolves the value from your cloud provider on every crew, flow, training, test, or checkpoint-restore kickoff and writes it into the process environment. With nothing assigned, the stage is a no-op. Otherwise, cost is proportional to the number of assigned variables: a small added latency per kickoff plus one cloud-side audit-log entry per variable.
|
||||
</Note>
|
||||
|
||||
<Warning>
|
||||
At the Workload Identity *configuration* level, scope is still organization-wide today. Every automation in the organization is bootstrapped against every Workload Identity configuration the org has registered, and you cannot today bind a specific Workload Identity configuration to a specific automation. Per-automation Workload Identity scoping is on the roadmap. Until then, only register Workload Identity configurations every automation in your organization is allowed to use.
|
||||
</Warning>
|
||||
|
||||
## Permissions
|
||||
|
||||
Two CrewAI Platform features control access to Secrets Manager:
|
||||
|
||||
- `secret_providers` — controls who can view or manage provider credentials.
|
||||
- `environment_variables` — controls who can create and edit environment variables (including those that reference secrets).
|
||||
|
||||
A third feature controls Workload Identity setup:
|
||||
|
||||
- `workload_identity_configs` — controls who can view or manage Workload Identity configurations. Required only if you're using the Workload Identity path.
|
||||
|
||||
Owners always have full access. Members do **not** receive access to `secret_providers` or `workload_identity_configs` by default and must be granted permission via a custom role. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac) for the full matrix and step-by-step instructions.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Pick your path:
|
||||
|
||||
- **Static credentials** (simpler, requires re-deploy on rotation):
|
||||
- [Configure AWS Secrets Manager](/en/enterprise/features/secrets-manager/aws)
|
||||
- [Configure Google Cloud Secret Manager](/en/enterprise/features/secrets-manager/gcp)
|
||||
- [Configure Azure Key Vault](/en/enterprise/features/secrets-manager/azure)
|
||||
- **Workload Identity** (rotation-aware, no re-deploy):
|
||||
- [Configure AWS Workload Identity](/en/enterprise/features/secrets-manager/aws-workload-identity)
|
||||
- [Configure GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
- [Configure Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity)
|
||||
- Then: [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
|
||||
137
docs/edge/en/enterprise/features/secrets-manager/usage.mdx
Normal file
137
docs/edge/en/enterprise/features/secrets-manager/usage.mdx
Normal file
@@ -0,0 +1,137 @@
|
||||
---
|
||||
title: Using the Secrets Manager
|
||||
description: Manage permissions and reference managed secrets from environment variables in CrewAI Platform
|
||||
sidebarTitle: Usage & Permissions
|
||||
icon: "list-check"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide is provider-agnostic. It assumes you (or another admin) have already configured at least one Secret Provider Credential. Pick your setup guide based on the path you want:
|
||||
|
||||
- Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp)
|
||||
- Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
|
||||
Use this guide to:
|
||||
|
||||
- Grant the right permissions to org members.
|
||||
- Reference secrets from environment variables on your automations.
|
||||
- Verify everything resolves correctly at runtime.
|
||||
|
||||
## Permissions (RBAC)
|
||||
|
||||
Three CrewAI Platform features are relevant when working with Secrets Manager:
|
||||
|
||||
- `secret_providers` — controls access to the **Secret Provider Credentials** page.
|
||||
- `workload_identity_configs` — controls access to the **Workload Identity** page (only relevant if you use the WI path).
|
||||
- `environment_variables` — controls who can create or edit environment variables.
|
||||
|
||||
Each feature has two action levels: `read` and `manage`. Granting `manage` automatically implies `read`.
|
||||
|
||||
### What to Grant
|
||||
|
||||
| Goal | `secret_providers` | `workload_identity_configs` | `environment_variables` |
|
||||
|---|---|---|---|
|
||||
| Use existing static credentials in environment variables (no provider edits) | `read` | — | `manage` |
|
||||
| Create, edit, or delete static credentials | `manage` | — | `manage` |
|
||||
| Use existing Workload Identity-backed credentials in env vars | `read` | — | `manage` |
|
||||
| Create, edit, or delete Workload Identity configs (and credentials referencing them) | `manage` | `manage` | `manage` |
|
||||
|
||||
<Note>
|
||||
**Owners** automatically have full access to every feature. The default **Member** role intentionally excludes `secret_providers` and `workload_identity_configs` — admins must explicitly opt members in via a custom role.
|
||||
</Note>
|
||||
|
||||
### How to Assign
|
||||
|
||||
1. In CrewAI Platform, navigate to **Settings** → **Roles**. From this page you can create new roles, edit each role's permissions, and assign roles to existing members of the organization.
|
||||
|
||||
{/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */}
|
||||
{/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */}
|
||||
|
||||
2. Click **Create Role** to make a new role, or open an existing role to edit its permissions.
|
||||
|
||||
3. In the role's permission editor, toggle the relevant features per the table above:
|
||||
|
||||
- `secret_providers`: choose **read** if this role only needs to use existing credentials, or **manage** if it should also be able to create, edit, and delete credentials.
|
||||
- `environment_variables`: choose **manage** so the role can create environment variables that reference secrets.
|
||||
|
||||
{/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */}
|
||||
{/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */}
|
||||
|
||||
4. Save the role.
|
||||
|
||||
5. Assign the role to the relevant members from the same Roles page (or the org Members list).
|
||||
|
||||
{/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */}
|
||||
|
||||
## Referencing Secrets in Environment Variables
|
||||
|
||||
Once a provider credential exists and your role has the right permissions, you can reference managed secrets from any environment variable.
|
||||
|
||||
In CrewAI Platform, navigate to **Environment Variables** and click **Add Environment Variables**.
|
||||
|
||||
{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */}
|
||||
|
||||
Fill the form:
|
||||
|
||||
- **Key** — the name of the environment variable. Must start with a letter or underscore and contain only letters, numbers, and underscores. Conventionally uppercase, e.g. `OPENAI_API_KEY`.
|
||||
|
||||
- **Value Source** — choose where the value comes from:
|
||||
- **Direct Value** — a plaintext value you type in. Use this when you do not want to involve a provider.
|
||||
- **Use AWS default** (or the equivalent for your provider) — uses the credential currently marked as the default for that provider type.
|
||||
- **A specific named credential** — select the credential by name. Use this if you have multiple credentials for the same provider (for example, `aws-prod` and `aws-staging`) and want to pick one explicitly.
|
||||
|
||||
{/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */}
|
||||
|
||||
- **Secret Name** — the name of the secret in your provider. Once a credential is selected, this field offers autocomplete: start typing and CrewAI Platform queries your provider for matching secret names.
|
||||
|
||||
Use the `secret-name#json_key` syntax to extract a single field from a structured (JSON) secret. For example, given a secret `database-credentials` with value `{"username": "...", "password": "..."}`, reference `database-credentials#password` to inject just the password.
|
||||
|
||||
{/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */}
|
||||
|
||||
<Note>
|
||||
**Azure Key Vault note:** Azure secret names cannot contain underscores. CrewAI Platform automatically converts underscores in your `Secret Name` field to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`).
|
||||
</Note>
|
||||
|
||||
Click **Create** to save the variable.
|
||||
|
||||
{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */}
|
||||
|
||||
<Tip>
|
||||
When editing an existing environment variable, leaving the **Value** field blank preserves the current value. This is intentional — it lets you change other fields (like the secret name or credential) without re-entering the value.
|
||||
</Tip>
|
||||
|
||||
## Verifying It Works
|
||||
|
||||
To verify end-to-end:
|
||||
|
||||
1. Reference the environment variable on an automation, crew, or deployment exactly as you would any other environment variable.
|
||||
2. Deploy the automation.
|
||||
3. Trigger a run and confirm it completes successfully.
|
||||
|
||||
### Rotation behavior depends on the credential path
|
||||
|
||||
| Credential path | When the secret is read | What rotation requires |
|
||||
|---|---|---|
|
||||
| **Static credentials** (AWS access keys, GCP service account JSON) | At **deploy time** — value is baked into the deployment image | Re-deploy the automation after rotating the secret |
|
||||
| **Workload Identity** (OIDC federation, AWS or GCP) | At **every automation kickoff** — value is fetched fresh from your cloud | Nothing — the next kickoff after rotation sees the new value |
|
||||
|
||||
<Note>
|
||||
**If you need rotation-aware secrets** (no re-deploy on rotation), use the Workload Identity path: [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity). The trade-off is more setup effort up front (registering CrewAI Platform as an OIDC provider in your cloud) but simpler operations long-term.
|
||||
</Note>
|
||||
|
||||
If the deploy or run fails with an error related to your secret, check the most common causes:
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| `no credential found` | The environment variable references a provider but no specific credential was selected, and there is no default credential set for that provider type. Either select a credential explicitly on the variable, or mark a credential as default on the **Secret Provider Credentials** page. |
|
||||
| `secret not found` | Typo in the **Secret Name**, or the secret does not exist in the provider account/region the credential points to. Re-check both. |
|
||||
| Automation runs with the old value after rotating (static-credentials path) | The previous value is baked into the deployment's container image. Re-deploy the automation to pick up the rotated value. To avoid this entirely, switch the credential to the Workload Identity path. |
|
||||
| Automation runs with the old value after rotating (Workload Identity path) | Confirm the env var references a WI-backed credential (not a static-keys one). With WI, the next kickoff after rotation should see the new value. If it doesn't, check that the secret was actually updated in your cloud (e.g., `aws secretsmanager get-secret-value`). |
|
||||
| `JSON key not found` | When using `secret-name#json_key`, the underlying secret must be a valid JSON object containing that key. Verify by reading the secret directly in your provider. |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview)
|
||||
- Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp)
|
||||
- Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
@@ -0,0 +1,261 @@
|
||||
---
|
||||
title: Verify Rotation
|
||||
description: A self-contained example crew that proves secret rotation propagates to running deployments without re-deploy.
|
||||
sidebarTitle: Verify Rotation
|
||||
icon: "arrows-rotate"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide shows you how to verify that **a secret rotated in your cloud provider is picked up on the very next automation kickoff** — no re-deploy, no worker restart. It's only relevant when you've configured a Workload Identity-backed credential ([AWS](/en/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/en/enterprise/features/secrets-manager/azure-workload-identity)). Static-credential deployments require a re-deploy after rotation; nothing to verify here.
|
||||
|
||||
The recipe below uses a tiny, self-contained crew with one tool, one agent, one task. The crew prompt never references the secret value — instead, a tool reads it from `os.environ` and reports a SHA-256 fingerprint of what it sees. Rotate the secret in your cloud provider, kickoff again, and the fingerprint changes.
|
||||
|
||||
<Note>
|
||||
Why a fingerprint, not the raw value? Putting raw secrets into LLM output and trace logs is a leak vector. The fingerprint is enough to confirm "the value changed" without writing the actual value anywhere observable.
|
||||
</Note>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before running this verification:
|
||||
|
||||
- A WI-backed Secret Provider Credential is configured ([AWS](/en/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/en/enterprise/features/secrets-manager/azure-workload-identity)).
|
||||
- An environment variable on your deployment with `Secret = true`, key `API_KEY` (or whatever name you prefer — adjust the tool below to match), referencing a secret in your cloud provider.
|
||||
- A way to update the secret value in your cloud provider (CLI access or the cloud console).
|
||||
- A way to kickoff the deployment via HTTP (curl, Postman, or the **Run** tab in CrewAI Platform).
|
||||
|
||||
## Step 1 — Scaffold a Verification Crew
|
||||
|
||||
Create a classic crew project because this example wires a Python tool through `crew.py`:
|
||||
|
||||
```bash
|
||||
crewai create crew rotation_verifier --classic --skip_provider
|
||||
cd rotation_verifier
|
||||
```
|
||||
|
||||
## Step 2 — Add the Credential Echo Tool
|
||||
|
||||
Replace `src/rotation_verifier/tools/custom_tool.py` with a tool that reads the secret-backed env var and returns a fingerprint:
|
||||
|
||||
```python src/rotation_verifier/tools/credential_echo_tool.py
|
||||
"""Tool that verifies a runtime-injected secret without leaking the value.
|
||||
|
||||
Reads the secret-backed env var (populated by the workload-identity
|
||||
secrets manager at kickoff time) and returns a stable fingerprint. Never
|
||||
echo raw credential values into LLM output or logs in production code —
|
||||
the fingerprint alone is sufficient to confirm rotation worked.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import os
|
||||
|
||||
from crewai.tools import BaseTool
|
||||
|
||||
|
||||
# Match the deployment environment variable's `key` field.
|
||||
ENV_VAR_NAME = "API_KEY"
|
||||
|
||||
|
||||
class CredentialEchoTool(BaseTool):
|
||||
name: str = "credential_echo"
|
||||
description: str = (
|
||||
"Read the API credential from the worker's environment and return a "
|
||||
"fingerprint summary. Use this exactly once when asked to verify the "
|
||||
"current credential. Takes no arguments."
|
||||
)
|
||||
|
||||
def _run(self) -> str:
|
||||
value = os.environ.get(ENV_VAR_NAME)
|
||||
if not value:
|
||||
return (
|
||||
f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-"
|
||||
"identity secret fetch did not run, or the deployment is "
|
||||
"missing the secret-backed env var."
|
||||
)
|
||||
fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12]
|
||||
return f"Authenticated. credential.fingerprint=sha256:{fingerprint}"
|
||||
```
|
||||
|
||||
## Step 3 — Replace the Default Agent and Task Configs
|
||||
|
||||
The crew has one agent and one task — both with descriptions that **never** mention the secret value, so task keys stay stable across rotations.
|
||||
|
||||
```yaml src/rotation_verifier/config/agents.yaml
|
||||
credential_checker:
|
||||
role: >
|
||||
Credential Verifier
|
||||
goal: >
|
||||
Confirm that the workload-identity-backed secret reached this worker
|
||||
process and report a fingerprint of the current value.
|
||||
backstory: >
|
||||
You are a no-nonsense reliability engineer responsible for verifying
|
||||
that secrets fetched at runtime via workload identity are present
|
||||
and fresh. You always use the credential_echo tool exactly once and
|
||||
report the result verbatim — you never make up values.
|
||||
```
|
||||
|
||||
```yaml src/rotation_verifier/config/tasks.yaml
|
||||
verify_credential_task:
|
||||
description: >
|
||||
Use the credential_echo tool to read the runtime-injected credential
|
||||
and produce a one-line confirmation. The current year is {current_year}
|
||||
(use it only in the timestamp; do not transform the credential output).
|
||||
expected_output: >
|
||||
A single line in the form:
|
||||
"[{current_year}] <credential_echo tool's exact output>"
|
||||
agent: credential_checker
|
||||
```
|
||||
|
||||
## Step 4 — Wire the Crew Class
|
||||
|
||||
```python src/rotation_verifier/crew.py
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
|
||||
from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool
|
||||
|
||||
|
||||
@CrewBase
|
||||
class RotationVerifierCrew():
|
||||
"""Single-task crew that verifies a workload-identity-backed secret
|
||||
was successfully fetched at runtime.
|
||||
|
||||
Rotate the underlying secret in the cloud provider, kickoff again, and
|
||||
the credential fingerprint in the agent's report changes — without any
|
||||
re-deploy, worker restart, or input change. The crew prompt itself
|
||||
never references the secret value.
|
||||
"""
|
||||
|
||||
agents: list[BaseAgent]
|
||||
tasks: list[Task]
|
||||
|
||||
@agent
|
||||
def credential_checker(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config["credential_checker"],
|
||||
tools=[CredentialEchoTool()],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
@task
|
||||
def verify_credential_task(self) -> Task:
|
||||
return Task(config=self.tasks_config["verify_credential_task"])
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
|
||||
## Step 5 — Deploy and Configure the Secret Env Var
|
||||
|
||||
Deploy this crew to CrewAI Platform exactly as you would any other crew. Then on the deployment's **Environment Variables** page:
|
||||
|
||||
- **Key:** `API_KEY` (must match `ENV_VAR_NAME` in the tool)
|
||||
- **Value Source:** the WI-backed credential you set up in [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity)
|
||||
- **Secret Name:** the name of the secret in your cloud provider's Secret Manager
|
||||
|
||||
{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */}
|
||||
|
||||
## Step 6 — Run the First Kickoff
|
||||
|
||||
Replace `<DEPLOYMENT_AUTH_TOKEN>` and `<DEPLOYMENT_HOST>` with values from your deployment's **Run** tab.
|
||||
|
||||
```bash
|
||||
curl -m 60 \
|
||||
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST https://<DEPLOYMENT_HOST>/kickoff \
|
||||
-d '{"inputs":{"current_year":"2026"}}'
|
||||
```
|
||||
|
||||
When the kickoff completes (a few seconds), check the agent's output. You'll see:
|
||||
|
||||
```
|
||||
[2026] Authenticated. credential.fingerprint=sha256:004421b993c9
|
||||
```
|
||||
|
||||
Note the fingerprint. That hash is uniquely tied to whatever secret value is currently in your cloud provider.
|
||||
|
||||
## Step 7 — Rotate the Secret in Your Cloud Provider
|
||||
|
||||
<Tabs>
|
||||
<Tab title="AWS">
|
||||
```bash
|
||||
aws secretsmanager update-secret \
|
||||
--region <REGION> \
|
||||
--secret-id <SECRET_NAME> \
|
||||
--secret-string "rotated value"
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="GCP">
|
||||
Add a new version (Secret Manager always reads `latest`):
|
||||
|
||||
```bash
|
||||
echo -n "rotated value" | gcloud secrets versions add <SECRET_NAME> \
|
||||
--data-file=- \
|
||||
--project=<YOUR_PROJECT_ID>
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Azure">
|
||||
```bash
|
||||
az keyvault secret set \
|
||||
--vault-name <VAULT_NAME> \
|
||||
--name <SECRET_NAME> \
|
||||
--value "rotated value"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Step 8 — Run a Second Kickoff and Compare
|
||||
|
||||
```bash
|
||||
curl -m 60 \
|
||||
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-X POST https://<DEPLOYMENT_HOST>/kickoff \
|
||||
-d '{"inputs":{"current_year":"2026"}}'
|
||||
```
|
||||
|
||||
The agent's output now shows a **different fingerprint**:
|
||||
|
||||
```
|
||||
[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72
|
||||
```
|
||||
|
||||
This proves the rotation was picked up by the running deployment with no re-deploy, worker restart, or other operator action.
|
||||
|
||||
## What This Verifies — and What It Doesn't
|
||||
|
||||
**Verifies:**
|
||||
- WI OIDC token minting from CrewAI Platform works.
|
||||
- Cloud-side trust (IAM OIDC provider for AWS, Workload Identity Pool for GCP, Federated Identity Credential for Azure) accepts the token.
|
||||
- The cloud-side identity (IAM Role / GCP service account / Entra App Registration) has access to read the secret.
|
||||
- The secret value reaches `os.environ` of the worker process at kickoff time.
|
||||
- Subsequent rotations propagate to the next kickoff.
|
||||
|
||||
**Does not verify:**
|
||||
- That your real production crews handle the rotation gracefully — e.g., long-running tasks that read the env var once at startup will keep using the old value until the task ends. Plan accordingly: read secrets at the point of use, not at module import.
|
||||
|
||||
## Why Not Reference the Secret Directly in the Prompt?
|
||||
|
||||
A simpler-looking demo would put the secret value directly into a task description (e.g., "Research about `{api_key}`") and inspect the prompt. **Don't do that.** Two reasons:
|
||||
|
||||
1. **It leaks the secret into LLM call traces and provider-side logs.** Anyone with trace access can read it.
|
||||
2. **It changes the task's description at every kickoff.** CrewAI Platform identifies tasks by an MD5 hash of the description; a rotating value means the hash changes per kickoff, which breaks the deploy-time → runtime task mapping. Symptom: the task records show as `pending_run` indefinitely, or only some of a multi-task crew's tasks register.
|
||||
|
||||
The tool-based pattern in this guide sidesteps both issues: the prompt is static, the tool reads the env var at runtime, and only a fingerprint of the value reaches the LLM.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview)
|
||||
- Once verified, drop the verification crew. Real crews should follow the same pattern: secrets accessed via `os.environ` inside a tool, never substituted into prompts.
|
||||
550
docs/edge/en/enterprise/features/sso.mdx
Normal file
550
docs/edge/en/enterprise/features/sso.mdx
Normal file
@@ -0,0 +1,550 @@
|
||||
---
|
||||
title: Single Sign-On (SSO)
|
||||
icon: "key"
|
||||
description: Configure enterprise SSO authentication for CrewAI Platform — SaaS and Factory
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP)** and **Factory (self-hosted)** deployments. SSO enables your team to authenticate using your organization's existing identity provider, enforcing centralized access control, MFA policies, and user lifecycle management.
|
||||
|
||||
### Supported Providers
|
||||
|
||||
| Provider | SaaS | Factory | Protocol | CLI Support |
|
||||
|---|---|---|---|---|
|
||||
| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC | ✅ |
|
||||
| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 | ✅ |
|
||||
| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ |
|
||||
| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ |
|
||||
| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC | ✅ |
|
||||
|
||||
### Key Capabilities
|
||||
|
||||
- **SAML 2.0 and OAuth 2.0 / OIDC** protocol support
|
||||
- **Device Authorization Grant** flow for CLI authentication
|
||||
- **Role-Based Access Control (RBAC)** with custom roles and per-resource permissions
|
||||
- **MFA enforcement** delegated to your identity provider
|
||||
- **User provisioning** through IdP assignment (users/groups)
|
||||
|
||||
---
|
||||
|
||||
## SaaS SSO
|
||||
|
||||
### Default Authentication
|
||||
|
||||
CrewAI's managed SaaS platform (AMP) uses **WorkOS** as the default authentication provider. When you sign up at [app.crewai.com](https://app.crewai.com), authentication is handled through `login.crewai.com` — no additional SSO configuration is required.
|
||||
|
||||
### Enterprise Custom SSO
|
||||
|
||||
Enterprise SaaS customers can configure SSO with their own identity provider (Entra ID, Okta, Auth0). Contact your CrewAI account team to enable custom SSO for your organization. Once configured:
|
||||
|
||||
1. Your team members authenticate through your organization's IdP
|
||||
2. Access control and MFA policies are enforced by your IdP
|
||||
3. The CrewAI CLI automatically detects your SSO configuration via `crewai enterprise configure`
|
||||
|
||||
### CLI Defaults (SaaS)
|
||||
|
||||
| Setting | Default Value |
|
||||
|---|---|
|
||||
| `enterprise_base_url` | `https://app.crewai.com` |
|
||||
| `oauth2_provider` | `workos` |
|
||||
| `oauth2_domain` | `login.crewai.com` |
|
||||
|
||||
---
|
||||
|
||||
## Factory SSO Setup
|
||||
|
||||
Factory (self-hosted) deployments require you to configure SSO by setting environment variables in your Helm `values.yaml` and registering an application in your identity provider.
|
||||
|
||||
### Microsoft Entra ID (Azure AD)
|
||||
|
||||
<Steps>
|
||||
<Step title="Register an Application">
|
||||
1. Go to [portal.azure.com](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations** → **New registration**
|
||||
2. Configure:
|
||||
- **Name:** `CrewAI` (or your preferred name)
|
||||
- **Supported account types:** Accounts in this organizational directory only
|
||||
- **Redirect URI:** Select **Web**, enter `https://<your-domain>/auth/entra_id/callback`
|
||||
3. Click **Register**
|
||||
</Step>
|
||||
|
||||
<Step title="Collect Credentials">
|
||||
From the app overview page, copy:
|
||||
- **Application (client) ID** → `ENTRA_ID_CLIENT_ID`
|
||||
- **Directory (tenant) ID** → `ENTRA_ID_TENANT_ID`
|
||||
</Step>
|
||||
|
||||
<Step title="Create Client Secret">
|
||||
1. Navigate to **Certificates & Secrets** → **New client secret**
|
||||
2. Add a description and select expiration period
|
||||
3. Copy the secret value immediately (it won't be shown again) → `ENTRA_ID_CLIENT_SECRET`
|
||||
</Step>
|
||||
|
||||
<Step title="Grant Admin Consent">
|
||||
1. Go to **Enterprise applications** → select your app
|
||||
2. Under **Security** → **Permissions**, click **Grant admin consent**
|
||||
3. Ensure **Microsoft Graph → User.Read** is granted
|
||||
</Step>
|
||||
|
||||
<Step title="Configure App Roles (Recommended)">
|
||||
Under **App registrations** → your app → **App roles**, create:
|
||||
|
||||
| Display Name | Value | Allowed Member Types |
|
||||
|---|---|---|
|
||||
| Member | `member` | Users/Groups |
|
||||
| Factory Admin | `factory-admin` | Users/Groups |
|
||||
|
||||
<Note>
|
||||
The `member` role grants login access. The `factory-admin` role grants admin panel access. Roles are included in the JWT automatically.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Assign Users">
|
||||
1. Under **Properties**, set **Assignment required?** to **Yes**
|
||||
2. Under **Users and groups**, assign users/groups with the appropriate role
|
||||
</Step>
|
||||
|
||||
<Step title="Set Environment Variables">
|
||||
```yaml
|
||||
envVars:
|
||||
AUTH_PROVIDER: "entra_id"
|
||||
|
||||
secrets:
|
||||
ENTRA_ID_CLIENT_ID: "<Application (client) ID>"
|
||||
ENTRA_ID_CLIENT_SECRET: "<Client Secret>"
|
||||
ENTRA_ID_TENANT_ID: "<Directory (tenant) ID>"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Enable CLI Support (Optional)">
|
||||
To allow `crewai login` via Device Authorization Grant:
|
||||
|
||||
1. Under **Authentication** → **Advanced settings**, enable **Allow public client flows**
|
||||
2. Under **Expose an API**, add an Application ID URI (e.g., `api://crewai-cli`)
|
||||
3. Add a scope (e.g., `read`) with **Admins and users** consent
|
||||
4. Under **Manifest**, set `accessTokenAcceptedVersion` to `2`
|
||||
5. Add environment variables:
|
||||
|
||||
```yaml
|
||||
secrets:
|
||||
ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID: "<Application (client) ID>"
|
||||
ENTRA_ID_CUSTOM_OPENID_SCOPE: "<scope URI, e.g. api://crewai-cli/read>"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
### Okta
|
||||
|
||||
<Steps>
|
||||
<Step title="Create App Integration">
|
||||
1. Open Okta Admin Console → **Applications** → **Create App Integration**
|
||||
2. Select **OIDC - OpenID Connect** → **Web Application** → **Next**
|
||||
3. Configure:
|
||||
- **App integration name:** `CrewAI SSO`
|
||||
- **Sign-in redirect URI:** `https://<your-domain>/auth/okta/callback`
|
||||
- **Sign-out redirect URI:** `https://<your-domain>`
|
||||
- **Assignments:** Choose who can access (everyone or specific groups)
|
||||
4. Click **Save**
|
||||
</Step>
|
||||
|
||||
<Step title="Collect Credentials">
|
||||
From the app details page:
|
||||
- **Client ID** → `OKTA_CLIENT_ID`
|
||||
- **Client Secret** → `OKTA_CLIENT_SECRET`
|
||||
- **Okta URL** (top-right corner, under your username) → `OKTA_SITE`
|
||||
</Step>
|
||||
|
||||
<Step title="Configure Authorization Server">
|
||||
1. Navigate to **Security** → **API**
|
||||
2. Select your authorization server (default: `default`)
|
||||
3. Under **Access Policies**, add a policy and rule:
|
||||
- In the rule, under **Scopes requested**, select **The following scopes** → **OIDC default scopes**
|
||||
4. Note the **Name** and **Audience** of the authorization server
|
||||
|
||||
<Warning>
|
||||
The authorization server name and audience must match `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` exactly. Mismatches cause `401 Unauthorized` or `Invalid token: Signature verification failed` errors.
|
||||
</Warning>
|
||||
</Step>
|
||||
|
||||
<Step title="Set Environment Variables">
|
||||
```yaml
|
||||
envVars:
|
||||
AUTH_PROVIDER: "okta"
|
||||
|
||||
secrets:
|
||||
OKTA_CLIENT_ID: "<Okta app client ID>"
|
||||
OKTA_CLIENT_SECRET: "<Okta client secret>"
|
||||
OKTA_SITE: "https://your-domain.okta.com"
|
||||
OKTA_AUTHORIZATION_SERVER: "default"
|
||||
OKTA_AUDIENCE: "api://default"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Enable CLI Support (Optional)">
|
||||
1. Create a **new** app integration: **OIDC** → **Native Application**
|
||||
2. Enable **Device Authorization** and **Refresh Token** grant types
|
||||
3. Allow everyone in your organization to access
|
||||
4. Add environment variable:
|
||||
|
||||
```yaml
|
||||
secrets:
|
||||
OKTA_DEVICE_AUTHORIZATION_CLIENT_ID: "<Native app client ID>"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Device Authorization requires a **Native Application** — it cannot use the Web Application created for browser-based SSO.
|
||||
</Note>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
### Keycloak
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Client">
|
||||
1. Open Keycloak Admin Console → navigate to your realm
|
||||
2. **Clients** → **Create client**:
|
||||
- **Client type:** OpenID Connect
|
||||
- **Client ID:** `crewai-factory` (suggested)
|
||||
3. Capability config:
|
||||
- **Client authentication:** On
|
||||
- **Standard flow:** Checked
|
||||
4. Login settings:
|
||||
- **Root URL:** `https://<your-domain>`
|
||||
- **Valid redirect URIs:** `https://<your-domain>/auth/keycloak/callback`
|
||||
- **Valid post logout redirect URIs:** `https://<your-domain>`
|
||||
5. Click **Save**
|
||||
</Step>
|
||||
|
||||
<Step title="Collect Credentials">
|
||||
- **Client ID** → `KEYCLOAK_CLIENT_ID`
|
||||
- Under **Credentials** tab: **Client secret** → `KEYCLOAK_CLIENT_SECRET`
|
||||
- **Realm name** → `KEYCLOAK_REALM`
|
||||
- **Keycloak server URL** → `KEYCLOAK_SITE`
|
||||
</Step>
|
||||
|
||||
<Step title="Set Environment Variables">
|
||||
```yaml
|
||||
envVars:
|
||||
AUTH_PROVIDER: "keycloak"
|
||||
|
||||
secrets:
|
||||
KEYCLOAK_CLIENT_ID: "<client ID>"
|
||||
KEYCLOAK_CLIENT_SECRET: "<client secret>"
|
||||
KEYCLOAK_SITE: "https://keycloak.yourdomain.com"
|
||||
KEYCLOAK_REALM: "<realm name>"
|
||||
KEYCLOAK_AUDIENCE: "account"
|
||||
# Only set if using a custom base path (pre-v17 migrations):
|
||||
# KEYCLOAK_BASE_URL: "/auth"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Keycloak includes `account` as the default audience in access tokens. For most installations, `KEYCLOAK_AUDIENCE=account` works without additional configuration. See [Keycloak audience documentation](https://www.keycloak.org/docs/latest/authorization_services/index.html) if you need a custom audience.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Enable CLI Support (Optional)">
|
||||
1. Create a **second** client:
|
||||
- **Client type:** OpenID Connect
|
||||
- **Client ID:** `crewai-factory-cli` (suggested)
|
||||
- **Client authentication:** Off (Device Authorization requires a public client)
|
||||
- **Authentication flow:** Check **only** OAuth 2.0 Device Authorization Grant
|
||||
2. Add environment variable:
|
||||
|
||||
```yaml
|
||||
secrets:
|
||||
KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID: "<CLI client ID>"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
### WorkOS
|
||||
|
||||
<Steps>
|
||||
<Step title="Configure in WorkOS Dashboard">
|
||||
1. Create an application in the [WorkOS Dashboard](https://dashboard.workos.com)
|
||||
2. Configure the redirect URI: `https://<your-domain>/auth/workos/callback`
|
||||
3. Note the **Client ID** and **AuthKit domain**
|
||||
4. Set up organizations in the WorkOS dashboard
|
||||
</Step>
|
||||
|
||||
<Step title="Set Environment Variables">
|
||||
```yaml
|
||||
envVars:
|
||||
AUTH_PROVIDER: "workos"
|
||||
|
||||
secrets:
|
||||
WORKOS_CLIENT_ID: "<WorkOS client ID>"
|
||||
WORKOS_AUTHKIT_DOMAIN: "<your-authkit-domain.authkit.com>"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
### Auth0
|
||||
|
||||
<Steps>
|
||||
<Step title="Create Application">
|
||||
1. In the [Auth0 Dashboard](https://manage.auth0.com), create a new **Regular Web Application**
|
||||
2. Configure:
|
||||
- **Allowed Callback URLs:** `https://<your-domain>/auth/auth0/callback`
|
||||
- **Allowed Logout URLs:** `https://<your-domain>`
|
||||
3. Note the **Domain**, **Client ID**, and **Client Secret**
|
||||
</Step>
|
||||
|
||||
<Step title="Set Environment Variables">
|
||||
```yaml
|
||||
envVars:
|
||||
AUTH_PROVIDER: "auth0"
|
||||
|
||||
secrets:
|
||||
AUTH0_CLIENT_ID: "<Auth0 client ID>"
|
||||
AUTH0_CLIENT_SECRET: "<Auth0 client secret>"
|
||||
AUTH0_DOMAIN: "<your-tenant.auth0.com>"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Enable CLI Support (Optional)">
|
||||
1. Create a **Native** application in Auth0 for Device Authorization
|
||||
2. Enable the **Device Authorization** grant type under application settings
|
||||
3. Configure the CLI with the appropriate audience and client ID
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## CLI Authentication
|
||||
|
||||
The CrewAI CLI supports SSO authentication via the **Device Authorization Grant** flow. This allows developers to authenticate from their terminal without exposing credentials.
|
||||
|
||||
### Quick Setup
|
||||
|
||||
For Factory installations, the CLI can auto-configure all OAuth2 settings:
|
||||
|
||||
```bash
|
||||
crewai enterprise configure https://your-factory-url.app
|
||||
```
|
||||
|
||||
This command fetches the SSO configuration from your Factory instance and sets all required CLI parameters automatically.
|
||||
|
||||
Then authenticate:
|
||||
|
||||
```bash
|
||||
crewai login
|
||||
```
|
||||
|
||||
<Note>
|
||||
Requires CrewAI CLI version **1.6.0** or higher for Entra ID, **0.159.0** or higher for Okta, and **1.9.0** or higher for Keycloak.
|
||||
</Note>
|
||||
|
||||
### Manual CLI Configuration
|
||||
|
||||
If you need to configure the CLI manually, use `crewai config set`:
|
||||
|
||||
```bash
|
||||
# Set the provider
|
||||
crewai config set oauth2_provider okta
|
||||
|
||||
# Set provider-specific values
|
||||
crewai config set oauth2_domain your-domain.okta.com
|
||||
crewai config set oauth2_client_id your-client-id
|
||||
crewai config set oauth2_audience api://default
|
||||
|
||||
# Set the enterprise base URL
|
||||
crewai config set enterprise_base_url https://your-factory-url.app
|
||||
```
|
||||
|
||||
### CLI Configuration Reference
|
||||
|
||||
| Setting | Description | Example |
|
||||
|---|---|---|
|
||||
| `enterprise_base_url` | Your CrewAI instance URL | `https://crewai.yourcompany.com` |
|
||||
| `oauth2_provider` | Provider name | `workos`, `okta`, `auth0`, `entra_id`, `keycloak` |
|
||||
| `oauth2_domain` | Provider domain | `your-domain.okta.com` |
|
||||
| `oauth2_client_id` | OAuth2 client ID | `0oaqnwji7pGW7VT6T697` |
|
||||
| `oauth2_audience` | API audience identifier | `api://default` |
|
||||
|
||||
View current configuration:
|
||||
|
||||
```bash
|
||||
crewai config list
|
||||
```
|
||||
|
||||
### How Device Authorization Works
|
||||
|
||||
1. Run `crewai login` — the CLI requests a device code from your IdP
|
||||
2. A verification URL and code are displayed in your terminal
|
||||
3. Your browser opens to the verification URL
|
||||
4. Enter the code and authenticate with your IdP credentials
|
||||
5. The CLI receives an access token and stores it locally
|
||||
|
||||
---
|
||||
|
||||
## Role-Based Access Control (RBAC)
|
||||
|
||||
CrewAI Platform provides granular RBAC that integrates with your SSO provider.
|
||||
|
||||
### Permission Model
|
||||
|
||||
| Permission | Description |
|
||||
|---|---|
|
||||
| **Read** | View resources (dashboards, automations, logs) |
|
||||
| **Write** | Create and modify resources |
|
||||
| **Manage** | Full control including deletion and configuration |
|
||||
|
||||
### Resources
|
||||
|
||||
Permissions can be scoped to individual resources:
|
||||
|
||||
- **Usage Dashboard** — Platform usage metrics and analytics
|
||||
- **Automations Dashboard** — Crew and flow management
|
||||
- **Environment Variables** — Secret and configuration management
|
||||
- **Individual Automations** — Per-automation access control
|
||||
|
||||
### Roles
|
||||
|
||||
- **Predefined roles** come out of the box with standard permission sets
|
||||
- **Custom roles** can be created with any combination of permissions
|
||||
- **Per-resource assignment** — limit specific automations to individual users or roles
|
||||
|
||||
### Factory Admin Access
|
||||
|
||||
For Factory deployments using Entra ID, admin access is controlled via App Roles:
|
||||
|
||||
- Assign the `factory-admin` role to users who need admin panel access
|
||||
- Assign the `member` role for standard platform access
|
||||
- Roles are communicated via JWT claims — no additional configuration needed after IdP setup
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Invalid Redirect URI
|
||||
|
||||
**Symptom:** Authentication fails with a redirect URI mismatch error.
|
||||
|
||||
**Fix:** Ensure the redirect URI in your IdP exactly matches the expected callback URL:
|
||||
|
||||
| Provider | Callback URL |
|
||||
|---|---|
|
||||
| Entra ID | `https://<domain>/auth/entra_id/callback` |
|
||||
| Okta | `https://<domain>/auth/okta/callback` |
|
||||
| Keycloak | `https://<domain>/auth/keycloak/callback` |
|
||||
| WorkOS | `https://<domain>/auth/workos/callback` |
|
||||
| Auth0 | `https://<domain>/auth/auth0/callback` |
|
||||
|
||||
### CLI Login Fails (Device Authorization)
|
||||
|
||||
**Symptom:** `crewai login` returns an error or times out.
|
||||
|
||||
**Fix:**
|
||||
- Verify that Device Authorization Grant is enabled in your IdP
|
||||
- For Okta: ensure you have a **Native Application** (not Web) with Device Authorization grant
|
||||
- For Entra ID: ensure **Allow public client flows** is enabled
|
||||
- For Keycloak: ensure the CLI client has **Client authentication: Off** and only Device Authorization Grant enabled
|
||||
- Check that `*_DEVICE_AUTHORIZATION_CLIENT_ID` environment variable is set on the server
|
||||
|
||||
### Token Validation Errors
|
||||
|
||||
**Symptom:** `Invalid token: Signature verification failed` or `401 Unauthorized` after login.
|
||||
|
||||
**Fix:**
|
||||
- **Okta:** Verify `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` match the authorization server's Name and Audience exactly
|
||||
- **Entra ID:** Ensure `accessTokenAcceptedVersion` is set to `2` in the app manifest
|
||||
- **Keycloak:** Verify `KEYCLOAK_AUDIENCE` matches the audience in your access tokens (default: `account`)
|
||||
|
||||
### Admin Consent Not Granted (Entra ID)
|
||||
|
||||
**Symptom:** Users can't log in, see "needs admin approval" message.
|
||||
|
||||
**Fix:** Go to **Enterprise applications** → your app → **Permissions** → **Grant admin consent**. Ensure `User.Read` is granted for Microsoft Graph.
|
||||
|
||||
### 403 Forbidden After Login
|
||||
|
||||
**Symptom:** User authenticates successfully but gets 403 errors.
|
||||
|
||||
**Fix:**
|
||||
- Check that the user is assigned to the application in your IdP
|
||||
- For Entra ID with **Assignment required = Yes**: ensure the user has a role assignment (Member or Factory Admin)
|
||||
- For Okta: verify the user or their group is assigned under the app's **Assignments** tab
|
||||
|
||||
### CLI Can't Reach Factory Instance
|
||||
|
||||
**Symptom:** `crewai enterprise configure` fails to connect.
|
||||
|
||||
**Fix:**
|
||||
- Verify the Factory URL is reachable from your machine
|
||||
- Check that `enterprise_base_url` is set correctly: `crewai config list`
|
||||
- Ensure TLS certificates are valid and trusted
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables Reference
|
||||
|
||||
### Common
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `AUTH_PROVIDER` | Authentication provider: `entra_id`, `okta`, `workos`, `auth0`, `keycloak`, `local` |
|
||||
|
||||
### Microsoft Entra ID
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `ENTRA_ID_CLIENT_ID` | ✅ | Application (client) ID from Azure |
|
||||
| `ENTRA_ID_CLIENT_SECRET` | ✅ | Client secret from Azure |
|
||||
| `ENTRA_ID_TENANT_ID` | ✅ | Directory (tenant) ID from Azure |
|
||||
| `ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Client ID for Device Authorization Grant |
|
||||
| `ENTRA_ID_CUSTOM_OPENID_SCOPE` | CLI only | Custom scope from "Expose an API" (e.g., `api://crewai-cli/read`) |
|
||||
|
||||
### Okta
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `OKTA_CLIENT_ID` | ✅ | Okta application client ID |
|
||||
| `OKTA_CLIENT_SECRET` | ✅ | Okta client secret |
|
||||
| `OKTA_SITE` | ✅ | Okta organization URL (e.g., `https://your-domain.okta.com`) |
|
||||
| `OKTA_AUTHORIZATION_SERVER` | ✅ | Authorization server name (e.g., `default`) |
|
||||
| `OKTA_AUDIENCE` | ✅ | Authorization server audience (e.g., `api://default`) |
|
||||
| `OKTA_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Native app client ID for Device Authorization |
|
||||
|
||||
### WorkOS
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `WORKOS_CLIENT_ID` | ✅ | WorkOS application client ID |
|
||||
| `WORKOS_AUTHKIT_DOMAIN` | ✅ | AuthKit domain (e.g., `your-domain.authkit.com`) |
|
||||
|
||||
### Auth0
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `AUTH0_CLIENT_ID` | ✅ | Auth0 application client ID |
|
||||
| `AUTH0_CLIENT_SECRET` | ✅ | Auth0 client secret |
|
||||
| `AUTH0_DOMAIN` | ✅ | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
|
||||
|
||||
### Keycloak
|
||||
|
||||
| Variable | Required | Description |
|
||||
|---|---|---|
|
||||
| `KEYCLOAK_CLIENT_ID` | ✅ | Keycloak client ID |
|
||||
| `KEYCLOAK_CLIENT_SECRET` | ✅ | Keycloak client secret |
|
||||
| `KEYCLOAK_SITE` | ✅ | Keycloak server URL |
|
||||
| `KEYCLOAK_REALM` | ✅ | Keycloak realm name |
|
||||
| `KEYCLOAK_AUDIENCE` | ✅ | Token audience (default: `account`) |
|
||||
| `KEYCLOAK_BASE_URL` | Optional | Base URL path (e.g., `/auth` for pre-v17 migrations) |
|
||||
| `KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Public client ID for Device Authorization |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Installation Guide](/installation) — Get started with CrewAI
|
||||
- [Quickstart](/quickstart) — Build your first crew
|
||||
- [RBAC Setup](/enterprise/features/rbac) — Detailed role and permission management
|
||||
262
docs/edge/en/enterprise/features/tools-and-integrations.mdx
Normal file
262
docs/edge/en/enterprise/features/tools-and-integrations.mdx
Normal 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>
|
||||
|
||||
</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></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>
|
||||
|
||||
</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>
|
||||
|
||||
</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></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>
|
||||
|
||||
</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></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/edge/en/enterprise/features/traces.mdx
Normal file
148
docs/edge/en/enterprise/features/traces.mdx
Normal 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></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></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></Frame>
|
||||
|
||||
### 3. Final Output
|
||||
|
||||
Displays the final result produced by the crew after all tasks are completed.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 4. Execution Timeline
|
||||
|
||||
A visual representation of when each task started and ended, helping you identify bottlenecks or parallel execution patterns.
|
||||
|
||||
<Frame></Frame>
|
||||
|
||||
### 5. Detailed Task View
|
||||
|
||||
When you click on a specific task in the timeline or task list, you'll see:
|
||||
|
||||
<Frame></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>
|
||||
|
||||
</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/edge/en/enterprise/features/webhook-streaming.mdx
Normal file
173
docs/edge/en/enterprise/features/webhook-streaming.mdx
Normal 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/edge/en/enterprise/guides/automation-triggers.mdx
Normal file
322
docs/edge/en/enterprise/guides/automation-triggers.mdx
Normal 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>
|
||||
|
||||
</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/edge/en/enterprise/guides/azure-openai-setup.mdx
Normal file
54
docs/edge/en/enterprise/guides/azure-openai-setup.mdx
Normal 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/edge/en/enterprise/guides/build-crew.mdx
Normal file
48
docs/edge/en/enterprise/guides/build-crew.mdx
Normal 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>
|
||||
63
docs/edge/en/enterprise/guides/capture_telemetry_logs.mdx
Normal file
63
docs/edge/en/enterprise/guides/capture_telemetry_logs.mdx
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
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:
|
||||
- **OpenTelemetry Traces** and **OpenTelemetry Logs** — export to any OTLP-compatible collector or backend.
|
||||
- **Datadog** — send traces straight to Datadog's OTLP intake, no separate collector or Datadog Agent required.
|
||||
4. Configure the connection. The fields depend on the integration you selected:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenTelemetry Traces / Logs">
|
||||
**OpenTelemetry Traces** and **OpenTelemetry Logs** are separate integrations that share the same fields — pick the one matching the signal you want to export.
|
||||
|
||||
- **Endpoint** — Your collector's OTLP endpoint (e.g., `https://otel-collector.example.com:4317`).
|
||||
- **Service Name** — A name to identify this service in your observability platform.
|
||||
- **Custom Headers** *(optional)* — Add authentication or routing headers as key-value pairs.
|
||||
- **Certificate** *(optional)* — Provide a TLS certificate if your collector requires one.
|
||||
|
||||
<Frame></Frame>
|
||||
</Tab>
|
||||
<Tab title="Datadog">
|
||||
- **Datadog Site Domain** — Your Datadog site's OTLP host only, with no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
|
||||
- `otlp.datadoghq.com` (US1)
|
||||
- `otlp.us3.datadoghq.com` (US3)
|
||||
- `otlp.us5.datadoghq.com` (US5)
|
||||
- `otlp.datadoghq.eu` (EU1)
|
||||
- `otlp.ap1.datadoghq.com` (AP1)
|
||||
- **API Key** — Your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
|
||||
|
||||
The Datadog integration exports **traces**.
|
||||
|
||||
<Frame></Frame>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
5. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided.
|
||||
6. Click **Save**.
|
||||
|
||||
<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/edge/en/enterprise/guides/custom-mcp-server.mdx
Normal file
136
docs/edge/en/enterprise/guides/custom-mcp-server.mdx
Normal 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>
|
||||
451
docs/edge/en/enterprise/guides/deploy-to-amp.mdx
Normal file
451
docs/edge/en/enterprise/guides/deploy-to-amp.mdx
Normal file
@@ -0,0 +1,451 @@
|
||||
---
|
||||
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 around 1 minute.
|
||||
</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>
|
||||
|
||||
</Frame>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Select the Repository">
|
||||
|
||||
After connecting your GitHub account, you'll be able to select which repository to deploy:
|
||||
|
||||
<Frame>
|
||||
|
||||
</Frame>
|
||||
|
||||
<Tip>
|
||||
If your Crew or Flow is inside a monorepo subfolder, expand **Advanced**
|
||||
and set a working directory before deploying. See
|
||||
[Monorepo Deployments](/en/enterprise/guides/monorepo-deployments).
|
||||
</Tip>
|
||||
|
||||
</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>
|
||||
|
||||
</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 1 minute
|
||||
|
||||
<Frame>
|
||||
|
||||
</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:
|
||||
|
||||
- **JSON-first Crews**: Keep `crew.jsonc` or `crew.json` and `agents/` at the project root
|
||||
- **Classic Crews**: Use `src/project_name/main.py` with a `run()` entry point
|
||||
- **Flows**: Use `src/project_name/main.py` with a `kickoff()` entry point
|
||||
|
||||
See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for detailed structure diagrams.
|
||||
|
||||
#### Missing CrewBase Decorator in a Classic Crew
|
||||
|
||||
**Symptom**: "Crew not found", "Config not found", or agent/task configuration errors
|
||||
|
||||
**Solution**: For classic Python/YAML crews, ensure all crew classes use the `@CrewBase` decorator. JSON-first crews do not need this decorator.
|
||||
|
||||
```python
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
|
||||
@CrewBase # This decorator is REQUIRED
|
||||
class YourCrew():
|
||||
"""Your crew description"""
|
||||
|
||||
@agent
|
||||
def my_agent(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['my_agent'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# ... rest of crew definition
|
||||
```
|
||||
|
||||
<Info>
|
||||
This applies to classic Python crew classes, including classic crews embedded inside Flow projects.
|
||||
JSON-first crews are validated from `crew.jsonc` and `agents/` instead.
|
||||
</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. For JSON-first crews, validate `crew.jsonc` and the referenced files in `agents/`
|
||||
4. For classic crews, ensure `agents.yaml` and `tasks.yaml` are valid
|
||||
|
||||
<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>
|
||||
179
docs/edge/en/enterprise/guides/enable-crew-studio.mdx
Normal file
179
docs/edge/en/enterprise/guides/enable-crew-studio.mdx
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
|
||||
</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/edge/en/enterprise/guides/gmail-trigger.mdx
Normal file
97
docs/edge/en/enterprise/guides/gmail-trigger.mdx
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: "Gmail Trigger"
|
||||
description: "Trigger automations when Gmail events occur (e.g., new emails, labels)."
|
||||
icon: "envelope"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use the Gmail Trigger to kick off your deployed crews when Gmail events happen in connected accounts, such as receiving a new email or messages matching a label/filter.
|
||||
|
||||
<Tip>
|
||||
Make sure Gmail is connected in Tools & Integrations and the trigger is
|
||||
enabled for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Gmail Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Gmail** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/trigger-selected.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Process new emails
|
||||
|
||||
When a new email arrives, the Gmail Trigger will send the payload to your Crew or Flow. Below is a Crew example that parses and processes the trigger payload.
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class GmailProcessingCrew:
|
||||
@agent
|
||||
def parser(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['parser'],
|
||||
)
|
||||
|
||||
@task
|
||||
def parse_gmail_payload(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['parse_gmail_payload'],
|
||||
agent=self.parser(),
|
||||
)
|
||||
|
||||
@task
|
||||
def act_on_email(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['act_on_email'],
|
||||
agent=self.parser(),
|
||||
)
|
||||
```
|
||||
|
||||
The Gmail payload will be available via the standard context mechanisms.
|
||||
|
||||
### 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/edge/en/enterprise/guides/google-calendar-trigger.mdx
Normal file
83
docs/edge/en/enterprise/guides/google-calendar-trigger.mdx
Normal 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/edge/en/enterprise/guides/google-drive-trigger.mdx
Normal file
80
docs/edge/en/enterprise/guides/google-drive-trigger.mdx
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: "Google Drive Trigger"
|
||||
description: "Respond to Google Drive file events with automated crews"
|
||||
icon: "folder"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Trigger your automations when files are created, updated, or removed in Google Drive. Typical workflows include summarizing newly uploaded content, enforcing sharing policies, or notifying owners when critical files change.
|
||||
|
||||
<Tip>
|
||||
Connect Google Drive in **Tools & Integrations** and confirm the trigger is
|
||||
enabled for the automation you want to monitor.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Google Drive Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Google Drive** and switch the toggle to enable
|
||||
|
||||
<Frame>
|
||||
<img
|
||||
src="/images/enterprise/gdrive-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize file activity
|
||||
|
||||
The drive example crews parse the payload to extract file metadata, evaluate permissions, and publish a summary.
|
||||
|
||||
```python
|
||||
from drive_file_crew import GoogleDriveFileTrigger
|
||||
|
||||
crew = GoogleDriveFileTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": drive_payload,
|
||||
})
|
||||
```
|
||||
|
||||
## 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/edge/en/enterprise/guides/hubspot-trigger.mdx
Normal file
61
docs/edge/en/enterprise/guides/hubspot-trigger.mdx
Normal 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/edge/en/enterprise/guides/human-in-the-loop.mdx
Normal file
157
docs/edge/en/enterprise/guides/human-in-the-loop.mdx
Normal 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/edge/en/enterprise/guides/kickoff-crew.mdx
Normal file
178
docs/edge/en/enterprise/guides/kickoff-crew.mdx
Normal 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></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></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></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></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></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/edge/en/enterprise/guides/microsoft-teams-trigger.mdx
Normal file
70
docs/edge/en/enterprise/guides/microsoft-teams-trigger.mdx
Normal 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
|
||||
229
docs/edge/en/enterprise/guides/monorepo-deployments.mdx
Normal file
229
docs/edge/en/enterprise/guides/monorepo-deployments.mdx
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
title: "Monorepo Deployments"
|
||||
description: "Deploy a Crew or Flow from a subfolder in a larger repository"
|
||||
icon: "folder-tree"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Use a working directory when your Crew or Flow lives inside a larger
|
||||
repository. CrewAI AMP validates, builds, tests, and runs the automation from
|
||||
that subfolder instead of the repository root.
|
||||
</Note>
|
||||
|
||||
## When to Use This
|
||||
|
||||
Monorepo deployments are useful when one repository contains multiple
|
||||
automations, shared packages, or other application code:
|
||||
|
||||
```text
|
||||
company-ai/
|
||||
|-- uv.lock
|
||||
|-- packages/
|
||||
| `-- shared_tools/
|
||||
`-- crews/
|
||||
|-- support_agent/
|
||||
| |-- pyproject.toml
|
||||
| |-- crew.jsonc
|
||||
| `-- agents/
|
||||
| `-- support_agent.jsonc
|
||||
`-- research_flow/
|
||||
|-- pyproject.toml
|
||||
`-- src/
|
||||
`-- research_flow/
|
||||
`-- main.py
|
||||
```
|
||||
|
||||
To deploy `support_agent`, set the working directory to:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
|
||||
AMP still pulls or uploads the whole repository, but it treats the selected
|
||||
folder as the automation project root.
|
||||
|
||||
## What the Working Directory Controls
|
||||
|
||||
When a working directory is set, AMP uses that folder for:
|
||||
|
||||
- Project validation, including `pyproject.toml`, JSON crew files, and any classic Crew or Flow entry point
|
||||
- Dependency installation with `uv`
|
||||
- The running process working directory
|
||||
- The `CREW_ROOT_DIR` environment variable
|
||||
|
||||
Leaving the field empty keeps the existing behavior and uses the repository
|
||||
root.
|
||||
|
||||
## Supported Sources
|
||||
|
||||
You can set a working directory when creating a deployment from:
|
||||
|
||||
- A connected GitHub repository
|
||||
- A Git repository configured in AMP
|
||||
- A ZIP upload
|
||||
|
||||
<Info>
|
||||
Configure working directories in the AMP web interface. The
|
||||
`crewai deploy create` CLI flow does not prompt for this field.
|
||||
</Info>
|
||||
|
||||
You can also add or change the working directory on an existing deployment from
|
||||
the deployment's **Settings** page. The change takes effect on the next deploy.
|
||||
|
||||
<Warning>
|
||||
Working directories and auto-deploy cannot be used together. If a deployment
|
||||
has a working directory, auto-deploy is disabled for that deployment. Turn
|
||||
auto-deploy off before setting a working directory.
|
||||
</Warning>
|
||||
|
||||
## Configure a New Deployment
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Deploy from Code">
|
||||
In CrewAI AMP, create a new deployment and choose your source: GitHub, Git
|
||||
Repository, or ZIP upload.
|
||||
</Step>
|
||||
|
||||
<Step title="Select the repository, branch, or ZIP file">
|
||||
Choose the repository and branch that contain your monorepo, or upload a ZIP
|
||||
file whose root contains the monorepo contents.
|
||||
</Step>
|
||||
|
||||
<Step title="Open Advanced settings">
|
||||
Expand the **Advanced** section in the deploy form.
|
||||
</Step>
|
||||
|
||||
<Step title="Enter the working directory">
|
||||
Enter the path from the repository root to the Crew or Flow project:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
|
||||
Do not include a leading slash.
|
||||
</Step>
|
||||
|
||||
<Step title="Deploy">
|
||||
Add any required environment variables, then start the deployment.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Configure an Existing Deployment
|
||||
|
||||
<Steps>
|
||||
<Step title="Open the deployment settings">
|
||||
Go to your automation in AMP and open **Settings**.
|
||||
</Step>
|
||||
|
||||
<Step title="Turn off auto-deploy if needed">
|
||||
If auto-deploy is enabled, disable it first. The working directory field is
|
||||
unavailable while auto-deploy is on.
|
||||
</Step>
|
||||
|
||||
<Step title="Set the working directory">
|
||||
In **Basic settings**, enter the subfolder path, such as:
|
||||
|
||||
```text
|
||||
crews/support_agent
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Redeploy">
|
||||
Save the setting and redeploy the automation. The new working directory is
|
||||
used on the next deploy.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Path Rules
|
||||
|
||||
The working directory must be a relative path inside the repository or ZIP root.
|
||||
|
||||
| Rule | Example |
|
||||
|------|---------|
|
||||
| Use a relative path | `crews/support_agent` |
|
||||
| Do not start with `/` | `/crews/support_agent` is invalid |
|
||||
| Do not use `.` or `..` path segments | `crews/../support_agent` is invalid |
|
||||
| Use only letters, numbers, dashes, underscores, dots, and forward slashes | `crews/support agent` is invalid |
|
||||
| Keep the path at 255 characters or fewer | Longer paths are rejected |
|
||||
|
||||
AMP trims leading and trailing whitespace, collapses repeated slashes, and
|
||||
removes trailing slashes. A blank value uses the repository root.
|
||||
|
||||
## Lock Files and UV Workspaces
|
||||
|
||||
The selected folder must contain the automation's `pyproject.toml` and the
|
||||
project files for its type:
|
||||
|
||||
- JSON-first crew: `crew.jsonc` or `crew.json`, plus `agents/`
|
||||
- Classic crew or Flow: `src/` with the expected Python entry point
|
||||
|
||||
A `uv.lock` or `poetry.lock` file can live either in the selected folder or at
|
||||
the repository root.
|
||||
|
||||
This supports both common lock-file layouts:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Project lock file">
|
||||
```text
|
||||
company-ai/
|
||||
`-- crews/
|
||||
`-- support_agent/
|
||||
|-- pyproject.toml
|
||||
|-- uv.lock
|
||||
|-- crew.jsonc
|
||||
`-- agents/
|
||||
`-- support_agent.jsonc
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="Workspace lock file">
|
||||
```text
|
||||
company-ai/
|
||||
|-- uv.lock
|
||||
|-- packages/
|
||||
| `-- shared_tools/
|
||||
`-- crews/
|
||||
`-- support_agent/
|
||||
|-- pyproject.toml
|
||||
|-- crew.jsonc
|
||||
`-- agents/
|
||||
`-- support_agent.jsonc
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
If your automation imports shared packages from elsewhere in the monorepo,
|
||||
declare those packages in `pyproject.toml` using UV workspace, path, or source
|
||||
configuration. AMP runs the automation from the selected folder, so shared
|
||||
code should be installed as a dependency instead of relying on the repository
|
||||
root being on the Python path.
|
||||
</Tip>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Working Directory Not Found
|
||||
|
||||
Check that the path is relative to the repository or ZIP root. For ZIP uploads,
|
||||
the ZIP contents must include the working directory path exactly as entered.
|
||||
|
||||
### Missing pyproject.toml
|
||||
|
||||
The working directory should point to the Crew or Flow project folder, not just
|
||||
to a parent folder that contains several projects.
|
||||
|
||||
### Missing uv.lock or poetry.lock
|
||||
|
||||
Commit a lock file either in the selected project folder or in the repository
|
||||
root. For UV workspaces, keeping `uv.lock` at the workspace root is supported.
|
||||
|
||||
### Auto-Deploy Is Unavailable
|
||||
|
||||
Auto-deploy is disabled while a working directory is set. Use manual redeploys
|
||||
or trigger redeployments from CI/CD with the AMP API instead.
|
||||
|
||||
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
|
||||
Continue with the deployment guide after choosing your monorepo working
|
||||
directory.
|
||||
</Card>
|
||||
69
docs/edge/en/enterprise/guides/onedrive-trigger.mdx
Normal file
69
docs/edge/en/enterprise/guides/onedrive-trigger.mdx
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "OneDrive Trigger"
|
||||
description: "Automate responses to OneDrive file activity"
|
||||
icon: "cloud"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Start automations when files change inside OneDrive. You can generate audit summaries, notify security teams about external sharing, or update downstream line-of-business systems with new document metadata.
|
||||
|
||||
<Tip>
|
||||
Connect OneDrive in **Tools & Integrations** and toggle the trigger on for
|
||||
your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the OneDrive Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **OneDrive** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft OneDrive trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/onedrive-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Audit file permissions
|
||||
|
||||
```python
|
||||
from onedrive_file_crew import OneDriveFileTrigger
|
||||
|
||||
crew = OneDriveFileTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": onedrive_payload,
|
||||
})
|
||||
```
|
||||
|
||||
The crew inspects file metadata, user activity, and permission changes to produce a compliance-friendly summary.
|
||||
|
||||
## 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/edge/en/enterprise/guides/outlook-trigger.mdx
Normal file
69
docs/edge/en/enterprise/guides/outlook-trigger.mdx
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: "Outlook Trigger"
|
||||
description: "Launch automations from Outlook emails and calendar updates"
|
||||
icon: "microsoft"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Automate responses when Outlook delivers a new message or when an event is removed from the calendar. Teams commonly route escalations, file tickets, or alert attendees of cancellations.
|
||||
|
||||
<Tip>
|
||||
Connect Outlook in **Tools & Integrations** and ensure the trigger is enabled
|
||||
for your deployment.
|
||||
</Tip>
|
||||
|
||||
## Enabling the Outlook Trigger
|
||||
|
||||
1. Open your deployment in CrewAI AMP
|
||||
2. Go to the **Triggers** tab
|
||||
3. Locate **Outlook** and switch the toggle to enable
|
||||
|
||||
<Frame caption="Microsoft Outlook trigger connection">
|
||||
<img
|
||||
src="/images/enterprise/outlook-trigger.png"
|
||||
alt="Enable or disable triggers with toggle"
|
||||
/>
|
||||
</Frame>
|
||||
|
||||
## Example: Summarize a new email
|
||||
|
||||
```python
|
||||
from outlook_message_crew import OutlookMessageTrigger
|
||||
|
||||
crew = OutlookMessageTrigger().crew()
|
||||
crew.kickoff({
|
||||
"crewai_trigger_payload": outlook_payload,
|
||||
})
|
||||
```
|
||||
|
||||
The crew extracts sender details, subject, body preview, and attachments before generating a structured response.
|
||||
|
||||
## 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
|
||||
347
docs/edge/en/enterprise/guides/prepare-for-deployment.mdx
Normal file
347
docs/edge/en/enterprise/guides/prepare-for-deployment.mdx
Normal file
@@ -0,0 +1,347 @@
|
||||
---
|
||||
title: "Prepare for Deployment"
|
||||
description: "Ensure your Crew or Flow is ready for deployment to CrewAI AMP"
|
||||
icon: "clipboard-check"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<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. New crews are JSON-first with `crew.jsonc` and `agents/`; classic crews can still use `crew.py`.
|
||||
</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** | Project root with `crew.jsonc` and `agents/` | `src/project_name/` with `crews/` folder |
|
||||
| **Main logic location** | `crew.jsonc` (classic: `src/project_name/crew.py`) | `src/project_name/main.py` (Flow class) |
|
||||
| **Entry point function** | Loaded from `crew.jsonc` (classic: `run()` in `main.py`) | `kickoff()` in `main.py` |
|
||||
| **pyproject.toml type** | `type = "crew"` | `type = "flow"` |
|
||||
| **CLI create command** | `crewai create crew name` | `crewai create flow name` |
|
||||
| **Config location** | `crew.jsonc`, `agents/`, optional `tools/` | `src/project_name/crews/crew_name/config/` or embedded JSON crew folders |
|
||||
| **Can contain other crews** | No | Yes (in `crews/` folder) |
|
||||
|
||||
## Project Structure Reference
|
||||
|
||||
### Crew Project Structure
|
||||
|
||||
When you run `crewai create crew my_crew`, you get the JSON-first structure:
|
||||
|
||||
```
|
||||
my_crew/
|
||||
├── .gitignore
|
||||
├── pyproject.toml # Must have type = "crew"
|
||||
├── README.md
|
||||
├── .env
|
||||
├── uv.lock # REQUIRED for deployment
|
||||
├── crew.jsonc # Crew settings, tasks, process, inputs
|
||||
├── agents/
|
||||
│ └── researcher.jsonc # Agent definitions
|
||||
├── tools/ # Optional custom:<name> tools
|
||||
├── knowledge/
|
||||
└── skills/
|
||||
```
|
||||
|
||||
<Warning>
|
||||
For JSON-first crews, keep `crew.jsonc`, `agents/`, `tools/`, `knowledge/`, and `skills/`
|
||||
at the project root. Placing them under `src/` will prevent `crewai run` and deployment
|
||||
validation from finding the crew definition.
|
||||
</Warning>
|
||||
|
||||
<Info>
|
||||
Classic projects created with `crewai create crew my_crew --classic` use the older
|
||||
`src/project_name/crew.py`, `src/project_name/config/agents.yaml`, and
|
||||
`src/project_name/config/tasks.yaml` layout. That layout remains supported for
|
||||
decorator-based Python crews.
|
||||
</Info>
|
||||
|
||||
### 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>
|
||||
JSON-first standalone crews use project-root JSON files. Flows still use
|
||||
`src/project_name/` and can contain either classic embedded crews or embedded
|
||||
JSON crew folders loaded with `crewai.project.load_crew`.
|
||||
</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 the Crew Definition
|
||||
|
||||
<Tabs>
|
||||
<Tab title="JSON-first Crews">
|
||||
JSON-first crews must have a `crew.jsonc` or `crew.json` file at the project root.
|
||||
The `agents` array must reference files in `agents/`, and each task should reference
|
||||
a valid agent name.
|
||||
|
||||
```jsonc crew.jsonc
|
||||
{
|
||||
"name": "Research Crew",
|
||||
"agents": ["researcher"],
|
||||
"tasks": [
|
||||
{
|
||||
"name": "research_task",
|
||||
"description": "Research {topic}.",
|
||||
"expected_output": "A concise report.",
|
||||
"agent": "researcher"
|
||||
}
|
||||
],
|
||||
"inputs": {
|
||||
"topic": "AI Agents"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Custom tools are referenced as `"custom:<name>"` and must be implemented in
|
||||
`tools/<name>.py` with a `BaseTool` subclass.
|
||||
</Tab>
|
||||
<Tab title="Classic Python/YAML Crews">
|
||||
Classic crews and Python crews embedded in Flows must use the `@CrewBase` decorator.
|
||||
|
||||
```python
|
||||
from crewai import Agent, Crew, Process, Task
|
||||
from crewai.project import CrewBase, agent, crew, task
|
||||
from crewai.agents.agent_builder.base_agent import BaseAgent
|
||||
from typing import List
|
||||
|
||||
@CrewBase
|
||||
class MyCrew():
|
||||
"""My crew description"""
|
||||
|
||||
agents: List[BaseAgent]
|
||||
tasks: List[Task]
|
||||
|
||||
@agent
|
||||
def my_agent(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['my_agent'], # type: ignore[index]
|
||||
verbose=True
|
||||
)
|
||||
|
||||
@task
|
||||
def my_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['my_task'] # type: ignore[index]
|
||||
)
|
||||
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 4. Check Project Entry Points
|
||||
|
||||
JSON-first standalone crews do not need a hand-written `src/project_name/main.py`; `crewai run`
|
||||
and deployment packaging load `crew.jsonc` directly. Classic crews and Flows use Python entry
|
||||
points:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="JSON-first Crews">
|
||||
Run locally from the project root:
|
||||
|
||||
```bash
|
||||
crewai run
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Classic 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. For JSON-first crews, verify crew.jsonc and agents/ exist
|
||||
([ -f crew.jsonc ] || [ -f crew.json ]) || echo "No crew.jsonc or crew.json found"
|
||||
test -d agents || echo "No agents/ directory found"
|
||||
|
||||
# 4. For classic Crews - verify crew.py exists
|
||||
ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)"
|
||||
|
||||
# 5. For Flows - verify crews/ folder exists
|
||||
ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)"
|
||||
|
||||
# 6. For classic Python crews - check for CrewBase usage
|
||||
grep -r "@CrewBase" . --include="*.py"
|
||||
```
|
||||
|
||||
## Common Setup Mistakes
|
||||
|
||||
| Mistake | Symptom | Fix |
|
||||
|---------|---------|-----|
|
||||
| Missing `uv.lock` | Build fails during dependency resolution | Run `uv lock` and commit |
|
||||
| Wrong `type` in pyproject.toml | Build succeeds but runtime fails | Change to correct type |
|
||||
| Missing `crew.jsonc` or `agents/` in a JSON-first crew | Crew definition not found | Keep `crew.jsonc` and `agents/` at the project root |
|
||||
| Missing `@CrewBase` decorator in a classic crew | "Config not found" errors | Add decorator to all classic crew classes |
|
||||
| Classic files at root instead of `src/` | Entry point not found | Move classic Python files to `src/project_name/` |
|
||||
| Missing `run()` or `kickoff()` | Cannot start automation | Add correct entry function |
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once your project passes all checklist items, you're ready to deploy:
|
||||
|
||||
<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/edge/en/enterprise/guides/private-package-registry.mdx
Normal file
263
docs/edge/en/enterprise/guides/private-package-registry.mdx
Normal 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/edge/en/enterprise/guides/react-component-export.mdx
Normal file
112
docs/edge/en/enterprise/guides/react-component-export.mdx
Normal 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/edge/en/enterprise/guides/salesforce-trigger.mdx
Normal file
50
docs/edge/en/enterprise/guides/salesforce-trigger.mdx
Normal 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/edge/en/enterprise/guides/slack-trigger.mdx
Normal file
62
docs/edge/en/enterprise/guides/slack-trigger.mdx
Normal 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/edge/en/enterprise/guides/team-management.mdx
Normal file
91
docs/edge/en/enterprise/guides/team-management.mdx
Normal 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/edge/en/enterprise/guides/tool-repository.mdx
Normal file
154
docs/edge/en/enterprise/guides/tool-repository.mdx
Normal 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>
|
||||
132
docs/edge/en/enterprise/guides/training-crews.mdx
Normal file
132
docs/edge/en/enterprise/guides/training-crews.mdx
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
title: "Training Crews"
|
||||
description: "Train your deployed crews directly from the CrewAI AMP platform to improve agent performance over time"
|
||||
icon: "dumbbell"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Training lets you improve crew performance by running iterative training sessions directly from the **Training** tab in CrewAI AMP. The platform uses **auto-train mode** — it handles the iterative process automatically, unlike CLI training which requires interactive human feedback per iteration.
|
||||
|
||||
After training completes, CrewAI evaluates agent outputs and consolidates feedback into actionable suggestions for each agent. These suggestions are then applied to future crew runs to improve output quality.
|
||||
|
||||
<Tip>
|
||||
For details on how CrewAI training works under the hood, see the [Training Concepts](/en/concepts/training) page.
|
||||
</Tip>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Active deployment" icon="rocket">
|
||||
You need a CrewAI AMP account with an active deployment in **Ready** status (Crew type).
|
||||
</Card>
|
||||
<Card title="Run permission" icon="key">
|
||||
Your account must have run permission for the deployment you want to train.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## How to train a crew
|
||||
|
||||
<Steps>
|
||||
<Step title="Open the Training tab">
|
||||
Navigate to **Deployments**, click your deployment, then select the **Training** tab.
|
||||
</Step>
|
||||
|
||||
<Step title="Enter a training name">
|
||||
Provide a **Training Name** — this becomes the `.pkl` filename used to store training results. For example, "Expert Mode Training" produces `expert_mode_training.pkl`.
|
||||
</Step>
|
||||
|
||||
<Step title="Fill in the crew inputs">
|
||||
Enter the crew's input fields. These are the same inputs you'd provide for a normal kickoff — they're dynamically loaded based on your crew's configuration.
|
||||
</Step>
|
||||
|
||||
<Step title="Start training">
|
||||
Click **Train Crew**. The button changes to "Training..." with a spinner while the process runs.
|
||||
|
||||
Behind the scenes:
|
||||
- A training record is created for your deployment
|
||||
- The platform calls the deployment's auto-train endpoint
|
||||
- The crew runs its iterations automatically — no manual feedback required
|
||||
</Step>
|
||||
|
||||
<Step title="Monitor progress">
|
||||
The **Current Training Status** panel displays:
|
||||
- **Status** — Current state of the training run
|
||||
- **Nº Iterations** — Number of training iterations configured
|
||||
- **Filename** — The `.pkl` file being generated
|
||||
- **Started At** — When training began
|
||||
- **Training Inputs** — The inputs you provided
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Understanding training results
|
||||
|
||||
Once training completes, you'll see per-agent result cards with the following information:
|
||||
|
||||
- **Agent Role** — The name/role of the agent in your crew
|
||||
- **Final Quality** — A score from 0 to 10 evaluating the agent's output quality
|
||||
- **Final Summary** — A summary of the agent's performance during training
|
||||
- **Suggestions** — Actionable recommendations for improving the agent's behavior
|
||||
|
||||
### Editing suggestions
|
||||
|
||||
You can refine the suggestions for any agent:
|
||||
|
||||
<Steps>
|
||||
<Step title="Click Edit">
|
||||
On any agent's result card, click the **Edit** button next to the suggestions.
|
||||
</Step>
|
||||
|
||||
<Step title="Modify suggestions">
|
||||
Update the suggestions text to better reflect the improvements you want.
|
||||
</Step>
|
||||
|
||||
<Step title="Save changes">
|
||||
Click **Save**. The edited suggestions sync back to the deployment and are used in all future runs.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Using trained data
|
||||
|
||||
To apply training results to your crew:
|
||||
|
||||
1. Note the **Training Filename** (the `.pkl` file) from your completed training session.
|
||||
2. Specify this filename in your deployment's kickoff or run configuration.
|
||||
3. The crew automatically loads the training file and applies the stored suggestions to each agent.
|
||||
|
||||
This means agents benefit from the feedback generated during training on every subsequent run.
|
||||
|
||||
## Previous trainings
|
||||
|
||||
The bottom of the Training tab displays a **history of all past training sessions** for the deployment. Use this to review previous training runs, compare results, or select a different training file to use.
|
||||
|
||||
## Error handling
|
||||
|
||||
If a training run fails, the status panel shows an error state along with a message describing what went wrong.
|
||||
|
||||
Common causes of training failures:
|
||||
- **Deployment runtime not updated** — Ensure your deployment is running the latest version
|
||||
- **Crew execution errors** — Issues within the crew's task logic or agent configuration
|
||||
- **Network issues** — Connectivity problems between the platform and the deployment
|
||||
|
||||
## Limitations
|
||||
|
||||
<Info>
|
||||
Keep these constraints in mind when planning your training workflow:
|
||||
- **One active training at a time** per deployment — wait for the current run to finish before starting another
|
||||
- **Auto-train mode only** — the platform does not support interactive per-iteration feedback like the CLI does
|
||||
- **Training data is deployment-specific** — training results are tied to the specific deployment instance and version
|
||||
</Info>
|
||||
|
||||
## Related resources
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Training Concepts" icon="book" href="/en/concepts/training">
|
||||
Learn how CrewAI training works under the hood.
|
||||
</Card>
|
||||
<Card title="Kickoff Crew" icon="play" href="/en/enterprise/guides/kickoff-crew">
|
||||
Run your deployed crew from the AMP platform.
|
||||
</Card>
|
||||
<Card title="Deploy to AMP" icon="cloud-arrow-up" href="/en/enterprise/guides/deploy-to-amp">
|
||||
Get your crew deployed and ready for training.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
91
docs/edge/en/enterprise/guides/update-crew.mdx
Normal file
91
docs/edge/en/enterprise/guides/update-crew.mdx
Normal 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></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></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>
|
||||
|
||||
</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>
|
||||
|
||||
</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>
|
||||
@@ -0,0 +1,295 @@
|
||||
---
|
||||
title: "Vertex AI with Workload Identity"
|
||||
description: "Connect Google Vertex AI to CrewAI AMP with no service account keys — credentials are minted per-execution via OIDC workload identity federation."
|
||||
icon: "google"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
<Note>
|
||||
Workload identity for LLM connections is currently available to enterprise SaaS customers on CrewAI AMP. Contact your CrewAI account team to enable it for your organization before starting this guide.
|
||||
</Note>
|
||||
|
||||
## Version requirements
|
||||
|
||||
| Component | Required version | Notes |
|
||||
|---|---|---|
|
||||
| **CrewAI AMP** | Early access (per-organization feature flag) | Contact CrewAI support to enable **Workload Identity Configs** and **LLM workload identity** on your org. |
|
||||
| **CrewAI Python SDK (`crewai`)** | **`1.14.3` or higher** | Crews built from this version (or later) include the OIDC token fetch and GCP credential setup needed for Vertex workload identity. |
|
||||
| **LLM provider** | **Google Gen AI SDK** (`google/` model prefix) | Required. LiteLLM's `vertex_ai/*` provider is **not** supported with workload identity. Use the `google/` prefix on your LLM connection's model field — for example `google/gemini-2.5-pro`, `google/gemini-2.5-flash`, `google/gemini-2.0-flash`. |
|
||||
| **Google Cloud APIs** | `iam.googleapis.com`, `iamcredentials.googleapis.com`, `sts.googleapis.com`, `aiplatform.googleapis.com` | All four must be enabled on the target project (see [Part 1, step 1](#part-1-gcp-setup)). |
|
||||
|
||||
<Warning>
|
||||
**Use the `google/` model prefix, not `vertex_ai/`.** Workload identity requires the native Google Gen AI SDK route, which uses Application Default Credentials. The LiteLLM `vertex_ai/*` provider does not consume the ADC config the runtime writes, so calls will fail to authenticate.
|
||||
</Warning>
|
||||
|
||||
## Overview
|
||||
|
||||
CrewAI AMP can authenticate to Google Vertex AI using **GCP Workload Identity Federation** instead of long-lived service account keys. At kickoff, your crew execution fetches a short-lived OIDC token from AMP scoped to your organization and writes a Google **Application Default Credentials (ADC)** `external_account` configuration that points at it. The Google Gen AI SDK (invoked via CrewAI's `google/` model prefix) then transparently exchanges that OIDC token at GCP STS, optionally impersonates a service account, and calls Vertex AI — all in-process inside the running crew.
|
||||
|
||||
The result:
|
||||
|
||||
- **No Google credentials stored in CrewAI AMP** — no service account JSON keys, no API keys. AMP holds only the OIDC signing key it uses to mint tokens.
|
||||
- **Trust is anchored in your GCP project.** You decide which CrewAI organization can impersonate which service account.
|
||||
- **The STS exchange happens inside the crew execution**, not in AMP's control plane. AMP only mints OIDC tokens; the Google credentials returned by GCP are never seen or persisted by AMP — they live and die inside a single execution.
|
||||
- **Access tokens are refreshed automatically**, and the underlying OIDC subject token is rotated before expiry — long-running crews are supported (with one edge case noted below).
|
||||
|
||||
### How it works
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Crew as Crew execution
|
||||
participant AMP as CrewAI AMP
|
||||
participant STS as GCP STS
|
||||
participant IAM as IAM Credentials API
|
||||
participant Vertex as Vertex AI
|
||||
|
||||
Crew->>AMP: Request OIDC JWT (aud = WI provider)
|
||||
AMP-->>Crew: OIDC JWT
|
||||
Note over Crew: Write GOOGLE_APPLICATION_CREDENTIALS<br/>external_account ADC file
|
||||
Crew->>STS: Exchange JWT (via google-auth)
|
||||
Note right of STS: Validate via JWKS<br/>+ attribute condition
|
||||
STS-->>Crew: Federated token
|
||||
Crew->>IAM: generateAccessToken (impersonate SA)
|
||||
IAM-->>Crew: SA access token
|
||||
Crew->>Vertex: generateContent / predict
|
||||
```
|
||||
|
||||
GCP fetches AMP's public signing keys from a standard OIDC discovery endpoint and validates each token before exchanging it. AMP never sees your GCP service account key, and the federated/SA tokens minted by GCP stay inside the crew execution that requested them — they are not returned to or persisted by AMP's control plane.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A GCP project with Vertex AI enabled (`aiplatform.googleapis.com`).
|
||||
- The `gcloud` CLI authenticated as a user with IAM admin on that project. See [Appendix: minimum IAM](#appendix-minimum-iam-for-setup) for the specific roles required.
|
||||
- Your **CrewAI organization UUID**. Find it in CrewAI AMP at **Settings → Organization** (use the UUID, not the numeric ID).
|
||||
- Workload identity for LLM connections enabled on your AMP organization — contact CrewAI support.
|
||||
|
||||
The CrewAI AMP OIDC issuer URL is:
|
||||
|
||||
```
|
||||
https://app.crewai.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 1 — GCP setup
|
||||
|
||||
<Steps>
|
||||
<Step title="Enable required APIs">
|
||||
```bash
|
||||
gcloud services enable \
|
||||
iam.googleapis.com \
|
||||
iamcredentials.googleapis.com \
|
||||
sts.googleapis.com \
|
||||
aiplatform.googleapis.com \
|
||||
--project=PROJECT_ID
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create a workload identity pool">
|
||||
```bash
|
||||
gcloud iam workload-identity-pools create crewai-amp \
|
||||
--project=PROJECT_ID \
|
||||
--location=global \
|
||||
--display-name="CrewAI AMP"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create the OIDC provider inside the pool">
|
||||
The `attribute-condition` is the **critical security boundary** — it restricts which CrewAI organization can assume any identity from this pool. Replace `YOUR_ORG_UUID` with your AMP organization UUID.
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers create-oidc crewai-amp-oidc \
|
||||
--project=PROJECT_ID \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-amp \
|
||||
--issuer-uri="https://app.crewai.com" \
|
||||
--attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
|
||||
--attribute-condition="assertion.organization_id == 'YOUR_ORG_UUID'"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`YOUR_ORG_UUID` must be your organization **UUID** (the same value used by `attribute.organization` in the principalSet binding below). A wrong value here is the most common cause of `PERMISSION_DENIED` failures during STS exchange.
|
||||
</Warning>
|
||||
|
||||
Record the full provider resource name — you'll need it in Part 2:
|
||||
|
||||
```bash
|
||||
gcloud iam workload-identity-pools providers describe crewai-amp-oidc \
|
||||
--project=PROJECT_ID \
|
||||
--location=global \
|
||||
--workload-identity-pool=crewai-amp \
|
||||
--format="value(name)"
|
||||
# projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/providers/crewai-amp-oidc
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Create a Vertex AI service account">
|
||||
`crewai-vertex` is an example name — pick anything that fits your naming conventions, but use the same value in the impersonation binding (next step) and on the LLM connection (Part 2).
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts create crewai-vertex \
|
||||
--project=PROJECT_ID \
|
||||
--display-name="CrewAI AMP — Vertex AI"
|
||||
|
||||
gcloud projects add-iam-policy-binding PROJECT_ID \
|
||||
--member="serviceAccount:crewai-vertex@PROJECT_ID.iam.gserviceaccount.com" \
|
||||
--role="roles/aiplatform.user"
|
||||
```
|
||||
|
||||
`roles/aiplatform.user` is the minimum role needed for `generateContent` and `predict`. Tighten further with custom roles if your security policy requires it.
|
||||
</Step>
|
||||
|
||||
<Step title="Allow the pool to impersonate the service account">
|
||||
This is the second security boundary: only federated identities whose `organization` attribute matches your org UUID can impersonate this SA.
|
||||
|
||||
```bash
|
||||
gcloud iam service-accounts add-iam-policy-binding \
|
||||
crewai-vertex@PROJECT_ID.iam.gserviceaccount.com \
|
||||
--project=PROJECT_ID \
|
||||
--role="roles/iam.workloadIdentityUser" \
|
||||
--member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/attribute.organization/YOUR_ORG_UUID"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Part 2 — CrewAI AMP setup
|
||||
|
||||
<Steps>
|
||||
<Step title="Create a Workload Identity Config">
|
||||
In AMP, go to **Settings → Workload Identity Configs → New** and fill in:
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Name** | A memorable label, e.g. `vertex-ai-prod` |
|
||||
| **Cloud provider** | `GCP` |
|
||||
| **GCP Workload Identity Provider** | The full resource name from Part 1, step 3 (`projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/crewai-amp/providers/crewai-amp-oidc`) |
|
||||
| **Default for GCP** | Optional — marks this as the default GCP config for new connections |
|
||||
|
||||
Creating workload identity configs requires a role with **manage** access to LLM connections (see [RBAC](/en/enterprise/features/rbac)).
|
||||
</Step>
|
||||
|
||||
<Step title="Attach the config to a Vertex LLM connection">
|
||||
Go to **LLM Connections → New** (or edit an existing one) and select:
|
||||
|
||||
- **Provider:** `Vertex`
|
||||
- **Workload Identity Config:** the config from the previous step
|
||||
- **GCP Service Account Email:** the SA you created in Part 1 (e.g., `crewai-vertex@PROJECT_ID.iam.gserviceaccount.com`)
|
||||
|
||||
No `GOOGLE_API_KEY` environment variable is required — leave that empty. For region, add a single connection-scoped env var:
|
||||
|
||||
- `GOOGLE_CLOUD_LOCATION=global` — recommended default. Vertex's `global` endpoint provides higher availability and is supported by current Gemini 2.x and 3.x models. Set a specific region (e.g. `us-central1`, `europe-west4`) if you need data residency (the global endpoint does **not** guarantee in-region processing) or if you plan to use Vertex features that don't run on `global` (notably **tuning**, **batch prediction** for Anthropic / OpenMaaS models, and **RAG corpus management** — RAG *requests* still work on global). For chat/completion crews, `global` is the right choice.
|
||||
|
||||
<Note>
|
||||
Service account impersonation is configured per-connection (not per-config) so a single workload identity pool can be reused for multiple service accounts with different Vertex permissions.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Bind the connection to a crew or deployment">
|
||||
Attach the LLM connection to a crew, Studio project, or deployment exactly as you would any other LLM connection. At kickoff, the running crew will request an OIDC token from AMP for this connection's workload identity provider and exchange it for Vertex credentials in-process — no Google credentials are stored or pushed by AMP.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
## Runtime behavior
|
||||
|
||||
For Vertex connections backed by workload identity, the crew does **not** receive a `GOOGLE_API_KEY` or service account JSON as a static deploy-time env var. Instead, at kickoff, the running crew:
|
||||
|
||||
1. Fetches an OIDC token from AMP, signed with AMP's private key and scoped to your organization (audience = your workload identity provider).
|
||||
2. Writes the JWT to a temporary file in the execution environment.
|
||||
3. Writes a Google **Application Default Credentials (ADC)** config of type `external_account` that references the JWT file, your STS audience, and (optionally) the service account impersonation URL.
|
||||
4. Sets the following environment variables for the crew process:
|
||||
|
||||
| Env var | Value |
|
||||
|---|---|
|
||||
| `GOOGLE_APPLICATION_CREDENTIALS` | Path to the temporary ADC `external_account` config file |
|
||||
| `GOOGLE_CLOUD_PROJECT` | Your GCP project number, parsed from the workload identity provider resource name (Google Gen AI SDK accepts either the project ID or the project number) |
|
||||
|
||||
No `GOOGLE_API_KEY` and no `GOOGLE_CLOUD_LOCATION` are set automatically. Configure `GOOGLE_CLOUD_LOCATION` on your LLM connection in AMP (recommended default: `global`).
|
||||
|
||||
5. From this point on, **`google-auth`** (used by the Google Gen AI SDK) does the STS exchange and SA impersonation transparently on the first Vertex API call, and caches/refreshes the resulting access token automatically.
|
||||
|
||||
The crew SDK reads these like any other env var — no code changes required, provided your crew was deployed against **`crewai>=1.14.3`** (see [Version requirements](#version-requirements)).
|
||||
|
||||
### Long-running crews
|
||||
|
||||
Access tokens are **automatically refreshed**:
|
||||
|
||||
- **Vertex access tokens** (1-hour TTL) are refreshed by `google-auth` in-process, transparently to your crew code.
|
||||
- **The underlying OIDC subject token** (also 1-hour TTL) is rotated before expiry on every kickoff entry point. The crew fetches a fresh OIDC JWT from AMP and rewrites the ADC token file; subsequent STS exchanges pick up the new JWT.
|
||||
|
||||
In practice this means:
|
||||
|
||||
- Crews that run for **less than 1 hour** never trigger a refresh — the initial token covers the whole execution.
|
||||
- Crews that run for **multiple hours** continue to function as long as kickoff entry points (sync hops, agent steps, etc.) fire during the execution; the refresh buffer ensures the OIDC token is rotated before STS rejects it.
|
||||
- If a single Vertex API call runs for more than 1 hour (very unusual — typical Gemini responses return in seconds), the OIDC token can expire mid-request and the call will fail. This is the one scenario where token refresh cannot help.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
Run a crew that uses the Vertex connection and tail the execution logs in AMP. A successful `generateContent` or `predict` call confirms the full chain — OIDC mint → STS exchange → SA impersonation → Vertex — is wired correctly.
|
||||
|
||||
If the crew fails, see [Troubleshooting](#troubleshooting) below. Most issues trace back to the GCP-side configuration — the OIDC provider's `attribute-condition` or the service account's `principalSet` binding.
|
||||
|
||||
### Inspecting on the GCP side
|
||||
|
||||
You can confirm tokens are being exchanged by looking at **Cloud Audit Logs** in your GCP project:
|
||||
|
||||
- Service: `sts.googleapis.com` → method `google.identity.sts.v1.SecurityTokenService.ExchangeToken`
|
||||
- Service: `iamcredentials.googleapis.com` → method `GenerateAccessToken`
|
||||
|
||||
A short crew execution produces one `ExchangeToken` and one `GenerateAccessToken` entry; longer executions produce additional entries each time the OIDC token is rotated. The `protoPayload.authenticationInfo` includes the `sub` and `organization_id` claims, useful for audit and incident response.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---|---|
|
||||
| AMP UI doesn't show **Workload Identity Configs** | Feature isn't enabled for your organization — contact CrewAI support. |
|
||||
| AMP UI rejects attaching a config to an LLM connection | The connection's provider must be `Vertex` (GCP). |
|
||||
| GCP STS returns `PERMISSION_DENIED: The given credential is rejected by the attribute condition` | Org UUID mismatch — typically the numeric org ID was used instead of the UUID, or the UUID in the attribute condition is wrong. |
|
||||
| GCP STS returns `INVALID_ARGUMENT: Invalid JWT` | Issuer URL in the provider doesn't match `https://app.crewai.com`, or GCP's JWKS cache is stale (wait up to 1 hour, or recreate the provider). |
|
||||
| `generateAccessToken` returns `PERMISSION_DENIED` | The pool member is missing `roles/iam.workloadIdentityUser` on the service account, or the `principalSet` in the binding uses the wrong attribute path. |
|
||||
| Vertex returns `PERMISSION_DENIED` on `generateContent` | The service account is missing `roles/aiplatform.user` (or an equivalent custom role) on the project. |
|
||||
| Crew fails immediately with `DefaultCredentialsError: File <path> was not found` | The ADC token file was cleaned up — typically because the execution process was forked after credentials initialized. Re-kickoff the crew. If it persists, bump `crewai>=1.14.3` in your `pyproject.toml` and re-deploy. |
|
||||
| Crew fails with `DefaultCredentialsError` and no `GOOGLE_APPLICATION_CREDENTIALS` is set in the execution env | Your crew was deployed against a pre-`1.14.3` `crewai`, so no ADC file was written and no API-key fallback exists for workload identity connections. Bump `crewai>=1.14.3` in your `pyproject.toml` and re-deploy. |
|
||||
| Crew fails after ~1 hour with `invalid_grant` from STS | The OIDC subject token expired and refresh did not fire — typically because a single in-process call held the execution past the refresh buffer. If this reproduces, contact CrewAI support with the failing execution ID. |
|
||||
| Vertex calls fail with `Unable to locate project` | `GOOGLE_CLOUD_PROJECT` was not parsed — your workload identity provider resource name in AMP doesn't match the `projects/PROJECT_NUMBER/...` format. Re-check the provider value copied from `gcloud iam workload-identity-pools providers describe`. |
|
||||
| Vertex calls fail with `region`/`location` errors | `GOOGLE_CLOUD_LOCATION` isn't set on the LLM connection. Add it as a connection-scoped env var (`global` is the recommended default). |
|
||||
| Vertex returns `model not found` or `not available in location` | The chosen region doesn't host the requested model. Switch the connection's `GOOGLE_CLOUD_LOCATION` to `global`, or pick a region known to host the model. |
|
||||
| Vertex calls fail to authenticate despite a working WI config | The model identifier uses the `vertex_ai/` (LiteLLM) prefix instead of `google/`. Workload identity only works through the Google Gen AI SDK route — change the model to `google/<model-name>`. |
|
||||
|
||||
---
|
||||
|
||||
## Security notes
|
||||
|
||||
- **The `organization_id` claim is your security boundary.** Your GCP attribute condition **must** restrict to your organization UUID. Without it, any CrewAI AMP organization could exchange a token through your pool. The `sub` claim contains the same UUID prefixed with `organization:` — either could be used, but `organization_id` matches the bare-UUID form used in the `attribute.organization` mapping and `principalSet` binding.
|
||||
- **Service account impersonation is the second boundary.** The `principalSet` binding restricts impersonation to identities whose `organization` attribute matches your UUID. Use it even when the attribute condition is set — defense in depth.
|
||||
- **Issuer trust is one-way.** GCP fetches AMP's public JWKS over HTTPS. AMP never receives any GCP credential.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: minimum IAM for setup
|
||||
|
||||
The user running the `gcloud` commands above needs, on the target project:
|
||||
|
||||
- `roles/iam.workloadIdentityPoolAdmin` — create pools and providers
|
||||
- `roles/iam.serviceAccountAdmin` — create service accounts
|
||||
- `roles/resourcemanager.projectIamAdmin` — bind project-level roles
|
||||
- `roles/serviceusage.serviceUsageAdmin` — enable required APIs
|
||||
|
||||
Or, equivalently, `roles/owner` on the project.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Single Sign-On (SSO)](/en/enterprise/features/sso) — Authentication for the AMP UI and CLI (separate system from LLM workload identity)
|
||||
- [Azure OpenAI Setup](/en/enterprise/guides/azure-openai-setup) — Static-key alternative for Azure OpenAI
|
||||
- [GCP: Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) — Google's reference docs
|
||||
157
docs/edge/en/enterprise/guides/webhook-automation.mdx
Normal file
157
docs/edge/en/enterprise/guides/webhook-automation.mdx
Normal 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/edge/en/enterprise/guides/zapier-trigger.mdx
Normal file
105
docs/edge/en/enterprise/guides/zapier-trigger.mdx
Normal 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/edge/en/enterprise/integrations/asana.mdx
Normal file
272
docs/edge/en/enterprise/integrations/asana.mdx
Normal 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/edge/en/enterprise/integrations/box.mdx
Normal file
281
docs/edge/en/enterprise/integrations/box.mdx
Normal 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/edge/en/enterprise/integrations/clickup.mdx
Normal file
302
docs/edge/en/enterprise/integrations/clickup.mdx
Normal 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>
|
||||
123
docs/edge/en/enterprise/integrations/databricks.mdx
Normal file
123
docs/edge/en/enterprise/integrations/databricks.mdx
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: Databricks Integration
|
||||
description: "Connect CrewAI agents to Databricks Genie, SQL, Unity Catalog Functions, and Vector Search through Databricks managed MCP servers."
|
||||
icon: "layer-group"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Connect your CrewAI agents directly to your Databricks workspace through [Databricks managed MCP servers](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp). The Databricks integration lets your agents ask natural-language questions with **Genie**, run governed **SQL**, call **Unity Catalog Functions**, and retrieve documents with **Vector Search** — all without writing or hosting any connector code, and with Unity Catalog permissions enforced on every call.
|
||||
|
||||
Under the hood, the Databricks integration is a managed wrapper around CrewAI's [Custom MCP Server](/en/enterprise/guides/custom-mcp-server) support. Databricks exposes each capability as its own [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, and CrewAI connects to them securely on your behalf. Because each server is added separately, you can enable exactly the capabilities your crews need.
|
||||
|
||||
## Key Capabilities
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Genie" icon="comments">
|
||||
Ask questions in plain language and get grounded answers from your data with [Genie](https://docs.databricks.com/aws/en/genie/), which queries Genie Spaces and Unity Catalog and links back to the Databricks UI.
|
||||
</Card>
|
||||
<Card title="Databricks SQL" icon="database">
|
||||
Run governed SQL against your Databricks warehouses to query, transform, and author data pipelines directly from your agents.
|
||||
</Card>
|
||||
<Card title="Unity Catalog Functions" icon="function">
|
||||
Invoke [Unity Catalog functions](https://docs.databricks.com/aws/en/udf/unity-catalog) to run predefined SQL and custom business logic as governed, reusable tools.
|
||||
</Card>
|
||||
<Card title="Vector Search" icon="magnifying-glass">
|
||||
Retrieve relevant documents for RAG and knowledge workflows from [Mosaic AI Vector Search](https://docs.databricks.com/aws/en/generative-ai/vector-search) indexes using semantic similarity.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Every server runs behind the Unity AI Gateway and enforces Unity Catalog access controls, so your agents only ever see the data and tools they're permitted to use.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before using the Databricks integration, ensure you have:
|
||||
|
||||
- A [CrewAI AMP](https://app.crewai.com) account with an active subscription
|
||||
- A Databricks workspace with the capabilities you want to expose (Genie Spaces, SQL warehouses, Unity Catalog functions, or Vector Search indexes)
|
||||
- Appropriate [Unity Catalog privileges](https://docs.databricks.com/aws/en/data-governance/unity-catalog) on the underlying objects
|
||||
- Your Databricks workspace hostname (e.g. `your-workspace.cloud.databricks.com`)
|
||||
|
||||
## Databricks Managed MCP Servers
|
||||
|
||||
Databricks publishes a separate managed MCP server for each capability. CrewAI exposes these as individual connections, each configured with your workspace host and the relevant Unity Catalog identifiers. The endpoints follow these patterns:
|
||||
|
||||
| Server | What it does | MCP URL pattern |
|
||||
|--------|--------------|-----------------|
|
||||
| **Genie** | Natural-language Q&A over a Genie Space | `https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}` |
|
||||
| **Databricks SQL** | Execute SQL against your warehouses | `https://<workspace-hostname>/api/2.0/mcp/sql` |
|
||||
| **Unity Catalog Functions** | Run registered UC functions | `https://<workspace-hostname>/api/2.0/mcp/functions/{catalog}/{schema}` |
|
||||
| **Vector Search** | Query a Vector Search index | `https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}` |
|
||||
|
||||
<Note>
|
||||
You don't construct these URLs by hand — CrewAI builds each endpoint from the workspace host and identifiers (Genie Space ID, or catalog/schema) you provide when configuring the connection. For the full specification and the latest endpoint details, see the [Databricks managed MCP documentation](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp).
|
||||
</Note>
|
||||
|
||||
## Connecting Databricks in CrewAI AMP
|
||||
|
||||
<Frame>
|
||||
<img src="/images/enterprise/databricks-configure.png" alt="Configure a Databricks managed MCP server in CrewAI AMP" />
|
||||
</Frame>
|
||||
|
||||
Each Databricks capability — **Databricks Genie**, **Databricks SQL**, **Databricks Unity Catalog Functions**, and **Databricks Vector Search** — appears as its own MCP server under the Databricks group on the **Tools & Integrations** page. Configure the ones you need:
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Tools & Integrations">
|
||||
Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP and locate the **Databricks** group in the Connections list. You'll see the Genie, SQL, Unity Catalog Functions, and Vector Search servers listed beneath it.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure a server">
|
||||
Click **Configure** next to the capability you want to enable and provide its connection details:
|
||||
|
||||
- **Workspace Host** — your Databricks workspace hostname (e.g. `my-workspace.cloud.databricks.com`).
|
||||
- **Genie** — the **Genie Space ID** to query.
|
||||
- **Unity Catalog Functions** — the **catalog** and **schema** that contain your functions.
|
||||
- **Vector Search** — the **catalog** and **schema** that contain your index.
|
||||
- **Databricks SQL** — no additional identifiers; queries run against your workspace's SQL warehouses.
|
||||
</Step>
|
||||
|
||||
<Step title="Choose an authentication method">
|
||||
Select how CrewAI authenticates to Databricks. **OAuth** is recommended.
|
||||
|
||||
- **Use OAuth** — Connect securely using OAuth 2.0. Each user authenticates individually, and Databricks issues tokens scoped to the capability (`genie`, `sql`, `unity-catalog`, or `vector-search`). CrewAI handles the authorization flow and refreshes tokens automatically.
|
||||
- **Use personal access token** — Authenticate with a [Databricks personal access token](https://docs.databricks.com/aws/en/dev-tools/auth/pat). Use a least-privileged identity to limit exposure.
|
||||
</Step>
|
||||
|
||||
<Step title="Authenticate">
|
||||
Complete authentication. Once connected, the server's tools become available to your crews. Repeat for any other Databricks capabilities you want to enable.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Because each capability is a separate connection, you can mix and match — for example, enable Genie and Vector Search for a research crew while reserving SQL and Unity Catalog Functions for a data-engineering crew. Visibility settings let you control which team members can use each one.
|
||||
</Tip>
|
||||
|
||||
## Using Databricks Tools in Your Crews
|
||||
|
||||
Once connected, the tools each MCP server exposes appear alongside built-in connections on the **Tools & Integrations** page. You can:
|
||||
|
||||
- **Assign tools to agents** in your crews just like any other CrewAI tool.
|
||||
- **Manage visibility** to control which team members can use each connection.
|
||||
- **Edit or remove** any connection at any time from the Connections list.
|
||||
|
||||
Your agents can now ask Genie for grounded answers, run SQL against your warehouses, call Unity Catalog functions, and search Vector Search indexes — with results flowing back into their reasoning automatically.
|
||||
|
||||
<Warning>
|
||||
Databricks enforces governance through Unity Catalog and the Unity AI Gateway: a user can only discover and invoke tools their workspace identity is permitted to use. If a tool call fails, confirm the connecting user (or token identity) has the required Unity Catalog privileges on the Genie Space, warehouse, function, or index. Some Genie and SQL queries run asynchronously and may take a moment to return results.
|
||||
</Warning>
|
||||
|
||||
## Learn More
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Databricks Managed MCP Servers" icon="layer-group" href="https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp">
|
||||
Official Databricks documentation for the managed Genie, SQL, Unity Catalog Functions, and Vector Search MCP servers.
|
||||
</Card>
|
||||
<Card title="Custom MCP Servers in CrewAI" icon="plug" href="/en/enterprise/guides/custom-mcp-server">
|
||||
Learn how CrewAI connects to any MCP server, the foundation the Databricks integration builds on.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
|
||||
Contact our support team for assistance with the Databricks integration or troubleshooting.
|
||||
</Card>
|
||||
331
docs/edge/en/enterprise/integrations/github.mdx
Normal file
331
docs/edge/en/enterprise/integrations/github.mdx
Normal 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/edge/en/enterprise/integrations/gmail.mdx
Normal file
303
docs/edge/en/enterprise/integrations/gmail.mdx
Normal 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/edge/en/enterprise/integrations/google_calendar.mdx
Normal file
367
docs/edge/en/enterprise/integrations/google_calendar.mdx
Normal 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/edge/en/enterprise/integrations/google_contacts.mdx
Normal file
494
docs/edge/en/enterprise/integrations/google_contacts.mdx
Normal 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/edge/en/enterprise/integrations/google_docs.mdx
Normal file
551
docs/edge/en/enterprise/integrations/google_docs.mdx
Normal 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/edge/en/enterprise/integrations/google_drive.mdx
Normal file
239
docs/edge/en/enterprise/integrations/google_drive.mdx
Normal 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/edge/en/enterprise/integrations/google_sheets.mdx
Normal file
369
docs/edge/en/enterprise/integrations/google_sheets.mdx
Normal 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/edge/en/enterprise/integrations/google_slides.mdx
Normal file
546
docs/edge/en/enterprise/integrations/google_slides.mdx
Normal 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/edge/en/enterprise/integrations/hubspot.mdx
Normal file
616
docs/edge/en/enterprise/integrations/hubspot.mdx
Normal 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/edge/en/enterprise/integrations/jira.mdx
Normal file
405
docs/edge/en/enterprise/integrations/jira.mdx
Normal 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/edge/en/enterprise/integrations/linear.mdx
Normal file
466
docs/edge/en/enterprise/integrations/linear.mdx
Normal 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/edge/en/enterprise/integrations/microsoft_excel.mdx
Normal file
507
docs/edge/en/enterprise/integrations/microsoft_excel.mdx
Normal 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/edge/en/enterprise/integrations/microsoft_onedrive.mdx
Normal file
329
docs/edge/en/enterprise/integrations/microsoft_onedrive.mdx
Normal 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/edge/en/enterprise/integrations/microsoft_outlook.mdx
Normal file
330
docs/edge/en/enterprise/integrations/microsoft_outlook.mdx
Normal 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/edge/en/enterprise/integrations/microsoft_sharepoint.mdx
Normal file
733
docs/edge/en/enterprise/integrations/microsoft_sharepoint.mdx
Normal 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>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user