agentex-sdk 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

agentex/lib/cli/templates/temporal-openai-agents/project/workflow.py.j2

@@ -0,0 +1,169 @@
+import json
+import os
+
+from temporalio import workflow
+
+from agentex.lib import adk
+from agentex.lib.types.acp import CreateTaskParams, SendEventParams
+from agentex.lib.core.temporal.workflows.workflow import BaseWorkflow
+from agentex.lib.core.temporal.types.workflow import SignalName
+from agentex.lib.utils.logging import make_logger
+from agentex.types.text_content import TextContent
+from agentex.lib.environment_variables import EnvironmentVariables
+from agents import Agent, Runner
+from agentex.lib.core.temporal.plugins.openai_agents.hooks.hooks import TemporalStreamingHooks
+from pydantic import BaseModel
+from typing import List, Dict, Any
+from temporalio.contrib import openai_agents
+from project.activities import get_weather
+from agentex.lib.core.tracing.tracing_processor_manager import (
+    add_tracing_processor_config,
+)
+from agentex.lib.types.tracing import SGPTracingProcessorConfig
+from datetime import timedelta
+
+
+environment_variables = EnvironmentVariables.refresh()
+
+if environment_variables.WORKFLOW_NAME is None:
+    raise ValueError("Environment variable WORKFLOW_NAME is not set")
+
+if environment_variables.AGENT_NAME is None:
+    raise ValueError("Environment variable AGENT_NAME is not set")
+
+logger = make_logger(__name__)
+
+# Setup tracing for SGP (Scale GenAI Platform)
+# This enables visibility into your agent's execution in the SGP dashboard
+add_tracing_processor_config(
+    SGPTracingProcessorConfig(
+        sgp_api_key=os.environ.get("SGP_API_KEY", ""),
+        sgp_account_id=os.environ.get("SGP_ACCOUNT_ID", ""),
+    )
+)
+
+
+class StateModel(BaseModel):
+    """
+    State model for preserving conversation history across turns.
+
+    This allows the agent to maintain context throughout the conversation,
+    making it possible to reference previous messages and build on the discussion.
+
+    Attributes:
+        input_list: The conversation history in OpenAI message format.
+        turn_number: Counter for tracking conversation turns (useful for tracing).
+    """
+
+    input_list: List[Dict[str, Any]]
+    turn_number: int
+
+
+class TurnInput(BaseModel):
+    """Input model for tracing spans."""
+    input_list: List[Dict[str, Any]]
+
+
+class TurnOutput(BaseModel):
+    """Output model for tracing spans."""
+    final_output: Any
+
+
+@workflow.defn(name=environment_variables.WORKFLOW_NAME)
+class {{ workflow_class }}(BaseWorkflow):
+    """
+    Workflow for {{ agent_name }} agent using OpenAI Agents SDK.
+
+    This workflow:
+    - Maintains conversation state across turns
+    - Creates tracing spans for each turn
+    - Runs an OpenAI agent with tools (activities)
+    - Streams responses back to the client
+    """
+
+    def __init__(self):
+        super().__init__(display_name=environment_variables.AGENT_NAME)
+        self._complete_task = False
+        self._state: StateModel = StateModel(input_list=[], turn_number=0)
+        self._task_id = None
+        self._trace_id = None
+        self._parent_span_id = None
+
+    @workflow.signal(name=SignalName.RECEIVE_EVENT)
+    async def on_task_event_send(self, params: SendEventParams) -> None:
+        logger.info(f"Received task message instruction: {params}")
+
+        # Increment turn number for tracing
+        self._state.turn_number += 1
+
+        self._task_id = params.task.id
+        self._trace_id = params.task.id
+        self._parent_span_id = params.task.id
+
+        # Add the user message to conversation history
+        self._state.input_list.append({"role": "user", "content": params.event.content.content})
+
+        # Echo back the client's message to show it in the UI
+        await adk.messages.create(task_id=params.task.id, content=params.event.content)
+
+        temporal_streaming_hooks = TemporalStreamingHooks(task_id=params.task.id)
+
+        # Create a span to track this turn of the conversation
+        turn_input = TurnInput(
+            input_list=self._state.input_list,
+        )
+        async with adk.tracing.span(
+            trace_id=params.task.id,
+            name=f"Turn {self._state.turn_number}",
+            input=turn_input.model_dump(),
+        ) as span:
+            self._parent_span_id = span.id if span else None
+
+            # Create the OpenAI agent with tools
+            # Add your activities as tools using activity_as_tool()
+            agent = Agent(
+                name="{{ agent_name }}",
+                instructions="You are a helpful assistant. Use your tools to help the user.",
+                model="gpt-4o-mini",
+                tools=[
+                    openai_agents.workflow.activity_as_tool(
+                        get_weather,
+                        start_to_close_timeout=timedelta(minutes=5),
+                    ),
+                    # Add more tools here as you create new activities:
+                    # openai_agents.workflow.activity_as_tool(
+                    #     your_new_activity,
+                    #     start_to_close_timeout=timedelta(minutes=5),
+                    # ),
+                ],
+            )
+
+            # Run the agent with hooks to enable streaming responses
+            result = await Runner.run(agent, self._state.input_list, hooks=temporal_streaming_hooks)
+
+            # Update the state with the assistant's response for the next turn
+            self._state.input_list = result.to_input_list()  # type: ignore[assignment]
+
+            # Set span output for tracing - include full state
+            if span:
+                turn_output = TurnOutput(final_output=result.final_output)
+                span.output = turn_output.model_dump()
+
+    @workflow.run
+    async def on_task_create(self, params: CreateTaskParams) -> str:
+        logger.info(f"Received task create params: {params}")
+
+        # Acknowledge that the task has been created
+        await adk.messages.create(
+            task_id=params.task.id,
+            content=TextContent(
+                author="agent",
+                content=f"Hello! I'm {{ agent_name }}, your AI assistant. How can I help you today?\n\nParams received:\n{json.dumps(params.params, indent=2)}",
+            ),
+        )
+
+        await workflow.wait_condition(
+            lambda: self._complete_task,
+            timeout=None,
+        )
+        return "Task completed"

