agents package

Reviewed against commit 8a2cb42ad on 2026-10-23.

Reference: package page (78 modules, 27,430 lines) · subpackages volks (50 modules) and swarm (3 modules) · key modules: volk_registry, runtime, task_executor, kernel_handler, tool_registry, volks/base. How the package fits the whole system is in the overview; the team of volks is described on the volks page.

The story

orchestrata_ultimate.agents is the Multi-Agent Runtime for Orchestrata — the place where the abstract idea of "a team of AI agents building software" becomes running code. The rest of the system produces intents, routes messages, and enforces policy; this package is what those intents ultimately land on. It exists to solve two problems at once: managing a fleet of agent processes safely (spawning, pooling, coordinating, and terminating "Volk" instances under constitutional constraints), and giving each agent an actual brain (an LLM-backed persona with tools, memory, and a role in the delivery pipeline). Per the package docstring, it provides Volk lifecycle management, task execution, pool management, multi-Volk coordination, and integration with the Intent Broker, Postman, CXP, and the DI container.

The runtime half reads like classic infrastructure. types.py defines the shared vocabulary (TaskDefinition, TaskResult, VolkInstance, pool configs and status enums); VolkRuntime spawns and terminates instances with every decision checked through MultiagentPrologBridge, the Python facade over the multiagent.pl governance rules; VolkPool keeps per-alias instance pools with auto-scaling and load-aware selection; and TaskExecutor ties it all together — governed task assignment, instance acquisition, execution tracking, and result collection, with state persisted in Redis. Above that, VolkCoordinator implements multi-volk patterns (leader election, consensus, fan-out, pipeline), while hierarchy.py, communication.py, escalation.py, and lifecycle.py enforce the parent-child agent tree, CXP-based inter-agent messaging within its boundaries, and escalation of failures upward with context preserved.

A task typically enters through one of three doors. The IntentTaskAdapter converts Intent Broker intents into TaskDefinitions and hands back dispatch results. The VolkPostmanAdapter dequeues CXP packets delivered by Postman, converts them to tasks, and acknowledges delivery after execution. And for the out-of-process deployment, runtime_main.py boots the agent-runtime CXP server whose per-packet handler — built by build_kernel_packet_handler() in kernel_handler.py — stands up a kernel PipelineRunner over all the volks so live CXP traffic drives the volk engine directly. (Until 2026-08 this server ran on grpcio; grpcio was retired on 2026-08-07 and the cxpt direct transport replaced it, though the port environment keys still carry the GRPC name.) Whichever door is used, work flows through the same governed executor-and-pool machinery.

The brain half lives in volks/. BaseAgent (a Pydantic model) is the base class of every volk: identity, validation, serialization, memory recall via memory_context.py, a shared team persona from persona.py, and the LLM call paths — including _call_llm_with_tools(), which drives the function-calling loop against the schemas and sandboxed executors in tool_registry.py. On top of it sit the concrete agents that form the delivery pipeline: Concierge (U:Cx) → Analyst (U:BA) → PM → UX → Architect (U:Ar) → CodeDirector (U:Cd, delegating to Junior volks over CXP and optionally fanning out via the swarm/ subpackage) → QA (U:Qa) → Compliance (U:Cp, deterministic RTM checking with no LLM) → Documentor (U:Do), with Senior Dev (U:SD) as an oscillation-recovery specialist. Neighboring packages appear exactly where you would expect: cxp supplies the packet format everywhere agents talk to each other, postman and kernel deliver and orchestrate that traffic, llm/providers back the brains, drivers back code generation, knowledge_graph stores design context, and core supplies config, tracing, and the Redis/Prolog plumbing.

Key responsibilities

• Volk lifecycle — spawn, terminate, force-terminate, and health-track live agent instances (VolkRuntime), every transition gated by a Prolog governance check and persisted to Redis.
• Pooling & auto-scaling — per-alias instance pools with min/max limits, idle timeouts, and load-aware acquire/release/scale_to (VolkPool).
• Governed task execution — assign tasks to agents only when the multiagent.pl rules permit, run them, and collect TaskResults (TaskExecutor).
• Multi-volk coordination — leader election, consensus, fan-out, and pipeline patterns composed on top of the executor (VolkCoordinator).
• Logic-programming governance — a single Python facade over the multiagent.pl rule set answering every who-may-do-what question (MultiagentPrologBridge).
• Agent brains — a Pydantic BaseAgent giving every volk identity, memory recall, a shared team persona, CXP messaging, and an LLM function-calling loop wired to tool_registry.py.
• The delivery team — eleven concrete volks (Concierge → Analyst → PM → UX → Architect → CodeDirector → QA → Compliance → Documentor, plus Junior and Senior Dev) that turn a user request into reviewed, documented, traced code.
• Parallel code generation — SwarmCoordinator fans N files across N concurrent codegen tasks in isolated workspaces and merges the results.
• Entry adapters & live service — intent, Postman, and CXP adapters plus the out-of-process agent-runtime CXP handler feed work into the same governed machinery.

Class diagram

Runtime core

The infrastructure spine. VolkRuntime owns the live instances; VolkPool scales them per alias; TaskExecutor is the seam where a TaskDefinition meets an agent; VolkCoordinator composes many executions into coordination patterns; and every one of them routes its authorization questions through MultiagentPrologBridge, the facade over multiagent.pl (render-verified):

Runtime data model

