본문으로 건너뛰기

LLM 트랜잭션 설정

AI Agent Observability에서 워크플로우와 에이전트 패턴을 계측하기 위한 공개 API 사용 가이드입니다.

워크플로우 및 AI 에이전트의 영역만 선언하면, 해당 스코프 안에서 발생하는 모든 LLM API 호출이 별도의 트랜잭션이 아니라 하나의 LLM 트랜잭션 아래 "스텝"으로 묶여 수집됩니다. 사용자가 할 일은 영역을 표시하는 것뿐입니다.

AI Agent Observability의 트랜잭션 종류​

LLM 트랜잭션의 종류는 총 3종입니다.

  • Workflow(기본) — [Workflow] <name>

  • Agent — [Agent] <name>

  • LLMAPI — 워크플로우로 감싸지 않은 단독 호출은 [LLMAPI] Pure LLM API로 수집됩니다.

워크플로우 안에서 다른 워크플로우가 실행되면 부모-자식 트랜잭션이 트라잭토리(Trajectory)로 연결되어 호출 관계를 추적할 수 있습니다.

워크플로우 트랜잭션 설정​

데코레이터와 컨텍스트 매니저 두 가지 형태를 모두 지원합니다.

데코레이터​

워크플로우 이름이 함수 단위로 고정되어 있을 때 사용합니다.

from whatap.llm import workflow

@workflow("support_chat")
async def support_chat(conversation_id, message, history):
    intent = await classify_intent(message)   # 이 안의 LLM 호출들은
    docs   = await retrieve(message)          # 전부 이 워크플로우의 "스텝"이 됩니다
    answer = await generate(message, docs)
    return {"intent": intent, "answer": answer}

컨텍스트 매니저​

워크플로우 이름을 런타임에 결정하거나, 함수 일부 구간만 감싸고 싶을 때 사용합니다.

from whatap.llm import workflow

with workflow("ticket_triage"):
    classification = await _classify(ticket_text)
    entities = await _extract(ticket_text)
주의

비동기 코드에서도 async with이 아니라 위와 같이 with를 사용하세요. workflow와 agent는 동기 컨텍스트 매니저이므로, 스코프 안에서 await하는 것은 문제가 없지만 async with으로 열면 에러가 발생합니다.

에이전트 트랜잭션 설정​

사용법은 워크플로우 설정과 동일하며, 트랜잭션 이름의 접두어만 [Agent]로 바뀝니다. 데코레이터와 컨텍스트 매니저 두 가지 형태를 모두 지원합니다.

데코레이터​

에이전트 실행 함수가 고정되어 있을 때 사용합니다.

from whatap.llm import agent

@agent("react_agent")
async def run_agent(task):
    ...
    return result

컨텍스트 매니저​

에이전트 이름을 런타임에 결정하거나, 실행 구간 일부만 감싸고 싶을 때 사용합니다.

from whatap.llm import agent

with agent("react_agent"):
    result = await react_agent.run(task)

코드 수정 없이 영역 선언하기​

애플리케이션 코드를 수정할 수 없을 때는 설정으로 워크플로우 경계를 지정할 수 있습니다. whatap.conf에 대상 메서드를 나열하면, 해당 메서드의 실행이 곧 워크플로우 경계가 됩니다. 워크플로우 이름은 메서드 이름이 사용됩니다.

whatap.conf
workflow_method_patterns=myapp:RagService.run, myapp.agent:run_agent

모듈:클래스.메서드 또는 모듈:함수 형태로 쉼표로 구분합니다.

자동 계측 지원 프레임워크​

다음 프레임워크는 별도의 영역 선언 없이 LLM 트랜잭션이 자동으로 수집됩니다.

프레임워크수집 방식
hermes-agent에이전트 실행 레이어(AIAgent.run_conversation)를 계측하여 [Agent] <name> 트랜잭션으로 등록합니다. 게이트웨이 인바운드(GatewayRunner._handle_message)는 [Workflow] gateway/<platform> 트랜잭션으로 등록되고, 그 안에서 실행된 에이전트가 자식 트랜잭션으로 연결됩니다.
LangGraph컴파일된 그래프의 실행 경계(Pregel.invoke / ainvoke / stream / astream)를 계측하여 그래프 1회 실행 = LLM 트랜잭션 1건으로 등록합니다. tools 노드를 가진 그래프(create_react_agent)는 [Agent], 그 외는 [Workflow]로 등록됩니다. 서브그래프는 자식 트랜잭션으로 중첩 연결됩니다.
최종 수정: