TypeScript Strands 에이전트

도구를 사용하여 AI 에이전트를 구축하기 위한 TypeScript Agent를 생성하고, 선택적으로 Amazon Bedrock AgentCore Runtime에 배포합니다. 기본적으로 이 생성기는 WebSocket을 통한 tRPC를 사용하여 AgentCore의 양방향 스트리밍 지원을 활용하여 실시간 타입 안전 통신을 제공합니다. 또는 다른 A2A 호환 에이전트와의 상호 운용성을 위해 Agent-to-Agent (A2A) 프로토콜을 선택할 수 있습니다.

Strands란 무엇인가요?

Strands는 AI 에이전트를 구축하기 위한 경량 프레임워크입니다. 주요 기능은 다음과 같습니다:

• 경량 및 커스터마이징 가능: 방해받지 않는 간단한 에이전트 루프
• 프로덕션 준비 완료: 확장을 위한 완전한 관찰성, 추적 및 배포 옵션
• 모델 및 제공업체 독립적: 다양한 제공업체의 여러 모델 지원
• 커뮤니티 기반 도구: 커뮤니티가 기여한 강력한 도구 세트
• 다중 에이전트 지원: 에이전트 팀 및 자율 에이전트와 같은 고급 기술
• 유연한 상호작용 모드: 대화형, 스트리밍 및 비스트리밍 지원

사용법

Agent 생성

두 가지 방법으로 TypeScript Agent를 생성할 수 있습니다:

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#agent

yarn

yarn nx g @aws/nx-plugin:ts#agent

npm

npx nx g @aws/nx-plugin:ts#agent

bun

bunx nx g @aws/nx-plugin:ts#agent

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

pnpm

pnpm nx g @aws/nx-plugin:ts#agent --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#agent --dry-run

npm

npx nx g @aws/nx-plugin:ts#agent --dry-run

bun

bunx nx g @aws/nx-plugin:ts#agent --dry-run

프로젝트 사전 요건

먼저 ts#project 생성기를 사용하여 Agent를 추가할 프로젝트를 생성하세요.

옵션

매개변수	타입	기본값	설명
project 필수	string	-	Agent를 추가할 프로젝트
sdk	string	strands	사용할 에이전트 SDK.
computeType	string	BedrockAgentCoreRuntime	Agent를 호스팅할 컴퓨팅 유형
name	string	-	Agent의 이름 (기본값: agent)
auth	string	IAM	Agent와 인증하는 데 사용되는 방법입니다. IAM(기본값) 또는 Cognito 중에서 선택하세요.
protocol	string	HTTP	Agent의 서버 프로토콜입니다. HTTP는 tRPC/WebSocket 서버를 노출합니다. A2A는 Agent-to-Agent 프로토콜 서버를 노출합니다. AG-UI는 아직 TypeScript agent에서 지원되지 않습니다.
iacProvider	string	Inherit	선호하는 IaC 프로바이더. 기본적으로 초기 선택에서 상속됩니다.

생성기 출력

생성기는 기존 TypeScript 프로젝트에 다음 파일을 추가합니다. 생성되는 파일은 선택한 protocol에 따라 다릅니다:

protocol = HTTP

HTTP 프로토콜 (기본값)

• 디렉터리your-project/

  • 디렉터리src/

    • 디렉터리agent/ (또는 지정된 경우 사용자 정의 이름)

      • index.ts Bedrock AgentCore Runtime의 진입점 (tRPC/WebSocket 서버)
      • init.ts tRPC 초기화
      • router.ts 에이전트 프로시저가 포함된 tRPC 라우터
      • agent.ts 샘플 도구가 포함된 메인 에이전트 정의
      • client.ts 에이전트를 호출하기 위한 제공된 클라이언트
      • agent-core-trpc-client.ts AgentCore Runtime의 에이전트에 연결하기 위한 클라이언트 팩토리
      • Dockerfile 에이전트 호스팅을 위한 진입점 (computeType이 None으로 설정된 경우 제외)
  • package.json Strands 종속성으로 업데이트됨
  • project.json 에이전트 서브 타겟으로 업데이트됨

