What causes "Agent not found: ${name}" in conductor-oss/conductor?

Confirm the workflow definition has metadata.agent_sdk or metadata.agentDef set (use getAgentDef to inspect).

conductor-oss/conductor · error · NotFoundException

Agent not found: ${name}

Error message

Agent not found: ${name}

What it means

Thrown by AgentService.getRegisteredAgent (private) when a workflow definition is found by name/version (or latest) but its metadata does not classify as an agent (WorkflowClassifiers.isAgent returns false). This means the name resolves to a regular Conductor workflow, not an agent. NotFoundException maps to HTTP 404. This guard prevents non-agent workflows from being started or resolved through the agent API surface.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/service/AgentService.java:313

    private WorkflowDef getRegisteredAgent(String name, Integer version) {
        WorkflowDef def =
                version != null
                        ? metadataDAO
                                .getWorkflowDef(name, version)
                                .orElseThrow(
                                        () ->
                                                new NotFoundException(
                                                        "Agent not found: "
                                                                + name
                                                                + " v"
                                                                + version))
                        : metadataDAO
                                .getLatestWorkflowDef(name)
                                .orElseThrow(
                                        () -> new NotFoundException("Agent not found: " + name));
        if (!WorkflowClassifiers.isAgent(def.getMetadata())) {
            throw new NotFoundException("Agent not found: " + name);
        }
        return def;
    }

    private AgentConfig resolveStoredConfig(WorkflowDef def) {
        Map<String, Object> agentDef = storedAgentDef(def);
        Object sdkValue = def.getMetadata().get("agent_sdk");
        String sdk = sdkValue instanceof String ? (String) sdkValue : "conductor";
        if (sdk.isBlank() || "conductor".equals(sdk)) {
            return MAPPER.convertValue(agentDef, AgentConfig.class);
        }
        return normalizerRegistry.normalize(sdk, agentDef);
    }

    @SuppressWarnings("unchecked")
    private Map<String, Object> storedAgentDef(WorkflowDef def) {
        Map<String, Object> metadata = def.getMetadata();
        if (metadata != null && metadata.get("agentDef") instanceof Map<?, ?>) {

View on GitHub (pinned to cf7c3e4a8a)

Solutions

Confirm the workflow definition has metadata.agent_sdk or metadata.agentDef set (use getAgentDef to inspect).
Redeploy the agent via AgentService.deploy() which stamps the required metadata.
If the name was meant for a regular workflow, use the standard workflow start API instead of the agent API.

Example fix

// before
startRequest.setName("my_regular_workflow");
service.start(startRequest); // -> NotFoundException: Agent not found

// after
// Redeploy as an agent so metadata.agent_sdk is stamped
service.deploy(agentStartRequest);
startRequest.setName("my_agent");
service.start(startRequest);

Defensive patterns

Strategy: validation

Validate before calling

// Verify the name resolves to an agent before starting
List<AgentSummary> agents = agentService.listAgents();
boolean isAgent = agents.stream()
    .anyMatch(a -> a.getName().equals(name));
if (!isAgent) {
    return ResponseEntity.notFound().build();
}

Try / catch

try {
    service.start(request);
} catch (NotFoundException e) {
    if (e.getMessage().contains("Agent not found")) {
        // name does not resolve to an agent def
        return ResponseEntity.status(404).body(e.getMessage());
    }
    throw e;
}

Prevention

Use deploy() to register agents so metadata.agent_sdk is stamped.
Avoid registering plain workflows with names that collide with agent names.
Call listAgents() to verify an agent name before start().

When it happens

Trigger: Calling start with agentName pointing to a regular (non-agent) workflow definition; the workflow def was registered without agent_sdk/agentDef metadata; a non-agent workflow happens to share the name of a previously-deployed agent.

Common situations: Naming collision between a hand-registered workflow and an agent; agent was deployed via a path that did not stamp agent_sdk metadata (e.g. direct MetadataService.registerWorkflowDef bypassing deploy()); the classifier logic changed between versions and a previously-valid agent no longer classifies.

Related errors

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