Python Agent

도구를 갖춘 AI 에이전트를 구축하기 위한 Python AI 에이전트를 생성하고, 선택적으로 Amazon Bedrock AgentCore Runtime에 배포합니다. framework 옵션으로 에이전트 프레임워크를 선택하세요: Strands (기본값) 또는 LangChain (LangGraph 기반).

생성기는 서버 protocol을 통해 에이전트를 노출합니다. 두 프레임워크 모두 HTTP (기본값), 다른 A2A 호환 에이전트와의 상호 운용을 위한 Agent-to-Agent (A2A) 프로토콜, 그리고 CopilotKit을 통한 직접 프론트엔드 통합을 위한 AG-UI 프로토콜을 지원합니다.

사용법

에이전트 생성

Python Agent를 생성하는 두 가지 방법이 있습니다:

이 제너레이터 실행@aws/nx-plugin:py#agent

CLI
VSCode

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

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

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

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

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

명령 구성하기9

project필수

framework

authinfra = agentcore | agentcore-ecr

protocol

iac

infra

session

name

preferInstallDependencies

true

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

옵션

제너레이터 옵션9 옵션

project필수string: Agent를 추가할 프로젝트
frameworkenum기본값: strands: 사용할 에이전트 SDK입니다.
strandslangchain
authenuminfra = agentcore | agentcore-ecr기본값: iam: 에이전트 인증에 사용되는 방법입니다. infra가 설정된 경우에만 적용됩니다 (infra가 none일 때는 무시됨).
iamcognito
protocolenum기본값: http: Agent의 서버 프로토콜입니다. HTTP는 FastAPI HTTP 서버를 노출합니다. A2A는 Agent-to-Agent 프로토콜 서버를 노출합니다. AG-UI는 프론트엔드와 직접 통합하기 위한 Agent-User Interaction 프로토콜 서버를 노출합니다.
httpa2aag-ui
iacenum기본값: inherit: 선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.
inheritcdkterraform
infraenum기본값: agentcore: Agent를 호스팅할 인프라 유형입니다. agentcore는 가장 빠른 빌드 및 배포 주기를 위해 코드를 zip으로 AgentCore 관리 런타임에 배포합니다. agentcore-ecr은 OS 수준 제어 또는 기존 컨테이너 파이프라인을 위해 컨테이너 이미지를 빌드하고 호스팅합니다.
agentcoreagentcore-ecrnone
sessionenum기본값: s3: Agent의 세션을 유지하는 데 사용되는 스토리지입니다. LangChain은 's3' 또는 'dynamodb-s3'를 지원하고, Strands는 's3'를 지원하며, 'in-memory'는 둘 다에서 유효합니다.
s3dynamodb-s3in-memory
namestring: Agent의 이름 (기본값: agent)
preferInstallDependenciesboolean기본값: true: 생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번 설치합니다.

생성기 출력

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

HTTP 프로토콜 (기본값)

디렉터리your-project/
- 디렉터리your_module/
  - 디렉터리agent/ (or custom name if specified)
    __init__.py Python package initialization
    init.py FastAPI application setup with CORS and error handling middleware
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    디렉터리middleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with Strands dependencies
- project.json Updated with agent serve targets

A2A 프로토콜

엔트리 포인트는 A2A 프로토콜을 통해 에이전트를 노출합니다 (Strands는 Strands A2A Server를 사용하고, LangChain은 그래프를 a2a-sdk 실행기로 래핑), FastAPI 앱에 마운트됩니다:

디렉터리your-project/
- 디렉터리your_module/
  - 디렉터리agent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    디렉터리middleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py A2A server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

AG-UI 프로토콜

엔트리 포인트는 CopilotKit을 통한 직접 프론트엔드 통합을 위해 AG-UI 프로토콜을 통해 에이전트를 노출합니다. Strands 에이전트는 ag-ui-strands 통합을 사용하고, LangChain 에이전트는 ag-ui-langgraph를 사용합니다:

디렉터리your-project/
- 디렉터리your_module/
  - 디렉터리agent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    디렉터리middleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py AG-UI server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

인프라

infra 옵션은 Amazon Bedrock AgentCore Runtime에서 코드를 패키징하고 호스팅하는 방법을 선택합니다:

