TypeScript Agent에서 A2A Agent로

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

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

전제 조건

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

Strands Agent 컴포넌트가 있는 TypeScript 프로젝트(모든 프로토콜)
--protocol=a2a 및 --auth=iam으로 생성된 Agent 컴포넌트가 있는 프로젝트(ts#agent 또는 py#agent)
infra: agentcore로 생성된 두 컴포넌트

사용법

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

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

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

옵션

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

생성기 출력

생성기는 공유 agent-connection 패키지를 생성하고 에이전트 코드를 수정합니다:

디렉터리packages/common/agent-connection
- 디렉터리src
  - 디렉터리app
    <target-agent-name>-client-strands.ts 연결된 A2A 에이전트를 위한 고수준 Strands 클라이언트
  - 디렉터리core
    agentcore-endpoints.ts 프레임워크 독립적인 ARN/URL 해석
    agentcore-fetch.ts 프레임워크 독립적인 SigV4 / JWT / 세션 전달 fetch
    agentcore-a2a-client-config.ts 프레임워크 독립적인 A2A 클라이언트 구성(서명된 clientFactory)
    agentcore-a2a-client-strands.ts 구성을 래핑하는 Strands A2A 클라이언트
  - index.ts 모든 클라이언트 내보내기
- project.json
- tsconfig.json

또한 다음을 수행합니다:

에이전트의 agent.ts를 변환하여 원격 A2A 에이전트를 Strands tool로 등록
에이전트의 dev 타겟을 업데이트하여 타겟 에이전트의 dev 타겟에 의존하도록 설정
필요한 종속성 설치

연결된 A2A Agent 사용

생성기는 에이전트의 agent.ts를 변환하여 원격 A2A 에이전트를 도구로 래핑합니다:

import { Agent, tool } from '@strands-agents/sdk';
import { RemoteAgentClientStrands } from '@my-scope/agent-connection';
import { z } from 'zod';

export const getAgent = async (sessionId: string) => {
  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
  const remoteAgentTool = tool({
    name: 'askRemoteAgent',
    description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
    inputSchema: z.object({ prompt: z.string() }),
    callback: async ({ prompt }) => (await remoteAgent.invoke(prompt)).toString(),
  });
  return new Agent({
    systemPrompt: '...',
    tools: [remoteAgentTool],
  });
};

sessionId 매개변수는 호출자로부터 전달되어 Bedrock AgentCore Observability의 일관성을 보장합니다.

내부적으로 RemoteAgentClientStrands.create(sessionId)는 AWS에 배포된 경우 SigV4 서명 clientFactory로 구성된 Strands A2AAgent를 반환하고, LOCAL_DEV=true인 경우 일반 http://localhost:<port>/ 엔드포인트를 반환합니다. 서명 및 엔드포인트 해석은 프레임워크 독립적인 agentcore-a2a-client-config.ts에 있으며, 얇은 agentcore-a2a-client-strands.ts만 Strands에 의존합니다.

인프라

연결 생성기를 실행한 후, 호스트 에이전트에게 원격 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 구성에 의해 런타임 구성의 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 모듈에 의해 런타임 구성의 agentcore 네임스페이스에 자동으로 등록되므로, 호스트 에이전트가 런타임에 이를 검색할 수 있습니다.

로컬 개발

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

연결된 A2A 에이전트를 자동으로 시작
LOCAL_DEV=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를 통해 원격 에이전트를 호출합니다.