liveBook · Manning

Workflow decorator

As explained in Designing AI Systems

A workflow decorator is a function annotation that converts an ordinary function into a managed workflow process.

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
    }    #G

A 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 decorator

The 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

How Designing AI Systems covers it

How deep it goes
Implements a delegating wrapper and metadata attachment, then traces configuration through deployment and runtime management.
Examples
Uses a patient intake workflow, a single-model-call assistant, and parallel research workflows.
What you can do after
Apply it via the platform SDK to configure and deploy Python workflow endpoints.
How it connects
Connects workflow orchestration to autoscaling, container deployment, observability, and service composition.

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.