파이썬 스트랜드 에이전트

도구를 갖춘 AI 에이전트를 구축하고 선택적으로 Amazon Bedrock AgentCore Runtime에 배포할 수 있는 Python Strands Agent를 생성합니다. 기본적으로 생성기는 FastAPI를 사용하여 HTTP 서버를 노출합니다. 또는 다른 A2A 호환 에이전트와의 상호 운용성을 위해 Agent-to-Agent (A2A) 프로토콜을 선택하거나, CopilotKit을 통한 직접적인 프론트엔드 통합을 위해 AG-UI 프로토콜을 선택할 수 있습니다.

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	-	Strands Agent를 추가할 프로젝트
computeType	string	BedrockAgentCoreRuntime	Strands Agent를 호스팅할 컴퓨팅 유형
name	string	-	Strands Agent의 이름 (기본값: agent)
auth	string	IAM	Strands Agent와 인증하는 데 사용되는 방법입니다. IAM(기본값) 또는 Cognito 중에서 선택하세요.
protocol	string	HTTP	Strands Agent의 서버 프로토콜입니다. HTTP는 FastAPI HTTP 서버를 노출합니다. A2A는 Agent-to-Agent 프로토콜 서버를 노출합니다. AG-UI는 프론트엔드와 직접 통합하기 위한 Agent-User Interaction 프로토콜 서버를 노출합니다.
iacProvider	string	Inherit	선호하는 IaC 공급자. 기본적으로 초기 선택에서 상속됩니다.

생성기 출력

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

HTTP 프로토콜 (기본값)

• 디렉터리your-project/

  • 디렉터리your_module/

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

      • __init__.py 파이썬 패키지 초기화
      • init.py CORS 및 오류 처리 미들웨어가 포함된 FastAPI 애플리케이션 설정
      • agent.py 샘플 도구가 포함된 주요 에이전트 정의
      • main.py Bedrock AgentCore Runtime용 FastAPI 진입점
      • Dockerfile 에이전트 호스팅용 진입점 (computeType이 None으로 설정된 경우 제외)
  • pyproject.toml Strands 종속성으로 업데이트
  • project.json 에이전트 서빙 타겟으로 업데이트

A2A 프로토콜

protocol이 A2A로 설정되면 진입점은 FastAPI 대신 Strands A2A Server를 사용합니다:

• 디렉터리your-project/

  • 디렉터리your_module/

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

      • __init__.py 파이썬 패키지 초기화
      • agent.py 샘플 도구가 포함된 주요 에이전트 정의
      • main.py A2A 서버 진입점
      • Dockerfile 에이전트 호스팅용 진입점 (computeType이 None으로 설정된 경우 제외)
  • pyproject.toml Strands 종속성으로 업데이트
  • project.json 에이전트 서빙 타겟으로 업데이트

AG-UI 프로토콜

protocol이 AG-UI로 설정되면 진입점은 ag-ui-strands 통합을 사용하며, CopilotKit과의 직접적인 프론트엔드 통합을 위해 AG-UI 프로토콜을 통해 에이전트를 노출합니다:

• 디렉터리your-project/

  • 디렉터리your_module/

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

      • __init__.py 파이썬 패키지 초기화
      • agent.py 샘플 도구가 포함된 주요 에이전트 정의
      • main.py ag-ui-strands를 사용하는 AG-UI 서버 진입점
      • Dockerfile 에이전트 호스팅용 진입점 (computeType이 None으로 설정된 경우 제외)
  • pyproject.toml Strands 및 AG-UI 종속성으로 업데이트
  • project.json 에이전트 서빙 타겟으로 업데이트

React 웹사이트에 연결

AG-UI 에이전트는 connection 생성기를 사용하여 React 프론트엔드에 연결할 수 있으며, 풍부한 채팅 경험을 위한 CopilotKit 컴포넌트를 설정합니다.

인프라

서버리스 배포

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 컨스트럭트

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 생성기를 사용하여 생성한 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 문서를 참조하세요.

프로토콜

에이전트의 서버 프로토콜은 통신 방식을 결정합니다. 모든 옵션은 FastAPI에서 제공되며 진입점이 다릅니다:

• HTTP (기본값): 사용자 정의 /invocations 엔드포인트, CORS 및 스트리밍이 포함된 표준 FastAPI 서버. 사용자 정의 클라이언트 통합에 최적.
• A2A: FastAPI 앱에 마운트된 Strands A2A Server. 에이전트가 다른 A2A 호환 에이전트에 의해 검색 및 호출 가능해야 할 때 최적.
• AG-UI: SSE를 통해 AG-UI 프로토콜을 노출하는 ag-ui-strands 통합. React 웹사이트에서 CopilotKit과의 직접적인 프론트엔드 통합에 최적.

