AgentOps: watsonx Orchestrate를 사용하여 IBM Telemetry로 AI 에이전트 모니터링 및 거버넌스 구현

AI 에이전트가 더욱 정교하고 자율적으로 발전함에 따라, 신뢰성과 거버넌스를 보장하려면 에이전트의 동작, 성능 및 의사결정 프로세스를 이해하는 것이 매우 중요합니다. AgentOps는 프로덕션 환경에서 AI 에이전트를 모니터링, 관찰 및 관리하는 방식으로, 신뢰할 수 있는 에이전틱 AI 시스템을 구축하는 데 필요한 가시성을 제공합니다.

이 튜토리얼에서는 watsonx Orchestrate Developer Edition과 IBM® Telemetry를 설정하고 사용하여 AI 에이전트를 모니터링하고 거버넌스를 구현하는 방법을 단계별로 안내합니다. AI 에이전트의 관측 가능성을 활성화하고, 개별 LLM 호출부터 전체 다단계 워크플로까지 에이전트의 동작을 심층적으로 분석하는 방법을 알아봅니다.

이 튜토리얼을 완료하면 다음을 수행할 수 있습니다.

• watsonx Developer Edition을 로컬 환경에 설치하고 구성합니다.
• 포괄적인 에이전트 관측 가능성을 위해 IBM Telemetry를 활성화합니다.
• 외부 툴이 통합된 사전 구성된 AI 에이전트를 가져와 테스트합니다.
• 상세한 추적 정보, 태스크, 스팬 및 워크플로를 통해 에이전트의 동작을 분석합니다.
• 고급 분석 기능을 사용하여 문제를 디버깅하고 에이전트 성능을 최적화합니다.

IBM Telemetry는 AI 에이전트가 요청을 실행하는 방식을 자세히 수집하는 watsonx Orchestrate의 기본 관측 가능성 프레임워크입니다. 라우팅 결정과 프롬프트 구성부터 LLM 호출과 툴 호출에 이르기까지 에이전트 수명 주기의 모든 단계를 기록하여 에이전트 동작에 대한 완전한 가시성을 제공합니다.

IBM Telemetry를 사용하면 성능 지표를 추적하고, LLM 비용을 모니터링하며, 오류를 식별하고, 에이전트가 의도한 대로 작동하는지 확인할 수 있습니다. IBM Telemetry는 프로덕션 환경과 대규모 AI 시스템을 위해 설계된 엔터프라이즈급 관측 가능성을 제공합니다.

시작하기 전에 다음 필수 구성 요소가 시스템에 설치 및 구성되어 있는지 확인하세요.

• Python 3.8 이상(python --version 명령으로 확인)
• RAM 16GB 이상
• watsonx Orchestrate ADK를 통한 watsonx Orchestrate Developer Edition

이 가이드에는 ADK 설치 단계가 포함되어 있습니다.

• watsonx Orchestrate 계정 계정이 없는 경우 30일 무료 평가판을 사용할 수 있습니다.
• watsonx Orchestrate API 키, IBM Cloud 대시보드에서 생성

인증 단계는 이 가이드의 뒷부분에서 설명합니다.

시작하려면 https://github.com/IBM/ibmdotcom-tutorials.git을 HTTPS URL로 사용하여 GitHub 리포지터리를 클론합니다. 리포지터리를 클론하는 자세한 방법은 GitHub 설명서를 참조하세요.

원하는 통합 개발 환경(IDE)(예: Visual Studio Code)에서 리포지터리를 열고 이 튜토리얼의 프로젝트 폴더(wxo-agentops)를 찾습니다. 이 디렉터리에서 이후 단계를 진행하게 됩니다.

IBM watsonx Orchestrate Agent Development Kit(ADK)는 watsonx Orchestrate Developer Edition의 설치, 구성 및 관리를 간소화하는 CLI 툴입니다.

ADK를 사용하려면 기존 watsonx Orchestrate 환경에 연결해야 합니다. 아직 watsonx Orchestrate 계정이 없다면 30일 무료 평가판에 등록할 수 있습니다. 이미 계정이 있다면 이를 사용하여 ADK에 필요한 환경 자격 증명을 제공할 수 있습니다.

다음 단계에서는 종속성을 격리하는 데 권장되는 방법인 Python 가상 환경을 사용하여 설치하는 과정을 안내합니다. 다른 설치 방법과 자세한 지침은 ADK 시작하기 설명서를 참조하세요.

프로젝트 디렉터리에 새 Python 가상 환경을 생성합니다.

이 단계에서는 격리된 Python 환경이 포함된 .venv 폴더를 생성합니다.

활성화 명령은 운영 체제에 따라 다릅니다.

macOS 및 Linux

Windows

활성화되면 터미널 프롬프트가 가상 환경에서 작업 중임을 나타내도록 변경됩니다(일반적으로 프롬프트 앞부분에 (.venv)이 표시됨).

가상 환경을 활성화한 후 pip를 사용하여 ADK를 설치합니다.

이 명령은 ADK와 필요한 모든 종속성을 다운로드하여 설치합니다. 설치를 완료하는 데 몇 분 정도 걸릴 수 있습니다.

