Como configurar o OpenAI ChatGPT Codex com LiteLLM no Amazon ECS e Amazon Bedrock

Controle centralizado para agentes de codificação com IA generativa

À medida que as organizações avançam da experimentação individual para a adoção gerenciada de agentes de IA, surge uma necessidade prática: controlar o acesso aos modelos de forma consistente entre desenvolvedores e equipes. O OpenAI ChatGPT Codex, combinado com o LiteLLM, oferece exatamente isso — um ponto de controle centralizado para roteamento de modelos, identidade com escopo definido, orçamentos, limites de uso e telemetria.

A AWS publicou um guia completo mostrando como implantar um gateway LiteLLM operado pelo próprio cliente no Serviço de Contêiner Elástico da Amazon (Amazon ECS), conectá-lo a um modelo OpenAI no Amazon Bedrock e configurar o Codex para enviar requisições por esse gateway. A implementação completa está disponível no repositório guidance-codex. Para o caminho principal, o recomendado é seguir o guia de início rápido do LiteLLM na AWS.

Visão geral da arquitetura

A solução posiciona o LiteLLM entre o Codex e o Amazon Bedrock. O gateway se torna o ponto de controle compartilhado para autenticação de modelos, roteamento, orçamentos, limites de taxa e telemetria. O Codex mantém a responsabilidade pelo loop local de execução de tarefas e ferramentas na estação de trabalho do desenvolvedor.

O fluxo de requisição ocorre em cinco etapas:

O Codex envia o contexto da tarefa atual e as definições de ferramentas disponíveis para o endpoint /v1/responses do gateway.
O Balanceador de Carga de Aplicação (ALB) e o AWS WAF aplicam controles de rede e de camada web antes de encaminhar a requisição ao LiteLLM no AWS Fargate.
O LiteLLM autentica o chamador, verifica o modelo configurado e a política de consumo, e usa a função de tarefa do ECS para invocar o modelo aprovado no Amazon Bedrock.
O Amazon Bedrock retorna texto ou uma chamada de função através do LiteLLM. Se o modelo solicitar uma ferramenta, o Codex a executa localmente sob sua política de sandbox e aprovação.
O Codex envia o resultado da ferramenta pelo LiteLLM na próxima requisição Responses, e o loop continua.

A implantação de referência também utiliza: Amazon RDS para PostgreSQL (para estado, uso e dados de orçamento do LiteLLM), AWS Secrets Manager e AWS KMS para armazenamento de chaves, Amazon CloudWatch para logs e alarmes, Amazon ECR para imagem imutável do gateway, e proteções opcionais do AWS WAF.

Por que usar o LiteLLM nesse padrão?

O LiteLLM é um gateway de IA de código aberto que fornece roteamento de modelos, chaves virtuais, orçamentos, limites de taxa e telemetria de uso por trás de endpoints compatíveis com a API. Nesse padrão, o cliente opera o LiteLLM e sua infraestrutura de suporte dentro da própria conta AWS.

O acesso direto ao Amazon Bedrock é a opção de menor complexidade quando identidade nativa da AWS, políticas do Gerenciamento de Identidade e Acesso (IAM) e logs do AWS CloudTrail atendem aos requisitos. Um gateway se torna útil quando a equipe de sistemas precisa de controles adicionais consistentes entre desenvolvedores, equipes ou provedores de modelos. O LiteLLM é uma boa opção quando é necessário:

Permitir apenas aliases de modelos aprovados.
Emitir chaves de gateway com escopo por usuário ou equipe.
Aplicar orçamentos fixos e limites de requisições por minuto ou tokens por minuto.
Centralizar política de roteamento e fallback.
Operar o gateway, banco de dados, rede, logs e processo de atualização na própria conta AWS.

A principal contrapartida é a responsabilidade operacional: a equipe fica responsável pela disponibilidade do gateway, ciclo de vida do banco de dados, atualizações de versão, resposta a incidentes e planejamento de capacidade.

Implantando o gateway LiteLLM no Amazon ECS

Pré-requisitos

Para o passo a passo, são necessários: uma conta AWS com permissões para criar Rede Virtual Privada (VPC), Amazon ECS, Elastic Load Balancing, Amazon RDS, Amazon ECR, AWS WAF, IAM, AWS KMS, Secrets Manager e recursos do CloudWatch; acesso ao modelo OpenAI selecionado no Amazon Bedrock na região de implantação; Interface de Linha de Comando da AWS (AWS CLI) versão 2 com perfil autenticado; Docker com Buildx; Codex CLI; e Python 3. Para implantação com HTTPS, é necessária uma zona hospedada pública no Amazon Route 53 ou um certificado existente no AWS Certificate Manager (ACM) na mesma região.

Nota de custos: A solução cria recursos faturáveis, incluindo um ALB, tarefas Fargate, Amazon RDS, AWS WAF, logs e inferência de modelos. Consulte o AWS Pricing Calculator para sua região e siga a seção de limpeza após o passo a passo.

Implantando o LiteLLM no Amazon ECS

