커스텀 에이전트

failproofai-sdk를 사용해 커스텀 에이전트의 트레이스를 계측하면 Failproof AI가 각 실행을 재구성하고, 동작을 감사하며, 근거 기반의 장애를 발견할 수 있습니다. SDK는 Failproof 데몬이 Cloud로 전달할 구조화된 이벤트를 기록합니다. Python 3.10 이상이 필요합니다. 트레이싱을 통해 커스텀 에이전트를 관측 가능하고 감사 가능한 상태로 만들 수 있습니다. 실행 전에 안전하지 않은 동작을 차단하려면 런타임에 별도의 강제 실행 훅도 필요합니다.

커스텀 에이전트 설정에서 정책을 적용하려면 Failproof AI에 문의하세요. 런타임의 모델, 도구, 라이프사이클 경계를 정책 훅에 매핑하는 작업을 도와드립니다.

`failproofai-sdk` 설치

SDK는 현재 프라이빗 휠로 배포됩니다. 현재 버전 및 다운로드 접근 권한은 Failproof AI 담당자에게 문의하세요.

VERSION=<sdk-version>
pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl"
python -c "import failproofai; print(failproofai.__version__)"

uv를 사용하는 경우, 먼저 휠을 다운로드한 후 uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl을 실행하세요. 프라이빗 아티팩트 저장소 또는 의존성 잠금 파일에 휠을 고정하세요. 패키지는 failproofai-sdk로 설치되며, Python에서는 failproofai로 임포트합니다.

Failproof 데몬 연결

대시보드
CLI

Admin → Keys로 이동하여 events:add 권한이 있는 키를 생성합니다.
에이전트 머신에서 Failproof 데몬을 Cloud에 연결합니다.
계측된 세션을 한 번 실행한 후, Observe → Events에서 정확한 ID를 확인합니다.
Observe → Sessions로 이동하여 동일한 환경을 선택하고 재구성된 트레이스를 엽니다.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

전체 실행 계측

프로세스 시작 시 configure()를 한 번 호출합니다. 모든 이벤트 호출은 키워드 전용이며, 안정적인 session_id와 agent_id가 필요합니다.

import traceback
import uuid

import failproofai

failproofai.configure(environment="production")

session_id = uuid.uuid4().hex
agent_id = "checkout-agent"

failproofai.event.agent_start(
    session_id=session_id,
    agent_id=agent_id,
    goal="Resolve a failed checkout",
)

try:
    tool_call_id = uuid.uuid4().hex
    failproofai.event.tool_use(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        input={"order_id": "ord_8421"},
    )
    result = {"status": "payment_failed"}
    failproofai.event.tool_result(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        output=result,
    )
except Exception as exc:
    failproofai.event.error(
        session_id=session_id,
        agent_id=agent_id,
        error_type=type(exc).__name__,
        message=str(exc),
        traceback=traceback.format_exc(),
    )
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="failed",
    )
    raise
else:
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="success",
        summary="Escalated the failed payment",
    )

액터당 agent_start를 한 번 발행합니다. 서브 에이전트의 경우 부모의 session_id를 재사용하고, 각 액터에 고유한 agent_id를 부여하며, parent_id는 세션 ID가 아닌 부모 에이전트 ID로 설정합니다.

설정 레퍼런스

failproofai.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

설정	동작
`base_dir`	명시적 스풀 루트. 모든 환경 변수보다 우선합니다.
`flush_interval`	메모리에서 JSONL로의 백그라운드 쓰기 간격(초). 기본값: `0.5`.
`environment`	모든 이벤트에 붙는 배포 레이블. 기본값은 `dev`.
`FAILPROOFAI_HOME`	`custom-agents` 스풀이 포함된 Failproof AI 루트를 변경합니다.

base_dir가 설정된 경우 SDK는 해당 경로에 기록합니다. 그렇지 않으면 FAILPROOFAI_HOME 또는 ~/.failproofai 아래 Failproof 데몬의 custom-agents 스풀을 사용합니다. SDK는 메모리에 호출을 큐에 저장하고 백그라운드 스레드에서 배치를 기록합니다. Python의 atexit 핸들링을 통해 최종 플러시도 시도합니다. 수명이 짧은 워커의 경우 정상적인 인터프리터 종료를 허용하세요. 강제 프로세스 종료 시 메모리에 남아있는 이벤트가 손실될 수 있습니다.

