Python SDK

AI 에이전트가 프로덕션에서 수행한 모든 작업을 확인하세요: 모든 에이전트 실행, 툴 호출, 모델 요청, hook, 그리고 사람의 개입까지. Failproof AI Observability Python SDK는 에이전트 코드 내부에서 그 기록을 남겨 디버깅, 감사, 평가에 활용할 수 있게 해줍니다. 에이전트를 Failproof AI Observability로 관찰하고 싶을 때마다 사용하세요. 내부적으로 SDK는 구조화된 이벤트를 로컬 JSONL 파일에 기록하며, 콜렉터 데몬이 이를 감지해 플랫폼으로 자동 전송합니다. 파일을 직접 관리할 필요가 없습니다.

팁: Failproof AI Observability가 처음이신가요? 이 페이지는 SDK 이벤트의 완전한 레퍼런스입니다.

설치

SDK는 공개 패키지 인덱스가 아닌 프라이빗 휠로 고객에게 배포됩니다. 온보딩 과정에서 취득, 설치, 버전 고정 방법을 안내받게 됩니다. 접근 권한이 필요하면 Failproof AI 담당자에게 문의하세요. 설치 후 다음 명령으로 확인하세요:

python -c "import agenteye; print(agenteye.__version__)"

코딩 에이전트가 전체 통합을 처리하게 하고 싶으신가요? Python SDK Agent Skill은 설치 경로를 파악하고, 계측 지점을 계획·작성하며, 이벤트가 정상적으로 수신되는지 검증합니다.

빠른 시작

import agenteye

agenteye.configure(environment="production")

agenteye.event.agent_start(session_id="run-001", agent_id="planner", goal="answer user query")

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    input={"query": "latest AI research"},
)

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",
    output={"results": ["..."]},
)

agenteye.event.agent_end(session_id="run-001", agent_id="planner", outcome="success")

실제 호출 계측하기

실제로는 기존 에이전트 코드를 감싸는 방식으로 사용합니다. 모델 호출 앞에 model_request를, 뒤에 model_response를 배치하면 두 이벤트가 실제 요청을 감싸게 되어 Failproof AI Observability가 두 이벤트를 서로 연결할 수 있습니다:

import anthropic
import agenteye

agenteye.configure(environment="production")
client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Summarise today's incidents."}]

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6",
    messages=messages,
)

reply = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=messages,
)

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model=reply.model,
    stop_reason=reply.stop_reason,
    input_tokens=reply.usage.input_tokens,
    output_tokens=reply.usage.output_tokens,
    content=[block.model_dump() for block in reply.content],
)

툴 호출도 동일한 방식으로 tool_use와 tool_result를 감싸되, 동일한 tool_call_id를 쌍으로 재사용하세요. 아래는 이벤트가 대시보드에 도달했을 때의 모습입니다. 이벤트 유형별로 색상이 구분되며 환경, 에이전트, 세션별로 필터링할 수 있습니다:

이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 라이브 이벤트 스트림

configure()

agenteye.configure(
    base_dir=None,           # Path | str | None. Default: $AGENTEYE_HOME or ~/.agenteye
    flush_interval=0.5,      # float, seconds between flush cycles
    environment=None,        # str | None. Deployment environment label
)

event.* 호출 전에 한 번 호출하세요. 생략해도 안전하며, 기본값만으로도 바로 사용할 수 있습니다. 모든 인수는 키워드 전용이므로 위와 같이 이름으로 전달하세요. base_dir가 None(기본값)인 경우, SDK는 $AGENTEYE_HOME이 설정되어 있으면 해당 값을 사용하고, 그렇지 않으면 ~/.agenteye로 폴백합니다. 이는 콜렉터 자체의 경로 결정 방식과 동일하므로, AGENTEYE_HOME 환경 변수 하나로 SDK와 콜렉터가 공유하는 이벤트 스풀을 설정할 수 있습니다.

환경

모든 이벤트에 배포 환경을 나타내는 레이블(production, staging, qa, canary 등)을 지정하세요. 한 번만 설정하면 SDK가 모든 이벤트에 자동으로 첨부합니다. 방법 1: configure()를 통해 설정:

agenteye.configure(environment="production")

방법 2: 환경 변수를 통해 설정:

export AGENTEYE_ENVIRONMENT=production

