soev_agents.toolkit

A ready agent that runs the ReAct loop: the model calls tools until its output calls none.

Each model output with tool calls runs the tools, and the model is called again with their results. The turn ends with the first model output that calls no tools. Register the agent in an AgentCatalog under a name.

The settings come from config: one ReActConfig for every turn, or a function that builds the config of each turn. The function gets the resources of the turn, the parsed turn and the model that the turn's input names. So it can give each model its own settings, or refuse a turn with InputDeniedError. The whole turn runs on that model. The adapter is never asked which model it is.

Nothing is recorded beyond the conversation. The system prompt and the instructions of required tools follow from the config and each recorded input, so each later model call writes them again.

from openai import AsyncOpenAI

from soev_agents.adapters import InMemoryTraceStore, OpenAIChatModel
from soev_agents.runtime import AgentCatalog
from soev_agents.toolkit import BRACKETS, ReActAgent, ReActConfig

# PROMPT is your system prompt text, and search is a tool that the `tool` decorator made.
model = OpenAIChatModel(AsyncOpenAI(), model="gpt-4.1-mini")
assistant = ReActAgent(ReActConfig(model=model, prompt=PROMPT, tools=[search], citations=BRACKETS))
agents = AgentCatalog(InMemoryTraceStore(), {"assistant": assistant}, version="1")

Make the agent.

Raises:

• ValueError: config is a ReActConfig that keeps the default render_input or tool_states, and input has no text or tools field for that default to read.

Every setting of a ReActAgent for one turn, except its input class.

Only model and prompt are required. A ReActAgent takes one config for every turn, or a function that builds the config of each turn.

The tool settings work together. declared lists the tools that the agent has, and tools are the tools that your code supplies for this turn. tool_states gives the state that the turn asks of each tool. A declared tool is offered when it is supplied and its state is not "off", in the order of declared. A turn that requires a tool gets the tool's instruction after its message, in the words of the tool's declaration.

passes caps the model calls of one turn that call tools. Past the cap, the tool calls do not run, and the default context strategy gives each of them a directive to finish as its result. The model keeps its tools for tool_rounds_after_cap more calls. Then it is called without tools, so it can only write its final output.

The tools that context adds, such as the reopen tool, are not declared. The context strategy offers them, and the tool step runs them each time that the model calls them.

Raises:

• ValueError: tool_rounds_after_cap is negative, two declarations share a name, or a declared or supplied tool has the name of a tool that context adds.
• PromptFileError: The system template of the prompt file, or a block that a model layer replaces, reads a variable other than citation.

A plain-text input: the payload is the message.

It asks nothing of any tool and brings no context. It is the default input class of a ReActAgent.

A chat turn: the message, the state that it asks of each tool, and context for the agent's system prompt.

Unknown fields are refused, so a misspelt field fails instead of being dropped.

Return a RenderInput that parses each input's payload into input_type and renders it with render.

Give it as the render_input of a MessageBuilder in a graph of your own. The payload is parsed strictly. A payload that input_type no longer parses is shown as recorded: its elements, then the payload, as text when it is a string and as JSON otherwise. So a change to input_type leaves older threads readable.

Return the elements that turn's fields hold, as show renders them, then its text after a blank line.

This is the default RenderTurn. A turn that holds no elements is its text alone.

Raises:

• AttributeError: turn has no text. Its agent needs a RenderTurn of its own.

How the model reads a parsed input: a function of the parsed turn, ShowElements and the recorded Input.

It returns the user message, or None to keep the input from the model on purpose. The recorded Input gives what the payload does not hold, such as when it was sealed (ts).

A function that renders an Input as the user message that the model reads.

It gets the input, and the function that shows the elements of the input. It returns None to keep the input from the model on purpose. rendered_by makes one.

A function that writes the system prompt of a turn.

It gets the parsed input of the turn, and an example marker of the citation strategy of the model about to be called, or None when the model does not cite. prompt_template makes one.

Return a prompt that writes template with the example marker and the turn's context in it.

{citation} becomes the example marker of the model's citation strategy. {context} becomes the turn's context, as ChatTurnInput holds it, without the spaces around it. Each is empty when there is none. Both are filled in one pass, so text that the turn brings is never read as a placeholder. Other braces stay as they are, and the spaces around the result are removed.

One agent's prompt file: every text that its models read, with a layer of overrides per group of models.

