Python API: Specialist agents

Default agent recipes (researcher, writer, critic, ...) and a registry for your own. Generated from the docstrings and type hints of criogenai 0.1.7. See also: Python API overview, the same module in TypeScript.

Specialist agents: default recipes for common jobs that you configure, extend or replace.

from criogenai import specialists

agent = specialists.researcher.build("openai:gpt-5-mini", tools=[search])
careful = specialists.researcher.extend("careful-researcher", add="Always give two sources.")
specialists.register(careful)
specialists.get("careful-researcher")

A Specialist is a recipe, not an agent: a name, a description (what a coordinator reads to decide when to use it), instructions, and default agent settings. build makes the agent. The built-in ones are prompts and sensible defaults; tools come from you, and no claim is made about their quality on your data.

Built-in recipes, registered under their names and available as module attributes: researcher (web search and page reading when TAVILY_API_KEY or BRAVE_API_KEY is set and you give it no tools), summarizer, classifier, extractor, planner, writer, critic, fact_checker, code_reviewer, translator and support_agent.

from criogenai import specialists

specialists.Specialist(...)

These are used as specialists.<name>.

Contents#

Name	Kind	Summary
`Specialist`	class	A recipe for an agent: a name, a description, instructions and default `Agent` settings.
`register`	function	Keeps a recipe under its name, so patterns and configuration can refer to it by name.
`unregister`	function	Forgets a registered recipe; nothing happens if the name is not registered.
`get`	function	The recipe registered under `name`.
`available`	function	The registered names, sorted.

Specialist#

class Specialist:
    def __init__(self, name: str, description: str, instructions: str, **settings: Any)

A recipe for an agent: a name, a description, instructions and default Agent settings.

Use it to describe an agent once and build it with different models, or to give ~criogenai.patterns.coordinator and the other patterns a step by name (after register).

Parameters

name (str): Letters, digits, - and _, at most 64 characters.
description (str): What the agent is for, in one sentence; coordinators choose specialists by it. Must not be empty.
instructions (str): The agent's instructions (system prompt).
**settings (Any): Default Agent keyword arguments (tools, output, limits, approve, hooks, storage, memory, fallbacks, ...). Anything Agent does not accept fails when build runs.

Raises

ValueError: An invalid name or an empty description.

Example

from criogenai import FakeModel, specialists

triage = specialists.Specialist(
    "triage",
    "Sorts incoming tickets by team.",
    "Sort the ticket into billing, shipping or other. Reply with one word.",
)
agent = triage.build(FakeModel(["billing"]))
agent.run_sync("I was charged twice").text   # "billing"

Specialist.build#

def build(model: Any, **overrides: Any) -> Agent

Builds the agent from this recipe.

Parameters

model (Any): The agent's model (a model string such as "openai:gpt-5-mini" or a model object).
**overrides (Any): Agent keyword arguments that win over the recipe's settings. instructions= replaces the instructions and tools= replaces the tools (use extend to add tools).

Returns: A new Agent.

Example

from criogenai import specialists

agent = specialists.summarizer.build("openai:gpt-5-mini", limits={"model_calls": 2})
result = await agent.run(long_text)

Specialist.extend#

def extend(
    name: Optional[str] = None,
    *,
    add: Optional[str] = None,
    instructions: Optional[str] = None,
    description: Optional[str] = None,
    tools: Sequence[Any] = (),
    **settings: Any,
) -> 'Specialist'

A new recipe based on this one; this recipe is unchanged.

Parameters

name (Optional[str], default None): The new recipe's name. Default: "<this name>-extended".
add (Optional[str], default None): Text appended to the instructions.
instructions (Optional[str], default None): Replaces the instructions (add is then appended to these).
description (Optional[str], default None): Replaces the description.
tools (Sequence[Any], default ()): Tools added to the recipe's tools.
**settings (Any): Other Agent settings, overriding the recipe's.

Returns: The new Specialist (not registered: call register).

Example

from criogenai import specialists

careful = specialists.researcher.extend("careful-researcher", add="Always give two sources.")
specialists.register(careful)

register#

def register(specialist: Specialist, *, replace: bool = False) -> Specialist

Keeps a recipe under its name, so patterns and configuration can refer to it by name.

Parameters

specialist (Specialist): The recipe.
replace (bool, default False): True replaces a recipe registered under the same name. Default False.

Returns: The recipe, unchanged.

Raises

ValueError: The name is taken and replace is False.

Example

from criogenai import patterns, specialists

specialists.register(specialists.writer.extend("short-writer", add="At most 50 words."))
flow = patterns.quick("researcher > short-writer", model="openai:gpt-5-mini")

unregister#

def unregister(name: str) -> None

Forgets a registered recipe; nothing happens if the name is not registered.

The built-in recipes stay available as module attributes (e.g. specialists.writer), so they can be registered again.

Parameters

name (str): The registered name.

get#

def get(name: str) -> Specialist

The recipe registered under name.

Parameters

name (str): The registered name, e.g. "researcher".

Returns: The Specialist.

Raises

KeyError: No recipe has this name (the message lists the registered names).

available#

def available() -> List[str]

The registered names, sorted.