코어 개념

코어 개념 (Core Concepts)

AgentOps가 동작하는 기반 요소와 운영 원리를 깊이 있게 살펴보는 문서예요. AgentOps SDK가 어떤 구조로 구성되어 있고, 각 구성 요소가 어떻게 동작하는지 함께 차근차근 알아볼게요.

출처: 문서

본문

AgentOps의 기본 요소와 운영 동작을 심층 탐구한 내용으로, 아키텍처와 구성 요소를 강조해서 설명합니다.

AgentOps SDK 클라이언트

원칙 (Principles)

AgentOps SDK는 개발자가 구현해야 하는 부분을 최대한 줄이면서 많은 기능을 제공하도록 설계되었어요. 이 목표를 이루기 위해 몇 가지 원칙을 따르는데, 함께 살펴볼게요.

자동 계측 (Auto-Instrumenting)
- agentops.init()을 호출하고 나면 SDK가 설치된 LLM provider를 자동으로 찾아서 그 호출들을 자동 계측(auto-instrument)해요. 이렇게 해서 여러분의 코드와 provider 사이의 호출을 캡처해 대시보드에 보여줄 데이터를 수집하는 거예요.
데코레이터 (Decorators)
- Decorators를 사용하면 SDK가 기존 함수와 클래스에 추적(tracing)을 추가해서, 모니터링과 분석을 위한 계층적 span을 만들 수 있어요.
프로세스 모니터링 (Process monitoring)
- SDK는 프로세스 모니터를 몇 개 만들어서 에이전트의 상태(state)와 건강(health)을 파악할 수 있게 해줘요.

세션 (Sessions)

Session은 여러분의 워크플로우를 한 번 실행한 단일 실행 인스턴스를 하나로 묶어주는 개념이에요. 모든 에이전트, LLM, 액션 등을 하나의 우산 아래 묶어 준다고 보면 돼요. 따라서 각 이벤트가 반드시 세션에 연결되어야 해요. AgentOps 대시보드는 비용, 토큰 수, 에러 등 세션 단위의 상세한 통계를 제공합니다.

세션은 다음과 같은 속성을 가져요:

ID: 세션을 식별하는 고유한 식별자예요.
Project ID: 세션과 연결된 프로젝트를 식별하며, 사용한 API Key에 따라 결정돼요.
Starting Timestamp: 세션이 시작된 시점을 표시해요.
Ending Timestamp: 세션이 끝난 시점을 표시해요.
End State: 세션의 성공 또는 실패 여부를 나타내요.

선택적으로, 세션은 다음 항목도 포함할 수 있어요:

End State Reason: 에러 때문이든 사용자가 트리거한 중단(SIGINT) 때문이든, 세션이 왜 끝났는지 설명해요.
Tags: Tags는 세션을 범주화하고 나중에 다시 검색할 수 있게 해줘요.
Host Environment: 세션이 실행된 시스템에 대한 기본 정보를 자동으로 수집해요.
Video: 해당하는 경우 세션의 선택적 동영상 녹화물이에요.

세션 관리 (Session Management)

AgentOps는 두 가지 상태 중 하나로 존재할 수 있어요.

단일 세션 (Single Session): 한 번에 하나의 세션만 존재해요. 모든 에이전트 사용은 동기적(synchronous)이에요.
- 사용 사례: 스크립팅, 개발, 로컬 머신 사용(브라우저 확장 프로그램, 웹 클라이언트 등)
동시 추적 (Concurrent Traces): REST 서버, 비동기(asynchronous) 에이전트, 여러 동시 워크플로우에 사용해요.

AgentOps는 단일 세션과 여러 동시 추적(세션)을 모두 매끄럽게 지원해요. 현대적인 trace 기반 API를 쓰거나, 하위 호환성을 위해 레거시 session 함수를 사용할 수 있어요.

현대적인 방식은 자동 계측과 함께 start_trace()와 end_trace()를 사용하고, 레거시 session 함수도 계속 사용할 수 있어요. 여러 동시 trace는 특별한 모드 전환이나 제한 없이 동작합니다.

