From 48823952069c24fc99ac62c7c6e639df124d7301 Mon Sep 17 00:00:00 2001 From: Matthias Schur <107557548+MattSchur@users.noreply.github.com> Date: Wed, 16 Sep 2026 16:46:13 +0200 Subject: [PATCH 1/8] AI Guid: Agents +Java --- guides/ai/cap-agents.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index fce9b385b..bfa296379 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -22,7 +22,7 @@ npm add @cap-js/agents cds-adapter-agent ``` - ::: +::: @@ -66,11 +66,14 @@ annotate CatalogService.submitOrder with @agent.hitl; // [!code focus] When the agent decides to call the action, the task pauses and transitions to the A2A [`input-required`](https://a2a-protocol.org/latest/specification/#413-taskstate) state instead of running the action immediately. +> [!warning] Only supported by CAP Node.js +> `@agent.hitl` is not yet supported by CAP Java + ### Optional: `AGENTS.md` -You can add an `AGENTS.md` file next to the service definition's `.cds` file to add detailed information about the agent's identity and behaviour. When present, it replaces the generic default agentification: instead of the auto-generated ReAct agent, the plugin auto-builds the agent from the directory at startup — no JavaScript handlers required. +You can add an `AGENTS.md` file next to the service definition's `.cds` file to add detailed information about the agent's identity and behaviour. When present, it replaces the generic default agentification: instead of the auto-generated ReAct agent, the plugin auto-builds the agent from the directory at startup — no custom handlers required. For example, we do so in the [XTravels sample](./xtravels-sample.md): @@ -241,10 +244,12 @@ DEBUG=agents cds watch > [!tip] Zero Configuration > The plugin can automatically fetch required/missing credentials from local installations of supported LLMs, allowing you to work with zero additional configuration. +> [!warning] CAP Node.js only +> Auto configuration from local Claude and OpenCode installations is not supported by CAP Java ### Using Chat Preview -For local development, the plugin serves a rudimentary experimental chat preview at http://localhost:4004/a2a/browse/preview/. +For local development, a rudimentary experimental chat preview is provided via the generic index page (In Node.js via http://localhost:4004/a2a/browse/preview/). Open the chat preview in your browser to interact with the agent. For example, enter the same prompts as we did over in the [MCP Services](./cap-mcp.md#using-opencode-or-alike) guide with OpenCode: @@ -268,6 +273,10 @@ Also answer the questions that the agent asks you back. Given [`@agent`](#declare-agent-services)-annotated service definitions, the plugin automatically creates an agent per CAP service with the configured models, served out of the box via A2A endpoints, with seamless integration with local service capabilities, and ready-to-use support for persistence, telemetry, quotas, content filtering, as well as enterprise-grade features like audit logging, data privacy, and security. +> [!warning] CAP Node.js only +> Persistent chat history, telemetry, quotas, content filtering, audit logging and data privacy features are not yet supported by CAP Java. + +[Learn more about agents in CAP Java.](/@external/java/ai#ai-agents){.learn-more} ### Autowired Tools via MCP @@ -338,6 +347,7 @@ All events are emitted as `SecurityEvent` for compatibility with the SAP Audit L For details on configuring and using audit logging, refer to the documentation at: https://github.com/cap-js/agents/blob/main/.docs/audit-logging.md. + ### Persistence The CAP-based harness provides short-term memory for agents by storing conversational and checkpoints in the connected primary database. From 5b2eb247db84c73ab4edd3d33878b9f27924ef0d Mon Sep 17 00:00:00 2001 From: Matthias Schur <107557548+MattSchur@users.noreply.github.com> Date: Wed, 16 Sep 2026 16:49:05 +0200 Subject: [PATCH 2/8] Apply suggestion from @MattSchur --- guides/ai/cap-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index bfa296379..82b0bc42a 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -249,7 +249,7 @@ DEBUG=agents cds watch ### Using Chat Preview -For local development, a rudimentary experimental chat preview is provided via the generic index page (In Node.js via http://localhost:4004/a2a/browse/preview/). +For local development, a rudimentary experimental chat preview is provided via the generic index page (In CAP Node.js via http://localhost:4004/a2a/browse/preview/). Open the chat preview in your browser to interact with the agent. For example, enter the same prompts as we did over in the [MCP Services](./cap-mcp.md#using-opencode-or-alike) guide with OpenCode: From e4de667ab2c4b380660dfc648466a5ae7dc58585 Mon Sep 17 00:00:00 2001 From: Matthias Schur <107557548+MattSchur@users.noreply.github.com> Date: Wed, 16 Sep 2026 16:49:27 +0200 Subject: [PATCH 3/8] Apply suggestion from @MattSchur --- guides/ai/cap-agents.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index 82b0bc42a..724ae2a47 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -347,7 +347,6 @@ All events are emitted as `SecurityEvent` for compatibility with the SAP Audit L For details on configuring and using audit logging, refer to the documentation at: https://github.com/cap-js/agents/blob/main/.docs/audit-logging.md. - ### Persistence The CAP-based harness provides short-term memory for agents by storing conversational and checkpoints in the connected primary database. From 369a1ea674674b42a39392a44712c14b6c9db226 Mon Sep 17 00:00:00 2001 From: Daniel Hutzel Date: Thu, 17 Sep 2026 09:32:59 +0200 Subject: [PATCH 4/8] Update guides/ai/cap-agents.md --- guides/ai/cap-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index 724ae2a47..8d67e7dd5 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -249,7 +249,7 @@ DEBUG=agents cds watch ### Using Chat Preview -For local development, a rudimentary experimental chat preview is provided via the generic index page (In CAP Node.js via http://localhost:4004/a2a/browse/preview/). +In CAP Node.js, a rudimentary experimental chat preview is provided in the generic _index.html_ page → see the _Preview_ links next to the A2A endpoints – which can be used in local development. Open the chat preview in your browser to interact with the agent. For example, enter the same prompts as we did over in the [MCP Services](./cap-mcp.md#using-opencode-or-alike) guide with OpenCode: From dbe2578c80814863e20775ae16e0765914741681 Mon Sep 17 00:00:00 2001 From: Daniel Hutzel Date: Thu, 17 Sep 2026 09:33:06 +0200 Subject: [PATCH 5/8] Update guides/ai/cap-agents.md --- guides/ai/cap-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index 8d67e7dd5..b1f0ba177 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -251,7 +251,7 @@ DEBUG=agents cds watch In CAP Node.js, a rudimentary experimental chat preview is provided in the generic _index.html_ page → see the _Preview_ links next to the A2A endpoints – which can be used in local development. -Open the chat preview in your browser to interact with the agent. For example, enter the same prompts as we did over in the [MCP Services](./cap-mcp.md#using-opencode-or-alike) guide with OpenCode: +For our bookshop sample, open the chat preview in your browser at http://localhost:4004/a2a/browse/preview/ to interact with the agent. In the chat, enter the same prompts as we did over in the [MCP Services](./cap-mcp.md#using-opencode-or-alike) guide with OpenCode: ```sh From 8382cc4104e2e0ade61b22034c9485f428b23265 Mon Sep 17 00:00:00 2001 From: Daniel Hutzel Date: Thu, 17 Sep 2026 09:34:24 +0200 Subject: [PATCH 6/8] Update guides/ai/cap-agents.md --- guides/ai/cap-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index b1f0ba177..af10e77f4 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -73,7 +73,7 @@ When the agent decides to call the action, the task pauses and transitions to th ### Optional: `AGENTS.md` -You can add an `AGENTS.md` file next to the service definition's `.cds` file to add detailed information about the agent's identity and behaviour. When present, it replaces the generic default agentification: instead of the auto-generated ReAct agent, the plugin auto-builds the agent from the directory at startup — no custom handlers required. +You can add an `AGENTS.md` file next to the service definition's `.cds` file to add detailed information about the agent's identity and behaviour. When present, it replaces the generic default agentification: instead of the auto-generated _ReAct_ agent, the plugin auto-builds the agent from the directory at startup — no custom handlers required. For example, we do so in the [XTravels sample](./xtravels-sample.md): From 69ee9a59093a619669934a1c5944febafbc22ffa Mon Sep 17 00:00:00 2001 From: Daniel Hutzel Date: Thu, 17 Sep 2026 10:15:56 +0200 Subject: [PATCH 7/8] Update guides/ai/cap-agents.md Co-authored-by: Matthias Schur <107557548+MattSchur@users.noreply.github.com> --- guides/ai/cap-agents.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index af10e77f4..8faa34e06 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -249,7 +249,7 @@ DEBUG=agents cds watch ### Using Chat Preview -In CAP Node.js, a rudimentary experimental chat preview is provided in the generic _index.html_ page → see the _Preview_ links next to the A2A endpoints – which can be used in local development. +A rudimentary experimental chat preview is provided in the generic _index.html_ page → see the _Preview_ links next to the A2A endpoints – which can be used in local development. For our bookshop sample, open the chat preview in your browser at http://localhost:4004/a2a/browse/preview/ to interact with the agent. In the chat, enter the same prompts as we did over in the [MCP Services](./cap-mcp.md#using-opencode-or-alike) guide with OpenCode: From 9f454e3a891b1d06c2b48f29a09433b11064edf4 Mon Sep 17 00:00:00 2001 From: Daniel Hutzel Date: Thu, 17 Sep 2026 10:21:37 +0200 Subject: [PATCH 8/8] Fixed links --- guides/ai/cap-agents.md | 2 +- java/ai.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index 8faa34e06..87af35eab 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -276,7 +276,7 @@ Given [`@agent`](#declare-agent-services)-annotated service definitions, the plu > [!warning] CAP Node.js only > Persistent chat history, telemetry, quotas, content filtering, audit logging and data privacy features are not yet supported by CAP Java. -[Learn more about agents in CAP Java.](/@external/java/ai#ai-agents){.learn-more} +[Learn more about agents in CAP Java.](../../java/ai#agents){.learn-more} ### Autowired Tools via MCP diff --git a/java/ai.md b/java/ai.md index 572737a45..867df248d 100644 --- a/java/ai.md +++ b/java/ai.md @@ -16,7 +16,7 @@ description: > -## Agents { #ai-agents } +## Agents A CAP agent turns a CDS service into a conversational endpoint. It answers natural-language requests by using the service's entities, actions, and functions as tools, backed by an