Skip to content

chore: link to capire #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Akatuoro wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

chore: link to capire #113

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 2 additions & 117 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,126 +6,11 @@

CDS plugin for building agents based on the [A2A](https://a2a-protocol.org) protocol.

## Requirements and Setup

We use the [@capire/bookshop](https://github.com/capire/bookshop) as a running sample hereinafter. Clone it and open it in VSCode as follows:
## Usage

```bash
git clone https://github.com/capire/bookshop
code bookshop
```
For detailed instructions about setup and usage, refer to the [official documentation](https://cap.cloud.sap/docs/guides/ai/cap-agents).

Within your project root run this to add the plugin:

```bash
npm add @cap-js/agents
```

Annotate the `CatalogService` with `@agent`:

```cds
// srv/cat-service.cds
...
annotate CatalogService with @agent;
```

Start your server with `cds watch` and note that the A2A protocol gets served:

```bash
[cds] - serving CatalogService {
at: [ ..., '/a2a/browse' ],
...
}
```

For local development, the plugin serves a chat preview at `http://localhost:4004/a2a/browse/preview/` and features a mock LLM.
To use a real LLM, simply bind your app to an existing instance of SAP AI Core and start your server in `hybrid` profile:

```bash
cds bind -2 <instance>
cds w --profile hybrid
```

See [SAP AI Core → Create a Service Instance](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-service-instance) for how to create an instance.

## Ways to Build Agents

Both approaches start from a CDS service annotated with `@agent` (as shown in [Requirements and Setup](#requirements-and-setup)). They differ only in how the agent's behaviour is defined.

### Agentify Existing CAP Services

With `@agent` alone, the plugin auto-generates tools from the service's entities and actions, creates a [ReAct agent](https://arxiv.org/abs/2210.03629) loop, and serves it as a remote agent — no code required.

```cds
@agent
service CatalogService {
entity Books as projection on my.Books;
action submitOrder(book: Books:ID, quantity: Integer) returns { stock: Integer };
}
```

### Markdown-Based Agents

To define an agent's identity, behaviour, and skills explicitly, add a sibling directory matching the slugified service name. When present, it replaces the default agentification: instead of the auto-generated ReAct agent, the plugin auto-builds the agent from the directory at startup — no JavaScript handler required.

```
srv/
├─ cat-service.cds
└─ catalog-agent/ ← matches the slugified service name
├─ AGENTS.md ← agent identity + behaviour
└─ skills/
└─ book-purchase/
└─ SKILL.md ← workflow + examples
```

`AGENTS.md` defines who the agent is. The frontmatter populates the agent card;
the body is the agent's system prompt:

```md
---
name: catalog-agent
version: "1.0.0"
description: >
Bookshop assistant for placing book orders on behalf of the user.
---

# Catalog Agent

## Identity

You are the **Catalog Agent**, a helpful assistant for the capire bookshop.
...
```

## Human-in-the-Loop

Annotate a CDS action with `@agent.hitl` to require human approval before the agent may execute it. 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.

```cds
// srv/cat-service.cds
...
annotate CatalogService.submitOrder with @agent.hitl;
```

## Configuration

The LLM used by an agent is configured via `cds.requires.llm`. You can provide a `kind` as with [any required service](https://cap.cloud.sap/docs/node.js/core-services#required-services).

```jsonc
"cds": {
"requires": {
"llm": {
"kind": "aicore",
"model": "anthropic--claude-4.6-sonnet"
}
}
}
```

| Kind | Description |
| -------- | --------------------------------------------------------------------- |
| `aicore` | The default for `production` and `hybrid`, connects to SAP AI Core |
| `mock` | The default for `development`, provides a mocked response when called |

## Advanced

Expand Down
Loading