strands-asyntai 0.1.0__tar.gz

strands_asyntai-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,24 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        strands: ["strands-agents==1.30.0", "strands-agents"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[test]" "${{ matrix.strands }}"
+      - run: pytest tests/test_client.py tests/test_plugin.py -v

strands_asyntai-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+catalog-entry.yaml

strands_asyntai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asyntai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strands_asyntai-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: strands-asyntai
+Version: 0.1.0
+Summary: Asyntai tools for Strands Agents: give your agent a whole website's knowledge, chats and leads
+Project-URL: Homepage, https://asyntai.com/documentation/integrations/strands/
+Project-URL: Documentation, https://asyntai.com/documentation/integrations/strands/
+Project-URL: Source, https://github.com/asyntai/strands-asyntai
+Author-email: Asyntai <hello@asyntai.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,asyntai,chatbot,leads,plugin,rag,strands,strands-agents,tools,website
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: strands-agents>=1.30.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# strands-asyntai
+
+[Strands Agents](https://strandsagents.com) tools for [Asyntai](https://asyntai.com), the AI chat agent for websites.
+
+Point Asyntai at a website. It reads the pages, the product feed and the documents, and keeps them current. `AsyntaiPlugin` hands that knowledge to any Strands agent, together with the website's chats and leads. Your agent answers questions about a real business without you building or maintaining an index.
+
+Full guide: [asyntai.com/documentation/integrations/strands](https://asyntai.com/documentation/integrations/strands/)
+
+## Install
+
+```bash
+pip install strands-asyntai
+```
+
+## Set the key
+
+Create an API key in the Asyntai dashboard under **Settings → API**. The API is available on the Starter plan and higher.
+
+```bash
+export ASYNTAI_API_KEY="your-key"
+```
+
+## Use it
+
+```python
+from strands import Agent
+from strands_asyntai import AsyntaiPlugin
+
+agent = Agent(plugins=[AsyntaiPlugin()])
+
+agent('Do they ship to Spain, and how long does it take?')
+```
+
+The questions of one plugin instance share one website conversation, so follow-up questions keep their context. To continue a conversation later, for example one per customer, pass `session_id="customer-42"`. Every conversation also shows in your Asyntai chat logs.
+
+## The tools
+
+| Tool | What the agent can do | On by default |
+| --- | --- | --- |
+| `asyntai_ask_website` | Answer a question from the website: products, prices, stock, delivery, opening hours, policies, documentation. | Yes |
+| `asyntai_list_websites` | List the website agents on the account, with their ids. | Yes |
+| `asyntai_list_knowledge` | List the pages, texts and files the website agent knows. | Yes |
+| `asyntai_get_leads` | Read the visitors who left an email address or a phone number. | Yes (`lead_tools`) |
+| `asyntai_get_conversation` | Read the messages of one website chat. | Yes (`lead_tools`) |
+| `asyntai_add_text` | Store a text so the website agent uses it in later answers. | No (`knowledge_tools`) |
+| `asyntai_add_url` | Read a page into the knowledge base. | No (`knowledge_tools`) |
+
+```python
+AsyntaiPlugin(
+    website_id=42,          # which website agent, when the account has several
+    lead_tools=False,       # hide visitor contact details and chats
+    knowledge_tools=True,   # allow writing to the knowledge base
+)
+```
+
+## Use the tools without the plugin
+
+`asyntai_tools()` takes the same arguments and returns a plain list, so you can mix the tools with your own:
+
+```python
+from strands import Agent
+from strands_asyntai import asyntai_tools
+
+agent = Agent(tools=[*asyntai_tools(lead_tools=False), my_other_tool])
+```
+
+## Errors
+
+A failed call reaches the model as a tool error with a clear message, for example a wrong API key or a wrong `website_id`. The model can then correct the call or explain the problem to the user.
+
+## Requirements
+
+Python 3.10 or higher and `strands-agents` 1.30 or higher.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+`tests/test_live.py` runs against a real Asyntai server when `ASYNTAI_LIVE_KEY` and `ASYNTAI_LIVE_URL` are set.
+
+## License
+
+MIT

strands_asyntai-0.1.0/README.md

@@ -0,0 +1,86 @@
+# strands-asyntai
+
+[Strands Agents](https://strandsagents.com) tools for [Asyntai](https://asyntai.com), the AI chat agent for websites.
+
+Point Asyntai at a website. It reads the pages, the product feed and the documents, and keeps them current. `AsyntaiPlugin` hands that knowledge to any Strands agent, together with the website's chats and leads. Your agent answers questions about a real business without you building or maintaining an index.
+
+Full guide: [asyntai.com/documentation/integrations/strands](https://asyntai.com/documentation/integrations/strands/)
+
+## Install
+
+```bash
+pip install strands-asyntai
+```
+
+## Set the key
+
+Create an API key in the Asyntai dashboard under **Settings → API**. The API is available on the Starter plan and higher.
+
+```bash
+export ASYNTAI_API_KEY="your-key"
+```
+
+## Use it
+
+```python
+from strands import Agent
+from strands_asyntai import AsyntaiPlugin
+
+agent = Agent(plugins=[AsyntaiPlugin()])
+
+agent('Do they ship to Spain, and how long does it take?')
+```
+
+The questions of one plugin instance share one website conversation, so follow-up questions keep their context. To continue a conversation later, for example one per customer, pass `session_id="customer-42"`. Every conversation also shows in your Asyntai chat logs.
+
+## The tools
+
+| Tool | What the agent can do | On by default |
+| --- | --- | --- |
+| `asyntai_ask_website` | Answer a question from the website: products, prices, stock, delivery, opening hours, policies, documentation. | Yes |
+| `asyntai_list_websites` | List the website agents on the account, with their ids. | Yes |
+| `asyntai_list_knowledge` | List the pages, texts and files the website agent knows. | Yes |
+| `asyntai_get_leads` | Read the visitors who left an email address or a phone number. | Yes (`lead_tools`) |
+| `asyntai_get_conversation` | Read the messages of one website chat. | Yes (`lead_tools`) |
+| `asyntai_add_text` | Store a text so the website agent uses it in later answers. | No (`knowledge_tools`) |
+| `asyntai_add_url` | Read a page into the knowledge base. | No (`knowledge_tools`) |
+
+```python
+AsyntaiPlugin(
+    website_id=42,          # which website agent, when the account has several
+    lead_tools=False,       # hide visitor contact details and chats
+    knowledge_tools=True,   # allow writing to the knowledge base
+)
+```
+
+## Use the tools without the plugin
+
+`asyntai_tools()` takes the same arguments and returns a plain list, so you can mix the tools with your own:
+
+```python
+from strands import Agent
+from strands_asyntai import asyntai_tools
+
+agent = Agent(tools=[*asyntai_tools(lead_tools=False), my_other_tool])
+```
+
+## Errors
+
+A failed call reaches the model as a tool error with a clear message, for example a wrong API key or a wrong `website_id`. The model can then correct the call or explain the problem to the user.
+
+## Requirements
+
+Python 3.10 or higher and `strands-agents` 1.30 or higher.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+`tests/test_live.py` runs against a real Asyntai server when `ASYNTAI_LIVE_KEY` and `ASYNTAI_LIVE_URL` are set.
+
+## License
+
+MIT

strands_asyntai-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strands-asyntai"
+version = "0.1.0"
+description = "Asyntai tools for Strands Agents: give your agent a whole website's knowledge, chats and leads"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Asyntai", email = "hello@asyntai.com" }]
+keywords = ["strands", "strands-agents", "agents", "tools", "plugin", "asyntai", "rag", "chatbot", "website", "leads"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "strands-agents>=1.30.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://asyntai.com/documentation/integrations/strands/"
+Documentation = "https://asyntai.com/documentation/integrations/strands/"
+Source = "https://github.com/asyntai/strands-asyntai"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strands_asyntai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

strands_asyntai-0.1.0/src/strands_asyntai/__init__.py

@@ -0,0 +1,13 @@
+"""Asyntai tools for Strands Agents."""
+
+from .client import AsyntaiClient, AsyntaiError, AsyntaiRequestError
+from .plugin import AsyntaiPlugin, asyntai_tools
+
+__all__ = [
+    'AsyntaiClient',
+    'AsyntaiError',
+    'AsyntaiPlugin',
+    'AsyntaiRequestError',
+    'asyntai_tools',
+]
+__version__ = '0.1.0'

strands_asyntai-0.1.0/src/strands_asyntai/client.py

@@ -0,0 +1,146 @@
+"""HTTP client for the Asyntai public API.
+
+Every tool in this package goes through this client, so authentication,
+timeouts and error messages have one implementation. The API is documented at
+https://asyntai.com/documentation/api-reference/.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = 'https://asyntai.com'
+DEFAULT_TIMEOUT = 60.0
+USER_AGENT = 'strands-asyntai'
+
+
+class AsyntaiError(RuntimeError):
+    """The Asyntai API refused a call, or could not be reached."""
+
+
+class AsyntaiRequestError(AsyntaiError):
+    """The Asyntai API refused the arguments of one call (HTTP 400 or 404)."""
+
+
+def resolve_api_key(api_key: str | None) -> str:
+    key = api_key or os.environ.get('ASYNTAI_API_KEY', '')
+    if not key:
+        raise AsyntaiError(
+            'An Asyntai API key is required. Pass api_key=... or set the '
+            'ASYNTAI_API_KEY environment variable. Create a key in the Asyntai '
+            'dashboard under Settings -> API.'
+        )
+    return key
+
+
+class AsyntaiClient:
+    """Calls the Asyntai REST API with one API key."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.api_key = resolve_api_key(api_key)
+        self.base_url = base_url.rstrip('/')
+        self.timeout = timeout
+        self._transport = transport
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        headers = {
+            'Authorization': f'Bearer {self.api_key}',
+            'Accept': 'application/json',
+            'User-Agent': USER_AGENT,
+        }
+        try:
+            with httpx.Client(base_url=self.base_url, timeout=self.timeout, transport=self._transport) as http:
+                response = http.request(method, path, headers=headers, params=params, json=json_body)
+        except httpx.HTTPError as exc:
+            raise AsyntaiError(f'Could not reach the Asyntai API: {exc}') from exc
+
+        try:
+            payload = response.json()
+        except ValueError:
+            raise AsyntaiError(f'Asyntai returned a non-JSON response (HTTP {response.status_code}).') from None
+        if not isinstance(payload, dict):
+            raise AsyntaiError('Asyntai returned an unexpected response body.')
+
+        if response.status_code == 401:
+            raise AsyntaiError('Asyntai rejected the API key. Check the key in Settings -> API.')
+        if response.status_code == 403:
+            raise AsyntaiError('The Asyntai API needs the Starter plan or higher. See https://asyntai.com/pricing/.')
+        if response.status_code == 429:
+            raise AsyntaiError('The Asyntai message limit for this month is reached.')
+        message = payload.get('error') or f'Asyntai API error (HTTP {response.status_code}).'
+        if response.status_code in (400, 404):
+            raise AsyntaiRequestError(message)
+        if not payload.get('success', False):
+            raise AsyntaiError(message)
+        return payload
+
+    def chat(self, message: str, *, session_id: str | None = None, website_id: int | None = None) -> dict[str, Any]:
+        """POST /api/v1/chat/: ask the website agent a question."""
+        body: dict[str, Any] = {'message': message}
+        if session_id:
+            body['session_id'] = session_id
+        if website_id is not None:
+            body['website_id'] = website_id
+        return self._request('POST', '/api/v1/chat/', json_body=body)
+
+    def websites(self) -> list[dict[str, Any]]:
+        """GET /api/v1/websites/: the website agents on this account."""
+        return self._request('GET', '/api/v1/websites/').get('websites', [])
+
+    def knowledge(self, *, limit: int = 50, website_id: int | None = None) -> list[dict[str, Any]]:
+        """GET /api/v1/knowledge/: what the website agent knows."""
+        params: dict[str, Any] = {'limit': limit}
+        if website_id is not None:
+            params['website_id'] = website_id
+        return self._request('GET', '/api/v1/knowledge/', params=params).get('entries', [])
+
+    def add_text(self, title: str, content: str, *, website_id: int | None = None) -> dict[str, Any]:
+        """POST /api/v1/knowledge/text/: store a text in the knowledge base."""
+        body: dict[str, Any] = {'title': title, 'content': content}
+        if website_id is not None:
+            body['website_id'] = website_id
+        return self._request('POST', '/api/v1/knowledge/text/', json_body=body)
+
+    def add_url(self, url: str, *, website_id: int | None = None) -> dict[str, Any]:
+        """POST /api/v1/knowledge/url/: read a page into the knowledge base."""
+        body: dict[str, Any] = {'url': url}
+        if website_id is not None:
+            body['website_id'] = website_id
+        return self._request('POST', '/api/v1/knowledge/url/', json_body=body)
+
+    def leads(
+        self,
+        *,
+        limit: int = 20,
+        website_id: int | None = None,
+        since: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """GET /api/v1/leads/: visitors who left an email address or a phone number."""
+        params: dict[str, Any] = {'limit': limit}
+        if website_id is not None:
+            params['website_id'] = website_id
+        if since:
+            params['since'] = since
+        return self._request('GET', '/api/v1/leads/', params=params).get('leads', [])
+
+    def conversation(self, session_id: str, *, limit: int = 50) -> list[dict[str, Any]]:
+        """GET /api/v1/conversations/: the messages of one website chat."""
+        params = {'session_id': session_id, 'limit': limit}
+        return self._request('GET', '/api/v1/conversations/', params=params).get('messages', [])

strands_asyntai-0.1.0/src/strands_asyntai/plugin.py

@@ -0,0 +1,163 @@
+"""The Asyntai plugin for Strands Agents."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import httpx
+from strands import tool
+from strands.plugins import Plugin
+from strands.tools.decorator import DecoratedFunctionTool
+
+from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, AsyntaiClient
+
+LEAD_TOOLS = frozenset({'asyntai_get_leads', 'asyntai_get_conversation'})
+KNOWLEDGE_TOOLS = frozenset({'asyntai_add_text', 'asyntai_add_url'})
+
+
+class AsyntaiPlugin(Plugin):
+    """Gives an agent the knowledge, chats and leads of an Asyntai website agent.
+
+    Asyntai reads a website, its product feed and its documents, and keeps that
+    knowledge current. This plugin hands it to a Strands agent as tools, so the
+    agent answers questions about a real business without a local index.
+
+    Example:
+        ```python
+        from strands import Agent
+        from strands_asyntai import AsyntaiPlugin
+
+        agent = Agent(plugins=[AsyntaiPlugin()])
+        agent('Do they ship to Spain, and how long does it take?')
+        ```
+
+    Args:
+        api_key: Asyntai API key. Defaults to the ``ASYNTAI_API_KEY`` environment variable.
+        website_id: Which website agent to use, when the account has several.
+            ``asyntai_list_websites`` returns the ids.
+        knowledge_tools: Also register ``asyntai_add_text`` and ``asyntai_add_url``,
+            which write to the knowledge base. Off by default.
+        lead_tools: Register ``asyntai_get_leads`` and ``asyntai_get_conversation``,
+            which read visitor contact details and chats. On by default.
+        session_id: The website conversation to continue, for example one per customer.
+            By default each plugin instance starts its own conversation.
+        base_url: API address. Change it only for a self-hosted test server.
+        timeout: Seconds to wait for one API call.
+    """
+
+    name = 'asyntai'
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        website_id: int | None = None,
+        knowledge_tools: bool = False,
+        lead_tools: bool = True,
+        session_id: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.client = AsyntaiClient(api_key, base_url=base_url, timeout=timeout, transport=transport)
+        self.website_id = website_id
+        # Without a session id the Asyntai API puts every call of the account into
+        # one shared conversation, so each plugin instance gets its own.
+        self.session_id = session_id or f'strands-{uuid.uuid4().hex}'
+        super().__init__()
+        hidden: set[str] = set()
+        if not lead_tools:
+            hidden |= LEAD_TOOLS
+        if not knowledge_tools:
+            hidden |= KNOWLEDGE_TOOLS
+        self._tools = [t for t in self._tools if t.tool_name not in hidden]
+
+    @tool
+    def asyntai_ask_website(self, question: str) -> str:
+        """Ask the business's Asyntai website agent a question and get its answer.
+
+        Use it instead of guessing for anything about the business: products, prices,
+        stock, delivery, returns, opening hours, policies and documentation. Asyntai
+        answers from the business's own website, product catalog and documents. Ask
+        follow-up questions freely: the website agent keeps the context of the conversation.
+
+        Args:
+            question: The question, in any language.
+        """
+        payload = self.client.chat(question, session_id=self.session_id, website_id=self.website_id)
+        return str(payload.get('response', ''))
+
+    @tool
+    def asyntai_list_websites(self) -> list[dict[str, Any]] | str:
+        """List the website agents on this Asyntai account, with their ids and domains."""
+        return self.client.websites() or 'This Asyntai account has no website agents yet.'
+
+    @tool
+    def asyntai_list_knowledge(self, limit: int = 50) -> list[dict[str, Any]] | str:
+        """List the pages, texts and files the website agent knows.
+
+        Args:
+            limit: How many entries to return, 1 to 200.
+        """
+        entries = self.client.knowledge(limit=_clamp(limit, 1, 200), website_id=self.website_id)
+        return entries or 'The knowledge base of this website agent is empty.'
+
+    @tool
+    def asyntai_get_leads(self, limit: int = 20, since: str | None = None) -> list[dict[str, Any]] | str:
+        """Read the website visitors who left an email address or a phone number.
+
+        Args:
+            limit: How many leads to return, newest first, 1 to 100.
+            since: Only leads after this ISO date, for example 2026-10-01.
+        """
+        leads = self.client.leads(limit=_clamp(limit, 1, 100), website_id=self.website_id, since=since)
+        if leads:
+            return leads
+        period = f' since {since}' if since else ''
+        return f'No website visitor left an email address or a phone number{period}. The call worked.'
+
+    @tool
+    def asyntai_get_conversation(self, session_id: str, limit: int = 50) -> list[dict[str, Any]] | str:
+        """Read the messages of one website chat.
+
+        Args:
+            session_id: The chat's session id, as returned with a lead.
+            limit: How many messages to return, 1 to 200.
+        """
+        messages = self.client.conversation(session_id, limit=_clamp(limit, 1, 200))
+        return messages or f'The chat {session_id} has no messages.'
+
+    @tool
+    def asyntai_add_text(self, title: str, content: str) -> str:
+        """Store a text in the knowledge base, so the website agent uses it in later answers.
+
+        Args:
+            title: A short title for the text.
+            content: The text itself.
+        """
+        self.client.add_text(title, content, website_id=self.website_id)
+        return f'Stored "{title}" in the knowledge base.'
+
+    @tool
+    def asyntai_add_url(self, url: str) -> str:
+        """Read a web page into the knowledge base.
+
+        Args:
+            url: The full address of the page, starting with https://.
+        """
+        self.client.add_url(url, website_id=self.website_id)
+        return f'Asyntai is reading {url} into the knowledge base.'
+
+
+def asyntai_tools(api_key: str | None = None, **kwargs: Any) -> list[DecoratedFunctionTool]:
+    """Return the Asyntai tools as a plain list, for ``Agent(tools=...)``.
+
+    Takes the same arguments as :class:`AsyntaiPlugin`. Use it to mix the tools
+    with your own, or to give them to an agent that does not use plugins.
+    """
+    return AsyntaiPlugin(api_key, **kwargs).tools
+
+
+def _clamp(value: int, low: int, high: int) -> int:
+    return max(low, min(high, int(value)))

strands_asyntai-0.1.0/tests/conftest.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+import pytest
+
+
+@dataclass
+class FakeAsyntai:
+    """A fake Asyntai API that records every request."""
+
+    requests: list[httpx.Request] = field(default_factory=list)
+    status: dict[str, int] = field(default_factory=dict)
+    empty: bool = False
+
+    def handler(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        path = request.url.path
+        if path in self.status:
+            code = self.status[path]
+            return httpx.Response(code, json={'success': False, 'error': f'fake error {code}'})
+        if request.headers.get('authorization') != 'Bearer test-key':
+            return httpx.Response(401, json={'success': False, 'error': 'Invalid API key'})
+        if path == '/api/v1/chat/':
+            payload = json.loads(request.content)
+            return httpx.Response(
+                200,
+                json={'success': True, 'response': f'Answer to: {payload["message"]}', 'session_id': 'x'},
+            )
+        if path == '/api/v1/websites/':
+            return httpx.Response(200, json={'success': True, 'websites': [] if self.empty else [{'id': 7}]})
+        if path == '/api/v1/knowledge/':
+            return httpx.Response(200, json={'success': True, 'entries': [] if self.empty else [{'id': 'k1'}]})
+        if path in ('/api/v1/knowledge/text/', '/api/v1/knowledge/url/'):
+            return httpx.Response(201, json={'success': True, 'id': 'k2'})
+        if path == '/api/v1/leads/':
+            leads = [] if self.empty else [{'session_id': 's1', 'email': 'ana@example.test'}]
+            return httpx.Response(200, json={'success': True, 'leads': leads})
+        if path == '/api/v1/conversations/':
+            messages = [] if self.empty else [{'role': 'user', 'content': 'Do you ship to Spain?'}]
+            return httpx.Response(200, json={'success': True, 'messages': messages})
+        return httpx.Response(404, json={'success': False, 'error': 'Not found'})
+
+    @property
+    def transport(self) -> httpx.MockTransport:
+        return httpx.MockTransport(self.handler)
+
+    def last(self, path: str) -> httpx.Request:
+        return [r for r in self.requests if r.url.path == path][-1]
+
+
+@pytest.fixture
+def fake() -> FakeAsyntai:
+    return FakeAsyntai()
+
+
+@pytest.fixture(autouse=True)
+def _no_env_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv('ASYNTAI_API_KEY', raising=False)
+
+
+def body(request: httpx.Request) -> dict[str, Any]:
+    return json.loads(request.content)

strands_asyntai-0.1.0/tests/test_client.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+from conftest import FakeAsyntai, body
+
+from strands_asyntai import AsyntaiClient, AsyntaiError, AsyntaiRequestError
+
+
+def client(fake: FakeAsyntai, key: str = 'test-key') -> AsyntaiClient:
+    return AsyntaiClient(key, base_url='https://api.test', transport=fake.transport)
+
+
+def test_key_is_required() -> None:
+    with pytest.raises(AsyntaiError, match='API key is required'):
+        AsyntaiClient()
+
+
+def test_key_comes_from_the_environment(monkeypatch: pytest.MonkeyPatch, fake: FakeAsyntai) -> None:
+    monkeypatch.setenv('ASYNTAI_API_KEY', 'test-key')
+    assert AsyntaiClient(base_url='https://api.test', transport=fake.transport).websites() == [{'id': 7}]
+
+
+def test_sends_bearer_key_and_user_agent(fake: FakeAsyntai) -> None:
+    client(fake).websites()
+    request = fake.requests[-1]
+    assert request.headers['authorization'] == 'Bearer test-key'
+    assert request.headers['user-agent'] == 'strands-asyntai'
+
+
+def test_chat_body_has_only_what_was_given(fake: FakeAsyntai) -> None:
+    client(fake).chat('Hi')
+    assert body(fake.last('/api/v1/chat/')) == {'message': 'Hi'}
+    client(fake).chat('Hi', session_id='s', website_id=3)
+    assert body(fake.last('/api/v1/chat/')) == {'message': 'Hi', 'session_id': 's', 'website_id': 3}
+
+
+def test_leads_params(fake: FakeAsyntai) -> None:
+    client(fake).leads(limit=5, website_id=3, since='2026-10-01')
+    params = fake.last('/api/v1/leads/').url.params
+    assert (params['limit'], params['website_id'], params['since']) == ('5', '3', '2026-10-01')
+
+
+@pytest.mark.parametrize(
+    ('code', 'expected', 'kind'),
+    [
+        (401, 'rejected the API key', AsyntaiError),
+        (403, 'Starter plan', AsyntaiError),
+        (429, 'message limit', AsyntaiError),
+        (400, 'fake error 400', AsyntaiRequestError),
+        (404, 'fake error 404', AsyntaiRequestError),
+        (500, 'fake error 500', AsyntaiError),
+    ],
+)
+def test_error_codes(fake: FakeAsyntai, code: int, expected: str, kind: type[Exception]) -> None:
+    fake.status['/api/v1/websites/'] = code
+    with pytest.raises(kind, match=expected):
+        client(fake).websites()
+
+
+def test_network_error() -> None:
+    def fail(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError('boom')
+
+    with pytest.raises(AsyntaiError, match='Could not reach'):
+        AsyntaiClient('k', base_url='https://api.test', transport=httpx.MockTransport(fail)).websites()
+
+
+def test_html_response() -> None:
+    transport = httpx.MockTransport(lambda r: httpx.Response(502, text='<html>'))
+    with pytest.raises(AsyntaiError, match='non-JSON'):
+        AsyntaiClient('k', base_url='https://api.test', transport=transport).websites()
+
+
+def test_base_url_trailing_slash(fake: FakeAsyntai) -> None:
+    AsyntaiClient('test-key', base_url='https://api.test/', transport=fake.transport).websites()
+    assert str(fake.requests[-1].url) == 'https://api.test/api/v1/websites/'

strands_asyntai-0.1.0/tests/test_live.py

@@ -0,0 +1,61 @@
+"""Runs against a real Asyntai server. Skipped unless both variables are set.
+
+    ASYNTAI_LIVE_KEY=...  ASYNTAI_LIVE_URL=https://asyntai.com  pytest tests/test_live.py
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import pytest
+from strands import Agent
+from strands.models import Model
+
+from strands_asyntai import AsyntaiClient, AsyntaiError, AsyntaiPlugin
+
+KEY = os.environ.get('ASYNTAI_LIVE_KEY')
+URL = os.environ.get('ASYNTAI_LIVE_URL')
+WEBSITE = os.environ.get('ASYNTAI_LIVE_WEBSITE_ID')
+
+pytestmark = pytest.mark.skipif(not (KEY and URL), reason='set ASYNTAI_LIVE_KEY and ASYNTAI_LIVE_URL')
+
+
+class NoModel(Model):
+    """The tools are called directly, so the model is never used."""
+
+    def update_config(self, **model_config: Any) -> None: ...
+
+    def get_config(self) -> Any:
+        return {}
+
+    def structured_output(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def stream(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+
+def agent() -> Agent:
+    plugin = AsyntaiPlugin(KEY, base_url=URL or '', website_id=int(WEBSITE) if WEBSITE else None, timeout=120)
+    return Agent(model=NoModel(), plugins=[plugin], callback_handler=None)
+
+
+def test_wrong_key_is_rejected() -> None:
+    with pytest.raises(AsyntaiError, match='rejected the API key'):
+        AsyntaiClient('wrong-key', base_url=URL or '').websites()
+
+
+@pytest.mark.parametrize('name', ['asyntai_list_websites', 'asyntai_list_knowledge', 'asyntai_get_leads'])
+def test_read_tools(name: str) -> None:
+    live_agent = agent()
+    result = getattr(live_agent.tool, name)()
+    assert result['status'] == 'success'
+    assert result['content'][0]['text']
+
+
+def test_ask_website_answers() -> None:
+    live_agent = agent()
+    result = live_agent.tool.asyntai_ask_website(question='What do you sell?')
+    assert result['status'] == 'success'
+    assert result['content'][0]['text'].strip()

strands_asyntai-0.1.0/tests/test_plugin.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from conftest import FakeAsyntai, body
+from strands import Agent
+from strands.models import Model
+
+from strands_asyntai import AsyntaiPlugin, asyntai_tools
+
+READ = {'asyntai_ask_website', 'asyntai_list_websites', 'asyntai_list_knowledge'}
+LEADS = {'asyntai_get_leads', 'asyntai_get_conversation'}
+WRITE = {'asyntai_add_text', 'asyntai_add_url'}
+
+
+class ScriptedModel(Model):
+    """Calls the given tools one by one, then finishes. Records what it was offered."""
+
+    def __init__(self, calls: list[tuple[str, dict[str, Any]]]) -> None:
+        self.calls = list(calls)
+        self.offered: list[str] = []
+        self.results: list[dict[str, Any]] = []
+
+    def update_config(self, **model_config: Any) -> None: ...
+
+    def get_config(self) -> Any:
+        return {}
+
+    async def structured_output(self, *args: Any, **kwargs: Any) -> AsyncGenerator[Any, None]:
+        raise NotImplementedError
+        yield
+
+    async def stream(self, messages: Any, tool_specs: Any = None, *args: Any, **kwargs: Any) -> AsyncGenerator[Any, None]:
+        self.offered = [spec['name'] for spec in tool_specs or []]
+        self.results = [
+            block['toolResult'] for message in messages for block in message['content'] if 'toolResult' in block
+        ]
+        yield {'messageStart': {'role': 'assistant'}}
+        if self.calls:
+            name, arguments = self.calls.pop(0)
+            yield {'contentBlockStart': {'start': {'toolUse': {'toolUseId': f'id-{len(self.calls)}', 'name': name}}}}
+            yield {'contentBlockDelta': {'delta': {'toolUse': {'input': json.dumps(arguments)}}}}
+            yield {'contentBlockStop': {}}
+            yield {'messageStop': {'stopReason': 'tool_use'}}
+        else:
+            yield {'contentBlockDelta': {'delta': {'text': 'Done.'}}}
+            yield {'contentBlockStop': {}}
+            yield {'messageStop': {'stopReason': 'end_turn'}}
+
+
+def plugin(fake: FakeAsyntai, **kwargs: Any) -> AsyntaiPlugin:
+    return AsyntaiPlugin('test-key', base_url='https://api.test', transport=fake.transport, **kwargs)
+
+
+def names(tools: list[Any]) -> set[str]:
+    return {t.tool_name for t in tools}
+
+
+def agent_with(p: AsyntaiPlugin, calls: list[tuple[str, dict[str, Any]]] | None = None) -> tuple[Agent, ScriptedModel]:
+    model = ScriptedModel(calls or [])
+    return Agent(model=model, plugins=[p], callback_handler=None), model
+
+
+def text_of(result: dict[str, Any]) -> str:
+    return result['content'][0]['text']
+
+
+def test_default_tools(fake: FakeAsyntai) -> None:
+    assert names(plugin(fake).tools) == READ | LEADS
+
+
+def test_knowledge_tools_are_opt_in(fake: FakeAsyntai) -> None:
+    assert names(plugin(fake, knowledge_tools=True).tools) == READ | LEADS | WRITE
+
+
+def test_lead_tools_can_be_hidden(fake: FakeAsyntai) -> None:
+    assert names(plugin(fake, lead_tools=False).tools) == READ
+
+
+def test_model_is_offered_only_the_enabled_tools(fake: FakeAsyntai) -> None:
+    agent, model = agent_with(plugin(fake, lead_tools=False))
+    agent('Hello')
+    assert set(model.offered) == READ
+
+
+def test_plugin_works_in_a_real_agent_loop(fake: FakeAsyntai) -> None:
+    agent, model = agent_with(plugin(fake), [('asyntai_ask_website', {'question': 'Do you ship to Spain?'})])
+    assert 'Done.' in str(agent('Ask the site.'))
+    assert model.results[0]['status'] == 'success'
+    assert text_of(model.results[0]) == 'Answer to: Do you ship to Spain?'
+
+
+def test_questions_of_one_plugin_share_a_conversation(fake: FakeAsyntai) -> None:
+    p = plugin(fake)
+    agent, _ = agent_with(p, [('asyntai_ask_website', {'question': 'A'}), ('asyntai_ask_website', {'question': 'B'})])
+    agent('Ask twice.')
+    sessions = [body(r)['session_id'] for r in fake.requests if r.url.path == '/api/v1/chat/']
+    assert len(sessions) == 2
+    assert sessions[0] == sessions[1] == p.session_id
+    assert p.session_id.startswith('strands-')
+
+
+def test_two_plugins_have_separate_conversations(fake: FakeAsyntai) -> None:
+    assert plugin(fake).session_id != plugin(fake).session_id
+
+
+def test_fixed_session_id_is_used(fake: FakeAsyntai) -> None:
+    agent, _ = agent_with(plugin(fake, session_id='customer-42'), [('asyntai_ask_website', {'question': 'A'})])
+    agent('Ask.')
+    assert body(fake.last('/api/v1/chat/'))['session_id'] == 'customer-42'
+
+
+def test_website_id_is_sent_by_every_scoped_tool(fake: FakeAsyntai) -> None:
+    calls = [
+        ('asyntai_ask_website', {'question': 'A'}),
+        ('asyntai_list_knowledge', {}),
+        ('asyntai_get_leads', {}),
+        ('asyntai_add_text', {'title': 'T', 'content': 'C'}),
+        ('asyntai_add_url', {'url': 'https://shop.test/a'}),
+    ]
+    agent, _ = agent_with(plugin(fake, website_id=9, knowledge_tools=True), calls)
+    agent('Use all.')
+    assert body(fake.last('/api/v1/chat/'))['website_id'] == 9
+    assert fake.last('/api/v1/knowledge/').url.params['website_id'] == '9'
+    assert fake.last('/api/v1/leads/').url.params['website_id'] == '9'
+    assert body(fake.last('/api/v1/knowledge/text/'))['website_id'] == 9
+    assert body(fake.last('/api/v1/knowledge/url/'))['website_id'] == 9
+
+
+def test_lists_reach_the_model_as_json(fake: FakeAsyntai) -> None:
+    agent, model = agent_with(plugin(fake), [('asyntai_get_leads', {})])
+    agent('Leads.')
+    assert json.loads(text_of(model.results[0])) == [{'session_id': 's1', 'email': 'ana@example.test'}]
+
+
+def test_conversation_tool(fake: FakeAsyntai) -> None:
+    agent, model = agent_with(plugin(fake), [('asyntai_get_conversation', {'session_id': 's1', 'limit': 5})])
+    agent('Read it.')
+    params = fake.last('/api/v1/conversations/').url.params
+    assert (params['session_id'], params['limit']) == ('s1', '5')
+    assert 'Spain' in text_of(model.results[0])
+
+
+def test_empty_results_say_the_call_worked(fake: FakeAsyntai) -> None:
+    fake.empty = True
+    agent, model = agent_with(
+        plugin(fake),
+        [
+            ('asyntai_get_leads', {'since': '2026-10-01'}),
+            ('asyntai_list_websites', {}),
+            ('asyntai_list_knowledge', {}),
+            ('asyntai_get_conversation', {'session_id': 's1'}),
+        ],
+    )
+    agent('Check.')
+    assert all(r['status'] == 'success' for r in model.results)
+    texts = {text_of(r) for r in model.results}
+    assert any('since 2026-10-01. The call worked.' in t for t in texts)
+    assert any('no website agents' in t for t in texts)
+    assert any('knowledge base of this website agent is empty' in t for t in texts)
+    assert any('has no messages' in t for t in texts)
+
+
+def test_limits_are_clamped(fake: FakeAsyntai) -> None:
+    agent, _ = agent_with(
+        plugin(fake),
+        [('asyntai_get_leads', {'limit': 5000}), ('asyntai_list_knowledge', {'limit': 0})],
+    )
+    agent('Check.')
+    assert fake.last('/api/v1/leads/').url.params['limit'] == '100'
+    assert fake.last('/api/v1/knowledge/').url.params['limit'] == '1'
+
+
+def test_wrong_key_reaches_the_model_as_a_tool_error(fake: FakeAsyntai) -> None:
+    p = AsyntaiPlugin('wrong-key', base_url='https://api.test', transport=fake.transport)
+    agent, model = agent_with(p, [('asyntai_list_websites', {})])
+    assert 'Done.' in str(agent('List.'))
+    assert model.results[0]['status'] == 'error'
+    assert 'rejected the API key' in text_of(model.results[0])
+
+
+def test_bad_arguments_reach_the_model_as_a_tool_error(fake: FakeAsyntai) -> None:
+    fake.status['/api/v1/chat/'] = 400
+    agent, model = agent_with(plugin(fake), [('asyntai_ask_website', {'question': 'A'})])
+    agent('Ask.')
+    assert model.results[0]['status'] == 'error'
+    assert 'fake error 400' in text_of(model.results[0])
+
+
+def test_write_tools_answer_with_a_sentence(fake: FakeAsyntai) -> None:
+    agent, model = agent_with(
+        plugin(fake, knowledge_tools=True),
+        [
+            ('asyntai_add_text', {'title': 'Hours', 'content': '9-5'}),
+            ('asyntai_add_url', {'url': 'https://shop.test/a'}),
+        ],
+    )
+    agent('Store.')
+    assert [text_of(r) for r in model.results] == [
+        'Stored "Hours" in the knowledge base.',
+        'Asyntai is reading https://shop.test/a into the knowledge base.',
+    ]
+    assert body(fake.last('/api/v1/knowledge/text/'))['title'] == 'Hours'
+
+
+def test_asyntai_tools_returns_a_plain_list_for_agents(fake: FakeAsyntai) -> None:
+    tools = asyntai_tools('test-key', base_url='https://api.test', transport=fake.transport, lead_tools=False)
+    assert names(tools) == READ
+    model = ScriptedModel([('asyntai_ask_website', {'question': 'Hi'})])
+    agent = Agent(model=model, tools=tools, callback_handler=None)
+    agent('Ask.')
+    assert text_of(model.results[0]) == 'Answer to: Hi'
+
+
+def test_tool_can_be_called_directly_on_the_agent(fake: FakeAsyntai) -> None:
+    agent, _ = agent_with(plugin(fake))
+    result = agent.tool.asyntai_ask_website(question='Hi')
+    assert result['status'] == 'success'
+    assert text_of(result) == 'Answer to: Hi'
+
+
+def test_tool_specs_describe_the_arguments(fake: FakeAsyntai) -> None:
+    specs = {t.tool_name: t.tool_spec for t in plugin(fake, knowledge_tools=True).tools}
+    ask = specs['asyntai_ask_website']['inputSchema']['json']
+    assert list(ask['properties']) == ['question']
+    assert ask['required'] == ['question']
+    assert 'any language' in ask['properties']['question']['description']
+    leads = specs['asyntai_get_leads']['inputSchema']['json']
+    assert not leads.get('required')