에이전트 앱을 만들 때 가장 두려운 것은 에러가 발생하는 것이 아니라, "에러는 발생하지 않는 것처럼 보이는데, 왠지 모르게 이상하다"는 점입니다. 예를 들어 다음과 같은 경우입니다.

• 사용자가 한 마디 입력했을 때, Agent는 도대체 어떤 모델을 호출했는가?
• 도구(Tool)가 실행되었는가?
• 도구의 실행 중 어디가 느린가?
• Prompt와 Response가 기대한 대로 흐르고 있는가?
• 운영 환경에서 문제가 발생했을 때, 어떻게 빠르게 특정할 것인가?

이것이 가관측성 (Observability)으로 해결해야 할 문제입니다.

Microsoft Agent Framework에는 이미 OpenTelemetry 지원이 내장되어 있어, Agent의 실행 프로세스를 trace, log, metric 형식으로 출력할 수 있습니다. 즉, 직접 방대한 로그를 작성하지 않아도 Agent의 호출 체인에서 어떤 일이 일어났는지 확인할 수 있습니다. 공식 문서에서도 Agent Framework는 OpenTelemetry GenAI의 시맨틱 규약 (Semantic Conventions)에 기반하여 트레이스 (trace), 로그 (log), 메트릭 (metrics)을 출력한다고 설명되어 있습니다.

공식 AgentOpenTelemetry

샘플을 참고했습니다. 이 데모는 주로 세 가지 부분으로 구성되어 있습니다. 하나의 콘솔 Agent 앱, Agent Framework의 OpenTelemetry 계측 (Instrumentation), 그리고 로컬에서 텔레메트리 (telemetry) 데이터를 확인하기 위한 Aspire Dashboard입니다.

전체 흐름은 매우 간단합니다.

• Aspire Dashboard를 실행한다
• OTLP endpoint를 설정한다
• Agent 앱을 실행한다
• Dashboard에서 trace, 로그, 메트릭을 확인한다

공식 샘플에서는 Aspire Dashboard를 Docker로 실행하고, OTLP의 텔레메트리 포트를 공개합니다. 앱은 http://localhost:4317에 데이터를 전송하고, 브라우저에서 결과를 확인합니다.

C#에서는 Agent Framework의 가관측성은 주로 2개 계층이 있습니다.

• 1계층은 Chat Client에 OpenTelemetry를 부여하는 것
• 2계층은 Agent 자체에 OpenTelemetry를 부여하는 것

공식 문서의 샘플에서는 .UseOpenTelemetry(...)와 .WithOpenTelemetry(...)가 사용되었습니다. 전자는 보다 저수준(low-level)의 모델 호출에 가깝고, 후자는 Agent의 실행 프로세스에 가깝습니다.

단, 여기서 한 가지 주의할 점이 있습니다. 두 가지를 모두 활성화하면, 특히 민감한 데이터 (sensitive data)도 활성화한 경우 prompt, response 또는 컨텍스트 (context) 정보가 중복되어 보일 수 있습니다. 공식 문서에서도 실제 니즈에 따라 Chat Client 측만, 또는 Agent 측만 활성화하여 데이터 중복을 피할 것을 권장하고 있습니다.

// Copyright (c) Microsoft. All rights reserved.
using Azure.AI.OpenAI;
using Azure.Monitor.OpenTelemetry.Exporter;
...

로컬에서 디버깅할 때는 먼저 Aspire Dashboard를 실행합니다.

docker run -d --name aspire-dashboard `
-p 4318:18888 `
-p 4317:18889 `
...

그 후, 위의 C# 프로젝트를 실행하도록 설정합니다. 브라우저에서 http://localhost:4318에 접속합니다.

다음으로, 콘솔에서 Agent와 약간의 대화를 나누면 Aspire Dashboard에서 trace를 확인할 수 있습니다.

일괄 실행(Batch startup)에는 설정 확인, 앱 빌드, Dashboard 실행, 브라우저 실행, 콘솔 프로그램 실행까지 포함됩니다.

ApplicationInsights의 효과는 더욱 명확합니다.

설정 후 특히 유용한 정보는 다음과 같습니다.

Agent 호출 전체의 체인, 예를 들어 invoke_agent <agent_name>을 확인할 수 있습니다.

Agent가 모델을 호출한 경우, chat <model_name>과 같은 span이 표시됩니다.

Agent가 도구를 호출한 경우에도 execute_tool <function_name>이 표시됩니다.

그러한 span이 표시됩니다. 공식 문서에서도 이러한 span은 설정 후에 자동으로 생성된다고 설명되어 있습니다.

이는 Agent 디버깅(Debugging)에 매우 유용합니다. 예를 들어, 도구(Tool)가 느리거나, 모델(Model)이 느리거나, 특정 단계의 파라미터(Parameter)가 올바르지 않은 문제 등을 trace(추적)를 통해 직접 확인할 수 있습니다.

개발 환경에서는 디버깅을 용이하게 하기 위해 sensitive data(민감 데이터)를 활성화하여 prompt(프롬프트), response(응답), 함수 파라미터, 도구의 반환값(Return value)을 확인할 수 있습니다.

하지만, 운영 환경(Production environment)에서는 부주의하게 활성화하지 마십시오.

이러한 내용에는 사용자 입력, 업무 데이터, 나아가 기밀 정보가 포함될 가능성이 있습니다. 공식 문서에서도 sensitive data는 개발 환경 또는 테스트 환경에서만 활성화할 것을 명확히 권장하고 있습니다.

Agent 애플리케이션은 일반적인 API가 아닙니다. 모델 호출, 도구 호출, 다회차(Multi-round) 컨텍스트, 나아가 외부 서비스 의존성까지 포함됩니다.

따라서, Console.WriteLine만으로는 곧 한계에 부딪히게 됩니다.

Agent Framework에 내장된 OpenTelemetry 지원과 Aspire Dashboard를 결합하면, 로컬에서 Agent의 전체 실행 체인(Execution chain)을 직관적으로 확인할 수 있습니다. 개발 단계에서의 문제 격리(Troubleshooting)가 훨씬 수월해지며, 이후 Application Insights나 기타 관측(Observability) 플랫폼으로 연결하는 것도 자연스럽습니다.