AgentCore Gateway에서 Agent로

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

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

전제 조건

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

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

TypeScript HTTP 에이전트

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

사용법

제너레이터 실행

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

VSCode

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

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');

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <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', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct id.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_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"

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  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]
}

격리된 프라이빗 서브넷이 아닌 이그레스가 있는 프라이빗 서브넷(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 제너레이터를 사용하세요.

런타임에 호출자 ID 전달

기본적으로 Gateway는 자체 IAM 역할(GATEWAY_IAM_ROLE 자격 증명 공급자)로 아웃바운드 호출에 서명하므로 런타임은 호출자가 아닌 Gateway의 ID를 봅니다. 대신 에이전트가 호출자를 기준으로 권한을 부여하도록 하려면(예: 사용자의 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를 기반으로 연결을 처리합니다:

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

호출자는 Authorization: Bearer <jwt>로 Gateway를 호출하고(SigV4 없음), 에이전트는 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 패스스루는 토큰 대상이 이미 런타임을 포함하는 단일 ID 공급자에 적합합니다. 하나의 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의 경로 기반 라우팅과 일치합니다.