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
