agentex-sdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

agentex/lib/cli/templates/sync/project/acp.py.j2

@@ -1,26 +1,75 @@
-from typing import AsyncGenerator, Union
+import json
+from agentex.lib import adk
 from agentex.lib.sdk.fastacp.fastacp import FastACP
-from agentex.lib.types.acp import SendMessageParams
+from agentex.lib.types.fastacp import AgenticACPConfig
+from agentex.lib.types.acp import CancelTaskParams, CreateTaskParams, SendEventParams
 
-from agentex.lib.types.task_message_updates import TaskMessageUpdate
-from agentex.types.task_message_content import TaskMessageContent
 from agentex.types.text_content import TextContent
 from agentex.lib.utils.logging import make_logger
 
 logger = make_logger(__name__)
 
 
-# Create an ACP server
+# Create an ACP server with base configuration
+# This sets up the core server that will handle task creation, events, and cancellation
 acp = FastACP.create(
-    acp_type="sync",
+    acp_type="agentic",
+    config=AgenticACPConfig(
+        type="base",
+    ),
 )
 
-@acp.on_message_send
-async def handle_message_send(
-    params: SendMessageParams
-) -> TaskMessageContent | list[TaskMessageContent] | AsyncGenerator[TaskMessageUpdate, None]:
-    """Default message handler with streaming support"""
-    return TextContent(
-        author="agent",
-        content=f"Hello! I've received your message. Here's a generic response, but in future tutorials we'll see how you can get me to intelligently respond to your message. This is what I heard you say: {params.content.content}",
+@acp.on_task_create
+async def handle_task_create(params: CreateTaskParams):
+    # This handler is called first whenever a new task is created.
+    # It's a good place to initialize any state or resources needed for the task.
+
+    #########################################################
+    # 1. (👋) Do task initialization here.
+    #########################################################
+
+    # Acknowledge that the task has been created.
+    await adk.messages.create(
+        task_id=params.task.id,
+        content=TextContent(
+            author="agent",
+            content=f"Hello! I've received your task. Normally you can do some state initialization here, or just pass and do nothing until you get your first event. For now I'm just acknowledging that I've received a task with the following params:\n\n{json.dumps(params.params, indent=2)}.\n\nYou should only see this message once, when the task is created. All subsequent events will be handled by the `on_task_event_send` handler.",
+        ),
     )
+
+@acp.on_task_event_send
+async def handle_event_send(params: SendEventParams):
+    # This handler is called whenever a new event (like a message) is sent to the task
+    
+    #########################################################
+    # 2. (👋) Echo back the client's message to show it in the UI.
+    #########################################################
+    
+    # This is not done by default so the agent developer has full control over what is shown to the user.
+    if params.event.content:
+        await adk.messages.create(task_id=params.task.id, content=params.event.content)
+
+    #########################################################
+    # 3. (👋) Send a simple response message.
+    #########################################################
+
+    # In future tutorials, this is where we'll add more sophisticated response logic.
+    await adk.messages.create(
+        task_id=params.task.id,
+        content=TextContent(
+            author="agent",
+            content=f"Hello! I've received your message. I can't respond right now, but in future tutorials we'll see how you can get me to intelligently respond to your message.",
+        ),
+    )
+
+@acp.on_task_cancel
+async def handle_task_cancel(params: CancelTaskParams):
+    # This handler is called when a task is cancelled.
+    # It's useful for cleaning up any resources or state associated with the task.
+
+    #########################################################
+    # 4. (👋) Do task cleanup here.
+    #########################################################
+
+    # This is mostly for durable workflows that are cancellable like Temporal, but we will leave it here for demonstration purposes.
+    logger.info(f"Hello! I've received task cancel for task {params.task.id}: {params.task}. This isn't necessary for this example, but it's good to know that it's available.")

agentex/lib/cli/templates/temporal/README.md.j2

@@ -68,6 +68,7 @@ This file is essential for both local development and deployment of your agent.
 │   └── run_worker.py        # Temporal worker setup
 ├── Dockerfile               # Container definition
 ├── manifest.yaml            # Deployment config
+├── dev.ipynb                # Development notebook for testing
 {% if use_uv %}
 └── pyproject.toml          # Dependencies (uv)
 {% else %}
@@ -82,12 +83,32 @@ This file is essential for both local development and deployment of your agent.
 - Add your own tools and capabilities
 - Implement custom state management
 
-### 2. Develop Temporal Workflows
+### 2. Test Your Agent with the Development Notebook
+Use the included `dev.ipynb` Jupyter notebook to test your agent interactively:
+
+```bash
+# Start Jupyter notebook (make sure you have jupyter installed)
+jupyter notebook dev.ipynb
+
+# Or use VS Code to open the notebook directly
+code dev.ipynb
+```
+
+The notebook includes:
+- **Setup**: Connect to your local AgentEx backend
+- **Task creation**: Create a new task for the conversation
+- **Event sending**: Send events to the agent and get responses
+- **Async message subscription**: Subscribe to server-side events to receive agent responses
+- **Rich message display**: Beautiful formatting with timestamps and author information
+
+The notebook automatically uses your agent name (`{{ agent_name }}`) and demonstrates the agentic ACP workflow: create task → send event → subscribe to responses.
+
+### 3. Develop Temporal Workflows
 - Edit `workflow.py` to define your agent's async workflow logic
 - Modify `activities.py` to add custom activities
 - Use `run_worker.py` to configure the Temporal worker
 
-### 3. Manage Dependencies
+### 4. Manage Dependencies
 
 {% if use_uv %}
 You chose **uv** for package management. Here's how to work with dependencies:
@@ -135,7 +156,7 @@ pip install -r requirements.txt
 - Wide compatibility
 {% endif %}
 
-### 4. Configure Credentials
+### 5. Configure Credentials
 - Add any required credentials to your manifest.yaml
 - For local development, create a `.env` file in the project directory
 - Use `load_dotenv()` only in development mode:

agentex/lib/cli/templates/temporal/dev.ipynb.j2

@@ -0,0 +1,126 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "36834357",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from agentex import Agentex\n",
+    "\n",
+    "client = Agentex(base_url=\"http://localhost:5003\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d1c309d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "AGENT_NAME = \"{{ agent_name }}\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f6e6ef0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# (REQUIRED) Create a new task. For Agentic agents, you must create a task for messages to be associated with.\n",
+    "import uuid\n",
+    "\n",
+    "rpc_response = client.agents.create_task(\n",
+    "    agent_name=AGENT_NAME,\n",
+    "    params={\n",
+    "        \"name\": f\"{str(uuid.uuid4())[:8]}-task\",\n",
+    "        \"params\": {}\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "task = rpc_response.result\n",
+    "print(task)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b03b0d37",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Send an event to the agent\n",
+    "\n",
+    "# The response is expected to be a list of TaskMessage objects, which is a union of the following types:\n",
+    "# - TextContent: A message with just text content   \n",
+    "# - DataContent: A message with JSON-serializable data content\n",
+    "# - ToolRequestContent: A message with a tool request, which contains a JSON-serializable request to call a tool\n",
+    "# - ToolResponseContent: A message with a tool response, which contains response object from a tool call in its content\n",
+    "\n",
+    "# When processing the message/send response, if you are expecting more than TextContent, such as DataContent, ToolRequestContent, or ToolResponseContent, you can process them as well\n",
+    "\n",
+    "rpc_response = client.agents.send_event(\n",
+    "    agent_name=AGENT_NAME,\n",
+    "    params={\n",
+    "        \"content\": {\"type\": \"text\", \"author\": \"user\", \"content\": \"Hello what can you do?\"},\n",
+    "        \"task_id\": task.id,\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "event = rpc_response.result\n",
+    "print(event)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a6927cc0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Subscribe to the async task messages produced by the agent\n",
+    "from agentex.lib.utils.dev_tools import subscribe_to_async_task_messages\n",
+    "\n",
+    "task_messages = subscribe_to_async_task_messages(\n",
+    "    client=client,\n",
+    "    task=task, \n",
+    "    only_after_timestamp=event.created_at, \n",
+    "    print_messages=True,\n",
+    "    rich_print=True,\n",
+    "    timeout=5,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4864e354",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

agentex/lib/core/adapters/streams/adapter_redis.py

@@ -7,13 +7,13 @@ from typing import Annotated, Any
 import redis.asyncio as redis
 from fastapi import Depends
 
-from agentex.lib.core.adapters.streams.port import EventStreamRepository
+from agentex.lib.core.adapters.streams.port import StreamRepository
 from agentex.lib.utils.logging import make_logger
 
 logger = make_logger(__name__)
 
 
-class RedisEventStreamRepository(EventStreamRepository):
+class RedisStreamRepository(StreamRepository):
     """
     A simplified Redis implementation of the EventStreamRepository interface.
     Optimized for text/JSON streaming with SSE.
@@ -123,6 +123,6 @@ class RedisEventStreamRepository(EventStreamRepository):
             raise
 
 
-DRedisEventStreamRepository = Annotated[
-    RedisEventStreamRepository | None, Depends(RedisEventStreamRepository)
+DRedisStreamRepository = Annotated[
+    RedisStreamRepository | None, Depends(RedisStreamRepository)
 ]

agentex/lib/core/adapters/streams/port.py

@@ -3,7 +3,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 
-class EventStreamRepository(ABC):
+class StreamRepository(ABC):
     """
     Interface for event streaming repositories.
     Used to publish and subscribe to event streams.

agentex/lib/core/services/adk/streaming.py

@@ -2,7 +2,7 @@ import json
 from typing import Literal, cast
 
 from agentex import AsyncAgentex
-from agentex.lib.core.adapters.streams.port import EventStreamRepository
+from agentex.lib.core.adapters.streams.port import StreamRepository
 from agentex.lib.types.task_message_updates import (
     TaskMessageDelta, 
     TaskMessageUpdate,
@@ -22,7 +22,6 @@ from agentex.types.task_message import (
     TaskMessage,
     TaskMessageContent,
 )
-from agentex.types.task_message_content_param import TaskMessageContentParam
 from agentex.types.text_content import TextContent
 from agentex.types.tool_request_content import ToolRequestContent
 from agentex.types.tool_response_content import ToolResponseContent
@@ -221,7 +220,7 @@ class StreamingService:
     def __init__(
         self,
         agentex_client: AsyncAgentex,
-        stream_repository: EventStreamRepository,
+        stream_repository: StreamRepository,
     ):
         self._agentex_client = agentex_client
         self._stream_repository = stream_repository

agentex/lib/core/temporal/activities/__init__.py

@@ -2,7 +2,7 @@ from scale_gp import SGPClient, SGPClientError
 
 from agentex import AsyncAgentex
 from agentex.lib.core.adapters.llm.adapter_litellm import LiteLLMGateway
-from agentex.lib.core.adapters.streams.adapter_redis import RedisEventStreamRepository
+from agentex.lib.core.adapters.streams.adapter_redis import RedisStreamRepository
 from agentex.lib.core.services.adk.acp.acp import ACPService
 from agentex.lib.core.services.adk.agent_task_tracker import AgentTaskTrackerService
 from agentex.lib.core.services.adk.events import EventsService
@@ -57,7 +57,7 @@ def get_all_activities(sgp_client=None):
         sgp_client = None
 
     llm_gateway = LiteLLMGateway()
-    stream_repository = RedisEventStreamRepository()
+    stream_repository = RedisStreamRepository()
     agentex_client = AsyncAgentex()
     tracer = AsyncTracer(agentex_client)
 

agentex/lib/sdk/fastacp/base/base_acp_server.py

@@ -2,6 +2,7 @@ import asyncio
 import base64
 import inspect
 import json
+import os
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from typing import Any
@@ -13,7 +14,7 @@ from fastapi.responses import StreamingResponse
 from pydantic import TypeAdapter, ValidationError
 
 # from agentex.lib.sdk.fastacp.types import BaseACPConfig
-from agentex.lib.environment_variables import EnvironmentVariables
+from agentex.lib.environment_variables import EnvironmentVariables, refreshed_environment_variables
 from agentex.lib.types.acp import (
     PARAMS_MODEL_BY_METHOD,
     RPC_SYNC_METHODS,
@@ -390,8 +391,16 @@ class BaseACPServer(FastAPI):
                         registration_url, json=registration_data, timeout=30.0
                     )
                     if response.status_code == 200:
+                        agent = response.json()
+                        agent_id, agent_name = agent["id"], agent["name"]
+
+                        os.environ["AGENT_ID"] = agent_id
+                        os.environ["AGENT_NAME"] = agent_name
+                        refreshed_environment_variables.AGENT_ID = agent_id
+                        refreshed_environment_variables.AGENT_NAME = agent_name
+                        
                         logger.info(
-                            f"Successfully registered agent '{env_vars.AGENT_NAME}' with Agentex server with acp_url: {full_acp_url}. Registration data: {registration_data}"
+                            f"Successfully registered agent '{agent_name}' with Agentex server with acp_url: {full_acp_url}. Registration data: {registration_data}"
                         )
                         return  # Success, exit the retry loop
                     else:

agentex/lib/utils/dev_tools/__init__.py

@@ -0,0 +1,9 @@
+"""Development tools for AgentEx."""
+
+from .async_messages import print_task_message, print_task_message_update, subscribe_to_async_task_messages
+
+__all__ = [
+    "print_task_message",
+    "print_task_message_update", 
+    "subscribe_to_async_task_messages",
+]