이벤트 카탈로그

모든 메서드는 None을 반환합니다. None으로 남겨진 필드는 JSON null로 기록되지 않고 생략됩니다.

메서드	식별 필드 외 필수 필드	선택 필드
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

완료가 실패로 분류되어야 하는 경우 outcome="failed", "error", "timeout", 또는 "rejected"를 사용하세요. "failure"를 포함한 다른 값은 현재 백엔드에서 실패로 분류되지 않습니다.

상관관계 및 지속 시간 규칙

매칭되는 완료 이벤트에는 동일한 tool_call_id, hook_id, pause_id, 또는 input_id를 재사용하세요.
SDK는 tool_result, hook_completed, agent_resume, human_input의 duration_ms를 자동으로 계산합니다. 해당 메서드에 직접 전달하면 ValueError가 발생합니다.
도구 및 훅 ID는 프로세스 전체의 단일 대기 맵을 공유합니다. 동시 세션과 두 네임스페이스 모두에서 전역적으로 고유하게 만드세요. 프로바이더 ID나 UUID를 사용하는 것이 가장 안전합니다.
프로세스가 분리된 쌍도 다운스트림에서는 상관관계가 유지되지만, SDK는 프로세스 내 지속 시간을 계산할 수 없습니다.
대기 맵은 최대 10,000개의 시작 항목을 보유하며, 가득 차면 가장 오래된 항목을 제거합니다.

커스텀 필드 및 페이로드

모든 이벤트는 추가 키워드 필드를 받을 수 있습니다. 다운스트림 쿼리에서 구조가 필요한 경우 JSON 호환 값을 사용하세요. UUID, datetime, decimal, set, bytes, 모델 객체 등 지원되지 않는 리프 타입은 작성기가 문자열로 변환합니다. 예약된 커스텀 이름은 timestamp, session_id, agent_id, type, environment입니다. 선택 필드의 오타는 새로운 커스텀 필드로 허용되므로, 표준 필드가 Cloud에 표시되지 않을 때는 발행된 JSON을 확인하세요.

전달 및 검증

대시보드
CLI

Observe → Events에서 처음에 agent_start가, 마지막에 agent_end가 있는지 확인합니다. 그런 다음 Observe → Sessions를 열어 모델, 도구, 휴먼, 훅, 오류 이벤트가 의도한 순서대로 나타나는지 확인합니다. 세션 ID를 주요 트러블슈팅 키로 사용하세요.

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

Cloud가 비어 있는 경우, $FAILPROOFAI_HOME/custom-agents/events를 확인하거나 해당 경로가 없으면 ~/.failproofai/custom-agents/events를 확인하세요. JSONL 파일이 존재하면 SDK가 이벤트를 발행한 것이고, 스풀이 계속 증가하면 데몬 설정 또는 전달 문제를, 스풀이 비어 있으면 계측 또는 프로세스 수명 문제를 의심하세요.

커스텀 런타임에서 장애 방지

감사 결과와 연결된 트레이스를 활용하여 안전하지 않은 동작, 필요한 근거, 의도된 응답을 정의합니다. 커스텀 강제 실행 통합은 실행 전에 동작을 노출하고, 구조화된 입력을 정책 엔진에 전달하며, 결과로 나오는 allow, instruct, 또는 deny 결정을 적용해야 합니다. 런타임에 맞는 통합을 설계하고 검증하려면 support@befailproof.ai로 이메일을 보내세요.

Connect your agents

Reference

HTTP API

`failproofai-sdk` 설치

Failproof 데몬 연결

전체 실행 계측

설정 레퍼런스

이벤트 카탈로그

상관관계 및 지속 시간 규칙

커스텀 필드 및 페이로드

전달 및 검증

커스텀 런타임에서 장애 방지

​failproofai-sdk 설치

​Failproof 데몬 연결

​전체 실행 계측

​설정 레퍼런스

​이벤트 카탈로그

​상관관계 및 지속 시간 규칙

​커스텀 필드 및 페이로드

​전달 및 검증

​커스텀 런타임에서 장애 방지

`failproofai-sdk` 설치

Failproof 데몬 연결

전체 실행 계측

설정 레퍼런스

이벤트 카탈로그

상관관계 및 지속 시간 규칙

커스텀 필드 및 페이로드

전달 및 검증

커스텀 런타임에서 장애 방지