# Create an access token
Source: https://docs-platform.crewai.com/api-reference/authentication/create-an-access-token

/openapi/platform-auth.yaml post /oauth/token
Exchange service account client credentials for an opaque bearer access token. Use HTTP Basic auth with `client_id` as the username and `client_secret` as the password; the header is `Authorization: Basic <base64(client_id:client_secret)>`.



# Introduction
Source: https://docs-platform.crewai.com/api/introduction

Build against the supported CrewAI Platform public API.

CrewAI Platform provides stable HTTP contracts for automation, integrations, and agent-facing workflows.

**Beta:** The CrewAI Platform API is currently in beta and may change as we continue to improve it.

The current public contract is `v1`. CrewAI Platform endpoints are available under `/api/v1` on your CrewAI Platform host.

## Authentication

Use a service account to obtain an access token, then send that token as a bearer credential when calling protected endpoints.


# Error responses
Source: https://docs-platform.crewai.com/api/problems

Error responses returned by the CrewAI Platform API.

When a request fails, the Platform API returns an `errors` array. Each item includes a stable `code`, an HTTP `status`, and a `detail` message with request-specific context.

Use the pages in this section to understand each error code and what to change before retrying.


# Bad request
Source: https://docs-platform.crewai.com/api/problems/bad_request



# Bad request

The request could not be processed because it was malformed or missing required request data.

## When It Happens

This usually means the request body, query string, headers, or required parameters are invalid before endpoint-specific validation can run.

## How To Fix

Review the endpoint contract, required parameters, request body shape, and content type before retrying.


# Conflict
Source: https://docs-platform.crewai.com/api/problems/conflict



# Conflict

The request was valid, but it could not be completed because of the current state of the target resource.

## When It Happens

This usually means the resource exists, but its current lifecycle state or invariants prevent the requested action.

## How To Fix

Inspect the `detail` message, resolve the resource state conflict, and retry the request when the action is valid again.


# Internal error
Source: https://docs-platform.crewai.com/api/problems/internal_error



# Internal error

An unexpected server-side failure prevented the request from completing.

## When It Happens

This means the platform encountered an unexpected condition while processing a valid request.

## How To Fix

Retry the request after a short delay. If the problem continues, contact support with the request details and timestamp.


# Not found
Source: https://docs-platform.crewai.com/api/problems/not_found



# Not found

The requested resource does not exist or is not available at the requested path.

## When It Happens

This can happen when the URL is incorrect, the resource identifier does not exist, or the resource is not visible through the public API.

## How To Fix

Check the endpoint path and resource identifier, then retry with a resource that exists and is available to the request.


# Unauthorized
Source: https://docs-platform.crewai.com/api/problems/unauthorized



# Unauthorized

The request could not be authenticated.

## When It Happens

This usually means required authentication credentials are missing, invalid, expired, or revoked.

## How To Fix

Provide valid active credentials and retry the request.


# Validation error
Source: https://docs-platform.crewai.com/api/problems/validation_error



# Validation error

The request was understood, but one or more submitted values failed validation.

## When It Happens

This usually means a submitted field is missing, malformed, out of range, duplicated, or conflicts with another value.

## How To Fix

Inspect the `detail` message for the field-specific issue, update the submitted values, and retry the request.


# Service accounts
Source: https://docs-platform.crewai.com/api/service-account



# Service accounts

Service accounts let an organization create credentials for server-side API clients without tying those credentials to a human user.

A service account has long-lived client credentials. API clients exchange those credentials for short-lived opaque access tokens, then use the access tokens to call protected CrewAI Platform API endpoints.

## Create a service account

1. Open **Settings** in your organization.
2. Open **Service Accounts**.
3. In the **Create service account** form, enter a descriptive name, such as `Production automation`.
4. Optionally enter a description.
5. Click **Create service account**.
6. Copy the generated **Client ID** and **Client secret** from the credentials dialog.
7. Store the client secret in the secret storage system your organization uses for server-side credentials.

The client secret is shown only once. After you close the credentials dialog, CrewAI cannot show that same secret again.

## Rotate a client secret

Rotate a service account to generate a new client secret.

1. Open **Settings** in your organization.
2. Open **Service Accounts**.
3. Click **View details** for the service account.
4. Click **Rotate**.
5. Copy the new **Client secret** from the credentials dialog.
6. Store the new secret in the secret storage system your organization uses for server-side credentials.

During rotation, the previous secret remains valid until the expiration time shown in the service account details. Use that window to update the systems that depend on the secret.

The new client secret is shown only once. If you close the credentials dialog before storing it, rotate again to generate another secret.

## If you lose the secret

CrewAI stores only a one-way digest of the client secret. The original secret cannot be recovered.

If you lose the secret, rotate the service account to generate a new one.

## Get an access token

Use the OAuth 2.0 client credentials flow to exchange a service account's `client_id` and `client_secret` for an access token.

The token endpoint is not versioned:

```http theme={null}
POST /oauth/token
```

Use HTTP Basic authentication with the service account client ID as the username and the client secret as the password. The `Authorization` header value is `Basic <base64(client_id:client_secret)>`.

```bash theme={null}
curl -X POST "https://app.crewai.com/oauth/token" \
  -H "Authorization: Basic $(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"
```

A successful response returns an opaque bearer token:

```json theme={null}
{
  "access_token": "crewai_sacat_...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

CrewAI does not issue refresh tokens for service account client credentials.

The access token is shown only in the token response. CrewAI stores only a one-way digest of the access token, so the original token cannot be recovered from the database.

## Call the API with an access token

Send the access token as a bearer token when calling protected Platform API endpoints:

```bash theme={null}
curl "https://app.crewai.com/api/v1/status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Access tokens are currently scoped to the CrewAI Platform API. They are not JWTs and clients should treat them as opaque strings.

## Cache access tokens

Access tokens are short-lived. The token response includes `expires_in`, which tells clients how many seconds the issued token remains valid. CrewAI currently issues service account access tokens with a 3600-second lifetime.

Clients should cache and reuse an access token until it is close to expiration. Do not call `/oauth/token` before every API request.

The token endpoint is rate-limited to protect the authentication service and to encourage token reuse. If a client receives a rate-limit response, it should back off and reuse a cached token if one is still valid.

## Token request errors

`/oauth/token` returns OAuth 2.0-style errors, not the CrewAI API `data` / `errors` envelope.

Example:

```json theme={null}
{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}
```

Protected `/api/v1/...` resource endpoints continue to return CrewAI API error envelopes.

Missing, expired, revoked, or invalid bearer tokens return `401 Unauthorized` with a `WWW-Authenticate: Bearer` header.

## Revoke a service account

Revoke a service account when it should no longer be used.

1. Open **Settings** in your organization.
2. Open **Service Accounts**.
3. Click **View details** for the service account.
4. Click **Revoke**.
5. Optionally enter a reason.
6. Confirm the revocation.

Revocation disables the service account immediately. Revoked service accounts cannot obtain new access tokens, and existing access tokens for a revoked service account are rejected.


# Create an Automation
Source: https://docs-platform.crewai.com/api/v1/reference/automations/create-an-automation

/openapi/platform-v1.yaml post /api/v1/automations
Creates an Automation from an uploaded ZIP source artifact. The upload is consumed after the deployment is created.



# Delete an Automation
Source: https://docs-platform.crewai.com/api/v1/reference/automations/delete-an-automation

/openapi/platform-v1.yaml delete /api/v1/automations/{id}
Enqueues an Automation in the authenticated service account's organization for deletion.



# Get an Automation
Source: https://docs-platform.crewai.com/api/v1/reference/automations/get-an-automation

/openapi/platform-v1.yaml get /api/v1/automations/{id}
Returns an Automation in the organization associated with the authenticated service account.



# List Automations
Source: https://docs-platform.crewai.com/api/v1/reference/automations/list-automations

/openapi/platform-v1.yaml get /api/v1/automations
Returns automations that belong to the organization associated with the authenticated service account.



# Redeploy an Automation
Source: https://docs-platform.crewai.com/api/v1/reference/automations/redeploy-an-automation

/openapi/platform-v1.yaml post /api/v1/automations/{id}/redeploy
Redeploys an existing Automation. An optional upload_id replaces the ZIP source and is consumed after the deployment is updated.



# Upload an Automation ZIP
Source: https://docs-platform.crewai.com/api/v1/reference/automations/upload-an-automation-zip

/openapi/platform-v1.yaml post /api/v1/automation-uploads
Uploads a ZIP source artifact for a later Automation create or redeploy request. Uploads expire one hour after creation and are scoped to the authenticated service account organization.



# A2A on AMP
Source: https://docs-platform.crewai.com/platform/en/features/a2a

Production-grade Agent-to-Agent communication with distributed state and multi-scheme authentication

<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](https://docs.crewai.com/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](https://docs.crewai.com/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 theme={null}
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](/platform/en/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](https://docs.crewai.com/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](https://docs.crewai.com/en/learn/a2a-agent-delegation#file-inputs-and-structured-output) for details.

### What AMP Adds

<CardGroup>
  <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](https://docs.crewai.com/en/learn/a2a-agent-delegation) — A2A protocol fundamentals and configuration
* [A2UI](https://docs.crewai.com/en/learn/a2ui) — Interactive UI rendering over A2A
* [Deploy to AMP](/platform/en/guides/deploy-to-amp) — General deployment guide
* [Webhook Streaming](/platform/en/features/webhook-streaming) — Event streaming for deployed automations


# Agent Repositories
Source: https://docs-platform.crewai.com/platform/en/features/agent-repositories

Learn how to use Agent Repositories to share and reuse your agents across teams and projects

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>
  <img alt="Agent Repositories" />
</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>
  <img alt="Agent Repositories" />
</Frame>

### Loading Agents from Repositories

You can load agents from repositories in your code using the `from_repository` parameter to run locally:

```python theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
# 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>


# Automations
Source: https://docs-platform.crewai.com/platform/en/features/automations

Manage, deploy, and monitor your live crews (automations) in one place.

## 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>
  <img alt="Automations Overview" />
</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>
  <img alt="GitHub Deployment" />
</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>
  <img alt="ZIP Deployment" />
</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>
  <img alt="Automations Table" />
</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>
  <Card title="Deploy a Crew" href="/platform/en/guides/deploy-to-amp" icon="rocket">
    Deploy a Crew from GitHub or ZIP file.
  </Card>

  <Card title="Automation Triggers" href="/platform/en/guides/automation-triggers" icon="trigger">
    Trigger automations via webhooks or API.
  </Card>

  <Card title="Webhook Automation" href="/platform/en/guides/webhook-automation" icon="webhook">
    Stream real-time events and updates to your systems.
  </Card>

  <Card title="Conversational Flow Chat" href="/platform/en/guides/conversational-flow-chat" icon="comments">
    Multi-turn chat sessions, streaming, and history for conversational Flows.
  </Card>
</CardGroup>


# Crew Studio
Source: https://docs-platform.crewai.com/platform/en/features/crew-studio

Build new automations with AI assistance, a visual editor, and integrated testing.

## Overview

Crew Studio is an interactive, AI‑assisted workspace for creating new automations from scratch using natural language and a visual workflow editor.

<Frame>
  <img alt="Crew Studio Overview" />
</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>
  <img alt="Prompt Builder" />
</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>
  <img alt="Visual Canvas" />
</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>
  <img alt="Execution View" />
</Frame>

## Publish & Export

* <b>Publish</b> to deploy a live automation
* <b>Download</b> source as a ZIP to continue development in code outside Studio

<Note>
  A downloaded ZIP is a one-way export. Your Studio project remains the source
  of truth: changes you make to the downloaded code are not reflected in Studio
  and cannot be imported back. If you deploy the customized code, it becomes a
  separate code-sourced automation without the Studio visual editor, versioning,
  or validation.
</Note>

<Frame>
  <img alt="Publish & Download" />
</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>
  <img alt="Published Automation" />
</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>
  <Card title="Enable Crew Studio" href="/platform/en/guides/enable-crew-studio" icon="palette">
    Enable Crew Studio.
  </Card>

  <Card title="Build a Crew" href="/platform/en/guides/build-crew" icon="paintbrush">
    Build a Crew.
  </Card>

  <Card title="Deploy a Crew" href="/platform/en/guides/deploy-to-amp" icon="rocket">
    Deploy a Crew from GitHub or ZIP file.
  </Card>

  <Card title="Export a React Component" href="/platform/en/guides/react-component-export" icon="download">
    Export a React Component.
  </Card>
</CardGroup>


# Flow HITL Management
Source: https://docs-platform.crewai.com/platform/en/features/flow-hitl-management

Enterprise-grade human review for Flows with email-first notifications, routing rules, and auto-response capabilities

<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>
  <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 theme={null}
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](https://docs.crewai.com/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 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 alt="HITL Routing Rules Configuration" />
</Frame>

### Rule Structure

```json theme={null}
{
  "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 theme={null}
{
  "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 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 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 alt="HITL Metrics Dashboard" />
</Frame>

<CardGroup>
  <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 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 theme={null}
{
  "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 theme={null}
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 theme={null}
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>
  <Card title="Human Feedback in Flows" icon="code" href="https://docs.crewai.com/en/learn/human-feedback-in-flows">
    Implementation guide for the `@human_feedback` decorator
  </Card>

  <Card title="Flow HITL Workflow Guide" icon="route" href="/platform/en/guides/human-in-the-loop">
    Step-by-step guide for setting up HITL workflows
  </Card>

  <Card title="RBAC Configuration" icon="shield-check" href="/platform/en/features/rbac">
    Configure role-based access control for your organization
  </Card>

  <Card title="Webhook Streaming" icon="bolt" href="/platform/en/features/webhook-streaming">
    Set up real-time event notifications
  </Card>
</CardGroup>


# Hallucination Guardrail
Source: https://docs-platform.crewai.com/platform/en/features/hallucination-guardrail

Prevent and detect AI hallucinations in your CrewAI tasks

## 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 theme={null}
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 theme={null}
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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
    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 theme={null}
    # 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>


# Marketplace
Source: https://docs-platform.crewai.com/platform/en/features/marketplace

Discover, install, and govern reusable assets for your enterprise crews.

## Overview

The Marketplace provides a curated surface for discovering integrations, internal tools, and reusable assets that accelerate crew development.

<Frame>
  <img alt="Marketplace Overview" />
</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>
  <img alt="Install & Configure" />
</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>
  <Card title="Tools & Integrations" href="/platform/en/features/tools-and-integrations" icon="wrench">
    Connect external apps and manage internal tools your agents can use.
  </Card>

  <Card title="Tool Repository" href="/platform/en/guides/tool-repository#tool-repository" icon="toolbox">
    Publish and install tools to enhance your crews' capabilities.
  </Card>

  <Card title="Agents Repository" href="/platform/en/features/agent-repositories" icon="people-group">
    Store, share, and reuse agent definitions across teams and projects.
  </Card>
</CardGroup>


# One Card per Step
Source: https://docs-platform.crewai.com/platform/en/features/merged-step-card

Each step on the Studio canvas is a single card that combines the task and the agent that performs it.

## Overview

On the Studio canvas, each step of work is represented by a **single card**. The card combines two things that used to live in separate nodes:

* **The task** — what to do (name, description, expected output, and response format).
* **The agent** — who does it (the assigned agent, its model, and its tools).

An agent isn't an independent participant in your workflow — it's an attribute of the task: *which agent performs this work.* Putting the task and its agent on one card makes that relationship explicit and turns your automation into a single, left-to-right chain of work units that's easier to read at a glance.

<Frame>
  <img alt="Merged step cards on the canvas" />
</Frame>

## On the canvas

Each collapsed card shows:

* The **task name and description** at the top.
* A **footer summarizing the assigned agent** — avatar, name, model, and tools.

There's no separate agent node and no vertical agent → task edge. Your steps connect directly to one another in the order they run.

## In the editor

Open a card to edit it. The expanded view is the same card in a detailed state — not a different screen — organized into two clearly labeled sections.

<Frame>
  <img alt="Expanded step editor" />
</Frame>

### The task — what to do

Open by default, since this is what you usually edit:

* **Name**
* **Description**
* **Expected Output**
* **Response Format** — surfaced here because it controls exactly what downstream steps (such as routing) read from this step.

### The agent — who does it

The assigned agent is shown as a summary — **name, model, and tools inline**. Its deeper configuration is preserved behind two disclosures:

* **Role, goal & backstory**
* **Agent settings** — reasoning, max reasoning attempts, allow delegation, max iterations, and LLM settings.

<Tip>
  An agent's full configuration — Role, Goal, Backstory, Model, Tools, LLM Settings, and the complete Agent Settings block — lives behind the **Role, goal & backstory** and **Agent settings** disclosures, organized by how often you edit it.
</Tip>

## Swapping vs. editing the agent

There are two distinct ways to work with the agent on a card, and they do different things:

* **Swap** reassigns *which* agent performs this task. Use the **Swap** control to pick a different agent from this project, choose one from your Agent Repository, or create a new agent. This is scoped to the task.
* **Editing** the agent — opening **Role, goal & backstory** or **Agent settings** — changes the agent *itself*.

<Frame>
  <img alt="Swap agent panel" />
</Frame>

<Warning>
  **Agents are reusable and shared.** The same agent can perform more than one task across your project. Editing an agent's role, backstory, or settings updates that agent **everywhere it's used** — not just on the card you opened. If you want a change to apply to only one step, **Swap** in a different agent instead of editing the shared one.
</Warning>

## Related

<CardGroup>
  <Card title="Crew Studio" href="/platform/en/features/crew-studio" icon="pencil">
    Build automations with AI assistance and a visual editor.
  </Card>

  <Card title="Agent Repositories" href="/platform/en/features/agent-repositories" icon="users">
    Manage and reuse agents across your automations.
  </Card>
</CardGroup>


# PII Redaction for Traces
Source: https://docs-platform.crewai.com/platform/en/features/pii-trace-redactions

Automatically redact sensitive data from crew and flow execution traces

## 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>
  <img alt="PII Redaction Overview" />
</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>
      <img alt="Enable PII Redaction" />
    </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>
      <img alt="Configure Entities" />
    </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](mailto: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](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>
  <img alt="Custom Recognizers" />
</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>
      <img alt="Configure Recognizer" />
    </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>
  <img alt="Salary Recognizer Configuration" />
</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>
      <img alt="Enable Custom Recognizer" />
    </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>


# Role-Based Access Control (RBAC)
Source: https://docs-platform.crewai.com/platform/en/features/rbac

Control access to crews, tools, and data with roles, scopes, and granular permissions.

## 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 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 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>


# AWS Secrets Manager (Static Credentials)
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/aws

Configure AWS Secrets Manager as a secret provider for CrewAI Platform using static access keys or AssumeRole

## 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)](/platform/en/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](/platform/en/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)](/platform/en/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).

## 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 theme={null}
{
  "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>

## 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**.
  </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 theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "sts:AssumeRole",
          "Resource": "ROLE_ARN_FROM_ABOVE"
        }
      ]
    }
    ```

    4. Name the policy `CrewAIAssumeSecretsRole` and click **Create policy**.
  </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).
  </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.
  </Tab>
</Tabs>

## Step 5 — Add the Credential in CrewAI Platform

In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.

<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**.
  </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**.
  </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>

## 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](/platform/en/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).

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

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](/platform/en/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)](/platform/en/features/secrets-manager/aws-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff.


# AWS Workload Identity (OIDC Federation)
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/aws-workload-identity

Configure AWS Secrets Manager via Workload Identity for rotation-aware, credential-free secret access

## 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](/platform/en/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)](/platform/en/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 theme={null}
{
  "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 theme={null}
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>

## 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 theme={null}
{
  "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 theme={null}
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>

## 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 theme={null}
{
  "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 theme={null}
    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 theme={null}
    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.
  </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 theme={null}
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**.

## 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. `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**.

## 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**.

## 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](/platform/en/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 theme={null}
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](/platform/en/features/secrets-manager/usage)
* For multi-cloud, see also [GCP Workload Identity Federation](/platform/en/features/secrets-manager/gcp-workload-identity) and [Azure Workload Identity Federation](/platform/en/features/secrets-manager/azure-workload-identity).


# Azure Key Vault
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/azure

Configure Azure Key Vault as a secret provider for CrewAI Platform, end-to-end

## 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](/platform/en/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](/platform/en/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)](/platform/en/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).

## 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](/platform/en/features/secrets-manager/azure-workload-identity) instead.
</Warning>

## 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 theme={null}
    az role assignment create \
      --assignee <APPLICATION_CLIENT_ID> \
      --role "Key Vault Secrets User" \
      --scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
    ```
  </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 theme={null}
    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)
    ```
  </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**.

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

## 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 theme={null}
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](/platform/en/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).

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

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](/platform/en/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](/platform/en/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.


# Azure Workload Identity Federation
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/azure-workload-identity

Configure Azure Key Vault via Microsoft Entra Workload Identity Federation for rotation-aware, credential-free secret access

## 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](/platform/en/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)](/platform/en/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 theme={null}
{
  "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.

## 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).

## 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 theme={null}
    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.
  </Tab>

  <Tab title="Per-secret (least privilege)">
    ```bash theme={null}
    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.
  </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 theme={null}
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**.

## 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>

## 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](/platform/en/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 theme={null}
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](/platform/en/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](/platform/en/features/secrets-manager/usage)
* For multi-cloud, the AWS-equivalent setup is at [AWS Workload Identity (OIDC Federation)](/platform/en/features/secrets-manager/aws-workload-identity) and the GCP-equivalent at [GCP Workload Identity Federation](/platform/en/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.


# Google Cloud Secret Manager
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/gcp

Configure Google Cloud Secret Manager as a secret provider for CrewAI Platform, end-to-end

## 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](/platform/en/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](/platform/en/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 theme={null}
    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)](/platform/en/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).

## 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 theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
      --role="roles/secretmanager.secretAccessor"
    ```
  </Tab>

  <Tab title="Per-secret (least privilege)">
    Grant the role only on the specific secrets CrewAI Platform should access. Repeat for each secret:

    ```bash theme={null}
    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.
  </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 theme={null}
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](/platform/en/features/secrets-manager/gcp-workload-identity) instead.
</Warning>

## Step 4 — Add the Credential in CrewAI Platform

In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.

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

## 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 theme={null}
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](/platform/en/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).

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

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](/platform/en/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](/platform/en/features/secrets-manager/gcp-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff.


# GCP Workload Identity Federation
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/gcp-workload-identity

Configure Google Cloud Secret Manager via Workload Identity Federation for rotation-aware, credential-free secret access

## 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](/platform/en/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 theme={null}
    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)](/platform/en/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 theme={null}
{
  "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 theme={null}
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**.

## Step 3 — Add CrewAI Platform as an OIDC Provider in the Pool

```bash theme={null}
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 theme={null}
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.

## 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 theme={null}
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 theme={null}
  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 theme={null}
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**.

## 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**.

## 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](/platform/en/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 theme={null}
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](/platform/en/features/secrets-manager/usage)
* For multi-cloud, see also [AWS Workload Identity (OIDC Federation)](/platform/en/features/secrets-manager/aws-workload-identity) and [Azure Workload Identity Federation](/platform/en/features/secrets-manager/azure-workload-identity).


# Secrets Manager Overview
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/overview

Connect external secret stores to CrewAI Platform and reference managed secrets from environment variables

## 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](/platform/en/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](/platform/en/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/platform/en/features/secrets-manager/aws-workload-identity)         |
| Google Cloud Secret Manager | [GCP — service account key](/platform/en/features/secrets-manager/gcp)      | [GCP — Workload Identity Federation](/platform/en/features/secrets-manager/gcp-workload-identity)     |
| Azure Key Vault             | [Azure — client secret](/platform/en/features/secrets-manager/azure)        | [Azure — Workload Identity Federation](/platform/en/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](/platform/en/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)](/platform/en/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](/platform/en/features/secrets-manager/aws)
  * [Configure Google Cloud Secret Manager](/platform/en/features/secrets-manager/gcp)
  * [Configure Azure Key Vault](/platform/en/features/secrets-manager/azure)
