AgentCore RuntimeのAIエージェントをローカルで動作確認する方法を整理

はじめに

AgentCoreのドキュメントを確認していたところ、これまで把握していなかったローカル実行方法が記載されていたため、整理してみました。

結論

• AgentCore SDKを使ったアプリ動作確認をローカルで実施するには（観測範囲内では）下記3つの方法がある
  • agentcore devコマンドを使う
  • agentcore deploy --localコマンドを使う(agentcore launch --localと同義)
  • pythonやuv runコマンドでエントリーポイントのファイルを実行する

agentcore deployコマンドについては2025/11/27、bedrock-agentcore-starter-toolkitに実装された機能です。現時点では互換性がありますが、agentcore launchではなくagentcore deployを使う方向性になりそうです。

https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/v0.2.4/CHANGELOG.md#020---2025-11-27

ドキュメントに従って、agentcore createを実施

事前に必要なライブラリをインストールしておき、agentcore createで作成する（選択は全てデフォルト）。

pip install bedrock-agentcore strands-agents bedrock-agentcore-starter-toolkit

% agentcore create


----------------------------------------------------------------------------------------------------
🤖 AgentCore activated. Let's build your agent.
----------------------------------------------------------------------------------------------------

Where should we create your new agent?
./astroRed                                                                                                                             

How would you like to start?
A basic starter project (recommended)
 
What agent framework should we use?
Strands Agents SDK
 
Which model provider will power your agent?
Amazon Bedrock
 
What kind of memory should your agent have?
None
 
Initialize a new git repository?
Yes
 
Agent initializing...
    • Template copied.                                                                                                                 
    • Venv created and installed.                                                                                                      
    • Git initialized.                                                                                                                 
✓ Agent initialized.

----------------------------------------------------------------------------------------------------
You're ready to go! Happy building 🚀
Enter your project directory using cd astroRed
Run agentcore dev to start the dev server
Log into AWS with aws login
Add memory with agentcore configure
Launch with agentcore deploy
----------------------------------------------------------------------------------------------------

ローカルで確認する方法①：agentcore dev

手順としては、これが最も簡単だと思います。

% cd astroRed # createで作成した名前のディレクトリに移動
% agentcore dev
🚀 Starting development server with hot reloading
Agent: astroRed_Agent
Module: src.main:app
💡 Test your agent with: agentcore invoke --dev "Hello" in a new terminal window
ℹ️  This terminal window will be used to run the dev server 
Press Ctrl+C to stop the server

Server will be available at:
  • Localhost: http://localhost:8080/invocations
  • 127.0.0.1: http://127.0.0.1:8080/invocations
  • Local network: http://172.16.80.19:8080/invocations

warning: `VIRTUAL_ENV=/Users/harada/project/agentcore_developer_guide/agentcore-runtime-quickstart/.venv` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead
INFO:     Will watch for changes in these directories: ['/Users/harada/project/agentcore_developer_guide/agentcore-runtime-quickstart/astroRed']
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
INFO:     Started reloader process [72638] using StatReload
INFO:     Started server process [72647]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

呼び出しの確認は、別のターミナルを開いてagentcore invoke --devするだけ。

% agentcore invoke --dev "こんにちは"
✓ Response from dev server:
こんにちは！どのようにお手伝いできますか？

プログラミングの質問、コードの実行、ウェブ検索、データ分析など、様々なことをサポートできます。お気軽にお尋ねください！😊

ローカルで確認する方法②：agentcore deploy(launch) --local

別のディレクトリでコードを書きます。agentcore createコマンド作成時とは異なり、requirements.txtを用意する必要があったりしたので、別で作成しました。

作ったコード

main.py

from strands import Agent
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

@app.entrypoint
async def invoke(payload, context):
    agent = Agent()
    # Execute and format response
    stream = agent.stream_async(payload.get("prompt"))

    async for event in stream:
        # Handle Text parts of the response
        if "data" in event and isinstance(event["data"], str):
            yield event["data"]


app.run()

requirements.txtも作成しておきます。

requirements.txt

strands-agents
bedrock-agentcore

agentcore configureをした後、agentcore deploy --localを実行します。

% agentcore deploy --local
🏠 Launching Bedrock AgentCore (local mode)...
   • Build and run container locally
   • Requires Docker/Finch/Podman to be installed
   • Perfect for development and testing

Preparing local direct_code_deploy execution for agent 'main'
Using source directory: /Users/harada/project/agentcore_developer_guide/agentcore-runtime-quickstart/deploy
Using entrypoint: main.py
✓ Ready to run locally with uv run
Starting server at:
  • Localhost: http://localhost:8080
  • 127.0.0.1: http://127.0.0.1:8080
  • Local network: http://172.16.80.19:8080
Press Ctrl+C to stop

この状態で、別ターミナルからはcurlコマンドを実行します。

% curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "こんにちは"     
  }'
data: "こんにちは！"

data: "元"

data: "気ですか？何"

data: "かお手伝いできること"

data: "があれば、"

data: "お気軽にお聞"

data: "かせください。"

agentcore devとは違い、Runtimeのパス要件でもある/invocations宛にリクエストする点がポイントですね。

agentcore deploy --localの他に、agentcore launch --localも同じ動作となります。
ただし、agentcore launchはagentcoreのhelpコマンドを見たときに

│ deploy                      Deploy Bedrock AgentCore with three deployment modes (formerly 'launch').                               │

と記載があり、launchがdeployに置き換える想定だと思いました。今は互換でlaunchが使える状態のように見えます。

ローカルで確認する方法③：python main.py

②とほぼ同じです。こちらは、agentcore deploy --localと違って、リクエストを送るまでは何も表示がなかったです。

% python main.py

リクエストの内容は②と同じです。

% curl -X POST http://localhost:8080/invocations \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "こんにちは"
  }'
data: "こんにちは"

data: "！お元"

data: "気ですか？"

data: "何"

data: "か"

data: "お手"

data: "伝いできること"

data: "があれば、"

data: "お"

data: "気軽にお"

data: "声"

data: "かけください。"

まとめ

以前、agentcore launch --localで動作確認をしたことがあったのですが、ドキュメントを読んで別の方法がありそうだったのでまとめてみました。
個人的にはいずれAWS上にデプロイすることを考えればagentcore deploy --localを使うのが良いかなと思いました。ただし、bedrock-agentcore-starter-toolkitを使うことを想定していなければpython main.pyで確認することも検討する必要がありそうです。