protocol = A2A

A2A 프로토콜

진입점은 tRPC 대신 Strands A2A Express Server를 사용합니다:

• 디렉터리your-project/

  • 디렉터리src/

    • 디렉터리agent/ (또는 지정된 경우 사용자 정의 이름)

      • index.ts A2A Express 서버 진입점
      • agent.ts 샘플 도구가 포함된 메인 에이전트 정의
      • Dockerfile 에이전트 호스팅을 위한 진입점 (computeType이 None으로 설정된 경우 제외)
  • package.json Strands 및 Express 종속성으로 업데이트됨
  • project.json 에이전트 서브 타겟으로 업데이트됨

인프라

computeType = BedrockAgentCoreRuntime

이 생성기는 선택한 iacProvider 기반으로 인프라를 코드 형태로 제공하므로, packages/common 디렉터리에 관련 CDK 구축 요소 또는 Terraform 모듈을 포함하는 프로젝트를 생성합니다.

공통 인프라스트럭처 코드 프로젝트의 구조는 다음과 같습니다:

CDK

• 디렉터리packages/common/constructs

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기에 종속적인 인프라를 위한 구축 요소

      • …
    • 디렉터리core/ app 내 구축 요소에서 재사용되는 일반적 구축 요소

      • …
    • index.ts app의 구축 요소를 익스포트하는 진입점
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 ts#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Terraform

• 디렉터리packages/common/terraform

  • 디렉터리src

    • 디렉터리app/ 특정 프로젝트/생성기 전용 Terraform 모듈

      • …
    • 디렉터리core/ app 내 모듈에서 재사용되는 일반적 모듈

      • …
  • project.json 프로젝트 빌드 대상 및 구성

생성된 프로젝트

이 프로젝트는 terraform#project 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Agent 배포를 위해 다음 파일이 생성됩니다:

CDK

• 디렉터리packages/common/constructs/src

  • 디렉터리app

    • 디렉터리agents

      • 디렉터리<project-name>

        • <project-name>.ts 에이전트 배포를 위한 CDK 구성

Terraform

• 디렉터리packages/common/terraform/src

  • 디렉터리app

    • 디렉터리agents

      • 디렉터리<project-name>

        • <project-name>.tf 에이전트 배포를 위한 모듈
  • 디렉터리core

    • 디렉터리agent-core

      • runtime.tf Bedrock AgentCore Runtime에 배포하기 위한 일반 모듈

computeType = None

computeType에 대해 None을 선택한 경우 CDK 구성 또는 Terraform 모듈이 생성되지 않습니다 — Agent는 로컬에서만 실행할 수 있습니다.

Architecture

Bedrock AgentCore Runtime

Bedrock AgentCore Runtime에 배포되면, 에이전트는 컨테이너 이미지로 빌드되어 Amazon ECR에 푸시되고 AgentCore Runtime에서 실행됩니다. 클라이언트는 AgentCore Runtime 데이터 플레인 엔드포인트를 호출하며, 이는 요청을 에이전트로 전달합니다. 에이전트는 모델 추론을 위해 Amazon Bedrock을 호출하고 도구, MCP 서버 또는 다운스트림 API를 호출할 수 있습니다.

None (local only)

computeType: None을 사용하면 AWS 인프라가 생성되지 않습니다. 에이전트는 로컬 프로세스로 실행되며 모델 추론을 위해 Amazon Bedrock을 호출합니다.

Agent 작업하기

프로토콜

에이전트의 서버 프로토콜은 통신 방식을 결정합니다. 다음 중에서 선택할 수 있습니다:

• HTTP (기본값): 실시간 타입 안전 통신을 위해 WebSocket을 통한 tRPC를 사용합니다. 사용자 정의 클라이언트 통합 및 에이전트 API에 대한 세밀한 제어에 가장 적합합니다.
• A2A: 표준화된 에이전트 간 통신을 위해 Agent-to-Agent (A2A) 프로토콜을 사용합니다. 에이전트가 다른 A2A 호환 에이전트에 의해 검색 및 호출 가능해야 하는 경우에 가장 적합합니다.

