# Assistant — the orchestrating agent

The single entry point for users. Understands a request, consults the
specialists that can settle it, and composes one answer.

**Framework:** LangGraph · **Mode:** conversational · **Client id:**
`classic-models-agent-assistant`

## It holds nothing, and that is enforced by the realm

This is the component that sees raw user text, so it is the prompt-injection
target. It has no MCP server, no domain scope, and no data of its own. That is
not a convention in the prompt — it is what the realm grants:

```
OBTAINED  classic-models-agent-catalogue-audience   aud=[classic-models-agent-catalogue]
refused   mcp-catalog-audience     → Invalid scopes
refused   mcp-sales-audience       → Invalid scopes
refused   catalog-api-audience     → Invalid scopes
```

An injection that succeeds against this agent finds no path to a domain,
because there is none to find. Its two optional scopes are one specialist and
the inference endpoint — inference is not a domain, and the agent has to reason.

Adding a specialist is an entry in `specialists.py` plus an audience scope
granted in the realm. Add the entry without the grant and every call to it fails
at the token exchange with `Invalid scopes`, loudly, before any data moves.

## The chain

Four hops, `sub` unchanged throughout — which is what makes the end user's own
roles apply at the far end:

```
1. user          sub=pm-user  azp=librechat                        aud=[…-agent-assistant]
2. assistant→cat sub=pm-user  azp=classic-models-agent-assistant   aud=[…-agent-catalogue]
3. cat→mcp       sub=pm-user  azp=classic-models-agent-catalogue   aud=[mcp-catalog, token-exchange-broker]
4. MCP call                                                        → 200
```

`azp` names the last agent in the chain, not the first. Keycloak accepts
`actor_token` and emits no `act` claim, so an orchestrator's identity does not
survive a second exchange — the delegation is visible in the traces, not in the
token.

## What it does with an answer

A specialist returns an answer, never data. The orchestrator composes; it does
not aggregate records it was not given.

Two behaviours worth naming, both verified end to end:

- **Out of remit → it says so.** Asked for a company-wide revenue figure, it
  reports that no specialist can settle it rather than answering from what the
  model knows. An invented answer is indistinguishable from one the estate gave.
- **A held write is relayed verbatim.** Catalogue parks a proposed write in
  `input-required`; this agent passes that message through unchanged and stops.
  The user's `approve` comes back through the same conversation and reaches the
  specialist, which owns the decision. The orchestrator never approves on
  anyone's behalf.

## The graph

`plan → delegate → plan → …` until the model stops calling tools. One tool per
specialist, described by what it *decides*. Delegations in the same step run
concurrently — that is the point of fanning out at all — and are capped by
`ASSISTANT_MAX_DELEGATIONS` (8), counted in calls rather than model turns,
because one specialist consulted twice for the same question is the loop worth
catching.

The graph is rebuilt per turn: its tools carry the user's token, and a graph
held across turns would be a token held across turns.

## Running it

```
uv venv && uv pip install -e '.[dev]'
ASSISTANT_CLIENT_SECRET=… ASSISTANT_CA_BUNDLE=… \
  ASSISTANT_URL_CATALOGUE=http://localhost:8099/ \
  python -m assistant_agent
```

`ASSISTANT_URL_<NAME>` overrides a specialist's address, for running outside the
cluster against a port-forward. In the cluster nothing sets it.

macOS resolves every `.local` name through mDNS before falling back to
`/etc/hosts`, at a flat ~5s per host. `ASSISTANT_HTTP_TIMEOUT` defaults to 60s
for that reason; in the cluster the names resolve instantly.

## Deployment

```
gitea.sttlab.eu/stt/classic-models-agent-assistant:v0.2.1
```

`k8s/` is what runs, `dev/` is the Flux plumbing. Two manual applies close the
loop once — the `agents` namespace and the `sttlab-ca` ConfigMap already exist,
created by the catalogue agent's repo, and are deliberately not declared here so
two Kustomizations do not fight over pruning them.

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

`replicas: 1` is a constraint: conversation history lives in the process, and a
specialist's approval round trip passes back through here.