Agent ABC + its neutral streamed-event vocabulary.
Re-exports the Agent interface (its PresetSpec input, AddressedMemory answer, the
TOOL_NAME_MAX_LEN / PRESET_NAME_PATTERN laws and AgentInterruptedError error)
alongside the StreamEvent types an agent’s astream yields and run drains.
PRESET_NAME_PATTERN
tai42_contract.agent.base.PRESET_NAME_PATTERN
TOOL_NAME_MAX_LEN
tai42_contract.agent.base.TOOL_NAME_MAX_LEN
AddressedMemory
tai42_contract.agent.base.AddressedMemory
keys names the run kwargs present that steer THIS run’s own thread or checkpoint
continuity (resuming, the checkpoint the run continues from, the checkpointer it runs on) — the
keys a door that owns the run’s identity refuses. A key that only configures a sub-role’s memory
is not one of them; its thread and checkpoint ids are still reported in thread_ids /
checkpoint_ids.
Attributes
Agent
tai42_contract.agent.base.Agent
run; override astream only when the agent produces real per-step
events.
Subclasses declare three class attributes that drive auto-tool generation:
tool_name— the registered name (also the auto-generated tool name);tool_description— the LLM-facing description (carried, not lost);ToolInput— a JSON-able pydantic model of the tool params. Livetools=is deliberately NOT inToolInput(API-only viaastream); a non-JSON field fails loudly atmodel_json_schema()time.
spec_runnable is a capability marker (default False):
spec_runnable = True declares that this agent’s ToolInput advertises
EXACTLY the composable fields its runtime honors — no more, no less. This lets
a generic UI gate authoring controls on the input schema’s fields: it renders a
control only for an advertised (honored) field, and baking an un-advertised
field is rejected at author time. The declaration is the implementation’s — it
is never inferred, and no agent name is ever hardcoded. Because every
ToolInput field of a spec_runnable agent is honored, all of them are
preset-bakeable; preset_bakeable_fields covers the other case.
preset_bakeable_fields names the ToolInput fields whose baked
(preset fixed_kwargs) value the runtime honors on an agent that is NOT
UI-composable — declaring a field here implies no UI control at all, only that
a hidden baked value is passed through and acted on. A field is preset-bakeable
iff the agent is spec_runnable (all fields, above) OR the field is listed
here. Like spec_runnable it is the implementation’s own declaration, never
inferred; every listed name must be a real ToolInput field. The empty
default means nothing is bakeable unless the agent is spec_runnable.
tool_names is the FIXED tool set this agent always binds — the
statically-declared set a bind check reads to judge what the agent will run
with (e.g. whether it can ask its caller). None (the default) declares an
agent that resolves its tool set per call (from its ToolInput/run kwargs),
so nothing static is known. An agent whose tool set is fixed declares it here;
like spec_runnable it is the implementation’s own declaration, never
inferred.
parks declares that this agent can suspend on an async ask raised by a
tool it runs and resume out of band (it emits SuspendedFinal). Like
spec_runnable it is the implementation’s own declaration, never inferred; a
consumer reads it to know whether a run of this agent can park.
Attributes
Members
addressed_memory
tai42_contract.agent.base.Agent.addressed_memory
run_kwargs (the output of from_tool_input) address.
The names of the run kwargs present that steer the run’s memory or continuity (keys),
and every thread id and checkpoint id they carry, however nested. The platform reserves
thread namespaces and decides caller pinning from this answer, so an agent that carries a
thread or checkpoint anywhere in its run kwargs MUST report it. An agent with no memory
returns AddressedMemory(). The contract’s own thread_id keyword is checked by the
platform itself and need not be reported.
Parameters
from_tool_input
tai42_contract.agent.base.Agent.from_tool_input
ToolInput instance to run kwargs.
Passes through every set field with nested pydantic values (presets,
subagents, inline_skills) kept as model instances, since run
and the resolvers it calls read them by attribute. model_dump is
deliberately NOT used — it would flatten those nested models to dicts.
Agents whose JSON tool-face shape differs from their run signature
override this.
Any error an override raises must be a constant, hand-authored message and
must NOT interpolate input values: the agent run routes surface these
messages verbatim to the caller, and the baked input can carry credentials
the caller is not entitled to see.
Parameters
run
tai42_contract.agent.base.Agent.run
thread_id, user_message, tool_names and response_format are the keys the
platform supplies or reads; every other keyword is the agent’s own, declared by its
ToolInput and documented by the agent. response_format: a JSON-Schema dict MUST
carry a non-empty top-level title (the structured-output name the run forces), and each
oneOf variant its own; a TemplatedText names a stored schema rendered at the point of
use; an in-process pydantic class (an agent’s own widening of this parameter) carries its
class name.
Parameters
astream
tai42_contract.agent.base.Agent.astream
str becomes a
MessageFinal (plain-text answer), any other value a
StructuredFinal (the structured response_format object).
Streaming agents override this with the real per-step projection and
implement run by draining their own astream via
_drain.
Parameters
append_thread_messages
tai42_contract.agent.base.Agent.append_thread_messages
messages to thread_id’s stored history WITHOUT running the agent.
Each item is {"role": "user"|"assistant", "content": str}. The conversation
bridge calls this to record a manual-mode inbound and an operator’s outbound reply
into the thread’s memory, so a later agent turn reads them as prior context. An
agent with no thread memory raises NotImplementedError.
Parameters
AgentInterruptedError
tai42_contract.agent.base.AgentInterruptedError
run/_drain when a non-streaming caller drains a run that paused on an interrupt.
A non-streaming caller cannot act on an interrupt, so it surfaces loudly rather than
returning a partial. interrupts is the list of InterruptFinal events the run
emitted.
Attributes
AsksFinal
tai42_contract.agent.events.AsksFinal
to="caller" ask is addressed to the run’s own caller — here the SSE client driving the
stream — so the run cannot proceed until the caller answers it, unlike a to="user" park
(SuspendedFinal) whose answer arrives out of band. asks carries the full parked
entries the caller must answer (id, question, answer format, and the rest of the parked-entry
shape); the vocabulary is generic — it names no driver, engine, or resume state.
Attributes
InterruptFinal
tai42_contract.agent.events.InterruptFinal
interrupt_id is the graph interrupt id (echoed back when resuming);
payload is the interrupt value the agent raised (e.g. the option set);
reason is an optional human-facing label. This event is emitted verbatim
as one SSE frame (type: "interrupt_final"); a consumer reads
interrupt_id, payload and reason off it — do NOT rename payload
or drop reason.
Attributes
MessageDelta
tai42_contract.agent.events.MessageDelta
MessageFinal
tai42_contract.agent.events.MessageFinal
PresetSpec
tai42_contract.agent.base.PresetSpec
name follows PRESET_NAME_PATTERN. A base tool that interprets its fixed kwargs as a
nested document carries that document opaquely here.
Attributes
ReasoningStep
tai42_contract.agent.events.ReasoningStep
RecursionLimitFinal
tai42_contract.agent.events.RecursionLimitFinal
recursion_limit) ceiling before it finished. Terminal, non-fatal.
A runaway loop that exhausts the super-step budget ends with this typed,
readable outcome instead of a generic failure, so a caller or route can branch
on it. limit is the super-step ceiling that was hit; steps is what is
known of the step count when the graph reports it, else None.
Attributes
RunUsage
tai42_contract.agent.events.RunUsage
None.
Attributes
StreamEvent
tai42_contract.agent.events.StreamEvent
Agent streams.
type is a stable discriminator; final marks a terminal event (see the terminal
rule in Agent._drain).
Attributes
StructuredFinal
tai42_contract.agent.events.StructuredFinal
data is the object the agent produced — typically the validated response_format
instance. A plain-text answer is carried by MessageFinal instead. Terminal.
Attributes
StructuredOutputUnresolvedFinal
tai42_contract.agent.events.StructuredOutputUnresolvedFinal
response_format. Terminal, non-fatal.
The structured-output rail re-prompted the model each time its final answer
failed to parse or validate against the schema, or carried no structured answer,
and the per-run re-prompt cap was reached with no conforming response. The run
ends with this typed outcome — branchable like a tool error — rather than looping
to the recursion limit or surfacing a generic failure. schema_name names the
requested schema; attempts is how many non-conforming responses the model
produced (the re-prompt cap plus the final rejected attempt); error is the
last error text — a validation error, or the message naming the missing
structured answer — masked as every recorded error is.
Attributes
SuspendedFinal
tai42_contract.agent.events.SuspendedFinal
ask questions and will resume out
of band when their answers (or expiries) arrive — it did NOT fail and did NOT
stop for a live decision, so a non-streaming drain returns a suspended RECEIPT
for it rather than raising AgentInterruptedError.
interaction_ids are the parked questions the resume converges on;
caller_interaction_ids is the subset of them addressed to the CALLER
(to="caller"), empty for a park of only user asks — the two id lists let the
platform’s visit normalise a caller-ask park inside an agent into its
caller/user partition; expiry_at is the step’s deadline — the latest of its parks’
deadlines (ISO-8601, or None when no park carried one); thread_id is the parked run’s thread. The
vocabulary is generic — it names no driver, engine, or resume state, only the parked
interaction ids the consumer-agnostic platform already holds.
Attributes
Members
to_suspended_interaction
tai42_contract.agent.events.SuspendedFinal.to_suspended_interaction
visit recognises by type.
It carries the whole super-step’s two id lists, so visit normalises it per ask, and the
step’s deadline. It carries NO resume_owner: the parked run recorded its own resume
state against those interactions and is the only thing the platform resumes for them, so no
caller may adopt the park as its own.
ToolCallStep
tai42_contract.agent.events.ToolCallStep
call_id is the model-assigned id the matching ToolResultStep carries.
Attributes
ToolResultStep
tai42_contract.agent.events.ToolResultStep
ToolCallStep by call_id.
result is passed through untouched.
Attributes
agent_session_thread
tai42_contract.agent.session_thread.agent_session_thread
thread_id as the ambient session thread for the wrapped block.
The deposit is reset in a finally. A task created inside the block inherits it on a
copy. Absent this wrap the deposit stays None and a run mints its own fresh thread.
Parameters
final_event_for_value
tai42_contract.agent.events.final_event_for_value
str is a plain-text answer (MessageFinal); any other value is structured output
(StructuredFinal, its data). The single rule both the non-streaming astream
default and a resumed run’s plain terminal map a raw value through, so every path surfaces the
same final shape.
Parameters
get_agent_session_thread
tai42_contract.agent.session_thread.get_agent_session_thread
None when none is set.
reset_agent_session_thread
tai42_contract.agent.session_thread.reset_agent_session_thread
token.
token is the return value of the matching set_agent_session_thread call.
Parameters
set_agent_session_thread
tai42_contract.agent.session_thread.set_agent_session_thread
thread_id as the current run’s session thread.
Pass the returned token to reset_agent_session_thread to restore the previous value.
Parameters

