agentex-sdk 0.1.1__py3-none-any.whl → 0.2.1__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,127 @@
+{
+ "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",
+    "\n",
+    "from typing import cast\n",
+    "import uuid\n",
+    "\n",
+    "from agentex.types import Task\n",
+    "\n",
+    "TASK_ID = str(uuid.uuid4())[:8]\n",
+    "\n",
+    "rpc_response = client.agents.rpc_by_name(\n",
+    "    agent_name=AGENT_NAME,\n",
+    "    method=\"task/create\",\n",
+    "    params={\n",
+    "        \"name\": f\"{TASK_ID}-task\",\n",
+    "        \"params\": {}\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "task = cast(Task, rpc_response.result)\n",
+    "print(task)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b03b0d37",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Test non streaming response\n",
+    "from typing import cast\n",
+    "from agentex.types import Event\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.rpc_by_name(\n",
+    "    agent_name=AGENT_NAME,\n",
+    "    method=\"event/send\",\n",
+    "    params={\n",
+    "        \"content\": {\"type\": \"text\", \"author\": \"user\", \"content\": \"Hello what can you do?\"},\n",
+    "        \"task_id\": task.id,\n",
+    "    }\n",
+    ")\n",
+    "\n",
+    "event = cast(Event, rpc_response.result)\n",
+    "print(event)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a6927cc0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "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",
+    ")"
+   ]
+  }
+ ],
+ "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/cli/templates/temporal/project/workflow.py.j2

@@ -7,7 +7,7 @@ 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.task_message import TextContent
+from agentex.types.text_content import TextContent
 from agentex.lib.environment_variables import EnvironmentVariables
 
 environment_variables = EnvironmentVariables.refresh()

agentex/lib/cli/utils/auth_utils.py

@@ -0,0 +1,18 @@
+import base64
+import json
+
+from agentex.lib.sdk.config.agent_manifest import AgentManifest
+
+
+# Base 64 encode principal dictionary
+def _encode_principal_context(manifest: AgentManifest):
+    if manifest.auth is None:
+        return None
+
+    principal = manifest.auth.principal
+    if principal is None:
+        return None
+
+    json_str = json.dumps(principal, separators=(',', ':'))
+    encoded_bytes = base64.b64encode(json_str.encode('utf-8'))
+    return encoded_bytes.decode('utf-8')

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/environment_variables.py

@@ -24,9 +24,11 @@ class EnvVarKeys(str, Enum):
     ACP_URL = "ACP_URL"
     ACP_PORT = "ACP_PORT"
     ACP_TYPE = "ACP_TYPE"
-    # Workflow Configuraiton
+    # Workflow Configuration
     WORKFLOW_NAME = "WORKFLOW_NAME"
     WORKFLOW_TASK_QUEUE = "WORKFLOW_TASK_QUEUE"
+    # Auth Configuration
+    AUTH_PRINCIPAL_B64 = "AUTH_PRINCIPAL_B64"
 
 
 class Environment(str, Enum):
@@ -54,6 +56,7 @@ class EnvironmentVariables(BaseModel):
     # Workflow Configuration
     WORKFLOW_TASK_QUEUE: str | None = None
     WORKFLOW_NAME: str | None = None
+    AUTH_PRINCIPAL_B64: str | None = None
 
     @classmethod
     def refresh(cls) -> EnvironmentVariables | None:

agentex/lib/sdk/config/agent_manifest.py

@@ -15,7 +15,7 @@ from pydantic import Field
 
 from agentex.lib.sdk.config.agent_config import AgentConfig
 from agentex.lib.sdk.config.build_config import BuildConfig
-from agentex.lib.sdk.config.deployment_config import DeploymentConfig
+from agentex.lib.sdk.config.deployment_config import DeploymentConfig, AuthenticationConfig
 from agentex.lib.sdk.config.local_development_config import LocalDevelopmentConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.utils.model_utils import BaseModel
@@ -36,6 +36,7 @@ class AgentManifest(BaseModel):
     deployment: DeploymentConfig | None = Field(
         default=None, description="Deployment configuration for the agent"
     )
+    auth: AuthenticationConfig | None = Field(default=None, description="Authentication configuration")
 
     def context_manager(self, build_context_root: Path) -> BuildContextManager:
         """

agentex/lib/sdk/config/deployment_config.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Dict
 
 from pydantic import Field
 
@@ -90,6 +90,10 @@ class ClusterConfig(BaseModel):
     )
 
 
+class AuthenticationConfig(BaseModel):
+    principal: Dict[str, Any] = Field(description="Principal used for authorization on registration")
+
+
 class InjectedImagePullSecretValues(BaseModel):
     """Values for image pull secrets"""
 

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

@@ -1,5 +1,7 @@
 import asyncio
+import base64
 import inspect
+import json
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
 from typing import Any
@@ -341,6 +343,16 @@ class BaseACPServer(FastAPI):
         """Start the Uvicorn server for async handlers."""
         uvicorn.run(self, host=host, port=port, **kwargs)
 
+    def _get_auth_principal(self, env_vars: EnvironmentVariables):
+        if not env_vars.AUTH_PRINCIPAL_B64:
+            return None
+
+        try:
+            decoded_str = base64.b64decode(env_vars.AUTH_PRINCIPAL_B64).decode('utf-8')
+            return json.loads(decoded_str)
+        except Exception:
+            return None
+
     async def _register_agent(self, env_vars: EnvironmentVariables):
         """Register this agent with the Agentex server"""
         # Build the agent's own URL
@@ -350,12 +362,14 @@ class BaseACPServer(FastAPI):
             env_vars.AGENT_DESCRIPTION
             or f"Generic description for agent: {env_vars.AGENT_NAME}"
         )
+
         # Prepare registration data
         registration_data = {
             "name": env_vars.AGENT_NAME,
             "description": description,
             "acp_url": full_acp_url,
             "acp_type": env_vars.ACP_TYPE,
+            "principal_context": self._get_auth_principal(env_vars)
         }
 
         if env_vars.AGENT_ID:

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",
+]