프로토콜은 CDK/Terraform 인프라에서 설정되며, 애플리케이션 코드는 그에 따라 생성됩니다.

protocol = HTTP

WebSocket을 통한 tRPC (HTTP 프로토콜)

TypeScript Agent는 WebSocket을 통한 tRPC를 사용하여 AgentCore의 양방향 스트리밍 지원을 활용하여 클라이언트와 에이전트 간의 실시간 타입 안전 통신을 가능하게 합니다.

tRPC는 WebSocket을 통한 Query, Mutation 및 Subscription 프로시저를 지원하므로 원하는 수의 프로시저를 정의할 수 있습니다. 기본적으로 router.ts에 invoke라는 단일 구독 프로시저가 정의되어 있습니다.

도구 추가

도구는 AI 에이전트가 작업을 수행하기 위해 호출할 수 있는 함수입니다. agent.ts 파일에 새 도구를 추가할 수 있습니다:

import { Agent, tool } from '@agents/sdk';
import { z } from 'zod';

const letterCounter = tool({
  name: 'letter_counter',
  description: 'Count occurrences of a specific letter in a word',
  inputSchema: z.object({
    word: z.string().describe('The input word to search in'),
    letter: z.string().length(1).describe('The specific letter to count'),
  }),
  callback: (input) => {
    const { word, letter } = input;
    const count = word.toLowerCase().split(letter.toLowerCase()).length - 1;
    return `The letter '${letter}' appears ${count} time(s) in '${word}'`;
  },
});

// Add tools to your agent
export const getAgent = async (sessionId: string) => {
  return new Agent({
    systemPrompt: 'You are a helpful assistant with access to various tools.',
    tools: [letterCounter],
  });
};

Strands 프레임워크는 다음을 자동으로 처리합니다:

• Zod 스키마를 사용한 입력 검증
• 도구 호출을 위한 JSON 스키마 생성
• 오류 처리 및 응답 포맷팅

모델 구성

기본적으로 Strands 에이전트는 Claude 4 Sonnet을 사용하지만, 모델 제공업체 간에 쉽게 전환할 수 있습니다:

import { Agent } from '@agents/sdk';
import { BedrockModel } from '@agents/sdk/models/bedrock';
import { OpenAIModel } from '@agents/sdk/models/openai';

// Use Bedrock
const bedrockModel = new BedrockModel({
  modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
});
let agent = new Agent({ model: bedrockModel });
let response = await agent.invoke('What can you help me with?');

// Alternatively, use OpenAI by just switching model provider
const openaiModel = new OpenAIModel({
  apiKey: process.env.OPENAI_API_KEY,
  modelId: 'gpt-4o',
});
agent = new Agent({ model: openaiModel });
response = await agent.invoke('What can you help me with?');

더 많은 구성 옵션은 모델 제공업체에 대한 Strands 문서를 참조하세요.

MCP 서버 사용

Strands 에이전트에 MCP 서버의 도구를 추가할 수 있습니다.

py#mcp-server 또는 ts#mcp-server 생성기를 사용하여 생성한 MCP 서버를 사용하려면 connection 생성기를 활용할 수 있습니다.

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

연결 설정 방법에 대한 자세한 내용은 connection 생성기 가이드를 참조하세요.

다른 MCP 서버의 경우 Strands 문서를 참조하세요.

더 보기

Strands 에이전트 작성에 대한 더 심층적인 가이드는 Strands 문서를 참조하세요.

protocol = A2A

A2A 서버 (A2A 프로토콜)

생성된 index.ts는 Strands A2A Express Server를 Express 앱에 마운트하여 생성된 에이전트가 /ping 상태 확인과 함께 A2A 프로토콜 엔드포인트를 노출하도록 합니다. AgentCore에 배포되면 진입점은 AppConfig에서 런타임의 공개 ARN을 확인하고 에이전트 카드에 이를 알립니다.

