Files
orchestration_engine/.agents/plans/iter-02-orchestration-engine/steps/step-2.md

2.9 KiB

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.