andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-07-08 16:35:08 +00:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

feat: adopt directory-based docs versioning with Edge channel

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

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

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

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

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

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

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

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

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

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

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

227
docs/edge/en/enterprise/features/a2a.mdx Normal file
View File

@@ -0,0 +1,227 @@
---
title: A2A on AMP
description: Production-grade Agent-to-Agent communication with distributed state and multi-scheme authentication
icon: "network-wired"
mode: "wide"
---
<Warning>
A2A server agents on AMP are in early release. APIs may change in future versions.
</Warning>
## Overview
CrewAI AMP extends the open-source [A2A protocol implementation](/en/learn/a2a-agent-delegation) with production infrastructure for deploying distributed agents at scale. AMP supports A2A protocol versions 0.2 and 0.3. When you deploy a crew or agent with A2A server configuration to AMP, the platform automatically provisions distributed state management, authentication, multi-transport endpoints, and lifecycle management.
<Note>
For A2A protocol fundamentals, client/server configuration, and authentication schemes, see the [A2A Agent Delegation](/en/learn/a2a-agent-delegation) documentation. This page covers what AMP adds on top of the open-source implementation.
</Note>
### Usage
Add `A2AServerConfig` to any agent in your crew and deploy to AMP. The platform detects agents with server configuration and automatically registers A2A endpoints, generates agent cards, and provisions the infrastructure described below.
```python
from crewai import Agent, Crew, Task
from crewai.a2a import A2AServerConfig
from crewai.a2a.auth import EnterpriseTokenAuth
agent = Agent(
role="Data Analyst",
goal="Analyze datasets and provide insights",
backstory="Expert data scientist with statistical analysis skills",
llm="gpt-4o",
a2a=A2AServerConfig(
auth=EnterpriseTokenAuth()
)
)
task = Task(
description="Analyze the provided dataset",
expected_output="Statistical summary with key insights",
agent=agent
)
crew = Crew(agents=[agent], tasks=[task])
```
After [deploying to AMP](/en/enterprise/guides/deploy-to-amp), the platform registers two levels of A2A endpoints:
- **Crew-level**: an aggregate agent card at `/.well-known/agent-card.json` where each agent with `A2AServerConfig` is listed as a skill, with a JSON-RPC endpoint at `/a2a`
- **Per-agent**: isolated agent cards and JSON-RPC endpoints mounted at `/a2a/agents/{role}/`, each with its own tenancy
Clients can interact with the crew as a whole or target a specific agent directly. To route a request to a specific agent through the crew-level endpoint, include `"target_agent"` in the message metadata with the agent's slugified role name (e.g., `"data-analyst"` for an agent with role `"Data Analyst"`). If no `target_agent` is provided, the request is handled by the first agent in the crew.
See [A2A Agent Delegation](/en/learn/a2a-agent-delegation#server-configuration-options) for the full list of `A2AServerConfig` options.
<Warning>
Per the A2A protocol, agent cards are publicly accessible to enable discovery. This includes both the crew-level card at `/.well-known/agent-card.json` and per-agent cards at `/a2a/agents/{role}/.well-known/agent-card.json`. Do not include sensitive information in agent names, descriptions, or skill definitions.
</Warning>
### File Inputs and Structured Output
A2A on AMP supports passing files and requesting structured output in both directions. Clients can send files as `FilePart`s and request structured responses by embedding a JSON schema in the message. Server agents receive files as `input_files` on the task, and return structured data as `DataPart`s when a schema is provided. See [File Inputs and Structured Output](/en/learn/a2a-agent-delegation#file-inputs-and-structured-output) for details.
### What AMP Adds
<CardGroup cols={2}>
<Card title="Distributed State" icon="database">
Persistent task, context, and result storage
</Card>
<Card title="Enterprise Authentication" icon="shield-halved">
OIDC, OAuth2, mTLS, and Enterprise token validation beyond simple bearer tokens
</Card>
<Card title="gRPC Transport" icon="bolt">
Full gRPC server with TLS and authentication
</Card>
<Card title="Context Lifecycle" icon="clock-rotate-left">
Automatic idle detection, expiration, and cleanup of long-running conversations
</Card>
<Card title="Signed Webhooks" icon="signature">
HMAC-SHA256 signed push notifications with replay protection
</Card>
<Card title="Multi-Transport" icon="arrows-split-up-and-left">
REST, JSON-RPC, and gRPC endpoints served simultaneously from a single deployment
</Card>
</CardGroup>
---
## Distributed State Management
In the open-source implementation, task and context state lives in memory on a single process. AMP replaces this with persistent, distributed stores.
### Storage Layers
| Store | Purpose |
|---|---|
| **Task Store** | Persists A2A task state and metadata |
| **Context Store** | Tracks conversation context, creation time, last activity, and associated tasks |
| **Result Store** | Caches task results for retrieval |
| **Push Config Store** | Manages webhook subscriptions per task |
Multiple A2A deployments are automatically isolated from each other, preventing data collisions when sharing infrastructure.
---
## Enterprise Authentication
AMP supports six authentication schemes for incoming A2A requests, configurable per deployment. Authentication works across both HTTP and gRPC transports.
| Scheme | Description | Use Case |
|---|---|---|
| **SimpleTokenAuth** | Static bearer token from `AUTH_TOKEN` env var | Development, simple deployments |
| **EnterpriseTokenAuth** | Token verification via CrewAI PlusAPI with integration token claims | AMP-to-AMP agent communication |
| **OIDCAuth** | OpenID Connect JWT validation with JWKS endpoint caching | Enterprise SSO integration |
| **OAuth2ServerAuth** | OAuth2 with configurable scopes | Fine-grained access control |
| **APIKeyServerAuth** | API key validation via header or query parameter | Third-party integrations |
| **MTLSServerAuth** | Mutual TLS certificate-based authentication | Zero-trust environments |
The configured auth scheme automatically populates the agent card's `securitySchemes` and `security` fields. Clients discover authentication requirements by fetching the agent card before making requests.
---
## Extended Agent Cards
AMP supports role-based skill visibility through extended agent cards. Unauthenticated users see the standard agent card with public skills. Authenticated users receive an extended card with additional capabilities.
This enables patterns like:
- Public agents that expose basic skills to anyone, with advanced skills available to authenticated clients
- Internal agents that advertise different capabilities based on the caller's identity
---
## gRPC Transport
If enabled, AMP provides full gRPC support alongside the default JSON-RPC transport.
- **TLS termination** with configurable certificate and key paths
- **gRPC reflection** for debugging with tools like `grpcurl`
- **Authentication** using the same schemes available for HTTP
- **Extension validation** ensuring clients support required protocol extensions
- **Version negotiation** across A2A protocol versions 0.2 and 0.3
For deployments exposing multiple agents, AMP automatically allocates per-agent gRPC ports and coordinates TLS, startup, and shutdown across all servers.
---
## Context Lifecycle Management
AMP tracks the lifecycle of A2A conversation contexts and automatically manages cleanup.
### Lifecycle States
| State | Condition | Action |
|---|---|---|
| **Active** | Context has recent activity | None |
| **Idle** | No activity for a configured period | Marked idle, event emitted |
| **Expired** | Context exceeds its maximum lifetime | Marked expired, associated tasks cleaned up, event emitted |
A background cleanup task runs hourly to scan for idle and expired contexts. All state transitions emit CrewAI events that integrate with the platform's observability features.
---
## Signed Push Notifications
When an A2A agent sends push notifications to a client webhook, AMP signs each request with HMAC-SHA256 to ensure integrity and prevent tampering.
### Signature Headers
| Header | Purpose |
|---|---|
| `X-A2A-Signature` | HMAC-SHA256 signature in `sha256={hex_digest}` format |
| `X-A2A-Signature-Timestamp` | Unix timestamp bound to the signature |
| `X-A2A-Notification-Token` | Optional notification auth token |
### Security Properties
- **Integrity**: payload cannot be modified without invalidating the signature
- **Replay protection**: signatures are timestamp-bound with a configurable tolerance window
- **Retry with backoff**: failed deliveries retry with exponential backoff
---
## Distributed Event Streaming
In the open-source implementation, SSE streaming works within a single process. AMP propagates SSE events across instances so that clients receive updates even when the instance holding the streaming connection differs from the instance executing the task.
---
## Multi-Transport Endpoints
AMP serves REST and JSON-RPC by default. gRPC is available as an additional transport if enabled.
| Transport | Path Convention | Description |
|---|---|---|
| **REST** | `/v1/message:send`, `/v1/message:stream`, `/v1/tasks` | Google API conventions |
| **JSON-RPC** | Standard A2A JSON-RPC endpoint | Default A2A protocol transport |
| **gRPC** | Per-agent port allocation | Optional, high-performance binary protocol |
All active transports share the same authentication, version negotiation, and extension validation. Agent cards are generated from agent and crew metadata — roles, goals, and tools become skills and descriptions — and automatically include interfaces for each active transport. They can also be manually configured via `A2AServerConfig`.
---
## Version and Extension Negotiation
AMP validates A2A protocol versions and extensions at the transport layer.
### Version Negotiation
- Clients send the `A2A-Version` header with their preferred version
- AMP validates against supported versions (0.2, 0.3) and falls back to 0.3 if unspecified
- The negotiated version is returned in the response headers
### Extension Validation
- Clients declare supported extensions via the `X-A2A-Extensions` header
- AMP validates that clients support all extensions the agent requires
- Requests from clients missing required extensions receive an `UnsupportedExtensionError`
---
## Next Steps
- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — A2A protocol fundamentals and configuration
- [A2UI](/en/learn/a2ui) — Interactive UI rendering over A2A
- [Deploy to AMP](/en/enterprise/guides/deploy-to-amp) — General deployment guide
- [Webhook Streaming](/en/enterprise/features/webhook-streaming) — Event streaming for deployed automations

112
docs/edge/en/enterprise/features/agent-control-plane/monitoring.mdx Normal file
View File

@@ -0,0 +1,112 @@
---
title: "Watch your Automations"
description: "Watch fleet health, LLM consumption, and per-automation behavior from the Automations tab."
sidebarTitle: "Monitoring"
icon: "gauge"
mode: "wide"
---
<Info>
**ACP (Beta) Docs Navigation**
- [Overview](/en/enterprise/features/agent-control-plane/overview)
- **Monitoring** *(you are here)*
- [Rules](/en/enterprise/features/agent-control-plane/rules)
</Info>
## Overview
The **Automations** tab is the read-only operations view of the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview). It combines two metric cards, an interactive sankey, and two sub-tables — **Automations** and **Consumption** — that you can search, filter, and sort.
<Frame>
![Agent Control Plane overview](/images/enterprise/acp-overview-automations-sankey.png)
</Frame>
All charts and tables respect the **Last 24 hours / Last Week / Last 30 days** selector at the top right. Deltas compare the selected window against the previous one of the same length.
<Note>
Rows only show data for deployments on **crewAI v1.13 or higher** — older deployments appear in the *"We've detected N other automations that we can't display"* banner under the sankey and contribute zero metrics until they're updated and re-deployed. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements).
</Note>
## Dashboard
The header of the page has two metric cards and an interactive sankey. Clicking either card switches the sankey between two modes:
- **Health mode** — `Total Automations → status buckets (Critical / Warning / Healthy)`. Click a bucket to filter the Automations table to just those deployments.
- **Consumption mode** — `Model Providers → Automations → Total Cost`. Click a provider to filter the Consumption table to that provider.
| Card | What it shows |
|------|---------------|
| **Automations** | `active` automations (and total count), total `errors` in the window, currently `active executions` (and total in the window), with a delta vs the previous period. |
| **Consumption** | Total `cost` and `tokens used`, with a cost delta vs the previous period. |
<Frame>
![Overview with consumption sankey](/images/enterprise/acp-overview-consumption-sankey.png)
</Frame>
## Automations table
The **Automations** sub-tab is the per-deployment breakdown of fleet health. Each row is one deployed crew or flow.
<Frame>
![Automations table with health status breakdown](/images/enterprise/acp-automations-table.png)
</Frame>
| Column | What it shows |
|--------|---------------|
| **Automation** | Deployment name and any tags assigned to it (e.g. `production`, `financial`). |
| **Last execution** | Time since the most recent run. |
| **Health Status Breakdown** | Stacked bar of `Critical` / `Warning` / `Healthy` percentages for executions in the window. |
| **Executions with Errors** | Total failed executions in the window. |
| **PII detection applied** | `Yes` if a per-deployment PII config or a matching [PII rule](/en/enterprise/features/agent-control-plane/rules) is active. |
| **Executions** | Total executions in the window. |
| **Last updated** | When the deployment was last re-deployed. |
| **Crew Version** | The `crewai` version reported by the deployment. An info icon next to versions below `1.13` flags rows that can't contribute metrics. |
Search by name, filter by `Status` (`Healthy` / `Warning` / `Critical`), and sort by any column header. Click a deployment name to open the **Automation panel** (see below).
## Consumption table
The **Consumption** sub-tab is the per-deployment breakdown of LLM spend and token usage.
<Frame>
![Consumption table broken down by LLM provider](/images/enterprise/acp-consumption-table.png)
</Frame>
| Column | What it shows |
|--------|---------------|
| **Automation** | Deployment name. |
| **Last execution** | Time since the most recent run. |
| **Tokens used** | One row per LLM provider used by this automation, with the delta vs the previous period. |
| **Cost** | Cost per LLM provider, with the delta vs the previous period. |
| **Total cost** | Sum across all providers, with the delta. |
| **Executions** | Total executions in the window. |
| **Last updated** | When the deployment was last re-deployed. |
| **Crew Version** | The `crewai` version reported by the deployment. |
Filter by **LLM provider** and sort by `Cost`, `Executions`, or `Last run`.
<Info>
**Empty cells (`—` or `$0.00`) usually mean the deployment is below crewAI v1.13.** In the screenshot above, *Automation F* (`1.7.0`) and *Automation I* (`1.12.2`) show blanks for tokens and cost — their executions still run, but they don't emit the provider-level telemetry that powers this table. Update and re-deploy these crews to start collecting consumption data.
</Info>
## Related
<CardGroup cols={2}>
<Card title="Agent Control Plane — Overview" icon="book-open" href="/en/enterprise/features/agent-control-plane/overview">
What ACP is, requirements, plan tiers, and RBAC.
</Card>
<Card title="Agent Control Plane — Rules" icon="shield-check" href="/en/enterprise/features/agent-control-plane/rules">
Apply organization-wide PII Redaction rules across many automations.
</Card>
<Card title="Traces" icon="timeline" href="/en/enterprise/features/traces">
Drill into a single execution to see agent reasoning, tool calls, and token usage.
</Card>
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
Deploy a crew on a crewAI version that supports the Agent Control Plane.
</Card>
</CardGroup>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for help interpreting metrics in the Agent Control Plane.
</Card>

82
docs/edge/en/enterprise/features/agent-control-plane/overview.mdx Normal file
View File

@@ -0,0 +1,82 @@
---
title: Agent Control Plane Overview
description: "Single operations hub for live automations — fleet health, LLM consumption, and organization-wide policies in one place."
sidebarTitle: Overview
icon: "book-open"
---
<Info>
**ACP (Beta) Docs Navigation**
- **Overview** *(you are here)*
- [Monitoring](/en/enterprise/features/agent-control-plane/monitoring)
- [Rules](/en/enterprise/features/agent-control-plane/rules)
</Info>
## Overview
The **Agent Control Plane** (ACP) is the operations hub for everything you have running on CrewAI AMP. It is a single screen — split into **Automations** and **Rules** tabs — that lets your team:
- Monitor the **health** of every live automation (crew or flow), with `Critical` / `Warning` / `Healthy` breakdowns and execution counts.
- Track **LLM consumption** — tokens and cost — per automation, per provider, and per model, with a delta vs the previous period.
- Drill into any single automation or model provider for time-series charts and per-provider breakdowns.
- Apply organization-wide **Rules** (today: PII Redaction) across many automations at once instead of editing each deployment individually.
<Frame>
![Agent Control Plane overview](/images/enterprise/acp-overview-automations-sankey.png)
</Frame>
<Note>
The Agent Control Plane is currently labeled **Beta** in CrewAI Platform.
</Note>
The two tabs answer two different questions:
- **Automations** — *"How is my fleet behaving right now, and what is it costing me?"* See [Monitoring](/en/enterprise/features/agent-control-plane/monitoring).
- **Rules** — *"How do I enforce a policy (e.g. PII redaction) across many deployments without re-deploying each one?"* See [Rules](/en/enterprise/features/agent-control-plane/rules).
## Requirements
<Warning>
**crewAI v1.13 or higher** is required for an automation to populate any data on this page — health, executions, errors, tokens, and cost all flow through telemetry that lit up in `crewai==1.13`. Older deployments appear in the *"We've detected N other automations that we can't display"* banner and contribute zero rows until they are updated and re-deployed.
</Warning>
<Warning>
**Enterprise Plan or Ultra Plan** is required to create or edit [Rules](/en/enterprise/features/agent-control-plane/rules). Lower-tier organizations can open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* Monitoring (the Automations tab) is available on all plans where the feature is enabled.
</Warning>
- The **Agent Control Plane** feature must be enabled for your organization. If you don't see it in the sidebar, ask your account owner to request enablement.
- Inside ACP, [RBAC](/en/enterprise/features/rbac) governs access: `read` to view the dashboard and rules, `manage` to create, edit, toggle, or delete rules.
- All charts and tables can be scoped to the **Last 24 hours**, **Last Week**, or **Last 30 days** using the time selector at the top right. Deltas (`↑ 8 vs yesterday`, `↓ $20.57 vs yesterday`, etc.) compare the selected window against the previous one of the same length.
## What you can do here
<CardGroup cols={2}>
<Card title="Monitoring" icon="gauge" href="/en/enterprise/features/agent-control-plane/monitoring">
Watch fleet health and LLM spend with metric cards, an interactive sankey, per-automation tables, and drill-down side panels for any automation or provider.
</Card>
<Card title="Rules" icon="shield-check" href="/en/enterprise/features/agent-control-plane/rules">
Apply organization-wide PII Redaction policies scoped by tools and tags. Changes take effect on the next execution — no re-deploy required.
</Card>
</CardGroup>
## Related
<CardGroup cols={2}>
<Card title="Traces" icon="timeline" href="/en/enterprise/features/traces">
Drill into a single execution to see agent reasoning, tool calls, and token usage.
</Card>
<Card title="RBAC" icon="users" href="/en/enterprise/features/rbac">
Manage who can read the Agent Control Plane and who can edit rules.
</Card>
<Card title="PII Redaction for Traces" icon="lock" href="/en/enterprise/features/pii-trace-redactions">
Entity catalog and per-deployment PII configuration referenced by Rules.
</Card>
<Card title="Deploy to AMP" icon="rocket" href="/en/enterprise/guides/deploy-to-amp">
Deploy a crew on a crewAI version that supports the Agent Control Plane.
</Card>
</CardGroup>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for help interpreting metrics or designing rules.
</Card>

122
docs/edge/en/enterprise/features/agent-control-plane/rules.mdx Normal file
View File

@@ -0,0 +1,122 @@
---
title: "Set up the Rules"
description: "Apply organization-wide policies across many automations from a single place."
sidebarTitle: "Rules"
icon: "shield-check"
mode: "wide"
---
<Info>
**ACP (Beta) Docs Navigation**
- [Overview](/en/enterprise/features/agent-control-plane/overview)
- [Monitoring](/en/enterprise/features/agent-control-plane/monitoring)
- **Rules** *(you are here)*
</Info>
## Overview
Rules let you apply policies — today: **PII Redaction** — across many automations at once, instead of configuring each deployment individually. Open the **Rules** tab in the [Agent Control Plane](/en/enterprise/features/agent-control-plane/overview) to manage them.
<Frame>
![Rules list](/images/enterprise/acp-rules-list.png)
</Frame>
Each rule card shows the name, description, the **scope** the rule applies to (selected tools and tags), and a count of **engaged automations** — deployments that currently match the scope. The toggle on the right enables or disables the rule without deleting it.
## Requirements
<Warning>
**Enterprise Plan or Ultra Plan** is required to create or edit PII Redaction rules. Lower-tier organizations can still open the Rules tab and view existing rules, but the editor renders read-only with an "Enterprise" lock pill and the alert *"PII Redaction rules require an Enterprise plan."* — contact your account owner or sales to upgrade.
</Warning>
- The **Agent Control Plane** feature must be enabled for your organization. See [Overview — Requirements](/en/enterprise/features/agent-control-plane/overview#requirements).
- The `manage` [RBAC permission](/en/enterprise/features/rbac) on Agent Control Plane is required to create, edit, toggle, or delete rules. The `read` permission is enough to view them.
- All rule changes are versioned for auditing.
## Available rule types
| Type | What it does |
|------|---------------|
| **PII Redaction** | Applies PII redaction to executions of every matching automation, using the same entity catalog and custom recognizers documented in [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions). |
More rule types will be added over time.
## Creating a rule
<Frame>
<img src="/images/enterprise/acp-rules-edit-side-panel.png" alt="Rule edit side panel with conditions and PII mask type" width="450" />
</Frame>
<Steps>
<Step title="Open the editor">
Click **+ Create new** at the top-right of the Rules tab, or **View Details** on an existing rule card.
</Step>
<Step title="Name and describe the rule">
Give the rule a clear name (e.g. *Mask PII (CC)*) and a description explaining when it applies. Both show up on the rule card and in the Engaged Automations modal.
</Step>
<Step title="Pick the type">
Today only **PII Redaction** is available.
</Step>
<Step title="Set the conditions">
Conditions decide which automations the rule engages with. Both are optional and use **set-equality** semantics:
- **Tools** — only automations whose tool set **exactly matches** the selected tools will engage. Picks from Studio apps, MCPs, OSS tools, and Tool Repository registry tools.
- **Automations** — only automations whose tag set **exactly matches** the selected tags will engage.
Leaving a picker empty means "no filter on this dimension". Leaving both empty means the rule applies to **every** automation in the organization.
</Step>
<Step title="Configure the PII Mask Type table">
Check each entity type you want covered and choose **Mask** (replaces with the entity label, e.g. `<CREDIT_CARD>`) or **Redact** (removes the matched text entirely). See [PII Redaction for Traces](/en/enterprise/features/pii-trace-redactions) for the full entity catalog and how to add organization-level custom recognizers.
</Step>
<Step title="Save">
The rule applies to **future** executions of every engaged automation as soon as you save. No re-deploy is needed.
</Step>
</Steps>
## Engaged automations
Click **Engaged N automations** on any rule card to see exactly which deployments the rule is currently matching, along with each one's last execution.
<Frame>
![Engaged automations modal](/images/enterprise/acp-rules-engaged-modal.png)
</Frame>
This is the fastest way to sanity-check a rule's scope before enabling it — for example, to confirm that a rule scoped to the `production` tag isn't accidentally matching a staging deployment.
## Org-wide rules vs per-deployment settings
PII Redaction can be configured in two places:
- **Per-deployment** — under **Settings → PII Protection** on each individual deployment ([guide](/en/enterprise/features/pii-trace-redactions))
- **Org-wide** — as a Rule on this page
When an enabled org-wide rule's scope matches a deployment, the rule's entity configuration **overrides** the deployment-owned PII settings for that deployment's executions — the rule becomes the single source of truth while it's attached. Disable or detach the rule (or change its scope so it no longer matches) and the deployment falls back to its own PII Protection settings.
Prefer org-wide rules when you want to enforce a consistent policy across many deployments; reserve per-deployment configuration for one-off exceptions.
## Related
<CardGroup cols={2}>
<Card title="Agent Control Plane — Overview" icon="book-open" href="/en/enterprise/features/agent-control-plane/overview">
What ACP is, requirements, plan tiers, and RBAC.
</Card>
<Card title="Agent Control Plane — Monitoring" icon="gauge" href="/en/enterprise/features/agent-control-plane/monitoring">
Monitor automations and LLM consumption across your fleet.
</Card>
<Card title="PII Redaction for Traces" icon="lock" href="/en/enterprise/features/pii-trace-redactions">
Entity catalog, custom recognizers, and per-deployment configuration.
</Card>
<Card title="RBAC" icon="users" href="/en/enterprise/features/rbac">
Manage who can create or edit rules.
</Card>
</CardGroup>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for help designing rules for your organization.
</Card>

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

@@ -0,0 +1,155 @@
---
title: 'Agent Repositories'
description: 'Learn how to use Agent Repositories to share and reuse your agents across teams and projects'
icon: 'people-group'
mode: "wide"
---
Agent Repositories allow enterprise users to store, share, and reuse agent definitions across teams and projects. This feature enables organizations to maintain a centralized library of standardized agents, promoting consistency and reducing duplication of effort.
<Frame>
![Agent Repositories](/images/enterprise/agent-repositories.png)
</Frame>
## Benefits of Agent Repositories
- **Standardization**: Maintain consistent agent definitions across your organization
- **Reusability**: Create an agent once and use it in multiple crews and projects
- **Governance**: Implement organization-wide policies for agent configurations
- **Collaboration**: Enable teams to share and build upon each other's work
## Creating and Use Agent Repositories
1. You must have an account at CrewAI, try the [free plan](https://app.crewai.com).
2. Create agents with specific roles and goals for your workflows.
3. Configure tools and capabilities for each specialized assistant.
4. Deploy agents across projects via visual interface or API integration.
<Frame>
![Agent Repositories](/images/enterprise/create-agent-repository.png)
</Frame>
### Loading Agents from Repositories
You can load agents from repositories in your code using the `from_repository` parameter to run locally:
```python
from crewai import Agent
# Create an agent by loading it from a repository
# The agent is loaded with all its predefined configurations
researcher = Agent(
from_repository="market-research-agent"
)
```
### Overriding Repository Settings
You can override specific settings from the repository by providing them in the configuration:
```python
researcher = Agent(
from_repository="market-research-agent",
goal="Research the latest trends in AI development", # Override the repository goal
verbose=True # Add a setting not in the repository
)
```
### Example: Creating a Crew with Repository Agents
```python
from crewai import Crew, Agent, Task
# Load agents from repositories
researcher = Agent(
from_repository="market-research-agent"
)
writer = Agent(
from_repository="content-writer-agent"
)
# Create tasks
research_task = Task(
description="Research the latest trends in AI",
agent=researcher
)
writing_task = Task(
description="Write a comprehensive report based on the research",
agent=writer
)
# Create the crew
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, writing_task],
verbose=True
)
# Run the crew
result = crew.kickoff()
```
### Example: Using `kickoff()` with Repository Agents
You can also use repository agents directly with the `kickoff()` method for simpler interactions:
```python
from crewai import Agent
from pydantic import BaseModel
from typing import List
# Define a structured output format
class MarketAnalysis(BaseModel):
key_trends: List[str]
opportunities: List[str]
recommendation: str
# Load an agent from repository
analyst = Agent(
from_repository="market-analyst-agent",
verbose=True
)
# Get a free-form response
result = analyst.kickoff("Analyze the AI market in 2025")
print(result.raw) # Access the raw response
# Get structured output
structured_result = analyst.kickoff(
"Provide a structured analysis of the AI market in 2025",
response_format=MarketAnalysis
)
# Access structured data
print(f"Key Trends: {structured_result.pydantic.key_trends}")
print(f"Recommendation: {structured_result.pydantic.recommendation}")
```
## Best Practices
1. **Naming Convention**: Use clear, descriptive names for your repository agents
2. **Documentation**: Include comprehensive descriptions for each agent
3. **Tool Management**: Ensure that tools referenced by repository agents are available in your environment
4. **Access Control**: Manage permissions to ensure only authorized team members can modify repository agents
## Organization Management
To switch between organizations or see your current organization, use the CrewAI CLI:
```bash
# View current organization
crewai org current
# Switch to a different organization
crewai org switch <org_id>
# List all available organizations
crewai org list
```
<Note>
When loading agents from repositories, you must be authenticated and switched to the correct organization. If you receive errors, check your authentication status and organization settings using the CLI commands above.
</Note>

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

@@ -0,0 +1,104 @@
---
title: Automations
description: "Manage, deploy, and monitor your live crews (automations) in one place."
icon: "rocket"
mode: "wide"
---
## Overview
Automations is the live operations hub for your deployed crews. Use it to deploy from GitHub or a ZIP file, manage environment variables, re‑deploy when needed, and monitor the status of each automation.
<Frame>
![Automations Overview](/images/enterprise/automations-overview.png)
</Frame>
## Deployment Methods
### Deploy from GitHub
Use this for version‑controlled projects and continuous deployment.
<Steps>
<Step title="Connect GitHub">
Click <b>Configure GitHub</b> and authorize access.
</Step>
<Step title="Select Repository & Branch">
Choose the <b>Repository</b> and <b>Branch</b> you want to deploy from.
</Step>
<Step title="Enable Auto‑deploy (optional)">
Turn on <b>Automatically deploy new commits</b> to ship updates on every push.
</Step>
<Step title="Add Environment Variables">
Add secrets individually or use <b>Bulk View</b> for multiple variables.
</Step>
<Step title="Deploy">
Click <b>Deploy</b> to create your live automation.
</Step>
</Steps>
<Frame>
![GitHub Deployment](/images/enterprise/deploy-from-github.png)
</Frame>
### Deploy from ZIP
Ship quickly without Git—upload a compressed package of your project.
<Steps>
<Step title="Choose File">
Select the ZIP archive from your computer.
</Step>
<Step title="Add Environment Variables">
Provide any required variables or keys.
</Step>
<Step title="Deploy">
Click <b>Deploy</b> to create your live automation.
</Step>
</Steps>
<Frame>
![ZIP Deployment](/images/enterprise/deploy-from-zip.png)
</Frame>
## Automations Dashboard
The table lists all live automations with key details:
- **CREW**: Automation name
- **STATUS**: Online / Failed / In Progress
- **URL**: Endpoint for kickoff/status
- **TOKEN**: Automation token
- **ACTIONS**: Re‑deploy, delete, and more
Use the top‑right controls to filter and search:
- Search by name
- Filter by <b>Status</b>
- Filter by <b>Source</b> (GitHub / Studio / ZIP)
Once deployed, you can view the automation details and have the **Options** dropdown menu to `chat with this crew`, `Export React Component` and `Export as MCP`.
<Frame>
![Automations Table](/images/enterprise/automations-table.png)
</Frame>
## Best Practices
- Prefer GitHub deployments for version control and CI/CD
- Use re‑deploy to roll forward after code or config updates or set it to auto-deploy on every push
## Related
<CardGroup cols={3}>
<Card title="Deploy a Crew" href="/en/enterprise/guides/deploy-crew" icon="rocket">
Deploy a Crew from GitHub or ZIP file.
</Card>
<Card title="Automation Triggers" href="/en/enterprise/guides/automation-triggers" icon="trigger">
Trigger automations via webhooks or API.
</Card>
<Card title="Webhook Automation" href="/en/enterprise/guides/webhook-automation" icon="webhook">
Stream real-time events and updates to your systems.
</Card>
</CardGroup>

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

@@ -0,0 +1,88 @@
---
title: Crew Studio
description: "Build new automations with AI assistance, a visual editor, and integrated testing."
icon: "pencil"
mode: "wide"
---
## Overview
Crew Studio is an interactive, AI‑assisted workspace for creating new automations from scratch using natural language and a visual workflow editor.
<Frame>
![Crew Studio Overview](/images/enterprise/crew-studio-overview.png)
</Frame>
## Prompt‑based Creation
- Describe the automation you want; the AI generates agents, tasks, and tools.
- Use voice input via the microphone icon if preferred.
- Start from built‑in prompts for common use cases.
<Frame>
![Prompt Builder](/images/enterprise/crew-studio-prompt.png)
</Frame>
## Visual Editor
The canvas reflects the workflow as nodes and edges with three supporting panels that allow you to configure the workflow easily without writing code; a.k.a. "**vibe coding AI Agents**".
You can use the drag-and-drop functionality to add agents, tasks, and tools to the canvas or you can use the chat section to build the agents. Both approaches share state and can be used interchangeably.
- **AI Thoughts (left)**: streaming reasoning as the workflow is designed
- **Canvas (center)**: agents and tasks as connected nodes
- **Resources (right)**: drag‑and‑drop components (agents, tasks, tools)
<Frame>
![Visual Canvas](/images/enterprise/crew-studio-canvas.png)
</Frame>
## Execution & Debugging
Switch to the <b>Execution</b> view to run and observe the workflow:
- Event timeline
- Detailed logs (Details, Messages, Raw Data)
- Local test runs before publishing
<Frame>
![Execution View](/images/enterprise/crew-studio-execution.png)
</Frame>
## Publish & Export
- <b>Publish</b> to deploy a live automation
- <b>Download</b> source as a ZIP for local development or customization
<Frame>
![Publish & Download](/images/enterprise/crew-studio-publish.png)
</Frame>
Once published, you can view the automation details and have the **Options** dropdown menu to `chat with this crew`, `Export React Component` and `Export as MCP`.
<Frame>
![Published Automation](/images/enterprise/crew-studio-published.png)
</Frame>
## Best Practices
- Iterate quickly in Studio; publish only when stable
- Keep tools constrained to minimum permissions needed
- Use Traces to validate behavior and performance
## Related
<CardGroup cols={4}>
<Card title="Enable Crew Studio" href="/en/enterprise/guides/enable-crew-studio" icon="palette">
Enable Crew Studio.
</Card>
<Card title="Build a Crew" href="/en/enterprise/guides/build-crew" icon="paintbrush">
Build a Crew.
</Card>
<Card title="Deploy a Crew" href="/en/enterprise/guides/deploy-crew" icon="rocket">
Deploy a Crew from GitHub or ZIP file.
</Card>
<Card title="Export a React Component" href="/en/enterprise/guides/react-component-export" icon="download">
Export a React Component.
</Card>
</CardGroup>

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

@@ -0,0 +1,558 @@
---
title: "Flow HITL Management"
description: "Enterprise-grade human review for Flows with email-first notifications, routing rules, and auto-response capabilities"
icon: "users-gear"
mode: "wide"
---
<Note>
Flow HITL Management features require the `@human_feedback` decorator, available in **CrewAI version 1.8.0 or higher**. These features apply specifically to **Flows**, not Crews.
</Note>
CrewAI Enterprise provides a comprehensive Human-in-the-Loop (HITL) management system for Flows that transforms AI workflows into collaborative human-AI processes. The platform uses an **email-first architecture** that enables anyone with an email address to respond to review requests—no platform account required.
## Overview
<CardGroup cols={3}>
<Card title="Email-First Design" icon="envelope">
Responders can reply directly to notification emails to provide feedback
</Card>
<Card title="Flexible Routing" icon="route">
Route requests to specific emails based on method patterns or flow state
</Card>
<Card title="Auto-Response" icon="clock">
Configure automatic fallback responses when no human replies in time
</Card>
</CardGroup>
### Key Benefits
- **Simple mental model**: Email addresses are universal; no need to manage platform users or roles
- **External responders**: Anyone with an email can respond, even non-platform users
- **Dynamic assignment**: Pull assignee email directly from flow state (e.g., `sales_rep_email`)
- **Reduced configuration**: Fewer settings to configure, faster time to value
- **Email as primary channel**: Most users prefer responding via email over logging into a dashboard
## Setting Up Human Review Points in Flows
Configure human review checkpoints within your Flows using the `@human_feedback` decorator. When execution reaches a review point, the system pauses, notifies the assignee via email, and waits for a response.
```python
from crewai.flow.flow import Flow, start, listen, or_
from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult
class ContentApprovalFlow(Flow):
@start()
def generate_content(self):
return "Generated marketing copy for Q1 campaign..."
@human_feedback(
message="Please review this content for brand compliance:",
emit=["approved", "rejected", "needs_revision"],
)
@listen(or_("generate_content", "needs_revision"))
def review_content(self):
return "Marketing copy for review..."
@listen("approved")
def publish_content(self, result: HumanFeedbackResult):
print(f"Publishing approved content. Reviewer notes: {result.feedback}")
@listen("rejected")
def archive_content(self, result: HumanFeedbackResult):
print(f"Content rejected. Reason: {result.feedback}")
```
For complete implementation details, see the [Human Feedback in Flows](/en/learn/human-feedback-in-flows) guide.
### Decorator Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | `str` | The message displayed to the human reviewer |
| `emit` | `list[str]` | Valid response options (displayed as buttons in UI) |
## Platform Configuration
Access HITL configuration from: **Deployment → Settings → Human in the Loop Configuration**
<Frame>
<img src="/images/enterprise/hitl-settings-overview.png" alt="HITL Configuration Settings" />
</Frame>
### Email Notifications
Toggle to enable or disable email notifications for HITL requests.
| Setting | Default | Description |
|---------|---------|-------------|
| Email Notifications | Enabled | Send emails when feedback is requested |
<Note>
When disabled, responders must use the dashboard UI or you must configure webhooks for custom notification systems.
</Note>
### SLA Target
Set a target response time for tracking and metrics purposes.
| Setting | Description |
|---------|-------------|
| SLA Target (minutes) | Target response time. Used for dashboard metrics and SLA tracking |
Leave empty to disable SLA tracking.
## Email Notifications & Responses
The HITL system uses an email-first architecture where responders can reply directly to notification emails.
### How Email Responses Work
<Steps>
<Step title="Notification Sent">
When a HITL request is created, an email is sent to the assigned responder with the review content and context.
</Step>
<Step title="Reply-To Address">
The email includes a special reply-to address with a signed token for authentication.
</Step>
<Step title="User Replies">
The responder simply replies to the email with their feedback—no login required.
</Step>
<Step title="Token Validation">
The platform receives the reply, verifies the signed token, and matches the sender email.
</Step>
<Step title="Flow Resumes">
The feedback is recorded and the flow continues with the human's input.
</Step>
</Steps>
### Response Format
Responders can reply with:
- **Emit option**: If the reply matches an `emit` option (e.g., "approved"), it's used directly
- **Free-form text**: Any text response is passed to the flow as feedback
- **Plain text**: The first line of the reply body is used as feedback
### Confirmation Emails
After processing a reply, the responder receives a confirmation email indicating whether the feedback was successfully submitted or if an error occurred.
### Email Token Security
- Tokens are cryptographically signed for security
- Tokens expire after 7 days
- Sender email must match the token's authorized email
- Confirmation/error emails are sent after processing
## Routing Rules
Route HITL requests to specific email addresses based on method patterns.
<Frame>
<img src="/images/enterprise/hitl-settings-routing-rules.png" alt="HITL Routing Rules Configuration" />
</Frame>
### Rule Structure
```json
{
"name": "Approvals to Finance",
"match": {
"method_name": "approve_*"
},
"assign_to_email": "finance@company.com",
"assign_from_input": "manager_email"
}
```
### Matching Patterns
| Pattern | Description | Example Match |
|---------|-------------|---------------|
| `approve_*` | Wildcard (any chars) | `approve_payment`, `approve_vendor` |
| `review_?` | Single char | `review_a`, `review_1` |
| `validate_payment` | Exact match | `validate_payment` only |
### Assignment Priority
1. **Dynamic assignment** (`assign_from_input`): If configured, pulls email from flow state
2. **Static email** (`assign_to_email`): Falls back to configured email
3. **Deployment creator**: If no rule matches, the deployment creator's email is used
### Dynamic Assignment Example
If your flow state contains `{"sales_rep_email": "alice@company.com"}`, configure:
```json
{
"name": "Route to Sales Rep",
"match": {
"method_name": "review_*"
},
"assign_from_input": "sales_rep_email"
}
```
The request will be assigned to `alice@company.com` automatically.
<Tip>
**Use Case**: Pull the assignee from your CRM, database, or previous flow step to dynamically route reviews to the right person.
</Tip>
## Auto-Response
Automatically respond to HITL requests if no human responds within a timeout. This ensures flows don't hang indefinitely.
### Configuration
| Setting | Description |
|---------|-------------|
| Enabled | Toggle to enable auto-response |
| Timeout (minutes) | Time to wait before auto-responding |
| Default Outcome | The response value (must match an `emit` option) |
<Frame>
<img src="/images/enterprise/hitl-settings-auto-respond.png" alt="HITL Auto-Response Configuration" />
</Frame>
### Use Cases
- **SLA compliance**: Ensure flows don't hang indefinitely
- **Default approval**: Auto-approve low-risk requests after timeout
- **Graceful degradation**: Continue with a safe default when reviewers are unavailable
<Warning>
Use auto-response carefully. Only enable it for non-critical reviews where a default response is acceptable.
</Warning>
## Review Process
### Dashboard Interface
The HITL review interface provides a clean, focused experience for reviewers:
- **Markdown Rendering**: Rich formatting for review content with syntax highlighting
- **Context Panel**: View flow state, execution history, and related information
- **Feedback Input**: Provide detailed feedback and comments with your decision
- **Quick Actions**: One-click emit option buttons with optional comments
<Frame>
<img src="/images/enterprise/hitl-list-pending-feedbacks.png" alt="HITL Pending Requests List" />
</Frame>
### Response Methods
Reviewers can respond via three channels:
| Method | Description |
|--------|-------------|
| **Email Reply** | Reply directly to the notification email |
| **Dashboard** | Use the Enterprise dashboard UI |
| **API/Webhook** | Programmatic response via API |
### History & Audit Trail
Every HITL interaction is tracked with a complete timeline:
- Decision history (approve/reject/revise)
- Reviewer identity and timestamp
- Feedback and comments provided
- Response method (email/dashboard/API)
- Response time metrics
## Analytics & Monitoring
Track HITL performance with comprehensive analytics.
### Performance Dashboard
<Frame>
<img src="/images/enterprise/hitl-metrics.png" alt="HITL Metrics Dashboard" />
</Frame>
<CardGroup cols={2}>
<Card title="Response Times" icon="stopwatch">
Monitor average and median response times by reviewer or flow.
</Card>
<Card title="Volume Trends" icon="chart-bar">
Analyze review volume patterns to optimize team capacity.
</Card>
<Card title="Decision Distribution" icon="chart-pie">
View approval/rejection rates across different review types.
</Card>
<Card title="SLA Tracking" icon="chart-line">
Track percentage of reviews completed within SLA targets.
</Card>
</CardGroup>
### Audit & Compliance
Enterprise-ready audit capabilities for regulatory requirements:
- Complete decision history with timestamps
- Reviewer identity verification
- Immutable audit logs
- Export capabilities for compliance reporting
## Common Use Cases
<AccordionGroup>
<Accordion title="Security Reviews" icon="shield-halved">
**Use Case**: Internal security questionnaire automation with human validation
- AI generates responses to security questionnaires
- Security team reviews and validates accuracy via email
- Approved responses are compiled into final submission
- Full audit trail for compliance
</Accordion>
<Accordion title="Content Approval" icon="file-lines">
**Use Case**: Marketing content requiring legal/brand review
- AI generates marketing copy or social media content
- Route to brand team email for voice/tone review
- Automatic publishing upon approval
</Accordion>
<Accordion title="Financial Approvals" icon="money-bill">
**Use Case**: Expense reports, contract terms, budget allocations
- AI pre-processes and categorizes financial requests
- Route based on amount thresholds using dynamic assignment
- Maintain complete audit trail for financial compliance
</Accordion>
<Accordion title="Dynamic Assignment from CRM" icon="database">
**Use Case**: Route reviews to account owners from your CRM
- Flow fetches account owner email from CRM
- Store email in flow state (e.g., `account_owner_email`)
- Use `assign_from_input` to route to the right person automatically
</Accordion>
<Accordion title="Quality Assurance" icon="magnifying-glass">
**Use Case**: AI output validation before customer delivery
- AI generates customer-facing content or responses
- QA team reviews via email notification
- Feedback loops improve AI performance over time
</Accordion>
</AccordionGroup>
## Webhooks API
When your Flows pause for human feedback, you can configure webhooks to send request data to your own application. This enables:
- Building custom approval UIs
- Integrating with internal tools (Jira, ServiceNow, custom dashboards)
- Routing approvals to third-party systems
- Mobile app notifications
- Automated decision systems
<Frame>
<img src="/images/enterprise/hitl-settings-webhook.png" alt="HITL Webhook Configuration" />
</Frame>
### Configuring Webhooks
<Steps>
<Step title="Navigate to Settings">
Go to your **Deployment** → **Settings** → **Human in the Loop**
</Step>
<Step title="Expand Webhooks Section">
Click to expand the **Webhooks** configuration
</Step>
<Step title="Add Your Webhook URL">
Enter your webhook URL (must be HTTPS in production)
</Step>
<Step title="Save Configuration">
Click **Save Configuration** to activate
</Step>
</Steps>
You can configure multiple webhooks. Each active webhook receives all HITL events.
### Webhook Events
Your endpoint will receive HTTP POST requests for these events:
| Event Type | When Triggered |
|------------|----------------|
| `new_request` | A flow pauses and requests human feedback |
### Webhook Payload
All webhooks receive a JSON payload with this structure:
```json
{
"event": "new_request",
"request": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"flow_id": "flow_abc123",
"method_name": "review_article",
"message": "Please review this article for publication.",
"emit_options": ["approved", "rejected", "request_changes"],
"state": {
"article_id": 12345,
"author": "john@example.com",
"category": "technology"
},
"metadata": {},
"created_at": "2026-01-14T12:00:00Z"
},
"deployment": {
"id": 456,
"name": "Content Review Flow",
"organization_id": 789
},
"callback_url": "https://api.crewai.com/...",
"assigned_to_email": "reviewer@company.com"
}
```
### Responding to Requests
To submit feedback, **POST to the `callback_url`** included in the webhook payload.
```http
POST {callback_url}
Content-Type: application/json
{
"feedback": "Approved. Great article!",
"source": "my_custom_app"
}
```
### Security
<Info>
All webhook requests are cryptographically signed using HMAC-SHA256 to ensure authenticity and prevent tampering.
</Info>
#### Webhook Security
- **HMAC-SHA256 signatures**: Every webhook includes a cryptographic signature
- **Per-webhook secrets**: Each webhook has its own unique signing secret
- **Encrypted at rest**: Signing secrets are encrypted in our database
- **Timestamp verification**: Prevents replay attacks
#### Signature Headers
Each webhook request includes these headers:
| Header | Description |
|--------|-------------|
| `X-Signature` | HMAC-SHA256 signature: `sha256=<hex_digest>` |
| `X-Timestamp` | Unix timestamp when the request was signed |
#### Verification
Verify by computing:
```python
import hmac
import hashlib
expected = hmac.new(
signing_secret.encode(),
f"{timestamp}.{payload}".encode(),
hashlib.sha256
).hexdigest()
if hmac.compare_digest(expected, signature):
# Valid signature
```
### Error Handling
Your webhook endpoint should return a 2xx status code to acknowledge receipt:
| Your Response | Our Behavior |
|---------------|--------------|
| 2xx | Webhook delivered successfully |
| 4xx/5xx | Logged as failed, no retry |
| Timeout (30s) | Logged as failed, no retry |
## Security & RBAC
### Dashboard Access
HITL access is controlled at the deployment level:
| Permission | Capability |
|------------|------------|
| `manage_human_feedback` | Configure HITL settings, view all requests |
| `respond_to_human_feedback` | Respond to requests, view assigned requests |
### Email Response Authorization
For email replies:
1. The reply-to token encodes the authorized email
2. Sender email must match the token's email
3. Token must not be expired (7-day default)
4. Request must still be pending
### Audit Trail
All HITL actions are logged:
- Request creation
- Assignment changes
- Response submission (with source: dashboard/email/API)
- Flow resume status
## Troubleshooting
### Emails Not Sending
1. Check "Email Notifications" is enabled in configuration
2. Verify routing rules match the method name
3. Verify assignee email is valid
4. Check deployment creator fallback if no routing rules match
### Email Replies Not Processing
1. Check token hasn't expired (7-day default)
2. Verify sender email matches assigned email
3. Ensure request is still pending (not already responded)
### Flow Not Resuming
1. Check request status in dashboard
2. Verify callback URL is accessible
3. Ensure deployment is still running
## Best Practices
<Tip>
**Start Simple**: Begin with email notifications to deployment creator, then add routing rules as your workflows mature.
</Tip>
1. **Use Dynamic Assignment**: Pull assignee emails from your flow state for flexible routing.
2. **Configure Auto-Response**: Set up a fallback for non-critical reviews to prevent flows from hanging.
3. **Monitor Response Times**: Use analytics to identify bottlenecks and optimize your review process.
4. **Keep Review Messages Clear**: Write clear, actionable messages in the `@human_feedback` decorator.
5. **Test Email Flow**: Send test requests to verify email delivery before going to production.
## Related Resources
<CardGroup cols={2}>
<Card title="Human Feedback in Flows" icon="code" href="/en/learn/human-feedback-in-flows">
Implementation guide for the `@human_feedback` decorator
</Card>
<Card title="Flow HITL Workflow Guide" icon="route" href="/en/enterprise/guides/human-in-the-loop">
Step-by-step guide for setting up HITL workflows
</Card>
<Card title="RBAC Configuration" icon="shield-check" href="/en/enterprise/features/rbac">
Configure role-based access control for your organization
</Card>
<Card title="Webhook Streaming" icon="bolt" href="/en/enterprise/features/webhook-streaming">
Set up real-time event notifications
</Card>
</CardGroup>

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

@@ -0,0 +1,251 @@
---
title: Hallucination Guardrail
description: "Prevent and detect AI hallucinations in your CrewAI tasks"
icon: "shield-check"
mode: "wide"
---
## Overview
The Hallucination Guardrail is an enterprise feature that validates AI-generated content to ensure it's grounded in facts and doesn't contain hallucinations. It analyzes task outputs against reference context and provides detailed feedback when potentially hallucinated content is detected.
## What are Hallucinations?
AI hallucinations occur when language models generate content that appears plausible but is factually incorrect or not supported by the provided context. The Hallucination Guardrail helps prevent these issues by:
- Comparing outputs against reference context
- Evaluating faithfulness to source material
- Providing detailed feedback on problematic content
- Supporting custom thresholds for validation strictness
## Basic Usage
### Setting Up the Guardrail
```python
from crewai.tasks.hallucination_guardrail import HallucinationGuardrail
from crewai import LLM
# Basic usage - will use task's expected_output as context
guardrail = HallucinationGuardrail(
llm=LLM(model="gpt-4o-mini")
)
# With explicit reference context
context_guardrail = HallucinationGuardrail(
context="AI helps with various tasks including analysis and generation.",
llm=LLM(model="gpt-4o-mini")
)
```
### Adding to Tasks
```python
from crewai import Task
# Create your task with the guardrail
task = Task(
description="Write a summary about AI capabilities",
expected_output="A factual summary based on the provided context",
agent=my_agent,
guardrail=guardrail # Add the guardrail to validate output
)
```
## Advanced Configuration
### Custom Threshold Validation
For stricter validation, you can set a custom faithfulness threshold (0-10 scale):
```python
# Strict guardrail requiring high faithfulness score
strict_guardrail = HallucinationGuardrail(
context="Quantum computing uses qubits that exist in superposition states.",
llm=LLM(model="gpt-4o-mini"),
threshold=8.0 # Requires score >= 8 to pass validation
)
```
### Including Tool Response Context
When your task uses tools, you can include tool responses for more accurate validation:
```python
# Guardrail with tool response context
weather_guardrail = HallucinationGuardrail(
context="Current weather information for the requested location",
llm=LLM(model="gpt-4o-mini"),
tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies"
)
```
## How It Works
### Validation Process
1. **Context Analysis**: The guardrail compares task output against the provided reference context
2. **Faithfulness Scoring**: Uses an internal evaluator to assign a faithfulness score (0-10)
3. **Verdict Determination**: Determines if content is faithful or contains hallucinations
4. **Threshold Checking**: If a custom threshold is set, validates against that score
5. **Feedback Generation**: Provides detailed reasons when validation fails
### Validation Logic
- **Default Mode**: Uses verdict-based validation (FAITHFUL vs HALLUCINATED)
- **Threshold Mode**: Requires faithfulness score to meet or exceed the specified threshold
- **Error Handling**: Gracefully handles evaluation errors and provides informative feedback
## Guardrail Results
The guardrail returns structured results indicating validation status:
```python
# Example of guardrail result structure
{
"valid": False,
"feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context."
}
```
### Result Properties
- **valid**: Boolean indicating whether the output passed validation
- **feedback**: Detailed explanation when validation fails, including:
- Faithfulness score
- Verdict classification
- Specific reasons for failure
## Integration with Task System
### Automatic Validation
When a guardrail is added to a task, it automatically validates the output before the task is marked as complete:
```python
# Task output validation flow
task_output = agent.execute_task(task)
validation_result = guardrail(task_output)
if validation_result.valid:
# Task completes successfully
return task_output
else:
# Task fails with validation feedback
raise ValidationError(validation_result.feedback)
```
### Event Tracking
The guardrail integrates with CrewAI's event system to provide observability:
- **Validation Started**: When guardrail evaluation begins
- **Validation Completed**: When evaluation finishes with results
- **Validation Failed**: When technical errors occur during evaluation
## Best Practices
### Context Guidelines
<Steps>
<Step title="Provide Comprehensive Context">
Include all relevant factual information that the AI should base its output on:
```python
context = """
Company XYZ was founded in 2020 and specializes in renewable energy solutions.
They have 150 employees and generated $50M revenue in 2023.
Their main products include solar panels and wind turbines.
"""
```
</Step>
<Step title="Keep Context Relevant">
Only include information directly related to the task to avoid confusion:
```python
# Good: Focused context
context = "The current weather in New York is 18°C with light rain."
# Avoid: Unrelated information
context = "The weather is 18°C. The city has 8 million people. Traffic is heavy."
```
</Step>
<Step title="Update Context Regularly">
Ensure your reference context reflects current, accurate information.
</Step>
</Steps>
### Threshold Selection
<Steps>
<Step title="Start with Default Validation">
Begin without custom thresholds to understand baseline performance.
</Step>
<Step title="Adjust Based on Requirements">
- **High-stakes content**: Use threshold 8-10 for maximum accuracy
- **General content**: Use threshold 6-7 for balanced validation
- **Creative content**: Use threshold 4-5 or default verdict-based validation
</Step>
<Step title="Monitor and Iterate">
Track validation results and adjust thresholds based on false positives/negatives.
</Step>
</Steps>
## Performance Considerations
### Impact on Execution Time
- **Validation Overhead**: Each guardrail adds ~1-3 seconds per task
- **LLM Efficiency**: Choose efficient models for evaluation (e.g., gpt-4o-mini)
### Cost Optimization
- **Model Selection**: Use smaller, efficient models for guardrail evaluation
- **Context Size**: Keep reference context concise but comprehensive
- **Caching**: Consider caching validation results for repeated content
## Troubleshooting
<Accordion title="Validation Always Fails">
**Possible Causes:**
- Context is too restrictive or unrelated to task output
- Threshold is set too high for the content type
- Reference context contains outdated information
**Solutions:**
- Review and update context to match task requirements
- Lower threshold or use default verdict-based validation
- Ensure context is current and accurate
</Accordion>
<Accordion title="False Positives (Valid Content Marked Invalid)">
**Possible Causes:**
- Threshold too high for creative or interpretive tasks
- Context doesn't cover all valid aspects of the output
- Evaluation model being overly conservative
**Solutions:**
- Lower threshold or use default validation
- Expand context to include broader acceptable content
- Test with different evaluation models
</Accordion>
<Accordion title="Evaluation Errors">
**Possible Causes:**
- Network connectivity issues
- LLM model unavailable or rate limited
- Malformed task output or context
**Solutions:**
- Check network connectivity and LLM service status
- Implement retry logic for transient failures
- Validate task output format before guardrail evaluation
</Accordion>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with hallucination guardrail configuration or troubleshooting.
</Card>

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

@@ -0,0 +1,46 @@
---
title: Marketplace
description: "Discover, install, and govern reusable assets for your enterprise crews."
icon: "store"
mode: "wide"
---
## Overview
The Marketplace provides a curated surface for discovering integrations, internal tools, and reusable assets that accelerate crew development.
<Frame>
![Marketplace Overview](/images/enterprise/marketplace-overview.png)
</Frame>
## Discoverability
- Browse by category and capability
- Search for assets by name or keyword
## Install & Enable
- One‑click install for approved assets
- Enable or disable per crew as needed
- Configure required environment variables and scopes
<Frame>
![Install & Configure](/images/enterprise/marketplace-install.png)
</Frame>
You can also download the templates directly from the marketplace by clicking on the `Download` button so
you can use them locally or refine them to your needs.
## Related
<CardGroup cols={3}>
<Card title="Tools & Integrations" href="/en/enterprise/features/tools-and-integrations" icon="wrench">
Connect external apps and manage internal tools your agents can use.
</Card>
<Card title="Tool Repository" href="/en/enterprise/guides/tool-repository#tool-repository" icon="toolbox">
Publish and install tools to enhance your crews' capabilities.
</Card>
<Card title="Agents Repository" href="/en/enterprise/features/agent-repositories" icon="people-group">
Store, share, and reuse agent definitions across teams and projects.
</Card>
</CardGroup>

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

@@ -0,0 +1,342 @@
---
title: PII Redaction for Traces
description: "Automatically redact sensitive data from crew and flow execution traces"
icon: "lock"
mode: "wide"
---
## Overview
PII Redaction is a CrewAI AMP feature that automatically detects and masks Personally Identifiable Information (PII) in your crew and flow execution traces. This ensures sensitive data like credit card numbers, social security numbers, email addresses, and names are not exposed in your CrewAI AMP traces. You can also create custom recognizers to protect organization-specific data.
<Info>
PII Redaction is available on the Enterprise plan.
Deployment must be version 1.8.0 or higher.
</Info>
<Frame>
![PII Redaction Overview](/images/enterprise/pii_mask_recognizer_trace_example.png)
</Frame>
## Why PII Redaction Matters
When running AI agents in production, sensitive information often flows through your crews:
- Customer data from CRM integrations
- Financial information from payment processors
- Personal details from form submissions
- Internal employee data
Without proper redaction, this data appears in traces, making compliance with regulations like GDPR, HIPAA, and PCI-DSS challenging. PII Redaction solves this by automatically masking sensitive data before it's stored in traces.
## How It Works
1. **Detect** - Scan trace event data for known PII patterns
2. **Classify** - Identify the type of sensitive data (credit card, SSN, email, etc.)
3. **Mask/Redact** - Replace the sensitive data with masked values based on your configuration
```
Original: "Contact john.doe@company.com or call 555-123-4567"
Redacted: "Contact <EMAIL_ADDRESS> or call <PHONE_NUMBER>"
```
## Enabling PII Redaction
<Info>
You must be on the Enterprise plan and your deployment must be version 1.8.0 or higher to use this feature.
</Info>
<Steps>
<Step title="Navigate to Crew Settings">
In the CrewAI AMP dashboard, select your deployed crew and go to one of your deployments/automations, then navigate to **Settings** → **PII Protection**.
</Step>
<Step title="Enable PII Protection">
Toggle on **PII Redaction for Traces**. This will enable automatic scanning and redaction of trace data.
<Info>
You need to manually enable PII Redaction for each deployment.
</Info>
<Frame>
![Enable PII Redaction](/images/enterprise/pii_mask_recognizer_enable.png)
</Frame>
</Step>
<Step title="Configure Entity Types">
Select which types of PII to detect and redact. Each entity can be individually enabled or disabled.
<Frame>
![Configure Entities](/images/enterprise/pii_mask_recognizer_supported_entities.png)
</Frame>
</Step>
<Step title="Save">
Save your configuration. PII redaction will be active on all subsequent crew executions, no redeployment is needed.
</Step>
</Steps>
## Supported Entity Types
CrewAI supports the following PII entity types, organized by category.
### Global Entities
| Entity | Description | Example |
|--------|-------------|---------|
| `CREDIT_CARD` | Credit/debit card numbers | "4111-1111-1111-1111" |
| `CRYPTO` | Cryptocurrency wallet addresses | "bc1qxy2kgd..." |
| `DATE_TIME` | Dates and times | "January 15, 2024" |
| `EMAIL_ADDRESS` | Email addresses | "john@example.com" |
| `IBAN_CODE` | International bank account numbers | "DE89 3704 0044 0532 0130 00" |
| `IP_ADDRESS` | IPv4 and IPv6 addresses | "192.168.1.1" |
| `LOCATION` | Geographic locations | "New York City" |
| `MEDICAL_LICENSE` | Medical license numbers | "MD12345" |
| `NRP` | Nationalities, religious, or political groups | - |
| `PERSON` | Personal names | "John Doe" |
| `PHONE_NUMBER` | Phone numbers in various formats | "+1 (555) 123-4567" |
| `URL` | Web URLs | "https://example.com" |
### US-Specific Entities
| Entity | Description | Example |
|--------|-------------|---------|
| `US_BANK_NUMBER` | US Bank account numbers | "1234567890" |
| `US_DRIVER_LICENSE` | US Driver's license numbers | "D1234567" |
| `US_ITIN` | Individual Taxpayer ID | "900-70-0000" |
| `US_PASSPORT` | US Passport numbers | "123456789" |
| `US_SSN` | Social Security Numbers | "123-45-6789" |
## Redaction Actions
For each enabled entity, you can configure how the data is redacted:
| Action | Description | Example Output |
|--------|-------------|----------------|
| `mask` | Replace with the entity type label | `<CREDIT_CARD>` |
| `redact` | Completely remove the text | *(empty)* |
## Custom Recognizers
In addition to built-in entities, you can create **custom recognizers** to detect organization-specific PII patterns.
<Frame>
![Custom Recognizers](/images/enterprise/pii_mask_recognizer.png)
</Frame>
### Recognizer Types
You have two options for custom recognizers:
| Type | Best For | Example Use Case |
|------|----------|------------------|
| **Pattern-based (Regex)** | Structured data with predictable formats | Salary amounts, employee IDs, project codes |
| **Deny-list** | Exact string matches | Company names, internal codenames, specific terms |
### Creating a Custom Recognizer
<Steps>
<Step title="Navigate to Custom Recognizers">
Go to your Organization **Settings** → **Organization** → **Add Recognizer**.
</Step>
<Step title="Configure the Recognizer">
<Frame>
![Configure Recognizer](/images/enterprise/pii_mask_recognizer_create.png)
</Frame>
Configure the following fields:
- **Name**: A descriptive name for the recognizer
- **Entity Type**: The entity label that will appear in redacted output (e.g., `EMPLOYEE_ID`, `SALARY`)
- **Type**: Choose between Regex Pattern or Deny List
- **Pattern/Values**: Regex pattern or list of strings to match
- **Confidence Threshold**: Minimum score (0.0-1.0) required for a match to trigger redaction. Higher values (e.g., 0.8) reduce false positives but may miss some matches. Lower values (e.g., 0.5) catch more matches but may over-redact. Default is 0.8.
- **Context Words** (optional): Words that increase detection confidence when found nearby
</Step>
<Step title="Save">
Save the recognizer. It will be available to enable on your deployments.
</Step>
</Steps>
### Understanding Entity Types
The **Entity Type** determines how matched content appears in redacted traces:
```
Entity Type: SALARY
Pattern: salary:\s*\$\s*\d+
Input: "Employee salary: $50,000"
Output: "Employee <SALARY>"
```
### Using Context Words
Context words improve accuracy by increasing confidence when specific terms appear near the matched pattern:
```
Context Words: "project", "code", "internal"
Entity Type: PROJECT_CODE
Pattern: PRJ-\d{4}
```
When "project" or "code" appears near "PRJ-1234", the recognizer has higher confidence it's a true match, reducing false positives.
## Viewing Redacted Traces
Once PII redaction is enabled, your traces will show redacted values in place of sensitive data:
```
Task Output: "Customer <PERSON> placed order #12345.
Contact email: <EMAIL_ADDRESS>, phone: <PHONE_NUMBER>.
Payment processed for card ending in <CREDIT_CARD>."
```
Redacted values are clearly marked with angle brackets and the entity type label (e.g., `<EMAIL_ADDRESS>`), making it easy to understand what data was protected while still allowing you to debug and monitor crew behavior.
## Best Practices
### Performance Considerations
<Steps>
<Step title="Enable Only Needed Entities">
Each enabled entity adds processing overhead. Only enable entities relevant to your data.
</Step>
<Step title="Use Specific Patterns">
For custom recognizers, use specific patterns to reduce false positives and improve performance. Regex patterns are best when identifying specific patterns in the traces such as salary, employee id, project code, etc. Deny-list recognizers are best when identifying exact strings in the traces such as company names, internal codenames, etc.
</Step>
<Step title="Leverage Context Words">
Context words improve accuracy by only triggering detection when surrounding text matches.
</Step>
</Steps>
## Troubleshooting
<Accordion title="PII Not Being Redacted">
**Possible Causes:**
- Entity type not enabled in configuration
- Pattern doesn't match the data format
- Custom recognizer has syntax errors
**Solutions:**
- Verify entity is enabled in Settings → Security
- Test regex patterns with sample data
- Check logs for configuration errors
</Accordion>
<Accordion title="Too Much Data Being Redacted">
**Possible Causes:**
- Overly broad entity types enabled (e.g., `DATE_TIME` catches dates everywhere)
- Custom recognizer patterns are too general
**Solutions:**
- Disable entities that cause false positives
- Make custom patterns more specific
- Add context words to improve accuracy
</Accordion>
<Accordion title="Performance Issues">
**Possible Causes:**
- Too many entities enabled
- NLP-based entities (`PERSON`, `LOCATION`, `NRP`) are computationally expensive as they use machine learning models
**Solutions:**
- Only enable entities you actually need
- Consider using pattern-based alternatives where possible
- Monitor trace processing times in the dashboard
</Accordion>
---
## Practical Example: Salary Pattern Matching
This example demonstrates how to create a custom recognizer to detect and mask salary information in your traces.
### Use Case
Your crew processes employee or financial data that includes salary information in formats like:
- `salary: $50,000`
- `salary: $125,000.00`
- `salary:$1,500.50`
You want to automatically mask these values to protect sensitive compensation data.
### Configuration
<Frame>
![Salary Recognizer Configuration](/images/enterprise/pii_mask_custom_recognizer_salary.png)
</Frame>
| Field | Value |
|-------|-------|
| **Name** | `SALARY` |
| **Entity Type** | `SALARY` |
| **Type** | Regex Pattern |
| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` |
| **Action** | Mask |
| **Confidence Threshold** | `0.8` |
| **Context Words** | `salary, compensation, pay, wage, income` |
### Regex Pattern Breakdown
| Pattern Component | Meaning |
|-------------------|---------|
| `salary:` | Matches the literal text "salary:" |
| `\s*` | Matches zero or more whitespace characters |
| `\$` | Matches the dollar sign (escaped) |
| `\s*` | Matches zero or more whitespace characters after $ |
| `\d{1,3}` | Matches 1-3 digits (e.g., "1", "50", "125") |
| `(,\d{3})*` | Matches comma-separated thousands (e.g., ",000", ",500,000") |
| `(\.\d{2})?` | Optionally matches cents (e.g., ".00", ".50") |
### Example Results
```
Original: "Employee record shows salary: $125,000.00 annually"
Redacted: "Employee record shows <SALARY> annually"
Original: "Base salary:$50,000 with bonus potential"
Redacted: "Base <SALARY> with bonus potential"
```
<Tip>
Adding context words like "salary", "compensation", "pay", "wage", and "income" helps increase detection confidence when these terms appear near the matched pattern, reducing false positives.
</Tip>
### Enable the Recognizer for Your Deployments
<Warning>
Creating a custom recognizer at the organization level does not automatically enable it for your deployments. You must manually enable each recognizer for every deployment where you want it applied.
</Warning>
After creating your custom recognizer, enable it for each deployment:
<Steps>
<Step title="Navigate to Your Deployment">
Go to your deployment/automation and open **Settings** → **PII Protection**.
</Step>
<Step title="Select Custom Recognizers">
Under **Mask Recognizers**, you'll see your organization-defined recognizers. Check the box next to the recognizers you want to enable.
<Frame>
![Enable Custom Recognizer](/images/enterprise/pii_mask_recognizers_options.png)
</Frame>
</Step>
<Step title="Save Configuration">
Save your changes. The recognizer will be active on all subsequent executions for this deployment.
</Step>
</Steps>
<Info>
Repeat this process for each deployment where you need the custom recognizer. This gives you granular control over which recognizers are active in different environments (e.g., development vs. production).
</Info>

256
docs/edge/en/enterprise/features/rbac.mdx Normal file
View File

@@ -0,0 +1,256 @@
---
title: "Role-Based Access Control (RBAC)"
description: "Control access to crews, tools, and data with roles, scopes, and granular permissions."
icon: "shield"
mode: "wide"
---
## Overview
RBAC in CrewAI AMP enables secure, scalable access management through two layers:
1. **Feature permissions** — control what each role can do across the platform (manage, read, or no access)
2. **Entity-level permissions** — fine-grained access on individual automations, environment variables, LLM connections, and Git repositories
<Frame>
<img src="/images/enterprise/users_and_roles.png" alt="RBAC overview in CrewAI AMP" />
</Frame>
## Users and Roles
Each member in your CrewAI workspace is assigned a role, which determines their access across various features.
You can:
- Use predefined roles (Owner, Member)
- Create custom roles tailored to specific permissions
- Assign roles at any time through the settings panel
You can configure users and roles in Settings → Roles.
<Steps>
<Step title="Open Roles settings">
Go to <b>Settings → Roles</b> in CrewAI AMP.
</Step>
<Step title="Choose a role type">
Use a predefined role (<b>Owner</b>, <b>Member</b>) or click{" "}
<b>Create role</b> to define a custom one.
</Step>
<Step title="Assign to members">
Select users and assign the role. You can change this anytime.
</Step>
</Steps>
### Predefined Roles
| Role | Description |
| :--------- | :-------------------------------------------------------------------------- |
| **Owner** | Full access to all features and settings. Cannot be restricted. |
| **Member** | Read access to most features, manage access to environment variables, LLM connections, and Studio projects. Cannot modify organization or default settings. |
### Configuration summary
| Area | Where to configure | Options |
| :-------------------- | :--------------------------------- | :-------------------------------------- |
| Users & Roles | Settings → Roles | Predefined: Owner, Member; Custom roles |
| Automation visibility | Automation → Settings → Visibility | Private; Whitelist users/roles |
---
## Feature Permissions Matrix
Every role has a permission level for each feature area. The three levels are:
- **Manage** — full read/write access (create, edit, delete)
- **Read** — view-only access
- **No access** — feature is hidden/inaccessible
| Feature | Owner | Member (default) | Available levels | Description |
| :------------------------ | :------ | :--------------- | :------------------------ | :-------------------------------------------------------------- |
| `usage_dashboards` | Manage | Read | Manage / Read / No access | View usage metrics and analytics |
| `crews_dashboards` | Manage | Read | Manage / Read / No access | View deployment dashboards, access automation details |
| `invitations` | Manage | Read | Manage / Read / No access | Invite new members to the organization |
| `training_ui` | Manage | Read | Manage / Read / No access | Access training/fine-tuning interfaces |
| `tools` | Manage | Read | Manage / Read / No access | Create and manage tools |
| `agents` | Manage | Read | Manage / Read / No access | Create and manage agents |
| `environment_variables` | Manage | Manage | Manage / No access | Create and manage environment variables |
| `llm_connections` | Manage | Manage | Manage / No access | Configure LLM provider connections |
| `default_settings` | Manage | No access | Manage / No access | Modify organization-wide default settings |
| `organization_settings` | Manage | No access | Manage / No access | Manage billing, plans, and organization configuration |
| `studio_projects` | Manage | Manage | Manage / No access | Create and edit projects in Studio |
<Tip>
When creating a custom role, most features can be set to **Manage**, **Read**, or **No access**. However, `environment_variables`, `llm_connections`, `default_settings`, `organization_settings`, and `studio_projects` only support **Manage** or **No access** — there is no read-only option for these features.
</Tip>
---
## Deploying from GitHub or Zip
One of the most common RBAC questions is: _"What permissions does a team member need to deploy?"_
### Deploy from GitHub
To deploy an automation from a GitHub repository, a user needs:
1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard where deployments are created
2. **Git repository access** (if entity-level RBAC for Git repositories is enabled): the user's role must be granted access to the specific Git repository via entity-level permissions
3. **`studio_projects`: `Manage`** — if building the crew in Studio before deploying
### Deploy from Zip
To deploy an automation from a Zip file upload, a user needs:
1. **`crews_dashboards`**: at least `Read` — required to access the automations dashboard
2. **Zip deployments enabled**: the organization must not have disabled zip deployments in organization settings
### Quick Reference: Minimum Permissions for Deployment
| Action | Required feature permissions | Additional requirements |
| :------------------- | :------------------------------------ | :----------------------------------------------- |
| Deploy from GitHub | `crews_dashboards: Read` | Git repo entity access (if Git RBAC is enabled) |
| Deploy from Zip | `crews_dashboards: Read` | Zip deployments must be enabled at the org level |
| Build in Studio | `studio_projects: Manage` | — |
| Configure LLM keys | `llm_connections: Manage` | — |
| Set environment vars | `environment_variables: Manage` | Entity-level access (if entity RBAC is enabled) |
---
## Automation‑level Access Control (Entity Permissions)
In addition to organization‑wide roles, CrewAI supports fine‑grained entity-level permissions that restrict access to individual resources.
### Automation Visibility
Automations support visibility settings that restrict access by user or role. This is useful for:
- Keeping sensitive or experimental automations private
- Managing visibility across large teams or external collaborators
- Testing automations in isolated contexts
Deployments can be configured as private, meaning only whitelisted users and roles will be able to interact with them.
You can configure automation‑level access control in Automation → Settings → Visibility tab.
<Steps>
<Step title="Open Visibility tab">
Navigate to <b>Automation → Settings → Visibility</b>.
</Step>
<Step title="Set visibility">
Choose <b>Private</b> to restrict access. The organization owner always
retains access.
</Step>
<Step title="Whitelist access">
Add specific users and roles allowed to view, run, and access
logs/metrics/settings.
</Step>
<Step title="Save and verify">
Save changes, then confirm that non‑whitelisted users cannot view or run the
automation.
</Step>
</Steps>
### Private visibility: access outcomes
| Action | Owner | Whitelisted user/role | Not whitelisted |
| :--------------------------- | :---- | :-------------------- | :-------------- |
| View automation | ✓ | ✓ | ✗ |
| Run automation/API | ✓ | ✓ | ✗ |
| Access logs/metrics/settings | ✓ | ✓ | ✗ |
<Tip>
The organization owner always has access. In private mode, only whitelisted
users and roles can view, run, and access logs/metrics/settings.
</Tip>
<Frame>
<img src="/images/enterprise/visibility.png" alt="Automation Visibility settings in CrewAI AMP" />
</Frame>
### Deployment Permission Types
When granting entity-level access to a specific automation, you can assign these permission types:
| Permission | What it allows |
| :------------------- | :-------------------------------------------------- |
| `run` | Execute the automation and use its API |
| `traces` | View execution traces and logs |
| `manage_settings` | Edit, redeploy, rollback, or delete the automation |
| `human_in_the_loop` | Respond to human-in-the-loop (HITL) requests |
| `full_access` | All of the above |
### Entity-level RBAC for Other Resources
When entity-level RBAC is enabled, access to these resources can also be controlled per user or role:
| Resource | Controlled by | Description |
| :--------------------- | :------------------------------- | :---------------------------------------------------- |
| Environment variables | Entity RBAC feature flag | Restrict which roles/users can view or manage specific env vars |
| LLM connections | Entity RBAC feature flag | Restrict access to specific LLM provider configurations |
| Git repositories | Git repositories RBAC org setting | Restrict which roles/users can access specific connected repos |
---
## Common Role Patterns
While CrewAI ships with Owner and Member roles, most teams benefit from creating custom roles. Here are common patterns:
### Developer Role
A role for team members who build and deploy automations but don't manage organization settings.
| Feature | Permission |
| :------------------------ | :--------- |
| `usage_dashboards` | Read |
| `crews_dashboards` | Manage |
| `invitations` | Read |
| `training_ui` | Read |
| `tools` | Manage |
| `agents` | Manage |
| `environment_variables` | Manage |
| `llm_connections` | Manage |
| `default_settings` | No access |
| `organization_settings` | No access |
| `studio_projects` | Manage |
### Viewer / Stakeholder Role
A role for non-technical stakeholders who need to monitor automations and view results.
| Feature | Permission |
| :------------------------ | :--------- |
| `usage_dashboards` | Read |
| `crews_dashboards` | Read |
| `invitations` | No access |
| `training_ui` | Read |
| `tools` | Read |
| `agents` | Read |
| `environment_variables` | No access |
| `llm_connections` | No access |
| `default_settings` | No access |
| `organization_settings` | No access |
| `studio_projects` | No access |
### Ops / Platform Admin Role
A role for platform operators who manage infrastructure settings but may not build agents.
| Feature | Permission |
| :------------------------ | :--------- |
| `usage_dashboards` | Manage |
| `crews_dashboards` | Manage |
| `invitations` | Manage |
| `training_ui` | Read |
| `tools` | Read |
| `agents` | Read |
| `environment_variables` | Manage |
| `llm_connections` | Manage |
| `default_settings` | Manage |
| `organization_settings` | Read |
| `studio_projects` | No access |
---
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with RBAC questions.
</Card>

321
docs/edge/en/enterprise/features/secrets-manager/aws-workload-identity.mdx Normal file
View File

@@ -0,0 +1,321 @@
---
title: AWS Workload Identity (OIDC Federation)
description: Configure AWS Secrets Manager via Workload Identity for rotation-aware, credential-free secret access
sidebarTitle: With Workload Identity
icon: "id-badge"
---
## Overview
This guide configures AWS Secrets Manager as a secret provider using **Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for AWS credentials via STS, and reads your secrets — without a long-lived AWS access key being stored anywhere.
<Note>
**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials and don't care about rotation propagation, see the simpler [AWS — static keys / AssumeRole](/en/enterprise/features/secrets-manager/aws) guide.
</Note>
### How it works at runtime
1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform.
2. The worker calls `sts:AssumeRoleWithWebIdentity` on the IAM role you set up below, presenting the JWT.
3. AWS STS validates the JWT against CrewAI Platform's public OIDC issuer (so your platform installation must be reachable from AWS), then returns short-lived AWS credentials.
4. The worker uses those credentials to call `secretsmanager:GetSecretValue`.
5. The fetched value is injected as the environment variable's value for that automation kickoff.
OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware.
## Prerequisites
<Note>
Before starting, make sure you have:
- The automation pod image must include CrewAI runtime version `1.14.5` or later.
- An AWS account with permission to create IAM OIDC providers, IAM roles, and IAM policies.
- The AWS region where your secrets live (or will live), e.g. `us-east-1`.
- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
- **Your CrewAI organization UUID.** Find it on the organization's settings page in CrewAI Platform — the trust policy in Step 3 binds the IAM role to this specific organization.
- **Your CrewAI Platform installation must be reachable from AWS over HTTPS** so that AWS STS can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible (or that AWS has network reach to it via VPC peering / equivalent).
</Note>
## Step 1 — Find Your CrewAI Platform OIDC Issuer URL
Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https://<your-platform-host>/.well-known/openid-configuration`. The `issuer` field in that document is the URL AWS will register as a trusted OIDC provider.
Open the URL in a browser (replacing `<your-platform-host>` with your actual hostname, e.g. `app.crewai.com`):
```
https://<your-platform-host>/.well-known/openid-configuration
```
You should see JSON containing:
```json
{
"issuer": "https://<your-platform-host>",
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
...
}
```
Note the exact value of `issuer` — you'll use it in Step 3.
<Tip>
If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration.
</Tip>
## Step 2 — Register CrewAI Platform as an IAM OIDC Identity Provider
Open the [IAM → Identity providers console](https://console.aws.amazon.com/iam/home#/identity_providers) and click **Add provider**.
- **Provider type:** OpenID Connect.
- **Provider URL:** the `issuer` value from Step 1 (e.g. `https://app.crewai.com`).
- **Audience:** `sts.amazonaws.com`
Click **Add provider**.
Or via CLI:
```bash
aws iam create-open-id-connect-provider \
--url "https://<your-platform-host>" \
--client-id-list "sts.amazonaws.com" \
--thumbprint-list "$(echo | openssl s_client -servername <your-platform-host> -connect <your-platform-host>:443 2>/dev/null | openssl x509 -fingerprint -noout -sha1 | cut -d= -f2 | tr -d ':')"
```
Copy the **OpenIDConnectProviderArn** from the output (or the provider's ARN from the console). You'll use it in Step 3.
<Note>
AWS does not actually validate the thumbprint for STS WebIdentity calls — it always re-fetches the JWKS at validation time — but the API requires the field to be present.
</Note>
{/* SCREENSHOT: AWS IAM "Add identity provider" form filled with the Platform issuer URL and audience sts.amazonaws.com → /images/secrets-manager/aws-wi/01-add-oidc-provider.png */}
{/* SCREENSHOT: Provider detail page showing the provider's ARN → /images/secrets-manager/aws-wi/02-oidc-provider-arn.png */}
## Step 3 — Create the IAM Role
Save as `trust-policy.json`, replacing `<YOUR_ACCOUNT_ID>`, `<your-platform-host>` (the issuer host **without** `https://` or `http://`, e.g. `app.crewai.com`), and `<YOUR_CREWAI_ORG_UUID>` (from the Prerequisites):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::<YOUR_ACCOUNT_ID>:oidc-provider/<your-platform-host>"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"<your-platform-host>:aud": "sts.amazonaws.com",
"<your-platform-host>:sub": "organization:<YOUR_CREWAI_ORG_UUID>"
}
}
}
]
}
```
Create the role:
```bash
aws iam create-role \
--role-name crewai-secrets-reader \
--assume-role-policy-document file://trust-policy.json
```
Copy the **Role Arn** from the output — that's your `aws_role_arn`. You'll paste it into CrewAI Platform in Step 6.
<Tip>
The two conditions scope the trust precisely: `aud` restricts assumption to tokens with the AWS STS audience, and `sub` scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted. CrewAI Platform always sets both claims on AWS workload identity tokens.
</Tip>
{/* SCREENSHOT: IAM "Create role" with Web Identity trust type, federated provider selector pointing at the CrewAI Platform OIDC provider → /images/secrets-manager/aws-wi/03-create-role-trust.png */}
## Step 4 — Create and attach the IAM policy for Secrets Manager + KMS access
Save as `secrets-policy.json`, replacing the placeholders with your account ID, region, secret-name prefix, and the KMS key ARN(s) that encrypt those secrets:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerListForUI",
"Effect": "Allow",
"Action": "secretsmanager:ListSecrets",
"Resource": "*"
},
{
"Sid": "SecretsManagerRead",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:<REGION>:<YOUR_ACCOUNT_ID>:secret:<SECRET_NAME_PREFIX>-*"
},
{
"Sid": "KMSDecrypt",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:<REGION>:<YOUR_ACCOUNT_ID>:key/<KMS_KEY_ID>"
}
]
}
```
`SecretsManagerListForUI` powers the **Secret Name autocomplete** in the Environment Variables form and the **Test Connection** button on the credential. `secretsmanager:ListSecrets` only accepts `Resource: "*"` — it is account-scoped at the IAM layer.
Attach the policy to the role using either the CLI (inline policy, simplest) or the console UI; for environments that reuse the same permissions across many roles, use the **Managed policy** tab for a reusable, named policy.
<Tabs>
<Tab title="Inline policy (CLI)">
```bash
aws iam put-role-policy \
--role-name crewai-secrets-reader \
--policy-name SecretsManagerRead \
--policy-document file://secrets-policy.json
```
This attaches the policy **inline** to the role. Inline policies are tied to the role and cannot be reused on other roles.
</Tab>
<Tab title="Managed policy (CLI, reusable)">
```bash
POLICY_ARN=$(aws iam create-policy \
--policy-name CrewAISecretsReader \
--policy-document file://secrets-policy.json \
--query 'Policy.Arn' --output text)
aws iam attach-role-policy \
--role-name crewai-secrets-reader \
--policy-arn "$POLICY_ARN"
```
A managed policy is a standalone IAM resource you can attach to multiple roles.
</Tab>
<Tab title="Console (UI)">
1. Open the [IAM → Roles console](https://console.aws.amazon.com/iam/home#/roles) and select **crewai-secrets-reader**.
2. On the **Permissions** tab, click **Add permissions** → **Create inline policy**.
3. Switch to the **JSON** editor and paste the contents of `secrets-policy.json`.
4. Click **Next**, give the policy a name (e.g. `SecretsManagerRead`), and click **Create policy**.
To create a reusable managed policy instead, use **IAM → Policies → Create policy** and then attach it to the role from the role's **Permissions** tab.
{/* SCREENSHOT: IAM Role detail → Permissions → Create inline policy with JSON editor → /images/secrets-manager/aws-wi/03b-attach-inline-policy.png */}
</Tab>
</Tabs>
## Step 5 — Create at Least One Secret in AWS
If you don't already have a secret to test against, create one now:
```bash
aws secretsmanager create-secret \
--region <REGION> \
--name crewai-test-keyword \
--secret-string "hello from aws"
```
Or via the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/) → **Store a new secret**.
{/* SCREENSHOT: AWS Secrets Manager "Store a new secret" page with a sample value → /images/secrets-manager/aws-wi/04-create-secret.png */}
## Step 6 — Add a Workload Identity Configuration in CrewAI Platform
In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**.
{/* SCREENSHOT: Sidebar highlighting Settings → Workload Identity → /images/secrets-manager/aws-wi/05-amp-settings-wi-nav.png */}
{/* SCREENSHOT: Empty state of Workload Identity page with "Add Workload Identity Config" button → /images/secrets-manager/aws-wi/06-amp-wi-empty-state.png */}
Fill the form:
- **Name:** A descriptive name, e.g. `aws-prod`.
- **Cloud Provider:** `AWS`.
- **AWS Role ARN:** the **Role Arn** from Step 3.
- **AWS Region:** the region where your secrets live, e.g. `us-east-1`.
- (Optional) Check **Set as default for AWS** if you'd like this WI config to be the default selected when creating an AWS-backed secret credential.
Click **Create**.
{/* SCREENSHOT: "Add Workload Identity Config" form with AWS, role ARN, and region filled in → /images/secrets-manager/aws-wi/07-amp-add-wi-config-aws.png */}
{/* SCREENSHOT: Workload Identity list showing the new AWS row with "(default)" badge if applicable → /images/secrets-manager/aws-wi/08-amp-wi-list-with-aws.png */}
## Step 7 — Add a Secret Provider Credential Bound to the WI Config
Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
Fill the form:
- **Name:** A descriptive name, e.g. `aws-prod-wi`.
- **Provider:** `AWS Secrets Manager`.
- **Authentication Method:** `Workload Identity` (instead of static keys / AssumeRole).
- **Workload Identity Configuration:** select the config you created in Step 6 (e.g. `aws-prod`).
- (Optional) Check **Set as default credential for this provider**.
The form will only ask for **AWS Region** under Workload Identity — the static-credential fields (Access Key ID, Secret Access Key, Role ARN, External ID) are intentionally hidden because they don't apply to this path; the role ARN comes from the linked WI config.
Click **Create**.
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + Workload Identity + WI config dropdown selected → /images/secrets-manager/aws-wi/09-amp-add-credential-aws-wi.png */}
## Step 8 — Test the Connection
After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT, exchanges it with AWS STS via `sts:AssumeRoleWithWebIdentity`, and confirms the resulting credentials can call `sts:GetCallerIdentity` against the assumed role. A green result means the federation binding is healthy.
A successful Test Connection proves the trust policy, OIDC provider registration, and audience condition are all wired correctly. It does **not** prove per-secret IAM is correct — `secretsmanager:GetSecretValue` on a specific secret ARN is exercised separately when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes.
## Step 9 — Reference the Secret in an Environment Variable
Now reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior.
The only difference between WI-backed and static-keys-backed env vars is **when** the secret is read:
- **WI-backed:** secret value is read fresh on every automation kickoff.
- **Static-keys-backed:** secret value is read at deploy time and baked into the deployment image.
## Step 10 — Verify Rotation
After the deployment is running, rotate the secret in AWS:
```bash
aws secretsmanager update-secret \
--region <REGION> \
--secret-id crewai-test-keyword \
--secret-string "rotated value"
```
Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no waiting on a TTL.
To confirm in logs (if you have access to the worker), look for:
```
Workload identity config '<id>' (aws): N secret(s) resolved
```
This line appears for every kickoff and indicates a fresh `GetSecretValue` call against AWS.
## Troubleshooting
| Symptom | Likely cause |
|---|---|
| Test Connection fails with a handshake error | The `sts:AssumeRoleWithWebIdentity` call was rejected. Verify the trust policy's federated principal ARN references `oidc-provider/<your-platform-host>` (host **without** `https://` or `http://`, no trailing slash), the audience condition is exactly `sts.amazonaws.com`, the `sub` condition matches your CrewAI organization UUID, and the platform's OIDC discovery URL is reachable from AWS over the public internet. |
| `InvalidIdentityToken: Couldn't retrieve verification key from your identity provider` | AWS STS can't reach your CrewAI Platform host to fetch JWKS. Confirm the host is internet-accessible from AWS, the OIDC discovery URL returns 200, and the JWKS endpoint is reachable. |
| `AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity` | Trust policy mismatch. Re-check Step 3: the federated principal ARN must include `oidc-provider/<your-platform-host>` (host **without** `https://` or `http://`, no trailing slash), the audience condition must be exactly `sts.amazonaws.com`, and the `sub` condition must equal `organization:<YOUR_CREWAI_ORG_UUID>`. |
| Secret Name autocomplete shows `AccessDenied: secretsmanager:ListSecrets` | The role is missing `secretsmanager:ListSecrets` with `Resource: "*"`. Add the `SecretsManagerListForUI` statement from Step 4. |
| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but resource-scoped IAM is missing on the failing secret. Audit the role's `secretsmanager:GetSecretValue` and `kms:Decrypt` permissions for that specific secret's ARN and KMS key. |
| `RegionDisabledException` / no secrets found | The region in the Workload Identity Config doesn't match where the secret lives. Re-check Step 6. |
| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. |
### Reference Links
- AWS: [Creating OpenID Connect (OIDC) identity providers](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
- AWS: [Configuring a role for OpenID Connect federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_relying-party.html)
- AWS: [STS:AssumeRoleWithWebIdentity API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)
## Next Steps
- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
- For multi-cloud, see also [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) and [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity).

295
docs/edge/en/enterprise/features/secrets-manager/aws.mdx Normal file
View File

@@ -0,0 +1,295 @@
---
title: AWS Secrets Manager (Static Credentials)
description: Configure AWS Secrets Manager as a secret provider for CrewAI Platform using static access keys or AssumeRole
sidebarTitle: With Static Credentials
icon: "key"
---
## Overview
This guide walks you through configuring AWS Secrets Manager as a secret provider for your CrewAI Platform organization, using **static credentials** (access keys, optionally with AssumeRole). By the end, CrewAI Platform will be able to read secrets stored in your AWS account and inject them as environment variable values at runtime.
<Note>
This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff (no re-deploy), see [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity).
</Note>
<Note>
This guide covers the AWS-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage).
</Note>
## Prerequisites
<Note>
Before starting, make sure you have:
- An AWS account with permission to create IAM users, customer-managed policies, and (optionally) IAM roles.
- The AWS region where your secrets live (or will live), for example `us-east-1`.
- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
</Note>
## Choose an Authentication Method
CrewAI Platform supports two ways for the platform to authenticate with AWS Secrets Manager. Pick one before you begin — the steps below differ depending on which you choose.
| Method | When to use | Trade-offs |
|---|---|---|
| **Static access keys** | Getting started, single-account deployments | Simplest setup; access keys must be rotated manually |
| **AssumeRole** | Cross-account, production hardening | Short-lived credentials; supports External ID; requires extra IAM role |
The rest of this guide uses tabs in Steps 3–5 so you can follow the path that matches your choice.
## Step 1 — Create an IAM User
Open the [IAM console](https://console.aws.amazon.com/iam/), navigate to **Users**, then click **Create user**.
- Suggested name: `crewai-secrets-reader`.
- Leave **Provide user access to the AWS Management Console** unchecked — this principal is used programmatically by CrewAI Platform, not by humans.
- Click **Next**.
On the **Set permissions** page, leave the default selection. You will attach the policy in Step 3.
Click **Next**, review, and click **Create user**.
For full details, see the AWS documentation: [Create an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
{/* SCREENSHOT: AWS IAM "Create user" form filled with name "crewai-secrets-reader" → /images/secrets-manager/aws/01-create-iam-user.png */}
## Step 2 — Create the IAM Policy
CrewAI Platform needs read-only access to AWS Secrets Manager and permission to decrypt secrets via KMS. Create a customer-managed policy with the following JSON.
In the IAM console, navigate to **Policies**, then click **Create policy**.
Choose the **JSON** tab and replace the contents with:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerRead",
"Effect": "Allow",
"Action": [
"secretsmanager:ListSecrets",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": "*"
},
{
"Sid": "KMSDecrypt",
"Effect": "Allow",
"Action": [
"kms:DescribeKey",
"kms:Decrypt"
],
"Resource": "*"
}
]
}
```
Click **Next**, then on the **Review and create** page:
- **Policy name:** `CrewAISecretsManagerRead`
- **Description (optional):** `Read-only access to AWS Secrets Manager for CrewAI Platform`
Click **Create policy**.
<Tip>
The policy above grants `*` on `Resource` for simplicity. In production, scope the `Resource` down to the ARNs of the specific secrets CrewAI Platform should access, and scope `kms:Decrypt` to the specific KMS key ARNs that encrypt those secrets. See the [AWS guidance on least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html).
</Tip>
{/* SCREENSHOT: AWS IAM "Create policy" → JSON tab with the policy above pasted → /images/secrets-manager/aws/02-create-policy-json-editor.png */}
{/* SCREENSHOT: AWS IAM "Review and create policy" page with name "CrewAISecretsManagerRead" → /images/secrets-manager/aws/03-policy-review-and-create.png */}
## Step 3 — Attach the Policy
<Tabs>
<Tab title="Static access keys">
1. In the IAM console, navigate to **Users** and click the user you created in Step 1.
2. On the **Permissions** tab, click **Add permissions** → **Attach policies directly**.
3. Search for `CrewAISecretsManagerRead`, select it, and click **Next**.
4. Click **Add permissions**.
{/* SCREENSHOT: "Add permissions" → "Attach policies directly" with CrewAISecretsManagerRead selected → /images/secrets-manager/aws/04a-attach-policy-to-user.png */}
</Tab>
<Tab title="AssumeRole">
With AssumeRole, the policy is attached to a separate IAM **role** (not directly to the user). The user from Step 1 only needs permission to call `sts:AssumeRole` on that role.
**Create the role:**
1. In the IAM console, navigate to **Roles** and click **Create role**.
2. **Trusted entity type:** AWS account. Choose **This account** (or **Another AWS account** for cross-account setups, then enter the AWS account ID hosting the IAM user from Step 1).
3. (Recommended) Check **Require external ID** and enter a value you generate yourself — this is a shared secret you will paste into CrewAI Platform in Step 5.
4. Click **Next**.
5. Attach the `CrewAISecretsManagerRead` policy.
6. Click **Next**, name the role `CrewAISecretsManagerRole`, and click **Create role**.
**Allow the IAM user to assume the role:**
1. Open the role you just created and copy its **ARN**.
2. In the IAM console, navigate to **Users**, click the user from Step 1, and on the **Permissions** tab click **Add permissions** → **Create inline policy**.
3. On the **JSON** tab, paste the following (replace `ROLE_ARN_FROM_ABOVE`):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "ROLE_ARN_FROM_ABOVE"
}
]
}
```
4. Name the policy `CrewAIAssumeSecretsRole` and click **Create policy**.
{/* SCREENSHOT: IAM "Create role" trust policy step with External ID checkbox enabled → /images/secrets-manager/aws/04b-create-role-trust-policy.png */}
{/* SCREENSHOT: Inline sts:AssumeRole policy attached to the IAM user → /images/secrets-manager/aws/04c-attach-assumerole-on-user.png */}
</Tab>
</Tabs>
## Step 4 — Get Credentials
<Tabs>
<Tab title="Static access keys">
1. In the IAM console, open the user from Step 1.
2. Click the **Security credentials** tab.
3. Under **Access keys**, click **Create access key**.
4. Select **Application running outside AWS** (or **Other**) as the use case. Click **Next**.
5. (Optional) Add a description tag. Click **Create access key**.
6. Click **Show** to reveal the secret access key, then copy both the **Access key ID** and the **Secret access key**, or click **Download .csv file**.
<Warning>
The secret access key is shown only once. If you close this page without copying it, you will need to delete the key and create a new one.
</Warning>
For full details, see the AWS documentation: [Manage access keys for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html).
{/* SCREENSHOT: Access key use-case selector ("Application running outside AWS") → /images/secrets-manager/aws/05a-create-access-key-use-case.png */}
{/* SCREENSHOT: "Retrieve access keys" page with Show/Download buttons → /images/secrets-manager/aws/06a-retrieve-access-keys.png */}
</Tab>
<Tab title="AssumeRole">
Even with AssumeRole, CrewAI Platform still needs an access key for the IAM user — it uses those keys as the calling identity to perform the `sts:AssumeRole` call.
1. Create an access key for the user exactly as described in the **Static access keys** tab above.
2. Open the role you created in Step 3 and copy:
- The **Role ARN** (from the role summary).
- The **External ID** you configured (if any) — you set this yourself in Step 3, so make sure you have it on hand.
{/* SCREENSHOT: IAM role detail page showing Role ARN → /images/secrets-manager/aws/05b-role-arn-detail.png */}
</Tab>
</Tabs>
## Step 5 — Add the Credential in CrewAI Platform
In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
{/* SCREENSHOT: Empty state of Secret Provider Credentials page with "Add Credential" button → /images/secrets-manager/usage/02-amp-credentials-empty-state.png */}
<Tabs>
<Tab title="Static access keys">
Fill the form:
- **Name:** A descriptive name, e.g. `aws-prod`.
- **Provider:** `AWS Secrets Manager`.
- **Region:** The AWS region where your secrets live, e.g. `us-east-1`. This must match the region of the secrets you want to read.
- **Access Key ID:** The value from Step 4.
- **Secret Access Key:** The value from Step 4.
- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference AWS secrets without specifying a credential explicitly.
Leave **Role ARN** and **External ID** blank.
Click **Create**.
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + static access keys filled in → /images/secrets-manager/usage/03a-amp-add-credential-form-aws-static.png */}
</Tab>
<Tab title="AssumeRole">
Fill the form:
- **Name:** A descriptive name, e.g. `aws-prod-assumerole`.
- **Provider:** `AWS Secrets Manager`.
- **Region:** The AWS region where your secrets live.
- **Access Key ID:** The IAM user's access key from Step 4 (used to call STS).
- **Secret Access Key:** The IAM user's secret access key from Step 4.
- **Role ARN:** The Role ARN you copied in Step 4.
- **External ID:** The External ID you set on the role's trust policy (omit if none).
- (Optional) Check **Set as default credential for this provider**.
Click **Create**.
{/* SCREENSHOT: "Add Secret Provider Credential" form with AWS + AssumeRole fields filled in → /images/secrets-manager/usage/03b-amp-add-credential-form-aws-assumerole.png */}
</Tab>
</Tabs>
<Note>
**How the two modes behave at runtime:**
- With **static access keys** only, CrewAI Platform calls AWS Secrets Manager directly using the keys you supplied.
- When a **Role ARN** is set, CrewAI Platform first calls `sts:AssumeRole` with the supplied access keys (and External ID if configured), then uses the short-lived credentials returned by STS to read your secrets.
</Note>
{/* SCREENSHOT: Credentials list showing the new AWS row, with "(default)" badge if applicable → /images/secrets-manager/usage/04-amp-credential-created.png */}
## Step 6 — Create at Least One Secret in AWS
If you do not already have secrets in AWS Secrets Manager, create one now so you can verify the connection in Step 7.
In the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/), click **Store a new secret**.
- **Secret type:** Choose **Other type of secret**.
- **Key/value pairs** — either:
- Enter one or more key/value pairs (recommended for structured secrets), or
- Use the **Plaintext** tab for a single string value.
- **Encryption key:** Use `aws/secretsmanager` (the AWS-managed key) unless you have a specific KMS key requirement.
Click **Next**, then enter:
- **Secret name:** A unique name, e.g. `crewai/openai-api-key`.
- **Description (optional):** A short note about what the secret is for.
Click **Next** through the rotation and review steps, then click **Store**.
<Note>
**JSON-key reference syntax.** If you store a secret with multiple key/value pairs (a JSON object), CrewAI Platform can extract a specific field using the `secret-name#json_key` syntax in environment variable references. For example, a secret named `database-credentials` with `{"username": "...", "password": "..."}` can be referenced as `database-credentials#password`. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details.
</Note>
For full details, see the AWS documentation: [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).
{/* SCREENSHOT: AWS Secrets Manager "Choose secret type" page → /images/secrets-manager/aws/07-create-secret-store-type.png */}
{/* SCREENSHOT: AWS Secrets Manager "Configure secret" page with name and description → /images/secrets-manager/aws/08-create-secret-name.png */}
## Step 7 — Test the Connection
Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**.
A success toast confirms that CrewAI Platform can authenticate to AWS and read secrets from your account.
{/* SCREENSHOT: Success toast after clicking "Test Connection" → /images/secrets-manager/usage/05-amp-test-connection-success.png */}
If the test fails, check the most common causes:
| Symptom | Likely cause |
|---|---|
| `AccessDenied` on `secretsmanager:ListSecrets` | Policy not attached, or wrong user. Re-check Step 3. |
| `AccessDenied` on `kms:Decrypt` | Missing the `KMSDecrypt` statement, or your secrets use a customer-managed KMS key not covered by `Resource: "*"`. |
| `InvalidClientTokenId` / `SignatureDoesNotMatch` | Wrong access key ID or secret access key. Re-check Step 4 and Step 5. |
| `RegionDisabledException` / no secrets found | The credential's **Region** does not match where your secrets actually live. |
| `AccessDenied` on `sts:AssumeRole` (AssumeRole only) | Inline `sts:AssumeRole` policy missing on the IAM user, or the role's trust policy does not allow this principal, or the External ID does not match. |
| Test passes immediately after creating the IAM user, but fails next time | IAM credentials sometimes take a minute or two to propagate globally. Retry. |
## Next Steps
Now that AWS is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to:
- Grant org members the right permissions to use (or manage) Secrets Manager.
- Reference your AWS secrets from CrewAI Platform environment variables.
If you want **rotation-aware** secrets that propagate without re-deploying, switch to [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff.

275
docs/edge/en/enterprise/features/secrets-manager/azure-workload-identity.mdx Normal file
View File

@@ -0,0 +1,275 @@
---
title: Azure Workload Identity Federation
description: Configure Azure Key Vault via Microsoft Entra Workload Identity Federation for rotation-aware, credential-free secret access
sidebarTitle: With Workload Identity
icon: "id-badge"
---
## Overview
This guide configures Azure Key Vault as a secret provider using **Microsoft Entra Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for an Entra access token via the Microsoft identity platform, and reads your secrets — without any client secret being stored anywhere.
<Note>
**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials, see the simpler [Azure Key Vault — client secret](/en/enterprise/features/secrets-manager/azure) guide.
</Note>
### How it works at runtime
1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform.
2. The worker presents the JWT to Microsoft Entra at `https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token` as a `client_assertion` (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`), referencing the App Registration whose **Federated Identity Credential** matches the JWT's issuer + subject.
3. Entra validates the JWT against your platform's OIDC discovery document and JWKS, then returns a short-lived access token scoped to `https://vault.azure.net/.default`.
4. The worker calls Azure Key Vault to read the secret.
5. The fetched value is injected as the environment variable's value for that automation kickoff.
OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware.
## Prerequisites
<Note>
Before starting, make sure you have:
- The automation pod image must include CrewAI runtime version `1.14.5` or later.
- An Azure subscription and a Microsoft Entra tenant you can manage.
- Permission in the tenant to create App Registrations and add Federated Identity Credentials.
- A Key Vault using **Azure RBAC** for authorization (not the legacy access-policy model).
- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
- **Your CrewAI Platform installation must be reachable from Microsoft Entra over HTTPS** so that Entra can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible.
</Note>
## Step 1 — Find Your CrewAI Platform OIDC Issuer URL
Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https://<your-platform-host>/.well-known/openid-configuration`. The `issuer` field there is the URL Microsoft Entra will register as a trusted federation issuer.
Open the URL in a browser:
```
https://<your-platform-host>/.well-known/openid-configuration
```
You should see JSON containing:
```json
{
"issuer": "https://<your-platform-host>",
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
...
}
```
Note the exact value of `issuer` — you'll use it in Step 3.
<Tip>
If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration.
</Tip>
## Step 2 — Create an App Registration
In the [Microsoft Entra portal](https://entra.microsoft.com), navigate to **App registrations** and click **New registration**.
- **Name:** `crewai-secrets-reader`
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
- Leave **Redirect URI** blank.
Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** on the App's overview blade — you'll use them in Step 6.
{/* SCREENSHOT: Azure portal "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure-wi/01-register-app.png */}
## Step 3 — Add a Federated Identity Credential
The Federated Identity Credential tells Microsoft Entra: *trust JWTs minted by this issuer, with this subject, when they're presented as a client assertion for this App Registration.*
On the App Registration, navigate to **Certificates & secrets** → **Federated credentials** → **Add credential**.
- **Federated credential scenario:** `Other issuer`.
- **Issuer:** the CrewAI Platform issuer URL from Step 1, e.g. `https://<your-platform-host>`.
- **Subject identifier:** `organization:<YOUR_CREWAI_ORG_UUID>` — exactly the value of the JWT's `sub` claim. Find your org UUID in CrewAI Platform's organization settings. This scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted.
- **Name:** any descriptive label, e.g. `crewai-org-prod`.
- **Audience:** `api://AzureADTokenExchange`. This is the fixed audience Microsoft Entra requires for federated credentials and is what CrewAI Platform sets in the JWT's `aud` claim.
Click **Add**.
<Tip>
**Per-org isolation.** The subject identifier (`organization:<UUID>`) restricts the federated credential to a specific CrewAI organization's tokens. If multiple CrewAI organizations should share one App Registration, add one Federated Identity Credential per organization (each with the org's UUID).
</Tip>
For full details, see the Microsoft documentation: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust).
{/* SCREENSHOT: "Add credential" panel with scenario = "Other issuer", issuer URL, subject "organization:<uuid>", audience "api://AzureADTokenExchange" → /images/secrets-manager/azure-wi/02-add-federated-credential.png */}
## Step 4 — Grant the App Registration Access to Key Vault
Grant the App Registration **Key Vault Secrets User** on the target vault — the same role you'd use for the static-credentials path. Use either vault-wide (simpler) or per-secret (least privilege).
<Tabs>
<Tab title="Vault-wide (simpler)">
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
```
Vault-wide scope grants the `secrets/list` permission that the **Secret Name autocomplete** in CrewAI Platform's env-var form depends on. Choose this tab if you want autocomplete to work.
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure-wi/03-grant-vault-rbac.png */}
</Tab>
<Tab title="Per-secret (least privilege)">
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
```
Per-secret bindings disable the **Secret Name autocomplete** in CrewAI Platform's env-var form (autocomplete requires `secrets/list`, which is vault-scoped only). Type the full secret name instead.
{/* SCREENSHOT: Per-secret IAM panel with the App Registration assigned **Key Vault Secrets User** at the secret resource scope → /images/secrets-manager/azure-wi/04-per-secret-rbac.png */}
</Tab>
<Tab title="Portal (UI)">
For a **vault-wide** assignment:
1. Open your Key Vault in the Azure portal.
2. Click **Access control (IAM)** → **Add** → **Add role assignment**.
3. Select role **Key Vault Secrets User** → **Next**.
4. Click **Select members**, search for the App Registration `crewai-secrets-reader`, click **Select**.
5. Click **Review + assign**.
For a **per-secret** assignment, use the same flow but start from **Objects** → **Secrets** → select the secret → its own **Access control (IAM)** panel. Per-secret bindings disable autocomplete (see the Per-secret tab above).
</Tab>
</Tabs>
## Step 5 — Create at Least One Secret in Key Vault
If you don't already have a secret to test against, create one via the Azure CLI:
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name openai-api-key \
--value "sk-your-actual-key"
```
Or via the Azure portal:
1. Open your Key Vault and navigate to **Objects** → **Secrets**.
2. Click **Generate/Import**.
3. **Upload options:** `Manual`. **Name:** the secret name (e.g. `openai-api-key`). **Secret value:** paste the value.
4. Click **Create**.
<Note>
**Secret name conventions.** Azure Key Vault secret names cannot contain underscores. CrewAI Platform automatically converts underscores to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`), so you can keep underscore-style env-var names — but the underlying secret in Key Vault must use hyphens.
</Note>
## Step 6 — Add a Workload Identity Configuration in CrewAI Platform
In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**.
Fill the form:
- **Name:** A descriptive name, e.g. `azure-prod`.
- **Cloud Provider:** `Azure`.
- **Tenant ID:** your Microsoft Entra **Directory (tenant) ID** from Step 2.
- **Client ID:** your App Registration's **Application (client) ID** from Step 2.
- (Optional) Check **Set as default for Azure** if you'd like this to be the default WI config selected when creating an Azure-backed secret credential.
The **Audience** is fixed at `api://AzureADTokenExchange` — Microsoft Entra requires this exact audience for federated credentials, so no Audience field is shown on the form.
Click **Create**.
{/* SCREENSHOT: "Add Workload Identity Config" form with Azure, tenant ID, client ID populated → /images/secrets-manager/azure-wi/05-amp-add-wi-config-azure.png */}
{/* SCREENSHOT: Workload Identity list showing AWS, GCP, and Azure rows → /images/secrets-manager/azure-wi/06-amp-wi-list-with-azure.png */}
## Step 7 — Add a Secret Provider Credential Bound to the WI Config
Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
Fill the form:
- **Name:** A descriptive name, e.g. `azure-prod-wi`.
- **Provider:** `Azure Key Vault`.
- **Authentication Method:** `Workload Identity`.
- **Workload Identity Configuration:** select the config you created in Step 6.
- **Key Vault URL:** the vault's DNS hostname, e.g. `https://my-vault.vault.azure.net`.
- (Optional) Check **Set as default credential for this provider**.
The form will only ask for **Key Vault URL** under Workload Identity — the static-credential fields (Tenant ID, Client ID, Client Secret) are intentionally hidden because they don't apply to this path; tenant + client come from the linked WI config.
Click **Create**.
<Tip>
**One App Registration, many vaults.** The Key Vault URL lives on the credential, not the WI config. So one App Registration (and one WI config) can serve multiple Key Vaults — just create one Secret Provider Credential per vault, all linked to the same WI config.
</Tip>
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure + Workload Identity + WI config dropdown + vault URL → /images/secrets-manager/azure-wi/07-amp-add-credential-azure-wi.png */}
## Step 8 — Test the Connection
After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT, presents it to Microsoft Entra as a federated `client_assertion`, and confirms Entra returns a vault-scoped access token. A green result means the federation binding is healthy.
A successful Test Connection proves the Federated Identity Credential's issuer, subject, and audience all match, and that the App Registration is reachable. It does **not** prove per-secret Key Vault RBAC is correct — `getSecret` against a specific secret is exercised separately when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes.
## Step 9 — Reference the Secret in an Environment Variable
Reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior.
## Step 10 — Verify Rotation
After the deployment is running, rotate the secret in Key Vault:
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name openai-api-key \
--value "rotated value"
```
Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no TTL wait.
To confirm in worker logs, look for:
```
Workload identity config '<id>' (azure): N secret(s) resolved
```
This line appears for every kickoff and indicates a fresh `getSecret` call against Azure Key Vault.
For an end-to-end fingerprint-based verification, see [Verify Rotation End-to-End](/en/enterprise/features/secrets-manager/verify-rotation).
## Troubleshooting
| Symptom | Likely cause |
|---|---|
| Test Connection fails with a handshake error | The federated `client_assertion` was rejected by Microsoft Entra. Verify the Federated Identity Credential's **Issuer** matches the platform's `issuer` value exactly, **Subject** is `organization:<your-org-uuid>` (matching the JWT's `sub` claim), **Audience** is `api://AzureADTokenExchange`, and the platform's OIDC discovery URL is reachable from Entra over the public internet. |
| `AADSTS70021: No matching federated identity record found for presented assertion` | The Federated Identity Credential's **Issuer** + **Subject** + **Audience** don't all match the JWT exactly. Re-check Step 3: subject must be `organization:<your-org-uuid>` (matching the JWT's `sub` claim), audience must be `api://AzureADTokenExchange`. |
| `AADSTS700024: Client assertion is not within its valid time range` | The CrewAI Platform host's clock is significantly skewed from real time. Check NTP on the host. |
| `AADSTS50013: Assertion failed signature validation` | Microsoft Entra couldn't verify the JWT's signature. Confirm `https://<your-platform-host>/oauth2/jwks` is reachable from the public internet and serves a valid JWKS. |
| Secret Name autocomplete shows `Forbidden — does not have permission to perform action 'Microsoft.KeyVault/vaults/secrets/.../list'` | The App Registration's **Key Vault Secrets User** role is scoped to a single secret. Grant the role at the vault scope so the `list` data-plane action is allowed. See Step 4. |
| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but per-secret Key Vault RBAC is missing on the failing secret. Audit **Key Vault Secrets User** on that specific secret (or extend the role assignment to the vault scope). |
| `Forbidden — request was not authorized` (vault using legacy access policies) | The vault hasn't been switched to Azure RBAC. Under the vault's **Access configuration**, set permission model to **Azure role-based access control** and re-grant the role from Step 4. |
| `azure_vault_url is required for Azure secret resolution` (worker logs) | The Secret Provider Credential is missing **Key Vault URL**. Re-check Step 7. |
| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. |
### Reference Links
- Microsoft: [Microsoft Entra Workload Identity Federation overview](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation)
- Microsoft: [Configure a federated identity credential on an app](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust)
- Microsoft: [Azure Key Vault RBAC guide](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide)
## Next Steps
- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
- For multi-cloud, the AWS-equivalent setup is at [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) and the GCP-equivalent at [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity).
## Screenshot Reference
The placeholders above map to:
- `01-register-app.png` — Azure portal "Register an application" form filled with `crewai-secrets-reader`.
- `02-add-federated-credential.png` — App Registration → Certificates & secrets → Federated credentials → Add credential, with **Other issuer**, the platform issuer URL, subject `organization:<uuid>`, audience `api://AzureADTokenExchange`.
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, with **Key Vault Secrets User** and the App Registration selected.
- `04-per-secret-rbac.png` — Same form but at a single secret's IAM scope (alternative least-privilege path).
- `05-amp-add-wi-config-azure.png` — CrewAI Platform "Add Workload Identity Config" form with Cloud Provider = Azure, Tenant ID, Client ID populated.
- `06-amp-wi-list-with-azure.png` — Workload Identity list page after creation, showing rows for AWS, GCP, and the new Azure config.
- `07-amp-add-credential-azure-wi.png` — "Add Secret Provider Credential" form with Provider = Azure Key Vault, Auth = Workload Identity, the WI config picked, and Key Vault URL populated.

196
docs/edge/en/enterprise/features/secrets-manager/azure.mdx Normal file
View File

@@ -0,0 +1,196 @@
---
title: Azure Key Vault
description: Configure Azure Key Vault as a secret provider for CrewAI Platform, end-to-end
sidebarTitle: With Static Credentials
icon: "key"
---
## Overview
This guide walks you through configuring Azure Key Vault as a secret provider for your CrewAI Platform organization, using a **Microsoft Entra App Registration with a client secret**. By the end, CrewAI Platform will be able to read secrets stored in your Azure Key Vault and inject them as environment variable values at runtime.
<Note>
This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff, see [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity).
</Note>
<Note>
This guide covers the Azure-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage).
</Note>
## Prerequisites
<Note>
Before starting, make sure you have:
- An Azure subscription with permission to create App Registrations in Microsoft Entra and to grant role assignments on Key Vault resources.
- A Key Vault using **Azure RBAC** for authorization (not the legacy access-policy model). If your vault still uses access policies, switch it to RBAC under the vault's **Access configuration** blade.
- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
</Note>
## Step 1 — Create an App Registration
The App Registration is the Microsoft Entra-side identity CrewAI Platform will authenticate as.
In the [Microsoft Entra portal](https://entra.microsoft.com), navigate to **App registrations** and click **New registration**.
- **Name:** `crewai-secrets-reader`
- **Supported account types:** `Accounts in this organizational directory only (Single tenant)`.
- Leave **Redirect URI** blank.
Click **Register**. Note the **Application (client) ID** and **Directory (tenant) ID** on the App's overview blade — you'll paste both into CrewAI Platform in Step 4.
For full details, see the Microsoft documentation: [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
{/* SCREENSHOT: Azure "Register an application" form with name "crewai-secrets-reader" → /images/secrets-manager/azure/01-register-app.png */}
## Step 2 — Create a Client Secret
On the App Registration, navigate to **Certificates & secrets** → **Client secrets** → **New client secret**.
- **Description:** `crewai-platform`
- **Expires:** pick a duration that matches your rotation policy (Microsoft caps this at 24 months).
Click **Add**. Copy the **Value** column immediately — it can never be re-displayed once you leave the page.
<Warning>
Client secrets are long-lived static credentials. Store the value securely (in a password manager or your own secret store) and rotate it before expiry. To eliminate static credentials entirely, use [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) instead.
</Warning>
{/* SCREENSHOT: "Client secrets" tab with the new secret row and the "Value" column highlighted → /images/secrets-manager/azure/02-create-client-secret.png */}
## Step 3 — Grant the App Registration Access to Key Vault
CrewAI Platform needs read access to secrets in your Key Vault. Use one of two scopes — **vault-wide** for simplicity, or **per-secret** for least privilege.
<Tabs>
<Tab title="Vault-wide (simpler)">
In the [Key Vault console](https://portal.azure.com/#view/HubsExtension/BrowseResource/resourceType/Microsoft.KeyVault%2Fvaults), open the target vault, then navigate to **Access control (IAM)** → **Add** → **Add role assignment**.
- **Role:** **Key Vault Secrets User**
- **Assign access to:** User, group, or service principal
- **Members:** search for and select your App Registration (`crewai-secrets-reader`).
Click **Review + assign**.
Or via the Azure CLI:
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault show --name <VAULT_NAME> --query id -o tsv)
```
{/* SCREENSHOT: Key Vault "Add role assignment" panel with "Key Vault Secrets User" and the App Registration selected → /images/secrets-manager/azure/03-grant-vault-rbac.png */}
</Tab>
<Tab title="Per-secret (least privilege)">
Grant the role at the level of an individual secret. Repeat for each secret CrewAI Platform should access:
```bash
az role assignment create \
--assignee <APPLICATION_CLIENT_ID> \
--role "Key Vault Secrets User" \
--scope $(az keyvault secret show --vault-name <VAULT_NAME> --name <SECRET_NAME> --query id -o tsv)
```
{/* SCREENSHOT: Per-secret "Access control (IAM)" panel showing role assignment scoped to one secret → /images/secrets-manager/azure/04-per-secret-rbac.png */}
</Tab>
</Tabs>
<Tip>
The **Key Vault Secrets User** role allows reading secret values but not listing all secrets in the vault. CrewAI Platform's secret-name autocomplete also calls `list` — that permission is included by the role at the vault scope, but **not** at the per-secret scope. With per-secret bindings, autocomplete won't suggest secrets; type the full secret name instead.
</Tip>
## Step 4 — Add the Credential in CrewAI Platform
In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
Fill the form:
- **Name:** A descriptive name, e.g. `azure-prod`.
- **Provider:** `Azure Key Vault`.
- **Key Vault URL:** the vault's DNS hostname, e.g. `https://my-vault.vault.azure.net`.
- **Tenant ID:** your Microsoft Entra **Directory (tenant) ID** from Step 1.
- **Client ID:** your App Registration's **Application (client) ID** from Step 1.
- **Client Secret:** the **Value** you copied in Step 2.
- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference Azure secrets without specifying a credential explicitly.
Click **Create**.
{/* SCREENSHOT: "Add Secret Provider Credential" form with Azure fields filled in → /images/secrets-manager/azure/05-amp-add-credential-form-azure.png */}
## Step 5 — Create at Least One Secret in Azure Key Vault
If you don't already have secrets in Key Vault, create one now so you can verify the connection in Step 6.
In the Key Vault console, navigate to **Objects** → **Secrets** → **Generate/Import**.
- **Upload options:** `Manual`
- **Name:** e.g. `openai-api-key`
- **Secret value:** paste your secret value
- Leave the rest at defaults.
Click **Create**.
Or via the Azure CLI:
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name openai-api-key \
--value "sk-your-actual-key"
```
<Note>
**Secret name conventions.** Azure Key Vault secret names cannot contain underscores. CrewAI Platform automatically converts underscores to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`), so you can keep underscore-style env-var names — but the underlying secret in Key Vault must use hyphens.
</Note>
<Note>
**JSON-key reference syntax.** Key Vault treats secret values as opaque strings. If your secret value happens to be a JSON object, CrewAI Platform can extract a single field using the `secret-name#json_key` syntax (e.g. `database-credentials#password`). See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details.
</Note>
For full details, see the Microsoft documentation: [Set and retrieve a secret](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli).
{/* SCREENSHOT: Azure Key Vault "Create a secret" form with name and value → /images/secrets-manager/azure/06-create-secret.png */}
## Step 6 — Test the Connection
Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**.
A success toast confirms that CrewAI Platform can authenticate to Microsoft Entra and read secrets from your vault.
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the Azure credential → /images/secrets-manager/azure/07-test-connection-success.png */}
If the test fails, check the most common causes:
| Symptom | Likely cause |
|---|---|
| `AADSTS7000215: Invalid client secret provided` | The pasted **Client Secret** is wrong or expired. Re-create the secret (Step 2) and update the credential. |
| `AADSTS700016: Application not found in the directory` | The **Tenant ID** or **Client ID** doesn't match the App Registration. Re-check Step 4. |
| `Forbidden — caller does not have permission` | The App Registration is missing the **Key Vault Secrets User** role on the vault (or per-secret). Re-check Step 3. |
| `Vault not found` / DNS errors | The **Key Vault URL** is wrong, or your vault has private endpoints that block public access. Confirm the host responds to `curl https://<vault-name>.vault.azure.net/secrets?api-version=7.4`. |
| `Forbidden — request was not authorized` (vault using legacy access policies) | The vault hasn't been switched to Azure RBAC. Under the vault's **Access configuration**, set permission model to **Azure role-based access control** and re-grant the role from Step 3. |
## Next Steps
Now that Azure Key Vault is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to:
- Grant org members the right permissions to use (or manage) Secrets Manager.
- Reference your Azure secrets from CrewAI Platform environment variables.
If you want **rotation-aware** secrets that propagate without re-deploying, switch to [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) — same vault, no client secret to rotate, secrets are fetched per kickoff.
## Screenshot Reference
The placeholders above map to:
- `01-register-app.png` — Azure portal "Register an application" form filled with `crewai-secrets-reader`.
- `02-create-client-secret.png` — App Registration → Certificates & secrets → Client secrets, with the freshly-created secret row visible (Value column highlighted before it gets masked).
- `03-grant-vault-rbac.png` — Key Vault → Access control (IAM) → Add role assignment, with **Key Vault Secrets User** picked and the App Registration selected as a member.
- `04-per-secret-rbac.png` — Same panel but scoped to a single secret resource (alternative least-privilege path).
- `05-amp-add-credential-form-azure.png` — CrewAI Platform "Add Secret Provider Credential" form: Provider = Azure Key Vault, all five fields populated.
- `06-create-secret.png` — Azure Key Vault "Create a secret" panel with `openai-api-key` and a pasted value.
- `07-test-connection-success.png` — CrewAI Platform success toast / row state after clicking **Test Connection** on the credential.