우선순위: configure(environment=...)가 환경 변수보다 우선합니다. 둘 다 설정되지 않은 경우 기본값은 "dev"입니다. 환경 값은 대시보드의 1급 필터로 표시되며, 빠른 쿼리를 위해 서버에 저장됩니다.

경고: 환경 값에는 리터럴 , 쉼표를 포함할 수 없습니다. 대시보드 필터는 와이어에서 쉼표로 구분된 다중 선택 방식을 사용(?environment=prod,staging)하므로, prod,blue라는 이름의 환경은 두 개의 값으로 분리됩니다. 쉼표가 포함된 환경의 이벤트는 수집 시 거부됩니다.

데이터 및 개인정보 보호

SDK는 명시적으로 전달한 필드만 기록합니다. 프롬프트, 메시지, 툴 입출력, 모델 콘텐츠는 event.* 호출에 전달할 때만 캡처됩니다. 프로세스에서 암묵적으로 읽거나 캡처하는 정보는 없습니다. 설정하지 않은 필드는 이벤트에서 완전히 제외되며 디스크에도 기록되지 않습니다. 따라서 데이터 삭제는 전적으로 여러분의 선택이자 책임입니다. 프롬프트나 툴 페이로드에 저장하고 싶지 않은 개인정보나 비밀이 포함된 경우, 이벤트 메서드에 전달하기 전에 제거하거나 마스킹하세요.

이벤트 레퍼런스

대부분의 이벤트는 상관 ID를 공유하는 시작/종료 쌍으로 구성됩니다: tool_use와 tool_result는 tool_call_id를 공유하고, hook_triggered와 hook_completed는 hook_id를 공유하며, human_wait와 human_input은 input_id를 공유합니다. 시작 이벤트를 발행하고 작업을 수행한 뒤, 동일한 ID로 종료 이벤트를 발행하세요. Failproof AI Observability가 쌍을 매칭하고 duration_ms를 자동으로 계산하므로 직접 전달할 필요가 없습니다.

페어드 이벤트로 재구성된 실행 그래프 및 타임라인과 툴/모델/hook 분류 패널이 나란히 표시된 세션 상세 화면

모든 이벤트 메서드에는 다음 두 필드가 필요합니다:

필드	타입	설명
`session_id`	`str`	최상위 에이전트 실행을 식별합니다
`agent_id`	`str`	세션 내에서 이벤트를 발행한 에이전트를 식별합니다

모든 메서드는 커스텀 메타데이터를 위한 임의의 **kwargs도 허용합니다(커스텀 필드 참고).

`event.agent_start()`

에이전트가 작업을 시작할 때 발행됩니다.

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="planner",
    goal="answer user query",   # str | None
    parent_id=None,             # str | None - parent agent_id for nested agents
)

`event.agent_end()`

에이전트가 작업을 완료할 때 발행됩니다.

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="planner",
    outcome="success",          # str | None
    summary="Answered query",   # str | None
)

`event.tool_use()`

에이전트가 툴을 호출할 때 발행됩니다. tool_result와 쌍을 이루며 SDK가 duration_ms를 자동 계산합니다.

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",     # str, required
    tool_call_id="toolu_01",    # str, required - correlation key for the matching tool_result
    input={"query": "..."},     # dict | None
)

`event.tool_result()`

툴이 결과를 반환할 때 발행됩니다. tool_call_id를 통해 tool_use와 연결됩니다.

agenteye.event.tool_result(
    session_id="run-001",
    agent_id="planner",
    tool_name="web_search",
    tool_call_id="toolu_01",        # must match the prior tool_use
    output={"results": ["..."]},    # Any | None
    error=None,                     # str | None - set if the tool raised
    # duration_ms is computed automatically - do not pass it
)

`event.model_request()`

LLM에 프롬프트를 전송하기 직전에 발행됩니다.

agenteye.event.model_request(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
    messages=[                   # list[dict] | None - conversation turns
        {"role": "user", "content": "..."},
    ],
    system="You are helpful.",   # Any | None - str or list of content blocks
    tools=[                      # list[dict] | None - tool schemas offered to the model
        {"name": "search", "input_schema": {"type": "object"}},
    ],
)