참고: 이전 버전의 ADK(>2.0)가 설치되어 있는 경우 pip install --upgrade ibm-watsonx-orchestrate을 실행합니다. 4b 단계의 문제 해결 절차를 수행해야 할 수도 있습니다.

ADK는 .env 파일을 사용하여 사용자 자격 증명을 인증하고 watsonx Orchestrate Developer Edition을 구성합니다. 필요한 환경 변수는 선택한 인증 방식에 따라 달라집니다. 이 튜토리얼에서는 시작하기에 가장 간단한 방법인 watsonx Orchestrate 계정 방식을 사용합니다.

다른 인증 방법과 자세한 구성 지침은 환경 파일 구성 설명서를 참조하세요.

wxo-agentops 디렉터리에서 제공된 템플릿을 복사하여 .env 파일을 생성합니다.

텍스트 편집기에서 .env 파일을 열고 다음 두 가지 필수 필드를 구성합니다.

• WO_INSTANCE 이 URL은 watsonx Orchestrate 인스턴스의 URL입니다. watsonx Orchestrate 계정에 로그인한 후 인스턴스 세부 정보로 이동하면 이 정보를 확인할 수 있습니다. 프로필 아이콘 > Settings를 클릭한 다음 API details 탭을 선택합니다. API 시작 방법에 대한 자세한 내용은 watsonx Orchestrate 설명서를 참조하세요.

URL 형식은 다음과 같습니다.

서비스 인스턴스 URL을 복사하여 .env 파일의 템플릿 값을 해당 URL로 바꿉니다. 리전(예: us-south)은 사용자의 지리적 위치에 따라 달라집니다.

• WO_API_KEY 이 키는 IBM Cloud 서비스에 대한 연결을 인증하는 watsonx Orchestrate 애플리케이션 프로그래밍 인터페이스(API) 키입니다. 이 키는 IBM Cloud 계정 대시보드에서 생성하거나 확인할 수 있습니다. <your-api-key>을(를) 실제 API 키로 바꾸세요. API 키를 생성하는 단계별 방법은 시작하기 설명서를 참조하세요.

API 키를 안전하게 보관하고 버전 관리 시스템에 커밋하지 마세요.우발적인 노출을 방지하기 위해 .env 파일은 .gitignore에 이미 포함되어 있어야 합니다.

이제 watsonx Orchestrate Developer Edition을 설치할 준비가 되었습니다. 이를 설치하면 컴퓨터에서 watsonx Orchestrate 서버의 로컬 인스턴스가 실행됩니다. 이 단계에서는 IBM Telemetry도 활성화되어 관측 가능성 기능을 바로 사용할 수 있습니다.

설치 명령 이해하기

ADK는 전체 설치 과정을 처리하는 단일 명령을 제공합니다.

이 명령의 기능을 살펴보겠습니다.

• orchestrate server start watsonx Orchestrate Developer Edition 서버를 초기화하고 시작합니다.
• -e <path-.env-file> 자격 증명이 포함된 구성 파일을 지정합니다.
• --with-ibm-telemetry IBM Telemetry의 기본 관측 가능성 프레임워크를 활성화합니다.

wxo-agentops 디렉터리에서 다음 명령을 실행합니다.

다음 명령은 서버 환경을 초기화하여 watsonx Orchestrate Developer Edition 서버를 시작합니다. orchestrate server start -e <path-.env-file> --with-ibm-telemetry 플래그를 추가하면 기본 관찰 가능성 프레임워크인 IBM Telemetry가 활성화됩니다.

IBM Telemetry와 함께 watsonx Orchestrate 서버를 설치하려면 다음 명령을 실행합니다.

이 명령은 다음 구성 요소에 대해 ADK가 관리하는 내부 컨테이너를 생성합니다.

• watsonx Orchestrate 서버
• PostgreSQL 및 Redis 데이터베이스
• IBM Telemetry 서비스
• 지원 종속성

ADK는 이러한 컨테이너가 http://localhost:3000에서 서로 통신할 수 있도록 가상 네트워크를 자동으로 구성합니다.

설치 과정은 몇 분 정도 걸릴 수 있으며, 특히 처음 실행할 때는 필요한 이미지를 다운로드하므로 시간이 더 소요될 수 있습니다. 설치가 성공하면 다음 예와 유사한 출력이 표시됩니다.

이 메시지가 표시되면 설치가 성공한 것입니다. 이제 IBM Telemetry가 포함된 로컬 watsonx Orchestrate 환경이 실행 중입니다.

설치에 실패하거나 설치가 중단되면 다음 단계를 시도해 보세요.

1. 서버 재설정:

이 명령은 watsonx Orchestrate용으로 생성된 모든 컨테이너를 중지하고 제거하여 초기 상태에서 다시 시작할 수 있도록 합니다.

2. 설치 다시 시작:

재설정을 완료한 후 시작 명령을 다시 실행합니다.

3. 서버 로그 및 컨테이너 상태 확인:

Orchestrate 서버의 서비스 로그를 확인하여 경고나 오류가 있는지 확인할 수 있습니다.