모든 프로토콜은 AgentCore 런타임 헬스 체크 계약을 위해 /ping을 노출합니다. A2A 에이전트는 포트 9000에서 수신하고, HTTP 및 AG-UI 에이전트는 포트 8080에서 수신합니다. 생성된 Dockerfile 및 인프라가 자동으로 구성됩니다.

FastAPI 서버 (HTTP 프로토콜)

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

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

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

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

입력 모델 정의

기본 InvokeInput 모델은 메시지를 받습니다.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

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

세션 ID는 Bedrock AgentCore Runtime 세션 계약과 일치하는 x-amzn-bedrock-agentcore-runtime-session-id HTTP 헤더에서 추출됩니다. 헤더가 제공되지 않으면 대체 방법으로 무작위 UUID가 생성됩니다.

코드 구성

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

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

출력 모델 정의

스트리밍 응답의 경우 생성기는 JsonStreamingResponse를 제공하며, 이는 Pydantic 모델을 JSON Lines 형식(application/jsonl)으로 자동 직렬화합니다. 이 형식은 OpenAPI 3.2의 스트리밍 사양과 호환되며 생성된 TypeScript 클라이언트와 원활하게 작동합니다.

기본적으로 에이전트는 에이전트의 응답 텍스트를 포함하는 StreamChunk 객체를 yield합니다:

class StreamChunk(BaseModel):
    content: str

필요에 맞게 StreamChunk 모델을 사용자 정의할 수 있습니다:

from pydantic import BaseModel

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

FastAPI 스트리밍 제한

FastAPI가 현재 스트리밍 응답에 대한 OpenAPI 사양 생성을 지원하지 않으므로, 각 스트리밍 작업에 대해 응답 모델을 명시적으로 설정해야 합니다:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

FastAPI의 네이티브 지원을 위한 기능 요청이 진행 중입니다.

Bedrock AgentCore Python SDK

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

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

Infrastructure as Code

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

A2A 서버 (A2A 프로토콜)

protocol=A2A인 경우 생성된 main.py는 /ping도 노출하는 상위 FastAPI 앱에 A2AServer.to_fastapi_app()을 마운트합니다. AgentCore에 배포되면 진입점은 AppConfig에서 런타임의 공개 ARN을 확인하고 에이전트 카드에 광고합니다.

대부분의 사용자는 이 파일을 수정할 필요가 없습니다 — 도구나 시스템 프롬프트를 변경하려면 agent.py를 편집하세요. A2A 서버는 Agent 생성자의 name 및 description에서 에이전트 카드(/.well-known/agent-card.json)를 채웁니다.

AG-UI 서버 (AG-UI 프로토콜)

protocol=AG-UI인 경우 생성된 main.py는 Strands Agent를 ag_ui_strands.StrandsAgent로 래핑하고 create_strands_app()을 통해 FastAPI 앱을 생성합니다. 결과 앱은 Server-Sent Events(SSE)를 통해 AG-UI 이벤트를 스트리밍하는 단일 POST 엔드포인트와 AgentCore 런타임 헬스 체크를 위한 /ping을 노출합니다.

대부분의 사용자는 이 파일을 수정할 필요가 없습니다 — 도구나 시스템 프롬프트를 변경하려면 agent.py를 편집하세요.

React 웹사이트에 연결

AG-UI 에이전트는 프론트엔드에서 직접 사용되도록 설계되었습니다. connection 생성기를 사용하여 CopilotKit 프로바이더와 AG-UI HttpAgent 클라이언트로 React 웹사이트를 에이전트에 연결하세요.

Strands 에이전트 실행

로컬 개발

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

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

이 명령은 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) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Alpha CDK 컨스트럭트

이 구성은 @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"
}

Bedrock 모델 권한

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

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

Docker 필요

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

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

인증

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

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

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

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

  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 인증만 지원합니다.

번들 및 도커 타겟

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

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

또한 Strands 에이전트 전용 docker 타겟이 추가되어 Dockerfile 및 번들된 아티팩트를 도커 컨텍스트 디렉토리로 복사합니다. 이렇게 하면 Dockerfile이 빌드 출력과 함께 배치되어 CDK가 AgentRuntimeArtifact.fromAsset을 사용하여 Docker 이미지를 직접 빌드할 수 있습니다.

관측성

에이전트는 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 '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Curl 스트리밍 플래그

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 '{"message": "what is 3 + 5?"}' \
-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 '{"message": "what is 3 + 5?"}' \
  -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

브라우저 / React 웹사이트

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

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 생성기 가이드를 참조하세요.

A2A 에이전트를 도구로 호출

이 에이전트에서 원격 A2A 에이전트(TypeScript 또는 Python)로 작업을 위임하려면 connection 생성기를 사용하세요. 이 생성기는 대상 에이전트에 대한 SigV4 인증 클라이언트를 제공하고 이 에이전트의 agent.py를 AST 변환하여 원격 A2A 에이전트를 @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 생성기 가이드를 참조하세요.