deploy-to-amp

CrewAI AMP にデプロイする

プロジェクト構成のエラー、古いコードや環境変数、誤った組織によってデプロイを無駄にすることなく、クルーまたはフローを AMP にリリースできます。

2026-10-01 に crewai 1.15.22 および 1.15.23 で検証済みです。 2026-10-01 に CrewAI AMP と実際の LLM を使用してライブテスト済みです。 最初に crewai version を実行してください。メジャー／マイナーバージョンが異なる場合は、以下のバージョン依存の項目を信頼する前に、ask-docs スキルを使って再検証してください。

---

1. 事前チェック - 毎回この3つを実行してください

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 と crewai deploy push は、同じ検証を自動的に実行します（理由を把握している場合のみ、--skip-validate でスキップしてください）。status --uuid を含め、すべての crewai deploy サブコマンドはプロジェクトルートから実行する必要があります。別の場所から実行すると、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 を使い、$? だけでなくコマンドの出力を確認してください。

Validate はプロジェクトをインポートするため、crewai のローカルストレージディレクトリ（macOS では ~/Library/Application Support/<pkg>/）が作成されます。CI または共有マシンで実行する場合は、CREWAI_STORAGE_DIR に一時用のパスを設定してください。

---

2. ビルドで想定されるプロジェクト構成

要件	クルー（クラシック、crewai create crew <name> --classic）	フロー（crewai create flow <name>）
デプロイ名	[project].name の値をそのまま使用（スキャフォールドではアンダースコアが使われます：research_crew）	同じ
[tool.crewai] type	"crew"	"flow"
ロックファイル	ルートに uv.lock（または poetry.lock）を配置し、コミットする	同じ
パッケージディレクトリ	[project].name を正規化した <pkg> を使う src/<pkg>/（research-crew → research_crew）	同じ
エントリーコード	@CrewBase クラスを含む src/<pkg>/crew.py と、config/agents.yaml および config/tasks.yaml	引数なしで構築できる Flow サブクラスと kickoff() を含む src/<pkg>/main.py
スクリプト（スキャフォールド）	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 を主体とするクルー（--classic を指定しない通常の crewai create crew <name>）では、crew.jsonc と agents/ は src/ ではなくプロジェクトルートに配置されます。crewai deploy validate はこの構成もチェックします。

検証に合格する最小限のフロー main.py：

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.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={...}) を使って、実行ごとの値を state に渡します
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 自体が [tool.crewai] project_id がない場合に pyproject.toml に書き込むため、それも警告の原因になります	pyproject.toml を編集するたびに uv lock を再実行します。uv lock はすでに最新のロックファイルを変更しないため、警告が残る場合があります。uv lock --check が成功した場合は、touch uv.lock で警告を解消し、両方のファイルをコミットします
sys.path を使って隣接ディレクトリ（../shared_lib）からコードをインポート	ローカルでは validate に合格しますが、アップロードされるのはプロジェクトのルートディレクトリのみです。AMP のビルドは ModuleNotFoundError: No module named 'helpers' と Automation error, fix the code and deploy again. のステータスで失敗します	共有コードを src/<pkg>/ 内に移動するか、パッケージ依存関係として公開します
通常の crewai[tools] で anthropic/... モデルを使用	ローカルでは Anthropic native provider not available, to install: uv add "crewai[anthropic]" と表示されます。validate では @CrewBase not found / No Flow subclass found としか報告されないため、create と push はプロジェクトを拒否します	uv add "crewai[anthropic]" を実行して、追加の依存関係を pyproject.toml と uv.lock に反映します。

データファイルは src/<pkg>/ 内に置き、リポジトリのルートを基準にしたパスを組み立てるのではなく、パッケージデータとして読み込みます。src/<pkg>/ 内のファイルは scaffold がビルドする wheel に含まれますが、プロジェクトのルートにあるファイルは含まれません。

from importlib.resources import files

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

クラスが明らかに存在するのに validate が @CrewBase not found または No Flow subclass found と表示する場合、ローダーが本当のエラーを握りつぶしています。トレースバックを表示して再現します。

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

すべてのチェックとコードについては、validate-checks.md を参照してください。

---

3. 3 つのデプロイ方法と、それぞれがアップロードするもの

パス	AMP がビルドするコード	送信される環境変数
crewai deploy create、プロジェクトに origin リモートがある場合	AMP はリポジトリをクローンします。ローカルディスクからアップロードされるものはありません。AMP がリポジトリにアクセスするには、AMP 組織内の接続（Settings > Git Repositories：GitHub OAuth または Any Git Repository）を介した読み取り権限が必要です。ない場合でも、create は Deployment created successfully! と表示しますが、その後のビルドは git_clone_failure（could not read Username for 'https://github.com'）で失敗します	ローカルの .env にあるすべてのキー。「Press Enter to continue with N env vars: ...」というプロンプトが表示された後に送信されます（-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 Repository タブ）	接続から選択したリポジトリとブランチ（新しいコミット時の自動デプロイは任意）	ダッシュボードで入力した内容
ダッシュボード、ZIP アップロード	選択した ZIP	ダッシュボードで入力した内容

