From 5504d9a8cfdb8b2b76a0ba7fc7ba6a1313d4f917 Mon Sep 17 00:00:00 2001 From: nicoferdi96 Date: Fri, 9 Jan 2026 15:35:45 +0100 Subject: [PATCH] Better project structure for flows --- docs/en/enterprise/guides/deploy-to-amp.mdx | 70 ++---------------- .../guides/prepare-for-deployment.mdx | 73 +++++++++++-------- 2 files changed, 46 insertions(+), 97 deletions(-) diff --git a/docs/en/enterprise/guides/deploy-to-amp.mdx b/docs/en/enterprise/guides/deploy-to-amp.mdx index dc686871c..31ff8ca20 100644 --- a/docs/en/enterprise/guides/deploy-to-amp.mdx +++ b/docs/en/enterprise/guides/deploy-to-amp.mdx @@ -289,68 +289,7 @@ For automated deployments in CI/CD pipelines, you can use the CrewAI API to trig -## ⚠️ Environment Variable Security Requirements - - - **Important**: CrewAI AMP has security restrictions on environment variable - names that can cause deployment failures if not followed. - - -### Blocked Environment Variable Patterns - -For security reasons, the following environment variable naming patterns are **automatically filtered** and will cause deployment issues: - -**Blocked Patterns:** - -- Variables ending with `_TOKEN` (e.g., `MY_API_TOKEN`) -- Variables ending with `_PASSWORD` (e.g., `DB_PASSWORD`) -- Variables ending with `_SECRET` (e.g., `API_SECRET`) -- Variables ending with `_KEY` in certain contexts - -**Specific Blocked Variables:** - -- `GITHUB_USER`, `GITHUB_TOKEN` -- `AWS_REGION`, `AWS_DEFAULT_REGION` -- Various internal CrewAI system variables - -### Allowed Exceptions - -Some variables are explicitly allowed despite matching blocked patterns: - -- `AZURE_AD_TOKEN` -- `AZURE_OPENAI_AD_TOKEN` -- `ENTERPRISE_ACTION_TOKEN` -- `CREWAI_ENTEPRISE_TOOLS_TOKEN` - -### How to Fix Naming Issues - -If your deployment fails due to environment variable restrictions: - -```bash -# ❌ These will cause deployment failures -OPENAI_TOKEN=sk-... -DATABASE_PASSWORD=mypassword -API_SECRET=secret123 - -# ✅ Use these naming patterns instead -OPENAI_API_KEY=sk-... -DATABASE_CREDENTIALS=mypassword -API_CONFIG=secret123 -``` - -### Best Practices - -1. **Use standard naming conventions**: `PROVIDER_API_KEY` instead of `PROVIDER_TOKEN` -2. **Test locally first**: Ensure your crew works with the renamed variables -3. **Update your code**: Change any references to the old variable names -4. **Document changes**: Keep track of renamed variables for your team - - - If you encounter deployment failures with cryptic environment variable errors, - check your variable names against these patterns first. - - -### Interact with Your Deployed Crew +## Interact with Your Deployed Automation Once deployment is complete, you can access your crew through: @@ -424,8 +363,9 @@ git push **Solution**: Verify your project matches the expected structure: -- **Crews**: Must have entry point at `src/project_name/main.py` with a `run()` function -- **Flows**: Must have entry point at `main.py` (project root) with a `kickoff()` function +- **Both Crews and Flows**: Must have entry point at `src/project_name/main.py` +- **Crews**: Use a `run()` function as entry point +- **Flows**: Use a `kickoff()` function as entry point See [Prepare for Deployment](/en/enterprise/guides/prepare-for-deployment) for detailed structure diagrams. @@ -481,7 +421,7 @@ type = "flow" **Solution**: 1. Verify your LLM provider's API key is correctly set in environment variables -2. Check that variable names don't match [blocked patterns](#blocked-environment-variable-patterns) +2. Ensure the environment variable names match what your code expects 3. Test locally with the exact same environment variables before deploying #### Crew Execution Errors diff --git a/docs/en/enterprise/guides/prepare-for-deployment.mdx b/docs/en/enterprise/guides/prepare-for-deployment.mdx index 27b30abfe..fe09e5319 100644 --- a/docs/en/enterprise/guides/prepare-for-deployment.mdx +++ b/docs/en/enterprise/guides/prepare-for-deployment.mdx @@ -13,7 +13,7 @@ mode: "wide" ## Understanding Automations -In CrewAI AMP, **automations** is the umbrella term for deployable AI projects. An automation can be either: +In CrewAI AMP, **automations** is the umbrella term for deployable Agentic AI projects. An automation can be either: - **A Crew**: A standalone team of AI agents working together on tasks - **A Flow**: An orchestrated workflow that can combine multiple crews, direct LLM calls, and procedural logic @@ -24,20 +24,21 @@ Understanding which type you're deploying is essential because they have differe - Standalone AI agent teams with a nested `src/` structure. Best for focused, collaborative tasks. + Standalone AI agent teams with `crew.py` defining agents and tasks. Best for focused, collaborative tasks. - Orchestrated workflows with root-level `main.py`. Best for complex, multi-stage processes. + Orchestrated workflows with embedded crews in a `crews/` folder. Best for complex, multi-stage processes. | Aspect | Crew | Flow | |--------|------|------| -| **Project structure** | Nested `src/project_name/` | Root-level files | -| **Main logic location** | `src/project_name/crew.py` | `main.py` at root | -| **Entry point** | `src/project_name/main.py` | `main.py` at root | +| **Project structure** | `src/project_name/` with `crew.py` | `src/project_name/` with `crews/` folder | +| **Main logic location** | `src/project_name/crew.py` | `src/project_name/main.py` (Flow class) | +| **Entry point function** | `run()` in `main.py` | `kickoff()` in `main.py` | | **pyproject.toml type** | `type = "crew"` | `type = "flow"` | | **CLI create command** | `crewai create crew name` | `crewai create flow name` | +| **Config location** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` | | **Can contain other crews** | No | Yes (in `crews/` folder) | ## Project Structure Reference @@ -82,20 +83,26 @@ my_flow/ ├── README.md ├── .env ├── uv.lock # REQUIRED for deployment -├── main.py # Entry point with kickoff() function -├── crews/ # Embedded crews -│ └── research_crew/ -│ ├── config/ -│ │ ├── agents.yaml -│ │ └── tasks.yaml -│ └── research_crew.py # Each crew needs @CrewBase decorator -└── tools/ - └── custom_tool.py +└── src/ + └── my_flow/ + ├── __init__.py + ├── main.py # Entry point with kickoff() function + Flow class + ├── crews/ # Embedded crews folder + │ └── poem_crew/ + │ ├── __init__.py + │ ├── poem_crew.py # Crew with @CrewBase decorator + │ └── config/ + │ ├── agents.yaml + │ └── tasks.yaml + └── tools/ + ├── __init__.py + └── custom_tool.py ``` - Flows have `main.py` at the **root level**, not inside a `src/` folder. - This is a key difference from Crew projects. + Both Crews and Flows use the `src/project_name/` structure. + The key difference is that Flows have a `crews/` folder for embedded crews, + while Crews have `crew.py` directly in the project folder. ## Pre-Deployment Checklist @@ -197,11 +204,11 @@ class MyCrew(): ### 4. Check Project Entry Points -Verify your project has the correct entry point function: +Both Crews and Flows have their entry point in `src/project_name/main.py`: - The entry point is in `src/project_name/main.py`: + The entry point uses a `run()` function: ```python # src/my_crew/main.py @@ -218,17 +225,19 @@ Verify your project has the correct entry point function: ``` - The entry point is in `main.py` at the project root: + The entry point uses a `kickoff()` function with a Flow class: ```python - # main.py (at project root) - from crewai.flow.flow import Flow, listen, start + # src/my_flow/main.py + from crewai.flow import Flow, listen, start + from my_flow.crews.poem_crew.poem_crew import PoemCrew class MyFlow(Flow): @start() def begin(self): # Flow logic here - pass + result = PoemCrew().crew().kickoff(inputs={...}) + return result def kickoff(): """Run the flow.""" @@ -246,7 +255,6 @@ Before deployment, ensure you have: 1. **LLM API keys** ready (OpenAI, Anthropic, Google, etc.) 2. **Tool API keys** if using external tools (Serper, etc.) -3. Variable names that comply with [security requirements](/en/enterprise/guides/deploy-to-amp#environment-variable-security-requirements) Test your project locally with the same environment variables before deploying @@ -264,14 +272,16 @@ grep -A2 "\[tool.crewai\]" pyproject.toml # 2. Verify uv.lock exists ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'" -# 3. For Crews - verify structure -ls -la src/*/crew.py 2>/dev/null || echo "No crew.py found in src/" +# 3. Verify src/ structure exists +ls -la src/*/main.py 2>/dev/null || echo "No main.py found in src/" -# 4. For Flows - verify structure -ls -la main.py 2>/dev/null || echo "No main.py at root" -ls -la crews/ 2>/dev/null || echo "No crews/ folder (optional for flows)" +# 4. For Crews - verify crew.py exists +ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)" -# 5. Check for CrewBase usage +# 5. For Flows - verify crews/ folder exists +ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)" + +# 6. Check for CrewBase usage grep -r "@CrewBase" . --include="*.py" ``` @@ -282,8 +292,7 @@ grep -r "@CrewBase" . --include="*.py" | Missing `uv.lock` | Build fails during dependency resolution | Run `uv lock` and commit | | Wrong `type` in pyproject.toml | Build succeeds but runtime fails | Change to correct type | | Missing `@CrewBase` decorator | "Config not found" errors | Add decorator to all crew classes | -| Crew `main.py` at root level | Entry point not found | Move to `src/project_name/` | -| Flow `main.py` in `src/` | Entry point not found | Move to project root | +| Files at root instead of `src/` | Entry point not found | Move to `src/project_name/` | | Missing `run()` or `kickoff()` | Cannot start automation | Add correct entry function | ## Next Steps