import agentops
agentops.init()
trace_context = agentops.start_trace("my_workflow")
# Your agent logic here
agentops.end_trace(trace_context, "Success")

import agentops
agentops.init(auto_start_session=False)
trace_1 = agentops.start_trace("workflow_1")
trace_2 = agentops.start_trace("workflow_2")

# Work with both traces concurrently
agentops.end_trace(trace_1, "Success")
agentops.end_trace(trace_2, "Success")

import agentops

@agentops.trace
def my_workflow():
    # Your agent logic here
    pass

my_workflow()

여러 동시 trace를 사용하는 방법에 대한 자세한 문서는 Concurrent Traces와 FastAPI Example을 참고하세요.

LLM, 도구, 그리고 작업 (Spans)

AgentOps 내에서 LLM, Tool, Operation은 모두 Spans로 분류되며, 에이전트가 실행해요. 에이전트는 주로 LLM 호출을 시작하고, 이로 인해 API/Tool 호출로 이어질 수 있으며, Operation은 함수 실행이나 스크린샷 촬영 같은 그 외의 중요한 절차들을 포함합니다.

모든 span은 다음과 같은 공통 특성을 가져요:

ID: 고유한 식별자예요.
Session ID: span이 속한 세션을 나타내요.
Agent ID: span을 실행한 에이전트를 식별해요.
Parameters: span에 제공된 입력값이에요.
Returns: span의 출력 또는 결과물이에요.
Starting Timestamp: span이 시작된 시점이에요.
Ending Timestamp: span이 끝난 시점이에요.

추가로, 각 span 유형마다 고유한 속성이 있어요:

LLM:

Model: 사용된 특정 LLM 모델이에요.
Prompt Messages: 모델에 보낸 초기 프롬프트예요.
Completion Messages: 모델이 받은 응답이에요.
Prompt Tokens: 프롬프트에 사용된 토큰 수예요.
Completion Tokens: 모델 응답에 들어있는 토큰 수예요.
Cost: span이 발생시킨 비용이에요.
Thread ID: 실행 추적을 위해 span을 특정 thread에 연결해요.

Tools:

Logs: 도구의 동작 기록으로, 출력과 에러를 포함해요.

Operations:

Operation Type: 작업의 성격을 지정해요 (예: 함수 실행, 스크린샷).
Logs: 파라미터와 결과를 포함한 작업 실행의 상세 기록이에요.

에러 (Errors)

에러는 운영 과정에서 피할 수 없는 부분이에요. AgentOps는 Spans와 관련된 에러를 종합적으로 기록해서 트러블슈팅에 풍부한 정보를 제공합니다.

Error Type: 에러와 연결된 span 유형(LLM, Tool, Operation)이에요.
Error Code: 에러를 식별하는 특정 코드예요.
Details: 에러에 대한 상세한 설명이에요.
Logs/Stack Trace: 에러 맥락을 담은 로그 또는 스택 트레이스예요.
Timestamp: 에러가 발생한 정확한 시각이에요.

에이전트 (Agents)

Agent는 자신만의 메모리와 능력을 가진 자율적 존재예요. 다중 에이전트 프레임워크에서 에이전트는 팀원 역할을 하며, 각자 특화된 기술과 책임(예: 프로젝트 관리, 소프트웨어 개발, 품질 보증)을 가지고 조정하고 소통하면서 집단 목표를 달성해요.

Agent는 다음과 같은 특성으로 설명됩니다:

ID: 에이전트를 식별하는 고유한 식별자예요.
Session ID: 에이전트를 연결된 세션에 연결해요.
Name: 에이전트를 쉽게 식별하기 위한 사용자 정의 이름이에요.

선택적으로, 에이전트는 다음 항목도 가질 수 있어요:

Logs: 에이전트가 수행한 작업의 텍스트 기록이에요.

참고: 특정 에이전트에 지정되지 않은 span에 대해서는 AgentOps가 기본 에이전트(default agent)를 자동으로 만들어 할당해요.

스레드 (Threads)

자세한 내용은 곧 제공될 예정이에요.