TypeScript Agent에서 Gateway로

connection 생성기는 TypeScript Agent를 AgentCore Gateway에 연결할 수 있습니다.

생성기는 배포 시 IAM SigV4로 Gateway에 인증하고, 로컬 실행 시 Gateway 프로젝트에서 시작된 로컬 게이트웨이에 연결하도록 에이전트를 구성합니다.

사전 요구 사항

이 생성기를 사용하기 전에 다음이 필요합니다:

Agent 컴포넌트가 있는 TypeScript 프로젝트 (infra: agentcore)
agentcore-gateway 프로젝트 (auth: iam 사용)

Gateway는 IAM 인증을 사용해야 합니다 — 에이전트는 자체 실행 역할을 사용하여 SigV4로 요청에 서명합니다. 생성기는 Cognito 인증 게이트웨이를 거부합니다.

사용법

설치 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

소스로 에이전트 프로젝트를 선택하고 대상으로 Gateway 프로젝트를 선택합니다.

옵션

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

생성기 출력

생성기는 agent-connection 패키지에 공유 코어 클라이언트 파일과 Gateway별 래퍼를 생성하고 에이전트를 수정합니다:

디렉터리packages/common/agent-connection
- 디렉터리src
  - 디렉터리core/
    agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
    agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
    agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
  - 디렉터리app/
    <gateway-kebab>-client-strands.ts Gateway별 Strands 클라이언트 래퍼
  - index.ts Gateway 클라이언트를 재내보냄

또한 생성기는:

에이전트의 agent.ts를 수정하여 Gateway 클라이언트 클래스를 가져오고, <Gateway>ClientStrands.create()를 호출하며, 반환된 클라이언트를 tools 배열에 등록합니다
에이전트의 <agent>-dev 타겟이 Gateway의 dev 타겟에 의존하도록 연결합니다
필요한 SigV4 / MCP 종속성을 설치합니다

연결된 Gateway 사용

생성기는 에이전트의 agent.ts를 변환하여 Gateway 클라이언트를 사용합니다:

import { Agent } from '@strands-agents/sdk';
import { MyGatewayClientStrands } from '@my-scope/agent-connection';

export const getAgent = async () => {
  const myGateway = await MyGatewayClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myGateway],
  });
};

배포 시 (SERVE_LOCAL 미설정), 클라이언트는 Gateway의 MCP 엔드포인트를 가리키고 SigV4로 인증합니다. SERVE_LOCAL=true일 때는 Gateway 프로젝트의 serve-local 타겟에서 시작된 로컬 게이트웨이를 가리키므로 동일한 agent.ts가 두 모드에서 균일하게 작동합니다.

세션 ID는 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 헤더를 통해 다운스트림 MCP 서버로 자동으로 전파됩니다.

인프라

생성기를 실행한 후 에이전트에 Gateway를 호출할 권한을 부여해야 합니다.

CDK
Terraform

const gateway = new MyGateway(this, 'MyGateway');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

Gateway URL은 생성된 CDK 구성에 의해 Runtime Configuration의 agentcore.gateways.<ClassName> 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

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

  # Grant the agent permission to invoke the Gateway
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

Gateway URL은 생성된 Terraform 모듈에 의해 Runtime Configuration의 agentcore.gateways.<ClassName> 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

로컬 개발

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

연결된 Gateway의 로컬 게이트웨이와 연결된 모든 MCP 서버 시작
SERVE_LOCAL=true로 설정하여 생성된 클라이언트가 배포된 Gateway 대신 로컬 게이트웨이를 가리키도록 함

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

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>

배포된 Gateway에 대해 에이전트를 로컬에서 실행하려면(예: Cedar 정책을 실행하기 위해) 에이전트의 serve 타겟을 사용합니다. SERVE_LOCAL이 설정되지 않으면 클라이언트는 런타임 구성에서 배포된 Gateway URL을 확인하고 로컬 AWS 자격 증명으로 요청에 SigV4 서명합니다:

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

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

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

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

로컬 충실도

로컬 게이트웨이는 배포된 Gateway를 대신하므로:

Cedar 정책 평가 없음. 정책에 관계없이 모든 도구가 에이전트에 표시됩니다. 배포된 Gateway에 대해 정책을 실행하려면 serve 타겟을 사용하세요.
도구 이름 접두사는 유지됨. 각 로컬 MCP 서버의 도구는 <target-name>___<tool-name> 형식의 이름을 노출하도록 래핑되어 배포된 Gateway가 내보내는 것과 일치합니다. 이를 통해 에이전트의 시스템 프롬프트와 참조하는 Cedar 액션 이름이 로컬 및 배포된 실행에서 일관되게 유지됩니다.