Python Agent a Gateway

Il generatore connection può connettere il tuo Python Agent a un AgentCore Gateway.

Il generatore configura l’agent in modo che si autentichi al Gateway con IAM SigV4 (tramite la firma delle richieste httpx) quando distribuito, e si connetta al gateway locale avviato dal progetto Gateway quando eseguito localmente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto Python con un componente Agent (infra: agentcore)
2. Un progetto agentcore-gateway con protocol: mcp e auth: iam

Il Gateway deve servire il protocollo mcp — l’agent lo raggiunge come client MCP, quindi i suoi target sono esposti come strumenti. Il Gateway deve anche utilizzare l’autenticazione IAM: l’agent firma le sue richieste con SigV4 utilizzando il proprio ruolo di esecuzione. Il generatore rifiuta i gateway autenticati con Cognito.

Una direzione per Gateway

Un singolo Gateway non può essere sia chiamato da un agent che fronteggiarne uno. Fronteggiare i runtime degli agent richiede protocol: http (vedi Gateway a Agent), mentre essere chiamato da un agent richiede protocol: mcp. Utilizza un Gateway separato per ogni direzione.

Utilizzo

Esegui il Generatore

Esegui questo generatore@aws/nx-plugin:connection

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

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Seleziona il progetto agent come sorgente e il progetto Gateway come destinazione.

Opzioni

Opzioni del generatore5 opzioni

sourceProjectObbligatoriostring

Il progetto sorgente

targetProjectObbligatoriostring

Il progetto di destinazione a cui connettersi

sourceComponentstring

Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come sorgente.

targetComponentstring

Il componente destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto destinazione, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come destinazione.

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore emette moduli core-gateway condivisi nel tuo progetto Python agent_connection, più un wrapper per-Gateway, e modifica il tuo agent:

• Directorypackages/common/agent_connection

  • Directory<scope>_agent_connection

    • Directorycore/

      • __init__.py Inizializzazione del package Python
      • agentcore_endpoints.py Risoluzione ARN/URL indipendente dal framework
      • agentcore_transport.py Plumbing di trasporto AgentCore condiviso
      • agentcore_gateway_mcp_transport.py Trasporto MCP Gateway indipendente dal framework
      • agentcore_gateway_mcp_client_<framework>.py Client MCP Gateway per il framework del tuo agent
      • Directoryauth/ httpx.Auth SigV4 / session-forwarding indipendente dal framework

        • …
    • Directoryapp/

      • __init__.py Inizializzazione del package Python
      • <gateway_snake>_client_<framework>.py Wrapper client per-Gateway
    • __init__.py Ri-esporta il client Gateway

Il suffisso del client corrisponde al framework del tuo agent (_strands o _langchain).

Inoltre, il generatore:

• Modifica il file agent.py del tuo agent per importare il client Gateway e registrare i suoi strumenti in tools
• Aggiunge agent_connection come dipendenza workspace dell’agent
• Configura il target <agent>-dev dell’agent per dipendere dal target dev del Gateway

Utilizzo del Gateway connesso

Il generatore trasforma il file agent.py del tuo agent per utilizzare il client 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() restituisce un singolo MCPClient gestibile tramite context manager il cui list_tools_sync() produce ogni strumento disponibile attraverso il 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() restituisce una lista di strumenti caricati tramite langchain-mcp-adapters. Ogni strumento apre una nuova sessione per chiamata, quindi non è necessario un blocco with.

In entrambi i casi il client si comporta allo stesso modo per modalità:

• Modalità distribuita (LOCAL_DEV non impostato): strumenti puntati all’endpoint MCP del Gateway, firmati con SigV4.
• Modalità locale (LOCAL_DEV=true): strumenti HTTP semplici puntati al gateway locale avviato dal target dev del progetto Gateway.

L’ID di sessione viene propagato automaticamente ai server MCP downstream tramite l’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infrastruttura

Dopo aver eseguito il generatore devi concedere all’agent il permesso di invocare il 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);

L’URL del Gateway viene automaticamente registrato nel namespace agentcore.gateways.<ClassName> della Runtime Configuration dal costrutto CDK generato, così l’agent può scoprirlo a runtime.

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]
  }]
}

L’URL del Gateway viene automaticamente registrato nel namespace agentcore.gateways.<ClassName> della Runtime Configuration dal modulo Terraform generato, così l’agent può scoprirlo a runtime.

Sviluppo Locale

Il generatore configura il target dev dell’agent per:

1. Avviare il gateway locale del Gateway connesso e ogni server MCP collegato
2. Impostare LOCAL_DEV=true in modo che il client generato punti al gateway locale invece del Gateway distribuito

Esegui l’agent localmente con:

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>

Per eseguire l’agent localmente contro il Gateway distribuito invece (ad esempio, per esercitare le policy Cedar), utilizza il target serve dell’agent. Senza LOCAL_DEV impostato, il client risolve l’URL del Gateway distribuito dalla configurazione runtime e firma le richieste con SigV4 utilizzando le tue credenziali AWS locali:

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>

Fedeltà locale

Il gateway locale sostituisce il Gateway distribuito, quindi:

• Nessuna valutazione delle policy Cedar. Ogni strumento è visibile all’agent indipendentemente dalle policy. Utilizza il target serve per esercitare le policy contro il Gateway distribuito.
• Il prefisso dei nomi degli strumenti è preservato. Gli strumenti di ogni server MCP locale sono esposti come <target-name>___<tool-name>, corrispondendo a ciò che emette il Gateway distribuito. Questo mantiene il prompt di sistema dell’agent e i nomi delle azioni Cedar a cui fai riferimento coerenti tra esecuzioni locali e distribuite.