feat: working orhcestration engine
This commit is contained in:
36
docs/adr/0001-the-execution-engine-takes-a-workflow.md
Normal file
36
docs/adr/0001-the-execution-engine-takes-a-workflow.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
status: accepted
|
||||
---
|
||||
|
||||
# The Execution engine takes a Workflow
|
||||
|
||||
The reference is one agent: its engine and its subject, cloud solution architecture, are the same code. About ten of its modules name its Deliverables directly, some forty-five times: the router knows that a failed validation reopens the infrastructure code, the submission tool knows which Deliverable gets a diagram. A second agent on a different subject cannot use it as it stands.
|
||||
|
||||
We decide that the Execution engine names no Deliverable, no Phase, no Cloud provider and no subject. Everything about a subject is one value, a **Workflow**, given to the engine when an agent is assembled. An agent is the Execution engine and one Workflow.
|
||||
|
||||
A Workflow supplies:
|
||||
|
||||
- its Phases, its Deliverables and their Dependencies, and the checks each submission must pass;
|
||||
- what code adds to a Deliverable when it is submitted;
|
||||
- which Deliverable is validation, how its result is read, and what a failure reopens;
|
||||
- the facts a user approves a Phase from;
|
||||
- any fan-out of one Deliverable's work to further agents;
|
||||
- its final Deliverable, and what it adds to an Execution's record and to a reply;
|
||||
- the roles it requires, its local tools and its reviews;
|
||||
- the catalogue its spec is read against, and the adapters that digest sources into one;
|
||||
- its own settings.
|
||||
|
||||
Accepted by the owner on 2026-10-13.
|
||||
|
||||
## Considered Options
|
||||
|
||||
- **Copy the reference and edit it for each new subject:** rejected. Every engine fix would be ported by hand to every copy.
|
||||
- **A plug-in registry the engine discovers Workflows from:** rejected. One agent has one Workflow; passing a value is enough, and it can be read.
|
||||
- **Subclassing the engine per subject:** rejected. The points that differ are data and a few functions, and inheritance would let a subject override what the Ledger guarantees.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The engine's tests need a subject. A toy Workflow of three Deliverables drives them.
|
||||
- The reference's own workflow is written as a Workflow in the engine's tests, to show the seam is wide enough for the case it came from. This shows nothing about results with real models.
|
||||
- A Workflow can run its own code at the points listed and nowhere else. A need that fits none of them is a change to this ADR.
|
||||
- Settings and paths that the reference resolves from its own repository are given by the agent.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
status: accepted
|
||||
---
|
||||
|
||||
# The engine is built from a reference that is never modified
|
||||
|
||||
The solution architecture agent works, and is still being developed: four of its iterations have open steps. We decide that the Execution engine is built in this repository from that agent as a **Reference**, and that no file of the Reference is changed in doing so.
|
||||
|
||||
- A module is brought across by `scripts/bring.py`: copied, with its imports renamed and nothing else changed.
|
||||
- `REFERENCE.lock.json` records, for every file brought, the Reference's commit and the hash of the file as it stood there.
|
||||
- A module is changed here only after it has been brought, in a later step, so the change is a diff against what was brought.
|
||||
- The Reference is never run by this repository's tests, and the tests read none of its files.
|
||||
|
||||
Accepted by the owner on 2026-10-13.
|
||||
|
||||
## Considered Options
|
||||
|
||||
- **Separate the engine inside the Reference, then take it from there:** rejected by the owner. It refactors working code that has other work open on it.
|
||||
- **Depend on the Reference as a package:** rejected. Its engine cannot be imported without its subject.
|
||||
|
||||
## Consequences
|
||||
|
||||
- There are two Execution engines: the Reference's own and this one. A fix made in one reaches the other only if someone carries it. The recorded hashes say which brought files the Reference has since changed.
|
||||
- Moving the Reference onto this engine is a separate decision and is not planned.
|
||||
- A test that a brought module depended on the Reference's own Skills, bundle or roles for is rewritten against stand-ins here, or waits for the step that brings what it needs.
|
||||
31
docs/adr/0003-one-orchestration-engine-above-the-agents.md
Normal file
31
docs/adr/0003-one-orchestration-engine-above-the-agents.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
status: proposed
|
||||
---
|
||||
|
||||
# One Orchestration engine above the agents
|
||||
|
||||
Every request for work is one of several kinds: an operating model, a solution architecture, both, or a question about work already delivered. Each kind belongs to an agent, and each agent is the Execution engine and one Workflow. The KAB platform does not route between agents; its workflows call one agent per step. Without something above the agents, every caller has to know which agent a request is for and talk to it directly, and "both" cannot be done at all.
|
||||
|
||||
We decide that **every request comes through one Orchestration engine**, a service of its own in this repository, beside the Execution engine package. It is an A2A agent: callers, the KAB platform among them, register and call it as they would any agent.
|
||||
|
||||
- **It decides which agent the work belongs to, and produces nothing itself.** No Deliverable, no Phase, no Approval of its own.
|
||||
- **It knows its agents by configuration**, a list of the kinds of work and the address of the agent that does each. Adding an agent is a line of configuration, not code.
|
||||
- **It dispatches the request unchanged.** The message and its metadata go to the chosen agent as they came, but for the field that named the work.
|
||||
- **It relays.** Every question and Approval the agent pauses for is passed to the caller, and every reply back, unchanged. It holds which agent's task each of its own tasks is waiting on.
|
||||
- **It does not guess.** In order: what the caller named settles it (`work`); with only one agent configured, that agent; otherwise it starts nothing and says how to name the work. Reading a request by Jev, with its confidence thresholds, is step F3 and is added to these rules, not in place of them.
|
||||
- **One Customer case across agents.** The same slug goes to each agent a request reaches.
|
||||
|
||||
Proposed 2026-10-20.
|
||||
|
||||
## Considered Options
|
||||
|
||||
- **Each caller calls the agents directly:** rejected. Every caller would carry the routing, and "both" (architecture, then the operating model from its files) would be built once per caller.
|
||||
- **Route in the KAB platform's workflows:** rejected. The platform calls one agent per step and cannot relay an agent's questions to a person; and decision 6 of the implementation plan keeps routing out of the platform.
|
||||
- **A router inside the Execution engine:** rejected. The engine holds one Execution of one Workflow (ADR-0001); choosing between agents is above any one Execution.
|
||||
|
||||
## Consequences
|
||||
|
||||
- The Orchestration engine is a fourth container beside the agents and is the only one registered with the KAB platform.
|
||||
- A caller that pauses for a person sees every agent's questions and Approvals through it. A caller that cannot answer, such as a platform workflow step, sends `pre_approved` as it would to the agent.
|
||||
- Its own tasks map to agents' tasks in memory. A restart loses tasks in flight; the agents keep their checkpoints.
|
||||
- While an agent works, it reports that it is still working at an interval, so a caller that treats a silent stream as dead does not retry and start a second Execution.
|
||||
Reference in New Issue
Block a user