alibaba/spring-ai-alibaba · warning

Sub-agent ' ' has no outputKey defined. This may cause data…

Error message

Sub-agent '{}' has no outputKey defined. This may cause data flow issues as downstream agents won't receive data from this agent.

What it means

During ParallelAgent validation, each sub-agent that is a ReactAgent is checked for an outputKey. A ReactAgent without outputKey stores results only in conversation messages, so downstream agents/siblings cannot read its output from state; validation logs this warning (validation itself still passes).

Solutions

1. Set an outputKey on every ReactAgent used as a parallel sub-agent
2. Use ParallelResultAggregator with explicit key mapping if output keys are intentionally absent
3. Ignore the warning if sub-agents communicate purely via messages, not state
4. Add a unit test asserting each sub-agent has outputKey before building the graph

Example fix

// before
ReactAgent researchAgent = ReactAgent.builder().name("researcher").model(model).build(); // no outputKey
// after
ReactAgent researchAgent = ReactAgent.builder().name("researcher").model(model).outputKey("research_result").build();

subAgents.stream().filter(a -> a instanceof ReactAgent)
  .map(a -> (ReactAgent) a)
  .filter(a -> a.getOutputKey() == null)
  .forEach(a -> { throw new IllegalStateException("Sub-agent missing outputKey: " + a.name()); });

static boolean hasOutputKey(Agent a) { return a instanceof ReactAgent r && r.getOutputKey() != null; }

When it happens

Trigger: ParallelAgent.validate → validateInputKeyCompatibility iterates subAgents and finds a ReactAgent whose getOutputKey() is null while parallel result aggregation/data flow between agents is expected.

Common situations: Sub-agent built without .outputKey(...) in the builder; agent reused in both sequential (message-passing) and parallel (state-based) contexts; copied agent config missing the outputKey after refactor.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Extra state key collision detected: key=
• No output found for sub-agent
• outputKey must not be null or empty
• Parallel flow requires at least 2 sub-agents for meaningful…
• Parallel flow requires at least one sub-agent

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/9197ce52d8d2f228. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java:324

		 * <li>The parent agent has an outputKey defined</li>
		 * <li>Sub-agents can properly handle the data flow through asAsyncNodeAction</li>
		 * </ul>
		 *
		 * <p>
		 * Note: BaseAgent doesn't have inputKey property, data flow is handled through
		 * asAsyncNodeAction parameters during graph construction.
		 * </p>
		 */
		private void validateInputKeyCompatibility() {
			// Check if sub-agents have outputKeys defined (they will be used as input
			// keys for downstream agents)
			for (Agent subAgent : subAgents) {
				if (!(subAgent instanceof ReactAgent)) {
					continue;
				}
				String subAgentOutputKey = ((ReactAgent)subAgent).getOutputKey();
				if (subAgentOutputKey == null) {
					logger.warn("Sub-agent '{}' has no outputKey defined. This may cause data flow issues "
							+ "as downstream agents won't receive data from this agent.", subAgent.name());
				}
			}
		}

		/**
		 * Builds the ParallelAgent instance.
		 * @return the built ParallelAgent instance
		 * @throws GraphStateException if agent creation fails
		 */
		@Override
		public ParallelAgent doBuild() {
			validate();
			return new ParallelAgent(this);
		}

	}

View on GitHub (pinned to f82da0b50f)