> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `<path>.md`.

# 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.

```text
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

```text
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](/docs/concepts/tenant) — the runtime identity used for tenant isolation.
- [Agents](/docs/concepts/agents) — coordinator, planner, executor, and specialist roles.
- [Plans](/docs/concepts/plans) — typed plan schemas with tagged action unions.
- [References & Glimpses](/docs/concepts/references) — TTL-bounded handles and summary normalization.
- [Tools](/docs/concepts/tools) — async handlers with input schemas and approval policies.
- [Prompts](/docs/concepts/prompts) — the layered prompt composer and how a prompt reaches the model.
- [Runtime](/docs/concepts/runtime) — building and driving the runtime handle.