liveBook · Manning

Workflow composition

As explained in Designing AI Systems

Workflow composition is the pattern of building an application workflow by invoking other independently deployed workflows instead of duplicating their logic.

Workflow composition builds an application workflow by calling independently deployed workflows instead of copying their logic. A parent sends HTTP requests through the API gateway to child workflow paths. Each child retains its own container, dependencies, scaling, and team ownership; improvements to a child are available without updating a duplicate implementation. section 9.4

Figure 9.3 Workflow composition. A parent workflow ("Research Assistant") calls three child workflows through the API Gateway. The parent's container runs the orchestration logic: classify the ticket, call the knowledge search workflow, use the results to draft a response. Each child workflow runs in its own container pool with independent scaling, dependencies, and team ownership. The Document Search workflow has two replicas; the Summarization workflow has four replicas with higher resource limits. The API Gateway treats the parent's HTTP requests to child workflows identically to requests from external clients: same routing, same load balancing, same authentication. The parent does not know or care how many replicas each child has or what dependencies they use. It sends a request to an api_path and gets a result back.

The deployment diagram shows a parent calling independently scaled child workflows through the same gateway used by external clients. section 9.4

A parent can sequence calls when one result depends on another, or use call_parallel() with a list of path-and-body pairs for independent work. The list can be built dynamically from earlier results. Parallel calls use the same call() behavior, including retries and response-mode handling; a failure after retries propagates to the parent for handling. section 9.4.2

Listing 10.20 Workflow composition for complex tasks
@workflow(
    name="claw-research",
    api_path="/claw/research",
    response_mode="async"    #A
)
def research_task(
    topic: str,
    user_id: str,
    session_id: str
) -> dict:
    # Search multiple sources in parallel
    results = platform.workflows.call_parallel([    #B
        ("/claw/knowledge-search",    #B
         {"query": topic, "index": "company-knowledge"}),    #B
        ("/claw/knowledge-search",    #B
         {"query": topic, "index": "engineering-docs"}),    #B
        ("/claw/web-search",    #B
         {"query": topic})    #B
    ])    #B
 
    # Synthesize findings
    combined_context = merge_search_results(results)    #C
    synthesis = platform.models.chat(
        model="gpt-4o",
        system_prompt_name="claw-researcher",
        messages=[{
            "role": "user",
            "content": (
                f"Synthesize a research summary on: "
                f"{topic}\n\n{combined_context}"
            )
        }]
    )
 
    return {
        "summary": synthesis.content,
        "sources": extract_sources(results)
    }

This research workflow fans out searches across two knowledge indexes and the web, then merges and synthesizes the results. section 10.12

The SDK runs in the parent container and sends requests to the gateway, which routes them to child containers. For a 200 response, call() reads JSON or consumes a stream; for a 202 response, it polls the job until completion. This lets a child change from synchronous to asynchronous operation without changing its callers. section 9.4.3

Listing 9.19 HTTP retry logic for workflow-to-workflow calls
def _http_post(self, api_path, body):
    last_error = None
    for attempt in range(
        self._max_retries + 1    #A
    ):
        try:
            response = requests.post(
                f"{self._gateway_url}"
                f"{api_path}",
                json=body,
                headers=self._trace_headers()    #B
            )
            if response.status_code < 500:    #C
                return response
            last_error = WorkflowCallError(
                f"HTTP {response.status_code}"
            )
        except requests.ConnectionError as e:
            last_error = e
 
        if attempt < self._max_retries:
            delay = 0.1 * (2 ** attempt)    #D
            time.sleep(delay)
 
    raise last_error

The HTTP helper illustrates retries for server errors and connection failures, exponential backoff, and trace headers. section 9.4.3

Composition adds a network hop and gateway round trip for each child call. Prefer a single workflow when the logic is simple, dependencies are shared, and one team owns it. Code sequencing also leaves the dependency graph invisible to the platform: it cannot automatically checkpoint, retry individual steps, or display step-level progress. Complex pipelines may instead use an orchestrator such as Argo or Metaflow, with workflows as execution targets. section 9.4.3 section 9.4.2

How Designing AI Systems covers it

How deep it goes
Implements parallel calls, response-mode handling, and retries, while identifying the limits of implicit dependency graphs.
Examples
Uses a research assistant that searches multiple sources in parallel and synthesizes their results.
What you can do after
Apply it via the platform SDK to sequence or parallelize child workflow calls and handle their results.
How it connects
Connects HTTP APIs, API gateways, asynchronous jobs, retry logic, and workflow orchestration.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.