diff --git a/argi-orchestration/argi-agent-framework/pom.xml b/argi-orchestration/argi-agent-framework/pom.xml index dece7ff0a..709970d3f 100644 --- a/argi-orchestration/argi-agent-framework/pom.xml +++ b/argi-orchestration/argi-agent-framework/pom.xml @@ -80,6 +80,11 @@ argi-workflow-graph-core ${project.parent.version} + + io.github.agentic-ai-java + argi-workflow-core + ${project.parent.version} + 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