파이썬 스트랜드 에이전트

도구를 갖춘 AI 에이전트를 구축하고 Amazon Bedrock AgentCore Runtime에 배포할 수 있는 Python Strands Agent를 생성합니다.

Strands란?

Strands는 AI 에이전트 구축을 위한 가볍고 프로덕션 준비가 된 Python 프레임워크입니다. 주요 기능은 다음과 같습니다:

• 가볍고 사용자 정의 가능: 간단한 에이전트 루프로 개발자 방해 최소화
• 프로덕션 준비 완료: 완전한 관측성, 추적 및 확장을 위한 배포 옵션
• 모델 및 제공자 독립적: 다양한 제공자의 여러 모델 지원
• 커뮤니티 주도 도구: 강력한 커뮤니티 기여 도구 세트
• 다중 에이전트 지원: 에이전트 팀 및 자율 에이전트와 같은 고급 기법
• 유연한 상호작용 모드: 대화형, 스트리밍 및 비스트리밍 지원

사용 방법

Strands 에이전트 생성

두 가지 방법으로 Python Strands 에이전트를 생성할 수 있습니다:

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent

yarn

yarn nx g @aws/nx-plugin:py#strands-agent

npm

npx nx g @aws/nx-plugin:py#strands-agent

bun

bunx nx g @aws/nx-plugin:py#strands-agent

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

pnpm

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

yarn

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

npm

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

bun

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

팁

먼저 py#project 생성기를 사용하여 Strands 에이전트를 추가할 프로젝트를 생성하세요.

옵션

매개변수	타입	기본값	설명
project 필수	string	-	The project to add the Strands Agent to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your Strands Agent.
name	string	-	The name of your Strands Agent (default: agent)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

생성기 출력

생성기는 기존 Python 프로젝트에 다음 파일들을 추가합니다:

• 디렉터리your-project/

  • 디렉터리your_module/

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

      • __init__.py 파이썬 패키지 초기화
      • agent.py 샘플 도구가 포함된 주요 에이전트 정의
      • main.py Bedrock AgentCore Runtime용 진입점
      • agentcore_mcp_client.py Bedrock AgentCore Runtime에 호스팅된 MCP 서버 호출에 유용한 클라이언트 팩토리
      • Dockerfile 에이전트 호스팅용 도커 파일 (computeType이 None으로 설정된 경우 제외)
  • pyproject.toml Strands 종속성으로 업데이트
  • project.json 에이전트 서빙 타겟으로 업데이트

인프라

참고

computeType으로 None을 선택한 경우 생성기는 인프라스트럭처 코드를 제공하지 않습니다.

이 생성기는 선택한 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 생성기를 사용하여 생성되었으므로 동일한 빌드 대상이 구성됩니다.

Strands 에이전트 배포를 위해 다음 파일들이 생성됩니다:

CDK

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

  • 디렉터리app

    • 디렉터리agents

      • 디렉터리<project-name>

        • <project-name>.ts 에이전트 배포용 CDK 컨스트럭트
        • Dockerfile CDK 컨스트럭트에서 사용하는 도커 파일

Terraform

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

  • 디렉터리app

    • 디렉터리agents

      • 디렉터리<project-name>

        • <project-name>.tf 에이전트 배포용 테라폼 모듈
  • 디렉터리core

    • 디렉터리agent-core

      • runtime.tf Bedrock AgentCore Runtime 배포용 일반 모듈

Strands 에이전트 작업

도구 추가

도구는 AI 에이전트가 작업 수행을 위해 호출할 수 있는 함수입니다. Strands 프레임워크는 도구 정의를 위해 간단한 데코레이터 기반 접근 방식을 사용합니다.

