Make Flow-Level Context Arguments Explicit and Opt-in

[jlowin]

Enhancement Description

Currently, when arguments are passed to a @cf.flow method, they are implicitly added to a flow-wide context, making them available to all tasks within that flow. While this allows for convenient sharing of context between tasks, it can result in redundancy and confusion, especially when certain arguments are only relevant at the flow level and not to individual tasks. For example, arguments passed to the flow can show up twice in the agent’s context, once as a flow argument and again if explicitly passed as a task context.

This implicit behavior has led to cases where users have to work around it by defining their @cf.flow as an inner method or explicitly managing the task context. As a result, the implicit context addition can feel too “magical” and can cause unintended token usage increases in LLM interactions.

Use Case

No response

Proposed Implementation

• Make flow-level context arguments explicit and opt-in.
• Introduce a way to mark which arguments should be passed to the context, either via a special flow argument or an explicit decorator instruction.

Two potential solutions:

1. Add a flow_context (or similar) keyword argument:
   Allow users to specify which arguments should be added to the context when calling a flow.

@cf.flow
def process_email(email_history: EmailHistory, config_param: str):
   cf.run(..., context=dict(email_history=email_history))

This way, only explicitly defined arguments (e.g., via context={...}) are passed, avoiding automatic duplication.

2. Add a @flow(context_kwargs=['x', 'z']) decorator feature:
   Allow users to declare which arguments should automatically be added to the flow context at the decorator level.

   @cf.flow(context_kwargs=['x', 'z'])
   def demo(x, y, z):
       # x and z are automatically added to context, y is not

We are leaning strongly toward option 2, as it permits the full argument convention while remaining explicit and opt-in