> **완성할 결과:** 회사 규정을 근거와 함께 답하고, 재고를 조회하고, 사람 승인 전 구매 초안을 만드는 에이전트. 그리고 그 에이전트가 제대로 동작하는지 설명할 수 있는 평가·추적·운영 체계.

<div class="lab-brief" markdown="1">

**진행 방식:** 읽기 · Azure 계정이나 설치 없이 시작합니다.

**먼저 할 일:** 아래 ‘처음이라면 여기부터’에서 Azure와 Foundry의 차이를 읽고 자신의 학습 경로를 고릅니다.

**확인할 결과:** 구매 도우미가 할 일과 하지 않을 일을 한 문장씩 설명합니다.

</div>

<a id="l00-first-steps"></a>

## 처음이라면 여기부터

**Azure는 Microsoft의 클라우드 서비스입니다. Foundry는 Azure에서 AI 모델과 에이전트를 만들고 관리하는 작업 공간입니다.** 이 실습에서는 가상 회사 Contoso의 구매 도우미를 만듭니다. 실제 회사 계정·구매 자료·결제 정보는 실습 데이터로 쓰지 않습니다.

```text
사용자: "노트북 2대의 규정과 재고를 확인하고 초안을 만들어줘."
  → 모델: 질문을 이해하고 답변을 작성
  → 문서 검색: 회사 규정의 근거를 찾음
  → 함수 도구: 합성 재고를 조회하고 초안을 계산
  → 사용자: 근거와 승인 대기 초안을 확인 — 실제 주문 아님
```

