> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 빠른 시작

> 등록, AWS 연결, 연결 확인, 첫 AI 기반 비용 분석 실행 — 각 단계마다 명확한 성공 기준을 제시합니다.

이 빠른 시작은 처음부터 직접 검증할 수 있는 실제 결과까지 안내합니다: 실제 AWS 계정을 읽는 AI 에이전트가 반환하는 유휴 EC2 인스턴스 목록과 예상 월간 절감액. AWS의 모델 액세스 승인과 CloudThinker의 리소스 인벤토리 작업을 기다리는 시간이 대부분인 **약 10분**을 허용하세요.

<Info>
  **필요한 것:** 이메일 주소, 역할을 생성할 수 있는 관리자(또는 충분한 IAM) 권한이 있는 AWS 계정, 에이전트가 반환하는 내용을 읽을 몇 분의 시간.
</Info>

***

## 30초 문법

에이전트에게 자연어로 말하세요. 전체 패턴은 다음과 같습니다:

```text theme={null}
@agent #tool your request
```

* **`@agent`** — 작업을 수행하는 에이전트: `@alex` (클라우드), `@oliver` (보안), `@tony` (데이터베이스), `@kai` (Kubernetes), `@anna` (조율).
* **`#tool`** *(선택 사항)* — 원하는 출력 형식: `#dashboard`, `#report`, `#recommend`, `#alert`, `#chart`, `#kb`.
* **요청 내용** — 필요한 것을 자유롭게 작성하세요. 관련 컨텍스트를 인라인으로 추가할 수 있습니다.

전체 구문은 [CloudThinker 언어 레퍼런스](/ko/guide/language)를 참고하세요.

***

