AgentCore Gateway에서 Agent로

connection 제너레이터는 에이전트(TypeScript 또는 Python)를 protocol: http로 생성된 AgentCore Gateway의 AgentCore Runtime target으로 등록할 수 있습니다.

연결되면 Gateway는 <gatewayUrl>/<targetName>/invocations 경로로 에이전트에 대한 요청을 프록시하며, IAM SigV4로 런타임에 대한 아웃바운드 트래픽에 서명합니다. 이를 통해 에이전트에 단일 관리 진입점을 제공하며, 호출자는 Gateway에만 도달하면 되므로 에이전트 런타임 자체는 Gateway 뒤의 VPC 내부에 배포할 수 있습니다.

사전 요구 사항

이 제너레이터를 사용하기 전에 다음을 확인하세요:

1. protocol: http로 생성된 agentcore-gateway 프로젝트
2. infra: agentcore로 생성된 에이전트 컴포넌트(ts#agent 또는 py#agent). auth: iam(Gateway가 자체 역할로 호출) 또는 auth: cognito(Gateway가 호출자의 JWT를 전달 — 호출자 신원을 런타임으로 전달하기 참조) 모두 작동합니다.

TypeScript HTTP 에이전트

TypeScript http 에이전트는 WebSocket을 통해 tRPC를 제공하며, AgentCore Gateway는 WebSocket 또는 양방향 스트리밍을 지원하지 않습니다. 제너레이터는 이 조합을 거부합니다. 대신 ag-ui 프로토콜로 에이전트를 생성하세요.

사용법

제너레이터 실행

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

Gateway 프로젝트를 소스로, 에이전트 프로젝트를 대상으로 선택합니다. 에이전트 프로젝트에 여러 컴포넌트가 포함된 경우 targetComponent를 지정하여 명확히 구분하세요.

옵션

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

제너레이터 출력

제너레이터는 새 소스 파일을 생성하는 대신 기존 프로젝트를 연결합니다. 다음 파일이 수정됩니다:

• 디렉터리packages/<gateway>

  • project.json Gateway의 dev 대상이 에이전트의 <agent>-dev에 대한 종속성을 얻습니다
  • local-dev.ts ATTACHED_AGENTS가 업데이트되어 로컬 게이트웨이가 에이전트로 프록시합니다

스택에 에이전트 대상 추가하기

제너레이터는 Gateway를 인스턴스화하는 스택이나 모듈을 알 수 없기 때문에 에이전트 대상을 인프라에 자동으로 연결할 수 없습니다. gateway.addAgent(agent) 호출을 직접 추가하세요.

CDK

Gateway를 인스턴스화하는 스택에서 에이전트를 대상으로 등록합니다:

packages/infra/src/stacks/application-stack.ts

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

// 에이전트를 Gateway의 런타임 대상으로 등록합니다. 대상 이름은
// 기본적으로 에이전트의 `agentName`(케밥 케이스의 클래스 이름,
// 예: `MyAgent` -> `my-agent`)이며, 대상의 호출 경로를 형성합니다:
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

기본 대상 이름을 재정의하려면 gatewayTargetName을 전달하세요:

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

구성은 Gateway의 실행 역할에 에이전트 런타임에 대한 호출 액세스 권한을 부여하고 GATEWAY_IAM_ROLE 자격 증명 공급자로 대상을 구성하므로 Gateway는 자체 역할로 아웃바운드 호출에 서명합니다.

VPC에 에이전트 배포하기

Gateway로 에이전트를 프론트하는 것은 VPC에 배포된 에이전트를 접근 가능하게 만드는 방법입니다: 호출자는 Gateway의 공개 엔드포인트와 통신하고, Gateway는 내부적으로 런타임에 도달합니다. VPC 네트워크 구성을 에이전트 구성에 전달하세요:

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // 각 에이전트에 네트워크 구성을 위한 자체 스코프를 제공합니다 — usingVpc는
  // 전달한 스코프 아래에 `SecurityGroup`이라는 이름의 보안 그룹을 생성하므로,
  // 둘 이상의 에이전트에 대해 `this`를 전달하면 구성 ID가 충돌합니다.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

egress가 있는 프라이빗 서브넷을 사용하고, 프라이빗 격리 서브넷은 사용하지 마세요: 런타임은 Bedrock에 도달하고 AWS AppConfig에서 구성을 읽기 위해 아웃바운드 인터넷 액세스가 필요합니다.

AgentCore Runtime VPC 배포는 특정 가용 영역에서만 지원됩니다. subnets are in unsupported availability zones 오류로 배포가 실패하는 경우, VPC(또는 서브넷 선택)를 해당 리전의 지원되는 영역으로 제한하세요.

Terraform

Gateway를 인스턴스화하는 Terraform 파일에서 에이전트 대상을 연결합니다:

packages/infra/src/main.tf

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

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

  # Gateway는 자체 역할로 런타임에 대한 아웃바운드 호출에 서명하고
  # 대상 생성 시 액세스를 검증하므로 먼저 호출 액세스가 필요합니다.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A 대상은 게이트웨이를 통해 에이전트 카드도 제공합니다
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# 에이전트를 Gateway의 런타임 대상으로 등록합니다. 대상 이름은
# 호출 경로를 형성합니다: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore는 설정되지 않은 경우 설명을 채우며, 이는 공급자가
  # 적용 후 일관되지 않은 결과로 보고하므로 항상 설정하세요.
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

VPC에 에이전트 배포하기

Gateway로 에이전트를 프론트하는 것은 VPC에 배포된 에이전트를 접근 가능하게 만드는 방법입니다: 호출자는 Gateway의 공개 엔드포인트와 통신하고, Gateway는 내부적으로 런타임에 도달합니다. 에이전트 모듈의 VPC 변수를 설정하세요:

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

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

egress가 있는 프라이빗 서브넷(NAT 게이트웨이로의 라우트)을 사용하고, 프라이빗 격리 서브넷은 사용하지 마세요: 런타임은 Bedrock에 도달하고 AWS AppConfig에서 구성을 읽기 위해 아웃바운드 인터넷 액세스가 필요합니다.

Gateway를 통해 에이전트 호출하기

<gatewayUrl origin>/<targetName>/invocations에 대한 요청은 프로토콜 변환 없이 에이전트 런타임으로 전달되므로, 호출자는 런타임에 직접 사용하는 것과 동일한 요청 형태를 사용합니다. SSE 스트림(AG-UI), JSON 스트리밍(Python HTTP) 및 A2A JSON-RPC가 모두 프록시를 통과합니다. 호출자는 에이전트가 아닌 Gateway로 인증합니다(Gateway의 auth에 따라 IAM SigV4 또는 Cognito JWT).

웹사이트를 Gateway의 에이전트에 연결하려면 connection 제너레이터를 사용하세요.

호출자 신원을 런타임으로 전달하기

기본적으로 Gateway는 자체 IAM 역할(GATEWAY_IAM_ROLE 자격 증명 공급자)로 아웃바운드 호출에 서명하므로 런타임은 호출자가 아닌 Gateway의 신원을 봅니다. 대신 에이전트가 호출자를 기반으로 권한을 부여하도록 하려면(예: 사용자의 sub 또는 scope 클레임을 읽기 위해) Cognito 에이전트를 Cognito Gateway로 프론트하세요. 그러면 Gateway가 호출자의 JWT를 변경하지 않고 런타임으로 전달하고(JWT_PASSTHROUGH 자격 증명 공급자), 런타임이 이를 재검증합니다.

위와 같이 양쪽 끝을 auth: cognito로 생성하고 연결합니다:

• auth: cognito로 생성된 에이전트(ts#agent 또는 py#agent), 그리고
• 동일한 Cognito 사용자 풀을 프론트하는 auth: cognito로 생성된 Gateway.

나머지는 모두 자동입니다 — gateway.addAgent(agent)(CDK) 및 생성된 Terraform 런타임 모듈이 에이전트의 auth를 기반으로 연결을 처리합니다:

• 대상은 JWT_PASSTHROUGH 자격 증명 공급자(GATEWAY_IAM_ROLE 대신)로 생성되고,
• 런타임은 Authorization 헤더를 허용 목록에 추가하여 전달된 토큰이 에이전트 코드에 도달하도록 합니다. 이 허용 목록이 없으면 AgentCore는 토큰을 검증하지만 컨테이너 이전에 헤더를 제거합니다.

호출자는 Authorization: Bearer <jwt>(SigV4 없음)로 Gateway를 호출하고, 에이전트는 Authorization 헤더에서 클레임을 읽습니다. 런타임의 인바운드 권한 부여자가 이미 토큰을 검증했으므로 서명 검증을 건너뜁니다:

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

참고

JWT 패스스루는 토큰 대상이 이미 런타임을 포함하는 단일 신원 공급자에 적합합니다. 하나의 Gateway가 여러 테넌트 또는 대상에 걸쳐 에이전트를 프론트하는 경우 대신 OAuth on-behalf-of 토큰 교환을 사용하세요.

로컬 개발

다음 명령으로 Gateway를 로컬에서 실행하면:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

로컬 게이트웨이와 할당된 로컬 포트의 모든 연결된 에이전트가 시작됩니다. 로컬 게이트웨이는 /<targetName>/... 경로를 각 에이전트의 로컬 서버로 프록시하여 배포된 Gateway의 경로 기반 라우팅과 일치합니다.