agentcore (기본값)은 직접 코드 배포를 사용합니다: 빌드된 코드가 .zip으로 패키징되어 S3에 업로드되고 AgentCore 관리형 언어 런타임에서 실행됩니다. 컨테이너 이미지를 빌드하거나, ECR 리포지토리를 관리하거나, 이미지를 푸시할 필요가 없어 빌드 및 배포 주기가 훨씬 빠릅니다.
**agentcore-ecr**은 제공된 Dockerfile에서 arm64 컨테이너 이미지를 빌드하고 워크스페이스의 다른 모든 컨테이너와 함께 공유 core/asset-ecr 레지스트리에서 호스팅합니다. 운영 체제 이미지를 제어해야 하는 경우(예: 네이티브 시스템 라이브러리 설치) 또는 기존 컨테이너 파이프라인이 있는 경우 이 옵션을 선택하세요. 이 옵션은 추가로 Trivy 이미지 스캔 대상을 제공합니다(아래 이미지 스캐닝 참조).
**none**은 인프라를 전혀 생성하지 않으므로 프로젝트를 로컬에서만 실행할 수 있습니다.

이 생성기는 선택한 iac를 기반으로 코드형 인프라를 제공하므로, 관련 CDK constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

CDK
Terraform

디렉터리packages/common/constructs
- 디렉터리src
  - 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs
    …
  - 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs
    …
  - index.ts app에서 constructs를 내보내는 진입점
- project.json 프로젝트 빌드 타겟 및 구성

디렉터리packages/common/terraform
- 디렉터리src
  - 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Terraform 모듈
    …
  - 디렉터리core/ app의 모듈에서 재사용되는 일반 모듈
    …
- project.json 프로젝트 빌드 타겟 및 구성

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

CDK
Terraform

디렉터리packages/common/constructs/src
- 디렉터리app
  - 디렉터리agents
    디렉터리<agent-name>
    <agent-name>.ts CDK construct for deploying your agent

디렉터리packages/common/terraform/src
- 디렉터리app
  - 디렉터리agents
    디렉터리<agent-name>
    <agent-name>.tf Module for deploying your agent
- 디렉터리core
  - 디렉터리agent-core
    runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
  - 디렉터리agent-core-code (when infra is agentcore)
    runtime.tf Packages your agent’s code and delegates to agent-core
  - 디렉터리agent-core-container (when infra is agentcore-ecr)
    runtime.tf Builds and publishes your agent’s image and delegates to agent-core

infra에 none을 선택한 경우, CDK 구성 요소나 Terraform 모듈이 생성되지 않으며 에이전트는 로컬에서만 실행할 수 있습니다. 호스팅된 엔드포인트가 없으므로 이 모드에서는 auth 옵션이 무시됩니다.

아키텍처

Bedrock AgentCore Runtime에 배포되면, 에이전트의 코드는 zip으로 패키징되어 AgentCore 관리형 런타임에서 실행됩니다. 클라이언트는 AgentCore Runtime 데이터 플레인 엔드포인트를 호출하며, 이는 요청을 에이전트로 전달합니다. 에이전트는 모델 추론을 위해 Amazon Bedrock을 호출하고 도구, MCP 서버 또는 다운스트림 API를 호출할 수 있습니다.

Loading the diagram…

infra: agentcore-ecr을 사용하면 에이전트는 컨테이너 이미지로 빌드되어 Amazon ECR에 푸시되고 AgentCore Runtime에서 실행됩니다. 이를 통해 런타임 환경에 대한 OS 수준의 제어가 가능하지만, 위의 zip 패키징보다 빌드 및 배포 주기가 더 길어집니다.

Loading the diagram…

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

Loading the diagram…

에이전트 작업하기

agent.py를 편집하여 도구를 추가하고, 모델을 구성하고, 시스템 프롬프트를 커스터마이즈할 수 있습니다. API는 선택한 프레임워크에 따라 다릅니다.

도구 추가하기

도구는 AI 에이전트가 작업을 수행하기 위해 호출할 수 있는 함수입니다. 두 프레임워크 모두 도구 정의에 데코레이터 기반 접근 방식을 사용하며, 함수 이름과 독스트링에서 도구 이름과 설명을 도출하고, 타입 힌트에서 입력 스키마를 생성합니다.

도구를 정의한 다음 get_agent() 내부의 tools 목록에 추가하세요:

Strands
LangChain

from contextlib import contextmanager

from strands import Agent, tool
from strands.hooks import HookCallback, HookProvider
from strands_tools import current_time
from my_scope_agent_connection import log_model_errors, log_tool_errors

from .session import get_session_manager


@tool
def subtract(a: int, b: int) -> int:
    return a - b


@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"


AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]


