Comece sem a AgentCore CLI

Você pode criar um agente AgentCore Runtime sem a AgentCore CLI. Em vez disso, você pode usar uma combinação de ferramentas de linha de comando para configurar e implantar seu agente em um AgentCore Runtime.

Este tutorial mostra como implantar um agente personalizado sem usar a AgentCore CLI. Um agente personalizado é um agente criado sem usar o SDK do AgentCore Python. Neste tutorial, o agente personalizado é criado usando FastAPI e Docker. O agente personalizado segue os requisitos AgentCore de tempo de execução, o que significa que o agente deve expor os endpoints /invocations POST e /ping GET e ser empacotado em um contêiner Docker. O Amazon Bedrock AgentCore exige a arquitetura ARM64 para todos os agentes implantados.

Configuração de início rápido

Habilite a observabilidade para seu agente

O Amazon Bedrock AgentCore Observability ajuda você a rastrear, depurar e monitorar agentes que você hospeda no Runtime. AgentCore Para observar um agente, primeiro ative a Pesquisa de CloudWatch Transações seguindo as instruções em Habilitando a AgentCore observabilidade.

Instalar uv

Neste exemplo, usaremos o gerenciador de uv pacotes, embora você possa usar qualquer utilitário ou gerenciador de pacotes do Python. Para instalar uv no macOS:

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

Para obter instruções de instalação em outras plataformas, consulte a documentação do uv.

Crie seu projeto de agente

Configurando seu projeto

Requisitos do contrato do agente

Seu agente personalizado deve atender aos seguintes requisitos principais:

Estrutura do projeto

Observação: por conveniência, o exemplo abaixo usa o FastAPI Server como a estrutura do servidor Web para lidar com solicitações.

Seu projeto deve ter a seguinte estrutura:

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

Exemplo completo de agente de filamentos

Crie agent.py na raiz do seu projeto com o seguinte conteúdo:

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

Essa implementação:

Testar localmente

Testando seu agente

Criar dockerfile

Crie Dockerfile na raiz do seu projeto com o seguinte conteúdo:

Example 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:

Crie e implante a imagem ARM64

Configurar docker buildx

O Docker buildx permite criar imagens para diferentes arquiteturas. Configure-o com:

docker buildx create --use

Crie para ARM64 e teste localmente

Construindo e testando sua imagem

Crie um repositório ECR e implante

Implantação no ECR

Tempo de execução do agente de implantação

Crie um arquivo chamado deploy_agent.py com o seguinte conteúdo:

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

Execute o script para implantar seu agente:

uv run deploy_agent.py

Esse script usa a create_agent_runtime operação para implantar seu agente no Amazon Bedrock AgentCore. Certifique-se de account-id substituir pelo ID real da sua AWS conta e garantir que a função do IAM tenha as permissões necessárias. Para obter mais informações, consulte Permissões do IAM para AgentCore tempo de execução.

Invoque seu agente

Crie um arquivo chamado invoke_agent.py com o seguinte conteúdo:

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

Execute o script para invocar seu agente:

uv run invoke_agent.py

Esse script usa a operação do InvokeAgentRuntime AWS SDK para enviar uma solicitação ao seu agente implantado. Certifique-se de substituir account-id e agentArn com seus valores reais.

Se você planeja integrar seu agente ao OAuth, não pode usar o AWS SDK para fazer chamadas. InvokeAgentRuntime Em vez disso, faça uma solicitação HTTPS para InvokeAgentRuntime. Para obter mais informações, consulte Autenticar e autorizar com Autenticação de Entrada e Autenticação de Saída.

Formato de resposta esperado

Ao invocar seu agente, você receberá uma resposta como esta:

Exemplo de resposta de amostra

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

Parar sessão de tempo de execução

Para interromper a sessão em execução antes do configurável IdleRuntimeSessionTimeout (o padrão é de 15 minutos) e economizar em possíveis custos descontrolados, execute: stop_runtime_session

Crie um arquivo chamado stop_runtime_session.py com o seguinte conteúdo:

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

Resumo dos AgentCore requisitos do Amazon Bedrock

Conclusão

Neste guia, você aprendeu como:

Seguindo essas etapas, você pode criar e implantar agentes personalizados que aproveitam o poder do Amazon Bedrock AgentCore enquanto mantêm controle total sobre a implementação do seu agente.