Python Agent에서 A2A Agent로

connection 생성기는 Python Agent를 원격 A2A 에이전트(TypeScript 또는 Python)에 연결하여, 에이전트가 다른 에이전트를 도구로 위임할 수 있도록 합니다.

생성기는 에이전트가 원격 A2A 에이전트를 발견하고 호출할 수 있도록 필요한 모든 배선을 설정하며, AWS에 배포된 경우(Bedrock AgentCore를 통해)와 로컬에서 실행되는 경우 모두 작동합니다.

전제 조건

이 생성기를 사용하기 전에 다음을 준비해야 합니다:

Python Agent 컴포넌트가 있는 Python 프로젝트 (Strands 또는 LangChain)
--protocol=A2A 및 --auth=IAM으로 생성된 Agent 컴포넌트가 있는 프로젝트 (ts#agent 또는 py#agent)
infra: agentcore으로 생성된 두 컴포넌트

사용법

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

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

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

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

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

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

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

호스트 에이전트 프로젝트를 소스로 선택하고 A2A 에이전트 프로젝트를 대상으로 선택합니다. 프로젝트에 여러 컴포넌트가 포함된 경우 sourceComponent 및 targetComponent 옵션을 지정하여 명확히 구분합니다.

옵션

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

생성기 출력

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

디렉터리packages/common/agent_connection
- 디렉터리<scope>_agent_connection
  - __init__.py 연결별 클라이언트 재내보내기
  - 디렉터리core
    agentcore_endpoints.py 프레임워크 독립적인 ARN/URL 해석
    agentcore_a2a_client_config.py 프레임워크 독립적인 A2A 클라이언트 구성 (서명된 ClientConfig)
    agentcore_a2a_client_<framework>.py 에이전트의 프레임워크를 위한 구성을 래핑하는 A2A 클라이언트
    디렉터리auth/ 프레임워크 독립적인 SigV4 / 세션 전달 httpx.Auth
    …
  - 디렉터리app
    <target_agent_name>_client_<framework>.py 각 A2A 에이전트에 대한 연결별 A2A 클라이언트

클라이언트 접미사는 에이전트의 프레임워크(_strands 또는 _langchain)와 일치합니다. 두 클라이언트 모두 동일한 프레임워크 독립적인 서명된 ClientConfig를 래핑합니다: Strands 클라이언트는 Strands A2AAgent를 래핑하고, LangChain 클라이언트는 a2a SDK를 직접 구동하므로 LangChain 에이전트는 Strands 의존성을 포함하지 않습니다.

또한 생성기는:

에이전트의 agent.py를 변환하여 원격 A2A 에이전트를 @tool을 사용하여 도구로 등록합니다
agent_connection 프로젝트를 에이전트 프로젝트의 워크스페이스 의존성으로 추가합니다
에이전트의 serve-local 대상을 대상 에이전트의 serve-local 대상에 의존하도록 업데이트합니다

연결된 A2A 에이전트 사용

생성기는 에이전트의 agent.py를 변환하여 원격 A2A 에이전트를 도구로 래핑합니다. 원격 에이전트는 @tool로 장식된 델리게이트로 등록되며 — 데코레이터의 import와 에이전트 생성자는 프레임워크에 따라 다릅니다:

Strands
LangChain

from contextlib import contextmanager
from strands import Agent, tool

from my_scope_agent_connection import RemoteAgentClientStrands

@contextmanager
def get_agent():
    remote_agent = RemoteAgentClientStrands.create()

    @tool
    def ask_remote_agent(prompt: str) -> str:
        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
        return str(remote_agent(prompt))

    yield Agent(
        system_prompt="...",
        tools=[ask_remote_agent],
    )

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

from my_scope_agent_connection import RemoteAgentClientLangChain

def get_agent():
    remote_agent = RemoteAgentClientLangChain.create()

    @tool
    def ask_remote_agent(prompt: str) -> str:
        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
        return str(remote_agent(prompt))

    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[ask_remote_agent],
    )

두 클라이언트 모두 직접 호출 가능하며 원격 에이전트의 응답을 반환하고, AWS에 배포된 경우 SigV4로 요청에 서명하고 LOCAL_DEV=true인 경우 일반 http://localhost:<port>/ 엔드포인트를 사용하는 httpx.AsyncClient를 래핑합니다. Strands 클라이언트는 Strands A2AAgent를 래핑하고, LangChain 클라이언트는 a2a SDK를 직접 구동합니다.

AgentCore 세션 ID는 프레임워크에 관계없이 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 헤더를 통해 원격 에이전트로 자동으로 전파됩니다: 에이전트 서버는 인바운드 요청의 세션을 비동기 컨텍스트에 바인딩하고, 연결 클라이언트의 서명된 httpx.Auth는 모든 아웃바운드 호출에 이를 스탬프하여 Bedrock AgentCore Observability의 일관성을 보장합니다.

인프라

연결 생성기를 실행한 후, 호스트 에이전트에게 원격 A2A 에이전트를 호출할 수 있는 권한을 부여해야 합니다.

CDK
Terraform

const remoteAgent = new RemoteAgent(this, 'RemoteAgent');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the host agent permission to invoke the remote A2A agent
remoteAgent.grantInvokeAccess(myAgent);

A2A 에이전트의 grantInvokeAccess는 bedrock-agentcore:InvokeAgentRuntime과 bedrock-agentcore:GetAgentCard 모두를 연결합니다 — A2A 클라이언트는 에이전트 카드를 가져오고 메시지를 전송하기 위해 두 가지 모두가 필요합니다.

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

module "remote_agent" {
  source = "../../common/terraform/src/app/agents/remote-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

# Grant the host agent permission to invoke the remote A2A agent
resource "aws_iam_policy" "agent_invoke_a2a" {
  name = "AgentInvokeA2aPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = module.remote_agent.agent_core_runtime_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_a2a" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_a2a.arn
}

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

로컬 개발

생성기는 호스트 에이전트의 serve-local 대상을 다음과 같이 구성합니다:

연결된 A2A 에이전트를 자동으로 시작
SERVE_LOCAL=true를 설정하여 생성된 클라이언트가 AgentCore 대신 http://localhost:<port>/에 직접 연결

다음 명령으로 에이전트를 로컬에서 실행합니다:

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>

이렇게 하면 호스트 에이전트와 연결된 모든 A2A 에이전트가 시작되며, 호스트 에이전트는 할당된 로컬 포트에서 일반 HTTP를 통해 원격 에이전트를 호출합니다.