feat(agenttool): group in-process sub-agents by conversation id (not shared session id)

[alenkacz]

What

Alternative to #153. Same goal — make an in-process agenttool sub-agent group with its parent as one conversation in session-oriented observability (Langfuse) — but without overloading the storage session.ID.

#153 made the sub-agent reuse the parent's session.ID. That conflates a storage primary key with a telemetry grouping id, and is safe only while the sub-agent session is never persisted — an invariant nothing enforces:

• Both session.Store impls (InMemoryStore, Kafka KVStore) key solely on session.ID with whole-record last-write-wins; there is no compound key or merge.
• AgentTool.New accepts any agent.Agent, so a persisting sub-agent (or future persistence on this path) would write under the shared id.
• Tools execute concurrently (default 3-way), so multiple sub-agents would adopt the same parent id at once → silent lost-update clobbering of sibling / parent sessions.

#153's own code comment concedes this ("safe ONLY because this session is never loaded or persisted"). This PR removes the hazard instead of documenting it.

How

Decouple the conversation/grouping id from the storage id:

• agent (+ llmagent): expose the calling agent's InvocationMetadata on the tool-execution ctx via new ContextWithInvocation / InvocationFromContext helpers. llmagent sets it before every tool call, so a tool can read the parent invocation (its session, conversation id) without a new tool interface; tools that ignore it are unaffected.
• agenttool: the sub-agent keeps its own freshly minted, globally unique session.ID (can never collide in a store). When a parent invocation is in ctx, it records the parent's conversation id in session metadata — propagated transitively, so nested sub-agents group under the root conversation.
• store/session: new ConversationID(*State) resolver (single source of truth) — returns the conversation id from metadata, else the session's own id. The metadata key is namespaced under redpanda.agent.conversation_id so it can't be confused with caller-supplied metadata (and matches the OTel attribute name).
• plugins/otel: emit gen_ai.conversation.id and the injector SessionID (→ langfuse.session.id) from ConversationID on invocation, model and tool spans, so the whole sub-agent subtree reports one consistent conversation id.

Within-trace parent/child nesting (the "sub-agent was spawned by this tool call" edge) is already free via ctx span propagation — the sub-agent's invoke_agent span is a child of the parent's execute_tool span. This PR only aligns the conversation-id value for cross-span / Langfuse session grouping.

Net: grouping is identical to #153 at the telemetry layer, but every storage session.ID stays unique — the "safe only while unpersisted" caveat is gone.

Scope

Deliberately limited to sharing the conversation id — the one thing session grouping needs. Direct cross-trace parent linkage (a parent_invocation_id back-reference, or the spawning gen_ai.tool.call.id) is not included: within a trace it is redundant with span parentage, and the only consumer that would need it across traces is the downstream ADP transcript-assembly query path. It can be added there, when a query actually requires it.

Tests

tool/agenttool/session_grouping_test.go covers: unique sub-agent id (never the parent's), grouping under the parent's conversation id, transitive propagation of the root id through nesting, context isolation, and no-parent / nil-session fallback. agent/context_test.go covers the ctx invocation round-trip. go build, go vet, and the agent / agenttool / store/session / plugins/otel suites pass.

🤖 Generated with Claude Code

[birdayz]

why not use agent.id / agent.name ?

[birdayz]

if we go for otel traceparent for assocation this is not needed (we could do it still if needed)