Skip to main content

설치

지원 버전: llama-index-core 0.14.23 ~ 0.15. 0.14.23은 워크플로우 스트림이 이 어댑터가 읽는 타입드 에이전트 이벤트를 포함하기 시작한 릴리즈입니다. 그 이전 버전에서는 모델 이름과 에이전트 구조가 모두 누락됩니다.

계측

LlamaIndex의 에이전트 API는 비동기입니다. 모든 스코프는 async withwith 모두에서 동일하게 작동하며 동일한 이벤트를 생성합니다. instrument()는 LlamaIndex의 전역 디스패처에 이벤트 핸들러와 스팬 핸들러를 연결합니다. 이를 통해 에이전트 루프 전체가 모델 호출뿐만 아니라 가시적으로 드러납니다.
LLM에 인수 하나를 추가하지 않으면 트레이스의 모든 토큰 카운트가 null이 됩니다. 아래의 토큰 카운트를 참고하세요.

토큰 카운트

FunctionAgentastream_chat을 호출하는데, llama-index-llms-openai는 스트리밍 시 stream_options={"include_usage": True}를 전송하지 않습니다. 따라서 프로바이더는 사용량 청크를 전송하지 않고, 어떤 계측 도구도 이를 읽을 수 없습니다. 이는 업스트림 LlamaIndex의 동작입니다. LLM에서 다음과 같이 직접 활성화하세요:
동일한 실행 및 모델 기준 측정 결과: 비스트리밍 호출(llm.chat, llm.achat)은 별도 설정 없이 사용량을 보고합니다. 기본 에이전트 경로인 스트리밍 경로에서만 이 설정이 필요합니다.

기록되는 항목

agent_id는 설정한 경우 FunctionAgent.name이 되고, 그렇지 않으면 워크플로우 클래스 이름이 됩니다. AgentWorkflow 하에서 턴을 가지는 각 에이전트는 워크플로우 아래 별도의 중첩 스팬을 가지므로, 핸드오프는 하나가 아닌 두 에이전트로 기록됩니다. 검색 출력은 전체 덤프 대신 요약됩니다. 리트리버는 문서를 반환하는데, 페이로드에 저장하면 쿼리마다 코퍼스 전체가 이벤트 스토어에 저장됩니다. 대신 문서 수, 점수 범위, 잘린 스니펫이 저장됩니다.

예제

에이전트 루프는 트레이스에 훅 쌍으로 나타납니다: init_run, setup_agent, run_agent_step, parse_agent_output, call_tool, aggregate_tool_results. 이들은 프레임워크 자체의 루프이므로 에이전트가 아닌 훅으로 분류되어 agent_id가 의미 있게 유지됩니다.

스팬 이름 지정

agent_id는 설정한 경우 FunctionAgent.name이 되고, 그렇지 않으면 워크플로우 클래스 이름이 됩니다.
AgentWorkflow에서 이 이름은 각 핸드오프가 기록되는 이름이기도 합니다:
따라서 agent_id어떤 에이전트가 작업했는지를, parent_id어떤 워크플로우에 속했는지를 알려줍니다. 나중에 제어권을 돌려받은 에이전트는 첫 번째 턴을 재개하는 것이 아니라 두 번째 턴을 새로 시작합니다. 재정의하거나 여러 에이전트를 하나의 부모 아래 묶으려면 실행을 감싸세요:
agent_id는 낮은 카디널리티로 유지하세요. 모든 대시보드 화면의 기본 패싯이므로 UUID나 실행별 문자열이 아닌 역할 또는 워크플로우 이름을 사용하세요.

세션 제어

이 어댑터는 session_id 옵션을 받지 않습니다. 세션은 감싸는 스코프에서 가져오며, 없을 경우 워크플로우 실행마다 생성된 uuid4().hex가 사용됩니다:

옵션

휴먼 인 더 루프

대기가 툴 내부에서 발생할 때 캡처됩니다:
일반 워크플로우 스텝에서의 ctx.wait_for_event는 캡처되지 않습니다. 런타임이 디스패처에 도달하기 전에 드롭을 감지하여 스텝이 종료되고 나중에 일시 정지 신호 없이 재실행됩니다. LlamaIndex가 문서화한 FunctionAgent 패턴은 툴 내부에서 대기하므로 완전히 캡처됩니다.

일반적인 문제

LLM에 additional_kwargs={"stream_options": {"include_usage": True}}를 추가하세요. 토큰 카운트를 참고하세요.
LlamaIndex에는 표준 usage 필드가 없습니다. 어댑터는 알려진 여러 형태를 시도하는데, 카운터 이름이 다른 인테그레이션은 어디에도 매칭되지 않습니다.원시 딕셔너리는 항상 전송되므로 페이로드의 usage를 확인하여 프로바이더가 어떤 이름을 사용했는지 확인하세요.채워진 usage와 빈 토큰 컬럼이 공존하는 것은 의도된 동작입니다 — 잘못된 숫자를 자신있게 표시하는 것보다 낫습니다.
이것은 반복마다 한 세트씩 생성되는 FunctionAgent 루프입니다. 대시보드에서 훅 이름으로 필터링하세요. 이 스텝 타이밍은 보통 모델 전용 어댑터 대신 이 어댑터를 사용하는 이유가 됩니다.
다음 순서로 확인하세요: instrument()가 실행 전에 호출되었는지; await 주변에 async with failproofai_sdk.session():이 있는지; llama-index-core가 0.14.23 이상인지; FAILPROOFAI_SDK_STRICT=1이 설정된 경우 저하된 훅이 삼켜지는 대신 예외를 발생시키는지.

다음 단계

작동 원리

쌍, ID, 세션 라이프사이클, 전달 방식.

트레이스 읽기

방금 캡처한 세션에서 인과 관계를 따라가 보세요.

다른 프레임워크

LangGraph, CrewAI, Pydantic AI, 커스텀 에이전트.