@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant with access to various tools.",
        tools=[subtract, current_time, get_weather],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

import os

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

from .session import get_checkpointer

REGION = os.environ.get("AWS_REGION", "us-east-1")
MODEL_ID = os.environ.get("MODEL_ID", "global.anthropic.claude-haiku-4-5-20251001-v1:0")


@tool
def subtract(a: int, b: int) -> int:
    """Subtract b from a."""
    return a - b


@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"


def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[subtract, get_weather],
        system_prompt="You are a helpful assistant with access to various tools.",
        checkpointer=get_checkpointer(),
    )

Strands는 strands-agents-tools 패키지를 통해 사전 구축된 도구 모음을 제공하며, 생성기는 이미 프로젝트의 pyproject.toml에 이를 추가합니다. 원하는 도구를 임포트하고 get_agent()에 추가하세요:

from strands_tools import current_time, file_read, http_request

# ...

@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[current_time, file_read, http_request],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

LangChain은 방대한 도구 및 통합 생태계를 제공하며, 각각 자체 패키지로 배포됩니다. 생성기는 이를 추가하지 않으므로 먼저 필요한 것을 설치하세요 — 예를 들어 아래 검색 도구가 포함된 langchain-community:

pnpm nx run <project-name>:add langchain-community

yarn nx run <project-name>:add langchain-community

npx nx run <project-name>:add langchain-community

bunx nx run <project-name>:add langchain-community

그런 다음 도구를 임포트하고 get_agent()에 추가하세요:

from langchain_community.tools import DuckDuckGoSearchRun

# ...

def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[DuckDuckGoSearchRun()],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

모델 구성

Strands
LangChain

생성된 에이전트는 Amazon Bedrock의 기본 Strands 모델을 사용합니다. 이를 구성하려면 Agent에 model을 전달하세요. 사용 가능한 공급자와 옵션은 Strands 모델 공급자 문서를 참조하세요:

from strands.models import BedrockModel

# ...

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

