What you can rely on
The fit table, the guarantee table, and the status of 0.2.x.
This page is the honest boundary of the project: what agentsparty proves, what it checks at run time, and what it deliberately leaves to you. Read it before you build anything on top.
Fit
| Use agentsparty when | Look elsewhere when |
|---|---|
| The allowed interaction shape is known up front | One agent with a free tool set is enough |
| Every role must act only on messages it actually receives | The route must be discovered at runtime by the model |
| Projection has to fail closed before the first model call | You need a large catalogue of vendor integrations out of the box |
| Tools are roles with a protocol surface, not free function-calling | You require a stable API before 1.0 |
| Sessions must resume from recorded decisions without re-asking | You need multi-process or multi-machine transport |
The runtime is in-process only. Distributed multi-host orchestration is not shipped, and roles are never invented mid-run: topology is known at bind time.
What is checked, and when
| Property | Result | Stage |
|---|---|---|
| Declared labels only | Guaranteed | Session constructor, projection, runtime decode |
| Knowledge of alt | Guaranteed | Session constructor (ProjectionError) |
| Well-formed recursion | Guaranteed | Protocol constructor |
| Payload shape | Guaranteed at the boundary | message decode |
| Endpoint conformance | Guaranteed when checked | Session constructor (ConformanceError) |
| Replay of authored decisions | Guaranteed for journaled decisions | resume (ProtocolMismatch if the shape changed) |
| Deadlock freedom | Not generally guaranteed | — |
| Liveness | Not guaranteed | — |
| Termination | Predicate only (may_terminate, must_terminate) | — |
| Exactly-once external effects | Not guaranteed | — |
| Distributed delivery | Not shipped | — |
The negative claims are part of the contract. Projection can reject a protocol before a model call; it cannot make a model answer, make a human respond, or make an external API idempotent. A participant can still fail or wait.
How to read the guarantee table
“Guaranteed” means the library checks the property at the named boundary and raises a typed error when it fails. “Guaranteed at the boundary” does not mean that arbitrary values elsewhere in the application are safe; it means the message codec refuses them before delivery. “Not guaranteed” is an intentional limit, not a missing promise that a later point release silently fills in.
For example, projection guarantees that a role will not receive a local
endpoint with an unseen branch. It does not guarantee that the role chooses the
branch your product owner wanted. Allowance guarantees that the runtime stops
after its configured limit; it does not guarantee that the work is useful when
the limit is reached. A journal guarantees replay of its recorded decisions;
it does not replay an external email or database write unless your application
made that effect idempotent and represented it explicitly.
A deployment decision
Before adopting the runtime in a service, write down the answers to these questions:
- What work can safely wait in one process, and what needs a durable queue?
- Which participant calls a network or filesystem boundary, and what timeout limits it?
- Which decisions must survive a restart, and which state can be reconstructed?
- What does the client see when a model refuses, a human does not answer, or an allowance is exhausted?
- Which external effects can be repeated during retry or resume?
If the answer requires a distributed scheduler, an exactly-once transport, or a model-discovered topology, this project is the wrong execution layer today. Keep the protocol as a local contract or choose a system that owns that missing responsibility.
Do not promote a check into a promise
Guaranteed in the table means a named boundary rejects an invalid value. It
does not mean the whole application is correct after that boundary succeeds.
Status of 0.2.x
- Research framework at
0.2.x. The public surface is tiered. - Exception types are stable; exception message text and journal formats are not.
- Removing a public export, changing a public signature, or changing protocol meaning is a breaking change and lands in the CHANGELOG.
- Protocol meaning is introduced in Protocol.
Related: Error taxonomy and Sessions and runs.