REST API
REST API
Python SDK를 쓰지 않고도 AgentOps API에 직접 연결해서 에이전트 모니터링을 통합하는 방법을 설명하는 문서예요. 인증부터 세션·이벤트·에이전트 관리까지 HTTP 엔드포인트를 통해 모든 것을 다룰 수 있어요.
출처: 문서
본문
AgentOps REST API를 사용하면 Python SDK 없이도 애플리케이션에 에이전트 모니터링을 직접 통합할 수 있어요. 이는 다음과 같은 경우에 유용해요:
- Python이 아닌 애플리케이션
- 커스텀 통합 (Custom integrations)
- 직접 API 접근 (Direct API access)
전체 API 참조는 OpenAPI specification에서 확인할 수 있어요.
인증 (Authentication)
AgentOps API는 두 단계의 인증 절차를 사용해요:
- API Key: 세션을 만들고 JWT 토큰을 받는 데 사용
- JWT: 세션 내의 모든 작업에 사용
초기 인증 (Initial Authentication)
세션을 만들 때 API 키를 사용하고, 응답으로 JWT 토큰을 받아요:
curl -X POST https://api.agentops.ai/create_session \
-H "Content-Type: application/json" \
-H "X-Agentops-Api-Key: *** \
-d '{
"id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z"
}'
{
"status": "success",
"jwt": "eyJhbG...NiIs...",
"session_id": "550e8400-e29b-41d4-a716-446655440000"
}
HTTP/1.1 401 Unauthorized
{
"error": "Invalid API key",
"message": "Please check your API key and try again"
}
JWT 토큰 사용하기 (Using JWT Tokens)
이후의 모든 요청에는 Authorization 헤더에 JWT 토큰을 사용해요:
curl -X POST https://api.agentops.ai/create_events \
-H "Authorization: Bearer eyJhbG...s..." \
-H "Content-Type: application/json" \
-d '{
"events": [{
"type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z"
}]
}'
HTTP/1.1 401 Unauthorized
{
"error": "Invalid or expired JWT",
"message": "Please reauthorize using /reauthorize_jwt"
}
토큰 갱신 (Refreshing Tokens)
JWT는 24시간 후에 만료돼요. 토큰이 만료되면 API 키를 사용해 새 토큰을 받아야 해요:
curl -X POST https://api.agentops.ai/v2/reauthorize_jwt \
-H "Content-Type: application/json" \
-H "X-Agentops-Api-Key: *** \
-d '{
"session_id": "550e8400-e29b-41d4-a716-446655440000"
}'
{
"status": "success",
"jwt": "eyJhbG...NiIs..."
}
세션 관리 (Session Management)
세션에는 클라이언트 쪽에서 직접 생성한 고유한 식별자가 필요해요. 어떤 고유 문자열이든 동작하지만, 일관성을 위해 UUID를 권장해요. Python에서 UUID를 생성하는 방법은 다음과 같아요:
import uuid
session_id = str(uuid.uuid4())
# "550e8400-e29b-41d4-a716-446655440000"
세션 생성 (Create Session)
생성한 세션 ID로 새 모니터링 세션을 시작해요:
curl -X POST https://api.agentops.ai/v2/create_session \
-H "Content-Type: application/json" \
-H "X-Agentops-Api-Key: *** \
-d '{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z",
"tags": ["production", "customer-service"],
"host_env": {
"OS": {
"OS": "Windows",
"OS Release": "11",
"OS Version": "10.0.22631"
},
"CPU": {
"CPU Usage": "5.9%",
"Total cores": 12
},
"RAM": {
"Used": "14.49 GB",
"Total": "31.75 GB"
},
"SDK": {
"Python Version": "3.12.0",
"System Packages": {
"agentops": "0.3.17",
"openai": "1.2.3"
}
}
}
}
}'
POST https://api.agentops.ai/v2/create_session
Content-Type: application/json
X-Agentops-Api-Key: ***
{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z",
"tags": ["production", "customer-service"],
"host_env": {
"OS": {
"OS": "Windows",
"OS Release": "11",
"OS Version": "10.0.22631"
},
"CPU": {
"CPU Usage": "5.9%",
"Total cores": 12
},
"RAM": {
"Used": "14.49 GB",
"Total": "31.75 GB"
},
"SDK": {
"Python Version": "3.12.0",
"System Packages": {
"agentops": "0.3.17",
"openai": "1.2.3"
}
}
}
}
}
세션 업데이트 (Update Session)
기존 세션을 업데이트해요 (예: 세션이 끝났을 때):
curl -X POST https://api.agentops.ai/v2/update_session \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"end_timestamp": "2024-03-14T12:05:00Z",
"end_state": "Success",
"end_state_reason": "Task successfully completed",
"tags": ["production", "updated-tag"]
}
}'
POST https://api.agentops.ai/v2/update_session
Content-Type: application/json
Authorization: Bearer ***
{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"end_timestamp": "2024-03-14T12:05:00Z",
"end_state": "Success",
"end_state_reason": "Task successfully completed",
"tags": ["production", "updated-tag"]
}
}
이벤트 추적 (Event Tracking)
이벤트 생성 (Create Events)
LLM 호출, 도구 사용, 또는 기타 이벤트를 추적해요:
curl -X POST https://api.agentops.ai/v2/create_events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"events": [
{
"type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z",
"end_timestamp": "2024-03-14T12:01:02Z",
"model": "gpt-4",
"prompt": [
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "Analyze this data..."}
],
"completion": {
"role": "assistant",
"content": "Based on the data..."
},
"prompt_tokens": 150,
"completion_tokens": 80
},
{
"type": "tool",
"name": "database_query",
"init_timestamp": "2024-03-14T12:01:03Z",
"end_timestamp": "2024-03-14T12:01:04Z",
"input": "SELECT * FROM users",
"output": "Retrieved 5 users"
}
]
}'
POST https://api.agentops.ai/v2/create_events
Content-Type: application/json
Authorization: Bearer ***
{
"events": [
{
"type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z",
"end_timestamp": "2024-03-14T12:01:02Z",
"model": "gpt-4",
"prompt": [
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "Analyze this data..."}
],
"completion": {
"role": "assistant",
"content": "Based on the data..."
},
"prompt_tokens": 150,
"completion_tokens": 80
},
{
"type": "tool",
"name": "database_query",
"init_timestamp": "2024-03-14T12:01:03Z",
"end_timestamp": "2024-03-14T12:01:04Z",
"input": "SELECT * FROM users",
"output": "Retrieved 5 users"
}
]
}
이벤트 업데이트 (Update Events)
기존 이벤트를 업데이트해요 (예: 완료(completion) 정보 추가):
curl -X POST https://api.agentops.ai/v2/update_events \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"events": [
{
"event_id": "event-id-123",
"end_timestamp": "2024-03-14T12:01:02Z",
"completion": "Updated completion text",
"completion_tokens": 100
}
]
}'
POST https://api.agentops.ai/v2/update_events
Content-Type: application/json
Authorization: Bearer ***
{
"events": [
{
"event_id": "event-id-123",
"end_timestamp": "2024-03-14T12:01:02Z",
"completion": "Updated completion text",
"completion_tokens": 100
}
]
}
에이전트 관리 (Agent Management)
에이전트 생성 (Create Agent)
세션에 새 에이전트를 등록해요:
curl -X POST https://api.agentops.ai/v2/create_agent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ***" \
-d '{
"id": "agent-123",
"name": "Research Assistant"
}'
POST https://api.agentops.ai/v2/create_agent
Content-Type: application/json
Authorization: Bearer ***
{
"id": "agent-123",
"name": "Research Assistant"
}
통합 예제 (Example Integration)
Python의 requests 라이브러리를 사용한 완전한 예제예요:
import requests
import uuid
from datetime import datetime, timezone
# 설정 (Configuration)
API_KEY = "your_api_key"
BASE_URL = "https://api.agentops.ai"
# 세션 생성 (Create session)
session_id = str(uuid.uuid4())
response = requests.post(
f"{BASE_URL}/v2/create_session",
headers={"X-Agentops-Api-Key": API_KEY},
json={
"session": {
"id": session_id,
"init_timestamp": datetime.now(timezone.utc).isoformat(),
"tags": ["example"]
}
}
)
jwt_token = response.json()["jwt"]
# LLM 호출 추적 (Track LLM call)
requests.post(
f"{BASE_URL}/v2/create_events",
headers={"Authorization": f"Bearer {jwt_token}"},
json={
"events": [{
"type": "llm",
"init_timestamp": datetime.now(timezone.utc).isoformat(),
"model": "gpt-4",
"prompt": "Hello, world!",
"completion": "Hi there!",
"prompt_tokens": 3,
"completion_tokens": 2
}]
}
)
# 세션 종료 (End session)
requests.post(
f"{BASE_URL}/v2/update_session",
headers={"Authorization": f"Bearer {jwt_token}"},
json={
"session": {
"id": session_id,
"end_timestamp": datetime.now(timezone.utc).isoformat(),
"end_state": "completed"
}
}
)