커스텀 에이전트

모든 설정, 메서드, 필드에 대한 설명입니다. 처음 계측을 시작하는 경우라면 가이드를 먼저 참조하세요 — 이 페이지는 참조용입니다.

커스텀 에이전트 가이드

설치, 계측, 이벤트 메서드, 실제 예제, 그리고 자주 발생하는 문제들을 다룹니다.

프레임워크를 사용 중이신가요?

LangChain, CrewAI, LlamaIndex, Pydantic AI는 한 번의 호출로 자체 계측됩니다.

Python 3.10 이상. 런타임 의존성 없음.

설치

pip install failproofai-sdk

패키지는 failproofai-sdk로 설치되며, Python에서는 failproofai_sdk로 임포트합니다. failproofai-sdk[langgraph]와 같은 프레임워크 extras는 해당 프레임워크를 함께 설치하지만, 어댑터는 항상 기본 wheel에 포함되어 있습니다.

Failproof 데몬 연결

대시보드
CLI

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

events:add 키를 셸에서 읽어옵니다. read -s는 에코되지 않는 프롬프트에서 입력을 받으므로, 명령어나 셸 히스토리에 노출되지 않습니다.

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

그런 다음 머신을 설정하고 연결 상태를 확인합니다.

failproofai config
failproofai config --status

설정

import failproofai_sdk

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

인수	역할
`environment`	모든 이벤트에 붙는 레이블 — `production`, `staging`, `prod-eu`. 기본값은 `dev`.
`flush_interval`	백그라운드 스레드가 디스크에 기록하는 주기(초). 기본값은 `0.5`.
`base_dir`	기록 위치. 기본값은 데몬의 스풀이며, 특별한 이유가 없다면 그대로 두는 것이 좋습니다.

환경 변수로 설정할 수도 있습니다.

변수	역할
`AGENTEYE_ENVIRONMENT`	코드 변경 없이 `environment`를 설정합니다. 레이블이 앱보다 배포 환경에 속하는 경우에 유용합니다. `configure()` 인수가 우선합니다.
`FAILPROOFAI_HOME`	스풀을 보관하는 Failproof AI 루트 경로를 변경합니다.
`FAILPROOFAI_SDK_STRICT`	`1`로 설정하면 계측 오류가 로깅 대신 예외를 발생시킵니다.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1`로 설정하면 프레임워크 호환성 문제가 경고 후 계속 진행하는 대신 예외를 발생시킵니다.

environment에 쉼표를 사용하지 마세요. 수집 과정에서 해당 필드를 쉼표로 분리해 필터를 구성하며, 레이블에 쉼표가 포함된 이벤트는 건너뜁니다 — 결과적으로 전체 실행이 소리 없이 사라집니다. prod,eu가 아니라 prod-eu로 작성하세요.configure(environment="prod,eu")는 즉시 예외를 발생시켜 문제를 바로 알 수 있습니다. AGENTEYE_ENVIRONMENT는 예외를 발생시킬 수 없습니다 — 호출 주체가 없기 때문에 — 따라서 한 번 경고를 출력하고 dev로 폴백합니다.

이벤트는 메모리에 큐잉되었다가 flush_interval초마다 백그라운드에서 기록되며, 인터프리터 종료 시 최종 플러시가 이루어집니다. 프로세스가 강제 종료되면 아직 기록되지 않은 이벤트는 손실됩니다.

식별자

모든 이벤트는 세션과 에이전트에 속합니다. 스코프가 두 가지를 모두 채워주므로, 직접 전달하는 경우는 드뭅니다.

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

session_id나 agent_id를 명시적으로 전달하면 해당 값이 우선합니다. 스코프에 바인딩되지도 않고 인수도 전달하지 않으면, 클라우드가 조용히 버릴 이벤트를 내보내는 대신 TypeError가 발생합니다.

식별자는 컨텍스트 변수에 의존합니다. asyncio 태스크에서는 자동으로 전파되지만, 새 스레드에서는 그렇지 않습니다 — 워커를 failproofai_sdk.propagate()로 감싸지 않으면 해당 이벤트가 미연결 상태로 남습니다.

이벤트 카탈로그

15개의 메서드가 있습니다. 대부분은 쌍으로 구성되어 있어, 시작 메서드를 호출한 후 종료 메서드를 호출하면 SDK가 그 사이의 시간을 측정합니다.

	시작	종료
에이전트	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
모델	`model_request`	`model_response`
도구	`tool_use`	`tool_result`
훅	`hook_triggered`	`hook_completed`
사람	`human_wait`	`human_input`

error, human_pause, human_interrupt는 단독으로 사용됩니다.

메서드별 전체 필드

모든 메서드는 session_id와 agent_id도 받으며, 스코프가 이를 자동으로 채워줍니다. None으로 남겨진 값은 JSON null로 전송되는 대신 제거되며, 모든 메서드는 None을 반환합니다.

메서드	필수	선택
`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`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`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"를 포함하여 그 외의 모든 값은 성공으로 처리됩니다.

