`run_architecture` / `resolve_architecture`

Two helper functions exposed at the top level of loomflow for working with architectures outside of an Agent.


from loomflow.architecture import resolve_architecture
from loomflow.team import run_architecture

`run_architecture`


async def run_architecture(
    architecture: Architecture,
    prompt: str,
    *,
    model: Model | str,
    user_id: str | None = None,
    session_id: str | None = None,
    metadata: Mapping[str, Any] | None = None,
    extra_tools: list[Tool] | None = None,
    output_schema: type[BaseModel] | None = None,
    output_validation_retries: int = 1,
    # additional Agent kwargs accepted ...
) -> RunResult: ...

Build a minimal Agent shell around any Architecture instance and run it. Useful for testing orchestrators in isolation without wiring a full Agent yourself.

Parameter	Type	Default	Description
`architecture`	`Architecture`	required	The orchestrator to test.
`prompt`	`str`	required	The user message.
`model`	`Model \| str`	required	The model the architecture’s `Dependencies` will see.
`user_id`	`str \| None`	`None`	Forwarded to the run context.
`session_id`	`str \| None`	`None`	Forwarded to the run context.
`metadata`	`Mapping[str, Any] \| None`	`None`	Forwarded to the run context.
`extra_tools`	`list[Tool] \| None`	`None`	Tools added to the architecture’s `Dependencies.tools` for this run.
`output_schema`	`type[BaseModel] \| None`	`None`	Optional Pydantic model for structured output.
`output_validation_retries`	`int`	`1`	Retry budget for `OutputValidationError`.

Additional Agent constructor kwargs (memory, runtime, budget, permissions, hooks, telemetry, audit_log, max_turns, auto_consolidate, retry_policy, auto_extract, approval_handler, secrets, skills) are accepted and forwarded.

Returns, RunResult. Same shape as agent.run().

Example. Testing a Supervisor in isolation


import pytest
from loomflow import Agent, ScriptedModel, ScriptedTurn
from loomflow.architecture import Supervisor
from loomflow.team import run_architecture
 
@pytest.mark.anyio
async def test_supervisor_delegates_to_writer():
    writer = Agent(
        "Write the answer.",
        model=ScriptedModel(turns=[ScriptedTurn(text="Hello world.")]),
    )
    supervisor_model = ScriptedModel(turns=[
        ScriptedTurn(tool_calls=[("delegate", {"worker": "writer", "instructions": "..."})]),
        ScriptedTurn(text="Here you go: Hello world."),
    ])
 
    sup = Supervisor(workers={"writer": writer})
    result = await run_architecture(sup, "say hello", model=supervisor_model)
 
    assert "Hello world" in result.output

`resolve_architecture`


def resolve_architecture(spec: Architecture | str | None) -> Architecture: ...

Coerce an architecture spec to a concrete Architecture instance. Used internally by Agent.__init__; exposed for callers that want the same coercion semantics.

`spec`	Resolves to
`None`	`ReAct()` (the default)
`str`	Looked up in the `KNOWN` map (see below)
`Architecture` instance	Returned as-is

Unknown strings raise ConfigError with the list of known names.

Known string specs

String	Resolves to
`"react"`	`ReAct()`
`"plan-and-execute"`	`PlanAndExecute()`
`"rewoo"`	`ReWOO()`
`"reflexion"`	`Reflexion()`
`"self-refine"`	`SelfRefine()`
`"tree-of-thoughts"`	`TreeOfThoughts()`

Multi-agent architectures (Supervisor / Router / Swarm / Debate / ActorCritic / Blackboard) require an instance. The string resolver only knows single-agent loops, since multi-agent shapes need worker Agents as constructor arguments.

Example


from loomflow.architecture import resolve_architecture
 
resolve_architecture(None)                  # ReAct()
resolve_architecture("react")               # ReAct()
resolve_architecture("plan-and-execute")    # PlanAndExecute()
resolve_architecture("bogus")               # raises ConfigError
 
from loomflow.architecture import Supervisor
arch = Supervisor(workers={"a": agent_a})
resolve_architecture(arch) is arch          # True (returned as-is)

Future: entry-point discovery

Third-party packages will be able to register custom architectures via [project.entry-points."loomflow.architecture"] so you can reference them by string from user code without an explicit import. Not in 0.9.x.

Source

loomflow/architecture/resolver.py · loomflow/team.py (the run_architecture definition)

run_architecture vs Team.*. Team.* builders return an Agent you keep around for many runs. run_architecture builds a single-use shell, runs once, returns the result. Use Team for production wiring; use run_architecture for tests and one-off explorations.

run_architecture / resolve_architecture

run_architecture