liveBook · Manning

Child workflow

As explained in Designing AI Systems

A child workflow is a workflow invoked by another workflow and executed as an independently managed deployment.

A child workflow is an independently deployed workflow invoked by a parent through the Workflow Service. The parent calls an API path and request body over the gateway, receives a result, and continues without sharing the child’s container, dependencies, scaling rules, retries, or deployment lifecycle. section 9.4.1

Treat workflow composition as a service boundary with explicit operational behavior:

  • Call platform.workflows.call(api_path, body) to send an HTTP POST through the gateway and receive a dictionary result. section 9.4.1
  • Hide response-mode differences behind one call interface: return JSON for synchronous children, poll job status for asynchronous children, and collect event-stream chunks for streaming children. section 9.4.3
  • Retry connection failures and 5xx responses with backoff, while allowing malformed 4xx requests to fail without retrying. section 9.4.3
  • Scale child workflows independently so bursts in specialized work do not starve the parent workflow. section 9.4.1 section 10.12

Parallel research composition

A research workflow can call knowledge-search twice and web-search once in parallel, merge the results, and send the combined context to a synthesis model. Running the research workflow asynchronously avoids holding an HTTP connection open during long retrieval tasks. section 10.12

Listing 9.15 Parent workflow calling a child workflow
@workflow(
    name="ticket_responder",
    api_path="/tickets/respond",
    response_mode="sync",
    timeout_seconds=30,
    max_retries=3
)
def respond_to_ticket(ticket_text, customer_id):
    platform = GenAIPlatform()
 
    category = platform.models.chat(    #A
        model="gpt-4o-mini",    #A
        messages=[{"role": "user",    #A
                   "content": f"Classify this"    #A
                              f" ticket:"    #A
                              f" {ticket_text}"}]    #A
    )    #A
 
    articles = platform.workflows.call(    #B
        "/knowledge/search",    #B
        {"query": ticket_text,    #B
         "category": category.content}    #B
    )    #B
    
    response = platform.models.chat(
        model="gpt-4o",
        messages=[{"role": "user",
                   "content": f"Draft a response"
                              f" to: {ticket_text}\n"
                              f"Articles:"
                              f" {articles['results']}"}]    #C
    )
 
    return {
        "response": response.content,
        "category": category.content,
        "sources": articles["sources"]
    }

Inspect the parent workflow pattern, including classification, a knowledge-search child call, and subsequent response generation. section 9.4.1

Listing 9.18 Routing a workflow call based on the child’s response mode
def call(self, api_path, body):
    response = self._http_post(    #A
        api_path, body
    )
 
    content_type = response.headers.get(
        "content-type", ""
    )
 
    if response.status_code == 200:    #B
        if "text/event-stream" in content_type:
            return self._consume_stream(
                response
            )
        return response.json()
 
    if response.status_code == 202:    #C
        job_id = response.json()["job_id"]
        return self._poll_until_complete(
            job_id
        )
    
    logger.error(    #D
        "child workflow %s returned %s: %s",    #D
        api_path, response.status_code,    #D
        response.text    #D
    )    #D
    raise WorkflowCallError(    #D
        f"Child workflow {api_path} failed"
        f" with status {response.status_code}"
    )

Trace how one call method routes synchronous, asynchronous, and streaming child responses. section 9.4.3

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)
    }

Compare parallel child calls, result merging, and synthesis in a production-oriented research workflow. section 10.12

How Designing AI Systems covers it

How deep it goes
Explains invocation, response normalization, polling, streaming, retries, and parallel composition, but does not detail deployment configuration.
Examples
Uses ticket response with knowledge search and parallel research across knowledge bases and web search.
What it assumes
Assumes familiarity with HTTP status codes, JSON responses, API gateways, and workflow response modes.
What you can do after
Build workflow compositions that invoke, retry, poll, stream, and parallelize independently deployed child workflows.
How it connects
Connects workflow composition with the Workflow Service, API gateway, asynchronous processing, streaming, retries, autoscaling, and fan-out/fan-in.

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.