# Amazon Bedrock AgentCore 시작하기
<a name="agentcore-get-started-cli"></a>

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

AgentCore에서 에이전트를 구축하는 두 가지 방법, 즉 동일한 CLI:
+  **관리형 하네스**. 구성 파일(모델, 프롬프트, 도구, 메모리)에서 에이전트를 선언하면 AgentCore가 루프를 실행합니다. 프레임워크, 오케스트레이션 코드가 없습니다. 아이디어에서 실행 중인 에이전트로 가장 빠른 경로를 원하는 경우 좋은 경로입니다. [자세히 알아보기](harness.md)
+  **코드 기반 에이전트**. 이미 알고 있는 프레임워크(Strands, LangGraph, Google ADK 또는 OpenAI Agents)를 사용하여 Python에서 에이전트 루프를 작성하고 AgentCore 런타임에 배포합니다. 오케스트레이션 로직을 완벽하게 제어합니다.

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

## AWS 계정 가입
<a name="sign_up_for_an_shared_id_aws_account"></a>

### AWS 계정 가입
<a name="sign-up-for-aws"></a>

시작하려면 AWS 계정이 AWS필요합니다. AWS 계정 생성에 대한 자세한 내용은 * AWS 계정 관리 참조 안내서*의 [AWS 계정 시작하기](https://docs.aws.amazon.com/accounts/latest/reference/getting-started.html)를 참조하세요.

## 사전 조건
<a name="agentcore-cli-prerequisites"></a>
+  **Node.js 20 이상.** AgentCore CLI는 npm 패키지로 배포됩니다. 로 확인합니다`node --version`. 필요한 경우 [nodejs.org](https://nodejs.org) 설치합니다.
+  **npm.** Node.js에 포함됩니다.
+  **자격 증명이 구성된 AWS 계정입니다.** AWS CLI, 환경 변수 또는 AWS 프로파일을 통해를 구성합니다. [AWS CLI 구성을 참조하세요](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
+  **Python 3.10 이상**(에이전트 코드의 경우). 로 확인합니다`python3 --version`.
+  **IAM 권한**. 자격 증명에는 AgentCore API를 호출하고 배포 중에 사용되는 CDK 부트스트랩 역할을 수임할 수 있는 권한이 필요합니다. [AgentCore CLI IAM 권한을 참조하세요](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam.html).

## 1단계: AgentCore CLI 설치
<a name="agentcore-cli-install"></a>

```
npm install -g @aws/agentcore
```

다음을 확인합니다.

```
agentcore --version
```

나중에 업데이트하려면 설치 명령 또는를 다시 실행합니다`agentcore update`. 소스 및 문제: [ GitHub의 agentcore-cli](https://github.com/aws/agentcore-cli).

## 2단계: 프로젝트 생성
<a name="agentcore-cli-create"></a>

```
agentcore create
```

대화형 마법사는 먼저 빌드할 항목을 묻습니다.
+  **Harness** - 관리형 구성 기반 에이전트 루프입니다. 프레임워크 또는 오케스트레이션 코드는 필요하지 않습니다. [AgentCore 하네스란 무엇입니까?를](harness.md) 참조하세요.
+  **에이전트** - 선택한 프레임워크를 사용하여 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
```

### 프로젝트 구조
<a name="agentcore-cli-project-structure"></a>

 `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단계: 로컬에서 테스트
<a name="agentcore-cli-test"></a>

```
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단계: 에이전트 배포
<a name="agentcore-cli-deploy"></a>

```
agentcore deploy
```

배포:

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

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

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

1. CloudWatch 로깅 및 관찰성 구성

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

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

```
agentcore deploy --dry-run
```

상태 확인:

```
agentcore status
```

## 5단계: 배포된 에이전트 간접 호출
<a name="agentcore-cli-invoke"></a>

```
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`.

## 프로젝트에 기능 추가
<a name="agentcore-cli-add-capabilities"></a>

 `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`하여 프로비저닝합니다.

연결할 수 있는 기능에 대한 심층 분석:
+  [AgentCore 메모리](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html) - 단기 및 장기 메모리, 검색 전략
+  [AgentCore Gateway](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html) - APIs 및 MCP 서버에 대한 관리형 연결
+  [AgentCore 브라우저](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html) - 에이전트를 위한 관리형 웹 브라우징
+  [AgentCore 코드 해석기](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html) - 샌드박스 코드 실행
+  [AgentCore 자격 증명](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) - OAuth, API 키 자격 증명 공급자, 워크로드 자격 증명
+  [AgentCore 관찰성](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) - CloudWatch의 추적, 로그 및 지표
+  [AgentCore VPC](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html) - VPC 내에서 에이전트 실행
+  [AgentCore 결제](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments.html) - x402를 통한 에이전트에 대한 마이크로트랜잭션 결제

## 로그 및 추적 보기
<a name="agentcore-cli-logs"></a>

```
# 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>
```

## 정리
<a name="agentcore-cli-cleanup"></a>

```
agentcore remove all
agentcore deploy
```

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

## 다음 단계
<a name="agentcore-cli-next-steps"></a>
+  [AgentCore 하네스란 무엇입니까](harness.md) - 실행 중인 에이전트에 대한 구성 기반 경로입니다. 원하는 모델을 사용하고, 도구에 연결하고, 상태를 유지하고, VPC에 배포하고, 필요할 때 코드로 전환합니다.
+  [AgentCore 코드 샘플](https://github.com/awslabs/amazon-bedrock-agentcore-samples) - 프레임워크 및 기능 전반의 end-to-end 예제입니다.