Load the file with load and give it as the prompt of a ReActConfig, which uses the texts of the turn's model. python -m soev_agents.toolkit.prompts FILE --model ENDPOINT prints what one model reads.

The system prompt is a Jinja template. A model layer replaces its {% block %}s, or extends them with {{ super() }}. A placeholder in a plain text is filled by the code that reads the text. A model layer replaces only keys that the base defines. Tool names and argument names are checked when the texts are applied (Prompts.described), because only the agent knows its tools.

Raises:

• pydantic.ValidationError: The file has another shape, a layer replaces a block or text that the base does not define, or two layers name one endpoint.
• jinja2.TemplateSyntaxError: The system template is not valid Jinja.

The texts of one agent for one model, which PromptFile.for_model resolves from the prompt file.

The overrides of a prompt file for a group of models, which endpoints names.

A layer replaces only blocks and texts that the base of the file defines. Unknown fields are refused.

What the model reads of one tool in a prompt file: its description and its arguments' descriptions.

Each text replaces the tool's own default. Unknown fields are refused.

A prompt file that does not fit its agent, or a model layer that does not fit the file's base.

PromptFile raises it, inside a pydantic.ValidationError, for a model layer that replaces a block or a text that the base does not define, or that names an endpoint of another layer. PromptFile.check_variables raises it for a template that reads a variable that the agent does not supply, and ReActConfig calls that check. Prompts.described raises it for texts of a tool or an argument that the agent does not have, Prompts.text for a text that the file does not define, and Prompts.system for a file without a system template.

The citation strategy that writes markers such as [4], and [4][5] for two sources.

It reads [4], [4, 5], [4;5], 【4】 and 【4†source】, so a model that writes another of these forms is still read.

The citation strategy that writes markers such as 【4】, and 【4】【5】 for two sources.

It reads the same markers as BRACKETS.

A tool that an agent has, by name, and the agent's rule for offering it.

A declaration is not the tool: two agents can offer the same tool by different rules. On each turn, the code supplies a tool for each declared name or leaves it out.

Raises:

• ValueError: required_tool_instruction uses a placeholder other than {tool}.

What a turn asks of one tool: "off", "auto" or "required".

"off": not offered. "auto": offered for the model to use as it sees fit. "required": offered with an instruction to use it. The instruction is a request, not a guarantee: the model can still not call the tool.

A subagent that the parent's model calls as a tool: one subagent for each call.

Each subagent runs on build(its input, its model), the model that the hand-off names. Put the delegation in a node of the parent's graph, and offer its spec to the parent's model.

The model is shown input's fields as the tool's arguments. An element field is shown as the id of an element of its class, which the hand-off turns into the parent's element with the parent's numbering. An input that is not an object, such as a RootModel[str], is shown under one input argument. A call whose arguments do not fit gets an error as its result and starts no subagent.

Raises:

• ValueError: An element field sits inside another model, inside a collection other than a list, tuple or Sequence, or in a union with a type other than None. The hand-off cannot fill it.

The input that a ToolDelegation hands off: one tool call of the parent's model, as a subagent's task.

The payload is the call's arguments, parsed into the delegation's input class, with each element id replaced by the parent's element. The input records the elements of the payload. The hand-back reads call_id and expects to link and check the subagent's result, so it reads nothing outside the subagent's stream. A task that names no model runs on the model of the parent's latest input.

The context management of a ReActAgent: what each model call of the agent receives.

The agent uses it in three places. for_turn makes the context builder of one turn, from the parts that the agent computes for that turn. added_tools are the tools that the strategy offers itself, such as reopen, which the agent's tool step runs. wrap gives the model step the strategy's own step, such as compaction. MessageBuilder is the default strategy.

The three parts are one context management, because they depend on each other. A strategy that compacts must build contexts that show the summary of each Compaction in place of the events that it replaced. A strategy that adds a reopen tool must offer it, and show what it reopens.

Whatever the strategy, the tool step checks the rules of each call, the runner ends the turn past the budget, and the model step reads citations and element numbers with the numbering of the built context.

The context builder for a chat model: the messages and the tools that one model call gets.

The messages are the system prompt that prompt writes, then the events that select picks from the trace. Each element shows by show, under its number in the whole thread, so a selection never renumbers. An agent's own event types become messages by renderers.

The builder is also the default ContextStrategy of a ReActAgent. Its own settings come first: policy, show, select and renderers. The parts of one turn follow. A ReActAgent gives them with for_turn. A graph of your own gives them when it makes the builder. The policy's reopen is the tool that the builder adds, and the policy's compact wraps the model step. So the shrinks, reopen and compaction stay in one place: the builder that reads the summaries that they write.

