adcp 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

adcp/__init__.py

@@ -18,6 +18,19 @@ from adcp.exceptions import (
     ADCPWebhookError,
     ADCPWebhookSignatureError,
 )
+
+# Test helpers
+from adcp.testing import (
+    CREATIVE_AGENT_CONFIG,
+    TEST_AGENT_A2A_CONFIG,
+    TEST_AGENT_MCP_CONFIG,
+    TEST_AGENT_TOKEN,
+    create_test_agent,
+    creative_agent,
+    test_agent,
+    test_agent_a2a,
+    test_agent_client,
+)
 from adcp.types.core import AgentConfig, Protocol, TaskResult, TaskStatus, WebhookMetadata
 from adcp.types.generated import (
     ActivateSignalError,
@@ -133,7 +146,7 @@ from adcp.types.generated import (
     TaskStatus as GeneratedTaskStatus,
 )
 
-__version__ = "1.2.1"
+__version__ = "1.3.0"
 
 __all__ = [
     # Client classes
@@ -145,6 +158,16 @@ __all__ = [
     "TaskResult",
     "TaskStatus",
     "WebhookMetadata",
+    # Test helpers
+    "test_agent",
+    "test_agent_a2a",
+    "creative_agent",
+    "test_agent_client",
+    "create_test_agent",
+    "TEST_AGENT_TOKEN",
+    "TEST_AGENT_MCP_CONFIG",
+    "TEST_AGENT_A2A_CONFIG",
+    "CREATIVE_AGENT_CONFIG",
     # Exceptions
     "ADCPError",
     "ADCPConnectionError",

adcp/testing/__init__.py

@@ -0,0 +1,38 @@
+"""Test helpers for AdCP client library.
+
+Provides pre-configured test agents for examples and quick testing.
+"""
+
+from __future__ import annotations
+
+from adcp.testing.test_helpers import (
+    CREATIVE_AGENT_CONFIG,
+    TEST_AGENT_A2A_CONFIG,
+    TEST_AGENT_A2A_NO_AUTH_CONFIG,
+    TEST_AGENT_MCP_CONFIG,
+    TEST_AGENT_MCP_NO_AUTH_CONFIG,
+    TEST_AGENT_TOKEN,
+    create_test_agent,
+    creative_agent,
+    test_agent,
+    test_agent_a2a,
+    test_agent_a2a_no_auth,
+    test_agent_client,
+    test_agent_no_auth,
+)
+
+__all__ = [
+    "test_agent",
+    "test_agent_a2a",
+    "test_agent_no_auth",
+    "test_agent_a2a_no_auth",
+    "creative_agent",
+    "test_agent_client",
+    "create_test_agent",
+    "TEST_AGENT_TOKEN",
+    "TEST_AGENT_MCP_CONFIG",
+    "TEST_AGENT_A2A_CONFIG",
+    "TEST_AGENT_MCP_NO_AUTH_CONFIG",
+    "TEST_AGENT_A2A_NO_AUTH_CONFIG",
+    "CREATIVE_AGENT_CONFIG",
+]

adcp/testing/test_helpers.py

@@ -0,0 +1,311 @@
+"""Test agent helpers for easy examples and quick testing.
+
+These provide pre-configured access to AdCP's public test agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from adcp.client import ADCPClient, ADCPMultiAgentClient
+from adcp.types.core import AgentConfig, Protocol
+
+# Public test agent auth token
+# This token is public and rate-limited, for testing/examples only.
+TEST_AGENT_TOKEN = "1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ"
+
+# Public test agent configuration - MCP protocol
+TEST_AGENT_MCP_CONFIG = AgentConfig(
+    id="test-agent-mcp",
+    agent_uri="https://test-agent.adcontextprotocol.org/mcp/",
+    protocol=Protocol.MCP,
+    auth_token=TEST_AGENT_TOKEN,
+)
+
+# Public test agent configuration - A2A protocol
+TEST_AGENT_A2A_CONFIG = AgentConfig(
+    id="test-agent-a2a",
+    agent_uri="https://test-agent.adcontextprotocol.org",
+    protocol=Protocol.A2A,
+    auth_token=TEST_AGENT_TOKEN,
+)
+
+# Public test agent configuration (no auth) - MCP protocol
+TEST_AGENT_MCP_NO_AUTH_CONFIG = AgentConfig(
+    id="test-agent-mcp-no-auth",
+    agent_uri="https://test-agent.adcontextprotocol.org/mcp/",
+    protocol=Protocol.MCP,
+)
+
+# Public test agent configuration (no auth) - A2A protocol
+TEST_AGENT_A2A_NO_AUTH_CONFIG = AgentConfig(
+    id="test-agent-a2a-no-auth",
+    agent_uri="https://test-agent.adcontextprotocol.org",
+    protocol=Protocol.A2A,
+)
+
+# Reference creative agent configuration - MCP protocol
+# No authentication required for the reference creative agent
+CREATIVE_AGENT_CONFIG = AgentConfig(
+    id="creative-agent",
+    agent_uri="https://creative.adcontextprotocol.org/mcp",
+    protocol=Protocol.MCP,
+)
+
+
+def _create_test_agent_client() -> ADCPClient:
+    """Create pre-configured test agent client using MCP protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent
+
+    Note:
+        This agent is rate-limited and intended for testing/examples only.
+        The auth token is public and may be rotated without notice.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_MCP_CONFIG)
+
+
+def _create_test_agent_a2a_client() -> ADCPClient:
+    """Create pre-configured test agent client using A2A protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent
+
+    Note:
+        This agent is rate-limited and intended for testing/examples only.
+        The auth token is public and may be rotated without notice.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_A2A_CONFIG)
+
+
+def _create_test_agent_no_auth_client() -> ADCPClient:
+    """Create pre-configured test agent client (no auth) using MCP protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent without authentication
+
+    Note:
+        This agent is rate-limited and intended for testing scenarios where no auth is provided.
+        Useful for testing behavior differences between authenticated and unauthenticated requests.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_MCP_NO_AUTH_CONFIG)
+
+
+def _create_test_agent_a2a_no_auth_client() -> ADCPClient:
+    """Create pre-configured test agent client (no auth) using A2A protocol.
+
+    Returns:
+        ADCPClient instance configured for the public test agent without authentication
+
+    Note:
+        This agent is rate-limited and intended for testing scenarios where no auth is provided.
+        Useful for testing behavior differences between authenticated and unauthenticated requests.
+        DO NOT use in production applications.
+    """
+    return ADCPClient(TEST_AGENT_A2A_NO_AUTH_CONFIG)
+
+
+def _create_creative_agent_client() -> ADCPClient:
+    """Create pre-configured creative agent client.
+
+    Returns:
+        ADCPClient instance configured for the reference creative agent
+
+    Note:
+        The reference creative agent is public and requires no authentication.
+        It provides creative preview functionality for testing and examples.
+    """
+    return ADCPClient(CREATIVE_AGENT_CONFIG)
+
+
+def _create_test_multi_agent_client() -> ADCPMultiAgentClient:
+    """Create multi-agent client with both test agents configured.
+
+    Returns:
+        ADCPMultiAgentClient with both MCP and A2A test agents
+
+    Note:
+        This client is rate-limited and intended for testing/examples only.
+        DO NOT use in production applications.
+    """
+    return ADCPMultiAgentClient([TEST_AGENT_MCP_CONFIG, TEST_AGENT_A2A_CONFIG])
+
+
+# Pre-configured test agent client using MCP protocol.
+# Ready to use for examples, documentation, and quick testing.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent
+#
+#     # Simple get_products call
+#     result = await test_agent.get_products(
+#         GetProductsRequest(
+#             brief="Coffee subscription service for busy professionals",
+#             promoted_offering="Premium monthly coffee deliveries"
+#         )
+#     )
+#
+#     if result.success:
+#         print(f"Found {len(result.data.products)} products")
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     The auth token is public and may be rotated without notice.
+#     DO NOT use in production applications.
+test_agent: ADCPClient = _create_test_agent_client()
+
+# Pre-configured test agent client using A2A protocol.
+# Identical functionality to test_agent but uses A2A instead of MCP.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_a2a
+#
+#     result = await test_agent_a2a.get_products(
+#         GetProductsRequest(
+#             brief="Sustainable fashion brands",
+#             promoted_offering="Eco-friendly clothing"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     The auth token is public and may be rotated without notice.
+#     DO NOT use in production applications.
+test_agent_a2a: ADCPClient = _create_test_agent_a2a_client()
+
+# Pre-configured test agent client (no auth) using MCP protocol.
+# Useful for testing scenarios where authentication is not provided,
+# such as testing how agents handle unauthenticated requests or
+# comparing behavior between authenticated and unauthenticated calls.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_no_auth
+#
+#     # Test behavior without authentication
+#     result = await test_agent_no_auth.get_products(
+#         GetProductsRequest(
+#             brief="Coffee subscription service",
+#             promoted_offering="Premium monthly coffee"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     DO NOT use in production applications.
+test_agent_no_auth: ADCPClient = _create_test_agent_no_auth_client()
+
+# Pre-configured test agent client (no auth) using A2A protocol.
+# Identical functionality to test_agent_no_auth but uses A2A instead of MCP.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_a2a_no_auth
+#
+#     # Test A2A behavior without authentication
+#     result = await test_agent_a2a_no_auth.get_products(
+#         GetProductsRequest(
+#             brief="Sustainable fashion brands",
+#             promoted_offering="Eco-friendly clothing"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This agent is rate-limited and intended for testing/examples only.
+#     DO NOT use in production applications.
+test_agent_a2a_no_auth: ADCPClient = _create_test_agent_a2a_no_auth_client()
+
+# Pre-configured reference creative agent.
+# Provides creative preview functionality without authentication.
+#
+# Example:
+#     ```python
+#     from adcp.testing import creative_agent
+#     from adcp.types.generated import PreviewCreativeRequest
+#
+#     result = await creative_agent.preview_creative(
+#         PreviewCreativeRequest(
+#             manifest={
+#                 "format_id": "banner_300x250",
+#                 "assets": {...}
+#             }
+#         )
+#     )
+#     ```
+#
+# Note:
+#     The reference creative agent is public and requires no authentication.
+#     Perfect for testing creative rendering and preview functionality.
+creative_agent: ADCPClient = _create_creative_agent_client()
+
+# Multi-agent client with both test agents configured.
+# Useful for testing multi-agent patterns and protocol comparisons.
+#
+# Example:
+#     ```python
+#     from adcp.testing import test_agent_client
+#
+#     # Access individual agents
+#     mcp_agent = test_agent_client.agent("test-agent-mcp")
+#     a2a_agent = test_agent_client.agent("test-agent-a2a")
+#
+#     # Use for parallel operations
+#     results = await test_agent_client.get_products(
+#         GetProductsRequest(
+#             brief="Premium coffee brands",
+#             promoted_offering="Artisan coffee"
+#         )
+#     )
+#     ```
+#
+# Note:
+#     This client is rate-limited and intended for testing/examples only.
+#     DO NOT use in production applications.
+test_agent_client: ADCPMultiAgentClient = _create_test_multi_agent_client()
+
+
+def create_test_agent(**overrides: Any) -> AgentConfig:
+    """Create a custom test agent configuration.
+
+    Useful when you need to modify the default test agent setup.
+
+    Args:
+        **overrides: Keyword arguments to override default config values
+
+    Returns:
+        Complete agent configuration
+
+    Example:
+        ```python
+        from adcp.testing import create_test_agent
+        from adcp.client import ADCPClient
+
+        # Use default test agent with custom ID
+        config = create_test_agent(id="my-test-agent")
+        client = ADCPClient(config)
+        ```
+
+    Example:
+        ```python
+        # Use A2A protocol instead of MCP
+        from adcp.types.core import Protocol
+
+        config = create_test_agent(
+            protocol=Protocol.A2A,
+            agent_uri="https://test-agent.adcontextprotocol.org"
+        )
+        ```
+    """
+    base_config = TEST_AGENT_MCP_CONFIG.model_dump()
+    base_config.update(overrides)
+    return AgentConfig(**base_config)

{adcp-1.2.1.dist-info → adcp-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.2.1
+Version: 1.3.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -61,8 +61,43 @@ pip install adcp
 
 > **Note**: This client requires Python 3.10 or later and supports both synchronous and asynchronous workflows.
 
+## Quick Start: Test Helpers
+
+The fastest way to get started is using the pre-configured test agents:
+
+```python
+from adcp.testing import test_agent
+from adcp.types.generated import GetProductsRequest
+
+# Zero configuration - just import and use!
+result = await test_agent.get_products(
+    GetProductsRequest(
+        brief="Coffee subscription service",
+        promoted_offering="Premium coffee deliveries"
+    )
+)
+
+if result.success:
+    print(f"Found {len(result.data.products)} products")
+```
+
+Test helpers include:
+- **`test_agent`**: Pre-configured MCP test agent with authentication
+- **`test_agent_a2a`**: Pre-configured A2A test agent with authentication
+- **`test_agent_no_auth`**: Pre-configured MCP test agent WITHOUT authentication
+- **`test_agent_a2a_no_auth`**: Pre-configured A2A test agent WITHOUT authentication
+- **`creative_agent`**: Reference creative agent for preview functionality
+- **`test_agent_client`**: Multi-agent client with both protocols
+- **`create_test_agent()`**: Factory for custom test configurations
+
+> **Note**: Test agents are rate-limited and for testing/examples only. DO NOT use in production.
+
+See [examples/test_helpers_demo.py](examples/test_helpers_demo.py) for more examples.
+
 ## Quick Start: Distributed Operations
 
+For production use, configure your own agents:
+
 ```python
 from adcp import ADCPMultiAgentClient, AgentConfig, GetProductsRequest
 
@@ -112,6 +147,66 @@ async with ADCPMultiAgentClient(
 
 ## Features
 
+### Test Helpers
+
+Pre-configured test agents for instant prototyping and testing:
+
+```python
+from adcp.testing import (
+    test_agent, test_agent_a2a,
+    test_agent_no_auth, test_agent_a2a_no_auth,
+    creative_agent, test_agent_client, create_test_agent
+)
+from adcp.types.generated import GetProductsRequest, PreviewCreativeRequest
+
+# 1. Single agent with authentication (MCP)
+result = await test_agent.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 2. Single agent with authentication (A2A)
+result = await test_agent_a2a.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 3. Single agent WITHOUT authentication (MCP)
+# Useful for testing unauthenticated behavior
+result = await test_agent_no_auth.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 4. Single agent WITHOUT authentication (A2A)
+result = await test_agent_a2a_no_auth.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 5. Creative agent (preview functionality, no auth required)
+result = await creative_agent.preview_creative(
+    PreviewCreativeRequest(
+        manifest={"format_id": "banner_300x250", "assets": {...}}
+    )
+)
+
+# 6. Multi-agent (parallel execution with both protocols)
+results = await test_agent_client.get_products(
+    GetProductsRequest(brief="Coffee brands")
+)
+
+# 7. Custom configuration
+from adcp.client import ADCPClient
+config = create_test_agent(id="my-test", timeout=60.0)
+client = ADCPClient(config)
+```
+
+**Use cases:**
+- Quick prototyping and experimentation
+- Example code and documentation
+- Integration testing without mock servers
+- Testing authentication behavior (comparing auth vs no-auth results)
+- Learning AdCP concepts
+
+**Important:** Test agents are public, rate-limited, and for testing only. Never use in production.
+
 ### Full Protocol Support
 - **A2A Protocol**: Native support for Agent-to-Agent protocol
 - **MCP Protocol**: Native support for Model Context Protocol
@@ -377,6 +472,46 @@ uvx adcp --json myagent get_products '{"brief":"TV ads"}'
 uvx adcp --debug myagent get_products '{"brief":"TV ads"}'
 ```
 
+### Using Test Agents from CLI
+
+The CLI provides easy access to public test agents without configuration:
+
+```bash
+# Use test agent with authentication (MCP)
+uvx adcp https://test-agent.adcontextprotocol.org/mcp/ \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ \
+  get_products '{"brief":"Coffee brands"}'
+
+# Use test agent WITHOUT authentication (MCP)
+uvx adcp https://test-agent.adcontextprotocol.org/mcp/ \
+  get_products '{"brief":"Coffee brands"}'
+
+# Use test agent with authentication (A2A)
+uvx adcp --protocol a2a \
+  --auth 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ \
+  https://test-agent.adcontextprotocol.org \
+  get_products '{"brief":"Coffee brands"}'
+
+# Save test agent for easier access
+uvx adcp --save-auth test-agent https://test-agent.adcontextprotocol.org/mcp/ mcp
+# Enter token when prompted: 1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ
+
+# Now use saved config
+uvx adcp test-agent get_products '{"brief":"Coffee brands"}'
+
+# Use creative agent (no auth required)
+uvx adcp https://creative.adcontextprotocol.org/mcp \
+  preview_creative @creative_manifest.json
+```
+
+**Test Agent Details:**
+- **URL (MCP)**: `https://test-agent.adcontextprotocol.org/mcp/`
+- **URL (A2A)**: `https://test-agent.adcontextprotocol.org`
+- **Auth Token**: `1v8tAhASaUYYp4odoQ1PnMpdqNaMiTrCRqYo9OJp6IQ` (optional, public token)
+- **Rate Limited**: For testing only, not for production
+- **No Auth Mode**: Omit `--auth` flag to test unauthenticated behavior
+```
+
 ### Configuration Management
 
 ```bash

{adcp-1.2.1.dist-info → adcp-1.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-adcp/__init__.py,sha256=3UpoB71XItkSZ_r1QuzE2GZIQsgVjt50ZawxQUO2-qs,6232
+adcp/__init__.py,sha256=FRJ5kL682ZQiohuDyzUzwLvrOEUM7Hjy0aavfo4g4gc,6724
 adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
 adcp/client.py,sha256=co4tKdkjDrqZltCUPcYwVRr8LQfbBbG-DLjapLjcVuo,28246
 adcp/config.py,sha256=Vsy7ZPOI8G3fB_i5Nk-CHbC7wdasCUWuKlos0fwA0kY,2017
@@ -7,6 +7,8 @@ adcp/protocols/__init__.py,sha256=6UFwACQ0QadBUzy17wUROHqsJDp8ztPW2jzyl53Zh_g,26
 adcp/protocols/a2a.py,sha256=FHgc6G_eU2qD0vH7_RyS1eZvUFSb2j3-EsceoHPi384,12467
 adcp/protocols/base.py,sha256=vBHD23Fzl_CCk_Gy9nvSbBYopcJlYkYyzoz-rhI8wHg,5214
 adcp/protocols/mcp.py,sha256=eIk8snCinZm-ZjdarGVMt5nEYJ4_8POM9Fa5Mkw7xxU,15902
+adcp/testing/__init__.py,sha256=kPsRncZ42g4HpOljVwLrFXm2O28K5NKcPUtvykfYY6M,888
+adcp/testing/test_helpers.py,sha256=4n8fZYy1cVpjZpFW2SxBzpC8fmY-MBFrzY4tIPqe4rQ,10028
 adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
 adcp/types/core.py,sha256=RXkKCWCXS9BVJTNpe3Opm5O1I_LaQPMUuVwa-ipvS1Q,4839
 adcp/types/generated.py,sha256=Ig4ucbJzKRuHlwYzsqvMF9M3w2KghhQQqsXuOnBqVMM,74993
@@ -15,9 +17,9 @@ adcp/utils/__init__.py,sha256=uetvSJB19CjQbtwEYZiTnumJG11GsafQmXm5eR3hL7E,153
 adcp/utils/operation_id.py,sha256=wQX9Bb5epXzRq23xoeYPTqzu5yLuhshg7lKJZihcM2k,294
 adcp/utils/preview_cache.py,sha256=8_2qs5CgrHv1_WOnD4bs43VWueu-rcZRu5PZMQ_lyuE,17573
 adcp/utils/response_parser.py,sha256=uPk2vIH-RYZmq7y3i8lC4HTMQ3FfKdlgXKTjgJ1955M,6253
-adcp-1.2.1.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
-adcp-1.2.1.dist-info/METADATA,sha256=mDI2lRdXxOluUZ9vgRE3fyoGSnj8DQ8nqBU30Tuphjg,14568
-adcp-1.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adcp-1.2.1.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
-adcp-1.2.1.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
-adcp-1.2.1.dist-info/RECORD,,
+adcp-1.3.0.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-1.3.0.dist-info/METADATA,sha256=QQQ8zxzwIelNWUxz-ZBTTgpORHp9RrxT-1BnjFZ5S_o,19097
+adcp-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-1.3.0.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
+adcp-1.3.0.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-1.3.0.dist-info/RECORD,,