ai-agent: add conversation query protocol for the AI Sessionizer - #166
Merged
Conversation
Conversations of long-lived AI agents reach the OAP from the AI Sessionizer (apache/skywalking-ai-sessionizer) as two file formats pushed over OTLP logs under the AI_AGENT layer: Session Data (.sd) and Session Flow (.sf). The OAP stores every file verbatim and rebuilds a conversation on read. Three queries, keyed by the conversation as the Sessionizer's model defines it (the unit of storage, analysis and export; a session is provenance): - listConversations: one row per conversation from the newest round's attributes, by service, optional sender instance and duration, newest first, at most `limit` rounds folded to one row per conversation. - getConversationView: the whole conversation once, as one `asz.view` 1.0 file in YAML, the same file `asz view` writes locally. Verification is content (summary.state, summary.problems), not an error. - getConversationRawFiles: every landed file and round of a conversation, as stored, for tooling and export; `body` is read only when selected, and an optional `files` id list narrows the read to named files. Follows the protocol's conventions: ServiceCondition and InstanceCondition from common.graphqls, errorReason and debuggingTrace on every result, and a debug flag on every query.
This was referenced Sep 5, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
ai-agent-conversation.graphqls, the query protocol for conversations of long-lived AI agents landed by the AI Sessionizer.A conversation reaches the OAP as two file formats pushed over OTLP logs under the
AI_AGENTlayer: Session Data (.sd, the records of one session as collected) and Session Flow (.sf, an append-only chain of rounds the assembler derived from them). The OAP stores every file verbatim and rebuilds a conversation on read.Everything is keyed by the conversation, as the Sessionizer's model defines it: the durable ownership boundary and the unit of storage, analysis and export. A session is the source-runtime context a record came from, carried as provenance; one conversation may contain several, and a session appears here only as the owner of a raw
.sdfile.Three queries:
listConversations(condition, duration, debug): one row per conversation, built from the newest round's attributes without decoding anything. Filters are service, optional sender instance and duration; the rounds are read newest first, at mostlimit(default 1000), then folded to one row per conversation.getConversationView(condition, debug): the whole conversation once, as oneasz.viewversion 1.0 file in YAML, the same fileasz viewwrites locally. The UI makes this one call per conversation and no other; evidence is inside the file. Verification is content (summary.state,summary.problems), never an error.getConversationRawFiles(condition, files, debug): every landed file and round of a conversation, as stored, for tooling and export.bodyis read from storage only when selected; the optionalfilesid list narrows the read to named files, which is an exact indexed read because a.sdid names its session and itsseq.Conventions followed:
ServiceConditionandInstanceConditionfromcommon.graphqls,errorReasonplus optionaldebuggingTraceon every result, anddebug: Booleanon every query. The file parses together withcommon.graphqlsunder graphql-java 25.The OAP side (the
AI_AGENTlayer, the LAL output builder, the two storage models and the resolvers) follows in apache/skywalking, which will register this file inGraphQLQueryProviderand bump the submodule.🤖 Generated with Claude Code
https://claude.ai/code/session_013BnFvESyArK2s9CJKn8Qvf