Skip to content

Call another flow ​

Use load(ref) to find another flow, then await it to run it as a step inside your epic and get its return value.

Your flow loads a flow and awaits it; what you pass is checked first, the called flow runs with its own ctx, sessions and hooks, and its return value or exception comes backYour flow loads a flow and awaits it; what you pass is checked first, the called flow runs with its own ctx, sessions and hooks, and its return value or exception comes back

Load a flow and call it ​

Save this flow as .hmz/flows/shipped/__init__.py. It calls goal from the official flowverse (see Find and install flows) and review, a hidden flow in the same file:

python
from hmz.flows import (
    Agent,
    AgentCollection,
    Budget,
    EnvCollection,
    FlowContext,
    FlowParams,
    GoalCommandAgentMixin,
    LocalEnv,
    flow,
    load,
)


class Coder(Agent, GoalCommandAgentMixin): ...


class Agents(AgentCollection):
    coder: Coder


class Reviewers(AgentCollection):
    reviewer: Agent


class Envs(EnvCollection):
    workspace: LocalEnv


class Focus(FlowParams):
    focus: str = "bugs"


@flow(agents=Reviewers, envs=Envs, params=Focus, name="review", hidden=True)
async def review(
    task: str, *, agents: Reviewers, envs: Envs, params: Focus, ctx: FlowContext
) -> str:
    """Read the change and say what is wrong with it."""
    reviewer = agents["reviewer"]
    session = await reviewer.spawn()
    return await reviewer.run(
        f"Review the change for {params.focus}: {task}",
        session=session,
        env=envs["workspace"],
    )


@flow(agents=Agents, envs=Envs, params=FlowParams)
async def shipped(
    task: str, *, agents: Agents, envs: Envs, params: FlowParams, ctx: FlowContext
) -> str:
    """The task as a goal, then a review of the change."""
    goal = load("goal")
    await goal(
        task,
        agents={"worker": agents["coder"]},
        envs={},
        params=goal.expected_params(),
    )
    review = load(":review")
    return await review(
        task,
        agents={"reviewer": agents["coder"]},
        envs=envs,
        params=review.expected_params(focus="security"),
        budget=Budget(output_tokens=2000),
    )

Run it from the command line:

sh
hmz exec -f @local/shipped -a coder=claude/claude-haiku-4-5 -p budget.output_tokens=20000 "Add a discount code to checkout"

The output of hmz exec for the shipped flow: one turn taken inside goal, then a second conversation taken inside reviewThe output of hmz exec for the shipped flow: one turn taken inside goal, then a second conversation taken inside review

The first turn runs inside goal, the second inside review.

Pass these arguments when calling a flow:

ArgumentWhat to pass
taskThe task text for the called flow.
agentsA mapping from the called flow's role names to your agents.
envsA mapping from the called flow's role names to your environments.
paramsAn instance of the called flow's params class, or a mapping of values.
budgetOptional. A Budget for this call alone.

The called flow runs with its own ctx, sessions, and hooks, and cannot use a session you opened. If it raises an exception, you receive that exception unwrapped with its original class.

Read a flow object's attributes to inspect its declaration: description, expected_agents, expected_envs, expected_params, and resumable.

If a flow is defined in the same file, it is already a flow object. You can await review(...) directly without calling load.

Name the flow ​

Pass a flow ref to load. hmz exec -f accepts the same forms, except :review.

RefWhat it names
:reviewThe flow called review in the same module as the code calling load.
goalA flow by name.
humanize1:gen-planThe flow called gen-plan in the humanize1 module.
alice/kernelA flow the official flowverse lists under a user.
@local/shippedA flow of one flowverse only: @local, @user or @<flowverse>.
./flows/mine, /abs/path, ~/flows/mineA path. The first that exists of <path>/__init__.py, <path> and <path>.py is used. A relative path starts from the workspace directory.
git+https://github.com/humanfia/humanize1-flow@v0.1.0#humanize1:rlcrA repository, at the revision after @, in the directory after #. :<name> picks a flow there, with or without #<subdir>.

Humanize resolves a flow name beside the calling flow first: among the flows in the same directory as the calling flow, or among flows from the same flowverse if it was installed from one. Next, it checks @local, @user, official, and other flowverses alphabetically.

A ref without :<name> selects the flow named after the directory or file, or else the only non-hidden flow.