With limits, the policy decides the form of each tool result, again at each call. Each result is made smaller by the function of its tool for that form, and cut at the cap of its tool. A compressed result starts with a line that names its handle. A stubbed result is only that line and what floors keep, and its call stays. A shrunk result keeps what floors kept when it shrank, so a later citation never changes it. An input's elements always show as recorded. Without limits, each result is full and each text shows as recorded.

The policy's reopen tool is offered after tools, from the first call that shortens a tool result or follows a summary. After a Compaction, the events that it replaced are left out, and its summary follows the prompt in the system message. On the call after the last trip of budget, no tools are offered, reopen included, so the model writes its final output.

from soev_agents.runtime import LlmStep, tool_def
from soev_agents.toolkit import ContextPolicy, MessageBuilder, ModelLimits, Text, Tokens, rendered_by

# model is a ChatModel, turn_model is the model name of the turn, PROMPT is the system prompt text,
# search is a tool that the `tool` decorator made, and graph is the Graph of the turn.
builder = MessageBuilder(
    ContextPolicy(result_cap=Tokens(4_000)),
    render_input=rendered_by(Text),
    model=model.resolve(turn_model),
    prompt=lambda citation: PROMPT,
    tools=(tool_def(search),),
    limits=ModelLimits(window=Tokens(128_000)),
)
graph.add_node("answer", LlmStep(builder=builder, model=model))

How a MessageBuilder keeps what a model is sent within what the model accepts.

Each default is the whole default: a field that you give replaces it, and nothing is added to it.

At each model call, the builder estimates the size of the context. When the size is over start_at, the builder applies the shrinks of shrink in order, until the size is under target. A shrink with its own when runs over that size instead. The builder works the forms out again at each call, from the first model call of the view, so nothing is stored. When the context is still over the threshold of compact after the shrinks, the model summarises earlier history. A call whose prompt leaves less than output_reserve in the window is refused before it is made: the builder raises ContextFullError.

from soev_agents.toolkit import (
    Compact,
    Compress,
    ContextPolicy,
    Forms,
    MessageBuilder,
    ReActConfig,
    Stub,
    turns,
)

# model is a ChatModel, and PROMPT is the system prompt text.
policy = ContextPolicy(
    shrink=(Compress(turns[:-2]), Stub(turns[:-4])),
    compact=Compact(where=turns[:-2]),
    tools={"read_document": Forms(cap=None)},
)
config = ReActConfig(model=model, prompt=PROMPT, context=MessageBuilder(policy))

Raises:

• ValueError: target is not below start_at, or max_images is negative.

Elements as the agent's Show renders them, under their numbers in the thread.

A RenderInput and a RenderEvent get one, to show the elements of their event. The Show gets None as the name of the tool.

A function that renders an agent's own event as the messages that the model reads.

It gets the event, and the function that shows the elements of the event under their numbers. Give it to a MessageBuilder in renderers, by the class of the event.

Return a selection of the events of types, subclasses included, for MessageBuilder.select.

A MessageBuilder without the parts of its turn was asked to build a context.

The builder needs model and render_input. A ReActAgent gives them with for_turn. A graph of your own gives them when it makes the builder.

An event that a MessageBuilder selected has a type that the builder has no renderer for.

The builder renders the built-in event types itself, and an agent's own event types by its renderers. It raises this error for any other type when it builds a context, so that no event is skipped silently.

A context that does not fit in the model's window, so the model call is not made.

A MessageBuilder with limits raises it when it builds a context: the estimated prompt plus the output_reserve of its policy is more than the model's window. A retry of the same call cannot help.

When the context does not fit, the step that MessageBuilder.wrap makes for a Compact first lets the model write a summary. That step raises this error when the where of the Compact selects nothing that a summary did not replace yet, or when the context still does not fit after the summary.

What one model accepts: its window in tokens, and how many characters make one of its tokens.

The app gives these numbers for each model. The framework uses no tokenizer: it estimates the tokens of a prompt from its characters. After a call to the same model records the real token count of its prompt, only the characters added since then are estimated.

A number of tokens, as its own type so that it is never taken for a share of a window.

Two numbers of tokens compare with < and >.

A share of the window of the model that the next call goes to.

It is its own type, so that it is never taken for a number of tokens. Share(0.6) of a window of 100 000 tokens is 60 000 tokens.

