synchronity-sdk 0.5.18

Python SDK for the AgentMesh agentic commerce infrastructure

Synchronity Python SDK

Python SDK for the Synchronity agentic commerce infrastructure — makes any e-commerce site transactable by autonomous AI agents via authenticated REST APIs.

Installation

pip install synchronity-sdk

Or with dev dependencies for testing:

pip install "synchronity-sdk[dev]"

Quickstart

import asyncio
from agentmesh import SynchronityClient, SynchronityConfig

async def main():
    config = SynchronityConfig(agent_token="your-agent-token")

    async with SynchronityClient(config) as client:
        # Search products on a site
        results = await client.products.search("site_abc123", q="laptop", in_stock=True)
        print(results["products"])

        # Create a cart and add an item
        cart = await client.cart.create("site_abc123", currency="USD")
        cart = await client.cart.add_item("site_abc123", cart.cart_id, "prod_42", quantity=1)

        # Apply a coupon
        cart = await client.cart.apply_coupon("site_abc123", cart.cart_id, "SAVE10")

        # Execute checkout
        from agentmesh import ShippingAddressParams
        order = await client.checkout.execute(
            site_id="site_abc123",
            cart_id=cart.cart_id,
            buyer_delegation_token="buyer-token-from-auth-flow",
            customer_phone="[phone]",
            shipping_address=ShippingAddressParams(
                name="Jane Smith",
                line1="123 Main St",
                city="San Francisco",
                state="CA",
                postal_code="94102",
                country="US",  # any ISO 3166-1 alpha-2 code
                phone="[phone]",
            ),
        )
        print(order.order_id, order.status)

asyncio.run(main())

Tools for LLM Frameworks

The SDK ships ready-to-use tool definitions for Anthropic, OpenAI, and LangChain.

Anthropic

from agentmesh.tools import anthropic_tools, ToolExecutor
from agentmesh import SynchronityClient, SynchronityConfig
import anthropic

client = SynchronityClient(SynchronityConfig(agent_token="your-token"))
executor = ToolExecutor(client)

anthropic_client = anthropic.Anthropic()
response = anthropic_client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    tools=anthropic_tools,
    messages=[{"role": "user", "content": "Find me a red laptop under $1000 on site site_abc123"}],
)

# Execute tool calls
import asyncio
for block in response.content:
    if block.type == "tool_use":
        result = asyncio.run(executor.execute(block.name, block.input))
        print(result)

OpenAI

from agentmesh.tools import openai_tools, ToolExecutor
from openai import OpenAI

openai_client = OpenAI()
response = openai_client.chat.completions.create(
    model="gpt-4o",
    tools=openai_tools,
    messages=[{"role": "user", "content": "Search for laptops on site_abc123"}],
)

LangChain

from agentmesh.tools import langchain_tools
# langchain_tools is a list of dicts with name, description, and schema

Available Tools (11)

Tool	Description
search_products	Search products on a site with filters
get_product	Get full product details by ID
compare_products	Compare products across multiple sites
create_cart	Create a new shopping cart
add_to_cart	Add a product/variant to a cart
remove_from_cart	Remove a line item from a cart
apply_coupon	Apply a discount code to a cart
get_cart	Get current cart contents
execute_checkout	Execute checkout and return a confirmed order
get_order	Get order details by ID
list_orders	List orders with optional status filter

Configuration

from agentmesh import SynchronityConfig

config = SynchronityConfig(
    agent_token="your-agent-token",   # required
    base_url="https://api.synchronity.app",  # default
    timeout=30.0,    # seconds
    retries=3,       # auto-retry on 429 and 5xx
    retry_delay=1.0, # base delay for exponential backoff
)

Error Handling

from agentmesh.errors import (
    AuthenticationError,   # 401
    AuthorizationError,    # 403
    NotFoundError,         # 404 / 410
    ValidationError,       # 400
    RateLimitError,        # 429 — has .retry_after attribute
    ConnectorError,        # 422
    NetworkError,          # network failures
    TimeoutError,          # request timeout
    SynchronityError,        # base class
)

try:
    product = await client.products.get_by_id("site_abc", "prod_999")
except NotFoundError as e:
    print(f"Product not found: {e.code}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

Running Tests

pip install -e ".[dev]"
pytest tests/ -v