From eb4a0c02497d7fed0318cd572fea6c41597b3c5e Mon Sep 17 00:00:00 2001 From: FacerAin Date: Tue, 2 Sep 2025 00:52:45 +0900 Subject: [PATCH 1/4] docs: translate to inspect_runs to ko --- docs/source/ko/_toctree.yml | 4 + docs/source/ko/tutorials/inspect_runs.md | 179 +++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 docs/source/ko/tutorials/inspect_runs.md diff --git a/docs/source/ko/_toctree.yml b/docs/source/ko/_toctree.yml index ae28860db..060474ab2 100644 --- a/docs/source/ko/_toctree.yml +++ b/docs/source/ko/_toctree.yml @@ -18,6 +18,10 @@ title: (번역중) "Human-in-the-Loop: Customize agent plan interactively" - local: in_translation title: (번역중) Async Applications with Agents +- title: 튜토리얼 + sections: + - local: tutorials/inspect_runs + title: 에이전트 실행 검사하기 - title: Reference sections: - local: reference/agents diff --git a/docs/source/ko/tutorials/inspect_runs.md b/docs/source/ko/tutorials/inspect_runs.md new file mode 100644 index 000000000..671b1313e --- /dev/null +++ b/docs/source/ko/tutorials/inspect_runs.md @@ -0,0 +1,179 @@ +# OpenTelemetry로 실행 검사하기[[inspecting-runs-with-opentelemetry]] + +[[open-in-colab]] + +> [!TIP] +> 에이전트 구축이 처음이라면 먼저 [에이전트 소개](../conceptual_guides/intro_agents)와 [안내서](../guided_tour)를 읽어보세요. + +## 에이전트 실행을 로깅하는 이유는?[[why-log-your-agent-runs?]] + +에이전트 실행을 디버깅하는 것은 복잡한 작업입니다. + +실행이 제대로 진행되었는지 확인하기가 어렵습니다. 에이전트 워크플로우는 설계상 예측 불가능하기 때문입니다(만약 예측 가능했다면 일반적인 코드를 사용했을 것입니다). + +실행 과정을 살펴보는 것도 쉽지 않습니다. 다단계 에이전트는 콘솔을 로그로 빠르게 채우는 경향이 있으며, 대부분의 오류는 단순한 "LLM의 실수" 유형으로, LLM이 다음 단계에서 더 나은 코드나 도구 호출을 작성하여 스스로 교정합니다. + +따라서 나중에 검사하고 모니터링할 수 있도록 계측을 통해 에이전트 실행을 기록하는 것이 프로덕션 환경에서는 필수입니다! + +에이전트 실행을 계측하기 위해 [OpenTelemetry](https://opentelemetry.io/) 표준을 도입했습니다. + +즉, 계측 코드를 실행한 후 에이전트를 평소처럼 실행하면 모든 내용이 플랫폼에 자동으로 로깅됩니다. 다양한 OpenTelemetry 백엔드에서 이를 구현하는 방법의 예시를 아래에 제시합니다. + +플랫폼에서의 실제 모습은 다음과 같습니다: + +
+ +
+ +## Arize AI Phoenix로 텔레메트리 설정[[setting-up-telemetry-with-arize-ai-phoenix]] + +먼저 필요한 패키지를 설치하세요. 여기서는 로그를 수집하고 검사하는 좋은 솔루션인 [Arize AI의 Phoenix](https://github.com/Arize-ai/phoenix)를 설치하지만, 이 수집 및 검사 부분에 사용할 수 있는 다른 OpenTelemetry 호환 플랫폼도 있습니다. + +```shell +pip install 'smolagents[telemetry,toolkit]' +``` + +그다음 백그라운드에서 수집기를 실행하세요. + +```shell +python -m phoenix.server.main serve +``` + +마지막으로 `SmolagentsInstrumentor`를 설정하여 에이전트를 추적하고 Phoenix 기본 엔드포인트로 추적을 보내세요. + +```python +from phoenix.otel import register +from openinference.instrumentation.smolagents import SmolagentsInstrumentor + +register() +SmolagentsInstrumentor().instrument() +``` +그러면 에이전트를 실행할 수 있습니다! + +```py +from smolagents import ( + CodeAgent, + ToolCallingAgent, + WebSearchTool, + VisitWebpageTool, + InferenceClientModel, +) + +model = InferenceClientModel() + +search_agent = ToolCallingAgent( + tools=[WebSearchTool(), VisitWebpageTool()], + model=model, + name="search_agent", + description="This is an agent that can do web search.", +) + +manager_agent = CodeAgent( + tools=[], + model=model, + managed_agents=[search_agent], +) +manager_agent.run( + "If the US keeps its 2024 growth rate, how many years will it take for the GDP to double?" +) +``` +끝입니다! +이제 `http://0.0.0.0:6006/projects/`로 이동하여 실행을 검사할 수 있습니다! + + + +CodeAgent가 관리하는 ToolCallingAgent를 호출해서(참고로 관리되는 에이전트는 CodeAgent가 될 수도 있습니다) 미국 2024년 성장률을 웹에서 검색하도록 요청한 것을 확인할 수 있습니다. 이후 관리되는 에이전트가 결과를 보고하면, 관리자 에이전트가 이 정보를 활용하여 경제 배증 시간을 계산했습니다! 흥미롭죠? + +## 🪢 Langfuse로 텔레메트리 설정[[setting-up-telemetry-with-🪢-langfuse]] + +이 부분은 `SmolagentsInstrumentor`를 사용하여 **Langfuse**로 Hugging Face **smolagents**를 모니터링하고 디버깅하는 방법을 보여줍니다. + +> **Langfuse란?** [Langfuse](https://langfuse.com)는 LLM 엔지니어링을 위한 오픈소스 플랫폼입니다. AI 에이전트를 위한 추적 및 모니터링 기능을 제공하여 개발자가 제품을 디버깅하고, 분석하고, 최적화할 수 있도록 도와줍니다. Langfuse는 네이티브 통합, OpenTelemetry, SDK를 통해 다양한 도구와 프레임워크와 통합됩니다. + +### 1단계: 의존성 설치[[step-1:-install-dependencies]] + +```python +%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents +``` + +### 2단계: 환경 변수 설정[[step-2:-set-up-environment-variables]] + +Langfuse API 키를 설정하고 Langfuse로 추적을 보내도록 OpenTelemetry 엔드포인트를 구성하세요. [Langfuse Cloud](https://cloud.langfuse.com)에 가입하거나 [Langfuse를 자체 호스팅](https://langfuse.com/self-hosting)하여 Langfuse API 키를 얻으세요. + +또한 [Hugging Face 토큰](https://huggingface.co/settings/tokens) (`HF_TOKEN`)을 환경 변수로 추가하세요. + +```python +import os +# Get keys for your project from the project settings page: https://cloud.langfuse.com +os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." +os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region + +# your Hugging Face token +os.environ["HF_TOKEN"] = "hf_..." +``` + +환경 변수가 설정되면 이제 Langfuse 클라이언트를 초기화할 수 있습니다. `get_client()`는 환경 변수에 제공된 자격 증명을 사용하여 Langfuse 클라이언트를 초기화합니다. + +```python +from langfuse import get_client + +langfuse = get_client() + +# Verify connection +if langfuse.auth_check(): + print("Langfuse client is authenticated and ready!") +else: + print("Authentication failed. Please check your credentials and host.") +``` + +### 3단계: `SmolagentsInstrumentor` 초기화[[step-3:-initialize-the-`smolagentsinstrumentor`]] + +애플리케이션 코드 앞에서 `SmolagentsInstrumentor`를 초기화하세요. + +```python +from openinference.instrumentation.smolagents import SmolagentsInstrumentor + +SmolagentsInstrumentor().instrument() +``` + +### 4단계: smolagent 실행[[step-4:-run-your-smolagent]] + +```python +from smolagents import ( + CodeAgent, + ToolCallingAgent, + WebSearchTool, + VisitWebpageTool, + InferenceClientModel, +) + +model = InferenceClientModel( + model_id="deepseek-ai/DeepSeek-R1-Distill-Qwen-32B" +) + +search_agent = ToolCallingAgent( + tools=[WebSearchTool(), VisitWebpageTool()], + model=model, + name="search_agent", + description="This is an agent that can do web search.", +) + +manager_agent = CodeAgent( + tools=[], + model=model, + managed_agents=[search_agent], +) +manager_agent.run( + "How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?" +) +``` + +### 5단계: Langfuse에서 추적 보기[[step-5:-view-traces-in-langfuse]] + +에이전트를 실행한 후 Langfuse에서 smolagents 애플리케이션에서 생성된 추적 정보를 확인할 수 있습니다. AI 에이전트 디버깅과 최적화에 도움이 되는 LLM 상호작용의 상세한 과정을 살펴볼 수 있습니다. + +![smolagents example trace](https://langfuse.com/images/cookbook/integration-smolagents/smolagent_example_trace.png) + +_[Langfuse의 추적 예시](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_ \ No newline at end of file From 7315daf7150e71edf58de65209fb687a9636737a Mon Sep 17 00:00:00 2001 From: Yong woo Song Date: Mon, 6 Oct 2025 23:03:41 +0900 Subject: [PATCH 2/4] Fix Korean title for telemetry inspection tutorial --- docs/source/ko/_toctree.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/ko/_toctree.yml b/docs/source/ko/_toctree.yml index cfbb8c7a2..0626539f0 100644 --- a/docs/source/ko/_toctree.yml +++ b/docs/source/ko/_toctree.yml @@ -11,7 +11,7 @@ - local: tutorials/building_good_agents title: 좋은 에이전트 구축하기 - local: tutorials/inspect_runs - title: 📊 Telemetry로 에이전트 실행 검사하기 + title: 📊 텔레메트리로 에이전트 실행 검사하기 # - local: tutorials/tools # title: 🛠️ Tools - in-depth guide # - local: tutorials/secure_code_execution @@ -51,4 +51,4 @@ # - title: Tool-related objects # local: reference/tools # - title: Built-in Tools -# local: reference/default_tools \ No newline at end of file +# local: reference/default_tools From 198b9b89dc0ed5a4c1836406862cadc9b4db40ba Mon Sep 17 00:00:00 2001 From: Yong woo Song Date: Mon, 6 Oct 2025 23:04:40 +0900 Subject: [PATCH 3/4] Fix typos in inspect_runs.md --- docs/source/ko/tutorials/inspect_runs.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/ko/tutorials/inspect_runs.md b/docs/source/ko/tutorials/inspect_runs.md index 671b1313e..2e704d8a6 100644 --- a/docs/source/ko/tutorials/inspect_runs.md +++ b/docs/source/ko/tutorials/inspect_runs.md @@ -9,7 +9,7 @@ 에이전트 실행을 디버깅하는 것은 복잡한 작업입니다. -실행이 제대로 진행되었는지 확인하기가 어렵습니다. 에이전트 워크플로우는 설계상 예측 불가능하기 때문입니다(만약 예측 가능했다면 일반적인 코드를 사용했을 것입니다). +실행이 제대로 진행되었는지 확인하기 어렵습니다. 에이전트 워크플로우는 설계상 예측 불가능하기 때문입니다(만약 예측 가능했다면 일반적인 코드를 사용했을 것입니다). 실행 과정을 살펴보는 것도 쉽지 않습니다. 다단계 에이전트는 콘솔을 로그로 빠르게 채우는 경향이 있으며, 대부분의 오류는 단순한 "LLM의 실수" 유형으로, LLM이 다음 단계에서 더 나은 코드나 도구 호출을 작성하여 스스로 교정합니다. @@ -33,7 +33,7 @@ pip install 'smolagents[telemetry,toolkit]' ``` -그다음 백그라운드에서 수집기를 실행하세요. +그 다음 백그라운드에서 수집기를 실행하세요. ```shell python -m phoenix.server.main serve @@ -82,7 +82,7 @@ manager_agent.run( -CodeAgent가 관리하는 ToolCallingAgent를 호출해서(참고로 관리되는 에이전트는 CodeAgent가 될 수도 있습니다) 미국 2024년 성장률을 웹에서 검색하도록 요청한 것을 확인할 수 있습니다. 이후 관리되는 에이전트가 결과를 보고하면, 관리자 에이전트가 이 정보를 활용하여 경제 배증 시간을 계산했습니다! 흥미롭죠? +CodeAgent가 관리하는 ToolCallingAgent를 호출하여(참고로 관리되는 에이전트는 CodeAgent가 될 수도 있습니다) 미국 2024년 성장률을 웹에서 검색하도록 요청한 것을 확인할 수 있습니다. 이후 관리되는 에이전트가 결과를 보고하면, 관리자 에이전트가 이 정보를 활용하여 경제 배증 시간을 계산했습니다! 흥미롭죠? ## 🪢 Langfuse로 텔레메트리 설정[[setting-up-telemetry-with-🪢-langfuse]] @@ -176,4 +176,4 @@ manager_agent.run( ![smolagents example trace](https://langfuse.com/images/cookbook/integration-smolagents/smolagent_example_trace.png) -_[Langfuse의 추적 예시](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_ \ No newline at end of file +_[Langfuse의 추적 예시](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_ From 057a4787d3307ef9807a7268875858725f1a5c60 Mon Sep 17 00:00:00 2001 From: Yong woo Song Date: Tue, 14 Oct 2025 23:35:32 +0900 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: HyunZ118 <156191095+HyunZ118@users.noreply.github.com> --- docs/source/ko/tutorials/inspect_runs.md | 26 ++++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/source/ko/tutorials/inspect_runs.md b/docs/source/ko/tutorials/inspect_runs.md index 2e704d8a6..bee0bb59e 100644 --- a/docs/source/ko/tutorials/inspect_runs.md +++ b/docs/source/ko/tutorials/inspect_runs.md @@ -19,7 +19,7 @@ 즉, 계측 코드를 실행한 후 에이전트를 평소처럼 실행하면 모든 내용이 플랫폼에 자동으로 로깅됩니다. 다양한 OpenTelemetry 백엔드에서 이를 구현하는 방법의 예시를 아래에 제시합니다. -플랫폼에서의 실제 모습은 다음과 같습니다: +플랫폼에서의 실제 모습은 다음과 같습니다.
@@ -27,19 +27,19 @@ ## Arize AI Phoenix로 텔레메트리 설정[[setting-up-telemetry-with-arize-ai-phoenix]] -먼저 필요한 패키지를 설치하세요. 여기서는 로그를 수집하고 검사하는 좋은 솔루션인 [Arize AI의 Phoenix](https://github.com/Arize-ai/phoenix)를 설치하지만, 이 수집 및 검사 부분에 사용할 수 있는 다른 OpenTelemetry 호환 플랫폼도 있습니다. +먼저 필요한 패키지를 설치합니다. 여기서는 로그를 수집하고 검사하기에 좋은 솔루션인 [Arize AI의 Phoenix](https://github.com/Arize-ai/phoenix)를 설치하지만, 이 과정에는 다른 OpenTelemetry 호환 플랫폼을 활용할 수도 있습니다. ```shell pip install 'smolagents[telemetry,toolkit]' ``` -그 다음 백그라운드에서 수집기를 실행하세요. +다음 단계로 수집기를 백그라운드에서 실행합니다. ```shell python -m phoenix.server.main serve ``` -마지막으로 `SmolagentsInstrumentor`를 설정하여 에이전트를 추적하고 Phoenix 기본 엔드포인트로 추적을 보내세요. +마지막으로 `SmolagentsInstrumentor`를 설정하여 에이전트를 추적하고 Phoenix 기본 엔드포인트로 해당 추적 데이터를 전송합니다. ```python from phoenix.otel import register @@ -48,7 +48,7 @@ from openinference.instrumentation.smolagents import SmolagentsInstrumentor register() SmolagentsInstrumentor().instrument() ``` -그러면 에이전트를 실행할 수 있습니다! +이제 에이전트를 실행할 수 있습니다! ```py from smolagents import ( @@ -78,7 +78,7 @@ manager_agent.run( ) ``` 끝입니다! -이제 `http://0.0.0.0:6006/projects/`로 이동하여 실행을 검사할 수 있습니다! +이제 `http://0.0.0.0:6006/projects/`로 이동하여 실행 결과를 확인할 수 있습니다! @@ -104,13 +104,13 @@ Langfuse API 키를 설정하고 Langfuse로 추적을 보내도록 OpenTelemetr ```python import os -# Get keys for your project from the project settings page: https://cloud.langfuse.com +# 프로젝트 설정 페이지(https://cloud.langfuse.com)에서 프로젝트 키를 가져옵니다. os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." -os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region -# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 유럽 지역 +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 미국 지역 -# your Hugging Face token +# Hugging Face 토큰을 입력합니다. os.environ["HF_TOKEN"] = "hf_..." ``` @@ -121,7 +121,7 @@ from langfuse import get_client langfuse = get_client() -# Verify connection +# 연결을 확인합니다. if langfuse.auth_check(): print("Langfuse client is authenticated and ready!") else: @@ -130,7 +130,7 @@ else: ### 3단계: `SmolagentsInstrumentor` 초기화[[step-3:-initialize-the-`smolagentsinstrumentor`]] -애플리케이션 코드 앞에서 `SmolagentsInstrumentor`를 초기화하세요. +애플리케이션 코드를 실행하기 전에 `SmolagentsInstrumentor`를 초기화하세요. ```python from openinference.instrumentation.smolagents import SmolagentsInstrumentor @@ -172,7 +172,7 @@ manager_agent.run( ### 5단계: Langfuse에서 추적 보기[[step-5:-view-traces-in-langfuse]] -에이전트를 실행한 후 Langfuse에서 smolagents 애플리케이션에서 생성된 추적 정보를 확인할 수 있습니다. AI 에이전트 디버깅과 최적화에 도움이 되는 LLM 상호작용의 상세한 과정을 살펴볼 수 있습니다. +에이전트를 실행한 후, Langfuse의 smolagents 애플리케이션에서 생성된 추적 정보를 확인할 수 있습니다. AI 에이전트의 디버깅과 최적화에 도움이 되는 LLM 상호작용의 상세한 세부 과정을 살펴볼 수 있습니다. ![smolagents example trace](https://langfuse.com/images/cookbook/integration-smolagents/smolagent_example_trace.png)