쌍 매칭과 소요 시간

규칙은 하나입니다: 종료 이벤트에 시작 이벤트와 동일한 id를 전달하세요. 이것이 두 이벤트를 쌍으로 묶고 SDK가 소요 시간을 측정하는 방법입니다.

쌍	매칭 기준
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

duration_ms는 직접 전달하지 마세요. SDK가 측정하며, 전달하면 ValueError가 발생합니다. 유일한 예외는 model_response로, 실제 제공자 지연 시간을 오직 사용자만 알 수 있습니다. 정수 밀리초를 전달하세요 — 해당 컬럼은 32비트 정수이므로 float를 전달하면 예외가 발생하여 값이 비어있게 됩니다.

예외 케이스

id는 종류별, 세션별로만 고유하면 됩니다. 도구 호출과 훅이 동일한 id를 공유할 수 있으며, 동시에 실행 중인 두 세션도 id가 겹쳐도 충돌하지 않습니다.
id는 에이전트 범위로 한정되지 않습니다. 한 에이전트에서 시작되고 다른 에이전트에서 종료된 쌍도 정상적으로 매칭됩니다 — 이는 멀티 에이전트 코드에서 일반적인 경우입니다.
request_id는 선택 사항이지만 권장합니다. 없을 경우, 모델 이벤트는 도착 순서대로 쌍을 맞추므로 동일 에이전트 내에서 두 개의 동시 호출이 잘못 매칭될 수 있습니다.
프로세스를 가로지르는 쌍도 클라우드에서는 매칭되지만, SDK는 시간을 측정할 수 없습니다 — 어느 프로세스도 양쪽 절반을 모두 보지 못했기 때문입니다.
최대 10,000개의 시작 이벤트만 종료 이벤트를 기다릴 수 있습니다. 그 이상이 되면 가장 오래된 것이 제거되어, 누수가 무한히 커지지 않습니다.

커스텀 필드

추가로 전달하는 키워드는 이벤트와 함께 저장됩니다.

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # 커스텀 필드
)

나중에 쿼리하려면 JSON 타입을 사용하는 것이 좋습니다. UUID, datetime, Decimal, set, bytes, 모델 객체 등 그 외의 타입은 문자열로 저장됩니다.

필드 이름에 접두사를 붙이세요. extras는 마지막에 적용되므로, model, tool_name, outcome이라는 필드는 실제 값을 소리 없이 덮어씁니다. 프레임워크 어댑터는 fw_를 사용합니다. 동일한 방식을 따르면 충돌이 발생하지 않습니다.오타가 있는 선택적 필드는 오류가 발생하지 않고 새로운 커스텀 필드가 됩니다. 클라우드에서 표준 필드가 없는 경우, 먼저 철자를 확인하세요.

다음 다섯 가지 이름은 예약되어 있으며 사용이 거부됩니다: timestamp, session_id, agent_id, type, environment.

전달 및 검증

대시보드
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

클라우드가 비어있다면, $FAILPROOFAI_HOME/custom-agents/events 또는 ~/.failproofai/custom-agents/events를 확인하세요. JSONL 파일이 있으면 SDK 방출이 이루어진 것이고, 스풀이 계속 커진다면 데몬 설정이나 전달 문제이며, 스풀이 비어있다면 계측이나 프로세스 수명 문제입니다.

데몬이 중지된 상태에서만 스풀을 검사하세요. 실행 중에는 데몬이 밀리초 단위로 배치를 수집하고 삭제하므로, 디렉터리 목록이 수집기와 경쟁하여 실제로 방출된 이벤트보다 훨씬 적은 수를 표시할 수 있습니다.

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

감사 결과와 연결된 트레이스를 사용하여 안전하지 않은 동작, 필요한 근거, 그리고 의도된 응답을 정의하세요. 커스텀 집행 통합은 실행 전에 동작을 노출하고, 구조화된 입력을 정책 엔진에 전달하며, 결과로 나오는 allow, instruct, deny 결정을 적용해야 합니다. Failproof AI에 문의하시면 런타임의 모델, 도구, 라이프사이클 경계를 정책 훅에 매핑하고 통합을 함께 검증하는 데 도움을 드리겠습니다.

Connect your agents

Reference