View a markdown version of this page

Amazon Bedrock AgentCore 시작하기 - Amazon Bedrock AgentCore
AWS 계정 가입사전 조건1단계: AgentCore CLI 설치2단계: 프로젝트 생성3단계: 로컬에서 테스트4단계: 에이전트 배포5단계: 배포된 에이전트 간접 호출프로젝트에 기능 추가로그 및 추적 보기정리다음 단계

Amazon Bedrock AgentCore 시작하기

이 빠른 시작은 AgentCore CLI를 사용하여 몇 분 안에 0에서 실행 중인 에이전트로 이동합니다. CLI를 설치하고, 프로젝트를 스캐폴드하고, 로컬에서 테스트하고, 에이전트에 배포하고 AWS, 에이전트를 호출합니다.

AgentCore에서 에이전트를 구축하는 두 가지 방법, 즉 동일한 CLI:

  • 관리형 하네스. 구성 파일(모델, 프롬프트, 도구, 메모리)에서 에이전트를 선언하면 AgentCore가 루프를 실행합니다. 프레임워크, 오케스트레이션 코드가 없습니다. 아이디어에서 실행 중인 에이전트로 가장 빠른 경로를 원하는 경우 좋은 경로입니다. 자세히 알아보기

  • 코드 기반 에이전트. 이미 알고 있는 프레임워크(Strands, LangGraph, Google ADK 또는 OpenAI Agents)를 사용하여 Python에서 에이전트 루프를 작성하고 AgentCore 런타임에 배포합니다. 오케스트레이션 로직을 완벽하게 제어합니다.

이 페이지에서는 코드 기반 흐름을 안내합니다. 하네스는 AgentCore 하네스란 무엇입니까?를 참조하세요.

AWS 계정 가입

AWS 계정 가입

시작하려면 AWS 계정이 AWS필요합니다. AWS 계정 생성에 대한 자세한 내용은 AWS 계정 관리 참조 안내서의 AWS 계정 시작하기를 참조하세요.

사전 조건

  • Node.js 20 이상. AgentCore CLI는 npm 패키지로 배포됩니다. 로 확인합니다node --version. 필요한 경우 nodejs.org 설치합니다.

  • npm. Node.js에 포함됩니다.

  • 자격 증명이 구성된 AWS 계정입니다. AWS CLI, 환경 변수 또는 AWS 프로파일을 통해를 구성합니다. AWS CLI 구성을 참조하세요.

  • Python 3.10 이상(에이전트 코드의 경우). 로 확인합니다python3 --version.

  • IAM 권한. 자격 증명에는 AgentCore API를 호출하고 배포 중에 사용되는 CDK 부트스트랩 역할을 수임할 수 있는 권한이 필요합니다. AgentCore CLI IAM 권한을 참조하세요.

1단계: AgentCore CLI 설치

npm install -g @aws/agentcore

다음을 확인합니다.

agentcore --version

나중에 업데이트하려면 설치 명령 또는를 다시 실행합니다agentcore update. 소스 및 문제: GitHub의 agentcore-cli.

2단계: 프로젝트 생성

agentcore create

대화형 마법사는 먼저 빌드할 항목을 묻습니다.

  • Harness - 관리형 구성 기반 에이전트 루프입니다. 프레임워크 또는 오케스트레이션 코드는 필요하지 않습니다. AgentCore 하네스란 무엇입니까?를 참조하세요.

  • 에이전트 - 선택한 프레임워크를 사용하여 AgentCore 런타임에 배포된 코드 기반 에이전트입니다.

  • 건너뛰기 - 에이전트 없이 프로젝트 구조를 생성합니다. 나중에를 사용하여 하나를 추가합니다agentcore add.

에이전트를 선택하면 마법사가 다음을 계속합니다.

  • 프레임워크 - Strands Agents(권장), LangChain/LangGraph, Google 에이전트 개발 키트 또는 OpenAI 에이전트 SDK

  • 모델 공급자 - Amazon Bedrock, Anthropic, OpenAI 또는 Gemini

  • 메모리 - 없음, 단기만 또는 장기 및 단기

  • 빌드 유형 - CodeZip(기본값) 또는 컨테이너

플래그를 직접 전달하여 코드 기반 에이전트를 생성할 수도 있습니다.

