Why our research agents talk through a single API contract

A research pipeline built from AI agents can be put together in two ways. One is a long conversation where every agent sees everything and anything can happen next. The other is a set of separate stages that hand finished work to each other. We chose the second, and we made every hand-off go through one contract.

This note explains what that contract is, what it buys us, and what it costs.

What we mean by a contract

A contract is a fixed description of what a stage receives and what it returns. The hypothesis stage returns a hypothesis card with named fields: the statement, its rationale, a testable prediction, the data it needs and the criteria it must meet. The implementation stage accepts that card and returns strategy code. The validation stage accepts strategy code and returns a verdict, together with the evidence behind it.

Every stage uses the same envelope around its work: what came in, what went out, whether the stage finished, and a record of what it used along the way. The content differs from stage to stage. The shape of the hand-off does not.

Stages that don’t know each other

Because a stage depends only on the contract, it never needs to know how its neighbours work. That lets us change one stage without touching the rest. A different model for hypothesis generation, a new approach to writing strategy code, a stricter validator: none of these requires rewriting the pipeline, as long as the stage still honours the contract.

It also makes model choice a per-stage decision. The agent that drafts hypotheses and the agent that writes code have different jobs, and the best model for one is not always the best for the other. With a shared contract, swapping the model behind a stage is a configuration change rather than a redesign.

Any stage can run on its own

The same property makes it possible to run a single stage without the others. You can bring a hypothesis of your own and only implement and validate it. You can generate hypotheses and stop there. You can re-run validation on code that already exists.

A stage doesn’t know or care where its input came from. It only checks that the input fits the contract. A hypothesis card written by a person and one written by an agent look the same at the boundary, and they are treated the same way.

Outputs you can open and read

When agents pass work along informally, it is hard to tell where things went wrong. A disappointing result could come from a weak idea, from code that doesn’t match the idea, or from a test that exposed a real flaw. Without clear hand-offs, those three cases blur together.

With a contract, every hand-off is a document you can open. If a strategy fails validation, you can look at the hypothesis card and ask whether it was testable, look at the code and ask whether it implements what the card says, and look at the validation record and ask what exactly failed. The chain stops being opaque and becomes a series of checkpoints.

The same documents make runs repeatable. A recorded output from one stage can be fed into the next stage again, with the same inputs, so a result can be traced back and reproduced instead of taken on trust.

Rules live at the boundary

A contract is also a natural place to enforce rules. A hypothesis without acceptance criteria does not pass to implementation. Code that doesn’t declare the data it needs is stopped before a backtest starts. A validation result without its evidence is not a result.

Catching a problem at the boundary is cheaper than discovering it at the end of a long run. It also keeps responsibility clear: each stage is accountable for what it hands over, and the next stage can rely on it.

What it costs

The main cost is upfront design. We have to decide what a stage returns before we build it, and that decision is harder to get right than it looks. When our needs change, the contract changes, and every stage that reads it has to follow. That is real work, and it slows down early experiments.

We also give up some flexibility. An agent that notices something interesting outside its task can only pass it on if the contract has a place for it. Free-form conversation would let that observation travel; a contract asks us to decide in advance which observations matter.

Finally, the contract itself needs care. It is versioned like code, and a change to it is reviewed like a change to code, because every stage depends on it.

Why we accept the trade

For research, the question is not only whether a pipeline produces an answer, but whether you can trust how it got there. Legible hand-offs make that question answerable. A contract makes each stage replaceable, each output inspectable and each run repeatable, and we think that is worth the design effort it takes.