Comience sin la AgentCore CLI

Puede crear un agente AgentCore de tiempo de ejecución sin la AgentCore CLI. En su lugar, puede utilizar una combinación de herramientas de línea de comandos para configurar e implementar el agente en un AgentCore entorno de ejecución.

Este tutorial muestra cómo implementar un agente personalizado sin usar la AgentCore CLI. Un agente personalizado es un agente creado sin usar el SDK de AgentCore Python. En este tutorial, el agente personalizado se crea con FastAPI y Docker. El agente personalizado cumple con los requisitos AgentCore de tiempo de ejecución, lo que significa que debe exponer los puntos finales /invocations POST y /ping GET y estar empaquetado en un contenedor de Docker. Amazon Bedrock AgentCore requiere la arquitectura ARM64 para todos los agentes implementados.

Configuración de inicio rápido

Habilite la observabilidad para su agente

Amazon Bedrock AgentCore Observability le ayuda a rastrear, depurar y supervisar los agentes que aloja en Runtime. AgentCore Para observar a un agente, primero active la búsqueda de CloudWatch transacciones siguiendo las instrucciones que se indican en Habilitar la observabilidad. AgentCore

Instale uv

Para este ejemplo, usaremos el administrador de uv paquetes, aunque puedes usar cualquier utilidad o administrador de paquetes de Python. Para instalar uv en macOS:

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

Para obtener instrucciones de instalación en otras plataformas, consulte la documentación de uv.

Cree su proyecto de agente

Configurando tu proyecto

Requisitos del contrato de agente

Su agente de aduanas debe cumplir estos requisitos básicos:

Estructura de un proyecto

Nota: Para mayor comodidad, el siguiente ejemplo utiliza el servidor FastAPI como marco de servidor web para gestionar las solicitudes.

El proyecto debe tener la siguiente estructura:

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

Ejemplo de agente Complete Strams

Crea agent.py la raíz de tu proyecto con el siguiente contenido:

Ejemplo: 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)

Esta implementación:

Haga una prueba local

Probando su agente

Cree un dockerfile

Crea Dockerfile en la raíz de tu proyecto el siguiente contenido:

Ejemplo 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"]

Este Dockerfile:

Cree e implemente una imagen ARM64

Configurar docker buildx

Docker buildx le permite crear imágenes para diferentes arquitecturas. Configúralo con:

docker buildx create --use

Compile para ARM64 y pruébelo localmente

Construye y prueba tu imagen

Cree un repositorio de ECR e impleméntelo

Implementación en ECR

Implemente el tiempo de ejecución

Cree un archivo denominado deploy_agent.py con el siguiente contenido:

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

Ejecute el script para implementar su agente:

uv run deploy_agent.py

Este script utiliza la create_agent_runtime operación para implementar el agente en Amazon Bedrock AgentCore. Asegúrese de account-id reemplazarlo por su ID de AWS cuenta real y asegúrese de que el rol de IAM tenga los permisos necesarios. Para obtener más información, consulte Permisos de IAM para AgentCore tiempo de ejecución.

Invocar al agente

Cree un archivo denominado invoke_agent.py con el siguiente contenido:

Ejemplo: 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)

Ejecute el script para invocar a su agente:

uv run invoke_agent.py

Este script usa la operación del InvokeAgentRuntime AWS SDK para enviar una solicitud al agente desplegado. Asegúrese de reemplazar account-id y agentArn con sus valores reales.

Si planeas integrar tu agente con OAuth, no puedes usar el AWS SDK para llamar. InvokeAgentRuntime En su lugar, haz una solicitud HTTPS a. InvokeAgentRuntime Para obtener más información, consulta Autenticar y autorizar con autenticación entrante y autenticación saliente.

Formato de respuesta esperado

Cuando invoques a tu agente, recibirás una respuesta como esta:

Ejemplo de respuesta:

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

Detenga la sesión de ejecución

Para detener la sesión en ejecución antes de la sesión configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar en posibles costes excesivos, ejecute: stop_runtime_session

Cree un archivo denominado stop_runtime_session.py con el siguiente contenido:

Ejemplo: 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"
)

Resumen de AgentCore requisitos de Amazon Bedrock

Conclusión

En esta guía, ha aprendido a:

Si sigue estos pasos, puede crear e implementar agentes personalizados que aprovechen el potencial de Amazon Bedrock y, AgentCore al mismo tiempo, mantener el control total sobre la implementación de su agente.