classic-models-agent-platform/CLAUDE.md

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.

{ "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.

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.