AgentCore CLI を使用せずに開始する

AgentCore CLI を使用せずに AgentCore ランタイムエージェントを作成できます。代わりに、コマンドラインツールを組み合わせてエージェントを設定して AgentCore ランタイムにデプロイできます。

このチュートリアルでは、AgentCore CLI を使用せずにカスタムエージェントをデプロイする方法を示します。カスタムエージェントは、AgentCore Python SDK を使用せずに構築されたエージェントです。このチュートリアルでは、カスタムエージェントは FastAPI と Docker を使用して構築されています。カスタムエージェントは AgentCore ランタイム要件 に従います。つまり、エージェントは /invocations POST エンドポイントと /ping GET エンドポイントを公開し、Docker コンテナにパッケージ化する必要があります。Amazon Bedrock AgentCore では、デプロイされたすべてのエージェントに ARM64 アーキテクチャが必要です。

クイックスタートのセットアップ

エージェントのオブザーバビリティを有効にする

Amazon Bedrock AgentCore オブザーバビリティは、AgentCore ランタイムでホストするエージェントをトレース、デバッグ、モニタリングするのに役立ちます。エージェントを監視するには、まず AgentCore オブザーバビリティの有効化の手順に従って CloudWatch トランザクション検索を有効にします。

uv をインストールする

この例では、 uvパッケージマネージャーを使用しますが、任意の Python ユーティリティまたはパッケージマネージャーを使用できます。macOS uvに をインストールするには:

curl -LsSf https://astral.sh/uv/install.sh | sh

他のプラットフォームのインストール手順については、「uv ドキュメント」を参照してください。

エージェントプロジェクトを作成する

プロジェクトのセットアップ

エージェント契約の要件

カスタムエージェントは、次のコア要件を満たしている必要があります。

プロジェクトの構造

注: 便宜上、以下の例では、リクエストを処理するためのウェブサーバーフレームワークとして FastAPI Server を使用しています。

プロジェクトには次の構造が必要です。

my-custom-agent/
├── agent.py                 # FastAPI application
├── Dockerfile               # ARM64 container configuration
├── pyproject.toml           # Created by uv init
└── uv.lock                  # Created automatically by uv

Complete strands エージェントの例

次の内容でプロジェクトルートagent.pyに を作成します。

例 agent.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
from datetime import datetime
from strands import Agent

app = FastAPI(title="Strands Agent Server", version="1.0.0")

# Initialize Strands agent
strands_agent = Agent()

class InvocationRequest(BaseModel):
    input: Dict[str, Any]

class InvocationResponse(BaseModel):
    output: Dict[str, Any]

@app.post("/invocations", response_model=InvocationResponse)
async def invoke_agent(request: InvocationRequest):
    try:
        user_message = request.input.get("prompt", "")
        if not user_message:
            raise HTTPException(
                status_code=400,
                detail="No prompt found in input. Please provide a 'prompt' key in the input."
            )

        result = strands_agent(user_message)
        response = {
            "message": result.message,
            "timestamp": datetime.utcnow().isoformat()
        }

        return InvocationResponse(output=response)

    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Agent processing failed: {str(e)}")

@app.get("/ping")
async def ping():
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8080)

この実装:

ローカルでテストします

エージェントをテストする

dockerfile を作成する

次の内容でプロジェクトルートDockerfileに を作成します。

サンプル Dockerfile

# Use uv's ARM64 Python base image
FROM --platform=linux/arm64 ghcr.io/astral-sh/uv:python3.11-bookworm-slim

WORKDIR /app

# Copy uv files
COPY pyproject.toml uv.lock ./

# Install dependencies (including strands-agents)
RUN uv sync --frozen --no-cache

# Copy agent file
COPY agent.py ./

# Expose port
EXPOSE 8080

# Run application
CMD ["uv", "run", "uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8080"]

この Dockerfile:

ARM64 イメージの構築とデプロイ

docker buildx のセットアップ

Docker buildx では、さまざまなアーキテクチャ用のイメージを構築できます。以下を使用してセットアップします。

docker buildx create --use

ARM64 用にビルドし、ローカルでテストする

イメージの構築とテスト

