Add implementation instructions
Design agreed in discussion, nothing built yet. Records the agent's role, its scopes and MCP servers, its A2A surface, and the framework choice with its reason — so the next session starts from the decisions rather than re-deriving them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Stéphane Tailland
@@ -0,0 +1,180 @@
|
||||
# classic-models-agent-platform
|
||||
|
||||
Shared ground for the classic-models agent estate: templates, conventions, and
|
||||
the identity plumbing every agent repeats. Plays the role `kong-k8s-platform`
|
||||
plays for the gateways.
|
||||
|
||||
**Nothing runs from this repo.** It holds the `${VAR}`-parameterised manifests a
|
||||
domain's Flux `Kustomization` builds, plus the reference documentation below.
|
||||
|
||||
## The estate this plugs into
|
||||
|
||||
The agents replace LibreChat as the MCP client and orchestrator. Everything
|
||||
below them already exists and does not change: Kong gateways per domain, MCP
|
||||
servers served by Kong's `ai-mcp-proxy`, Keycloak, and the domain APIs.
|
||||
|
||||
| Agent | Repo | Framework | Mode |
|
||||
|---|---|---|---|
|
||||
| Assistant | `classic-models-agent-assistant` | LangGraph | conversational |
|
||||
| Ventes | `classic-models-agent-ventes` | CrewAI | conversational |
|
||||
| Catalogue | `classic-models-agent-catalogue` | PydanticAI + FastA2A | conversational |
|
||||
| Support | `classic-models-agent-support` | Google ADK | conversational |
|
||||
| Approvisionnement | `classic-models-agent-flows` | n8n | autonomous |
|
||||
| Recouvrement | `classic-models-agent-flows` | n8n | autonomous |
|
||||
|
||||
Five runtimes is deliberate. The point is proving A2A interoperability between
|
||||
stacks that do not know each other; a single framework would prove nothing.
|
||||
|
||||
## Topology
|
||||
|
||||
A2A between agents, MCP between an agent and data.
|
||||
|
||||
```
|
||||
Assistant ──→ every agent (orchestration; holds no scopes itself)
|
||||
Ventes ──→ Approvisionnement, Recouvrement
|
||||
Support ──→ Ventes
|
||||
Catalogue ──→ Approvisionnement
|
||||
```
|
||||
|
||||
**An A2A call returns an answer, not data.** Ventes asks Approvisionnement "can
|
||||
I promise delivery on 15 March?" and receives yes/no — it never gains read
|
||||
access to the catalog domain. Agent Cards therefore expose narrow,
|
||||
decision-shaped skills (`check_availability`, `check_creditworthiness`), never a
|
||||
generic `query`. An agent that exposes "ask me anything about my domain" has
|
||||
become a data proxy and defeats the scoping.
|
||||
|
||||
The Assistant holds **no scopes at all**. It is the component that sees raw user
|
||||
text, so it is the prompt-injection target, and it must be unable to exfiltrate
|
||||
anything.
|
||||
|
||||
## Identity
|
||||
|
||||
Each agent is its own Keycloak client. That is what makes the actor
|
||||
identifiable: the exchanged token carries `azp` = the agent's client id
|
||||
alongside `sub` = the end user.
|
||||
|
||||
```json
|
||||
{ "sub": "alice", "azp": "classic-models-agent-ventes",
|
||||
"aud": ["mcp-catalog"], "scope": "openid profile email mcp-catalog-audience" }
|
||||
```
|
||||
|
||||
Two measured facts that constrain the implementation:
|
||||
|
||||
**`actor_token` is silently ignored.** Keycloak 26.6's Standard Token Exchange
|
||||
accepts the parameter, returns a valid token, and emits **no `act` claim**. No
|
||||
error. Do not build delegation on RFC 8693 `act` — use `azp`.
|
||||
|
||||
**The audience is requested via a scope, not the `audience` parameter.** Passing
|
||||
`audience=mcp-catalog` returns `Requested audience not available`. Pass
|
||||
`scope=openid mcp-catalog-audience`.
|
||||
|
||||
### The exchange
|
||||
|
||||
Do what LibreChat already does — a POST per target audience, roughly twenty
|
||||
lines. Do not build a sidecar or move the exchange into Kong; both were
|
||||
considered and rejected as over-engineering, the second also because it would
|
||||
leave the agent holding one broad token instead of several narrow ones.
|
||||
|
||||
```
|
||||
POST https://keycloak.sttlab.local/realms/classic-models/protocol/openid-connect/token
|
||||
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
|
||||
client_id=<the agent's client id>
|
||||
client_secret=<from the agent's Secret>
|
||||
subject_token=<the end user's access token>
|
||||
subject_token_type=urn:ietf:params:oauth:token-type:access_token
|
||||
scope=openid mcp-<domain>-audience
|
||||
```
|
||||
|
||||
Neither LangGraph nor CrewAI injects a per-call MCP token natively
|
||||
(langchain-mcp-adapters issues #172/#194/#235; CrewAI's `MCPServerAdapter` fixes
|
||||
headers at construction). This is a non-issue: build the MCP client **once per
|
||||
conversation turn** with freshly exchanged tokens. A turn lasts seconds, an
|
||||
access token five minutes.
|
||||
|
||||
## Endpoints
|
||||
|
||||
MCP servers, one per domain, served by Kong:
|
||||
|
||||
| Domain | URL | Audience scope |
|
||||
|---|---|---|
|
||||
| catalog | `https://catalog-dev.sttlab.local/catalog-mcp` | `mcp-catalog-audience` |
|
||||
| customers | `https://customers-dev.sttlab.local/customers-mcp` | `mcp-customers-audience` |
|
||||
| payments | `https://payments-dev.sttlab.local/payments-mcp` | `mcp-payments-audience` |
|
||||
| sales | `https://sales-dev.sttlab.local/sales-mcp` | `mcp-sales-audience` |
|
||||
| workforce | `https://workforce-dev.sttlab.local/workforce-mcp` | `mcp-workforce-audience` |
|
||||
|
||||
LLM inference goes through the Kong AI gateway, never direct to a provider:
|
||||
|
||||
```
|
||||
https://llm-dev.sttlab.local/llm/v1/chat/completions
|
||||
```
|
||||
|
||||
It applies rate limiting, prompt guards and semantic guards, and routes to
|
||||
OpenRouter. Sending inference anywhere else bypasses all of them.
|
||||
|
||||
These hostnames are lab-only with a self-signed certificate. `/etc/hosts`:
|
||||
|
||||
```
|
||||
192.168.139.103 catalog-dev.sttlab.local
|
||||
192.168.139.105 llm-dev.sttlab.local
|
||||
192.168.139.106 customers-dev.sttlab.local
|
||||
192.168.139.107 payments-dev.sttlab.local
|
||||
192.168.139.108 sales-dev.sttlab.local
|
||||
192.168.139.109 workforce-dev.sttlab.local
|
||||
192.168.139.101 keycloak.sttlab.local
|
||||
```
|
||||
|
||||
The CA is `sttlab-local-ca` (cert-manager ClusterIssuer). Trust that one CA
|
||||
rather than disabling verification.
|
||||
|
||||
## Adding an agent
|
||||
|
||||
An agent is a declaration first. Put it here, let the generator produce the rest
|
||||
— the Keycloak client is generated from this, never hand-written in the agent's
|
||||
own repo, so the realm stays the single source of truth.
|
||||
|
||||
```yaml
|
||||
name: ventes
|
||||
client_id: classic-models-agent-ventes
|
||||
framework: crewai
|
||||
surfaces: [conversational]
|
||||
mcp_servers: [catalog, sales]
|
||||
scopes: [catalog:read, sales:read, sales:write]
|
||||
a2a_calls: [approvisionnement, recouvrement]
|
||||
limits:
|
||||
max_tool_calls_per_run: 20
|
||||
max_records_read_per_run: 500
|
||||
```
|
||||
|
||||
`scopes` becomes the client's `optionalClientScopes`; `mcp_servers` becomes the
|
||||
audience scopes it may request; `a2a_calls` becomes the A2A authorisations.
|
||||
|
||||
The realm actually deployed is `infra-keycloak/k8s/keycloak/configmap-realm.yaml`
|
||||
— note that `kong-v2/classic-models-realm.yaml` is an older partial copy and is
|
||||
**not** authoritative.
|
||||
|
||||
## Known blockers
|
||||
|
||||
**Konnect is not persisting configuration.** The operator loops on the same
|
||||
objects without converging and the dataplanes stay behind the control plane, so
|
||||
no new Kong config reaches the gateways — including any new agent audience.
|
||||
Resolve this before expecting an end-to-end run.
|
||||
|
||||
**No `employeeNumber` in tokens.** Sales territory scoping (a rep sees their
|
||||
territory, a manager sees all) resolves through
|
||||
`employee → officeCode → offices.territory`, but the token carries no employee
|
||||
identity, so the API cannot filter server-side. The realm's users
|
||||
(`admin-user`, `pm-user`, …) are role placeholders, not real employees.
|
||||
|
||||
**The `kong-token-exchange-broker` secret does not match the realm** — its
|
||||
`client_credentials` returns `unauthorized_client`.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Deliverables in English: code, comments, READMEs, Agent Cards. Conversation
|
||||
with the maintainer is in French.
|
||||
- GitOps throughout. Never `kubectl apply` an object carrying
|
||||
`kustomize.toolkit.fluxcd.io/name` — Flux reverts it within its interval, and
|
||||
tests run against config that no longer exists.
|
||||
- Secrets never committed. Follow the `secret.example.yaml` pattern used by the
|
||||
`infra-*` repos.
|
||||
Reference in New Issue
Block a user