<Steps>
  <Step title="등록">
    [app.cloudthinker.io](https://app.cloudthinker.io/auth/register)에서 가입하세요.

    1. 이름, 업무용 이메일, 비밀번호 입력
    2. 수신함의 인증 링크 클릭
    3. 프로필 확인

    **성공 기준:** 기본 워크스페이스가 준비된 개인 조직에 진입합니다. 왼쪽 사이드바 상단에 **New chat**, **Skills**, **Artifacts**가 표시되고 오른쪽에는 빈 대화 패널이 나타납니다.

    <Tip>
      무료 14일 체험 — 15일째부터 요금이 청구됩니다. 요금제 한도는 [요금](/ko/guide/billing/pricing)을 참고하세요.
    </Tip>
  </Step>

  <Step title="AWS 연결">
    **Settings → Connections → New Connection → AWS**로 이동한 후 인증 방법을 선택하세요:

    | 방법                  | 사용 시점              | 필요 사항                                    |
    | ------------------- | ------------------ | ---------------------------------------- |
    | **IAM Role** *(권장)* | 프로덕션 계정; 장기 키보다 안전 | 생성할 역할에 Trust policy + 권한 정책             |
    | **Access Key**      | 빠른 데모 또는 샌드박스 계정   | 프로그래밍 방식 액세스가 있는 IAM 사용자; 액세스 키 ID + 시크릿 |

    IAM Role 경로의 경우, CloudThinker가 Trust policy에 붙여넣을 **External ID**와 첨부할 [최소 권한](/ko/guide/connections/aws#required-permissions)을 보여줍니다. CloudShell 명령어와 Trust policy JSON을 포함한 전체 AWS 콘솔 안내는 [AWS 연결 가이드](/ko/guide/connections/aws)에 있습니다.

    **기본 안전:** 권장 시작 정책은 읽기 전용입니다. 쓰기 작업(적정 크기 조정, 인스턴스 종료, 보안 그룹 변경)은 별도 정책이 필요하며 [승인 워크플로](/ko/guide/approval)에 따라 실행됩니다 — 첫 실행에서 에이전트는 사용자의 승인 없이 변경 사항을 푸시하지 않습니다.

    **성공 기준:** 연결 카드가 녹색 점과 함께 **Connected** 상태로 전환됩니다. 디스커버리가 자동으로 시작되며, 약 2분 내에 카드에 0이 아닌 리소스 수(인스턴스, RDS, S3 등)가 표시됩니다. 디스커버리가 계속 0이면 아래 [문제 해결](#문제-해결)로 이동하세요.
  </Step>

  <Step title="디스커버리 확인">
    왼쪽 사이드바에서 **Infrastructure** 탭을 열세요.

    다음이 표시되어야 합니다:

    * 0이 아닌 리소스 수를 가진 리전 목록
    * EC2 인스턴스, S3 버킷, RDS 데이터베이스, Lambda 함수 중 하나 이상
    * 서비스 관계를 보여주는 토폴로지 뷰(그래프 아이콘 클릭)

    **성공 기준:** 리소스 수가 계정에서 예상되는 것과 대략 일치합니다. EC2 5개를 가진 샌드박스를 연결했을 때 5개가 보이면 완료입니다. 0이 표시되거나 숫자가 맞지 않으면 [문제 해결](#문제-해결)을 참고하세요.
  </Step>

  <Step title="첫 번째 프롬프트 실행">
    **New chat**을 클릭하고 다음을 붙여넣으세요:

    ```text theme={null}
    @alex give me a summary of my AWS resources — count by service, top regions, and any obviously idle instances
    ```

    Alex가 CloudWatch 사용률 메트릭을 조회하고 리소스 인벤토리와 결합하여 구조화된 요약을 반환합니다.

    **예상 출력:** 약 30초 내에 다음을 포함한 응답:

    * **리소스 수** — 리전별 EC2, RDS, S3, Lambda 등
    * **유휴 후보** — 최근 30일 동안 지속적으로 `<20%` CPU를 유지한 인스턴스
    * **예상 절감액** — 유휴 리소스를 계속 유지할 경우의 월간 비용
    * **인라인 추론** — *"지난 30일간 CloudWatch의 `CPUUtilization` 메트릭을 확인하고 95번째 백분위가 20% 미만인 인스턴스를 필터링했습니다"*

    어떤 줄이든 드릴다운할 수 있습니다: 인스턴스를 클릭하면 태그, 리전, 소유자, Alex가 참조한 전체 메트릭 히스토리를 볼 수 있습니다.
  </Step>

  <Step title="도구 명령 시도">
    더 풍부한 출력 형식을 위해 프롬프트 앞에 `#tool`을 붙이세요:

    ```text theme={null}
    @alex #dashboard EC2 cost breakdown by instance type over the last 30 days
    ```

    Alex가 텍스트 답변 대신 정렬/필터 가능한 차트가 있는 인터랙티브 대시보드를 반환합니다.

    연결 후 시도해볼 만한 다른 도구들:

    ```text theme={null}
    @alex #recommend right-sizing options for the over-provisioned instances above
    @alex #report monthly AWS cost narrative I can share with finance
    ```

    **성공 기준:** 대시보드가 인라인으로 렌더링되고, 추천 항목에 변경 사항과 예상 월간 절감액이 모두 포함됩니다.
  </Step>
</Steps>

***

## 완료 기준

* [x] Infrastructure 탭에서 AWS 리소스 수를 확인할 수 있으며 실제와 일치합니다
* [x] `@alex`가 실제로 알고 있는 특정 인스턴스나 서비스를 언급한 요약을 반환했습니다
* [x] 팀원에게 Alex가 유휴 리소스를 찾기 위해 수행한 작업을 설명할 수 있습니다(인라인 추론을 다시 읽으세요)

세 가지 모두 해당되면 첫 성공 흐름을 완료한 것입니다.

***

## 문제 해결

<AccordionGroup>
  <Accordion title="AWS 연결이 '보류 중' 또는 '실패' 상태를 유지함" icon="circle-exclamation">
    **가능한 원인:** Trust policy에 External ID가 누락되거나 역할의 권한 정책이 너무 좁습니다.

    **확인:**

    1. AWS 콘솔 → IAM → 역할 → 해당 역할 → 신뢰 관계에서 `sts:ExternalId` 조건이 CloudThinker가 보여준 것과 정확히 일치하는지 확인하세요(공백 없음).
    2. 역할의 권한 정책에 최소한 `ec2:Describe*`, `rds:Describe*`, `s3:List*`, `cloudwatch:GetMetricStatistics`가 포함되어 있는지 확인하세요. 전체 목록: [AWS 연결 최소 권한](/ko/guide/connections/aws#required-permissions).
    3. 역할의 최대 세션 기간이 1시간 이상인지 확인하세요.

    **수정:** Trust policy/권한을 수정한 후 연결 카드에서 **Reconnect**를 클릭하세요. 디스커버리가 자동으로 재시작됩니다.
  </Accordion>

  <Accordion title="연결됐지만 리소스 수가 0으로 유지됨" icon="magnifying-glass">
    **가능한 원인:** 역할을 가정할 수 있지만 계정이 실제로 사용하는 리전/서비스에 대한 `Describe` 권한이 없거나, 계정이 활성화하지 않은 리전에 있습니다.

    **확인:**

    * **Connection details → Discovery log**로 이동하세요. 시도된 각 리전은 결과를 표시합니다. `AccessDenied` 오류는 어떤 API 호출이 거부됐는지 정확히 알려줍니다.
    * 계정에 역할이 볼 수 있는 적어도 하나의 리전에 실제로 리소스가 있는지 확인하세요.

    **수정:** 실패한 API를 커버하도록 권한 정책을 확장하거나, 연결의 리전 범위에서 해당 리전을 활성화하세요.
  </Accordion>

  <Accordion title="Alex가 'AWS에 아직 액세스할 수 없습니다'라고 말함" icon="user-slash">
    **가능한 원인:** 현재 워크스페이스에 연결이 바인딩되지 않았습니다. 각 연결은 하나의 워크스페이스에 존재하며, 다른 워크스페이스에서 채팅 중일 수 있습니다.

    **수정:** 워크스페이스 선택기(사이드바 상단)가 AWS를 추가한 워크스페이스와 동일한지 확인하세요. 워크스페이스를 전환하거나, 채팅 중인 워크스페이스에서 연결을 다시 추가하세요.
  </Accordion>

  <Accordion title="첫 번째 프롬프트가 실제 데이터 대신 일반적인 모범 사례를 반환함" icon="comment-slash">
    **가능한 원인:** Alex가 도구(CloudWatch, Cost Explorer)에 접근하지 못했습니다 — 보통 권한 부족입니다. 일반적인 답변은 구체적인 데이터를 사용할 수 없을 때의 폴백입니다.

    **확인:** Alex의 답변 하단까지 스크롤하세요; **Tools used** 섹션에 시도된 모든 API 호출이 성공/실패 여부와 함께 나열됩니다. 실패한 호출은 AWS 오류를 표시합니다.

    **수정:** 역할에 누락된 권한을 추가하고(사용률 확인을 위한 CloudWatch 읽기, 지출 확인을 위한 Cost Explorer 읽기), 재연결 후 프롬프트를 다시 실행하세요.
  </Accordion>

  <Accordion title="첫 번째 프롬프트에서 느린 응답 또는 타임아웃" icon="hourglass-half">
    **가능한 원인:** 초기 디스커버리가 아직 실행 중입니다 — Alex가 인벤토리 완료를 기다린 후 추론을 시작합니다. 이후 프롬프트는 훨씬 빠릅니다.

    **수정:** Infrastructure 탭에 0이 아닌 리소스 수가 표시될 때까지 기다린 후 프롬프트를 다시 실행하세요. 500개 미만의 리소스가 있는 계정의 경우 디스커버리는 일반적으로 2\~5분 내에 완료됩니다.
  </Accordion>
</AccordionGroup>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="역할별 AgenticOps 빠른 성과" icon="comments" href="/ko/guide/tutorial/agenticops">
    역할을 찾고, 프롬프트를 복사하고, 1분 이내에 실제 결과를 얻으세요
  </Card>

  <Card title="더 많은 도구 연결" icon="plug" href="/ko/guide/connections/overview">
    Datadog, GitHub, Kubernetes, Postgres, Slack 연결 — 연결이 추가될수록 에이전트가 활성화됩니다
  </Card>

  <Card title="팀 초대" icon="user-plus" href="/ko/guide/workspace-users">
    Owner, Admin, Developer, Viewer 역할로 팀원을 추가하고 워크스페이스 액세스를 할당하세요
  </Card>

  <Card title="요금제 업그레이드" icon="credit-card" href="/ko/guide/billing/subscription">
    팀이 준비됐을 때 시트를 추가하고 체험판에서 전환하세요 — 시트당 요금, 언제든지 업그레이드 가능
  </Card>
</CardGroup>