핵심 개념

핵심 개념 (Core Concepts)

AgentOps가 AI 에이전트 워크플로우를 어떻게 모니터링하고 분석하는지 이해하기 위한 핵심 개념을 소개해요. 세션(Session), 스팬 계층(Span Hierarchy), 에이전트(Agent), 태그(Tag) 등 기본 요소가 어떻게 함께 동작하는지 살펴볼게요.

출처: 문서

본문

AgentOps SDK 아키텍처

AgentOps는 최소한의 구현 노력으로 AI 에이전트 워크플로우에 대한 포괄적인 모니터링과 분석을 제공하도록 설계되었어요. SDK는 다음과 같은 핵심 설계 원칙을 따릅니다.

자동 계측 (Automated Instrumentation)

agentops.init()을 호출하면 SDK가 설치된 LLM 프로바이더를 자동으로 식별하고 해당 API 호출을 자동으로 계측해요. 이를 통해 AgentOps는 여러분의 코드와 LLM 프로바이더 사이의 상호작용을 캡처해 대시보드용 데이터를 수집하므로, 매 호출마다 수동으로 계측할 필요가 없습니다.

데코레이터 기반 선언적 트레이싱 (Declarative Tracing with Decorators)

데코레이터 시스템을 사용하면 기존 함수와 클래스에 최소한의 코드 변경만으로 트레이싱을 추가할 수 있어요. 데코레이터는 계층적 스팬(hierarchical spans)을 만들어 에이전트의 작업을 구조적으로 볼 수 있게 해주며, 모니터링과 분석에 활용됩니다.

OpenTelemetry 기반

AgentOps는 관측성 계측(observability instrumentation)을 위한 널리 채택된 표준인 OpenTelemetry 위에 구축되어 있어요. 이를 통해 텔레메트리 데이터를 수집·처리·내보내는 견고하고 표준화된 방법을 제공합니다.

세션 (Sessions)

세션은 에이전트와 사용자의 단일 상호작용을 나타내요. init 함수로 AgentOps를 초기화하면 세션이 자동으로 생성됩니다.

import agentops

# Initialize AgentOps with automatic session creation
agentops.init(api_key="YOUR_API_KEY")

기본적으로 모든 이벤트와 API 호출은 이 세션에 연결돼요. 더 고급 사용 사례가 필요하다면 세션 생성을 수동으로 제어할 수도 있습니다.

# Initialize without auto-starting a session
agentops.init(api_key="YOUR_API_KEY", auto_start_session=False)

# Later, manually start a session when needed
agentops.start_session(tags=["customer-query"])

스팬 계층 (Span Hierarchy)

AgentOps에서 활동은 스팬(spans)의 계층 구조로 구성됩니다.

  • SESSION: 워크플로우의 단일 실행에서 모든 활동을 담는 루트 컨테이너
  • AGENT: 특화된 능력을 가진 자율 에이전트를 나타냄
  • WORKFLOW: 관련 작업들의 논리적 그룹
  • OPERATION/TASK: 에이전트가 수행하는 특정 작업 또는 함수
  • LLM: 언어 모델과의 상호작용
  • TOOL: 에이전트가 도구나 API를 사용하는 것

이 계층 구조는 에이전트 실행의 완전한 트레이스를 만들어 냅니다.

SESSION
  ├── AGENT
  │     ├── OPERATION/TASK
  │     │     ├── LLM
  │     │     └── TOOL
  │     └── WORKFLOW
  │           └── OPERATION/TASK
  └── LLM (unattributed to a specific agent)

에이전트 (Agents)

Agent는 여러분의 애플리케이션에서 작업을 수행하는 컴포넌트를 나타내요. @agent 데코레이터를 사용해 에이전트를 만들고 추적할 수 있습니다.

from agentops.sdk.decorators import agent, operation

@agent(name="customer_service")
class CustomerServiceAgent:
    @operation
    def answer_query(self, query):
        # Agent logic here
        pass

LLM 이벤트

AgentOps는 지원되는 프로바이더의 LLM API 호출을 자동으로 추적하며, 다음과 같은 유용한 정보를 수집해요.

  • Model: 사용된 특정 모델 (예: "gpt-4", "claude-3-opus")
  • Provider: LLM 프로바이더 (예: "OpenAI", "Anthropic")
  • Prompt Tokens: 입력에 사용된 토큰 수
  • Completion Tokens: 출력에 사용된 토큰 수
  • Cost: 상호작용의 예상 비용
  • Messages: 프롬프트와 완성(completion) 콘텐츠
import agentops
from openai import OpenAI

# Initialize AgentOps
agentops.init(api_key="YOUR_API_KEY")

# Initialize the OpenAI client
client = OpenAI()

# This LLM call is automatically tracked
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the capital of France?"}]
)

태그 (Tags)

태그는 세션을 조직화하고 필터링하는 데 도움을 줘요. AgentOps를 초기화할 때나 세션을 시작할 때 태그를 추가할 수 있습니다.

# Add tags when initializing
agentops.init(api_key="YOUR_API_KEY", tags=["production", "web-app"])

# Or when manually starting a session
agentops.start_session(tags=["customer-service", "tier-1"])

호스트 환경 (Host Environment)

AgentOps는 에이전트가 실행되는 환경에 대한 기본 정보를 자동으로 수집해요.

  • Operating System: OS 타입과 버전
  • Python Version: 사용 중인 Python 버전
  • Hostname: 호스트 머신의 이름 (익명화됨)
  • SDK Version: 사용 중인 AgentOps SDK 버전

대시보드 뷰 (Dashboard Views)

AgentOps 대시보드는 에이전트의 성능을 시각화하고 분석할 수 있는 여러 방법을 제공합니다.

  • Session List: 필터링 옵션을 제공하는 전체 세션 개요
  • Timeline View: 기간과 관계를 보여주는 스팬의 시간순 표시
  • Tree View: 부모-자식 관계를 보여주는 스팬의 계층 표현
  • Message View: 프롬프트와 완성 콘텐츠를 포함한 LLM 상호작용 상세 뷰
  • Analytics: 세션과 작업 전반의 집계 메트릭

모두 종합하기 (Putting It All Together)

일반적인 구현은 다음과 같습니다.

import agentops
from openai import OpenAI
from agentops.sdk.decorators import agent, operation

# Initialize AgentOps
agentops.init(api_key="YOUR_API_KEY", tags=["production"])

# Define an agent
@agent(name="assistant")
class AssistantAgent:
    def __init__(self):
        self.client = OpenAI()
    
    @operation
    def answer_question(self, question):
        # This LLM call will be automatically tracked and associated with this agent
        response = self.client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": question}]
        )
        return response.choices[0].message.content

def workflow():
    # Use the agent
    assistant = AssistantAgent()
    answer = assistant.answer_question("What's the capital of France?")
    print(answer)

workflow()
# Session is automatically tracked until application terminates

더 알아보기 (Learn more)