huggingface · Kim-Ju-won · Oct 15, 2025 · Oct 15, 2025 · Oct 15, 2025 · Oct 15, 2025
diff --git a/docs/source/ko/_toctree.yml b/docs/source/ko/_toctree.yml
@@ -20,8 +20,8 @@
     title: 📚 에이전트 메모리 관리
 - title: Conceptual guides
   sections:
-#  - local: conceptual_guides/intro_agents
-#    title: 🤖 What are agents?
+  - local: conceptual_guides/intro_agents
+    title: 🤖 에이전트란 무엇인가요?
   - local: conceptual_guides/react
     title: 🤔 멀티스텝 에이전트는 어떻게 동작하나요?
 - title: 예제

diff --git a/docs/source/ko/conceptual_guides/intro_agents.md b/docs/source/ko/conceptual_guides/intro_agents.md
@@ -0,0 +1,105 @@
+# 에이전트란 무엇일까요? 🤔[[what-are-agents-]]
+
+## 에이전틱 시스템 소개[[an-introduction-to-agentic-systems]]
+
+효율적인 AI 시스템을 만들기 위해서는 LLM에게 현실 세계에 대한 일종의 접근 권한을 제공해야 합니다. 예를 들어, 외부 정보를 얻기 위해 검색 도구를 호출하거나, 특정 작업을 해결하기 위해 특정 프로그램에 따라 행동하도록 만들 수 있습니다. 다시 말해, LLM은 ***주체성(agency)***을 가져야 합니다. 에이전틱 프로그램은 LLM이 외부 세계와 상호작용할 수 있도록 연결하는 인터페이스입니다.
+
+> [!TIP]
+> AI 에이전트는 **LLM의 출력이 워크플로우를 제어하는 프로그램**입니다.
+
+LLM을 활용하는 모든 시스템은 코드에 LLM의 출력을 통합합니다. LLM의 입력이 코드 워크플로우에 얼마나 영향을 미치는지가, 시스템 내에서 LLM이 가지는 주체성의 수준을 결정합니다.
+
+이 정의에 따르면, "에이전트"는 0 또는 1로 나뉘는 이산적인 정의가 아닙니다. 대신, "주체성"은 워크플로우에 대해 LLM에 얼마나 많은 권한을 부여하는지에 따라 연속적인 스펙트럼 위에서 변화합니다.
+
+아래 표에서 주체성이 시스템에 따라 어떻게 달라질 수 있는지 확인해 보세요.
+
+| 주체성 수준 | 설명 | 간단한 이름 | 예시 코드 |
+| ------------ | --------------------------------------------------------------- | ---------------- | -------------------------------------------------- |
+| ☆☆☆ | LLM 출력이 프로그램 흐름에 영향을 미치지 않음 | 단순 처리기 | `process_llm_output(llm_response)` |
+| ★☆☆ | LLM 출력이 if/else 분기를 제어함 | 라우터 | `if llm_decision(): path_a() else: path_b()` |
+| ★★☆ | LLM 출력이 함수 실행을 제어함 | 도구 호출 | `run_function(llm_chosen_tool, llm_chosen_args)` |
+| ★★☆ | LLM 출력이 반복 및 프로그램 지속 여부를 제어함 | 멀티스텝 에이전트 | `while llm_should_continue(): execute_next_step()` |
+| ★★★ | 하나의 에이전틱 워크플로우가 다른 에이전틱 워크플로우를 시작할 수 있음 | 멑티 에이전트 | `if llm_trigger(): execute_agent()` |
+| ★★★ | LLM이 코드 내에서 행동하며, 자체 도구를 정의하거나 다른 에이전트를 시작할 수 있음 | 코드 에이전트 | `def custom_tool(args): ...` |
+
+멀티스텝 에이전트는 다음과 같은 코드 구조를 가집니다.
+
+```python
+memory = [user_defined_task]
+while llm_should_continue(memory): # 이 루프가 멀티 스텝(multi-step) 추론, 호출을 반복해서 수행하는 루프 입니다. 
+    action = llm_get_next_action(memory) # 이 부분이 도구 호출(tool-calling) 부분입니다
+    observations = execute_action(action)
+    memory += [action, observations]
+```
+
+이 에이전틱 시스템은 루프 안에서 실행되며, 각 단계에서 새로운 행동을 수행합니다(이 행동은 미리 정해진 *도구*, 즉 함수를 호출하는 것을 포함할 수 있습니다). 그리고 관찰을 통해 주어진 작업을 해결하기에 만족스러운 상태에 도달했다고 판단될 때까지 이 과정을 반복합니다. 다음은 멀티스텝 에이전트가 간단한 수학 문제를 해결하는 예시입니다.
+
+<div class="flex justify-center">
+    <img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/Agent_ManimCE.gif"/>
+</div>
+
+
+## ✅ 에이전트 사용 시점 / ⛔ 사용을 피해야 할 때[[-when-to-use-agents---when-to-avoid-them]]
+
+에이전트는 앱의 워크플로우를 LLM이 결정하도록 해야 할 때 유용합니다. 하지만 종종 과도한 기능일 수 있습니다. 핵심 질문은 '당면한 작업을 효율적으로 해결하기 위해 워크플로우에 정말 유연성이 필요한가?'입니다.
+만약 미리 정해진 워크플로우가 상황에 맞지 않는 경우가 잦다면, 이는 더 많은 유연성이 필요하다는 의미입니다.
+예를 들어, 서핑 여행 웹사이트에서 고객 요청을 처리하는 앱을 만든다고 가정해 봅시다.
+
+요청이 (사용자 선택에 따라) 두 가지 유형 중 하나에 속할 것을 미리 알 수 있고, 이 두 경우 각각에 대해 미리 정의된 워크플로우를 가지고 있을 수 있습니다.
+
+1. 여행에 대한 정보가 필요한가요? ⇒ 지식 베이스를 검색할 수 있는 검색창 접근 권한을 제공합니다.
+2. 영업팀과 상담을 원하나요? ⇒ 문의 양식을 작성하도록 합니다.
+
+만약 이 결정론적인 워크플로우가 모든 쿼리에 적합하다면, 주저 없이 모든 것을 직접 코딩하세요! 이렇게 하면 예측 불가능한 LLM이 워크플로우에 개입하여 발생할 수 있는 오류 위험 없이 100% 신뢰할 수 있는 시스템을 만들 수 있습니다. 단순하고 안정적인 시스템을 만들기위해 에이전트 기반 동작을 사용하지 않는 쪽으로 설계하는 것이 좋습니다.
+
+하지만 워크플로우를 사전에 그렇게 잘 결정할 수 없다면 어떨까요?
+
+예를 들어, 사용자가 다음과 같이 질문한다고 가정해 봅시다. `"월요일에 출발할 수 있지만, 여권을 두고 와서 수요일로 미뤄질 수도 있어요. 화요일 아침에 짐이랑 같이 서핑하러 갈 수 있을까요? 취소 보험도 포함해서요."` 이 질문은 여러 요인에 따라 달라지며, 아마도 위에서 미리 정해진 기준 중 어느 것도 이 요청을 처리하기에 충분하지 않을 것입니다.
+
+만약 미리 정해진 워크플로우가 상황에 맞지 않는 경우가 잦다면, 이는 더 많은 유연성이 필요하다는 의미입니다.
+
+바로 이 지점에서 에이전틱 설정이 도움이 됩니다.
+
+위 예시에서는, 날씨 예보를 위한 날씨 API, 이동 거리를 계산하기 위한 Google Maps API, 직원 근무 현황 대시보드, 그리고 지식 베이스에 대한 RAG 시스템에 접근할 수 있는 멀티스텝 에이전트를 만들 수 있습니다.
+
+최근까지의 컴퓨터 프로그램은 미리 정해진 워크플로우 안에서만 동작하며, if/else 문을 쌓아 복잡성을 처리하려고 했습니다. 이들은 "이 숫자들의 합을 계산하라" 또는 "이 그래프에서 최단 경로를 찾아라"와 같이 극히 한정된 작업에 초점을 맞췄습니다. 하지만 실제로는 위 여행 예시처럼 대부분의 실생활 작업은 미리 정해진 워크플로우에 들어맞지 않습니다. 에이전틱 시스템은 이러한 한계를 넘어, 프로그램이 현실 세계의 다양한 문제를 스스로 탐색하고 해결할 수 있도록 합니다.
+
+## 왜 `smolagents`인가요?[[why-smolagents-]]
+
+체인이나 라우터처럼 비교적 단순한 에이전틱 활용 사례라면, 모든 코드를 직접 작성하는 편이 좋습니다. 그렇게 하는 것이 시스템을 더 잘 제어하고 이해할 수 있게 해주므로 훨씬 더 나은 방법입니다.
+
+하지만 LLM이 함수를 호출하게 하거나(도구 호출) LLM이 while 루프를 실행하게 하는(멀티스텝 에이전트) 등 더 복잡한 동작으로 넘어가기 시작하면, 몇 가지 추상화가 필요해집니다.
+- 도구 호출의 경우, 에이전트의 출력을 파싱해야 합니다. 따라서 이 출력은 "사고: 'get_weather' 도구를 호출해야겠다. 행동: get_weather(Paris)."와 같이 미리 정의된 형식이 필요하며, 이 형식은 미리 정의된 함수로 파싱해야 합니다. 그리고 LLM에 제공되는 시스템 프롬프트는 이 형식에 대해 알려주어야 합니다.
+- LLM 출력이 루프를 결정하는 멀티스텝 에이전트의 경우, 마지막 루프 반복에서 일어난 일에 따라 LLM에 다른 프롬프트를 제공해야 합니다. 따라서 일종의 메모리가 필요합니다.
+
+보시다시피, 이 두 가지 예시만으로도 에이전트 시스템 구성을 도와줄 몇 가지 핵심 요소의 필요성을 이미 발견했습니다.
+
+- 물론, 시스템의 엔진 역할을 하는 LLM
+- 에이전트가 접근할 수 있는 도구 목록
+- 에이전트 로직에 대해 LLM을 안내하는 시스템 프롬프트: ReAct 루프(성찰 -> 행동 -> 관찰), 사용 가능한 도구, 사용할 도구 호출 형식 등...
+- 위 시스템 프롬프트에 명시된 형식으로 LLM 출력에서 도구 호출을 추출하는 파서
+- 메모리
+
+하지만 잠깐, LLM에게 결정의 여지를 주기 때문에 분명 실수를 할 것입니다. 따라서 오류 로깅과 재시도 메커니즘이 필요합니다.
+
+잘 작동하는 시스템을 만들기 위해서는 이 모든 요소들이 긴밀하게 결합되어야 합니다. 이것이 바로 이 모든 것들이 함께 작동하도록 만드는 기본 구성 요소를 만들어야 한다고 결정한 이유입니다.
+
+## 코드 에이전트[[code-agents]]
+
+멀티스텝 에이전트에서 각 단계마다 LLM은 외부 도구를 호출하는 형태의 행동을 정의할 수 있습니다. 이러한 행동을 정의하는 일반적인 형식(Anthropic, OpenAI 및 다른 많은 곳에서 사용)은 대체로 "사용할 도구 이름과 인수를 JSON으로 작성하고, 이를 파싱하여 어떤 도구를 어떤 인수로 실행할지 파악하는" 구조입니다. 이 방식은 구현에 따라 여러 가지 형태로 변형될 수 있습니다.
+
+[여러](https://huggingface.co/papers/2402.01030) [연구](https://huggingface.co/papers/2411.01747) [논문](https://huggingface.co/papers/2401.00812)에서는 LLM의 행동을 코드 스니펫으로 작성하는 것이 더 자연스럽고 유연한 방법임을 보여주었습니다.
+
+그 이유는 간단합니다. 사람은 *컴퓨터가 수행하는 행동을 표현하기 위해 특별히 코드 언어를 만들었기 때문*입니다.
+다시 말해, 에이전트는 사용자의 문제를 해결하기 위해 프로그램을 작성할 것입니다. 여러분은 파이썬 블록과 JSON 블록 중 어느 것으로 프로그래밍하는 것이 더 쉬울 것이라고 생각하시나요?
+
+[실행 가능한 코드 행동이 더 나은 LLM 에이전트를 이끌어낸다(Executable Code Actions Elicit Better LLM Agents)](https://huggingface.co/papers/2402.01030)에서 가져온 아래 그림은 행동을 코드로 작성할 때의 몇 가지 장점을 보여줍니다.
+
+<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/code_vs_json_actions.png">
+
+JSON과 유사한 스니펫 대신 코드로 행동을 작성하면 다음과 같은 점에서 더 좋습니다.
+
+- **구성 가능성:** 파이썬 함수를 정의하는 것처럼 JSON 행동을 서로 중첩하거나, 나중에 재사용할 JSON 행동 집합을 정의할 수 있을까요?
+- **객체 관리:** `generate_image`와 같은 행동의 출력을 JSON에 어떻게 저장할 수 있을까요?
+- **일반성:** 코드는 컴퓨터가 할 수 있는 모든 것을 간단하게 표현하도록 만들어졌습니다.
+- **LLM 훈련 데이터에서의 표현:** 양질의 코드 행동이 이미 LLM의 훈련 데이터에 많이 포함되어 있어, LLM이 이미 이를 위해 훈련되었다는 것을 의미합니다