conductor-oss/conductor · error · IllegalArgumentException

Passthrough agent ' ' must have exactly one worker tool…

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.

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.

Appendix: 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)