Commencez sans la AgentCore CLI

Vous pouvez créer un agent AgentCore Runtime sans la AgentCore CLI. Vous pouvez plutôt utiliser une combinaison d'outils de ligne de commande pour configurer et déployer votre agent sur un AgentCore environnement d'exécution.

Ce didacticiel explique comment déployer un agent personnalisé sans utiliser la AgentCore CLI. Un agent personnalisé est un agent créé sans utiliser le SDK AgentCore Python. Dans ce didacticiel, l'agent personnalisé est créé à l'aide de FastAPI et Docker. L'agent personnalisé respecte les exigences AgentCore d'exécution, ce qui signifie qu'il doit exposer les points de terminaison /invocations POST et /ping GET et être empaqueté dans un conteneur Docker. Amazon Bedrock AgentCore nécessite une architecture ARM64 pour tous les agents déployés.

Configuration de démarrage rapide

Offrez l'observabilité à votre agent

Amazon Bedrock AgentCore Observability vous permet de suivre, de déboguer et de surveiller les agents que vous hébergez dans Runtime. AgentCore Pour observer un agent, activez d'abord la recherche de CloudWatch transactions en suivant les instructions de la section Activation de l' AgentCore observabilité.

Installez UV

Pour cet exemple, nous utiliserons le gestionnaire de uv packages, mais vous pouvez utiliser n'importe quel utilitaire ou gestionnaire de packages Python. Pour l'installer uv sur macOS :

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

Pour les instructions d'installation sur d'autres plateformes, reportez-vous à la documentation UV.

Créez votre projet d'agent

Configuration de votre projet

Exigences relatives au contrat d'agent

Votre agent personnalisé doit satisfaire aux exigences fondamentales suivantes :

Structure du projet

Remarque : Pour des raisons pratiques, l'exemple ci-dessous utilise le serveur FastAPI comme infrastructure de serveur Web pour le traitement des demandes.

Votre projet doit avoir la structure suivante :

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

Exemple d'agent à mèches complètes

Créez agent.py à la racine de votre projet avec le contenu suivant :

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

Cette implémentation :

Test local

Tester votre agent

Créer un fichier docker

Créez Dockerfile à la racine de votre projet avec le contenu suivant :

Exemple de 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"]

Ce Dockerfile :

Création et déploiement d'une image ARM64

Configurer docker buildx

Docker buildx vous permet de créer des images pour différentes architectures. Configurez-le avec :

docker buildx create --use

Compiler pour ARM64 et tester localement

Construire et tester votre image

Création d'un référentiel ECR et déploiement

Déploiement vers ECR

Déployer l'environnement d'exécution

Créez un fichier nommé deploy_agent.py avec le contenu suivant:

Exemple 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']}")

Exécutez le script pour déployer votre agent :

uv run deploy_agent.py

Ce script utilise l'create_agent_runtimeopération pour déployer votre agent sur Amazon Bedrock AgentCore. Assurez-vous de le account-id remplacer par votre identifiant de AWS compte réel et assurez-vous que le rôle IAM dispose des autorisations nécessaires. Pour plus d'informations, consultez la section Permissions IAM pour AgentCore Runtime.

Invocation de l’agent

Créez un fichier nommé invoke_agent.py avec le contenu suivant:

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

Exécutez le script pour appeler votre agent :

uv run invoke_agent.py

Ce script utilise l'opération du InvokeAgentRuntime AWS SDK pour envoyer une demande à votre agent déployé. Assurez-vous de remplacer account-id et agentArn par vos valeurs réelles.

Si vous envisagez d'intégrer votre agent à OAuth, vous ne pouvez pas utiliser le AWS SDK pour appeler. InvokeAgentRuntime Envoyez plutôt une requête HTTPS à InvokeAgentRuntime. Pour plus d'informations, consultez Authentifier et autoriser avec l'authentification entrante et l'authentification sortante.

Format de réponse attendu

Lorsque vous appelez votre agent, vous recevez une réponse comme celle-ci :

Exemple de réponse type

{
  "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"
  }
}

Arrêter la session d'exécution

Pour arrêter la session en cours avant la configuration IdleRuntimeSessionTimeout (15 minutes par défaut) et économiser sur d'éventuels coûts supplémentaires, exécutez : stop_runtime_session

Créez un fichier nommé stop_runtime_session.py avec le contenu suivant:

Exemple 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"
)

Résumé des AgentCore exigences d'Amazon Bedrock

Conclusion

Dans ce guide, vous avez appris à :

En suivant ces étapes, vous pouvez créer et déployer des agents personnalisés qui tirent parti de la puissance d'Amazon Bedrock AgentCore tout en gardant un contrôle total sur la mise en œuvre de votre agent.