Deploy to CrewAI AMP

Ship a crew or flow to AMP without burning deploys on project-shape errors, stale code, stale env values, or the wrong org.

Verified against crewai 1.15.22 and 1.15.23 on 2026-10-01. Live-tested on CrewAI AMP and real LLMs on 2026-10-01. Run crewai version first; if the major/minor differs, re-verify the version-sensitive rows below with the ask-docs skill before trusting them.

1. Preflight - run these three every time

crewai org current        # which org will receive this deploy (machine-wide, see section 5)
uv lock && git status     # lockfile fresh, and you know what is uncommitted
crewai deploy validate    # local checks, no platform contact, exit 1 on blocking errors

crewai deploy create and crewai deploy push run the same validation automatically (skip with --skip-validate only when you know why). Every crewai deploy subcommand, including status --uuid, must run from the project root - elsewhere it stops with Error: pyproject.toml not found.

Exit codes are not a reliable signal in scripts or CI. crewai deploy validate exits 1 on errors, but create and push exit 0 when their built-in validation fails (Pre-deploy validation failed. Fix the issues above or re-run with --skip-validate.), and status / logs exit 0 on deployment_not_found. Gate CI on crewai deploy validate and check the command output, not only $?.

Validate imports your project, which creates crewai's local storage directory (on macOS ~/Library/Application Support/<pkg>/). Set CREWAI_STORAGE_DIR to a scratch path when running it in CI or on a shared machine.

2. Project shape the build expects

JSON-first crews (plain crewai create crew <name>, no --classic) keep crew.jsonc and agents/ at the project root instead of src/; crewai deploy validate checks that layout too.

Minimal flow main.py that passes validation:

from crewai.flow import Flow, listen, start
from pydantic import BaseModel


class ReportState(BaseModel):
    topic: str = "AI agents"
    summary: str = ""


class ReportFlow(Flow[ReportState]):
    @start()
    def gather(self):
        return f"notes on {self.state.topic}"

    @listen(gather)
    def summarize(self, notes):
        self.state.summary = notes.upper()
        return self.state.summary


def kickoff():
    ReportFlow().kickoff()


if __name__ == "__main__":
    kickoff()

Shape rules, each with the failure it prevents

Keep data files inside src/<pkg>/ and load them as package data, not with paths built from the repo root. Files under src/<pkg>/ go into the wheel the scaffold builds; files at the project root do not.

from importlib.resources import files

rules = files("research_crew").joinpath("data/rules.json").read_text()

When validate says @CrewBase not found or No Flow subclass found and the class is clearly there, the loader swallowed the real error. Reproduce it with a traceback:

# 1. Run the file outside its package, as the loader does (catches relative imports and import-time errors)
uv run python -c "import runpy; runpy.run_path('src/research_crew/crew.py', run_name='deploy_check')"   # flows: src/<pkg>/main.py
# 2. Build the object with no arguments (catches missing provider extras and Flow `__init__` arguments)
uv run python -c "from research_crew.crew import ResearchCrew; ResearchCrew().crew()"
uv run python -c "from acme_flow.main import ContentFlow; ContentFlow()"

See validate-checks.md for every check and code.

3. The three deploy paths and what each one uploads

push decides between a ZIP upload and a rebuild from your local origin, while AMP builds from the source the deployment was created with. If the two disagree, the push can succeed without shipping your changes:

Rules that follow from this:

• Never add or remove origin on a project after create. For a ZIP deployment, a correct push prints Preparing project ZIP... and Uploading project ZIP...; if those lines are missing, nothing new shipped.
• Git-based: AMP builds the commit on the remote, never your disk. Uncommitted edits and local commits that are not pushed are both skipped (the build ran the previous pushed version, status Crew is Online). git commit, git push, then crewai deploy push.
• ZIP-based: the ZIP holds files Git tracks plus untracked files that are not ignored, and always drops .env, .env.* (except .env.example / .env.sample), .git, .venv, caches, build/ and dist/. Add run outputs (report.md, output/) and scratch files to .gitignore, or they ship. Do not depend on root-level dotfiles at runtime: .gitignore and .env.example were in the ZIP but absent from the deployed project root.
• If the directory has no commits yet (the scaffold runs git init but does not commit), create/push commits everything not ignored as "Initial crew". If uv.lock is missing, validation's own uv run creates it before the upload (and create/push fall back to crewai install).
• Only the project root is packaged. Monorepo subfolders need a working directory set in the dashboard (the CLI create flow has no such option).
• push without --uuid finds the deployment by [project].name in the selected org. Deployment names are not unique in an org, so keep the name stable and prefer --uuid in scripts.
• push prints the deployment's full record, including its public URL and bearer token. Do not paste push output into tickets or keep it in CI logs. crewai deploy status prints only the name and status.
• crewai deploy logs fetches the deployment (build) log. When a deploy fails, read the real error there (ModuleNotFoundError ..., git_clone_failure): the status line only says Automation error, fix the code and deploy again., Provisioning Failed, try again. or Something went wrong, try again. Read run output from the kickoff result or the dashboard's Executions and Traces tabs.
• Crew is Online means the build finished and AMP's import test of your project passed. Runtime problems (a missing provider key, a bad model name) only show at kickoff - for example status FAILED with ValueError: ANTHROPIC_API_KEY is required. After every deploy, kick off the cheapest real input and read the output (see call-deployed-crew).