Clone o repositório e crie um arquivo de ambiente de implantação local:

git clone https://github.com/openai-on-aws/guidance-codex.git
cd guidance-codex
git checkout feat/enterprise-gateway-readiness
cp deployment/litellm/.env.deploy.example \
   deployment/litellm/.env.deploy

Configure o perfil AWS, regiões, CIDR de origem e valores de DNS ou certificado. O trecho a seguir mostra as configurações orientadas à produção:

AWS_PROFILE=your-profile
AWS_REGION=us-east-1
BEDROCK_REGION=us-east-1
ENABLE_TLS=true
GATEWAY_DOMAIN_NAME=codex-gateway.example.com
ROUTE53_HOSTED_ZONE_ID=Z0123456789EXAMPLE
ALB_CERTIFICATE_ARN=
ALLOWED_CIDR=203.0.113.10/32
ENABLE_WAF=true
DB_MULTI_AZ=true
DESIRED_COUNT=2
MIN_TASK_COUNT=2
MAX_TASK_COUNT=10

Execute a verificação prévia somente leitura:

make litellm-check

Construa a imagem LiteLLM revisada e envie para o Amazon ECR:

CONFIRM_AWS_WRITE=1 make litellm-build

Crie um conjunto de alterações do CloudFormation sem executá-lo:

make litellm-plan

Revise o conjunto de alterações e, em seguida, implante:

CONFIRM_AWS_WRITE=1 make litellm-deploy
make litellm-status

Criando uma identidade de gateway com escopo definido

Não distribua a chave mestra do LiteLLM para os desenvolvedores. Configure uma identidade de usuário ou equipe no arquivo de implantação:

CODEX_API_SECRET_ID=codex-litellm-gateway/alice-key
CODEX_KEY_ALIAS=alice@example.com
CODEX_KEY_USER_ID=alice@example.com
CODEX_KEY_MODELS=gpt-5.5
CODEX_KEY_MAX_BUDGET=50
CODEX_KEY_BUDGET_DURATION=30d
CODEX_KEY_TPM_LIMIT=100000
CODEX_KEY_RPM_LIMIT=1000

Provisione a chave:

CONFIRM_AWS_WRITE=1 make litellm-provision-key

O helper resolve a credencial mestra em um processo filho, chama a API /key/generate do LiteLLM com as políticas configuradas de modelo, orçamento e taxa, e grava a chave gerada diretamente em um segredo do Secrets Manager criptografado com KMS.

Configurando o Codex

Gere o bloco de provedor:

make litellm-codex-config

O helper lê o endpoint do gateway implantado a partir do CloudFormation e imprime a configuração de provedor do Codex. Adicione a saída ao arquivo de configuração em nível de usuário ~/.codex/config.toml. A configuração gerada tem este formato:

model = "gpt-5.5"
model_provider = "litellm-gateway"
web_search = "disabled"

[model_providers.litellm-gateway]
name = "LiteLLM Gateway"
base_url = "https://codex-gateway.example.com/v1"
wire_api = "responses"

[model_providers.litellm-gateway.auth]
command = "/absolute/path/to/python3"
args = [
  "/absolute/path/to/deployment/scripts/aws-secret-auth.py",
  "--aws-cli", "/absolute/path/to/aws",
  "--region", "us-east-1",
  "--secret-id", "codex-litellm-gateway/alice-key",
  "--field", "LITELLM_API_KEY",
  "--profile", "developer-profile",
  "print-token"
]
timeout_ms = 30000
refresh_interval_ms = 300000

Testando o Codex através do LiteLLM

Inicie uma sessão interativa do Codex e use /status para verificar que litellm-gateway é o provedor selecionado. Para um teste não interativo repetível, execute primeiro uma requisição mínima de verificação:

codex exec --sandbox read-only --ephemeral \
  "Reply with exactly LITELLM_GATEWAY_OK and no other text."

Em seguida, exercite o loop do agente com uma tarefa que exija tanto inferência de modelo quanto uma ferramenta local:

codex exec --sandbox read-only --ephemeral \
  "Read README.md with shell tools and summarize the deployment architecture. Do not modify files."

Validando o contrato da Responses API

Um prompt de texto bem-sucedido não prova que um fluxo de trabalho de agente é compatível. O Codex depende de mais do que uma resposta básica de chat. Execute a sonda estrita incluída:

make litellm-validate

A sonda verifica: campos obrigatórios do objeto Responses e formato de saída; continuação semântica com previous_response_id; streaming de eventos enviados pelo servidor com uma resposta terminal completa; e uma chamada de ferramenta forçada com ID de chamada.

O script de validação é um portão de compatibilidade, não um teste de carga. Antes da produção, também é importante testar sessões de agentes concorrentes, streams de longa duração, cancelamento de requisições, revogação de chaves, recuperação de falhas e pico de tráfego esperado.

Operacionalizando o LiteLLM para uso empresarial

A compatibilidade é apenas o ponto de partida. Antes de integrar desenvolvedores, é necessário definir como o gateway controlará o acesso ao modelo, atribuirá uso, aplicará política de consumo e fornecerá registro operacional para cada requisição.

Comece pela superfície de modelos que os desenvolvedores têm permissão de usar. Publique aliases de gateway estáveis apenas para modelos aprovados pela organização e fixe cada mapeamento upstream em deployment/litellm/litellm_config.yaml. Emita chaves com escopo separadas para usuários, equipes ou cargas de trabalho em vez de distribuir a chave mestra do LiteLLM.

A mesma identidade com escopo pode aplicar política de consumo. Defina CODEX_KEY_MAX_BUDGET, CODEX_KEY_BUDGET_DURATION, CODEX_KEY_TPM_LIMIT e CODEX_KEY_RPM_LIMIT ao provisionar uma chave.

Operar o gateway também requer uma visão do caminho completo de requisições. Monitore contagens de tarefas desejadas e em execução no ECS, rollback de implantação, saúde e latência do alvo do ALB, saúde do Amazon RDS, requisições e rejeições do LiteLLM, uso de tokens, gasto, acesso a segredos, mudanças de IAM e bloqueios do AWS WAF.

Implantações em produção devem habilitar o Amazon Bedrock Guardrails no caminho de acesso ao modelo para filtragem de conteúdo, detecção de tópicos negados e verificações de fundamentação. Os controles em nível de gateway (orçamentos, limites de taxa e roteamento) complementam, mas não substituem, as salvaguardas de IA responsável aplicadas na camada do modelo.

Caminhos alternativos de acesso

Acesso direto com IAM Identity Center

Use o provedor nativo amazon-bedrock do Codex quando identidade nativa da AWS e controles de auditoria forem suficientes:

model_provider = "amazon-bedrock"
model = "openai.gpt-5.5"

[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"
region = "us-east-1"

O desenvolvedor faz login com um perfil nomeado do IAM Identity Center:

aws sso login --profile codex-bedrock

Esse caminho remove o gateway, o banco de dados e as operações associadas. O guia de início rápido do IAM Identity Center do repositório inclui comandos CloudFormation e helpers para criar um grupo isolado e conjunto de permissões, atribuir o grupo a uma conta AWS, imprimir a configuração do cliente e validar o perfil autenticado contra o Amazon Bedrock.

Acesso gerenciado ou híbrido com Portkey

O Portkey pode ser útil quando o cliente deseja um plano de controle gerenciado, roteamento centralizado e política, ou um plano de dados híbrido suportado sem operar a pilha de referência do LiteLLM. Para uma avaliação do Codex, configure uma chave de workspace do Portkey, um provedor do Amazon Bedrock Model Catalog e o protocolo wire Responses:

model_provider = "portkey"
model = "@bedrock-validation/"

[model_providers.portkey]
name = "Portkey"
base_url = "https://api.portkey.ai/v1"
env_key = "PORTKEY_API_KEY"
wire_api = "responses"

Execute a mesma sonda estrita de Responses antes de promover para produção. Escolha o Portkey quando o modelo operacional gerenciado ou híbrido for mais importante do que executar o gateway inteiramente na sua conta AWS. Consulte o guia de início rápido de avaliação do Portkey para mais detalhes.

Limpeza dos recursos

Visualize o que o CloudFormation excluirá e reterá:

make litellm-cleanup-plan

Exclua o gateway somente após confirmar seu nome exato de pilha:

CONFIRM_STACK_DELETE=codex-litellm-gateway \
  make litellm-cleanup

A pilha de referência cria um snapshot final do Amazon RDS e retém chaves KMS, segredos do Secrets Manager, o grupo de logs do CloudWatch e o bucket de logs de acesso do ALB. Imagens do ECR e segredos de chaves com escopo provisionadas também ficam fora da exclusão da pilha. Revise e remova os recursos retidos de acordo com sua política de retenção de dados.

Conclusão

Rotear o Codex através do LiteLLM fornece um ponto de controle operado pelo cliente para seleção de modelos, identidade com escopo, orçamentos, limites de taxa e telemetria, preservando o modelo local de execução de tarefas e ferramentas do Codex. A porta de produção importante não é se um gateway pode retornar texto — é se o gateway preserva os comportamentos da Responses API que um fluxo de trabalho de agente precisa e se a equipe de sistema consegue operar a infraestrutura adicionada de forma confiável.

A recomendação é começar com acesso direto via IAM Identity Center quando os controles nativos da AWS atendem ao requisito. Adicionar o LiteLLM quando a política de gateway operada pelo cliente justificar o trabalho operacional. E avaliar o Portkey quando um modelo operacional gerenciado ou híbrido for o melhor encaixe organizacional — aplicando os mesmos testes de contrato a cada caminho.

Recursos adicionais

Fonte

Set up OpenAI ChatGPT Codex with LiteLLM on Amazon ECS and Amazon Bedrock (https://aws.amazon.com/blogs/machine-learning/set-up-openai-chatgpt-codex-with-litellm-on-amazon-ecs-and-amazon-bedrock/)