앞의 단계가 작동하지 않으면 orchestrate server purge을(를) 실행하여 서버를 재설정하고 서버 환경을 완전히 제거한 다음 다시 설치하세요.

watsonx Orchestrate 서버를 성공적으로 설치했다면 이제 로컬 환경을 활성화하고 AI 에이전트와 상호 작용할 채팅 인터페이스를 실행해야 합니다.

watsonx Orchestrate ADK는 여러 환경(로컬, 개발, 프로덕션 등)을 지원합니다. 생성한 로컬 환경을 명시적으로 활성화해야 합니다.

환경이 활성화되었다는 확인 메시지가 표시됩니다.

이렇게 하면 이후 실행하는 모든 ADK 명령의 기본 컨텍스트가 로컬 환경으로 설정됩니다. 이제 작업하는 모든 에이전트, 툴 및 구성은 이 로컬 인스턴스를 대상으로 합니다.

다음 명령을 사용하여 watsonx Orchestrate 채팅 UI 서비스를 시작합니다.

이 명령은 웹 기반 채팅 인터페이스를 초기화하고 기본 브라우저에서 자동으로 엽니다. 다음과 유사한 출력이 표시됩니다.

채팅 인터페이스를 통해 AI 에이전트와 손쉽게 상호 작용할 수 있습니다. 브라우저가 자동으로 열리지 않으면 다음 주소로 직접 이동합니다. http://localhost:3000/chat-lite.

채팅 인터페이스가 로드되면 바로 상호 작용할 수 있는 빈 채팅 창이 표시됩니다. 이 단계에서는 아직 에이전트를 가져오지 않았으므로 인터페이스에는 거의 아무 내용도 표시되지 않습니다. 이는 정상적인 동작이며, 다음 단계에서 첫 번째 에이전트를 추가합니다.

환경 설정이 완료되었으므로 이제 IBM Telemetry의 모니터링 기능을 보여주는 사전 구성된 AI 에이전트를 가져오겠습니다. 이 날씨 에이전트는 외부 API 툴을 사용하여 실시간 날씨 데이터를 가져오므로 관측 가능성과 분석 기능을 직접 확인할 수 있는 실용적인 예제를 제공합니다.

날씨 에이전트는 다음과 같은 이유로 시작하기에 적합합니다.

• 툴 사용 방식 시연: 에이전트가 외부 API를 호출하는 방식을 보여줍니다.
• 명확하게 관측 가능한 동작 제공: 모든 요청이 예측 가능한 패턴에 따라 수행됩니다.
• 의미 있는 Telemetry 데이터 생성: IBM Telemetry에서 분석할 수 있는 풍부한 추적 데이터를 생성합니다.
• 오류 시나리오 포함: Telemetry가 오류를 처리하는 방식을 이해하는 데 도움이 됩니다.
• 자동화 구현 방식 제시: 에이전트 작업을 통해 수동으로 데이터를 조회할 필요가 없어집니다.

프로젝트 루트 디렉터리(wxo-agentops)에서 Weather Agent 폴더로 이동하세요.

이 디렉터리에는 두 개의 YAML 구성 파일이 있습니다.

• get_weather.yaml 날씨 API 툴을 정의합니다.
• weather_agent.yaml 이 툴을 사용하는 에이전트를 정의합니다.

툴은 에이전트가 특정 작업을 수행하기 위해 호출할 수 있는 재사용 가능한 기능입니다. 먼저 get_weather 툴을 가져옵니다.

--kind openapi 플래그는 이 툴이 인터페이스를 정의하기 위해 OpenAPI 사양을 사용함을 나타냅니다. 툴을 성공적으로 가져왔다는 확인 메시지가 표시됩니다.

이제 이 툴을 사용할 에이전트를 가져옵니다.

이 명령은 로컬 watsonx Orchestrate 환경에 Weather Agent를 등록합니다. 이 에이전트에는 다음 항목이 미리 구성되어 있습니다.

• 날씨 데이터를 해석하는 방법에 대한 지침
• get_weather 툴을 호출할 권한
• 잘못된 위치가 입력된 경우의 대체 동작

채팅 인터페이스가 실행 중인 브라우저로 돌아갑니다. 새로 가져온 에이전트를 보려면 페이지를 새로 고쳐야 할 수 있습니다.

에이전트 드롭다운 메뉴(일반적으로 채팅 인터페이스 상단에 있음)를 클릭한 다음 목록에서 Weather_Agent를 선택합니다.

Weather Agent를 선택한 상태에서 Telemetry 데이터를 생성하기 위해 다음과 같은 질문을 해보세요.

예시 질문:

• "뉴욕의 날씨는 어떤가요?"
• "런던의 현재 기온을 알려주세요."
• "도쿄의 날씨는 어떤가요?"
• "지금 시애틀에 비가 오고 있나요?"

에이전트는 각 요청을 다음과 같은 순서로 처리합니다.

1. 질문 이해
2. 위치 추출
3. 적절한 좌표를 사용하여 get_weather 툴 호출
4. 날씨 데이터 해석
5. 자연어로 응답 생성