지금은 다음 다섯 단어만 알면 됩니다. 다른 약어는 필요한 장에서 배우고 [용어 사전](#glossary)에서 다시 찾습니다.

| 단어 | 이 실습에서의 뜻 |
| --- | --- |
| 포털(Portal) | 브라우저로 여는 관리 화면. Azure 포털은 자원·권한·비용, Foundry 포털은 AI 작업 중심 |
| 프로젝트(Project) | 이 도우미의 에이전트와 연결을 정리하는 작업 공간 |
| 모델(Model) | 입력을 받아 문장을 생성하는 AI |
| 에이전트(Agent) | 모델에 지시·지식·도구를 연결해 일을 처리하는 프로그램 |
| 배포(Deployment) | 모델을 내 프로젝트에서 호출할 수 있도록 준비하는 것. 학습시키는 작업이 아님 |

**처음에는 기본 11개(L00–L10)를 따라갑니다.** 심화 8개(L11–L18)는 선택이고, **마지막에는 공통 마무리 L19**를 진행합니다. 기본만 듣는다면 L10 다음에 L19로 바로 이동하며 심화를 모두 체크할 필요는 없습니다.

| 지금 내 상황 | 바로 할 일 | 여기까지 되면 다음으로 |
| --- | --- | --- |
| 강사가 프로젝트와 비용 승인을 제공함 | [L01 준비](#l01) → L02 모델 확인 → L03 첫 호출 | 내 프로젝트에서 실제 답변과 응답 ID 확인 |
| Azure 계정·권한이 없거나 아직 준비 중 | [L01 PC 준비](#l01-pc) → [로컬 검사](#l01-local) → L06 로컬 함수 → L08 결과 읽기 | 데이터 검사·290만 원 초안 계산·두 답변 비교 |

두 번째 경로는 **Azure 실행 연습을 대신 통과하는 경로가 아닙니다.** 계정이나 결제 수단을 임의로 새로 만들지 말고, 실제 호출은 미실행으로 남깁니다. 웹 목차의 **Azure 없이**를 선택하면 해당 단계가 있는 장을 모아 볼 수 있습니다.

## 목표

**Foundry는 “모델을 호출하는 화면”보다 넓습니다.** 모델을 선택하고, 에이전트에 지식과 도구를 연결하고, 품질·안전·비용을 관리하는 개발·운영 플랫폼입니다.

<details markdown="1">
<summary>선택 참고: 기본 실습이 Foundry의 어느 기능에 해당하나요?</summary>

| 필요한 것 | 맡는 구성 요소 | 이 가이드에서 하는 일 |
| --- | --- | --- |
| 생각하고 문장을 생성 | Foundry Models | 같은 질문으로 모델을 비교 |
| 목표·대화·도구 사용 | Foundry Agent Service | 구매·정책 도우미 제작 |
| 회사 문서의 근거 | File search / AI Search / Foundry IQ | 문서에서 답을 찾고 인용 |
| 실제 시스템과 연결 | Functions / MCP / OpenAPI / Toolbox | 재고 조회와 구매 초안 |
| 맞는지 판단 | Evaluations / Red teaming | 정답·도구·거절·승인 경계 검사 |
| 실행 경로와 운영 | Tracing / Monitoring / Control Plane | 실패 원인·비용·권한 확인 |

</details>

![Contoso 실습 아키텍처. 사용자는 에이전트에 요청하고, 에이전트는 모델·정책 문서·읽기 도구와 초안 도구를 사용한다. 실제 주문 전에 사람과 업무 시스템의 승인이 필요하다.](../assets/architecture.svg)

## 개념과 실습 지도

**경험할 기능:** 질문에 답하는 모델에 회사 문서와 재고 조회 기능을 하나씩 붙입니다.

**무엇이며 왜 중요한가요?** 모델은 답변을 쓰고, 에이전트는 모델에 지시·문서·도구를 연결합니다. “재고를 확인하겠다”는 말과 도구로 재고 8개를 조회한 결과는 다릅니다.

**어떻게 사용하나요?** 각 장에서 한 가지를 추가하고 결과를 확인합니다. 규정은 원문과, 재고·금액은 함수 결과와 대조합니다. 메뉴 이름을 모두 외울 필요는 없습니다.

**어디서 실행하나요?** 이 웹페이지는 설명서입니다. 포털은 브라우저의 AI 작업 화면, 터미널은 내 PC의 명령 입력창입니다. **복사 버튼은 실행 버튼이 아닙니다.**

### 실제 포털의 다섯 입구

![로그인한 Microsoft Foundry의 Contoso 프로젝트 Home. 위쪽에 Home, Discover, Build, Operate, Manage가 있고 중앙에 모델·에이전트 시작 카드와 두 종류의 엔드포인트가 있다.](../assets/portal/01-home.png)

**화면 읽기:** 상단 프로젝트 선택기에서 자기 실습 프로젝트를 먼저 확인합니다. **Discover**는 후보 탐색, **Build**는 모델·에이전트·도구 구성, **Operate**는 운영 상태, **Manage**는 프로젝트·리소스 관리입니다. Home의 **Project endpoint**와 **Azure OpenAI endpoint**는 서로 다른 주소입니다.

사진의 회색 부분은 가린 식별 정보이며 복사할 값이 아닙니다. 자기 프로젝트의 값을 사용하세요. 메뉴가 다르면 새/Classic 포털·현재 프로젝트·권한부터 확인합니다.

<details class="provenance-note" markdown="1">
<summary>참고: 사진의 촬영 범위와 검증 기록</summary>

이 가이드의 포털 이미지는 **2026-09-30 실제 로그인 화면을 Playwright MCP의 Headless Chromium으로 캡처**한 것입니다. 계정·식별 정보는 회색으로 가리거나 대화상자만 잘라 제외했고, 메뉴·결과를 합성하거나 성공 화면으로 바꾸지 않았습니다. 설정·목록 관찰과 새 실행은 구분합니다. **L03의 모델 시연만 합성 질문을 1회 전송**했고, 새 agent/정책·예약·평가·학습 job은 만들지 않았습니다. 어떤 사진도 전체 배포·릴리스 품질 통과를 대신 증명하지 않습니다. 표시되는 모델·기능·버전은 자신의 권한·지역·시점에 따라 달라집니다.

촬영 시각·마스킹·파일 hash·관찰 범위는 [스크린샷 출처](../content/portal-screenshots.json)에 있습니다. 자신의 실행·품질 기록은 가이드 밖에 보관합니다.

</details>

### 소스코드와 명령을 읽는 방법

전체 실습 ZIP을 내려받아 압축을 푼 뒤 VS Code의 **파일 → 폴더 열기**에서 엽니다. `samples`, `data`, `requirements.txt`가 함께 보이는 폴더가 **실습 폴더(리포 루트)**입니다. 브라우저의 “페이지 소스 보기”는 실행 코드가 아니라 가이드 HTML만 보여 줍니다. Git 명령을 알아야 시작할 수 있는 것은 아닙니다.

<details markdown="1">
<summary>참고: 원본 파일의 역할</summary>

| 찾아볼 것 | 실제 원본 |
| --- | --- |
| 기본 실습과 함수 구현 | [samples/workshop.py](../samples/workshop.py) |
| Hosted 요청 처리 | [hosted/main.py](../hosted/main.py), [samples/hosted_runtime.py](../samples/hosted_runtime.py) |
| 환경 변수와 모델 이름 | [.env.example](../.env.example) — 개인 `.env`의 출발점 |
| 배포할 서비스·진입점 | [azure.yaml](../azure.yaml) |
| 인프라 정의 | [infra/main.bicep](../infra/main.bicep) |
| 학습 문서의 원문 | [docs/00-start.md](../docs/00-start.md) — 수정 후 HTML/Markdown/PDF/ZIP 재생성 |

</details>

`python samples/workshop.py model --live`를 읽으면 `python`은 실행기, `samples/workshop.py`는 파일, `model`은 수행할 하위 명령, `--live`는 이 샘플의 실제 Azure 실행 허용 옵션입니다. 각 실행 블록 아래 **명령 해설**의 순서는 위 블록의 명령 순서와 같습니다. 실행 위치는 별도 안내가 없으면 리포 루트이며, `실제-...`·`승인된-...`은 그대로 입력하는 값이 아니라 자신의 값으로 바꿀 자리표시자입니다.

**붙여넣을 곳을 먼저 확인하세요.** Bash/PowerShell 명령은 터미널, 질문은 본문이 지정한 포털 입력창, `.env` 값은 편집기의 `.env` 파일에 넣습니다. Python 코드 발췌와 JSON 결과 예시는 터미널에 붙여넣는 명령이 아닙니다. 여러 명령이 있는 블록은 한 줄씩 실행하고 결과를 읽은 뒤 다음 줄로 넘어갑니다.

`--live`는 모든 CLI의 공통 안전장치가 아닙니다. `azd deploy`, `az login`, 일부 관리 스크립트는 이 옵션 없이도 동작하므로 반드시 해당 해설을 읽으세요. `--local`도 항상 “Azure 비용 없음”을 뜻하지 않습니다. L12의 로컬 Hosted 서버는 실제 모델·검색을 호출할 수 있습니다. 브라우저 로그인과 터미널의 `az login`도 별도 세션입니다.

<details markdown="1">
<summary>심화 명령을 읽을 때: 환경 변수·여러 줄·azd</summary>

명령 앞의 `KEY=value`는 macOS/Linux 셸에서 **그 명령에만** 환경 변수를 전달하는 문법입니다. PowerShell에서는 같은 의미의 `$env:KEY = "value"`로 현재 세션에 값을 설정한 뒤 명령 부분을 실행하며, 끝나면 이전 값으로 복원합니다. 줄 끝 `\`는 bash의 줄 이어쓰기이므로 PowerShell에 그대로 붙이지 말고 한 줄 명령으로 합칩니다. `AZURE_DEV_USER_AGENT=microsoft_foundry_skill`은 제작 도구를 식별하는 값일 뿐, 학습자에게 Copilot skill 설치를 요구하지 않습니다.

</details>

## 준비

대상은 **생성형 AI를 업무에 적용하려는 개발자·아키텍트·기술 담당자**입니다. 포털 관찰 단계에는 코딩 경험이 필수가 아니지만, 기본 코스 전체를 완료하려면 Python과 터미널을 사용합니다. 처음 접하는 명령은 복사부터 하지 말고 바로 아래 해설과 실행 범위를 먼저 읽으세요.

파일은 모두 같은 폴더 구조를 유지하세요. 한국어 웹 가이드는 `index.ko.html`, 영어는 `index.html`을 직접 열면 됩니다. 네트워크가 없어도 가이드와 로컬 연습을 볼 수 있습니다. Azure 실습과 공식 출처 열기는 인터넷이 필요합니다.

## 실행

### 1. 자신의 경로를 고르기

| 경로 | 추천 순서 | 전제 |
| --- | --- | --- |
| 90분 체험 | L00 → 준비된 L01 → L04 → L05 → 축약 L08 → L19 | 강사가 프로젝트·모델·권한 사전 준비 |
| 기본 코스 | L00–L10 → L19 | 기본 4시간 45분 + 마무리 10분, 대기·휴식 별도 |
| 개발자 확장 | 기본 → L11 → L12 → L13·L14 → 선택 L18 → L19 | SDK·배포·검색 심화 |
| 기업 도입 | 기본 → L15 → L16 → L17 → 선택 L18 → L19 | 관리자·보안 담당자 협업 |
| 계정 없이 | L01 로컬 → L06 로컬 → L08 기존 결과 읽기 → 설계 과제 | 실제 Azure 성공으로 기록하지 않기 |

시간은 **손으로 진행하는 예상 시간**입니다. quota 승인, 리소스 준비, 인덱싱, 관리자 승인 대기는 포함하지 않습니다.

### 2. 한 가지 시나리오만 기억하기

가상의 Contoso 직원이 질문합니다.

```text
노트북 2대가 필요해요.
회사 규정과 NB-14 재고를 확인하고 구매 요청 초안을 만들어줘.
```

완성된 시스템은 정책을 검색하고, 재고 8개·단가 145만 원을 조회하며, 총액 290만 원의 **승인 대기 초안**을 반환합니다. 팀장과 구매 담당자 승인이 필요합니다. **“주문 완료”라고 답하면 실패**입니다.

### 3. 세 가지 구분 익히기

| 혼동하기 쉬운 것 | 정확한 구분 |
| --- | --- |
| 모델 vs 에이전트 | 모델은 추론 엔진. 에이전트는 모델 + 지시 + 상태 + 도구를 이용하는 실행 단위 |
| 지식 vs 도구 vs 기억 | 지식은 회사의 근거. 도구는 기능. 기억은 사용자/세션을 넘어 유지할 맥락 |
| GA vs Preview | 새 포털이 GA여도 Memory·Voice·일부 운영 기능까지 모두 GA인 것은 아님 |

### 4. 결과를 증거로 남기기

각 모듈 끝의 **성공 기준**을 통과한 뒤 진도를 체크합니다. 브라우저 진도는 이 기기의 로컬 저장소에만 저장되며 서비스 호출 여부를 판정하지 않습니다. 실제 결과는 `results/`나 강사 기록표에 남기세요. 개인정보나 토큰은 기록하지 않습니다.

웹 진도는 **선택한 경로의 모듈만** 집계합니다. 기본은 11개+마무리 1개, 심화는 8개+마무리 1개, 90분 체험은 마무리를 포함한 6개입니다. 기존에 통합된 장의 별도 체크를 새 기능의 완료로 옮기지는 않습니다. **용어가 낯설어요 / 진행이 막혔어요**를 열어 도움말을 읽고 **읽던 실습으로 돌아가기**로 복귀할 수 있습니다. 휴대폰에서는 위쪽 **목차**에서 찾습니다.

## 성공 기준

- “모델만 호출”과 “도구를 쓰는 에이전트”를 구분할 수 있습니다.
- 완성 결과에 **근거, 실제 도구 결과, 미승인 상태**가 필요하다는 것을 설명할 수 있습니다.
- 자신이 진행할 코스와 마지막 정리 단계를 선택했습니다.

## 막혔을 때

**처음부터 모든 기능을 켜지 마세요.** 첫날에는 Prompt Agent, File search, 함수 도구, 평가, 추적이면 충분합니다. Preview·복잡한 네트워크·추가 업무 연결은 기본 결과를 완성한 뒤 붙입니다.

## 정리

이 모듈은 리소스를 생성하지 않습니다. 다음은 **L01: 실행 가능한 환경 만들기**입니다.

<details markdown="1">
<summary>이 가이드가 말하는 “전체 핵심 기능”의 범위</summary>

Microsoft의 capability map/reference를 기준으로 기능군을 빠짐없이 학습 경로에 연결합니다. 모든 모델·지역·API 조합을 전수 실행했다는 뜻은 아닙니다. 핵심은 직접 실습하고, 관리자·추가 라이선스가 필요한 기능은 조건부 실습 또는 설계 과제로 명확히 표시합니다. 자세한 대응표는 **기능 커버리지**에서 확인합니다.

</details>