agentcore create \
  --name MyAgent \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

프로젝트 구조

agentcore create는 다음을 생성합니다.

MyAgent/
├── agentcore/
│   ├── agentcore.json      # Project and resource configuration
│   ├── aws-targets.json    # Deployment target (account and region)
│   └── cdk/                # CDK infrastructure (auto-managed)
└── app/
    └── MyAgent/            # Your agent code
        ├── main.py         # Agent entrypoint
        ├── pyproject.toml  # Python dependencies
        └── ...

키 파일:

  • agentcore/agentcore.json - 기본 구성입니다. 에이전트, 메모리 스토어, 게이트웨이, 자격 증명 및 기타 리소스를 정의합니다. agentcore add 및에서 관리합니다agentcore remove.

  • app/ - 에이전트 코드. 각 에이전트는 진입점 및를 사용하여 자체 하위 디렉터리를 가져옵니다pyproject.toml.

  • agentcore/aws-targets.json - 배포를 위한 AWS 계정 및 리전입니다.

3단계: 로컬에서 테스트

cd MyAgent
agentcore dev

agentcore dev는 Python 가상 환경을 생성하고, 종속성을 설치하고, 핫 재로드로 로컬 서버를 시작하고, 에이전트와 채팅하고, 트레이스를 검사하고, 프로젝트 리소스를 찾아볼 수 있도록 브라우저에서 에이전트 검사기를 엽니다. 코드 변경 사항은 자동으로 선택됩니다.

유용한 플래그:

  • --no-browser - 브라우저 검사기 대신 터미널 기반 TUI를 사용합니다.

  • --no-traces -에 대한 추적 쓰기를 비활성화합니다agentcore/.cli/traces.

  • --logs - 비대화형 모드의 테일 서버 로그입니다.

  • --port <N> - 개발 포트를 고정합니다(HTTP의 경우 기본값 8080, MCP의 경우 8000, A2A의 경우 9000, 사용 중인 경우 자동 증가).

4단계: 에이전트 배포

agentcore deploy

배포:

  1. 코드를 zip 아티팩트로 패키징(또는 인 경우 컨테이너 빌드--build Container)

  2. 후드 아래의 AWS CDK를 사용하여 리소스를 합성하고 프로비저닝합니다.

  3. 에이전트에 대한 AgentCore 런타임 엔드포인트를 생성합니다.

  4. CloudWatch 로깅 및 관찰성 구성

CDK가 계정을 부트스트랩하는 동안 처음 배포하는 데 몇 분 정도 걸립니다. 후속 배포가 더 빠릅니다.

배포하지 않고 변경될 내용 미리 보기:

agentcore deploy --dry-run

상태 확인:

agentcore status

5단계: 배포된 에이전트 간접 호출

agentcore invoke --prompt "Hello, what can you do?"

에이전트에 결제가 구성된 경우 호출 시 결제 컨텍스트를 제공합니다.

agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com

이것이 바로 루프입니다. 에서 반복하고app/MyAgent/main.py,를 사용하여 테스트하고agentcore dev,를 사용하여 배포하고agentcore deploy,를 사용하여 호출합니다agentcore invoke.

프로젝트에 기능 추가

agentcore add는에서 리소스를 관리합니다agentcore.json. 대화형 메뉴의 인수 없이 실행하거나 리소스를 직접 대상으로 지정합니다.

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

각 추가 명령은 구성을 스캐폴드하고 필요한 값을 묻는 메시지를 표시합니다. 추가한 후를 실행agentcore deploy하여 프로비저닝합니다.

연결할 수 있는 기능에 대한 심층 분석:

로그 및 추적 보기

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

정리

agentcore remove all
agentcore deploy

remove all는 구성을 재설정합니다. 후속 작업은 빈 상태를 deploy 감지하고 계정의 리소스를 해제합니다.

다음 단계

  • AgentCore 하네스란 무엇입니까 - 실행 중인 에이전트에 대한 구성 기반 경로입니다. 원하는 모델을 사용하고, 도구에 연결하고, 상태를 유지하고, VPC에 배포하고, 필요할 때 코드로 전환합니다.

  • AgentCore 코드 샘플 - 프레임워크 및 기능 전반의 end-to-end 예제입니다.