Weather Agent와 수행하는 모든 상호 작용은 IBM Telemetry에 기록됩니다. 시스템은 다음 정보를 기록합니다.

• 전체 대화 컨텍스트
• 모든 LLM 호출 및 사용된 토큰
• 입력과 출력이 포함된 툴 호출
• 라우팅 결정 및 워크플로 단계
• 실행 시간 및 성능 지표
• 발생한 모든 오류 및 예외
• 외부 제공자와의 상호 작용 및 응답 시간

다음 단계에서는 이 Telemetry 데이터를 자세히 살펴보면서 에이전트가 실제로 어떻게 동작하는지 확인합니다.

이제 이 튜토리얼의 핵심 단계인 IBM Telemetry를 사용하여 에이전트의 동작을 심층적으로 살펴보겠습니다. IBM Telemetry는 에이전트가 요청을 처리하는 전 과정을 이해할 수 있도록 다양한 보기와 분석 툴을 제공합니다.

브라우저를 열고 https://localhost:8765/?serviceName=wxo-server(으)로 이동합니다. 이 인터페이스에서는 세션 리플레이를 통해 이전 에이전트 상호 작용을 다시 확인하며 분석할 수 있습니다.

참고: URL은 https를 사용하지만, 이 Space는 로컬 개발 환경이므로 브라우저에 자체 서명된 인증서에 대한 보안 경고가 표시될 수 있습니다. 이 메시지는 정상적인 동작이며, 로컬 환경에서는 무시하고 계속 진행해도 안전합니다.

로그인 화면이 표시되면 로컬 세션을 식별하기 위한 이름을 입력한 다음 Login을 클릭합니다.

IBM Telemetry 기본 대시보드가 표시됩니다.

대시보드에는 최근 추적 목록이 표시되며, 각 추적은 에이전트와의 단일 사용자 상호 작용을 나타냅니다. Trace and Group Selection 패널에서 첫 번째 추적을 클릭하여 Weather Agent와의 가장 최근 채팅에 대한 상세 분석 정보를 확인합니다.

이 단계에서는 에이전트 동작을 분석하는 중심 화면인 Agent Analytics로 이동합니다.

Agent Analytics 화면에서는 선택한 추적에 대한 다음 개요 정보를 제공합니다.

• 요약 통계: 총 실행 시간, 토큰 사용량, 비용 추정치 및 벤치마킹 데이터
• 에이전트 정보: 요청을 처리한 에이전트
• 사용자 질의: 사용자가 입력한 원래 질문
• 응답 미리보기: 에이전트의 최종 응답
• 상태 표시기: 성공, 경고 또는 오류

이 상위 수준 보기에서는 에이전트가 예상대로 동작했는지와 얼마나 효율적으로 실행되었는지를 즉시 파악할 수 있습니다.

Tasks 섹션은 에이전트 동작을 분석할 때 가장 많이 활용하게 되는 영역입니다. 요청을 처리하는 동안 에이전트가 수행한 모든 작업(LLM 호출, 툴 호출, 라우팅 결정 및 출력 생성)을 단계별 타임라인으로 시각화하여 보여줍니다.

Tasks는 에이전트가 실제로 워크플로를 실행한 방식을 반영하도록 계층 구조로 구성되어 있어 작업 순서와 작업 간의 관계를 쉽게 파악할 수 있습니다.

watsonx Orchestrate 에이전트 요청의 일반적인 실행 경로를 살펴보겠습니다. Weather Agent의 추적은 다음 예와 유사한 구조로 표시됩니다.

이 워크플로는 단일 사용자 질의의 전체 처리 과정을 보여줍니다. 각 Task의 의미는 다음과 같습니다.

• 0:_ROOT 모든 하위 Task를 포함하는 최상위 스팬입니다. 전체 에이전트 실행을 담고 있는 최상위 폴더라고 생각하면 됩니다. 요청이 시스템에 들어온 시점부터 최종 응답이 전달될 때까지 전체 추적의 시작 시간과 종료 시간을 정의합니다.

루트 Task의 실행 시간은 사용자가 실제로 경험한 전체 지연 시간을 보여주므로 이 정보는 매우 중요합니다. 이 값이 너무 크다면 하위 Task를 분석하여 병목 지점을 찾을 수 있습니다.

• 0.0:agent_style_router 라우팅 Task는 어떤 에이전트가 메시지를 처리할지 결정하고 요청을 적절한 처리 방식으로 분류합니다. 라우터는 들어오는 요청을 분석하여 대화형 처리, 툴 기반 실행, 검색 증강 생성(RAG) 또는 멀티 에이전트 오케스트레이션 중 어떤 방식으로 처리할지를 결정합니다.

라우터는 적절한 다운스트림 로직이 호출되도록 합니다. 요청이 잘못 라우팅되는 경우에는 이 단계에서 문제를 확인할 수 있습니다.

• 0.1:agent 전체 요청을 오케스트레이션하는 기본 에이전트 실행 컨텍스트입니다. 이 Task는 시스템 상호 작용, 대화 기록 및 툴 응답을 바탕으로 프롬프트를 구성합니다. 오케스트레이션 규칙과 정책을 적용하고 LLM에 전달할 입력을 준비합니다. 이 Task는 어떤 유형의 LLM 호출을 수행할지 결정합니다.

