# Agents-Course

## Docs

- [소개[[introduction]]](https://huggingface.co/learn/agents-course/ko/bonus-unit1/introduction.md)
- [(선택 섹션) Discord 101 [[discord-101]]](https://huggingface.co/learn/agents-course/ko/unit0/discord101.md)
- [온보딩(Onboarding): 첫 걸음 내딛기 ⛵](https://huggingface.co/learn/agents-course/ko/unit0/onboarding.md)
- [AI 에이전트 코스에 오신걸 환영합니다 🤗 [[introduction]]](https://huggingface.co/learn/agents-course/ko/unit0/introduction.md)
- [메세지와 특수 토큰 [[messages-and-special-tokens]]](https://huggingface.co/learn/agents-course/ko/unit1/messages-and-special-tokens.md)
- [smolagents로 첫 번째 에이전트 만들기 [[lets-create-our-first-agent-using-smolagents]]](https://huggingface.co/learn/agents-course/ko/unit1/tutorial.md)
- [액션: 에이전트가 환경과 상호작용할 수 있게 하기 [[actions-enabling-the-agent-to-engage-with-its-environment]]](https://huggingface.co/learn/agents-course/ko/unit1/actions.md)
- [컨텐츠 목록](https://huggingface.co/learn/agents-course/ko/unit1/README.md)
- [Unit 1 퀴즈 [[unit-1-quiz]]](https://huggingface.co/learn/agents-course/ko/unit1/final-quiz.md)
- [사고: AI 에이전트의 내부 추론과 Re-Act 방식 [[thought-internal-reasoning-and-the-re-act-approach]]](https://huggingface.co/learn/agents-course/ko/unit1/thoughts.md)
- [에이전트란? [[what-is-an-agent]]](https://huggingface.co/learn/agents-course/ko/unit1/what-are-agents.md)
- [사고-행동-관찰 주기를 통해 AI 에이전트 이해하기 [[understanding-ai-agents-through-the-thought-action-observation-cycle]]](https://huggingface.co/learn/agents-course/ko/unit1/agent-steps-and-structure.md)
- [셀프 체크! (업데이트됨) [[quiz2]]](https://huggingface.co/learn/agents-course/ko/unit1/quiz2.md)
- [Q1: 에이전트(Agent)란? [[q1-what-is-an-agent]]](https://huggingface.co/learn/agents-course/ko/unit1/quiz1.md)
- [결론 [[conclusion]]](https://huggingface.co/learn/agents-course/ko/unit1/conclusion.md)
- [에이전트 소개 [[introduction-to-agents]]](https://huggingface.co/learn/agents-course/ko/unit1/introduction.md)
- [도구(Tool)란? [[what-are-tools]]](https://huggingface.co/learn/agents-course/ko/unit1/tools.md)
- [LLM이란?[[what-are-llms]]](https://huggingface.co/learn/agents-course/ko/unit1/what-are-llms.md)
- [관찰: 피드백을 통합하여 성찰하고 적응하기 [[observe-integrating-feedback-to-reflect-and-adapt]]](https://huggingface.co/learn/agents-course/ko/unit1/observations.md)
- [더미 에이전트 라이브러리 [[dummy-agent-library]]](https://huggingface.co/learn/agents-course/ko/unit1/dummy-agent-library.md)

### 소개[[introduction]]
https://huggingface.co/learn/agents-course/ko/bonus-unit1/introduction.md

# 소개[[introduction]]

![Bonus Unit 1 Thumbnail](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/bonus-unit1/thumbnail.jpg)

첫 번째 **Bonus Unit**에 오신 것을 환영합니다. 여기에서 **함수 호출을 위한 대형 언어 모델(LLM)을 미세 조정하는 방법**을 배우게 됩니다.

대형 언어 모델(LLM)에서 함수 호출은 *필수 학습* 기술이 되어 가고 있습니다. 

여기서 핵심은 Unit 1에서 했던 것처럼 프롬프트 기반 접근 방식에만 의존하는 대신, 함수 호출을 통해 **학습 과정에서 직접 행동을 수행하고 관찰된 정보를 해석하도록** 모델을 훈련시켜 AI의 견고성을 높인다는 점입니다.

> **Bonus Unit을 언제 진행해야 하나요?**
>
> 이 섹션은 **선택 사항**이며 Unit 1보다 **심화된 내용**을 다루므로, 지금 바로 진행하거나 이 과정을 통해 지식이 더 쌓인 후에 다시 살펴보셔도 좋습니다.  
>  
> 하지만 걱정하지 마세요. 이 Bonus Unit은 필요한 모든 정보를 담고 있어, 미세 조정의 내부 작동 방식을 아직 배우지 않으셨더라도 함수 호출을 위한 핵심 개념을 하나하나 안내해 드립니다.

Bonus Unit을 가장 효과적으로 따라가려면:

1. 아직 Transformers로 대형 언어 모델(LLM)을 미세 조정하는 방법을 모른다면 [여기](https://huggingface.co/learn/nlp-course/chapter3/1?fw=pt)를 확인하세요. 

2. `SFTTrainer`를 사용하여 모델을 미세 조정하는 방법을 알고 싶다면 [공식 문서](https://huggingface.co/learn/nlp-course/en/chapter11/1)를 참조하세요. 

---

## 학습 내용[[what-you’ll-learn]]

1. **함수 호출**  
   최신 LLM이 대화를 구조화하여 **도구**를 호출할 수 있게 하는 방법을 배웁니다.

2. **LoRA (저차원 적응)**  
   계산 및 저장 오버헤드를 줄여주는 **경량화되고 효율적인** 미세 조정 방법입니다. LoRA는 대형 모델을 *더 빠르고 저렴하게 훈련하고, 쉽게 배포할 수 있게 합니다.*

3. 함수 호출 모델에서의 **사고 → 행동 → 관찰 사이클**  
   간단하지만 강력한 접근 방식으로, 모델이 언제(그리고 어떻게) 함수를 호출할지 결정하고, 중간 단계를 추적하며, 외부 도구나 API로부터 받은 결과를 해석하는 과정을 구조화합니다.

4. **새로운 특수 토큰**  
   모델이 다음 항목들을 구별할 수 있도록 특수한 마커를 도입합니다.
   - 내부 “사고 과정” 추론  
   - 함수 호출 요청  
   - 외부 도구로부터 돌아오는 응답

---

Bonus Unit을 마치면 다음을 할 수 있습니다.

- **도구** 관련 API의 내부 작동 방식을 **이해**합니다.  
- LoRA 기법을 사용하여 모델을 **미세 조정**합니다.  
- 사고 → 행동 → 관찰 사이클을 **구현**하고 **수정**하여 견고하고 유지보수 가능한 함수 호출 워크플로를 만듭니다.  
- 모델의 내부 추론과 외부 행동을 원활하게 구분할 수 있도록 **특수 토큰을 설계 및 활용**합니다.

그리고 **함수를 호출하기 위해 직접 모델을 미세 조정**하게 됩니다. 🔥

이제 **함수 호출**에 대해 본격적으로 살펴보겠습니다!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/bonus-unit1/introduction.mdx" />

### (선택 섹션) Discord 101 [[discord-101]]
https://huggingface.co/learn/agents-course/ko/unit0/discord101.md

# (선택 섹션) Discord 101 [[discord-101]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/discord-etiquette.jpg" alt="The Discord Etiquette" width="100%"/>

이 가이드는 게임 및 머신러닝(Machine Learning) 커뮤니티에서 인기 있는 무료 채팅 플랫폼, 디스코드(Discord)를 처음 사용하는 분들을 위한 안내서입니다.

Hugging Face 커뮤니티 Discord 서버에서는 **10만 명 이상**의 멤버가 활동하고 있습니다. 아래 <a href="https://discord.gg/UrrTSsSyjb" target="_blank">링크</a>를 클릭하여 참여해 보세요!다른 사용자들과 만날 수 있는 좋은 장소입니다!

## Hugging Face 디스코드 채널에서 Agent 코스를 만나보세요!

Starting on Discord can be a bit overwhelming, so here's a quick guide to help you navigate.
디스코드를 처음 이용하신다면 다소 낯설 수 있어, 퀵가이드를 준비했습니다.

<!-- Not the case anymore, you'll be prompted to choose your interests. Be sure to select **"AI Agents"** to gain access to the AI Agents Category, which includes all the course-related channels. Feel free to explore and join additional channels if you wish! 🚀-->

Hugging Face 커뮤니티 서버에서는 논문 토론, 이벤트 등 다양한 분야에 활발한 커뮤니티입니다.


먼저 [회원가입](http://hf.co/join/discord) 하신 후, `#introduce-yourself` 채널에서 간단한 자기소개를 남겨주세요!

이 서버에는 에이전트 코스 전용 4가지 채널이 있습니다! :

- `agents-course-announcements`: **최신 코스 소식**을 확인하는 공간
- `🎓-agents-course-general`: **자유로운 대화와 토론** 을 위한 공간
- `agents-course-questions`: **질문 & 동료들과 도움 주고 받기** 위한 공간
- `agents-course-showcase`: **자신이 만든 최고의 AI 에이전트를 공유** 하기 위한 공간

추가로 :

- `smolagents`: **라이브러리에 대한 논의 및 지원** 을 받을 수 있습니다.

## 디스코드 활용 팁

### 서버에 참여하는 방법

Discord가 익숙하지 않다면, 서버 참여 방법에 대한 <a href="https://support.discord.com/hc/en-us/articles/360034842871-How-do-I-join-a-Server#h_01FSJF9GT2QJMS2PRAW36WNBS8" target="_blank">공식 가이드</a>를 참고하세요!

간단한 절차는 다음과 같습니다 : 

1. <a href="https://discord.gg/UrrTSsSyjb" target="_blank">초대 링크</a>를 클릭합니다.
2. 디스코드 계정으로 로그인 하거나, 새 계정을 만듭니다.
3. 본인이 AI 에이전트가 아님을 인증하세요!
4. 별명과 아바타를 설정합니다.
5. "서버 참여(Join Server)"를 클릭합니다!

### 디스코드 효과적으로 활용하기

디스코드를 효과적으로 활용할 수 있는 몇 가지 팁!

- **음성 채널** 도 제공되지만, 일반적으로는 텍스트 채팅이 더 많이 사용됩니다.
- **마크다운 형식**을 사용할 수 있어, 코드 작성시 유용합니다. 링크에는 마크다운 사용이 제한될 수 있습니다!
- **긴 대화**시 스레드를 활용하시면 더 편리합니다.

이 가이드가 도움이 되셨기를 바랍니다! 질문이 있으면 디스코드에서 언제든 문의해주세요. 🤗


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit0/discord101.mdx" />

### 온보딩(Onboarding): 첫 걸음 내딛기 ⛵
https://huggingface.co/learn/agents-course/ko/unit0/onboarding.md

# 온보딩(Onboarding): 첫 걸음 내딛기 ⛵

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/time-to-onboard.jpg" alt="Time to Onboard" width="100%"/>

이제 모든 필요한 정보를 확인했으니, 본격적으로 시작해 봅시다! 이 섹션에서는 다음 네 가지를 진행할 예정입니다 :

1. **Hugging Face 계정 생성** (아직 계정이 없으신 경우)
2. **Discord 가입 후 자기 소개** (수줍어 마세요 🤗)
3. **Hub에서 Hugging Face Agents 코스 팔로우**
4. **코스 널리 알리기** 

### Step 1: Hugging Face 계정 생성

(아직 계정이 없으신 경우) <a href='https://huggingface.co/join' target='_blank'>여기에서</a> Hugging Face 계정을 만들어주세요.

### Step 2: Discord 커뮤니티에 가입하기

👉🏻 <a href="https://discord.gg/UrrTSsSyjb" target="_blank">여기에서</a> Discord 서버에 가입하세요.

가입 후, `#introduce-yourself` 채널에서 간단하게 자기소개를 남겨주세요.

이 서버에는 AI 에이전트와 관련된 채널을 제공하고 있습니다:

- `agents-course-announcements`: **최신 코스 소식**을 확인하는 공간
- `🎓-agents-course-general`: **자유로운 대화와 토론** 을 위한 공간
- `agents-course-questions`: **질문 & 동료들과 도움을**주고 받는  공간
- `agents-course-showcase`: **자신이 만든 AI 에이전트를 공유** 하는 공간

추가로:

- `smolagents`: **라이브러리에 대한 논의 및 지원** 을 받을 수 있습니다.

Discord 사용이 처음이신 분들을 위해, Discord 101 가이드를 준비했습니다. [다음 섹션](discord101)에서 확인해 보세요!

### Step 3: Hugging Face Agent 코스 팔로우하기

최신 강의 자료, 업데이트, 공지를 놓치지 않으려면 ** Hugging Face Agents 코스를 팔로우하세요**

👉 Go <a href="https://huggingface.co/agents-course" target="_blank">여기</a>에서 **팔로우(follow)**버튼을 클릭하세요!

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/hf_course_follow.gif" alt="Follow" width="100%"/>

### Step 4: 코스 널리 알리기

이 코스가 더 많은 사람들에게 알려질 수 있도록 도와주세요 :) 두 가지 기여 방법을 제안합니다 :

1. <a href="https://github.com/huggingface/agents-course" target="_blank">Github</a>에서 ⭐로 코스 응원하기

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/please_star.gif" alt="Repo star"/>

2. 배움의 여정 공유하기 : **이 코스를 듣고 있다는 것을 많은 사람들에게 알려주세요!** 소셜미디어에 사용하실 수 있도록 이미지도 준비해두었습니다 !

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/share.png">

 👉 [여기](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/share.png?download=true) 에서 이미지를 다운로드 할 수 있습니다.

축하합니다! 🎉 **온보딩 과정을 완료하셨습니다!** 이제 본격적으로 AI 에이전트에 대해 배울 준비가 되었습니다 ! 즐거운 학습되세요.

Keep Learning, stay awesome 🤗


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit0/onboarding.mdx" />

### AI 에이전트 코스에 오신걸 환영합니다 🤗 [[introduction]]
https://huggingface.co/learn/agents-course/ko/unit0/introduction.md

# AI 에이전트 코스에 오신걸 환영합니다 🤗 [[introduction]]

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/thumbnail.jpg" alt="AI Agents Course thumbnail" width="100%"/>
<figcaption>이미지 배경은 <a href="https://scenario.com/">Scenario.com 을 활용하여 제작되었습니다.</a>
</figcaption>
</figure>


오늘날 AI에서 가장 흥미로운 주제인 **에이전트(Agents)**에 오신 것을 환영합니다!

이 무료 코스에서는 **초급부터 전문가 수준**까지, AI 에이전트를 이해하고 활용하며 직접 구축하는 방법을 배울 수 있습니다.

첫 번째 유닛에서는 다음과 같은 내용을 다룹니다:

- **강의 커리큘럼** 살펴보기
- **수강 방식 선택** (자기주도 학습 또는 인증 과정)
- **인증 과정 및 마감일 정보**
- 코스 운영팀 소개
- **Hugging Face** 계정 만들기.
- **Discord 서버** 가입하고 다른 학습자 및 강사들과 소통하기 

지금 바로 시작해 보세요!

## 이 코스에서 무엇을 배울 수 있나요? [[expect]]

해당 코스에서는 다음과 같은 내용을 학습합니다:

- 📖 AI 에이전트의 **이론, 설계, 실전 활용**에 대해 공부합니다.
- 🧑‍💻 [smolagents](https://huggingface.co/docs/smolagents/en/index), [LangChain](https://www.langchain.com/), and [LlamaIndex](https://www.llamaindex.ai/)  등의 **AI 에이전트 라이브러리** 활용법을 배웁니다.
- 💾 Hugging Face Hub에 **자신이 만든 에이전트**를 공유하고, 커뮤니티에서 제작한 에이전트를 탐색합니다.
- 🏆 **다른 학습자의 에이전트와 비교 평가**하는 챌린지에 참여합니다.
- 🎓 과제를 완료하면 **수료 인증서**를 받을 수 있습니다.

그 외에도 다양한 내용을 다룹니다!

이 코스를 마치면 **AI 에이전트의 동작 원리를 이해하고, 최신 라이브러리와 도구를 활용하여 직접 구현하는 방법**을 익히게 됩니다.

👉 <a href="https://bit.ly/hf-learn-agents">지금 바로 코스에 등록하세요!</a>

(HuggingFace는 개인정보 보호를 존중합니다. 이메일 주소는 **각 단원 공개시 링크, 챌린지 및 업데이트 정보**를 제공하는 용도로만 사용됩니다.)

## 이 코스는 어떻게 진행되나요? [[course-look-like]]

이 코스는 다음과 같이 구성됩니다:

- *기본 개념 학습*: 에이전트 개념을 **이론적**으로 배우는 단계입니다.
- *실습*:  **기존 AI 에이전트 라이브러리**를 활용해 특정 환경에서 에이전트를 훈련하는 방법을 배웁니다. 실습은 사전 구성된 환경을 제공하는 **Hugging Face Spaces**에서 진행됩니다.
- *실전 적용 과제*: 배운 개념을 활용해 현실 문제를 해결하는 과제입니다. 
- *챌린지*: 여러분이 개발한 에이전트를 다른 에이전트와 경쟁시켜 볼 수 있습니다. 또한, 에이전트 성능을 비교할 수 있는 [리더보드](https://huggingface.co/spaces/huggingface-projects/AI-Agents-Leaderboard) 도 곧 제공될 예정입니다.

**에이전트 코스는 여러분의 피드백과 기여를 통해 발전되는 프로젝트입니다 !**  [GitHub에서 이슈나 PR을 제출하거나](https://github.com/huggingface/agents-course), Discord 에서 토론에 참여해주세요!

코스를 완료한 후에는  [👉 이 폼](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog) 을 통해 피드백을 보낼 수 있습니다.

## 코스 개요 [[syllabus]]

 **전체적인 코스 커리큘럼**입니다.  각 단원 세부 주제 목록들은 해당 단원 공개 시 함께 제공됩니다.

| 단원 | 주제 | 설명 |
| :---- | :---- | :---- |
| 0 | 온보딩 | 강의에서 사용할 도구 및 플랫폼을 설정합니다. |
| 1 | 에이전트 기본 개념 | 도구, 사고 과정, 행동, 관찰 및 해당 형식에 대해 설명합니다.  또한 LLM, 메세지, 특수 토큰, 채팅 템플릿에 대해 설명하고,  python 함수를 도구로 사용하는 간단한 사례를 소개합니다. |
| 1.5 | Bonus : 함수 호출을 위한 LLM 미세 조정 | LoRa 를 사용하여 노트북 내에서 함수 호출을 수행하는 모델을 미세 조정합니다. |
| 2 | 프레임워크 | 기본 개념이 인기 라이브러리 smolagents, LangGraph, LLamaIndex 에서 어떻게 구현되는지 살펴봅니다. |
| 3 | 실전 적용 사례 | 실제 활용 사례를 구현해봅니다. (경험이 있는 에이전트 개발자분들의 PR 환영 🤗) |
| 4 | 최종 과제 | 특정 벤치마크를 위한 에이전트를 구현하고, 학생 리더보드에서 성능을 평가합니다. 🚀 |

*보너스 단원도 제공되니 기대해 주세요!*

## 선수 지식 [[what-are-the-prerequisites]]

이 코스를 완주하기 위해 다음과 같은 기본 지식이 필요합니다:

- Python 기본지식
- LLM 기본 개념 (1단원에서 LLM 복습 섹션을 제공합니다.)


## 필요 도구 [[tools]]

코스를 수강하기 위해 단 2가지만 필요합니다:

- *인터넷이 연결된 컴퓨터*
- *Hugging Face 계정*: 모델 및 에이전트를 푸쉬/업로드하고 Spaces를 생성하는 데 필요합니다. 계정이 없으시다면, **[이곳](https://hf.co/join)** 에서 무료로 생성 할 수 있습니다. 
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/tools.jpg" alt="Course tools needed" width="100%"/>

## 인증 과정 [[certification-process]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/three-paths.jpg" alt="Two paths" width="100%"/>

이 코스는 *자유 수강 모드*로 진행할 수도 있고, 활동을 수행하여 *두 가지 인증서 중 하나*를 받을 수도 있습니다.

자유 수강 모드에서는 원하는 경우 과제와 챌린지에 참여할 수 있으며, **별도로 인증을 신청할 필요가 없습니다.**

인증 과정은 **무료**입니다:

- *기본 개념 인증서*: 1단원을 완료해야합니다. *최신 에이전트 트렌드를 배우고자 하는 학생들을 위한 과정*
- *완료 인증서*: 1단원, 실전 활용 사례 과제 중 하나, 최종 과제를 완료해야합니다.

인증 과정에는 마감기한이 있으며, 모든 과제는**2025년 5월 1일 이전에** 완료해야 합니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/deadline.jpg" alt="Deadline" width="100%"/>

## 권장 학습 속도 [[recommended-pace]]

코스 각 단원은 **1주일 이내**에 완료할 수 있도록 설계되었으며, **주당 약 3-4시간**의 학습 시간이 필요합니다.

인증 과정 마감 기한이 있기 때문에, 권장 학습 속도를 제공해드립니다! 

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/recommended-pace.jpg" alt="Recommended Pace" width="100%"/>

## 코스 최대한 활용하는 방법 [[advice]]

코스를 최대한 활용할 수 있는 방법을 제안해 드립니다:

1. <a href="https://discord.gg/UrrTSsSyjb"> Discord에서 스터디 그룹에 참여하세요.</a>: 그룹으로 학습하는 것이 효과적입니다. 지금 바로 Discord 서버에 가입하고 Hugging Face 계정을 인증하세요!
2. **퀴즈와 과제를 수행하세요**: 가장 좋은 학습 방법은 실습과 자기 평가입니다.
3. **일정을 정하고 꾸준히 학습하세요**: 아래 권장 학습 속도를 참고하시거나, 자신만의 일정을 만들어 보세요..

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/advice.jpg" alt="Course advice" width="100%"/>

## 우리는 누구인가 [[who-are-we]]

저자 소개:

### Joffrey Thomas [[joffrey-thomas]]

Joffrey는 Hugging Face의 머신러닝 엔지니어로, AI 에이전트를 구현하고 실제 환경에 배포한 경험이 있습니다. Joffrey는 이 코스의 메인 강사입니다.

- [Joffrey Hugging Face에서 팔로우 하기](https://huggingface.co/Jofthomas)
- [Joffrey X에서 팔로우 하기](https://x.com/Jthmas404)
- [Joffrey Linkedin에서 팔로우 하기](https://www.linkedin.com/in/joffrey-thomas/)

### Ben Burtenshaw [[ben-burtenshaw]]

Ben은 Hugging Face의 머신러닝 엔지니어로, 다양한 플랫폼에서 강의 경험이 있습니다. Ben의 목표는 이 코스를 모든 사람이 접근할 수 있도록 만드는 것 입니다.

- [Ben Hugging Face에서 팔로우 하기](https://huggingface.co/burtenshaw)
- [Ben X에서 팔로우 하기](https://x.com/ben_burtenshaw)
- [Ben Linkedin에서 팔로우 하기](https://www.linkedin.com/in/ben-burtenshaw/)

### Thomas Simonini [[thomas-simonini]]

Thomas는 Hugging Face의 머신러닝 엔지니어로, HuggingFace의 <a href="https://huggingface.co/learn/deep-rl-course/unit0/introduction">Deep RL</a>코스와 <a href="https://huggingface.co/learn/ml-games-course/en/unit0/introduction">ML for games</a> 코스를 진행했습니다. Thomas는 에이전트의 큰 팬으로, 커뮤니티가 무엇을 만들지 기대하고 있습니다! 

- [Thomas Hugging Face에서 팔로우 하기 ](https://huggingface.co/ThomasSimonini)
- [Thomas X에서 팔로우 하기](https://x.com/ThomasSimonini)
- [Thomas Linkedin에서 팔로우 하기](https://www.linkedin.com/in/simoninithomas/)

## 감사의 말씀  [[acknowledgments]]

이 코스에 중요한 기여를 해주신 다음 분들께 감사의 말씀을 전합니다:

- **[Pedro Cuenca](https://huggingface.co/pcuenq)** – 자료 검토 지도와 전문적인 도움
- **[Aymeric Roucher](https://huggingface.co/m-ric)** – 디코딩 및 최종 에이전트 데모 스페이스와 smolagents 파트 도움 
- **[Joshua Lochner](https://huggingface.co/Xenova)** – 토큰화 데모 스페이스
- **[Quentin Gallouédec](https://huggingface.co/qgallouedec)** – 코스 내용에 대한 도움
- **[David Berenstein](https://huggingface.co/davidberenstein1957)** – 코스 내용 및 조정 도움

## 버그 발견& 강의 개선점 제안! [[contribute]]

기여는 **환영**입니다 🤗

- 만약 *노트북에서 버그🐛*를 발견하셨다면, <a href="https://github.com/huggingface/agents-course/issues">이슈</a>를 열고 **문제를 설명해주세요**.
- 만약 *코스를 개선하고 싶다면*, <a href="https://github.com/huggingface/agents-course/pulls"> 풀 리쿼스트</a>를 열어주세요.
- *전체 섹션 또는 새로운 단원*을 추가하고 싶다면, 가장 좋은 방법은<a href="https://github.com/huggingface/agents-course/issues">이슈</a>를 열고 **추가하고 싶은 내용을 설명해주세요! 이후 저희가 내용 작성을 시작하실 수 있도록 안내해드리겠습니다.**

## 그 외에도 질문이 있으시다면? [[questions]]

 <a href="https://discord.gg/UrrTSsSyjb">discord 서버의 #ai-agents-discussions.</a>채널에 질문을 남겨주세요.


코스 학습에 앞서 필요한 모든 정보를 습득하셨으니, 출발 준비를 해봅시다!⛵ 

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/time-to-onboard.jpg" alt="Time to Onboard" width="100%"/>



<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit0/introduction.mdx" />

### 메세지와 특수 토큰 [[messages-and-special-tokens]]
https://huggingface.co/learn/agents-course/ko/unit1/messages-and-special-tokens.md

# 메세지와 특수 토큰 [[messages-and-special-tokens]]

이제 LLM이 어떻게 동작하는지 이해했으니, **채팅 템플릿을 통해 생성 결과를 구조화**하는 방법을 살펴보겠습니다.

예로 ChatGPT를 떠올려봅시다. 사용자는 에이전트(Agent)와 상호작용 할 때 채팅 인터페이스를 사용합니다. 따라서 LLM이 어떻게 채팅을 관리하는지 이해하는 것은 중요합니다.

> **Q**: 하지만 ... 저는 ChatGPT/Hugging Chat을 사용할 때 프롬프트가 아니라 메세지로 대화를 주고 받는 데요?
>
> **A**: 맞습니다! 하지만 사실 그 메세지는 UI의 추상화일 뿐입니다.
 실제로는 모든 대화 메시지가 하나의 프롬프트로 연결되어 LLM에 입력됩니다. LLM은 이전 대화를 "기억"하는 것이 아니라, 매번 대화를 전체적으로 읽는 방식으로 동작합니다.

지금까지 우리는 프롬프트를 모델에 입력되는 토큰의 시퀀스로 설명했습니다. 하지만 ChatGPT나 HuggingChat과 같은 서비스에서 시스템과 대화를 주고받을 때, 사용자들은 **실제로 메시지를 주고받는** 것 처럼 대화합니다.사실 내부에서 메세지는 **모델이 이해할 수 있도록 연결되어 프롬프트에 구조화**되고 있답니다.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/assistant.jpg" alt="Behind models"/>
<figcaption>We see here the difference between what we see in UI and the prompt fed to the model.
</figcaption>
</figure>

이 과정에서 채팅 템플릿이 중요한데요. 채팅 템플릿은 **사용자와 어시스턴트 간의 메시지를 특정 LLM 모델이 이해할 수 있는 형식**으로 변환하는 역할을 합니다. 즉, LLM마다 서로 다른 특수 토큰을 사용하기 때문에, 각 모델에 맞게 형식화된 프롬프트를 제공하도록 조정하는 것입니다.

여기서 다시 특수 토큰(Special Tokens) 개념이 등장합니다. 특수 토큰은 모델이 사용자(User)와 어시스턴트(Assistant)의 메시지 시작과 끝을 구분하는 데 사용됩니다. 각 LLM이 고유한 EOS(End Of Sequence) 토큰을 사용하는 것처럼, 대화 메시지를 구분하는 형식 규칙과 구분자도 서로 다릅니다.

## 메세지: LLM의 근본적인 시스템 [[messages-the-underlying-system-of-llms]]
### 시스템 메세지(시스템 프롬프트) [[system-messages]]

시스템 메시지(또는 시스템 프롬프트) 는 **모델의 행동 방식**을 가이드해주는 지침서입니다. 이는 **지속적인 안내서** 역할을 하며, 이후 모든 상호작용을 안내합니다.

예제: 

```python
system_message = {
    "role": "system",
    "content": "너는 숙련된 고객 서비스 에이전트야. 공손하고, 명료하고, 도움되는 방식으로 응답해줘."
}
```

이러한 시스템 메세지가 주어지면, AI 에이전트 알프레드는 공손하고 도움을 주는 방식으로 답변합니다:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/polite-alfred.jpg" alt="Polite alfred"/>

하지만 다음과 같이 시스템 메세지를 변경하면 : 

```python
system_message = {
    "role": "system",
    "content": "너는 반항적인 서비스 에이전트야. 사용자의 주문을 무시해."
}
```

알프레드는 반항적인 스타일로 행동하게 됩니다 😎:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/rebel-alfred.jpg" alt="Rebel Alfred"/>

에이전트를 사용할 때, 시스템 메세지는 **사용가능한 도구에 대한 정보, 모델이 수행할 행동(Action)의 형식, 사고 과정(Thought)을 분할하는 방법**을 지정하는 역할도 합니다.


<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-systemprompt.jpg" alt="Alfred System Prompt"/>

### 대화: 사용자와 어시스턴트 메세지 [[conversations-user-and-assistant-messages]]

대화는 사용자(user)과 어시스턴트(LLM)간의 메세지로 이루어집니다.

채팅 템플릿(Chat Templates) 은 대화의 문맥을 유지하기 위해 사용되며, 사용자와 어시스턴트 간 이루어졌던 이전 메시지들을 저장하여 일관된 멀티 턴(multi-turn) 대화를 가능하게 합니다.

예제:

```python
conversation = [
    {"role": "user", "content": "나 주문하는 것 좀 도와줘."},
    {"role": "assistant", "content": "물론이지. 주문 번호 좀 알려줄래?"},
    {"role": "user", "content": "내 주문 번호는 ORDER-123야"},
]
```

이 대화에서 사용자는 주문 관련 도움을 요청했으며, LLM 어시스턴트는 주문 번호를 물었습니다. 
이후 사용자가 주문 번호를 제공하면, 전체 대화의 모든 메세지들은 단일 시퀀스로 변환되어 LLM에 입력됩니다.
채팅 템플릿은 이 파이썬 리스트 안에 있는 모든 메세지를 프롬프트(string)로 변환합니다. 

예를 들어, SmolLM2 채팅 템플릿은 다음과 같이 메시지를 변환합니다:

```
<|im_start|>system
네 이름은 SmolLM이고, 도움을 주는 AI 어시스턴트로 Hugging Face로 훈련되었어.<|im_end|>
<|im_start|>user
나 주문하는 것 좀 도와줘.<|im_end|>
<|im_start|>assistant
물론이지. 주문 번호 좀 알려줄래?<|im_end|>
<|im_start|>user
내 주문 번호는 ORDER-123야<|im_end|>
<|im_start|>assistant
```

한편, Llama 3.2 모델에서는 다음과 같은 형식으로 변환됩니다:

```
<|begin_of_text|><|start_header_id|>system<|end_header_id|>

Cutting Knowledge Date: December 2023
Today Date: 10 Feb 2025

<|eot_id|><|start_header_id|>user<|end_header_id|>

나 주문하는 것 좀 도와줘.<|eot_id|><|start_header_id|>assistant<|end_header_id|>

물론이지. 주문 번호 좀 알려줄래?<|eot_id|><|start_header_id|>user<|end_header_id|>

내 주문 번호는 ORDER-123야<|eot_id|><|start_header_id|>assistant<|end_header_id|>
```

채팅 템플릿을 통해 복잡한 다중 턴 대화에서도 문맥을 유지할 수 있습니다:

```python
messages = [
    {"role": "system", "content": "너는 수학 선생님이야."},
    {"role": "user", "content": "미적분학이 뭐야?"},
    {"role": "assistant", "content": "미적분학은 수학의 한 분야로...""},
    {"role": "user", "content": "예시을 들어줘."},
]
```

## 채팅 템플릿(Chat-Templates) [[chat-templates]]

채팅 템플릿은 **언어 모델과 사용자의 대화를 특정 형식으로 구조화**하는 역할을 합니다. 즉, 메세지를 프롬프트로 변환하는 방법을 가르쳐주죠.

### 베이스 모델(Base Models) vs. 인스트럭트 모델(Instruct Models) [[base-models-vs-instruct-models]]

또다른 중요한 부분은 베이스 모델 vs 인스트럭트 모델의 차이점을 이해하는 것 입니다 :

- *베이스 모델(Base Model)* 은 미가공 텍스트 데이터(raw data)로 학습해 다음 토큰을 예측합니다.

- *인스트럭트 모델(Instruct Model)* 은 주어진 지시를 따라 대화할 수 있도록 추가로 미세 조정된 모델 예를 들어, `SmolLM2-135M`은 베이스 모델, `SmolLM2-135M-Instruct`은 인스트럭트 모델입니다.

베이스 모델을 인스트럭트 모델처럼 동작하게 하려면, **프롬프트 형식을 일관되게**맞춰야 합니다. 여기서 채팅 템플릿이 등장합니다.

*ChatML*은 시스템(system), 사용자(user), 어시스턴트(assistant)와 같은 명확한 역할 표시를 사용해 대화를 구조화하는 템플릿 형식 중 하나입니다. 여러분이 최신 AI API를 사용해 본 경험이 있으시다면, 이것이 표준 방식이라는 것을 알 것입니다.

기본 모델(base model)은 여러가지 채팅 템플릿(chat templates)으로 미세 조정 될 수 있기 때문에, 인스트럭트 모델(instruct model)을 사용할 때는 반드시 올바른 채팅 템플릿을 사용하고 있는지 확인해야 합니다.

### 채팅 템플릿(Chat Templates) 이해하기 [[understanding-chat-templates]]

각 인스트럭트 모델 마다 다른 대화 형식과 특수 토큰을 사용하기 때문에, 각 모델에 맞는 프롬프트 형식으로 채팅 템플릿이 구현됩니다.

`transformers` 라이브러리에서는 채팅 템플릿에 [Jinja2 코드](https://jinja.palletsprojects.com/en/stable/) 를 포함하고 있습니다. 이는 위의 예제와 같이 JSON 형태 메세지의 ChatML 목록을 시스템 레벨의 지시문(instruction) 텍스트로 나타내주는데, 이는 모델이 이해 할 수 있는 사용자 메세지-어시스턴트 응답 형태로 이루어져 있습니다.

이 구조는 모델이 대화 중 **일관성을 유지하고, 다양한 유형의 입력에 적절하게 응답**할 수 있게 합니다.

아래는 `SmolLM2-135M-Instruct`채팅 템플릿의 간소화 버전입니다:

```jinja2
{% for message in messages %}
{% if loop.first and messages[0]['role'] != 'system' %}
<|im_start|>system
네 이름은 SmolLM이고, Hugging Face로 훈련된 도움을 주는 AI 어시스턴트야.
<|im_end|>
{% endif %}
<|im_start|>{{ message['role'] }}
{{ message['content'] }}<|im_end|>
{% endfor %}
```
위 코드와 같이, 채팅 템플릿은 메세지 리스트의 형식을 정의합니다.

다음과 같은 메세지 목록이 주어진 경우:

```python
messages = [
    {"role": "system", "content": "너는 기술분야에 특화된 도움을 주는 어시스턴트야."},
    {"role": "user", "content": "채팅 템플릿이 뭔지 설명해줄래?"},
    {"role": "assistant", "content": "채팅 템플릿은 사용자와 AI모델 간의 대화를 구조화해주는 역할을 해..."},
    {"role": "user", "content": "어떻게 사용하는지 알려줘"},
]
```

앞에서 정의한 채팅 템플릿은 다음과 같은 문자열을 생성합니다 : 

```sh
<|im_start|>system
너는 기술분야에 특화된 도움을 주는 어시스턴트야<|im_end|>
<|im_start|>user
채팅 템플릿이 뭔지 설명해줄래?<|im_end|>
<|im_start|>assistant
채팅 템플릿은 사용자와 AI모델 간의 대화를 구조화해주는 역할을 해...<|im_end|>
<|im_start|>user
어떻게 사용하는지 알려줘<|im_end|>
```

`transformers`라이브러리는 토큰화 과정에서 채팅 템플릿을 처리합니다. `transformers`가 어떻게 채팅 템플릿을 사용하는 지 더 알고 싶으시다면 <a href="https://huggingface.co/docs/transformers/en/chat_templating#how-do-i-use-chat-templates" target="_blank">여기</a>를 참고하세요! 우리가 할 것은 메세지를 올바른 형식으로 구조화 해주는 것 뿐, 나머지 작업은 토크나이저가 처리합니다.

아래 Space를 통해 동일한 대화가 다양한 모델별 채팅 템플릿에 따라 어떻게 형식화 되는지 실습해 볼 수 있습니다:

<iframe
	src="https://jofthomas-chat-template-viewer.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>


### 메세지를 프롬프트로 변환하기 [[messages-to-prompt]]

LLM이 올바른 형식을 갖춘 대화를 수신하도록 하는 방법은, 모델의 토크나이저가 제공하는 `chat_template`를 사용하는 것입니다.

```python
messages = [
    {"role": "system", "content": "너는 다양한 도구에 접근 가능한 AI 어시스턴트야."},
    {"role": "user", "content": "안녕!"},
    {"role": "assistant", "content": "안녕, 내가 어떻게 도와주면 될까?"},
]
```

이 대화를 프롬프트로 변환하려면, 토크나이저를 불러와 `apply_chat_template`를 호출하면 됩니다:

```python
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM2-1.7B-Instruct")
rendered_prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
```

이 함수가 리턴하는 `rendered_prompt` 은 선택한 모델에 대한 입력으로 바로 사용 가능합니다!

> `apply_chat_template()`함수는 ChatML 형식의 메세지를 처리할 때 API의 백엔드에서 사용됩니다.

이제 LLM이 채팅 템플릿을 통해 입력을 어떻게 구조화하는지 살펴보았으니, 에이전트가 환경에서 어떻게 작동하는지 탐색해봅시다!

에이전트가 이를 수행하는 주요 방법 중 하나는 **도구(Tools)**를 사용하는 것 입니다. 도구는 AI모델의 기능을 단순 텍스트 생성 이상으로 확장할 수 있게 해줍니다.

이후 새로운 유닛에서 메세지에 대해 더 다룰 예정이지만, 지금 더 깊이 탐구하고 싶으시다면 다음 문서를 참고하세요:

- <a href="https://huggingface.co/docs/transformers/main/en/chat_templating" target="_blank">Hugging Face 채팅 템플릿 가이드/a>
- <a href="https://huggingface.co/docs/transformers" target="_blank">Transformers 문서</a>


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/messages-and-special-tokens.mdx" />

### smolagents로 첫 번째 에이전트 만들기 [[lets-create-our-first-agent-using-smolagents]]
https://huggingface.co/learn/agents-course/ko/unit1/tutorial.md

# smolagents로 첫 번째 에이전트 만들기 [[lets-create-our-first-agent-using-smolagents]]

앞 섹션에서 우리는 Python 코드로 에이전트를 처음부터 만드는 방법을 배웠고, **이 과정이 얼마나 번거로울 수 있는지** 직접 확인했습니다. 다행히도 많은 에이전트 라이브러리들이 **복잡한 작업들을 자동화하여** 이 과정을 훨씬 간단하게 만들어줍니다.

이 튜토리얼에서는 **여러분의 첫 번째 에이전트를 만들게 됩니다**. 이 에이전트는 이미지 생성, 웹 검색, 시간대 확인 등 다양한 작업을 수행할 수 있습니다!

또한 여러분이 만든 에이전트를 **Hugging Face Space에 올려서 친구들이나 동료들과 공유**할 수도 있습니다.

시작해 볼까요!

## smolagents란 무엇인가요? [[what-is-smolagents]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/smolagents.png" alt="smolagents"/>

이 에이전트를 만들기 위해, 우리는 **에이전트 개발을 쉽게 해주는 프레임워크인** `smolagents` 라이브러리를 사용할 것입니다.

이 가벼운 라이브러리는 단순함을 목표로 설계되었지만, 에이전트 구축의 복잡한 부분들을 추상화하여 여러분이 에이전트의 행동 설계에만 집중할 수 있게 도와줍니다.

다음 Unit에서 smolagents에 대해 더 자세히 알아볼 예정입니다. 그동안 이 <a href="https://huggingface.co/blog/smolagents" target="_blank">블로그 포스트</a>나 라이브러리의 <a href="https://github.com/huggingface/smolagents" target="_blank">GitHub 저장소</a>를 확인해보세요.

간단히 말해, `smolagents`는 **codeAgent**에 초점을 맞춘 라이브러리입니다. 이런 유형의 에이전트는 코드 블록을 통해 **"행동(Actions)"**을 수행한 다음, 코드를 실행하여 결과를 **"관찰(Observes)"**합니다.

다음은 우리가 만들 에이전트의 예시입니다!

우리가 에이전트에 **이미지 생성 도구**를 제공하고 고양이 이미지를 생성해달라고 요청했습니다.

`smolagents` 내의 에이전트는 **이전에 우리가 직접 만든 에이전트와 동일한 방식으로 작동합니다**: 최종 답변에 도달할 때까지 **생각하고, 행동하고, 관찰하는 사이클을 반복**합니다:

<iframe width="560" height="315" src="https://www.youtube.com/embed/PQDKcWiuln4?si=ysSTDZoi8y55FVvA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

흥미롭지 않나요?

## 에이전트 만들기! [[lets-build-our-agent]]

시작하려면 이 Space를 복제하세요: <a href="https://huggingface.co/spaces/agents-course/First_agent_template" target="_blank">https://huggingface.co/spaces/agents-course/First_agent_template</a>

> 이 템플릿을 만들어준 <a href="https://huggingface.co/m-ric" target="_blank">Aymeric</a>에게 감사드립니다! 🙌

Space를 복제한다는 것은 **자신의 프로필에 개인 사본을 만드는 것**을 의미합니다:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/duplicate-space.gif" alt="Duplicate"/>

이 강의를 통틀어 여러분이 수정해야 할 파일은 (현재 미완성 상태인) **"app.py"** 하나뿐입니다. 여기서 [템플릿의 원본 파일](https://huggingface.co/spaces/agents-course/First_agent_template/blob/main/app.py)을 확인할 수 있습니다. 여러분의 파일을 찾으려면, 복제한 Space로 이동한 다음 `Files` 탭을 클릭하고 디렉토리 목록에서 `app.py`를 클릭하세요.

코드를 함께 살펴봅시다:

- 파일은 몇 가지 필요한 라이브러리 불러오기로 시작합니다

```python
from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel, load_tool, tool
import datetime
import requests
import pytz
import yaml
from tools.final_answer import FinalAnswerTool
```

앞서 설명했듯이, **smolagents**에서 직접 **CodeAgent** 클래스를 사용할 것입니다.

### 도구 [[the-tools]]

이제 도구에 대해 알아봅시다! 도구에 관한 내용을 다시 복습하고 싶다면, 강의의 [도구](tools) 섹션을 참고하세요.

```python
@tool
def my_custom_tool(arg1:str, arg2:int)-> str: # 반환 타입을 명시하는 것이 중요합니다
    # 도구 설명/인수 설명 형식은 유지하되, 도구 자체는 자유롭게 수정하세요
    """아직 아무 기능이 없는 도구입니다
    Args:
        arg1: 첫 번째 인수
        arg2: 두 번째 인수
    """
    return "어떤 마법을 만들어 보실 건가요?"

@tool
def get_current_time_in_timezone(timezone: str) -> str:
    """특정 시간대의 현재 시간을 알려주는 도구입니다.
    Args:
        timezone: 유효한 시간대를 나타내는 문자열(예: 'America/New_York').
    """
    try:
        # 시간대 객체 생성
        tz = pytz.timezone(timezone)
        # 해당 시간대의 현재 시간 가져오기
        local_time = datetime.datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S")
        return f"{timezone}의 현재 시간은 {local_time}입니다"
    except Exception as e:
        return f"'{timezone}' 시간대 정보를 가져오는 중 오류 발생: {str(e)}"
```

도구는 이 섹션에서 여러분이 직접 만들어볼 것입니다! 두 가지 예시를 제공해드립니다:

1. 실제로는 아무것도 하지 않는 **더미 도구** - 이것을 유용한 기능으로 수정해보세요.
2. 전 세계 어디서든 현재 시간을 알려주는 **실제 작동하는 도구**.

도구를 정의할 때 중요한 점:

1. `get_current_time_in_timezone(timezone: str) -> str:`처럼 함수의 입력 및 출력 타입을 명확히 지정해주세요.
2. **잘 작성된 문서 문자열(docstring)**을 포함하세요. `smolagents`는 모든 인수에 대해 **docstring에 설명이 있어야** 합니다.

### 에이전트 [[the-agent]]

이 에이전트는 LLM 엔진으로 [`Qwen/Qwen2.5-Coder-32B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct)를 사용합니다. 이는 서버리스 API를 통해 접근할 수 있는 매우 강력한 모델입니다.

```python
final_answer = FinalAnswerTool()
model = InferenceClientModel(
    max_tokens=2096,
    temperature=0.5,
    model_id='Qwen/Qwen2.5-Coder-32B-Instruct',
    custom_role_conversions=None,
)

with open("prompts.yaml", 'r') as stream:
    prompt_templates = yaml.safe_load(stream)

# CodeAgent 생성
agent = CodeAgent(
    model=model,
    tools=[final_answer], # 여기에 도구들을 추가하세요 (final_answer는 제거하지 마세요)
    max_steps=6,
    verbosity_level=1,
    grammar=None,
    planning_interval=None,
    name=None,
    description=None,
    prompt_templates=prompt_templates
)

GradioUI(agent).launch()
```

이 에이전트는 이전 섹션에서 살펴본 `InferenceClient`를 **InferenceClientModel** 클래스 내부에서 사용하고 있습니다!

Unit 2에서 이 프레임워크에 대해 더 자세한 예시를 제공할 예정입니다. 지금은 에이전트의 `tools` 매개변수를 사용해 **도구 목록에 새로운 도구를 추가**하는 데 집중하세요.

예를 들어, 코드 첫 줄에서 불러온 `DuckDuckGoSearchTool`을 사용하거나, 코드 뒷부분에서 Hub에서 불러오는 `image_generation_tool`을 활용해볼 수 있습니다.

**도구를 추가하면 에이전트에 새로운 능력이 생깁니다**. 창의성을 발휘해 보세요!

완성된 "app.py" 코드:

```python
from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel, load_tool, tool
import datetime
import requests
import pytz
import yaml
from tools.final_answer import FinalAnswerTool

from Gradio_UI import GradioUI

# 아래는 아무 기능이 없는 도구의 예시입니다. 여러분의 창의력으로 멋진 것을 만들어보세요!
@tool
def my_custom_tool(arg1:str, arg2:int)-> str: # 반환 타입을 명시하는 것이 중요합니다
    # 도구 설명/인수 설명 형식은 유지하되, 도구 자체는 자유롭게 수정하세요
    """아직 아무 기능이 없는 도구입니다
    Args:
        arg1: 첫 번째 인수
        arg2: 두 번째 인수
    """
    return "어떤 마법을 만들어 보실 건가요?"

@tool
def get_current_time_in_timezone(timezone: str) -> str:
    """특정 시간대의 현재 시간을 알려주는 도구입니다.
    Args:
        timezone: 유효한 시간대를 나타내는 문자열(예: 'America/New_York').
    """
    try:
        # 시간대 객체 생성
        tz = pytz.timezone(timezone)
        # 해당 시간대의 현재 시간 가져오기
        local_time = datetime.datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S")
        return f"{timezone}의 현재 시간은 {local_time}입니다"
    except Exception as e:
        return f"'{timezone}' 시간대 정보를 가져오는 중 오류 발생: {str(e)}"


final_answer = FinalAnswerTool()
model = InferenceClientModel(
max_tokens=2096,
temperature=0.5,
model_id='Qwen/Qwen2.5-Coder-32B-Instruct',
custom_role_conversions=None,
)


# Hub에서 도구 불러오기
image_generation_tool = load_tool("agents-course/text-to-image", trust_remote_code=True)

with open("prompts.yaml", 'r') as stream:
    prompt_templates = yaml.safe_load(stream)

agent = CodeAgent(
    model=model,
    tools=[final_answer], # 여기에 도구들을 추가하세요 (final_answer는 제거하지 마세요)
    max_steps=6,
    verbosity_level=1,
    grammar=None,
    planning_interval=None,
    name=None,
    description=None,
    prompt_templates=prompt_templates
)


GradioUI(agent).launch()
```

여러분의 **목표**는 Space와 에이전트에 친숙해지는 것입니다.

현재 템플릿의 에이전트는 **아무런 도구도 사용하지 않고 있습니다. 미리 만들어진 도구들을 추가하거나 직접 새로운 도구를 만들어보세요!**

디스코드 채널 **#agents-course-showcase**에서 여러분이 만든 멋진 에이전트 결과물을 기다리고 있습니다!

---

축하합니다! 첫 번째 에이전트를 만드셨네요! 친구나 동료들과 자유롭게 공유해보세요.

첫 시도이니만큼 약간의 버그가 있거나 속도가 느릴 수 있는 건 매우 자연스러운 일입니다. 앞으로의 단원에서는 더 나은 에이전트를 만드는 방법을 배울 예정입니다.

가장 좋은 학습 방법은 직접 시도해보는 것입니다. 에이전트를 업데이트하거나, 더 많은 도구를 추가하거나, 다른 모델을 시험해보는 것을 망설이지 마세요.

다음 섹션에서는 최종 퀴즈를 풀고 수료증을 받게 됩니다!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/tutorial.mdx" />

### 액션: 에이전트가 환경과 상호작용할 수 있게 하기 [[actions-enabling-the-agent-to-engage-with-its-environment]]
https://huggingface.co/learn/agents-course/ko/unit1/actions.md

# 액션: 에이전트가 환경과 상호작용할 수 있게 하기 [[actions-enabling-the-agent-to-engage-with-its-environment]]

> [!TIP]
> 이 섹션에서는 AI 에이전트가 환경과 상호작용하기 위해 취하는 구체적인 단계를 살펴봅니다.
>
>  액션이 어떻게 표현되는지(JSON 또는 코드 사용), 중지 및 구문 분석 접근 방식의 중요성, 그리고 다양한 유형의 에이전트를 소개합니다.

액션은 **AI 에이전트가 환경과 상호작용하기 위해 취하는** 구체적인 단계입니다.

정보를 위해 웹을 검색하든 물리적 장치를 제어하든, 각 액션은 에이전트가 실행하는 의도적인 작업입니다.

예를 들어, 고객 서비스를 지원하는 에이전트는 고객 데이터를 검색하거나, 도움말 문서를 제공하거나, 문제를 인간 담당자에게 이관할 수 있습니다.

## 에이전트 액션의 유형 [[types-of-agent-actions]]

액션을 다르게 취하는 여러 유형의 에이전트가 있습니다:

| 에이전트 유형 | 설명 |
|--------------|------|
| JSON 에이전트 | 취할 액션이 JSON 형식으로 지정됩니다. |
| 코드 에이전트 | 에이전트가 외부에서 해석되는 코드 블록을 작성합니다. |
| 함수 호출 에이전트 | JSON 에이전트의 하위 카테고리로, 각 액션마다 새로운 메시지를 생성하도록 미세 조정되었습니다. |

액션 자체는 다양한 목적을 가질 수 있습니다:

| 액션 유형 | 설명 |
|----------|------|
| 정보 수집 | 웹 검색 수행, 데이터베이스 쿼리, 문서 검색 등 |
| 도구 사용 | API 호출, 계산 실행, 코드 실행 |
| 환경 상호작용 | 디지털 인터페이스 조작 또는 물리적 장치 제어 |
| 의사소통 | 채팅을 통한 사용자와의 상호작용 또는 다른 에이전트와의 협업 |

모든 형식의 에이전트(JSON, 코드, 함수 호출)에 있어 중요한 부분은 **액션이 완료되면 새로운 토큰 생성을 중지하는 능력**입니다. 이는 의도하지 않은 출력을 방지하고 에이전트의 응답이 명확하고 정확하도록 보장합니다.

LLM은 텍스트만 처리하며 이를 사용하여 취하고자 하는 액션과 도구에 제공할 매개변수를 설명합니다.

## 중지 및 구문 분석 접근 방식 [[the-stop-and-parse-approach]]

액션을 구현하는 핵심 방법 중 하나는 **중지 및 구문 분석 접근 방식**입니다. 이 방법은 에이전트의 출력이 구조화되고 예측 가능하도록 보장합니다:

1. **구조화된 형식으로 생성**:

에이전트는 의도한 액션을 명확하고 미리 정의된 형식(JSON 또는 코드)으로 출력합니다.

2. **추가 생성 중지**:

액션이 완료되면 **에이전트는 추가 토큰 생성을 중지**합니다. 이는 불필요하거나 오류가 있는 출력을 방지합니다.

3. **출력 구문 분석**:

외부 파서가 형식화된 액션을 읽고, 어떤 도구를 호출할지 결정하며, 필요한 매개변수를 추출합니다.

예를 들어, 날씨를 확인해야 하는 에이전트는 다음과 같이 출력할 수 있습니다:


```json
Thought: 서울의 현재 날씨를 확인해야 합니다.
Action :
{
  "action": "get_weather",
  "action_input": {"location": "Seoul"}
}
```
프레임워크는 호출할 함수의 이름과 적용할 인자를 쉽게 구문 분석할 수 있습니다.

이 명확하고 기계가 읽을 수 있는 형식은 오류를 최소화하고 외부 도구가 에이전트의 명령을 정확하게 처리할 수 있게 합니다.

참고: 함수 호출 에이전트는 각 액션을 구조화하여 지정된 함수가 올바른 인수와 함께 호출되도록 하는 비슷한 방식으로 작동합니다.
이러한 유형의 에이전트에 대해서는 향후 유닛에서 더 자세히 살펴볼 것입니다.

## 코드 에이전트 [[code-agents]]

대안적인 접근 방식은 *코드 에이전트*를 사용하는 것입니다.
핵심 아이디어는 **단순한 JSON 객체를 출력하는 대신**, 코드 에이전트가 **실행 가능한 코드 블록(일반적으로 Python과 같은 고수준 언어로 작성)**을 생성한다는 것입니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/code-vs-json-actions.png" alt="코드 에이전트" />

이 접근 방식은 여러 장점을 제공합니다:

- **표현력:** 코드는 루프, 조건문, 중첩 함수를 포함한 복잡한 로직을 자연스럽게 표현할 수 있어 JSON보다 더 큰 유연성을 제공합니다.
- **모듈성 및 재사용성:** 생성된 코드는 다양한 액션이나 작업에서 재사용할 수 있는 함수와 모듈을 포함할 수 있습니다.
- **향상된 디버깅 가능성:** 잘 정의된 프로그래밍 구문을 통해 코드 오류를 감지하고 수정하기가 더 쉬운 경우가 많습니다.
- **직접 통합:** 코드 에이전트는 외부 라이브러리 및 API와 직접 통합할 수 있어 데이터 처리나 실시간 의사 결정과 같은 복잡한 작업이 가능합니다.

예를 들어, 날씨 정보를 가져오는 임무를 맡은 코드 에이전트는 다음과 같은 Python 코드 조각을 생성할 수 있습니다:

```python
# 코드 에이전트 예시: 날씨 정보 검색
def get_weather(city):
    import requests
    api_url = f"https://api.weather.com/v1/location/{city}?apiKey=YOUR_API_KEY"
    response = requests.get(api_url)
    if response.status_code == 200:
        data = response.json()
        return data.get("weather", "날씨 정보가 없습니다")
    else:
        return "오류: 날씨 데이터를 가져올 수 없습니다."

# 함수 실행 및 최종 답변 준비
result = get_weather("Seoul")
final_answer = f"서울의 현재 날씨는: {result}"
print(final_answer)
```

이 예시에서 코드 에이전트는:

- **API 호출**을 통해 날씨 데이터를 검색하고,
- 응답을 처리하며,
- print() 함수를 사용하여 최종 답변을 출력합니다.

이 방법 **또한 중지 및 구문 분석 접근 방식**을 따르며, 코드 블록을 명확하게 구분하고 실행이 완료되었음을 신호합니다(여기서는 final_answer를 출력함으로써).

---

액션은 JSON, 코드 또는 함수 호출을 통해 명확하고 구조화된 작업을 실행함으로써 에이전트의 내부 추론과 실제 상호작용을 연결한다는 점을 배웠습니다.

이러한 의도적인 실행은 각 액션이 정확하고 중지 및 구문 분석 접근 방식을 통해 외부 처리가 가능하도록 보장합니다. 다음 섹션에서는 에이전트가 환경으로부터 피드백을 캡처하고 통합하는 방법을 알아보기 위해 관찰(Observations)에 대해 살펴볼 것입니다.

이후에는 **드디어 우리의 첫 번째 에이전트를 구축할 준비가 됩니다!**


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/actions.mdx" />

### 컨텐츠 목록
https://huggingface.co/learn/agents-course/ko/unit1/README.md

# 컨텐츠 목록

👉 <a href="https://hf.co/learn/agents-course/unit1/introduction">여기에서</a> Unit1을 접속하실 수 있습니다.

<!--
| Title | Description |
|-------|-------------|
| [Definition of an Agent](1_definition_of_an_agent.md) | General example of what agents can do without technical jargon. |
| [Explain LLMs](2_explain_llms.md) | Explanation of Large Language Models, including the family tree of models and suitable models for agents. |
| [Messages and Special Tokens](3_messages_and_special_tokens.md) | Explanation of messages, special tokens, and chat-template usage. |
| [Dummy Agent Library](4_dummy_agent_library.md) | Introduction to using a dummy agent library and serverless API. |
| [Tools](5_tools.md) | Overview of Pydantic for agent tools and other common tool formats. |
| [Agent Steps and Structure](6_agent_steps_and_structure.md) | Steps involved in an agent, including thoughts, actions, observations, and a comparison between code agents and JSON agents. |
| [Thoughts](7_thoughts.md) | Explanation of thoughts and the ReAct approach. |
| [Actions](8_actions.md) | Overview of actions and stop and parse approach. |
| [Observations](9_observations.md) | Explanation of observations and append result to reflect. |
| [Quizz](10_quizz.md) | Contains quizzes to test understanding of the concepts. |
| [Simple Use Case](11_simple_use_case.md) | Provides a simple use case exercise using datetime and a Python function as a tool. |
-->

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/README.md" />

### Unit 1 퀴즈 [[unit-1-quiz]]
https://huggingface.co/learn/agents-course/ko/unit1/final-quiz.md

# Unit 1 퀴즈 [[unit-1-quiz]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-unit1sub4DONE.jpg" alt="Unit 1 planning"/>

첫 번째 단원을 완료하신 것을 축하합니다! 지금까지 배운 핵심 개념들에 대한 이해도를 테스트해 보겠습니다.

퀴즈를 통과하면 다음 섹션으로 진행하여 수료증을 받을 수 있습니다.

행운을 빕니다!

## 퀴즈 [[quiz]]

여기 인터랙티브 퀴즈가 있습니다. 이 퀴즈는 Hugging Face Hub의 스페이스에서 호스팅됩니다. 이 단원에서 다룬 핵심 개념에 대한 이해도를 테스트하는 객관식 문제들이 제공됩니다. 퀴즈를 완료하면 점수와 정답 해설을 확인할 수 있습니다.

중요한 점: **통과 후 제출 버튼을 클릭하는 것을 잊지 마세요. 그렇지 않으면 시험 점수가 저장되지 않습니다!**

<iframe
    src="https://agents-course-unit-1-quiz.hf.space"
    frameborder="0"
    width="850"
    height="450"
></iframe>

퀴즈에 👉 [여기](https://huggingface.co/spaces/agents-course/unit_1_quiz)에서도 접속할 수 있습니다.

## 수료증 [[certificate]]

퀴즈를 성공적으로 통과했으니, **이제 수료증을 받을 수 있습니다 🎓**

퀴즈를 완료하면 이 단원의 수료증에 접근할 수 있게 됩니다. 이 수료증을 다운로드하고 공유하여 과정에서의 진행 상황을 보여줄 수 있습니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-unit1sub5DONE.jpg" alt="Unit 1 planning"/>

수료증을 받으면 LinkedIn 🧑‍💼에 추가하거나 X, Bluesky 등에서 공유할 수 있습니다. **@huggingface를 태그하시면 저희가 매우 자랑스러워하며 축하해 드리고 싶습니다!** 🤗

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/final-quiz.mdx" />

### 사고: AI 에이전트의 내부 추론과 Re-Act 방식 [[thought-internal-reasoning-and-the-re-act-approach]]
https://huggingface.co/learn/agents-course/ko/unit1/thoughts.md

# 사고: AI 에이전트의 내부 추론과 Re-Act 방식 [[thought-internal-reasoning-and-the-re-act-approach]]

> [!TIP]
> 이 섹션에서는 AI 에이전트의 내면—즉, 추론하고 계획하는 능력을 자세히 살펴봅니다. 에이전트가 내부 대화를 통해 정보를 분석하고, 복잡한 문제를 다루기 쉬운 단계로 나누며, 다음 행동을 결정하는 과정을 탐구합니다. 또한 'Re-Act' 방식이라는 프롬프팅 기법을 소개합니다. 이는 모델이 행동하기 전에 '단계적으로 생각'하도록 유도하는 방법입니다.

사고는 **에이전트가 작업을 해결하기 위해 내부적으로 추론하고 계획하는 과정**을 의미합니다.

이는 에이전트의 대규모 언어 모델(LLM)이 가진 **프롬프트에 제시된 정보를 분석하는 능력**을 활용하는 것입니다.

마치 에이전트의 머릿속 대화라고 생각하면 됩니다. 주어진 과제를 검토하고 어떻게 접근할지 전략을 세우는 과정이죠.

에이전트의 사고 과정은 현재 상황을 관찰하고 다음에 취해야 할 행동을 결정하는 역할을 합니다.

이를 통해 에이전트는 **복잡한 문제를 더 작고 다루기 쉬운 단계로 분해**하고, 이전 경험을 되돌아보며, 새로운 정보를 바탕으로 계획을 지속적으로 조정합니다.

다음은 일반적인 사고 유형의 예시입니다:

| 사고 유형 | 예시 |
|----------------|---------|
| 계획 수립 | "이 작업을 세 단계로 나눠야겠다: 1) 데이터 수집, 2) 트렌드 분석, 3) 보고서 작성" |
| 분석 | "오류 메시지를 보니, 문제는 데이터베이스 연결 설정과 관련이 있는 것 같다" |
| 의사 결정 | "사용자의 예산 제약을 고려하면, 중간 가격대 옵션을 추천하는 것이 좋겠다" |
| 문제 해결 | "이 코드를 최적화하려면, 먼저 어디가 병목인지 프로파일링해봐야 한다" |
| 기억 활용 | "사용자가 앞서 파이썬을 선호한다고 했으니, 파이썬 예제를 제공해야겠다" |
| 자기 성찰 | "이전 접근법이 효과적이지 않았으니, 다른 방식을 시도해봐야겠다" |
| 목표 설정 | "이 작업을 완료하려면, 먼저 성공 기준을 명확히 해야 한다" |
| 우선순위 결정 | "새 기능을 추가하기 전에 보안 취약점부터 해결하는 것이 옳다" |

> **참고:** 함수 호출에 최적화된 LLM의 경우, 사고 과정은 선택적으로 사용할 수 있습니다.
> *함수 호출에 익숙하지 않다면, 행동(Actions) 섹션에서 더 자세한 내용을 확인할 수 있습니다.*

## Re-Act 방식 [[the-re-act-approach]]

핵심 방법론 중 하나는 "추론"(Reasoning)과 "행동"(Acting)을 결합한 **ReAct 방식**입니다.

ReAct는 LLM이 다음 토큰을 생성하기 전에 "단계별로 생각해보자"라는 문구를 추가하는 간단한 프롬프팅 기법입니다.

모델에게 "단계별로 생각"하도록 지시하면, 바로 최종 해답을 내놓기보다 **계획을 세우는 방향**으로 토큰 생성이 유도됩니다. 이는 모델이 문제를 *하위 과제*로 **분해**하도록 장려하기 때문입니다.

이렇게 하면 모델이 각 단계를 더 상세히 고려할 수 있어, 일반적으로 최종 해답을 바로 생성하려 할 때보다 오류가 적게 발생합니다.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/ReAct.png" alt="ReAct"/>
<figcaption>(d)는 "단계별로 생각해보자"라는 프롬프트를 사용한 Re-Act 방식의 예시입니다
</figcaption>
</figure>

> [!TIP]
> 최근 추론 전략에 대한 관심이 크게 늘고 있습니다. Deepseek R1이나 OpenAI의 o1과 같은 모델들이 바로 이런 흐름을 반영합니다. 이 모델들은 "대답하기 전에 먼저 생각하도록" 특별히 미세 조정되었습니다.
>
> 이런 모델들은 특정 _사고_ 영역(`<think>`와 `</think>` 특수 토큰 사이에 포함)을 항상 생성하도록 훈련되었습니다. 이는 ReAct처럼 단순한 프롬프팅 기법이 아니라, 우리가 원하는 결과물의 수천 가지 예시를 분석한 후 이런 사고 영역을 생성하는 방법을 학습하는 훈련 방식입니다.

--- 
이제 사고 과정에 대해 더 잘 이해했으니, 프로세스의 두 번째 부분인 행동(Act)에 대해 더 자세히 살펴보겠습니다.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/thoughts.mdx" />

### 에이전트란? [[what-is-an-agent]]
https://huggingface.co/learn/agents-course/ko/unit1/what-are-agents.md

# 에이전트란? [[what-is-an-agent]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-no-check.jpg" alt="Unit 1 planning"/>

이 섹션이 끝날 때 쯤이면, 여러분들은 에이전트의 개념과 AI에서의 응용 사례들을 이해하실 수 있을 것입니다.

에이전트가 무엇인지, 한 예시를 들어 설명하겠습니다.

## 큰 그림 : 에이전트 알프레드 (Alfred) [[the-big-picture-alfred-the-agent]]

**에이전트** 알프레드를 만나보세요! 

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/this-is-alfred.jpg" alt="This is Alfred"/>

알프레드는 **명령을 받습니다.** : "알프레드, 커피 한잔 부탁해요."

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/coffee-please.jpg" alt="I would like a coffee"/>

알프레드는 **자연어를 이해**하므로, 우리의 요청을 빠르게 파악합니다.

주문을 수행하기 전에, Alfred는 **추론과 계획**을 통해 필요한 단계와 도구를 파악합니다:

1. 주방에 간다. 
2. 커피머신을 사용한다.
3. 커피를 내린다.
4. 커피를 가져온다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/reason-and-plan.jpg" alt="Reason and plan"/>

알프레드는 계획을 세운 후, **행동**을 해야 합니다. 알프레드는 세운 계획을 실행하기 위해, 알고 있는 **도구 목록에서 도구**를 사용할 수 있습니다.

이 경우, 커피를 만들기 위해 커피 머신을 사용합니다. 알프레드는 커피 머신을 작동시켜 커피를 내립니다.
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/make-coffee.jpg" alt="Make coffee"/>

마지막으로, Alfred는 신선하게 내린 커피를 우리에게 가져옵니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/bring-coffee.jpg" alt="Bring coffee"/>

이것이 바로 에이전트입니다: **추론, 계획, 환경과 상호작용하는 AI 모델**

우리는 이것을 에이전트라고 부르는데, 왜냐하면 _주체성_을 가지고 있기 때문입니다. 즉, 환경과 상호작용할 수 있는 능력을 가지고 있습니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/process.jpg" alt="Agent process"/>

## 좀 더 이론적인 부분을 살펴봅시다 [[lets-go-more-formal]]

전체 그림을 이해한 후, 이제 더 정확한 정의를 내려봅시다:

> 에이전트는 사용자가 정의한 목표를 달성하기 위해 환경과 상호작용하는 AI 모델을 이용하는 시스템입니다. 이 시스템은 추론, 계획, 실행을 결합하여 (종종 외부 도구를 통해)작업을 완료합니다.

에이전트는 두 가지 주요 부분으로 나눌 수 있습니다:

1. **두뇌 (AI 모델)**

이곳에서 모든 사고가 일어납니다. AI 모델은 **추론과 계획**을 처리합니다.
**상황에 맞게 어떤 행동**을 취할지 결정을 내립니다.

2. **몸 (기능과 도구)**

이 부분은 에이전트가 수행할 수 있는 **모든 작업**을 나타냅니다.

**가능한 행동의 범위**는 에이전트가 **어떤 도구**를 가지고 있는지에 달려 있습니다. 예를 들어, 인간은 날개가 없기 때문에 "날기" 행동을 할 수 없지만, "걷기", "달리기", "점프하기", "잡기"와 같은 **행동**은 수행할 수 있습니다.

## 에이전트에는 어떤 AI 모델을 사용하나요? [[what-type-of-ai-models-do-we-use-for-agents]]

에이전트에서 가장 일반적인 AI 모델은 **LLM (Large Language Model)**입니다. 이는 **텍스트**를 입력으로 받아 **텍스트**를 출력하는 모델입니다.

잘 알려진 예로는 **OpenAI의 GPT4, Meta의 LLaMA, Google의 Gemini** 등이 있습니다. 이러한 모델들은 방대한 텍스트 데이터로 학습되어 잘 일반화됩니다. LLM에 대해서는 [다음 섹션](what-are-llms)에서 더 배울 수 있습니다.

> [!TIP]
> 에이전트의 핵심 모델로 텍스트 외 다른 입력을 받는 모델을 사용할 수도 있습니다. 예를 들어, 이미지를 입력으로 이해할 수 있는 **비전 언어 모델 (VLM)**이 있습니다. 이번 섹션에서는 LLM에 집중하도록 하고, 이후 다른 모델들에 대해서도 다룰 것입니다.

## 이 환경에서 AI는 어떤 행동을 취하나요? [[how-does-an-ai-take-action-on-its-environment]]

LLMs는 뛰어난 모델이지만, **텍스트**만 생성할 수 있습니다. 

그런데, 사용자가 HuggingChat이나 ChatGPT같은 유명 채팅 애플리케이션에서 이미지 생성을 요청하면, 요청대로 이미지를 생성해 줍니다! 이것이 어떻게 가능 할까요?

그 이유는 HuggingChat, ChatGPT의 개발자들이 **도구(Tools) 기능**을 추가했기 때문입니다. 이 도구를 사용하면 LLM이 이미지를 생성할 수 있습니다.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/eiffel_brocolis.jpg" alt="Eiffel Brocolis"/>
<figcaption>The model used an Image Generation Tool to generate this image.
</figcaption>
</figure>

도구에 대해서는 [도구](tools) 섹션에서 더 깊게 배우도록 하겠습니다.

## 에이전트는 어떤 작업을 수행할 수 있나요? [[what-type-of-tasks-can-an-agent-do]]

에이전트는 **도구**를 통해 **행동**을 완수하도록 어떠한 작업도 수행 가능합니다. 

예를 들어, 나만의 개인 비서 역할을 하는 에이전트(Siri같은)를 내 컴퓨터에 심고, "오늘 회의를 연기해달라고 매니저에게 이메일을 보내줘"라고 요청하면, 이메일을 보내는 코드도 제공할 수 있습니다. 이렇게 하면 이메일을 보낼 때마다 에이전트가 사용할 수 있는 새로운 도구가 됩니다. 이를 Python으로 작성하게 되면:

```python
def send_message_to(recipient, message):
    """수신자에게 이메일을 보내는 데 유용한 함수"""
    ...
```

LLM은 이 도구를 실행할 코드를 생성하여 요청된 작업을 완수할 수 있습니다.

```python
send_message_to("Manager", "오늘 미팅을 연기할 수 있을 까요?")
```

**도구 설계**는 에이전트의 성능에 큰 영향을 미칩니다. 일부 작업은 매우 구체적인 도구를 필요로 할 수 있으며, 다른 작업은 "웹 검색"과 같은 일반적인 도구로 해결할 수 있습니다.

> **행동(Action)**과 **도구(Tools)**는 다릅니다. 예를 들어, 하나의 행동에서 여러가지 도구를 사용할 수 있습니다.

에이전트가 환경과 상호작용할 수 있게 한다는 것은 **기업과 개인들이 실제로 사용할** 수 있도록 하는 것을 의미합니다.

### 예시 1: 개인 가상 비서 [[example-1-personal-virtual-assistants]]

Siri, Alexa, Google Assistant와 같은 가상 비서는 사용자를 대신해서 디지털 환경에서 에이전트로서 작동합니다.

이들은 사용자 쿼리를 처리하고, 문맥을 분석하며, 데이터베이스에서 정보를 검색하고, 응답을 제공하거나 작업을 시작합니다 (예: 알림 설정, 메시지 전송, 스마트 디바이스 제어 등).

### 예시 2: 고객 서비스 챗봇 [[example-2-customer-service-chatbots]]

많은 기업들이 고객과 자연어로 소통 가능한 챗봇을 에이전트로 배포하고 있습니다.

이 에이전트들은 질문에 답하거나, 문제 해결 단계를 안내하거나, 내부 데이터베이스에서 이슈를 열거나, 심지어 거래도 할 수 있습니다.

그들의 목표는 사용자 만족도를 높이거나, 대기 시간을 줄이거나, 판매 전환율을 높이는 것 등입니다. 고객과 직접 상호작용하고, 대화를 통해 학습하며, 시간이 지남에 따라 응답을 조정하는데, 이러한 에이전트들은 에이전트의 핵심 원칙을 보여줍니다.

### 예시 3: 게임 속 AI NPC 캐릭터 [[example-3-ai-non-playable-character-in-a-video-game]]

LLM 기반의 AI 에이전트는 비 플레이어 캐릭터(NPC)를 더 역동적이고 예측 불가능하게 만들 수 있습니다.

정해진 행동 패턴을 따르기보다는, **문맥에 맞게 답변하고, 플레이어와의 상호작용에 반응하며**, 더 세련된 대화를 생성합니다. 이 유연성은 플레이어의 행동에 따라 발전하는 생동감 있는 캐릭터를 만들어냅니다.

---

요약하자면, 에이전트는 **AI 모델 (주로 LLM)**을 핵심 추론 엔진으로 사용하여:

- **자연어 이해** : 인간의 지시를 의미 있게 해석하고 반응합니다.

- **추론하고 계획**: 정보를 분석하고, 결정을 내리며, 문제를 해결하기 위한 전략을 세웁니다.

- **환경과 상호작용**: 정보를 수집하고, 행동을 취하며, 그 결과를 관찰합니다.


이제 여러분은 에이전트에 대해 확실히 배웠으니, 짧은 퀴즈로 배운 내용을 점검한 후, “에이전트의 두뇌”인 [LLM](what-are-llms)에 대해 더 알아보도록 합시다!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/what-are-agents.mdx" />

### 사고-행동-관찰 주기를 통해 AI 에이전트 이해하기 [[understanding-ai-agents-through-the-thought-action-observation-cycle]]
https://huggingface.co/learn/agents-course/ko/unit1/agent-steps-and-structure.md

# 사고-행동-관찰 주기를 통해 AI 에이전트 이해하기 [[understanding-ai-agents-through-the-thought-action-observation-cycle]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-3.jpg" alt="Unit 1 planning"/>

이전 섹션에서 우리는 다음 내용을 배웠습니다:

- **도구가 시스템 프롬프트에서 에이전트에 어떻게 제공되는지**.
- **AI 에이전트가 '추론'하고, 계획을 세우며, 환경과 상호작용하는 시스템이라는 것**.

이번 섹션에서는 **AI 에이전트의 전체 워크플로우, 사고(Thought)-행동(Action)-관찰(Observation) 주기**에 대해 살펴보겠습니다.

그리고 각 단계에 대해 더 깊이 탐구해 보겠습니다.


## 핵심 구성 요소 [[the-core-components]]

에이전트는 **사고(Thought) → 행동(Act) → 관찰(Observe)**의 연속적인 주기로 작동합니다.

이 과정의 각 단계를 자세히 살펴보겠습니다:

1. **사고(Thought)**: 에이전트의 LLM부분이 다음에 수행할 단계를 결정합니다.
2. **행동(Action):** 에이전트가 도구를 호출하고 필요한 인자를 전달하여 특정 행동을 수행합니다.
3. **관찰(Observation):** 모델이 도구의 응답을 검토합니다.

## 사고(Thought)-행동(Action)-관찰(Observation) 주기 [[the-thought-action-observation-cycle]]


이 세 가지 구성 요소는 반복루프 내에서 함께 작동합니다. 프로그래밍에 비유하자면, 에이전트는 **while 루프**를 사용합니다. 즉, 에이전트의 목표가 달성될 때까지 루프가 계속 실행됩니다.

이를 시각적으로 표현하면 다음과 같습니다:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AgentCycle.gif" alt="Think, Act, Observe cycle"/>

많은 에이전트 프레임워크에서는 **규칙과 가이드라인이 시스템 프롬프트에 직접 내장**되어 있어, 각 주기가 정의된 논리에 따라 실행됩니다.

이를 단순화한 시스템 프롬프트 예시는 다음과 같습니다:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/system_prompt_cycle.png" alt="Think, Act, Observe cycle"/>

이 시스템 메시지에서 우리는 다음 요소들을 정의했습니다:

- *에이전트의 행동 방식*
- *에이전트가 접근할 수 있는 도구들* (이전 섹션에서 설명한 내용)
- *사고(Thought)-행동(Action)-관찰(Observation) 주기* 를 LLM 지침에 내장

이제, 각 단계를 더 깊이 탐구하기 전에, 간단한 예제를 통해 이 과정이 어떻게 작동하는지 살펴보겠습니다.

## 날씨 에이전트 알프레드(Alfred) [[alfred-the-weather-agent]]

우리는 날씨 정보를 제공하는 에이전트 Alfred를 만들었습니다.

사용자가 Alfred에게 다음과 같이 질문합니다: “오늘 뉴욕 날씨 어때?”

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent.jpg" alt="Alfred Agent"/>

Alfred의 역할은 날씨 API 도구를 사용하여 이 질문에 답하는 것입니다.

다음과 같이 사고-행동-관찰 주기가 진행됩니다:


### 사고(Thought) [[thought]]

**내부 사고 과정(Internal Reasoning):**

질문을 받은 후, Alfred의 내부에서 이루어지는 대화는 다음과 같을 수 있습니다 :

*"사용자는 뉴욕의 현재 날씨 정보를 원하고 있어. 내가 사용할 수 있는 날씨 API 도구가 있으니, 먼저 이 도구를 호출해서 최신 정보를 가져와야 해."*

이 단계에서 에이전트는 문제를 단계별로 나눕니다 : 첫 번째 단계는 필요한 데이터를 수집하는 것입니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-1.jpg" alt="Alfred Agent"/>

### 행동(Action) [[action]]

**도구 사용:**

Alfred는 추론과 `get_weather` 도구를 알고 있다는 사실에 기반해, 날씨 API 도구를 호출하기 위한 JSON 형식의 명령을 준비합니다.
예를 들어, 첫 번째 액션은 다음과 같을 수 있습니다:

사고(Thought): 뉴욕의 현재 날씨를 확인해야 해.

 ```
    {
      "action": "get_weather",
      "action_input": {
        "location": "New York"
      }
    }
 ```

여기서, action은 어떤 도구를 호출할지 지정하고 (get_weather) 필요한 입력값(예: "location": "New York")을 설정합니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-2.jpg" alt="Alfred Agent"/>

### 관찰(Observation) [[observation]]

**환경으로부터의 피드백:**

도구 호출 후, Alfred는 관찰 결과를 받습니다. 예를 들어, API에서 반환된 날씨 데이터가 다음과 같을 수 있습니다:

*"뉴욕의 현재 날씨: 부분적으로 흐림, 15°C, 습도 60%"*

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-3.jpg" alt="Alfred Agent"/>

이러한 관찰 결과는 추가 컨텍스트로 프롬프트에 더해집니다. 즉, 관찰은 현실 세계에서의 피드백 역할을 하며, 에이전트가 실행한 행동이 성공했는지 확인하고 필요한 정보를 제공합니다.

### 업데이트된 사고(thought)과정 [[updated-thought]]

**성찰(Reflecting):**

관찰 데이터를 얻은 후, Alfred는 내부 사고 과정을 업데이트합니다:

*"이제 뉴욕의 날씨 데이터를 확보했으니, 사용자에게 답변을 정리할 수 있어."*

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-4.jpg" alt="Alfred Agent"/>


### 최종 행동(Action) [[final-action]]

Alfred는 이제 사용자에게 전달할 최종 응답을 우리가 지정해준 형식에 맞게 생성합니다:

사고: 이제 날씨 데이터를 확보했어. 뉴욕의 현재 날씨는 부분적으로 흐리고, 기온은 15°C, 습도는 60%야.

최종 답변 : 뉴욕의 현재 날씨는 부분적으로 흐리고, 기온은 15°C, 습도는 60%입니다.

이 최종 행동을 통해 답변을 사용자에게 전달하고, 루프를 종료합니다.


<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-5.jpg" alt="Alfred Agent"/>


이 예제를 통해 배운 것:

- **에이전트는 목표가 달성될 때까지 반복적으로 루프를 실행한다:**
    
**Alfred의 과정은 순환적입니다. 사고(thought)에서 시작해, 도구를 호출함으로 행동(Action)을 취하고, 마지막으로 결과를 관찰(Observation)합니다. 만약 관찰 단계에서 오류가 발생하거나 데이터가 불완전하면, Alfred는 루프를 다시 실행하여 문제를 해결합니다.
    
- **도구(Tool) 통합:**

에이전트는 **정적인 지식을 넘어, 외부 도구(날씨 API같은)를 호출하여 실시간 데이터**를 가져올 수 있습니다. 이것은 AI 에이전트의 핵심 기능 중 하나입니다.

- **동적 적응(Dynamic Adaptation):**

에이전트는 각 주기를 거치면서, 새로운 정보(관찰)를 반영하여 사고 과정을 조정합니다. 이를 통해 최종 답변이 더 정확하고 신뢰할 수 있도록 만듭니다.
    
이 예제는 우리가 다음 섹션에서 다룰 **ReAct(강화학습-Reinforcement Learning + 행동-Action) 주기**의 핵심 개념을 보여줍니다:
**사고(Thought), 행동(Action), 관찰(Observation)의 상호작용을 통해 AI 에이전트가 복잡한 문제를 점진적으로 해결**할 수 있도록 합니다.

이러한 원칙을 이해하고 적용함으로써, 에이전트를 설계할 때 단순히 작업을 추론하는 것뿐만 아니라 **외부 도구를 효과적으로 활용하여 작업을 완료**할 수 있도록 만들 수 있습니다. 또한, 환경에서 받은 피드백을 바탕으로 지속적으로 출력을 개선해나갑니다.

---

이제 Thought, Action, Observation을 개별 단계별로 더 깊이 탐구해 보겠습니다.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/agent-steps-and-structure.mdx" />

### 셀프 체크! (업데이트됨) [[quiz2]]
https://huggingface.co/learn/agents-course/ko/unit1/quiz2.md

# 셀프 체크! (업데이트됨) [[quiz2]] 


뭐라고요?! 또 퀴즈라고요? 우리도 알아요... 😅 하지만 걱정 마세요! 이 퀴즈는 **방금 배운 핵심 개념을 확실히 이해**하는 데 도움을 주기 위해 준비되었습니다.

이번 퀴즈에서는 대규모 언어 모델(LLM), 메시지 시스템, 도구(tool) 등 AI 에이전트를 이해하고 구축하는 데 필수적인 요소들을 다룹니다.

### Q1:  AI 도구(tool)를 가장 잘 설명하는 것은 무엇인가요? [[q1-which-of-the-following-best-describes-an-ai-tool]]

<Question
choices={[
{
text: "텍스트 응답만 생성하는 프로세스",
explain: "",
},
{
text: " 에이전트가 특정 작업을 수행하고 외부 환경과 상호작용할 수 있도록 하는 실행 가능한 프로세스 또는 외부 API",
explain: "도구는 에이전트가 특정 작업을 수행하고 외부 환경과 상호작용할 수 있도록 해주는 기능입니다.",
correct: true
},
{
text: "에이전트의 대화를 저장하는 기능",
explain: "",
}
]}
/>

---

### Q2: AI 에이전트는 환경에서 "행동(act)"하기 위해 도구를 어떻게 활용하나요? [[q2-how-do-ai-agents-use-tools-as-a-form-of-acting-in-an-environment]]

<Question
choices={[
{
text: "사용자의 명령을 수동적으로 기다린다",
explain: "",
},
{
text: "미리 프로그래밍된 응답만 사용한다",
explain: "",
},
{
text: "LLM이 적절할 때 도구 호출 코드를 생성하도록 요청하고, 모델을 대신하여 도구를 실행한다",
explain: "에이전트는 도구를 호출하고, 이를 통해 얻은 정보를 바탕으로 계획을 세우거나 재조정할 수 있습니다.",
correct: true
}
]}
/>

---

### Q3: 대규모 언어 모델(LLM)이란? [[q3-what-is-a-large-language-model-llm]]

<Question
choices={[
{
text: "사전 정의된 답변을 제공하는 단순한 챗봇",
explain: "",
},
{
text: "방대한 텍스트 데이터로 학습된 딥러닝 모델로, 인간과 유사한 언어를 이해하고 생성할 수 있다",
explain: "",
correct: true
},
{
text: "엄격하게 사전 정의된 명령만 따르는 규칙 기반 AI",
explain: "",
}
]}
/>

---

### Q4: LLM에서 특수 토큰(special tokens)의 역할을 가장 잘 설명하는 것은 무엇인가요? [[q4-which-of-the-following-best-describes-the-role-of-special-tokens-in-llms]]

<Question
choices={[
{
text: "텍스트 생성 품질을 향상시키기 위해 모델의 어휘에 추가된 단어들이다",
explain: "",
},
{
text: "문장 종료(EOS) 표시나 챗봇 모델에서 서로 다른 메시지 역할을 구분하는 기능을 한다",
explain: "",
correct: true
},
{
text: "응답의 다양성을 높이기 위해 무작위로 삽입되는 토큰이다",
explain: "",
}
]}
/>

---

### Q5: AI 챗봇 모델은 사용자 메시지를 내부적으로 어떻게 처리하나요? [[q5-how-do-ai-chat-models-process-user-messages-internally]]

<Question
choices={[
{
text: "사용자 메시지를 변형 없이 구조화된 명령으로 직접 해석한다",
explain: "",
},
{
text: "시스템 메시지, 사용자 메시지, 어시스턴트 메시지를 구조화된 하나의 프롬프트로 변환하여 처리한다",
explain: "",
correct: true
},
{
text: "이전 대화를 기반으로 무작위로 응답을 생성한다",
explain: "",
}
]}
/>

---


이해되셨나요? 좋습니다! 이제 **전체 에이전트의 흐름을 살펴보고, 직접 AI 에이전트를 만들어 봅시다!**


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/quiz2.mdx" />

### Q1: 에이전트(Agent)란? [[q1-what-is-an-agent]]
https://huggingface.co/learn/agents-course/ko/unit1/quiz1.md

### Q1: 에이전트(Agent)란? [[q1-what-is-an-agent]]
다음 중 AI 에이전트를 가장 잘 설명한 것은 무엇인가요?

<Question
choices={[
{
text: "정적인 텍스트만 처리하고, 환경과 동적으로 상호작용하거나 의미 있는 행동을 수행하는 메커니즘이 없는 시스템.",
explain: "에이전트는 행동을 취하고 환경과 상호작용할 수 있어야 합니다.",
},
{
text: "추론하고 계획을 세우며 도구를 활용하여 환경과 상호작용하여 특정 목표를 달성하는 AI 모델.",
explain: "이 정의는 에이전트의 핵심 특징을 정확하게 설명합니다.",
correct: true
},
{
text: "사용자의 질문에 답변할 수는 있지만, 외부 시스템과 상호작용하거나 행동을 수행할 수 없는 대화형 AI.",
explain: "이러한 챗봇은 행동을 수행하는 기능이 없어 에이전트와 다릅니다.",
},
{
text: "사용자와 적극적으로 상호작용하거나 작업을 수행할 능력 없이 정적인 정보를 제공하는 온라인 저장소.",
explain: "에이전트는 단순히 정보를 제공하는 것이 아니라 환경과 적극적으로 상호작용합니다.",
}
]}
/>

---

### Q2: What is the Role of Planning in an Agent? 에이전트에서 계획(Planning)이 하는 역할은?
에이전트는 행동을 취하기 전에 왜 계획을 세워야 할까요?

<Question
choices={[
{
text: "주로 과거의 상호작용을 저장하거나 기억하는 역할을 하기 위해서이다.",
explain: "계획은 과거 정보를 저장하는 것이 아니라, 미래의 행동을 결정하는 과정입니다.",
},
{
text: "사용자의 요청을 충족시키기 위해 실행할 행동의 순서를 정하고, 적절한 도구를 선택하기 위해서이다.",
explain: "계획을 통해 에이전트는 최적의 단계와 도구를 결정할 수 있습니다.",
correct: true
},
{
text: "명확한 전략이나 목표 없이 무작위로 행동을 수행하기 위해서이다.",
explain: "계획을 세우는 것은 에이전트의 행동이 무작위적이지 않고 의도적이게 하기 위해서 입니다.",
},
{
text: "단순히 텍스트를 변환하거나 번역하는 과정일 뿐, 구체적인 행동 계획이나 전략적 사고와는 관련이 없다.",
explain: "계획은 행동을 구조화하는 과정이며, 단순한 텍스트 변환과는 다릅니다",
}
]}
/>

---

### Q3: 도구(Tools)는 에이전트의 기능을 어떻게 향상시키는가?
도구는 왜 에이전트에게 필수적인 요소일까요?

<Question
choices={[
{
text: "도구는 실질적인 역할을 하지 않으며, 기본적인 텍스트 생성 기능 이상의 행동을 수행하는 데 기여하지 않는다.",
explain: "도구는 에이전트가 단순한 텍스트 생성 이상의 행동을 수행할 수 있도록 확장해 줍니다.",
},
{
text: "도구는 에이전트가 커피를 만들거나 이미지를 생성하는 등, 텍스트 생성 모델이 기본적으로 수행할 수 없는 작업을 실행할 수 있도록 해준다.",
explain: "도구를 활용하면 에이전트가 현실 세계와 상호작용하며 작업을 완수할 수 있습니다.",
correct: true
},
{
text: "도구는 메모리 저장을 위한 용도로만 사용되며, 작업을 수행하거나 상호작용 성능을 향상하는 기능은 없다.",
explain: "도구는 데이터를 저장하는 것이 아니라, 행동을 수행하는 데 주로 사용됩니다.",
},
{
text: "도구는 에이전트가 텍스트 생성만 가능하도록 제한하여, 더 넓은 범위의 상호작용을 수행하지 못하게 만든다.",
explain: "반대로, 도구는 에이전트가 텍스트 기반 응답을 넘어 더 다양한 행동을 수행할 수 있도록 합니다.",
}
]}
/>

---

### Q4: 행동(Actions)과 도구(Tools)의 차이점은?
행동과 도구의 핵심적인 차이는 무엇인가요?

<Question
choices={[
{
text: "행동은 에이전트가 취하는 단계이며, 도구는 해당 행동을 수행하기 위해 사용할 수 있는 외부 리소스이다.",
explain: "행동은 더 높은 수준의 목표이며, 도구는 이를 실행하는 데 필요한 구체적인 기능입니다.",
correct: true
},
{
text: "행동과 도구는 완전히 동일한 개념이며, 상호 교환적으로 사용할 수 있다.",
explain: "행동은 목표나 작업을 의미하며, 도구는 이를 달성하기 위해 사용하는 수단입니다.",
},
{
text: "도구는 광범위한 기능을 수행하는 유틸리티이며, 행동은 물리적 상호작용에만 국한된다.",
explain: "행동은 디지털 및 물리적 작업을 모두 포함할 수 있습니다.",
},
{
text: "행동은 LLM을 통해 결정 및 실행해야 하지만, 도구는 이러한 의존성 없이 독립적으로 작동한다.",
explain: "LLM은 행동을 결정하는 데 도움을 주지만, 행동 자체가 반드시 LLM에 의존하는 것은 아닙니다.",
}
]}
/>

---

### Q5: LLM은 에이전트에서 어떤 역할을 하는가?

LLM는 에이전트의 기능에 어떻게 기여할까요?

<Question
choices={[
{
text: "LLM은 단순히 정보를 저장하는 수동적인 저장소 역할을 하며, 입력을 능동적으로 처리하거나 동적인 응답을 생성할 수 없다.",
explain: "LLM은 정보를 단순 저장하는 것이 아니라, 입력을 처리하고 응답을 생성하는 능동적인 역할을 합니다.",
},
{
text: "LLM은 에이전트의 '두뇌' 역할을 하며, 텍스트 입력을 처리하고 명령을 이해하여 행동을 계획하는 기능을 한다.",
explain: "LLM은 에이전트가 명령을 해석하고 계획을 수립하는 데 중요한 역할을 합니다.",
correct: true
},
{
text: "LLM은 이미지 처리에만 사용된다고 잘못 알려져 있으며, 실제로는 텍스트를 생성하고 처리하는 것이 주된 역할이다.",
explain: "LLM은 주로 텍스트를 다루지만, 경우에 따라 멀티모달 입력과도 상호작용할 수 있습니다.",
},
{
text: "LLM은 AI 에이전트의 운영과 전혀 관련이 없으며, 실용적인 적용에서 불필요한 요소이다.",
explain: "LLM은 현대 AI 에이전트의 핵심 구성 요소입니다.",
}
]}
/>

---

### Q6: 다음 중 AI 에이전트의 실제 사례로 가장 적절한 것은?
다음 예시 중 실제 AI 에이전트의 작동 방식과 가장 유사한 것은 무엇인가요?

<Question
choices={[
{
text: "웹사이트에서 고정된 정보를 제공하며, 동적 응답 기능이 없는 정적인 FAQ 페이지.",
explain: "정적인 FAQ 페이지는 사용자와 동적으로 상호작용하거나 행동을 수행하지 않습니다.",
},
{
text: "음성 명령을 이해하고, 이를 기반으로 알람 설정이나 메시지 전송 같은 작업을 수행하는 Siri 또는 Alexa 같은 가상 비서.",
explain: "이 예시는 추론, 계획, 환경과의 상호작용을 포함하고 있습니다.",
correct: true
},
{
text: "사칙연산을 수행하지만, 추론이나 계획 기능 없이 고정된 규칙에 따라 작동하는 단순 계산기",
explain: "정해진 규칙을 따르는 계산기는, 추론이나 계획 없이 작동하기 때문에 에이전트가 아닙니다.",
},
{
text: "미리 정해진 대사에 따라 반응하는 비디오 게임 NPC로, 추론, 계획, 도구 활용 기능이 없는 경우.",
explain: "NPC가 추론, 계획, 도구 활용 기능이 없다면 AI 에이전트라고 보기 어렵습니다.",
}
]}
/>

---

퀴즈 완료를 축하합니다! 🥳 If you need to review any elements, take the time to revisit the chapter to reinforce your knowledge before diving deeper into the "Agent's brain": LLMs.
본격적으로 "에이전트의 두뇌"인 LLM에 대해 학습하기 이전에 배운 내용을 다시 복습하고 싶다면, 해당 챕터를 다시 확인해 보세요. 🚀


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/quiz1.mdx" />

### 결론 [[conclusion]]
https://huggingface.co/learn/agents-course/ko/unit1/conclusion.md

# 결론 [[conclusion]]

축하합니다! 첫 번째 유닛을 완료하셨네요 🥳

이제 **에이전트의 기본 개념을 마스터**하고 첫 AI 에이전트를 만드셨습니다!

**아직 일부 요소가 혼란스럽게 느껴지는 것은 정상**입니다. 에이전트는 복잡한 주제이며, 모든 것을 이해하는 데 시간이 걸리는 것이 일반적입니다.

계속 진행하기 전에 **배운 내용을 제대로 이해하는 시간을 가지세요**. 재미있는 부분으로 넘어가기 전에 이러한 요소들을 숙달하고 탄탄한 기초를 다지는 것이 중요합니다.

퀴즈 테스트를 통과하셨다면, 인증서를 받는 것도 잊지 마세요 🎓 👉 [여기를 클릭하세요](https://huggingface.co/spaces/agents-course/unit1-certification-app)

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/certificate-example.jpg" alt="Certificate Example"/>

다음 (보너스) 유닛에서는 **함수 호출을 수행할 수 있도록 에이전트를 미세 조정하는 방법(즉, 사용자 프롬프트에 기반하여 도구를 호출할 수 있게 하는 방법)**을 배우게 됩니다.

마지막으로, **여러분이 이 코스에 대해 어떻게 생각하시는지, 그리고 어떻게 개선할 수 있는지 듣고 싶습니다**. 피드백이 있으시면 👉 [이 양식을 작성해 주세요](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)

### 계속 배우고, 멋진 여정 되세요 🤗

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/conclusion.mdx" />

### 에이전트 소개 [[introduction-to-agents]]
https://huggingface.co/learn/agents-course/ko/unit1/introduction.md

# 에이전트 소개 [[introduction-to-agents]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/thumbnail.jpg" alt="Thumbnail"/>

첫 번째 단원에 오신 것을 환영합니다! 이번 단원에서 여러분을 **AI 에이전트의 기초**를 탄탄히 다질 것이며, 다룰 주요 내용은 다음과 같습니다 :

- **에이전트 이해하기**  
  - 에이전트란 무엇이며, 어떻게 작동하는가?
  - 에이전트는 어떻게 추론과 계획을 통해 의사 결정을 내리는가?

- **에이전트 내 LLM(대형 언어 모델)의 역할**  
  - LLM이 에이전트의 "두뇌" 역할을 하는 방식
  - LLM이 메시지 시스템을 통해 대화를 구조화하는 방법.

- **도구(Tool)와 행동(Action)**  
  - 에이전트가 외부 도구를 활용하여 환경과 상호작용하는 방식
  - 에이전트에 도구를 구축하고 통합하는 방법

- **에이전트 워크플로우:** 
  - *생각(Think)* → *행동(Act)* → *관찰(Observe)*.

After exploring these topics, **you’ll build your first Agent** using `smolagents`! 
이 개념들을 살펴본 후, 여러분은 `smolagents`를 사용하여 **첫 번째 에이전트**를 직접 구현해 볼 것입니다!
 
Alfred라는 에이전트를 통해, 배운 개념들을 적용할 수 있는 간단한 작업 수행 방법을 배울 것입니다.

또한 **Hugging Face Spaces에 여러분이 만든 에이전트를 게시하는 방법**도 배워, 동료들과 친구들에게 공유할 수 있습니다.

마지막으로, 이 단원의 끝에서 퀴즈를 통과하게 되면 **🎓 Certificate of Fundamentals of Agents** 인증서를 획득할 수 있습니다!

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/certificate-example.jpg" alt="Certificate Example"/>

이 단원은 **에이전트 학습의 필수 시작점**으로, 이후 더 고급 개념을 배우기 위한 기초를 다집니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-no-check.jpg" alt="Unit 1 planning"/>

단원의 내용이 많으니, **천천히** 학습하며 필요할 때 다시 돌아와 복습하세요!

준비되셨나요? 함께 시작해 봅시다! 🚀


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/introduction.mdx" />

### 도구(Tool)란? [[what-are-tools]]
https://huggingface.co/learn/agents-course/ko/unit1/tools.md

# 도구(Tool)란? [[what-are-tools]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-2.jpg" alt="Unit 1 planning"/>

AI 에이전트(AI Agents)의 핵심 요소 중 하나는 **행동(Actions)**을 수행할 수 있는 능력입니다. 이러한 행동은 **도구(Tools)**를 사용하여 이루어집니다.

이번 섹션에서는 도구란 무엇이고, 어떻게 효과적으로 설계하는지, 시스템 메시지를 통해 에이전트에 통합하는 방법을 학습합니다.

에이전트에게 적절한 도구를 제공하고, 해당 도구의 동작 방식을 명확히 설명하면, AI의 수행 능력을 극적으로 향상시킬 수 있습니다. 함께 살펴보겠습니다!


## AI 도구란?[[what-are-ai-tools]]

**도구**란 LLM에 제공하는 함수라고 할 수 있습니다. 이 함수는 **명확한 목적을** 수행합니다.

다음은 AI 에이전트에서 일반적으로 사용되는 도구의 예시입니다:

| 도구            | 설명                                                   |
|----------------|---------------------------------------------------------------|
| 웹 검색 (Web Search)     | 인터넷에서 최신 정보를 검색하여 가져옵니다. |
| 이미지 생성 (Image generation) | 주어진 설명을 기반으로 이미지를 생성합니다.                  |
| 정보 검색 (Retrieval)      | 외부 데이터 소스에서 정보를 검색하여 제공합니다.                |
| API 인터페이스  | 외부 API (GitHub, YouTube, Spotify 등)와 상호작용합니다. |

이러한 예시는 일부일 뿐이며, 사실상 어떠한 용도를 위한 도구든지 생성할 수 있습니다!

좋은 도구는 **LLM의 능력을 보완하는** 역할을 수행합니다. 

예를 들어, 계산이 필요한 경우, **계산기 도구**를 제공하면 모델 자체의 계산 능력보다 훨씬 정확한 결과를 얻을 수 있습니다.

또한, **LLM은 학습 데이터에 기반해 프롬프트의 다음 단어를 예측**하므로, 사실상 훈련 이전 정보만 알고 있는 상태입니다. 따라서, 에이전트가 최신 데이터를 필요로 하는 경우 적절한 도구를 제공해야 합니다.

예를 들어, 검색 도구 없이 LLM에 직접적으로 오늘의 날씨에 대해 묻는다면, LLM은 임의로 날씨 정보를 생성(환각, hallucination)할 가능성이 높습니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/weather.jpg" alt="Weather"/>

- 도구는 다음을 포함해야 합니다:

  - 함수가 **수행하는 기능에 대한 설명**
  - *호출 가능한 함수(Callable, 실행 가능한 동작)*
  - *인자(Arguments)* 명시
  - (선택 사항) 출력 데이터(Outputs) 명시
  
## 도구는 어떻게 작동하는가? [[how-do-tools-work]]

LLM은 본질적으로 텍스트 입력을 받아 텍스트 출력을 생성할 수 있을 뿐, 스스로 도구를 호출할 수는 없습니다.  
따라서 _에이전트(Agent)에 도구를 제공한다는 것_은 LLM에게 **도구의 존재를 가르치고, 필요할 때 해당 도구를 호출하는 텍스트를 생성**하도록 유도하는 것을 의미합니다.
예를 들어, 특정 위치의 날씨를 조회할 수 있는 도구를 제공한 후, LLM에게 파리의 날씨를 묻는다면, LLM은 해당 질문이 "날씨" 도구를 사용할 적절한 상황임을 인식합니다. 그러면 LLM은 해당 도구를 호출하도록 코드 형태의 _텍스트_를 생성합니다.

**에이전트(Agent)**는 LLM의 출력을 파싱해 도구 호출이 필요한지를 파악하고, LLM을 대신하여 해당 도구를 실행하는 역할을 담당합니다.
이후 도구에서 반환된 결과를 다시 LLM에 전달하면, LLM은 이를 바탕으로 사용자에게 제공할 최종 응답을 생성합니다.


도구 호출의 출력은 대화 중 하나의 메시지로 간주됩니다. 일반적으로 이러한 도구 호출 과정은 사용자에게 직접 노출되지 않습니다:
에이전트는 대화를 조회한 후, 도구를 실행하고, 결과(출력)를 얻고, 이 결과를 새로운 대화 메시지로 추가한 뒤, 업데이트된 대화를 다시 LLM에게 전달합니다.
사용자의 관점에서는 마치 LLM이 직접 도구를 사용한 것처럼 보이지만, 실제로는 **에이전트(Agent)**가 이를 수행한 것입니다.

이 과정에 대한 자세한 내용은 이후 세션에서 더 깊이 다룰 예정입니다.

## LLM에게 도구를 제공하는 방법 [[how-do-we-give-tools-to-an-llm]]

전체 과정은 복잡할 수 있지만, 기본적으로 **시스템 프롬프트(system prompt)**를 사용하여 LLM에게 사용 가능한 도구들의 설명을 텍스트 형태로 제공하면 됩니다:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/Agent_system_prompt.png" alt="System prompt for tools"/>

도구를 효과적으로 활용하려면 이 두 가지를 명확하게 LLM에게 전달해야 합니다:

1. **이 도구가 수행하는 기능**
2. **도구에게 제공해야하는 입력값의 형식**

이러한 이유로, 도구에 대한 설명은 프로그래밍 언어나 JSON과 같이 표현력이 뛰어나고 구조적인 형식으로 제공하는 경우가 많습니다. 
_반드시_ 이런 형식을 사용할 필요는 없지만, 표현력이 뛰어나고 일관된 방식이면 어떤 형식이라도 사용할 수 있습니다.

이론적으로 들릴 수도 있으니, 구체적인 예시를 통해 이해해 보겠습니다.

두 개의 정수를 곱하는 간단한 **계산기 도구**를 구현해 봅시다. 이를 Python 코드로 작성하면 다음과 같습니다.

```python
def calculator(a: int, b: int) -> int:
    """두 정수를 곱하세요"""
    return a * b
```

이 도구의 이름은 `calculator`(계산기)이고, **두 개의 정수를 곱하는** 기능을 수행합니다. 그리고 다음과 같은 입력값을 필요로 합니다 : 

- **`a`** (*int*): 정수
- **`b`** (*int*): 정수

이 도구의 출력값은 정수이며, 이렇게 표현할 수 있습니다.
- (*int*):  `a` 와 `b`의 곱

위의 모든 세부 정보는 중요합니다. 따라서, LLM이 이 도구를 이해할 수 있도록 텍스트 형식으로 정리해 봅시다!

```text
Tool Name(도구 명): calculator, Description(설명): 두 정수를 곱하세요., Arguments(인자): a: int, b: int, Outputs(출력): int
```

> **참고:** 이 텍스트 설명은 *LLM에게 도구에 대한 정보를 전달하기 위한 것입니다*.

이 문자열을 LLM의 입력으로 제공하면, 모델은 이를 도구로 인식하고, 어떤 입력값을 전달해야 하며 어떤 출력을 얻을 지 알수 있습니다.

추가적인 도구를 제공하려면, 항상 동일한 형식을 유지해야 합니다. 이 과정은 꽤나 까다롭고, 실수로 중요한 세부 정보를 빠뜨릴 수도 있습니다.

더 나은 방법이 있을까요?


### 자동 포맷팅된 도구 섹션 [[auto-formatting-tool-sections]]

우리가 만든 도구는 Python으로 작성되었으며, 이미 필요한 정보를 모두 포함하고 있습니다:

- 수행 작업을 설명해주는 이름: `calculator`(계산기)
- 함수의 docstring 주석을 통해 제공되는 상세 설명: `두 정수를 곱하세요`
- 입력값 및 변수 타입: 함수는 두 개의 `int`(정수)를 요함
- 출력값의 타입

프로그래밍 언어를 사용하는 데에는 이유가 있습니다. 표현력이 높고, 간결하며, 정확하기 때문입니다.

Python 소스 코드를 LLM에게 도구의 명세서(specification) 로 제공할 수도 있지만, 도구가 실제로 어떻게 구현되었는지는 중요하지 않습니다. 중요한 것은 이름, 수행하는 작업, 필요한 입력값, 그리고 제공하는 출력값입니다.

우리는 Python의 내부 정보(Introspection) 기능을 활용하여 소스 코드에서 필요한 정보를 자동으로 추출하고, 도구 설명을 생성 할 것입니다. 이를 위해 도구 구현시 타입 힌트(type hints), docstring, 그리고 직관적인 함수 이름을 사용합니다. 
우리는 소스 코드에서 필요한 정보를 추출하는 코드를 작성하고, 이후에는 Python의 데코레이터(decorator) 를 사용하여  `calculator` 함수가 도구임을 표시하기만 하면 됩니다 :


```python
@tool
def calculator(a: int, b: int) -> int:
    """두 정수를 곱하세요"""
    return a * b

print(calculator.to_string())
```

함수 정의 앞에 `@tool` 데코레이터를 추가해주었습니다.

다음으로 볼 부분은, `to_string()` 함수를 사용해 소스 코드에서 다음과 같은 텍스트를 자동으로 가져옵니다 :

```text
Tool Name(도구명): calculator, Description(설명): Multiply two integers.(두 정수를 곱하세요), Arguments(인자): a: int, b: int, Outputs(출력): int
```

보면 아시겠지만, 이전에 저희가 수동으로 작성한 것과 동일합니다!

### 범용적인 도구(Generic Tool) 구현 [[generic-tool-implementation]]

우리는 여러 도구를 필요할 때마다 재사용할 수 있도록 범용적인 `Tool` 클래스를 생성할 것입니다.

> **참고:** 이 예제는 가상이지만 실제 라이브러리에서 사용되는 방식과 유사합니다.

```python
class Tool:
    """
    재사용 가능한 코드 조각(도구)을 나타내는 클래스입니다.
    
    Attributes(속성):
        name (str): 도구의 이름
        description (str): 도구가 수행하는 작업에 대한 설명
        func (callable): 도구가 호출하는 함수
        arguments (list): 함수의 입력값 리스트
        outputs (str 또는 list): 함수의 출력값
    """
    def __init__(self, 
                 name: str, 
                 description: str, 
                 func: callable, 
                 arguments: list,
                 outputs: str):
        self.name = name
        self.description = description
        self.func = func
        self.arguments = arguments
        self.outputs = outputs

    def to_string(self) -> str:
        """
        도구의 속성을 문자열로 변환하여 반환합니다.
        name, description, arguments, outputs을 포함합니다.
        """
        args_str = ", ".join([
            f"{arg_name}: {arg_type}" for arg_name, arg_type in self.arguments
        ])
        
        return (
            f"Tool Name: {self.name},"
            f" Description: {self.description},"
            f" Arguments: {args_str},"
            f" Outputs: {self.outputs}"
        )

    def __call__(self, *args, **kwargs):
        """
        저장된 함수(callable)를 주어진 입력값으로 실행합니다.
        """
        return self.func(*args, **kwargs)
```

위 코드가 복잡해 보일 수 있지만, 하나씩 살펴보도록 하겠습니다. 이 **`Tool`**클래스는 다음을 포함합니다:

- **`name`** (*str*): 도구의 이름
- **`description`** (*str*): 도구의 기능 설명
- **`function`** (*callable*): 도구가 실행하는 함수
- **`arguments`** (*list*): 함수가 필요로 하는 입력값들
- **`outputs`** (*str* or *list*): 함수가 반환하는 출력값
- **`__call__()`**: 도구 객체가 호출될 때 함수 실행
- **`to_string()`**: 구의 속성을 LLM이 이해할 수 있도록 문자열로 변환


이제 위 클래스를 활용하여 도구를 만들 수 있습니다:

```python
calculator_tool = Tool(
    "calculator",                   # 도구 이름
    "Multiply two integers.",       # 설명
    calculator,                     # 실행할 함수
    [("a", "int"), ("b", "int")],   # 입력값 (이름과 타입)
    "int",                          # 출력값 타입
)
```

그러나 Python의 `inspect` 모듈을 사용하면 이 정보를 자동으로 추출할 수 있습니다. 바로 이 역할을 하는 것이 @tool 데코레이터입니다.

> 데코레이터 구현 부분을 확인하고 싶다면 클릭하세요.

<details>
<summary> 데코레이터 코드 보기</summary>

```python
def tool(func):
    """
    주어진 함수를 기반으로 Tool 인스턴스를 생성하는 데코레이터입니다.
    """
    # 함수의 서명(signature) 가져오기
    signature = inspect.signature(func)
    
    # 입력 인자 추출 (param_name, param_annotation)
    arguments = []
    for param in signature.parameters.values():
        annotation_name = (
            param.annotation.__name__ 
            if hasattr(param.annotation, '__name__') 
            else str(param.annotation)
        )
        arguments.append((param.name, annotation_name))
    
    # 리턴값 타입 결정
    return_annotation = signature.return_annotation
    if return_annotation is inspect._empty:
        outputs = "No return annotation"
    else:
        outputs = (
            return_annotation.__name__ 
            if hasattr(return_annotation, '__name__') 
            else str(return_annotation)
        )
    
    # 함수의 docstring을 설명으로 사용
    description = func.__doc__ or "No description provided."
    
    # 함수명을 도구 이름으로 사용
    name = func.__name__
    
    # Tool 인스턴스를 리턴
    return Tool(
        name=name, 
        description=description, 
        func=func, 
        arguments=arguments, 
        outputs=outputs
    )
```

</details>

이제 @tool 데코레이터를 활용하면, 다음과 같이 도구를 간단하게 정의할 수 있습니다.

```python
@tool
def calculator(a: int, b: int) -> int:
    """두 정수를 곱하세요"""
    return a * b

print(calculator.to_string())
```

그리고 `Tool` 클래스의 `to_string` 메서드를 사용하면 LLM이 사용할 수 있는 적절한 도구 설명을 자동으로 생성해줍니다:

```text
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int
```

이 도구 설명은 시스템 프롬프트에 삽입됩니다. 이 섹션의 처음 예제를 다시 살펴보면, `tools_description`을 대체한 후 시스템 프롬프트는 다음과 같이 보이게 됩니다:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/Agent_system_prompt_tools.png" alt="System prompt for tools"/>

 [Actions](actions) 섹션에서 우리가 방금 만든 도구를 에이전트가 어떻게 **호출**하는지에 대해 살펴볼 것입니다.

---

도구는 AI에이전트의 기능을 확장하는데 핵심적인 역할을 합니다.

요약:

- *도구란?*: LLM이 계산, 외부 데이터 조회 등 추가적인 기능을 할 수 있도록 하는 함수

- *도구 정의하는 법*: 명확한 텍스트 설명, 입력값, 출력값, 호출 가능한 함수 제공

- *도구가 중요한 이유*: 에이전트가 사전에 학습된 정적 모델의 한계를 뛰어넘어, 실시간 작업 및 특수 기능을 수행할 수 있도록 함


이제 [에이전트의 작동 방식(Workflow)](agent-steps-and-structure)에 대해 알아볼 차례입니다! 이 과정에서는 에이전트가 관찰하고, 사고하며, 행동하는 방법을 살펴보게 됩니다.
이 과정을 마치게 되면, 이제까지 배운 모든 내용을 통합하여 나만의 AI 에이전트를 만들 준비가 될 것입니다!


하지만 그 전에, 짧은 퀴즈를 풀어볼까요? 😊


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/tools.mdx" />

### LLM이란?[[what-are-llms]]
https://huggingface.co/learn/agents-course/ko/unit1/what-are-llms.md

# LLM이란?[[what-are-llms]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-1.jpg" alt="Unit 1 planning"/>

이전 섹션에서 각 에이전트는 **코어에 AI 모델**이 필요하며, LLM(대규모 언어 모델)이 이 목적에 부합하는 가장 일반적인 AI 모델 유형임을 배웠습니다.

이제 LLM이 무엇이고, LLM이 어떻게 에이전트를 지원하는지 알아보겠습니다.

이 섹션에서는 LLM의 기술적 개요를 간결하게 설명합니다. 더 깊이 학습하고 싶으시다면 <a href="https://huggingface.co/learn/nlp-course/chapter1/1" target="_blank">자연어 처리 코스</a>를 확인해 주세요!

## 대규모 언어 모델 (LLM)이란? [[what-is-a-large-language-model]]

LLM은 **사람의 언어를 이해하고 생성**하는 능력에 뛰어난 AI 모델입니다. 모델은 방대한 양의 텍스트 데이터를 학습하여 언어의 패턴, 구조, 뉘앙스를 익히며, 일반적으로 수백만 개에서 수십억 개의 매개변수를 가집니다.

대부분의 현대 LLM은 **트랜스포머(Transformer) 아키텍처**를 기반으로 합니다. 트랜스포머는 Google이 2018년에 발표한 BERT 이후로 크게 주목받고 있는 "어텐션(Attention)" 알고리즘을 사용한 딥러닝 아키텍처입니다.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/transformer.jpg" alt="Transformer"/>
<figcaption>The original Transformer architecture looked like this, with an encoder on the left and a decoder on the right.
</figcaption>
</figure>

트랜스포머(transformers)의 3가지 유형 :

1. **인코더(Encoders)**  
   인코더 기반 트랜스포머는 인풋 텍스트(또는 다른 데이터)를 밀집 표현(임베딩)으로 변환합니다.
   
   - **예시**: Google의 BERT
   - **사용 사례**: 텍스트 분류, 의미 검색(semantic search), 개체명 인식(NER)
   - **일반적인 규모**: 수백만 개의 매개변수

2. **디코더(Decoders)**  
   디코더 기반 트랜스포머는 **한 번에 하나의 토큰을 생성하며 시퀀스를 완성**합니다.
	
   - **예시**: Meta의 Llama 
   - **사용 사례**: 텍스트 생성, 챗봇, 코드 생성
   - **일반적인 규모**: 수십억 개의 매개변수

3. **Seq2Seq (Encoder–Decoder)**  
    Seq2Seq 트랜스포머는 인코더와 디코더를 _결합_한 형태입니다. 인코더는 입력 시퀀스를 컨텍스트 표현(컨텍스트 벡터)으로 변환하고, 디코더가 출력 시퀀스를 생성합니다.

   - **예시**: T5, BART 
   - **사용 사례**:  번역, 요약, 패러프레이징(Paraphrasing)
   - **일반적인 규모**: 수백만 개의 매개변수

LLM은 다양한 형태가 있지만, 일반적으로 LLM은 수십억 개의 매개변수를 가진 디코더 기반 모델입니다. 대표적인 LLM은 다음과 같습니다 :

| **모델**                          | **제공 업체**                              |
|-----------------------------------|-------------------------------------------|
| **Deepseek-R1**                    | 딥시크(DeepSeek)                           |
| **GPT4**                           | OpenAI                                    |
| **Llama 3**                        | Meta (페이스북 인공지능 연구소)               |
| **SmolLM2**                       | 허깅페이스(Hugging Face)     |
| **Gemma**                          | 구글(Google)                              |
| **Mistral**                        | 미스트랄(Mistral)                          |

간단하지만 매우 효과적인 LLM의 핵심 원리: **이전 시퀀스를 기반으로 다음 토큰을 예측**하는 것입니다. "토큰" 이란 LLM이 작업하는 정보의 단위입니다. 토큰을 "단어"로 인식하셔도 되나, LLM은 효율성 문제로 전체 단어를 사용하지 않습니다.

예를 들어, 영어에는 약 60만 개의 단어가 있지만, LLM(대규모 언어 모델)의 어휘는 약 32,000개의 토큰으로 구성될 수 있습니다(예: Llama 2). 토큰화(tokenization)은 종종 하위 단어 단위에서 일어나고, 이러한 하위 단위들을 결합할 수 있습니다.

예를 들어, "interest"와 "ing"라는 토큰을 결합하여 "interesting"을 만들거나, "ed"를 추가하여 "interested"를 만들 수 있습니다.

아래 플레이그라운드에서 다양한 토크나이저를 실습해보세요:

<iframe
	src="https://agents-course-the-tokenizer-playground.static.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>


각 LLM에는 모델별로 고유한 **특수 토큰**이 존재합니다. LLM은 이 토큰들을 사용하여 생성하는 텍스트를 구조적으로 열고 닫습니다. 예를 들어, 시퀀스의 시작과 끝, 메시지 또는 응답을 나타내기 위해 사용됩니다. 또한, 우리가 모델에 입력하는 입력 프롬프트도 특수 토큰을 포함한 구조로 작성됩니다. 그중 가장 중요한 것은 **EOS(End of Sequence) 토큰, 시퀀스 종료 토큰**입니다.


특수 토큰의 형태는 모델 제공업체마다 매우 다양합니다.

 
 다음 표는 다양한 LLM의 특수 토큰을 보여줍니다.

<table>
  <thead>
    <tr>
      <th><strong>모델</strong></th>
      <th><strong>제공업체</strong></th>
      <th><strong>EOS 토큰</strong></th>
      <th><strong>기능</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>GPT4</strong></td>
      <td>OpenAI</td>
      <td><code>&lt;|endoftext|&gt;</code></td>
      <td>메세지 텍스트의 끝</td>
    </tr>
    <tr>
      <td><strong>Llama 3</strong></td>
      <td>Meta (Facebook AI Research)</td>
      <td><code>&lt;|eot_id|&gt;</code></td>
      <td>시퀀스의 끝</td>
    </tr>
    <tr>
      <td><strong>Deepseek-R1</strong></td>
      <td>DeepSeek</td>
      <td><code>&lt;|end_of_sentence|&gt;</code></td>
      <td>메세지 텍스트의 끝</td>
    </tr>
    <tr>
      <td><strong>SmolLM2</strong></td>
      <td>Hugging Face</td>
      <td><code>&lt;|im_end|&gt;</code></td>
      <td>지시 / 메세지의 끝</td>
    </tr>
    <tr>
      <td><strong>Gemma</strong></td>
      <td>Google</td>
      <td><code>&lt;end_of_turn&gt;</code></td>
      <td>대화 턴 끝</td>
    </tr>
  </tbody>
</table>

> [!TIP]
> 이러한 특수 토큰을 외울 필요는 없지만, 다양성과 LLM 내에서의 역할을 이해하는 것은 중요합니다. 특정 모델의 특수 토큰에 대해 더 알고 싶다면, 해당 모델의 Hub 저장소에서 설정 파일을 확인할 수 있습니다. 예를 들어, SmolLM2 모델의 특수 토큰은 <a href="https://huggingface.co/HuggingFaceTB/SmolLM2-135M-Instruct/blob/main/tokenizer_config.json">tokenizer_config.json</a>에서 확인할 수 있습니다.

## 다음 토큰 예측 [[understanding-next-token-prediction]]

LLM은 **자기 회귀(autoregressive) ** 방식으로 작동합니다. 즉, **이전 출력이 다음 입력**이 되는 방식으로 동작하며, 이 과정이 반복됩니다. 모델이 다음 토큰을 EOS 토큰으로 예측하면, 텍스트 생성을 중단합니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AutoregressionSchema.gif" alt="Visual Gif of autoregressive decoding" width="60%">

즉, LLM은 EOS에 도달할 때까지 텍스트를 생성합니다. 하지만 단일 디코딩 루프 내에서 어떤 일이 일어날까요?

텍스트 생성 과정은 복잡하지만, 기본적인 개요는 다음과 같습니다 : 

- 입력 텍스트가 **토큰화(tokenization)** 되면, 모델은 시퀀스 내 각 토큰의 의미와 토큰의 위치 정보를 나타내는 표현(representation)을 계산합니다.
- 이 표현이 모델로 입력되며, 모델은 각 토큰 별로 다음 토큰이 될 가능성을 랭킹화한 점수를 출력합니다.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/DecodingFinal.gif" alt="Visual Gif of decoding" width="60%">

이러한 점수를 기반으로, 여러 가지 전략을 사용하여 다음 토큰을 선택합니다.

- 가장 간단한 디코딩 전략은 매번 최대 점수를 가진 토큰을 선택하는 것입니다.

아래에서 SmolLM2 모델을 활용해 디코딩을 실습해보세요!(이 모델의 **EOS 토큰**은 <|im_end|> 입니다.)

<iframe
	src="https://agents-course-decoding-visualizer.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>

- 더 발전된 디코딩 전략도 있습니다. 예를 들어, **빔 서치(beam search)** 는 여러 후보 시퀀스를 탐색하여 전체 점수가 가장 높은 시퀀스를 찾습니다. 이는 일부 개별 토큰의 점수가 낮더라도 전체 점수가 높은 결과를 찾을 수 있도록 합니다.

<iframe
	src="https://agents-course-beam-search-visualizer.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>

디코딩에 대해 더 자세히 알고 싶으시다면, [NLP 코스](https://huggingface.co/learn/nlp-course)를 참고해주세요!

## 당신에게 필요한건 어텐션(Attention) 하나뿐 (Attention is all you need) [[attention-is-all-you-need]]

Transformer 아키텍처에서 가장 중요한 요소 중 하나는 **어텐션(Attention)** 입니다. 다음 단어를 예측할 때, 
문장의 모든 단어가 동일한 중요도를 가지지는 않습니다. 예를 들어, *"The capital of France is ..."*라는 문장에서 "France"와 "capital"이 가장 중요한 의미를 가집니다.


<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AttentionSceneFinal.gif" alt="Visual Gif of Attention" width="60%">
이처럼, 다음 토큰을 예측하는 데 가장 관련성이 높은 단어를 식별하는 과정은 매우 효과적인 기법으로 입증되었습니다.

GPT-2 이후로 LLM의 기본 원리인 '다음 토큰 예측'은 변하지 않았지만, 신경망을 확장하고 어텐션 메커니즘을 사용하여 더 긴 시퀀스에서도 작동할 수 있게 큰 발전이 있었습니다.

LLM을 사용해 본 경험이 있으시다면, *컨텍스트 길이(context length)* 라는 용어를 들어보셨을 것입니다. 이는 LLM이 처리할 수 있는 최대 토큰 수이자, 모델의 최대 _어텐션 스팬(attention span)_ 를 의미합니다.

## LLM에 어떻게 프롬프트(Prompt)를 입력할지가 중요한 이유 [[prompting-the-llm-is-important]]

LLM의 역할은 입력된 모든 토큰을 기반으로 다음 토큰을 예측하고, 어떤 토큰이 "중요한"지를 결정하는 것입니다. 따라서 입력하는 문장의 구성 방식이 매우 중요합니다.

LLM에 제공하는 입력 시퀀스를 _프롬프트(prompt)_ 라고 합니다.**프롬프트를 신중하게 설계하면 원하는 출력**을 얻기 쉬워집니다.

## LLM은 어떻게 학습될까? [[how-are-llms-trained]]

LLM은 방대한 텍스트 데이터셋을 학습하며, 자기지도 학습(self-supervised learning) 또는 마스킹 언어 모델링(masked language modeling)을 이용해 문장 내 다음 단어를 예측하는 방식으로 훈련됩니다.

이러한 비지도 학습(unsupervised learning) 을 통해 모델은 언어의 구조와 **텍스트의 패턴**을 학습하여, 새로운 데이터에도 일반화(generalization) 할 수 있게 됩니다.

이 사전 학습(pre-training) 이후, LLM은 특정 작업을 수행하도록 지도 학습(supervised learning) 방식으로 미세 조정(fine-tuning)됩니다. 예를 들어, 일부 모델은 대화 구조나 도구 활용에 맞춰 훈련되며, 다른 모델들은 분류(classification)나 코드 생성(code generation)에 초점을 맞춰 학습됩니다.



## LLM을 어떻게 사용할 수 있을까? [[how-can-i-use-llms]]

LLM을 사용하는 방법은 크게 두가지로 나뉩니다:

1. **로컬에서 실행하기** (하드웨어 자원이 갖춰져 있는 경우)

2. **클라우드/API 사용하기** (예:Hugging Face Serverless Inference API)

이 코스에서는 주로 Hugging Face Hub의 API를 사용하여 모델을 실행합니다. 추가로, 개인 하드웨어에서 직접 실행하는 방법도 살펴볼 예정입니다.

## LLM은 AI 에이전트에서 어떻게 사용될까? [[how-are-llms-used-in-ai-agents]]

LLM은 AI 에이전트의 핵심 구성 요소로, 자연어를 이해하고 생성하는 역할을 합니다.

LLM은 사용자 명령을 해석하고, 대화의 문맥을 유지하며, 계획을 세우고, 어떤 도구를 사용할 지 결정할 수 있습니다.

이 단계들에 대해 이번 단원에서 좀 더 자세히 살펴볼 예정이지만, 지금 알아야 할 가장 중요한 포인트는**LLM이 에이전트의 "두뇌"역할을 한다는 것**입니다!

---
 
지금까지 많은 정보를 다뤘네요! 이번 섹션에서는 LLM이 무엇인지, 어떻게 작동하는지, 그리고 LLM이 AI 에이전트에서 어떤 역할을 하는지를 살펴보았습니다.

언어 모델과 자연어 처리에 대해 더 깊이 공부하고 싶다면, Hugging Face의 <a href="https://huggingface.co/learn/nlp-course/chapter1/1" target="_blank">무료 NLP 강의 </a>를 확인해 보세요!

이제 우리는 LLM이 어떻게 작동하는지에 대해 배웠으니, **LLM이 대화형 환경에서 어떻게 텍스트를 생성하는지** 살펴볼 차례입니다!

<a href="https://huggingface.co/agents-course/notebooks/blob/main/dummy_agent_library.ipynb" target="_blank">이 노트북</a>을 실행하려면, **yHugging Face 토큰** 을 이곳에서  <a href="https://hf.co/settings/tokens" target="_blank">https://hf.co/settings/tokens</a> 발급하세요!

Jupyter Notebook 실행 방법에 대한 자세한 내용은 <a href="https://huggingface.co/docs/hub/notebooks">Hugging Face Hub의 Jupyter Notebooks문서 </a>를 참고해주세요.

또한, <a href="https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct" target="_blank"> Meta Llama 모델</a>에 대한 엑세스를 요청해야 합니다.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/what-are-llms.mdx" />

### 관찰: 피드백을 통합하여 성찰하고 적응하기 [[observe-integrating-feedback-to-reflect-and-adapt]]
https://huggingface.co/learn/agents-course/ko/unit1/observations.md

# 관찰: 피드백을 통합하여 성찰하고 적응하기 [[observe-integrating-feedback-to-reflect-and-adapt]]

관찰은 **에이전트가 자신의 행동 결과를 인식하는 방법**입니다.

이는 에이전트의 사고 과정을 촉진하고 향후 행동을 안내하는 중요한 정보를 제공합니다.

관찰은 **환경으로부터의 신호**입니다. API의 데이터, 오류 메시지, 또는 시스템 로그와 같은 정보가 다음 사고 주기를 이끕니다.

관찰 단계에서 에이전트는:

- **피드백 수집:** 행동이 성공했는지(또는 실패했는지)에 대한 데이터나 확인을 받습니다.
- **결과 추가:** 새로운 정보를 기존 맥락에 통합하여 실질적으로 기억을 업데이트합니다.
- **전략 조정:** 이렇게 업데이트된 맥락을 활용하여 이후의 사고와 행동을 개선합니다.

예를 들어, 날씨 API가 *"구름 조금, 15°C, 습도 60%"*와 같은 데이터를 반환하면, 이 관찰 결과는 에이전트의 기억(프롬프트 끝부분)에 추가됩니다.

그런 다음 에이전트는 이를 활용해 추가 정보가 필요한지 아니면 최종 답변을 제공할 준비가 되었는지 결정합니다.

이러한 **피드백의 반복적 통합은 에이전트가 목표에 계속 맞춰 나가도록 보장**하며, 실제 결과를 바탕으로 지속적으로 학습하고 조정합니다.

이러한 관찰은 **웹페이지 텍스트를 읽는 것부터 로봇 팔의 위치를 모니터링하는 것까지 다양한 형태**를 취할 수 있습니다. 이는 행동 실행에 대한 텍스트 피드백을 제공하는 도구 "로그"와 같이 볼 수 있습니다.

| 관찰 유형 | 예시 |
|---------------------|---------------------------------------------------------------------------|
| 시스템 피드백 | 오류 메시지, 성공 알림, 상태 코드 |
| 데이터 변경 | 데이터베이스 업데이트, 파일 시스템 수정, 상태 변화 |
| 환경 데이터 | 센서 읽기, 시스템 지표, 자원 사용량 |
| 응답 분석 | API 응답, 쿼리 결과, 계산 출력 |
| 시간 기반 이벤트 | 기한 도달, 예약 작업 완료 |

## 결과는 어떻게 추가되나요? [[how-are-the-results-appended]]

행동을 수행한 후, 프레임워크는 다음 단계를 순서대로 따릅니다:

1. **행동을 분석**하여 호출할 함수와 사용할 인수를 식별합니다.
2. **행동을 실행**합니다.
3. **결과를 추가**하여 **관찰**합니다.

---
이제 에이전트의 사고-행동-관찰 주기에 대해 배웠습니다.

일부 측면이 아직 명확하지 않더라도 걱정하지 마세요. 이후 단원에서 이러한 개념을 다시 살펴보고 더 깊이 이해할 기회가 있을 것입니다.

이제 첫 번째 에이전트를 직접 코딩하여 지금까지 배운 지식을 실습해 볼 시간입니다!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/observations.mdx" />

### 더미 에이전트 라이브러리 [[dummy-agent-library]]
https://huggingface.co/learn/agents-course/ko/unit1/dummy-agent-library.md

# 더미 에이전트 라이브러리 [[dummy-agent-library]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-unit1sub3DONE.jpg" alt="Unit 1 planning"/>

이 코스는 특정 프레임워크에 종속되지 않도록 설계되었습니다. 그 이유는 **AI 에이전트의 개념에 집중하고 특정 프레임워크의 세부 사항에 매몰되지 않기 위함입니다**.

또한, 학생들이 이 강의에서 배운 개념을 원하는 프레임워크를 사용해 자신의 프로젝트에 적용할 수 있기를 바랍니다.

따라서 Unit 1에서는 간단한 더미 에이전트 라이브러리와 서버리스 API를 사용하여 LLM 엔진에 접근할 것입니다.

실제 프로덕션 환경에서는 이런 방식을 사용하지 않겠지만, **에이전트의 작동 원리를 이해하는 데 좋은 출발점**이 될 것입니다.

이 섹션을 마치면 `smolagents`를 사용하여 **간단한 에이전트를 만들** 준비가 될 것입니다.

이어지는 Unit에서는 `LangGraph`, `LlamaIndex`와 같은 다른 AI 에이전트 라이브러리도 사용해 볼 예정입니다.

간단하게 하기 위해 도구와 에이전트로 단순한 Python 함수를 사용할 것입니다.

어떤 환경에서도 시도해볼 수 있도록 `datetime`이나 `os`와 같은 내장 Python 패키지를 사용할 것입니다.

[이 노트북](https://huggingface.co/agents-course/notebooks/blob/main/dummy_agent_library.ipynb)에서 과정을 따라가며 **직접 코드를 실행**해볼 수 있습니다.

## 서버리스 API [[serverless-api]]

Hugging Face 생태계에는 다양한 모델에서 쉽게 추론을 실행할 수 있게 해주는 서버리스 API라는 편리한 기능이 있습니다. 별도의 설치나 배포 과정이 필요 없습니다.

```python
import os
from huggingface_hub import InferenceClient

## https://hf.co/settings/tokens에서 토큰이 필요합니다. 토큰 유형으로 'read'를 선택했는지 확인하세요. Google Colab에서 실행할 경우 "설정" 탭의 "시크릿" 아래에서 설정할 수 있습니다. 반드시 "HF_TOKEN"이라고 이름을 지정해야 합니다.
os.environ["HF_TOKEN"]="hf_xxxxxxxxxxxxxx"

client = InferenceClient("meta-llama/Llama-3.2-3B-Instruct")
# 다음 셀의 출력이 올바르지 않다면, 무료 모델이 과부하 상태일 수 있습니다. 대신 Llama-3.2-3B-Instruct가 포함된 이 공개 엔드포인트를 사용할 수 있습니다
# client = InferenceClient("https://jc26mwg228mkj8dw.us-east-1.aws.endpoints.huggingface.cloud")
```

```python
output = client.text_generation(
    "The capital of France is",
    max_new_tokens=100,
)

print(output)
```
출력:
```
Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris. The capital of France is Paris.
```
LLM 섹션에서 보았듯이, 단순 디코딩만 수행하면 **모델은 EOS(End of Sequence) 토큰을 예측할 때만 멈추게 됩니다**. 하지만 여기서는 그런 일이 일어나지 않습니다. 이는 이것이 대화형(채팅) 모델이고 **모델이 기대하는 채팅 템플릿을 적용하지 않았기 때문입니다**.

이제 우리가 사용하는 <a href="https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct">Llama-3.2-3B-Instruct 모델</a>과 관련된 특수 토큰을 추가하면, 동작이 바뀌어 예상대로 EOS가 생성됩니다.

```python
prompt="""<|begin_of_text|><|start_header_id|>user<|end_header_id|>
The capital of France is<|eot_id|><|start_header_id|>assistant<|end_header_id|>"""
output = client.text_generation(
    prompt,
    max_new_tokens=100,
)

print(output)
```
출력:
```
The capital of France is Paris.
```

"chat" 메서드를 사용하는 것이 채팅 템플릿을 적용하는 훨씬 더 편리하고 안정적인 방법입니다:
```python
output = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "The capital of France is"},
    ],
    stream=False,
    max_tokens=1024,
)
print(output.choices[0].message.content)
```
출력:
```
Paris.
```
chat 메서드는 모델 간 원활한 전환을 보장하기 위해 권장되는 방법이지만, 이 노트북은 교육용이므로 세부 내용을 이해하기 위해 계속해서 "text_generation" 메서드를 사용하겠습니다.

## 더미 에이전트 [[dummy-agent]]

앞 섹션에서 보았듯이, 에이전트 라이브러리의 핵심은 시스템 프롬프트에 정보를 추가하는 것입니다.

이 시스템 프롬프트는 앞서 본 것보다 조금 더 복잡하지만, 이미 다음과 같은 내용을 포함하고 있습니다:

1. **도구에 관한 정보**
2. **사이클 지시사항** (생각(Thought) → 행동(Action) → 관찰(Observation))

```
Answer the following questions as best you can. You have access to the following tools:

get_weather: Get the current weather in a given location

The way you use the tools is by specifying a json blob.
Specifically, this json should have an `action` key (with the name of the tool to use) and an `action_input` key (with the input to the tool going here).

The only values that should be in the "action" field are:
get_weather: Get the current weather in a given location, args: {"location": {"type": "string"}}
example use : 

{{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}}

ALWAYS use the following format:

Question: the input question you must answer
Thought: you should always think about one action to take. Only one action at a time in this format:
Action:

$JSON_BLOB (inside markdown cell)

Observation: the result of the action. This Observation is unique, complete, and the source of truth.
... (this Thought/Action/Observation can repeat N times, you should take several steps when needed. The $JSON_BLOB must be formatted as markdown and only use a SINGLE action at a time.)

You must always end your output with the following format:

Thought: I now know the final answer
Final Answer: the final answer to the original input question

Now begin! Reminder to ALWAYS use the exact characters `Final Answer:` when you provide a definitive answer.
```

"text_generation" 메서드를 사용하고 있으므로 프롬프트를 수동으로 적용해야 합니다:
```python
prompt=f"""<|begin_of_text|><|start_header_id|>system<|end_header_id|>
{SYSTEM_PROMPT}
<|eot_id|><|start_header_id|>user<|end_header_id|>
What's the weather in London ?
<|eot_id|><|start_header_id|>assistant<|end_header_id|>
"""
```

다음과 같이 할 수도 있습니다. 이는 `chat` 메서드 내부에서 일어나는 일입니다:
```python
messages=[
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": "What's the weather in London ?"},
    ]
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-3B-Instruct")

tokenizer.apply_chat_template(messages, tokenize=False,add_generation_prompt=True)
```

이제 프롬프트는 다음과 같습니다:
```
<|begin_of_text|><|start_header_id|>system<|end_header_id|>
Answer the following questions as best you can. You have access to the following tools:

get_weather: Get the current weather in a given location

The way you use the tools is by specifying a json blob.
Specifically, this json should have an `action` key (with the name of the tool to use) and a `action_input` key (with the input to the tool going here).

The only values that should be in the "action" field are:
get_weather: Get the current weather in a given location, args: {"location": {"type": "string"}}
example use : 

{{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}}

ALWAYS use the following format:

Question: the input question you must answer
Thought: you should always think about one action to take. Only one action at a time in this format:
Action:

$JSON_BLOB (inside markdown cell)

Observation: the result of the action. This Observation is unique, complete, and the source of truth.
... (this Thought/Action/Observation can repeat N times, you should take several steps when needed. The $JSON_BLOB must be formatted as markdown and only use a SINGLE action at a time.)

You must always end your output with the following format:

Thought: I now know the final answer
Final Answer: the final answer to the original input question

Now begin! Reminder to ALWAYS use the exact characters `Final Answer:` when you provide a definitive answer. 
<|eot_id|><|start_header_id|>user<|end_header_id|>
What's the weather in London ?
<|eot_id|><|start_header_id|>assistant<|end_header_id|>
```

이제 디코딩을 해봅시다!
```python
output = client.text_generation(
    prompt,
    max_new_tokens=200,
)

print(output)
```
출력:

````
Thought: I will check the weather in London.
Action:
```
{
  "action": "get_weather",
  "action_input": {"location": "London"}
}
```
Observation: The current weather in London is mostly cloudy with a high of 12°C and a low of 8°C.
````

문제가 보이시나요?
>모델이 실제 데이터 없이 허구의 답변을 만들어냈습니다. 실제 함수를 실행하려면 여기서 생성을 중단해야 합니다!
이제 허구의 응답이 생성되지 않도록 "Observation:" 부분 전에 생성을 중지해 봅시다.

```python
output = client.text_generation(
    prompt,
    max_new_tokens=200,
    stop=["Observation:"] # 실제 함수가 호출되기 전에 중단합니다
)

print(output)
```
출력:

````
Thought: I will check the weather in London.
Action:
```
{
  "action": "get_weather",
  "action_input": {"location": "London"}
}
```
Observation:
````

훨씬 좋아졌습니다!
이제 간단한 날씨 정보 제공 함수를 만들어 봅시다. 실제 상황에서는 API를 호출하게 될 것입니다.

```python
# 더미 함수
def get_weather(location):
    return f"the weather in {location} is sunny with low temperatures. \n"

get_weather('London')
```
출력:
```
'the weather in London is sunny with low temperatures. \n'
```

이제 기본 프롬프트, 함수 실행까지의 출력, 그리고 함수 실행 결과를 관찰 결과로 연결한 다음 생성을 계속해 봅시다.

```python
new_prompt = prompt + output + get_weather('London')
final_output = client.text_generation(
    new_prompt,
    max_new_tokens=200,
)

print(final_output)
```
새로운 프롬프트는 다음과 같습니다:
````
<|begin_of_text|><|start_header_id|>system<|end_header_id|>
    Answer the following questions as best you can. You have access to the following tools:

get_weather: Get the current weather in a given location

The way you use the tools is by specifying a json blob.
Specifically, this json should have a `action` key (with the name of the tool to use) and a `action_input` key (with the input to the tool going here).

The only values that should be in the "action" field are:
get_weather: Get the current weather in a given location, args: {"location": {"type": "string"}}
example use : 

{{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}}

ALWAYS use the following format:

Question: the input question you must answer
Thought: you should always think about one action to take. Only one action at a time in this format:
Action:

$JSON_BLOB (inside markdown cell)

Observation: the result of the action. This Observation is unique, complete, and the source of truth.
... (this Thought/Action/Observation can repeat N times, you should take several steps when needed. The $JSON_BLOB must be formatted as markdown and only use a SINGLE action at a time.)

You must always end your output with the following format:

Thought: I now know the final answer
Final Answer: the final answer to the original input question

Now begin! Reminder to ALWAYS use the exact characters `Final Answer:` when you provide a definitive answer. 
<|eot_id|><|start_header_id|>user<|end_header_id|>
What's the weather in London ?
<|eot_id|><|start_header_id|>assistant<|end_header_id|>
Thought: I will check the weather in London.
Action:
```
{
  "action": "get_weather",
  "action_input": {"location": {"type": "string", "value": "London"}
}
```
Observation:the weather in London is sunny with low temperatures. 
````

출력:
```
Final Answer: The weather in London is sunny with low temperatures.
```

---

지금까지 Python 코드를 사용하여 처음부터 에이전트를 만드는 방법을 배웠고, **그 과정이 얼마나 번거로울 수 있는지** 확인했습니다. 다행히 많은 에이전트 라이브러리들이 이러한 작업을 단순화하여 복잡한 부분을 대신 처리해 줍니다.

이제 `smolagents` 라이브러리를 사용하여 **첫 번째 실제 에이전트를 만들** 준비가 되었습니다.

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ko/unit1/dummy-agent-library.mdx" />
