세션

세션 (Sessions)

AgentOps를 초기화하고 세션을 관리하는 방법을 자세히 다루는 문서예요. 세션의 속성, 시작·종료 방법, 세션 상속, 데이터 내보내기, 분석까지 함께 차근차근 알아볼게요.

출처: 문서

본문

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

AgentOps를 사용하려면 반드시 활성 세션(active session)이 있어야 해요.

---

Session

속성 (Properties)

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

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

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

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

메서드 (Methods)

end_session

Params

• end_state (str, enum): Success|Failure|Indeterminate
• end_state_reason (optional, str): 종료 상태에 대한 추가 메모

Returns (str): 세션의 총 비용 (USD)

record

Params

• event (Event): 세션의 일부로 기록할 Event

get_analytics

Returns (dict): 세션에 대한 다양한 분석(analytics) 지표를 담은 딕셔너리

세션 시작하기 (Starting a Session)

agentops.init()을 호출하면 세션이 자동으로 시작돼요. agentops.init(auto_start_session=False)를 호출하면 AgentOps SDK는 초기화하지만 세션은 시작하지 않아요.

나중에 세션을 시작하려면 agentops.start_session()을 호출하세요. (reference)

agentops.init()과 agentops.start_session()은 모두 팩토리(factory) 패턴으로 동작하며 Session 객체를 반환해요. 위의 메서드들은 모두 이 세션 객체에서 호출할 수 있어요.

세션 종료하기 (Ending a Session)

agentops 호출 없이 프로세스가 끝나면 대시보드에 Indeterminate로 표시돼요. 상태와 함께 종료하려면, 단 하나의 세션만 사용 중일 때는 agentops.end_session(...) (reference)을 호출하고, 그 외에는 session.end_session(...)을 사용하세요.

상속된 세션 (Inherited Sessions)

서로 다른 프로세스에서 실행되는 여러 에이전트를 다룰 때, 기존의 session_id로 AgentOps를 초기화하거나 세션을 시작할 수 있어요.

agentops.init(inherited_session_id=<id>) agentops.start_session(inherited_session_id=<id>)

init() 또는 start_session()이 반환한 값을 할당하면 현재 session_id를 얻을 수 있어요.

import agentops
session = agentops.init()
# pass session.session_id to the other process

# -- other process --
session_id = retrieve_session_id() # <-- your function
agentops.init(inherited_session_id=<id>)

이제 두 프로세스 모두 같은 세션에 데이터를 기여하게 돼요.

세션 데이터 내보내기 (Session Data Export)

AgentOps는 세션 데이터와 통계를 내보낼 수 있는 REST 엔드포인트를 제공해요. 이 엔드포인트들을 통해 프로그래밍 방식으로 세션에 대한 상세 정보를 가져올 수 있어요.

인증 (Authentication)

모든 데이터 내보내기 요청에는 단일 헤더가 필요해요:

• X-Agentops-Api-Key: 여러분의 AgentOps API key

사용 가능한 엔드포인트 (Available Endpoints)

세션 통계 가져오기 (Get Session Statistics)

GET /v2/sessions/<session_id>/stats

지정된 세션에 대한 통계를 반환하며 다음을 포함해요:

• Event 개수
• Duration (지속 시간)
• Cost (비용)
• Token 사용량
• 기타 세션 지표

완전한 세션 데이터 내보내기 (Export Complete Session Data)

GET /v2/sessions/<session_id>/export

포괄적인 세션 데이터를 반환하며 다음을 포함해요:

• Session 메타데이터
• Statistics (통계)
• 기록된 모든 events:
  • Actions
  • LLM calls
  • Tool usage
  • Errors

사용 예시 (Example Usage)

import requests

# Your AgentOps API key
api_key = "your-api-key"
session_id = "your-session-id"

headers = {
    "X-Agentops-Api-Key": api_key
}

# Get session stats
stats_url = f"https://api.agentops.ai/v2/sessions/{session_id}/stats"
stats_response = requests.get(stats_url, headers=headers)
stats = stats_response.json()

# Export complete session data
export_url = f"https://api.agentops.ai/v2/sessions/{session_id}/export"
export_response = requests.get(export_url, headers=headers)
session_data = export_response.json()

세션 분석 (Session Analytics)

session.get_analytics()를 호출해서 세션의 분석을 얻을 수 있어요.

아래 예시는 events를 기록하고 분석을 검색하는 방법을 보여줘요.

import agentops
session = agentops.init()
session.record(ActionEvent("llms"))
session.record(ActionEvent("tools"))
analytics = session.get_analytics()
print(analytics)
session.end_session("Success")

출력은 이렇게 보여요 -

{'LLM calls': 0, 'Tool calls': 0, 'Actions': 0, 'Errors': 0, 'Duration': '0.9s', 'Cost': '0.00'}

AgentOps SDK 클라이언트

궁금한 분들을 위한 추가 정보

내부적으로 agentops.init()은 다양한 구성 옵션을 가진 Client 객체를 만들어요. 새 세션을 시작할 때마다 이러한 구성 옵션이 자동으로 적용돼요. 새 세션을 시작할 때 Config 객체를 전달해서 다른 구성 옵션을 적용할 수도 있어요.

더 알아보기 (Learn more)

• Core Concepts
• Tags
• Host Environment Data