이 단계에서 오케스트레이션의 핵심 로직이 수행됩니다. 에이전트 Task는 LLM이 적절한 판단을 내리는 데 필요한 모든 컨텍스트를 전달받도록 합니다.

• 0.1.0:WatsonxChatModel.chat LLM이 전체 프롬프트를 전달받아 툴을 호출할지, 추가 정보를 요청할지, 또는 직접 응답을 생성할지를 결정하는 실제 LLM 호출 단계입니다. 텍스트 응답 또는 구조화된 툴 호출 형태로 결과를 생성합니다.

이 단계에서는 모델이 정보를 처리하고 의사결정을 수행합니다. 토큰 사용량, 지연 시간 및 응답 품질은 모두 이 Task의 영향을 받습니다. 에이전트의 응답 속도가 느리거나 비용이 많이 발생한다면 대부분 이 단계가 주요 원인입니다.

• 0.2:answer 마지막 단계에서는 LLM의 출력을 전달할 수 있는 형식으로 변환합니다. 이 Task는 LLM의 원시 출력을 최종 응답 형식으로 변환하고 필요한 후처리 및 서식 규칙을 적용합니다. 마지막으로 응답을 채팅 인터페이스에 전달합니다.

이 Task는 사용자에게 올바른 형식의 응답이 전달되도록 합니다. 응답이 잘리거나 형식이 올바르지 않은 경우에는 이 단계에서 원인을 확인할 수 있습니다.

Task 워크플로 요약

전체 워크플로를 요약하면 다음과 같습니다.

1. Router가 요청 처리 방식을 결정합니다.
2. Agent가 컨텍스트와 오케스트레이션 로직을 준비합니다.
3. LLM이 응답 또는 툴 호출을 생성합니다.
4. Answer가 최종 출력을 형식에 맞게 구성하여 반환합니다.

이 전체 워크플로는 ROOT 요청 컨테이너 아래에 포함되어 있어 에이전트의 실행 과정을 처음부터 끝까지 전체적으로 파악할 수 있습니다. 이러한 수준의 관찰 가능성은 대규모로 에이전트 운영과 복잡한 파이프라인을 관리하는 MLOps 및 DevOps 팀에 필수적입니다.

계층 구조의 각 Task에는 Task가 사용한 입력과 생성한 결과에 대한 상세 메타데이터를 제공하는 다음 세 가지 속성 범주가 있습니다.

1. Input attributes: Task가 실행되기 전에 받은 모든 정보(메시지, 툴 응답, 시스템 지침 및 내부 상태)를 보여줍니다.

예: WatsonxChatModel.chat Task의 입력 속성에는 시스템 지침, 대화 기록, 해석이 필요한 모든 툴 결과를 포함하여 완전히 생성된 프롬프트가 포함됩니다.

2. Output attributes: LLM 완료 결과, 툴 호출 및 의사결정 등 Task가 생성한 결과를 보여줍니다.

예: 동일한 WatsonxChatModel.chat Task는 자연어 응답 또는 get_weather(latitude=40, longitude=-74)과 같은 구조화된 툴 호출을 출력할 수 있습니다 .

3. General attributes: 토큰 사용량, 실행 시간 정보, 고유 ID와 같은 식별자 및 모델 정보 등의 Telemetry 메타데이터를 제공합니다.

예: Task에서 입력 토큰 450개와 출력 토큰 120개를 사용했고, 실행 시간은 1.2초였으며, ibm/granite-3.1-8b-instruct model을 사용한 것을 확인할 수 있습니다 .

Task 속성 활용하기

이러한 속성을 함께 살펴보면 모델이 어떤 정보를 바탕으로 어떤 판단을 내렸으며 어떻게 응답했는지를 전체적으로 이해할 수 있습니다.

이러한 수준의 상세 정보는 디버깅, 최적화 및 검증에 매우 유용합니다.

각 Task에는 실행 방식과 관련된 성능 및 비용 지표가 포함되어 있습니다. 이러한 지표는 에이전트 성능을 정량적으로 보여줍니다.

주요 지표는 다음과 같습니다.

• 총 실행 시간: Task 시작부터 완료까지 걸린 시간
• LLM 호출 횟수: 언어 모델이 호출된 횟수
• 툴 호출 횟수: 외부 툴이 호출된 횟수
• 토큰 사용량: 입력 토큰, 출력 토큰 및 총 사용 토큰 수
• 비용 추정치: 토큰 사용량을 기준으로 계산한 예상 비용(요금 데이터가 제공되는 경우)
• 하위 Task 분포: 작업이 하위 Task에 어떻게 분배되었는지

이러한 지표를 활용하면 성능을 최적화하고 에이전트 동작을 디버깅할 수 있습니다. 또한 병렬 처리하거나 캐시를 적용할 수 있는 성능 저하 Task를 식별하는 데도 도움이 됩니다. 이 보기는 확장에 필요한 리소스 요구 사항을 파악하고 토큰 사용량을 추적하여 비용을 관리할 수 있으므로 용량 계획을 수립하는 데 매우 중요합니다.

