Amazon Bedrock AgentCore: o “core” operacional para agentes em produção

Se você já colocou um agente para rodar localmente (LangGraph, Strands, CrewAI, etc.), você sabe: o problema raramente é “fazer o modelo responder”. O problema é operar isso com segurança, rastreabilidade, isolamento, controle de acesso, versionamento, endpoints estáveis, observabilidade e governança, sem virar um festival de scripts e exceções.

O Amazon Bedrock AgentCore existe exatamente para eliminar essa camada de “undifferentiated heavy lifting” e te dar serviços composáveis para levar agentes para produção. O coração disso é o AgentCore Runtime, que hospeda seu agente como workload serverless com isolamento por sessão em microVM, suporte a execuções longas, autenticação, e trilhas de observabilidade orientadas a agentes.

A seguir eu vou direto ao ponto: como desenhar a fundação (rede, IAM, chaves, logs, versionamento e esteiras) e como provisionar runtimes e endpoints em Terraform sem ficar na superfície.

1) O que você está provisionando, de verdade

1.1 Runtime ≠ “o agente”

No AgentCore, o Runtime é o ambiente de execução do seu agente (ou de uma ferramenta / servidor MCP). Você “deposita” um artefato (container no ECR ou código via S3) e o Runtime passa a expor um contrato de invocação.

O Runtime traz propriedades que importam operacionalmente:

• NetworkConfiguration: PUBLIC ou VPC (sim, isso muda totalmente seu threat model).
• LifecycleConfiguration: limites de tempo por sessão e vida máxima. (Essencial para custo, resiliência e segurança).
• EnvironmentVariables: controlável, mas precisa disciplina (não vire “cofre de segredos” acidental).
• AuthorizerConfiguration: opções de autorização inbound.

1.2 Versionamento e endpoints (o que quase todo mundo negligencia)

Toda vez que você cria um Runtime, você ganha versão 1. Cada update gera uma nova versão imutável. Endpoints são ponteiros para versões — inclusive um DEFAULT que aponta para a versão mais recente.

Isso é a base do seu modelo de promoção:

• dev → staging → prod
• endpoint prod não deveria “flutuar” (a menos que você queira), enquanto DEFAULT pode ser usado para iteração rápida.

1.3 Invocação: Runtime ARN + payload (e suporte a streaming)

A invocação usa o InvokeAgentRuntime, com suporte a sessão e resposta em tempo real/streaming.

2) A fundação mínima para provisionar agentes “com boas práticas” (sem conversa mole)

Vou organizar a fundação como camadas, porque é assim que você evita retrabalho quando o número de agentes cresce.

Camada A — Padrões de conta/ambiente e governança

Objetivo: ambientes previsíveis, separação de blast radius e rastreabilidade.

• Separar por contas (mínimo: shared, dev, prod). Se não der, separar por workspaces + naming/tagging rigoroso.
• Tags obrigatórias: app, env, owner, cost_center, data_classification, criticality.
• KMS por domínio (logs/segredos/dados sensíveis) e políticas mínimas.

Camada B — Rede e egress (onde “PUBLIC” vira dívida)

Decisão crítica: PUBLIC vs VPC.

Para enterprise, o padrão tende a ser VPC para:

• controlar egress,
• usar endpoints privados,
• reduzir superfície de exposição.

O próprio Runtime suporta NetworkMode: PUBLIC | VPC.

Recomendação prática:

• Subnets privadas + NAT com egress controlado (ou egress via firewall).
• VPC Endpoints (Interface/Gateway) para o que seu agente usa (S3, ECR, Logs, STS, Bedrock conforme aplicável).
• SG “deny by default”, liberar só o necessário.

Camada C — IAM (o lugar onde agentes quebram segurança em silêncio)

Você vai ter, no mínimo:

1. Role de execução do Runtime (o roleArn do runtime).
2. Permissões de invocação de modelos (bedrock:InvokeModel* quando o agente chamar modelos no Bedrock). Isso aparece inclusive em atualizações de políticas gerenciadas relacionadas ao AgentCore.
3. Permissões específicas de ferramentas (S3, DynamoDB, APIs internas, etc.) — sempre em política separada por “capability”, não um monstrão.

Regra operacional: “runtime role” não deveria ter permissão de administrar infraestrutura. Ele executa. Ponto.

Camada D — Observabilidade de agente (não é só log)

AgentCore Runtime dá trilhas focadas em “agent reasoning / tool invocations / model interactions” para debugging e auditoria.

Fundação recomendada:

• Log groups padronizados por env/app/runtime.
• Retention por classe (dev: curto, prod: alinhado a compliance).
• Correlação por sessionId, requestId, traceId (OpenTelemetry quando aplicável).

Camada E — Versionamento, endpoints e promoção (CI/CD)

Se você não automatizar isso, vira “deploy artesanal”:

• Build do artefato (container) → push no ECR
• Atualiza Runtime (gera nova versão)
• Atualiza endpoint staging
• Smoke test (invoke)
• Promotion manual/aprovada → atualiza endpoint prod

O mecanismo de endpoints/versões existe justamente para isso.

3) Provisionamento em Terraform (com Runtime + Endpoint + fundação)

3.1 Por que eu vou usar awscc aqui

No momento, os recursos do AgentCore Runtime/Endpoint aparecem de forma natural via CloudFormation e no ecossistema Terraform o caminho mais direto é o provider awscc (Cloud Control / CloudFormation-backed). Isso te dá uma trilha estável enquanto o provider aws “main” evolui para cobrir tudo nativamente.

_Se você preferir não depender do awscc, a alternativa pragmática é acionar a criação via AWS CLI (bedrock-agentcore-control create-agent-runtime etc.) em null_resource — mas aí você está assumindo drift e idempotência na unha._

3.2 Estrutura recomendada de repositório Terraform

/infra
  /modules
    /agentcore-foundation
    /agentcore-runtime
  /envs
    /dev
    /prod

• agentcore-foundation: VPC, endpoints, KMS, ECR, logs, IAM base
• agentcore-runtime: runtime + endpoints + policies específicas do agente

3.3 Código: providers, convenções e tags

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0"
    }
    awscc = {
      source  = "hashicorp/awscc"
      version = ">= 0.80.0"
    }
  }
}

provider "aws" {
  region = var.region
}

provider "awscc" {
  region = var.region
}

locals {
  tags = {
    app                = var.app_name
    env                = var.env
    owner              = var.owner
    cost_center        = var.cost_center
    data_classification = var.data_classification
  }
}

3.4 Fundação: ECR (artefato do runtime) + KMS + Logs

ECR (com immutability e scan)

resource "aws_ecr_repository" "agent" {
  name                 = "${var.app_name}-${var.env}-agentcore"
  image_tag_mutability = "IMMUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }

  tags = local.tags
}

KMS (para criptografia de logs/segredos/dados)

resource "aws_kms_key" "agentcore" {
  description             = "KMS for AgentCore (${var.app_name}/${var.env})"
  deletion_window_in_days = 30
  enable_key_rotation     = true
  tags                    = local.tags
}

CloudWatch Logs (padrão de retenção)

resource "aws_cloudwatch_log_group" "agentcore" {
  name              = "/agentcore/${var.env}/${var.app_name}"
  retention_in_days = var.log_retention_days
  kms_key_id        = aws_kms_key.agentcore.arn
  tags              = local.tags
}

Observação: o AgentCore pode criar logs próprios em namespaces específicos (inclusive para avaliações). Se você quer “tudo sob controle”, planeje naming/retention e permissões de forma explícita.

3.5 IAM: Role do Runtime (least privilege de verdade)