messages 항목은 일반 문자열 content 또는 Anthropic 스타일의 블록 리스트 content를 모두 허용합니다. 샘플링 파라미터(temperature, max_tokens 등)는 추가 kwargs로 전달할 수 있습니다.

`event.model_response()`

LLM이 응답을 반환할 때 발행됩니다.

agenteye.event.model_response(
    session_id="run-001",
    agent_id="planner",
    model="claude-sonnet-4-6", # str | None - any provider/model string; not validated
    stop_reason="end_turn",     # str | None
    input_tokens=1024,          # int | None
    output_tokens=256,          # int | None
    content=[                    # Any | None - str, or list of content blocks
        {"type": "text", "text": "..."},
    ],
    role="assistant",            # str | None
)

content는 일반 문자열(일반 프로바이더) 또는 Anthropic 스타일의 콘텐츠 블록 리스트를 모두 허용합니다. 툴 호출은 별도의 tool_calls 필드 없이 {"type": "tool_use", ...} 블록 형태로 content 안에 포함됩니다.

`event.hook_triggered()`

hook이 실행될 때 발행됩니다. hook_completed와 쌍을 이루며 SDK가 duration_ms를 자동 계산합니다.

agenteye.event.hook_triggered(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",   # str, required
    hook_id="hook-abc",         # str, required - correlation key
    trigger_event="tool_use",   # str | None
    input={"tool": "search"},   # Any | None
)

`event.hook_completed()`

hook이 완료될 때 발행됩니다. hook_id를 통해 hook_triggered와 연결됩니다.

agenteye.event.hook_completed(
    session_id="run-001",
    agent_id="planner",
    hook_name="pre_tool_use",
    hook_id="hook-abc",         # must match the prior hook_triggered
    outcome="allow",            # str | None
    output=None,                # Any | None
    error=None,                 # str | None
    # duration_ms is computed automatically - do not pass it
)

`event.error()`

처리되지 않은 오류가 발생할 때 발행됩니다.

agenteye.event.error(
    session_id="run-001",
    agent_id="planner",
    error_type="TimeoutError",  # str, required
    message="timed out",        # str, required
    traceback="Traceback...",   # str | None
)

사람 개입(Human-in-the-Loop) 이벤트

사람 개입 이벤트는 에이전트 실행 중 사람이 개입하는 순간(승인 대기, 입력 제공, 일시 중지, 에이전트 중단)에 대한 감시를 제공합니다. 이를 통해 사람이 응답하는 데 걸리는 시간을 측정하고(SDK가 페어드 이벤트에서 duration_ms를 자동 계산), 에이전트를 일시 중지하거나 중단한 사람을 감사하며, 대시보드에 표시되는 승인 및 감독 워크플로를 구축할 수 있습니다.

`event.human_wait()`

에이전트가 사람의 입력을 기다리기 위해 실행을 일시 중지할 때 발행됩니다. human_input과 쌍을 이루며 SDK가 duration_ms(사람이 응답하는 데 걸린 시간)를 자동 계산합니다.

agenteye.event.human_wait(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",                          # str, required - correlation key for the matching human_input
    prompt="Do you approve this action?",        # str | None - the question shown to the human
    options=["approve", "reject", "defer"],      # list[str] | None - choices presented to the human
    reason="approval_required",                  # str | None - why the agent is waiting
)

`event.human_input()`

사람이 입력을 제공하고 에이전트가 재개될 때 발행됩니다. input_id를 통해 human_wait와 연결됩니다. duration_ms는 자동으로 계산되므로 호출자가 전달해서는 안 됩니다.

agenteye.event.human_input(
    session_id="run-001",
    agent_id="planner",
    input_id="inp-abc",    # str, required - must match the prior human_wait
    response="approve",    # str | None - the human's answer (free text or selected option)
    # duration_ms is computed automatically - do not pass it
)

`event.human_pause()`

사람이 능동적으로 에이전트를 일시 중지할 때(예: 대시보드 컨트롤을 통해) 발행됩니다. 에이전트는 종료되지 않고 일시 중단됩니다.

agenteye.event.human_pause(
    session_id="run-001",
    agent_id="planner",
    reason="user_requested",  # str | None
    user_id="usr_42",         # str | None - who paused the agent
)

`event.human_interrupt()`

사람이 에이전트를 실행 중에 능동적으로 중단시킬 때 발행됩니다. human_pause와 달리 에이전트의 작업이 일시 중단이 아닌 종료됩니다.

