io.micrometer
micrometer-observation
diff --git a/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/workflow/WorkflowStepObservationObserver.java b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/workflow/WorkflowStepObservationObserver.java
new file mode 100644
index 000000000..c383aac68
--- /dev/null
+++ b/argi-orchestration/argi-agent-framework/src/main/java/io/github/agentic/ai/agent/orchestration/workflow/WorkflowStepObservationObserver.java
@@ -0,0 +1,99 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.agentic.ai.agent.orchestration.workflow;
+
+import java.util.Deque;
+import java.util.Set;
+import java.util.concurrent.ConcurrentLinkedDeque;
+
+import io.github.agentic.ai.agent.lifecycle.LifecycleEvent;
+import io.github.agentic.ai.agent.lifecycle.LifecycleObserver;
+import io.github.agentic.ai.agent.lifecycle.LifecycleStage;
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTraceContext;
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTraceOperation;
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTraceSpan;
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTracer;
+
+/**
+ * Bridges the workflow engine's {@link LifecycleStage#WORKFLOW_STEP} lifecycle events
+ * (issue #322) into micrometer {@link AgentTracer} spans, following the cross-agent
+ * trace conventions of #131: one {@code argi.agent.workflow.step} span per executed
+ * step, attributed with the run identity and the step id, ended exactly once on the
+ * thread that started it.
+ *
+ * The workflow engine emits enter/exit pairs on the executing thread (parallel branch
+ * workers included), so enter/exit pairing is a per-thread LIFO stack here. The
+ * workflow run identity is carried as the span's run id; with a disabled tracer the
+ * observer still receives events but creates no observation, so leaving the workflow
+ * unobserved preserves the historical behavior exactly.
+ */
+public final class WorkflowStepObservationObserver implements LifecycleObserver {
+
+ private final AgentTracer tracer;
+
+ private final ThreadLocal> spans = ThreadLocal.withInitial(ConcurrentLinkedDeque::new);
+
+ public WorkflowStepObservationObserver(AgentTracer tracer) {
+ this.tracer = tracer;
+ }
+
+ @Override
+ public Set stages() {
+ return Set.of(LifecycleStage.WORKFLOW_STEP);
+ }
+
+ @Override
+ public String id() {
+ return "workflow-step-observation";
+ }
+
+ @Override
+ public void onEvent(LifecycleEvent event) {
+ if (event instanceof LifecycleEvent.StageEntered entered) {
+ AgentTraceSpan span = startSpan(entered);
+ this.spans.get().push(span);
+ }
+ else if (event instanceof LifecycleEvent.StageExited exited) {
+ AgentTraceSpan span = this.spans.get().poll();
+ if (span == null) {
+ return;
+ }
+ if (exited.successful()) {
+ span.success();
+ }
+ else {
+ span.outcome("failed").failure();
+ }
+ span.close();
+ }
+ }
+
+ private AgentTraceSpan startSpan(LifecycleEvent.StageEntered entered) {
+ if (this.tracer == null || !this.tracer.isEnabled()) {
+ return AgentTraceSpan.disabled();
+ }
+ // The workflow run identity travels as the invocation id of the event.
+ AgentTraceContext context = AgentTraceContext.builder()
+ .runId(entered.identity().invocation() == null ? null : entered.identity().invocation().value())
+ .build();
+ AgentTraceSpan span = this.tracer.start(AgentTraceOperation.WORKFLOW_STEP, context);
+ if (span.isDisabled()) {
+ return span;
+ }
+ return entered.identity().step() == null ? span : span.stepId(entered.identity().step().value());
+ }
+
+}
diff --git a/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/workflow/WorkflowStepObservationObserverTest.java b/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/workflow/WorkflowStepObservationObserverTest.java
new file mode 100644
index 000000000..94cf2d726
--- /dev/null
+++ b/argi-orchestration/argi-agent-framework/src/test/java/io/github/agentic/ai/agent/orchestration/workflow/WorkflowStepObservationObserverTest.java
@@ -0,0 +1,164 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.agentic.ai.agent.orchestration.workflow;
+
+import java.time.Clock;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.Flow;
+import java.util.concurrent.TimeUnit;
+
+import io.github.agentic.ai.agent.Agent;
+import io.github.agentic.ai.agent.AgentEvent;
+import io.github.agentic.ai.agent.AgentExecutionContext;
+import io.github.agentic.ai.agent.AgentOutcome;
+import io.github.agentic.ai.agent.AgentRequest;
+import io.github.agentic.ai.api.chat.ChatMessage;
+import io.github.agentic.ai.api.chat.Usage;
+import io.github.agentic.ai.agent.lifecycle.LifecycleObserver;
+import io.github.agentic.ai.runtime.execution.DelegationScope;
+import io.github.agentic.ai.runtime.execution.ExecutionBudget;
+import io.github.agentic.ai.runtime.execution.PrincipalReference;
+import io.github.agentic.ai.runtime.execution.TenantReference;
+import io.github.agentic.ai.runtime.execution.TrustedExecutionContext;
+import io.github.agentic.ai.workflow.WorkflowAgent;
+import io.github.agentic.ai.workflow.WorkflowDefinition;
+import io.github.agentic.ai.workflow.WorkflowStep;
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTraceKeys;
+import io.github.agentic.ai.workflow.graph.observation.trace.AgentTracer;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationHandler;
+import io.micrometer.observation.ObservationRegistry;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** Issue #322: the workflow step lifecycle events must surface as real micrometer spans. */
+class WorkflowStepObservationObserverTest {
+
+ private final RecordingHandler handler = new RecordingHandler();
+
+ private final AgentTracer tracer;
+
+ WorkflowStepObservationObserverTest() {
+ ObservationRegistry registry = ObservationRegistry.create();
+ registry.observationConfig().observationHandler(this.handler);
+ this.tracer = new AgentTracer(registry);
+ }
+
+ @Test
+ void workflowStepEventsSurfaceAsWorkflowStepSpans() throws Exception {
+ Agent agent = agent(request -> AgentOutcome.completed(List.of(ChatMessage.assistant("done")),
+ Map.of("value", "v"), new Usage(1L, 1L, 2L)));
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker")));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", agent))
+ .observers(observer())
+ .build();
+
+ try (AgentExecutionContext context = context()) {
+ AgentOutcome outcome = workflow
+ .invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ assertThat(outcome.status()).isEqualTo(AgentOutcome.Status.COMPLETED);
+ }
+
+ assertThat(this.handler.stopped).hasSize(1);
+ Observation.Context span = this.handler.stopped.get(0);
+ assertThat(span.getName()).isEqualTo("argi.agent.workflow.step");
+ assertThat(span.getHighCardinalityKeyValue(AgentTraceKeys.STEP_ID).getValue()).isEqualTo("answer");
+ assertThat(span.getHighCardinalityKeyValue(AgentTraceKeys.RUN_ID).getValue()).isEqualTo("run");
+ assertThat(span.getLowCardinalityKeyValue(AgentTraceKeys.SUCCESS).getValue()).isEqualTo("true");
+ }
+
+ @Test
+ void aFailingWorkflowStepEndsItsSpanUnsuccessfully() throws Exception {
+ Agent failing = agent(request -> {
+ throw new IllegalStateException("boom");
+ });
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker")));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", failing))
+ .observers(observer())
+ .build();
+
+ try (AgentExecutionContext context = context()) {
+ workflow.invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ }
+ catch (Exception pending) {
+ // The workflow surfaces the error to its subscriber; the span is the point.
+ }
+
+ assertThat(this.handler.stopped).hasSize(1);
+ Observation.Context span = this.handler.stopped.get(0);
+ assertThat(span.getName()).isEqualTo("argi.agent.workflow.step");
+ assertThat(span.getLowCardinalityKeyValue(AgentTraceKeys.SUCCESS).getValue()).isEqualTo("false");
+ assertThat(span.getLowCardinalityKeyValue(AgentTraceKeys.OUTCOME).getValue()).isEqualTo("failed");
+ }
+
+ private LifecycleObserver observer() {
+ return new WorkflowStepObservationObserver(this.tracer);
+ }
+
+ private static Agent agent(java.util.function.Function function) {
+ return (request, context) -> subscriber -> {
+ subscriber.onSubscribe(new Flow.Subscription() {
+ public void request(long demand) {
+ if (demand > 0) {
+ subscriber.onNext(new AgentEvent.Finished(function.apply(request)));
+ subscriber.onComplete();
+ }
+ }
+
+ public void cancel() {
+ }
+ });
+ };
+ }
+
+ private static AgentExecutionContext context() {
+ TrustedExecutionContext trusted = TrustedExecutionContext.builder()
+ .tenant(new TenantReference("test", "tenant"))
+ .principal(new PrincipalReference("test", "principal"))
+ .runId("run")
+ .correlationId("correlation")
+ .budget(ExecutionBudget.unlimited())
+ .delegationScope(DelegationScope.none())
+ .build();
+ return new AgentExecutionContext(trusted, Clock.systemUTC());
+ }
+
+ static final class RecordingHandler implements ObservationHandler {
+
+ final List stopped = new CopyOnWriteArrayList<>();
+
+ @Override
+ public boolean supportsContext(Observation.Context context) {
+ return true;
+ }
+
+ @Override
+ public void onStop(Observation.Context context) {
+ this.stopped.add(context);
+ }
+
+ }
+
+}
diff --git a/argi-orchestration/argi-workflow-core/src/main/java/io/github/agentic/ai/workflow/WorkflowAgent.java b/argi-orchestration/argi-workflow-core/src/main/java/io/github/agentic/ai/workflow/WorkflowAgent.java
index dcd1701bd..596ca11c0 100644
--- a/argi-orchestration/argi-workflow-core/src/main/java/io/github/agentic/ai/workflow/WorkflowAgent.java
+++ b/argi-orchestration/argi-workflow-core/src/main/java/io/github/agentic/ai/workflow/WorkflowAgent.java
@@ -34,6 +34,12 @@
import io.github.agentic.ai.api.tool.ToolContext;
import io.github.agentic.ai.api.tool.ToolRegistry;
import io.github.agentic.ai.api.tool.ToolResult;
+import io.github.agentic.ai.agent.lifecycle.InvocationId;
+import io.github.agentic.ai.agent.lifecycle.LifecycleEvent;
+import io.github.agentic.ai.agent.lifecycle.LifecycleIdentity;
+import io.github.agentic.ai.agent.lifecycle.LifecycleObserver;
+import io.github.agentic.ai.agent.lifecycle.LifecycleStage;
+import io.github.agentic.ai.agent.lifecycle.StepId;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collections;
@@ -86,6 +92,10 @@ public final class WorkflowAgent implements Agent {
private final int subflowMaxDepth;
+ private final List observers;
+
+ private final java.util.concurrent.Executor parallelExecutor;
+
private final Map continuations = new ConcurrentHashMap<>();
private final Schema inputSchema;
@@ -100,6 +110,8 @@ private WorkflowAgent(Builder builder) {
this.registry = Objects.requireNonNull(builder.registry, "registry must not be null");
this.mapper = Objects.requireNonNull(builder.mapper, "mapper must not be null");
this.subflowMaxDepth = builder.subflowMaxDepth;
+ this.observers = List.copyOf(builder.observers);
+ this.parallelExecutor = builder.parallelExecutor;
this.inputSchema = compileSchema(definition.inputSchema());
this.outputSchema = compileSchema(definition.outputSchema());
}
@@ -163,6 +175,10 @@ public static final class Builder {
private int subflowMaxDepth = 16;
+ private final List observers = new ArrayList<>();
+
+ private java.util.concurrent.Executor parallelExecutor;
+
private Builder(WorkflowDefinition definition) {
this.definition = Objects.requireNonNull(definition, "definition must not be null");
}
@@ -206,6 +222,33 @@ public Builder subflowMaxDepth(int subflowMaxDepth) {
return this;
}
+ /**
+ * Register lifecycle observers that receive {@link LifecycleStage#WORKFLOW_STEP}
+ * enter/exit events for every executed step (issue #322). Observation remains an
+ * explicit opt-in: with no observers, execution behavior is preserved exactly.
+ * @param observers the observers to append, must not be null
+ * @return this builder
+ */
+ public Builder observers(LifecycleObserver... observers) {
+ Objects.requireNonNull(observers, "observers must not be null");
+ for (LifecycleObserver observer : observers) {
+ this.observers.add(Objects.requireNonNull(observer, "observer must not be null"));
+ }
+ return this;
+ }
+
+ /**
+ * Set the executor that runs parallel branches. When omitted, branches run on
+ * {@link java.util.concurrent.ForkJoinPool#commonPool()} exactly as before; the
+ * seam exists so tests can drive deterministic branch interleaving.
+ * @param parallelExecutor the branch executor, may be null for the default
+ * @return this builder
+ */
+ public Builder parallelExecutor(java.util.concurrent.Executor parallelExecutor) {
+ this.parallelExecutor = parallelExecutor;
+ return this;
+ }
+
public WorkflowAgent build() {
return new WorkflowAgent(this);
}
@@ -345,7 +388,42 @@ private ExecutionResult continueAfter(ExecutionResult suspended, List observer.onEvent(new LifecycleEvent.StageEntered(LifecycleStage.WORKFLOW_STEP, identity)));
+ try {
+ ExecutionResult result = doExecuteStep(step, data, context);
+ // A normal return - completion or a suspension hand-off - is a successful
+ // stage exit; only a thrown failure marks the stage unsuccessful.
+ this.observers.forEach(observer -> observer
+ .onEvent(new LifecycleEvent.StageExited(LifecycleStage.WORKFLOW_STEP, identity, true, null)));
+ return result;
+ }
+ catch (RuntimeException error) {
+ this.observers.forEach(observer -> observer.onEvent(new LifecycleEvent.StageExited(LifecycleStage.WORKFLOW_STEP,
+ identity, false, error.getClass().getSimpleName() + ": " + error.getMessage())));
+ throw error;
+ }
+ }
+
+ /** The workflow run identity: the trusted run id, falling back to the definition. */
+ private InvocationId runInvocation(AgentExecutionContext context) {
+ String runId = context.trusted() != null ? context.trusted().runId() : null;
+ return new InvocationId(Objects.requireNonNullElse(runId, definition.id() + ":" + definition.version()));
+ }
+
+ private ExecutionResult doExecuteStep(WorkflowStep step, RunData data, AgentExecutionContext context) {
context.control().assertActive();
if (step instanceof WorkflowStep.Agent agent) {
return executeWithRetry(agent.retry(), () -> executeAgent(agent, data, context), context);
@@ -545,26 +623,30 @@ private ExecutionResult executeParallel(WorkflowStep.Parallel step, RunData data
int baseMessageCount = data.messages.size();
Semaphore permits = new Semaphore(step.maxConcurrency());
List> futures = step.branches().stream()
- .map(branch -> CompletableFuture.supplyAsync(() -> {
- try {
- permits.acquire();
- }
- catch (InterruptedException interrupted) {
- Thread.currentThread().interrupt();
- throw new WorkflowExecutionException("Parallel workflow admission was interrupted", interrupted);
- }
- RunData branchData = data.copy();
- try {
- ExecutionResult result = executeStep(branch, branchData, context);
- if (result.suspension != null) {
- throw new WorkflowExecutionException("Parallel workflow suspension requires durable coordination");
+ .map(branch -> {
+ java.util.function.Supplier task = () -> {
+ try {
+ permits.acquire();
}
- return branchData;
- }
- finally {
- permits.release();
- }
- }))
+ catch (InterruptedException interrupted) {
+ Thread.currentThread().interrupt();
+ throw new WorkflowExecutionException("Parallel workflow admission was interrupted", interrupted);
+ }
+ RunData branchData = data.copy();
+ try {
+ ExecutionResult result = executeStep(branch, branchData, context);
+ if (result.suspension != null) {
+ throw new WorkflowExecutionException("Parallel workflow suspension requires durable coordination");
+ }
+ return branchData;
+ }
+ finally {
+ permits.release();
+ }
+ };
+ return this.parallelExecutor == null ? CompletableFuture.supplyAsync(task)
+ : CompletableFuture.supplyAsync(task, this.parallelExecutor);
+ })
.toList();
for (CompletableFuture future : futures) {
RunData branch = await(future);
diff --git a/argi-orchestration/argi-workflow-core/src/test/java/io/github/agentic/ai/workflow/WorkflowStepLifecycleTest.java b/argi-orchestration/argi-workflow-core/src/test/java/io/github/agentic/ai/workflow/WorkflowStepLifecycleTest.java
new file mode 100644
index 000000000..5d4764032
--- /dev/null
+++ b/argi-orchestration/argi-workflow-core/src/test/java/io/github/agentic/ai/workflow/WorkflowStepLifecycleTest.java
@@ -0,0 +1,408 @@
+/*
+ * Copyright 2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.github.agentic.ai.workflow;
+
+import java.time.Clock;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.Flow;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicReference;
+
+import io.github.agentic.ai.agent.Agent;
+import io.github.agentic.ai.agent.AgentEvent;
+import io.github.agentic.ai.agent.AgentExecutionContext;
+import io.github.agentic.ai.agent.AgentOutcome;
+import io.github.agentic.ai.agent.AgentRequest;
+import io.github.agentic.ai.agent.lifecycle.LifecycleEvent;
+import io.github.agentic.ai.agent.lifecycle.LifecycleObserver;
+import io.github.agentic.ai.agent.lifecycle.LifecycleStage;
+import io.github.agentic.ai.api.chat.ChatMessage;
+import io.github.agentic.ai.api.chat.Usage;
+import io.github.agentic.ai.api.tool.Tool;
+import io.github.agentic.ai.api.tool.ToolContext;
+import io.github.agentic.ai.api.tool.ToolRegistry;
+import io.github.agentic.ai.api.tool.ToolResult;
+import io.github.agentic.ai.runtime.execution.DelegationScope;
+import io.github.agentic.ai.runtime.execution.ExecutionBudget;
+import io.github.agentic.ai.runtime.execution.PrincipalReference;
+import io.github.agentic.ai.runtime.execution.TenantReference;
+import io.github.agentic.ai.runtime.execution.TrustedExecutionContext;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/** 复现 #322:步骤进入/退出事件严格成对,并行分支乱序归属正确,NOOP 零行为差异。 */
+class WorkflowStepLifecycleTest {
+
+ private final RecordingObserver observer = new RecordingObserver();
+
+ @Test
+ void stepsEmitPairedEnterAndExitEventsInLifoOrder() throws Exception {
+ Agent agent = agent(request -> AgentOutcome.completed(List.of(ChatMessage.assistant("done")),
+ Map.of("value", "v"), new Usage(1L, 1L, 2L)));
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker"),
+ new WorkflowStep.Tool("mark", "mark", Map.of())));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", agent))
+ .tools(new ToolRegistry(List.of(textTool("mark"))))
+ .observers(observer)
+ .build();
+ observer.expectExits(2);
+
+ try (AgentExecutionContext context = context()) {
+ AgentOutcome outcome = workflow
+ .invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ assertEquals(AgentOutcome.Status.COMPLETED, outcome.status());
+ }
+ observer.awaitExits();
+
+ assertEquals(List.of("ENTER answer", "EXIT answer ok", "ENTER mark", "EXIT mark ok"), observer.events);
+ }
+
+ @Test
+ void aFailedStepExitsUnsuccessfullyExactlyOnce() throws Exception {
+ AtomicInteger attempts = new AtomicInteger();
+ Agent failing = agent(request -> {
+ attempts.incrementAndGet();
+ throw new IllegalStateException("boom");
+ });
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker", Map.of(), null,
+ new WorkflowStep.RetryPolicy(2, java.time.Duration.ZERO))));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", failing))
+ .observers(observer)
+ .build();
+ observer.expectExits(1);
+
+ try (AgentExecutionContext context = context()) {
+ workflow.invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ }
+ catch (Exception pending) {
+ // The exhausted retries surface as an error completion; the events are the point.
+ }
+ observer.awaitExits();
+
+ assertEquals(2, attempts.get(), "both attempts must have run");
+ // Issue #322 acceptance: each step ends exactly once, retries included.
+ assertEquals(List.of("ENTER answer", "EXIT answer failed:WorkflowExecutionException: Workflow step failed after 2 attempts"),
+ observer.events);
+ }
+
+ @Test
+ void aCancelledStepExitsUnsuccessfully() throws Exception {
+ Agent canceller = (request, agentContext) -> subscriber -> {
+ subscriber.onSubscribe(new Flow.Subscription() {
+ public void request(long demand) {
+ if (demand > 0) {
+ agentContext.control().cancel();
+ subscriber.onError(new WorkflowExecutionException("cancelled mid-step"));
+ }
+ }
+
+ public void cancel() {
+ }
+ });
+ };
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker")));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", canceller))
+ .observers(observer)
+ .build();
+ observer.expectExits(1);
+
+ try (AgentExecutionContext context = context()) {
+ workflow.invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ }
+ catch (Exception pending) {
+ // Cancellation surfaces as an error completion; the events are the point.
+ }
+ observer.awaitExits();
+
+ assertTrue(observer.events.size() >= 2 && observer.events.get(0).equals("ENTER answer")
+ && observer.events.get(1).startsWith("EXIT answer failed"),
+ "the cancelled step must enter once and exit unsuccessfully: " + observer.events
+ + " unexpected=" + observer.unexpected.get());
+ }
+
+ @Test
+ void parallelBranchesKeepTheirAttributionWhenCompletionOrderIsReversed() throws Exception {
+ CountDownLatch branchBFinished = new CountDownLatch(1);
+ Agent slowFirst = agent(request -> {
+ try {
+ assertTrue(branchBFinished.await(5, TimeUnit.SECONDS), "branch B must finish first");
+ }
+ catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ throw new IllegalStateException("interrupted while waiting for branch B", e);
+ }
+ return AgentOutcome.completed(List.of(ChatMessage.assistant("a")), Map.of("branch", "a"),
+ new Usage(0L, 0L, 0L));
+ });
+ Agent fastSecond = agent(request -> AgentOutcome.completed(List.of(ChatMessage.assistant("b")),
+ Map.of("branch", "b"), new Usage(0L, 0L, 0L)));
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Parallel("parallel",
+ List.of(new WorkflowStep.Agent("left", "slow"), new WorkflowStep.Agent("right", "fast")))));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("slow", slowFirst, "fast", fastSecond))
+ .observers(observer)
+ .parallelExecutor(java.util.concurrent.Executors.newFixedThreadPool(2))
+ .build();
+ observer.expectExits(2);
+ // Release the slow branch only after the fast branch's exit event was recorded,
+ // making the reversed completion order deterministic.
+ observer.onExit = stepId -> {
+ if (stepId.equals("right")) {
+ branchBFinished.countDown();
+ }
+ };
+
+ try (AgentExecutionContext context = context()) {
+ AgentOutcome outcome = workflow
+ .invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(5, TimeUnit.SECONDS);
+ assertEquals(AgentOutcome.Status.COMPLETED, outcome.status());
+ }
+ observer.awaitExits();
+
+ int leftEnter = observer.events.indexOf("ENTER left");
+ int leftExit = observer.events.indexOf("EXIT left ok");
+ int rightEnter = observer.events.indexOf("ENTER right");
+ int rightExit = observer.events.indexOf("EXIT right ok");
+ assertTrue(leftEnter >= 0 && leftExit > leftEnter, "branch left must emit a paired event: " + observer.events);
+ assertTrue(rightEnter >= 0 && rightExit > rightEnter, "branch right must emit a paired event: " + observer.events);
+ assertTrue(rightExit < leftExit, "branch right completes first (reversed order): " + observer.events);
+ // The left branch's enter/exit pair runs on one worker thread even though the
+ // fan-in merges in declaration order.
+ assertEquals(observer.threads.get(leftEnter), observer.threads.get(leftExit), "left pair must share a thread");
+ assertEquals(observer.threads.get(rightEnter), observer.threads.get(rightExit), "right pair must share a thread");
+ assertTrue(!observer.threads.get(leftEnter).equals(Thread.currentThread().getName()),
+ "branch events must come from the branch worker thread, not the caller");
+ }
+
+ @Test
+ void loopIterationsEmitOnePairPerIteration() throws Exception {
+ AtomicInteger toggles = new AtomicInteger();
+ Tool toggle = new Tool() {
+ public io.github.agentic.ai.api.chat.ToolDefinition definition() {
+ return new io.github.agentic.ai.api.chat.ToolDefinition("toggle", "toggle", "{}");
+ }
+
+ public CompletionStage execute(io.github.agentic.ai.api.chat.ToolCall call,
+ ToolContext context) {
+ // First pass keeps the loop condition truthy, the second one ends it.
+ return CompletableFuture.completedFuture(ToolResult.text(toggles.incrementAndGet() == 1 ? "true" : "false"));
+ }
+ };
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Loop("repeat", WorkflowValue.state("runLoop"),
+ new WorkflowStep.Tool("toggle", "toggle", Map.of(), "runLoop", null), 3)));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .tools(new ToolRegistry(List.of(toggle)))
+ .observers(observer)
+ .build();
+ observer.expectExits(3);
+
+ try (AgentExecutionContext context = context()) {
+ AgentOutcome outcome = workflow
+ .invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of("runLoop", true), null), context)
+ .get(3, TimeUnit.SECONDS);
+ assertEquals(AgentOutcome.Status.COMPLETED, outcome.status());
+ }
+ observer.awaitExits();
+
+ // The Loop container emits its own pair around the body pairs (nested LIFO).
+ assertEquals(List.of("ENTER repeat", "ENTER toggle", "EXIT toggle ok", "ENTER toggle", "EXIT toggle ok",
+ "EXIT repeat ok"), observer.events);
+ }
+
+ @Test
+ void aSuspensionExitsOnceAndTheResumeDoesNotDoubleExit() throws Exception {
+ Agent suspending = agent(request -> request.resumeToken() != null
+ ? AgentOutcome.completed(List.of(ChatMessage.assistant("resumed")), Map.of("value", "done"),
+ new Usage(0L, 0L, 0L))
+ : new AgentOutcome(AgentOutcome.Status.SUSPENDED, List.of(), Map.of(), new Usage(0L, 0L, 0L),
+ new AgentOutcome.Suspension("agent-token", Map.of())));
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker")));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", suspending))
+ .observers(observer)
+ .build();
+ observer.expectExits(1);
+ String resumeToken;
+
+ try (AgentExecutionContext context = context()) {
+ AgentOutcome suspended = workflow
+ .invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ assertEquals(AgentOutcome.Status.SUSPENDED, suspended.status());
+ // The workflow wraps the suspension with its own opaque token.
+ resumeToken = suspended.suspension().resumeToken();
+ }
+
+ try (AgentExecutionContext context = context()) {
+ AgentOutcome completed = workflow
+ .invoke(new AgentRequest(List.of(ChatMessage.user("hello")), Map.of(), resumeToken), context)
+ .get(3, TimeUnit.SECONDS);
+ assertEquals(AgentOutcome.Status.COMPLETED, completed.status());
+ }
+ observer.awaitExits();
+
+ assertEquals(List.of("ENTER answer", "EXIT answer ok"), observer.events);
+ }
+
+ @Test
+ void independentRunsDoNotInheritEachOthersEvents() throws Exception {
+ Agent agent = agent(request -> AgentOutcome.completed(List.of(ChatMessage.assistant("done")),
+ Map.of("value", "v"), new Usage(1L, 1L, 2L)));
+ WorkflowDefinition definition = new WorkflowDefinition("demo", "1",
+ List.of(new WorkflowStep.Agent("answer", "worker")));
+ WorkflowAgent workflow = WorkflowAgent.builder(definition)
+ .agents(Map.of("worker", agent))
+ .observers(observer)
+ .build();
+ observer.expectExits(2);
+
+ try (AgentExecutionContext context = context()) {
+ workflow.invoke(new AgentRequest(List.of(ChatMessage.user("first")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ }
+
+ try (AgentExecutionContext context = context()) {
+ workflow.invoke(new AgentRequest(List.of(ChatMessage.user("second")), Map.of(), null), context)
+ .get(3, TimeUnit.SECONDS);
+ }
+ observer.awaitExits();
+
+ assertEquals(List.of("ENTER answer", "EXIT answer ok", "ENTER answer", "EXIT answer ok"), observer.events);
+ }
+
+ private static Agent agent(java.util.function.Function function) {
+ return (request, context) -> subscriber -> {
+ subscriber.onSubscribe(new Flow.Subscription() {
+ public void request(long demand) {
+ if (demand > 0) {
+ subscriber.onNext(new AgentEvent.Finished(function.apply(request)));
+ subscriber.onComplete();
+ }
+ }
+
+ public void cancel() {
+ }
+ });
+ };
+ }
+
+ private static Tool textTool(String name) {
+ return new Tool() {
+ public io.github.agentic.ai.api.chat.ToolDefinition definition() {
+ return new io.github.agentic.ai.api.chat.ToolDefinition(name, name, "{}");
+ }
+
+ public CompletionStage execute(io.github.agentic.ai.api.chat.ToolCall call,
+ ToolContext context) {
+ return CompletableFuture.completedFuture(ToolResult.text("recorded"));
+ }
+ };
+ }
+
+ private static AgentExecutionContext context() {
+ TrustedExecutionContext trusted = TrustedExecutionContext.builder()
+ .tenant(new TenantReference("test", "tenant"))
+ .principal(new PrincipalReference("test", "principal"))
+ .runId("run")
+ .correlationId("correlation")
+ .budget(ExecutionBudget.unlimited())
+ .delegationScope(DelegationScope.none())
+ .build();
+ return new AgentExecutionContext(trusted, Clock.systemUTC());
+ }
+
+ static final class RecordingObserver implements LifecycleObserver {
+
+ final List events = new CopyOnWriteArrayList<>();
+
+ final List threads = new CopyOnWriteArrayList<>();
+
+ final AtomicReference unexpected = new AtomicReference<>();
+
+ /** Gate the test thread until the expected number of exits has been recorded. */
+ private volatile CountDownLatch exitGate;
+
+ /** Deterministic hook invoked with the step id after an exit event was recorded. */
+ volatile java.util.function.Consumer onExit;
+
+ void expectExits(int count) {
+ this.exitGate = new CountDownLatch(count);
+ }
+
+ void awaitExits() throws InterruptedException {
+ assertTrue(this.exitGate.await(5, TimeUnit.SECONDS), "expected exits were not recorded: " + this.events);
+ }
+
+ @Override
+ public java.util.Set stages() {
+ return java.util.Set.of(LifecycleStage.WORKFLOW_STEP);
+ }
+
+ @Override
+ public String id() {
+ return "recording-observer";
+ }
+
+ @Override
+ public void onEvent(LifecycleEvent event) {
+ try {
+ if (event instanceof LifecycleEvent.StageEntered entered) {
+ this.events.add("ENTER " + entered.identity().step().value());
+ this.threads.add(Thread.currentThread().getName());
+ }
+ else if (event instanceof LifecycleEvent.StageExited exited) {
+ this.events.add("EXIT " + exited.identity().step().value()
+ + (exited.successful() ? " ok" : " failed:" + exited.failureReason()));
+ this.threads.add(Thread.currentThread().getName());
+ java.util.function.Consumer hook = this.onExit;
+ if (hook != null) {
+ hook.accept(exited.identity().step().value());
+ }
+ CountDownLatch gate = this.exitGate;
+ if (gate != null) {
+ gate.countDown();
+ }
+ }
+ }
+ catch (Throwable error) {
+ this.unexpected.compareAndSet(null, error);
+ }
+ }
+
+ }
+
+}
diff --git a/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceKeys.java b/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceKeys.java
index cd1b8159a..689bfb120 100644
--- a/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceKeys.java
+++ b/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceKeys.java
@@ -59,6 +59,9 @@ public final class AgentTraceKeys {
/** High-cardinality key carrying the delegation identifier of this span. */
public static final String DELEGATION_ID = "argi.agent.delegation.id";
+ /** High-cardinality key carrying the workflow step identifier. */
+ public static final String STEP_ID = "argi.agent.step.id";
+
/**
* High-cardinality key carrying the delegation identifier of a linked producer span.
* Producers and consumers run on different threads (or processes) and are rarely in a
diff --git a/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceOperation.java b/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceOperation.java
index 7505abef1..72d1bbd92 100644
--- a/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceOperation.java
+++ b/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceOperation.java
@@ -37,6 +37,9 @@ public enum AgentTraceOperation {
/** A consumer span that receives or waits for a background task result. */
TASK_RECEIVE("argi.agent.task.receive"),
+ /** A workflow engine step (Agent, Tool, Condition, Loop, Parallel branch, Subflow). */
+ WORKFLOW_STEP("argi.agent.workflow.step"),
+
/** A durable run store operation (submit, acquire, commit). */
RUN_STORE("argi.run.store");
diff --git a/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceSpan.java b/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceSpan.java
index 9cb8dc4bd..6af800588 100644
--- a/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceSpan.java
+++ b/argi-orchestration/argi-workflow-graph-core/src/main/java/io/github/agentic/ai/workflow/graph/observation/trace/AgentTraceSpan.java
@@ -159,6 +159,31 @@ public AgentTraceSpan taskId(String taskId) {
return this;
}
+ /**
+ * Attach the workflow step identifier of this span (issue #322).
+ * @param stepId the workflow step identifier
+ * @return this span
+ */
+ /**
+ * Mark the span as failed without a throwable. Lifecycle events carry only a reason
+ * string, so observers that translate them into spans use this instead of
+ * {@link #error(Throwable)}; the error type key stays unset.
+ * @return this span
+ */
+ public AgentTraceSpan failure() {
+ if (this.observation != null) {
+ this.observation.lowCardinalityKeyValue(AgentTraceKeys.SUCCESS, "false");
+ }
+ return this;
+ }
+
+ public AgentTraceSpan stepId(String stepId) {
+ if (this.observation != null && stepId != null) {
+ this.observation.highCardinalityKeyValue(AgentTraceKeys.STEP_ID, stepId);
+ }
+ return this;
+ }
+
/**
* Record a failure. The exception type is kept as a low-cardinality attribute, its
* message is redacted and truncated before it is attached, and only a sanitized wrapper