agentex/lib/cli/templates/temporal-openai-agents/pyproject.toml.j2

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "{{ description }}"
+requires-python = ">=3.12"
+dependencies = [
+    "agentex-sdk",
+    "scale-gp",
+    "temporalio",
+    "openai-agents>=0.4.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "black",
+    "isort",
+    "flake8",
+    "debugpy>=1.8.15",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["project"]
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+
+[tool.isort]
+profile = "black"
+line_length = 88

agentex/lib/cli/templates/temporal-openai-agents/requirements.txt.j2

@@ -0,0 +1,4 @@
+agentex-sdk
+scale-gp
+temporalio
+openai-agents>=0.4.2

agentex/lib/cli/templates/temporal-openai-agents/test_agent.py.j2

@@ -0,0 +1,147 @@
+"""
+Sample tests for AgentEx ACP agent.
+
+This test suite demonstrates how to test the main AgentEx API functions:
+- Non-streaming event sending and polling
+- Streaming event sending
+
+To run these tests:
+1. Make sure the agent is running (via docker-compose or `agentex agents run`)
+2. Set the AGENTEX_API_BASE_URL environment variable if not using default
+3. Run: pytest test_agent.py -v
+
+Configuration:
+- AGENTEX_API_BASE_URL: Base URL for the AgentEx server (default: http://localhost:5003)
+- AGENT_NAME: Name of the agent to test (default: {{ agent_name }})
+"""
+
+import os
+import uuid
+import asyncio
+import pytest
+import pytest_asyncio
+from agentex import AsyncAgentex
+from agentex.types import TaskMessage
+from agentex.types.agent_rpc_params import ParamsCreateTaskRequest
+from agentex.types.text_content_param import TextContentParam
+from test_utils.async_utils import (
+    poll_for_agent_response,
+    send_event_and_poll_yielding,
+    stream_agent_response,
+    validate_text_in_response,
+    poll_messages,
+)
+
+
+# Configuration from environment variables
+AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003")
+AGENT_NAME = os.environ.get("AGENT_NAME", "{{ agent_name }}")
+
+
+@pytest_asyncio.fixture
+async def client():
+    """Create an AsyncAgentex client instance for testing."""
+    client = AsyncAgentex(base_url=AGENTEX_API_BASE_URL)
+    yield client
+    await client.close()
+
+
+@pytest.fixture
+def agent_name():
+    """Return the agent name for testing."""
+    return AGENT_NAME
+
+
+@pytest_asyncio.fixture
+async def agent_id(client, agent_name):
+    """Retrieve the agent ID based on the agent name."""
+    agents = await client.agents.list()
+    for agent in agents:
+        if agent.name == agent_name:
+            return agent.id
+    raise ValueError(f"Agent with name {agent_name} not found.")
+
+
+class TestNonStreamingEvents:
+    """Test non-streaming event sending and polling."""
+
+    @pytest.mark.asyncio
+    async def test_send_event_and_poll(self, client: AsyncAgentex, _agent_name: str, agent_id: str):
+        """Test sending an event and polling for the response."""
+        # TODO: Create a task for this conversation
+        # task_response = await client.agents.create_task(agent_id, params=ParamsCreateTaskRequest(name=uuid.uuid1().hex))
+        # task = task_response.result
+        # assert task is not None
+
+        # TODO: Poll for the initial task creation message (if your agent sends one)
+        # async for message in poll_messages(
+        #     client=client,
+        #     task_id=task.id,
+        #     timeout=30,
+        #     sleep_interval=1.0,
+        # ):
+        #     assert isinstance(message, TaskMessage)
+        #     if message.content and message.content.type == "text" and message.content.author == "agent":
+        #         # Check for your expected initial message
+        #         assert "expected initial text" in message.content.content
+        #         break
+
+        # TODO: Send an event and poll for response using the yielding helper function
+        # user_message = "Your test message here"
+        # async for message in send_event_and_poll_yielding(
+        #     client=client,
+        #     agent_id=agent_id,
+        #     task_id=task.id,
+        #     user_message=user_message,
+        #     timeout=30,
+        #     sleep_interval=1.0,
+        # ):
+        #     assert isinstance(message, TaskMessage)
+        #     if message.content and message.content.type == "text" and message.content.author == "agent":
+        #         # Check for your expected response
+        #         assert "expected response text" in message.content.content
+        #         break
+        pass
+
+
+class TestStreamingEvents:
+    """Test streaming event sending."""
+
+    @pytest.mark.asyncio
+    async def test_send_event_and_stream(self, client: AsyncAgentex, _agent_name: str, agent_id: str):
+        """Test sending an event and streaming the response."""
+        # TODO: Create a task for this conversation
+        # task_response = await client.agents.create_task(agent_id, params=ParamsCreateTaskRequest(name=uuid.uuid1().hex))
+        # task = task_response.result
+        # assert task is not None
+
+        # user_message = "Your test message here"
+
+        # # Collect events from stream
+        # all_events = []
+
+        # async def collect_stream_events():
+        #     async for event in stream_agent_response(
+        #         client=client,
+        #         task_id=task.id,
+        #         timeout=30,
+        #     ):
+        #         all_events.append(event)
+
+        # # Start streaming task
+        # stream_task = asyncio.create_task(collect_stream_events())
+
+        # # Send the event
+        # event_content = TextContentParam(type="text", author="user", content=user_message)
+        # await client.agents.send_event(agent_id=agent_id, params={"task_id": task.id, "content": event_content})
+
+        # # Wait for streaming to complete
+        # await stream_task
+
+        # # TODO: Add your validation here
+        # assert len(all_events) > 0, "No events received in streaming response"
+        pass
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

agentex/resources/messages/messages.py

@@ -15,7 +15,12 @@ from .batch import (
     BatchResourceWithStreamingResponse,
     AsyncBatchResourceWithStreamingResponse,
 )
-from ...types import message_list_params, message_create_params, message_update_params
+from ...types import (
+    message_list_params,
+    message_create_params,
+    message_update_params,
+    message_list_paginated_params,
+)
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
 from ..._utils import maybe_transform, async_maybe_transform
 from ..._compat import cached_property
@@ -30,6 +35,7 @@ from ..._base_client import make_request_options
 from ...types.task_message import TaskMessage
 from ...types.message_list_response import MessageListResponse
 from ...types.task_message_content_param import TaskMessageContentParam
+from ...types.message_list_paginated_response import MessageListPaginatedResponse
 
 __all__ = ["MessagesResource", "AsyncMessagesResource"]
 
@@ -192,7 +198,10 @@ class MessagesResource(SyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MessageListResponse:
         """
-        List Messages
+        List messages for a task with offset-based pagination.
+
+        For cursor-based pagination with infinite scroll support, use
+        /messages/paginated.
 
         Args:
           task_id: The task ID
@@ -226,6 +235,70 @@ class MessagesResource(SyncAPIResource):
             cast_to=MessageListResponse,
         )
 
+    def list_paginated(
+        self,
+        *,
+        task_id: str,
+        cursor: Optional[str] | Omit = omit,
+        direction: Literal["older", "newer"] | Omit = omit,
+        limit: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> MessageListPaginatedResponse:
+        """
+        List messages for a task with cursor-based pagination.
+
+        This endpoint is designed for infinite scroll UIs where new messages may arrive
+        while paginating through older ones.
+
+        Args: task_id: The task ID to filter messages by limit: Maximum number of
+        messages to return (default: 50) cursor: Opaque cursor string for pagination.
+        Pass the `next_cursor` from a previous response to get the next page. direction:
+        Pagination direction - "older" to get older messages (default), "newer" to get
+        newer messages.
+
+        Returns: PaginatedMessagesResponse with: - data: List of messages (newest first
+        when direction="older") - next_cursor: Cursor for fetching the next page (null
+        if no more pages) - has_more: Whether there are more messages to fetch
+
+        Example: First request: GET /messages/paginated?task_id=xxx&limit=50 Next page:
+        GET /messages/paginated?task_id=xxx&limit=50&cursor=<next_cursor>
+
+        Args:
+          task_id: The task ID
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._get(
+            "/messages/paginated",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "task_id": task_id,
+                        "cursor": cursor,
+                        "direction": direction,
+                        "limit": limit,
+                    },
+                    message_list_paginated_params.MessageListPaginatedParams,
+                ),
+            ),
+            cast_to=MessageListPaginatedResponse,
+        )
+
 
 class AsyncMessagesResource(AsyncAPIResource):
     @cached_property
