finAI — the coordination layer

01Overview and problem

A relationship adviser types an open-ended request: review this client's portfolio against current market conditions, say. In a multi-agent system that one sentence has to become a plan: which specialists to call, in what order, and with which client data.

Two things can go quietly wrong. A language model can misread the request and plan the wrong work, and the client's situation can change while the work is still running. My teammates built the specialist agents; I built the coordination layer in front of them, which decides what they are allowed to do. Deterministic rules govern authorisation, plan admission and execution. Optional model assistance can suggest a reading at the start and draft wording at the end, but it cannot override those controls.

02What I built, and where the team's work begins

I owned the Clarifier and Orchestrator coordination layer that sits between the adviser and the specialist agents. Within that layer I built the Clarifier, plan admission, the Orchestrator's runtime graph, one typed adapter per capability, the approval cards, the optional model layer with its synthesis guard, and the evaluation harness.

Everything behind the adapters belongs to my teammates: the specialist agents, the application-level graph and its database checkpointing, parallel execution and multi-need planning, the risk-acknowledgement cards, and the model factory with provider fallback. I integrated with these services. I didn't build them.

I directed much of the implementation through AI coding assistants. The design contracts, reviews and merge decisions were mine.

03Clarifier: interpreting the request

The Clarifier reads the adviser's message together with the session's context and produces a typed intent: a structured description of what is being asked, rather than free text. Rules do this first.

With the optional model layer switched on, the model can propose a reading too. One asymmetric rule validates it: the proposal may widen what gets coordinated, but never narrow it and never authorise anything. If the model fails or returns something invalid, the Clarifier returns the rules' reading.

04Orchestrator: deterministic task admission

Plans are not generated. Each intent maps to a fixed template; a product review always runs market research, then portfolio analysis, then investment, then risk. Before anything runs, the plan has to pass admission. Proposals can't choose endpoints or grant themselves permissions, and anything that fails admission doesn't run.

Admitted steps run in dependency order through typed adapters. A step whose prerequisite failed is skipped. A failed required step blocks the run; a failed optional step leaves it partial. The result is a typed status the adviser can read, never a silent gap.

05Approvals and changing client context

A product review waits for a confirmed approval card. Only the card's structured confirm action counts; a typed "yes" is never approval. Each card carries an ID, its issue time, a fingerprint of the client context and a digest of the objective, and it expires after 15 minutes.

A reused, expired, mismatched or tampered card is refused. If the client context has gone stale, nothing runs and a fresh card is issued, and any other turn withdraws a pending card. During execution, client context is re-read before each specialist call and after each result; if it moved, the result is withheld rather than replaced.

06Engineering decisions, safeguards and trade-offs

1. Fixed plans over model-generated plansMy layer

   Why

   Every run is predictable and reviewable, and the model never designs the workflow.

   Trade-off

   New kinds of request need new templates.

2. Rules first; the model is optional and may only widenMy layer

   Why

   The system works with the model switched off, and the model can't remove work or approve anything.

   Trade-off

   Rules need upkeep, and model mode is slower.

3. Structured confirmation, not conversational consentMy layer

   Why

   A typed "yes" can be ambiguous; a card action is explicit and single-use.

   Trade-off

   One extra step for the adviser.

4. Approvals bound to client stateMy layer

   Why

   The context fingerprint, objective digest and 15-minute expiry stop an approval being applied to a changed record or a different objective.

   Trade-off

   Stale cards must be re-issued.

5. Withhold, don't substituteMy layer

   Why

   If client context changes mid-run, showing nothing is safer than an answer built on old data.

   Trade-off

   Some runs end without a result.

6. Guarded synthesis within configured limitsMy layer

   Why

   The guard rejects model text that adds numbers, product IDs, tickers or links not in the evidence, names an internal agent, gives advice, or claims something was executed or approved. Each turn is capped by configuration at 3 model calls, US$0.01 and a 20-second timeout.

   Trade-off

   Some useful model wording is rejected.

07Testing and evaluation

I built an evaluation harness that runs end-to-end coordination scenarios. It checks the intent, the routing to specialists and the grounding of the response, using synthetic specialist responses, and compares the rules-only path with model-assisted interpretation alongside guardrail checks.

What it can't tell you: the scenario sets are small, I wrote the expected answers, and the specialists were synthetic. It describes coordination behaviour, not advice quality or production accuracy.

08Challenges and limitations

• A prototype: specialist providers run in test mode, with no production deployment or live-data acceptance.
• Market data comes from the newest saved research run, up to seven days old; the portfolio agent works with mock product candidates.
• In model mode, recent conversation text is sent to the external model provider. I identified this as a possible data-handling gap to close before any use with real client data.
• The evaluation is small-scale and self-labelled.

09Technologies and implementation

Python & FastAPI

Services for the coordination layer

LangGraph

The Orchestrator's runtime graph: load, admit, execute, finalise

Typed contracts

At every boundary: intents, plans, adapters and results

GPT-OSS-120B

Optional, via OpenRouter; off by default and never able to authorise

AI-assisted build

Implementation directed through coding assistants; design, review and merge decisions mine