agent.py 파일에 새 도구를 추가할 수 있습니다:

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """숫자 리스트의 합계 계산"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """도시의 날씨 정보 조회"""
    # 날씨 API 통합 구현
    return f"Weather in {city}: Sunny, 25°C"

# 에이전트에 도구 추가
agent = Agent(
    system_prompt="다양한 도구에 접근 가능한 유용한 어시스턴트입니다.",
    tools=[calculate_sum, get_weather],
)

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

• 함수 타입 힌트 기반 타입 검증
• 도구 호출을 위한 JSON 스키마 생성
• 오류 처리 및 응답 포맷팅

사전 제작 도구 사용

Strands는 strands-tools 패키지를 통해 사전 제작된 도구 컬렉션을 제공합니다:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="유용한 어시스턴트입니다.",
    tools=[current_time, http_request, file_read],
)

모델 구성

기본적으로 Strands 에이전트는 Claude 4 Sonnet을 사용하지만 모델 제공자를 사용자 정의할 수 있습니다. 구성 옵션은 Strands 모델 제공자 문서를 참조하세요:

from strands import Agent
from strands.models import BedrockModel

# BedrockModel 생성
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

MCP 서버 사용

Strands 에이전트에 MCP 서버 도구 추가가 가능합니다.

py#mcp-server 또는 ts#mcp-server 생성기(또는 Bedrock AgentCore Runtime에 호스팅된 기타 서버)를 사용하여 생성한 MCP 서버의 경우, agentcore_mcp_client.py에 클라이언트 팩토리가 생성됩니다.

agent.py의 get_agent 메서드를 업데이트하여 MCP 클라이언트를 생성하고 도구를 추가할 수 있습니다. 다음 예제는 IAM(SigV4) 인증을 사용하는 방법을 보여줍니다:

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# 리전 및 자격 증명 획득
region = os.environ["AWS_REGION"]
boto_session = boto3.Session(region_name=region)
credentials = boto_session.get_credentials()

@contextmanager
def get_agent(session_id: str):
    mcp_client = AgentCoreMCPClient.with_iam_auth(
        agent_runtime_arn=os.environ["MCP_AGENTCORE_RUNTIME_ARN"],
        credentials=credentials,
        region=region,
        session_id=session_id,
    )

    with mcp_client:
        mcp_tools = mcp_client.list_tools_sync()

        yield Agent(
            system_prompt="..."
            tools=[*mcp_tools],
        )

팁

대상 MCP 서버가 JWT 인증을 사용하는 경우 AgentCoreMCPClient.with_jwt_auth 메서드를 대신 사용할 수 있습니다.

위 IAM 인증 예제를 사용하려면 인프라스트럭처에서 두 가지를 구성해야 합니다. 먼저 MCP 서버의 AgentCore Runtime ARN을 위한 환경 변수를 추가하고, 두 번째로 에이전트에 MCP 서버 호출 권한을 부여해야 합니다. 이는 다음과 같이 구현할 수 있습니다:

CDK

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

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

    const agent = new MyProjectAgent(this, 'MyProjectAgent', {
      environmentVariables: {
        MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.agentRuntimeArn,
      },
    });

    mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# MCP 서버
module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

# 에이전트
module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  env = {
    MCP_AGENTCORE_RUNTIME_ARN = module.my_project_mcp_server.agent_core_runtime_arn
  }

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

추가 정보

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

FastAPI 서버

생성기는 FastAPI를 사용하여 Strands 에이전트용 HTTP 서버를 생성합니다. FastAPI는 자동 API 문서화 및 타입 검증 기능을 갖춘 Python API 구축을 위한 현대적이고 빠른 웹 프레임워크를 제공합니다.

생성된 서버에는 다음이 포함됩니다:

• CORS 미들웨어가 포함된 FastAPI 애플리케이션 설정
• 오류 처리 미들웨어
• OpenAPI 스키마 생성
• 헬스 체크 엔드포인트 (/ping)
• 에이전트 호출 엔드포인트 (/invocations)

Pydantic을 사용한 호출 입력 및 출력 사용자 정의

에이전트의 호출 엔드포인트는 Pydantic 모델을 사용하여 요청 및 응답 스키마를 정의하고 검증합니다. main.py에서 이러한 모델을 에이전트의 요구사항에 맞게 사용자 정의할 수 있습니다.

입력 모델 정의

기본 InvokeInput 모델은 프롬프트와 세션 ID를 받습니다.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str
    session_id: str

에이전트에 필요한 추가 필드를 포함하도록 이 모델을 확장할 수 있습니다.

주의

사용자가 에이전트를 직접 호출하는 경우 호출자로부터 세션 ID의 일부 또는 전체를 추상화하는 것이 좋습니다. 예를 들어 인증된 사용자 ID를 세션 ID의 일부로 사용할 수 있습니다.

또한 사용 사례에 따라 세션에 대한 권한 부여를 구현해야 할 수 있습니다. 예를 들어 사용자가 자신의 세션에만 접근하고 다른 사용자의 세션에는 접근할 수 없도록 보장하는 것입니다.

출력 모델 정의

스트리밍 응답의 경우 엔드포인트의 반환 타입 어노테이션은 생성기 함수가 yield하는 각 값의 타입에 해당합니다. 기본적으로 에이전트는 Strands에서 스트리밍되는 에이전트의 응답 텍스트를 포함하는 문자열을 yield합니다:

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> str:
    """Entry point for agent invocation"""
    return StreamingResponse(handle_invoke(input), media_type="text/event-stream")

구조화된 데이터를 yield하도록 Pydantic 모델을 정의할 수 있습니다. 이를 위해서는 handle_invoke가 yield하는 pydantic 모델을 직렬화해야 합니다:

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

def handle_invoke(...):
    ...
    yield StreamChunk(content="xx", timestamp="yy", token_count=5)

def serialize_stream(generator):
    async for output in generator:
        yield (output.model_dump_json() + "\n").encode("utf-8")

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> StreamChunk:
    return StreamingResponse(serialize_stream(handle_invoke(input)), media_type="application/json")

주의

여기서 제공된 서버(및 위의 serialize_stream 메서드)는 현재 Server-Sent Events(SSE) 표준을 준수하지 않습니다. 따라서 원하는 경우 프론트엔드에서 생성된 TypeScript 클라이언트로 에이전트를 호출할 수 있지만, 현재는 SSE 형식의 스트리밍 이벤트를 예상하지 않습니다. 이것이 영향을 미치는 경우 이 GitHub 이슈에 +1을 눌러 우선순위 지정에 도움을 주세요.

Bedrock AgentCore Python SDK

생성기는 PingStatus 상수를 위해 Bedrock AgentCore Python SDK에 대한 종속성을 포함합니다. 원하는 경우 FastAPI 대신 BedrockAgentCoreApp을 사용하는 것도 간단하지만, 타입 안전성이 손실된다는 점에 유의하세요.

SDK 기능에 대한 자세한 내용은 문서에서 확인할 수 있습니다.

참고

생성기가 에이전트 배포를 관리하는 CDK 또는 Terraform 인프라를 제공하므로 문서에 언급된 bedrock-agentcore-starter-toolkit을 사용할 필요가 없습니다.

Strands 에이전트 실행

로컬 개발

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

pnpm

pnpm nx run your-project:agent-serve

yarn

yarn nx run your-project:agent-serve

npm

npx nx run your-project:agent-serve

bun

bunx nx run your-project:agent-serve

이 명령은 Bedrock AgentCore Python SDK를 사용하여 Strands 에이전트를 실행하기 위해 uv run을 사용합니다.

Bedrock AgentCore Runtime에 Strands 에이전트 배포

Infrastructure as Code

computeType에 대해 BedrockAgentCoreRuntime을 선택한 경우, Strands 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) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.addToRolePolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: [
          'arn:aws:bedrock:*:*:foundation-model/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

참고

이 구성은 @aws-cdk/aws-bedrock-agentcore-alpha 모듈을 사용합니다.

Terraform

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

Terraform 프로젝트에서 이 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"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

주의

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

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

인증

IAM

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

CDK

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

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

grantInvoke 메서드를 사용하여 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.agentCoreRuntime.grantInvoke(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"
}

에이전트를 호출할 수 있는 액세스 권한을 부여하려면 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 JWT 인증

다음은 에이전트에 대한 Cognito 인증을 구성하는 방법을 보여줍니다.

CDK

Cognito를 사용하여 JWT 인증을 구성하려면 RuntimeAuthorizerConfiguration.usingCognito() 팩토리 메서드를 사용하세요:

import { MyProjectAgent } from ':my-scope/common-constructs';
import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito(
        userPool,
        [client],
      ),
    });
  }
}

또는 자체 OIDC 공급자를 사용하는 사용자 지정 JWT 인증의 경우 RuntimeAuthorizerConfiguration.usingJWT()를 사용하세요:

import { MyProjectAgent } from ':my-scope/common-constructs';
import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingJWT(
        'https://example.com/.well-known/openid-configuration',
        ['client1', 'client2'], // Allowed Client IDs (optional)
        ['audience1'],          // Allowed Audiences (optional)
      ),
    });
  }
}

Terraform

JWT 인증을 구성하려면 다음과 같이 authorizer_configuration 변수를 구성하도록 에이전트 모듈을 편집할 수 있습니다:

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.id

  # Replace with your user pool and client ids or expose as variables
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  authorizer_configuration = {
    custom_jwt_authorizer = {
      discovery_url = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration"
      allowed_clients = local.user_pool_client_ids
    }
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

번들 및 도커 타겟

Bedrock AgentCore Runtime용 Strands 에이전트 빌드를 위해 프로젝트에 bundle 타겟이 추가됩니다. 이 타겟은:

• uv export를 사용하여 Python 종속성을 requirements.txt 파일로 내보냄
• 대상 플랫폼(aarch64-manylinux2014)용 종속성을 uv pip install로 설치

또한 Strands 에이전트 전용 docker 타겟이 추가되어:

• AgentCore 런타임 계약에 따라 에이전트를 실행하는 Dockerfile에서 도커 이미지 빌드

팁

도커 이미지는 태그(예: my-scope-my-project-agent:latest)를 사용하여 빌드되며, 이는 CDK 또는 Terraform 인프라에서 참조되어 Strands 에이전트 프로젝트와 함께 Dockerfile을 배치할 수 있게 합니다.

인증

IAM

기본적으로 Strands 에이전트는 IAM 인증으로 보호되며, 인수 없이 배포할 수 있습니다:

CDK

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

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

에이전트 호출 권한을 부여하려면 grantInvoke 메서드를 사용할 수 있습니다. 예시:

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.agentCoreRuntime.grantInvoke(lambdaFunction);
  }
}

Terraform

# 에이전트
module "my_project_agent" {
  # common/terraform 프로젝트 내 생성된 모듈 상대 경로
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

에이전트 호출 권한을 부여하려면 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 JWT 인증

다음은 에이전트에 Cognito 인증을 구성하는 방법을 보여줍니다.

CDK

Cognito를 사용한 JWT 인증을 구성하려면 RuntimeAuthorizerConfiguration.usingCognito() 팩토리 메서드를 사용하세요:

import { MyProjectAgent } from ':my-scope/common-constructs';
import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito(
        userPool,
        [client],
      ),
    });
  }
}

또는 자체 OIDC 제공자를 사용한 사용자 정의 JWT 인증의 경우 RuntimeAuthorizerConfiguration.usingJWT()를 사용하세요:

import { MyProjectAgent } from ':my-scope/common-constructs';
import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingJWT(
        'https://example.com/.well-known/openid-configuration',
        ['client1', 'client2'], // 허용된 클라이언트 ID (선택 사항)
        ['audience1'],          // 허용된 오디언스 (선택 사항)
      ),
    });
  }
}

Terraform

JWT 인증을 구성하려면 에이전트 모듈의 authorizer_configuration 변수를 다음과 같이 편집할 수 있습니다:

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.id

  # 사용자 풀 및 클라이언트 ID로 교체하거나 변수로 노출
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  authorizer_configuration = {
    custom_jwt_authorizer = {
      discovery_url = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration"
      allowed_clients = local.user_pool_client_ids
    }
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

관측성

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

CloudWatch AWS 콘솔에서 “GenAI Observability”를 선택하여 추적을 찾을 수 있습니다. 추적이 표시되려면 트랜잭션 검색을 활성화해야 합니다.

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

Strands 에이전트 호출

로컬 서버 호출

<your-agent-name>-serve 타겟을 통해 로컬에서 실행 중인 에이전트를 호출하려면 로컬 에이전트가 실행 중인 포트의 /invocations로 간단한 POST 요청을 보낼 수 있습니다. 예를 들어 curl을 사용하면:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -H "Content-Type: application/json"

참고

curl에 제공된 -N 인수는 출력 스트림 버퍼링을 비활성화하여 실시간으로 스트리밍 응답을 볼 수 있게 합니다.

배포된 에이전트 호출

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"
}

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을 호출하는 정확한 방법은 사용된 인증 방법에 따라 다릅니다.

IAM 인증

IAM 인증의 경우 AWS Signature Version 4(SigV4)를 사용하여 요청에 서명해야 합니다.

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock
-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
-H 'Content-Type: application/json'

위 acurl 명령 구성에 대한 자세한 내용은 여기를 클릭하세요

JWT / Cognito 인증

Cognito 인증의 경우 Authorization 헤더에 Cognito 액세스 토큰을 전달합니다:

curl -N -X POST 'https://bedrock
-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"prompt": "what is 3 + 5?", "session_id": "abcdefghijklmnopqrstuvwxyz0123456789"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

AWS CLI의 cognito-idp admin-initiate-auth 명령을 사용하여 액세스 토큰을 얻을 수 있습니다. 예를 들어:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text