@@ -385,7 +458,10 @@ class AsyncMessagesResource(AsyncAPIResource):
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MessageListResponse:
         """
-        List Messages
+        List messages for a task with offset-based pagination.
+
+        For cursor-based pagination with infinite scroll support, use
+        /messages/paginated.
 
         Args:
           task_id: The task ID
@@ -419,6 +495,70 @@ class AsyncMessagesResource(AsyncAPIResource):
             cast_to=MessageListResponse,
         )
 
+    async def list_paginated(
+        self,
+        *,
+        task_id: str,
+        cursor: Optional[str] | Omit = omit,
+        direction: Literal["older", "newer"] | Omit = omit,
+        limit: int | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> MessageListPaginatedResponse:
+        """
+        List messages for a task with cursor-based pagination.
+
+        This endpoint is designed for infinite scroll UIs where new messages may arrive
+        while paginating through older ones.
+
+        Args: task_id: The task ID to filter messages by limit: Maximum number of
+        messages to return (default: 50) cursor: Opaque cursor string for pagination.
+        Pass the `next_cursor` from a previous response to get the next page. direction:
+        Pagination direction - "older" to get older messages (default), "newer" to get
+        newer messages.
+
+        Returns: PaginatedMessagesResponse with: - data: List of messages (newest first
+        when direction="older") - next_cursor: Cursor for fetching the next page (null
+        if no more pages) - has_more: Whether there are more messages to fetch
+
+        Example: First request: GET /messages/paginated?task_id=xxx&limit=50 Next page:
+        GET /messages/paginated?task_id=xxx&limit=50&cursor=<next_cursor>
+
+        Args:
+          task_id: The task ID
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._get(
+            "/messages/paginated",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform(
+                    {
+                        "task_id": task_id,
+                        "cursor": cursor,
+                        "direction": direction,
+                        "limit": limit,
+                    },
+                    message_list_paginated_params.MessageListPaginatedParams,
+                ),
+            ),
+            cast_to=MessageListPaginatedResponse,
+        )
+
 
 class MessagesResourceWithRawResponse:
     def __init__(self, messages: MessagesResource) -> None:
@@ -436,6 +576,9 @@ class MessagesResourceWithRawResponse:
         self.list = to_raw_response_wrapper(
             messages.list,
         )
+        self.list_paginated = to_raw_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> BatchResourceWithRawResponse:
@@ -458,6 +601,9 @@ class AsyncMessagesResourceWithRawResponse:
         self.list = async_to_raw_response_wrapper(
             messages.list,
         )
+        self.list_paginated = async_to_raw_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> AsyncBatchResourceWithRawResponse:
@@ -480,6 +626,9 @@ class MessagesResourceWithStreamingResponse:
         self.list = to_streamed_response_wrapper(
             messages.list,
         )
+        self.list_paginated = to_streamed_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> BatchResourceWithStreamingResponse:
@@ -502,6 +651,9 @@ class AsyncMessagesResourceWithStreamingResponse:
         self.list = async_to_streamed_response_wrapper(
             messages.list,
         )
+        self.list_paginated = async_to_streamed_response_wrapper(
+            messages.list_paginated,
+        )
 
     @cached_property
     def batch(self) -> AsyncBatchResourceWithStreamingResponse:

agentex/types/__init__.py

@@ -63,6 +63,8 @@ from .task_message_content_param import TaskMessageContentParam as TaskMessageCo
 from .tool_request_content_param import ToolRequestContentParam as ToolRequestContentParam
 from .tool_response_content_param import ToolResponseContentParam as ToolResponseContentParam
 from .task_retrieve_by_name_params import TaskRetrieveByNameParams as TaskRetrieveByNameParams