ECR リポジトリを作成してデプロイする

ECR へのデプロイ

エージェントランタイムをデプロイする

以下の内容で deploy_agent.py という名前のファイルを作成します。

deploy_agent.py の例

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

response = client.create_agent_runtime(
    agentRuntimeName='strands_agent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': 'account-id.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest'
        }
    },
    networkConfiguration={"networkMode": "PUBLIC"},
    roleArn='arn:aws:iam::account-id:role/AgentRuntimeRole',
    lifecycleConfiguration={
        'idleRuntimeSessionTimeout': 300,  # 5 min, configurable
        'maxLifetime': 1800                # 30 minutes, configurable
    },
)

print(f"Agent Runtime created successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")

スクリプトを実行してエージェントをデプロイします。

uv run deploy_agent.py

このスクリプトは、 create_agent_runtimeオペレーションを使用して、エージェントを Amazon Bedrock AgentCore にデプロイします。account-id を実際の AWS アカウント ID に置き換え、IAM ロールに必要なアクセス許可があることを確認してください。詳細については、AgentCore ランタイムの IAM アクセス許可」を参照してください。

エージェントを呼び出す

以下の内容で invoke_agent.py という名前のファイルを作成します。

invoke_agent.py の例

import boto3
import json

agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
payload = json.dumps({
    "input": {"prompt": "Explain machine learning in simple terms"}
})

response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/myStrandsAgent-suffix',
    runtimeSessionId='dfmeoagmreaklgmrkleafremoigrmtesogmtrskhmtkrlshmt',  # Must be 33+ chars
    payload=payload,
    qualifier="DEFAULT"
)

response_body = response['response'].read()
response_data = json.loads(response_body)
print("Agent Response:", response_data)

スクリプトを実行してエージェントを呼び出します。

uv run invoke_agent.py

このスクリプトは、InvokeAgentRuntime SDK オペレーションを使用して、デプロイされたエージェントにリクエストを送信します。 AWS account-id と agentArn を実際の値に置き換えてください。

エージェントを OAuth と統合する場合は、 AWS SDK を使用して InvokeAgentRuntime を呼び出すことはできません。代わりに、InvokeAgentRuntime に HTTPS リクエストを行います。詳細については、「インバウンド認証とアウトバウンド認証による認証と認可」を参照してください。

予想されるレスポンス形式

エージェントを呼び出すと、次のようなレスポンスが表示されます。

サンプルレスポンスの例

{
  "output": {
    "message": {
      "role": "assistant",
      "content": [
        {
          "text": "# Artificial Intelligence in Simple Terms\n\nArtificial Intelligence (AI) is technology that allows computers to do tasks that normally need human intelligence. Think of it as teaching machines to:\n\n- Learn from information (like how you learn from experience)\n- Make decisions based on what they've learned\n- Recognize patterns (like identifying faces in photos)\n- Understand language (like when I respond to your questions)\n\nInstead of following specific step-by-step instructions for every situation, AI systems can adapt to new information and improve over time.\n\nExamples you might use every day include voice assistants like Siri, recommendation systems on streaming services, and email spam filters that learn which messages are unwanted."
        }
      ]
    },
    "timestamp": "2025-07-13T01:48:06.740668"
  }
}

ランタイムセッションを停止する

設定可能な IdleRuntimeSessionTimeout (デフォルトは 15 分) より前に実行中のセッションを停止し、潜在的なランアウェイコストを節約するには、以下を実行します。 stop_runtime_session

以下の内容で stop_runtime_session.py という名前のファイルを作成します。

stop_runtime_session.py の例

import boto3

agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = agent_core_client.stop_runtime_session(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/myStrandsAgent-suffix',
    runtimeSessionId='dfmeoagmreaklgmrkleafremoigrmtesogmtrskhmtkrlshmt',
    qualifier="DEFAULT"
)

Amazon Bedrock AgentCore の要件の概要

結論

このガイドでは、以下の方法を学習しました。

これらのステップに従うことで、エージェントの実装を完全に制御しながら、Amazon Bedrock AgentCore の能力を活用するカスタムエージェントを作成およびデプロイできます。