What causes "Tool run failed, toolId: {}, error: {}" in iflytek/astron-agent?

Inspect the logged `error: {}` message for the toolId to see the underlying exception

TOOL_CALL_FAILED

TOOL_CALL_FAILED

Error message

Tool run failed, toolId: {}, error: {}

What it means

AgentToolRuntimeService.runTool builds a ToolProtocolDto request and delegates to toolServiceCallHandler.toolRun. Any exception thrown during the remote tool execution is caught, logged with the toolId, and converted into an error content payload with code TOOL_CALL_FAILED instead of propagating. It means the tool invocation itself failed (connection error, remote exception, protocol error), and the failure is returned as normal tool output content.

Solutions

Inspect the logged `error: {}` message for the toolId to see the underlying exception
Verify the tool's endpoint configuration/definition (URL, auth headers) is correct and reachable from the service
Check the target tool service health (is the link/aitools plugin service running?)
Increase timeout or add retries for transient network failures
Surface the error content to the agent so it can retry or degrade gracefully

Example fix

// before
} catch (Exception e) {
    log.warn("Tool run failed, toolId: {}, error: {}", definition.getToolId(), e.getMessage());
    return errorContent("TOOL_CALL_FAILED", "Tool call failed: " + e.getMessage());
}
// after
} catch (Exception e) {
    log.warn("Tool run failed, toolId: {}, error: {}", definition.getToolId(), e.getMessage(), e);
    return retryOnceOrErrorContent(definition, "TOOL_CALL_FAILED", e);
}

Defensive patterns

Strategy: fallback

Validate before calling

// verify definition is complete before calling
if (definition == null || definition.getToolId() == null) return errorContent("TOOL_CALL_FAILED", "missing tool definition");

Try / catch

try { response = handler.toolRun(request); } catch (Exception e) { log.warn("tool {} failed", id, e); return errorContent("TOOL_CALL_FAILED", e.getMessage()); }

Prevention

Validate tool definitions (URL, headers) before registration
Add health checks for tool backend services
Set sane timeouts on the tool HTTP client
Return structured error content so agents can retry or degrade

When it happens

Trigger: toolServiceCallHandler.toolRun throws while executing a Link tool (callLinkTool path): network failure to the tool endpoint, timeout, remote 5xx, or serialization errors inside the handler.

Common situations: Link plugin service down or unreachable from the toolkit pod; tool endpoint timeout under load; bad tool definition (wrong URL/path template) causing handler exceptions; TLS/certificate issues in internal service calls.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/d3ddd3d27e7bdefa. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/tool/AgentToolRuntimeService.java:150

            if (item == null || StringUtils.isBlank(item.getName())) {
                continue;
            }
            Object value = assembleValue(item, args);
            String location = StringUtils.lowerCase(StringUtils.defaultString(item.getLocation()));
            switch (location) {
                case "header" -> header.put(item.getName(), value);
                case "query" -> query.put(item.getName(), value);
                case "path" -> path.put(item.getName(), value);
                default -> body.put(item.getName(), value);
            }
        }

        ToolProtocolDto request = buildRequest(definition, header, query, path, body);
        ToolProtocolDto response;
        try {
            response = toolServiceCallHandler.toolRun(request);
        } catch (Exception e) {
            log.warn("Tool run failed, toolId: {}, error: {}", definition.getToolId(), e.getMessage());
            return errorContent("TOOL_CALL_FAILED", "Tool call failed: " + e.getMessage());
        }
        return extractResult(response);
    }

    private ToolProtocolDto buildRequest(AgentToolDefinition definition, JSONObject header, JSONObject query,
            JSONObject path, JSONObject body) {
        ToolHeader toolHeader = new ToolHeader();
        toolHeader.setUid(definition.getUid());
        toolHeader.setAppId(commonConfig.getAppId());

        ToolParameter parameter = new ToolParameter();
        parameter.setToolId(definition.getToolId());
        parameter.setOperationId(definition.getOperationId());
        parameter.setVersion(definition.getVersion());

        Message message = new Message();
        if (!header.isEmpty()) {

View on GitHub (pinned to 5e758547a8)