* **Workload Identity** (rotation-aware, no re-deploy):
  * [Configure AWS Workload Identity](/platform/en/features/secrets-manager/aws-workload-identity)
  * [Configure GCP Workload Identity Federation](/platform/en/features/secrets-manager/gcp-workload-identity)
  * [Configure Azure Workload Identity Federation](/platform/en/features/secrets-manager/azure-workload-identity)
* Then: [Use secrets in environment variables and manage permissions](/platform/en/features/secrets-manager/usage)


# Using the Secrets Manager
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/usage

Manage permissions and reference managed secrets from environment variables in CrewAI Platform

## 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](/platform/en/features/secrets-manager/aws) · [GCP](/platform/en/features/secrets-manager/gcp)
* Workload Identity (rotation-aware): [AWS](/platform/en/features/secrets-manager/aws-workload-identity) · [GCP](/platform/en/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.

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.

4. Save the role.

5. Assign the role to the relevant members from the same Roles page (or the org Members list).

## 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**.

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.

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

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

<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](/platform/en/features/secrets-manager/aws-workload-identity) or [GCP WI](/platform/en/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](/platform/en/features/secrets-manager/overview)
* Static credentials: [AWS](/platform/en/features/secrets-manager/aws) · [GCP](/platform/en/features/secrets-manager/gcp)
* Workload Identity (rotation-aware): [AWS](/platform/en/features/secrets-manager/aws-workload-identity) · [GCP](/platform/en/features/secrets-manager/gcp-workload-identity)


# Verify Rotation
Source: https://docs-platform.crewai.com/platform/en/features/secrets-manager/verify-rotation

A self-contained example crew that proves secret rotation propagates to running deployments without re-deploy.