대부분의 사용자는 이 파일을 수정할 필요가 없습니다 — 도구나 시스템 프롬프트를 변경하려면 agent.ts를 편집하세요. A2A 에이전트는 포트 9000에서 수신 대기하며(HTTP의 경우 8080), 생성된 Dockerfile 및 인프라는 이미 이에 맞게 구성되어 있습니다.

Agent 실행

로컬 개발

생성기는 <your-agent-name>-serve라는 타겟을 구성하여 개발 및 테스트를 위해 Agent를 로컬에서 시작합니다.

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

이 명령은 tsx --watch를 사용하여 파일이 변경될 때 서버를 자동으로 재시작합니다. 에이전트는 http://localhost:8081(또는 여러 에이전트가 있는 경우 할당된 포트)에서 사용할 수 있습니다.

에이전트와 채팅하기

생성기는 <your-agent-name>-serve-local에 의존하는 <your-agent-name>-chat Nx 타겟을 구성합니다. 실행하면 에이전트를 로컬에서 시작하고 대화형 터미널 채팅으로 진입합니다:

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

bunx nx run your-project:agent-chat

HTTP (tRPC over WebSocket) 에이전트의 경우, 생성기는 에이전트의 입력 형태를 발전시킬 때 커스터마이징할 수 있도록 생성된 <Agent>Client.local({ url })를 래핑하는 작은 scripts/<your-agent-name>/chat.ts도 생성합니다.

computeType = BedrockAgentCoreRuntime

Agent를 Bedrock AgentCore Runtime에 배포

Infrastructure as Code

computeType에 대해 BedrockAgentCoreRuntime을 선택한 경우, Agent를 Amazon Bedrock AgentCore Runtime에 배포하는 데 사용할 수 있는 관련 CDK 또는 Terraform 인프라가 생성됩니다.

CDK

에이전트에 대한 CDK 구성이 생성되며, 생성기를 실행할 때 선택한 name을 기반으로 이름이 지정되거나 기본적으로 <ProjectName>Agent로 지정됩니다.

CDK 애플리케이션에서 이 CDK 구성을 사용할 수 있습니다:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

CDK 컨스트럭트

이 구성은 aws-cdk-lib/aws-bedrockagentcore 모듈을 사용합니다.

Terraform

Terraform 모듈이 생성되며, 생성기를 실행할 때 선택한 name을 기반으로 이름이 지정되거나 기본적으로 <ProjectName>-agent로 지정됩니다.

공유 runtime_config_appconfig 모듈의 출력을 에이전트 모듈에 전달합니다:

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Bedrock 모델 권한

