Python Agent a MCP

Il generatore connection può connettere il tuo Python Agent a un server MCP (sia TypeScript che Python).

Il generatore configura tutti i collegamenti necessari in modo che il tuo agente possa scoprire e invocare gli strumenti del server MCP, sia quando viene distribuito su AWS (tramite Bedrock AgentCore) che quando viene eseguito localmente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto Python con un componente Python Agent (Strands o LangChain)
2. Un progetto con un componente server MCP (sia ts#mcp-server che py#mcp-server)
3. Entrambi i componenti creati con infra: agentcore

Utilizzo

Eseguire il Generatore

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

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Seleziona il tuo progetto agente come sorgente e il tuo progetto server MCP come destinazione. Se i tuoi progetti contengono più componenti, specifica le opzioni sourceComponent e targetComponent per disambiguare.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	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 crea un progetto Python condiviso agent_connection in packages/common/agent_connection/ (se non esiste già). I moduli client per-connessione vengono generati in questo progetto condiviso:

• Directorypackages/common/agent_connection

  • Directory<scope>_agent_connection

    • __init__.py Ri-esporta i client per-connessione
    • Directorycore

      • agentcore_endpoints.py Risoluzione ARN/URL framework-agnostic
      • agentcore_mcp_transport.py Trasporto MCP framework-agnostic
      • agentcore_mcp_client_<framework>.py Client MCP che avvolge il trasporto per il framework del tuo agente
      • Directoryauth/ httpx.Auth framework-agnostic per SigV4 / session-forwarding

        • …
    • Directoryapp

      • <mcp_server_name>_client_<framework>.py Client per-connessione per ogni server MCP

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

Inoltre, il generatore:

• Trasforma il file agent.py del tuo agente per importare e utilizzare gli strumenti del server MCP tramite un client basato su classi
• Aggiunge il progetto agent_connection come dipendenza del workspace del tuo progetto agente
• Aggiorna il target dev dell’agente per dipendere dal target serve del server MCP

Utilizzo del Server MCP Connesso

Il generatore trasforma il file agent.py del tuo agente per utilizzare gli strumenti del server MCP:

Strands

packages/my-project/my_module/agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyMcpServerClientStrands

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

Il client Strands è un context manager, inserito in un blocco with attorno all’agente.

LangChain

packages/my-project/my_module/agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyMcpServerClientLangChain

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

Il client LangChain restituisce una lista di strumenti caricati tramite langchain-mcp-adapters. Ogni strumento apre una nuova sessione MCP per chiamata, quindi gli strumenti rimangono utilizzabili per tutta la durata dell’agente — non è necessario un blocco with.

L’ID di sessione AgentCore viene propagato automaticamente al server MCP tramite l’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id per entrambi i framework, garantendo la coerenza per Bedrock AgentCore Observability.

Infrastruttura

CDK

Dopo aver eseguito il generatore di connessione, devi concedere all’agente il permesso di invocare il server MCP:

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

const mcpServer = new MyMcpServer(this, 'MyMcpServer');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the MCP server
mcpServer.grantInvokeAccess(myAgent);

L’ARN del runtime AgentCore del server MCP viene registrato automaticamente nel namespace agentcore della Runtime Configuration dal costrutto CDK generato, in modo che l’agente possa scoprirlo a runtime.

Terraform

Dopo aver eseguito il generatore di connessione, devi concedere all’agente il permesso di invocare il server MCP nella tua configurazione Terraform:

packages/infra/src/main.tf

module "inventory_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
}

module "story_agent" {
  source = "../../common/terraform/src/app/agents/story-agent"
}

# Grant the agent permissions to invoke the MCP server
resource "aws_iam_policy" "agent_invoke_mcp" {
  name = "AgentInvokeMcpPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeAgent"
      Resource = module.inventory_mcp_server.agent_core_runtime_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
  role       = module.story_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
}

L’ARN del runtime AgentCore del server MCP viene registrato automaticamente nel namespace agentcore della Runtime Configuration dal modulo Terraform generato, in modo che l’agente possa scoprirlo a runtime.

Sviluppo Locale

Il generatore configura il target dev dell’agente per:

1. Avviare automaticamente i server MCP connessi
2. Impostare LOCAL_DEV=true in modo che il client generato utilizzi il trasporto HTTP diretto invece di AgentCore

Esegui l’agente 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>

Questo avvierà sia l’agente che tutti i server MCP connessi, con l’agente che si connette ai server MCP direttamente tramite HTTP sulle loro porte locali assegnate.