Skip to content

Factories

A factory is a named, ordered list of stations. You give it a mission, and each station’s output becomes the next station’s input. The factory holds no state of its own: running it returns a Run, a plain record of what happened, which is also kept in the store.

from pydantic_ai import Agent
from pydantic_ai_factory import Factory, MemoryStore, station
designer = Agent("anthropic:claude-opus-5-5", name="designer", instructions="Write a short design.")
builder = Agent("anthropic:claude-opus-5-5", name="builder", instructions="Build what the design says.")
software = Factory("software", [station(designer), station(builder)])
run = software.run_sync("A to-do list web page where I can add tasks and tick them off.", store=MemoryStore())
print(run.outcome)
#> passed
print([step.station for step in run.steps])
#> ['designer', 'builder']

Name a factory for what it makes, such as "software", not for one piece of work it is given.

Call Does
factory.run(input, store=...) Runs the work and returns a Run. Async.
factory.resume(run, answer, store=...) Carries on a run that is waiting for a person. Async.
run_sync, resume_sync The same, for code that is not async.

input is the first station’s input. A plain string becomes a Mission when that station takes a mission or a string; a station that takes a string is given the mission as its prompt. Both calls also take deps=, which every station receives as ctx.deps.

Field Holds
outcome "passed", "failed", "did_not_run" or "waiting". A run saved between stations is "running".
output The last station’s output, once the run has finished.
waiting What a person is being asked, when the outcome is "waiting". See approvals.
steps One result per station attempt, in order.
approvals Every decision a person made.

"failed" means a gate judged the work and it fell short. "did_not_run" means something could not be done at all, such as an unreachable model. The library never reports one as the other.

The factory saves the run after every step. Pass on_step= to run or resume, and it is awaited with the run each time it is saved.

from pydantic_ai import Agent
from pydantic_ai_factory import Factory, MemoryStore, Run, station
designer = Agent("anthropic:claude-opus-5-5", name="designer", instructions="Write a short design.")
builder = Agent("anthropic:claude-opus-5-5", name="builder", instructions="Build what the design says.")
software = Factory("software", [station(designer), station(builder)])
async def show(run: Run) -> None:
print(run.outcome, [step.station for step in run.steps])
#> running []
#> running ['designer']
#> running ['designer', 'builder']
#> passed ['designer', 'builder']
software.run_sync("A to-do list web page.", store=MemoryStore(), on_step=show)

Use it to tell people a run is waiting for them, or to show progress. The run is already saved when on_step is called, so it only watches. The next station waits for it to return, so keep it short. If it raises, the error ends the call and the run stays saved as "running", which nothing can resume. Catch your own errors inside it.

When a station fails its gate, a rework rule sends the work back a fixed number of times.

from pydantic_ai import Agent
from pydantic_ai_factory import Artifact, Evidence, Factory, MemoryStore, Rework, Verdict, failed, gate, passed, station
designer = Agent("anthropic:claude-opus-5-5", name="designer", instructions="Write a short design.")
@gate(version="1")
def mentions_blank_tasks(output: Artifact[str], evidence: Evidence) -> Verdict:
if "blank" in output.payload.lower():
return passed("the design says what happens to a blank task")
return failed("the design never says what happens to a blank task")
design = station(designer, gate=mentions_blank_tasks)
software = Factory("software", [design], rework=[Rework(design, limit=2)])
run = software.run_sync("A to-do list web page.", store=MemoryStore())
print(run.outcome, len(run.steps))
#> passed 2

Rework(design) redoes design when it fails. To send work back to an earlier station, add to=: Rework(build, to=design) redoes the design when the build fails. The agent picks up its own conversation and is told what was wrong; see agents in stations. At the limit the run stops as "failed". Pass on_limit="continue" to carry on anyway, or on_limit="escalate" to ask a person.

Rework is only for work that was judged and failed. A station that did not run is never sent back.

A factory can say what it will use before anything runs, so you can check keys and costs first.

from pydantic_ai import Agent
from pydantic_ai_factory import Factory, station
designer = Agent("anthropic:claude-opus-5-5", name="designer")
builder = Agent("anthropic:claude-opus-5-5", name="builder")
software = Factory("software", [station(designer), station(builder)])
print({name: [agent.name for agent in agents] for name, agents in software.agents().items()})
#> {'designer': ['designer'], 'builder': ['builder']}
print(software.methodologies())
#> {'designer': (), 'builder': ()}

factory.methodologies() gives each station’s methodologies, the objects themselves, before anything runs. These agents have none.

A factory is checked when it is declared. If one station’s output type does not match the next station’s input, or two stations share a name, Factory(...) raises FactoryDefinitionError listing every problem at once.