# 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](runtime-service-contract.md), 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.
**nota**
También puede utilizar este enfoque para los agentes que cree con el SDK de AgentCore Python.
## Configuración de inicio rápido
### Habilite la observabilidad para su agente
[Amazon Bedrock AgentCore Observability](observability.md) 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 ](observability-configure.md#observability-configure-builtin)
### 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](https://docs.astral.sh/uv/getting-started/installation/).
### Cree su proyecto de agente
**Configurando tu proyecto**
1. Crea el directorio de tu proyecto y navega hasta él:
```
mkdir my-custom-agent && cd my-custom-agent
```
1. Inicialice el proyecto con Python 3.11:
```
uv init --python 3.11
```
1. Agregue las dependencias necesarias (uv crea automáticamente un .venv):
```
uv add fastapi 'uvicorn[standard]' pydantic httpx strands-agents
```
## Requisitos del contrato de agente
Su agente de aduanas debe cumplir estos requisitos básicos:
+ **/invocations Endpoint: punto final** POST para las interacciones entre los agentes (OBLIGATORIO)
+ Punto final **/ping: punto final** GET para controles de estado (OBLIGATORIO)
+ **Docker Container: paquete** de despliegue arm64 en contenedores
## 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:
+ Crea una aplicación FastAPI con los puntos finales necesarios
+ Inicializa un agente de Strands para procesar los mensajes de los usuarios
+ Implementa el punto final `/invocations` POST para las interacciones entre los agentes
+ Implementa el punto final `/ping` GET para los controles de estado
+ Configura el servidor para que se ejecute en el host `0.0.0.0` y el puerto `8080`
## Haga una prueba local
**Probando su agente**
1. Ejecute la aplicación:
```
uv run uvicorn agent:app --host 0.0.0.0 --port 8080
```
1. Pruebe el `/ping` punto final (en otro terminal):
```
curl http://localhost:8080/ping
```
1. Pruebe el `/invocations` punto final:
```
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{
"input": {"prompt": "What is artificial intelligence?"}
}'
```
## 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:
+ Utiliza una imagen base de Python ARM64 (requerida por Amazon Bedrock AgentCore)
+ Configura el directorio de trabajo
+ Copia los archivos de dependencias e instala las dependencias
+ Copia el código del agente
+ Expone el puerto 8080
+ Configura el comando para ejecutar la aplicación
## 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**
1. Cree la imagen localmente para probarla:
```
docker buildx build --platform linux/arm64 -t my-agent:arm64 --load.
```
1. Realice pruebas localmente con credenciales (los agentes de Strands necesitan AWS credenciales):
```
docker run --platform linux/arm64 -p 8080:8080 \
-e AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \
-e AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \
-e AWS_SESSION_TOKEN="$AWS_SESSION_TOKEN" \
-e AWS_REGION="$AWS_REGION" \
my-agent:arm64
```
### Cree un repositorio de ECR e impleméntelo
**Implementación en ECR**
1. Cree un repositorio de ECR:
```
aws ecr create-repository --repository-name my-strands-agent --region us-west-2
```
1. Inicie sesión en ECR:
```
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin account-id.dkr.ecr.us-west-2.amazonaws.com
```
1. Cree e inserte en ECR:
```
docker buildx build --platform linux/arm64 -t account-id.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest --push.
```
1. Verifica que se haya insertado la imagen:
```
aws ecr describe-images --repository-name my-strands-agent --region us-west-2
```
## 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 ](runtime-permissions.md) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) 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](runtime-oauth.md).
## 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
+ **Plataforma**: Debe ser `linux/arm64`
+ **Puntos finales**: `/invocations` POST y `/ping` GET son obligatorios
+ **ECR**: Las imágenes deben desplegarse en el ECR
+ **Puerto**: la aplicación se ejecuta en el puerto 8080
+ **Integración de Strands**: utiliza el agente Strands para el procesamiento de IA
+ **Credenciales**: los agentes de Strands requieren AWS credenciales para operar
## Conclusión
En esta guía, ha aprendido a:
+ Configurar un entorno de desarrollo para crear agentes personalizados
+ Cree una aplicación FastAPI que implemente los puntos finales necesarios
+ Coloque su agente en contenedores para la arquitectura ARM64
+ Pruebe su agente localmente
+ Despliegue a su agente en ECR
+ Cree un entorno de ejecución para agentes en Amazon Bedrock AgentCore
+ Invoque a su agente desplegado
+ Detenga la sesión de ejecución del agente
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.