alibaba/nacos · error · IllegalArgumentException

Agent direct-online request must contain callInterfaces

Error message

Agent direct-online request must contain callInterfaces

What it means

Thrown by AgentOperationService.validateDirectOnlineRequest as an IllegalArgumentException when callInterfaces is null OR basedOnVersion is non-blank. A direct-online version must declare its own callInterfaces (it cannot derive from a base version), so the presence of basedOnVersion or absence of callInterfaces is rejected. This enforces that direct-online versions are self-contained.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/service/agent/AgentOperationService.java:777

            AiConstants.Agent.VERSION_STATUS_ONLINE);
        persistenceService.synchronizeDerivedState(namespaceId, agentName,
            setAsLatest ? version : null, null,
            AiConstants.Agent.VERSION_STATUS_DRAFT.equals(status) ? version : null,
            AiConstants.Agent.VERSION_STATUS_REVIEWING.equals(status)
                || AiConstants.Agent.VERSION_STATUS_REVIEWED.equals(status) ? version : null);
        return persistenceService.getAgentVersion(namespaceId, agentName, version);
    }
    
    private void validateDirectOnlineRequest(String namespaceId,
        AgentDraftCreateRequest request) {
        if (request == null) {
            throw new IllegalArgumentException("Agent direct-online request must not be null");
        }
        AgentValidationUtils.validateNamespaceId(namespaceId);
        request.validate();
        if (request.getCallInterfaces() == null || StringUtils.isNotBlank(
            request.getBasedOnVersion())) {
            throw new IllegalArgumentException(
                "Agent direct-online request must contain callInterfaces");
        }
    }
    
    private AgentVersionDetail toOnlineVersion(AgentDraftCreateRequest request) {
        AgentVersionDetail result = new AgentVersionDetail();
        result.setVersion(request.getVersion());
        result.setStatus(AiConstants.Agent.VERSION_STATUS_ONLINE);
        result.setCallInterfaces(request.getCallInterfaces());
        result.setAuthor(request.getAuthor());
        result.setChangeDescription(request.getChangeDescription());
        return result;
    }
    
    private boolean containsProtocol(AgentVersionDetail version, String protocol) {
        if (version.getCallInterfaces() == null) {
            return false;
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

Ensure request.setCallInterfaces(...) is populated with a non-null list before the direct-online call.
Clear request.setBasedOnVersion(null) or empty string — direct-online does not derive from a base version.
Validate both conditions client-side before submitting: callInterfaces != null AND basedOnVersion is blank.

Example fix

// before — reusing a draft request for direct-online
AgentDraftCreateRequest req = new AgentDraftCreateRequest();
req.setBasedOnVersion("1.0.0");
// callInterfaces null
service.registerDirectOnline(ns, req);

// after
AgentDraftCreateRequest req = new AgentDraftCreateRequest();
req.setBasedOnVersion(null); // direct-online is self-contained
req.setCallInterfaces(List.of(new AgentCallInterface("A2A", ...)));
service.registerDirectOnline(ns, req);

Defensive patterns

Strategy: validation

Validate before calling

// Validate direct-online preconditions before calling
if (request.getCallInterfaces() == null) {
    throw new IllegalArgumentException("callInterfaces is required for direct-online");
}
if (StringUtils.isNotBlank(request.getBasedOnVersion())) {
    request.setBasedOnVersion(null); // direct-online is self-contained
}
agentOperationService.registerDirectOnline(ns, request);

Type guard

public static boolean isDirectOnlineReady(AgentDraftCreateRequest request) {
    return request != null
        && request.getCallInterfaces() != null
        && !request.getCallInterfaces().isEmpty()
        && StringUtils.isBlank(request.getBasedOnVersion());
}

Try / catch

try {
    agentOperationService.registerDirectOnline(ns, request);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must contain callInterfaces")) {
        // fix the request and retry
        request.setBasedOnVersion(null);
        request.setCallInterfaces(loadCallInterfaces(request));
        agentOperationService.registerDirectOnline(ns, request);
    } else {
        throw e;
    }
}

Prevention

Always populate callInterfaces with a non-null, non-empty list for direct-online.
Never set basedOnVersion on a direct-online request — it must be self-contained.
Use a dedicated request builder for direct-online that enforces both rules.

When it happens

Trigger: Calling the direct-online path with request.getCallInterfaces() == null. Calling it with a non-blank basedOnVersion (which implies deriving from another version, incompatible with direct-online semantics). Both conditions trigger the same exception.

Common situations: Client reuses a draft-create request (which has basedOnVersion set) for the direct-online path without clearing it. Frontend forgets to populate callInterfaces for direct-online. Misunderstanding that direct-online requires full interface declarations, not a delta from a base version.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/7ed554fe18b85c72. Report an issue: GitHub.