> ⚠️ **Postponed pending approval.** Part of the [Chat Fundamentals plan](https://git.drupalcode.org/project/ai/-/work_items/3586640); awaits maintainer approval ([approval issue](https://git.drupalcode.org/project/ai/-/work_items/3586639)). Targets the **1.6.x branches of ai and ai_agents once created**. **Depends on (ai project):** [ContentBlockProducerInterface + tool annotations (#3586642)](https://git.drupalcode.org/project/ai/-/work_items/3586642), [content blocks (#3586643)](https://git.drupalcode.org/project/ai/-/work_items/3586643), [structured response channel (#3586644)](https://git.drupalcode.org/project/ai/-/work_items/3586644); the [renderer plugin type (#3586645)](https://git.drupalcode.org/project/ai/-/work_items/3586645) for the rendered end result. ### Problem/Motivation `AiAgentEntityWrapper` flattens every tool result to a string. In the tool loop (`src/PluginBase/AiAgentEntityWrapper.php`, ~lines 612–642): ```php $this->executeTool($tool, TRUE); $output = $tool->getReadableOutput(); // (artifact substitution may replace $output with an artifact handle) $message = new ChatMessage('tool', $output); $message->setToolsId($tool->getToolsId()); $this->chatHistory[] = $message; ``` Two things are lost here: 1. `StructuredExecutableFunctionCallInterface::getStructuredOutput()` — already implemented in `FunctionCallBase` — is never read. A tool that computes structured data throws it away at the loop boundary. 2. There is no path for a tool to surface anything rich to the *end user*. The readable output serves the model; whatever the user eventually sees is the model's prose paraphrase of it. A weather tool cannot ship a forecast card; a search tool cannot ship result links. With the ai-side foundations in place (tool-side `ContentBlockProducerInterface`, content blocks on `ChatMessage`), the agent loop just needs to stop dropping them. ### Proposed resolution After tool execution in the loop, additively enrich the tool `ChatMessage`: - If the tool implements `StructuredExecutableFunctionCallInterface`, attach its structured output as `_meta['drupal.org/ai.structured_content']` on the tool message — the analog of MCP's `CallToolResult.structuredContent`. - If the tool implements `ContentBlockProducerInterface` (#3586642), attach its blocks via `setContentBlocks()`. - **Audience routing** (the MCP-native mechanism, no custom routing needed): blocks whose `annotations.audience` includes `"user"` bubble into the agent's final response manifest — surfaced to the frontend through the assistant processor's `getStructuredResponse()` (#3586644). The LLM continues to see **only** the readable output string, so prompt size and token cost are unchanged. Blocks with `audience: ["assistant"]` are reserved for future model-facing use and are not bubbled. - **Artifact composition:** the existing artifact-replacement path (readable output swapped for an artifact handle when `toolShouldUseArtifacts()`) is untouched — blocks and `_meta` ride alongside whichever string the model sees. - The `toolShouldReturnDirectly()` short-circuit also carries the tool's user-audience blocks into the direct response. **Documentation:** a worked example in ai_agents docs — a weather tool implementing `ContentBlockProducerInterface` returning one `resource_link`/`text` block with `_meta` payload, plus a `ChatBlockRenderer` plugin with a Twig template matching `tool_name`, demonstrating the full "weather tool → card" path. **Tests:** kernel test with a fixture tool implementing both interfaces, asserting: the tool message carries `_meta` + blocks; user-audience blocks appear in the final manifest; readable output and the messages sent to the (mocked) provider are byte-identical to before. ### Backwards compatibility Tool messages gain `_meta`/blocks; readable-output text is unchanged, so prompts, providers and existing consumers are unaffected. Sites not using block-aware consumers see no difference. ### AI Assistance Yes, AI was used to explore the codebase and draft this issue.