push は、ZIP のアップロードとローカルの origin からの再ビルドのどちらにするかを決定しますが、AMP はデプロイメントの作成時に指定されたソースからビルドします。両者が一致しない場合、変更が反映されないまま push が成功することがあります。

デプロイメントの作成方法	push 時のローカル状態	結果
ZIP	後から origin を追加	ZIP はアップロードされず、AMP は最後にアップロードされた ZIP を再ビルドします。作業ツリーのコードと .env の変更はデプロイされず、ステータスは Crew is Online に戻ります
Git	origin を削除	CLI は ZIP と .env をアップロードしますが、AMP は ZIP を無視してリポジトリを再度クローンします

これに基づくルールは次のとおりです。

• create の実行後に、プロジェクトの origin を追加したり削除したりしないでください。ZIP デプロイで正しくプッシュされると、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 にフォールバックします）。
• パッケージ化されるのはプロジェクトのルートだけです。モノレポのサブフォルダーを使う場合は、ダッシュボードで作業ディレクトリを設定する必要があります（CLI の create フローにはそのオプションがありません）。
• --uuid を指定しない push は、選択した組織内で [project].name によってデプロイメントを検索します。組織内ではデプロイメント名が一意ではないため、名前を固定し、スクリプトでは --uuid を優先してください。
• push は、パブリック URL とベアラー トークンを含むデプロイメントの完全なレコードを表示します。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. のいずれかしか表示されません。実行時の出力は、キックオフの結果、またはダッシュボードの Executions タブと Traces タブで確認してください。
• Crew is Online はビルドが完了し、AMP によるプロジェクトのインポートテストに合格したことを意味します。プロバイダーキーの欠落やモデル名の誤りなどの実行時の問題は、キックオフ時に初めて表示されます。たとえば、ステータスが FAILED となり、ValueError: ANTHROPIC_API_KEY is required と表示されます。デプロイのたびに、最も低コストの実入力でキックオフし、出力を確認してください（call-deployed-crew を参照）。

完全な一覧、除外対象、ZIP デプロイに含まれるファイルを表示するスクリプトについては、what-gets-uploaded.md を参照してください。

---

4. 環境変数

環境変数はデプロイごとに設定します。プロバイダーキー（OPENAI_API_KEY、ANTHROPIC_API_KEY、…）とツールキー（SERPER_API_KEY、…）を、AMP ダッシュボードでそのデプロイの環境変数として設定し、組織レベルの設定がコードに反映されると決めつけず、キックオフで設定を確認してください。

ローカルの .env に対して CLI が行う処理：

状況	送信される内容
create 時に .env がある	コメント以外の KEY=VALUE 行をすべて、フィルタリングせずに送信します。ファイル内の無関係なシークレットも含まれます
ZIP の push 時に .env がある（ローカルに origin がない）	同じ内容を送信し、デプロイの変数をこのセットで完全に置き換えます。.env にないキーはデプロイから削除されます
.env がない	環境変数フィールドは一切送信されません（Error: .env not found. と表示して処理を続けます）。デプロイには現在の変数が保持されます
ローカルに origin がある状態での push	環境変数は送信されません。値はダッシュボードで変更してください。Git ベースのデプロイには、create 時の値が保持されます。変更する場合はダッシュボードで編集してください

値はそのまま送信されます。MAX_CASES=3 # note は 3 # note として届きます（ローカルでは python-dotenv がコメントを取り除いて 3 にするため、ローカル実行時にはこの問題が表面化しません）。QUOTED="abc" は引用符も含めて届きます。.env には値だけを記述し、行末にコメントを付けないでください。

ZIP デプロイの環境変数を変更せずにコードをプッシュするには、.env のないディレクトリツリー（.env を別の場所に移動）から crewai deploy push を実行し、値はダッシュボードで管理してください。不完全な .env を使ってプッシュしないでください。必要なキー名を記載した <your-key> プレースホルダー入りの .env.example を用意してください。

デプロイ時に注意すべきプロバイダーの仕様：

• llm= を指定しないエージェントは OpenAI のデフォルト（gpt-4.1-mini）を使用するため、Anthropic のみを使用するプロジェクトでも OPENAI_API_KEY が必要です。すべてのエージェントに llm= を設定してください。
• ネイティブプロバイダーは api_key= またはプロバイダー変数からキーを読み取ります。キーがない場合、デプロイ時ではなくキックオフ時に失敗します：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 もできません。
• crewai deploy validate は、既知のキーが .env にもシェルにもない状態で、コードが os.getenv("SERPER_API_KEY") などを呼び出すと、env_vars_not_in_dotenv 警告を表示します。これはデプロイにキーを追加するためのリマインダーであり、処理を妨げるものではありません。

