SDK 레퍼런스

SDK 레퍼런스 (SDK Reference)

SDK의 최상위 계층에서 노출되는 모든 함수와 클래스를 소개해요. 핵심 함수, 트레이스 관리, 상세 계측용 데코레이터, 그리고 레거시 함수까지 알아볼게요.

출처: 문서

본문

SDK 레퍼런스

이 레퍼런스는 Python SDK의 import agentops로 사용 가능한 함수와 클래스를 문서화합니다. AgentOps SDK는 에이전트 애플리케이션에 쉽게 통합되도록 설계되었으며, 간단한 자동 계측과 더 상세한 수동 트레이싱 기능을 모두 제공합니다.

This documentation covers the Python SDK. A TypeScript/JavaScript SDK is also available - see our [TypeScript SDK guide](/v2/usage/typescript-sdk) for details.

핵심 함수 (Core Functions)

이것들은 애플리케이션에서 AgentOps를 초기화하고 구성하는 데 사용하는 주요 함수입니다.

`init()`

AgentOps SDK를 초기화하고 애플리케이션 추적을 자동으로 시작합니다.

파라미터:

api_key (str, 선택): AgentOps 서비스를 위한 API 키. 제공하지 않으면 AGENTOPS_API_KEY 환경 변수에서 읽습니다.
endpoint (str, 선택): AgentOps 서비스의 엔드포인트. 제공하지 않으면 AGENTOPS_API_ENDPOINT 환경 변수에서 읽습니다. 기본값은 'https://api.agentops.ai'입니다.
app_url (str, 선택): AgentOps 앱의 대시보드 URL. 제공하지 않으면 AGENTOPS_APP_URL 환경 변수에서 읽습니다. 기본값은 'https://app.agentops.ai'입니다.
max_wait_time (int, 선택): 큐를 flush 하기 전 최대 대기 시간(밀리초). 기본값은 5,000 (5초)입니다.
max_queue_size (int, 선택): 이벤트 큐의 최대 크기. 기본값은 512입니다.
default_tags (List[str], 선택): 나중에 그룹화나 정렬에 사용할 수 있는 세션의 기본 태그 (예: ["GPT-4"]).
tags (List[str], 선택): [Deprecated] default_tags를 대신 사용하세요. v4.0에서 제거될 예정입니다.
instrument_llm_calls (bool, 선택): LLM 호출을 자동으로 계측할지 여부. 기본값은 True입니다.
auto_start_session (bool, 선택): 클라이언트 생성 시 세션을 자동으로 시작할지 여부. Jupyter Notebook에서 실행 중이면 False로 설정하세요. 기본값은 True입니다.
auto_init (bool, 선택): import 시 클라이언트를 자동으로 초기화할지 여부. 기본값은 True입니다.
skip_auto_end_session (bool, 선택): 여러분의 프레임워크 의사결정에 따라 세션을 자동으로 종료하지 않기. 기본값은 False입니다.
env_data_opt_out (bool, 선택): 환경 데이터 수집을 거부할지 여부. 기본값은 False입니다.
log_level (str, int, 선택): 클라이언트에 사용할 로그 레벨. 기본값은 'INFO'입니다.
fail_safe (bool, 선택): 가능할 때 오류를 억제하고 실행을 계속할지 여부. 기본값은 False입니다.
exporter_endpoint (str, 선택): exporter의 엔드포인트. 제공하지 않으면 AGENTOPS_EXPORTER_ENDPOINT 환경 변수에서 읽습니다. 기본값은 'https://otlp.agentops.ai/v1/traces'입니다.
export_flush_interval (int, 선택): 텔레메트리 데이터 자동 내보내기 사이의 시간 간격(밀리초). 기본값은 1000입니다.
trace_name (str, 선택): 자동으로 생성된 트레이스의 커스텀 이름. 제공하지 않으면 기본 이름이 사용됩니다.

반환:

auto_start_session=True이면 생성된 Session 객체를 반환합니다. 그렇지 않으면 None을 반환합니다.

예제:

import agentops

# Basic initialization with automatic session creation
agentops.init("your-api-key")

# Initialize with custom trace name
agentops.init("your-api-key", trace_name="my-workflow")

`configure()`

초기화 후 클라이언트 구성을 업데이트합니다. init()과 동일한 파라미터를 지원합니다.

파라미터:

api_key (str, 선택): AgentOps 서비스를 위한 API 키.
endpoint (str, 선택): AgentOps 서비스의 엔드포인트.
app_url (str, 선택): AgentOps 앱의 대시보드 URL.
max_wait_time (int, 선택): 큐를 flush 하기 전 최대 대기 시간(밀리초).
max_queue_size (int, 선택): 이벤트 큐의 최대 크기.
default_tags (List[str], 선택): 세션의 기본 태그.
instrument_llm_calls (bool, 선택): LLM 호출을 계측할지 여부.
auto_start_session (bool, 선택): 세션을 자동으로 시작할지 여부.
auto_init (bool, 선택): import 시 클라이언트를 자동으로 초기화할지 여부.
skip_auto_end_session (bool, 선택): 세션을 자동으로 종료하지 않기.
env_data_opt_out (bool, 선택): 환경 데이터 수집을 거부할지 여부.
log_level (str, int, 선택): 클라이언트에 사용할 로그 레벨.
fail_safe (bool, 선택): 오류를 억제하고 실행을 계속할지 여부.
exporter (object, 선택): OpenTelemetry 트레이스 데이터용 커스텀 스팬 exporter.
processor (object, 선택): OpenTelemetry 트레이스 데이터용 커스텀 스팬 프로세서.
exporter_endpoint (str, 선택): exporter의 엔드포인트.
export_flush_interval (int, 선택): 텔레메트리 데이터 자동 내보내기 사이의 시간 간격(밀리초).
trace_name (str, 선택): 트레이스의 커스텀 이름.

예제:

import agentops

# Initialize first
agentops.init()

# Later, update configuration
agentops.configure(
    max_wait_time=10000,
    max_queue_size=200,
    default_tags=["production", "gpt-4"],
    trace_name="production-workflow"
)

`get_client()`

싱글턴 클라이언트 인스턴스를 가져옵니다. 대부분의 사용자는 이 함수를 직접 사용할 필요가 없습니다.

반환:

AgentOps 클라이언트 인스턴스.

트레이스 관리 (Trace Management)

이 함수들은 트레이스 추적의 수명주기를 관리하는 데 도움을 줍니다.

`start_trace()`

새 AgentOps 트레이스를 수동으로 시작합니다. 자동 세션 생성을 비활성화했거나 여러 개의 별도 트레이스가 필요할 때 유용합니다.

파라미터:

trace_name (str, 선택): 트레이스의 이름. 제공하지 않으면 기본 이름이 사용됩니다.
tags (Union[Dict[str, Any], List[str]], 선택): 트레이스에 붙일 선택적 태그로, 대시보드에서 필터링에 유용합니다. 문자열 리스트 또는 키-값 쌍의 dict일 수 있습니다.

반환:

시작된 트레이스를 나타내는 TraceContext 객체.

예제:

import agentops

# Initialize without auto-starting a session
agentops.init("your-api-key", auto_start_session=False)

# Start a trace manually
trace = agentops.start_trace("customer-service-workflow", tags=["customer-query"])

`end_trace()`

특정 트레이스 또는 모든 활성 트레이스를 종료합니다.

파라미터:

trace (TraceContext, 선택): 종료할 특정 트레이스. 제공하지 않으면 모든 활성 트레이스가 종료됩니다.
end_state (str, 선택): 트레이스의 종료 상태. 애플리케이션에 의미 있는 어떤 설명 문자열이든 사용할 수 있어요 (예: "Success", "Indeterminate", "Error", "Timeout" 등).

예제:

import agentops

# End a specific trace
trace = agentops.start_trace("my-workflow")
# ... your code ...
agentops.end_trace(trace, "Success")

# End all active traces
agentops.end_trace(end_state="Emergency_Shutdown")

`update_trace_metadata()`

현재 실행 중인 트레이스의 메타데이터를 업데이트합니다. 트레이스 실행 중 컨텍스트를 추가하거나, 진행률을 추적하거나, 중간 결과를 저장하는 데 유용합니다.

파라미터:

metadata (Dict[str, Any]): 트레이스 메타데이터로 설정할 키-값 쌍의 딕셔너리. 값은 문자열, 숫자, 불리언 또는 이러한 유형의 리스트여야 합니다. 리스트는 자동으로 JSON 문자열 표현으로 변환됩니다.
prefix (str, 선택): 메타데이터 속성의 프리픽스. 기본값은 "trace.metadata"입니다. 시맨틱 컨벤션 속성에는 무시됩니다.

반환:

bool: 메타데이터가 성공적으로 업데이트되었으면 True, 그렇지 않으면 False.

기능:

시맨틱 컨벤션 지원: "tags", "agent_name", "workflow_name" 같은 사용자 친화적인 키가 OpenTelemetry 시맨틱 컨벤션으로 자동 매핑됩니다.
커스텀 속성: 시맨틱이 아닌 키는 지정된 프리픽스(기본: "trace.metadata")로 접두사가 붙습니다.
타입 안전성: 입력 타입을 검증하고 OpenTelemetry 호환을 위해 리스트를 JSON 문자열로 변환합니다.
오류 처리: 불리언 성공 지표를 반환하고 잘못된 데이터에 대한 경고를 로그합니다.

예제:

import agentops
from agentops import update_trace_metadata

# Initialize and start trace with initial tags
agentops.init(auto_start_session=False)
trace = agentops.start_trace("ai-workflow", tags=["startup", "initialization"])

# Your code here...

# Update metadata mid-run with new tags and operation info
update_trace_metadata({
    "operation_name": "OpenAI GPT-4o-mini",
    "tags": ["ai-agent", "processing", "gpt-4"],  # Updates tags
    "status": "processing"
})

# End the trace
agentops.end_trace(trace, "Success")

자세한 예제와 사용 사례는 수동 트레이스 제어를 참조하세요.

상세 계측용 데코레이터 (Decorators for Detailed Instrumentation)

더 세밀한 제어를 위해 AgentOps는 애플리케이션의 서로 다른 컴포넌트를 명시적으로 추적하는 데코레이터를 제공합니다. @trace 데코레이터는 커스텀 트레이스를 만드는 권장 방법이며, 특히 멀티스레드 환경에서 그렇습니다. 이 데코레이터들은 agentops.sdk.decorators에서 import 됩니다.

import agentops
from agentops.sdk.decorators import trace, agent, operation, tool

# Initialize without automatic session creation
agentops.init("your-api-key", auto_start_session=False)

# Create and run a trace using the decorator
@trace
def my_workflow():
    # Your workflow code here
    pass

# Run the workflow, which creates and manages the trace
my_workflow()

사용 가능한 데코레이터 (Available Decorators)

@trace: 관련 작업을 그룹화하기 위한 트레이스 스팬 생성
@agent: 에이전트 작업을 추적하기 위한 에이전트 스팬 생성
@operation / @task: 특정 작업을 추적하기 위한 운영/태스크 스팬 생성 (이 둘은 별칭)
@workflow: 관련 작업을 조직화하기 위한 워크플로우 스팬 생성
@tool: 에이전트 작업에서 도구 사용과 비용을 추적하기 위한 도구 스팬 생성. 도구 사용 비용 추적을 위한 cost 파라미터를 지원합니다.

도구 데코레이터 예제:

from agentops.sdk.decorators import tool

@tool(cost=0.05)
def web_search(query):
    # Tool implementation with cost tracking
    return f"Search results for: {query}"

@tool
def calculator(expression):
    # Tool without cost tracking
    return eval(expression)

이 데코레이터 사용에 대한 더 자세한 문서는 데코레이터를 참조하세요.

레거시 함수 (Legacy Functions)

The following functions are **deprecated** and will be removed in v4.0. They are maintained for backward compatibility with older versions of the SDK and integrations. New code should use the functions and decorators described above instead. When used, these functions will log deprecation warnings.

start_session(): Deprecated. 세션 시작을 위한 레거시 함수. 대신 @trace 데코레이터 또는 start_trace()를 사용하세요.
end_session(): Deprecated. 세션 종료를 위한 레거시 함수. 대신 end_trace()를 사용하세요.
record(event): Deprecated. 이벤트를 기록하는 레거시 함수. 데코레이터 기반 트레이싱으로 대체되었습니다.
track_agent(): Deprecated. 에이전트를 표시하는 레거시 데코레이터. @agent 데코레이터로 대체되었습니다.
track_tool(): Deprecated. 도구를 표시하는 레거시 데코레이터. @tool 데코레이터로 대체되었습니다.
ToolEvent(), ErrorEvent(), ActionEvent(), LLMEvent(): Deprecated. 레거시 이벤트 타입. 자동 계측과 데코레이터로 대체되었습니다.

더 알아보기 (Learn more)

AgentOps 공식 문서