TypeScript Agent에서 Gateway로

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

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

사전 요구 사항

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

Agent 컴포넌트(infra: agentcore)가 있는 TypeScript 프로젝트
protocol: mcp 및 auth: iam이 설정된 agentcore-gateway 프로젝트

Gateway는 mcp 프로토콜을 제공해야 합니다 — 에이전트는 MCP 클라이언트로서 Gateway에 접근하므로 Gateway의 타겟이 도구로 노출됩니다. Gateway는 또한 IAM 인증을 사용해야 합니다: 에이전트는 자체 실행 역할을 사용하여 SigV4로 요청에 서명합니다. 생성기는 Cognito 인증 게이트웨이를 거부합니다.

사용법

생성기 실행

이 제너레이터 실행@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어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

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

옵션

제너레이터 옵션5 옵션

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

생성기 출력

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

디렉터리packages/common/agent-connection
- 디렉터리src
  - 디렉터리core/
    agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
    agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
    agentcore-transport.ts Shared AgentCore transport plumbing
    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 Per-Gateway Strands client wrapper
  - index.ts Re-exports the Gateway client

또한 생성기는:

에이전트의 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],
  });
};

배포될 때(LOCAL_DEV 미설정), 클라이언트는 Gateway의 MCP 엔드포인트를 가리키고 SigV4로 인증합니다. LOCAL_DEV=true일 때는 Gateway 프로젝트의 dev 타겟에서 시작한 로컬 게이트웨이를 가리키므로 동일한 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 구성에 의해 런타임 구성의 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 모듈에 의해 런타임 구성의 agentcore.gateways.<ClassName> 네임스페이스에 자동으로 등록되므로 에이전트가 런타임에 이를 검색할 수 있습니다.

로컬 개발

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

연결된 Gateway의 로컬 게이트웨이와 연결된 모든 MCP 서버를 시작합니다
LOCAL_DEV=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 타겟을 사용합니다. LOCAL_DEV가 설정되지 않으면 클라이언트는 런타임 구성에서 배포된 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 액션 이름이 로컬 및 배포된 실행에서 일관되게 유지됩니다.