---

5. 組織の選択はマシン全体に適用されます

CLI は、OS ユーザーごとに選択中の組織を ~/.config/crewai/settings.json に保存し、プラットフォームへのすべての呼び出し（deploy create/push/status/logs/list/remove）にその組織を指定します。あるターミナルで切り替えると、そのマシン上のすべてのシェルとプロジェクトに反映されます。

• 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 がデプロイを所有する組織とは別の組織を指していること、または create 後に [project].name が変更されたことです（検索は名前で行われます）。まず crewai org current を確認し、次に名前または --uuid を確認してください。
• CLI を操作するスクリプトや CI では、最後に選択された組織に依存せず、開始時に明示的に組織を切り替えて確認してください。

---

6. よくある間違い

症状	原因	対処方法
デプロイはオンラインだが、古いコードが実行される	Git ベースのデプロイで変更がプッシュされていない。または、現在 origin があるツリーから ZIP デプロイをプッシュした（ZIP がアップロードされていない）	git push を実行してから、crewai deploy push を実行します。ZIP の場合は、追加された origin を削除して再度プッシュし、Uploading project ZIP... が表示されることを確認します
.env の編集後も、デプロイに古い環境変数の値が残る	ローカルの origin を使ったプッシュでは環境変数が送信されない	ダッシュボードで値を編集します
古い値がローテーション済みのキーを上書きする、無関係なシークレットがデプロイに表示される、またはキーが消える	ZIP の create／push ではローカルの .env にあるキーだけがそのままアップロードされ、デプロイ側のキー一式が置き換えられた	.env のないツリーからデプロイするか、このデプロイで使うキー一式がすべて含まれた .env のあるツリーからデプロイします
ステータスがオンラインなのに、キックオフが ValueError: ANTHROPIC_API_KEY is required で FAILED になる	デプロイにキーがない（不完全な .env を使った ZIP のプッシュで削除されたケースがよくあります）	ダッシュボードで設定するか、完全な .env を使ってプッシュします
git_clone_failure、could not read Username for 'https://github.com'	Git ベースのデプロイで、AMP が（プライベートな）リポジトリにアクセスできない	AMP 組織の Settings > Git Repositories を確認します。「Configure GitHub」／「Add Repository」しか表示されない場合は、何も接続されていません。このリポジトリへのアクセス権を持つ 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 を実行していないのに、2 回目の実行で Validate が成功した	Validate のインポートチェックで 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]" を実行します
キックオフ時に ValueError: OPENAI_API_KEY is required が発生する	llm= のないエージェント、または OpenAI モデルを使用しているが、デプロイにキーがない	llm= を明示的に設定し、デプロイの環境変数としてキーを追加します
プッシュ、ステータス確認、ログ確認時に deployment_not_found が発生する	選択している組織が間違っている、または [project].name がデプロイ名と一致しなくなった	crewai org current を実行してから crewai org switch <org-id> を実行するか、--uuid を渡します
いずれかの crewai deploy サブコマンドで Error: pyproject.toml not found. が発生する	プロジェクトディレクトリの外で実行している	プロジェクトルートへ cd します
モノレポのサブフォルダーからのデプロイで、プロジェクトが見つからない	デフォルトではリポジトリまたは ZIP のルートだけが使われる	ダッシュボードで作業ディレクトリを設定します

---

7. デプロイチェックリスト

• 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 ベースの場合：作成後に origin を追加していない。実行出力と一時ファイルは無視される
• .env にこのデプロイに必要なキー一式だけを値のみの形式で記述している。または、何も送信されないように別の場所へ移動している
• プロバイダーとツールのキーをダッシュボードでデプロイの環境変数として設定している
• プッシュの出力に Uploading project ZIP...（ZIP）が表示されている。また、その出力をどこにも貼り付けていない（ベアラートークンが含まれています）
• オンラインになった後、コストの低いキックオフを1回実行し、期待どおりの出力が返された

---

参考資料

• アップロードされる内容 - パスごとの一覧、ZIP の対象／除外ルール、環境変数の処理、ZIP デプロイに含まれる内容を一覧表示するスクリプト
• 検証チェック - crewai deploy validate の各チェックとそのコードおよび重大度、検出できない内容
• 公開ドキュメント：デプロイの準備、AMP へのデプロイ、自動化、モノレポのデプロイ、CLI

関連スキル：

• call-deployed-crew - デプロイがオンラインになった後の /inputs、/kickoff、/status
• test-crewai-project - キーなしで crewai run と検証を実行できる、オフライン用のスタブ LLM
• check-crewai-api - 現行の LLM モデル文字列、デフォルトモデル、構造化出力
• build-flow - Flow の状態、ルーター、永続化
• connect-tools-and-mcp - ホスト型デプロイで使用できるツールと MCP トランスポート
• ask-docs - ここで扱っていない内容を最新のドキュメントで検索