conductor-oss/conductor · error · IllegalArgumentException

Passthrough agent '{}' must have exactly one worker tool def

Error message

Passthrough agent '{}' must have exactly one worker tool defined.

What it means

Error "Passthrough agent '{}' must have exactly one worker tool defined." thrown in conductor-oss/conductor.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java:3810

        metadata.put("_graph_workflow", true);
        if (config.getModel() != null) {
            metadata.put("model", config.getModel());
        }
        wf.setMetadata(metadata);

        return wf;
    }

    private boolean isFrameworkPassthrough(AgentConfig config) {
        return config.getMetadata() != null
                && Boolean.TRUE.equals(config.getMetadata().get("_framework_passthrough"));
    }

    WorkflowDef compileFrameworkPassthrough(AgentConfig config) {
        log.debug("Compiling framework passthrough workflow: {}", config.getName());

        if (config.getTools() == null || config.getTools().isEmpty()) {
            throw new IllegalArgumentException(
                    "Passthrough agent '"
                            + config.getName()
                            + "' must have exactly one worker tool defined.");
        }
        String workerName = config.getTools().get(0).getName();

        WorkflowTask fwTask = new WorkflowTask();
        fwTask.setType("SIMPLE");
        fwTask.setName(workerName);
        fwTask.setTaskReferenceName("_fw_task");
        fwTask.setInputParameters(
                new LinkedHashMap<>(
                        Map.of(
                                "prompt", "${workflow.input.prompt}",
                                "session_id", "${workflow.input.session_id}",
                                "media", "${workflow.input.media}",
                                "cwd", "${workflow.input.cwd}")));

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Define exactly one worker tool on the passthrough agent.
2. Remove extra tools or add the single worker tool the passthrough should delegate to.

When it happens

Trigger: Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java:3810 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/19edda2689bbbd65. Report an issue: GitHub.