fixing merge

Author: RoxyFarhad

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.0"
+  ".": "0.5.1"
 }

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.5.1 (2025-10-29)
+
+Full Changelog: [v0.5.0...v0.5.1](https://github.com/scaleapi/agentex-python/compare/v0.5.0...v0.5.1)
+
+### Bug Fixes
+
+* **client:** close streams without requiring full consumption ([f56acae](https://github.com/scaleapi/agentex-python/commit/f56acae74ee83a116e735ca7bf68f2096aafaf6e))
+
 ## 0.5.0 (2025-10-28)
 
 Full Changelog: [v0.4.28...v0.5.0](https://github.com/scaleapi/agentex-python/compare/v0.4.28...v0.5.0)

examples/tutorials/00_sync/000_hello_acp/README.md

@@ -1,8 +1,44 @@
 # [Sync] Hello ACP
 
 This is a simple AgentEx agent that just says hello and acknowledges the user's message to show which ACP methods need to be implemented for the sync ACP type.
-It is a SYNC agent.
+The simplest agent type: synchronous request/response pattern with a single `@acp.on_message_send` handler. Best for stateless operations that complete immediately.
 
-## Official Documentation
+## What You'll Learn
+- Building a basic synchronous agent
+- The `@acp.on_message_send` handler pattern
+- When to use sync vs agentic agents
 
-[000 Hello ACP](https://dev.agentex.scale.com/docs/tutorials/sync/000_hello_acp)
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository (agentex) root
+
+## Quick Start
+
+```bash
+cd examples/tutorials/00_sync/000_hello_acp
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Code
+
+```python
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    return TextContent(
+        author="agent",
+        content=f"Echo: {params.content.content}"
+    )
+```
+
+That's it - one handler, immediate response. No task creation, no state management.
+
+## When to Use
+- Simple chatbots with no memory requirements
+- Quick Q&A or information lookup agents
+- Prototyping and testing agent responses
+- Operations that complete in under a second
+
+## Why This Matters
+Sync agents are the simplest way to get started with AgentEx. They're perfect for learning the basics and building stateless agents. Once you need conversation memory or task tracking, you'll graduate to agentic agents.
+
+**Next:** [010_multiturn](../010_multiturn/) - Add conversation memory to your agent

examples/tutorials/00_sync/010_multiturn/README.md

@@ -1,7 +1,54 @@
 # [Sync] Multiturn
 
-This tutorial demonstrates how to handle multiturn conversations in AgentEx agents using the Agent 2 Client Protocol (ACP).
+Handle multi-turn conversations in synchronous agents by manually maintaining conversation history and context between messages.
 
-## Official Documentation
+## What You'll Learn
+- How to handle conversation history in sync agents
+- Building context from previous messages
+- The limitations of stateless multiturn patterns
 
-[010 Multiturn](https://dev.agentex.scale.com/docs/tutorials/sync/010_multiturn)
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of basic sync agents (see [000_hello_acp](../000_hello_acp/))
+
+## Quick Start
+
+```bash
+cd examples/tutorials/00_sync/010_multiturn
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Pattern
+
+Sync agents are stateless by default. To handle multi-turn conversations, you need to:
+1. Accept conversation history in the request
+2. Maintain context across messages
+3. Return responses that build on previous exchanges
+
+```python
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    # Accept conversation history from client
+    history = params.conversation_history
+
+    # Build context from history
+    context = build_context(history)
+
+    # Generate response considering full context
+    response = generate_response(params.content, context)
+
+    return TextContent(author="agent", content=response)
+```
+
+The handler accepts history, builds context, and returns responses that reference previous exchanges.
+
+## When to Use
+- Simple chatbots that need conversation memory
+- When client can maintain and send conversation history
+- Quick prototypes before building full agentic agents
+
+## Why This Matters
+While sync agents can handle conversations, you're responsible for managing state on the client side. This becomes complex quickly. For production conversational agents, consider agentic agents ([10_agentic/00_base/010_multiturn](../../10_agentic/00_base/010_multiturn/)) where the platform manages state automatically.
+
+**Next:** [020_streaming](../020_streaming/) - Stream responses in real-time

examples/tutorials/00_sync/010_multiturn/project/acp.py

@@ -1,14 +1,17 @@
 import os
 from typing import Union, AsyncGenerator
 
+from agents import Agent, Runner, RunConfig
+
 from agentex.lib import adk
 from agentex.types import TextContent
 from agentex.lib.types.acp import SendMessageParams
+from agentex.lib.types.converters import convert_task_messages_to_oai_agents_inputs
 from agentex.lib.utils.model_utils import BaseModel
-from agentex.lib.types.llm_messages import LLMConfig, UserMessage, SystemMessage, AssistantMessage
 from agentex.lib.sdk.fastacp.fastacp import FastACP
 from agentex.types.task_message_update import TaskMessageUpdate
 from agentex.types.task_message_content import TaskMessageContent
+from agentex.lib.adk.providers._modules.sync_provider import SyncStreamingProvider
 
 # Create an ACP server
 acp = FastACP.create(
@@ -66,21 +69,27 @@ async def handle_message_send(
     task_messages = await adk.messages.list(task_id=params.task.id)
 
     #########################################################
-    # 3. Convert task messages to LLM messages.
+    # 3. Run the agent with OpenAI Agents SDK
     #########################################################
 
-    # This might seem duplicative, but the split between TaskMessage and LLMMessage is intentional and important.
+    # Initialize the provider and run config to allow for tracing
+    provider = SyncStreamingProvider(
+        trace_id=params.task.id,
+    )
+
+    run_config = RunConfig(
+        model_provider=provider,
+    )
+
+    # Initialize the agent
+    test_agent = Agent(name="assistant", instructions=state.system_prompt, model=state.model)
+
+    # Convert task messages to OpenAI Agents SDK format
+    input_list = convert_task_messages_to_oai_agents_inputs(task_messages)
+
+    # Run the agent
+    result = await Runner.run(test_agent, input_list, run_config=run_config)
 
-    llm_messages = [
-        SystemMessage(content=state.system_prompt),
-        *[
-            UserMessage(content=getattr(message.content, "content", ""))
-            if getattr(message.content, "author", None) == "user"
-            else AssistantMessage(content=getattr(message.content, "content", ""))
-            for message in task_messages
-            if getattr(message.content, "type", None) == "text"
-        ],
-    ]
 
     # TaskMessages are messages that are sent between an Agent and a Client. They are fundamentally decoupled from messages sent to the LLM. This is because you may want to send additional metadata to allow the client to render the message on the UI differently.
 
@@ -94,25 +103,7 @@ async def handle_message_send(
     #   - If using multiple LLMs, but one LLM's output should not be sent to the user (i.e. a critic model), you can leverage the State as an internal storage mechanism to store the critic model's conversation history. This i s a powerful and flexible way to handle complex scenarios.
 
     #########################################################
-    # 4. Call an LLM to respond to the user's message.
+    # 4. Return the agent response to the client.
     #########################################################
 
-    # Call an LLM to respond to the user's message
-    chat_completion = await adk.providers.litellm.chat_completion(
-        llm_config=LLMConfig(model=state.model, messages=llm_messages),
-        trace_id=params.task.id,
-    )
-
-    #########################################################
-    # 5. Return the agent response to the client.
-    #########################################################
-
-    # The Agentex server automatically commits input and output messages to the database so you don't need to do this yourself, simply process the input content and return the output content.
-
-    # Return the agent response to the client
-    if chat_completion.choices[0].message:
-        content_str = chat_completion.choices[0].message.content or ""
-    else:
-        content_str = ""
-
-    return TextContent(author="agent", content=content_str)
+    return TextContent(author="agent", content=result.final_output)

examples/tutorials/00_sync/010_multiturn/pyproject.toml

@@ -9,7 +9,7 @@ description = "An AgentEx agent"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
-    "agentex-sdk",
+    "agentex-sdk==0.4.28",
     "scale-gp",
 ]
 

examples/tutorials/00_sync/020_streaming/README.md

@@ -1,9 +1,45 @@
 # [Sync] Streaming
 
-This tutorial demonstrates how to implement streaming responses in AgentEx agents using the Agent 2 Client Protocol (ACP).
+Stream responses progressively using async generators instead of returning a single message. Enables showing partial results as they're generated.
 
-## Official Documentation
+## What You'll Learn
+- How to stream responses using async generators
+- The `yield` pattern for progressive updates
+- When streaming improves user experience
 
-[020 Streaming](https://dev.agentex.scale.com/docs/tutorials/sync/020_streaming)
+## Prerequisites
+- Development environment set up (see [main repo README](https://github.com/scaleapi/scale-agentex))
+- Backend services running: `make dev` from repository root
+- Understanding of basic sync agents (see [000_hello_acp](../000_hello_acp/))
 
+## Quick Start
 
+```bash
+cd examples/tutorials/00_sync/020_streaming
+uv run agentex agents run --manifest manifest.yaml
+```
+
+## Key Code
+
+```python
+@acp.on_message_send
+async def handle_message_send(params: SendMessageParams):
+    async def stream_response():
+        for chunk in response_chunks:
+            yield TaskMessageUpdate(content=TextContent(...))
+
+    return stream_response()
+```
+
+Return an async generator instead of a single response - each `yield` sends an update to the client.
+
+## When to Use
+- Streaming LLM responses (OpenAI, Anthropic, etc.)
+- Large data processing with progress updates
+- Any operation that takes >1 second to complete
+- Improving perceived responsiveness
+
+## Why This Matters
+Streaming dramatically improves user experience for longer operations. Instead of waiting 10 seconds for a complete response, users see results immediately as they're generated. This is essential for modern AI agents.
+
+**Next:** Ready for task management? → [10_agentic/00_base/000_hello_acp](../../10_agentic/00_base/000_hello_acp/)

examples/tutorials/00_sync/020_streaming/project/acp.py

@@ -1,19 +1,19 @@
 import os
 from typing import Union, AsyncGenerator
 
+from agents import Agent, Runner, RunConfig
+
 from agentex.lib import adk
 from agentex.lib.types.acp import SendMessageParams
+from agentex.lib.types.converters import convert_task_messages_to_oai_agents_inputs
 from agentex.lib.utils.model_utils import BaseModel
-from agentex.lib.types.llm_messages import LLMConfig, UserMessage, SystemMessage, AssistantMessage
 from agentex.lib.sdk.fastacp.fastacp import FastACP
-from agentex.types.task_message_delta import TextDelta
-from agentex.types.task_message_update import (
-    TaskMessageUpdate,
-    StreamTaskMessageDone,
-    StreamTaskMessageFull,
-    StreamTaskMessageDelta,
-)
+from agentex.types.task_message_update import TaskMessageUpdate, StreamTaskMessageFull
 from agentex.types.task_message_content import TextContent, TaskMessageContent
+from agentex.lib.adk.providers._modules.sync_provider import (
+    SyncStreamingProvider,
+    convert_openai_to_agentex_events,
+)
 
 # Create an ACP server
 acp = FastACP.create(
@@ -69,40 +69,35 @@ async def handle_message_send(
 
     task_messages = await adk.messages.list(task_id=params.task.id)
 
-    llm_messages = [
-        SystemMessage(content=state.system_prompt),
-        *[
-            UserMessage(content=getattr(message.content, "content", ""))
-            if getattr(message.content, "author", None) == "user"
-            else AssistantMessage(content=getattr(message.content, "content", ""))
-            for message in task_messages
-            if message.content and getattr(message.content, "type", None) == "text"
-        ],
-    ]
 
-    #########################################################
-    # 4. Call an LLM to respond to the user's message and stream the response to the client.
-    #########################################################
+    # Initialize the provider and run config to allow for tracing
+    provider = SyncStreamingProvider(
+        trace_id=params.task.id,
+    )
 
-    # Call an LLM to respond to the user's message
+    # Initialize the run config to allow for tracing and streaming
+    run_config = RunConfig(
+        model_provider=provider,
+    )
 
-    print(f"Calling LLM with model {state.model} and messages {llm_messages}")
 
-    # The Agentex server automatically commits input and output messages to the database so you don't need to do this yourself, simply process the input content and return the output content.
+    test_agent = Agent(name="assistant", instructions=state.system_prompt, model=state.model)
+
+    # Convert task messages to OpenAI Agents SDK format
+    input_list = convert_task_messages_to_oai_agents_inputs(task_messages)
+
+    # Run the agent and stream the events
+    result = Runner.run_streamed(test_agent, input_list, run_config=run_config)
+
+
+    #########################################################
+    # 4. Stream the events to the client.
+    #########################################################
+    # Convert the OpenAI events to Agentex events
+    # This is done by converting the OpenAI events to Agentex events and yielding them to the client
+    stream = result.stream_events()
+
+    # Yield the Agentex events to the client
+    async for agentex_event in convert_openai_to_agentex_events(stream):
+        yield agentex_event
 
-    message_index = 0
-    async for chunk in adk.providers.litellm.chat_completion_stream(
-        llm_config=LLMConfig(model=state.model, messages=llm_messages, stream=True),
-        trace_id=params.task.id,
-    ):
-        if chunk and chunk.choices and chunk.choices[0].delta and chunk.choices[0].delta.content:
-            yield StreamTaskMessageDelta(
-                type="delta",
-                index=message_index,
-                delta=TextDelta(type="text", text_delta=chunk.choices[0].delta.content or ""),
-            )
-
-    yield StreamTaskMessageDone(
-        type="done",
-        index=message_index,
-    )

examples/tutorials/00_sync/020_streaming/pyproject.toml

@@ -9,7 +9,7 @@ description = "An AgentEx agent that does multiturn streaming chat"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
-    "agentex-sdk",
+    "agentex-sdk==0.4.28",
     "scale-gp",
 ]