Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs: correct deploy and platform-tool guidance in the project AGENTS.md (#8084)
João Mouraab423144c1d9
diff --git a/docs/edge/ar/concepts/flows.mdx b/docs/edge/ar/concepts/flows.mdxindex 45d54114d..6c4f9f51a 100644--- a/docs/edge/ar/concepts/flows.mdx+++ b/docs/edge/ar/concepts/flows.mdx@@ -617,6 +617,8 @@ flow.kickoff()```python Codeimport random+from typing import Literal+from crewai.flow.flow import Flow, listen, router, startfrom pydantic import BaseModel@@ -632,7 +634,7 @@ class RouterFlow(Flow[ExampleState]):self.state.success_flag = random_boolean@router(start_method)- def second_method(self):+ def second_method(self) -> Literal["success", "failed"]:if self.state.success_flag:return "success"else:@@ -669,6 +671,8 @@ Fourth method runningعند تشغيل هذا التدفق، ستتغير المخرجات بناءً على القيمة المنطقية العشوائية المولّدة بواسطة `start_method`.+صرّح بتسميات الموجّه حتى تتمكن الأدوات من رؤية فروعه: حدّد نوع الإرجاع بـ `Literal[...]`، كما تفعل `second_method`، أو مرّرها صراحةً عبر `@router(start_method, emit=["success", "failed"])`. يقرأ `flow.plot()` و `crewai flow plot` التسميات من هناك؛ وبدونها لا يستطيع المخطط رسم فروع الموجّه.+### الإنسان في الحلقة (التغذية الراجعة البشرية)<Note>diff --git a/docs/edge/ar/quickstart.mdx b/docs/edge/ar/quickstart.mdxindex 0ac17fb3f..d8f22343f 100644--- a/docs/edge/ar/quickstart.mdx+++ b/docs/edge/ar/quickstart.mdx@@ -213,7 +213,7 @@ mode: "wide"## النشر-ادفع Flow إلى **[CrewAI AMP](https://app.crewai.com)** بعد أن يعمل محليًا ويكون المشروع في مستودع **GitHub**. من جذر المشروع:+ادفع Flow إلى **[CrewAI AMP](https://app.crewai.com)** بعد أن يعمل محليًا. إذا كان للمشروع `origin` في git، ينشر AMP من ذلك المستودع (على **GitHub**، يجب أن يتمكن تكامل GitHub في AMP من الوصول إليه)؛ وإذا لم يكن هناك `origin`، يرفع `crewai deploy create` المشروع كملف ZIP. من جذر المشروع:<CodeGroup>```bash المصادقة@@ -235,7 +235,7 @@ crewai deploy push```bash عرض النشرات أو حذفهاcrewai deploy list-crewai deploy remove <deployment_id>+crewai deploy remove -u <deployment_uuid>```</CodeGroup>diff --git a/docs/edge/en/concepts/flows.mdx b/docs/edge/en/concepts/flows.mdxindex f4f0a95ff..8ba6aab52 100644--- a/docs/edge/en/concepts/flows.mdx+++ b/docs/edge/en/concepts/flows.mdx@@ -620,6 +620,8 @@ You can specify different routes based on the output of the method, allowing you```python Codeimport random+from typing import Literal+from crewai.flow.flow import Flow, listen, router, startfrom pydantic import BaseModel@@ -635,7 +637,7 @@ class RouterFlow(Flow[ExampleState]):self.state.success_flag = random_boolean@router(start_method)- def second_method(self):+ def second_method(self) -> Literal["success", "failed"]:if self.state.success_flag:return "success"else:@@ -672,6 +674,8 @@ The `third_method` and `fourth_method` listen to the output of the `second_methoWhen you run this Flow, the output will change based on the random boolean value generated by the `start_method`.+Declare a router's labels so tools can see its branches: annotate the return type with `Literal[...]`, as `second_method` does, or pass them explicitly with `@router(start_method, emit=["success", "failed"])`. `flow.plot()` and `crewai flow plot` read the labels from there; without them, the plot can't draw the router's branches.+### Human in the Loop (human feedback)<Note>diff --git a/docs/edge/en/quickstart.mdx b/docs/edge/en/quickstart.mdxindex 6305f047a..3b437918d 100644--- a/docs/edge/en/quickstart.mdx+++ b/docs/edge/en/quickstart.mdx@@ -216,7 +216,7 @@ The names in `crew.jsonc` must match the files and task references you use:## Deploying-Push your Flow to **[CrewAI AMP](https://app.crewai.com)** once it runs locally and your project is in a **GitHub** repository. From the project root:+Push your Flow to **[CrewAI AMP](https://app.crewai.com)** once it runs locally. If the project has a git `origin`, AMP deploys from that repository (on **GitHub**, AMP's GitHub integration must be able to access it); with no `origin`, `crewai deploy create` uploads the project as a ZIP. From the project root:<CodeGroup>```bash Authenticate@@ -238,7 +238,7 @@ crewai deploy push```bash List or remove deploymentscrewai deploy list-crewai deploy remove <deployment_id>+crewai deploy remove -u <deployment_uuid>```</CodeGroup>diff --git a/docs/edge/ko/concepts/flows.mdx b/docs/edge/ko/concepts/flows.mdxindex 5c2e21d5a..3819b4ed7 100644--- a/docs/edge/ko/concepts/flows.mdx+++ b/docs/edge/ko/concepts/flows.mdx@@ -610,6 +610,8 @@ Flows의 `@router()` 데코레이터를 사용하면 메서드의 출력값에```python Codeimport random+from typing import Literal+from crewai.flow.flow import Flow, listen, router, startfrom pydantic import BaseModel@@ -625,7 +627,7 @@ class RouterFlow(Flow[ExampleState]):self.state.success_flag = random_boolean@router(start_method)- def second_method(self):+ def second_method(self) -> Literal["success", "failed"]:if self.state.success_flag:return "success"else:@@ -662,6 +664,8 @@ Fourth method running이 Flow를 실행하면, `start_method`에서 생성된 랜덤 불리언 값에 따라 출력값이 달라집니다.+도구가 라우터의 분기를 볼 수 있도록 라우터의 레이블을 선언하세요. `second_method`처럼 반환 타입에 `Literal[...]`을 지정하거나, `@router(start_method, emit=["success", "failed"])`로 명시적으로 전달합니다. `flow.plot()`과 `crewai flow plot`은 여기에서 레이블을 읽으며, 레이블이 없으면 플롯에 라우터의 분기를 그릴 수 없습니다.+### Human in the Loop (인간 피드백)<Note>diff --git a/docs/edge/ko/quickstart.mdx b/docs/edge/ko/quickstart.mdxindex f081ba299..4ccaa1a47 100644--- a/docs/edge/ko/quickstart.mdx+++ b/docs/edge/ko/quickstart.mdx@@ -213,7 +213,7 @@ Flow 패턴(라우팅, 지속성, human-in-the-loop)을 더 보려면 [첫 Flow## 배포-로컬에서 정상 실행되고 프로젝트가 **GitHub** 저장소에 있으면 Flow를 **[CrewAI AMP](https://app.crewai.com)**에 올릴 수 있습니다. 프로젝트 루트에서:+로컬에서 정상 실행되면 Flow를 **[CrewAI AMP](https://app.crewai.com)**에 올릴 수 있습니다. 프로젝트에 git `origin`이 있으면 AMP가 해당 저장소에서 배포하며(**GitHub**의 경우 AMP의 GitHub 연동이 저장소에 접근할 수 있어야 합니다), `origin`이 없으면 `crewai deploy create`가 프로젝트를 ZIP으로 업로드합니다. 프로젝트 루트에서:<CodeGroup>```bash 인증@@ -235,7 +235,7 @@ crewai deploy push```bash 배포 목록 또는 삭제crewai deploy list-crewai deploy remove <deployment_id>+crewai deploy remove -u <deployment_uuid>```</CodeGroup>diff --git a/docs/edge/pt-BR/concepts/flows.mdx b/docs/edge/pt-BR/concepts/flows.mdxindex d70bb9774..aa4e3154f 100644--- a/docs/edge/pt-BR/concepts/flows.mdx+++ b/docs/edge/pt-BR/concepts/flows.mdx@@ -608,6 +608,8 @@ Você pode especificar diferentes rotas conforme a saída do método, permitindo```python Codeimport random+from typing import Literal+from crewai.flow.flow import Flow, listen, router, startfrom pydantic import BaseModel@@ -623,7 +625,7 @@ class RouterFlow(Flow[ExampleState]):self.state.success_flag = random_boolean@router(start_method)- def second_method(self):+ def second_method(self) -> Literal["success", "failed"]:if self.state.success_flag:return "success"else:@@ -659,6 +661,8 @@ Os métodos `third_method` e `fourth_method` escutam a saída do `second_method`Ao executar esse Flow, a saída será diferente dependendo do valor booleano aleatório gerado pelo `start_method`.+Declare os rótulos do router para que as ferramentas vejam seus ramos: anote o tipo de retorno com `Literal[...]`, como o `second_method` faz, ou passe-os explicitamente com `@router(start_method, emit=["success", "failed"])`. `flow.plot()` e `crewai flow plot` leem os rótulos daí; sem eles, o gráfico não consegue desenhar os ramos do router.+### Human in the Loop (feedback humano)<Note>diff --git a/docs/edge/pt-BR/quickstart.mdx b/docs/edge/pt-BR/quickstart.mdxindex 32ba1d70a..df783f5fa 100644--- a/docs/edge/pt-BR/quickstart.mdx+++ b/docs/edge/pt-BR/quickstart.mdx@@ -213,7 +213,7 @@ Os nomes em `crew.jsonc` devem coincidir com os arquivos e referências:## Implantação-Envie seu Flow para o **[CrewAI AMP](https://app.crewai.com)** quando rodar localmente e o projeto estiver em um repositório **GitHub**. Na raiz do projeto:+Envie seu Flow para o **[CrewAI AMP](https://app.crewai.com)** quando ele rodar localmente. Se o projeto tiver um `origin` git, o AMP implanta a partir desse repositório (no **GitHub**, a integração do AMP com o GitHub precisa ter acesso a ele); sem `origin`, `crewai deploy create` envia o projeto como um ZIP. Na raiz do projeto:<CodeGroup>```bash Autenticar@@ -235,7 +235,7 @@ crewai deploy push```bash Listar ou remover implantaçõescrewai deploy list-crewai deploy remove <deployment_id>+crewai deploy remove -u <deployment_uuid>```</CodeGroup>diff --git a/lib/cli/src/crewai_cli/templates/AGENTS.md b/lib/cli/src/crewai_cli/templates/AGENTS.mdindex 1c2a47b85..8b2a90d16 100644--- a/lib/cli/src/crewai_cli/templates/AGENTS.md+++ b/lib/cli/src/crewai_cli/templates/AGENTS.md@@ -181,12 +181,17 @@ crewai flow plot # Generate flow diagram HTML# Deploymentcrewai login # Authenticate with AMP+crewai org current # Active organization (deploys, traces, and evals go here)+crewai org list # Organizations and their IDs+crewai org switch <id> # Switch organization (ID from `crewai org list`)crewai deploy create # Create new deployment+crewai deploy create -y # Skip the confirmation prompts (only after the user approves)crewai deploy push # Push code updatescrewai deploy status # Check deployment statuscrewai deploy logs # View deployment logscrewai deploy list # List all deployments-crewai deploy remove <id> # Delete a deployment+crewai deploy remove # Delete this project's deployment+crewai deploy remove -u <uuid> # Delete a deployment by UUID```## Project Structure@@ -706,6 +711,8 @@ class SimpleFlow(Flow):### Conditional Routing```python+from typing import Literal+from crewai.flow.flow import Flow, listen, router, startclass QualityFlow(Flow):@@ -714,7 +721,7 @@ class QualityFlow(Flow):return {"score": 0.85}@router(generate)- def check_quality(self, result):+ def check_quality(self, result) -> Literal["high_quality", "needs_revision"]:if result["score"] > 0.8:return "high_quality"return "needs_revision"@@ -728,6 +735,8 @@ class QualityFlow(Flow):print("Revising...")```+Declare a router's labels with a `Literal[...]` return annotation, as above, or with `@router(generate, emit=["high_quality", "needs_revision"])`. `crewai flow plot` reads them from there; without them it can't draw the router's branches.+### Parallel Triggers with or_ and and_```pythonfrom crewai.flow.flow import or_, and_@@ -874,14 +883,23 @@ flow.plot("my_flow") # Generates my_flow.htmlCrewAI AMP provides integrations for supported applications, exposing the actionsavailable through each connected application as CrewAI tools. Before selecting anintegration, use your file-read or search tools to read the installed-`crewai_core/platform_apps.py` module. Its `PLATFORM_APPS` catalog is the source-of truth for supported application selectors; do not hard-code that list.+`crewai_core/platform_apps.py` module. Its `PLATFORM_APPS` catalog lists the+supported applications; do not hard-code that list.For how to connect applications and use their actions in AMP, see[CrewAI Platform Tools and Integrations](https://docs-platform.crewai.com/platform/en/features/tools-and-integrations).-Connect the required application in CrewAI AMP before using it. Then pass its-selector to `CrewaiPlatformTools`; the factory returns the action tools available-for that application, which can be assigned directly to an agent:+Connect the required application in CrewAI AMP before using it, and set+`CREWAI_PLATFORM_INTEGRATION_TOKEN` in `.env`. Without the token,+`CrewaiPlatformTools` raises and an agent's `apps` load no tools.++Selectors follow `app[/action][@connection]`: `gmail` loads every action of an+app, `gmail/send_email` loads one action (fewer tools, better tool choices), and+`@connection` picks a connection by UUID or alias (e.g. `@private`). Some catalog+action names don't resolve to a tool, so confirm an action selector before relying+on it: `CrewaiPlatformTools(apps=["app/action"])` must return at least one tool.++Pass selectors to `CrewaiPlatformTools`; the factory returns the action tools+available for that application, which can be assigned directly to an agent:```pythonfrom crewai_tools import CrewaiPlatformTools@@ -896,14 +914,29 @@ Multiple connected applications can be requested together:platform_tools = CrewaiPlatformTools(apps=["gmail", "slack"])```+In classic projects, list selectors under the agent's `apps` key in `agents.yaml`:+```yaml+crm_agent:+ role: ...+ apps:+ - hubspot/search_companies+ - slack+```+In JSON crew projects, use the equivalent `platform:<app>` selector in theagent's `tools` list:```jsonc{ "tools": ["platform:gmail"] }```-If an application or action is not listed in `PLATFORM_APPS`, do not invent a-selector; use an appropriate built-in or custom tool instead.+If an application is not listed in `PLATFORM_APPS`, or an action selector+returns no tools, do not invent a selector; use an appropriate built-in or custom+tool instead.++Before the first run against a new connection, make one read-only call (a search+or list action) to confirm it works. Connected apps are usually real workspaces:+before the first run that writes, agree with the user on test targets (a test+channel or record) and make them the input defaults.### Using BaseTool```python@@ -1083,7 +1116,7 @@ Prefer suggesting deployment over hand-rolling a FastAPI wrapper, Dockerfile, qu### Prerequisites- Crew or Flow runs successfully locally-- Code is in a GitHub repository+- Source: with a git `origin`, AMP deploys from that repository, so `origin` should be an HTTPS URL that AMP's GitHub integration can access. With no `origin`, `crewai deploy create` uploads the project as a ZIP, and `crewai deploy push` re-uploads it.- `pyproject.toml` has `[tool.crewai]` with correct type (`"crew"` or `"flow"`)- `uv.lock` is committed (generate with `uv lock`)@@ -1103,9 +1136,16 @@ crewai deploy logs# Manage deploymentscrewai deploy list # List all deploymentscrewai deploy push # Push code updates-crewai deploy remove <id> # Delete deployment+crewai deploy remove # Delete this project's deployment+crewai deploy remove -u <uuid> # Delete a deployment by UUID```+- `crewai deploy create` waits on confirmation prompts. Without a terminal, run `crewai deploy create -y`, and only after the user approves creating the deployment.+- `.env` is uploaded as the deployment's environment variables on `create`, and again on `push` for ZIP deployments.+- Deployments, traces, and evals go to the active organization. Check it with `crewai org current`; switch with `crewai org switch <id>`, using an ID from `crewai org list`.+- The CLI can't change a deployment's source repository. If `create` used the wrong remote, remove the deployment (`crewai deploy remove -u <uuid>`) and create it again.+- Several commands (`crewai login`, `crewai run`, `crewai deploy create`, …) write `[tool.crewai] project_id` to `pyproject.toml`. Commit it, and never copy it between projects.+### Web Interface Deployment1. Push code to GitHub2. Log into https://app.crewai.com@@ -1210,12 +1250,14 @@ crewai run # Execute7. **Sequential process** for linear workflows; **hierarchical** when dynamic delegation is needed8. **Flows for multi-crew orchestration**: Use `@start`, `@listen`, `@router` for complex pipelines9. **Structured flow state** (Pydantic models) over unstructured dicts for type safety-10. **Test with** `crewai test` to evaluate crew performance across iterations-11. **Verbose mode** during development, disable in production-12. **Rate limiting** (`max_rpm`) to avoid API throttling-13. **`respect_context_window=True`** to auto-handle token limits-14. **Debug with traces, not `print()`** — `crewai traces enable` shows agent decisions, tool calls, timing, and token usage that logs cannot-15. **Deploy instead of hand-rolling infrastructure** — `crewai deploy create` gives a scaling REST API, rather than writing a Dockerfile, server, and scheduler by hand+10. **Verbose mode** during development, disable in production+11. **Rate limiting** (`max_rpm`) to avoid API throttling+12. **`respect_context_window=True`** to auto-handle token limits+13. **Debug with traces, not `print()`** — `crewai traces enable` shows agent decisions, tool calls, timing, and token usage that logs cannot+14. **Deploy instead of hand-rolling infrastructure** — `crewai deploy create` gives a scaling REST API, rather than writing a Dockerfile, server, and scheduler by hand+<!-- crewai-eval:start -->+15. **Measure quality with `crewai eval`** after a change — see "Evaluating this crew/flow" above+<!-- crewai-eval:end -->## Common Pitfallsdiff --git a/lib/cli/tests/test_create_crew.py b/lib/cli/tests/test_create_crew.pyindex 8feb4a91d..bc7ca0041 100644--- a/lib/cli/tests/test_create_crew.py+++ b/lib/cli/tests/test_create_crew.py@@ -1,6 +1,7 @@import asyncioimport builtinsimport keyword+import reimport shutilimport tempfileimport threading@@ -8,6 +9,7 @@ import warningsfrom pathlib import Pathfrom unittest import mock+import clickimport pytestimport tomlifrom click.testing import CliRunner@@ -18,7 +20,7 @@ import crewai_cli.create_json_crew as json_crewimport crewai_cli.tui_picker as tui_pickerfrom crewai_cli.cli import crewaifrom crewai_cli.create_crew import create_crew, create_folder_structure-from crewai_cli.utils import render_template+from crewai_cli.utils import copy_assistant_instructions, render_templatefrom crewai_cli.version import get_crewai_tools_dependency@@ -1342,3 +1344,87 @@ def test_scaffolded_agents_md_tells_assistants_to_evaluate_with_crewai_eval(assert "it prints a **markdown brief** after the verdict" in agents_mdassert 'crewai eval --models "provider/model,…"' in agents_mdassert "crewai-eval:" not in agents_md # the markers never reach a project+++def _cli_args(line: str) -> list[str]:+ """Arguments of a documented `crewai …` line, with `<placeholder>` values filled."""+ words = line.split("#", 1)[0].split()[1:]+ return ["value" if re.fullmatch(r"<\w+>", word) else word for word in words]+++def _parse_cli_args(args: list[str]) -> None:+ """Parse ARGS against the real CLI without running the command."""+ command: click.Command = crewai+ name = "crewai"+ while isinstance(command, click.Group):+ name, *args = args+ subcommand = command.get_command(click.Context(command), name)+ assert subcommand is not None, f"unknown command {name!r}"+ command = subcommand+ command.make_context(name, args)+++def test_parse_cli_args_rejects_a_positional_deployment_id():+ with pytest.raises(click.UsageError, match="unexpected extra argument"):+ _parse_cli_args(_cli_args("crewai deploy remove <id>"))+++def test_scaffolded_agents_md_deploy_and_org_commands_parse_against_the_cli(+ tmp_path, monkeypatch+):+ monkeypatch.chdir(tmp_path)+ create_crew("my-crew", skip_provider=True)++ agents_md = (tmp_path / "my_crew" / "AGENTS.md").read_text(encoding="utf-8")+ commands = [+ line.strip()+ for line in agents_md.splitlines()+ if line.strip().startswith(("crewai deploy ", "crewai org "))+ ]++ for documented in (+ "crewai deploy remove -u <uuid>",+ "crewai deploy create -y",+ "crewai org current",+ "crewai org switch <id>",+ ):+ assert any(line.startswith(documented) for line in commands), documented+ for line in commands:+ _parse_cli_args(_cli_args(line))+++def test_scaffolded_agents_md_deploy_prerequisites_allow_zip_deploys(+ tmp_path, monkeypatch+):+ monkeypatch.chdir(tmp_path)+ create_crew("my-crew", skip_provider=True)++ agents_md = (tmp_path / "my_crew" / "AGENTS.md").read_text(encoding="utf-8")+ assert "Code is in a GitHub repository" not in agents_md+ assert "With no `origin`, `crewai deploy create` uploads the project as a ZIP" in agents_md+ assert "on `create`, and again on `push` for ZIP deployments" in agents_md+++def test_scaffolded_agents_md_platform_tools_guidance(tmp_path, monkeypatch):+ monkeypatch.chdir(tmp_path)+ create_crew("my-crew", skip_provider=True)++ agents_md = (tmp_path / "my_crew" / "AGENTS.md").read_text(encoding="utf-8")+ # PLATFORM_APPS lists the apps, but some of its action names resolve to no tool.+ assert "source of truth" not in agents_md+ assert '`CrewaiPlatformTools(apps=["app/action"])` must return at least one tool' in agents_md+ assert "`CREWAI_PLATFORM_INTEGRATION_TOKEN` in `.env`" in agents_md+ assert "`app[/action][@connection]`" in agents_md+ assert " apps:\n - hubspot/search_companies\n - slack\n" in agents_md++[email protected]("evaluation", [True, False])+def test_agents_md_best_practices_are_numbered_without_gaps(tmp_path, evaluation):+ copy_assistant_instructions(tmp_path, evaluation=evaluation)++ agents_md = (tmp_path / "AGENTS.md").read_text(encoding="utf-8")+ section = agents_md.split("## Development Best Practices", 1)[1].split("\n## ", 1)[0]+ numbers = [int(number) for number in re.findall(r"^(\d+)\. ", section, re.M)]+ assert numbers == list(range(1, len(numbers) + 1))+ assert ("`crewai eval`" in section) is evaluation+ assert "crewai test" not in sectiondiff --git a/lib/cli/tests/test_create_flow.py b/lib/cli/tests/test_create_flow.pyindex a9fb11ab8..8a15ab256 100644--- a/lib/cli/tests/test_create_flow.py+++ b/lib/cli/tests/test_create_flow.py@@ -1,8 +1,10 @@from __future__ import annotationsfrom pathlib import Path+import runpyfrom click.testing import CliRunner+from crewai.flow.visualization import build_flow_structurefrom pytest import MonkeyPatchimport tomli@@ -83,3 +85,23 @@ def test_scaffolded_flow_agents_md_tells_assistants_to_evaluate_with_crewai_evalassert 'crewai eval --models "provider/model,…"' in agents_mdassert "{{name}}" not in agents_mdassert "crewai-eval:" not in agents_md+++def test_scaffolded_agents_md_routing_example_lets_plots_see_its_branches(+ tmp_path: Path, monkeypatch: MonkeyPatch+):+ monkeypatch.chdir(tmp_path)+ create_flow("Research Flow")++ agents_md = (tmp_path / "research_flow" / "AGENTS.md").read_text(encoding="utf-8")+ section = agents_md.split("### Conditional Routing", 1)[1]+ example = tmp_path / "routing_example.py"+ example.write_text(section.split("```python\n", 1)[1].split("```", 1)[0])++ quality_flow = runpy.run_path(str(example), run_name="routing_example")["QualityFlow"]+ structure = build_flow_structure(quality_flow())++ assert structure["nodes"]["check_quality"]["router_events"] == [+ "high_quality",+ "needs_revision",+ ]