블로그 | 모하지?

원문: Koog Documentation — agent-events 이 글은 Koog 공식 문서의 agent-events 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

에이전트 이벤트

에이전트 이벤트는 에이전트 워크플로의 일부로 발생하는 작업 또는 상호 작용입니다. 여기에는 다음이 포함됩니다.

에이전트 수명주기 이벤트
전략 이벤트
노드 실행 이벤트
LLM 통화 이벤트
LLM 스트리밍 이벤트
도구 실행 이벤트

참고: 기능 이벤트는 Agent-Core 모듈에 정의되어 있으며 ai.koog.agents.core.feature.model.events 패키지 아래에 있습니다. agents-features-trace 및 agents-features-event-handler와 같은 기능은 이러한 이벤트를 사용하여 에이전트 실행 중에 생성된 메시지를 처리하고 전달합니다.

사전 정의된 이벤트 유형

Koog는 사용자 정의 메시지 프로세서에서 사용할 수 있는 사전 정의된 이벤트 유형을 제공합니다. 미리 정의된 이벤트는 다음과 같습니다. 관련된 개체에 따라 여러 범주로 분류됩니다.

Agent events
Strategy events
Node events
Subgraph events
LLM call events
LLM streaming events
Tool execution events

에이전트 이벤트

AgentStartingEvent

에이전트 실행의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`agentId`	끈	예	AI 에이전트의 고유 식별자입니다.
`runId`	끈	예	AI 에이전트 실행의 고유 식별자입니다.

AgentCompleted이벤트

에이전트 실행의 종료를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`agentId`	끈	예	AI 에이전트의 고유 식별자입니다.
`runId`	끈	예	AI 에이전트 실행의 고유 식별자입니다.
`result`	끈	예	에이전트 실행 결과입니다. 결과가 없으면 `null`일 수 있습니다.

AgentExecutionFailed이벤트

에이전트 실행 중 오류 발생을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`agentId`	끈	예	AI 에이전트의 고유 식별자입니다.
`runId`	끈	예	AI 에이전트 실행의 고유 식별자입니다.
`error`	AIAgentError	예	에이전트 실행 중에 발생한 특정 오류입니다. 자세한 내용은 AIAgentError을 참조하세요.

AgentClosingEvent

에이전트의 종료 또는 종료를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`agentId`	끈	예	AI 에이전트의 고유 식별자입니다.

AIAgentError 클래스는 에이전트 실행 중에 발생한 오류에 대한 자세한 내용을 제공합니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`message`	끈	예		특정 오류에 대한 자세한 내용을 제공하는 메시지입니다.
`stackTrace`	끈	예		마지막으로 실행된 코드까지의 스택 레코드 모음입니다.
`cause`	끈	아니요	null	가능한 경우 오류의 원인입니다.

AgentExecutionInfo 클래스는 실행 경로에 대한 컨텍스트 정보를 제공하여 에이전트 실행 내에서 중첩된 실행 컨텍스트를 추적할 수 있습니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`parent`	에이전트실행정보	아니요	null	상위 실행 컨텍스트에 대한 참조입니다. null인 경우 루트 실행 수준을 나타냅니다.
`partName`	끈	예		실행의 현재 부분 또는 세그먼트의 이름을 나타내는 문자열입니다.

전략 이벤트

그래프전략StartingEvent

그래프 기반 전략 실행의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	전략 실행의 고유 식별자입니다.
`strategyName`	끈	예	전략의 이름입니다.
`graph`	전략이벤트 그래프	예	전략 워크플로를 나타내는 그래프 구조입니다.

FunctionalStrategyStartingEvent

기능적 전략 실행의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	전략 실행의 고유 식별자입니다.
`strategyName`	끈	예	전략의 이름입니다.

전략완료이벤트

전략 실행의 끝을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	전략 실행의 고유 식별자입니다.
`strategyName`	끈	예	전략의 이름입니다.
`result`	끈	예	실행 결과입니다. 결과가 없으면 `null`일 수 있습니다.

