파이썬 에이전트

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

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

사용 방법

에이전트 생성

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

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

프로젝트 사전 요건

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

옵션

매개변수	타입	기본값	설명
project 필수	string	-	Agent를 추가할 프로젝트
framework	strands | langchain	strands	사용할 에이전트 SDK입니다.
name	string	-	Agent의 이름 (기본값: agent)
auth	iam | cognito	iam	에이전트 인증에 사용되는 방법입니다. infra가 설정된 경우에만 적용됩니다 (infra가 none일 때는 무시됨).
protocol	http | a2a | ag-ui	http	Agent의 서버 프로토콜입니다. HTTP는 FastAPI HTTP 서버를 노출합니다. A2A는 Agent-to-Agent 프로토콜 서버를 노출합니다. AG-UI는 프론트엔드와 직접 통합하기 위한 Agent-User Interaction 프로토콜 서버를 노출합니다.
iac	inherit | cdk | terraform	inherit	선호하는 IaC 공급자입니다. 기본적으로 초기 선택에서 상속됩니다.
infra	agentcore | none	agentcore	에이전트를 호스팅할 인프라 유형입니다.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번 설치합니다.

생성기 출력

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

protocol = http

HTTP 프로토콜 (기본값)

• 디렉터리your-project/

  • 디렉터리your_module/

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

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

protocol = a2a

A2A 프로토콜

진입점은 A2A 프로토콜을 통해 에이전트를 노출합니다(Strands는 Strands A2A Server를 사용하고, LangChain은 그래프를 a2a-sdk executor로 래핑합니다). 이는 FastAPI 앱에 마운트됩니다:

• 디렉터리your-project/

  • 디렉터리your_module/

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

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

protocol = ag-ui

AG-UI 프로토콜

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

• 디렉터리your-project/

  • 디렉터리your_module/

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

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

React 웹사이트에 연결

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

인프라

infra = agentcore

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

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

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 배포용 일반 모듈

infra = none

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

아키텍처

Bedrock AgentCore Runtime

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

None (local only)

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

에이전트 작업

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

도구 추가

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

Strands

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],
)

LangChain

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import 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 = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="다양한 도구에 접근 가능한 유용한 어시스턴트입니다.",
)

사전 제작 도구 사용

Strands

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

from strands_tools import current_time, http_request, file_read

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

LangChain

LangChain은 대규모 도구 및 통합 생태계를 제공합니다. 관련 통합 패키지를 설치한 다음 도구를 create_agent에 전달하세요:

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="유용한 어시스턴트입니다.",
)

모델 구성

Strands

기본적으로 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)

LangChain

LangChain 에이전트는 ChatBedrockConverse 모델을 사용합니다. 생성된 에이전트는 MODEL_ID 및 AWS_REGION 환경 변수에서 모델 ID와 리전을 읽지만, agent.py에서 직접 모델을 구성할 수 있습니다:

from langchain_aws import ChatBedrockConverse

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

MCP 서버 사용

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

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 또는 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에서 수신합니다. 생성된 Dockerfile 및 인프라가 자동으로 구성됩니다.

protocol = http

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을 사용할 필요가 없습니다.

protocol = a2a

A2A 서버 (A2A 프로토콜)

생성된 main.py는 /ping도 노출하는 상위 FastAPI 앱에 A2A 서버를 마운트합니다. Strands 에이전트는 Strands A2AServer를 사용하고, LangChain 에이전트는 컴파일된 그래프를 a2a-sdk AgentExecutor로 래핑합니다. AgentCore에 배포될 때 진입점은 AppConfig에서 런타임의 공개 ARN을 확인하고 에이전트 카드에 광고합니다.

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

protocol = ag-ui

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

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

• Strands: Agent를 ag_ui_strands.StrandsAgent로 래핑하고 create_strands_app()을 통해 FastAPI 앱을 생성합니다.
• LangChain: 컴파일된 그래프를 ag_ui_langgraph.LangGraphAgent로 래핑하고 수동으로 작성된 FastAPI /invocations 루프에서 제공합니다.

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

React 웹사이트에 연결

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

에이전트 실행

로컬 개발

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

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

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

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

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

에이전트와 채팅하기

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

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

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

그런 다음 다른 터미널에서 채팅을 시작합니다:

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

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

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

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

에이전트의 입력 형태를 사용자 정의할 때(예: InvokeInput에 새 필드 추가), 에이전트를 호출할 때 새 필드를 전달하도록 chat.ts를 업데이트하면 나머지는 자동으로 작동합니다.

infra = agentcore

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

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

IAM

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

pnpm

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

yarn

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

npm

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

bun

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

Cognito

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

pnpm

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

yarn

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

npm

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

bun

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

infra = agentcore

Bedrock AgentCore Runtime에 에이전트 배포

Infrastructure as Code

infra에 대해 agentcore을 선택한 경우, 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#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 인증만 지원합니다.

보안 모범 사례

에이전트의 비즈니스 로직을 구현할 때 Bedrock AgentCore Runtime 보안 모범 사례를 검토하세요.

번들 및 도커 타겟

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

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

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

관측성

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

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

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

에이전트 호출

protocol = http

로컬 서버 호출

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

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

IAM

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 명령 구성에 대한 자세한 내용은 여기를 클릭하세요

Cognito

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 웹사이트에서 에이전트를 호출하려면 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 생성기 가이드를 참조하세요.

protocol = a2a

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

protocol = ag-ui

AG-UI 에이전트 호출

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

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

연결

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

React to Python Agent React 웹사이트에서 Python Agent 호출하기

React to AG-UI Agent CopilotKit를 통해 React 웹사이트에서 AG-UI 프로토콜을 노출하는 Agent 호출하기

Python Agent to MCP Python Agent를 MCP 서버에 연결하기

Python Agent to A2A Agent Python Agent를 원격 A2A 에이전트에 연결하기

TypeScript Agent to A2A Agent TypeScript Agent를 원격 A2A 에이전트에 연결하기

Python Agent to Python DynamoDB Python Agent를 DynamoDB 테이블에 연결하기

Python Agent to AgentCore Gateway Python Agent를 AgentCore Gateway에 연결하기