fix(ollama): use native schemas for structured agent output

[guslegend0510]

AgentScope-Java Version

2.1.0-SNAPSHOT

Description

Fixes #3452.

ReActAgent.call(messages, Output.class) used Ollama's synthetic generate_response tool. When the model returned JSON text instead of invoking that tool, the response preserved its text and usage but lacked _structured_output, causing getStructuredData(Output.class) to throw.

Send the output schema through Ollama's native format field for structured calls, including calls with application tools. Map JSON Schema to the bare schema and JSON object mode to "json". Requests with application tools include both tools and format, allowing the agent to execute tools before reading the final JSON response. Native request errors retain the existing synthetic-tool fallback.

Regression tests cover streaming and non-streaming results, image input, thinking/usage preservation, default-format precedence, direct constructors, native output with registered tools, a complete business-tool round trip, and fallback after a native request error. Update the English and Chinese Ollama guides with the required server/model capabilities and official API references.

Validation

• The new routing tests fail before removing the tools restriction and pass afterward.
• Focused structured-output tests: 27 tests, zero failures/errors, 1 conditional skip.
• Full relevant module tests: Core 2,590 (9 skipped), Harness 1,144 (18 skipped), AG-UI 508, Ollama 187 (1 skipped); zero failures/errors.
• Repository-wide mvn -B -T1 clean verify passed across all 97 reactor modules, including MongoDB Testcontainers tests: 10,444 tests, zero failures/errors, 196 skipped.
• git diff --check and Spotless passed.
• Documentation: npm test (13 passed), npm run validate, and npm run broken-links passed.
• Provider responses are mocked; a live qwen3.5/Ollama run has not been performed.

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test) — full repository clean verify passed; skipped tests are listed above
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated
• Code is ready for review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[jujn]

意思是“Ollama 有业务工具时不支持原生结构化输出”？有官方文档或代码依据吗？

[guslegend0510]

这里表述不够清楚。带业务工具时继续使用 generate_response，描述的是本 PR 的实现策略；目前没有依据可以断言 Ollama 本身不支持 tools + format。官方 API 同时定义了这两个字段，服务端也有一起传递它们的路径。当前测试仅验证合成工具回退，尚未实测组合行为。文档应明确这一范围，避免被理解为 Ollama 的通用限制。

[jujn]

如果方便的话，可以本地验证下 tools + format 是否支持。单纯支持不带工具的原生结构化输出，作用面很有限（Ollama 其实也支持 ToolChoice.Specific("generate_response")）

[xiaoshuai288]

我出现这个没有key的bug时，调用工具的与未调用工具的请求都出现了这个bug，另外现在这个修复算不算稳定版，小版本发布下一次是什么时候，现在是否可以使用兜底的方式去从TextBlock中拿结果去解析JSON这种做法是否可以稳定

 public static <T> T getStructuredData(Msg msg, Class<T> clazz) {
        if (msg == null) {
            return null;
        }
        // 优先使用框架提供的结构化数据方法
        if (msg.hasStructuredData()) {
            return msg.getStructuredData(clazz);
        }

        // 兜底：从文本内容解析 JSON
        log.warn("Agent 未包含结构化数据标识，尝试从文本内容解析 JSON");
        return parseFromTextContent(msg, clazz);
    }

[jujn]

我出现这个没有key的bug时，调用工具的与未调用工具的请求都出现了这个bug，另外现在这个修复算不算稳定版，小版本发布下一次是什么时候，现在是否可以使用兜底的方式去从TextBlock中拿结果去解析JSON这种做法是否可以稳定

主分支已经有了增强的结构化输出保障：#2697
这边大概每隔三周发布一次版本。

[jujn]

设置了不能编辑，麻烦开下，我本地修改推不上来（其它PR可以）

[guslegend0510]

设置了不能编辑，麻烦开下，我本地修改推不上来（其它PR可以）

好了

[xiaoshuai288]

下一个小版本什么时候发布