data "aws_iam_policy_document" "runtime_assume" {
  statement {
    effect = "Allow"
    actions = ["sts:AssumeRole"]

    principals {
      type        = "Service"
      identifiers = ["bedrock-agentcore.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "runtime" {
  name               = "${var.app_name}-${var.env}-agentcore-runtime"
  assume_role_policy = data.aws_iam_policy_document.runtime_assume.json
  tags               = local.tags
}

# Exemplo: permitir invocar modelos no Bedrock
data "aws_iam_policy_document" "runtime_permissions" {
  statement {
    sid     = "BedrockInvoke"
    effect  = "Allow"
    actions = ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"]
    resources = var.allowed_model_arns
  }

  # Exemplo: logs
  statement {
    sid    = "WriteLogs"
    effect = "Allow"
    actions = [
      "logs:CreateLogStream",
      "logs:PutLogEvents"
    ]
    resources = ["${aws_cloudwatch_log_group.agentcore.arn}:*"]
  }
}

resource "aws_iam_policy" "runtime_permissions" {
  name   = "${var.app_name}-${var.env}-agentcore-runtime-permissions"
  policy = data.aws_iam_policy_document.runtime_permissions.json
  tags   = local.tags
}

resource "aws_iam_role_policy_attachment" "runtime_attach" {
  role       = aws_iam_role.runtime.name
  policy_arn = aws_iam_policy.runtime_permissions.arn
}

3.6 Provisionando o Runtime (awscc / CloudFormation-backed)

A CloudFormation define que o Runtime exige:

• AgentRuntimeName
• AgentRuntimeArtifact (container ou código no S3)
• RoleArn
• NetworkConfiguration (PUBLIC ou VPC)
• (opcionais) LifecycleConfiguration, EnvironmentVariables, AuthorizerConfiguration, etc.

Exemplo com container no ECR e VPC mode

resource "awscc_bedrockagentcore_runtime" "this" {
  agent_runtime_name = "${var.app_name}_${var.env}"

  description = "AgentCore Runtime for ${var.app_name} (${var.env})"

  role_arn = aws_iam_role.runtime.arn

  # Artefato: container
  agent_runtime_artifact = {
    container_configuration = {
      container_uri = "${aws_ecr_repository.agent.repository_url}:${var.image_tag}"
    }
  }

  # Rede: VPC
  network_configuration = {
    network_mode = "VPC"
    network_mode_config = {
      vpc_id     = var.vpc_id
      subnet_ids = var.private_subnet_ids
      security_group_ids = [var.runtime_sg_id]
    }
  }

  # Ciclo de vida (controle de custo / segurança)
  lifecycle_configuration = {
    idle_runtime_session_timeout = var.idle_session_timeout_seconds
    max_lifetime                 = var.max_session_lifetime_seconds
  }

  environment_variables = {
    ENV        = var.env
    LOG_LEVEL  = var.log_level
  }

  tags = local.tags
}

A API do AgentCore Runtime expõe explicitamente networkConfiguration, lifecycleConfiguration, environmentVariables e roleArn como parâmetros de criação/controle.

3.7 Endpoint estável para promoção (dev/staging/prod)

O recurso RuntimeEndpoint em CloudFormation pede:

• AgentRuntimeId
• Name
• (opcional) AgentRuntimeVersion e Description

Em Terraform (awscc), isso fica assim:

resource "awscc_bedrockagentcore_runtime_endpoint" "prod" {
  agent_runtime_id = awscc_bedrockagentcore_runtime.this.agent_runtime_id
  name             = "prod"
  description      = "Stable production endpoint for ${var.app_name}"

  # Fixar versão (recomendado em prod)
  agent_runtime_version = awscc_bedrockagentcore_runtime.this.agent_runtime_version

  tags = local.tags
}

Como eu opero isso na prática (sem drama)

• Em dev, eu posso deixar o endpoint “flutuar” (apontar para latest) ou usar DEFAULT.
• Em prod, eu fixo versão e só atualizo o endpoint após pipeline e aprovação.

Esse modelo é exatamente o que o AgentCore descreve: endpoints como ponteiros, versões imutáveis, e DEFAULT acompanhando o latest.

3.8 Invocação: smoke test automatizado no pipeline

Você pode testar após provisionamento usando AWS CLI (ou SDK). O CLI existe para create-agent-runtime e também para invocar.

Exemplo de invoke (payload em JSON):

aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn "$RUNTIME_ARN" \
  --payload fileb://payload.json \
  --content-type application/json \
  /dev/stdout

A API InvokeAgentRuntime é o contrato para requests/respostas em tempo real e suporta qualificador para endpoint/versão.

4) Checklists práticos: o que diferencia “provisionar” de “provisionar direito”

4.1 Segurança (baseline)

• Runtime em VPC quando houver dado sensível ou integração interna (padrão enterprise).
• IAM “capability-based”: policies pequenas por recurso (S3 read, Dynamo read, etc.).
• Segredos fora de env var (env var é config, não vault).
• Auditoria: log/trace com retenção adequada e correlação por sessão.

4.2 Operação

• Endpoint prod fixado em versão.
• Deploy = novo container tag imutável + update runtime + update endpoint.
• Timeouts (idle e max lifetime) explícitos para evitar sessões “zumbi”.

4.3 Qualidade (antes de escalar)

A AWS publicou um conjunto bem “pé no chão” de boas práticas para agentes em enterprise — instrumentar desde o dia 1, estratégia deliberada de ferramentas, avaliação automatizada, combinar agente com código determinístico, etc. Eu recomendo usar isso como checklist de maturidade para quando você sair de 1 agente para “plataforma de agentes”.

5) Fechando: a ideia central

AgentCore não é “mais um jeito de fazer prompt”. É uma camada operacional para agentes com:

• runtime com isolamento por sessão e execução longa,
• versionamento automático + endpoints,
• e uma superfície de infraestrutura (rede/IAM/observabilidade) que você precisa tratar como produto interno.

Até o próximo post!