Use a git+ ref to run a flow without installing it. Supported URL schemes are https, http, ssh, file, and git. Omitting @<rev> uses the default branch, and omitting #<subdir> uses the repository's root. A flow that is one file is named by the file, as in #tools/review.py. load does not fetch the repository; Humanize clones it when you first call the flow or read a property like expected_params.

load raises these exceptions:

ExceptionWhen
FlowRefErrorThe text is not a ref, or :<name> is used where no flow is asking.
FlowNotFoundThe ref names no flow. For a git+ ref, this is raised when the repository is first fetched, if it cannot be.
FlowLoadConflictTwo flow directories that import under the same module name are loaded in one epic.
FlowDefinitionErrorThe named flow is written wrong, or importing it fails.

Pass agents and environments ​

Map the called flow's role names to your agents and environments. In the example above, your coder fills the worker role in goal and the reviewer role in review.

Every agent or environment you pass must meet the called role's declarations. Humanize checks requirements before the called flow starts, so a failed check runs and spends nothing.

The called role declaresRaised if what you pass falls short
A required roleMissingRole
A mixin, such as GoalCommandAgentMixinCapabilityMissing
A permissionPermissionTooNarrow
One harness, such as ClaudeCodeAgentHarnessMismatch
CPUs, memory or GPUsResourceUnmet
A LocalEnvCapabilityMissing, if the environment is not on this machine

All of these exceptions inherit from RequirementError. Passing an object that is not an agent or environment of the current epic raises RequirementError directly.

Your agent can only pass on capabilities that your own role declares. Because goal requires GoalCommandAgentMixin, Coder must declare it too. If coder is a plain Agent, Humanize refuses the call:

The output of hmz exec when the coder role is a plain Agent: CapabilityMissing, goal's worker needs GoalCommandAgentMixinThe output of hmz exec when the coder role is a plain Agent: CapabilityMissing, goal's worker needs GoalCommandAgentMixin

The called flow receives only what its own role declares: its mixins, permission, skills, tools, and command lines. It never receives extra capabilities held by your flow.

Names in a mapping that the called flow does not declare are ignored. You can omit roles that the run provides automatically. An omitted LocalEnv role receives the epic's directory, which lets envs={} work for goal. An omitted Outworlder role receives the epic's person. To answer for the person from your flow instead, see The person as an agent.

Pass params ​

Call expected_params on the loaded flow to build its params instance:

python
params=review.expected_params(focus="security")

Calling review.expected_params() with no arguments uses the defaults. You can also pass a plain mapping like {"focus": "security"}, which Humanize validates against the params class. Invalid values raise ParamsError before the called flow starts. See Params.

Give the call a budget ​

Pass budget=Budget(...) to cap what a single call can spend. Without budget=, the called flow uses your remaining budget. With budget=, both limits apply, and everything the called flow spends counts against your flow and the epic.

If the call exhausts its own budget, it raises BudgetExceeded, which you can catch to continue your flow. The budget argument must be a Budget or None, or the call raises TypeError. See Budgets in a flow.

In the app ​

Open the epic and look under Called flows in the Epic panel to see each call's task and state. On the graph, each agent is drawn in the flow that opened its first session: a called flow's box is labelled Called with the flow's ref.

The epic page in Humanize Desktop: the graph shows a box for the flow and one for the called goal flow, and the panel lists goal:goal and shipped:review under Called flowsThe epic page in Humanize Desktop: the graph shows a box for the flow and one for the called goal flow, and the panel lists goal:goal and shipped:review under Called flows

Good to know ​

  • Run several flow calls at once with asyncio.gather (see Concurrent turns).
  • A flow can call itself. Calls nest at most 64 flows deep, counting the flow the epic started with; one level deeper raises FlowDepthExceeded, which is a subclass of RecursionError.
  • Awaiting a flow outside an epic raises FlowRuntimeError. Calling a flow after your own call or the epic has finished raises FlowCancelled.
  • Within one epic, loading the same ref from the same module returns the same flow object, and a git+ URL at a given revision is fetched at most once.
  • When you resume an epic, a called flow resumes if called with the same task, agents, environments, and params (see Resumable flows).
  • In tests, called flows run against the same fakes as the caller (see Test a flow).

Open source on github.com/humanfia · RSS: blog · news