Raises:

• ValueError: fraction is not above 0 and at most 1.

A size of a context: a Share of the model's window, or a number of Tokens.

A Share follows the window of the model that the call goes to. A number of Tokens is the same for each model.

A function that offers tool results to shrink, each with the form that it goes to.

At each model call of the view, the context policy asks its shrinks while the context is too big. It applies the offers one at a time, in the order of the shrink, and stops when the context is small enough. So a shrink never decides when to stop. An offer that raises a form, or that frees nothing, is skipped.

Compress and Stub are the built-in shrinks. A plain function with the signature of __call__ is a shrink too.

A shrink can also have this attribute, which the context policy reads:

• when: a Threshold, or None. A shrink with a when starts when the context is over it, and stops when the context is no longer over it. A shrink without one, or with None, starts when the context is over the policy's start_at, and goes on down to the policy's target.

A shrink that compresses the tool results that where selects, oldest first.

It offers each selected result that is full. Without when, it starts when the context is over the policy's start_at, and goes on down to the policy's target. With when, it starts when the context is over when, and stops when the context is no longer over it.

A shrink that replaces the output of the tool results that where selects by one line, oldest first.

The line names the result handle. The elements that floors keep follow it, and the calls of the results stay. It offers each selected result that is full or compressed. Without when, it starts when the context is over the policy's start_at, and goes on down to the policy's target. With when, it starts when the context is over when, and stops when the context is no longer over it.

Some tool results of a view, selected by a Python index or slice of its turns, rounds or results.

Make one with turns, rounds or results: turns[:-2] selects the results of every turn but the last two. The units count from the oldest, the current one last. An index out of range selects nothing.

The turns of a view, the current one last. Index or slice it for a Selection.

turns[:-2] selects the tool results of every turn but the last two.

The rounds of a view, the current one last. Index or slice it for a Selection.

rounds[:-3] selects the tool results of every round but the last three.

The tool results of a view, in recorded order. Index or slice it for a Selection.

results[:-3] selects every tool result but the newest three.

What context management counts the age of tool results in: turns, rounds or results.

A turn starts at a fresh input. A round starts at a model output that calls tools. A result is one tool result. turns, rounds and results select by each unit.

Why a tool result has its form: the shrink that gave the form, and the model call at which it did.

MessageBuilder.explain returns these.

The lowest form that some elements can reach, whatever form their tool result has.

The form of an element is the form of its result, lifted to the highest floor that applies to it. A floor only shows more of a result: it never changes the form of the result. The default floor of a ContextPolicy is Floor(cited, FULL): a Source that the model cited before its result shrank keeps its text.

A predicate that says whether a floor applies to an element.

It reads only the events before the model call at which the result of the element shrank. So what happens later never changes a message that the model was sent already. cited is the built-in predicate.

Whether an earlier model output cited an element: the predicate of the default floor, Floor(cited, FULL).

A floor calls it with the element, the name of the tool that recorded the element, and the events before the call where the element's result shrank. It is true when a marker of a model output in those events cites the element's id. So a passage that the model relied on keeps its text after its result shrinks.

How much of a tool result the model is shown.

Forms are ordered: STUBBED is below COMPRESSED, and COMPRESSED is below FULL. A shrink only lowers the form of a result, and a floor only lifts the form of an element. Forms are not recorded: each model call works them out again.

The form of a tool result that the model reads whole, Form.FULL.

The form of a tool result with less text, under a line that names its handle, Form.COMPRESSED.

The form of a tool result that is one line with its handle, Form.STUBBED.

How the results of one tool look in each form.

Give it to a ContextPolicy in tools, by the name of the tool. A field that is None uses the policy's own function. A stubbed result is always its handle line and the elements that floors keep, so it has no function.

A function that makes a tool result look as it does in one form, for the model that reads it.

It gets the tool result as recorded, and the limits of the model that the call goes to. It can change text, data and the text of each element. It must keep every element, in order, and error, because floors and reopen find elements by id, and the model reacts to the error. A MessageBuilder raises ShortenError for a function that breaks this rule.

Give one to a ContextPolicy as full or compressed, or to one tool in a Forms. as_recorded, drop_text, sources and json_cap make the usual ones.

A function that shortens one text for the model that reads it.

It gets the text and the limits of the model that the call goes to. sources applies one to the text of each Source of a tool result. cap and first_words make the usual ones.