The shared vocabulary from types.py that every module above speaks — the task lifecycle (TaskDefinition/TaskResult), the live-instance record (VolkInstance), pool config/status, the consensus result, and the two lifecycle enums (render-verified):

The volk brain and team

BaseAgent is the Pydantic trunk every concrete volk inherits — carrying identity, status, artifacts, the Postman/KG handles, and the CXP process/send/emit_event surface. The eleven concrete volks form Orchestrata's delivery pipeline; CodeDirectorVolk additionally delegates to JuniorVolk over CXP and fans out through SwarmCoordinator (render-verified):

Full inheritance overview

Inheritance across the whole package — every volk descends from the Pydantic BaseAgent, the QA volk is assembled from capability mixins, and the exception tree roots at VolkRuntimeError (render-verified, do not edit):

Module dependency diagram

Internal module imports within orchestrata_ultimate.agents (generated from the AST, render-verified):

Module inventory

The runtime core — types.py, runtime.py, pool.py, task_executor.py

Everything else in the package speaks the vocabulary defined in types.py: TaskDefinition and TaskResult describe the task lifecycle, VolkInstance tracks a live agent, and PoolConfig/PoolStatus/ConsensusResult plus the TaskStatus/InstanceStatus/CoordinationPattern enums round out the model. VolkRuntime in runtime.py is the component that actually spawns and terminates instances — each spawn passes a Prolog governance check and lands its state in Redis. VolkPool sits on top, maintaining per-alias pools with min/max limits, auto-scaling, idle timeouts, and load-aware selection, so callers never touch raw instances. TaskExecutor is the seam where a task meets an agent: it asks the Prolog bridge whether the assignment is permitted, acquires an instance from the pool, tracks execution, and collects the result — converting the TaskDefinition into a CXPPacket along the way. AgentRuntime and AgentPool survive as compatibility aliases.

Coordination and governance — coordinator.py and prolog_bridge.py

When one volk is not enough, VolkCoordinator composes many of them on top of TaskExecutor, implementing the multi-volk patterns — leader election, consensus, fan-out, and pipeline. None of these decisions are made in Python alone: MultiagentPrologBridge exposes the multiagent.pl rule set (lifecycle governance, task assignment, coordination patterns, health monitoring, recovery) so the runtime's who-may-do-what questions are answered by the same logic-programming governance layer the rest of Orchestrata uses. The dependency diagram makes this visible — runtime, pool, task_executor, coordinator, hierarchy, communication, escalation, and constraints all import prolog_bridge.

The agent brain — volks/base.py and tool_registry.py

BaseAgent is the Pydantic base class every volk inherits, and it carries the shared machinery: identity and validation, serialization, the team-persona preamble from persona.py, run-scoped memory recall via memory_context.py, and the LLM call paths. The most interesting of those is _call_llm_with_tools(), which runs the function-calling loop: tool_registry.py supplies the OpenAI/DeepSeek tool schemas and a thread-safe executor mapping tool names to sandboxed Python functions — file operations, Mermaid validation, governed web research, and cloud design-pattern lookups. Because both the schemas and the execution live here, adding a capability to every volk means editing one module, not eleven.

The volk team — volks/

The concrete agents form Orchestrata's delivery pipeline: Concierge (U:Cx) receives the user, Analyst (U:BA) turns intent into user stories and requirements, PM (U:PM) validates scope and estimates effort (and owns the goal registry and completion reports), UX (U:Ux) produces UI design artifacts, Architect (U:Ar) writes the design with KG-backed context, CodeDirector (U:Cd) turns design into code — delegating to Junior volks over CXP and choosing among skeleton, serial, and swarm generation paths — QA (U:Qa) generates and runs tests with autofix and dependency-install mixins, Compliance (U:Cp) does deterministic design-vs-code checking and RTM generation from @traces with no LLM at all, and Documentor (U:Do) writes the docs. Senior Dev (U:SD) is the escape hatch: when the pipeline oscillates, it reads recent iteration conversations, identifies the root cause, and rewrites the Concierge prompt with constraints. The class diagram shows the shape clearly — one BaseAgent trunk, with QaVolk assembled from four capability mixins and ArchitectVolk from its context and project mixins.

Parallel code generation — swarm/coordinator.py

SwarmCoordinator is CodeDirector's throughput lever: it fans N source files out across N concurrent asyncio tasks, each running an async codegen driver in an isolated temporary workspace, then atomically merges the results back into the project. Per-file outcomes come back as ShardResults, so a single failed shard degrades gracefully instead of poisoning the batch.

The live CXP service — kernel_handler.py and runtime_main.py

For the out-of-process deployment, runtime_main.py is the entry point of the agent-runtime service speaking the CXP protocol (the cxpt direct transport since 2026-08-07; the section was headed "gRPC" while grpcio was in use). Its per-packet handler is constructed by build_kernel_packet_handler() in kernel_handler.py, which boots a kernel PipelineRunner wired with all the volks — so a CXP packet arriving over the wire flows straight into the same volk engine that the in-process pipeline uses.

Class map (generated)

Generated from the live source AST by scripts/gen-module-class-diagrams.py — do not hand-edit. Abstract classes have a green border; members listed are those defined on the class itself (inherited members excluded). Solid empty-triangle arrows = in-package inheritance; dashed arrows into dashed boxes = external/stdlib/cross-package bases; filled diamond = composition (constructed in __init__); open diamond = aggregation (annotated/injected reference); diamond edge labels name the owning attribute.