Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Comience sin la AgentCore CLI

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

En este tutorial se 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 sigue 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 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 habilite la búsqueda de CloudWatch transacciones siguiendo las instrucciones que aparecen en Habilitar la observabilidad. AgentCore

Instala uv

Para este ejemplo, usaremos el administrador de uv paquetes, aunque puedes usar cualquier utilidad o administrador de paquetes de Python. Para instalarlo 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.

Crea tu proyecto de agente

Configurando tu proyecto

Requisitos de contrato de agente

Su agente personalizado 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 completo de un agente de Strands

Crea agent.py en 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 isinstance(user_message, str) or not user_message.strip():
            raise HTTPException(
                status_code=400,
                detail="Invalid input: 'prompt' must be a non-empty string"
            )

        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

Crea un archivo docker

Crea Dockerfile en la raíz de tu proyecto con 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 archivo Docker:

Compila e implementa la imagen ARM64

Configura las compilaciones de Docker

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

docker buildx create --use

Compile para ARM64 y pruébelo localmente

Construyendo y probando tu imagen

Cree un repositorio de ECR e impleméntelo

Despliegue en ECR

Implemente la ejecución del agente

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 el agente:

uv run deploy_agent.py

Este script utiliza la create_agent_runtime operación para implementar su agente en Amazon Bedrock AgentCore. Asegúrese de sustituirlo por el account-id identificador de su AWS cuenta real y asegúrese de que el rol de IAM tiene los permisos necesarios. Para obtener más información, consulta los permisos de IAM para AgentCore el 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 realizar llamadas. InvokeAgentRuntime En su lugar, haz una solicitud HTTPS a. InvokeAgentRuntime Para obtener más información, consulta Autenticar y autorizar con la autenticación entrante y la autenticación saliente.

Formato de respuesta esperado

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

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

Detener la sesión de ejecución

Para detener la sesión en ejecución antes que la configurable IdleRuntimeSessionTimeout (el valor predeterminado es de 15 minutos) y ahorrar cualquier posible coste adicional, 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 los AgentCore requisitos de Amazon Bedrock

Conclusión

En esta guía, has aprendido a:

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