deploy-to-amp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy to CrewAI AMP

部署到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.

将crew或flow部署到AMP，避免因项目结构错误、代码过时、环境变量过期或组织错误导致的部署失败。

已于2026-10-01在crewai 1.15.22和1.15.23版本下验证通过。已于2026-10-01在CrewAI AMP和真实LLM上完成实际测试。请先运行

crewai version

；如果主版本/次版本不一致，请在参考以下版本相关内容前，使用

ask-docs

技能重新验证。

1. Preflight - run these three every time

1. 前置检查 - 每次部署前都执行这三步

bash

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.

bash

crewai org current        # 哪个组织将接收本次部署（全局生效，见第5节）
uv lock && git status     # 锁文件为最新，且你清楚未提交的内容
crewai deploy validate    # 本地检查，不访问平台，存在阻塞性错误时退出码为1

crewai deploy create

和

crewai deploy push

会自动执行相同的验证（仅当你明确原因时才使用

--skip-validate

跳过）。所有

crewai deploy

子命令（包括

status --uuid

）都必须在项目根目录下运行——在其他目录下执行会报错

Error: pyproject.toml not found.

。

在脚本或CI中，退出码不是可靠的判断依据。

crewai deploy validate

出错时退出码为1，但

create

和

push

在内置验证失败时退出码仍为0（提示

Pre-deploy validation failed. Fix the issues above or re-run with --skip-validate.

），而

status

logs

在遇到

deployment_not_found

时退出码也为0。CI中请以

crewai deploy validate

的输出作为判断依据，而不仅仅是

$?

退出码。

验证过程会导入你的项目，这会创建crewai的本地存储目录（在macOS上为

~/Library/Application Support/<pkg>/

）。在CI或共享机器上运行时，请将

CREWAI_STORAGE_DIR

设置为临时路径。

2. Project shape the build expects

2. 构建所需的项目结构

Requirement	Crew (classic, `crewai create crew <name> --classic` )	Flow ( `crewai create flow <name>` )
Deployment name	`[project].name` , verbatim (the scaffold writes underscores: `research_crew` )	same
`[tool.crewai] type`	`"crew"`	`"flow"`
Lockfile	`uv.lock` (or `poetry.lock` ) at the root, committed	same
Package dir	`src/<pkg>/` , where `<pkg>` is `[project].name` normalized ( `research-crew` -> `research_crew` )	same
Entry code	`src/<pkg>/crew.py` with an `@CrewBase` class, plus `config/agents.yaml` and `config/tasks.yaml`	`src/<pkg>/main.py` with a `Flow` subclass that can be built with no arguments, plus `kickoff()`
Scripts (scaffold)	`run_crew = "<pkg>.main:run"`	`kickoff = "<pkg>.main:kickoff"`
Imports	absolute: `from research_crew.tools.x import Y`	absolute: `from acme_flow.crews.content_crew.content_crew import ContentCrew`

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:

python

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

要求	Crew（经典版， `crewai create crew <name> --classic` ）	Flow（ `crewai create flow <name>` ）
部署名称	`[project].name` ，原样使用（脚手架生成的名称带下划线： `research_crew` ）	相同
`[tool.crewai] type`	`"crew"`	`"flow"`
锁文件	根目录下的 `uv.lock` （或 `poetry.lock` ），已提交到版本库	相同
包目录	`src/<pkg>/` ，其中 `<pkg>` 是规范化后的 `[project].name` （ `research-crew` -> `research_crew` ）	相同
入口代码	`src/<pkg>/crew.py` 包含一个 `@CrewBase` 类，以及 `config/agents.yaml` 和 `config/tasks.yaml`	`src/<pkg>/main.py` 包含一个无需参数即可构建的 `Flow` 子类，以及 `kickoff()` 函数
脚本（脚手架生成）	`run_crew = "<pkg>.main:run"`	`kickoff = "<pkg>.main:kickoff"`
导入方式	绝对导入： `from research_crew.tools.x import Y`	绝对导入： `from acme_flow.crews.content_crew.content_crew import ContentCrew`

JSON优先的crew项目（直接执行

