A workflow decorator turns a Python function into a managed workflow by attaching the configuration the platform needs to deploy and run it. The function expresses the application logic: it accepts keyword arguments, calls services, makes decisions, and returns a dictionary. HTTP handling and server configuration belong to the runtime, not the function. section 9.1.1 section 10.12
This separation helps move a prototype into production without embedding deployment machinery in business logic. Each workflow becomes an independently deployable service, with its own scaling, versioning, observability, and cost attribution. section 2.2.3 section 10.2
The decorator captures deployment and runtime settings as metadata:
- Identity and delivery: name, API path, and synchronous or asynchronous response mode. section 9.1.1 section 10.12
- Scaling: minimum and maximum replicas and CPU or optional memory utilization targets. section 9.1.1
- Resources and reliability: CPU, memory, optional GPU settings, timeout, and retry policy. section 9.1.1 section 10.12
Listing 9.1 A workflow function decorated with @workflow
from genai_platform import GenAIPlatform, workflow
@workflow(
name="patient_intake_assistant",
api_path="/patient-assistant",
response_mode="sync",
# Scaling
min_replicas=1, #A
max_replicas=10, #A
target_cpu_percent=70, #A
target_memory_percent=80, #A
# Resources
cpu="500m", #B
memory="512Mi", #B
gpu_type=None, #B
num_gpus=0, #B
# Reliability
timeout_seconds=30, #C
max_retries=3, #D
)
def handle_patient_question(question, patient_id):
platform = GenAIPlatform() #E
session = platform.sessions.get_or_create(
patient_id
)
safety = platform.guardrails.validate_input( #F
content=question,
checks=["healthcare_compliance"]
)
if not safety["allowed"]: #F
return {"response": safety["denial_reason"]} #F
relevant_info = platform.data.search(
index_name="patient_procedures",
query=question
)
context = "\n".join(
r.text for r in relevant_info
)
history, _ = platform.sessions.get_messages(
session.session_id
)
response = platform.models.chat(
model="gpt-4o",
system_prompt_name="patient_intake_assistant",
messages=[*history,
{"role": "user",
"content": f"Context:\n{context}"
f"\n\n{question}"}]
)
platform.sessions.add_messages(
session.session_id,
[{"role": "user", "content": question},
{"role": "assistant",
"content": response.content}]
)
return { #G
"response": response.content, #G
"sources": [r.document_id #G
for r in relevant_info] #G
} #GA patient intake workflow declares its deployment settings alongside the service calls and safety decisions it coordinates. section 9.1.1
The decorator implementation wraps the function and attaches its configuration as metadata. It rejects coroutine functions because the runtime executes workflows in worker threads; the wrapper itself delegates to the original function. section 9.1.1
Listing 9.2 @workflow decorator implementation
from functools import wraps
import asyncio
def workflow(
name, api_path, response_mode="sync",
min_replicas=1, max_replicas=10,
target_cpu_percent=70, target_memory_percent=None,
cpu="250m", memory="256Mi",
gpu_type=None, num_gpus=0,
timeout_seconds=30, max_retries=3
):
def decorator(func):
if asyncio.iscoroutinefunction(func): #A
raise TypeError( #A
f"Workflow '{name}' must be a" #A
f" regular function: the runtime" #A
f" server runs workflows in" #A
f" worker threads" #A
) #A
@wraps(func)
def wrapper(*args, **kwargs):
return func(*args, **kwargs) #B
wrapper._workflow_metadata = { #C
"name": name,
"api_path": api_path,
"response_mode": response_mode,
"scaling": {
"min_replicas": min_replicas,
"max_replicas": max_replicas,
"target_cpu_percent":
target_cpu_percent,
"target_memory_percent":
target_memory_percent
},
"resources": { #D
"cpu": cpu,
"memory": memory,
"gpu_type": gpu_type,
"num_gpus": num_gpus
},
"reliability": { #E
"timeout_seconds": timeout_seconds,
"max_retries": max_retries
}
}
return wrapper
return decoratorThe implementation shows the regular-function check, delegating wrapper, and metadata attachment. section 9.1.1
At deployment, the Workflow Service packages the code and runtime into a container, registers the route, and configures Kubernetes resources. A Deployment uses the replica floor and resource limits; an autoscaler adjusts replicas within the configured bounds. Health checks and rolling updates support continued operation, while the platform can roll back a version whose error rate rises significantly. section 9.7 section 10.12
Composing a research workflow
An asynchronous research workflow calls knowledge and web searches in parallel, then synthesizes their results. It returns a job ID for client polling rather than holding an HTTP connection open. Child workflows run in separate containers and scale independently; shared state remains in platform services. section 10.12
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)
}The research workflow combines asynchronous response mode with parallel child workflow calls and a synthesis step. section 10.12
