Skip to content

feat(core,agent): add opt-in cross-agent trace correlation - #187

Merged
yuluo-yx merged 1 commit into
agentic-ai-java:mainfrom
Carl-Zhou-CN:feat/131-cross-agent-tracing
Oct 22, 2026
Merged

yuluo-yx merged 1 commit into
agentic-ai-java:mainfrom
Carl-Zhou-CN:feat/131-cross-agent-tracing

Conversation

@Carl-Zhou-CN

Copy link
Copy Markdown
Contributor

Cross-agent trace correlation (T26)

Confirmed contribution to ARGI. Adds an explicit opt-in AgentTracer on top of Micrometer Observation so submission, delegation, receipt, model/tool attempts and recovery form a searchable chain instead of surfacing only isolated child-agent errors.

What this does

  • graph-core observation.trace package (AgentTraceOperation, AgentTraceKeys, AgentTraceContext, AgentTraceSpan, AgentTracer): low-cardinality operation/role/phase/success/outcome/error-type keys, high-cardinality tenant/run/task/attempt/delegation/thread identifiers, MDC mirroring with restore-on-close, delegation-id span-link modeling (Micrometer 1.x has no span-link API), and sanitizer-based error redaction - only the redacted wrapper reaches observation.error(...).
  • ObservedRunStore decorator: explicit submit/acquire/commit spans with the lease fencing token as the attempt id; read-through calls stay span-free.
  • TaskTool / TaskOutputTool: share one TaskTraceCorrelation store; delegation spans carry run/tenant/attempt/delegation ids, background tasks anchor the delegation id, receive spans link back to it; timeouts and failures record outcomes with sanitized content; child configs follow the AgentTool derivation convention; the upstream tenant isolation in TaskRepository.getTask(taskId, callerTenantId) is preserved.
  • A2A: send/receive spans on the calling thread and the streaming worker thread (no thread-local dependency); producer context propagates as argiRunId/argiTenant/argiAttemptId/argiThreadId/argiDelegationId request metadata; fan-in/long-wait connections use the argi.agent.link.delegation.id link key.
  • Docs: new "Cross-Agent Trace Correlation" section in the graph-core README and an opt-in wiring section in the observation starter README.

Opt-in and compatibility

  • Enabling requires constructing an AgentTracer and passing it to TaskToolsBuilder, A2aRemoteAgent.Builder or wrapping a RunStore - installing the observation starter alone does not enable it, and the starter gains no new configuration keys (the strict 2.1.0 metadata compatibility test stays intact).
  • With a null/NOOP registry every code path behaves exactly as before and emits nothing.

Verification

  • 23 new tests: 14 graph-core (context capture, span lifecycle, redaction, MDC restore, 4x50 parallel-tenant isolation, ObservedRunStore) + 9 framework (TaskTool sync/background/timeout/failure, TaskOutputTool receive link, A2A blocking/streaming/disabled).
  • Gates: package, format-check, checkstyle-check, licenses-check, yamllint/codespell/newline-check, verify-api-contract.sh - all green (full-suite numbers in the evidence record for this change).

Fixes #131

…ntic-ai-java#131)

Introduce an explicit AgentTracer opt-in on top of Micrometer Observation so
submission, delegation, receipt and recovery form a searchable chain:

- graph-core observation.trace package: AgentTraceOperation/AgentTraceKeys/
  AgentTraceContext/AgentTraceSpan/AgentTracer with low- and high-cardinality
  correlation keys, MDC mirroring, delegation-id span links and sanitizer-based
  error redaction
- ObservedRunStore decorator records submit/acquire/commit spans with the lease
  fencing token as the attempt id
- TaskTool/TaskOutputTool share a TaskTraceCorrelation store so delegation and
  receive spans correlate through run/task/attempt/delegation ids, including
  background execution, timeouts and failures
- A2A send/receive spans propagate producer context in request metadata and
  survive the streaming worker thread without thread-locals
- documentation in graph-core and observation starter READMEs; no new starter
  configuration keys, historical behavior unchanged when no tracer is supplied
@Carl-Zhou-CN

Copy link
Copy Markdown
Contributor Author

CI note: the test failure in the first run was AgentToolNodeExecutionLeaseTest.activeCancellableToolGetsCancellationOnLeaseLossAndLateOutputIsNotMerged (lease loss must request original stage cancellation). This change does not touch AgentToolNode or ExecutionGuard; the test is timing-sensitive and passed 5/5 locally on this exact tree plus the full reactor suite (2543 tests) is green. Reopened the PR to re-trigger CI.

@yuluo-yx
yuluo-yx merged commit 10266c7 into agentic-ai-java:main Oct 22, 2026
13 of 14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[P3][T26] 完善跨 Agent 链路追踪与真实 exporter 验证

2 participants