conductor-oss/conductor · error · IllegalArgumentException

Cannot compile external agent '{}' directly. External agents

Error message

Cannot compile external agent '{}' directly. External agents are compiled as SubWorkflowTask references.

What it means

Error "Cannot compile external agent '{}' directly. External agents are compiled as SubWorkflowTask references." thrown in conductor-oss/conductor.

Source

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

    }

    /**
     * Public entry point: compile an {@link AgentConfig} into a {@link WorkflowDef}. An agent's
     * compiled tool list is exactly its declared tool list — capabilities are opted into explicitly
     * from the SDK, never injected here.
     */
    public WorkflowDef compile(AgentConfig config) {
        WorkflowDef wf;

        // Passthrough check MUST be first — passthrough configs have null model.
        // Any other branch would crash on null model.
        if (isFrameworkPassthrough(config)) {
            wf = compileFrameworkPassthrough(config);
        } else if (isGraphStructure(config)) {
            // Graph-structure: custom StateGraph with node/edge workflow
            wf = compileGraphStructure(config);
        } else if (config.isExternal()) {
            throw new IllegalArgumentException(
                    "Cannot compile external agent '"
                            + config.getName()
                            + "' directly. "
                            + "External agents are compiled as SubWorkflowTask references.");
        } else {
            // ``hasAgents`` covers any of the ways an agent can declare
            // sub-agents: the legacy ``agents=[…]`` list, OR the named
            // PLAN_EXECUTE slots (``planner=`` and/or ``fallback=``).
            // Without checking the named slots, a PLAN_EXECUTE coordinator
            // declared with ``planner=`` would have an empty agents list,
            // hasAgents=false, and dispatch would fall to compileWithTools
            // — silently dropping the strategy.
            boolean hasAgents =
                    (config.getAgents() != null && !config.getAgents().isEmpty())
                            || config.getPlanner() != null
                            || config.getFallback() != null;
            boolean hasTools = config.getTools() != null && !config.getTools().isEmpty();

View on GitHub (pinned to cf7c3e4a8a)

Solutions

1. Reference the external agent as a SubWorkflowTask instead of compiling it directly.
2. Move external agents into the harness's sub-agent list so the compiler emits a SubWorkflow reference.

When it happens

Trigger: Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java:127 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/a4f659ba6ebb3d46. Report an issue: GitHub.