Public API

AgentOps 트레이스와 스팬 데이터에 접근하기 위한 읽기 전용 HTTP API를 소개해요. 인증 방법, 핵심 엔드포인트, 그리고 MCP 서버 설정까지 알아볼게요.

출처: 문서

본문

Public API

AgentOps Public API는 여러분의 모니터링 데이터에 대한 읽기 전용 HTTP 접근을 제공합니다. 이 RESTful API를 사용하면 프로그래밍 언어와 관계없이 어떤 애플리케이션이나 프레임워크에서 트레이스 정보, 스팬 세부 정보, 메트릭을 조회할 수 있습니다.

This is a **read-only API** for accessing existing data. To create traces and spans, use the [AgentOps SDK](/v2/quickstart) or our instrumentation libraries.

기본 URL (Base URL)

모든 API 요청은 다음으로 보내야 합니다.

https://api.agentops.ai

인증 (Authentication)

API는 JWT 토큰 인증을 사용합니다. 먼저 API 키를 JWT 토큰으로 교환해야 합니다.

접근 토큰 얻기 (Get Access Token)

API 접근을 위해 API 키를 bearer 토큰으로 변환하세요.

```bash curl theme={null} curl -X POST https://api.agentops.ai/public/v1/auth/access_token \ -H "Content-Type: application/json" \ -d '{ "api_key": "YOUR_API_KEY" }' ```

{
  "bearer": "eyJhbG...NiIs..."
}

