커스텀 에이전트

각 설정, 메서드, 필드가 하는 일을 설명합니다. 처음 계측하는 경우라면 가이드부터 시작하세요 — 이 페이지는 참조용입니다.

커스텀 에이전트 가이드

설치, 계측, 이벤트 메서드, 실제 예제 및 흔한 문제들.

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

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 데몬을 Cloud에 연결합니다.
계측된 세션을 한 번 실행한 후 Observe → Events에서 정확한 ID를 확인합니다.
Observe → Sessions으로 이동하여 동일한 환경을 선택하고 재구성된 트레이스를 엽니다.

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
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를 명시적으로 전달해도 되며, 이 경우 전달한 값이 우선 적용됩니다. 스코프에 바인딩된 값도 없고 직접 전달하지도 않으면, Cloud가 조용히 버릴 이벤트를 방출하는 대신 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는 예외입니다. 실제 프로바이더 지연은 여러분만 알고 있습니다. 밀리초 단위의 정수를 전달하세요 — float를 전달하면 예외가 발생합니다. 해당 컬럼이 32비트 정수이므로 float는 빈 값으로 저장될 수 있기 때문입니다.

엣지 케이스

id는 같은 종류, 같은 세션 내에서만 고유하면 됩니다. 도구 호출과 훅이 같은 id를 공유할 수 있으며, 동시에 실행 중인 두 세션이 같은 id를 재사용해도 충돌하지 않습니다.
id는 에이전트에 종속되지 않습니다. 한 에이전트에서 열고 다른 에이전트에서 닫은 쌍도 여전히 매칭됩니다 — 멀티 에이전트 코드에서는 이것이 일반적인 경우입니다.
request_id는 선택 사항이지만 권장합니다. 없으면 모델 이벤트는 도착 순서대로 쌍이 맞춰지므로, 같은 에이전트에서 두 개의 동시 호출이 잘못 쌍을 이룰 수 있습니다.
프로세스를 나눠 처리된 쌍은 Cloud에서 여전히 매칭되지만, 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, 모델 객체 등 — 은 문자열로 저장됩니다.

필드 이름에 접두사를 붙이세요. 추가 필드는 마지막에 적용되므로, model, tool_name, outcome이라는 이름의 필드는 실제 값을 조용히 덮어씁니다. 프레임워크 어댑터는 fw_를 사용합니다; 동일하게 하면 충돌이 발생하지 않습니다.오탈자가 있는 선택 필드가 오류를 발생시키지 않는 것도 이 때문입니다 — 그냥 새로운 커스텀 필드가 됩니다. Cloud에서 표준 필드가 누락된 경우 먼저 철자를 확인하세요.

다음 다섯 가지 이름은 예약되어 있어 사용이 거부됩니다: 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

Cloud가 비어 있다면 $FAILPROOFAI_HOME/custom-agents/events를 확인하고, 그렇지 않으면 ~/.failproofai/custom-agents/events를 확인하세요. JSONL 파일이 있으면 SDK가 이벤트를 방출했다는 증거입니다. 스풀이 계속 늘어나면 데몬 설정이나 전달 문제를, 스풀이 비어 있으면 계측 또는 프로세스 수명 문제를 의심하세요.

스풀은 데몬이 중지된 상태에서만 확인하세요. 데몬이 실행 중이면 밀리초 단위로 배치를 수집하고 삭제하므로, 디렉터리 목록 조회가 수집기와 경쟁 상태가 되어 실제로 방출된 것보다 훨씬 적은 이벤트만 보일 수 있습니다.

커스텀 런타임에서 실패 방지

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

Connect your agents

Reference