@contextmanager
def get_agent():
    yield Agent(
        model=MODEL,
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[subtract, current_time],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

LangChain 에이전트는 ChatBedrockConverse 모델을 사용합니다. 생성된 에이전트는 MODEL_ID 및 AWS_REGION 환경 변수에서 모델 ID와 리전을 읽으며, 인프라가 배포된 에이전트에 대해 이를 설정합니다. 모델을 추가로 구성하려면 get_agent()에서 구성되는 위치에 인수를 추가하세요:

# ...

def get_agent():
    model = ChatBedrockConverse(
        model=MODEL_ID,
        region_name=REGION,
        temperature=0.3,
    )
    return create_agent(
        model=model,
        tools=[subtract],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

MCP 서버 사용하기

py#mcp-server 또는 ts#mcp-server 생성기를 사용하여 생성한 MCP 서버를 사용하려면 connection 생성기를 활용할 수 있으며, 이는 두 프레임워크 모두에서 MCP 서버의 도구를 에이전트에 연결합니다.

이 제너레이터 실행@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

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

더 알아보기

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

프로토콜

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

HTTP (기본값): 커스텀 /invocations 엔드포인트, CORS, 스트리밍을 갖춘 표준 FastAPI 서버. 커스텀 클라이언트 통합에 가장 적합합니다.
A2A: FastAPI 앱에 마운트된 Agent-to-Agent 서버 (Strands는 Strands A2A Server를 사용하고, LangChain은 프레임워크 독립적인 a2a-sdk를 사용). 에이전트가 다른 A2A 호환 에이전트에 의해 검색되고 호출될 수 있어야 할 때 가장 적합합니다.
AG-UI: SSE를 통한 AG-UI 프로토콜 (Strands는 ag-ui-strands를 사용하고, LangChain은 ag-ui-langgraph를 사용). React 웹사이트에서 CopilotKit을 통한 직접 프론트엔드 통합에 가장 적합합니다.

서버 엔트리 포인트는 프레임워크에 따라 다르지만 (Strands는 컨텍스트 관리되는 Agent를 생성하고, LangChain은 컴파일된 create_agent 그래프를 구동), 각 프로토콜의 외부 계약은 동일합니다.

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

FastAPI 서버 (HTTP 프로토콜)

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

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

Pydantic으로 호출 입출력 커스터마이즈하기

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

입력 모델 정의하기

기본 InvokeInput 모델은 프롬프트를 받습니다.

from pydantic import BaseModel, Field

class InvokeInput(BaseModel):
    prompt: str = Field(max_length=100000)

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

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

출력 모델 정의하기

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

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

class StreamChunk(BaseModel):
    content: str

필요에 맞게 StreamChunk 모델을 커스터마이즈할 수 있습니다:

from pydantic import BaseModel

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

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 기능에 대한 자세한 내용은 여기 문서에서 확인할 수 있습니다.

A2A 서버 (A2A 프로토콜)

생성된 main.py는 /ping도 노출하는 상위 FastAPI 앱에 A2A 서버를 마운트합니다. Strands 에이전트는 Strands A2AServer를 사용하고, LangChain 에이전트는 컴파일된 그래프를 a2a-sdk AgentExecutor로 래핑합니다. 에이전트 카드에 광고되는 URL은 AGENTCORE_RUNTIME_URL 환경 변수에서 가져오며, 로컬 개발의 경우 http://localhost:<port>/로 대체됩니다.

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

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

생성된 main.py는 Server-Sent Events (SSE)를 통해 AG-UI 이벤트를 스트리밍하는 단일 POST 엔드포인트와 AgentCore 런타임 헬스 체크를 위한 /ping을 노출합니다. 연결 방식은 프레임워크에 따라 다릅니다:

Strands: Agent를 ag_ui_strands.StrandsAgent로 래핑하고, FastAPI lifespan 핸들러 내부에서 구축(임포트 시간이 아닌 컨테이너/세션 시작 시 구성이 이루어짐)하여 직접 작성된 FastAPI /invocations 루프에서 제공합니다.
LangChain: 컴파일된 그래프를 ag_ui_langgraph.LangGraphAgent로 래핑하고, lifespan 내부에서 동일한 방식으로 구축하여 직접 작성된 FastAPI /invocations 루프에서 제공합니다.

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

에이전트 실행하기

로컬 개발

에이전트(및 연결된 모든 것)를 로컬에서 실행하려면 프로젝트의 dev 타겟을 사용하세요:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

프로젝트에 여러 컴포넌트(에이전트, MCP 서버 등)를 추가한 경우 모두 시작됩니다. 이 에이전트만 실행하려면 <your-agent-name>-dev 타겟을 지정하세요:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

이는 uv run을 사용하여 Bedrock AgentCore Python SDK로 에이전트를 실행합니다.

에이전트는 생성 시 워크스페이스 풀에서 할당된 포트에서 수신합니다. 프로젝트의 project.json에서 metadata.ports를 읽거나 <your-agent-name>-dev 타겟의 명령에서 --port 플래그를 읽으세요. 아래 예제는 새 워크스페이스에서 첫 번째 HTTP 에이전트에 할당되는 포트인 8081을 사용합니다.

<your-agent-name>-serve 타겟도 생성되며, 배포된 인프라에 대해 에이전트를 실행하므로 RUNTIME_CONFIG_APP_ID를 설정해야 합니다. dev와 serve의 차이점은 로컬 개발 가이드를 참조하세요.

에이전트와 채팅하기

생성기는 에이전트와 대화형 터미널 채팅을 시작하는 <your-agent-name>-chat Nx 타겟을 구성합니다.

채팅 타겟은 독립적으로 실행됩니다. 기본적으로 로컬에서 실행 중인 에이전트에 연결되므로, 먼저 에이전트의 <your-agent-name>-dev 타겟을 시작하세요 (별도의 터미널에서):

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

그런 다음 다른 터미널에서 채팅을 시작하세요:

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

생성기는 모든 프로토콜에 대해 scripts/<your-agent-name>/chat.ts를 생성합니다. 기본적으로 로컬 에이전트에 연결하거나, RUNTIME_CONFIG_APP_ID가 설정된 경우 배포된 에이전트에 연결합니다 (아래 배포된 에이전트와 채팅하기 참조).

HTTP 에이전트의 경우, 채팅 스크립트는 에이전트의 OpenAPI 스펙에서 생성된 타입 안전 TypeScript 클라이언트를 사용합니다. 생성기는 또한 다음을 생성합니다:

scripts/<your_agent_name>_openapi.py — 에이전트의 OpenAPI 스펙을 내보내는 작은 스크립트 (에이전트 이름을 snake_case로 사용)
이를 실행하는 <your-agent-name>-openapi Nx 타겟
scripts/<your-agent-name>/generated/ 아래에 타입 안전 TypeScript 클라이언트를 생성하는 <your-agent-name>-generate-client Nx 타겟

에이전트의 입력 형태를 커스터마이즈할 때 (예: InvokeInput에 새 필드 추가), chat.ts를 업데이트하여 에이전트 호출 시 새 필드를 전달하면 나머지는 자동으로 작동합니다.

배포된 에이전트와 채팅하기

Bedrock AgentCore에 배포된 에이전트와 채팅하려면 RUNTIME_CONFIG_APP_ID 환경 변수를 배포 스택에서 RuntimeConfigApplicationId로 출력된 AppConfig 애플리케이션 ID로 설정하세요. 채팅 스크립트는 런타임 구성에서 에이전트의 런타임 ARN을 확인하고 배포된 엔드포인트에 연결합니다:

IAM
Cognito

IAM 인증 에이전트의 경우, 요청은 기본 AWS 자격 증명을 사용하여 SigV4로 서명됩니다. 환경에 런타임을 호출할 권한이 있는 AWS 자격 증명이 있는지 확인하세요:

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Cognito 인증 에이전트의 경우, AGENT_ACCESS_TOKEN 환경 변수를 통해 Cognito 액세스 토큰을 제공하면 베어러 토큰으로 전송됩니다:

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

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> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Bedrock AgentCore Runtime에 에이전트 배포하기

Infrastructure as Code

infra에 대해 agentcore 또는 agentcore-ecr을 선택한 경우, 관련 CDK 또는 Terraform 인프라가 생성되며 이를 사용하여 Agent를 Amazon Bedrock AgentCore Runtime에 배포할 수 있습니다.

CDK
Terraform

제너레이터를 실행할 때 선택한 name을 기반으로 하거나 기본적으로 <ProjectName>Agent로 명명된 Agent용 CDK 구성이 생성됩니다.

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

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

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

제너레이터를 실행할 때 선택한 name을 기반으로 하거나 기본적으로 <ProjectName>-agent로 명명된 Terraform 모듈이 생성됩니다.

공유된 runtime_config_appconfig 모듈의 출력을 에이전트 모듈에 전달하고, 패키징에 사용되는 공유 아티팩트 저장소도 함께 전달하세요. 기본 agentcore 패키징에서는 에이전트의 코드가 공유 자산 버킷에 스테이징되므로 Lambda 및 API 모듈이 이미 수행하는 것처럼 배포당 한 번 core/asset-bucket 모듈을 인스턴스화하세요:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

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

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

agentcore-ecr에서는 에이전트의 이미지가 대신 공유 자산 레지스트리에 게시되므로 버킷 대신 core/asset-ecr의 출력을 전달하세요. 하나의 레지스트리가 워크스페이스의 모든 컨테이너를 제공하므로 에이전트는 자체 리포지토리가 필요하지 않습니다:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

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

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

Authentication

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

IAM

기본적으로 Agent는 IAM 인증을 사용하여 보호되며, 인수 없이 배포하면 됩니다:

CDK
Terraform

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

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# 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

  # Under `agentcore-ecr`, pass `core/asset-ecr`'s outputs instead.
  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_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 Authentication

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

CDK
Terraform

생성된 구성은 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#website#auth 제너레이터를 사용하여 생성할 수 있으며, 또는 자체 CDK UserPool 및 UserPoolClient를 생성할 수 있습니다.

생성된 모듈은 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]
}

번들 및 Docker 타겟

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

uv export를 사용하여 Python 의존성을 requirements.txt 파일로 내보냅니다
대상 플랫폼(aarch64-manylinux_2_28)용 의존성을 uv pip install로 설치합니다

<your-agent-name>-package 타겟도 추가되며, 배포 가능한 코드 패키지를 조립합니다: aarch64 의존성 번들, Python 모듈 트리, 그리고 루트 main.py 엔트리 포인트. 생성된 인프라는 이 디렉토리를 .zip으로 업로드합니다 — CDK에서는 AgentRuntimeArtifact.fromCodeAsset을 통해, Terraform에서는 공유 자산 버킷에 아카이브됩니다.

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

이미지 스캔

이 프로젝트를 위해 빌드된 Docker 이미지는 ECR 호스팅 Trivy 이미지에서 실행되는 Trivy를 사용하여 취약점을 스캔할 수 있습니다.

trivy 타겟이 프로젝트에 추가되어 빌드된 이미지를 스캔하고 HIGH 또는 CRITICAL 심각도의 취약점이 발견되면 0이 아닌 값으로 종료합니다. 생성된 Dockerfile은 생성 시점에 이러한 심각도의 알려진 수정 가능한 취약점이 없는 베이스 이미지를 사용하며, 번들된 도구(예: npm)를 업그레이드하여 이를 유지합니다.

