Concepts

The harness is a spec-and-callback boundary. Python describes the agent topology with validated Pydantic models and provides callback handlers for tools and approvals; the Rust runtime (flowai-runtime) owns the loop, the plan lifecycle, approval gating, provider transport, and event streaming. Every public Python primitive is either a define_* helper that produces a frozen Pydantic spec or a helper that constructs prompts and schemas the runtime can consume.

Your Python application
    -> flowai_harness            (facade: validated specs + callbacks)
    -> flowai_harness._internal  (PyO3 extension)
    -> flowai-runtime            (Rust crate: the runtime)

The flowai_harness facade builds and validates specs, normalizes them to the camelCase wire shape, and threads handlers through flowai_harness._internal into the runtime. From that boundary down, everything runs in Rust.

Concept map

References and glimpses --> Tools --+
                          Prompts --+--> Agents --+
                            Plans --+             |
                                                  |
Tenant -------------------------------------------+--> RuntimeSpec
                                                          |
                                                          v
                                                    Runtime handle
                                                     |          |
                                                     v          v
                                          Streaming events   Approvals

• Tenant scopes runtime-owned state and catalog access.
• Agents define roles, routes, models, prompts, tools, and approval policy.
• Prompts provide deterministic system text; executable tools are registered separately.
• Plans give planners and executors a typed action contract.
• References and glimpses pass large or sensitive values through compact handles.
• Runtime validates the full topology and constructs the native handle that drives it.

Pages in this section

• Tenant — the runtime identity used for tenant isolation.
• Agents — coordinator, planner, executor, and specialist roles.
• Plans — typed plan schemas with tagged action unions.
• References & Glimpses — TTL-bounded handles and summary normalization.
• Tools — async handlers with input schemas and approval policies.
• Prompts — the layered prompt composer and how a prompt reaches the model.
• Runtime — building and driving the runtime handle.