Rework arguments to models.stream and Agents.run

README.md

@@ -38,7 +38,7 @@ async def main() -> None:
         ai.user_message("What's the weather in Tokyo?"),
     ]
 
-    async with agent.run(model, messages) as stream:
+    async with agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.TextDelta):
                 print(event.chunk, end="", flush=True)
@@ -107,7 +107,7 @@ Override the default loop when you need approval gates, routing, or custom orche
 @agent.loop
 async def custom(context: ai.Context):
     while True:
-        async with ai.stream(context.model, context.messages, tools=context.tools) as s:
+        async with ai.stream(context) as s:
             async for event in s:
                 yield event
             context.add(s.message)

examples/fastapi-vite/backend/agent.py

@@ -36,7 +36,7 @@ async def talk_to_mothership(question: str) -> ai.SubAgentTool:
         ai.system_message(MOTHERSHIP_SYSTEM),
         ai.user_message(question),
     ]
-    async with mothership.run(MOTHERSHIP_MODEL, messages) as stream:
+    async with mothership.run(model=MOTHERSHIP_MODEL, messages=messages) as stream:
         async for event in stream:
             yield event
 
@@ -56,9 +56,7 @@ async def graph(context: ai.Context) -> AsyncGenerator[ai.events.AgentEvent]:
     Reject buttons and sends the decision back on the next request.
     """
     while context.keep_running():
-        async with ai.models.stream(
-            context.model, context.messages, tools=context.tools
-        ) as s:
+        async with ai.models.stream(context) as s:
             async for event in s:
                 yield event
         context.add(s.message)

examples/fastapi-vite/backend/main.py

@@ -63,7 +63,9 @@ async def chat(request: ChatRequest) -> fastapi.responses.StreamingResponse:
     ai.agents.ui.ai_sdk.apply_approvals(approvals)
 
     async def stream_response() -> AsyncGenerator[str]:
-        async with agent_.chat_agent.run(agent_.MODEL, messages) as result:
+        async with agent_.chat_agent.run(
+            model=agent_.MODEL, messages=messages
+        ) as result:
             async for chunk in ai.agents.ui.ai_sdk.to_sse(result):
                 yield chunk
 

examples/multiagent-textual/server.py

@@ -110,7 +110,7 @@ def _gated_agent(
     async def gated_loop(context: ai.Context) -> AsyncGenerator[ai.events.AgentEvent]:
         while context.keep_running():
             async with (
-                ai.stream(context.model, context.messages, tools=context.tools) as s,
+                ai.stream(context) as s,
                 ai.agents.ToolRunner() as tr,
             ):
                 async for event in ai.util.merge(s, tr.events()):
@@ -158,8 +158,8 @@ async def multiagent_loop(context: ai.Context) -> AsyncGenerator[ai.events.Agent
     # carrying the branch label, so the TUI can route to the right panel.
     async with (
         mothership_agent.run(
-            context.model,
-            [
+            model=context.model,
+            messages=[
                 ai.system_message(
                     "You are assistant 1. Use contact_mothership "
                     "when asked about the future."
@@ -168,8 +168,8 @@ async def multiagent_loop(context: ai.Context) -> AsyncGenerator[ai.events.Agent
             ],
         ) as mothership_stream,
         data_centers_agent.run(
-            context.model,
-            [
+            model=context.model,
+            messages=[
                 ai.system_message(
                     "You are assistant 2. Use contact_data_centers "
                     "when asked about the future."
@@ -198,8 +198,8 @@ async def multiagent_loop(context: ai.Context) -> AsyncGenerator[ai.events.Agent
     # panel as its default.
     summary_agent = ai.agent()
     async with summary_agent.run(
-        context.model,
-        [
+        model=context.model,
+        messages=[
             ai.system_message(
                 "You are assistant 3. Summarise the results from the other assistants."
             ),
@@ -263,7 +263,7 @@ async def read_resolutions() -> None:
 
     try:
         async with orchestrator.run(
-            MODEL, [ai.user_message("When will the robots take over?")]
+            model=MODEL, messages=[ai.user_message("When will the robots take over?")]
         ) as result:
             async for event in result:
                 data = _normalise_event(event.model_dump())

examples/samples/agent_custom_loop.py

@@ -27,9 +27,7 @@ async def default_loop(
         """Stream, execute tools with logging, repeat."""
         while context.keep_running():
             async with (
-                ai.models.stream(
-                    context.model, context.messages, tools=context.tools
-                ) as stream,
+                ai.models.stream(context) as stream,
                 ai.ToolRunner() as tr,
             ):
                 async for event in ai.util.merge(stream, tr.events()):
@@ -55,8 +53,10 @@ async def main() -> None:
     my_agent = CustomAgent(tools=tools)
 
     async with my_agent.run(
-        model,
-        [ai.user_message("Compare the weather and population of New York and Tokyo.")],
+        model=model,
+        messages=[
+            ai.user_message("Compare the weather and population of New York and Tokyo.")
+        ],
     ) as stream:
         async for event in stream:
             if (

examples/samples/agent_hooks.py

@@ -70,7 +70,7 @@ async def with_approval(
     ) -> AsyncGenerator[ai.events.AgentEvent]:
         while context.keep_running():
             async with (
-                ai.stream(context.model, context.messages, tools=context.tools) as s,
+                ai.stream(context) as s,
                 ai.ToolRunner() as tr,
             ):
                 async for event in ai.util.merge(s, tr.events()):
@@ -92,7 +92,7 @@ async def with_approval(
         ai.user_message("When will the robots take over?"),
     ]
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/agent_hooks_inline.py

@@ -46,7 +46,7 @@ async def with_approval(
     ) -> AsyncGenerator[ai.events.AgentEvent]:
         while context.keep_running():
             async with (
-                ai.stream(context.model, context.messages, tools=context.tools) as s,
+                ai.stream(context) as s,
                 ai.ToolRunner() as tr,
             ):
                 async for event in ai.util.merge(s, tr.events()):
@@ -84,7 +84,7 @@ async def with_approval(
         ai.user_message("When will the robots take over?"),
     ]
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/agent_hooks_serverless.py

@@ -47,9 +47,7 @@ async def with_confirmation(
         context: ai.Context,
     ) -> AsyncGenerator[ai.events.AgentEvent]:
         while context.keep_running():
-            async with ai.models.stream(
-                context.model, context.messages, tools=context.tools
-            ) as s:
+            async with ai.models.stream(context) as s:
                 async for event in s:
                     yield event
 
@@ -93,7 +91,7 @@ async def with_confirmation(
     print("--- Run 1: hook fires, no resolution, run suspends ---")
     pending_hook_labels: list[str] = []
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             # HACK?: When we get a complete assistant message, add it to
             # messages so it can get replayed easily.
@@ -120,7 +118,7 @@ async def with_confirmation(
     for label in pending_hook_labels:
         ai.resolve_hook(label, Confirmation(approved=True, reason="user approved"))
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/agent_nested.py

@@ -30,7 +30,7 @@ async def research(topic: str) -> ai.SubAgentTool:
         ai.user_message(f"Research: {topic}"),
     ]
 
-    async with researcher.run(model, messages) as stream:
+    async with researcher.run(model=model, messages=messages) as stream:
         async for event in stream:
             yield event
 
@@ -45,7 +45,7 @@ async def main() -> None:
         ai.user_message("Tell me about Mars."),
     ]
 
-    async with orchestrator.run(model, messages) as stream:
+    async with orchestrator.run(model=model, messages=messages) as stream:
         async for event in stream:
             # Subtool results
             if isinstance(event, ai.events.PartialToolCallResult):

examples/samples/agent_simple.py

@@ -21,7 +21,7 @@ async def main() -> None:
         ai.user_message("What's the weather in Tokyo?"),
     ]
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/builtin_web_search.py

@@ -48,7 +48,7 @@ def format(value: object) -> str:
 
 
 async def main() -> None:
-    async with ai.stream(model, messages, tools=tools) as s:
+    async with ai.stream(model=model, messages=messages, tools=tools) as s:
         async for event in s:
             match event:
                 case ai.events.TextDelta():

examples/samples/builtin_web_search_gateway.py

@@ -40,8 +40,8 @@ def format(value: object) -> str:
 async def main() -> None:
     print("anthropic web search")
     async with ai.stream(
-        model,
-        messages,
+        model=model,
+        messages=messages,
         tools=[ai.anthropic.tools.web_search(max_uses=3)],
     ) as s:
         async for event in s:
@@ -59,8 +59,8 @@ async def main() -> None:
 
     print("perplexity web search")
     async with ai.stream(
-        model,
-        messages,
+        model=model,
+        messages=messages,
         tools=[ai.ai_gateway.tools.perplexity_search(max_results=5)],
     ) as s:
         async for event in s:

examples/samples/explicit_client.py

@@ -19,7 +19,7 @@
 
 async def main() -> None:
     try:
-        async with ai.stream(model, messages) as s:
+        async with ai.stream(model=model, messages=messages) as s:
             async for event in s:
                 if isinstance(event, ai.events.TextDelta):
                     print(event.chunk, end="", flush=True)

examples/samples/inline_image.py

@@ -25,7 +25,7 @@
 async def main() -> None:
     # Stream — text deltas arrive as TextDelta events, generated images
     # arrive as FileEvent events and accumulate on s.message.
-    async with ai.stream(model, messages) as s:
+    async with ai.stream(model=model, messages=messages) as s:
         async for event in s:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/mcp_tools.py

@@ -24,7 +24,7 @@ async def main() -> None:
         ai.user_message("How do I create middleware in Next.js?"),
     ]
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/middleware_simple.py

@@ -120,7 +120,9 @@ async def main() -> None:
     ]
 
     print("--- starting agent run ---\n")
-    async with my_agent.run(model, messages, middleware=[PrintMiddleware()]) as stream:
+    async with my_agent.run(
+        model=model, messages=messages, middleware=[PrintMiddleware()]
+    ) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/model_params.py

@@ -19,7 +19,7 @@ async def main() -> None:
         GatewayParams(sort="cost"),
         AnthropicParams(speed="fast"),
     ]
-    async with ai.stream(model, messages, params=params) as stream:
+    async with ai.stream(model=model, messages=messages, params=params) as stream:
         async for event in stream:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/multimodal_input.py

@@ -19,7 +19,7 @@
 
 
 async def main() -> None:
-    async with ai.stream(model, messages) as s:
+    async with ai.stream(model=model, messages=messages) as s:
         async for event in s:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/stream.py

@@ -13,7 +13,7 @@
 
 
 async def main() -> None:
-    async with ai.stream(model, messages) as s:
+    async with ai.stream(model=model, messages=messages) as s:
         async for event in s:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/samples/stream_all.py

@@ -27,7 +27,7 @@ async def _run(name: str, provider: ai.Provider[Any], model_id: str) -> None:
     model = provider(model_id)
 
     try:
-        async with ai.stream(model, messages) as s:
+        async with ai.stream(model=model, messages=messages) as s:
             async for event in s:
                 if isinstance(event, ai.events.TextDelta):
                     print(event.chunk, end="", flush=True)

examples/samples/streaming_tool.py

@@ -35,7 +35,7 @@ async def main() -> None:
         ai.user_message("When will the robots take over?"),
     ]
 
-    async with my_agent.run(model, messages) as stream:
+    async with my_agent.run(model=model, messages=messages) as stream:
         async for event in stream:
             if isinstance(event, ai.events.PartialToolCallResult):
                 print(f"  [{event.value}]")

examples/samples/tools_schema.py

@@ -27,7 +27,7 @@
 
 async def main() -> None:
     # Stream with tools — the model may emit tool calls.
-    async with ai.stream(model, messages, tools=[get_weather]) as s:
+    async with ai.stream(model=model, messages=messages, tools=[get_weather]) as s:
         async for event in s:
             if isinstance(event, ai.events.TextDelta):
                 print(event.chunk, end="", flush=True)

examples/temporal-direct/main.py

@@ -107,7 +107,7 @@ async def llm_call_activity(params: LLMParams) -> LLMResult:
         for t in params.tool_schemas
     ]
 
-    async with ai.models.stream(model, messages, tools=tools) as s:
+    async with ai.models.stream(model=model, messages=messages, tools=tools) as s:
         async for _event in s:
             pass
         if s.message is None:
@@ -187,7 +187,7 @@ async def run(self, user_query: str) -> str:
         ]
 
         final_text = ""
-        async with weather_agent.run(model, messages) as stream:
+        async with weather_agent.run(model=model, messages=messages) as stream:
             async for event in stream:
                 if isinstance(event, ai.events.TerminalEvent):
                     final_text = event.message.text

examples/temporal-middleware/main.py

@@ -124,7 +124,7 @@ async def llm_call_activity(params: LLMParams) -> LLMResult:
         for t in params.tool_schemas
     ]
 
-    async with ai.models.stream(model, messages, tools=tools) as s:
+    async with ai.models.stream(model=model, messages=messages, tools=tools) as s:
         async for _event in s:
             pass
         if s.message is None:
@@ -250,7 +250,9 @@ async def run(self, user_query: str) -> str:
         mw = TemporalMiddleware(tool_schemas)
 
         final_text = ""
-        async with weather_agent.run(model, messages, middleware=[mw]) as stream:
+        async with weather_agent.run(
+            model=model, messages=messages, middleware=[mw]
+        ) as stream:
             async for event in stream:
                 if isinstance(event, ai.events.TerminalEvent):
                     final_text = event.message.text