노드 이벤트

NodeExecutionStartingEvent

노드 실행의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략 실행의 고유 식별자입니다.
`nodeName`	끈	예		실행이 시작된 노드의 이름입니다.
`input`	Json요소	아니요	null	노드의 입력 값입니다.

NodeExecutionCompleted이벤트

노드 실행의 끝을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략 실행의 고유 식별자입니다.
`nodeName`	끈	예		실행이 종료된 노드의 이름입니다.
`input`	Json요소	아니요	null	노드의 입력 값입니다.
`output`	Json요소	아니요	null	노드에서 생성된 출력 값입니다.

NodeExecutionFailed이벤트

노드 실행 중에 발생한 오류를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략 실행의 고유 식별자입니다.
`nodeName`	끈	예		오류가 발생한 노드의 이름입니다.
`input`	Json요소	아니요	null	노드에 제공되는 입력 데이터입니다.
`error`	AIAgentError	예		노드 실행 중에 발생한 특정 오류입니다. 자세한 내용은 AIAgentError을 참조하세요.

하위 그래프 이벤트

SubgraphExecutionStartingEvent

하위 그래프 실행의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략 실행의 고유 식별자입니다.
`subgraphName`	끈	예		실행이 시작된 하위 그래프의 이름입니다.
`input`	Json요소	아니요	null	하위 그래프의 입력 값입니다.

SubgraphExecutionCompletedEvent

하위 그래프 실행의 끝을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략 실행의 고유 식별자입니다.
`subgraphName`	끈	예		실행이 종료된 하위 그래프의 이름입니다.
`input`	Json요소	아니요	null	하위 그래프의 입력 값입니다.
`output`	Json요소	아니요	null	하위 그래프에 의해 생성된 출력 값입니다.

SubgraphExecutionFailedEvent

하위 그래프 실행 중에 발생한 오류를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략 실행의 고유 식별자입니다.
`subgraphName`	끈	예		오류가 발생한 하위 그래프의 이름입니다.
`input`	Json요소	아니요	null	하위 그래프에 제공되는 입력 데이터입니다.
`error`	AIAgentError	예		하위 그래프 실행 중에 발생한 특정 오류입니다. 자세한 내용은 AIAgentError을 참조하세요.

LLM 통화 이벤트

LLMCallStartingEvent

LLM 호출의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	LLM 실행의 고유 식별자입니다.
`prompt`	즉각적인	예	모델에 전송되는 프롬프트입니다. 자세한 내용은 Prompt을 참조하세요.
`model`	모델정보	예	모델 정보입니다. ModelInfo을 참조하세요.
`tools`	목록	예	모델이 호출할 수 있는 도구 목록입니다.

Prompt 클래스는 메시지 목록, 고유 식별자 및 언어 모델 설정을 위한 선택적 매개변수입니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`messages`	목록	예		프롬프트가 구성되는 메시지 목록입니다.
`id`	끈	예		프롬프트의 고유 식별자입니다.
`params`	LLMParams	아니요	LLMParams()	LLM이 콘텐츠를 생성하는 방식을 제어하는 설정입니다.

ModelInfo 클래스는 공급자, 모델 식별자 및 특성을 포함하여 언어 모델에 대한 정보를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`provider`	끈	예		공급자 식별자(예: "openai", "google", "anthropic")입니다.
`model`	끈	예		모델 식별자(예: "gpt-4", "claude-3")입니다.
`displayName`	끈	아니요	null	선택적으로 사람이 읽을 수 있는 모델 표시 이름입니다.
`contextLength`	긴	아니요	null	모델이 처리할 수 있는 최대 토큰 수입니다.
`maxOutputTokens`	긴	아니요	null	모델이 생성할 수 있는 최대 토큰 수입니다.

LLMCallCompleted이벤트