{
  "detail": [
    {
      "loc": ["body", "api_key"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

중요: Bearer 토큰은 30일간 유효합니다. 안전하게 저장하고 만료 전에 갱신하세요.

핵심 엔드포인트 (Core Endpoints)

프로젝트 정보 얻기 (Get Project Information)

현재 프로젝트에 대한 세부 정보를 조회합니다.

```bash curl theme={null} curl -X GET https://api.agentops.ai/public/v1/project \ -H "Authorization: Bearer ***" ```

{
  "id": "proj_abc123",
  "name": "My AI Project",
  "environment": "production"
}

이 엔드포인트는 여러분의 API 키와 연결된 프로젝트에 대한 정보를 반환합니다.

트레이스 세부 정보 얻기 (Get Trace Details)

특정 트레이스에 대한 포괄적인 정보를 조회하며, 모든 스팬을 포함합니다.

```bash curl theme={null} curl -X GET https://api.agentops.ai/public/v1/traces/trace_123 \ -H "Authorization: Bearer ***" ```

{
  "trace_id": "trace_123",
  "project_id": "proj_abc123",
  "tags": ["production", "chatbot", "gpt-4"],
  "spans": [
    {
      "span_id": "span_456",
      "parent_span_id": null,
      "span_name": "User Query Processing",
      "span_kind": "SPAN_KIND_INTERNAL",
      "start_time": "2024-03-14T12:00:00.000Z",
      "end_time": "2024-03-14T12:00:05.000Z",
      "duration": 5000,
      "status_code": "STATUS_CODE_OK",
      "status_message": "Success"
    },
    {
      "span_id": "span_789",
      "parent_span_id": "span_456",
      "span_name": "OpenAI GPT-4 Call",
      "span_kind": "SPAN_KIND_CLIENT",
      "start_time": "2024-03-14T12:00:01.000Z",
      "end_time": "2024-03-14T12:00:03.000Z",
      "duration": 2000,
      "status_code": "STATUS_CODE_OK",
      "status_message": "Success"
    }
  ]
}

{
  "detail": [
    {
      "loc": ["path", "trace_id"],
      "msg": "trace not found",
      "type": "value_error.not_found"
    }
  ]
}

파라미터:

trace_id (path, 필수): 트레이스의 고유 식별자

응답 필드:

trace_id: 고유 트레이스 식별자
project_id: 연결된 프로젝트 ID
tags: 트레이스와 연결된 태그 배열
spans: 트레이스 내 스팬 요약 배열

트레이스 메트릭 얻기 (Get Trace Metrics)

트레이스에 대한 집계 메트릭과 통계를 조회합니다.

```bash curl theme={null} curl -X GET https://api.agentops.ai/public/v1/traces/trace_123/metrics \ -H "Authorization: Bearer ***" ```

{
  "span_count": 5,
  "trace_count": 1,
  "success_count": 4,
  "fail_count": 1,
  "indeterminate_count": 0,
  "prompt_tokens": 150,
  "completion_tokens": 75,
  "cache_read_input_tokens": 0,
  "reasoning_tokens": 25,
  "total_tokens": 250,
  "prompt_cost": "0.0030",
  "completion_cost": "0.0015",
  "average_cost_per_trace": "0.0045",
  "total_cost": "0.0045"
}

메트릭 설명:

span_count: 트레이스의 총 스팬 수
success_count/fail_count/indeterminate_count: 상태 분류
*_tokens: 유형별 토큰 사용량 분류
*_cost: USD로 계산된 비용

스팬 세부 정보 얻기 (Get Span Details)

특정 스팬에 대한 포괄적인 정보를 조회하며, 전체 속성 페이로드를 포함합니다.

```bash curl theme={null} curl -X GET https://api.agentops.ai/public/v1/spans/span_456 \ -H "Authorization: Bearer ***" ```

{
  "span_id": "span_456",
  "parent_span_id": null,
  "span_name": "User Query Processing",
  "span_kind": "SPAN_KIND_INTERNAL",
  "service_name": "chatbot-service",
  "start_time": "2024-03-14T12:00:00.000Z",
  "end_time": "2024-03-14T12:00:05.000Z",
  "duration": 5000,
  "status_code": "STATUS_CODE_OK",
  "status_message": "Success",
  "attributes": {
    "llm.model": "gpt-4-turbo",
    "llm.prompt": "What is the weather like today?",
    "llm.completion": "I need your location to provide weather information.",
    "llm.usage.prompt_tokens": 50,
    "llm.usage.completion_tokens": 25
  },
  "resource_attributes": {
    "service.name": "chatbot-service",
    "service.version": "1.2.3"
  },
  "span_attributes": {
    "user_id": "user_123",
    "session_id": "session_456"
  }
}

파라미터:

span_id (path, 필수): 스팬의 고유 식별자

응답 필드:

attributes: 핵심 스팬 데이터 (LLM 호출, 도구 사용 등)
resource_attributes: 서비스와 인프라 메타데이터
span_attributes: 여러분의 애플리케이션이 설정한 커스텀 속성

스팬 메트릭 얻기 (Get Span Metrics)

특정 스팬에 대한 상세 메트릭을 조회합니다.

```bash curl theme={null} curl -X GET https://api.agentops.ai/public/v1/spans/span_456/metrics \ -H "Authorization: Bearer ***" ```

{
  "total_tokens": 75,
  "prompt_tokens": 50,
  "completion_tokens": 25,
  "cache_read_input_tokens": 0,
  "reasoning_tokens": 0,
  "success_tokens": 75,
  "fail_tokens": 0,
  "indeterminate_tokens": 0,
  "prompt_cost": "0.0015",
  "completion_cost": "0.0005",
  "total_cost": "0.0020"
}

MCP 서버 (MCP Server)

AgentOps는 Public API를 AI 어시스턴트용 도구로 노출하는 Model Context Protocol (MCP) 서버를 제공합니다. 이를 통해 AI 모델이 대화 중에 여러분의 AgentOps 데이터를 직접 쿼리할 수 있습니다.

설정 (Configuration)

MCP 서버 설정 파일을 만드세요 (보통 mcp_config.json).

Python 기반 설정:

{
  "mcpServers": {
    "agentops": {
      "command": "python",
      "args": ["-m", "agentops.mcp.server"],
      "env": {
        "AGENTOPS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Docker 기반 설정:

{
  "mcpServers": {
    "agentops": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "AGENTOPS_API_KEY",
        "agentops/agentops-mcp:latest"
      ],
      "env": {
        "AGENTOPS_API_KEY": "your-agentops-api-key-here"
      }
    }
  }
}

사용 가능한 도구 (Available Tools)

MCP 서버는 Public API 엔드포인트를 반영하는 다음 도구를 노출합니다.

`auth`

AgentOps 프로젝트 API 키로 인증합니다.

Parameters: api_key (string) - 여러분의 AgentOps 프로젝트 API 키
Usage: 서버가 필요할 때 자동으로 인증을 요청합니다

`get_project`

현재 프로젝트에 대한 세부 정보를 가져옵니다.

Parameters: 없음
Returns: ID, 이름, 환경을 포함한 프로젝트 정보

`get_trace`

ID로 포괄적인 트레이스 정보를 가져옵니다.

Parameters: trace_id (string) - 트레이스 식별자
Returns: 관련 스팬이 포함된 트레이스 세부 정보

`get_trace_metrics`

특정 트레이스에 대한 집계 메트릭을 가져옵니다.

Parameters: trace_id (string) - 트레이스 식별자
Returns: 비용, 토큰 사용량, 성능 메트릭

`get_span`

ID로 상세 스팬 정보를 가져옵니다.

Parameters: span_id (string) - 스팬 식별자
Returns: 속성을 포함한 완전한 스팬 데이터

`get_span_metrics`

특정 스팬에 대한 메트릭을 가져옵니다.

Parameters: span_id (string) - 스팬 식별자
Returns: 스팬 특화 비용과 토큰 메트릭

환경 변수 (Environment Variables)

MCP 서버는 다음 환경 변수를 지원합니다.

AGENTOPS_API_KEY: 여러분의 AgentOps 프로젝트 API 키
HOST: API 엔드포인트 (기본값: https://api.agentops.ai)

더 알아보기 (Learn more)

AgentOps 공식 문서