스캔은 이미지 빌드와 동일한 컨테이너 엔진(docker 또는 finch)을 사용하므로 추가 도구가 필요하지 않습니다. 스캔은 캐시되지 않습니다. 읽는 이미지가 디스크가 아닌 컨테이너 엔진에 있기 때문입니다. 따라서 항상 실제 이미지를 스캔하며, 더 이상 존재하지 않는 이미지에 대해 캐시된 통과를 보고하는 대신 명확하게 실패합니다. 따라서 각 실행은 이미지당 수십 초가 걸리며 Trivy의 취약점 데이터베이스를 새로 고치므로 네트워크 액세스가 필요합니다. 제공되는 trivy 루트 스크립트는 워크스페이스의 모든 이미지를 스캔합니다:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Trivy 결과 억제

특정 취약점을 억제하고 싶은 경우가 있을 수 있습니다. 예를 들어 아직 수정 사항이 없고 위험을 허용 가능한 것으로 평가한 경우입니다.

프로젝트 루트의 .trivyignore 파일(즉, project.json 옆)에 취약점 ID를 한 줄에 하나씩 추가하세요:

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

결과 필터링에 대한 자세한 내용은 Trivy 필터링 문서를 참조하세요.

관찰 가능성

에이전트는 AWS Distro for Open Telemetry (ADOT)를 사용한 관찰 가능성으로 자동 구성됩니다.

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

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

세션 관리

session 옵션은 선택한 프레임워크에 따라 다른 기본 지속성 개념에 매핑됩니다: strands 프레임워크의 경우 Strands의 세션 관리 개념, langchain 프레임워크의 경우 LangGraph의 체크포인터 개념.

session 옵션은 Strands SDK의 SessionManager를 사용하여 에이전트가 호출 간에 대화 상태(메시지 기록, 도구 상태 등)를 유지하는 방법을 제어합니다:

s3 (기본값): CDK/Terraform 인프라는 세션 데이터를 위한 전용 S3 버킷을 프로비저닝하며, 전용 KMS 키로 암호화되고 모든 공개 액세스가 차단됩니다. 서버 액세스 로그는 동일한 키를 통해 CloudWatch Logs 로그 그룹으로 전달됩니다. 에이전트의 IAM 역할에는 버킷에 대한 읽기/쓰기/목록/삭제 액세스와 키에 대한 복호화/데이터 키 생성 액세스가 부여되며, 버킷 이름은 AppConfig 런타임 구성에 에이전트의 ARN과 함께 등록됩니다.
in-memory: 버킷이 프로비저닝되지 않습니다. 대화 상태는 실행 중인 프로세스의 수명 동안만 메모리에 유지되며 재시작이나 스케일 인 시 유지되지 않습니다.

이는 생성된 session.py에 구현되며, 현재 세션에 대한 SessionManager를 확인하는 get_session_manager() 함수를 내보냅니다.

세션 ID 자체는 AgentCore Runtime 세션에서 가져오며 (x-amzn-bedrock-agentcore-runtime-session-id 헤더를 통해 전파), contextvars.ContextVar 기반 컨텍스트에 바인딩되어 get_current_session_id()가 요청의 어디서든 확인할 수 있습니다 — connection 생성기를 통해 연결된 다운스트림 MCP 또는 A2A 클라이언트 포함, 전체 호출 체인이 일관된 세션을 공유합니다.

세션을 소유자로 제한하기

세션 ID는 호출자로부터 전달되므로, 그 자체로는 대화를 식별하지만 대화가 누구에게 속하는지는 식별하지 않습니다. AgentCore Runtime은 개별 세션이 아닌 에이전트 런타임 리소스 ARN에 대해 호출을 승인하므로, 에이전트가 애플리케이션에서 세션이 무엇을 의미하는지 자유롭게 결정할 수 있습니다.

각 사용자를 자신의 대화로 제한하려면:

tRPC, FastAPI 또는 Smithy를 사용하여 세션을 생성하는 API를 추가하세요. 불투명한 세션 ID(최소 33자)를 생성하고 호출 사용자의 ID와 함께 저장하세요 — 예를 들어 py#dynamodb 생성기로 생성된 테이블에. 각 API 가이드는 호출 사용자의 ID를 검색하는 방법을 보여줍니다.
에이전트에서 제공된 세션 ID에 대해 저장된 사용자 ID를 조회하고, 호출자와 일치하지 않으면 요청을 거부하세요. auth=cognito를 사용하면 호출자의 JWT가 에이전트 코드에 도달하므로 sub 클레임이 호출자를 식별합니다.

