2222import io .github .agentic .ai .api .tool .Tool ;
2323import io .github .agentic .ai .graph .RunnableConfig ;
2424import io .github .agentic .ai .graph .agent .tool .TypedTool ;
25+ import io .github .agentic .ai .graph .agent .tools .ToolContextHelper ;
2526import io .github .agentic .ai .graph .execution .TrustedExecutionContext ;
27+ import io .github .agentic .ai .graph .observation .trace .AgentTraceContext ;
28+ import io .github .agentic .ai .graph .observation .trace .AgentTraceOperation ;
29+ import io .github .agentic .ai .graph .observation .trace .AgentTraceSpan ;
30+ import io .github .agentic .ai .graph .observation .trace .AgentTracer ;
2631import org .springframework .util .Assert ;
2732
33+ import java .util .Map ;
2834import java .util .function .BiFunction ;
2935
3036import static io .github .agentic .ai .graph .agent .tools .ToolContextConstants .AGENT_CONFIG_CONTEXT_KEY ;
@@ -54,9 +60,27 @@ Retrieves output from a running or completed background task (sub-agent).
5460
5561 private final TaskRepository taskRepository ;
5662
63+ private final AgentTracer agentTracer ;
64+
65+ private final TaskTraceCorrelation traceCorrelation ;
66+
5767 public TaskOutputTool (TaskRepository taskRepository ) {
68+ this (taskRepository , null , null );
69+ }
70+
71+ /**
72+ * Create a TaskOutputTool with optional cross-agent trace correlation. The tracer is an
73+ * explicit opt-in; with a null tracer the historical behavior is preserved exactly.
74+ * @param taskRepository the repository that holds the background tasks
75+ * @param agentTracer the cross-agent tracer, may be null
76+ * @param traceCorrelation the correlation store shared with the TaskTool, may be null
77+ */
78+ public TaskOutputTool (TaskRepository taskRepository , AgentTracer agentTracer ,
79+ TaskTraceCorrelation traceCorrelation ) {
5880 Assert .notNull (taskRepository , "taskRepository must not be null" );
5981 this .taskRepository = taskRepository ;
82+ this .agentTracer = agentTracer ;
83+ this .traceCorrelation = traceCorrelation ;
6084 }
6185
6286 @ Override
@@ -80,34 +104,75 @@ public String apply(Request request, ToolContext toolContext) {
80104 boolean shouldBlock = request .block () == null || request .block ();
81105 long timeoutMs = request .timeout () != null ? Math .min (request .timeout (), 600000 ) : 30000 ;
82106
83- if (shouldBlock && !bgTask .isCompleted ()) {
84- try {
85- bgTask .waitForCompletion (timeoutMs );
86- }
87- catch (InterruptedException e ) {
88- Thread .currentThread ().interrupt ();
89- return "Error: Wait for task interrupted" ;
107+ boolean tracing = this .agentTracer != null && this .agentTracer .isEnabled ();
108+ AgentTraceContext context = tracing ? receiveContext (request .taskId (), toolContext ) : null ;
109+
110+ try (AgentTraceSpan span = tracing
111+ ? startReceiveSpan (request .taskId (), context )
112+ : AgentTraceSpan .disabled ()) {
113+ String outcome = null ;
114+ if (shouldBlock && !bgTask .isCompleted ()) {
115+ boolean completed = false ;
116+ try {
117+ completed = bgTask .waitForCompletion (timeoutMs );
118+ }
119+ catch (InterruptedException e ) {
120+ Thread .currentThread ().interrupt ();
121+ span .outcome ("interrupted" ).success ();
122+ return "Error: Wait for task interrupted" ;
123+ }
124+ outcome = completed ? null : "timeout" ;
90125 }
91- }
92126
93- StringBuilder result = new StringBuilder ();
94- result .append ("Task ID: " ).append (request .taskId ()).append ("\n " );
95- result .append ("Status: " ).append (bgTask .getStatus ()).append ("\n \n " );
127+ StringBuilder result = new StringBuilder ();
128+ result .append ("Task ID: " ).append (request .taskId ()).append ("\n " );
129+ result .append ("Status: " ).append (bgTask .getStatus ()).append ("\n \n " );
96130
97- if (bgTask .isCompleted () && bgTask .getResult () != null ) {
98- result .append ("Result:\n " ).append (bgTask .getResult ());
99- }
100- else if (bgTask .getError () != null ) {
101- result .append ("Error:\n " ).append (bgTask .getError ().getMessage ());
102- if (bgTask .getError ().getCause () != null ) {
103- result .append ("\n Cause: " ).append (bgTask .getError ().getCause ().getMessage ());
131+ if (bgTask .isCompleted () && bgTask .getResult () != null ) {
132+ result .append ("Result:\n " ).append (bgTask .getResult ());
133+ }
134+ else if (bgTask .getError () != null ) {
135+ result .append ("Error:\n " ).append (bgTask .getError ().getMessage ());
136+ if (bgTask .getError ().getCause () != null ) {
137+ result .append ("\n Cause: " ).append (bgTask .getError ().getCause ().getMessage ());
138+ }
139+ span .error (bgTask .getError ()).outcome ("failed" );
140+ return result .toString ();
104141 }
142+ else if (!bgTask .isCompleted ()) {
143+ result .append ("Task still running..." );
144+ span .outcome (outcome != null ? outcome : "still-running" ).success ();
145+ return result .toString ();
146+ }
147+
148+ span .outcome (outcome != null ? outcome : "completed" ).success ();
149+ return result .toString ();
105150 }
106- else if (!bgTask .isCompleted ()) {
107- result .append ("Task still running..." );
151+ }
152+
153+ /**
154+ * Start the receive span as a consumer; when the delegation context is known (fan-in
155+ * or long-running waits), the span links back to the delegation id instead of
156+ * depending on thread-local propagation.
157+ */
158+ private AgentTraceSpan startReceiveSpan (String taskId , AgentTraceContext context ) {
159+ AgentTraceSpan span = this .agentTracer .start (AgentTraceOperation .TASK_RECEIVE , context ).role ("consumer" );
160+ if (context != null && context .delegationId () != null ) {
161+ span .linkToDelegation (context .delegationId ());
108162 }
163+ return span ;
164+ }
109165
110- return result .toString ();
166+ private AgentTraceContext receiveContext (String taskId , ToolContext toolContext ) {
167+ AgentTraceContext recorded = this .traceCorrelation != null ? this .traceCorrelation .correlation (taskId ).orElse (null )
168+ : null ;
169+ if (recorded != null ) {
170+ return recorded ;
171+ }
172+ Map <String , Object > state = ToolContextHelper .getState (toolContext ).map (stateValue -> stateValue .data ())
173+ .orElse (null );
174+ return AgentTraceContext .capture (ToolContextHelper .getConfig (toolContext ).orElse (null ), state )
175+ .withTaskId (taskId );
111176 }
112177
113178 /**
@@ -133,6 +198,10 @@ public static class Builder {
133198
134199 private TaskRepository taskRepository ;
135200
201+ private AgentTracer agentTracer ;
202+
203+ private TaskTraceCorrelation traceCorrelation ;
204+
136205 private String name = "TaskOutput" ;
137206
138207 private String description = DEFAULT_DESCRIPTION ;
@@ -143,6 +212,27 @@ public Builder taskRepository(TaskRepository taskRepository) {
143212 return this ;
144213 }
145214
215+ /**
216+ * Enable cross-agent trace correlation with the given tracer.
217+ * @param agentTracer the tracer, may be null to keep tracing disabled
218+ * @return this builder
219+ */
220+ public Builder agentTracer (AgentTracer agentTracer ) {
221+ this .agentTracer = agentTracer ;
222+ return this ;
223+ }
224+
225+ /**
226+ * Share one correlation store between TaskTool and TaskOutputTool so receive spans
227+ * can link to their delegation span.
228+ * @param traceCorrelation the shared store, may be null
229+ * @return this builder
230+ */
231+ public Builder traceCorrelation (TaskTraceCorrelation traceCorrelation ) {
232+ this .traceCorrelation = traceCorrelation ;
233+ return this ;
234+ }
235+
146236 public Builder withName (String name ) {
147237 this .name = name != null ? name : "TaskOutput" ;
148238 return this ;
@@ -155,7 +245,8 @@ public Builder withDescription(String description) {
155245
156246 public Tool build () {
157247 Assert .notNull (this .taskRepository , "taskRepository must be provided" );
158- return TypedTool .builder (this .name , new TaskOutputTool (this .taskRepository ))
248+ return TypedTool
249+ .builder (this .name , new TaskOutputTool (this .taskRepository , this .agentTracer , this .traceCorrelation ))
159250 .description (this .description )
160251 .inputType (Request .class )
161252 .build ();
0 commit comments