Return the tool result as the tool recorded it: the default full form.

Return the tool result with the text of each Source removed: the default compressed form.

With the xml layout, each source then shows as a tag without content. The result's own text and data stay.

Return a Shorten that applies shorten to the text of each Source of a tool result.

Other elements, and the result's own text and data, stay as they are. sources(cap(Tokens(500))) cuts the text of each source at 500 tokens.

Return a ShortenText that cuts a text at limit tokens, before the word that the limit falls in.

A cut text ends with cut, so the model can tell a cut text from a short one. A text that fits stays as it is.

Return a ShortenText that keeps the first count words of a text.

A text with more words becomes its first count words, with one space between them, followed by …. A shorter text stays as it is.

Return a Shorten that writes the data of a tool result as JSON and cuts it at limit tokens.

When the JSON is longer than limit, the result gets no data, and the cut JSON follows its text on a new line. Shorter data stays as it is, and so does a result without data.

A function of a form removed, added or reordered an element of a tool result, or changed its error.

Floors and reopen find elements by id, and the error is a fact that the model reacts to. A MessageBuilder raises it when it builds the context of a model call.

How the model summarises earlier history when the context is still too big after every shrink.

When the context of a model call is over when after every shrink, or does not fit at all (the context builder raises ContextFullError), the model first writes a summary of the units that where selects. Then the call is made from the summary. The Compaction and the model's output are recorded together. From then on, the MessageBuilder shows the summary in the system message, in place of the events that it replaced. Element numbers and result handles stay those of the whole thread.

The running unit is always kept. The summary never splits a tool call from its results: a cut that would split them moves to before the call. The summary call offers no tools and is not streamed. When a summary replaced every unit that where selects already, nothing is compacted, and a call that does not fit raises ContextFullError.

Give it to a ContextPolicy as compact.

A summary that replaces nothing.

The model step that MessageBuilder.wrap makes for a Compact raises it in two cases. The model wrote an empty summary. Or the context builder built the same ChatRequest after the summary as before it, because the builder does not show Compaction events.

The tool that shows the model again what a context policy shortened or removed.

The tool records only which elements and whole tool results to show again. The MessageBuilder draws them from where they were first recorded, as the result of the reopen call. Each element shows inside its whole, in the forms of the tool that recorded it. Each whole result shows under its handle, cut at the cap of its tool. Nothing earlier in the conversation changes.

A ContextPolicy holds the tool as reopen. The builder offers it from the first model call that shortens a tool result or follows a summary, until the turn's tools are withdrawn.

The arguments that the model writes to the reopen tool: elements by number, whole results by handle.

LlmStep replaces each number with the real id of its element, and each handle with the call id of its result, when it records the call.

Raises:

• pydantic.ValidationError: The arguments name no element and no result, or hold a field of another name.

Which reasoning of earlier model outputs the MessageBuilder sends back to the model.

Reasoning that is sent back counts toward the context like any text. CURRENT_TURN lets a model continue its reasoning between tool calls. When a new turn starts, the reasoning of the earlier turn is dropped, so the prompt cache misses once in each turn.

Send no reasoning of earlier model outputs back to the model, Reasoning.NEVER.

Send back the reasoning of the model outputs of the running turn, Reasoning.CURRENT_TURN.

Send back the reasoning of every earlier model output, Reasoning.ALWAYS.

The text of one tool call's elements: a layout.

It gets four arguments: the elements, the thread's numbering, the name of the tool that ran, and the citation strategy of the model. The tool name is None for the elements of an input. The strategy is None when the agent does not cite.

A layout shows the numbers of the numbering, never real ids. xml makes the default layout. Give one to a MessageBuilder as show.

Return the layout that shows each element as an XML tag named by its type, with its number as id.

A Source, the only element that can be cited, also carries the exact marker the model cites it with, written by its citation strategy, in the attribute cite names, e.g. <passage id="7" cite="[7]">. So the model copies what to cite instead of choosing among the numbers it sees.

Every field a subclass adds and every properties key is an attribute, unless fields names the class. A Source's text is the tag's content. An element nests inside the element its ref names when both are in the same call, in arrival order. Otherwise its tag names the ref as an attribute, called by the tag of the element recorded under that number, or ref when none was.

id, the cite attribute and the attribute naming the whole are the layout's own: an attribute of the same name is shown with data- before it. Text is escaped, so it never reads as a tag.

Raises:

• ValueError: a path in fields or order does not start with a field of its class.