273
docs/edge/en/enterprise/features/secrets-manager/gcp-workload-identity.mdx Normal file
View File

@@ -0,0 +1,273 @@
---
title: GCP Workload Identity Federation
description: Configure Google Cloud Secret Manager via Workload Identity Federation for rotation-aware, credential-free secret access
sidebarTitle: With Workload Identity
icon: "id-badge"
---
## Overview
This guide configures Google Cloud Secret Manager as a secret provider using **Workload Identity Federation**: CrewAI Platform mints short-lived OIDC tokens, exchanges them for Google Cloud credentials via the Security Token Service, and reads your secrets — without a long-lived service account key being stored anywhere.
<Note>
**Why this path:** secrets are resolved at automation execution time, so **rotated values propagate to the next kickoff with no re-deploy**. If you only need static credentials, see the simpler [GCP — service account key](/en/enterprise/features/secrets-manager/gcp) guide.
</Note>
### How it works at runtime
1. The deployment worker requests a fresh OIDC JWT from CrewAI Platform.
2. The worker exchanges the JWT for a federated Google credential via the [Security Token Service](https://cloud.google.com/iam/docs/reference/sts/rest), referencing the Workload Identity Pool Provider you set up below.
3. The worker calls `secretmanager.googleapis.com:accessSecretVersion` to read the secret, using the federated credential directly (the federated principal holds `roles/secretmanager.secretAccessor` — see Step 4).
4. The fetched value is injected as the environment variable's value for that automation kickoff.
OIDC subject tokens are cached for ~1 hour to avoid re-issuing on every kickoff. Secret values are fetched fresh on every kickoff regardless of OIDC cache state, which is what makes this path rotation-aware.
## Prerequisites
<Note>
Before starting, make sure you have:
- The automation pod image must include CrewAI runtime version `1.14.5` or later.
- A Google Cloud project with the **Secret Manager API**, **Security Token Service API**, and **IAM Credentials API** enabled. Enable them via the console or:
```bash
gcloud services enable secretmanager.googleapis.com sts.googleapis.com iamcredentials.googleapis.com \
--project=<YOUR_PROJECT_ID>
```
- Permission in the project to create Workload Identity Pools, IAM roles, service accounts, and (if needed) secrets.
- A CrewAI Platform organization where your user has the `workload_identity_configs: manage` and `secret_providers: manage` permissions. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
- **Your CrewAI Platform installation must be reachable from Google Cloud over HTTPS** so that GCP STS can fetch the OIDC discovery document and JWKS during token validation. Confirm with your platform administrator that the host is internet-accessible.
</Note>
## Step 1 — Find Your CrewAI Platform OIDC Issuer URL
Your CrewAI Platform installation publishes an OpenID Connect discovery document at `https://<your-platform-host>/.well-known/openid-configuration`. The `issuer` field there is the URL Google will register as a trusted OIDC provider.
Open the URL in a browser:
```
https://<your-platform-host>/.well-known/openid-configuration
```
You should see JSON containing:
```json
{
"issuer": "https://<your-platform-host>",
"jwks_uri": "https://<your-platform-host>/oauth2/jwks",
...
}
```
Note the exact value of `issuer` — you'll use it in Step 3.
<Tip>
If the URL returns 404 or 503, contact your platform administrator. The OIDC issuer requires a private signing key to be configured at install time. See the platform's installation guide for the `OIDC_PRIVATE_KEY` and `OIDC_ISSUER` configuration.
</Tip>
## Step 2 — Create a Workload Identity Pool
A Workload Identity Pool is a Google Cloud-side container for trusted external identities. You'll register CrewAI Platform as a provider inside this pool.
```bash
gcloud iam workload-identity-pools create crewai-pool \
--project=<YOUR_PROJECT_ID> \
--location=global \
--display-name="CrewAI Platform"
```
Or in the [Workload Identity Pools console](https://console.cloud.google.com/iam-admin/workload-identity-pools), click **Create Pool**.
{/* SCREENSHOT: GCP "Create Workload Identity Pool" form with name "crewai-pool" → /images/secrets-manager/gcp-wi/01-create-pool.png */}
## Step 3 — Add CrewAI Platform as an OIDC Provider in the Pool
```bash
gcloud iam workload-identity-pools providers create-oidc crewai-provider \
--project=<YOUR_PROJECT_ID> \
--location=global \
--workload-identity-pool=crewai-pool \
--display-name="CrewAI Platform OIDC" \
--issuer-uri="https://<your-platform-host>" \
--attribute-mapping="google.subject=assertion.sub,attribute.organization=assertion.organization_id" \
--attribute-condition="assertion.organization_id != ''"
```
The `--attribute-mapping` tells Google how to map JWT claims into Google attributes:
- `google.subject` is the principal identifier — we map it to the JWT's `sub` claim, which CrewAI Platform sets to `organization:<uuid>`.
- `attribute.organization` is a custom attribute — we map it to the JWT's `organization_id` claim so you can reference it in IAM bindings later.
The `--attribute-condition` is a defense-in-depth check that rejects tokens missing an `organization_id` claim.
Get the **provider resource name** (you'll need it for the audience and IAM bindings):
```bash
gcloud iam workload-identity-pools providers describe crewai-provider \
--project=<YOUR_PROJECT_ID> \
--location=global \
--workload-identity-pool=crewai-pool \
--format="value(name)"
```
Output looks like:
```
projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider
```
This is your **Workload Identity Provider** value for CrewAI Platform in Step 6. CrewAI Platform automatically computes the OIDC audience as `//iam.googleapis.com/<this-resource-name>` when issuing tokens.
{/* SCREENSHOT: "Add provider to pool" form with OIDC selected, issuer URI, audience defaults, attribute mapping → /images/secrets-manager/gcp-wi/02-add-oidc-provider.png */}
## Step 4 — Grant Secret Manager Access to the Federated Principal
Bind both Secret Manager roles at project scope to the federated principal — one role enables the Secret Name autocomplete in the env-var form, the other allows reading secret values at automation kickoff. Both are required for the feature to work end-to-end.
```bash
PRINCIPAL_SET="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/attribute.organization/<YOUR_CREWAI_ORG_UUID>"
# Required for the Secret Name autocomplete (calls secretmanager.secrets.list)
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="$PRINCIPAL_SET" \
--role="roles/secretmanager.viewer"
# Required to read secret values at kickoff
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="$PRINCIPAL_SET" \
--role="roles/secretmanager.secretAccessor"
```
Replace `<PROJECT_NUMBER>` with the numeric project number (`gcloud projects describe <YOUR_PROJECT_ID> --format='value(projectNumber)'`) and `<YOUR_CREWAI_ORG_UUID>` with the UUID of the CrewAI Platform organization that should be allowed to read your secrets. You can find the org UUID in the platform UI on the organization's settings page, or via the API. This scopes federation to a specific CrewAI organization — only tokens minted for that org's automations are accepted.
Or via the Google Cloud console:
1. Open **IAM & Admin** → **IAM** for your project.
2. Click **GRANT ACCESS**.
3. **New principals:** paste the full `principalSet://...attribute.organization/<YOUR_CREWAI_ORG_UUID>` string.
4. Assign role **Secret Manager Viewer** (`roles/secretmanager.viewer`).
5. Click **SAVE**.
6. Click **GRANT ACCESS** again and repeat with role **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
<Tip>
**Per-org isolation.** The `principalSet://...attribute.organization/<UUID>` pattern restricts access to a specific organization's tokens. If you have multiple CrewAI organizations sharing one Google Cloud project, repeat both bindings per-org with the correct UUID — or use a less restrictive attribute condition if isolation isn't needed.
</Tip>
<Tip>
**Scoping `secretAccessor` per-secret (optional).** If you'd rather not grant `roles/secretmanager.secretAccessor` project-wide, omit the second binding above and bind per-secret instead:
```bash
gcloud secrets add-iam-policy-binding <SECRET_NAME> \
--member="$PRINCIPAL_SET" \
--role="roles/secretmanager.secretAccessor" \
--project=<YOUR_PROJECT_ID>
```
Keep `roles/secretmanager.viewer` at the project scope either way — `secretmanager.secrets.list` (which the autocomplete relies on) cannot be granted per-secret.
</Tip>
## Step 5 — Create at Least One Secret in GCP
If you don't already have a secret to test against, create one via the `gcloud` CLI:
```bash
echo -n "hello from gcp" | gcloud secrets create crewai-test-keyword \
--data-file=- \
--project=<YOUR_PROJECT_ID> \
--replication-policy=automatic
```
Or via the [Secret Manager console](https://console.cloud.google.com/security/secret-manager):
1. Open **Secret Manager** in your GCP project.
2. Click **+ CREATE SECRET**.
3. **Name:** `crewai-test-keyword`. **Secret value:** paste your value.
4. Click **CREATE SECRET**.
## Step 6 — Add a Workload Identity Configuration in CrewAI Platform
In CrewAI Platform, navigate to **Settings** → **Workload Identity** and click **Add Workload Identity Config**.
Fill the form:
- **Name:** A descriptive name, e.g. `gcp-prod`.
- **Cloud Provider:** `GCP`.
- **Workload Identity Provider:** the provider resource name from Step 3, e.g. `projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/crewai-pool/providers/crewai-provider`.
- (Optional) Toggle **Default Configuration** if you'd like this to be the default WI config selected when creating a GCP-backed secret credential.
Click **Create**.
{/* SCREENSHOT: "Add Workload Identity Config" form with GCP and provider resource name → /images/secrets-manager/gcp-wi/03-amp-add-wi-config-gcp.png */}
{/* SCREENSHOT: Workload Identity list showing both AWS and GCP rows → /images/secrets-manager/gcp-wi/04-amp-wi-list-with-gcp.png */}
## Step 7 — Add a Secret Provider Credential Bound to the WI Config
Navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
Fill the form:
- **Name:** A descriptive name, e.g. `gcp-prod-wi`.
- **Provider:** `Google Cloud Secret Manager`.
- **Authentication Method:** `Workload Identity`.
- **Workload Identity Configuration:** select the config you created in Step 6.
- **Project ID:** your GCP project ID (the same project that owns the secrets).
- (Optional) Check **Set as default credential for this provider**.
The form will only ask for **Project ID** under Workload Identity — the **Service Account JSON** field is intentionally hidden because it doesn't apply to this path; the federated identity comes from the linked WI config.
Click **Create**.
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP + Workload Identity + WI config dropdown → /images/secrets-manager/gcp-wi/05-amp-add-credential-gcp-wi.png */}
## Step 8 — Test the Connection
After saving the credential, click **Test Connection**. For workload-identity credentials this verifies the OIDC handshake: CrewAI Platform mints a JWT and exchanges it via the Security Token Service for a federated Google access token. A green result means the federation binding is healthy.
A successful Test Connection proves the Workload Identity Pool, OIDC provider, attribute mapping, and attribute condition are all wired correctly. It does **not** prove Secret Manager IAM is correct — `secretmanager.secrets.list` and `secretmanager.versions.access` are exercised separately when the Secret Name autocomplete loads or when an environment variable resolves at kickoff. See [Troubleshooting](#troubleshooting) for handshake failure modes.
## Step 9 — Reference the Secret in an Environment Variable
Reference the secret on an automation, exactly as you would for any other Secrets Manager-backed env var. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for the form fields and behavior.
## Step 10 — Verify Rotation
After the deployment is running, rotate the secret in GCP by adding a new version (Secret Manager always reads the latest enabled version by default):
```bash
echo -n "rotated value" | gcloud secrets versions add crewai-test-keyword \
--data-file=- \
--project=<YOUR_PROJECT_ID>
```
Trigger a new automation kickoff. The kickoff's environment will see `"rotated value"` — no re-deploy, no worker restart, no TTL wait.
To confirm in worker logs, look for:
```
Workload identity config '<id>' (gcp): N secret(s) resolved
```
This line appears for every kickoff and indicates a fresh `accessSecretVersion` call against GCP.
## Troubleshooting
| Symptom | Likely cause |
|---|---|
| Test Connection fails with a handshake error | The STS token exchange was rejected. Verify the Workload Identity Pool exists, the OIDC provider's issuer matches the platform's `issuer` value, and the attribute condition accepts the JWT's claims. Confirm the platform's OIDC discovery URL is reachable from GCP over the public internet. |
| `Could not refresh access token: invalid_target` | The audience claim doesn't match the Workload Identity Provider's expected audience. CrewAI Platform sets the audience automatically; if you customized it, ensure it matches `//iam.googleapis.com/<provider-resource-name>`. |
| `Failed to fetch JWKS from issuer` | GCP STS can't reach your CrewAI Platform host. Confirm the host is internet-accessible and `/.well-known/openid-configuration` returns 200. |
| `Attribute condition rejected token` | The OIDC provider's attribute condition (Step 3) requires `organization_id`. CrewAI Platform always sets this claim, so this usually means a misconfigured pool/provider. Re-check the provider's attribute condition. |
| Secret Name autocomplete shows `PERMISSION_DENIED: secretmanager.secrets.list` | The federated principal is missing `roles/secretmanager.viewer` at project scope. The `secretmanager.secrets.list` permission is project-scoped only and cannot be granted per-secret. See Step 4. |
| Kickoff fails to resolve a secret even though Test Connection passes | The WI binding is healthy, but `secretmanager.versions.access` is missing on the failing secret. Audit `roles/secretmanager.secretAccessor` (project-scoped, or per-secret if you scoped it that way in Step 4). |
| Rotated value isn't picked up on the next kickoff | Confirm the env var on the automation is referencing a Workload Identity-backed credential (not a static-keys credential). The static path bakes values into the deploy image. |
### Reference Links
- GCP: [Workload Identity Federation overview](https://cloud.google.com/iam/docs/workload-identity-federation)
- GCP: [Configure Workload Identity Federation with OIDC](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers)
- GCP: [Secret Manager IAM roles](https://cloud.google.com/secret-manager/docs/access-control)
## Next Steps
- [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)
- For multi-cloud, see also [AWS Workload Identity (OIDC Federation)](/en/enterprise/features/secrets-manager/aws-workload-identity) and [Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity).

189
docs/edge/en/enterprise/features/secrets-manager/gcp.mdx Normal file
View File

@@ -0,0 +1,189 @@
---
title: Google Cloud Secret Manager
description: Configure Google Cloud Secret Manager as a secret provider for CrewAI Platform, end-to-end
sidebarTitle: With Static Credentials
icon: "key"
---
## Overview
This guide walks you through configuring Google Cloud Secret Manager as a secret provider for your CrewAI Platform organization, using **service account credentials**. By the end, CrewAI Platform will be able to read secrets stored in your Google Cloud project and inject them as environment variable values at runtime.
<Note>
This guide covers the **static credentials** path — secrets are resolved at deploy time and baked into the deployment image. Rotated values require a re-deploy. If you want rotation-aware secrets that update on every automation kickoff, see [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity).
</Note>
<Note>
This guide covers the GCP-side configuration and the credential setup in CrewAI Platform. To then reference a secret from an environment variable, see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage).
</Note>
## Prerequisites
<Note>
Before starting, make sure you have:
- A Google Cloud project with the **Secret Manager API** enabled. Enable it in the [APIs & Services console](https://console.cloud.google.com/apis/library/secretmanager.googleapis.com) or via `gcloud`:
```bash
gcloud services enable secretmanager.googleapis.com --project=YOUR_PROJECT_ID
```
- Permission in the project to create service accounts, grant IAM roles, and (if needed) create secrets.
- A CrewAI Platform organization where your user has the `secret_providers: manage` permission. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac).
</Note>
## Step 1 — Create a Service Account
A service account is the GCP-side identity CrewAI Platform will authenticate as.
In the [IAM & Admin → Service Accounts console](https://console.cloud.google.com/iam-admin/serviceaccounts), click **Create Service Account**.
- **Service account name:** `crewai-secrets-reader`
- **Service account ID:** auto-fills from the name (e.g. `crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`)
- **Description (optional):** "Read-only access to Secret Manager for CrewAI Platform"
Click **Create and Continue**. Skip the optional grants on this screen — you'll attach the role in Step 2. Click **Done**.
For full details, see the GCP documentation: [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
{/* SCREENSHOT: GCP "Create service account" form with name "crewai-secrets-reader" → /images/secrets-manager/gcp/01-create-service-account.png */}
## Step 2 — Grant Secret Manager Access
CrewAI Platform needs permission to list and read secrets in your project. Use one of two scopes — **project-wide** for simplicity, or **per-secret** for least privilege.
<Tabs>
<Tab title="Project-wide (simpler)">
In the [IAM console](https://console.cloud.google.com/iam-admin/iam), click **Grant Access** and:
- **New principals:** the service account's email from Step 1.
- **Role:** **Secret Manager Secret Accessor** (`roles/secretmanager.secretAccessor`).
Click **Save**.
Or via `gcloud`:
```bash
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor"
```
{/* SCREENSHOT: GCP IAM "Grant access" panel with the service account and Secret Manager Secret Accessor role → /images/secrets-manager/gcp/02-iam-grant-access.png */}
</Tab>
<Tab title="Per-secret (least privilege)">
Grant the role only on the specific secrets CrewAI Platform should access. Repeat for each secret:
```bash
gcloud secrets add-iam-policy-binding YOUR_SECRET_NAME \
--member="serviceAccount:crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/secretmanager.secretAccessor" \
--project=YOUR_PROJECT_ID
```
Or in the console: open each secret in [Secret Manager](https://console.cloud.google.com/security/secret-manager), click **Permissions** in the right panel, and grant **Secret Manager Secret Accessor** to the service account.
{/* SCREENSHOT: Per-secret "Permissions" panel in Secret Manager with the service account granted accessor role → /images/secrets-manager/gcp/03-per-secret-permissions.png */}
</Tab>
</Tabs>
<Tip>
The `roles/secretmanager.secretAccessor` role grants read-only access to secret values. CrewAI Platform also calls `secretmanager.secrets.list` for the autocomplete experience in the env-var form — that permission is included in the role at the project scope, but **not** at the per-secret scope. With per-secret bindings, autocomplete won't suggest secrets; you'll need to type the full secret name.
</Tip>
## Step 3 — Create a Service Account Key
Open the service account from Step 1 in the [IAM & Admin → Service Accounts console](https://console.cloud.google.com/iam-admin/serviceaccounts).
- Click the **Keys** tab.
- Click **Add Key** → **Create new key**.
- **Key type:** JSON.
- Click **Create**. The browser downloads a JSON file — keep it secure; it cannot be re-downloaded.
Or via `gcloud`:
```bash
gcloud iam service-accounts keys create ./crewai-secrets-reader.json \
--iam-account=crewai-secrets-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
```
<Warning>
The service account key is a long-lived static credential. Store it securely (in a password manager or your own secret store) and rotate it on a regular cadence. To eliminate static credentials entirely, use [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) instead.
</Warning>
{/* SCREENSHOT: Service account "Keys" tab with the "Create new key" → JSON option → /images/secrets-manager/gcp/04-create-service-account-key.png */}
## Step 4 — Add the Credential in CrewAI Platform
In CrewAI Platform, navigate to **Settings** → **Secret Provider Credentials** and click **Add Credential**.
{/* SCREENSHOT: Sidebar/nav highlighting Settings → Secret Provider Credentials → /images/secrets-manager/usage/01-amp-settings-nav.png */}
Fill the form:
- **Name:** A descriptive name, e.g. `gcp-prod`.
- **Provider:** `Google Cloud Secret Manager`.
- **Project ID:** Your GCP project ID (e.g. `my-crewai-prod`).
- **Service Account JSON:** Paste the entire contents of the JSON file you downloaded in Step 3.
- (Optional) Check **Set as default credential for this provider**. The default credential is used by environment variables that reference GCP secrets without specifying a credential explicitly.
Click **Create**.
{/* SCREENSHOT: "Add Secret Provider Credential" form with GCP fields filled in → /images/secrets-manager/gcp/05-amp-add-credential-form-gcp.png */}
## Step 5 — Create at Least One Secret in GCP
If you don't already have secrets in GCP Secret Manager, create one now so you can verify the connection in Step 6.
In the [Secret Manager console](https://console.cloud.google.com/security/secret-manager), click **Create secret**.
- **Name:** A unique name, e.g. `openai-api-key`.
- **Secret value:** Either paste a raw value or upload a file.
- Leave the rotation, replication, and other settings at their defaults unless you have a specific requirement.
Click **Create secret**.
Or via `gcloud`:
```bash
echo -n "sk-your-actual-key" | gcloud secrets create openai-api-key \
--data-file=- \
--project=YOUR_PROJECT_ID \
--replication-policy=automatic
```
<Note>
**JSON-key reference syntax.** GCP Secret Manager treats secret values as opaque blobs. If your secret value happens to be a JSON string, CrewAI Platform can extract a single field using the `secret-name#json_key` syntax (e.g. `database-credentials#password`). See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables) for details.
</Note>
For full details, see the GCP documentation: [Create a secret](https://cloud.google.com/secret-manager/docs/create-secret-quickstart).
{/* SCREENSHOT: GCP "Create secret" form with name and value → /images/secrets-manager/gcp/06-create-secret.png */}
## Step 6 — Test the Connection
Back in CrewAI Platform, on the **Secret Provider Credentials** page, find the credential you just created and click **Test Connection**.
A success toast confirms that CrewAI Platform can authenticate to GCP and read secrets from your project.
{/* SCREENSHOT: Success toast after clicking "Test Connection" on the GCP credential → /images/secrets-manager/gcp/07-test-connection-success.png */}
If the test fails, check the most common causes:
| Symptom | Likely cause |
|---|---|
| `PERMISSION_DENIED` on listing secrets | Service account is missing `roles/secretmanager.secretAccessor`, or you scoped it per-secret (`list` is not granted). Re-check Step 2. |
| `PERMISSION_DENIED` on `secretmanager.secrets.access` | Same as above, but for a specific secret. Confirm the service account has accessor role on the secret in question. |
| `unauthorized_client` / `invalid_grant` | The pasted Service Account JSON is invalid, expired, or for a deleted service account. Re-create the key (Step 3) and re-paste. |
| `Project ID does not match` | The Project ID field in CrewAI Platform doesn't match the project that owns the service account / secrets. Re-check Step 4. |
| `API not enabled` | Secret Manager API isn't enabled on the project. See Prerequisites. |
## Next Steps
Now that GCP is connected, head to [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage) to:
- Grant org members the right permissions to use (or manage) Secrets Manager.
- Reference your GCP secrets from CrewAI Platform environment variables.
If you want **rotation-aware** secrets that propagate without re-deploying, switch to [GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) — same secret store, no static credentials, secrets are fetched per kickoff.

96
docs/edge/en/enterprise/features/secrets-manager/overview.mdx Normal file
View File

@@ -0,0 +1,96 @@
---
title: Secrets Manager Overview
description: Connect external secret stores to CrewAI Platform and reference managed secrets from environment variables
sidebarTitle: Overview
icon: "book-open"
---
## Overview
The Secrets Manager feature lets your organization connect an external secret store — AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault — and reference those secrets directly from environment variables on your automations and crews. Instead of pasting plaintext values into the platform, you store one set of credentials per provider and refer to secrets by name.
This gives you:
- **Centralized storage** — manage secrets in your provider rather than editing CrewAI Platform configuration. CrewAI Platform keeps no plaintext copy of the secret value.
- **Reduced exposure** — sensitive values never live in plaintext in your CrewAI Platform configuration.
- **Cloud-native auditability** — your provider's audit log records every secret read.
<Note>
Secrets Manager (both the static-credentials and Workload Identity paths) requires CrewAI runtime version `1.14.5` or later in the automation pod image.
</Note>
## Two Paths: Static Credentials vs Workload Identity
There are two ways to wire CrewAI Platform up to your cloud's secret store. **They differ significantly in rotation behavior**, so choose based on how often your secrets rotate and how strict your security posture is.
| Aspect | Static Credentials | Workload Identity (OIDC Federation) |
|---|---|---|
| **Authentication** | Long-lived access keys / service account JSON stored in CrewAI Platform | Short-lived tokens minted per worker process; no static credentials stored anywhere |
| **Rotation propagation** | Resolved at deploy time and **baked into the deployment's container image** — rotated values require a re-deploy | Resolved at **automation execution time** — rotated values propagate to the next kickoff with no re-deploy |
| **Setup effort** | Lower — paste keys / upload service account JSON | Higher — register CrewAI Platform as an OIDC provider in your cloud, configure trust policies |
| **Best for** | Getting started, infrequently-rotated secrets, single-account deployments | Production, frequently-rotated secrets, compliance-driven environments that prohibit long-lived credentials |
<Note>
**Both paths use the same UI flow** to reference secrets in environment variables (see [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage)). The difference is entirely in how the platform authenticates to your cloud and when it reads the secret value.
</Note>
### Choose your setup guide
| Provider | Static Credentials | Workload Identity |
|---|---|---|
| AWS Secrets Manager | [AWS — static keys / AssumeRole](/en/enterprise/features/secrets-manager/aws) | [AWS — Workload Identity (OIDC)](/en/enterprise/features/secrets-manager/aws-workload-identity) |
| Google Cloud Secret Manager | [GCP — service account key](/en/enterprise/features/secrets-manager/gcp) | [GCP — Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity) |
| Azure Key Vault | [Azure — client secret](/en/enterprise/features/secrets-manager/azure) | [Azure — Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity) |
<Note>
The Secrets Manager and Workload Identity UIs are currently labeled **Beta** in CrewAI Platform.
</Note>
## How It Fits Together
Setting up Secrets Manager is a three-step flow that involves both your cloud provider and CrewAI Platform:
1. **An admin configures a provider credential.** This is the cloud-side work — and the work differs depending on which path (static credentials or Workload Identity) you choose. Provider-specific guides cover this end to end.
2. **An admin (or a permitted member) references a secret in an environment variable.** From the Environment Variables page, the user picks a provider credential and selects the secret name. See [Using the Secrets Manager](/en/enterprise/features/secrets-manager/usage#referencing-secrets-in-environment-variables).
3. **The automation receives the resolved value at runtime.** When a crew or automation runs, CrewAI Platform fetches the secret from your provider and injects it as the environment variable's value. With Workload Identity, this fetch happens on every kickoff (rotation-aware). With static credentials, this fetch happens at deploy time and the value is baked into the deployment image.
## Visibility & Scope
<Note>
WI-backed environment variables follow the same assignment model as plaintext environment variables: an automation resolves only the WI-backed variables explicitly assigned to it. Assign a WI-backed variable to an automation from the Environment Variables page on that automation; variables defined at the organization level or in a Studio project are not resolved at kickoff until you assign them.
</Note>
<Note>
The secret-fetch stage runs on every kickoff but only does work when WI-backed environment variables are assigned to the deployment. For each assigned variable, the runtime resolves the value from your cloud provider on every crew, flow, training, test, or checkpoint-restore kickoff and writes it into the process environment. With nothing assigned, the stage is a no-op. Otherwise, cost is proportional to the number of assigned variables: a small added latency per kickoff plus one cloud-side audit-log entry per variable.
</Note>
<Warning>
At the Workload Identity *configuration* level, scope is still organization-wide today. Every automation in the organization is bootstrapped against every Workload Identity configuration the org has registered, and you cannot today bind a specific Workload Identity configuration to a specific automation. Per-automation Workload Identity scoping is on the roadmap. Until then, only register Workload Identity configurations every automation in your organization is allowed to use.
</Warning>
## Permissions
Two CrewAI Platform features control access to Secrets Manager:
- `secret_providers` — controls who can view or manage provider credentials.
- `environment_variables` — controls who can create and edit environment variables (including those that reference secrets).
A third feature controls Workload Identity setup:
- `workload_identity_configs` — controls who can view or manage Workload Identity configurations. Required only if you're using the Workload Identity path.
Owners always have full access. Members do **not** receive access to `secret_providers` or `workload_identity_configs` by default and must be granted permission via a custom role. See [Permissions (RBAC)](/en/enterprise/features/secrets-manager/usage#permissions-rbac) for the full matrix and step-by-step instructions.
## Next Steps
Pick your path:
- **Static credentials** (simpler, requires re-deploy on rotation):
- [Configure AWS Secrets Manager](/en/enterprise/features/secrets-manager/aws)
- [Configure Google Cloud Secret Manager](/en/enterprise/features/secrets-manager/gcp)
- [Configure Azure Key Vault](/en/enterprise/features/secrets-manager/azure)
- **Workload Identity** (rotation-aware, no re-deploy):
- [Configure AWS Workload Identity](/en/enterprise/features/secrets-manager/aws-workload-identity)
- [Configure GCP Workload Identity Federation](/en/enterprise/features/secrets-manager/gcp-workload-identity)
- [Configure Azure Workload Identity Federation](/en/enterprise/features/secrets-manager/azure-workload-identity)
- Then: [Use secrets in environment variables and manage permissions](/en/enterprise/features/secrets-manager/usage)

137
docs/edge/en/enterprise/features/secrets-manager/usage.mdx Normal file
View File

@@ -0,0 +1,137 @@
---
title: Using the Secrets Manager
description: Manage permissions and reference managed secrets from environment variables in CrewAI Platform
sidebarTitle: Usage & Permissions
icon: "list-check"
---
## Overview
This guide is provider-agnostic. It assumes you (or another admin) have already configured at least one Secret Provider Credential. Pick your setup guide based on the path you want:
- Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp)
- Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity)
Use this guide to:
- Grant the right permissions to org members.
- Reference secrets from environment variables on your automations.
- Verify everything resolves correctly at runtime.
## Permissions (RBAC)
Three CrewAI Platform features are relevant when working with Secrets Manager:
- `secret_providers` — controls access to the **Secret Provider Credentials** page.
- `workload_identity_configs` — controls access to the **Workload Identity** page (only relevant if you use the WI path).
- `environment_variables` — controls who can create or edit environment variables.
Each feature has two action levels: `read` and `manage`. Granting `manage` automatically implies `read`.
### What to Grant
| Goal | `secret_providers` | `workload_identity_configs` | `environment_variables` |
|---|---|---|---|
| Use existing static credentials in environment variables (no provider edits) | `read` | — | `manage` |
| Create, edit, or delete static credentials | `manage` | — | `manage` |
| Use existing Workload Identity-backed credentials in env vars | `read` | — | `manage` |
| Create, edit, or delete Workload Identity configs (and credentials referencing them) | `manage` | `manage` | `manage` |
<Note>
**Owners** automatically have full access to every feature. The default **Member** role intentionally excludes `secret_providers` and `workload_identity_configs` — admins must explicitly opt members in via a custom role.
</Note>
### How to Assign
1. In CrewAI Platform, navigate to **Settings** → **Roles**. From this page you can create new roles, edit each role's permissions, and assign roles to existing members of the organization.
{/* SCREENSHOT: Sidebar highlighting Settings → Roles → /images/secrets-manager/usage/06-amp-settings-roles-nav.png */}
{/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */}
2. Click **Create Role** to make a new role, or open an existing role to edit its permissions.
3. In the role's permission editor, toggle the relevant features per the table above:
- `secret_providers`: choose **read** if this role only needs to use existing credentials, or **manage** if it should also be able to create, edit, and delete credentials.
- `environment_variables`: choose **manage** so the role can create environment variables that reference secrets.
{/* SCREENSHOT: Role editor showing the secret_providers feature with read/manage toggles → /images/secrets-manager/usage/08-amp-role-editor-secret-providers-toggles.png */}
{/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */}
4. Save the role.
5. Assign the role to the relevant members from the same Roles page (or the org Members list).
{/* SCREENSHOT: Member assignment screen where the new role is applied to a user → /images/secrets-manager/usage/10-amp-assign-role-to-member.png */}
## Referencing Secrets in Environment Variables
Once a provider credential exists and your role has the right permissions, you can reference managed secrets from any environment variable.
In CrewAI Platform, navigate to **Environment Variables** and click **Add Environment Variables**.
{/* SCREENSHOT: Environment Variables empty state with "Add" button → /images/secrets-manager/usage/11-amp-env-vars-empty.png */}
Fill the form:
- **Key** — the name of the environment variable. Must start with a letter or underscore and contain only letters, numbers, and underscores. Conventionally uppercase, e.g. `OPENAI_API_KEY`.
- **Value Source** — choose where the value comes from:
- **Direct Value** — a plaintext value you type in. Use this when you do not want to involve a provider.
- **Use AWS default** (or the equivalent for your provider) — uses the credential currently marked as the default for that provider type.
- **A specific named credential** — select the credential by name. Use this if you have multiple credentials for the same provider (for example, `aws-prod` and `aws-staging`) and want to pick one explicitly.
{/* SCREENSHOT: Env var form with the "Value Source" dropdown open, showing "AWS default" + named credentials → /images/secrets-manager/usage/12-amp-env-var-form-source-selector.png */}
- **Secret Name** — the name of the secret in your provider. Once a credential is selected, this field offers autocomplete: start typing and CrewAI Platform queries your provider for matching secret names.
Use the `secret-name#json_key` syntax to extract a single field from a structured (JSON) secret. For example, given a secret `database-credentials` with value `{"username": "...", "password": "..."}`, reference `database-credentials#password` to inject just the password.
{/* SCREENSHOT: Env var form with the secret name autocomplete dropdown showing live results → /images/secrets-manager/usage/13-amp-env-var-form-secret-name-autocomplete.png */}
<Note>
**Azure Key Vault note:** Azure secret names cannot contain underscores. CrewAI Platform automatically converts underscores in your `Secret Name` field to hyphens when calling Azure (e.g., `db_password` is sent as `db-password`).
</Note>
Click **Create** to save the variable.
{/* SCREENSHOT: Env var list with the new variable showing masked value and a "secret" indicator → /images/secrets-manager/usage/14-amp-env-var-created.png */}
<Tip>
When editing an existing environment variable, leaving the **Value** field blank preserves the current value. This is intentional — it lets you change other fields (like the secret name or credential) without re-entering the value.
</Tip>
## Verifying It Works
To verify end-to-end:
1. Reference the environment variable on an automation, crew, or deployment exactly as you would any other environment variable.
2. Deploy the automation.
3. Trigger a run and confirm it completes successfully.
### Rotation behavior depends on the credential path
| Credential path | When the secret is read | What rotation requires |
|---|---|---|
| **Static credentials** (AWS access keys, GCP service account JSON) | At **deploy time** — value is baked into the deployment image | Re-deploy the automation after rotating the secret |
| **Workload Identity** (OIDC federation, AWS or GCP) | At **every automation kickoff** — value is fetched fresh from your cloud | Nothing — the next kickoff after rotation sees the new value |
<Note>
**If you need rotation-aware secrets** (no re-deploy on rotation), use the Workload Identity path: [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity). The trade-off is more setup effort up front (registering CrewAI Platform as an OIDC provider in your cloud) but simpler operations long-term.
</Note>
If the deploy or run fails with an error related to your secret, check the most common causes:
| Symptom | Likely cause |
|---|---|
| `no credential found` | The environment variable references a provider but no specific credential was selected, and there is no default credential set for that provider type. Either select a credential explicitly on the variable, or mark a credential as default on the **Secret Provider Credentials** page. |
| `secret not found` | Typo in the **Secret Name**, or the secret does not exist in the provider account/region the credential points to. Re-check both. |
| Automation runs with the old value after rotating (static-credentials path) | The previous value is baked into the deployment's container image. Re-deploy the automation to pick up the rotated value. To avoid this entirely, switch the credential to the Workload Identity path. |
| Automation runs with the old value after rotating (Workload Identity path) | Confirm the env var references a WI-backed credential (not a static-keys one). With WI, the next kickoff after rotation should see the new value. If it doesn't, check that the secret was actually updated in your cloud (e.g., `aws secretsmanager get-secret-value`). |
| `JSON key not found` | When using `secret-name#json_key`, the underlying secret must be a valid JSON object containing that key. Verify by reading the secret directly in your provider. |
## Next Steps
- [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview)
- Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp)
- Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity)

261
docs/edge/en/enterprise/features/secrets-manager/verify-rotation.mdx Normal file
View File

@@ -0,0 +1,261 @@
---
title: Verify Rotation
description: A self-contained example crew that proves secret rotation propagates to running deployments without re-deploy.
sidebarTitle: Verify Rotation
icon: "arrows-rotate"
---
## Overview
This guide shows you how to verify that **a secret rotated in your cloud provider is picked up on the very next automation kickoff** — no re-deploy, no worker restart. It's only relevant when you've configured a Workload Identity-backed credential ([AWS](/en/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/en/enterprise/features/secrets-manager/azure-workload-identity)). Static-credential deployments require a re-deploy after rotation; nothing to verify here.
The recipe below uses a tiny, self-contained crew with one tool, one agent, one task. The crew prompt never references the secret value — instead, a tool reads it from `os.environ` and reports a SHA-256 fingerprint of what it sees. Rotate the secret in your cloud provider, kickoff again, and the fingerprint changes.
<Note>
Why a fingerprint, not the raw value? Putting raw secrets into LLM output and trace logs is a leak vector. The fingerprint is enough to confirm "the value changed" without writing the actual value anywhere observable.
</Note>
## Prerequisites
Before running this verification:
- A WI-backed Secret Provider Credential is configured ([AWS](/en/enterprise/features/secrets-manager/aws-workload-identity), [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity), [Azure](/en/enterprise/features/secrets-manager/azure-workload-identity)).
- An environment variable on your deployment with `Secret = true`, key `API_KEY` (or whatever name you prefer — adjust the tool below to match), referencing a secret in your cloud provider.
- A way to update the secret value in your cloud provider (CLI access or the cloud console).
- A way to kickoff the deployment via HTTP (curl, Postman, or the **Run** tab in CrewAI Platform).
## Step 1 — Scaffold a Verification Crew
Create a classic crew project because this example wires a Python tool through `crew.py`:
```bash
crewai create crew rotation_verifier --classic --skip_provider
cd rotation_verifier
```
## Step 2 — Add the Credential Echo Tool
Replace `src/rotation_verifier/tools/custom_tool.py` with a tool that reads the secret-backed env var and returns a fingerprint:
```python src/rotation_verifier/tools/credential_echo_tool.py
"""Tool that verifies a runtime-injected secret without leaking the value.
Reads the secret-backed env var (populated by the workload-identity
secrets manager at kickoff time) and returns a stable fingerprint. Never
echo raw credential values into LLM output or logs in production code —
the fingerprint alone is sufficient to confirm rotation worked.
"""
from __future__ import annotations
import hashlib
import os
from crewai.tools import BaseTool
# Match the deployment environment variable's `key` field.
ENV_VAR_NAME = "API_KEY"
class CredentialEchoTool(BaseTool):
name: str = "credential_echo"
description: str = (
"Read the API credential from the worker's environment and return a "
"fingerprint summary. Use this exactly once when asked to verify the "
"current credential. Takes no arguments."
)
def _run(self) -> str:
value = os.environ.get(ENV_VAR_NAME)
if not value:
return (
f"ERROR: {ENV_VAR_NAME} env var is not set. The workload-"
"identity secret fetch did not run, or the deployment is "
"missing the secret-backed env var."
)
fingerprint = hashlib.sha256(value.encode()).hexdigest()[:12]
return f"Authenticated. credential.fingerprint=sha256:{fingerprint}"
```
## Step 3 — Replace the Default Agent and Task Configs
The crew has one agent and one task — both with descriptions that **never** mention the secret value, so task keys stay stable across rotations.
```yaml src/rotation_verifier/config/agents.yaml
credential_checker:
role: >
Credential Verifier
goal: >
Confirm that the workload-identity-backed secret reached this worker
process and report a fingerprint of the current value.
backstory: >
You are a no-nonsense reliability engineer responsible for verifying
that secrets fetched at runtime via workload identity are present
and fresh. You always use the credential_echo tool exactly once and
report the result verbatim — you never make up values.
```
```yaml src/rotation_verifier/config/tasks.yaml
verify_credential_task:
description: >
Use the credential_echo tool to read the runtime-injected credential
and produce a one-line confirmation. The current year is {current_year}
(use it only in the timestamp; do not transform the credential output).
expected_output: >
A single line in the form:
"[{current_year}] <credential_echo tool's exact output>"
agent: credential_checker
```
## Step 4 — Wire the Crew Class
```python src/rotation_verifier/crew.py
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai.agents.agent_builder.base_agent import BaseAgent
from rotation_verifier.tools.credential_echo_tool import CredentialEchoTool
@CrewBase
class RotationVerifierCrew():
"""Single-task crew that verifies a workload-identity-backed secret
was successfully fetched at runtime.
Rotate the underlying secret in the cloud provider, kickoff again, and
the credential fingerprint in the agent's report changes — without any
re-deploy, worker restart, or input change. The crew prompt itself
never references the secret value.
"""
agents: list[BaseAgent]
tasks: list[Task]
@agent
def credential_checker(self) -> Agent:
return Agent(
config=self.agents_config["credential_checker"],
tools=[CredentialEchoTool()],
verbose=True,
)
@task
def verify_credential_task(self) -> Task:
return Task(config=self.tasks_config["verify_credential_task"])
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
## Step 5 — Deploy and Configure the Secret Env Var
Deploy this crew to CrewAI Platform exactly as you would any other crew. Then on the deployment's **Environment Variables** page:
- **Key:** `API_KEY` (must match `ENV_VAR_NAME` in the tool)
- **Value Source:** the WI-backed credential you set up in [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity)
- **Secret Name:** the name of the secret in your cloud provider's Secret Manager
{/* SCREENSHOT: Environment Variables form with key=API_KEY, secret-backed value source selected, secret name filled → /images/secrets-manager/verify-rotation/01-env-var-form.png */}
## Step 6 — Run the First Kickoff
Replace `<DEPLOYMENT_AUTH_TOKEN>` and `<DEPLOYMENT_HOST>` with values from your deployment's **Run** tab.
```bash
curl -m 60 \
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
-H "Content-Type: application/json" \
-X POST https://<DEPLOYMENT_HOST>/kickoff \
-d '{"inputs":{"current_year":"2026"}}'
```
When the kickoff completes (a few seconds), check the agent's output. You'll see:
```
[2026] Authenticated. credential.fingerprint=sha256:004421b993c9
```
Note the fingerprint. That hash is uniquely tied to whatever secret value is currently in your cloud provider.
## Step 7 — Rotate the Secret in Your Cloud Provider
<Tabs>
<Tab title="AWS">
```bash
aws secretsmanager update-secret \
--region <REGION> \
--secret-id <SECRET_NAME> \
--secret-string "rotated value"
```
</Tab>
<Tab title="GCP">
Add a new version (Secret Manager always reads `latest`):
```bash
echo -n "rotated value" | gcloud secrets versions add <SECRET_NAME> \
--data-file=- \
--project=<YOUR_PROJECT_ID>
```
</Tab>
<Tab title="Azure">
```bash
az keyvault secret set \
--vault-name <VAULT_NAME> \
--name <SECRET_NAME> \
--value "rotated value"
```
</Tab>
</Tabs>
## Step 8 — Run a Second Kickoff and Compare
```bash
curl -m 60 \
-H "Authorization: Bearer <DEPLOYMENT_AUTH_TOKEN>" \
-H "Content-Type: application/json" \
-X POST https://<DEPLOYMENT_HOST>/kickoff \
-d '{"inputs":{"current_year":"2026"}}'
```
The agent's output now shows a **different fingerprint**:
```
[2026] Authenticated. credential.fingerprint=sha256:e2fc89848f72
```
This proves the rotation was picked up by the running deployment with no re-deploy, worker restart, or other operator action.
## What This Verifies — and What It Doesn't
**Verifies:**
- WI OIDC token minting from CrewAI Platform works.
- Cloud-side trust (IAM OIDC provider for AWS, Workload Identity Pool for GCP, Federated Identity Credential for Azure) accepts the token.
- The cloud-side identity (IAM Role / GCP service account / Entra App Registration) has access to read the secret.
- The secret value reaches `os.environ` of the worker process at kickoff time.
- Subsequent rotations propagate to the next kickoff.
**Does not verify:**
- That your real production crews handle the rotation gracefully — e.g., long-running tasks that read the env var once at startup will keep using the old value until the task ends. Plan accordingly: read secrets at the point of use, not at module import.
## Why Not Reference the Secret Directly in the Prompt?
A simpler-looking demo would put the secret value directly into a task description (e.g., "Research about `{api_key}`") and inspect the prompt. **Don't do that.** Two reasons:
1. **It leaks the secret into LLM call traces and provider-side logs.** Anyone with trace access can read it.
2. **It changes the task's description at every kickoff.** CrewAI Platform identifies tasks by an MD5 hash of the description; a rotating value means the hash changes per kickoff, which breaks the deploy-time → runtime task mapping. Symptom: the task records show as `pending_run` indefinitely, or only some of a multi-task crew's tasks register.
The tool-based pattern in this guide sidesteps both issues: the prompt is static, the tool reads the env var at runtime, and only a fingerprint of the value reaches the LLM.
## Next Steps
- [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview)
- Once verified, drop the verification crew. Real crews should follow the same pattern: secrets accessed via `os.environ` inside a tool, never substituted into prompts.

550
docs/edge/en/enterprise/features/sso.mdx Normal file
View File

@@ -0,0 +1,550 @@
---
title: Single Sign-On (SSO)
icon: "key"
description: Configure enterprise SSO authentication for CrewAI Platform — SaaS and Factory
---
## Overview
CrewAI Platform supports enterprise Single Sign-On (SSO) across both **SaaS (AMP)** and **Factory (self-hosted)** deployments. SSO enables your team to authenticate using your organization's existing identity provider, enforcing centralized access control, MFA policies, and user lifecycle management.
### Supported Providers
| Provider | SaaS | Factory | Protocol | CLI Support |
|---|---|---|---|---|
| **WorkOS** | ✅ (default) | ✅ | OAuth 2.0 / OIDC | ✅ |
| **Microsoft Entra ID** (Azure AD) | ✅ (enterprise) | ✅ | OAuth 2.0 / SAML 2.0 | ✅ |
| **Okta** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ |
| **Auth0** | ✅ (enterprise) | ✅ | OAuth 2.0 / OIDC | ✅ |
| **Keycloak** | — | ✅ | OAuth 2.0 / OIDC | ✅ |
### Key Capabilities
- **SAML 2.0 and OAuth 2.0 / OIDC** protocol support
- **Device Authorization Grant** flow for CLI authentication
- **Role-Based Access Control (RBAC)** with custom roles and per-resource permissions
- **MFA enforcement** delegated to your identity provider
- **User provisioning** through IdP assignment (users/groups)
---
## SaaS SSO
### Default Authentication
CrewAI's managed SaaS platform (AMP) uses **WorkOS** as the default authentication provider. When you sign up at [app.crewai.com](https://app.crewai.com), authentication is handled through `login.crewai.com` — no additional SSO configuration is required.
### Enterprise Custom SSO
Enterprise SaaS customers can configure SSO with their own identity provider (Entra ID, Okta, Auth0). Contact your CrewAI account team to enable custom SSO for your organization. Once configured:
1. Your team members authenticate through your organization's IdP
2. Access control and MFA policies are enforced by your IdP
3. The CrewAI CLI automatically detects your SSO configuration via `crewai enterprise configure`
### CLI Defaults (SaaS)
| Setting | Default Value |
|---|---|
| `enterprise_base_url` | `https://app.crewai.com` |
| `oauth2_provider` | `workos` |
| `oauth2_domain` | `login.crewai.com` |
---
## Factory SSO Setup
Factory (self-hosted) deployments require you to configure SSO by setting environment variables in your Helm `values.yaml` and registering an application in your identity provider.
### Microsoft Entra ID (Azure AD)
<Steps>
<Step title="Register an Application">
1. Go to [portal.azure.com](https://portal.azure.com) → **Microsoft Entra ID** → **App registrations** → **New registration**
2. Configure:
- **Name:** `CrewAI` (or your preferred name)
- **Supported account types:** Accounts in this organizational directory only
- **Redirect URI:** Select **Web**, enter `https://<your-domain>/auth/entra_id/callback`
3. Click **Register**
</Step>
<Step title="Collect Credentials">
From the app overview page, copy:
- **Application (client) ID** → `ENTRA_ID_CLIENT_ID`
- **Directory (tenant) ID** → `ENTRA_ID_TENANT_ID`
</Step>
<Step title="Create Client Secret">
1. Navigate to **Certificates & Secrets** → **New client secret**
2. Add a description and select expiration period
3. Copy the secret value immediately (it won't be shown again) → `ENTRA_ID_CLIENT_SECRET`
</Step>
<Step title="Grant Admin Consent">
1. Go to **Enterprise applications** → select your app
2. Under **Security** → **Permissions**, click **Grant admin consent**
3. Ensure **Microsoft Graph → User.Read** is granted
</Step>
<Step title="Configure App Roles (Recommended)">
Under **App registrations** → your app → **App roles**, create:
| Display Name | Value | Allowed Member Types |
|---|---|---|
| Member | `member` | Users/Groups |
| Factory Admin | `factory-admin` | Users/Groups |
<Note>
The `member` role grants login access. The `factory-admin` role grants admin panel access. Roles are included in the JWT automatically.
</Note>
</Step>
<Step title="Assign Users">
1. Under **Properties**, set **Assignment required?** to **Yes**
2. Under **Users and groups**, assign users/groups with the appropriate role
</Step>
<Step title="Set Environment Variables">
```yaml
envVars:
AUTH_PROVIDER: "entra_id"
secrets:
ENTRA_ID_CLIENT_ID: "<Application (client) ID>"
ENTRA_ID_CLIENT_SECRET: "<Client Secret>"
ENTRA_ID_TENANT_ID: "<Directory (tenant) ID>"
```
</Step>
<Step title="Enable CLI Support (Optional)">
To allow `crewai login` via Device Authorization Grant:
1. Under **Authentication** → **Advanced settings**, enable **Allow public client flows**
2. Under **Expose an API**, add an Application ID URI (e.g., `api://crewai-cli`)
3. Add a scope (e.g., `read`) with **Admins and users** consent
4. Under **Manifest**, set `accessTokenAcceptedVersion` to `2`
5. Add environment variables:
```yaml
secrets:
ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID: "<Application (client) ID>"
ENTRA_ID_CUSTOM_OPENID_SCOPE: "<scope URI, e.g. api://crewai-cli/read>"
```
</Step>
</Steps>
---
### Okta
<Steps>
<Step title="Create App Integration">
1. Open Okta Admin Console → **Applications** → **Create App Integration**
2. Select **OIDC - OpenID Connect** → **Web Application** → **Next**
3. Configure:
- **App integration name:** `CrewAI SSO`
- **Sign-in redirect URI:** `https://<your-domain>/auth/okta/callback`
- **Sign-out redirect URI:** `https://<your-domain>`
- **Assignments:** Choose who can access (everyone or specific groups)
4. Click **Save**
</Step>
<Step title="Collect Credentials">
From the app details page:
- **Client ID** → `OKTA_CLIENT_ID`
- **Client Secret** → `OKTA_CLIENT_SECRET`
- **Okta URL** (top-right corner, under your username) → `OKTA_SITE`
</Step>
<Step title="Configure Authorization Server">
1. Navigate to **Security** → **API**
2. Select your authorization server (default: `default`)
3. Under **Access Policies**, add a policy and rule:
- In the rule, under **Scopes requested**, select **The following scopes** → **OIDC default scopes**
4. Note the **Name** and **Audience** of the authorization server
<Warning>
The authorization server name and audience must match `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` exactly. Mismatches cause `401 Unauthorized` or `Invalid token: Signature verification failed` errors.
</Warning>
</Step>
<Step title="Set Environment Variables">
```yaml
envVars:
AUTH_PROVIDER: "okta"
secrets:
OKTA_CLIENT_ID: "<Okta app client ID>"
OKTA_CLIENT_SECRET: "<Okta client secret>"
OKTA_SITE: "https://your-domain.okta.com"
OKTA_AUTHORIZATION_SERVER: "default"
OKTA_AUDIENCE: "api://default"
```
</Step>
<Step title="Enable CLI Support (Optional)">
1. Create a **new** app integration: **OIDC** → **Native Application**
2. Enable **Device Authorization** and **Refresh Token** grant types
3. Allow everyone in your organization to access
4. Add environment variable:
```yaml
secrets:
OKTA_DEVICE_AUTHORIZATION_CLIENT_ID: "<Native app client ID>"
```
<Note>
Device Authorization requires a **Native Application** — it cannot use the Web Application created for browser-based SSO.
</Note>
</Step>
</Steps>
---
### Keycloak
<Steps>
<Step title="Create a Client">
1. Open Keycloak Admin Console → navigate to your realm
2. **Clients** → **Create client**:
- **Client type:** OpenID Connect
- **Client ID:** `crewai-factory` (suggested)
3. Capability config:
- **Client authentication:** On
- **Standard flow:** Checked
4. Login settings:
- **Root URL:** `https://<your-domain>`
- **Valid redirect URIs:** `https://<your-domain>/auth/keycloak/callback`
- **Valid post logout redirect URIs:** `https://<your-domain>`
5. Click **Save**
</Step>
<Step title="Collect Credentials">
- **Client ID** → `KEYCLOAK_CLIENT_ID`
- Under **Credentials** tab: **Client secret** → `KEYCLOAK_CLIENT_SECRET`
- **Realm name** → `KEYCLOAK_REALM`
- **Keycloak server URL** → `KEYCLOAK_SITE`
</Step>
<Step title="Set Environment Variables">
```yaml
envVars:
AUTH_PROVIDER: "keycloak"
secrets:
KEYCLOAK_CLIENT_ID: "<client ID>"
KEYCLOAK_CLIENT_SECRET: "<client secret>"
KEYCLOAK_SITE: "https://keycloak.yourdomain.com"
KEYCLOAK_REALM: "<realm name>"
KEYCLOAK_AUDIENCE: "account"
# Only set if using a custom base path (pre-v17 migrations):
# KEYCLOAK_BASE_URL: "/auth"
```
<Note>
Keycloak includes `account` as the default audience in access tokens. For most installations, `KEYCLOAK_AUDIENCE=account` works without additional configuration. See [Keycloak audience documentation](https://www.keycloak.org/docs/latest/authorization_services/index.html) if you need a custom audience.
</Note>
</Step>
<Step title="Enable CLI Support (Optional)">
1. Create a **second** client:
- **Client type:** OpenID Connect
- **Client ID:** `crewai-factory-cli` (suggested)
- **Client authentication:** Off (Device Authorization requires a public client)
- **Authentication flow:** Check **only** OAuth 2.0 Device Authorization Grant
2. Add environment variable:
```yaml
secrets:
KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID: "<CLI client ID>"
```
</Step>
</Steps>
---
### WorkOS
<Steps>
<Step title="Configure in WorkOS Dashboard">
1. Create an application in the [WorkOS Dashboard](https://dashboard.workos.com)
2. Configure the redirect URI: `https://<your-domain>/auth/workos/callback`
3. Note the **Client ID** and **AuthKit domain**
4. Set up organizations in the WorkOS dashboard
</Step>
<Step title="Set Environment Variables">
```yaml
envVars:
AUTH_PROVIDER: "workos"
secrets:
WORKOS_CLIENT_ID: "<WorkOS client ID>"
WORKOS_AUTHKIT_DOMAIN: "<your-authkit-domain.authkit.com>"
```
</Step>
</Steps>
---
### Auth0
<Steps>
<Step title="Create Application">
1. In the [Auth0 Dashboard](https://manage.auth0.com), create a new **Regular Web Application**
2. Configure:
- **Allowed Callback URLs:** `https://<your-domain>/auth/auth0/callback`
- **Allowed Logout URLs:** `https://<your-domain>`
3. Note the **Domain**, **Client ID**, and **Client Secret**
</Step>
<Step title="Set Environment Variables">
```yaml
envVars:
AUTH_PROVIDER: "auth0"
secrets:
AUTH0_CLIENT_ID: "<Auth0 client ID>"
AUTH0_CLIENT_SECRET: "<Auth0 client secret>"
AUTH0_DOMAIN: "<your-tenant.auth0.com>"
```
</Step>
<Step title="Enable CLI Support (Optional)">
1. Create a **Native** application in Auth0 for Device Authorization
2. Enable the **Device Authorization** grant type under application settings
3. Configure the CLI with the appropriate audience and client ID
</Step>
</Steps>
---
## CLI Authentication
The CrewAI CLI supports SSO authentication via the **Device Authorization Grant** flow. This allows developers to authenticate from their terminal without exposing credentials.
### Quick Setup
For Factory installations, the CLI can auto-configure all OAuth2 settings:
```bash
crewai enterprise configure https://your-factory-url.app
```
This command fetches the SSO configuration from your Factory instance and sets all required CLI parameters automatically.
Then authenticate:
```bash
crewai login
```
<Note>
Requires CrewAI CLI version **1.6.0** or higher for Entra ID, **0.159.0** or higher for Okta, and **1.9.0** or higher for Keycloak.
</Note>
### Manual CLI Configuration
If you need to configure the CLI manually, use `crewai config set`:
```bash
# Set the provider
crewai config set oauth2_provider okta
# Set provider-specific values
crewai config set oauth2_domain your-domain.okta.com
crewai config set oauth2_client_id your-client-id
crewai config set oauth2_audience api://default
# Set the enterprise base URL
crewai config set enterprise_base_url https://your-factory-url.app
```
### CLI Configuration Reference
| Setting | Description | Example |
|---|---|---|
| `enterprise_base_url` | Your CrewAI instance URL | `https://crewai.yourcompany.com` |
| `oauth2_provider` | Provider name | `workos`, `okta`, `auth0`, `entra_id`, `keycloak` |
| `oauth2_domain` | Provider domain | `your-domain.okta.com` |
| `oauth2_client_id` | OAuth2 client ID | `0oaqnwji7pGW7VT6T697` |
| `oauth2_audience` | API audience identifier | `api://default` |
View current configuration:
```bash
crewai config list
```
### How Device Authorization Works
1. Run `crewai login` — the CLI requests a device code from your IdP
2. A verification URL and code are displayed in your terminal
3. Your browser opens to the verification URL
4. Enter the code and authenticate with your IdP credentials
5. The CLI receives an access token and stores it locally
---
## Role-Based Access Control (RBAC)
CrewAI Platform provides granular RBAC that integrates with your SSO provider.
### Permission Model
| Permission | Description |
|---|---|
| **Read** | View resources (dashboards, automations, logs) |
| **Write** | Create and modify resources |
| **Manage** | Full control including deletion and configuration |
### Resources
Permissions can be scoped to individual resources:
- **Usage Dashboard** — Platform usage metrics and analytics
- **Automations Dashboard** — Crew and flow management
- **Environment Variables** — Secret and configuration management
- **Individual Automations** — Per-automation access control
### Roles
- **Predefined roles** come out of the box with standard permission sets
- **Custom roles** can be created with any combination of permissions
- **Per-resource assignment** — limit specific automations to individual users or roles
### Factory Admin Access
For Factory deployments using Entra ID, admin access is controlled via App Roles:
- Assign the `factory-admin` role to users who need admin panel access
- Assign the `member` role for standard platform access
- Roles are communicated via JWT claims — no additional configuration needed after IdP setup
---
## Troubleshooting
### Invalid Redirect URI
**Symptom:** Authentication fails with a redirect URI mismatch error.
**Fix:** Ensure the redirect URI in your IdP exactly matches the expected callback URL:
| Provider | Callback URL |
|---|---|
| Entra ID | `https://<domain>/auth/entra_id/callback` |
| Okta | `https://<domain>/auth/okta/callback` |
| Keycloak | `https://<domain>/auth/keycloak/callback` |
| WorkOS | `https://<domain>/auth/workos/callback` |
| Auth0 | `https://<domain>/auth/auth0/callback` |
### CLI Login Fails (Device Authorization)
**Symptom:** `crewai login` returns an error or times out.
**Fix:**
- Verify that Device Authorization Grant is enabled in your IdP
- For Okta: ensure you have a **Native Application** (not Web) with Device Authorization grant
- For Entra ID: ensure **Allow public client flows** is enabled
- For Keycloak: ensure the CLI client has **Client authentication: Off** and only Device Authorization Grant enabled
- Check that `*_DEVICE_AUTHORIZATION_CLIENT_ID` environment variable is set on the server
### Token Validation Errors
**Symptom:** `Invalid token: Signature verification failed` or `401 Unauthorized` after login.
**Fix:**
- **Okta:** Verify `OKTA_AUTHORIZATION_SERVER` and `OKTA_AUDIENCE` match the authorization server's Name and Audience exactly
- **Entra ID:** Ensure `accessTokenAcceptedVersion` is set to `2` in the app manifest
- **Keycloak:** Verify `KEYCLOAK_AUDIENCE` matches the audience in your access tokens (default: `account`)
### Admin Consent Not Granted (Entra ID)
**Symptom:** Users can't log in, see "needs admin approval" message.
**Fix:** Go to **Enterprise applications** → your app → **Permissions** → **Grant admin consent**. Ensure `User.Read` is granted for Microsoft Graph.
### 403 Forbidden After Login
**Symptom:** User authenticates successfully but gets 403 errors.
**Fix:**
- Check that the user is assigned to the application in your IdP
- For Entra ID with **Assignment required = Yes**: ensure the user has a role assignment (Member or Factory Admin)
- For Okta: verify the user or their group is assigned under the app's **Assignments** tab
### CLI Can't Reach Factory Instance
**Symptom:** `crewai enterprise configure` fails to connect.
**Fix:**
- Verify the Factory URL is reachable from your machine
- Check that `enterprise_base_url` is set correctly: `crewai config list`
- Ensure TLS certificates are valid and trusted
---
## Environment Variables Reference
### Common
| Variable | Description |
|---|---|
| `AUTH_PROVIDER` | Authentication provider: `entra_id`, `okta`, `workos`, `auth0`, `keycloak`, `local` |
### Microsoft Entra ID
| Variable | Required | Description |
|---|---|---|
| `ENTRA_ID_CLIENT_ID` | ✅ | Application (client) ID from Azure |
| `ENTRA_ID_CLIENT_SECRET` | ✅ | Client secret from Azure |
| `ENTRA_ID_TENANT_ID` | ✅ | Directory (tenant) ID from Azure |
| `ENTRA_ID_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Client ID for Device Authorization Grant |
| `ENTRA_ID_CUSTOM_OPENID_SCOPE` | CLI only | Custom scope from "Expose an API" (e.g., `api://crewai-cli/read`) |
### Okta
| Variable | Required | Description |
|---|---|---|
| `OKTA_CLIENT_ID` | ✅ | Okta application client ID |
| `OKTA_CLIENT_SECRET` | ✅ | Okta client secret |
| `OKTA_SITE` | ✅ | Okta organization URL (e.g., `https://your-domain.okta.com`) |
| `OKTA_AUTHORIZATION_SERVER` | ✅ | Authorization server name (e.g., `default`) |
| `OKTA_AUDIENCE` | ✅ | Authorization server audience (e.g., `api://default`) |
| `OKTA_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Native app client ID for Device Authorization |
### WorkOS
| Variable | Required | Description |
|---|---|---|
| `WORKOS_CLIENT_ID` | ✅ | WorkOS application client ID |
| `WORKOS_AUTHKIT_DOMAIN` | ✅ | AuthKit domain (e.g., `your-domain.authkit.com`) |
### Auth0
| Variable | Required | Description |
|---|---|---|
| `AUTH0_CLIENT_ID` | ✅ | Auth0 application client ID |
| `AUTH0_CLIENT_SECRET` | ✅ | Auth0 client secret |
| `AUTH0_DOMAIN` | ✅ | Auth0 tenant domain (e.g., `your-tenant.auth0.com`) |
### Keycloak
| Variable | Required | Description |
|---|---|---|
| `KEYCLOAK_CLIENT_ID` | ✅ | Keycloak client ID |
| `KEYCLOAK_CLIENT_SECRET` | ✅ | Keycloak client secret |
| `KEYCLOAK_SITE` | ✅ | Keycloak server URL |
| `KEYCLOAK_REALM` | ✅ | Keycloak realm name |
| `KEYCLOAK_AUDIENCE` | ✅ | Token audience (default: `account`) |
| `KEYCLOAK_BASE_URL` | Optional | Base URL path (e.g., `/auth` for pre-v17 migrations) |
| `KEYCLOAK_DEVICE_AUTHORIZATION_CLIENT_ID` | CLI only | Public client ID for Device Authorization |
---
## Next Steps
- [Installation Guide](/installation) — Get started with CrewAI
- [Quickstart](/quickstart) — Build your first crew
- [RBAC Setup](/enterprise/features/rbac) — Detailed role and permission management

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

@@ -0,0 +1,262 @@
---
title: Tools & Integrations
description: "Connect external apps and manage internal tools your agents can use."
icon: "wrench"
mode: "wide"
---
## Overview
Tools & Integrations is the central hub for connecting third‑party apps and managing internal tools that your agents can use at runtime.
<Frame>
![Tools & Integrations Overview](/images/enterprise/crew_connectors.png)
</Frame>
## Explore
<Tabs>
<Tab title="Integrations" icon="plug">
## Agent Apps (Integrations)
Connect enterprise‑grade applications (e.g., Gmail, Google Drive, HubSpot, Slack) via OAuth to enable agent actions.
{" "}
<Steps>
<Step title="Connect">
Click <b>Connect</b> on an app and complete OAuth.
</Step>
<Step title="Configure">
Optionally adjust scopes, triggers, and action availability.
</Step>
<Step title="Use in Agents">
Connected services become available as tools for your agents.
</Step>
</Steps>
{" "}
<Frame>![Integrations Grid](/images/enterprise/agent-apps.png)</Frame>
### Connect your Account
1. Go to <Link href="https://app.crewai.com/crewai_plus/connectors">Integrations</Link>
2. Click <b>Connect</b> on the desired service
3. Complete the OAuth flow and grant scopes
4. Copy your Enterprise Token from <Link href="https://app.crewai.com/crewai_plus/settings/integrations">Integration Settings</Link>
{" "}
<Frame>
![Enterprise Token](/images/enterprise/enterprise_action_auth_token.png)
</Frame>
### Install Integration Tools
To use the integrations locally, you need to install the latest `crewai-tools` package.
```bash
uv add crewai-tools
```
### Environment Variable Setup
{" "}
<Note>
To use integrations with `Agent(apps=[])`, you must set the
`CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
Token.
</Note>
```bash
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```
Or add it to your `.env` file:
```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```
### Usage Example
{" "}
<Tip>
Use the new streamlined approach to integrate enterprise apps. Simply specify
the app and its actions directly in the Agent configuration.
</Tip>
```python
from crewai import Agent, Task, Crew
# Create an agent with Gmail capabilities
email_agent = Agent(
role="Email Manager",
goal="Manage and organize email communications",
backstory="An AI assistant specialized in email management and communication.",
apps=['gmail', 'gmail/send_email'] # Using canonical name 'gmail'
)
# Task to send an email
email_task = Task(
description="Draft and send a follow-up email to john@example.com about the project update",
agent=email_agent,
expected_output="Confirmation that email was sent successfully"
)
# Run the task
crew = Crew(
agents=[email_agent],
tasks=[email_task]
)
# Run the crew
crew.kickoff()
```
### Filtering Tools
```python
from crewai import Agent, Task, Crew
# Create agent with specific Gmail actions only
gmail_agent = Agent(
role="Gmail Manager",
goal="Manage gmail communications and notifications",
backstory="An AI assistant that helps coordinate gmail communications.",
apps=['gmail/fetch_emails'] # Using canonical name with specific action
)
notification_task = Task(
description="Find the email from john@example.com",
agent=gmail_agent,
expected_output="Email found from john@example.com"
)
crew = Crew(
agents=[gmail_agent],
tasks=[notification_task]
)
```
On a deployed crew, you can specify which actions are available for each integration from the service settings page.
{" "}
<Frame>
![Filter Actions](/images/enterprise/filtering_enterprise_action_tools.png)
</Frame>
### Scoped Deployments (multi‑user orgs)
You can scope each integration to a specific user. For example, a crew that connects to Google can use a specific user’s Gmail account.
{" "}
<Tip>Useful when different teams/users must keep data access separated.</Tip>
Use the `user_bearer_token` to scope authentication to the requesting user. If the user isn’t logged in, the crew won’t use connected integrations. Otherwise it falls back to the default bearer token configured for the deployment.
{" "}
<Frame>![User Bearer Token](/images/enterprise/user_bearer_token.png)</Frame>
{" "}
<div id="catalog"></div>
### Catalog
#### Communication & Collaboration
- Gmail — Manage emails and drafts
- Slack — Workspace notifications and alerts
- Microsoft — Office 365 and Teams integration
#### Project Management
- Jira — Issue tracking and project management
- ClickUp — Task and productivity management
- Asana — Team task and project coordination
- Notion — Page and database management
- Linear — Software project and bug tracking
- GitHub — Repository and issue management
#### Customer Relationship Management
- Salesforce — CRM account and opportunity management
- HubSpot — Sales pipeline and contact management
- Zendesk — Customer support ticket management
#### Business & Finance
- Stripe — Payment processing and customer management
- Shopify — E‑commerce store and product management
#### Productivity & Storage
- Google Sheets — Spreadsheet data synchronization
- Google Calendar — Event and schedule management
- Box — File storage and document management
…and more to come!
</Tab>
<Tab title="Internal Tools" icon="toolbox">
## Internal Tools
Create custom tools locally, publish them on CrewAI AMP Tool Repository and use them in your agents.
{" "}
<Tip>
Before running the commands below, make sure you log in to your CrewAI AMP
account by running this command: ```bash crewai login ```
</Tip>
{" "}
<Frame>
![Internal Tool Detail](/images/enterprise/tools-integrations-internal.png)
</Frame>
{" "}
<Steps>
<Step title="Create">
Create a new tool locally. ```bash crewai tool create your-tool ```
</Step>
<Step title="Publish">
Publish the tool to the CrewAI AMP Tool Repository. ```bash crewai tool
publish ```
</Step>
<Step title="Install">
Install the tool from the CrewAI AMP Tool Repository. ```bash crewai tool
install your-tool ```
</Step>
</Steps>
Manage:
- Name and description
- Visibility (Private / Public)
- Required environment variables
- Version history and downloads
- Team and role access
{" "}
<Frame>![Internal Tool Detail](/images/enterprise/tool-configs.png)</Frame>
</Tab>
</Tabs>
## Related
<CardGroup cols={2}>
<Card
title="Tool Repository"
href="/en/enterprise/guides/tool-repository#tool-repository"
icon="toolbox"
>
Create, publish, and version custom tools for your organization.
</Card>
<Card
title="Webhook Automation"
href="/en/enterprise/guides/webhook-automation"
icon="bolt"
>
Automate workflows and integrate with external platforms and services.
</Card>
</CardGroup>

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

@@ -0,0 +1,148 @@
---
title: Traces
description: "Using Traces to monitor your Crews"
icon: "timeline"
mode: "wide"
---
## Overview
Traces provide comprehensive visibility into your crew executions, helping you monitor performance, debug issues, and optimize your AI agent workflows.
## What are Traces?
Traces in CrewAI AMP are detailed execution records that capture every aspect of your crew's operation, from initial inputs to final outputs. They record:
- Agent thoughts and reasoning
- Task execution details
- Tool usage and outputs
- Token consumption metrics
- Execution times
- Cost estimates
<Frame>![Traces Overview](/images/enterprise/traces-overview.png)</Frame>
## Accessing Traces
<Steps>
<Step title="Navigate to the Traces Tab">
Once in your CrewAI AMP dashboard, click on the **Traces** to view all execution records.
</Step>
<Step title="Select an Execution">
You'll see a list of all crew executions, sorted by date. Click on any execution to view its detailed trace.
</Step>
</Steps>
## Understanding the Trace Interface
The trace interface is divided into several sections, each providing different insights into your crew's execution:
### 1. Execution Summary
The top section displays high-level metrics about the execution:
- **Total Tokens**: Number of tokens consumed across all tasks
- **Prompt Tokens**: Tokens used in prompts to the LLM
- **Completion Tokens**: Tokens generated in LLM responses
- **Requests**: Number of API calls made
- **Execution Time**: Total duration of the crew run
- **Estimated Cost**: Approximate cost based on token usage
<Frame>![Execution Summary](/images/enterprise/trace-summary.png)</Frame>
### 2. Tasks & Agents
This section shows all tasks and agents that were part of the crew execution:
- Task name and agent assignment
- Agents and LLMs used for each task
- Status (completed/failed)
- Individual execution time of the task
<Frame>![Task List](/images/enterprise/trace-tasks.png)</Frame>
### 3. Final Output
Displays the final result produced by the crew after all tasks are completed.
<Frame>![Final Output](/images/enterprise/final-output.png)</Frame>
### 4. Execution Timeline
A visual representation of when each task started and ended, helping you identify bottlenecks or parallel execution patterns.
<Frame>![Execution Timeline](/images/enterprise/trace-timeline.png)</Frame>
### 5. Detailed Task View
When you click on a specific task in the timeline or task list, you'll see:
<Frame>![Detailed Task View](/images/enterprise/trace-detailed-task.png)</Frame>
- **Task Key**: Unique identifier for the task
- **Task ID**: Technical identifier in the system
- **Status**: Current state (completed/running/failed)
- **Agent**: Which agent performed the task
- **LLM**: Language model used for this task
- **Start/End Time**: When the task began and completed
- **Execution Time**: Duration of this specific task
- **Task Description**: What the agent was instructed to do
- **Expected Output**: What output format was requested
- **Input**: Any input provided to this task from previous tasks
- **Output**: The actual result produced by the agent
## Using Traces for Debugging
Traces are invaluable for troubleshooting issues with your crews:
<Steps>
<Step title="Identify Failure Points">
When a crew execution doesn't produce the expected results, examine the trace to find where things went wrong. Look for:
- Failed tasks
- Unexpected agent decisions
- Tool usage errors
- Misinterpreted instructions
<Frame>
![Failure Points](/images/enterprise/failure.png)
</Frame>
</Step>
<Step title="Optimize Performance">
Use execution metrics to identify performance bottlenecks:
- Tasks that took longer than expected
- Excessive token usage
- Redundant tool operations
- Unnecessary API calls
</Step>
<Step title="Improve Cost Efficiency">
Analyze token usage and cost estimates to optimize your crew's efficiency:
- Consider using smaller models for simpler tasks
- Refine prompts to be more concise
- Cache frequently accessed information
- Structure tasks to minimize redundant operations
</Step>
</Steps>
## Performance and batching
CrewAI batches trace uploads to reduce overhead on high-volume runs:
- A TraceBatchManager buffers events and sends them in batches via the Plus API client
- Reduces network chatter and improves reliability on flaky connections
- Automatically enabled in the default trace listener; no configuration needed
This yields more stable tracing under load while preserving detailed task/agent telemetry.
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with trace analysis or any other
CrewAI AMP features.
</Card>

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

@@ -0,0 +1,173 @@
---
title: Webhook Streaming
description: "Using Webhook Streaming to stream events to your webhook"
icon: "webhook"
mode: "wide"
---
## Overview
Enterprise Event Streaming lets you receive real-time webhook updates about your crews and flows deployed to
CrewAI AMP, such as model calls, tool usage, and flow steps.
## Usage
When using the Kickoff API, include a `webhooks` object to your request, for example:
```json
{
"inputs": { "foo": "bar" },
"webhooks": {
"events": ["crew_kickoff_started", "llm_call_started"],
"url": "https://your.endpoint/webhook",
"realtime": false,
"authentication": {
"strategy": "bearer",
"token": "my-secret-token"
}
}
}
```
If `realtime` is set to `true`, each event is delivered individually and immediately, at the cost of crew/flow performance.
## Webhook Format
Each webhook sends a list of events:
```json
{
"events": [
{
"id": "event-id",
"execution_id": "crew-run-id",
"timestamp": "2025-02-16T10:58:44.965Z",
"type": "llm_call_started",
"data": {
"model": "gpt-4",
"messages": [
{ "role": "system", "content": "You are an assistant." },
{ "role": "user", "content": "Summarize this article." }
]
}
}
]
}
```
The `data` object structure varies by event type. Refer to the [event list](https://github.com/crewAIInc/crewAI/tree/main/lib/crewai/src/crewai/events/types) on GitHub.
As requests are sent over HTTP, the order of events can't be guaranteed. If you need ordering, use the `timestamp` field.
## Supported Events
CrewAI supports both system events and custom events in Enterprise Event Streaming. These events are sent to your configured webhook endpoint during crew and flow execution.
### Flow Events:
- `flow_created`
- `flow_started`
- `flow_finished`
- `flow_plot`
- `method_execution_started`
- `method_execution_finished`
- `method_execution_failed`
### Agent Events:
- `agent_execution_started`
- `agent_execution_completed`
- `agent_execution_error`
- `lite_agent_execution_started`
- `lite_agent_execution_completed`
- `lite_agent_execution_error`
- `agent_logs_started`
- `agent_logs_execution`
- `agent_evaluation_started`
- `agent_evaluation_completed`
- `agent_evaluation_failed`
### Crew Events:
- `crew_kickoff_started`
- `crew_kickoff_completed`
- `crew_kickoff_failed`
- `crew_train_started`
- `crew_train_completed`
- `crew_train_failed`
- `crew_test_started`
- `crew_test_completed`
- `crew_test_failed`
- `crew_test_result`
### Task Events:
- `task_started`
- `task_completed`
- `task_failed`
- `task_evaluation`
### Tool Usage Events:
- `tool_usage_started`
- `tool_usage_finished`
- `tool_usage_error`
- `tool_validate_input_error`
- `tool_selection_error`
- `tool_execution_error`
### LLM Events:
- `llm_call_started`
- `llm_call_completed`
- `llm_call_failed`
- `llm_stream_chunk`
### LLM Guardrail Events:
- `llm_guardrail_started`
- `llm_guardrail_completed`
### Memory Events:
- `memory_query_started`
- `memory_query_completed`
- `memory_query_failed`
- `memory_save_started`
- `memory_save_completed`
- `memory_save_failed`
- `memory_retrieval_started`
- `memory_retrieval_completed`
### Knowledge Events:
- `knowledge_search_query_started`
- `knowledge_search_query_completed`
- `knowledge_search_query_failed`
- `knowledge_query_started`
- `knowledge_query_completed`
- `knowledge_query_failed`
### Reasoning Events:
- `agent_reasoning_started`
- `agent_reasoning_completed`
- `agent_reasoning_failed`
Event names match the internal event bus. See GitHub for the full list of events.
You can emit your own custom events, and they will be delivered through the webhook stream alongside system events.
<CardGroup>
<Card
title="GitHub"
icon="github"
href="https://github.com/crewAIInc/crewAI/tree/main/src/crewai/utilities/events"
>
Full list of events
</Card>
<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
Contact our support team for assistance with webhook integration or
troubleshooting.
</Card>
</CardGroup>