## 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](/platform/en/features/secrets-manager/aws-workload-identity), [GCP](/platform/en/features/secrets-manager/gcp-workload-identity), [Azure](/platform/en/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](/platform/en/features/secrets-manager/aws-workload-identity), [GCP](/platform/en/features/secrets-manager/gcp-workload-identity), [Azure](/platform/en/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 theme={null}
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 theme={null}
"""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 theme={null}
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 theme={null}
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 theme={null}
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](/platform/en/features/secrets-manager/aws-workload-identity) or [GCP WI](/platform/en/features/secrets-manager/gcp-workload-identity)
* **Secret Name:** the name of the secret in your cloud provider's Secret Manager

## Step 6 — Run the First Kickoff

Replace `<DEPLOYMENT_AUTH_TOKEN>` and `<DEPLOYMENT_HOST>` with values from your deployment's **Run** tab.

```bash theme={null}
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 theme={null}
    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 theme={null}
    echo -n "rotated value" | gcloud secrets versions add <SECRET_NAME> \
      --data-file=- \
      --project=<YOUR_PROJECT_ID>
    ```
  </Tab>

  <Tab title="Azure">
    ```bash theme={null}
    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 theme={null}
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](/platform/en/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.


# Single Sign-On (SSO)
Source: https://docs-platform.crewai.com/platform/en/features/sso

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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
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 theme={null}
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 theme={null}
# 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 theme={null}
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](https://docs.crewai.com/installation) — Get started with CrewAI
* [Quickstart](https://docs.crewai.com/quickstart) — Build your first crew
* [RBAC Setup](/platform/en/features/rbac) — Detailed role and permission management


# Flows in Studio
Source: https://docs-platform.crewai.com/platform/en/features/studio-flows

Build event-driven workflows that combine deterministic, step-by-step control with agentic intelligence — no code required.

<Info>
  **Rolling out now**: Flows in Studio is being rolled out gradually during the week of July 20th, 2026. If you don't see the Flows option in Studio yet, it hasn't reached your organization — check back soon.
</Info>

## Overview

Studio now supports building **Flows** in addition to Crews. Flows are event-driven workflows where you control exactly which steps run, in what order, and under what conditions — while still delegating the intelligent work within each step to AI agents.

To build a Flow, open Studio, describe your automation, and select **Flows** from the selector next to the prompt box.

<Frame>
  <img alt="Flows selector in Studio" />
</Frame>

## Why Flows?

Crews are great when you want a team of agents to collaborate autonomously toward a goal. But many real-world automations need more predictability: fetch this data first, then summarize it, then post the result — every time, in that order.

Flows give you both:

* **Determinism where it matters**: steps execute in a defined sequence with explicit branching, so runs are predictable, repeatable, and easy to debug.
* **Intelligence where you need it**: each step is powered by an agent (or an entire crew), so the work inside a step — summarizing, scoring, drafting, deciding — benefits from full LLM reasoning.

This mix is what makes Flows well suited for production automations: the structure is guaranteed, and the agency is scoped to the steps that need it.

## Building a Flow

Describe what you want in natural language and the Studio Assistant designs the Flow for you — creating the steps, wiring them together, and configuring the agents and app integrations each step needs. The canvas on the right shows the resulting workflow as connected nodes, and you can keep iterating conversationally or edit any node directly.

<Frame>
  <img alt="Flow canvas with the Studio Assistant" />
</Frame>

When you're ready, use **Run** to test the Flow end-to-end, inspect results in the **Output** and **Traces** tabs, and **Deploy** when it's stable. You can also **Share** the project or **Download** the source code to continue development outside Studio.

<Note>
  Downloading source code is a one-way export. The Studio project remains the
  source of truth, and changes to downloaded code cannot be imported back.
  Deploying customized code creates a separate code-sourced automation without
  the Studio visual editor, versioning, or validation.
</Note>

## Node Types

Flows are composed from three core node types. Each node is a step in the workflow, and you can mix them freely.

### Single Agent

A Single Agent node runs one agent against one focused task — ideal for well-scoped steps like fetching data from an integration, transforming content, or posting a message.

Clicking into an agent node opens its full configuration:

* **Task**: what this step should accomplish and what output it should produce
* **Profile**: the agent's role, goal, and backstory
* **Model**: which LLM powers the agent
* **Apps**: the integrations the agent can use (e.g. Linear, Slack, HubSpot)
* **Runtime Controls**: toggles for planning before executing, delegation, and memory

<Frame>
  <img alt="Single Agent node configuration" />
</Frame>

### Crews

A Crew node embeds an entire crew — multiple agents collaborating across multiple tasks — as a single step in your Flow. Use it when a step is too rich for one agent, like grouping and summarizing data by team and then formatting the result for delivery.

<Frame>
  <img alt="Crew node in a Flow" />
</Frame>

Opening a Crew node reveals its internal structure: the tasks it performs, the agents assigned to each, and the apps they use. The crew runs autonomously within the step, then hands its output to the next node in the Flow.

<Frame>
  <img alt="Inside a Crew node" />
</Frame>

This is the deterministic-plus-agentic pattern in action: the Flow guarantees *when* the crew runs, and the crew brings collaborative intelligence to *how* the work gets done.

### Router

A Router node branches the Flow based on conditions, so different outcomes take different paths. For example, a lead-routing Flow can score incoming leads and then route high-quality leads to a sales-assignment step while logging the rest for future nurturing.

<Frame>
  <img alt="Router node with conditional branches" />
</Frame>

Routers are what make Flows genuinely event-driven: the same workflow handles every case, but each run follows only the branch its data warrants — no wasted steps, no ambiguity about what happens next.

## Agent Repository Sync

Agents you build in Flows don't have to stay locked inside a single project. Every agent node includes a **Publish to Agent Repository** button that saves the agent — its role, goal, backstory, model, and configuration — to your organization's [Agent Repository](/platform/en/features/agent-repositories).

This works in both directions:

* **Publish**: promote an agent you've refined in a Flow to the repository so other teams and projects can reuse it.
* **Pull**: bring an existing repository agent into a new Flow instead of rebuilding it from scratch.

Because repository agents are synced across your organization, an improvement made to a shared agent benefits every Flow that uses it — keeping agent behavior consistent, governed, and free of duplicated effort.

## Best Practices

* **Reach for a Flow** when the automation has a clear sequence or branching logic; reach for a Crew when the path to the goal is open-ended.
* **Keep agent tasks focused** — a Single Agent node with a tight task description is more reliable than one asked to do three things.
* **Use Routers to handle every case explicitly**, including the "do nothing" path (e.g. logging skipped leads), so runs are fully accounted for.
* **Publish stable agents to the Agent Repository** so your organization builds a shared library instead of parallel one-offs.
* **Test with Run and inspect Traces** before deploying to catch integration or prompt issues early.

## Related

<CardGroup>
  <Card title="Crew Studio" href="/platform/en/features/crew-studio" icon="pencil">
    Build Crews in Studio.
  </Card>

  <Card title="Agent Repositories" href="/platform/en/features/agent-repositories" icon="people-group">
    Share and reuse agents across your organization.
  </Card>

  <Card title="Flows Concepts" href="https://docs.crewai.com/en/concepts/flows" icon="diagram-project">
    Learn how Flows work in the CrewAI framework.
  </Card>

  <Card title="Tools & Integrations" href="/platform/en/features/tools-and-integrations" icon="plug">
    Connect the apps your agents use.
  </Card>
</CardGroup>


# Tools & Integrations
Source: https://docs-platform.crewai.com/platform/en/features/tools-and-integrations

Connect external apps and manage internal tools your agents can use.

## Overview

Tools & Integrations is the central hub for connecting third‑party apps and managing internal tools that your agents can use at runtime.

<Frame>
  <img alt="Tools & Integrations Overview" />
</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>
      <img alt="Integrations Grid" />
    </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>
      <img alt="Enterprise Token" />
    </Frame>

    ### Install Integration Tools

    To use the integrations locally, you need to install the latest `crewai-tools` package.

    ```bash theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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>
      <img alt="Filter Actions" />
    </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>
      <img alt="User Bearer Token" />
    </Frame>

    <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>
      <img alt="Internal Tool Detail" />
    </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>
      <img alt="Internal Tool Detail" />
    </Frame>
  </Tab>
</Tabs>

## Related

<CardGroup>
  <Card title="Tool Repository" href="/platform/en/guides/tool-repository#tool-repository" icon="toolbox">
    Create, publish, and version custom tools for your organization.
  </Card>

  <Card title="Webhook Automation" href="/platform/en/guides/webhook-automation" icon="bolt">
    Automate workflows and integrate with external platforms and services.
  </Card>
</CardGroup>


# Traces
Source: https://docs-platform.crewai.com/platform/en/features/traces

Using Traces to monitor your Crews

## 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>
  <img alt="Traces Overview" />
</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>
  <img alt="Execution Summary" />
</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>
  <img alt="Task List" />
</Frame>

### 3. Final Output

Displays the final result produced by the crew after all tasks are completed.

<Frame>
  <img alt="Final Output" />
</Frame>

### 4. Execution Timeline

A visual representation of when each task started and ended, helping you identify bottlenecks or parallel execution patterns.

<Frame>
  <img alt="Execution Timeline" />
</Frame>

### 5. Detailed Task View

When you click on a specific task in the timeline or task list, you'll see:

<Frame>
  <img alt="Detailed Task View" />
</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>
      <img alt="Failure Points" />
    </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>


# Webhook Streaming
Source: https://docs-platform.crewai.com/platform/en/features/webhook-streaming

Using Webhook Streaming to stream events to your webhook

## 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 theme={null}
{
  "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 theme={null}
{
  "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>


# Triggers Overview
Source: https://docs-platform.crewai.com/platform/en/guides/automation-triggers

Understand how CrewAI AMP triggers work, how to manage them, and where to find integration-specific playbooks

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>
  <img alt="Automation Triggers Overview" />
</Frame>

### Integration Playbooks

Deep-dive guides walk through setup and sample workflows for each integration:

<CardGroup>
  <Card title="Gmail Trigger" icon="envelope">
    <a href="/platform/en/guides/gmail-trigger">Enable crews when emails arrive or threads update.</a>
  </Card>

  <Card title="Google Calendar Trigger" icon="calendar-days">
    <a href="/platform/en/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="/platform/en/guides/google-drive-trigger">
      Handle Drive file uploads, edits, and deletions.
    </a>
  </Card>

  <Card title="Outlook Trigger" icon="envelope-open">
    <a href="/platform/en/guides/outlook-trigger">
      Automate responses to new Outlook messages and calendar updates.
    </a>
  </Card>

  <Card title="OneDrive Trigger" icon="cloud">
    <a href="/platform/en/guides/onedrive-trigger">
      Audit file activity and sharing changes in OneDrive.
    </a>
  </Card>

  <Card title="Microsoft Teams Trigger" icon="comments">
    <a href="/platform/en/guides/microsoft-teams-trigger">
      Kick off workflows when new Teams chats start.
    </a>
  </Card>

  <Card title="HubSpot Trigger" icon="hubspot">
    <a href="/platform/en/guides/hubspot-trigger">
      Launch automations from HubSpot workflows and lifecycle events.
    </a>
  </Card>

  <Card title="Salesforce Trigger" icon="salesforce">
    <a href="/platform/en/guides/salesforce-trigger">
      Connect Salesforce processes to CrewAI for CRM automation.
    </a>
  </Card>

  <Card title="Slack Trigger" icon="slack">
    <a href="/platform/en/guides/slack-trigger">
      Start crews directly from Slack slash commands.
    </a>
  </Card>

  <Card title="Zapier Trigger" icon="bolt">
    <a href="/platform/en/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>
  <img 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>
  <img 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>
  <img 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 theme={null}
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 theme={null}
crewai triggers run <trigger_name>
```

For example:

```bash theme={null}
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 theme={null}
@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: ") - 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 theme={null}
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 theme={null}
@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.


# Azure OpenAI Setup
Source: https://docs-platform.crewai.com/platform/en/guides/azure-openai-setup

Configure Azure OpenAI with Crew Studio for enterprise LLM connections

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 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](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


# Build Crew
Source: https://docs-platform.crewai.com/platform/en/guides/build-crew

A Crew is a group of agents that work together to complete a task.

## Overview

[CrewAI AMP](https://app.crewai.com) streamlines the process of **creating**, **deploying**, and **managing** your AI agents in production environments.

## Getting Started

<iframe title="Building crews with the CrewAI CLI" />

### Installation and Setup

<Card title="Follow Standard Installation" icon="wrench" href="https://docs.crewai.com/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="https://docs.crewai.com/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>


# OpenTelemetry Export
Source: https://docs-platform.crewai.com/platform/en/guides/capture_telemetry_logs

Export traces and logs from your CrewAI AMP deployments to your own OpenTelemetry collector

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.

<Tip>
  OpenTelemetry is the **recommended observability path** — vendor-neutral, works with any OTLP-compatible backend (Grafana, Honeycomb, NewRelic, your own collector). If you specifically use Datadog, see the dedicated [Datadog Integration](./datadog) guide which covers both the Datadog Agent path and Datadog's OTLP intake.
</Tip>

## Prerequisites

<CardGroup>
  <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>
      <img alt="OpenTelemetry collector configuration" />
    </Frame>
  </Tab>

  <Tab title="Datadog">
    For Datadog setup, see the dedicated [Datadog Integration](./datadog) guide — it covers both the Datadog Agent path (recommended, cheaper for log volume) and Datadog's OTLP intake with full collector configuration steps.
  </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>


# Conversational Flow Chat API
Source: https://docs-platform.crewai.com/platform/en/guides/conversational-flow-chat

Use the deployment chat endpoints to run multi-turn conversational Flows on CrewAI AMP

## Overview

Deployed conversational Flows expose a chat session API on the automation URL. Instead of a single `/kickoff` run, you create a session, send user messages as turns, optionally stream tokens and runtime events, and resume HITL pauses when a turn needs human feedback.

<Note>
  Conversational Flow chat is **experimental**. Endpoints are available only when the deployed Flow reports both `conversational: true` and `handle_turn: true` from [`GET /inspect`](#discover-chat-capability).
</Note>

For building the Flow itself (`conversational = True`, `handle_turn`, routers, tracing), see the open-source [Conversational Flows](https://docs.crewai.com/en/guides/flows/conversational-flows) guide.

## Prerequisites

1. Deploy a Flow automation that implements conversational turns (`handle_turn`).
2. Copy the bearer token from the automation **Status** tab (same token used for `/kickoff`).
3. Confirm chat is enabled via `/inspect` (below).

All requests use:

```bash theme={null}
Authorization: Bearer YOUR_FLOW_TOKEN
```

Base URL examples in this guide use `https://your-flow-url.crewai.com`.

## Discover chat capability

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect
```

Look for `flow.chat`:

```json theme={null}
{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}
```

If either flag is false, chat endpoints return `404` with `"Conversational flow chat is not available"`.

## End-to-end chat loop

<Steps>
  <Step title="Start a session">
    Create a chat session. Optionally register a completed-turn webhook and event webhooks for the session lifetime.

    ```bash theme={null}
    curl -X POST \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
        "webhooks": {
          "url": "https://your-server.com/webhooks/events",
          "events": ["*"],
          "realtime": false,
          "authentication": {
            "strategy": "bearer",
            "token": "my-secret-token"
          }
        }
      }' \
      https://your-flow-url.crewai.com/chat/start
    ```

    Response:

    ```json theme={null}
    { "session_id": "11111111-2222-3333-4444-555555555555" }
    ```

    An empty body (`{}` or no body) is valid when you do not need webhooks.
  </Step>

  <Step title="Send a user message">
    Queue one turn for the session:

    ```bash theme={null}
    curl -X POST \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "message": "Where is my order?",
        "stream": true
      }' \
      https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message
    ```

    Response:

    ```json theme={null}
    {
      "session_id": "11111111-2222-3333-4444-555555555555",
      "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "queued"
    }
    ```

    | Field            | Description                                                                                                                                                  |
    | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `message`        | Required. Current user line for this turn.                                                                                                                   |
    | `stream`         | Default `true`. When `true`, token/event frames are published for WebSocket/SSE clients.                                                                     |
    | `messageHistory` | Optional fallback transcript (`[{ "role", "content" }, ...]`). Server-side session history is authoritative; this is used only when stored history is empty. |

    Roles accepted in `messageHistory`: `user`, `assistant`, `system`, `tool`.
  </Step>

  <Step title="Wait for the turn to finish">
    Poll the turn with the returned `kickoff_id` (same status API as a normal Flow kickoff):

    ```bash theme={null}
    curl -X GET \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    ```

    Only one turn can be active per session. A second `/message` while `active_kickoff_id` is set returns `409`:

    ```json theme={null}
    {
      "detail": {
        "code": "session_busy",
        "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
    }
    ```

    Wait until history shows `active_kickoff_id: null` (or the turn reaches a terminal status / pause) before sending the next message.
  </Step>

  <Step title="Read session history">
    ```bash theme={null}
    curl -X GET \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history
    ```

    ```json theme={null}
    {
      "session_id": "11111111-2222-3333-4444-555555555555",
      "messages": [
        { "role": "user", "content": "Where is my order?" },
        { "role": "assistant", "content": "Your order is on the way." }
      ],
      "active_kickoff_id": null
    }
    ```
  </Step>
</Steps>

## Streaming a turn

Streaming is optional. Use it when a UI needs tokens or runtime events as the turn runs. Frames always include lifecycle types (`turn_started`, `turn_completed`, `turn_failed`, `token`, `error`). Additional `event` frames can be filtered with the `events` query parameter (`*` or a comma-separated list).

### Option A: HTTP message + SSE attach

1. `POST /chat/{session_id}/message` with `"stream": true`.
2. Attach to the active turn:

```bash theme={null}
curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"
```

SSE returns `text/event-stream` JSON frames (`data: {...}`), plus keepalive comments. The stream ends on `turn_completed` or `turn_failed`.

If there is no active turn, this endpoint returns `409` (`No active chat turn`).

### Option B: WebSocket (attach or send)

```text theme={null}
wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0
```

Auth: pass the bearer token as the `token` query param, or as an `Authorization: Bearer ...` header when your client supports WebSocket headers.

Behavior:

* **Active turn already running** — the socket attaches and first emits `turn_started` with `data.status: "attached"`, then streams frames until a terminal type.
* **No active turn** — send a JSON message to queue a turn, then consume the stream:

```json theme={null}
{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}
```

The server responds with `turn_started` (`status: "queued"`) and then stream frames for that `kickoff_id`.

Use `last_event_id` / `lastEventId` to resume after disconnects.

### Example stream frames

```json theme={null}
{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}
```

```json theme={null}
{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}
```

```json theme={null}
{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}
```

## HITL inside a chat session

If a turn pauses for human feedback (`status` / state `PAUSED`), resume with the same Flow resume endpoint used for non-chat runs:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback
```

Then poll the resume `kickoff_id` from the response. Wait until `/history` shows `active_kickoff_id: null` before sending the next chat message.

See [HITL Workflows](/platform/en/guides/human-in-the-loop) and [Flow HITL Management](/platform/en/features/flow-hitl-management) for platform review UX.

## API reference

| Method | Path                               | Purpose                                         |
| ------ | ---------------------------------- | ----------------------------------------------- |
| `GET`  | `/inspect`                         | Discover whether conversational chat is enabled |
| `POST` | `/chat/start`                      | Create a chat session                           |
| `POST` | `/chat/{session_id}/message`       | Queue a user turn                               |
| `GET`  | `/chat/{session_id}/history`       | Read messages and active turn id                |
| `GET`  | `/chat/{session_id}/stream/events` | SSE stream for the active turn                  |
| `WS`   | `/chat/{session_id}/stream`        | WebSocket stream (attach or send + stream)      |
| `GET`  | `/status/{kickoff_id}`             | Poll turn (or resume) execution status          |
| `POST` | `/resume_feedback`                 | Resume a paused HITL turn                       |

### Common errors

| Status | When                                                                                   |
| ------ | -------------------------------------------------------------------------------------- |
| `400`  | Empty `message`                                                                        |
| `404`  | Chat not enabled on this deployment, or unknown `session_id`                           |
| `409`  | Session already has an active turn (`session_busy`), or SSE attach with no active turn |
| `422`  | `session_id` is not a valid UUID                                                       |
| `503`  | Chat session or stream storage unavailable                                             |

## Related

<CardGroup>
  <Card title="Conversational Flows" href="https://docs.crewai.com/en/guides/flows/conversational-flows" icon="comments">
    Build multi-turn Flows with `handle_turn`, routers, and tracing.
  </Card>

  <Card title="Kickoff Crew / Flow" href="/platform/en/guides/kickoff-crew" icon="flag-checkered">
    Single-run kickoff and status polling on a deployment URL.
  </Card>

  <Card title="Webhook Streaming" href="/platform/en/features/webhook-streaming" icon="webhook">
    Event webhook payload shape and authentication options.
  </Card>

  <Card title="Flow HITL Management" href="/platform/en/features/flow-hitl-management" icon="users-gear">
    Email-first human review for paused Flow steps.
  </Card>
</CardGroup>


# Custom MCP Servers
Source: https://docs-platform.crewai.com/platform/en/guides/custom-mcp-server

Connect your own MCP servers to CrewAI AMP with public access, API key authentication, or OAuth 2.0

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


# Datadog Integration
Source: https://docs-platform.crewai.com/platform/en/guides/datadog

Monitor self-hosted CrewAI AMP deployments in Datadog via the Datadog Agent or Datadog's OTLP intake — either path lands the same structured facets so you can import the ready-made operations dashboard.

CrewAI ships first-class support for Datadog: two log-ingestion paths, a JSON log schema designed for cheap indexing, and a ready-made operations dashboard you can import in under five minutes.

<Note>
  For vendor-neutral observability via any OTLP backend (Grafana, Honeycomb, your own collector), see [OpenTelemetry Export](./capture_telemetry_logs).
</Note>

## Choose a path

CrewAI supports two log-ingestion paths to Datadog — both are first-class and produce the same structured facets that power the dashboard. Pick the one that fits your infrastructure.

<Tabs>
  <Tab title="Datadog Agent">
    The Datadog Agent runs alongside your CrewAI containers (typically as a DaemonSet on Kubernetes) and tails their stdout. Each log event ships as a single billable line with structured attributes — see the [log schema reference](#log-schema-reference) for the full field contract.

    **Setup:**

    1. Run the Datadog Agent next to your CrewAI containers — see [Datadog's deployment docs](https://docs.datadoghq.com/agent/) for Kubernetes, ECS, or VM setup. Enable log collection (`logs_enabled: true`) and container log collection (`logs_config.container_collect_all: true`).
    2. Confirm logs arrive in Datadog Logs with the JSON fields parsed — see [Verify ingestion](#verify-ingestion).

    **Pick this path if** you already operate Datadog Agents (e.g. for infrastructure metrics), or your log volume makes per-event ingestion cost a real concern — collapsing tracebacks into single events keeps Agent ingestion cheap at scale.
  </Tab>

  <Tab title="Datadog OTLP intake">
    CrewAI AMP exports OpenTelemetry traffic directly to Datadog's OTLP endpoint with no Agent required. Logs and traces ride a single export pipeline configured in AMP's UI, using the same protocol you'd use for any other OTLP backend.

    **Setup:**

    1. In CrewAI AMP, go to **Settings → OpenTelemetry Collectors → Add Collector** and pick **Datadog**.
    2. Configure the connection:
       * **Datadog Site Domain** — your Datadog site's OTLP host only, no protocol or path. CrewAI builds the full HTTPS OTLP endpoint for you. Use the host that matches your [Datadog site](https://docs.datadoghq.com/getting_started/site/):
         * `otlp.datadoghq.com` (US1)
         * `otlp.us3.datadoghq.com` (US3)
         * `otlp.us5.datadoghq.com` (US5)
         * `otlp.datadoghq.eu` (EU1)
         * `otlp.ap1.datadoghq.com` (AP1)
       * **API Key** — your Datadog API key. See [how to create one](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys).
    3. The Datadog template provisions **both signals at once** — when you save, AMP creates a traces collector at `/v1/traces` and a logs collector at `/v1/logs`, both sharing the same Datadog OTLP host and API key. You'll see them as two separate rows in your OTel collectors list.
    4. *(optional)* Click **Test Connection** to verify CrewAI can reach the endpoint with the credentials you provided. Then click **Save** — both collectors are created in one step.

    <Frame>
      <img alt="Datadog collector configuration" />
    </Frame>

    **Pick this path if** you'd rather not operate a Datadog Agent, you already use OTLP for traces and want one export pipeline, or you may later want to fan out the same telemetry to other backends (Grafana, Honeycomb, etc.) without changing your application setup.
  </Tab>
</Tabs>

Either path lands the same structured facets in Datadog (`@automation_id`, `@kickoff_id`, `@execution_id`, `@automation_name`, `@crewai_version`, `@exception.type`, `@gen_ai.*`), so the dashboard works identically with either choice.

## Log schema reference

<Info>
  This schema applies to the **Datadog Agent path** — structured stdout JSON logs emitted by every CrewAI worker container. Logs delivered via the **Datadog OTLP intake** use OpenTelemetry attribute names and may differ; see [OpenTelemetry Export](./capture_telemetry_logs).
</Info>

Every log event is emitted as a **single JSON object per line** to stdout, with internal newlines escaped. The format is plain JSON — Datadog parses it natively, and the same payload is also consumable by Splunk, Loki, Elasticsearch, and CloudWatch without custom log pipelines.

### Why JSON output

<CardGroup>
  <Card title="Lower ingestion cost" icon="dollar-sign">
    Most managed log backends bill per event. A Python traceback in text format is counted as one event per line — 30+ events for a single error. JSON output collapses each traceback into a single event with the stack trace as an escaped string field.
  </Card>

  <Card title="Structured search" icon="magnifying-glass">
    Search by `@automation_id`, `@exception.type`, `@kickoff_id` instead of grepping free-text. Build dashboards on typed facets without parser configuration.
  </Card>

  <Card title="APM ↔ logs correlation" icon="link">
    Every event carries `trace_id` and `span_id` when fired inside a recording span, so backends auto-link logs to traces.
  </Card>

  <Card title="Stable contract" icon="file-shield">
    The `schema` field gates compatibility — within `v1`, fields are added but never renamed or removed.
  </Card>
</CardGroup>

### Example events

A single info-level log inside an active automation kickoff:

```json theme={null}
{
  "schema": "v1",
  "ts": "2026-06-17T16:14:23.482914Z",
  "level": "INFO",
  "logger": "crewai_enterprise.utilities.pii_redaction",
  "crewai_version": "1.14.7",
  "msg": "PII tracking state reset (engines preserved)",
  "automation_id": "12",
  "task_id": "0843a930-b306-464b-89c8-bfafa78cc711",
  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
  "automation_name": "research_flow"
}
```

An error with a Python exception is collapsed into a single event with the traceback as a string:

```json theme={null}
{
  "schema": "v1",
  "ts": "2026-06-17T16:14:31.218450Z",
  "level": "ERROR",
  "logger": "api.tasks.flow_run_task",
  "crewai_version": "1.14.7",
  "msg": "Flow execution failed",
  "automation_id": "12",
  "kickoff_id": "0843a930-b306-464b-89c8-bfafa78cc711",
  "execution_id": "0843a930-b306-464b-89c8-bfafa78cc711",
  "automation_name": "research_flow",
  "exception": {
    "type": "ValueError",
    "message": "Topic cannot be empty",
    "stacktrace": "Traceback (most recent call last):\n  File \"/app/flow.py\", line 42, in summarize\n    ...\nValueError: Topic cannot be empty\n"
  }
}
```

Without JSON output, that same error would produce \~25 separate log events (one per traceback line) — all of which the backend would bill and index individually.

### Schema v1 fields

Within the `v1` schema, fields are only added, never renamed or removed. New fields will appear as soon as a deployment is upgraded.

| Field             | Type                                | Always present                                     | Source                                                                                                                                |
| ----------------- | ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `schema`          | string                              | Yes                                                | Constant `"v1"`. Increment indicates a breaking schema change.                                                                        |
| `ts`              | string (ISO-8601 UTC, microseconds) | Yes                                                | Record creation time, e.g. `2026-06-17T16:14:23.482914Z`.                                                                             |
| `level`           | string                              | Yes                                                | Python log level name: `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`.                                                           |
| `logger`          | string                              | Yes                                                | Dotted logger name, e.g. `api.tasks.flow_run_task`.                                                                                   |
| `crewai_version`  | string                              | Yes (when `crewai` package metadata is resolvable) | Installed `crewai` package version, e.g. `"1.14.7"`.                                                                                  |
| `msg`             | string                              | Yes                                                | Rendered log message (after `%`-formatting / `{}`-formatting).                                                                        |
| `automation_id`   | string                              | When `CREWAI_PLUS_ID` env var is set               | Numeric deployment ID (AMP provisions this on every container).                                                                       |
| `task_id`         | string                              | On Celery worker logs                              | Celery task UUID, or `"no-task"` for non-task contexts.                                                                               |
| `kickoff_id`      | string                              | Inside an automation kickoff                       | UUID of the current kickoff.                                                                                                          |
| `execution_id`    | string                              | Inside an automation kickoff                       | UUID of the current sub-execution. Equal to `kickoff_id` at the top level; differs for nested flow methods that spawn sub-executions. |
| `automation_name` | string                              | Inside an automation kickoff                       | Human-readable automation/flow name, e.g. `"research_flow"`.                                                                          |
| `trace_id`        | string (32-hex)                     | Inside a recording OpenTelemetry span              | Hex trace ID. Omitted when no span is active.                                                                                         |
| `span_id`         | string (16-hex)                     | Inside a recording OpenTelemetry span              | Hex span ID. Omitted when no span is active.                                                                                          |
| `exception`       | object                              | When the log record has `exc_info`                 | `{type, message, stacktrace}` — full traceback as a single escaped string.                                                            |

<Tip>
  Any additional `extra={...}` kwargs passed to a logger call appear as top-level JSON fields verbatim. Reserved field names above always win to keep the schema stable.
</Tip>

### Stability promise

The `schema` field declares the contract. Within `v1`, CrewAI commits to:

* **Never removing a field** that customers may have built queries or dashboards against.
* **Never renaming a field** in place — renames happen via a schema bump (e.g. `v2`), with the old name kept as a deprecated alias for at least one release cycle.
* **Adding new fields** at any time. Consumers should ignore unknown top-level keys.

When a `v2` is introduced, both the `schema` field and the migration guide will be published in advance, and `v1` will continue to be emitted for one release cycle so dashboards and queries have time to migrate.

## Prerequisite: promote facets

Datadog auto-discovers fields the first time it sees them but doesn't make them queryable in widgets until they're promoted to **facets**. This is a one-time setup in your Datadog account.

<Steps>
  <Step title="Search for a CrewAI log">
    Open [Logs Explorer](https://app.datadoghq.com/logs) and search `service:crewai*`. You should see at least one log event.
  </Step>

  <Step title="Promote each field">
    Click any log entry to open the right-hand details panel. For each field below, hover the field name → click the gear icon → **Create facet**.

    * `automation_id`, `automation_name`, `execution_id`, `kickoff_id`, `task_id`
    * `crewai_version`, `model_id`
    * `exception.type`, `exception.message`

    Skip any field that already shows a star icon next to its name — that means it's already a facet. The `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, and `gen_ai.request.model` facets are typically promoted automatically by Datadog's LLM Observability auto-discovery, but verify they exist before importing the dashboard.
  </Step>
</Steps>

## Import the dashboard

<Steps>
  <Step title="Download the dashboard JSON">
    Save [`datadog_dashboard.json`](https://raw.githubusercontent.com/crewAIInc/crewAI/main/docs/platform/en/guides/datadog_dashboard.json) to your machine.
  </Step>

  <Step title="Open the import dialog in Datadog">
    Navigate to **Dashboards → New Dashboard**. Click the **gear icon** in the top right of the empty dashboard and select **Import Dashboard JSON**.
  </Step>

  <Step title="Paste or upload the JSON">
    Paste the contents of `datadog_dashboard.json` into the import dialog (or drag the file in). Click **Import**.

    Datadog creates the dashboard immediately and lands you on it. The first load may show empty widgets for a few seconds while queries execute against the time range.
  </Step>
</Steps>

<Tip>
  Datadog's [Dashboard API](https://docs.datadoghq.com/api/latest/dashboards/#create-a-new-dashboard) accepts the same JSON via `POST /api/v1/dashboard`. Use it if you manage dashboards through Terraform, Pulumi, or CI.
</Tip>

## What you get

The dashboard is organized into four sections plus a placeholder for a custom drill-down widget:

| Section        | Widgets                                                                                 | Useful for                                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Header**     | Total Executions · Error Rate (%) · Active Automations · CrewAI Versions in Use         | At-a-glance health for the last hour. Error Rate is conditionally formatted (green ≤ 5%, yellow ≤ 10%, red > 10%).           |
| **Throughput** | Executions per Hour by Automation (top 10, stacked bars)                                | Spotting traffic shifts, surfacing busy automations, validating that a rollout didn't change baseline volume.                |
| **Errors**     | Errors by Exception Type (top 5, stacked bars) · Top Exception Types by Count (toplist) | Triaging failures — which exception types are spiking, which automations they're hitting.                                    |
| **Cost**       | Total Tokens per Hour by Model (input + output, stacked area)                           | Tracking LLM token spend by model. Useful for catching cost regressions when an automation switches model or starts looping. |
| **Drill-Down** | *(empty placeholder)*                                                                   | See [Customization](#customize) for adding a recent-errors log stream here.                                                  |

Three template variables at the top of the dashboard re-scope every widget at once:

* **`$automation`** — filter to a single automation by name.
* **`$version`** — filter to a single `crewai` SDK version (useful for comparing pre- and post-upgrade behavior).
* **`$service`** — filter to a specific Datadog `service` tag (useful when multiple CrewAI deployments share one Datadog account).

## Verify ingestion

Open [Logs Explorer](https://app.datadoghq.com/logs) and run a query that matches your ingestion path:

<Tabs>
  <Tab title="Datadog Agent">
    Search `service:crewai* @schema:v1`. You should see structured logs with the JSON fields parsed into Datadog facets. Pick a recent event and verify it has `@automation_id`, `@kickoff_id`, `@execution_id`, `@crewai_version`, and (when running inside a span) `@trace_id` / `@span_id` populated.

    If nothing appears, confirm the Datadog Agent is tailing container stdout and that the deployment is running a recent enough CrewAI Enterprise build.
  </Tab>

  <Tab title="Datadog OTLP intake">
    Search `source:otlp service:crewai*`. OTLP attributes land with their OpenTelemetry names (`automation_id`, `crewai.kickoff.id`, etc.) rather than the stdout JSON keys, but they map to the same dashboard facets after [facet promotion](#prerequisite-promote-facets).

    If nothing appears, verify the collector endpoint is correct (`/v1/logs` for logs, `/v1/traces` for traces) and **Test Connection** succeeded when the collector was saved.
  </Tab>
</Tabs>

## Customize

The dashboard ships with deliberate gaps so you can extend it without uninstalling and re-importing.

### Add a Recent Errors log stream

The **Drill-Down** section is intentionally empty. Add a Log Stream widget to it for an inline view of recent failures:

1. Edit the dashboard and click **+ Add Widgets** inside the Drill-Down group.
2. Drag in a **Log Stream** widget.
3. Set the filter query to `status:error $automation $version $service`.
4. Choose columns: `@timestamp`, `@automation_name`, `@exception.type`, `@exception.message`, `@execution_id`.
5. Sort by most recent, limit to 25 entries.

Clicking any row jumps to Logs Explorer with the same filter pre-applied.

### Add p95 latency

Logs don't include execution duration by default. Two ways to add a latency widget:

* **From APM traces** — if you also export OTLP traces to Datadog, add a Timeseries widget with data source **Traces**, query `service:crewai*`, aggregation `p95 of @duration`. Datadog APM auto-tracks span duration.
* **From metric extraction** — extract a `flow.duration_ms` metric from logs via [Datadog's log-to-metric pipeline](https://docs.datadoghq.com/logs/log_configuration/logs_to_metrics/), then chart it like any other metric. Useful if you don't run APM.

### Re-scope to multiple deployments

The `$service` template variable defaults to `*` and will catch every CrewAI deployment in your Datadog account. Change the default to a specific service name in **Configure → Template Variables** if you want the dashboard to focus on one deployment by default.

## Troubleshooting

| Symptom                                           | Likely cause                                                     | Fix                                                                                                                                                                                                                                                              |
| ------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| All widgets show "No data"                        | Facets aren't promoted                                           | Re-do the [Promote facets](#prerequisite-promote-facets) step. Datadog won't query against an un-promoted field.                                                                                                                                                 |
| Error Rate widget shows `NaN`                     | No executions in the time window                                 | Either no traffic, or `@execution_id` isn't faceted. Expand the time range and re-check facets.                                                                                                                                                                  |
| Throughput chart is flat at the same value        | Logs aren't reaching Datadog                                     | Search `service:crewai*` in Logs Explorer. If nothing shows, verify the Datadog Agent is running (Agent path) or the OTel collector endpoint is correct (OTLP path).                                                                                             |
| `crewai_version` shows fewer values than expected | Some containers predate the structured-logs work                 | The `crewai_version` field was added alongside JSON output. Older deployments (pre-structured-logs AMP builds) won't emit it. Upgrade those deployments to pick up the field. See the [log schema reference](#log-schema-reference) for the full field contract. |
| Template variables don't filter widgets           | The widget's filter line doesn't reference the template variable | Edit the widget and confirm the search includes `$automation $version $service`.                                                                                                                                                                                 |

## Next steps

<CardGroup>
  <Card title="OpenTelemetry Export" icon="magnifying-glass-chart" href="./capture_telemetry_logs">
    Vendor-neutral observability for non-Datadog stacks (Grafana, Honeycomb, your own collector) — or as a Datadog complement when you want to fan out telemetry to multiple backends.
  </Card>

  <Card title="Datadog Log Search Syntax" icon="magnifying-glass" href="https://docs.datadoghq.com/logs/explorer/search_syntax/">
    Reference for customizing widget queries against the structured facets above.
  </Card>
</CardGroup>


# Deploy to AMP
Source: https://docs-platform.crewai.com/platform/en/guides/deploy-to-amp

Deploy your Crew or Flow to CrewAI AMP

<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>
  <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](/platform/en/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](/platform/en/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 theme={null}
    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 theme={null}
    # 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 theme={null}
    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 theme={null}
    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 theme={null}
    crewai deploy status
    ```

    For detailed logs of the build process:

    ```bash theme={null}
    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 theme={null}
# 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](https://docs.crewai.com/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>
      <img alt="Connect GitHub Button" />
    </Frame>
  </Step>

  <Step title="Select the Repository">
    After connecting your GitHub account, you'll be able to select which repository to deploy:

    <Frame>
      <img alt="Select Repository" />
    </Frame>

    <Tip>
      If your Crew or Flow is inside a monorepo subfolder, expand **Advanced**
      and set a working directory before deploying. See
      [Monorepo Deployments](/platform/en/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>
      <img alt="Set Environment Variables" />
    </Frame>

    <Info>
      Using private Python packages? You'll need to add your registry credentials here too.
      See [Private Package Registries](/platform/en/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>
      <img alt="Deploy Progress" />
    </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 theme={null}
    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 theme={null}
    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 theme={null}
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](/platform/en/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 theme={null}
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 theme={null}
# 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>


# Enable Crew Studio
Source: https://docs-platform.crewai.com/platform/en/guides/enable-crew-studio

Enabling Crew Studio on CrewAI AMP

<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>
  <img alt="Crew Studio Interface" />
</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
* Export generated code to continue development outside Studio
* 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>
      <img alt="LLM Connection Configuration" />
    </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>
      <img alt="Connection Added" />
    </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>
      <img alt="LLM Defaults Configuration" />
    </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 theme={null}
    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 to continue development outside Studio
    * Deploy the crew directly to the CrewAI AMP platform
    * Keep refining the configuration in Studio and regenerate the crew

    <Note>
      Downloading code is a one-way export. The Studio project remains the
      source of truth, and changes to downloaded code cannot be imported back.
      Deploying customized code creates a separate code-sourced automation
      without the Studio visual editor, versioning, or validation.
    </Note>
  </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 theme={null}
    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 to continue development outside Studio, or deploy directly
    from Studio. Downloaded code cannot be imported back into the Studio project.
  </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>


# Gmail Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/gmail-trigger

Trigger automations when Gmail events occur (e.g., new emails, labels).

## 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 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 theme={null}
@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 theme={null}
# 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 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


# Google Calendar Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/google-calendar-trigger

Kick off crews when Google Calendar events are created, updated, or cancelled

## 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 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 theme={null}
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 theme={null}
# 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 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


# Google Drive Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/google-drive-trigger

Respond to Google Drive file events with automated crews

## 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 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 theme={null}
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 theme={null}
# 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 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


# HubSpot Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/hubspot-trigger

Trigger CrewAI crews directly from HubSpot Workflows

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


# HITL Workflows
Source: https://docs-platform.crewai.com/platform/en/guides/human-in-the-loop

Learn how to implement Human-In-The-Loop workflows in CrewAI for enhanced decision-making

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>
  <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](https://docs.crewai.com/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 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 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 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 theme={null}
    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>
  <Card title="Flow HITL Management" icon="users-gear" href="/platform/en/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="https://docs.crewai.com/en/learn/human-feedback-in-flows">
    Implementation guide for the `@human_feedback` decorator in your Flows.
  </Card>
</CardGroup>


# Kickoff Crew
Source: https://docs-platform.crewai.com/platform/en/guides/kickoff-crew

Kickoff a Crew on CrewAI AMP

## 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>
  <img alt="Crew Dashboard" />
</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>
  <img alt="Kickoff Endpoint" />
</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>
  <img alt="Run Crew" />
</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>
  <img alt="Copy Task ID" />
</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>
  <img alt="Get Status" />
</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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{ "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 theme={null}
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 theme={null}
{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" }
```

### Step 3: Check Execution Status

Monitor the execution progress using the kickoff\_id:

```bash theme={null}
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>


# Microsoft Teams Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/microsoft-teams-trigger

Kick off crews from Microsoft Teams chat activity

## 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>
  <img alt="Enable or disable triggers with toggle" />
</Frame>

## Example: Summarize a new chat thread

```python theme={null}
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 theme={null}
# 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


# Monorepo Deployments
Source: https://docs-platform.crewai.com/platform/en/guides/monorepo-deployments

Deploy a Crew or Flow from a subfolder in a larger repository

<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 theme={null}
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 theme={null}
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 theme={null}
    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 theme={null}
    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 theme={null}
    company-ai/
    `-- crews/
        `-- support_agent/
            |-- pyproject.toml
            |-- uv.lock
            |-- crew.jsonc
            `-- agents/
                `-- support_agent.jsonc
    ```
  </Tab>

  <Tab title="Workspace lock file">
    ```text theme={null}
    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="/platform/en/guides/deploy-to-amp">
  Continue with the deployment guide after choosing your monorepo working
  directory.
</Card>


# OneDrive Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/onedrive-trigger

Automate responses to OneDrive file activity

## 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>
  <img alt="Enable or disable triggers with toggle" />
</Frame>

## Example: Audit file permissions

```python theme={null}
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 theme={null}
# 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


# Outlook Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/outlook-trigger

Launch automations from Outlook emails and calendar updates

## 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>
  <img alt="Enable or disable triggers with toggle" />
</Frame>

## Example: Summarize a new email

```python theme={null}
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 theme={null}
# 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


# Prepare for Deployment
Source: https://docs-platform.crewai.com/platform/en/guides/prepare-for-deployment

Ensure your Crew or Flow is ready for deployment to CrewAI AMP

<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>
  <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 theme={null}
    [tool.crewai]
    type = "crew"
    ```
  </Tab>

  <Tab title="For Flows">
    ```toml theme={null}
    [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 theme={null}
# 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 theme={null}
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 theme={null}
    {
      "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 theme={null}
    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 theme={null}
    crewai run
    ```
  </Tab>

  <Tab title="Classic Crews">
    The entry point uses a `run()` function:

    ```python theme={null}
    # 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 theme={null}
    # 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](/platform/en/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 theme={null}
# 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="/platform/en/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>


# Private Package Registries
Source: https://docs-platform.crewai.com/platform/en/guides/private-package-registry

Install private Python packages from authenticated PyPI registries in CrewAI AMP

<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 theme={null}
[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 theme={null}
[[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 theme={null}
[tool.uv.sources]
my-private-package = { index = "my-private-registry" }
```

### Complete example

```toml theme={null}
[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 theme={null}
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](/platform/en/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](/platform/en/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 theme={null}
    # .env
    OPENAI_API_KEY=sk-...
    UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token
    UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here
    ```

    ```bash theme={null}
    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](/platform/en/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 theme={null}
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>
  <Card title="Prepare for Deployment" icon="clipboard-check" href="/platform/en/guides/prepare-for-deployment">
    Verify project structure and dependencies before deploying.
  </Card>

  <Card title="Deploy to AMP" icon="rocket" href="/platform/en/guides/deploy-to-amp">
    Deploy your crew or flow and configure environment variables.
  </Card>

  <Card title="Update Your Crew" icon="arrows-rotate" href="/platform/en/guides/update-crew">
    Update environment variables and push changes to a running deployment.
  </Card>
</CardGroup>


# React Component Export
Source: https://docs-platform.crewai.com/platform/en/guides/react-component-export

Learn how to export and integrate CrewAI AMP React components into your applications

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 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/](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 theme={null}
      npx create-react-app my-crew-app
      ```
    * Change into the project directory:

      ```bash theme={null}
      cd my-crew-app
      ```
  </Step>

  <Step title="Install necessary dependencies">
    ```bash theme={null}
    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 theme={null}
    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 theme={null}
      npm start
      ```
    * This will start the development server, and your default web browser should open automatically to [http://localhost:3000](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 alt="Customise React Component" />
</Frame>

<Frame>
  <img 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


# Salesforce Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/salesforce-trigger

Trigger CrewAI crews from Salesforce workflows for CRM automation

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 title="CrewAI + Salesforce trigger demo" />

## Getting Started

To set up Salesforce triggers:

1. **Contact Support**: Reach out to CrewAI AMP support for assistance with Salesforce trigger setup
2. **Review Requirements**: Ensure you have the necessary Salesforce permissions and API access
3. **Configure Connection**: Work with the support team to establish the connection between CrewAI and your Salesforce instance
4. **Test Triggers**: Verify the triggers work correctly with your specific use cases

## Use Cases

Common Salesforce + CrewAI trigger scenarios include:

* **Lead Processing**: Automatically analyze and score incoming leads
* **Proposal Generation**: Create customized proposals based on opportunity data
* **Customer Insights**: Generate analysis reports from customer interaction history
* **Follow-up Automation**: Create personalized follow-up messages and recommendations

## Next Steps

For detailed setup instructions and advanced configuration options, please contact CrewAI AMP support who can provide tailored guidance for your specific Salesforce environment and business needs.


# Slack Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/slack-trigger

Trigger CrewAI crews directly from Slack using slash commands

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 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 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 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 alt="Kickoff crew" />
      </Frame>
    * The crew will start executing and you will see the results in the Slack channel.
      <Frame>
        <img 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.


# Team Management
Source: https://docs-platform.crewai.com/platform/en/guides/team-management

Learn how to invite and manage team members in your CrewAI AMP organization

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


# Tool Repository
Source: https://docs-platform.crewai.com/platform/en/guides/tool-repository

Using the Tool Repository to manage your tools

## 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](https://docs.crewai.com/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 theme={null}
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 theme={null}
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 theme={null}
crewai tool install my-tool
```

And now you want to add another package to your project, you can use the following command:

```bash theme={null}
crewai uv add requests
```

Other commands like `uv sync` or `uv remove` can also be used with the `crewai uv` command:

```bash theme={null}
crewai uv sync
```

```bash theme={null}
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 theme={null}
crewai tool create <tool-name>
```

This generates a scaffolded tool project locally.

After making changes, initialize a Git repository and commit the code:

```bash theme={null}
git init
git add .
git commit -m "Initial version"
```

To publish the tool:

```bash theme={null}
crewai tool publish
```

By default, tools are published as private. To make a tool public:

```bash theme={null}
crewai tool publish --public
```

For more details on how to build tools, see [Creating your own tools](https://docs.crewai.com/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 theme={null}
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>


# Update Crew
Source: https://docs-platform.crewai.com/platform/en/guides/update-crew

Updating a Crew on CrewAI AMP

<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>
  <img alt="Re-deploy Button" />
</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>
  <img alt="Reset Token" />
</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>
  <img alt="Environment Variables Button" />
</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>
  <img alt="Update Environment Variables" />
</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>


# Vertex AI with Workload Identity
Source: https://docs-platform.crewai.com/platform/en/guides/vertex-ai-workload-identity-setup

Connect Google Vertex AI to CrewAI AMP with no service account keys — credentials are minted per-execution via OIDC workload identity federation.

<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 theme={null}
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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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 theme={null}
    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](/platform/en/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)](/platform/en/features/sso) — Authentication for the AMP UI and CLI (separate system from LLM workload identity)
* [Azure OpenAI Setup](/platform/en/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


# Webhook Automation
Source: https://docs-platform.crewai.com/platform/en/guides/webhook-automation

Automate CrewAI AMP workflows using webhooks with platforms like ActivePieces, Zapier, and Make.com

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 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 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 alt="ActivePieces Headers" />
         </Frame>

       * In the body, include the JSON content as configured in step 2
         <Frame>
           <img 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 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 alt="ActivePieces Webhook" />
         </Frame>

       * Configure the email to use crew webhook body text
         <Frame>
           <img 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 theme={null}
    {
        "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 theme={null}
    {
        "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 theme={null}
    {
        "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>


# Zapier Trigger
Source: https://docs-platform.crewai.com/platform/en/guides/zapier-trigger

Trigger CrewAI crews from Zapier workflows to automate cross-app workflows

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 alt="Zapier 1" />
    </Frame>
  </Step>

  <Step title="Choose Slack as your trigger app">
    <Frame>
      <img 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 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 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 alt="Zapier 8" />
    </Frame>

    <Frame>
      <img 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 alt="Zapier 7" />
    </Frame>
  </Step>

  <Step title="Kick Off the crew from Slack">
    * Enter the text in your Slack channel

    <Frame>
      <img alt="Zapier 10" />
    </Frame>

    * Select the 3 ellipsis button and then chose Push to Zapier

    <Frame>
      <img alt="Zapier 11" />
    </Frame>
  </Step>

  <Step title="Select the crew and then Push to Kick Off">
    <Frame>
      <img 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.


# Asana Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/asana

Team task and project coordination with Asana integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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()
```


# Box Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/box

File storage and document management with Box integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      {
        "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](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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
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 theme={null}
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 theme={null}
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()
```


# ClickUp Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/clickup

Task and productivity management with ClickUp integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      {
        "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 theme={null}
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 theme={null}

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 theme={null}
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 theme={null}
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>


# Databricks Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/databricks

Connect CrewAI agents to Databricks Genie, SQL, Unity Catalog Functions, and Vector Search through Databricks managed MCP servers.

## 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](/platform/en/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>
  <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 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>
  <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="/platform/en/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>


# GitHub Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/github

Repository and issue management with GitHub integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      {
        "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 theme={null}
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 theme={null}

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 theme={null}
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 theme={null}
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>


# Gmail Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/gmail

Email and contact management with Gmail integration for CrewAI.

## 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 theme={null}
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 theme={null}
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](mailto: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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Google Calendar Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/google_calendar

Event and schedule management with Google Calendar integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      [
        {
          "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 theme={null}
      [
        {
          "email": "attendee@example.com",
          "displayName": "Attendee Name",
          "optional": false
        }
      ]
      ```
    * `reminders` (object, optional): Information about the event's reminders.
      ```json theme={null}
      {
        "useDefault": true,
        "overrides": [
          {
            "method": "email",
            "minutes": 15
          }
        ]
      }
      ```
    * `conferenceData` (object, optional): The conference-related information, such as details of a Google Meet conference.
      ```json theme={null}
      {
        "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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Google Contacts Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/google_contacts

Contact and directory management with Google Contacts integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      [
        {
          "givenName": "John",
          "familyName": "Doe",
          "displayName": "John Doe"
        }
      ]
      ```
    * `emailAddresses` (array, optional): Email addresses
      ```json theme={null}
      [
        {
          "value": "john.doe@example.com",
          "type": "work"
        }
      ]
      ```
    * `phoneNumbers` (array, optional): Phone numbers
      ```json theme={null}
      [
        {
          "value": "+1234567890",
          "type": "mobile"
        }
      ]
      ```
    * `addresses` (array, optional): Postal addresses
      ```json theme={null}
      [
        {
          "formattedValue": "123 Main St, City, State 12345",
          "type": "home"
        }
      ]
      ```
    * `organizations` (array, optional): Organizations/companies
      ```json theme={null}
      [
        {
          "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 theme={null}
      [
        {
          "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 theme={null}
      [
        {
          "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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Google Docs Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/google_docs

Document creation and editing with Google Docs integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Google Drive Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/google_drive

File storage and management with Google Drive integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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()
```


# Google Sheets Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/google_sheets

Spreadsheet data synchronization with Google Sheets integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      [
        ["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 theme={null}
      [
        ["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 theme={null}
      [
        {
          "properties": {
            "title": "Sheet1"
          }
        }
      ]
      ```
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Google Sheets Agent Setup

```python theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Google Slides Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/google_slides

Presentation creation and management with Google Slides integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      [
        {
          "insertText": {
            "objectId": "slide_id",
            "text": "Your text content here"
          }
        }
      ]
      ```
    * `writeControl` (object, optional): Provides control over how write requests are executed.
      ```json theme={null}
      {
        "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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# HubSpot Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/hubspot

Manage companies and contacts in HubSpot with CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Jira Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/jira

Issue tracking and project management with Jira integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
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 theme={null}

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 theme={null}
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 theme={null}
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 theme={null}
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>


# Linear Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/linear

Software project and bug tracking with Linear integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      [
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
      {
        "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 theme={null}
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 theme={null}

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 theme={null}
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 theme={null}
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 theme={null}
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>


# Microsoft Excel Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/microsoft_excel

Workbook and data management with Microsoft Excel integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      [
        {
          "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 theme={null}
      [
        ["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 theme={null}
      ["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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Microsoft OneDrive Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/microsoft_onedrive

File and folder management with Microsoft OneDrive integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Microsoft Outlook Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/microsoft_outlook

Email, calendar, and contact management with Microsoft Outlook integration for CrewAI.

## 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 theme={null}
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 theme={null}
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](mailto:john@example.com)", "[jane@example.com](mailto: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 theme={null}
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 theme={null}
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 theme={null}
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>


# Microsoft SharePoint Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/microsoft_sharepoint

Site, list, and document management with Microsoft SharePoint integration for CrewAI.

## 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 theme={null}
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 theme={null}
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 theme={null}
      {
        "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 theme={null}
      {
        "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](mailto: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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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>


# Microsoft Teams Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/microsoft_teams

Team collaboration and communication with Microsoft Teams integration for CrewAI.

## Overview

Enable your agents to access Teams data, send messages, create meetings, and manage channels. Automate team communication, schedule meetings, retrieve messages, and streamline your collaboration workflows with AI-powered automation.

## Prerequisites

Before using the Microsoft Teams integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Microsoft account with Teams access
* Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors)

## Setting Up Microsoft Teams Integration

### 1. Connect Your Microsoft Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Microsoft Teams** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for Teams access
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Actions

<AccordionGroup>
  <Accordion title="microsoft_teams/get_teams">
    **Description:** Get all teams the user is a member of.

    **Parameters:**

    * No parameters required.
  </Accordion>

  <Accordion title="microsoft_teams/get_channels">
    **Description:** Get channels in a specific team.

    **Parameters:**

    * `team_id` (string, required): The ID of the team.
  </Accordion>

  <Accordion title="microsoft_teams/send_message">
    **Description:** Send a message to a Teams channel.

    **Parameters:**

    * `team_id` (string, required): The ID of the team.
    * `channel_id` (string, required): The ID of the channel.
    * `message` (string, required): The message content.
    * `content_type` (string, optional): Content type (html or text). Enum: `html`, `text`. Default is `text`.
  </Accordion>

  <Accordion title="microsoft_teams/get_messages">
    **Description:** Get messages from a Teams channel.

    **Parameters:**

    * `team_id` (string, required): The ID of the team.
    * `channel_id` (string, required): The ID of the channel.
    * `top` (integer, optional): Number of messages to retrieve (max 50). Default is `20`.
  </Accordion>

  <Accordion title="microsoft_teams/create_meeting">
    **Description:** Create a Teams meeting.

    **Parameters:**

    * `subject` (string, required): Meeting subject/title.
    * `startDateTime` (string, required): Meeting start time (ISO 8601 format with timezone).
    * `endDateTime` (string, required): Meeting end time (ISO 8601 format with timezone).
  </Accordion>

  <Accordion title="microsoft_teams/search_online_meetings_by_join_url">
    **Description:** Search online meetings by Join Web URL.

    **Parameters:**

    * `join_web_url` (string, required): The join web URL of the meeting to search for.
  </Accordion>

  <Accordion title="microsoft_teams/search_online_meetings_by_meeting_id">
    **Description:** Search online meetings by external Meeting ID.

    **Parameters:**

    * `join_meeting_id` (string, required): The meeting ID (numeric code) that attendees use to join. This is the joinMeetingId shown in meeting invitations, not the Graph API meeting id.
  </Accordion>

  <Accordion title="microsoft_teams/get_meeting">
    **Description:** Get details of a specific online meeting.

    **Parameters:**

    * `meeting_id` (string, required): The Graph API meeting ID (a long alphanumeric string). Obtain from create\_meeting or search\_online\_meetings actions. Different from the numeric joinMeetingId.
  </Accordion>

  <Accordion title="microsoft_teams/get_team_members">
    **Description:** Get members of a specific team.

    **Parameters:**

    * `team_id` (string, required): The unique identifier of the team. Obtain from get\_teams action.
    * `top` (integer, optional): Maximum number of members to retrieve per page (1-999). Default is `100`.
    * `skip_token` (string, optional): Pagination token from a previous response. When the response includes @odata.nextLink, extract the \$skiptoken parameter value and pass it here to get the next page of results.
  </Accordion>

  <Accordion title="microsoft_teams/create_channel">
    **Description:** Create a new channel in a team.

    **Parameters:**

    * `team_id` (string, required): The unique identifier of the team. Obtain from get\_teams action.
    * `display_name` (string, required): Name of the channel as displayed in Teams. Must be unique within the team. Max 50 characters.
    * `description` (string, optional): Optional description explaining the channel's purpose. Visible in channel details. Max 1024 characters.
    * `membership_type` (string, optional): Channel visibility. Enum: `standard`, `private`. "standard" = visible to all team members, "private" = visible only to specifically added members. Default is `standard`.
  </Accordion>

  <Accordion title="microsoft_teams/get_message_replies">
    **Description:** Get replies to a specific message in a channel.

    **Parameters:**

    * `team_id` (string, required): The unique identifier of the team. Obtain from get\_teams action.
    * `channel_id` (string, required): The unique identifier of the channel. Obtain from get\_channels action.
    * `message_id` (string, required): The unique identifier of the parent message. Obtain from get\_messages action.
    * `top` (integer, optional): Maximum number of replies to retrieve per page (1-50). Default is `50`.
    * `skip_token` (string, optional): Pagination token from a previous response. When the response includes @odata.nextLink, extract the \$skiptoken parameter value and pass it here to get the next page of results.
  </Accordion>

  <Accordion title="microsoft_teams/reply_to_message">
    **Description:** Reply to a message in a Teams channel.

    **Parameters:**

    * `team_id` (string, required): The unique identifier of the team. Obtain from get\_teams action.
    * `channel_id` (string, required): The unique identifier of the channel. Obtain from get\_channels action.
    * `message_id` (string, required): The unique identifier of the message to reply to. Obtain from get\_messages action.
    * `message` (string, required): The reply content. For HTML, include formatting tags. For text, plain text only.
    * `content_type` (string, optional): Content format. Enum: `html`, `text`. "text" for plain text, "html" for rich text with formatting. Default is `text`.
  </Accordion>

  <Accordion title="microsoft_teams/update_meeting">
    **Description:** Update an existing online meeting.

    **Parameters:**

    * `meeting_id` (string, required): The unique identifier of the meeting. Obtain from create\_meeting or search\_online\_meetings actions.
    * `subject` (string, optional): New meeting title.
    * `startDateTime` (string, optional): New start time in ISO 8601 format with timezone. Example: "2024-01-20T10:00:00-08:00".
    * `endDateTime` (string, optional): New end time in ISO 8601 format with timezone.
  </Accordion>

  <Accordion title="microsoft_teams/delete_meeting">
    **Description:** Delete an online meeting.

    **Parameters:**

    * `meeting_id` (string, required): The unique identifier of the meeting to delete. Obtain from create\_meeting or search\_online\_meetings actions.
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Microsoft Teams Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent with Microsoft Teams capabilities
teams_agent = Agent(
    role="Teams Coordinator",
    goal="Manage Teams communication and meetings efficiently",
    backstory="An AI assistant specialized in Microsoft Teams operations and team collaboration.",
    apps=['microsoft_teams']  # All Teams actions will be available
)

# Task to list teams and channels
explore_teams_task = Task(
    description="List all teams I'm a member of and then get the channels for the first team.",
    agent=teams_agent,
    expected_output="List of teams and channels displayed."
)

# Run the task
crew = Crew(
    agents=[teams_agent],
    tasks=[explore_teams_task]
)

crew.kickoff()
```

### Messaging and Communication

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent focused on messaging
messenger = Agent(
    role="Teams Messenger",
    goal="Send and retrieve messages in Teams channels",
    backstory="An AI assistant skilled in team communication and message management.",
    apps=['microsoft_teams/send_message', 'microsoft_teams/get_messages']
)

# Task to send a message and retrieve recent messages
messaging_task = Task(
    description="Send a message 'Hello team! This is an automated update from our AI assistant.' to the General channel of team 'your_team_id', then retrieve the last 10 messages from that channel.",
    agent=messenger,
    expected_output="Message sent successfully and recent messages retrieved."
)

crew = Crew(
    agents=[messenger],
    tasks=[messaging_task]
)

crew.kickoff()
```

### Meeting Management

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent for meeting management
meeting_scheduler = Agent(
    role="Meeting Scheduler",
    goal="Create and manage Teams meetings",
    backstory="An AI assistant that handles meeting scheduling and organization.",
    apps=['microsoft_teams/create_meeting', 'microsoft_teams/search_online_meetings_by_join_url']
)

# Task to create a meeting
schedule_meeting_task = Task(
    description="Create a Teams meeting titled 'Weekly Team Sync' scheduled for tomorrow at 10:00 AM lasting for 1 hour (use proper ISO 8601 format with timezone).",
    agent=meeting_scheduler,
    expected_output="Teams meeting created successfully with meeting details."
)

crew = Crew(
    agents=[meeting_scheduler],
    tasks=[schedule_meeting_task]
)

crew.kickoff()
```

## Troubleshooting

### Common Issues

**Authentication Errors**

* Ensure your Microsoft account has the necessary permissions for Teams access.
* Required scopes include: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `ChannelMessage.Read.All`, `OnlineMeetings.ReadWrite`, `OnlineMeetings.Read`.
* Verify that the OAuth connection includes all required scopes.

**Team and Channel Access**

* Ensure you are a member of the teams you're trying to access.
* Double-check team IDs and channel IDs for correctness.
* Team and channel IDs can be obtained using the `get_teams` and `get_channels` actions.

**Message Sending Issues**

* Ensure `team_id`, `channel_id`, and `message` are provided for `send_message`.
* Verify that you have permissions to send messages to the specified channel.
* Choose appropriate `content_type` (text or html) based on your message format.

**Meeting Creation**

* Ensure `subject`, `startDateTime`, and `endDateTime` are provided.
* Use proper ISO 8601 format with timezone for datetime fields (e.g., '2024-01-20T10:00:00-08:00').
* Verify that the meeting times are in the future.

**Message Retrieval Limitations**

* The `get_messages` action can retrieve a maximum of 50 messages per request.
* Messages are returned in reverse chronological order (newest first).

**Meeting Search**

* For `search_online_meetings_by_join_url`, ensure the join URL is exact and properly formatted.
* The URL should be the complete Teams meeting join URL.

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Microsoft Teams integration setup
  or troubleshooting.
</Card>


# Microsoft Word Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/microsoft_word

Document creation and management with Microsoft Word integration for CrewAI.

## Overview

Enable your agents to create, read, and manage Word documents and text files in OneDrive or SharePoint. Automate document creation, retrieve content, manage document properties, and streamline your document workflows with AI-powered automation.

## Prerequisites

Before using the Microsoft Word integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Microsoft account with Word and OneDrive/SharePoint access
* Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors)

## Setting Up Microsoft Word Integration

### 1. Connect Your Microsoft Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Microsoft Word** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for file access
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Actions

<AccordionGroup>
  <Accordion title="microsoft_word/get_documents">
    **Description:** Get all Word documents from OneDrive or SharePoint.

    **Parameters:**

    * `select` (string, optional): Select specific properties to return.
    * `filter` (string, optional): Filter results using OData syntax.
    * `expand` (string, optional): Expand related resources inline.
    * `top` (integer, optional): Number of items to return (min 1, max 999).
    * `orderby` (string, optional): Order results by specified properties.
  </Accordion>

  <Accordion title="microsoft_word/create_text_document">
    **Description:** Create a text document (.txt) with content. RECOMMENDED for programmatic content creation that needs to be readable and editable.

    **Parameters:**

    * `file_name` (string, required): Name of the text document (should end with .txt).
    * `content` (string, optional): Text content for the document. Default is "This is a new text document created via API."
  </Accordion>

  <Accordion title="microsoft_word/get_document_content">
    **Description:** Get the content of a document (works best with text files).

    **Parameters:**

    * `file_id` (string, required): The ID of the document.
  </Accordion>

  <Accordion title="microsoft_word/get_document_properties">
    **Description:** Get properties and metadata of a document.

    **Parameters:**

    * `file_id` (string, required): The ID of the document.
  </Accordion>

  <Accordion title="microsoft_word/delete_document">
    **Description:** Delete a document.

    **Parameters:**

    * `file_id` (string, required): The ID of the document to delete.
  </Accordion>

  <Accordion title="microsoft_word/copy_document">
    **Description:** Copy a document to a new location in OneDrive.

    **Parameters:**

    * `file_id` (string, required): The ID of the document to copy
    * `name` (string, optional): New name for the copied document
    * `parent_id` (string, optional): The ID of the destination folder (defaults to root)
  </Accordion>

  <Accordion title="microsoft_word/move_document">
    **Description:** Move a document to a new location in OneDrive.

    **Parameters:**

    * `file_id` (string, required): The ID of the document to move
    * `parent_id` (string, required): The ID of the destination folder
    * `name` (string, optional): New name for the moved document
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Microsoft Word Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent with Microsoft Word capabilities
word_agent = Agent(
    role="Document Manager",
    goal="Manage Word documents and text files efficiently",
    backstory="An AI assistant specialized in Microsoft Word document operations and content management.",
    apps=['microsoft_word']  # All Word actions will be available
)

# Task to create a new text document
create_doc_task = Task(
    description="Create a new text document named 'meeting_notes.txt' with content 'Meeting Notes from January 2024: Key discussion points and action items.'",
    agent=word_agent,
    expected_output="New text document 'meeting_notes.txt' created successfully."
)

# Run the task
crew = Crew(
    agents=[word_agent],
    tasks=[create_doc_task]
)

crew.kickoff()
```

### Reading and Managing Documents

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent focused on document operations
document_reader = Agent(
    role="Document Reader",
    goal="Retrieve and analyze document content and properties",
    backstory="An AI assistant skilled in reading and analyzing document content.",
    apps=['microsoft_word/get_documents', 'microsoft_word/get_document_content', 'microsoft_word/get_document_properties']
)

# Task to list and read documents
read_docs_task = Task(
    description="List all Word documents in my OneDrive, then get the content and properties of the first document found.",
    agent=document_reader,
    expected_output="List of documents with content and properties of the first document."
)

crew = Crew(
    agents=[document_reader],
    tasks=[read_docs_task]
)

crew.kickoff()
```

### Document Cleanup and Organization

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent for document management
document_organizer = Agent(
    role="Document Organizer",
    goal="Organize and clean up document collections",
    backstory="An AI assistant that helps maintain organized document libraries.",
    apps=['microsoft_word/get_documents', 'microsoft_word/get_document_properties', 'microsoft_word/delete_document']
)

# Task to organize documents
organize_task = Task(
    description="List all documents, check their properties, and identify any documents that might be duplicates or outdated for potential cleanup.",
    agent=document_organizer,
    expected_output="Analysis of document library with recommendations for organization."
)

crew = Crew(
    agents=[document_organizer],
    tasks=[organize_task]
)

crew.kickoff()
```

## Troubleshooting

### Common Issues

**Authentication Errors**

* Ensure your Microsoft account has the necessary permissions for file access (e.g., `Files.Read.All`, `Files.ReadWrite.All`).
* Verify that the OAuth connection includes all required scopes.

**File Creation Issues**

* When creating text documents, ensure the `file_name` ends with `.txt` extension.
* Verify that you have write permissions to the target location (OneDrive/SharePoint).

**Document Access Issues**

* Double-check document IDs for correctness when accessing specific documents.
* Ensure the referenced documents exist and are accessible.
* Note that this integration works best with text files (.txt) for content operations.

**Content Retrieval Limitations**

* The `get_document_content` action works best with text files (.txt).
* For complex Word documents (.docx), consider using the document properties action to get metadata.

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Microsoft Word integration setup
  or troubleshooting.
</Card>


# Notion Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/notion

User management and commenting with Notion integration for CrewAI.

## Overview

Enable your agents to manage users and create comments through Notion. Access workspace user information and create comments on pages and discussions, streamlining your collaboration workflows with AI-powered automation.

## Prerequisites

Before using the Notion integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Notion account with appropriate workspace permissions
* Connected your Notion account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors)

## Setting Up Notion Integration

### 1. Connect Your Notion Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Notion** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for user access and comment creation
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Actions

<AccordionGroup>
  <Accordion title="notion/list_users">
    **Description:** List all users in the workspace.

    **Parameters:**

    * `page_size` (integer, optional): Number of items returned in the response. Minimum: 1, Maximum: 100, Default: 100
    * `start_cursor` (string, optional): Cursor for pagination. Return results after this cursor.
  </Accordion>

  <Accordion title="notion/get_user">
    **Description:** Retrieve a specific user by ID.

    **Parameters:**

    * `user_id` (string, required): The ID of the user to retrieve.
  </Accordion>

  <Accordion title="notion/create_comment">
    **Description:** Create a comment on a page or discussion.

    **Parameters:**

    * `parent` (object, required): The parent page or discussion to comment on.
      ```json theme={null}
      {
        "type": "page_id",
        "page_id": "PAGE_ID_HERE"
      }
      ```
      or
      ```json theme={null}
      {
        "type": "discussion_id",
        "discussion_id": "DISCUSSION_ID_HERE"
      }
      ```
    * `rich_text` (array, required): The rich text content of the comment.
      ```json theme={null}
      [
        {
          "type": "text",
          "text": {
            "content": "This is my comment text"
          }
        }
      ]
      ```
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Notion Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent with Notion capabilities
notion_agent = Agent(
    role="Workspace Manager",
    goal="Manage workspace users and facilitate collaboration through comments",
    backstory="An AI assistant specialized in user management and team collaboration.",
    apps=['notion']  # All Notion actions will be available
)

# Task to list workspace users
user_management_task = Task(
    description="List all users in the workspace and provide a summary of team members",
    agent=notion_agent,
    expected_output="Complete list of workspace users with their details"
)

# Run the task
crew = Crew(
    agents=[notion_agent],
    tasks=[user_management_task]
)

crew.kickoff()
```

### Filtering Specific Notion Tools

```python theme={null}
comment_manager = Agent(
    role="Comment Manager",
    goal="Create and manage comments on Notion pages",
    backstory="An AI assistant that focuses on facilitating discussions through comments.",
    apps=['notion/create_comment']
)

# Task to create comments on pages
comment_task = Task(
    description="Create a summary comment on the project status page with key updates",
    agent=comment_manager,
    expected_output="Comment created successfully with project status updates"
)

crew = Crew(
    agents=[comment_manager],
    tasks=[comment_task]
)

crew.kickoff()
```

### User Information and Team Management

```python theme={null}
from crewai import Agent, Task, Crew

team_coordinator = Agent(
    role="Team Coordinator",
    goal="Coordinate team activities and manage user information",
    backstory="An AI assistant that helps coordinate team activities and manages user information.",
    apps=['notion']
)

# Task to coordinate team activities
coordination_task = Task(
    description="""
    1. List all users in the workspace
    2. Get detailed information for specific team members
    3. Create comments on relevant pages to notify team members about updates
    """,
    agent=team_coordinator,
    expected_output="Team coordination completed with user information gathered and notifications sent"
)

crew = Crew(
    agents=[team_coordinator],
    tasks=[coordination_task]
)

crew.kickoff()
```

### Collaboration and Communication

```python theme={null}
from crewai import Agent, Task, Crew

collaboration_facilitator = Agent(
    role="Collaboration Facilitator",
    goal="Facilitate team collaboration through comments and user management",
    backstory="An AI assistant that specializes in team collaboration and communication.",
    apps=['notion']
)

# Task to facilitate collaboration
collaboration_task = Task(
    description="""
    1. Identify active users in the workspace
    2. Create contextual comments on project pages to facilitate discussions
    3. Provide status updates and feedback through comments
    """,
    agent=collaboration_facilitator,
    expected_output="Collaboration facilitated with comments created and team members notified"
)

crew = Crew(
    agents=[collaboration_facilitator],
    tasks=[collaboration_task]
)

crew.kickoff()
```

### Automated Team Communication

```python theme={null}
from crewai import Agent, Task, Crew

communication_automator = Agent(
    role="Communication Automator",
    goal="Automate team communication and user management workflows",
    backstory="An AI assistant that automates communication workflows and manages user interactions.",
    apps=['notion']
)

# Complex communication automation task
automation_task = Task(
    description="""
    1. List all workspace users and identify team roles
    2. Get specific user information for project stakeholders
    3. Create automated status update comments on key project pages
    4. Facilitate team communication through targeted comments
    """,
    agent=communication_automator,
    expected_output="Automated communication workflow completed with user management and comments"
)

crew = Crew(
    agents=[communication_automator],
    tasks=[automation_task]
)

crew.kickoff()
```

## Troubleshooting

### Common Issues

**Permission Errors**

* Ensure your Notion account has appropriate permissions to read user information
* Verify that the OAuth connection includes required scopes for user access and comment creation
* Check that you have permissions to comment on the target pages or discussions

**User Access Issues**

* Ensure you have workspace admin permissions to list all users
* Verify that user IDs are correct and users exist in the workspace
* Check that the workspace allows API access to user information

**Comment Creation Issues**

* Verify that page IDs or discussion IDs are correct and accessible
* Ensure that rich text content follows Notion's API format specifications
* Check that you have comment permissions on the target pages or discussions

**API Rate Limits**

* Be mindful of Notion's API rate limits when making multiple requests
* Implement appropriate delays between requests if needed
* Consider pagination for large user lists

**Parent Object Specification**

* Ensure parent object type is correctly specified (page\_id or discussion\_id)
* Verify that the parent page or discussion exists and is accessible
* Check that the parent object ID format is correct

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Notion integration setup or
  troubleshooting.
</Card>


# Salesforce Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/salesforce

CRM and sales automation with Salesforce integration for CrewAI.

## Overview

Enable your agents to manage customer relationships, sales processes, and data through Salesforce. Create and update records, manage leads and opportunities, execute SOQL queries, and streamline your CRM workflows with AI-powered automation.

## Prerequisites

Before using the Salesforce integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Salesforce account with appropriate permissions
* Connected your Salesforce account through the [Integrations page](https://app.crewai.com/integrations)

<Note>
  Salesforce requires a **one-time admin install** of the CrewAI package in
  your org before any user can connect. This is a Salesforce platform
  requirement for all ExternalClientApp-based integrations as of the Spring
  '26 release — not a CrewAI-specific step. The Connect Salesforce flow in
  CrewAI AMP walks you through it the first time.
</Note>

## Setting Up Salesforce Integration

### 1. Connect Your Salesforce Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/unified_tools).
2. Find **Salesforce** in the Authentication Integrations section.
3. Click **Connect**.

What happens next depends on whether a Salesforce admin in your org has
already installed the CrewAI package:

* **Package already installed:** you're taken straight to the Salesforce
  OAuth consent screen — approve it and you're connected.
* **Package not installed yet:** you'll see an **Install CrewAI in
  Salesforce** page. Follow the one-time install steps below, then come
  back to CrewAI AMP and click **Connect** again.

4. Grant the necessary permissions for CRM and sales management.
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations).

#### One-time admin install (Salesforce admin only)

The first time anyone in your org clicks **Connect Salesforce**, CrewAI
redirects them to an install page that points at the CrewAI managed package.
A Salesforce admin needs to install it once for the whole org.

1. On the install page in CrewAI, click **Install in Salesforce**. (You can
   also share the page URL with your admin — the install link works for
   anyone who opens it.)
2. Sign in to Salesforce as an admin. For sandboxes, swap `login.salesforce.com`
   for `test.salesforce.com` in the URL before opening it.
3. Choose **Install for All Users**, acknowledge the third-party app prompt,
   and click **Install**.
4. In Salesforce Setup, search **External Client App Manager** → **CrewAI
   App** → open the **Policies** tab → **Edit** and set:
   * **Permitted Users:** All users may self-authorize
   * **IP Relaxation:** Relax IP restrictions
   * **Refresh Token Policy:** Refresh token is valid until revoked
5. Save.
6. Return to CrewAI AMP and click **Connect Salesforce** again. OAuth will
   complete this time.

<Note>
  **Not a Salesforce admin?** Forward the install page URL (or the install
  link itself) to your Salesforce admin and ask them to complete the steps
  above. Once they're done, return to CrewAI AMP and click **Connect** again.
</Note>

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Tools

### **Record Management**

<AccordionGroup>
  <Accordion title="salesforce/create_record_contact">
    **Description:** Create a new Contact record in Salesforce.

    **Parameters:**

    * `FirstName` (string, optional): First Name
    * `LastName` (string, required): Last Name - This field is required
    * `accountId` (string, optional): Account ID - The Account that the Contact belongs to
    * `Email` (string, optional): Email address
    * `Title` (string, optional): Title of the contact, such as CEO or Vice President
    * `Description` (string, optional): A description of the Contact
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Contact fields
  </Accordion>

  <Accordion title="salesforce/create_record_lead">
    **Description:** Create a new Lead record in Salesforce.

    **Parameters:**

    * `FirstName` (string, optional): First Name
    * `LastName` (string, required): Last Name - This field is required
    * `Company` (string, required): Company - This field is required
    * `Email` (string, optional): Email address
    * `Phone` (string, optional): Phone number
    * `Website` (string, optional): Website URL
    * `Title` (string, optional): Title of the contact, such as CEO or Vice President
    * `Status` (string, optional): Lead Status - Use Connect Portal Workflow Settings to select Lead Status
    * `Description` (string, optional): A description of the Lead
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Lead fields
  </Accordion>

  <Accordion title="salesforce/create_record_opportunity">
    **Description:** Create a new Opportunity record in Salesforce.

    **Parameters:**

    * `Name` (string, required): The Opportunity name - This field is required
    * `StageName` (string, optional): Opportunity Stage - Use Connect Portal Workflow Settings to select stage
    * `CloseDate` (string, optional): Close Date in YYYY-MM-DD format - Defaults to 30 days from current date
    * `AccountId` (string, optional): The Account that the Opportunity belongs to
    * `Amount` (string, optional): Estimated total sale amount
    * `Description` (string, optional): A description of the Opportunity
    * `OwnerId` (string, optional): The Salesforce user assigned to work on this Opportunity
    * `NextStep` (string, optional): Description of next task in closing Opportunity
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Opportunity fields
  </Accordion>

  <Accordion title="salesforce/create_record_task">
    **Description:** Create a new Task record in Salesforce.

    **Parameters:**

    * `whatId` (string, optional): Related to ID - The ID of the Account or Opportunity this Task is related to
    * `whoId` (string, optional): Name ID - The ID of the Contact or Lead this Task is related to
    * `subject` (string, required): Subject of the task
    * `activityDate` (string, optional): Activity Date in YYYY-MM-DD format
    * `description` (string, optional): A description of the Task
    * `taskSubtype` (string, required): Task Subtype - Options: task, email, listEmail, call
    * `Status` (string, optional): Status - Options: Not Started, In Progress, Completed
    * `ownerId` (string, optional): Assigned To ID - The Salesforce user assigned to this Task
    * `callDurationInSeconds` (string, optional): Call Duration in seconds
    * `isReminderSet` (boolean, optional): Whether reminder is set
    * `reminderDateTime` (string, optional): Reminder Date/Time in ISO format
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Task fields
  </Accordion>

  <Accordion title="salesforce/create_record_account">
    **Description:** Create a new Account record in Salesforce.

    **Parameters:**

    * `Name` (string, required): The Account name - This field is required
    * `OwnerId` (string, optional): The Salesforce user assigned to this Account
    * `Website` (string, optional): Website URL
    * `Phone` (string, optional): Phone number
    * `Description` (string, optional): Account description
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Account fields
  </Accordion>

  <Accordion title="salesforce/create_record_any">
    **Description:** Create a record of any object type in Salesforce.

    **Note:** This is a flexible tool for creating records of custom or unknown object types.
  </Accordion>
</AccordionGroup>

### **Record Updates**

<AccordionGroup>
  <Accordion title="salesforce/update_record_contact">
    **Description:** Update an existing Contact record in Salesforce.

    **Parameters:**

    * `recordId` (string, required): The ID of the record to update
    * `FirstName` (string, optional): First Name
    * `LastName` (string, optional): Last Name
    * `accountId` (string, optional): Account ID - The Account that the Contact belongs to
    * `Email` (string, optional): Email address
    * `Title` (string, optional): Title of the contact
    * `Description` (string, optional): A description of the Contact
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Contact fields
  </Accordion>

  <Accordion title="salesforce/update_record_lead">
    **Description:** Update an existing Lead record in Salesforce.

    **Parameters:**

    * `recordId` (string, required): The ID of the record to update
    * `FirstName` (string, optional): First Name
    * `LastName` (string, optional): Last Name
    * `Company` (string, optional): Company name
    * `Email` (string, optional): Email address
    * `Phone` (string, optional): Phone number
    * `Website` (string, optional): Website URL
    * `Title` (string, optional): Title of the contact
    * `Status` (string, optional): Lead Status
    * `Description` (string, optional): A description of the Lead
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Lead fields
  </Accordion>

  <Accordion title="salesforce/update_record_opportunity">
    **Description:** Update an existing Opportunity record in Salesforce.

    **Parameters:**

    * `recordId` (string, required): The ID of the record to update
    * `Name` (string, optional): The Opportunity name
    * `StageName` (string, optional): Opportunity Stage
    * `CloseDate` (string, optional): Close Date in YYYY-MM-DD format
    * `AccountId` (string, optional): The Account that the Opportunity belongs to
    * `Amount` (string, optional): Estimated total sale amount
    * `Description` (string, optional): A description of the Opportunity
    * `OwnerId` (string, optional): The Salesforce user assigned to work on this Opportunity
    * `NextStep` (string, optional): Description of next task in closing Opportunity
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Opportunity fields
  </Accordion>

  <Accordion title="salesforce/update_record_task">
    **Description:** Update an existing Task record in Salesforce.

    **Parameters:**

    * `recordId` (string, required): The ID of the record to update
    * `whatId` (string, optional): Related to ID - The ID of the Account or Opportunity this Task is related to
    * `whoId` (string, optional): Name ID - The ID of the Contact or Lead this Task is related to
    * `subject` (string, optional): Subject of the task
    * `activityDate` (string, optional): Activity Date in YYYY-MM-DD format
    * `description` (string, optional): A description of the Task
    * `Status` (string, optional): Status - Options: Not Started, In Progress, Completed
    * `ownerId` (string, optional): Assigned To ID - The Salesforce user assigned to this Task
    * `callDurationInSeconds` (string, optional): Call Duration in seconds
    * `isReminderSet` (boolean, optional): Whether reminder is set
    * `reminderDateTime` (string, optional): Reminder Date/Time in ISO format
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Task fields
  </Accordion>

  <Accordion title="salesforce/update_record_account">
    **Description:** Update an existing Account record in Salesforce.

    **Parameters:**

    * `recordId` (string, required): The ID of the record to update
    * `Name` (string, optional): The Account name
    * `OwnerId` (string, optional): The Salesforce user assigned to this Account
    * `Website` (string, optional): Website URL
    * `Phone` (string, optional): Phone number
    * `Description` (string, optional): Account description
    * `additionalFields` (object, optional): Additional fields in JSON format for custom Account fields
  </Accordion>

  <Accordion title="salesforce/update_record_any">
    **Description:** Update a record of any object type in Salesforce.

    **Note:** This is a flexible tool for updating records of custom or unknown object types.
  </Accordion>
</AccordionGroup>

### **Record Retrieval**

<AccordionGroup>
  <Accordion title="salesforce/get_record_by_id_contact">
    **Description:** Get a Contact record by its ID.

    **Parameters:**

    * `recordId` (string, required): Record ID of the Contact
  </Accordion>

  <Accordion title="salesforce/get_record_by_id_lead">
    **Description:** Get a Lead record by its ID.

    **Parameters:**

    * `recordId` (string, required): Record ID of the Lead
  </Accordion>

  <Accordion title="salesforce/get_record_by_id_opportunity">
    **Description:** Get an Opportunity record by its ID.

    **Parameters:**

    * `recordId` (string, required): Record ID of the Opportunity
  </Accordion>

  <Accordion title="salesforce/get_record_by_id_task">
    **Description:** Get a Task record by its ID.

    **Parameters:**

    * `recordId` (string, required): Record ID of the Task
  </Accordion>

  <Accordion title="salesforce/get_record_by_id_account">
    **Description:** Get an Account record by its ID.

    **Parameters:**

    * `recordId` (string, required): Record ID of the Account
  </Accordion>

  <Accordion title="salesforce/get_record_by_id_any">
    **Description:** Get a record of any object type by its ID.

    **Parameters:**

    * `recordType` (string, required): Record Type (e.g., "CustomObject\_\_c")
    * `recordId` (string, required): Record ID
  </Accordion>
</AccordionGroup>

### **Record Search**

<AccordionGroup>
  <Accordion title="salesforce/search_records_contact">
    **Description:** Search for Contact records with advanced filtering.

    **Parameters:**

    * `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators
    * `sortBy` (string, optional): Sort field (e.g., "CreatedDate")
    * `sortDirection` (string, optional): Sort direction - Options: ASC, DESC
    * `includeAllFields` (boolean, optional): Include all fields in results
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/search_records_lead">
    **Description:** Search for Lead records with advanced filtering.

    **Parameters:**

    * `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators
    * `sortBy` (string, optional): Sort field (e.g., "CreatedDate")
    * `sortDirection` (string, optional): Sort direction - Options: ASC, DESC
    * `includeAllFields` (boolean, optional): Include all fields in results
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/search_records_opportunity">
    **Description:** Search for Opportunity records with advanced filtering.

    **Parameters:**

    * `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators
    * `sortBy` (string, optional): Sort field (e.g., "CreatedDate")
    * `sortDirection` (string, optional): Sort direction - Options: ASC, DESC
    * `includeAllFields` (boolean, optional): Include all fields in results
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/search_records_task">
    **Description:** Search for Task records with advanced filtering.

    **Parameters:**

    * `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators
    * `sortBy` (string, optional): Sort field (e.g., "CreatedDate")
    * `sortDirection` (string, optional): Sort direction - Options: ASC, DESC
    * `includeAllFields` (boolean, optional): Include all fields in results
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/search_records_account">
    **Description:** Search for Account records with advanced filtering.

    **Parameters:**

    * `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators
    * `sortBy` (string, optional): Sort field (e.g., "CreatedDate")
    * `sortDirection` (string, optional): Sort direction - Options: ASC, DESC
    * `includeAllFields` (boolean, optional): Include all fields in results
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/search_records_any">
    **Description:** Search for records of any object type.

    **Parameters:**

    * `recordType` (string, required): Record Type to search
    * `filterFormula` (string, optional): Filter search criteria
    * `includeAllFields` (boolean, optional): Include all fields in results
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>
</AccordionGroup>

### **List View Retrieval**

<AccordionGroup>
  <Accordion title="salesforce/get_record_by_view_id_contact">
    **Description:** Get Contact records from a specific List View.

    **Parameters:**

    * `listViewId` (string, required): List View ID
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/get_record_by_view_id_lead">
    **Description:** Get Lead records from a specific List View.

    **Parameters:**

    * `listViewId` (string, required): List View ID
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/get_record_by_view_id_opportunity">
    **Description:** Get Opportunity records from a specific List View.

    **Parameters:**

    * `listViewId` (string, required): List View ID
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/get_record_by_view_id_task">
    **Description:** Get Task records from a specific List View.

    **Parameters:**

    * `listViewId` (string, required): List View ID
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/get_record_by_view_id_account">
    **Description:** Get Account records from a specific List View.

    **Parameters:**

    * `listViewId` (string, required): List View ID
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>

  <Accordion title="salesforce/get_record_by_view_id_any">
    **Description:** Get records of any object type from a specific List View.

    **Parameters:**

    * `recordType` (string, required): Record Type
    * `listViewId` (string, required): List View ID
    * `paginationParameters` (object, optional): Pagination settings with pageCursor
  </Accordion>
</AccordionGroup>

### **Custom Fields**

<AccordionGroup>
  <Accordion title="salesforce/create_custom_field_contact">
    **Description:** Deploy custom fields for Contact objects.

    **Parameters:**

    * `label` (string, required): Field Label for displays and internal reference
    * `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
    * `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields
    * `length` (string, required): Length for numeric/text fields
    * `decimalPlace` (string, required): Decimal places for numeric fields
    * `pickListValues` (string, required): Values for picklist fields (separated by new lines)
    * `visibleLines` (string, required): Visible lines for multiselect/text area fields
    * `description` (string, optional): Field description
    * `helperText` (string, optional): Helper text shown on hover
    * `defaultFieldValue` (string, optional): Default field value
  </Accordion>

  <Accordion title="salesforce/create_custom_field_lead">
    **Description:** Deploy custom fields for Lead objects.

    **Parameters:**

    * `label` (string, required): Field Label for displays and internal reference
    * `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
    * `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields
    * `length` (string, required): Length for numeric/text fields
    * `decimalPlace` (string, required): Decimal places for numeric fields
    * `pickListValues` (string, required): Values for picklist fields (separated by new lines)
    * `visibleLines` (string, required): Visible lines for multiselect/text area fields
    * `description` (string, optional): Field description
    * `helperText` (string, optional): Helper text shown on hover
    * `defaultFieldValue` (string, optional): Default field value
  </Accordion>

  <Accordion title="salesforce/create_custom_field_opportunity">
    **Description:** Deploy custom fields for Opportunity objects.

    **Parameters:**

    * `label` (string, required): Field Label for displays and internal reference
    * `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
    * `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields
    * `length` (string, required): Length for numeric/text fields
    * `decimalPlace` (string, required): Decimal places for numeric fields
    * `pickListValues` (string, required): Values for picklist fields (separated by new lines)
    * `visibleLines` (string, required): Visible lines for multiselect/text area fields
    * `description` (string, optional): Field description
    * `helperText` (string, optional): Helper text shown on hover
    * `defaultFieldValue` (string, optional): Default field value
  </Accordion>

  <Accordion title="salesforce/create_custom_field_task">
    **Description:** Deploy custom fields for Task objects.

    **Parameters:**

    * `label` (string, required): Field Label for displays and internal reference
    * `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, Time, Url
    * `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields
    * `length` (string, required): Length for numeric/text fields
    * `decimalPlace` (string, required): Decimal places for numeric fields
    * `pickListValues` (string, required): Values for picklist fields (separated by new lines)
    * `visibleLines` (string, required): Visible lines for multiselect fields
    * `description` (string, optional): Field description
    * `helperText` (string, optional): Helper text shown on hover
    * `defaultFieldValue` (string, optional): Default field value
  </Accordion>

  <Accordion title="salesforce/create_custom_field_account">
    **Description:** Deploy custom fields for Account objects.

    **Parameters:**

    * `label` (string, required): Field Label for displays and internal reference
    * `type` (string, required): Field Type - Options: Checkbox, Currency, Date, Email, Number, Percent, Phone, Picklist, MultiselectPicklist, Text, TextArea, LongTextArea, Html, Time, Url
    * `defaultCheckboxValue` (boolean, optional): Default value for checkbox fields
    * `length` (string, required): Length for numeric/text fields
    * `decimalPlace` (string, required): Decimal places for numeric fields
    * `pickListValues` (string, required): Values for picklist fields (separated by new lines)
    * `visibleLines` (string, required): Visible lines for multiselect/text area fields
    * `description` (string, optional): Field description
    * `helperText` (string, optional): Helper text shown on hover
    * `defaultFieldValue` (string, optional): Default field value
  </Accordion>

  <Accordion title="salesforce/create_custom_field_any">
    **Description:** Deploy custom fields for any object type.

    **Note:** This is a flexible tool for creating custom fields on custom or unknown object types.
  </Accordion>
</AccordionGroup>

### **Advanced Operations**

<AccordionGroup>
  <Accordion title="salesforce/write_soql_query">
    **Description:** Execute custom SOQL queries against your Salesforce data.

    **Parameters:**

    * `query` (string, required): SOQL Query (e.g., "SELECT Id, Name FROM Account WHERE Name = 'Example'")
  </Accordion>

  <Accordion title="salesforce/create_custom_object">
    **Description:** Deploy a new custom object in Salesforce.

    **Parameters:**

    * `label` (string, required): Object Label for tabs, page layouts, and reports
    * `pluralLabel` (string, required): Plural Label (e.g., "Accounts")
    * `description` (string, optional): A description of the Custom Object
    * `recordName` (string, required): Record Name that appears in layouts and searches (e.g., "Account Name")
  </Accordion>

  <Accordion title="salesforce/describe_action_schema">
    **Description:** Get the expected schema for operations on specific object types.

    **Parameters:**

    * `recordType` (string, required): Record Type to describe
    * `operation` (string, required): Operation Type (e.g., "CREATE\_RECORD" or "UPDATE\_RECORD")

    **Note:** Use this function first when working with custom objects to understand their schema before performing operations.
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Salesforce Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew
from crewai import Agent, Task, Crew

# Create an agent with Salesforce capabilities
salesforce_agent = Agent(
    role="CRM Manager",
    goal="Manage customer relationships and sales processes efficiently",
    backstory="An AI assistant specialized in CRM operations and sales automation.",
    apps=['salesforce']  # All Salesforce actions will be available
)

# Task to create a new lead
create_lead_task = Task(
    description="Create a new lead for John Doe from Example Corp with email john.doe@example.com",
    agent=salesforce_agent,
    expected_output="Lead created successfully with lead ID"
)

# Run the task
crew = Crew(
    agents=[salesforce_agent],
    tasks=[create_lead_task]
)

crew.kickoff()
```

### Filtering Specific Salesforce Tools

```python theme={null}

sales_manager = Agent(
    role="Sales Manager",
    goal="Manage leads and opportunities in the sales pipeline",
    backstory="An experienced sales manager who handles lead qualification and opportunity management.",
    apps=['salesforce/create_record_lead']
)

# Task to manage sales pipeline
pipeline_task = Task(
    description="Create a qualified lead and convert it to an opportunity with $50,000 value",
    agent=sales_manager,
    expected_output="Lead created and opportunity established successfully"
)

crew = Crew(
    agents=[sales_manager],
    tasks=[pipeline_task]
)

crew.kickoff()
```

### Contact and Account Management

```python theme={null}
from crewai import Agent, Task, Crew

account_manager = Agent(
    role="Account Manager",
    goal="Manage customer accounts and maintain strong relationships",
    backstory="An AI assistant that specializes in account management and customer relationship building.",
    apps=['salesforce']
)

# Task to manage customer accounts
account_task = Task(
    description="""
    1. Create a new account for TechCorp Inc.
    2. Add John Doe as the primary contact for this account
    3. Create a follow-up task for next week to check on their project status
    """,
    agent=account_manager,
    expected_output="Account, contact, and follow-up task created successfully"
)

crew = Crew(
    agents=[account_manager],
    tasks=[account_task]
)

crew.kickoff()
```

### Advanced SOQL Queries and Reporting

```python theme={null}
from crewai import Agent, Task, Crew

data_analyst = Agent(
    role="Sales Data Analyst",
    goal="Generate insights from Salesforce data using SOQL queries",
    backstory="An analytical AI that excels at extracting meaningful insights from CRM data.",
    apps=['salesforce']
)

# Complex task involving SOQL queries and data analysis
analysis_task = Task(
    description="""
    1. Execute a SOQL query to find all opportunities closing this quarter
    2. Search for contacts at companies with opportunities over $100K
    3. Create a summary report of the sales pipeline status
    4. Update high-value opportunities with next steps
    """,
    agent=data_analyst,
    expected_output="Comprehensive sales pipeline analysis with actionable insights"
)

crew = Crew(
    agents=[data_analyst],
    tasks=[analysis_task]
)

crew.kickoff()
```

This comprehensive documentation covers all the Salesforce tools organized by functionality, making it easy for users to find the specific operations they need for their CRM automation tasks.

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Salesforce integration setup or
  troubleshooting.
</Card>


# Shopify Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/shopify

E-commerce and online store management with Shopify integration for CrewAI.

## Overview

Enable your agents to manage e-commerce operations through Shopify. Handle customers, orders, products, inventory, and store analytics to streamline your online business with AI-powered automation.

## Prerequisites

Before using the Shopify integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Shopify store with appropriate admin permissions
* Connected your Shopify store through the [Integrations page](https://app.crewai.com/integrations)

## Setting Up Shopify Integration

### 1. Connect Your Shopify Store

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Shopify** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for store and product management
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Tools

### **Customer Management**

<AccordionGroup>
  <Accordion title="shopify/get_customers">
    **Description:** Retrieve a list of customers from your Shopify store.

    **Parameters:**

    * `customerIds` (string, optional): Comma-separated list of customer IDs to filter by (example: "207119551, 207119552")
    * `createdAtMin` (string, optional): Only return customers created after this date (ISO or Unix timestamp)
    * `createdAtMax` (string, optional): Only return customers created before this date (ISO or Unix timestamp)
    * `updatedAtMin` (string, optional): Only return customers updated after this date (ISO or Unix timestamp)
    * `updatedAtMax` (string, optional): Only return customers updated before this date (ISO or Unix timestamp)
    * `limit` (string, optional): Maximum number of customers to return (defaults to 250)
  </Accordion>

  <Accordion title="shopify/search_customers">
    **Description:** Search for customers using advanced filtering criteria.

    **Parameters:**

    * `filterFormula` (object, optional): Advanced filter in disjunctive normal form with field-specific operators
    * `limit` (string, optional): Maximum number of customers to return (defaults to 250)
  </Accordion>

  <Accordion title="shopify/create_customer">
    **Description:** Create a new customer in your Shopify store.

    **Parameters:**

    * `firstName` (string, required): Customer's first name
    * `lastName` (string, required): Customer's last name
    * `email` (string, required): Customer's email address
    * `company` (string, optional): Company name
    * `streetAddressLine1` (string, optional): Street address
    * `streetAddressLine2` (string, optional): Street address line 2
    * `city` (string, optional): City
    * `state` (string, optional): State or province code
    * `country` (string, optional): Country
    * `zipCode` (string, optional): Zip code
    * `phone` (string, optional): Phone number
    * `tags` (string, optional): Tags as array or comma-separated list
    * `note` (string, optional): Customer note
    * `sendEmailInvite` (boolean, optional): Whether to send email invitation
    * `metafields` (object, optional): Additional metafields in JSON format
  </Accordion>

  <Accordion title="shopify/update_customer">
    **Description:** Update an existing customer in your Shopify store.

    **Parameters:**

    * `customerId` (string, required): The ID of the customer to update
    * `firstName` (string, optional): Customer's first name
    * `lastName` (string, optional): Customer's last name
    * `email` (string, optional): Customer's email address
    * `company` (string, optional): Company name
    * `streetAddressLine1` (string, optional): Street address
    * `streetAddressLine2` (string, optional): Street address line 2
    * `city` (string, optional): City
    * `state` (string, optional): State or province code
    * `country` (string, optional): Country
    * `zipCode` (string, optional): Zip code
    * `phone` (string, optional): Phone number
    * `tags` (string, optional): Tags as array or comma-separated list
    * `note` (string, optional): Customer note
    * `sendEmailInvite` (boolean, optional): Whether to send email invitation
    * `metafields` (object, optional): Additional metafields in JSON format
  </Accordion>
</AccordionGroup>

### **Order Management**

<AccordionGroup>
  <Accordion title="shopify/get_orders">
    **Description:** Retrieve a list of orders from your Shopify store.

    **Parameters:**

    * `orderIds` (string, optional): Comma-separated list of order IDs to filter by (example: "450789469, 450789470")
    * `createdAtMin` (string, optional): Only return orders created after this date (ISO or Unix timestamp)
    * `createdAtMax` (string, optional): Only return orders created before this date (ISO or Unix timestamp)
    * `updatedAtMin` (string, optional): Only return orders updated after this date (ISO or Unix timestamp)
    * `updatedAtMax` (string, optional): Only return orders updated before this date (ISO or Unix timestamp)
    * `limit` (string, optional): Maximum number of orders to return (defaults to 250)
  </Accordion>

  <Accordion title="shopify/create_order">
    **Description:** Create a new order in your Shopify store.

    **Parameters:**

    * `email` (string, required): Customer email address
    * `lineItems` (object, required): Order line items in JSON format with title, price, quantity, and variant\_id
    * `sendReceipt` (boolean, optional): Whether to send order receipt
    * `fulfillmentStatus` (string, optional): Fulfillment status - Options: fulfilled, null, partial, restocked
    * `financialStatus` (string, optional): Financial status - Options: pending, authorized, partially\_paid, paid, partially\_refunded, refunded, voided
    * `inventoryBehaviour` (string, optional): Inventory behavior - Options: bypass, decrement\_ignoring\_policy, decrement\_obeying\_policy
    * `note` (string, optional): Order note
  </Accordion>

  <Accordion title="shopify/update_order">
    **Description:** Update an existing order in your Shopify store.

    **Parameters:**

    * `orderId` (string, required): The ID of the order to update
    * `email` (string, optional): Customer email address
    * `lineItems` (object, optional): Updated order line items in JSON format
    * `sendReceipt` (boolean, optional): Whether to send order receipt
    * `fulfillmentStatus` (string, optional): Fulfillment status - Options: fulfilled, null, partial, restocked
    * `financialStatus` (string, optional): Financial status - Options: pending, authorized, partially\_paid, paid, partially\_refunded, refunded, voided
    * `inventoryBehaviour` (string, optional): Inventory behavior - Options: bypass, decrement\_ignoring\_policy, decrement\_obeying\_policy
    * `note` (string, optional): Order note
  </Accordion>

  <Accordion title="shopify/get_abandoned_carts">
    **Description:** Retrieve abandoned carts from your Shopify store.

    **Parameters:**

    * `createdWithInLast` (string, optional): Restrict results to checkouts created within specified time
    * `createdAfterId` (string, optional): Restrict results to after the specified ID
    * `status` (string, optional): Show checkouts with given status - Options: open, closed (defaults to open)
    * `createdAtMin` (string, optional): Only return carts created after this date (ISO or Unix timestamp)
    * `createdAtMax` (string, optional): Only return carts created before this date (ISO or Unix timestamp)
    * `limit` (string, optional): Maximum number of carts to return (defaults to 250)
  </Accordion>
</AccordionGroup>

### **Product Management (REST API)**

<AccordionGroup>
  <Accordion title="shopify/get_products">
    **Description:** Retrieve a list of products from your Shopify store using REST API.

    **Parameters:**

    * `productIds` (string, optional): Comma-separated list of product IDs to filter by (example: "632910392, 632910393")
    * `title` (string, optional): Filter by product title
    * `productType` (string, optional): Filter by product type
    * `vendor` (string, optional): Filter by vendor
    * `status` (string, optional): Filter by status - Options: active, archived, draft
    * `createdAtMin` (string, optional): Only return products created after this date (ISO or Unix timestamp)
    * `createdAtMax` (string, optional): Only return products created before this date (ISO or Unix timestamp)
    * `updatedAtMin` (string, optional): Only return products updated after this date (ISO or Unix timestamp)
    * `updatedAtMax` (string, optional): Only return products updated before this date (ISO or Unix timestamp)
    * `limit` (string, optional): Maximum number of products to return (defaults to 250)
  </Accordion>

  <Accordion title="shopify/create_product">
    **Description:** Create a new product in your Shopify store using REST API.

    **Parameters:**

    * `title` (string, required): Product title
    * `productType` (string, required): Product type/category
    * `vendor` (string, required): Product vendor
    * `productDescription` (string, optional): Product description (accepts plain text or HTML)
    * `tags` (string, optional): Product tags as array or comma-separated list
    * `price` (string, optional): Product price
    * `inventoryPolicy` (string, optional): Inventory policy - Options: deny, continue
    * `imageUrl` (string, optional): Product image URL
    * `isPublished` (boolean, optional): Whether product is published
    * `publishToPointToSale` (boolean, optional): Whether to publish to point of sale
  </Accordion>

  <Accordion title="shopify/update_product">
    **Description:** Update an existing product in your Shopify store using REST API.

    **Parameters:**

    * `productId` (string, required): The ID of the product to update
    * `title` (string, optional): Product title
    * `productType` (string, optional): Product type/category
    * `vendor` (string, optional): Product vendor
    * `productDescription` (string, optional): Product description (accepts plain text or HTML)
    * `tags` (string, optional): Product tags as array or comma-separated list
    * `price` (string, optional): Product price
    * `inventoryPolicy` (string, optional): Inventory policy - Options: deny, continue
    * `imageUrl` (string, optional): Product image URL
    * `isPublished` (boolean, optional): Whether product is published
    * `publishToPointToSale` (boolean, optional): Whether to publish to point of sale
  </Accordion>
</AccordionGroup>

### **Product Management (GraphQL)**

<AccordionGroup>
  <Accordion title="shopify/get_products_graphql">
    **Description:** Retrieve products using advanced GraphQL filtering capabilities.

    **Parameters:**

    * `productFilterFormula` (object, optional): Advanced filter in disjunctive normal form with support for fields like id, title, vendor, status, handle, tag, created\_at, updated\_at, published\_at
  </Accordion>

  <Accordion title="shopify/create_product_graphql">
    **Description:** Create a new product using GraphQL API with enhanced media support.

    **Parameters:**

    * `title` (string, required): Product title
    * `productType` (string, required): Product type/category
    * `vendor` (string, required): Product vendor
    * `productDescription` (string, optional): Product description (accepts plain text or HTML)
    * `tags` (string, optional): Product tags as array or comma-separated list
    * `media` (object, optional): Media objects with alt text, content type, and source URL
    * `additionalFields` (object, optional): Additional product fields like status, requiresSellingPlan, giftCard
  </Accordion>

  <Accordion title="shopify/update_product_graphql">
    **Description:** Update an existing product using GraphQL API with enhanced media support.

    **Parameters:**

    * `productId` (string, required): The GraphQL ID of the product to update (e.g., "gid://shopify/Product/913144112")
    * `title` (string, optional): Product title
    * `productType` (string, optional): Product type/category
    * `vendor` (string, optional): Product vendor
    * `productDescription` (string, optional): Product description (accepts plain text or HTML)
    * `tags` (string, optional): Product tags as array or comma-separated list
    * `media` (object, optional): Updated media objects with alt text, content type, and source URL
    * `additionalFields` (object, optional): Additional product fields like status, requiresSellingPlan, giftCard
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Shopify Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew
from crewai import Agent, Task, Crew

# Create an agent with Shopify capabilities
shopify_agent = Agent(
    role="E-commerce Manager",
    goal="Manage online store operations and customer relationships efficiently",
    backstory="An AI assistant specialized in e-commerce operations and online store management.",
    apps=['shopify']  # All Shopify actions will be available
)

# Task to create a new customer
create_customer_task = Task(
    description="Create a new VIP customer Jane Smith with email jane.smith@example.com and phone +1-555-0123",
    agent=shopify_agent,
    expected_output="Customer created successfully with customer ID"
)

# Run the task
crew = Crew(
    agents=[shopify_agent],
    tasks=[create_customer_task]
)

crew.kickoff()
```

### Filtering Specific Shopify Tools

```python theme={null}

store_manager = Agent(
    role="Store Manager",
    goal="Manage customer orders and product catalog",
    backstory="An experienced store manager who handles customer relationships and inventory management.",
    apps=['shopify/create_customer']
)

# Task to manage store operations
store_task = Task(
    description="Create a new customer and process their order for 2 Premium Coffee Mugs",
    agent=store_manager,
    expected_output="Customer created and order processed successfully"
)

crew = Crew(
    agents=[store_manager],
    tasks=[store_task]
)

crew.kickoff()
```

### Product Management with GraphQL

```python theme={null}
from crewai import Agent, Task, Crew

product_manager = Agent(
    role="Product Manager",
    goal="Manage product catalog and inventory with advanced GraphQL capabilities",
    backstory="An AI assistant that specializes in product management and catalog optimization.",
    apps=['shopify']
)

# Task to manage product catalog
catalog_task = Task(
    description="""
    1. Create a new product "Premium Coffee Mug" from Coffee Co vendor
    2. Add high-quality product images and descriptions
    3. Search for similar products from the same vendor
    4. Update product tags and pricing strategy
    """,
    agent=product_manager,
    expected_output="Product created and catalog optimized successfully"
)

crew = Crew(
    agents=[product_manager],
    tasks=[catalog_task]
)

crew.kickoff()
```

### Order and Customer Analytics

```python theme={null}
from crewai import Agent, Task, Crew

analytics_agent = Agent(
    role="E-commerce Analyst",
    goal="Analyze customer behavior and order patterns to optimize store performance",
    backstory="An analytical AI that excels at extracting insights from e-commerce data.",
    apps=['shopify']
)

# Complex task involving multiple operations
analytics_task = Task(
    description="""
    1. Retrieve recent customer data and order history
    2. Identify abandoned carts from the last 7 days
    3. Analyze product performance and inventory levels
    4. Generate recommendations for customer retention
    """,
    agent=analytics_agent,
    expected_output="Comprehensive e-commerce analytics report with actionable insights"
)

crew = Crew(
    agents=[analytics_agent],
    tasks=[analytics_task]
)

crew.kickoff()
```

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Shopify integration setup or
  troubleshooting.
</Card>


# Slack Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/slack

Team communication and collaboration with Slack integration for CrewAI.

## Overview

Enable your agents to manage team communication through Slack. Send messages, search conversations, manage channels, and coordinate team activities to streamline your collaboration workflows with AI-powered automation.

## Prerequisites

Before using the Slack integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Slack workspace with appropriate permissions
* Connected your Slack workspace through the [Integrations page](https://app.crewai.com/integrations)

## Setting Up Slack Integration

### 1. Connect Your Slack Workspace

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Slack** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for team communication
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Tools

### **User Management**

<AccordionGroup>
  <Accordion title="slack/list_members">
    **Description:** List all members in a Slack channel.

    **Parameters:**

    * No parameters required - retrieves all channel members
  </Accordion>

  <Accordion title="slack/get_user_by_email">
    **Description:** Find a user in your Slack workspace by their email address.

    **Parameters:**

    * `email` (string, required): The email address of a user in the workspace
  </Accordion>

  <Accordion title="slack/get_users_by_name">
    **Description:** Search for users by their name or display name.

    **Parameters:**

    * `name` (string, required): User's real name to search for
    * `displayName` (string, required): User's display name to search for
    * `paginationParameters` (object, optional): Pagination settings
      * `pageCursor` (string, optional): Page cursor for pagination
  </Accordion>
</AccordionGroup>

### **Channel Management**

<AccordionGroup>
  <Accordion title="slack/list_channels">
    **Description:** List all channels in your Slack workspace.

    **Parameters:**

    * No parameters required - retrieves all accessible channels
  </Accordion>
</AccordionGroup>

### **Messaging**

<AccordionGroup>
  <Accordion title="slack/send_message">
    **Description:** Send a message to a Slack channel.

    **Parameters:**

    * `channel` (string, required): Channel name or ID - Use Connect Portal Workflow Settings to allow users to select a channel, or enter a channel name to create a new channel
    * `message` (string, required): The message text to send
    * `botName` (string, required): The name of the bot that sends this message
    * `botIcon` (string, required): Bot icon - Can be either an image URL or an emoji (e.g., ":dog:")
    * `blocks` (object, optional): Slack Block Kit JSON for rich message formatting with attachments and interactive elements
    * `authenticatedUser` (boolean, optional): If true, message appears to come from your authenticated Slack user instead of the application (defaults to false)
  </Accordion>

  <Accordion title="slack/send_direct_message">
    **Description:** Send a direct message to a specific user in Slack.

    **Parameters:**

    * `memberId` (string, required): Recipient user ID - Use Connect Portal Workflow Settings to allow users to select a workspace member
    * `message` (string, required): The message text to send
    * `botName` (string, required): The name of the bot that sends this message
    * `botIcon` (string, required): Bot icon - Can be either an image URL or an emoji (e.g., ":dog:")
    * `blocks` (object, optional): Slack Block Kit JSON for rich message formatting with attachments and interactive elements
    * `authenticatedUser` (boolean, optional): If true, message appears to come from your authenticated Slack user instead of the application (defaults to false)
  </Accordion>
</AccordionGroup>

### **Search & Discovery**

<AccordionGroup>
  <Accordion title="slack/search_messages">
    **Description:** Search for messages across your Slack workspace.

    **Parameters:**

    * `query` (string, required): Search query using Slack search syntax to find messages that match specified criteria

    **Search Query Examples:**

    * `"project update"` - Search for messages containing "project update"
    * `from:@john in:#general` - Search for messages from John in the #general channel
    * `has:link after:2023-01-01` - Search for messages with links after January 1, 2023
    * `in:@channel before:yesterday` - Search for messages in a specific channel before yesterday
  </Accordion>
</AccordionGroup>

## Block Kit Integration

Slack's Block Kit allows you to create rich, interactive messages. Here are some examples of how to use the `blocks` parameter:

### Simple Text with Attachment

```json theme={null}
[
  {
    "text": "I am a test message",
    "attachments": [
      {
        "text": "And here's an attachment!"
      }
    ]
  }
]
```

### Rich Formatting with Sections

```json theme={null}
[
  {
    "type": "section",
    "text": {
      "type": "mrkdwn",
      "text": "*Project Update*\nStatus: ✅ Complete"
    }
  },
  {
    "type": "divider"
  },
  {
    "type": "section",
    "text": {
      "type": "plain_text",
      "text": "All tasks have been completed successfully."
    }
  }
]
```

## Usage Examples

### Basic Slack Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew

# Create an agent with Slack capabilities
slack_agent = Agent(
    role="Team Communication Manager",
    goal="Facilitate team communication and coordinate collaboration efficiently",
    backstory="An AI assistant specialized in team communication and workspace coordination.",
    apps=['slack']  # All Slack actions will be available
)

# Task to send project updates
update_task = Task(
    description="Send a project status update to the #general channel with current progress",
    agent=slack_agent,
    expected_output="Project update message sent successfully to team channel"
)

# Run the task
crew = Crew(
    agents=[slack_agent],
    tasks=[update_task]
)

crew.kickoff()
```

### Filtering Specific Slack Tools

```python theme={null}
from crewai import Agent, Task, Crew

# Create agent with specific Slack actions only
communication_manager = Agent(
    role="Communication Coordinator",
    goal="Manage team communications and ensure important messages reach the right people",
    backstory="An experienced communication coordinator who handles team messaging and notifications.",
    apps=[
        'slack/send_message',
        'slack/send_direct_message',
        'slack/search_messages'
    ]  # Using canonical action names from canonical_integrations.yml
)

# Task to coordinate team communication
coordination_task = Task(
    description="Send task completion notifications to team members and update project channels",
    agent=communication_manager,
    expected_output="Team notifications sent and project channels updated successfully"
)

crew = Crew(
    agents=[communication_manager],
    tasks=[coordination_task]
)

crew.kickoff()
```

### Advanced Messaging with Block Kit

```python theme={null}
from crewai import Agent, Task, Crew

# Create agent with Slack messaging capabilities
notification_agent = Agent(
    role="Notification Manager",
    goal="Create rich, interactive notifications and manage workspace communication",
    backstory="An AI assistant that specializes in creating engaging team notifications and updates.",
    apps=['slack/send_message']  # Specific action for sending messages
)

# Task to send rich notifications
notification_task = Task(
    description="""
    1. Send a formatted project completion message to #general with progress charts
    2. Send direct messages to team leads with task summaries
    3. Create interactive notification with action buttons for team feedback
    """,
    agent=notification_agent,
    expected_output="Rich notifications sent with interactive elements and formatted content"
)

crew = Crew(
    agents=[notification_agent],
    tasks=[notification_task]
)

crew.kickoff()
```

### Message Search and Analytics

```python theme={null}
from crewai import Agent, Task, Crew

# Create agent with Slack search and user management capabilities
analytics_agent = Agent(
    role="Communication Analyst",
    goal="Analyze team communication patterns and extract insights from conversations",
    backstory="An analytical AI that excels at understanding team dynamics through communication data.",
    apps=[
        'slack/search_messages',
        'slack/get_user_by_email',
        'slack/list_members'
    ]  # Using canonical action names from canonical_integrations.yml
)

# Complex task involving search and analysis
analysis_task = Task(
    description="""
    1. Search for recent project-related messages across all channels
    2. Find users by email to identify team members
    3. Analyze communication patterns and response times
    4. Generate weekly team communication summary
    """,
    agent=analytics_agent,
    expected_output="Comprehensive communication analysis with team insights and recommendations"
)

crew = Crew(
    agents=[analytics_agent],
    tasks=[analysis_task]
)

crew.kickoff()
```

## Contact Support

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Slack integration setup or
  troubleshooting.
</Card>


# Snowflake Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/snowflake

Connect CrewAI agents to Snowflake Cortex Analyst, Cortex Search, and SQL execution through the Snowflake-managed MCP server.

## Overview

Connect your CrewAI agents directly to your Snowflake data through the [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp). The Snowflake integration lets your agents query structured data with **Cortex Analyst**, search unstructured data with **Cortex Search**, and run governed SQL against your warehouses — all without writing or hosting any connector code.

Under the hood, the Snowflake integration is a managed wrapper around CrewAI's [Custom MCP Server](/platform/en/guides/custom-mcp-server) support. Snowflake exposes its Cortex AI capabilities through a [Model Context Protocol](https://modelcontextprotocol.io/) endpoint, and CrewAI connects to it securely on your behalf. Any tool you expose on the Snowflake side — Cortex Analyst, Cortex Search, SQL execution, Cortex Agents, or your own custom tools — becomes available to your crews.

## Key Capabilities

<CardGroup>
  <Card title="Cortex Analyst" icon="chart-bar">
    Ask questions in natural language and let [Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) generate and run SQL against your **structured** data using rich semantic models.
  </Card>

  <Card title="Cortex Search" icon="magnifying-glass">
    Retrieve relevant **unstructured** data for RAG and knowledge workflows with [Cortex Search](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview), Snowflake's fully managed search service.
  </Card>

  <Card title="SQL Execution" icon="database">
    Run governed SQL queries directly against your Snowflake warehouses, with configurable read-only mode, timeouts, and warehouse selection.
  </Card>
</CardGroup>

Because the integration surfaces whatever tools your MCP server publishes, you can also expose **Cortex Agents** and **custom tools** (user-defined functions and stored procedures) to your CrewAI agents.

## Prerequisites

Before using the Snowflake integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Snowflake account with access to Cortex AI features
* A [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) configured with the tools you want to expose
* Appropriate Snowflake privileges (USAGE/SELECT) on the MCP server and its underlying objects

## Setting Up the Snowflake MCP Server

The Snowflake-managed MCP server runs inside your Snowflake account and defines which tools are available to external clients like CrewAI. Create one with the [`CREATE MCP SERVER`](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server) command, listing the Cortex Search services, Cortex Analyst semantic views, and SQL tools you want to expose.

```sql theme={null}
CREATE MCP SERVER my_mcp_server
  FROM SPECIFICATION $$
    tools:
      - name: "sales_analyst"
        type: "CORTEX_ANALYST"
        identifier: "MY_DATABASE.MY_SCHEMA.sales_semantic_view"
        description: "Answer questions about sales metrics"
      - name: "docs_search"
        type: "CORTEX_SEARCH_SERVICE_QUERY"
        identifier: "MY_DATABASE.MY_SCHEMA.support_docs_search"
        description: "Search internal support documentation"
      - name: "run_sql"
        type: "SQL_EXECUTION"
        description: "Execute read-only SQL queries"
  $$;
```

<Note>
  The MCP endpoint follows the format `https://<account_URL>/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}`. CrewAI builds this URL automatically from the **Account URL**, **Database**, **Schema**, and **MCP Server Name** you provide when configuring the integration.
</Note>

For the complete specification — including Cortex Agents, custom tools, response-size limits, and governance options — see the [Snowflake-managed MCP server documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp).

## Connecting Snowflake in CrewAI AMP

<Frame>
  <img alt="Configure Snowflake integration in CrewAI AMP" />
</Frame>

<Steps>
  <Step title="Open Tools & Integrations">
    Navigate to **Tools & Integrations** in the left sidebar of CrewAI AMP, find **Snowflake** in the list of applications, and open its configuration panel.
  </Step>

  <Step title="Provide connection details">
    Fill in the connection fields that CrewAI uses to reach your Snowflake MCP server:

    | Field               | Required | Description                                                                        |
    | ------------------- | -------- | ---------------------------------------------------------------------------------- |
    | **Name**            | Yes      | A descriptive name for this connection (defaults to `Snowflake`).                  |
    | **Description**     | No       | An optional summary of what this connection provides.                              |
    | **Account URL**     | Yes      | Your Snowflake account URL, e.g. `xy12345.us-east-1.snowflakecomputing.com`.       |
    | **Database**        | Yes      | The database that contains your MCP server (e.g. `MY_DATABASE`).                   |
    | **Schema**          | Yes      | The schema that contains your MCP server (e.g. `MY_SCHEMA`).                       |
    | **MCP Server Name** | Yes      | The name of the MCP server object you created in Snowflake (e.g. `MY_MCP_SERVER`). |
  </Step>

  <Step title="Choose an authentication method">
    Select how CrewAI authenticates to Snowflake. **OAuth** is recommended.

    * **Use OAuth** — Connect securely using OAuth 2.0 for token-based authentication without sharing your credentials. CrewAI handles the full authorization flow and refreshes tokens automatically. Copy the **Redirect URI** shown in the form (`https://oauth.crewai.com/oauth/add`) and register it as an authorized redirect URI in your Snowflake [OAuth security integration](https://docs.snowflake.com/en/user-guide/oauth-custom).
    * **Use personal access token** — Authenticate using a [programmatic access token](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) generated from your Snowflake account settings. Assign a least-privileged role to the token to limit exposure.
  </Step>

  <Step title="Authenticate">
    Click **Authenticate**. For OAuth, you'll be redirected to Snowflake to authorize access. Once authenticated, the Snowflake server appears in your Connections and its tools become available to your crews.
  </Step>
</Steps>

<Tip>
  With OAuth, each user authenticates individually and queries run with their Snowflake `DEFAULT_ROLE`. Make sure connecting users have a default role and warehouse set (`ALTER USER <username> SET DEFAULT_ROLE = '<role>' DEFAULT_WAREHOUSE = '<warehouse>'`) so Cortex Analyst and SQL tools have compute to run on.
</Tip>

## Using Snowflake Tools in Your Crews

Once connected, the tools your MCP server exposes appear alongside built-in connections on the **Tools & Integrations** page. You can:

* **Assign tools to agents** in your crews just like any other CrewAI tool.
* **Manage visibility** to control which team members can use the connection.
* **Edit or remove** the connection at any time from the Connections list.

Your agents can now ask Cortex Analyst for metrics, run Cortex Search over your documents, and execute SQL — with results flowing back into their reasoning automatically.

<Warning>
  Snowflake enforces governance on the MCP server: role-based access control determines which tools a user can discover and invoke, and limits apply to response size, tool count (max 50 per server), and recursion depth. If a tool call fails, confirm the connecting user's role has the required privileges on the MCP server and its underlying objects.
</Warning>

## Learn More

<CardGroup>
  <Card title="Snowflake-managed MCP Server" icon="snowflake" href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp">
    Official Snowflake documentation for creating and governing the MCP server.
  </Card>

  <Card title="Custom MCP Servers in CrewAI" icon="plug" href="/platform/en/guides/custom-mcp-server">
    Learn how CrewAI connects to any MCP server, the foundation the Snowflake integration builds on.
  </Card>
</CardGroup>

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with the Snowflake integration or troubleshooting.
</Card>


# Stripe Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/stripe

Payment processing and subscription management with Stripe integration for CrewAI.

## Overview

Enable your agents to manage payments, subscriptions, and customer billing through Stripe. Handle customer data, process subscriptions, manage products, and track financial transactions to streamline your payment workflows with AI-powered automation.

## Prerequisites

Before using the Stripe integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Stripe account with appropriate API permissions
* Connected your Stripe account through the [Integrations page](https://app.crewai.com/integrations)

## Setting Up Stripe Integration

### 1. Connect Your Stripe Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Stripe** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for payment processing
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Tools

### **Customer Management**

<AccordionGroup>
  <Accordion title="stripe/create_customer">
    **Description:** Create a new customer in your Stripe account.

    **Parameters:**

    * `emailCreateCustomer` (string, required): Customer's email address
    * `name` (string, optional): Customer's full name
    * `description` (string, optional): Customer description for internal reference
    * `metadataCreateCustomer` (object, optional): Additional metadata as key-value pairs (e.g., `{"field1": 1, "field2": 2}`)
  </Accordion>

  <Accordion title="stripe/get_customer_by_id">
    **Description:** Retrieve a specific customer by their Stripe customer ID.

    **Parameters:**

    * `idGetCustomer` (string, required): The Stripe customer ID to retrieve
  </Accordion>

  <Accordion title="stripe/get_customers">
    **Description:** Retrieve a list of customers with optional filtering.

    **Parameters:**

    * `emailGetCustomers` (string, optional): Filter customers by email address
    * `createdAfter` (string, optional): Filter customers created after this date (Unix timestamp)
    * `createdBefore` (string, optional): Filter customers created before this date (Unix timestamp)
    * `limitGetCustomers` (string, optional): Maximum number of customers to return (defaults to 10)
  </Accordion>

  <Accordion title="stripe/update_customer">
    **Description:** Update an existing customer's information.

    **Parameters:**

    * `customerId` (string, required): The ID of the customer to update
    * `emailUpdateCustomer` (string, optional): Updated email address
    * `name` (string, optional): Updated customer name
    * `description` (string, optional): Updated customer description
    * `metadataUpdateCustomer` (object, optional): Updated metadata as key-value pairs
  </Accordion>
</AccordionGroup>

### **Subscription Management**

<AccordionGroup>
  <Accordion title="stripe/create_subscription">
    **Description:** Create a new subscription for a customer.

    **Parameters:**

    * `customerIdCreateSubscription` (string, required): The customer ID for whom the subscription will be created
    * `plan` (string, required): The plan ID for the subscription - Use Connect Portal Workflow Settings to allow users to select a plan
    * `metadataCreateSubscription` (object, optional): Additional metadata for the subscription
  </Accordion>

  <Accordion title="stripe/get_subscriptions">
    **Description:** Retrieve subscriptions with optional filtering.

    **Parameters:**

    * `customerIdGetSubscriptions` (string, optional): Filter subscriptions by customer ID
    * `subscriptionStatus` (string, optional): Filter by subscription status - Options: incomplete, incomplete\_expired, trialing, active, past\_due, canceled, unpaid
    * `limitGetSubscriptions` (string, optional): Maximum number of subscriptions to return (defaults to 10)
  </Accordion>
</AccordionGroup>

### **Product Management**

<AccordionGroup>
  <Accordion title="stripe/create_product">
    **Description:** Create a new product in your Stripe catalog.

    **Parameters:**

    * `productName` (string, required): The product name
    * `description` (string, optional): Product description
    * `metadataProduct` (object, optional): Additional product metadata as key-value pairs
  </Accordion>

  <Accordion title="stripe/get_product_by_id">
    **Description:** Retrieve a specific product by its Stripe product ID.

    **Parameters:**

    * `productId` (string, required): The Stripe product ID to retrieve
  </Accordion>

  <Accordion title="stripe/get_products">
    **Description:** Retrieve a list of products with optional filtering.

    **Parameters:**

    * `createdAfter` (string, optional): Filter products created after this date (Unix timestamp)
    * `createdBefore` (string, optional): Filter products created before this date (Unix timestamp)
    * `limitGetProducts` (string, optional): Maximum number of products to return (defaults to 10)
  </Accordion>
</AccordionGroup>

### **Financial Operations**

<AccordionGroup>
  <Accordion title="stripe/get_balance_transactions">
    **Description:** Retrieve balance transactions from your Stripe account.

    **Parameters:**

    * `balanceTransactionType` (string, optional): Filter by transaction type - Options: charge, refund, payment, payment\_refund
    * `paginationParameters` (object, optional): Pagination settings
      * `pageCursor` (string, optional): Page cursor for pagination
  </Accordion>

  <Accordion title="stripe/get_plans">
    **Description:** Retrieve subscription plans from your Stripe account.

    **Parameters:**

    * `isPlanActive` (boolean, optional): Filter by plan status - true for active plans, false for inactive plans
    * `paginationParameters` (object, optional): Pagination settings
      * `pageCursor` (string, optional): Page cursor for pagination
  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Stripe Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew
from crewai import Agent, Task, Crew

# Create an agent with Stripe capabilities
stripe_agent = Agent(
    role="Payment Manager",
    goal="Manage customer payments, subscriptions, and billing operations efficiently",
    backstory="An AI assistant specialized in payment processing and subscription management.",
    apps=['stripe']  # All Stripe actions will be available
)

# Task to create a new customer
create_customer_task = Task(
    description="Create a new premium customer John Doe with email john.doe@example.com",
    agent=stripe_agent,
    expected_output="Customer created successfully with customer ID"
)

# Run the task
crew = Crew(
    agents=[stripe_agent],
    tasks=[create_customer_task]
)

crew.kickoff()
```

### Filtering Specific Stripe Tools

```python theme={null}

billing_manager = Agent(
    role="Billing Manager",
    goal="Handle customer billing, subscriptions, and payment processing",
    backstory="An experienced billing manager who handles subscription lifecycle and payment operations.",
    apps=['stripe']
)

# Task to manage billing operations
billing_task = Task(
    description="Create a new customer and set up their premium subscription plan",
    agent=billing_manager,
    expected_output="Customer created and subscription activated successfully"
)

crew = Crew(
    agents=[billing_manager],
    tasks=[billing_task]
)

crew.kickoff()
```

### Subscription Management

```python theme={null}
from crewai import Agent, Task, Crew

subscription_manager = Agent(
    role="Subscription Manager",
    goal="Manage customer subscriptions and optimize recurring revenue",
    backstory="An AI assistant that specializes in subscription lifecycle management and customer retention.",
    apps=['stripe']
)

# Task to manage subscription operations
subscription_task = Task(
    description="""
    1. Create a new product "Premium Service Plan" with advanced features
    2. Set up subscription plans with different tiers
    3. Create customers and assign them to appropriate plans
    4. Monitor subscription status and handle billing issues
    """,
    agent=subscription_manager,
    expected_output="Subscription management system configured with customers and active plans"
)

crew = Crew(
    agents=[subscription_manager],
    tasks=[subscription_task]
)

crew.kickoff()
```

### Financial Analytics and Reporting

```python theme={null}
from crewai import Agent, Task, Crew

financial_analyst = Agent(
    role="Financial Analyst",
    goal="Analyze payment data and generate financial insights",
    backstory="An analytical AI that excels at extracting insights from payment and subscription data.",
    apps=['stripe']
)

# Complex task involving financial analysis
analytics_task = Task(
    description="""
    1. Retrieve balance transactions for the current month
    2. Analyze customer payment patterns and subscription trends
    3. Identify high-value customers and subscription performance
    4. Generate monthly financial performance report
    """,
    agent=financial_analyst,
    expected_output="Comprehensive financial analysis with payment insights and recommendations"
)

crew = Crew(
    agents=[financial_analyst],
    tasks=[analytics_task]
)

crew.kickoff()
```

## Subscription Status Reference

Understanding subscription statuses:

* **incomplete** - Subscription requires payment method or payment confirmation
* **incomplete\_expired** - Subscription expired before payment was confirmed
* **trialing** - Subscription is in trial period
* **active** - Subscription is active and current
* **past\_due** - Payment failed but subscription is still active
* **canceled** - Subscription has been canceled
* **unpaid** - Payment failed and subscription is no longer active

## Metadata Usage

Metadata allows you to store additional information about customers, subscriptions, and products:

```json theme={null}
{
  "customer_segment": "enterprise",
  "acquisition_source": "google_ads",
  "lifetime_value": "high",
  "custom_field_1": "value1"
}
```

This integration enables comprehensive payment and subscription management automation, allowing your AI agents to handle billing operations seamlessly within your Stripe ecosystem.


# Zendesk Integration
Source: https://docs-platform.crewai.com/platform/en/integrations/zendesk

Customer support and helpdesk management with Zendesk integration for CrewAI.

## Overview

Enable your agents to manage customer support operations through Zendesk. Create and update tickets, manage users, track support metrics, and streamline your customer service workflows with AI-powered automation.

## Prerequisites

Before using the Zendesk integration, ensure you have:

* A [CrewAI AMP](https://app.crewai.com) account with an active subscription
* A Zendesk account with appropriate API permissions
* Connected your Zendesk account through the [Integrations page](https://app.crewai.com/integrations)

## Setting Up Zendesk Integration

### 1. Connect Your Zendesk Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Zendesk** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for ticket and user management
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash theme={null}
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 theme={null}
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Tools

### **Ticket Management**

<AccordionGroup>
  <Accordion title="zendesk/create_ticket">
    **Description:** Create a new support ticket in Zendesk.

    **Parameters:**

    * `ticketSubject` (string, required): Ticket subject line (e.g., "Help, my printer is on fire!")
    * `ticketDescription` (string, required): First comment that appears on the ticket (e.g., "The smoke is very colorful.")
    * `requesterName` (string, required): Name of the user requesting support (e.g., "Jane Customer")
    * `requesterEmail` (string, required): Email of the user requesting support (e.g., "[jane@example.com](mailto:jane@example.com)")
    * `assigneeId` (string, optional): Zendesk Agent ID assigned to this ticket - Use Connect Portal Workflow Settings to allow users to select an assignee
    * `ticketType` (string, optional): Ticket type - Options: problem, incident, question, task
    * `ticketPriority` (string, optional): Priority level - Options: urgent, high, normal, low
    * `ticketStatus` (string, optional): Ticket status - Options: new, open, pending, hold, solved, closed
    * `ticketDueAt` (string, optional): Due date for task-type tickets (ISO 8601 timestamp)
    * `ticketTags` (string, optional): Array of tags to apply (e.g., `["enterprise", "other_tag"]`)
    * `ticketExternalId` (string, optional): External ID to link tickets to local records
    * `ticketCustomFields` (object, optional): Custom field values in JSON format
  </Accordion>

  <Accordion title="zendesk/update_ticket">
    **Description:** Update an existing support ticket in Zendesk.

    **Parameters:**

    * `ticketId` (string, required): ID of the ticket to update (e.g., "35436")
    * `ticketSubject` (string, optional): Updated ticket subject
    * `requesterName` (string, required): Name of the user who requested this ticket
    * `requesterEmail` (string, required): Email of the user who requested this ticket
    * `assigneeId` (string, optional): Updated assignee ID - Use Connect Portal Workflow Settings
    * `ticketType` (string, optional): Updated ticket type - Options: problem, incident, question, task
    * `ticketPriority` (string, optional): Updated priority - Options: urgent, high, normal, low
    * `ticketStatus` (string, optional): Updated status - Options: new, open, pending, hold, solved, closed
    * `ticketDueAt` (string, optional): Updated due date (ISO 8601 timestamp)
    * `ticketTags` (string, optional): Updated tags array
    * `ticketExternalId` (string, optional): Updated external ID
    * `ticketCustomFields` (object, optional): Updated custom field values
  </Accordion>

  <Accordion title="zendesk/get_ticket_by_id">
    **Description:** Retrieve a specific ticket by its ID.

    **Parameters:**

    * `ticketId` (string, required): The ticket ID to retrieve (e.g., "35436")
  </Accordion>

  <Accordion title="zendesk/add_comment_to_ticket">
    **Description:** Add a comment or internal note to an existing ticket.

    **Parameters:**

    * `ticketId` (string, required): ID of the ticket to add comment to (e.g., "35436")
    * `commentBody` (string, required): Comment message (accepts plain text or HTML, e.g., "Thanks for your help!")
    * `isInternalNote` (boolean, optional): Set to true for internal notes instead of public replies (defaults to false)
    * `isPublic` (boolean, optional): True for public comments, false for internal notes
  </Accordion>

  <Accordion title="zendesk/search_tickets">
    **Description:** Search for tickets using various filters and criteria.

    **Parameters:**

    * `ticketSubject` (string, optional): Filter by text in ticket subject
    * `ticketDescription` (string, optional): Filter by text in ticket description and comments
    * `ticketStatus` (string, optional): Filter by status - Options: new, open, pending, hold, solved, closed
    * `ticketType` (string, optional): Filter by type - Options: problem, incident, question, task, no\_type
    * `ticketPriority` (string, optional): Filter by priority - Options: urgent, high, normal, low, no\_priority
    * `requesterId` (string, optional): Filter by requester user ID
    * `assigneeId` (string, optional): Filter by assigned agent ID
    * `recipientEmail` (string, optional): Filter by original recipient email address
    * `ticketTags` (string, optional): Filter by ticket tags
    * `ticketExternalId` (string, optional): Filter by external ID
    * `createdDate` (object, optional): Filter by creation date with operator (EQUALS, LESS\_THAN\_EQUALS, GREATER\_THAN\_EQUALS) and value
    * `updatedDate` (object, optional): Filter by update date with operator and value
    * `dueDate` (object, optional): Filter by due date with operator and value
    * `sort_by` (string, optional): Sort field - Options: created\_at, updated\_at, priority, status, ticket\_type
    * `sort_order` (string, optional): Sort direction - Options: asc, desc
  </Accordion>
</AccordionGroup>

### **User Management**

<AccordionGroup>
  <Accordion title="zendesk/create_user">
    **Description:** Create a new user in Zendesk.

    **Parameters:**

    * `name` (string, required): User's full name
    * `email` (string, optional): User's email address (e.g., "[jane@example.com](mailto:jane@example.com)")
    * `phone` (string, optional): User's phone number
    * `role` (string, optional): User role - Options: admin, agent, end-user
    * `externalId` (string, optional): Unique identifier from another system
    * `details` (string, optional): Additional user details
    * `notes` (string, optional): Internal notes about the user
  </Accordion>

  <Accordion title="zendesk/update_user">
    **Description:** Update an existing user's information.

    **Parameters:**

    * `userId` (string, required): ID of the user to update
    * `name` (string, optional): Updated user name
    * `email` (string, optional): Updated email (adds as secondary email on update)
    * `phone` (string, optional): Updated phone number
    * `role` (string, optional): Updated role - Options: admin, agent, end-user
    * `externalId` (string, optional): Updated external ID
    * `details` (string, optional): Updated user details
    * `notes` (string, optional): Updated internal notes
  </Accordion>

  <Accordion title="zendesk/get_user_by_id">
    **Description:** Retrieve a specific user by their ID.

    **Parameters:**

    * `userId` (string, required): The user ID to retrieve
  </Accordion>

  <Accordion title="zendesk/search_users">
    **Description:** Search for users using various criteria.

    **Parameters:**

    * `name` (string, optional): Filter by user name
    * `email` (string, optional): Filter by user email (e.g., "[jane@example.com](mailto:jane@example.com)")
    * `role` (string, optional): Filter by role - Options: admin, agent, end-user
    * `externalId` (string, optional): Filter by external ID
    * `sort_by` (string, optional): Sort field - Options: created\_at, updated\_at
    * `sort_order` (string, optional): Sort direction - Options: asc, desc
  </Accordion>
</AccordionGroup>

### **Administrative Tools**

<AccordionGroup>
  <Accordion title="zendesk/get_ticket_fields">
    **Description:** Retrieve all standard and custom fields available for tickets.

    **Parameters:**

    * `paginationParameters` (object, optional): Pagination settings
      * `pageCursor` (string, optional): Page cursor for pagination
  </Accordion>

  <Accordion title="zendesk/get_ticket_audits">
    **Description:** Get audit records (read-only history) for tickets.

    **Parameters:**

    * `ticketId` (string, optional): Get audits for specific ticket (if empty, retrieves audits for all non-archived tickets, e.g., "1234")
    * `paginationParameters` (object, optional): Pagination settings
      * `pageCursor` (string, optional): Page cursor for pagination
  </Accordion>
</AccordionGroup>

## Custom Fields

Custom fields allow you to store additional information specific to your organization:

```json theme={null}
[
  { "id": 27642, "value": "745" },
  { "id": 27648, "value": "yes" }
]
```

## Ticket Priority Levels

Understanding priority levels:

* **urgent** - Critical issues requiring immediate attention
* **high** - Important issues that should be addressed quickly
* **normal** - Standard priority for most tickets
* **low** - Minor issues that can be addressed when convenient

## Ticket Status Workflow

Standard ticket status progression:

* **new** - Recently created, not yet assigned
* **open** - Actively being worked on
* **pending** - Waiting for customer response or external action
* **hold** - Temporarily paused
* **solved** - Issue resolved, awaiting customer confirmation
* **closed** - Ticket completed and closed

## Usage Examples

### Basic Zendesk Agent Setup

```python theme={null}
from crewai import Agent, Task, Crew
from crewai import Agent, Task, Crew

# Create an agent with Zendesk capabilities
zendesk_agent = Agent(
    role="Support Manager",
    goal="Manage customer support tickets and provide excellent customer service",
    backstory="An AI assistant specialized in customer support operations and ticket management.",
    apps=['zendesk']  # All Zendesk actions will be available
)

# Task to create a new support ticket
create_ticket_task = Task(
    description="Create a high-priority support ticket for John Smith who is unable to access his account after password reset",
    agent=zendesk_agent,
    expected_output="Support ticket created successfully with ticket ID"
)

# Run the task
crew = Crew(
    agents=[zendesk_agent],
    tasks=[create_ticket_task]
)

crew.kickoff()
```

### Filtering Specific Zendesk Tools

```python theme={null}
from crewai import Agent, Task, Crew

# Create agent with specific Zendesk actions only
support_agent = Agent(
    role="Customer Support Agent",
    goal="Handle customer inquiries and resolve support issues efficiently",
    backstory="An experienced support agent who specializes in ticket resolution and customer communication.",
    apps=['zendesk/create_ticket']  # Specific Zendesk actions
)

# Task to manage support workflow
support_task = Task(
    description="Create a ticket for login issues, add troubleshooting comments, and update status to resolved",
    agent=support_agent,
    expected_output="Support ticket managed through complete resolution workflow"
)

crew = Crew(
    agents=[support_agent],
    tasks=[support_task]
)

crew.kickoff()
```

### Advanced Ticket Management

```python theme={null}
from crewai import Agent, Task, Crew

ticket_manager = Agent(
    role="Ticket Manager",
    goal="Manage support ticket workflows and ensure timely resolution",
    backstory="An AI assistant that specializes in support ticket triage and workflow optimization.",
    apps=['zendesk']
)

# Task to manage ticket lifecycle
ticket_workflow = Task(
    description="""
    1. Create a new support ticket for account access issues
    2. Add internal notes with troubleshooting steps
    3. Update ticket priority based on customer tier
    4. Add resolution comments and close the ticket
    """,
    agent=ticket_manager,
    expected_output="Complete ticket lifecycle managed from creation to resolution"
)

crew = Crew(
    agents=[ticket_manager],
    tasks=[ticket_workflow]
)

crew.kickoff()
```

### Support Analytics and Reporting

```python theme={null}
from crewai import Agent, Task, Crew

support_analyst = Agent(
    role="Support Analyst",
    goal="Analyze support metrics and generate insights for team performance",
    backstory="An analytical AI that excels at extracting insights from support data and ticket patterns.",
    apps=['zendesk']
)

# Complex task involving analytics and reporting
analytics_task = Task(
    description="""
    1. Search for all open tickets from the last 30 days
    2. Analyze ticket resolution times and customer satisfaction
    3. Identify common issues and support patterns
    4. Generate weekly support performance report
    """,
    agent=support_analyst,
    expected_output="Comprehensive support analytics report with performance insights and recommendations"
)

crew = Crew(
    agents=[support_analyst],
    tasks=[analytics_task]
)

crew.kickoff()
```


# CrewAI AMP
Source: https://docs-platform.crewai.com/platform/en/introduction

Deploy, monitor, and scale your AI agent workflows

## Introduction

CrewAI AMP(Agent Management Platform) provides a platform for deploying, monitoring, and scaling your crews and agents in a production environment.

<Frame>
  <img alt="CrewAI AMP Dashboard" />
</Frame>

CrewAI AMP extends the power of the open-source framework with features designed for production deployments, collaboration, and scalability. Deploy your crews to a managed infrastructure and monitor their execution in real-time.

## Key Features

<CardGroup>
  <Card title="Crew Deployments" icon="rocket">
    Deploy your crews to a managed infrastructure with a few clicks
  </Card>

  <Card title="API Access" icon="code">
    Access your deployed crews via REST API for integration with existing
    systems
  </Card>

  <Card title="Observability" icon="chart-line">
    Monitor your crews with detailed execution traces and logs
  </Card>

  <Card title="Tool Repository" icon="toolbox">
    Publish and install tools to enhance your crews' capabilities
  </Card>

  <Card title="Webhook Streaming" icon="webhook">
    Stream real-time events and updates to your systems
  </Card>

  <Card title="Crew Studio" icon="paintbrush">
    Create and customize crews using a no-code/low-code interface
  </Card>
</CardGroup>

## Deployment Options

<CardGroup>
  <Card title="GitHub Integration" icon="github">
    Connect directly to your GitHub repositories to deploy code
  </Card>

  <Card title="Crew Studio" icon="palette">
    Deploy crews created through the no-code Crew Studio interface
  </Card>

  <Card title="CLI Deployment" icon="terminal">
    Use the CrewAI CLI for more advanced deployment workflows
  </Card>
</CardGroup>

## Getting Started

<Steps>
  <Step title="Sign up for an account">
    Create your account at [app.crewai.com](https://app.crewai.com)

    <Card title="Sign Up" icon="user" href="https://app.crewai.com/signup">
      Sign Up
    </Card>
  </Step>

  <Step title="Build your first crew">
    Use code or Crew Studio to build your crew

    <Card title="Build Crew" icon="paintbrush" href="/platform/en/guides/build-crew">
      Build Crew
    </Card>
  </Step>

  <Step title="Deploy your crew">
    Deploy your crew to the Enterprise platform

    <Card title="Deploy Crew" icon="rocket" href="/platform/en/guides/deploy-to-amp">
      Deploy Crew
    </Card>
  </Step>

  <Step title="Access your crew">
    Integrate with your crew via the generated API endpoints

    <Card title="API Access" icon="code" href="/platform/en/guides/kickoff-crew">
      Use the Crew API
    </Card>
  </Step>
</Steps>

For detailed instructions, check out our [deployment guide](/platform/en/guides/deploy-to-amp) or click the button below to get started.


# FAQs
Source: https://docs-platform.crewai.com/platform/en/resources/frequently-asked-questions

Frequently asked questions about CrewAI AMP

<AccordionGroup>
  <Accordion title="How is task execution handled in the hierarchical process?">
    In the hierarchical process, a manager agent is automatically created and coordinates the workflow, delegating tasks and validating outcomes for streamlined and effective execution. The manager agent utilizes tools to facilitate task delegation and execution by agents under the manager's guidance. The manager LLM is crucial for the hierarchical process and must be set up correctly for proper function.
  </Accordion>

  <Accordion title="Where can I get the latest CrewAI documentation?">
    The most up-to-date documentation for CrewAI is available on our official documentation website: [https://docs.crewai.com/](https://docs.crewai.com/)
    <Card href="https://docs.crewai.com/" icon="books">CrewAI Docs</Card>
  </Accordion>

  <Accordion title="What are the key differences between Hierarchical and Sequential Processes in CrewAI?">
    #### Hierarchical Process:

    * Tasks are delegated and executed based on a structured chain of command
    * A manager language model (`manager_llm`) must be specified for the manager agent
    * Manager agent oversees task execution, planning, delegation, and validation
    * Tasks are not pre-assigned; the manager allocates tasks to agents based on their capabilities

    #### Sequential Process:

    * Tasks are executed one after another, ensuring tasks are completed in an orderly progression
    * Output of one task serves as context for the next
    * Task execution follows the predefined order in the task list

    #### Which Process is Better for Complex Projects?

    The hierarchical process is better suited for complex projects because it allows for:

    * **Dynamic task allocation and delegation**: Manager agent can assign tasks based on agent capabilities
    * **Structured validation and oversight**: Manager agent reviews task outputs and ensures completion
    * **Complex task management**: Precise control over tool availability at the agent level
  </Accordion>

  <Accordion title="What are the benefits of using memory in the CrewAI framework?">
    * **Adaptive Learning**: Crews become more efficient over time, adapting to new information and refining their approach to tasks
    * **Enhanced Personalization**: Memory enables agents to remember user preferences and historical interactions, leading to personalized experiences
    * **Improved Problem Solving**: Access to a rich memory store aids agents in making more informed decisions, drawing on past learnings and contextual insights
  </Accordion>

  <Accordion title="What is the purpose of setting a maximum RPM limit for an agent?">
    Setting a maximum RPM limit for an agent prevents the agent from making too many requests to external services, which can help to avoid rate limits and improve performance.
  </Accordion>

  <Accordion title="What role does human input play in the execution of tasks within a CrewAI crew?">
    Human input allows agents to request additional information or clarification when necessary. This feature is crucial in complex decision-making processes or when agents require more details to complete a task effectively.

    To integrate human input into agent execution, set the `human_input` flag in the task definition. When enabled, the agent prompts the user for input before delivering its final answer. This input can provide extra context, clarify ambiguities, or validate the agent's output.

    For detailed implementation guidance, see our [Human-in-the-Loop guide](/platform/en/guides/human-in-the-loop).
  </Accordion>

  <Accordion title="What advanced customization options are available for tailoring and enhancing agent behavior and capabilities in CrewAI?">
    CrewAI provides a range of advanced customization options:

    * **Language Model Customization**: Agents can be customized with specific language models (`llm`) and function-calling language models (`function_calling_llm`)
    * **Performance and Debugging Settings**: Adjust an agent's performance and monitor its operations
    * **Verbose Mode**: Enables detailed logging of an agent's actions, useful for debugging and optimization
    * **RPM Limit**: Sets the maximum number of requests per minute (`max_rpm`)
    * **Maximum Iterations**: The `max_iter` attribute allows users to define the maximum number of iterations an agent can perform for a single task
    * **Delegation and Autonomy**: Control an agent's ability to delegate or ask questions with the `allow_delegation` attribute (default: True)
    * **Human Input Integration**: Agents can request additional information or clarification when necessary
  </Accordion>

  <Accordion title="In what scenarios is human input particularly useful in agent execution?">
    Human input is particularly useful when:

    * **Agents require additional information or clarification**: When agents encounter ambiguity or incomplete data
    * **Agents need to make complex or sensitive decisions**: Human input can assist in ethical or nuanced decision-making
    * **Oversight and validation of agent output**: Human input can help validate results and prevent errors
    * **Customizing agent behavior**: Human input can provide feedback to refine agent responses over time
    * **Identifying and resolving errors or limitations**: Human input helps address agent capability gaps
  </Accordion>

  <Accordion title="What are the different types of memory that are available in crewAI?">
    The different types of memory available in CrewAI are:

    * **Short-term memory**: Temporary storage for immediate context
    * **Long-term memory**: Persistent storage for learned patterns and information
    * **Entity memory**: Focused storage for specific entities and their attributes
    * **Contextual memory**: Memory that maintains context across interactions

    Learn more about the different types of memory:
    <Card href="https://docs.crewai.com/concepts/memory" icon="brain">CrewAI Memory</Card>
  </Accordion>

  <Accordion title="How do I use Output Pydantic in a Task?">
    To use Output Pydantic in a task, you need to define the expected output of the task as a Pydantic model. Here's a quick example:

    <Steps>
      <Step title="Define a Pydantic model">
        ```python theme={null}
        from pydantic import BaseModel

        class User(BaseModel):
            name: str
            age: int
        ```
      </Step>

      <Step title="Create a task with Output Pydantic">
        ```python theme={null}
        from crewai import Task, Crew, Agent
        from my_models import User

        task = Task(
            description="Create a user with the provided name and age",
            expected_output=User,  # This is the Pydantic model
            agent=agent,
            tools=[tool1, tool2]
        )
        ```
      </Step>

      <Step title="Set the output_pydantic attribute in your agent">
        ```python theme={null}
        from crewai import Agent
        from my_models import User

        agent = Agent(
            role='User Creator',
            goal='Create users',
            backstory='I am skilled in creating user accounts',
            tools=[tool1, tool2],
            output_pydantic=User
        )
        ```
      </Step>
    </Steps>

    Here's a tutorial on how to consistently get structured outputs from your agents:

    <iframe title="Structured outputs in CrewAI" />
  </Accordion>

  <Accordion title="How can I create custom tools for my CrewAI agents?">
    You can create custom tools by subclassing the `BaseTool` class provided by CrewAI or by using the tool decorator. Subclassing involves defining a new class that inherits from `BaseTool`, specifying the name, description, and the `_run` method for operational logic. The tool decorator allows you to create a `Tool` object directly with the required attributes and a functional logic.

    <Card href="https://docs.crewai.com/en/learn/create-custom-tools" icon="code">CrewAI Tools Guide</Card>
  </Accordion>

  <Accordion title="How can you control the maximum number of requests per minute that the entire crew can perform?">
    The `max_rpm` attribute sets the maximum number of requests per minute the crew can perform to avoid rate limits and will override individual agents' `max_rpm` settings if you set it.
  </Accordion>
</AccordionGroup>


# Export an Automation ZIP
Source: https://docs-platform.crewai.com/api/v1/reference/automations/export-an-automation-zip

/openapi/platform-v1.yaml get /api/v1/automations/{id}/export
Downloads an Automation source archive as a ZIP file.



# List a service account's teams
Source: https://docs-platform.crewai.com/api/v1/reference/service-accounts/list-a-service-accounts-teams

/openapi/platform-v1.yaml get /api/v1/service-accounts/{service_account_id}/teams
Returns teams the service account belongs to that the caller is allowed to manage.



# Check API status
Source: https://docs-platform.crewai.com/api/v1/reference/status/check-api-status

/openapi/platform-v1.yaml get /api/v1/status
Returns whether the public API is available.



# Add a service account to a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/add-a-service-account-to-a-team

/openapi/platform-v1.yaml post /api/v1/teams/{team_id}/service-accounts
Adds a service account from the organization to a team. If the service account
already belongs to the team, the existing membership is returned rather than
treated as an error. Both a new membership and an existing one respond with 201.




# Add a user to a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/add-a-user-to-a-team

/openapi/platform-v1.yaml post /api/v1/teams/{team_id}/users
Adds a user from the organization to a team. If the user already belongs to the
team, the existing membership is returned rather than treated as an error.
Both a new membership and an existing one respond with 201.




# Assign a role to a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/assign-a-role-to-a-team

/openapi/platform-v1.yaml post /api/v1/teams/{team_id}/granted-roles
Grants a role to a customer-owned team, scoped to a single record or to the whole organization. CrewAI-managed teams reject a role change.



# Create a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/create-a-team

/openapi/platform-v1.yaml post /api/v1/teams
Creates a customer-owned team in the organization associated with the authenticated service account. CrewAI-managed teams cannot be created through the API.



# Delete a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/delete-a-team

/openapi/platform-v1.yaml delete /api/v1/teams/{id}
Deletes a customer-owned team in the organization associated with the authenticated service account. CrewAI-managed teams cannot be deleted.



# Get a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/get-a-team

/openapi/platform-v1.yaml get /api/v1/teams/{id}
Returns a team in the organization associated with the authenticated service account.



# List team granted roles
Source: https://docs-platform.crewai.com/api/v1/reference/teams/list-team-granted-roles

/openapi/platform-v1.yaml get /api/v1/teams/{team_id}/granted-roles
Returns roles granted to a team in the organization associated with the authenticated service account.



# List team service accounts
Source: https://docs-platform.crewai.com/api/v1/reference/teams/list-team-service-accounts

/openapi/platform-v1.yaml get /api/v1/teams/{team_id}/service-accounts
Returns service accounts who belong to a team in the organization associated with the authenticated service account.



# List team users
Source: https://docs-platform.crewai.com/api/v1/reference/teams/list-team-users

/openapi/platform-v1.yaml get /api/v1/teams/{team_id}/users
Returns users who belong to a team in the organization associated with the authenticated service account.



# List teams
Source: https://docs-platform.crewai.com/api/v1/reference/teams/list-teams

/openapi/platform-v1.yaml get /api/v1/teams
Returns teams in the authenticated service account's organization that the caller is allowed to manage.



# Remove a service account from a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/remove-a-service-account-from-a-team

/openapi/platform-v1.yaml delete /api/v1/teams/{team_id}/service-accounts/{id}
Removes a service account from a team in the organization associated with the authenticated service account.



# Remove a user from a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/remove-a-user-from-a-team

/openapi/platform-v1.yaml delete /api/v1/teams/{team_id}/users/{id}
Removes a user from a team in the organization associated with the authenticated service account.



# Revoke a team granted role
Source: https://docs-platform.crewai.com/api/v1/reference/teams/revoke-a-team-granted-role

/openapi/platform-v1.yaml delete /api/v1/teams/{team_id}/granted-roles/{id}
Revokes an active role granted to a customer-owned team in the organization
associated with the authenticated service account. CrewAI-managed teams reject a
role change. The granted role stays in the platform for audit purposes, so this
does not delete it. Later requests for it return not found.




# Update a team
Source: https://docs-platform.crewai.com/api/v1/reference/teams/update-a-team

/openapi/platform-v1.yaml patch /api/v1/teams/{id}
Updates a customer-owned team's name or description in the organization associated with the authenticated service account. CrewAI-managed teams reject a name change.



# Assign a role to a user
Source: https://docs-platform.crewai.com/api/v1/reference/users/assign-a-role-to-a-user

/openapi/platform-v1.yaml post /api/v1/users/{user_id}/granted-roles
Assigns a role to a user in the organization associated with the authenticated service account.



# Create invitations
Source: https://docs-platform.crewai.com/api/v1/reference/users/create-invitations

/openapi/platform-v1.yaml post /api/v1/invites
Creates pending invitations in the organization associated with the authenticated service account. Invitation emails are sent asynchronously.



# List a user's teams
Source: https://docs-platform.crewai.com/api/v1/reference/users/list-a-users-teams

/openapi/platform-v1.yaml get /api/v1/users/{user_id}/teams
Returns teams the user belongs to that the caller is allowed to manage.



# List roles
Source: https://docs-platform.crewai.com/api/v1/reference/users/list-roles

/openapi/platform-v1.yaml get /api/v1/roles
Returns all roles available for grant assignments.



# List user granted roles
Source: https://docs-platform.crewai.com/api/v1/reference/users/list-user-granted-roles

/openapi/platform-v1.yaml get /api/v1/users/{user_id}/granted-roles
Returns roles granted to a user in the organization associated with the authenticated service account.



# List users
Source: https://docs-platform.crewai.com/api/v1/reference/users/list-users

/openapi/platform-v1.yaml get /api/v1/users
Returns users that belong to the organization associated with the authenticated service account.



# Remove user
Source: https://docs-platform.crewai.com/api/v1/reference/users/remove-user

/openapi/platform-v1.yaml delete /api/v1/users/{id}
Removes a user's membership from the organization associated with the authenticated service account. The user record is not deleted.



# Revoke a granted role
Source: https://docs-platform.crewai.com/api/v1/reference/users/revoke-a-granted-role

/openapi/platform-v1.yaml delete /api/v1/users/{user_id}/granted-roles/{id}
Revokes an active granted role held by a user in the organization associated with the
authenticated service account. The granted role stays in the platform for audit
purposes, so this does not delete it. Later requests for it return not found.