예를 들어 추적 하나를 완료하는 데 8초가 걸렸지만 LLM 호출에는 0.5초만 소요되었다면 병목 현상은 다른 곳(대개 툴 실행 또는 네트워크 지연)에 있다는 것을 알 수 있습니다.

Tasks가 에이전트의 논리적인 워크플로를 보여준다면, Spans는 실행 중 내부에서 수행되는 시스템 수준의 작업을 보여줍니다. Spans 탭을 클릭하면 플랫폼이 각 요청을 처리하는 과정에서 내부적으로 수행하는 작업을 확인할 수 있습니다.

Spans는 오케스트레이션 프레임워크(이 경우 wxo-server 내부에서 실행되는 오픈 소스 프레임워크인 LangGraph)가 기록한 저수준 실행 단계에 대한 가시성을 제공합니다. 각 Span은 다음과 같은 개별 작업을 나타냅니다.

• 요청을 올바른 에이전트로 라우팅(agent_style_router )
• 에이전트를 호출하고 컨텍스트 초기화(agent.task )
• 템플릿을 사용하여 프롬프트와 컨텍스트 생성(ChatPromptTemplate.task )
• 생성된 프롬프트로 LLM 호출(WatsonxChatModel.chat )
• 사용자에게 결과 반환(answer.task )

작업은 에이전트 실행의 논리적 단계(에이전트가 달성하려는 목표)를 보여주는 반면, 스팬은 기술적 단계 (시스템이 이를 달성하는 방법)를 보여줍니다. 이러한 두 가지 보기를 통해 전체적인 흐름을 이해하는 동시에 저수준 디버깅도 수행할 수 있습니다.

예: 0.1:agent과 같은 단일 Task에는 데이터베이스 질의, 캐시 조회, 구성 로딩을 나타내는 여러 Span이 포함될 수 있습니다. 이러한 작업은 에이전트의 실행을 지원하기 위해 백그라운드에서 수행됩니다.

각 Span에는 추가 메타데이터와 컨텍스트를 제공하는 tags가 포함되어 있습니다. 이러한 tags는 필터링, 디버깅 및 에이전트 성능 분석에 필수적입니다.

일반적인 Span 태그는 다음과 같습니다.

• 에이전트 식별:  agent_id , agent_name
• 세션 추적:  thread_id , session_id , conversation_id
• 워크플로 컨텍스트: step_number ,  workflow_path , parent_span_id
• 성능 데이터:  token_count ,  duration_ms , model_name
• 요청 세부 정보:  tool_calls ,  input_preview , output_preview

Spans를 활용하면 지연 시간의 원인을 추적하고, 어떤 내부 구성 요소에서 오류가 발생했는지 확인하여 장애를 분석하며, 태그를 기준으로 Span을 필터링해 추세를 파악하고, 세션 ID를 사용해 여러 추적에 걸쳐 Span을 연결하여 상호 참조할 수 있습니다.

예를 들어 에이전트가 간헐적으로 응답하지 않는 경우, 실행 시간을 기준으로 Span을 필터링하면 어떤 내부 작업이 예상보다 오래 걸리는지 확인할 수 있습니다. 이를 통해 데이터베이스 질의나 외부 서비스에 대한 네트워크 호출과 같은 병목 지점을 파악할 수 있습니다.

Workflows 탭에서는 에이전트 워크플로의 전체 실행 구조를 보여주는 Runnables Tree라는 계층 구조 시각화를 제공합니다. 이 보기는 복잡한 멀티 에이전트 시스템과 중첩된 실행 패턴을 이해하는 데 특히 유용합니다.

watsonx Orchestrate 프레임워크에서 runnable은 실행 가능한 작업 단위(Task)를 의미합니다. Runnable은 다음과 같은 형태가 될 수 있습니다.

• Simple operations: 단일 LLM 호출 또는 툴 호출
• Composite workflows: 여러 Runnable을 연결한 워크플로
• Conditional branches: 조건에 따라 달라지는 실행 경로
• Parallel executions: 여러 Runnable을 동시에 실행하는 방식

Runnable Tree는 부모-자식 관계를 표시하여 다음과 같은 내용을 쉽게 확인할 수 있습니다.

• 어떤 Task가 다른 Task를 실행하는지: 실행 체인을 따라 확인
• 병렬 실행과 순차 실행: 워크플로의 동시 실행 방식 파악
• 분기 로직: 결정에 따라 실행 경로가 어떻게 달라지는지 확인
• 워크플로 깊이: 에이전트 로직이 얼마나 깊게 중첩되어 있는지 확인

Weather Agent와 같은 단순한 에이전트에서는 워크플로 보기가 Task 보기와 거의 동일한 구조를 보여줍니다. 하지만 다음과 같은 경우에는 워크플로 보기가 매우 유용합니다.

