실습 ②: Copilot Studio 에서 REST API 등록 → 입력 변수 → 인터넷 검색 끄기 → 테스트
| 시간 | 소요 | 수강생 역할 |
|---|---|---|
| 13:15 | 20분 | 🟢 직접 실습 |
목차
- 이 실습의 목표
- Step 1 — 도구 추가 → REST API
- Step 2 — 도구 검색에서 등록 확인
- Step 3 — 입력 변수 다듬기
- Step 4 — 지침에 사용 규칙 추가
- Step 5 — 인터넷 검색 끄기 (도구 강제 채택)
- Step 6 — 테스트
- Step 7 — 디버깅: 채택이 안 될 때
- 체크리스트
- 정리 — 두 실습 합치면
이 실습의 목표
- 실습 ① 의 OpenAPI YAML 을 Copilot Studio 의 도구 추가 → REST API 에 붙여넣어 커스텀 커넥터를 자동 생성
- 도구 검색에서 새 도구를 찾아 에이전트에 등록
- 입력 변수 (
base,quotes) 를 다듬어 채택률을 높인다 - 설정에서 인터넷 검색을 끄고 도구 채택을 강제한다
- 테스트 발화 4가지로 검증
이 실습이 새 흐름의 핵심 — 기존에는 Power Apps 에서 커넥터를 먼저 만들었지만, 이제는 Studio 의 “도구 추가 → REST API” 가 백엔드 커스텀 커넥터를 자동 생성 합니다. 화면 한 곳에서 끝납니다.
Step 1 — 도구 추가 → REST API
Copilot Studio → 작업 중인 에이전트 → 좌측 도구 탭 → + 도구 추가.
도구 카탈로그에서 “REST API” 카드를 찾습니다 (또는 상단 새 도구 → REST API).
| 입력 | 값 |
|---|---|
| OpenAPI 정의 | 실습 ① 의 YAML 을 그대로 붙여넣기 |
| 인증 유형 | 인증 없음 (Frankfurter 는 무인증) |
| 도구 이름 | GetExchangeRate |
| 설명 | “사용자가 환율을 물으면 이 도구로 최신 환율을 조회합니다. 통화 코드 (예: USD, KRW) 를 받습니다.” |
만들기 클릭.
이 한 번의 클릭으로 백엔드에서 다음이 동시에 일어납니다.
- 사용자 지정 커넥터 가 자동 생성됨 (Power Apps 의 데이터 → 사용자 지정 커넥터에서 확인 가능)
- 그 커넥터의 액션이 에이전트의 도구 로 등록됨
- 도구 카탈로그에 검색 가능 한 항목으로 노출됨
Step 2 — 도구 검색에서 등록 확인
도구 페이지 상단 검색 에 GetExchangeRate 또는 ExchangeRate 입력 → 방금 만든 도구가 보여야 합니다.
| 확인 항목 | 기대 |
|---|---|
| 검색에 노출 | ✅ |
| 상태 | “에이전트에 추가됨” / “활성” |
| 액션 | GetLatestRate (operationId) |
검색에서 안 보이면 페이지 새로고침 → 좌측 도구 트리에서 직접 확인.
Step 3 — 입력 변수 다듬기
도구 카드 클릭 → 입력 섹션을 엽니다. OpenAPI 의 parameters 가 그대로 입력 변수로 노출됩니다.
두 변수의 사용자 친화적 라벨·설명
| 변수 (OpenAPI 명) | UI 라벨 (한국어) | 설명 (학습자 노출) | 예시 |
|---|---|---|---|
base |
기준 통화 (Base) | 환율 계산의 기준이 되는 통화 (ISO 4217). 사용자가 “달러 환율” 이라 하면 USD. | USD |
symbols |
비교 통화 (Quotes) | 변환할 대상 통화. 콤마로 여러 개 가능 (예: KRW,JPY). |
KRW |
변수 설명(description) 이 오케스트레이터의 채택률·정확도에 결정적입니다. “무엇을, 어떤 형식으로, 어떤 예시로” 세 가지를 한 줄에 담으세요.
채움 동작 (Fill 옵션) 권장 설정
| 변수 | 채움 모드 | 이유 |
|---|---|---|
base |
모델로 채움 | 사용자 발화에서 “달러” → USD 추론 필요 |
symbols |
모델로 채움 | 명시 안 하면 기본 KRW 추론 |
기본값을 두려면: base = USD, symbols = KRW. (한국 사용자 기본 시나리오)
Step 4 — 지침에 사용 규칙 추가
에이전트의 지침 에 한 블록을 추가합니다.
## 환율 처리 규칙
- 환율 관련 질문이 오면 반드시 GetExchangeRate 도구를 호출하세요.
- 사용자가 통화 이름 (달러·엔화·유로 등) 을 한국어로 말해도 ISO 코드 (USD·JPY·EUR) 로 변환해서 호출하세요.
- 비교 통화를 명시하지 않으면 KRW 를 기본값으로 사용하세요.
- 응답에는 기준 통화·비교 통화·환율 값·기준 날짜를 포함하세요.
- 도구가 실패하면 "환율을 가져오지 못했습니다" 라고 안내하고 다시 시도를 제안하세요.
지침이 도구 설명·변수 설명을 직접 인용 하면 채택률이 크게 올라갑니다. 위 블록의 첫 줄이 그 예시.
Step 5 — 인터넷 검색 끄기 (도구 강제 채택)
이 단계가 이번 실습의 진짜 차별점 입니다. 인터넷 검색이 켜져 있으면 오케스트레이터가 환율을 검색으로도 답할 수 있다고 판단 해 도구를 우회할 수 있습니다.
끄는 위치
좌측 메뉴 개요 → 일반 (또는 우측 상단 설정) → 생성형 AI 또는 지식 / 일반 지식 섹션.
| 항목 | 설정 |
|---|---|
| 웹 검색 사용 / 일반 지식으로 응답 | 끔 (Off) |
| 자체 데이터/도구만 사용 (있다면) | 켬 (On) |
끄고 나면 환율 발화는 반드시 도구를 거쳐야 답할 수 있습니다. 이게 도구 채택을 강제하는 가장 깔끔한 방법.
이름이 다른 경우 (UI 변종)
| UI 표기 | 동일 의미 |
|---|---|
| “Use general knowledge” | 일반 지식 ON/OFF |
| “Allow web search” | 웹 검색 ON/OFF |
| “Use AI to fill gaps” | 모델 자체 응답 허용 |
세 항목 모두 OFF 로 두면 가장 안전.
Step 6 — 테스트
테스트 패널에서 발화를 차례대로 입력합니다.
| 발화 | 기대 동작 |
|---|---|
| “오늘 달러 환율 알려줘” | GetExchangeRate(base=USD, symbols=KRW) → 응답 |
| “엔화 환율은?” | GetExchangeRate(base=JPY, symbols=KRW) → 응답 |
| “유로 → 달러” | GetExchangeRate(base=EUR, symbols=USD) → 응답 |
| “오늘 점심 뭐 먹지?” | 도구 호출 안 함 (관련 없음, 일반 지식 OFF 라 “모릅니다” 또는 도구로 답할 수 없음 안내) |
기대 답변 예시
2026-05-09 기준 USD → KRW 환율은 약 1,352.41원 입니다.
활동 추적 (Activity)
테스트 패널의 활동 보기 에서 다음을 확인합니다.
| 단계 | 확인 |
|---|---|
| 도구 선택 | GetExchangeRate 채택됨 |
| 입력 | base=USD, symbols=KRW |
| 호출 | GET https://api.frankfurter.app/latest?base=USD&symbols=KRW → 200 |
| 응답 | rates.KRW 값 추출 → 자연어 답 생성 |
Step 7 — 디버깅: 채택이 안 될 때
| 점검 | 행동 |
|---|---|
| 인터넷 검색이 아직 켜져 있음 | Step 5 의 3가지 항목 모두 OFF 재확인 |
| 도구 설명이 모호 | “환율을 물으면 이 도구를…” 처럼 트리거 조건 명시 |
| 변수 설명이 비어 있음 | base/symbols 에 설명·예시 추가 (Step 3) |
| 지침이 도구를 안 가리킴 | Step 4 블록 추가 또는 강조 문구 |
| 모델이 약함 | 오케스트레이터 모델 점검 (기본과정 M6) |
가장 자주 놓치는 게 Step 5 (인터넷 검색 OFF) 입니다. 켜져 있으면 모델이 도구 없이도 답을 시도해 채택률이 들쭉날쭉해집니다.
체크리스트
- 도구 추가 → REST API 로 YAML 붙여넣기 →
GetExchangeRate생성 - 백엔드에서 사용자 지정 커넥터가 자동 생성됨 (Power Apps 에서 확인 가능)
- 도구 검색에서
GetExchangeRate노출 확인 - 입력 변수
base(기준) /symbols(비교) UI 라벨·설명 다듬음 - 지침에 “환율 처리 규칙” 블록 추가
- 설정 → 인터넷 검색 / 일반 지식 OFF
- 4가지 테스트 발화 모두 기대대로 동작 (활동 추적 확인)
정리 — 두 실습 합치면
| 실습 | 학습 포인트 |
|---|---|
| ① | REST API 선정 + Copilot 으로 OpenAPI YAML 작성 = AI 가 어떤 API 든 도구화 가능한 입력을 만들어준다 |
| ② | Studio “도구 추가 → REST API” + 인터넷 검색 OFF + 테스트 = 한 화면에서 자동 커넥터 생성 + 채택 강제 |
다른 외부 API 를 연결할 때도 이 두 단계는 그대로 동일 합니다. 바뀌는 건 ① 의 프롬프트(대상 API 정보) 와 ② 의 인증 설정뿐입니다.
다음 모듈: S5. MCP 서버 연결