crewai create crew <name>

，不加

--classic

）会将

crew.jsonc

和

agents/

放在项目根目录而非

src/

下；

crewai deploy validate

也会检查这种布局。

可通过验证的最简Flow

main.py

示例：

python

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

结构规则及对应的错误规避

Bad	What happens	Good
`from .stub_tools import X` in `crew.py` / `main.py`	`crewai run` works, but `crewai deploy validate` fails with `Crew class annotated with @CrewBase not found` (the loader runs the file outside its package, and the real `attempted relative import` error is hidden). Pushed with `--skip-validate` , the AMP build fails the same way: `ImportError: attempted relative import with no known parent package`	`from research_crew.stub_tools import X`
Only a `def kickoff():` in `main.py` , no Flow class	`No Flow subclass found in the module`	Define `class MyFlow(Flow[...])` and call it from `kickoff()`
Flow `__init__(self, tenant: str)`	`No Flow subclass found` - the class must build with no arguments	Pass per-run values through `kickoff(inputs={...})` into state
`type = "flow"` on a crew project	`No Flow subclass found`	`type = "crew"`
`type = "crew"` on a flow project	`Cannot find src/<pkg>/crew.py` , `Cannot find src/<pkg>/config`	`type = "flow"`
Renamed `src/research_crew/` to `src/researchcrew/`	`Cannot find src/research_crew/` and `Hatchling cannot determine which files to ship`	Keep the dir equal to the normalized `[project].name`
`uv.lock` missing	`missing_lockfile` error	`uv lock` , then `git add uv.lock`
Edited `pyproject.toml` after locking	`stale_lockfile` warning (does not block) - deployed deps may differ from local. The check compares file times, and the CLI itself writes `[tool.crewai] project_id` into `pyproject.toml` when it is missing, which also triggers it	Re-run `uv lock` after every `pyproject.toml` edit. `uv lock` leaves an already-current lockfile untouched, so the warning can persist; if `uv lock --check` passes, `touch uv.lock` clears it and commit both
Importing code from a sibling dir ( `../shared_lib` ) via `sys.path`	Validate passes locally, but only the project root is uploaded: the AMP build fails with `ModuleNotFoundError: No module named 'helpers'` and status `Automation error, fix the code and deploy again.`	Move shared code inside `src/<pkg>/` or publish it as a package dependency
`anthropic/...` model with plain `crewai[tools]`	Locally: `Anthropic native provider not available, to install: uv add "crewai[anthropic]"` ; validate reports it only as `@CrewBase not found` / `No Flow subclass found` , so `create` and `push` refuse the project	`uv add "crewai[anthropic]"` so the extra lands in `pyproject.toml` and `uv.lock` .

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.

python

from importlib.resources import files

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

When validate says

@CrewBase not found

No Flow subclass found

and the class is clearly there, the loader swallowed the real error. Reproduce it with a traceback:

bash

undefined