• Multi-agent systems: 하나의 Task를 수행하기 위해 여러 전문 에이전트가 협업하는 시스템
• Complex orchestration: 에이전트가 여러 툴이나 하위 에이전트 중에서 동적으로 선택하는 방식
• Iterative refinement: 조건이 충족될 때까지 단계를 반복 수행하는 에이전트
• Conditional routing: 중간 결과에 따라 워크플로가 분기되는 방식
• Scalable architectures: 실제 환경의 부하를 효율적으로 처리할 수 있도록 워크플로를 설계하는 방식

예를 들어, 먼저 질의에 웹 검색이 필요한지 확인한 다음 계산기 툴과 데이터베이스 질의 툴 중 하나를 선택하여 사용하고, 마지막으로 결과를 검증한 후 응답하는 에이전트를 생각해 보겠습니다. Runnable Tree는 이러한 전체 분기 구조를 한눈에 보여줍니다.

다음과 같은 방법으로 트리와 상호 작용할 수 있습니다.

• Expanding/collapsing nodes: 특정 워크플로 섹션에 집중할 수 있도록 노드를 펼치거나 접기
• Clicking nodes: 상세한 Task 정보로 이동
• Following execution paths: 데이터가 워크플로를 통해 어떻게 흐르는지 추적
• Identifying bottlenecks: 워크플로의 비효율이 발생하는 지점 식별

이러한 시각화를 활용하면 텍스트 로그나 추적 데이터만으로 분석하는 것보다 워크플로를 훨씬 쉽게 디버깅할 수 있습니다.

Eval(evaluation) 탭에서는 에이전트 실행의 정확성과 신뢰성을 측정하는 품질 보증 및 모니터링 보기를 제공합니다. 이 단계에서는 무슨 일이 발생했는지를 확인하는 수준에서 나아가 얼마나 잘 수행되었는지를 평가하게 됩니다.

Eval 탭에는 가드레일을 기반으로 품질을 평가한 결과가 표시됩니다.

• Task success: 완료된 Task와 실패한 Task
• Output quality: 출력이 예상 결과 또는 품질 기준에 부합하는지 여부
• Performance scores: 성공 수준을 나타내는 정량적 지표
• Error analysis: 오류의 유형 및 심각도 분석
• Use case validation: 에이전트 동작이 의도한 사용 사례에 부합하는지 여부

평가를 통해 에이전트가 얼마나 일관되게 올바른 결과를 생성하는지 추적하여 신뢰성을 모니터링하고, 변경 사항으로 인해 에이전트 성능이 저하되는 시점을 파악하며, 개선 사항의 우선순위를 정하고, 프로덕션 환경에 배포하기 전에 에이전트가 올바르게 동작하는지 검증하여 신뢰도를 높일 수 있습니다.

평가 결과를 활용하여 알림을 설정하고, 개선 사항을 추적하며, 패턴을 식별하고, 피드백을 바탕으로 프롬프트나 툴을 개선하는 방향으로 개발을 진행할 수 있습니다.

예를 들어 날씨 질의의 15%가 평가를 통과하지 못하는 경우, 해당 추적을 조사하여 입력 처리 문제인지, API 오류인지, 또는 응답 형식이 잘못되었는지 원인을 파악할 수 있습니다.

Issues 탭에서는 워크플로 실행 중 발생한 모든 문제를 한곳에서 확인할 수 있습니다. 에이전트 오류나 예상치 못한 동작을 디버깅할 때 가장 먼저 확인해야 하는 탭입니다.

Issues 탭에는 다음과 같은 문제가 표시됩니다.

• Failed API calls: 오류를 반환한 외부 서비스
• Tool execution failures: 비정상 종료되거나 시간 초과된 툴
• Missing inputs: 필요한 시점에 사용할 수 없는 필수 입력 데이터
• Model exceptions: 토큰 한도 초과나 잘못된 입력 등 LLM 오류
• Validation errors: 예상된 형식에 맞지 않는 데이터
• Timeout errors: 시간 제한을 초과한 작업
• Unhandled runtime failures: 에이전트 코드에서 처리되지 않은 런타임 오류

위 스크린샷에서는 날씨 API가 424(Failed Dependency) 또는 404(Not Found) 오류를 반환하면서 발생한 Tool Error를 확인할 수 있습니다. Issues 탭에는 다음 정보가 표시됩니다.

1. 오류 유형: "Tool Error"
2. 오류가 발생한 툴: get_weather
3. 오류 응답: 오류 내용을 보여주는 전체 API 응답
4. 직접 링크: 클릭하면 오류가 발생한 Task로 바로 이동

이 방식을 사용하면 로그나 추적 데이터를 일일이 확인하지 않아도 무엇이 잘못되었는지 쉽게 파악할 수 있습니다.

Issues 탭은 개별 Task를 하나씩 확인하지 않아도 모든 오류를 한곳에 모아 보여주므로 특히 유용합니다. 또한 전체 오류 세부 정보와 관련 데이터를 함께 제공하여 충분한 컨텍스트를 제공하며, 심각도 수준을 통해 신속하게 문제를 분류하고 우선적으로 해결해야 할 문제를 판단할 수 있습니다. 원본 Task로 연결되는 직접 링크를 사용하면 한 번의 클릭만으로 문제가 발생한 정확한 실행 지점으로 이동할 수 있습니다.

