Harness

A bare Agent is just a model loop. The harness is the set of opt-in primitives you compose onto it to give it richer capabilities — context assembly, persistent knowledge, sub-task spawning, and the supporting middleware they wire in.

This page is the configuration reference for those primitives. For the conversational entry point (agent.ask(), tools, HITL, observing events), see Agent Communication.

Constructor #

The loop-related parameters (config, tools, middleware, observers, prompt, …) are covered in Agent Communication and the parameter-specific guides. The harness hooks are assembly=, knowledge=, and tasks=, each documented below.

assembly= — context policies #

A list of AssemblyPolicy instances. When non-empty, the Agent wires an internal AssemblerMiddleware at the outermost position of the middleware chain so your policies transform (prompts, events) before every LLM call.

Order matters — see the ordering rule in the assembly doc. AssemblerMiddleware.validate_order() will flag known problematic compositions.

knowledge= — KnowledgeConfig #

Groups everything that involves the KnowledgeStore: the store itself, optional bootstrap, and optional compaction + aggregation strategies.

The compaction and aggregation middleware are opt-in per field: passing compact= without compact_trigger= still works (a default CompactTrigger() with all thresholds disabled is used). Omit a strategy entirely and the corresponding middleware is not wired.

tasks= — TaskConfig #

Sub-task delegation is off by default — a bare Agent has no run_subtask / run_subtasks tools. Pass tasks=TaskConfig(...) to opt in, and the Agent will auto-inject the pair of sub-task tools that let the LLM spawn isolated child Agents to handle self-contained work. TaskConfig configures how those children are built.

By default a sub-task Agent inherits all of the parent's user-supplied tools. Sub-tasks are themselves constructed with tasks=False (the Agent default), so they have no run_subtask / run_subtasks tools — recursive delegation is structurally impossible and no depth limit is needed.

tasks=False — the default #

tasks=False is the Agent default, so a bare Agent never spawns children. You only need to pass it explicitly to be self-documenting; otherwise just omit tasks= entirely.

run_subtask / run_subtasks — auto-injected tools #

When you opt in via tasks=TaskConfig(...), the Agent exposes two tools to the LLM:

• run_subtask(task: str) — spawn one sub-task Agent. Useful when the LLM has a single self-contained piece of work to delegate.
• run_subtasks(tasks: list[str], parallel: bool = True) — spawn multiple sub-tasks in one tool call. Defaults to running them concurrently with asyncio.gather; pass parallel=False only when later tasks depend on earlier results.

The LLM is told (via the tool descriptions) that it can call run_subtask multiple times in parallel within a single response, and that run_subtasks is the deliberate fan-out form. Each child gets a fresh MemoryStream and the parent's tools (filtered by TaskConfig).

For a more explicit, named delegate where the parent LLM sees a tool like task_researcher instead of generic run_subtask, use Agent.as_tool(). The two patterns can coexist: a coordinator can have both auto-injected sub-tasks and a named task_researcher tool.

See Task Delegation for the full sub-task delegation guide — context flow and custom streams for self-delegation via as_tool().

Agent.as_tool() #

Expose any Agent as a FunctionTool so another Agent can invoke it like any other tool:

as_tool() returns a FunctionTool named task_{child.name} that accepts an objective parameter and forwards it into the child's stream. See Task Delegation for sub-task streams, depth limiting, and stream factories.

Turn lifecycle #

Each await agent.ask(...) runs through the middleware chain in this order (outermost → innermost):

1. AssemblerMiddleware              (if assembly=[...])
2. _HaltCheckMiddleware             (if assembly=[...] — watches for HaltEvent)
3. _CompactionMiddleware            (if knowledge.compact configured)
4. _AggregationMiddleware           (if knowledge.aggregate configured)
5. User-provided middleware         (retry, rate-limit, logging, …)
6. LLM client                       (innermost)

The internal harness middleware (_AssemblerMiddleware, _HaltCheckMiddleware, _CompactionMiddleware, _AggregationMiddleware) are assembled conditionally — you only pay for what you turn on.

Lifecycle events emitted during a turn include ObserverStarted / ObserverCompleted, CompactionCompleted, AggregationCompleted, and HaltEvent. Subscribe to any of them via an Observer or a stream subscriber.

Back to top