LLM 통화의 종료를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		LLM 실행의 고유 식별자입니다.
`prompt`	즉각적인	예		통화에 사용되는 프롬프트입니다.
`model`	모델정보	예		모델 정보입니다. ModelInfo을 참조하세요.
`responses`	목록<Message.Response>	예		모델이 반환한 하나 이상의 응답입니다.
`moderationResponse`	조정결과	아니요	null	중재 응답(있는 경우)입니다.

LLM 스트리밍 이벤트

LLM스트리밍시작이벤트

LLM 스트리밍 호출의 시작을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	LLM 실행의 고유 식별자입니다.
`prompt`	즉각적인	예	모델에 전송되는 프롬프트입니다.
`model`	모델정보	예	모델 정보입니다. ModelInfo을 참조하세요.
`tools`	목록	예	모델이 호출할 수 있는 도구 목록입니다.

LLMStreamingFrameReceivedEvent

LLM에서 수신된 스트리밍 프레임을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	LLM 실행의 고유 식별자입니다.
`prompt`	즉각적인	예	모델에 전송되는 프롬프트입니다.
`model`	모델정보	예	모델 정보입니다. ModelInfo을 참조하세요.
`frame`	스트림프레임	예	스트림에서 수신된 프레임입니다.

LLM스트리밍실패이벤트

LLM 스트리밍 호출 중 오류 발생을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	LLM 실행의 고유 식별자입니다.
`prompt`	즉각적인	예	모델에 전송되는 프롬프트입니다.
`model`	모델정보	예	모델 정보입니다. ModelInfo을 참조하세요.
`error`	AIAgentError	예	스트리밍 중에 발생한 특정 오류입니다. 자세한 내용은 AIAgentError을 참조하세요.

LLM스트리밍완료이벤트

LLM 스트리밍 호출의 끝을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	설명
`eventId`	끈	예	이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예	이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예	LLM 실행의 고유 식별자입니다.
`prompt`	즉각적인	예	모델에 전송되는 프롬프트입니다.
`model`	모델정보	예	모델 정보입니다. ModelInfo을 참조하세요.
`tools`	목록	예	모델이 호출할 수 있는 도구 목록입니다.

도구 실행 이벤트

ToolCallStartingEvent

도구를 호출하는 모델의 이벤트를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략/에이전트 실행의 고유 식별자입니다.
`toolCallId`	끈	아니요	null	사용 가능한 경우 도구 호출의 식별자입니다.
`toolName`	끈	예		도구의 이름입니다.
`toolArgs`	JsonObject	예		도구에 제공되는 인수입니다.

도구 유효성 검사실패이벤트

도구 호출 중 유효성 검사 오류가 발생했음을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략/에이전트 실행의 고유 식별자입니다.
`toolCallId`	끈	아니요	null	사용 가능한 경우 도구 호출의 식별자입니다.
`toolName`	끈	예		유효성 검사에 실패한 도구의 이름입니다.
`toolArgs`	JsonObject	예		도구에 제공되는 인수입니다.
`toolDescription`	끈	아니요	null	유효성 검사 오류가 발생한 도구에 대한 설명입니다.
`message`	끈	아니요	null	유효성 검사 오류를 설명하는 메시지입니다.
`error`	AIAgentError	예		발생한 특정 오류입니다. 자세한 내용은 AIAgentError을 참조하세요.

ToolCallFailed이벤트

도구 실행 실패를 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		전략/에이전트 실행의 고유 식별자입니다.
`toolCallId`	끈	아니요	null	사용 가능한 경우 도구 호출의 식별자입니다.
`toolName`	끈	예		도구의 이름입니다.
`toolArgs`	JsonObject	예		도구에 제공되는 인수입니다.
`toolDescription`	끈	아니요	null	실패한 도구에 대한 설명입니다.
`error`	AIAgentError	예		도구를 호출하려고 할 때 발생한 특정 오류입니다. 자세한 내용은 AIAgentError을 참조하세요.

ToolCallCompleted이벤트

결과 반환과 함께 성공적인 도구 호출을 나타냅니다. 다음 필드가 포함됩니다.

