Python Agent para Gateway

O gerador connection pode conectar seu Python Agent a um AgentCore Gateway.

O gerador configura o agente para que ele se autentique no Gateway com IAM SigV4 (via assinatura de requisição httpx) quando implantado, e se conecte ao gateway local iniciado pelo projeto Gateway quando executado localmente.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

1. Um projeto Python com um componente Agent (infra: agentcore)
2. Um projeto agentcore-gateway com auth: iam

O Gateway deve usar autenticação IAM — o agente assina suas requisições com SigV4 usando sua própria função de execução. O gerador rejeita gateways autenticados com Cognito.

Uso

Executar o Gerador

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Selecione o projeto do agente como origem e o projeto Gateway como destino.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador emite módulos compartilhados core-gateway em seu projeto Python agent_connection, além de um wrapper por Gateway, e modifica seu agente:

• Directorypackages/common/agent_connection

  • Directory<scope>_agent_connection

    • Directorycore/

      • agentcore_endpoints.py Framework-agnostic ARN/URL resolution
      • agentcore_gateway_mcp_transport.py Framework-agnostic Gateway MCP transport
      • agentcore_gateway_mcp_client_<framework>.py Gateway MCP client for your agent’s framework
      • Directoryauth/ Framework-agnostic SigV4 / session-forwarding httpx.Auth

        • …
    • Directoryapp/

      • <gateway_snake>_client_<framework>.py Per-Gateway client wrapper
    • __init__.py Re-exports the Gateway client

O sufixo do cliente corresponde ao framework do seu agente (_strands ou _langchain).

Além disso, o gerador:

• Modifica o agent.py do seu agente para importar o cliente Gateway e registrar suas ferramentas em tools
• Adiciona agent_connection como uma dependência de workspace do agente
• Configura o target <agent>-dev do agente para depender do target dev do Gateway

Usando o Gateway conectado

O gerador transforma o agent.py do seu agente para usar o cliente Gateway:

Strands

packages/example/example/my_agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyGatewayClientStrands

@contextmanager
def get_agent():
    my_gateway = MyGatewayClientStrands.create()
    with (
        my_gateway,
    ):
        yield Agent(
            system_prompt="...",
            tools=[*my_gateway.list_tools_sync()],
        )

MyGatewayClientStrands.create() retorna um único MCPClient gerenciável por contexto cujo list_tools_sync() produz todas as ferramentas disponíveis através do Gateway.

LangChain

packages/example/example/my_agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyGatewayClientLangChain

def get_agent():
    my_gateway = MyGatewayClientLangChain.create()
    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[*my_gateway],
    )

MyGatewayClientLangChain.create() retorna uma lista de ferramentas carregadas via langchain-mcp-adapters. Cada ferramenta abre uma nova sessão por chamada, então nenhum bloco with é necessário.

Em ambos os casos, o cliente se comporta da mesma forma por modo:

• Modo implantado (LOCAL_DEV não definido): ferramentas apontadas para o endpoint MCP do Gateway, assinadas com SigV4.
• Modo local (LOCAL_DEV=true): ferramentas HTTP simples apontadas para o gateway local iniciado pelo target dev do projeto Gateway.

O ID da sessão é propagado automaticamente para servidores MCP downstream via o cabeçalho X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infraestrutura

Após executar o gerador, você deve conceder ao agente permissão para invocar o Gateway.

CDK

packages/infra/src/stacks/application-stack.ts

const gateway = new MyGateway(this, 'MyGateway');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

A URL do Gateway é automaticamente registrada no namespace agentcore.gateways.<ClassName> da Runtime Configuration pelo construto CDK gerado, para que o agente possa descobri-la em tempo de execução.

Terraform

packages/infra/src/main.tf

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  # Grant the agent permission to invoke the Gateway
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

A URL do Gateway é automaticamente registrada no namespace agentcore.gateways.<ClassName> da Runtime Configuration pelo módulo Terraform gerado, para que o agente possa descobri-la em tempo de execução.

Desenvolvimento Local

O gerador configura o target dev do agente para:

1. Iniciar o gateway local do Gateway conectado e todos os servidores MCP anexados
2. Definir LOCAL_DEV=true para que o cliente gerado aponte para o gateway local em vez do Gateway implantado

Execute o agente localmente com:

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

Para executar o agente localmente contra o Gateway implantado (por exemplo, para exercitar políticas Cedar), use o target serve do agente. Sem LOCAL_DEV definido, o cliente resolve a URL do Gateway implantado a partir da configuração de tempo de execução e assina requisições com SigV4 usando suas credenciais AWS locais:

pnpm

pnpm nx <agent-name>-serve <project-name>

yarn

yarn nx <agent-name>-serve <project-name>

npm

npx nx <agent-name>-serve <project-name>

bun

bunx nx <agent-name>-serve <project-name>

Fidelidade local

O gateway local substitui o Gateway implantado, então:

• Sem avaliação de política Cedar. Todas as ferramentas são visíveis para o agente independentemente das políticas. Use o target serve para exercitar políticas contra o Gateway implantado.
• A prefixação de nomes de ferramentas é preservada. As ferramentas de cada servidor MCP local são expostas como <target-name>___<tool-name>, correspondendo ao que o Gateway implantado emite. Isso mantém o prompt do sistema do agente e os nomes de ação Cedar que você referencia consistentes entre execuções locais e implantadas.