TypeScript Strands Agent에서 A2A Agent로

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

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

사전 요구사항

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

Strands Agent 컴포넌트(모든 프로토콜)가 있는 TypeScript 프로젝트
--protocol=A2A 및 --auth=IAM으로 생성된 Strands Agent 컴포넌트가 있는 프로젝트(ts#strands-agent 또는 py#strands-agent)
computeType: BedrockAgentCoreRuntime으로 생성된 두 컴포넌트

사용법

설치 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). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.

생성기 출력

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

디렉터리packages/common/agent-connection
- 디렉터리src
  - 디렉터리app
    <target-agent-name>-client.ts 연결된 A2A 에이전트용 고수준 클라이언트
  - 디렉터리core
    agentcore-a2a-client.ts SigV4 인증을 사용하는 저수준 AgentCore A2A 클라이언트
  - index.ts 모든 클라이언트 내보내기
- project.json
- tsconfig.json

또한 다음을 수행합니다:

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

연결된 A2A 에이전트 사용

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

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

export const getAgent = async (sessionId: string) => {
  const remoteAgent = await RemoteAgentClient.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의 일관성을 보장합니다.

내부적으로 RemoteAgentClient.create(sessionId)는 AWS에 배포되었을 때 SigV4 서명 clientFactory로 구성된 Strands A2AAgent를 반환하고, SERVE_LOCAL=true일 때는 일반 http://localhost:<port>/ 엔드포인트를 반환합니다.

인프라

연결 생성기를 실행한 후, 호스트 에이전트에게 원격 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"
}

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

# 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>-serve-local <project-name>

yarn nx <agent-name>-serve-local <project-name>

npx nx <agent-name>-serve-local <project-name>

bunx nx <agent-name>-serve-local <project-name>

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