agenteye.event.human_interrupt(
    session_id="run-001",
    agent_id="planner",
    reason="output_incorrect",       # str | None
    user_id="usr_42",                # str | None - who interrupted the agent
    at_step="tool_use:web_search",   # str | None - what the agent was doing when stopped
)

커스텀 필드

추가 키워드 인수는 표준 필드 뒤에 이벤트에 추가됩니다:

agenteye.event.tool_use(
    session_id="run-001",
    agent_id="planner",
    tool_name="db_query",
    tool_call_id="toolu_02",
    tenant_id="acme",           # custom field
    region="us-east-1",         # custom field
)

timestamp, type, environment는 예약된 이름으로, 커스텀 필드로 전달하면 ValueError(Reserved field names cannot be used as custom fields: [...])가 발생합니다. session_id와 agent_id는 모든 이벤트 메서드의 필수 파라미터이므로 두 번 제공할 수 없으며, 그렇게 하면 Python이 TypeError를 발생시킵니다. 환경은 configure(environment=...)(또는 AGENTEYE_ENVIRONMENT 변수)로 설정하세요. 필드를 쿼리하고 싶다면 페이로드를 구조화된 JSON으로 유지하세요. JSON이 기본적으로 지원하지 않는 값(datetime, UUID, decimal, set, bytes, 모델 객체 등)은 기록이 안전하게 계속될 수 있도록 문자열로 변환됩니다.

이벤트 기록 방식

이벤트는 프로세스 내에 버퍼링되었다가 flush_interval초마다(기본값 500ms) 디스크에 플러시됩니다. 각 플러시는 하나의 JSONL 파일을 작성합니다:

~/.agenteye/events/event-2026-04-01T12-00-00-000Z.jsonl

콜렉터는 이 디렉터리를 감시하고 파일을 자동으로 업로드합니다. 파일을 직접 관리할 필요가 없습니다. 각 파일은 원자적으로 작성됩니다: SDK가 임시 파일에 쓴 다음 제자리로 이름을 변경하므로 콜렉터가 절반만 쓰인 파일을 볼 일이 없습니다. 프로세스가 종료될 때도 최종 플러시가 실행되므로 마지막 인터벌에 버퍼링된 이벤트가 유실되지 않습니다. 콜렉터가 오프라인 상태인 경우 이벤트는 디스크에 파일로 쌓여 있다가 콜렉터가 복구되면 전송됩니다.

다음 단계

이벤트 스트림: 이벤트 유형별로 색상이 구분되고 환경, 에이전트, 세션별로 필터링 가능한 라이브 이벤트 스트림을 확인하세요.
세션: 페어드 이벤트가 각 에이전트 실행을 실행 그래프 및 타임라인으로 어떻게 재구성하는지 확인하세요.

Overview

Features

SDK and CLI

Administration

설치

빠른 시작

실제 호출 계측하기

configure()

환경

데이터 및 개인정보 보호

이벤트 레퍼런스

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

사람 개입(Human-in-the-Loop) 이벤트

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

커스텀 필드

이벤트 기록 방식

다음 단계

​설치

​빠른 시작

​실제 호출 계측하기

​configure()

​환경

​데이터 및 개인정보 보호

​이벤트 레퍼런스

​event.agent_start()

​event.agent_end()

​event.tool_use()

​event.tool_result()

​event.model_request()

​event.model_response()

​event.hook_triggered()

​event.hook_completed()

​event.error()

​사람 개입(Human-in-the-Loop) 이벤트

​event.human_wait()

​event.human_input()

​event.human_pause()

​event.human_interrupt()

​커스텀 필드

​이벤트 기록 방식

​다음 단계

설치

빠른 시작

실제 호출 계측하기

configure()

환경

데이터 및 개인정보 보호

이벤트 레퍼런스

`event.agent_start()`

`event.agent_end()`

`event.tool_use()`

`event.tool_result()`

`event.model_request()`

`event.model_response()`

`event.hook_triggered()`

`event.hook_completed()`

`event.error()`

사람 개입(Human-in-the-Loop) 이벤트

`event.human_wait()`

`event.human_input()`

`event.human_pause()`

`event.human_interrupt()`

커스텀 필드

이벤트 기록 방식

다음 단계