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 | **none yet** — the agent says so when asked |
| Calls | nothing yet. `Approvisionnement.check_availability` comes with discontinuation decisions |
| Exposes | `describe_catalog` |

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.