생성된 에이전트 구성은 기본적으로 모든 Bedrock 기반 모델 및 추론 프로필을 호출할 수 있는 권한을 부여합니다(arn:aws:bedrock:*:*:foundation-model/* 및 arn:aws:bedrock:*:*:inference-profile/*에 대한 bedrock:InvokeModel 및 bedrock:InvokeModelWithResponseStream).

에이전트가 사용하는 특정 모델로 범위를 축소할 수 있습니다. Strands 에이전트가 사용하는 기본 모델은 Strands 문서에서 확인할 수 있습니다. 다른 모델을 구성하려면 Strands 모델 프로바이더 가이드를 참조하세요.

Docker 필요

Agent를 빌드하고 배포하려면 Docker가 필요합니다. 다음과 같은 오류를 방지하려면 Docker를 설치하고 실행했는지 확인하세요:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

인증

생성기는 Agent에 대한 인증을 구성하기 위한 auth 옵션을 제공합니다. 에이전트를 생성할 때 IAM(기본값) 또는 Cognito 인증 중에서 선택할 수 있습니다.

IAM

기본적으로 Agent는 IAM 인증을 사용하여 보호되며, 인수 없이 간단히 배포할 수 있습니다:

CDK

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

grantInvokeAccess 메서드를 사용하여 Bedrock AgentCore Runtime에서 에이전트를 호출할 수 있는 액세스 권한을 부여할 수 있습니다. 예를 들어:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

에이전트를 호출할 수 있는 액세스 권한을 부여하려면 module.my_project_agent.agent_core_runtime_arn 출력을 참조하여 다음과 같은 정책을 추가해야 합니다:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Cognito 인증

Cognito 인증을 선택하면 생성기가 에이전트가 Cognito를 인증에 사용하도록 구성합니다.

CDK

생성된 구성은 Cognito 인증을 구성하는 identity prop을 허용합니다:

import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

UserIdentity 구성은 ts#react-website#auth 생성기를 사용하여 생성하거나, 자체 CDK UserPool 및 UserPoolClient를 생성할 수 있습니다.

Terraform

생성된 모듈은 Cognito 인증을 위한 user_pool_id 및 user_pool_client_ids 변수를 허용합니다:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

사용자 정의 OIDC 프로바이더

Cognito가 아닌 OIDC 공급자를 사용하는 사용자 지정 JWT 인증이 필요한 경우 에이전트에 대해 생성된 CDK 구성 또는 Terraform 모듈을 직접 수정할 수 있습니다. 연결 생성기는 IAM 또는 Cognito 인증만 지원합니다.

번들 타겟

제너레이터는 Rolldown을 사용하여 배포 패키지를 생성하는 bundle 타겟을 자동으로 구성합니다:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Rolldown 구성은 rolldown.config.ts에서 확인할 수 있으며, 생성할 각 번들별로 엔트리가 존재합니다. 정의된 경우 Rolldown은 여러 번들을 병렬로 생성하는 작업을 관리합니다.

사용자 정의 구성

rolldown.config.ts에서 Rolldown 구성을 조정할 수 있습니다. 예를 들어 파일 경로에 의존하는 종속성이 있어 번들링이 불가능한 경우, external 모듈 목록에 추가할 수 있습니다.

번들 타겟은 Bedrock AgentCore Runtime에서 호스팅할 WebSocket 서버의 진입점으로 index.ts를 사용합니다.

Docker 타겟

생성기는 에이전트 소스 디렉토리의 Dockerfile을 번들 출력 디렉토리로 복사하는 <your-agent-name>-docker 타겟을 구성합니다. 이렇게 하면 Dockerfile이 번들된 아티팩트와 함께 배치되어 CDK가 AgentRuntimeArtifact.fromAsset을 사용하여 Docker 이미지를 직접 빌드할 수 있습니다.

여러 에이전트가 정의된 경우 모든 에이전트에 대한 도커 컨텍스트를 준비하는 docker 타겟도 생성됩니다.

관찰성

에이전트는 Dockerfile에서 자동 계측을 구성하여 AWS Distro for Open Telemetry (ADOT)를 사용한 관찰성으로 자동 구성됩니다.

CloudWatch AWS 콘솔에서 메뉴의 “GenAI Observability”를 선택하여 추적을 찾을 수 있습니다. 추적이 채워지려면 Transaction Search를 활성화해야 합니다.

자세한 내용은 관찰성에 대한 AgentCore 문서를 참조하세요.

Agent 호출

에이전트 통신은 WebSocket을 통한 tRPC를 통해 전송됩니다. 따라서 client.ts에 생성된 타입 안전 클라이언트 팩토리를 사용하는 것이 좋습니다.

protocol = HTTP

로컬 서버 호출

클라이언트 팩토리의 .local 팩토리 메서드를 사용하여 로컬에서 실행 중인 에이전트를 호출할 수 있습니다.

예를 들어 워크스페이스에 클라이언트를 가져오는 scripts/test.ts라는 파일을 생성할 수 있습니다:

scripts/test.ts

import { AgentClient } from '../packages/<project>/src/agent/client.js';

const client = AgentClient.local({ url: 'http://localhost:8081/ws' });

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, { onData: console.log });

빠른 테스트

에이전트를 빠르게 테스트하는 방법으로 tsx로 실행하세요.

pnpm

pnpm tsx scripts/test.ts

yarn

yarn tsx scripts/test.ts

npm

npx tsx scripts/test.ts

bun

bunx tsx scripts/test.ts

배포된 에이전트 호출

Bedrock AgentCore Runtime에 배포된 Agent를 호출하려면, URL 인코딩된 런타임 ARN과 함께 Bedrock AgentCore Runtime 데이터플레인 엔드포인트로 POST 요청을 보낼 수 있습니다.

다음과 같이 인프라에서 런타임 ARN을 얻을 수 있습니다:

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

ARN은 다음 형식을 가집니다: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

그런 다음 :를 %3A로, /를 %2F로 바꿔서 ARN을 URL 인코딩할 수 있습니다.

브라우저 콘솔

브라우저 콘솔이나 Node REPL에서 내장된 encodeURIComponent 메서드를 사용하면 간단합니다:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

에이전트를 호출하기 위한 Bedrock AgentCore Runtime 데이터플레인 URL은 다음과 같습니다:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

이 URL을 호출하는 정확한 방법은 사용된 인증 방법에 따라 다릅니다.

NodeJS

생성된 client.ts 파일에는 배포된 에이전트를 호출하는 데 사용할 수 있는 타입 안전 클라이언트 팩토리가 포함되어 있습니다.

HTTP 헤더 인증

클라이언트 팩토리는 WebSocket 핸드셰이크에서 HTTP 헤더를 사용하여 Bedrock AgentCore Runtime에 대한 요청을 인증합니다. 이는 브라우저에서는 불가능하므로 이 클라이언트는 브라우저 환경에 적합하지 않습니다. 브라우저에서의 호출에 대한 자세한 내용은 아래 “브라우저” 섹션을 참조하세요.

IAM

IAM 인증

withIamAuth 팩토리 메서드에 ARN을 전달하여 배포된 에이전트를 호출할 수 있습니다:

import { AgentClient } from './agent/client.js';

const client = AgentClient.withIamAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
});

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

AWS 자격 증명

이는 기본 AWS 자격 증명 공급자 체인을 사용하여 요청을 인증하므로, 위 코드가 실행되는 환경에는 런타임을 호출할 수 있는 액세스 권한이 있는 AWS 자격 증명이 구성되어 있어야 합니다.

Cognito

JWT / Cognito 인증

JWT / Cognito 액세스 토큰으로 인증하려면 withJwtAuth 팩토리 메서드를 사용하세요.

const client = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => `<access-token>`,
});

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
  onData: console.log,
});

accessTokenProvider는 요청을 인증하는 데 사용되는 토큰을 반환해야 합니다. 예를 들어 이 메서드 내에서 토큰을 가져와 tRPC가 WebSocket 연결을 재시작할 때 새로운 자격 증명이 재사용되도록 할 수 있습니다. 아래는 AWS SDK를 사용하여 Cognito에서 토큰을 가져오는 방법을 보여줍니다:

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";

const cognito = new CognitoIdentityProvider();

const jwtClient = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => {
    const response = await cognito.adminInitiateAuth({
      UserPoolId: '<user-pool-id>',
      ClientId: '<user-pool-client-id>',
      AuthFlow: 'ADMIN_NO_SRP_AUTH',
      AuthParameters: {
        USERNAME: '<username>',
        PASSWORD: '<password>',
      },
    });
    return response.AuthenticationResult!.AccessToken!;
  },
});

브라우저 / React 웹사이트

React 웹사이트에서 Agent를 호출하려면 connection 생성기를 활용할 수 있으며, 이는 올바른 인증(IAM 또는 Cognito)으로 tRPC WebSocket 클라이언트를 자동으로 설정합니다.

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

연결 설정 방법에 대한 자세한 내용은 connection 생성기 가이드를 참조하세요.

protocol = A2A

A2A 에이전트를 도구로 호출

이 에이전트에서 원격 A2A 에이전트(TypeScript 또는 Python)로 작업을 위임하려면 connection 생성기를 사용하세요. 이는 대상 에이전트에 대한 SigV4 인증 클라이언트를 제공하고 이 에이전트의 agent.ts를 AST 변환하여 원격 A2A 에이전트를 Strands tool로 등록합니다.

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

연결 설정 방법에 대한 자세한 내용은 connection 생성기 가이드를 참조하세요.