错误做法	导致的问题	正确做法
在 `crew.py` / `main.py` 中使用 `from .stub_tools import X`	`crewai run` 可以正常运行，但 `crewai deploy validate` 会报错 `Crew class annotated with @CrewBase not found` （加载器在包外运行该文件，真实的 `attempted relative import` 错误被隐藏）。如果使用 `--skip-validate` 推送，AMP构建会以同样的方式失败： `ImportError: attempted relative import with no known parent package`	`from research_crew.stub_tools import X`
`main.py` 中只有 `def kickoff():` 函数，没有Flow类	`No Flow subclass found in the module`	定义 `class MyFlow(Flow[...])` 并在 `kickoff()` 中调用它
Flow的 `__init__(self, tenant: str)` 带参数	`No Flow subclass found` - 类必须支持无参构建	通过 `kickoff(inputs={...})` 将每次运行的参数传入状态
crew项目设置 `type = "flow"`	`No Flow subclass found`	`type = "crew"`
flow项目设置 `type = "crew"`	`Cannot find src/<pkg>/crew.py` 、 `Cannot find src/<pkg>/config`	`type = "flow"`
将 `src/research_crew/` 重命名为 `src/researchcrew/`	`Cannot find src/research_crew/` 以及 `Hatchling cannot determine which files to ship`	保持目录名与规范化后的 `[project].name` 一致
缺少 `uv.lock`	报 `missing_lockfile` 错误	执行 `uv lock` ，然后 `git add uv.lock`
锁定后编辑了 `pyproject.toml`	出现 `stale_lockfile` 警告（不阻塞部署）- 部署的依赖可能与本地不一致。该检查比较文件修改时间，而CLI本身会在 `pyproject.toml` 缺少 `[tool.crewai] project_id` 时写入该字段，这也会触发警告	每次编辑 `pyproject.toml` 后重新执行 `uv lock` 。如果锁文件已经是最新的， `uv lock` 不会修改它，因此警告可能持续存在；如果 `uv lock --check` 通过，执行 `touch uv.lock` 即可清除警告，然后提交两个文件
通过 `sys.path` 导入兄弟目录（ `../shared_lib` ）的代码	本地验证通过，但只有项目根目录会被上传：AMP构建会报错 `ModuleNotFoundError: No module named 'helpers'` ，状态显示为 `Automation error, fix the code and deploy again.`	将共享代码移到 `src/<pkg>/` 内，或将其发布为包依赖
使用 `anthropic/...` 模型但只安装了 `crewai[tools]`	本地提示： `Anthropic native provider not available, to install: uv add "crewai[anthropic]"` ；验证仅会报 `@CrewBase not found` / `No Flow subclass found` ，因此 `create` 和 `push` 会拒绝该项目	执行 `uv add "crewai[anthropic]"` ，使该额外依赖进入 `pyproject.toml` 和 `uv.lock`

请将数据文件放在

src/<pkg>/

内，并作为包数据加载，不要使用从仓库根目录拼接的路径。

src/<pkg>/

下的文件会被包含在脚手架构建的wheel包中；项目根目录下的文件不会。

python

from importlib.resources import files

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

当验证提示

@CrewBase not found

或

No Flow subclass found

，但类明明存在时，说明加载器吞掉了真实错误。可以通过以下命令复现错误并查看完整回溯：

bash

undefined

1. Run the file outside its package, as the loader does (catches relative imports and import-time errors)

1. 像加载器一样在包外运行文件（可捕获相对导入和导入时错误）

uv run python -c "import runpy; runpy.run_path('src/research_crew/crew.py', run_name='deploy_check')" # flows: src/<pkg>/main.py

uv run python -c "import runpy; runpy.run_path('src/research_crew/crew.py', run_name='deploy_check')" # flow项目对应: src/<pkg>/main.py

2. Build the object with no arguments (catches missing provider extras and Flow

__init__

arguments)

2. 无参构建对象（可捕获缺少提供商额外依赖和Flow

__init__

参数问题）

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](references/validate-checks.md) for every check and code.

---

uv run python -c "from research_crew.crew import ResearchCrew; ResearchCrew().crew()" uv run python -c "from acme_flow.main import ContentFlow; ContentFlow()"


所有检查项及错误码请参考 [validate-checks.md](references/validate-checks.md)。

---

3. The three deploy paths and what each one uploads

3. 三种部署路径及各自上传的内容

Path	Code AMP builds	Env vars sent
`crewai deploy create` , project has an `origin` remote	AMP clones the repo; nothing is uploaded from your disk. AMP needs read access to the repo through a connection in the AMP org (Settings > Git Repositories: GitHub OAuth or Any Git Repository) - otherwise create still prints `Deployment created successfully!` and the build then fails with `git_clone_failure` ( `could not read Username for 'https://github.com'` )	Every key in local `.env` , after a "Press Enter to continue with N env vars: ..." prompt ( `-y` skips it)
`crewai deploy create` , no `origin` remote	A ZIP of your working tree (prints `No origin remote found. Deploying from a ZIP upload instead.` )	Every key in local `.env` , after the same prompt
`crewai deploy push` , local `origin` present	Nothing is uploaded; AMP rebuilds from the deployment's own source	None
`crewai deploy push` , no local `origin`	A fresh ZIP of your working tree, including uncommitted edits	Every key in local `.env` , with no prompt - and it replaces the deployment's variables (see section 4)
Dashboard, Deploy from Code (GitHub OAuth or Git Repository tab)	The repository and branch you pick from a connection (optional auto-deploy on new commits)	What you enter in the dashboard
Dashboard, ZIP upload	The ZIP you choose	What you enter in the dashboard

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:

Deployment created as	Local state at `push`	Result
ZIP	`origin` added later	No ZIP uploaded; AMP rebuilt the last uploaded ZIP. Working-tree code and `.env` changes were not deployed, status went back to `Crew is Online`
Git	`origin` removed	CLI uploaded a ZIP and `.env` ; AMP ignored the ZIP and cloned the repository again

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.

部署路径	AMP构建的代码来源	发送的环境变量
`crewai deploy create` ，项目有 `origin` 远程仓库	AMP克隆仓库；不会从你的磁盘上传任何内容。AMP需要通过AMP组织中的连接获得仓库读取权限（设置 > Git仓库：GitHub OAuth或任意Git仓库）——否则create仍会打印 `Deployment created successfully!` ，但构建随后会失败并报 `git_clone_failure` （ `could not read Username for 'https://github.com'` ）	本地 `.env` 中的所有键，会先提示 “按回车继续，共N个环境变量：...”（使用 `-y` 可跳过提示）
`crewai deploy create` ，没有 `origin` 远程仓库	你的工作目录的ZIP包（会打印 `No origin remote found. Deploying from a ZIP upload instead.` ）	本地 `.env` 中的所有键，同样会有上述提示
`crewai deploy push` ，本地存在 `origin`	不上传任何内容；AMP从部署自身的源重新构建	无
`crewai deploy push` ，本地没有 `origin`	你的工作目录的全新ZIP包，包含未提交的修改	本地 `.env` 中的所有键，无提示——并且会覆盖部署的现有变量（见第4节）
仪表盘，从代码部署（GitHub OAuth或Git仓库标签页）	你从连接中选择的仓库和分支（可选新提交自动部署）	你在仪表盘中输入的内容
仪表盘，ZIP上传	你选择的ZIP文件	你在仪表盘中输入的内容

push

会根据你本地的

origin

存在与否，选择是上传ZIP还是重新构建，但AMP是根据部署创建时的源来构建的。如果两者不一致，push可能成功但实际上没有部署你的修改：

部署创建方式	`push` 时的本地状态	结果
ZIP	之后添加了 `origin`	不会上传ZIP；AMP会重建上次上传的ZIP。工作目录的代码和 `.env` 修改都不会被部署，状态会回到 `Crew is Online`
Git	移除了 `origin`	CLI上传了ZIP和 `.env` ；AMP会忽略ZIP并再次克隆仓库

由此得出以下规则：

