classic-models-agent-catalogue/README.md

# Catalogue

Product management agent for the Classic Models catalog domain. Serves a product
manager: what exists, how it is priced, whether it sells, what to discontinue.

Reached over **A2A**; reads data over **MCP** through the Kong gateways; thinks
through the **Kong AI gateway**. It is one MCP client among others, exactly as
LibreChat is — nothing under it changes to accommodate it.

## Running it

```bash
uv venv && uv pip install -e ".[dev]"
export CATALOGUE_CLIENT_SECRET=...        # Keycloak client secret, no default
export CATALOGUE_CA_BUNDLE=/path/to/sttlab-local-ca.crt
python -m catalogue_agent
```

Everything else has a working default in `config.py` and is overridable with
`CATALOGUE_`-prefixed variables.

```bash
curl localhost:8080/.well-known/agent-card.json

curl -X POST localhost:8080/ \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  -H "Authorization: Bearer $USER_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage",
       "params":{"message":{"messageId":"m1","role":"ROLE_USER",
                            "parts":[{"text":"How many product lines are there?"}]}}}'
```

**`A2A-Version: 1.0` is required.** Without it the SDK assumes 0.3 and answers
`VERSION_NOT_SUPPORTED`, which reads as a protocol error even though the request
is fine.

## How a turn works

```
A2A SendMessage  ──►  exchange the user's token, once per audience
                 ──►  build one MCP toolset per server, with that turn's tokens
                 ──►  PydanticAI runs the model through the Kong AI gateway
                 ──►  answer, toolsets dropped
```

The MCP client is built **per turn**. A token that outlives the turn it was
minted for is a token that can be replayed after the user's session ended, and
holding one long-lived connection would mean one long-lived token.

Several narrow tokens rather than one broad one: a token minted for
`mcp-catalog` is refused by the sales gateway, so a prompt injection that talks
the agent into reaching the wrong domain fails at Kong rather than succeeding
quietly.

## What it can and cannot do

| | |
|---|---|
| Reads | catalog (products, product lines), sales (read-only, to judge whether a product sells) |
| Writes | catalog: `create-product`, and only after the user confirms the exact record |
| Calls | nothing yet. `Approvisionnement.check_availability` comes with discontinuation decisions |
| Exposes | `describe_catalog` |

Who may write is decided by Kong, not by this agent. `ai-mcp-proxy` carries a
per-tool ACL — `create-product` allows the `admin` and `product_manager`
consumer groups — and the group comes from `realm_access.roles` in the end
user's own token. The filtering happens at **discovery**, not just at call time:

```
pm-user   catalog  ['create-product', 'get-product', 'list-products']
ro-user   catalog  ['get-product', 'list-products']
```

So a read-only user's turn has no write tool in it at all, and no prompt
injection can conjure one. The agent holds no standing write access of its own;
the system prompt's confirm-before-writing rule is a courtesy on top of that,
not the control.

Writing needs conversation history — the agent restates the record, the user
says yes, and "yes" only means something if the previous turn is still there.
History is kept in memory, keyed by A2A `contextId`, bounded, and never
persisted. More than one replica therefore needs sticky routing on `contextId`
or a shared store.

Skills are decision-shaped on purpose. An agent exposing a generic `query` has
become a data proxy and defeats the per-domain scoping the estate is built on,
so skills get added when another agent has a specific question — not in advance.

## Two Keycloak facts this depends on

Both measured against Keycloak 26.6, both costly to rediscover:

**`actor_token` is silently ignored.** Standard Token Exchange accepts it,
returns a valid token and emits no `act` claim — no error. Delegation cannot be
built on RFC 8693 `act`; the actor is identified by `azp`, which carries this
agent's client id while `sub` stays the human.

**The audience is requested as a scope.** `audience=mcp-catalog` returns
"Requested audience not available". `scope=openid mcp-catalog-audience` works.

## Library choices

Pinned to what was current on 2026-08-28, ranges below the next major so patch
fixes arrive but an upgrade stays deliberate.

**`a2a-sdk` rather than FastA2A.** The earlier design said FastA2A, on the
grounds that `Agent.to_a2a()` was going away in PydanticAI v2 — which has since
happened, so that argument no longer distinguishes them. This estate exists to
prove A2A interoperability across five runtimes, and the reference
implementation is the safer thing for four other stacks to interoperate with.

**`httpx2` rather than `httpx`.** PydanticAI deprecates httpx clients for
OpenAI-compatible providers and removes them in v3.

Notes on `a2a-sdk` 1.1 that are not guessable, all established against the
running library:

- `a2a.types` are protobuf messages, not pydantic models.
- Use `DefaultRequestHandlerV2`; `DefaultRequestHandler` speaks 0.3.
- JSON-RPC methods are `SendMessage`, `GetTask`… The 0.3 spelling
  (`message/send`) still works — `enable_v0_3_compat` is on.
- An executor must enqueue a `Task` before any status update when
  `context.current_task` is None.

## Not done yet

- **The Keycloak client does not exist.** `classic-models-agent-catalogue` has
  to be declared in `infra-keycloak/k8s/keycloak/configmap-realm.yaml`, with
  `mcp-catalog-audience` and `mcp-sales-audience` as optional scopes. Until then
  the exchange fails and the agent says so.
- Writes, and the A2A call to Approvisionnement.
- Deployment manifests — they belong in `classic-models-agent-platform` once a
  second agent shows what is actually shared.

## Deployment

```
ghcr.io/staillanibm/classic-models-agent-catalogue:v0.1.0
```

Built from the `Dockerfile` here — two stages, so the runtime image carries no
build toolchain; non-root, read-only root filesystem, all capabilities dropped.
The image is built and pushed by hand for now: this repo lives on gitea and
gitea Actions is not set up, so there is no pipeline to do it.

```
docker build -t ghcr.io/staillanibm/classic-models-agent-catalogue:vX.Y.Z .
docker push  ghcr.io/staillanibm/classic-models-agent-catalogue:vX.Y.Z
```

`k8s/` is what runs; `dev/` is the Flux plumbing that applies it. Three manual
applies close the loop once — nothing can watch `./dev` before the namespace and
the source that serves it exist:

```
kubectl apply -f k8s/namespace.yaml
kubectl apply -f dev/gitrepository.yaml
kubectl apply -f dev/bootstrap-kustomization.yaml
```

After that every file here reconciles from git, `dev/` included. Never
`kubectl apply` the objects under `k8s/` afterwards — Flux reverts them within
its interval and the cluster silently stops matching what you edited.

What the deployment assumes:

| | |
|---|---|
| Namespace | `agents` — one for the estate; what isolates an agent is its Keycloak client, not its namespace |
| Secret | `CATALOGUE_CLIENT_SECRET`, from the same Vault entry the realm import reads, through the `vault-keycloak` store |
| CA | `k8s/ca-configmap.yaml` holds the lab CA **certificate** — public by construction, checked in so the deployment has no hidden prerequisite. Regenerate it when the CA rotates (expires 2026-11-24) |
| DNS | every `*.sttlab.local` name resolves in-cluster already; no `hostAliases` needed |
| Replicas | exactly one. Conversation history lives in the process, so a second replica would route a user's "yes" to a pod that never saw the question |