Python Agent에서 MCP로

connection 생성기는 Python Agent를 MCP 서버(TypeScript 또는 Python)에 연결할 수 있습니다.

생성기는 에이전트가 MCP 서버의 도구를 검색하고 호출할 수 있도록 필요한 모든 연결을 설정합니다. AWS에 배포된 경우(Bedrock AgentCore를 통해)와 로컬에서 실행되는 경우 모두에서 작동합니다.

전제 조건

이 생성기를 사용하기 전에 다음을 확인하세요:

Python Agent 컴포넌트(Strands 또는 LangChain)가 있는 Python 프로젝트
MCP 서버 컴포넌트(ts#mcp-server 또는 py#mcp-server)가 있는 프로젝트
두 컴포넌트 모두 infra: agentcore로 생성됨

사용법

생성기 실행

이 제너레이터 실행@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
VSCode에서 Nx 콘솔 열기
클릭 Generate (UI) "Common Nx Commands" 섹션에서
검색 @aws/nx-plugin - connection
필수 매개변수 입력
클릭 Generate

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-run어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

소스로 에이전트 프로젝트를 선택하고 타겟으로 MCP 서버 프로젝트를 선택하세요. 프로젝트에 여러 컴포넌트가 포함된 경우 sourceComponent 및 targetComponent 옵션을 지정하여 명확히 구분하세요.

옵션

제너레이터 옵션5 옵션

sourceProject필수string: 소스 프로젝트
targetProject필수string: 연결할 대상 프로젝트
sourceComponentstring: 연결할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponentstring: 연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependenciesboolean기본값: true: 생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

생성기는 packages/common/agent_connection/에 공유 agent_connection Python 프로젝트를 생성합니다(아직 존재하지 않는 경우). 연결별 클라이언트 모듈은 이 공유 프로젝트에 생성됩니다:

디렉터리packages/common/agent_connection
- 디렉터리<scope>_agent_connection
  - __init__.py 연결별 클라이언트를 재내보냄
  - 디렉터리core
    __init__.py Python package initialization
    agentcore_endpoints.py 프레임워크 독립적인 ARN/URL 해석
    agentcore_transport.py Shared AgentCore transport plumbing
    agentcore_mcp_transport.py 프레임워크 독립적인 MCP 전송
    agentcore_mcp_client_<framework>.py 에이전트 프레임워크용 전송을 래핑하는 MCP 클라이언트
    디렉터리auth/ 프레임워크 독립적인 SigV4 / 세션 전달 httpx.Auth
    …
  - 디렉터리app
    __init__.py Python package initialization
    <mcp_server_name>_client_<framework>.py 각 MCP 서버에 대한 연결별 클라이언트

클라이언트 접미사는 에이전트의 프레임워크(_strands 또는 _langchain)와 일치합니다.

또한 생성기는:

에이전트의 agent.py를 변환하여 클래스 기반 클라이언트를 통해 MCP 서버의 도구를 가져오고 사용
agent_connection 프로젝트를 에이전트 프로젝트의 워크스페이스 종속성으로 추가
에이전트의 dev 타겟을 업데이트하여 MCP 서버의 serve 타겟에 의존하도록 설정

연결된 MCP 서버 사용

생성기는 에이전트의 agent.py를 변환하여 MCP 서버의 도구를 사용합니다:

Strands
LangChain

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()],
        )

Strands 클라이언트는 컨텍스트 매니저이며, 에이전트 주변의 with 블록에서 진입합니다.

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],
    )

LangChain 클라이언트는 langchain-mcp-adapters를 통해 로드된 도구 목록을 반환합니다. 각 도구는 호출당 새로운 MCP 세션을 열기 때문에 도구는 에이전트의 수명 동안 사용 가능한 상태로 유지됩니다. with 블록이 필요하지 않습니다.

AgentCore 세션 ID는 두 프레임워크 모두에서 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 헤더를 통해 MCP 서버로 자동으로 전파되어 Bedrock AgentCore Observability의 일관성을 보장합니다.

인프라

CDK
Terraform

연결 생성기를 실행한 후 에이전트가 MCP 서버를 호출할 수 있는 권한을 부여해야 합니다:

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

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

grantInvokeAccess는 MCP 서버의 런타임 ARN에 AgentCore 호출 작업(InvokeAgentRuntime, InvokeAgentRuntimeForUser 및 InvokeAgentRuntimeWithWebSocketStream)을 연결합니다.

MCP 서버의 AgentCore 런타임 ARN은 생성된 CDK 구성에 의해 런타임 구성의 agentcore 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

연결 생성기를 실행한 후 Terraform 구성에서 에이전트가 MCP 서버를 호출할 수 있는 권한을 부여해야 합니다:

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:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.inventory_mcp_server.agent_core_runtime_arn,
        "${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
}

MCP 서버의 AgentCore 런타임 ARN은 생성된 Terraform 모듈에 의해 런타임 구성의 agentcore 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

로컬 개발

생성기는 에이전트의 dev 타겟을 다음과 같이 구성합니다:

연결된 MCP 서버를 자동으로 시작
LOCAL_DEV=true를 설정하여 생성된 클라이언트가 AgentCore 대신 직접 HTTP 전송을 사용하도록 설정

다음 명령으로 에이전트를 로컬에서 실행하세요:

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

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

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

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

이렇게 하면 에이전트와 연결된 모든 MCP 서버가 시작되며, 에이전트는 할당된 로컬 포트에서 HTTP를 통해 MCP 서버에 직접 연결됩니다.