项目create之后，不要添加或移除
```
origin
```
。对于ZIP部署，成功的push会打印
```
Preparing project ZIP...
```
和
```
Uploading project ZIP...
```
；如果没有这些行，说明没有部署新内容。
基于Git的部署：AMP构建的是远程仓库上的提交，永远不是你本地磁盘上的内容。未提交的修改和未推送的本地提交都会被忽略（构建运行的是上一次推送的版本，状态为
```
Crew is Online
```
）。请先执行
```
git commit
```
、
```
git push
```
，再执行
```
crewai deploy push
```
。
基于ZIP的部署：ZIP包含Git跟踪的文件，加上未被忽略的未跟踪文件，且始终会排除
```
.env
```
、
```
.env.*
```
（除了
```
.env.example
```
/
```
.env.sample
```
）、
```
.git
```
、
```
.venv
```
、缓存、
```
build/
```
和
```
dist/
```
。请将运行输出（
```
report.md
```
、
```
output/
```
）和临时文件添加到
```
.gitignore
```
，否则它们会被一起部署。不要在运行时依赖根目录下的点文件：
```
.gitignore
```
和
```
.env.example
```
会在ZIP中，但部署后的项目根目录中没有这些文件。
如果目录还没有任何提交（脚手架会执行
```
git init
```
但不会提交），
```
create
```
/
```
push
```
会将所有未被忽略的内容提交为 “Initial crew”。如果缺少
```
uv.lock
```
，验证过程中的
```
uv run
```
会在上传前创建它（并且
```
create
```
/
```
push
```
会回退到
```
crewai install
```
）。
只有项目根目录会被打包。monorepo的子文件夹需要在仪表盘中设置工作目录（CLI的create流程没有该选项）。
不带
```
--uuid
```
的
```
push
```
会通过所选组织中的
```
[project].name
```
查找部署。组织内的部署名称不是唯一的，因此请保持名称稳定，在脚本中优先使用
```
--uuid
```
。
```
push
```
会打印部署的完整信息，包括其公开URL和Bearer Token。请不要将push输出粘贴到工单中，也不要保留在CI日志中。
```
crewai deploy status
```
仅打印名称和状态。
```
crewai deploy logs
```
会获取部署（构建）日志。当部署失败时，请在日志中查看真实错误（
```
ModuleNotFoundError ...
```
、
```
git_clone_failure
```
）：状态行只会显示
```
Automation error, fix the code and deploy again.
```
、
```
Provisioning Failed, try again.
```
或
```
Something went wrong, try again.
```
。运行输出请查看kickoff结果或仪表盘的执行与追踪标签页。
```
Crew is Online
```
表示构建已完成，且AMP对你的项目的导入测试通过了。运行时问题（缺少提供商密钥、模型名称错误）只会在kickoff时显现——例如状态为
```
FAILED
```
并提示
```
ValueError: ANTHROPIC_API_KEY is required
```
。每次部署后，请用成本最低的真实输入执行一次kickoff并查看输出（参考
```
call-deployed-crew
```
）。

完整的矩阵、排除规则，以及列出ZIP部署包含内容的脚本，请参考 what-gets-uploaded.md。

4. Environment variables

4. 环境变量

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

Situation	What gets sent
`.env` present on `create`	Every non-comment `KEY=VALUE` line, unfiltered - including unrelated secrets in the file
`.env` present on a ZIP `push` (no local `origin` )	The same, and the deployment's variables are replaced by exactly this set: a key missing from `.env` is deleted from the deployment
`.env` absent	No env fields at all (it prints `Error: .env not found.` and carries on); the deployment keeps its current variables
`push` with a local `origin`	Never sends env vars - change values in the dashboard. A Git-based deployment keeps the values from its `create` until you edit them there

Values are sent verbatim:

MAX_CASES=3  # note

arrives as

3  # note

