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:
- 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.
- The plan is validated: every node must name a registered module. Optionally the LLM is asked to check the plan as well.
- 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.
- If execution fails or gets stuck, the planner replans with the completed nodes, failed nodes and global context, and execution continues, up to
max_replanstimes.
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:
SelectionEngineasks a model to pick the best candidate from a list of objects that exposeget_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.