Trajectory 탭에서는 사용자와 에이전트가 호출한 툴 간의 상호 작용을 대화 형식으로 시간순에 따라 확인할 수 있습니다. 이 보기는 에이전트 동작의 전체적인 컨텍스트와 흐름을 이해하는 데 매우 유용합니다.

Trajectory 보기를 사용하면 에이전트가 요청을 처음부터 끝까지 어떻게 처리하는지 정확하게 확인할 수 있어 에이전트 동작 전반에 대한 가시성을 확보할 수 있습니다. 툴이 올바른 매개변수로 호출되고 적절한 응답을 반환하는지 확인하여 툴 통합을 검증할 수 있습니다. 예상과 다른 응답을 디버깅할 때는 Trajectory를 통해 로직이 예상과 달라진 지점을 추적할 수 있습니다. 또한 여러 대화 턴에 걸쳐 컨텍스트가 어떻게 축적되는지 분석하면서 워크플로가 자연스럽게 전개되는 과정을 확인할 수 있습니다. Trajectory는 디버깅뿐 아니라 문서화 용도로도 활용할 수 있으며, 올바르게 동작한 사례를 기록하여 팀원과 공유하거나 향후 개발을 위한 참고 사례로 활용할 수 있습니다. 이 보기는 다양한 시나리오에서 에이전트의 적응 능력을 검증해야 하는 생성형 AI 개발 팀에 특히 유용합니다.

이제 스크린샷에 표시된 Weather Agent의 Trajectory를 살펴보겠습니다.

1. 사용자 질의

대화는 뉴욕시의 날씨에 대한 명확하고 구체적인 요청으로 시작됩니다.

2. 에이전트가 툴을 호출합니다.

에이전트는 외부 데이터가 필요하다는 것을 인식하고 날씨 툴을 호출합니다.

이 예에서는 에이전트가 뉴욕시의 대략적인 좌표를 올바르게 식별하고, API 요청을 적절한 형식으로 구성했으며, 현재 날씨를 조회하기 위한 올바른 플래그를 설정했음을 확인할 수 있습니다.

IBM Telemetry는 이 결과를 원시 JSON 형식과 보기 좋게 구문 분석된 확장 가능한 트리 보기 형식으로 모두 표시합니다.

3. 툴이 데이터를 반환합니다.

날씨 API는 구조화된 날씨 데이터를 반환합니다.

이 예에서는 툴이 데이터를 성공적으로 가져왔으며, 응답이 예상된 스키마를 따르고 필요한 모든 필드를 포함하고 있음을 확인할 수 있습니다. 툴의 원시 응답을 직접 확인할 수 있는 기능은 에이전트가 툴의 출력을 잘못 해석하는 문제를 디버깅하는 데 매우 중요합니다.

4. 에이전트가 결과를 요약합니다.

마지막으로 에이전트는 구조화된 데이터를 처리하여 자연스러운 응답을 생성합니다.

에이전트는 기온과 날씨 코드를 정확하게 추출하고, 구조화된 데이터를 자연어로 변환했습니다. 응답은 간결하며 사용자의 질문에 적절하게 답합니다.

Trajectory 탭에서는 역할별 필터링도 지원하므로 사용자 메시지, 에이전트 메시지 또는 툴 상호 작용만 선택하여 볼 수 있습니다. 또한 긴 대화의 일부를 펼치거나 접어 필요한 내용에 집중할 수 있습니다. 추가 분석이나 디버깅이 필요한 경우 데이터를 JSON 형식으로 내보내거나 Trajectory 단계에서 연결된 Task로 이동하여 해당 세부 정보를 확인할 수 있습니다.

축하합니다! watsonx Orchestrate와 IBM Telemetry를 성공적으로 설정하고 AI 에이전트의 동작을 심층적으로 모니터링하고 분석하는 방법을 익혔습니다. IBM Telemetry는 여러 계층의 가시성을 제공하여 AI 에이전트가 어떻게 추론하고, 의사결정을 내리며, 작업을 수행하는지 전체적으로 관측할 수 있도록 지원합니다. 지금까지 살펴본 기능은 프로덕션 환경에서 에이전트 운영의 라이프사이클을 효과적으로 관리하거나 사용자 환경의 다른 에이전트 프레임워크와 통합하는 데 매우 중요합니다.

문제가 발생하거나 궁금한 사항이 있으면 문서를 확인하세요. 대부분의 일반적인 문제는 문제 해결 가이드에서 확인할 수 있습니다. 다른 사용자들도 비슷한 문제를 겪었는지 GitHub Issues에서 확인할 수도 있습니다.

IBM Telemetry와 같은 플랫폼을 통한 에이전트 모니터링은 AgentOps를 위한 강력한 생태계를 구축했으며, 자율 에이전트가 SDK, 툴 및 외부 API를 통합하는 더욱 복잡한 작업을 수행하게 되면서 이러한 기능의 중요성은 더욱 커지고 있습니다. 에이전트 동작에 대한 이러한 가시성을 통해 더욱 신뢰할 수 있고, 효율적이며, 믿을 수 있는 AI 시스템을 구축할 수 있습니다.