{"record":{"id":"a4f659ba6ebb3d46","repo":"conductor-oss/conductor","slug":"cannot-compile-external-agent-directly-exter","errorCode":null,"errorMessage":"Cannot compile external agent '{}' directly. External agents are compiled as SubWorkflowTask references.","messagePattern":"Cannot compile external agent '(.+?)' directly\\. External agents are compiled as SubWorkflowTask references\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java","lineNumber":127,"sourceCode":"    }\n\n    /**\n     * Public entry point: compile an {@link AgentConfig} into a {@link WorkflowDef}. An agent's\n     * compiled tool list is exactly its declared tool list — capabilities are opted into explicitly\n     * from the SDK, never injected here.\n     */\n    public WorkflowDef compile(AgentConfig config) {\n        WorkflowDef wf;\n\n        // Passthrough check MUST be first — passthrough configs have null model.\n        // Any other branch would crash on null model.\n        if (isFrameworkPassthrough(config)) {\n            wf = compileFrameworkPassthrough(config);\n        } else if (isGraphStructure(config)) {\n            // Graph-structure: custom StateGraph with node/edge workflow\n            wf = compileGraphStructure(config);\n        } else if (config.isExternal()) {\n            throw new IllegalArgumentException(\n                    \"Cannot compile external agent '\"\n                            + config.getName()\n                            + \"' directly. \"\n                            + \"External agents are compiled as SubWorkflowTask references.\");\n        } else {\n            // ``hasAgents`` covers any of the ways an agent can declare\n            // sub-agents: the legacy ``agents=[…]`` list, OR the named\n            // PLAN_EXECUTE slots (``planner=`` and/or ``fallback=``).\n            // Without checking the named slots, a PLAN_EXECUTE coordinator\n            // declared with ``planner=`` would have an empty agents list,\n            // hasAgents=false, and dispatch would fall to compileWithTools\n            // — silently dropping the strategy.\n            boolean hasAgents =\n                    (config.getAgents() != null && !config.getAgents().isEmpty())\n                            || config.getPlanner() != null\n                            || config.getFallback() != null;\n            boolean hasTools = config.getTools() != null && !config.getTools().isEmpty();\n","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java#L109-L145","documentation":"Error \"Cannot compile external agent '{}' directly. External agents are compiled as SubWorkflowTask references.\" thrown in conductor-oss/conductor.","triggerScenarios":"Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/AgentCompiler.java:127 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Reference the external agent as a SubWorkflowTask instead of compiling it directly.","Move external agents into the harness's sub-agent list so the compiler emits a SubWorkflow reference."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}