+from .message_list_paginated_params import MessageListPaginatedParams as MessageListPaginatedParams
 from .deployment_history_list_params import DeploymentHistoryListParams as DeploymentHistoryListParams
 from .task_retrieve_by_name_response import TaskRetrieveByNameResponse as TaskRetrieveByNameResponse
+from .message_list_paginated_response import MessageListPaginatedResponse as MessageListPaginatedResponse
 from .deployment_history_list_response import DeploymentHistoryListResponse as DeploymentHistoryListResponse

agentex/types/message_list_paginated_params.py

@@ -0,0 +1,19 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Optional
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["MessageListPaginatedParams"]
+
+
+class MessageListPaginatedParams(TypedDict, total=False):
+    task_id: Required[str]
+    """The task ID"""
+
+    cursor: Optional[str]
+
+    direction: Literal["older", "newer"]
+
+    limit: int

agentex/types/message_list_paginated_response.py

@@ -0,0 +1,21 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Optional
+
+from .._models import BaseModel
+from .task_message import TaskMessage
+
+__all__ = ["MessageListPaginatedResponse"]
+
+
+class MessageListPaginatedResponse(BaseModel):
+    """Response with cursor pagination metadata."""
+
+    data: List[TaskMessage]
+    """List of messages"""
+
+    has_more: Optional[bool] = None
+    """Whether there are more messages to fetch"""
+
+    next_cursor: Optional[str] = None
+    """Cursor for fetching the next page of older messages"""

{agentex_sdk-0.7.0.dist-info → agentex_sdk-0.7.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentex-sdk
-Version: 0.7.0
+Version: 0.7.2
 Summary: The official Python library for the agentex API
 Project-URL: Homepage, https://github.com/scaleapi/scale-agentex-python
 Project-URL: Repository, https://github.com/scaleapi/scale-agentex-python