스팬

스팬 (Spans)

AgentOps에서 활동을 조직화하는 기본 단위인 스팬(spans)의 종류와 계층 구조를 설명해요. 스팬을 만드는 여러 방법과 대시보드에서 보는 법, 그리고 좋은 습관까지 알아볼게요.

출처: 문서

본문

핵심 스팬 종류 (Core Span Types)

AgentOps는 모든 스팬을 특정 kind로 구성합니다.

스팬 계층 구조 (Span Hierarchy)

AgentOps의 스팬은 계층적으로 조직됩니다.

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

모든 스팬은 세션의 컨텍스트 안에 존재하며, 대부분의 스팬은 (세션 자신을 제외하고) 컨텍스트를 제공하는 부모 스팬을 가집니다.

스팬 속성 (Span Attributes)

AgentOps의 모든 스팬은 다음을 포함합니다.

• ID: 고유 식별자
• Name: 설명적인 이름
• Kind: 스팬의 종류 (SESSION, AGENT 등)
• Start Time: 스팬이 시작된 시각
• End Time: 스팬이 완료된 시각
• Status: 성공 또는 오류 상태
• Attributes: 추가 메타데이터를 담은 키-값 쌍

스팬 종류에 따라 특화된 속성이 있습니다.

LLM 스팬

LLM 스팬은 대규모 언어 모델과의 상호작용을 추적하며 다음을 포함합니다.

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

도구 스팬 (Tool Spans)

도구 스팬은 도구나 API의 사용을 추적하며 다음을 포함합니다.

• Tool Name: 사용된 도구의 이름
• Input: 도구에 제공된 데이터
• Output: 도구가 반환한 결과
• Duration: 도구 작업에 걸린 시간

작업/태스크 스팬 (Operation/Task Spans)

작업 스팬은 특정 함수나 태스크를 추적합니다.

• Operation Type: 수행된 작업의 종류
• Parameters: 작업에 전달된 입력 파라미터
• Result: 작업의 출력
• Duration: 작업에 걸린 시간

스팬 만들기 (Creating Spans)

AgentOps에서 스팬을 만드는 방법은 여러 가지가 있습니다.

데코레이터 사용

스팬을 만드는 권장 방법은 데코레이터를 사용하는 것입니다.

from agentops.sdk.decorators import agent, operation, session, workflow, task

@session
def my_workflow():
    agent_instance = MyAgent()
    return agent_instance.perform_task()

@agent
class MyAgent:
    @operation
    def perform_task(self):
        # Perform the task
        return result

자동 계측 (Automatic Instrumentation)

AgentOps는 auto_instrument=True(기본값)일 때 지원되는 프로바이더의 LLM API 호출을 자동으로 계측합니다.

import agentops
from openai import OpenAI

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

# Initialize the OpenAI client
client = OpenAI()

# This LLM call will be automatically tracked
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

대시보드에서 스팬 보기 (Viewing Spans in the Dashboard)

기록된 모든 스팬은 AgentOps 대시보드에서 볼 수 있습니다.

1. Timeline View: 스팬의 순서와 기간을 보여줌
2. Tree View: 스팬 사이의 계층 관계를 표시
3. Details Panel: 각 스팬에 대한 심층 정보 제공
4. Analytics: 스팬 전반의 통계를 집계

모범 사례 (Best Practices)

• 식별하기 쉽도록 스팬에 설명적인 이름을 사용하세요
• 세션, 에이전트, 작업으로 논리적 계층 구조를 만드세요
• 디버깅을 위해 관련 파라미터와 결과를 기록하세요
• 스팬 종류에 일관된 명명 규칙을 사용하세요
• 리소스 소비를 모니터링하기 위해 비용과 토큰 사용량을 추적하세요

더 알아보기 (Learn more)

• AgentOps 공식 문서