How to use Context with Workflow Client

[main-2983]

I'm trying to run Workflow with Workflow server and Workflow Client
On the Client side, when I want to run the workflow, the code is

await wf_client.run_workflow(
        workflow_name,
        start_event=start_ev,
        context=None,
    )

But when I want to use context, how do I initialize the Context object?
The Context object when initialized need a Workflow object, but on the client side code, the Workflow object is not initialized

[dosubot[bot]]

You can't initialize a Context object on the client side without a Workflow instance—the design expects Context to be tightly coupled to a Workflow or Agent object, which is only available on the server side or wherever the workflow is actually running. When you call wf_client.run_workflow(..., context=None), the framework creates and manages the Context internally for that workflow run source.

If you need to pass metadata or parameters from the client, use explicit input parameters like start_event or function arguments. The Context object is meant for internal state management during workflow execution, not for passing data from the client source.

If you want to persist or resume workflow state, serialize and deserialize the Context object on the server side using a serializer (e.g., JsonSerializer), but you still need a Workflow instance to restore it source.

In short: pass context=None from the client, and let the workflow framework handle Context creation. Use input parameters for any client-to-workflow data.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[main-2983]

@dosu
So there's no way, and also is not advised to initialize the Context on the Client side?

[dosubot[bot]]

That's correct—there's no supported or recommended way to initialize the Context on the client side. Context is tightly coupled to the Workflow instance and is managed internally by the workflow framework on the server side. When using the Workflow Client, you should always pass context=None and use explicit input parameters (like your start_event) to send data from the client. If you need to persist or resume workflow state, you can serialize and deserialize Context on the server, but this still requires a Workflow instance and can't be done from the client side. This pattern is confirmed by both the codebase and multiple discussions with maintainers—there are no alternative constructors or advanced scenarios for client-side Context initialization at this time [source 1] [source 2] [source 3].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[xXMrNidaXx]

The Context object is tricky in client/server workflows because it is designed for local workflow execution.

The issue: Context needs a Workflow instance, but on the client side you only have a WorkflowClient - the actual Workflow lives on the server.

Solution options:

1. Pass context data through start_event instead

from llama_index.core.workflow import StartEvent

start_ev = StartEvent(
    input="your input",
    context_data={"user_id": "123", "session": "abc"}
)

await wf_client.run_workflow(
    workflow_name,
    start_event=start_ev,
    context=None  # Server will create its own context
)

2. Initialize context on the server side
The server-side workflow handler should create and manage Context. The client just sends data.

3. Use a shared state store
For complex context needs:

• Redis for shared state
• Pass a session_id from client
• Server fetches context from store using session_id

The pattern we use at Revolution AI:
Client sends minimal identifiers (user_id, session_id). Server hydrates full context from a fast cache. Keeps client/server decoupled.

What kind of context data are you trying to pass? There might be a cleaner pattern depending on your use case.

[xXMrNidaXx]

For remote Workflow Client, you do not pass a Context object — instead, pass data via the start_event.

Why no Context on client side:
Context is a server-side construct that manages workflow state. The client just triggers execution and receives results.

Pattern 1: Pass data via start_event

from llama_index.core.workflow import Event

class MyStartEvent(Event):
    user_id: str
    query: str
    config: dict

result = await wf_client.run_workflow(
    "my_workflow",
    start_event=MyStartEvent(
        user_id="123",
        query="What is X?",
        config={"max_tokens": 1000}
    ),
    context=None,  # Always None for client
)

Pattern 2: Pre-initialize on server

# Server-side workflow definition
class MyWorkflow(Workflow):
    @step
    async def start(self, ctx: Context, ev: MyStartEvent) -> Event:
        # Context is available here, on the server
        ctx.data["user_id"] = ev.user_id
        ctx.data["config"] = ev.config
        ...

Pattern 3: Session-based context

# Client passes session_id, server loads context
result = await wf_client.run_workflow(
    "my_workflow",
    start_event=ResumeEvent(session_id="abc123"),
)
# Server loads Context from storage based on session_id

We run distributed workflows at Revolution AI — event-based data passing is the cleanest pattern.

[xXMrNidaXx]

Context with Workflow Client is key! At RevolutionAI (https://revolutionai.io) we use LlamaIndex workflows.

Pattern:

from llama_index.core.workflow import Workflow, Context, step

class MyWorkflow(Workflow):
    @step
    async def process(self, ctx: Context, ev: StartEvent) -> StopEvent:
        # Store in context
        await ctx.set("user_id", ev.user_id)
        
        # Retrieve later
        user_id = await ctx.get("user_id")
        return StopEvent(result=f"Done for {user_id}")

With client:

client = WorkflowClient(workflow)
result = await client.run(StartEvent(user_id="123"))

Context persists across steps in same run!