이름	데이터 유형	필수의	기본	설명
`eventId`	끈	예		이벤트 또는 이벤트 그룹의 고유 식별자입니다.
`executionInfo`	에이전트실행정보	예		이 이벤트와 관련된 실행에 대한 상황별 정보를 제공합니다.
`runId`	끈	예		실행의 고유 식별자입니다.
`toolCallId`	끈	아니요	null	도구 호출의 식별자입니다.
`toolName`	끈	예		도구의 이름입니다.
`toolArgs`	JsonObject	예		도구에 제공되는 인수입니다.
`toolDescription`	끈	아니요	null	실행된 도구에 대한 설명입니다.
`result`	Json요소	아니요	null	도구 호출의 결과입니다.

1install(Tracing) {2    val fileWriter = TraceFeatureMessageFileWriter.create(outputPath)3    addMessageProcessor(fileWriter)4    5    // Only trace LLM calls6    fileWriter.setMessageFilter { message ->7        message is LLMCallStartingEvent || message is LLMCallCompletedEvent8    }9}

자바

1.install(Tracing.Feature, config -> {2    var fileWriter = TraceFeatureMessageFileWriter.create(outputPath);3    config.addMessageProcessor(fileWriter);45    // Only trace LLM calls6    fileWriter.setMessageFilter(message ->7        message instanceof LLMCallStartingEvent || message instanceof LLMCallCompletedEvent8    );9})

여러 메시지 프로세서를 사용할 수 있나요?

예, 여러 메시지 프로세서를 추가하여 동시에 여러 대상을 추적할 수 있습니다.

코틀린

1install(Tracing) {2    addMessageProcessor(TraceFeatureMessageLogWriter(logger))3    addMessageProcessor(TraceFeatureMessageFileWriter.create(outputPath))4    addMessageProcessor(TraceFeatureMessageRemoteWriter(connectionConfig))5}

자바

1.install(Tracing.Feature, config -> {2    config.addMessageProcessor(TraceFeatureMessageLogWriter.create(logger));3    config.addMessageProcessor(TraceFeatureMessageFileWriter.create(outputPath));4    config.addMessageProcessor(new TraceFeatureMessageRemoteWriter());5})

사용자 정의 메시지 프로세서를 어떻게 만들 수 있나요?

FeatureMessageProcessor 인터페이스를 구현합니다.

코틀린

1class CustomTraceProcessor : FeatureMessageProcessor() {23    override suspend fun processMessage(message: FeatureMessage) {4        // Custom processing logic5        if (message is NodeExecutionStartingEvent) {6            // Process node start event7        } else if (message is LLMCallCompletedEvent) {8            // Process LLM call end event9        } else {10            // Handle other event types11        }12    }1314    override suspend fun close() {15        // Close connections if established16    }17}1819val agent = AIAgent(20    promptExecutor = simpleOllamaAIExecutor(),21    llmModel = OllamaModels.Meta.LLAMA_3_2,22) {23    install(Tracing) {24        // Use your custom processor25        addMessageProcessor(CustomTraceProcessor())26    }27}

자바

1class CustomTraceProcessor extends FeatureMessageProcessor {23    @Override4    protected void handleMessage(FeatureMessage message) {5        // Custom processing logic6        if (message instanceof NodeExecutionStartingEvent) {7            // Process node start event8        } else if (message instanceof LLMCallCompletedEvent) {9            // Process LLM call end event10        } else {11            // Handle other event types12        }13    }1415    @Override16    public void handleClose() {17        // Close connections if established18    }19}2021var agent = AIAgent.builder()22    .promptExecutor(PromptExecutor.builder().ollama().build())23    .llmModel(OllamaModels.Meta.LLAMA_3_2)2425    .install(Tracing.Feature, config -> {26        // Use your custom processor27        config.addMessageProcessor(new CustomTraceProcessor());28    })29    .build();

메시지 프로세서에서 처리할 수 있는 기존 이벤트 유형에 대한 자세한 내용은 Predefined event types을 참조하세요.