{"record":{"id":"c814d19319ee40df","repo":"conductor-oss/conductor","slug":"a2a-agent-card-discovery-requires-agenturl","errorCode":null,"errorMessage":"A2A agent-card discovery requires 'agentUrl'","messagePattern":"A2A agent-card discovery requires 'agentUrl'","errorType":"http","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"ai/src/main/java/org/conductoross/conductor/ai/a2a/A2ACallbackResource.java","lineNumber":86,"sourceCode":"        this.taskService = taskService;\n        this.a2aService = a2aService;\n    }\n\n    /**\n     * Resolve a public A2A Agent Card using the same discovery, network policy, and SSRF checks as\n     * the {@code GET_AGENT_CARD} system task.\n     *\n     * <p>The typed result deliberately contains only the discovered card. Request headers are used\n     * for discovery but are never reflected into the response, which makes the result safe to\n     * persist as workflow task metadata.\n     */\n    @PostMapping(\"/agent-card\")\n    public A2AAgentCardResult getAgentCard(@RequestBody A2AAgentCardRequest request) {\n        if (request == null || !A2AService.isA2aAgentType(request.getAgentType())) {\n            throw new IllegalArgumentException(\"A2A agent-card discovery requires agentType 'a2a'\");\n        }\n        if (StringUtils.isBlank(request.getAgentUrl())) {\n            throw new IllegalArgumentException(\"A2A agent-card discovery requires 'agentUrl'\");\n        }\n        AgentCard card = a2aService.getAgentCard(request.getAgentUrl(), request.getHeaders());\n        return new A2AAgentCardResult(card);\n    }\n\n    @PostMapping(\"/callback/{taskId}\")\n    public ResponseEntity<Void> onPushNotification(\n            @PathVariable(\"taskId\") String taskId,\n            @RequestHeader(value = \"Authorization\", required = false) String authHeader,\n            @RequestHeader(value = \"X-Conductor-A2A-Token\", required = false) String customHeader,\n            @RequestBody(required = false) JsonNode payload) {\n\n        try (A2ALogging.Scope scope = A2ALogging.of(A2ALogging.TASK_ID, taskId)) {\n            String token = resolveToken(authHeader, customHeader);\n\n            Task task = loadTask(taskId);\n            if (task == null || !A2AWorkers.AGENT.equals(task.getTaskType())) {\n                return ResponseEntity.notFound().build();","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/ai/src/main/java/org/conductoross/conductor/ai/a2a/A2ACallbackResource.java#L68-L104","documentation":"Thrown by the A2ACallbackResource.getAgentCard() REST endpoint when the request passes the agentType check but agentUrl is null, empty, or whitespace-only. The endpoint needs a valid URL to discover the remote agent's card.","triggerScenarios":"POST to /api/a2a/agent-card with agentType correctly set (or null) but agentUrl missing, empty, or blank in the request body.","commonSituations":"The agentUrl field was omitted from the request JSON. The agentUrl was templated from a variable that resolved to null or empty. The request body was partially constructed.","solutions":["Include a non-blank agentUrl in the request body, e.g. \"agentUrl\": \"https://my-agent.example.com\"","Verify the URL value is populated before making the request","Ensure the agentUrl points to the base URL of the remote A2A agent (the endpoint appends /.well-known/agent-card.json)"],"exampleFix":"// before\n{\"agentType\": \"a2a\"}\n// after\n{\"agentType\": \"a2a\", \"agentUrl\": \"https://my-agent.example.com\"}","handlingStrategy":"validation","validationCode":"// Validate agentUrl is present before calling the endpoint\nif (StringUtils.isBlank(request.getAgentUrl())) {\n    throw new IllegalArgumentException(\"agentUrl is required\");\n}","typeGuard":"public boolean hasValidAgentUrl(A2AAgentCardRequest req) {\n    return req != null && StringUtils.isNotBlank(req.getAgentUrl());\n}","tryCatchPattern":"// REST endpoint — IllegalArgumentException maps to HTTP 400 by default","preventionTips":["Always include agentUrl in the A2AAgentCardRequest body","Validate the request JSON on the client side before posting","Ensure agentUrl is populated from a reliable source, not a variable that may be null"],"tags":["a2a","rest-api","input-validation"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}