From 6f34c1fa049ba71fb93f833a4996256d05d3e06e Mon Sep 17 00:00:00 2001 From: D051920 Date: Tue, 29 Sep 2026 16:52:27 +0200 Subject: [PATCH 1/2] fix: improve agent docs --- guides/ai/cap-agents.md | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index 8033fc7d8..dfbeaea23 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -66,9 +66,22 @@ 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. +> [!tip] Annotation Placement Matters +> The CDS compiler only recognizes annotations placed **before** the action keyword or in a separate `annotate` statement. Annotations placed **after** the `returns` clause are silently ignored: +> ```cds +> // ✅ Correct - annotation before action +> @agent.hitl +> action submitOrder(...) returns String; +> +> // ✅ Also correct - separate annotate statement (shown above) +> annotate CatalogService.submitOrder with @agent.hitl; +> +> // ❌ WRONG - silently ignored by CDS compiler +> action submitOrder(...) returns String @agent.hitl; +> ``` + > [!warning] Only supported by CAP Node.js > `@agent.hitl` is not yet supported by CAP Java @@ -221,7 +234,7 @@ You can see the effects of this in the server logs when starting your CAP applic ```shell [agents] - cds.connect.to 'llm' with: { kind: 'anthropic', - model: 'claude-sonnet-4-6', + model: 'anthropic--claude-4.6-sonnet', credentials: { anthropicApiUrl: 'http://localhost:4711/anthropic/', apiKey: '***' @@ -237,7 +250,7 @@ DEBUG=agents cds watch ```shell [agents] - Loaded config from ~/.claude/settings.json : { anthropicApiUrl: 'http://localhost:4711/anthropic/', - model: 'claude-sonnet-4-6', + model: 'anthropic--claude-4.6-sonnet', apiKey: '***' } ``` @@ -312,13 +325,13 @@ Similarly, when asked to _"order wuthering heights"_, the agent eventually invok -### Subagents via A2A +### Multi-Agent Coordination via A2A -In addition to a main agent served out of the box, developers can define subagents that handle specific tasks or domains within the CAP application, allowing for modular and scalable agent architectures. +CAP agents can communicate with each other using the [A2A protocol](https://a2a-protocol.org), enabling modular and scalable multi-agent architectures. All [`@agent`](#declare-agent-services)-annotated services are **peers** — any agent can call other agents, regardless of whether they run in the same process or are deployed separately. -This includes [`@agent`](#declare-agent-services)-ified services, [imported](../integration/calesi.md) from external CAP projects. The main agent coordinates these subagents, and communicates with them via A2A endpoints. +This includes [`@agent`](#declare-agent-services)-ified services [imported](../integration/calesi.md) from external CAP projects, which can be invoked via their A2A endpoints. -We demonstrate the use of subagents in the [_XTravels_ sample](./xtravels-sample.md) application. +Common patterns include **coordinator agents** that delegate domain-specific tasks to specialist agents. For example, a travel planning agent might coordinate with separate hotel and event booking agents. We demonstrate this pattern in the [_XTravels_ sample](./xtravels-sample.md) application. ### Audit Logging From 34e3225b5380bc025972aac2f37b82bd72a9c599 Mon Sep 17 00:00:00 2001 From: D051920 Date: Wed, 30 Sep 2026 09:28:31 +0200 Subject: [PATCH 2/2] remove wrong part --- guides/ai/cap-agents.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/guides/ai/cap-agents.md b/guides/ai/cap-agents.md index dfbeaea23..ea3393186 100644 --- a/guides/ai/cap-agents.md +++ b/guides/ai/cap-agents.md @@ -68,20 +68,6 @@ 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. -> [!tip] Annotation Placement Matters -> The CDS compiler only recognizes annotations placed **before** the action keyword or in a separate `annotate` statement. Annotations placed **after** the `returns` clause are silently ignored: -> ```cds -> // ✅ Correct - annotation before action -> @agent.hitl -> action submitOrder(...) returns String; -> -> // ✅ Also correct - separate annotate statement (shown above) -> annotate CatalogService.submitOrder with @agent.hitl; -> -> // ❌ WRONG - silently ignored by CDS compiler -> action submitOrder(...) returns String @agent.hitl; -> ``` - > [!warning] Only supported by CAP Node.js > `@agent.hitl` is not yet supported by CAP Java