Skip to main content
Agent contract: the 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
The memory a set of run kwargs addresses, as the agent reads them. 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
The uniform agent contract. Implement 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. Live tools= is deliberately NOT in ToolInput (API-only via astream); a non-JSON field fails loudly at model_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
Report the 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
Map a validated 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
Run the agent once and return its final value. 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
Free default for non-streaming agents: run once, emit one terminal. The terminal type matches the result: a 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
Append 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
Raised by 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
The agent run asked its CALLER one or more questions before it could answer. Terminal. A 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
A platform interrupt surfaced out of a paused agent graph. Terminal. 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
A token-level chunk of the agent’s final answer as it streams. Attributes

MessageFinal

tai42_contract.agent.events.MessageFinal
The agent’s complete final answer, assembled from the deltas. Terminal. Attributes

PresetSpec

tai42_contract.agent.base.PresetSpec
A base tool bound to fixed kwargs, bound as one more tool of the run that carries it. 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
A chunk of the model’s intermediate reasoning (“thinking”) for one step of the agent loop. Empty/whitespace-only reasoning is never emitted. Attributes

RecursionLimitFinal

tai42_contract.agent.events.RecursionLimitFinal
The run hit the graph’s step (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
Token usage (and model label) for the run. Any field may be None. Attributes

StreamEvent

tai42_contract.agent.events.StreamEvent
Base class for every event an 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
The agent’s structured (non-text) output. 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
The model never produced output conforming to the requested 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
A generic async park surfaced out of a paused agent graph. Terminal. The run parked on one or more async 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
The park as the shared typed sentinel the platform’s 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
One tool invocation the agent decided to make. call_id is the model-assigned id the matching ToolResultStep carries. Attributes

ToolResultStep

tai42_contract.agent.events.ToolResultStep
The value one tool call returned, matched to a ToolCallStep by call_id. result is passed through untouched. Attributes

agent_session_thread

tai42_contract.agent.session_thread.agent_session_thread
Deposit 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
The terminal event a plain agent result value represents. A 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
The session thread deposited for the current run, or None when none is set.

reset_agent_session_thread

tai42_contract.agent.session_thread.reset_agent_session_thread
Restore the session thread to the value captured in 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
Bind thread_id as the current run’s session thread. Pass the returned token to reset_agent_session_thread to restore the previous value. Parameters