대화 이름과 같은 사용자 제공 값에서 파생하는 대신 세션 ID를 생성하세요 — 호출자가 예측할 수 있는 것은 호출자가 보낼 수 있습니다.

session 옵션은 에이전트의 LangGraph 체크포인터가 대화 상태를 유지하는 방법을 제어합니다:

s3 (기본값): 배포된 에이전트는 프로비저닝된 세션 버킷과 함께 S3CheckpointSaver를 사용하여 checkpoints/ 접두사 아래에 체크포인트와 보류 중인 쓰기를 저장합니다. 이 클래스는 공유 에이전트 연결 프로젝트의 s3_checkpoint_saver_langchain.py에 있습니다.
dynamodb-s3: CDK/Terraform 인프라는 체크포인트를 위한 DynamoDB 테이블을 프로비저닝하며, LangGraph 에이전트의 체크포인트 저장소로 DynamoDB 사용에 관한 AWS 문서에서 권장하는 대로 구성됩니다 (통합 PK/SK 스키마, PAY_PER_REQUEST 청구, 특정 시점 복구, ttl 속성), 350KB를 초과하는 체크포인트를 오프로드하기 위한 S3 버킷도 포함됩니다. 둘 다 전용 KMS 키로 암호화되며, 버킷의 서버 액세스 로그는 동일한 키를 통해 CloudWatch Logs 로그 그룹으로 전달됩니다. 에이전트의 IAM 역할에는 테이블과 버킷에 대한 읽기/쓰기 액세스가 부여되며, 테이블/버킷 이름은 AppConfig 런타임 구성에 에이전트의 ARN과 함께 등록됩니다.
in-memory: 테이블이나 버킷이 프로비저닝되지 않습니다. 대화 상태는 실행 중인 프로세스의 수명 동안만 메모리에 유지되며 재시작이나 스케일 인 시 유지되지 않습니다.

이는 생성된 session.py에 구현되며, agent.py의 create_agent(..., checkpointer=get_checkpointer())에서 호출되는 get_checkpointer() 함수를 내보냅니다.

에이전트 호출하기

로컬 서버 호출하기

<your-agent-name>-dev 타겟으로 에이전트를 시작하세요:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

그런 다음 로컬 에이전트가 실행 중인 포트의 /invocations에 POST 요청을 보내세요. 에이전트에 할당된 포트로 대체하세요 — 프로젝트의 project.json에서 metadata.ports를 읽거나 <your-agent-name>-dev 타겟의 명령에서 --port 플래그를 읽으세요. 새 워크스페이스의 첫 번째 HTTP 에이전트는 8081이 할당됩니다:

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

배포된 에이전트 호출하기

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

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

CDK
Terraform

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

# 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

인프라에서 ARN 인코딩을 처리하여 전체 호출 URL을 직접 출력할 수도 있습니다:

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

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

IAM
Cognito

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?"}' \
-H 'Content-Type: application/json'

Click here for more details on configuring the above acurl command

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?"}' \
  -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 웹사이트에서 에이전트를 호출하려면 connection 생성기를 활용할 수 있으며, 올바른 인증(IAM 또는 Cognito)으로 클라이언트를 자동으로 설정합니다.

이 제너레이터 실행@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

A2A 에이전트를 도구로 호출하기

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

이 제너레이터 실행@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

AG-UI 에이전트 호출하기

React 웹사이트에서 AG-UI 에이전트를 호출하려면 connection 생성기를 사용하세요. 이는 올바른 인증(IAM 또는 Cognito)으로 배포된 에이전트에 구성된 CopilotKit 클라이언트를 연결합니다.

이 제너레이터 실행@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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

명령 구성하기5

sourceProject필수

targetProject필수

sourceComponent

targetComponent

preferInstallDependencies

true

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

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

에이전트 보안

에이전트는 신뢰할 수 없는 입력에 대해 작동하며 도구를 통해 실제 작업을 수행할 수 있으므로, 처음부터 보안을 고려할 가치가 있습니다. 다음 관행은 생성된 에이전트에 적용됩니다.

모델 입력 및 출력을 신뢰할 수 없는 것으로 취급

프롬프트에는 적대적인 지시사항(프롬프트 인젝션)이 포함될 수 있으며, 모델 출력은 비결정적입니다. 따라서 보안에 민감한 로직에서 둘 다 신뢰해서는 안 됩니다:

생성된 예제 도구와 같이 도구에 대해 엄격한 입력 스키마를 정의하세요. 자유 형식 문자열을 허용하는 대신 도구가 실제로 필요로 하는 값(열거형, 길이 제한, 숫자 범위)으로 제한하세요.
모델 출력을 검증이나 인코딩 없이 셸 명령, SQL 쿼리, 코드 평가 또는 렌더링된 HTML에 직접 전달하지 마세요.
도구 및 다운스트림 서비스에 권한 부여 검사를 적용하세요. 모델이 액세스 권한이 있는 도구를 오용하지 못하도록 시스템 프롬프트에만 의존하지 마세요.

Strands의 Prompt Engineering 및 Responsible AI 가이드는 견고하고 안전을 고려한 시스템 프롬프트 작성을 다룹니다.

도구 권한을 엄격하게 범위 지정

에이전트의 IAM 역할에 도구가 필요로 하는 권한만 부여하세요. 제공되는 CDK 구성 요소 및 Terraform 모듈은 이러한 목적을 위해 grant* 메서드와 범위가 지정된 정책을 노출합니다. 예를 들어 광범위한 관리형 정책을 연결하는 대신 특정 API를 호출할 수 있는 액세스 권한을 에이전트에 부여합니다. 도구가 사용자를 대신하여 작동하는 경우, 에이전트 자체의 앰비언트 권한보다 호출하는 사용자의 ID(요청 컨텍스트를 통해 전달됨)를 사용하여 작업을 승인하는 것을 선호하세요.

킬 스위치 제공

모델 동작이 예상치 못한 방식으로 변경될 수 있으므로, 코드 변경 없이 모델을 신속하게 비활성화하거나 교체할 수 있도록 계획하세요:

운영자가 구성을 업데이트하여 다른 모델로 전환하거나 롤백할 수 있도록 구성에서 모델 ID를 읽으세요(예: MODEL_ID 환경 변수).
AI 기능을 완전히 비활성화할 수 있도록 기능 플래그 뒤에 에이전트를 배치하세요. 비활성화된 경우 오류 대신 일반 메시지를 반환하고, 애플리케이션의 나머지 부분이 정상적으로 저하되도록 하세요.

운영 런북에 이러한 제어를 전환하는 방법을 문서화하세요.

민감한 데이터 보호

사용자 데이터가 포함될 수 있는 프롬프트 및 완료를 로깅하지 마세요. 생성된 에이전트의 모델 오류 로깅 후크는 대화 내용이 아닌 오류 메타데이터만 로깅합니다. 자체 로깅을 추가할 때 이 속성을 유지하세요.
사용자에게 일반적인 오류 메시지를 반환하고, 상세한 오류는 서버 측에서 로깅하세요.
사용자와 세션 간에 대화 상태를 격리하고, 지속된 세션 데이터에 대한 액세스를 승인하세요.
프롬프트 및 출력에서 개인 식별 정보(PII)를 수정하세요. Bedrock Guardrail 민감한 정보 필터(아래 참조) 또는 Strands 에이전트의 경우 PII Redaction 가이드의 접근 방식을 사용하세요.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails는 모델 입력 및 출력에서 평가되는 구성 가능한 콘텐츠 필터, 거부된 주제 및 민감한 정보(PII) 필터를 제공합니다. 생성된 에이전트가 사용하는 모델에 가드레일을 연결할 수 있습니다:

Strands
LangChain

import os

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
    model_id=os.environ.get("MODEL_ID"),
    guardrail_id=os.environ["GUARDRAIL_ID"],
    guardrail_version=os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
)

agent = Agent(model=model)

자세한 내용은 Strands 가드레일 가이드를 참조하세요.

import os

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model=os.environ.get("MODEL_ID"),
    guardrail_config={
        "guardrailIdentifier": os.environ["GUARDRAIL_ID"],
        "guardrailVersion": os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
    },
)

guardrail_config 필드에 대한 자세한 내용은 ChatBedrockConverse 문서를 참조하세요.

연결

connection 생성기를 사용하여 이 프로젝트를 워크스페이스의 다른 프로젝트와 통합하세요. 이 프로젝트와 관련된 연결은 다음과 같습니다:

React to Python AgentCall a Python Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit

Python Agent to MCPConnect a Python Agent to an MCP server

Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent

TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent

Python Agent to Python DynamoDBConnect a Python Agent to a DynamoDB table

Python Agent to AgentCore GatewayConnect a Python Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target