Full matrix, exclusions, and a script to list what a ZIP deploy would contain: what-gets-uploaded.md.

4. Environment variables

Env vars live on each deployment. Set provider keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, ...) and tool keys (SERPER_API_KEY, ...) as that deployment's environment variables in the AMP dashboard, and confirm them with a kickoff rather than assuming an org-level setting reaches your code.

What the CLI does with local .env:

Values are sent verbatim: MAX_CASES=3 # note arrives as 3 # note (python-dotenv locally strips the comment and gives 3, so local runs hide this), and QUOTED="abc" arrives with the quotes. Write .env with bare values and no inline comments.

To push code without touching a ZIP deployment's variables, run crewai deploy push from a tree with no .env (move it aside) and manage values in the dashboard. Never push with a partial .env. Ship a .env.example with <your-key> placeholders so the required names are documented.

Provider facts that bite on deploy:

• An agent with no llm= uses the OpenAI default (gpt-4.1-mini), so it needs OPENAI_API_KEY even in an Anthropic-only project. Set llm= on every agent.
• The native providers read their key from api_key= or the provider variable; a missing key fails at kickoff, not at deploy: ValueError: OPENAI_API_KEY is required, ValueError: ANTHROPIC_API_KEY is required.
• Non-OpenAI providers are extras: crewai[anthropic], crewai[google-genai], crewai[bedrock], crewai[azure-ai-inference]. Add them with uv add so they are in pyproject.toml and uv.lock; without the extra, validate (and therefore create / push) rejects the project.
• crewai deploy validate warns (env_vars_not_in_dotenv) when code calls os.getenv("SERPER_API_KEY") or similar for a known key that is missing from .env and your shell. It is a reminder to add the key to the deployment, not a blocker.

5. Org selection is machine-wide

The CLI keeps one selected org per OS user in ~/.config/crewai/settings.json, and every platform call (deploy create/push/status/logs/list/remove) carries that org. Switching in one terminal switches it for every shell and project on the machine.

• Run crewai org current before every create, push, or remove. (Bare crewai org prints nothing on 1.15.22-1.15.23 - use the current subcommand.)
• crewai org list shows the orgs you belong to; crewai org switch <org-id> changes the selection.
• crewai login replaces the selection with the account's current org as reported by the platform, so re-check with crewai org current after every login.
• deployment_not_found (Request to Enterprise API failed. Details: deployment_not_found) means the selected org has no deployment with that UUID or name. The usual causes: the CLI is pointed at a different org than the one that owns the deployment, or [project].name changed since create (lookup is by name). Check crewai org current first, then the name or --uuid.
• Scripts and CI that drive the CLI should switch org explicitly at the start and verify it, never rely on whatever was last selected.

6. Common mistakes

7. Deploy checklist

• crewai org current shows the intended org
• [tool.crewai] type matches the project (crew or flow)
• src/<pkg>/ matches [project].name; crew has @CrewBase + config/*.yaml, flow has a no-arg Flow subclass + kickoff()
• All project imports are absolute; nothing imported from outside the project root
• Provider extras (crewai[anthropic], ...) added with uv add; uv lock run after the last pyproject.toml edit
• uv.lock committed
• crewai deploy validate exits 0
• Git-based: changes committed and pushed, and AMP can access the repo. ZIP-based: no origin added since create; run outputs and scratch files ignored
• .env holds exactly this deployment's complete key set with bare values - or is moved aside so nothing is sent
• Provider and tool keys set as the deployment's env vars in the dashboard
• Push output showed Uploading project ZIP... (ZIP) - and was not pasted anywhere (it contains the bearer token)
• After Online, one cheap kickoff returned the expected output

References

• What gets uploaded - per-path matrix, ZIP include/exclude rules, env-var handling, and a script to list what a ZIP deploy would contain
• Validate checks - every crewai deploy validate check, its code and severity, and what it cannot catch
• Public docs: Prepare for Deployment, Deploy to AMP, Automations, Monorepo Deployments, CLI

For related skills:

• call-deployed-crew - /inputs, /kickoff, /status once the deployment is Online
• test-crewai-project - offline stub LLM so crewai run and validate work without keys
• check-crewai-api - current LLM model strings, default model, structured output
• build-flow - Flow state, routers, persistence
• connect-tools-and-mcp - which tool and MCP transports work on a hosted deployment
• ask-docs - query the live docs for anything not covered here