refactor(types): promote protocol types to agentex.protocol.* (#371)

max-parke-scale · claude · web-flow · commit 6f1c14fd6107 · 2026-05-27T11:35:59.000-04:00
Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -55,11 +55,27 @@ The package provides the `agentex` CLI with these main commands:
 
 ### Code Structure
 - `/src/agentex/` - Core SDK and generated API client code
+- `/src/agentex/protocol/` - **Canonical** location for wire-protocol shapes
+  (JSON-RPC envelopes, ACP method-param types). Depends only on `pydantic`
+  and the Stainless-generated `agentex.types.*` surface, so it is safe to
+  import from a future slim REST-only install.
+  - `acp.py` - `RPCMethod`, `CreateTaskParams`, `SendMessageParams`,
+    `SendEventParams`, `CancelTaskParams`, `RPC_SYNC_METHODS`,
+    `PARAMS_MODEL_BY_METHOD`
+  - `json_rpc.py` - `JSONRPCRequest`, `JSONRPCResponse`, `JSONRPCError`
 - `/src/agentex/lib/` - Custom library code (not modified by code generator)
   - `/cli/` - Command-line interface implementation
   - `/core/` - Core services, adapters, and temporal workflows
   - `/sdk/` - SDK utilities and FastACP implementation
   - `/types/` - Custom type definitions
+    - `acp.py`, `json_rpc.py` - **back-compat shims** re-exporting from
+      `agentex.protocol.*`. Existing `from agentex.lib.types.{acp,json_rpc}
+      import ...` keeps working; new code should import from the canonical
+      `agentex.protocol.*` paths.
+    - Other modules (`tracing`, `agent_card`, `credentials`, `fastacp`,
+      `llm_messages`, `converters`, etc.) stay here — they have heavier
+      transitive deps (temporal, openai-agents, model_utils/yaml) and
+      aren't slim-safe.
   - `/utils/` - Utility functions
 - `/examples/` - Example implementations and tutorials
 - `/tests/` - Test suites
diff --git a/src/agentex/lib/cli/templates/default-langgraph/project/acp.py.j2 b/src/agentex/lib/cli/templates/default-langgraph/project/acp.py.j2
@@ -18,7 +18,7 @@ import agentex.lib.adk as adk
 from agentex.lib.adk import create_langgraph_tracing_handler, stream_langgraph_events
 from agentex.lib.core.tracing.tracing_processor_manager import add_tracing_processor_config
 from agentex.lib.sdk.fastacp.fastacp import FastACP
-from agentex.lib.types.acp import SendEventParams, CancelTaskParams, CreateTaskParams
+from agentex.protocol.acp import SendEventParams, CancelTaskParams, CreateTaskParams
 from agentex.lib.types.fastacp import AsyncACPConfig
 from agentex.lib.types.tracing import SGPTracingProcessorConfig
 from agentex.lib.utils.logging import make_logger
diff --git a/src/agentex/lib/cli/templates/default-pydantic-ai/project/acp.py.j2 b/src/agentex/lib/cli/templates/default-pydantic-ai/project/acp.py.j2
@@ -28,7 +28,7 @@ from agentex.lib.adk import (
     stream_pydantic_ai_events,
     create_pydantic_ai_tracing_handler,
 )
-from agentex.lib.types.acp import SendEventParams, CancelTaskParams, CreateTaskParams
+from agentex.protocol.acp import SendEventParams, CancelTaskParams, CreateTaskParams
 from agentex.lib.types.fastacp import AsyncACPConfig
 from agentex.lib.types.tracing import SGPTracingProcessorConfig
 from agentex.lib.utils.logging import make_logger
diff --git a/src/agentex/lib/cli/templates/default/project/acp.py.j2 b/src/agentex/lib/cli/templates/default/project/acp.py.j2
@@ -1,6 +1,6 @@
 from agentex.lib.sdk.fastacp.fastacp import FastACP
 from agentex.lib.types.fastacp import AsyncACPConfig
-from agentex.lib.types.acp import SendEventParams, CancelTaskParams, CreateTaskParams
+from agentex.protocol.acp import SendEventParams, CancelTaskParams, CreateTaskParams
 from agentex.lib.utils.logging import make_logger
 from agentex.types.text_content import TextContent
 from agentex.lib import adk
diff --git a/src/agentex/lib/cli/templates/sync-langgraph/project/acp.py.j2 b/src/agentex/lib/cli/templates/sync-langgraph/project/acp.py.j2
@@ -11,7 +11,7 @@ import agentex.lib.adk as adk
 from agentex.lib.adk import create_langgraph_tracing_handler, convert_langgraph_to_agentex_events
 from agentex.lib.core.tracing.tracing_processor_manager import add_tracing_processor_config
 from agentex.lib.sdk.fastacp.fastacp import FastACP
-from agentex.lib.types.acp import SendMessageParams
+from agentex.protocol.acp import SendMessageParams
 from agentex.lib.types.tracing import SGPTracingProcessorConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.types.task_message_content import TaskMessageContent
diff --git a/src/agentex/lib/cli/templates/sync-openai-agents/project/acp.py.j2 b/src/agentex/lib/cli/templates/sync-openai-agents/project/acp.py.j2
@@ -4,7 +4,7 @@ from typing import AsyncGenerator, List
 from agentex.lib import adk
 from agentex.lib.adk.providers._modules.sync_provider import SyncStreamingProvider, convert_openai_to_agentex_events
 from agentex.lib.sdk.fastacp.fastacp import FastACP
-from agentex.lib.types.acp import SendMessageParams
+from agentex.protocol.acp import SendMessageParams
 from agentex.lib.core.tracing.tracing_processor_manager import add_tracing_processor_config
 from agentex.lib.types.tracing import SGPTracingProcessorConfig
 from agentex.lib.utils.model_utils import BaseModel
diff --git a/src/agentex/lib/cli/templates/sync-pydantic-ai/project/acp.py.j2 b/src/agentex/lib/cli/templates/sync-pydantic-ai/project/acp.py.j2
@@ -22,7 +22,7 @@ from agentex.lib.adk import (
     create_pydantic_ai_tracing_handler,
     convert_pydantic_ai_to_agentex_events,
 )
-from agentex.lib.types.acp import SendMessageParams
+from agentex.protocol.acp import SendMessageParams
 from agentex.lib.types.tracing import SGPTracingProcessorConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.sdk.fastacp.fastacp import FastACP
diff --git a/src/agentex/lib/cli/templates/sync/project/acp.py.j2 b/src/agentex/lib/cli/templates/sync/project/acp.py.j2
@@ -1,6 +1,6 @@
 from typing import AsyncGenerator, Union
 from agentex.lib.sdk.fastacp.fastacp import FastACP
-from agentex.lib.types.acp import SendMessageParams
+from agentex.protocol.acp import SendMessageParams
 
 from agentex.types.task_message_update import TaskMessageUpdate
 from agentex.types.task_message_content import TaskMessageContent
diff --git a/src/agentex/lib/cli/templates/temporal-openai-agents/project/workflow.py.j2 b/src/agentex/lib/cli/templates/temporal-openai-agents/project/workflow.py.j2
@@ -4,7 +4,7 @@ import os
 from temporalio import workflow
 
 from agentex.lib import adk
-from agentex.lib.types.acp import CreateTaskParams, SendEventParams
+from agentex.protocol.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
diff --git a/src/agentex/lib/cli/templates/temporal-pydantic-ai/project/workflow.py.j2 b/src/agentex/lib/cli/templates/temporal-pydantic-ai/project/workflow.py.j2
@@ -23,7 +23,7 @@ from temporalio import workflow
 from project.agent import TaskDeps, temporal_agent
 
 from agentex.lib import adk
-from agentex.lib.types.acp import SendEventParams, CreateTaskParams
+from agentex.protocol.acp import SendEventParams, CreateTaskParams
 from agentex.lib.types.tracing import SGPTracingProcessorConfig
 from agentex.lib.utils.logging import make_logger
 from agentex.types.text_content import TextContent
diff --git a/src/agentex/lib/cli/templates/temporal/project/workflow.py.j2 b/src/agentex/lib/cli/templates/temporal/project/workflow.py.j2
@@ -3,7 +3,7 @@ import json
 from temporalio import workflow
 
 from agentex.lib import adk
-from agentex.lib.types.acp import CreateTaskParams, SendEventParams
+from agentex.protocol.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
diff --git a/src/agentex/lib/core/temporal/services/temporal_task_service.py b/src/agentex/lib/core/temporal/services/temporal_task_service.py
@@ -6,7 +6,7 @@
 from agentex.types.task import Task
 from agentex.types.agent import Agent
 from agentex.types.event import Event
-from agentex.lib.types.acp import SendEventParams, CreateTaskParams
+from agentex.protocol.acp import SendEventParams, CreateTaskParams
 from agentex.lib.environment_variables import EnvironmentVariables
 from agentex.lib.core.clients.temporal.types import WorkflowState
 from agentex.lib.core.temporal.types.workflow import SignalName
diff --git a/src/agentex/lib/core/temporal/workflows/workflow.py b/src/agentex/lib/core/temporal/workflows/workflow.py
@@ -2,7 +2,7 @@
 
 from temporalio import workflow
 
-from agentex.lib.types.acp import SendEventParams, CreateTaskParams
+from agentex.protocol.acp import SendEventParams, CreateTaskParams
 from agentex.lib.utils.logging import make_logger
 from agentex.lib.core.temporal.types.workflow import SignalName
 
diff --git a/src/agentex/lib/sdk/fastacp/base/base_acp_server.py b/src/agentex/lib/sdk/fastacp/base/base_acp_server.py
@@ -14,7 +14,7 @@
 from starlette.types import Send, Scope, ASGIApp, Receive
 from fastapi.responses import StreamingResponse
 
-from agentex.lib.types.acp import (
+from agentex.protocol.acp import (
     RPC_SYNC_METHODS,
     PARAMS_MODEL_BY_METHOD,
     RPCMethod,
@@ -24,7 +24,7 @@
     SendMessageParams,
 )
 from agentex.lib.utils.logging import make_logger, ctx_var_request_id
-from agentex.lib.types.json_rpc import JSONRPCError, JSONRPCRequest, JSONRPCResponse
+from agentex.protocol.json_rpc import JSONRPCError, JSONRPCRequest, JSONRPCResponse
 from agentex.lib.utils.model_utils import BaseModel
 from agentex.lib.utils.registration import register_agent
 
diff --git a/src/agentex/lib/sdk/fastacp/impl/async_base_acp.py b/src/agentex/lib/sdk/fastacp/impl/async_base_acp.py
@@ -1,7 +1,7 @@
 from typing import Any
 from typing_extensions import override
 
-from agentex.lib.types.acp import (
+from agentex.protocol.acp import (
     SendEventParams,
     CancelTaskParams,
     CreateTaskParams,
diff --git a/src/agentex/lib/sdk/fastacp/impl/sync_acp.py b/src/agentex/lib/sdk/fastacp/impl/sync_acp.py
@@ -3,7 +3,7 @@
 from typing import Any, override
 from collections.abc import AsyncGenerator
 
-from agentex.lib.types.acp import SendMessageParams
+from agentex.protocol.acp import SendMessageParams
 from agentex.lib.utils.logging import make_logger
 from agentex.types.task_message_delta import TextDelta
 from agentex.types.task_message_update import (
diff --git a/src/agentex/lib/sdk/fastacp/impl/temporal_acp.py b/src/agentex/lib/sdk/fastacp/impl/temporal_acp.py
@@ -6,7 +6,7 @@
 from fastapi import FastAPI
 from temporalio.converter import PayloadCodec
 
-from agentex.lib.types.acp import (
+from agentex.protocol.acp import (
     SendEventParams,
     CancelTaskParams,
     CreateTaskParams,
diff --git a/src/agentex/lib/sdk/fastacp/tests/conftest.py b/src/agentex/lib/sdk/fastacp/tests/conftest.py
@@ -13,12 +13,12 @@
 
 from agentex.types.task import Task
 from agentex.types.agent import Agent
-from agentex.lib.types.acp import (
+from agentex.protocol.acp import (
     CancelTaskParams,
     CreateTaskParams,
     SendMessageParams,
 )
-from agentex.lib.types.json_rpc import JSONRPCRequest
+from agentex.protocol.json_rpc import JSONRPCRequest
 from agentex.types.task_message import TaskMessageContent
 from agentex.types.task_message_content import TextContent
 from agentex.lib.sdk.fastacp.impl.sync_acp import SyncACP
diff --git a/src/agentex/lib/sdk/fastacp/tests/test_base_acp_server.py b/src/agentex/lib/sdk/fastacp/tests/test_base_acp_server.py
@@ -5,7 +5,7 @@
 import pytest
 from fastapi.testclient import TestClient
 
-from agentex.lib.types.acp import (
+from agentex.protocol.acp import (
     RPCMethod,
     SendEventParams,
     CancelTaskParams,
diff --git a/src/agentex/lib/sdk/fastacp/tests/test_integration.py b/src/agentex/lib/sdk/fastacp/tests/test_integration.py
@@ -5,7 +5,7 @@
 import httpx
 import pytest
 
-from agentex.lib.types.acp import (
+from agentex.protocol.acp import (
     RPCMethod,
     SendEventParams,
     CancelTaskParams,
diff --git a/src/agentex/lib/types/acp.py b/src/agentex/lib/types/acp.py
@@ -1,116 +1,15 @@
-from __future__ import annotations
-
-from enum import Enum
-from typing import Any
-
-from pydantic import Field, BaseModel
-
-from agentex.types.task import Task
-from agentex.types.agent import Agent
-from agentex.types.event import Event
-from agentex.types.task_message_content import TaskMessageContent
-
-
-class RPCMethod(str, Enum):
-    """Available JSON-RPC methods for agent communication."""
-
-    EVENT_SEND = "event/send"
-    MESSAGE_SEND = "message/send"
-    TASK_CANCEL = "task/cancel"
-    TASK_CREATE = "task/create"
-
-
-class CreateTaskParams(BaseModel):
-    """Parameters for task/create method.
-
-    Attributes:
-        agent: The agent that the task was sent to.
-        task: The task to be created.
-        params: The parameters for the task as inputted by the user.
-        request: Additional request context including headers forwarded to this agent.
-    """
-
-    agent: Agent = Field(..., description="The agent that the task was sent to")
-    task: Task = Field(..., description="The task to be created")
-    params: dict[str, Any] | None = Field(
-        None,
-        description="The parameters for the task as inputted by the user",
-    )
-    request: dict[str, Any] | None = Field(
-        default=None,
-        description="Additional request context including headers forwarded to this agent",
-    )
-
-
-class SendMessageParams(BaseModel):
-    """Parameters for message/send method.
-
-    Attributes:
-        agent: The agent that the message was sent to.
-        task: The task that the message was sent to.
-        content: The message that was sent to the agent.
-        stream: Whether to stream the message back to the agentex server from the agent.
-        request: Additional request context including headers forwarded to this agent.
-    """
-
-    agent: Agent = Field(..., description="The agent that the message was sent to")
-    task: Task = Field(..., description="The task that the message was sent to")
-    content: TaskMessageContent = Field(
-        ..., description="The message that was sent to the agent"
-    )
-    stream: bool = Field(
-        False,
-        description="Whether to stream the message back to the agentex server from the agent",
-    )
-    request: dict[str, Any] | None = Field(
-        default=None,
-        description="Additional request context including headers forwarded to this agent",
-    )
-
-
-class SendEventParams(BaseModel):
-    """Parameters for event/send method.
-
-    Attributes:
-        agent: The agent that the event was sent to.
-        task: The task that the message was sent to.
-        event: The event that was sent to the agent.
-        request: Additional request context including headers forwarded to this agent.
-    """
-
-    agent: Agent = Field(..., description="The agent that the event was sent to")
-    task: Task = Field(..., description="The task that the message was sent to")
-    event: Event = Field(..., description="The event that was sent to the agent")
-    request: dict[str, Any] | None = Field(
-        default=None,
-        description="Additional request context including headers forwarded to this agent",
-    )
-
-
-class CancelTaskParams(BaseModel):
-    """Parameters for task/cancel method.
-
-    Attributes:
-        agent: The agent that the task was sent to.
-        task: The task that was cancelled.
-        request: Additional request context including headers forwarded to this agent.
-    """
-
-    agent: Agent = Field(..., description="The agent that the task was sent to")
-    task: Task = Field(..., description="The task that was cancelled")
-    request: dict[str, Any] | None = Field(
-        default=None,
-        description="Additional request context including headers forwarded to this agent",
-    )
-
-
-RPC_SYNC_METHODS = [
-    RPCMethod.MESSAGE_SEND,
-]
-
-PARAMS_MODEL_BY_METHOD: dict[RPCMethod, type[BaseModel]] = {
-    RPCMethod.EVENT_SEND: SendEventParams,
-    RPCMethod.TASK_CANCEL: CancelTaskParams,
-    RPCMethod.MESSAGE_SEND: SendMessageParams,
-    RPCMethod.TASK_CREATE: CreateTaskParams,
-}
+"""Back-compat shim. The canonical location is :mod:`agentex.protocol.acp`.
+
+Kept here so existing ``from agentex.lib.types.acp import ...`` imports
+continue to work. New code should import from the canonical path.
+"""
+
+from agentex.protocol.acp import (  # noqa: F401
+    RPC_SYNC_METHODS,
+    PARAMS_MODEL_BY_METHOD,
+    RPCMethod,
+    SendEventParams,
+    CancelTaskParams,
+    CreateTaskParams,
+    SendMessageParams,
+)
diff --git a/src/agentex/lib/types/json_rpc.py b/src/agentex/lib/types/json_rpc.py
diff --git a/src/agentex/protocol/__init__.py b/src/agentex/protocol/__init__.py
diff --git a/src/agentex/protocol/acp.py b/src/agentex/protocol/acp.py
diff --git a/src/agentex/protocol/json_rpc.py b/src/agentex/protocol/json_rpc.py
diff --git a/tests/test_header_forwarding.py b/tests/test_header_forwarding.py
diff --git a/tests/test_protocol_shims.py b/tests/test_protocol_shims.py

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ from agentex.lib.adk import (`
`28`	`28`	`stream_pydantic_ai_events,`
`29`	`29`	`create_pydantic_ai_tracing_handler,`
`30`	`30`	`)`
`31`		`-from agentex.lib.types.acp import SendEventParams, CancelTaskParams, CreateTaskParams`
	`31`	`+from agentex.protocol.acp import SendEventParams, CancelTaskParams, CreateTaskParams`
`32`	`32`	`from agentex.lib.types.fastacp import AsyncACPConfig`
`33`	`33`	`from agentex.lib.types.tracing import SGPTracingProcessorConfig`
`34`	`34`	`from agentex.lib.utils.logging import make_logger`
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ from agentex.lib.adk import (`
`22`	`22`	`create_pydantic_ai_tracing_handler,`
`23`	`23`	`convert_pydantic_ai_to_agentex_events,`
`24`	`24`	`)`
`25`		`-from agentex.lib.types.acp import SendMessageParams`
	`25`	`+from agentex.protocol.acp import SendMessageParams`
`26`	`26`	`from agentex.lib.types.tracing import SGPTracingProcessorConfig`
`27`	`27`	`from agentex.lib.utils.logging import make_logger`
`28`	`28`	`from agentex.lib.sdk.fastacp.fastacp import FastACP`