(python-dotenv locally strips the comment and gives

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

环境变量隶属于每个部署。请在AMP仪表盘的部署环境变量中设置提供商密钥（

OPENAI_API_KEY

、

ANTHROPIC_API_KEY

等）和工具密钥（

SERPER_API_KEY

等），并通过kickoff验证，不要假设组织级别的设置会生效。

CLI对本地

.env

的处理方式：

场景	发送的内容
`create` 时存在 `.env`	所有非注释的 `KEY=VALUE` 行，不做过滤——包括文件中不相关的密钥
ZIP方式的 `push` （本地无 `origin` ）时存在 `.env`	同样发送所有内容，且部署的变量会被完全替换为该集合： `.env` 中缺失的键会从部署中删除
不存在 `.env`	完全不发送环境变量（会打印 `Error: .env not found.` 然后继续执行）；部署保留其当前变量
本地有 `origin` 的 `push`	永远不发送环境变量——请在仪表盘中修改值。基于Git的部署会保留create时的变量，直到你在仪表盘中编辑

值会原样发送：

MAX_CASES=3  # note

会被发送为

3  # note

（本地的python-dotenv会去除注释，得到

，因此本地运行不会暴露这个问题），而

QUOTED="abc"

会连同引号一起发送。请在

.env

中使用纯值，不要加行内注释。

要在不修改ZIP部署变量的情况下推送代码，请在没有

.env

的目录下运行

crewai deploy push

（把.env移走），并在仪表盘中管理变量。永远不要用不完整的

.env

推送。请提供带有

<your-key>

占位符的

.env.example

，以记录所需的变量名。

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.

没有设置
```
llm=
```
的agent会使用OpenAI默认模型（
```
gpt-4.1-mini
```
），因此即使是纯Anthropic的项目也需要
```
OPENAI_API_KEY
```
。请为每个agent都设置
```
llm=
```
。
原生提供商会从
```
api_key=
```
参数或对应的提供商环境变量读取密钥；密钥缺失会在kickoff时失败，而不是部署时：
```
ValueError: OPENAI_API_KEY is required
```
、
```
ValueError: ANTHROPIC_API_KEY is required
```
。
非OpenAI提供商属于额外依赖：
```
crewai[anthropic]
```
、
```
crewai[google-genai]
```
、
```
crewai[bedrock]
```
、
```
crewai[azure-ai-inference]
```
。请使用
```
uv add
```
添加它们，确保它们在
```
pyproject.toml
```
和
```
uv.lock
```
中；没有这些额外依赖的话，验证（以及
```
create
```
/
```
push
```
）会拒绝该项目。
当代码调用
```
os.getenv("SERPER_API_KEY")
```
等已知密钥，但
```
.env
```
和你的shell环境中都没有该密钥时，
```
crewai deploy validate
```
会发出警告（
```
env_vars_not_in_dotenv
```
）。这只是提醒你需要将该密钥添加到部署中，不会阻塞部署。

6. Common mistakes

5. 组织选择是全局生效的

Symptom	Cause	Fix
Deploy is Online but runs old code	Git-based deployment and the change was not pushed; or a ZIP deployment pushed from a tree that now has an `origin` (no ZIP was uploaded)	`git push` , then `crewai deploy push` ; for ZIP, remove the added `origin` and push again - check for `Uploading project ZIP...`
Deploy keeps old env values after editing `.env`	Push with a local `origin` never sends env vars	Edit the values in the dashboard
A stale value overwrites a rotated key, an unrelated secret appears on the deployment, or a key vanished	ZIP `create` / `push` uploaded exactly the keys in local `.env` , replacing the deployment's set	Deploy from a tree without `.env` , or with the complete set of this deployment's keys
Kickoff `FAILED` with `ValueError: ANTHROPIC_API_KEY is required` although status is Online	Key missing on the deployment (often removed by a ZIP push with a partial `.env` )	Set it in the dashboard, or push with a complete `.env`
`git_clone_failure` , `could not read Username for 'https://github.com'`	Git-based deployment and AMP has no access to the (private) repo	Check Settings > Git Repositories in the AMP org: if it only offers "Configure GitHub" / "Add Repository", nothing is connected. Connect GitHub (or add the repo) with access to this repository, then push again: a deployment created from the CLI picks up the connection on its next `push` , with no dashboard step and no need to recreate it. Until then every `push` re-runs the same clone and fails the same way. Or deploy from ZIP (a project with no `origin` )
`Automation error, fix the code and deploy again.`	The AMP build's import test failed	`crewai deploy logs` shows the real traceback
`MAX_CASES` parses as `3 # note`	Inline comment in `.env` sent verbatim	Bare values only
`Expected to find at least one of these files: uv.lock or poetry.lock`	No lockfile	`uv lock` , commit it
Validate passed on the second run although you never ran `uv lock`	Validate's import check ran `uv run` , which created `uv.lock`	Commit the new `uv.lock` (a Git-based build only sees committed files)
`Crew class annotated with @CrewBase not found` with the decorator present	Relative import, missing provider extra, or any import error in `crew.py`	Run the diagnostic commands in section 2 to see the real error
`No Flow subclass found in the module`	No Flow class, Flow needs constructor args, or `type = "flow"` on a crew	Add a no-arg Flow subclass; fix `type`
`ImportError` on AMP for code that works locally	Imports from outside the project root	Move it under `src/<pkg>/` or make it a dependency
`Anthropic native provider not available`	Extra missing from `pyproject.toml`	`uv add "crewai[anthropic]"`
`ValueError: OPENAI_API_KEY is required` at kickoff	Agent without `llm=` or OpenAI model and no key on the deployment	Set `llm=` explicitly; add the key as a deployment env var
`deployment_not_found` on push, status or logs	Wrong org selected, or `[project].name` no longer matches the deployment	`crewai org current` , then `crewai org switch <org-id>` ; or pass `--uuid`
`Error: pyproject.toml not found.` from any `crewai deploy` subcommand	Run outside a project dir	`cd` to the project root
Deployment from a monorepo subfolder fails to find the project	Only the repo or ZIP root is used by default	Set the working directory in the dashboard

CLI会在

~/.config/crewai/settings.json

中为每个操作系统用户保存一个选中的组织，所有平台调用（

deploy create/push/status/logs/list/remove

）都会携带该组织。在一个终端中切换组织，会影响机器上所有的shell和项目。

每次create、push或remove前都请运行
```
crewai org current
```
。（在1.15.22-1.15.23版本中，直接执行
```
crewai org
```
不会输出任何内容——请使用
```
current
```
子命令。）
```
crewai org list
```
会显示你所属的所有组织；
```
crewai org switch <org-id>
```
会切换选中的组织。
```
crewai login
```
会将选中的组织替换为平台返回的账户当前组织，因此每次登录后都请用
```
crewai org current
```
重新检查。
```
deployment_not_found
```
（
```
Request to Enterprise API failed. Details: deployment_not_found
```
）表示所选组织中没有对应UUID或名称的部署。常见原因：CLI指向的组织与部署所属的组织不同，或者
```
[project].name
```
自create后发生了变化（查找是按名称进行的）。请先检查
```
crewai org current
```
，再检查名称或
```
--uuid
```
。
脚本和CI中驱动CLI的操作应在开头明确切换组织并验证，永远不要依赖上次选中的组织。

7. Deploy checklist

6. 常见错误

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

症状	原因	解决方法
部署显示Online但运行的是旧代码	基于Git的部署，修改未推送；或者ZIP部署的推送时目录已经有了 `origin` （没有上传ZIP）	执行 `git push` ，然后 `crewai deploy push` ；对于ZIP部署，移除新增的 `origin` 后重新推送——检查是否有 `Uploading project ZIP...` 输出
编辑 `.env` 后部署仍保留旧的环境变量值	本地有 `origin` 的push永远不会发送环境变量	在仪表盘中修改变量值
过期的值覆盖了轮换后的密钥、部署上出现了不相关的密钥，或者某个密钥消失了	ZIP方式的 `create` / `push` 原样上传了本地 `.env` 中的所有密钥，替换了部署的变量集	在没有 `.env` 的目录下部署，或者使用包含该部署所有密钥的完整 `.env` 文件
尽管状态为Online，kickoff仍 `FAILED` 并提示 `ValueError: ANTHROPIC_API_KEY is required`	部署上缺少该密钥（通常是因为使用不完整的 `.env` 进行ZIP推送导致被删除）	在仪表盘中设置，或者使用完整的 `.env` 推送
`git_clone_failure` ， `could not read Username for 'https://github.com'`	基于Git的部署，AMP没有（私有）仓库的访问权限	检查AMP组织中的设置 > Git仓库：如果只有“配置GitHub”/“添加仓库”选项，说明没有连接任何仓库。连接GitHub（或添加仓库）并授予该仓库的访问权限，然后重新推送：从CLI创建的部署会在下次 `push` 时自动使用该连接，无需仪表盘操作，也无需重新创建部署。在此之前，每次 `push` 都会执行同样的克隆操作并以同样的方式失败。或者使用ZIP方式部署（没有 `origin` 的项目）
`Automation error, fix the code and deploy again.`	AMP构建的导入测试失败	通过 `crewai deploy logs` 查看真实的回溯信息
`MAX_CASES` 被解析为 `3 # note`	`.env` 中的行内注释被原样发送	仅使用纯值，不加注释
`Expected to find at least one of these files: uv.lock or poetry.lock`	没有锁文件	执行 `uv lock` 并提交
你从未运行过 `uv lock` ，但第二次验证就通过了	验证的导入检查执行了 `uv run` ，它自动创建了 `uv.lock`	提交新生成的 `uv.lock` （基于Git的构建只能看到已提交的文件）
明明有装饰器，却报 `Crew class annotated with @CrewBase not found`	相对导入、缺少提供商额外依赖，或者 `crew.py` 中存在其他导入错误	运行第2节中的诊断命令查看真实错误
`No Flow subclass found in the module`	没有Flow类、Flow需要构造参数，或者crew项目设置了 `type = "flow"`	添加无参的Flow子类；修正 `type`
本地运行正常，但AMP上出现 `ImportError`	导入了项目根目录外的代码	将其移到 `src/<pkg>/` 下，或将其设为依赖
`Anthropic native provider not available`	`pyproject.toml` 中缺少额外依赖	执行 `uv add "crewai[anthropic]"`
kickoff时报 `ValueError: OPENAI_API_KEY is required`	agent没有设置 `llm=` ，或者使用了OpenAI模型但部署上没有密钥	显式设置 `llm=` ；将该密钥添加为部署环境变量
push、status或logs时报 `deployment_not_found`	所选组织错误，或者 `[project].name` 与部署不再匹配	执行 `crewai org current` ，然后 `crewai org switch <org-id>` ；或者传入 `--uuid`
任何 `crewai deploy` 子命令都报 `Error: pyproject.toml not found.`	在项目目录外运行	`cd` 到项目根目录
从monorepo子文件夹部署时找不到项目	默认只使用仓库或ZIP的根目录	在仪表盘中设置工作目录

References

7. 部署检查清单

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

```
crewai org current
```
显示的是目标组织
```
[tool.crewai] type
```
与项目类型匹配（crew或flow）

src/<pkg>/

与

[project].name

匹配；crew有

@CrewBase

config/*.yaml

，flow有无参的

Flow

子类 +

kickoff()

所有项目导入都是绝对导入；没有导入项目根目录外的内容
提供商额外依赖（
```
crewai[anthropic]
```
等）已通过
```
uv add
```
添加；最后一次编辑
```
pyproject.toml
```
后已执行
```
uv lock
```
```
uv.lock
```
已提交
```
crewai deploy validate
```
退出码为0
基于Git的部署：修改已提交并推送，且AMP可以访问仓库。基于ZIP的部署：create后没有添加过
```
origin
```
；运行输出和临时文件已被忽略
```
.env
```
恰好包含该部署的完整密钥集，且为纯值——或者已被移走，不会发送任何内容
提供商和工具密钥已在仪表盘中设置为部署环境变量
Push输出显示了
```
Uploading project ZIP...
```
（ZIP方式）——且没有被粘贴到任何地方（包含Bearer Token）
部署变为Online后，执行了一次低成本的kickoff并返回了预期输出

—

参考资料

—

上传内容说明 - 各部署路径的矩阵、ZIP包含/排除规则、环境变量处理，以及列出ZIP部署包含内容的脚本
验证检查项 -
```
crewai deploy validate
```
的所有检查项、错误码和严重程度，以及无法捕获的问题
官方文档：部署准备、部署到AMP、自动化、Monorepo部署、CLI

deploy-to-amp

Original

Translation

Deploy to CrewAI AMP

部署到CrewAI AMP

1. Preflight - run these three every time

1. 前置检查 - 每次部署前都执行这三步

2. Project shape the build expects

2. 构建所需的项目结构

Shape rules, each with the failure it prevents

结构规则及对应的错误规避

1. Run the file outside its package, as the loader does (catches relative imports and import-time errors)

1. 像加载器一样在包外运行文件（可捕获相对导入和导入时错误）

2. Build the object with no arguments (catches missing provider extras and Flow
`init`
arguments)

2. 无参构建对象（可捕获缺少提供商额外依赖和Flow
`init`
参数问题）

3. The three deploy paths and what each one uploads

3. 三种部署路径及各自上传的内容

4. Environment variables

4. 环境变量

5. Org selection is machine-wide

部署时容易踩坑的提供商相关事实：

6. Common mistakes

5. 组织选择是全局生效的

7. Deploy checklist

6. 常见错误

References

7. 部署检查清单

参考资料