feat: working orhcestration engine
This commit is contained in:
26
.agents/plans/iter-02-orchestration-engine/MAP.md
Normal file
26
.agents/plans/iter-02-orchestration-engine/MAP.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# Plan Map
|
||||
|
||||
**Iteration:** 2, the Orchestration engine
|
||||
**Intent:** The service every request comes through. It decides which agent the work belongs to, dispatches it, and relays every question and Approval. First behind it: the operating model agent (`../tom_analysis`).
|
||||
**Status:** F1 proposed; F2 and F4 built 2026-10-20
|
||||
|
||||
## Decided by the owner, 2026-10-20
|
||||
|
||||
- Two agents on the platform: the Orchestration engine, which routes each request to an agent, and the operating model agent behind it. The Orchestration engine is what callers use.
|
||||
- The solution architecture agent (`../solution_architecture_agent`) behind it too, its output passed to the operating model agent through the Orchestration engine (F4).
|
||||
|
||||
## Sources of truth
|
||||
|
||||
- `../tom_analysis/IMPLEMENTATION_PLAN.md`, sections 2 and 4, and steps F1 to F5 in section 10.
|
||||
- `docs/adr/0003-one-orchestration-engine-above-the-agents.md`.
|
||||
- `../tom_analysis/.agents/plans/iter-02-platform-deployment/`: how an agent runs on the local KAB platform.
|
||||
|
||||
## Status
|
||||
|
||||
| Step | What | Done when | Status |
|
||||
| --- | --- | --- | --- |
|
||||
| F1 | ADR-0003: one Orchestration engine above the agents | Accepted by the owner | proposed |
|
||||
| F2 | The service: an A2A server, a configured list of agents, a request passed through to one agent with every prompt relayed; its image; on the local platform | An Execution of the operating model agent runs through it, Approvals included, with the agent untouched | built (`steps/step-2.md`); the platform workflow through it is step 4 of `../tom_analysis` iteration 2 |
|
||||
| F3 | The decision: readings in code, the Jev question, thresholds, the fallbacks, the record | A labelled set of messages is routed correctly; low confidence asks; no Jev key still routes what is named | planned |
|
||||
| F4 | "Both": architecture, then its files as `sources` to the operating model agent | One request yields both sets of Deliverables under one Customer case | built against scripted agents (`steps/step-4.md`), ahead of F3 at the owner's request; not yet run with real models |
|
||||
| F5 | Later messages to the agent that owns the work | A change to the architecture is followed by a change to the operating model | planned |
|
||||
25
.agents/plans/iter-02-orchestration-engine/steps/step-2.md
Normal file
25
.agents/plans/iter-02-orchestration-engine/steps/step-2.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Step F2: the service
|
||||
|
||||
Built 2026-10-20.
|
||||
|
||||
## What was built
|
||||
|
||||
A package of its own, `orchestration/`, beside `execution_engine/`, run as `python -m orchestration.main`.
|
||||
|
||||
- **`agents.py`:** the agents it routes to, read from a YAML file (`AGENTS_FILE`): `work`, `url`, `description`. Two agents for one kind of work are refused by name.
|
||||
- **`routing.py`:** the rules of ADR-0003 without Jev. The `work` the caller named settles it; with one agent configured, that agent; otherwise nothing starts, and the reply says how to name the work and lists what can be named. Work no agent does is refused by name.
|
||||
- **`relay.py`:** each of its tasks stands for one task of one agent. The first message goes to the agent with its parts and metadata unchanged but for `work`; every status, question, Approval and file the agent sends comes back unchanged; a reply goes to the agent's waiting task. Agents are reached through the A2A SDK's client, from each agent's card, so the agent's own `/a2a` interface is called. While an agent works, a "still working" status is sent every `HEARTBEAT_SECONDS` (60): the Execution engine says nothing for the length of an Execution, and the KAB platform takes a stream silent for 20 minutes as dead and retries it, which would start a second Execution.
|
||||
- **`card.py`:** the card, and on its skill the KAB input contract: `work` as a choice of the configured agents, then the fields every Execution engine agent takes (`request`, `customer_case`, `scope`, `pre_approved`).
|
||||
- **`main.py`:** the server: `/health` (with the configured work), both card paths, and JSON-RPC at `/a2a` and at `/`.
|
||||
- **`Dockerfile.orchestration`** and `deploy/agents.local.yaml`, which routes `operating_model` to `http://tom-analysis:8080`. In the dev kit, `orchestration-engine` is in both personal compose files, on port 10030.
|
||||
|
||||
## What differed from the plan
|
||||
|
||||
- Tasks are held in memory, as the agent's own A2A tasks are. A restart loses the place of tasks in flight, and a reply to one is answered by saying so; the agents keep their checkpoints.
|
||||
- The step's "done when" names an architecture Execution. The owner chose the operating model agent as the first behind it; the architecture agent is a line in `agents.local.yaml` once it runs on the platform.
|
||||
|
||||
## Verified
|
||||
|
||||
- Eleven tests in `tests/orchestration/`. The relay runs in front of the real Execution engine on the toy Workflow, both in one process: a question, a text reply and an Approval relayed both ways, a pre-approved request completing with all four files, a request naming no work starting nothing, and a silent agent reported as still working (the test fails with the heartbeat at 10 seconds).
|
||||
- On the local platform, from the workers container to `http://orchestration-engine:8080` (its root, as the platform calls it): a request for `operating_model` reached the operating model agent at its `/a2a` interface, and its eight scoping questions came back with their structured prompt in 60 seconds.
|
||||
- 545 tests pass; `ruff` and `mypy` clean.
|
||||
25
.agents/plans/iter-02-orchestration-engine/steps/step-4.md
Normal file
25
.agents/plans/iter-02-orchestration-engine/steps/step-4.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Step F4: a sequence of agents
|
||||
|
||||
Built 2026-10-20, ahead of F3: the owner asked for the solution architecture agent's output to reach the operating model agent through the Orchestration engine.
|
||||
|
||||
## What was built
|
||||
|
||||
- **Sequences in configuration** (`agents.py`): `sequences: [{work, steps, description}]` beside `agents`. A step names a configured agent; a kind of work is an agent's or a sequence's, never both. `deploy/agents.local.yaml` has `solution_architecture`, `operating_model`, and `architecture_and_operating_model` of the two.
|
||||
- **Routing** (`routing.py`): a decision is the agents in the order they work. A sequence is named like any work.
|
||||
- **The relay** (`relay.py`): each task runs a plan, one agent or several. The first agent gets the request as it came. When an agent completes and another follows:
|
||||
- if its last word is a status other than `completed` (`completed_with_warnings`), nothing after it starts, and the caller is told what was not started (`{"status": "stopped", ...}`). The implementation plan asks for the user to be asked here; that waits for F3's disposition;
|
||||
- otherwise its files, by artifact name, go to the next agent as `sources`, with the Orchestration engine's own record, `execution.json`: `status`, `customer_case`, `execution_id` (the agent's task), `workflow_request`, `work`.
|
||||
- **What each agent is sent:** the first, every field but `work`. The ones after it, `customer_case`, `pre_approved` and `request` only, so the first agent's spec never reaches the second. A field for one agent goes under its work's name, such as `operating_model: {scope: ...}` for the operating model's own fields.
|
||||
- **Every agent's files reach the caller,** each artifact's metadata naming the work it is of.
|
||||
- **The request is the text** every agent is sent, when the caller gives `request`: a KAB step otherwise sends all its fields again as one JSON document.
|
||||
|
||||
## Verified
|
||||
|
||||
- Six tests in `tests/orchestration/test_sequence.py` against scripted agents: the sequence read from configuration and routed; the first agent's files and record reaching the second as `sources` with the right fields; a first agent ending with warnings starting nothing after it; the second agent's question relayed and answered. One more in `test_relay.py` for the request as text.
|
||||
- The operating model agent's real digest read the solution architecture agent's scripted files with this record (`../../../solution_architecture_agent/.agents/plans/iter-01-on-the-engine/steps/step-1.md`).
|
||||
- 552 tests pass; `ruff` and `mypy` clean.
|
||||
|
||||
## Not done
|
||||
|
||||
- No run with real models through the sequence.
|
||||
- A platform workflow step has no way to send a field nested under a work's name; the operating model's own fields reach it only from an A2A caller.
|
||||
Reference in New Issue
Block a user