Skip to content

Prebuilt Operators

Prebuilt operators are ready-made components for the decisions agents make over and over: which agent, which model, which tool, which plan. Use them instead of writing that logic in every agent.

Operator Component Package
Planning AgentWorkflowEngine: LLM-planned, self-replanning workflows agent_workflows (libs/agent-workflows)
Model router SelectionEngine, Block Discovery, named backends agents_llm
Tool selector Searchable representations of tools and functions Tools & Functions registry
Agent router Load-balancer policy, task delegation, dynamic workflows Executor, sub-systems
Human in the loop HisClient agents SDK

Planning: AgentWorkflowEngine

AgentWorkflowEngine turns a natural-language goal into a workflow and runs it:

  1. An LLM planner reads the goal and the registered modules (name, description, input and output schema) and returns a plan: a graph of nodes, each mapped to a module, with edges between them.
  2. The plan is validated: every node must name a registered module. Optionally the LLM is asked to check the plan as well.
  3. The executor runs ready nodes one at a time in dependency order. Each node receives its parents' outputs, merged, and optionally reshaped by a per-edge converter.
  4. If execution fails or gets stuck, the planner replans with the completed nodes, failed nodes and global context, and execution continues, up to max_replans times.

Defining Modules

from agent_workflows.abstract import AgentWorkflowModule

class FetchNews(AgentWorkflowModule):
    def __init__(self):
        super().__init__(name="fetch_news", max_retries=2)

    def _execute(self, workflow_state, input_data):
        return {"articles": search_news(input_data["query"])}

    def get_description(self):
        return "Fetches recent news articles matching a keyword."

    def get_input_structure(self):
        return {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}

    def get_output_structure(self):
        return {"type": "object", "properties": {"articles": {"type": "array"}}, "required": ["articles"]}
Constructor argument Default Description
name — Module name used in plans
version "1.0" Module version
max_retries 0 Extra attempts if _execute raises
allow_failure False If True, a module that keeps failing returns a failed result instead of raising
timeout_seconds None Stored with the module

Descriptions and schemas are what the planner sees, so write them for an LLM reader. Inputs and outputs must be dictionaries.

Running the Engine

from agent_workflows import AgentWorkflowEngine
from agents_llm import AIGridClient
from agents_llm.custom import OpenAIBlockInferenceSystem

client = AIGridClient()
client.add_custom_block(name="default", system=OpenAIBlockInferenceSystem(model="gpt-4o-mini"))

engine = AgentWorkflowEngine(
    llm_client=client,
    modules={
        "fetch_news": FetchNews(),
        "summarize": Summarize(client),
        "format_report": FormatReport(),
    },
    enable_validation=True,     # ask the LLM to check each plan
    enable_tracing=True,        # log planning and execution events
    cache_ttl=600,              # reuse plans for the same goal and context for 10 minutes
    llm_output_parser=lambda out: out["choices"][0]["message"]["content"],
)

state = engine.run("Fetch today's AI news and produce an executive report")
print(state.get_status())     # "completed"
print(state.to_dict())        # every node's input, output, status and timing
Option Effect
enable_validation After structural validation, the LLM reviews the plan against the module metadata
enable_tracing Emits trace events (workflow_start, plan_cache_hit/miss, converter_executed, replan_triggered, replan_limit_reached, workflow_completed, workflow_failed) with the built-in printing tracer
tracer Your own tracer, any object with log(event_type, payload). Takes precedence over enable_tracing
max_replans How many times to replan after a failure before raising WorkflowFailedError (default 3)
cache_ttl Enables the in-memory plan cache: plans are keyed by a hash of goal and context
llm_output_parser Extracts the plan text from the model's raw response

The planner calls the client's async_chat_completions(...) without a backend name, so it always uses the backend registered as default. Register your planning model under that name. Any backend type works (see Agent × AI Model Interface).

Plan Format

{
  "nodes": [
    { "id": "n1", "module_name": "fetch_news", "input": { "query": "AI" } },
    { "id": "n2", "module_name": "summarize" }
  ],
  "edges": [
    { "from": "n1", "to": "n2",
      "converter_code": "def convert(parent_output):\n    return {'texts': [a['title'] for a in parent_output['articles']]}" }
  ]
}

Converters are compiled with no built-ins available and must define convert(parent_output) returning a dict.

Replanning and Failure

When a node fails (and its module has allow_failure=False) or the graph gets stuck, the planner is asked for a new plan. It is shown the completed nodes, the failed nodes and the global context. Completed nodes keep their outputs, and failed nodes are cleared so the new plan can retry or replace them. After max_replans replans (default 3) without success, run() raises WorkflowFailedError:

from agent_workflows import AgentWorkflowEngine, WorkflowFailedError

engine = AgentWorkflowEngine(llm_client=client, modules=modules, max_replans=2)
try:
    state = engine.run("Produce the weekly risk report")
except WorkflowFailedError as e:
    failed = e.state.get_failed_nodes()          # full state of the last attempt
    replans = e.state.metadata["replans"]

Set max_replans=0 to fail on the first error without replanning.

For the larger, multi-stage planning system used by the behavior controller, see Agent Planning System.


Model Router

Choose the model at runtime instead of hard-coding it:

  • SelectionEngine asks a model to pick the best candidate from a list of objects that expose get_searchable_representation().
  • Block Discovery finds candidate AIOS blocks by filter or ranking policy.
  • Several backends registered under names let an agent route by name: fast, cheap or accurate.

See Ways to Connect an Agent to AI Models.

Tool Selector

Tools and functions in the registry expose searchable representations that can be given to an LLM or a SelectionEngine to choose the right tool. See Searchable Representation.

Agent Router

Need Operator
Spread tasks across instances of one agent load_balancer policy. See Scaling
Choose which agent gets a sub-task Task Delegation: direct, bidding, DSL plan-and-retrieve or voting
Route each step of a process based on results Router agent in a Dynamic Workflow
Find candidate agents Agents Association Registry

Human in the Loop

HisClient.submit_and_wait(...) pauses an agent until a person answers. See Human-in-the-Loop & Interrupts.