crewai-cloro 0.1.0__tar.gz

crewai_cloro-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

crewai_cloro-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cloro
+
+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.

crewai_cloro-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: crewai-cloro
+Version: 0.1.0
+Summary: CrewAI tools for cloro: live Google search results with the AI Overview, and Google AI Mode, Bing AI Mode, ChatGPT and Gemini answers with sources.
+Project-URL: Homepage, https://cloro.dev/?utm_source=crewai-cloro&utm_medium=byok
+Project-URL: Documentation, https://github.com/cloro-dev/crewai-cloro#readme
+Project-URL: Issues, https://github.com/cloro-dev/crewai-cloro/issues
+Project-URL: Source, https://github.com/cloro-dev/crewai-cloro
+Author-email: cloro <support@cloro.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: AI Mode,AI Overview,Bing,ChatGPT,CrewAI,Gemini,Google,Web Search,agents,cloro
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.10
+Requires-Dist: crewai>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# crewai-cloro
+
+[CrewAI](https://www.crewai.com) tools for [cloro](https://cloro.dev/?utm_source=crewai-cloro&utm_medium=byok). cloro
+loads the live page of a search engine or an AI assistant for a query and a country, and returns the result as
+structured data.
+
+| Tool | cloro endpoint | The agent gets | Credits per call |
+|---|---|---|--:|
+| `CloroGoogleSearchTool` | `POST /v1/monitor/google` | Google organic results: title, URL and snippet. With `include_ai_overview=True`, the Google AI Overview and its sources first. | 5, or 7 with the AI Overview |
+| `CloroAIAnswerTool(engine="google_ai_mode")` | `POST /v1/monitor/aimode` | The Google AI Mode answer as Markdown, with its sources | 6 |
+| `CloroAIAnswerTool(engine="bing_ai_mode")` | `POST /v1/monitor/bing/aimode` | The Bing AI Mode (Copilot Search in Bing) answer, with its sources | 6 |
+| `CloroAIAnswerTool(engine="chatgpt")` | `POST /v1/monitor/chatgpt` | The ChatGPT answer that users see, with its sources | 7 |
+| `CloroAIAnswerTool(engine="gemini")` | `POST /v1/monitor/gemini` | The Gemini answer, with its sources | 6 |
+
+## Installation
+
+```bash
+pip install crewai-cloro
+```
+
+Get an API key at [dashboard.cloro.dev](https://dashboard.cloro.dev/api-keys?utm_source=crewai-cloro&utm_medium=byok).
+The free plan includes 500 credits each month. Set the key as `CLORO_API_KEY`, or pass `api_key=...` to a tool.
+
+## Usage
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_cloro import CloroAIAnswerTool, CloroGoogleSearchTool
+
+researcher = Agent(
+    role="Search analyst",
+    goal="Compare what Google and AI assistants say about a topic.",
+    backstory="You check live sources and cite the URLs you use.",
+    tools=[
+        CloroGoogleSearchTool(max_results=5, include_ai_overview=True),
+        CloroAIAnswerTool(engine="chatgpt"),
+        CloroAIAnswerTool(engine="google_ai_mode"),
+    ],
+)
+
+task = Task(
+    description="Which SERP APIs do Google, ChatGPT and Google AI Mode recommend for AI agents?",
+    expected_output="A short comparison with the cited URLs.",
+    agent=researcher,
+)
+
+print(Crew(agents=[researcher], tasks=[task]).kickoff())
+```
+
+Each `CloroAIAnswerTool` gets its own tool name, `cloro_<engine>`, so one agent can hold several engines. Pass
+`name=` to change it.
+
+A direct call returns the same text the agent gets:
+
+```python
+print(CloroGoogleSearchTool().run(query="retrieval-augmented generation", country="GB"))
+```
+
+### Parameters
+
+Both tools take:
+
+- `api_key`: the cloro API key. Defaults to the `CLORO_API_KEY` environment variable.
+- `country`: ISO 3166-1 alpha-2 country code for the search location (default `US`). The agent can also pass
+  `country` per call.
+- `timeout`: request timeout in seconds (default 180). An AI answer can take 15 to 60 seconds.
+
+`CloroGoogleSearchTool` also takes `max_results` (default 10) and `include_ai_overview` (default `False`).
+Results with an empty link or a Google redirect link are skipped.
+
+`CloroAIAnswerTool` also takes `engine`: `google_ai_mode` (default), `bing_ai_mode`, `chatgpt` or `gemini`.
+
+## Limits
+
+- Bing AI Mode accepts a prompt of up to 3,500 characters after URL encoding. Non-Latin scripts allow fewer
+  characters. The tool refuses a longer prompt before it sends the request.
+- Your plan sets how many requests can run at the same time. A request sent while all slots are busy gets a `429`
+  (`CONCURRENCY_LIMIT_EXCEEDED`).
+- An API error raises `CloroError` with the HTTP status, the cloro error code and the message.
+
+## Development
+
+```bash
+uv run --python 3.12 --with crewai --with httpx --with pytest -- env PYTHONPATH=src python -m pytest tests
+```
+
+The tests mock the network. The API reference is at
+[cloro.dev/docs](https://cloro.dev/docs?utm_source=crewai-cloro&utm_medium=byok).
+
+## License
+
+MIT

crewai_cloro-0.1.0/README.md

@@ -0,0 +1,92 @@
+# crewai-cloro
+
+[CrewAI](https://www.crewai.com) tools for [cloro](https://cloro.dev/?utm_source=crewai-cloro&utm_medium=byok). cloro
+loads the live page of a search engine or an AI assistant for a query and a country, and returns the result as
+structured data.
+
+| Tool | cloro endpoint | The agent gets | Credits per call |
+|---|---|---|--:|
+| `CloroGoogleSearchTool` | `POST /v1/monitor/google` | Google organic results: title, URL and snippet. With `include_ai_overview=True`, the Google AI Overview and its sources first. | 5, or 7 with the AI Overview |
+| `CloroAIAnswerTool(engine="google_ai_mode")` | `POST /v1/monitor/aimode` | The Google AI Mode answer as Markdown, with its sources | 6 |
+| `CloroAIAnswerTool(engine="bing_ai_mode")` | `POST /v1/monitor/bing/aimode` | The Bing AI Mode (Copilot Search in Bing) answer, with its sources | 6 |
+| `CloroAIAnswerTool(engine="chatgpt")` | `POST /v1/monitor/chatgpt` | The ChatGPT answer that users see, with its sources | 7 |
+| `CloroAIAnswerTool(engine="gemini")` | `POST /v1/monitor/gemini` | The Gemini answer, with its sources | 6 |
+
+## Installation
+
+```bash
+pip install crewai-cloro
+```
+
+Get an API key at [dashboard.cloro.dev](https://dashboard.cloro.dev/api-keys?utm_source=crewai-cloro&utm_medium=byok).
+The free plan includes 500 credits each month. Set the key as `CLORO_API_KEY`, or pass `api_key=...` to a tool.
+
+## Usage
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_cloro import CloroAIAnswerTool, CloroGoogleSearchTool
+
+researcher = Agent(
+    role="Search analyst",
+    goal="Compare what Google and AI assistants say about a topic.",
+    backstory="You check live sources and cite the URLs you use.",
+    tools=[
+        CloroGoogleSearchTool(max_results=5, include_ai_overview=True),
+        CloroAIAnswerTool(engine="chatgpt"),
+        CloroAIAnswerTool(engine="google_ai_mode"),
+    ],
+)
+
+task = Task(
+    description="Which SERP APIs do Google, ChatGPT and Google AI Mode recommend for AI agents?",
+    expected_output="A short comparison with the cited URLs.",
+    agent=researcher,
+)
+
+print(Crew(agents=[researcher], tasks=[task]).kickoff())
+```
+
+Each `CloroAIAnswerTool` gets its own tool name, `cloro_<engine>`, so one agent can hold several engines. Pass
+`name=` to change it.
+
+A direct call returns the same text the agent gets:
+
+```python
+print(CloroGoogleSearchTool().run(query="retrieval-augmented generation", country="GB"))
+```
+
+### Parameters
+
+Both tools take:
+
+- `api_key`: the cloro API key. Defaults to the `CLORO_API_KEY` environment variable.
+- `country`: ISO 3166-1 alpha-2 country code for the search location (default `US`). The agent can also pass
+  `country` per call.
+- `timeout`: request timeout in seconds (default 180). An AI answer can take 15 to 60 seconds.
+
+`CloroGoogleSearchTool` also takes `max_results` (default 10) and `include_ai_overview` (default `False`).
+Results with an empty link or a Google redirect link are skipped.
+
+`CloroAIAnswerTool` also takes `engine`: `google_ai_mode` (default), `bing_ai_mode`, `chatgpt` or `gemini`.
+
+## Limits
+
+- Bing AI Mode accepts a prompt of up to 3,500 characters after URL encoding. Non-Latin scripts allow fewer
+  characters. The tool refuses a longer prompt before it sends the request.
+- Your plan sets how many requests can run at the same time. A request sent while all slots are busy gets a `429`
+  (`CONCURRENCY_LIMIT_EXCEEDED`).
+- An API error raises `CloroError` with the HTTP status, the cloro error code and the message.
+
+## Development
+
+```bash
+uv run --python 3.12 --with crewai --with httpx --with pytest -- env PYTHONPATH=src python -m pytest tests
+```
+
+The tests mock the network. The API reference is at
+[cloro.dev/docs](https://cloro.dev/docs?utm_source=crewai-cloro&utm_medium=byok).
+
+## License
+
+MIT

crewai_cloro-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crewai-cloro"
+version = "0.1.0"
+description = "CrewAI tools for cloro: live Google search results with the AI Overview, and Google AI Mode, Bing AI Mode, ChatGPT and Gemini answers with sources."
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["CrewAI", "cloro", "Web Search", "Google", "AI Overview", "AI Mode", "Bing", "ChatGPT", "Gemini", "agents"]
+authors = [{ name = "cloro", email = "support@cloro.dev" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+]
+dependencies = ["crewai>=1.0.0", "httpx>=0.27.0"]
+
+[project.urls]
+Homepage = "https://cloro.dev/?utm_source=crewai-cloro&utm_medium=byok"
+Documentation = "https://github.com/cloro-dev/crewai-cloro#readme"
+Issues = "https://github.com/cloro-dev/crewai-cloro/issues"
+Source = "https://github.com/cloro-dev/crewai-cloro"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.11"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "LICENSE", "README.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crewai_cloro"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"

crewai_cloro-0.1.0/src/crewai_cloro/__init__.py

@@ -0,0 +1,3 @@
+from crewai_cloro.tools import CloroAIAnswerTool, CloroError, CloroGoogleSearchTool
+
+__all__ = ["CloroAIAnswerTool", "CloroError", "CloroGoogleSearchTool"]

crewai_cloro-0.1.0/src/crewai_cloro/tools.py

@@ -0,0 +1,196 @@
+"""CrewAI tools for cloro: live Google results and AI search engine answers."""
+
+import os
+from typing import Any, Literal
+from urllib.parse import quote
+
+import httpx
+from crewai.tools import BaseTool, EnvVar
+from pydantic import BaseModel, Field, PrivateAttr
+
+CLORO_API_BASE = "https://api.cloro.dev"
+USER_AGENT = "crewai-cloro"
+API_KEY_ENV = EnvVar(
+    name="CLORO_API_KEY", description="API key for cloro (https://dashboard.cloro.dev).", required=True
+)
+
+# Bing AI Mode refuses a prompt longer than this after URL encoding.
+BING_PROMPT_LIMIT = 3500
+
+Engine = Literal["google_ai_mode", "bing_ai_mode", "chatgpt", "gemini"]
+
+_ENGINES: dict[str, tuple[str, str]] = {
+    "google_ai_mode": ("/v1/monitor/aimode", "Google AI Mode"),
+    "bing_ai_mode": ("/v1/monitor/bing/aimode", "Bing AI Mode (Copilot Search in Bing)"),
+    "chatgpt": ("/v1/monitor/chatgpt", "ChatGPT"),
+    "gemini": ("/v1/monitor/gemini", "Gemini"),
+}
+
+
+class CloroError(RuntimeError):
+    """The cloro API returned an error or a response that cannot be read."""
+
+
+def _is_direct_link(url: Any) -> bool:
+    """Return True for an http(s) link that is not a Google redirect or search page."""
+    return (
+        isinstance(url, str)
+        and url.startswith(("http://", "https://"))
+        and "google.com/goto" not in url
+        and "google.com/search" not in url
+    )
+
+
+def _encoded_length(prompt: str) -> int:
+    return len(quote(prompt.strip(), safe="-_.!~*'()").replace("%20", "+"))
+
+
+def _sources(items: Any) -> list[tuple[str, str]]:
+    sources: list[tuple[str, str]] = []
+    for item in items or []:
+        url = item.get("url") if isinstance(item, dict) else None
+        if _is_direct_link(url) and url not in [u for _, u in sources]:
+            sources.append((item.get("label") or "", url))
+    return sources
+
+
+def _format_sources(sources: list[tuple[str, str]]) -> str:
+    return "\n".join(f"- {title}: {url}" if title else f"- {url}" for title, url in sources)
+
+
+class _CloroTool(BaseTool):
+    api_key: str | None = Field(default=None, description="cloro API key. Defaults to CLORO_API_KEY.")
+    country: str = Field(default="US", description="ISO 3166-1 alpha-2 country code for the search location.")
+    timeout: float = Field(default=180.0, description="Request timeout in seconds.")
+    env_vars: list[EnvVar] = [API_KEY_ENV]
+    _key: str = PrivateAttr(default="")
+
+    def model_post_init(self, context: Any) -> None:
+        super().model_post_init(context)
+        key = self.api_key or os.environ.get("CLORO_API_KEY")
+        if not key:
+            raise ValueError("Set CLORO_API_KEY or pass api_key. Get a key at https://dashboard.cloro.dev")
+        self._key = key
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = httpx.post(
+                f"{CLORO_API_BASE}{path}",
+                json=payload,
+                headers={
+                    "Authorization": f"Bearer {self._key}",
+                    "Content-Type": "application/json",
+                    "User-Agent": USER_AGENT,
+                },
+                timeout=self.timeout,
+            )
+        except httpx.HTTPError as error:
+            raise CloroError(f"Request to cloro {path} failed: {error}") from error
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        if response.is_error or not isinstance(data, dict) or not data.get("success"):
+            error = data.get("error") if isinstance(data, dict) else None
+            code = error.get("code") if isinstance(error, dict) else None
+            message = error.get("message") if isinstance(error, dict) else None
+            raise CloroError(
+                f"cloro {path} returned HTTP {response.status_code}: {code or 'no error code'} {message or ''}".strip()
+            )
+        result = data.get("result")
+        if not isinstance(result, dict):
+            raise CloroError(f"cloro {path} returned no result.")
+        return result
+
+
+class CloroGoogleSearchInput(BaseModel):
+    """Input schema for CloroGoogleSearchTool."""
+
+    query: str = Field(..., description="The search query.")
+    country: str | None = Field(default=None, description="Optional ISO 3166-1 alpha-2 country code, for example GB.")
+
+
+class CloroGoogleSearchTool(_CloroTool):
+    """Live Google organic results, and optionally the Google AI Overview, through cloro."""
+
+    name: str = "cloro_google_search"
+    description: str = (
+        "Search Google live and return the organic results of the first results page: title, URL and snippet. "
+        "Use it for current facts, sources and what ranks on Google for a query."
+    )
+    args_schema: type[BaseModel] = CloroGoogleSearchInput
+    max_results: int = Field(default=10, description="The maximum number of organic results to return.")
+    include_ai_overview: bool = Field(
+        default=False, description="Also return the Google AI Overview and its sources. Costs 2 more credits."
+    )
+
+    def _run(self, query: str, country: str | None = None) -> str:
+        payload: dict[str, Any] = {"query": query, "country": (country or self.country).upper()}
+        if self.include_ai_overview:
+            payload["include"] = {"aioverview": True}
+        result = self._post("/v1/monitor/google", payload)
+
+        parts: list[str] = []
+        overview = result.get("aioverview")
+        if self.include_ai_overview and isinstance(overview, dict) and overview.get("text"):
+            text = f"Google AI Overview:\n{overview['text']}"
+            sources = _sources(overview.get("sources"))
+            if sources:
+                text += "\nSources:\n" + _format_sources(sources)
+            parts.append(text)
+
+        organic = [
+            item
+            for item in result.get("organicResults") or []
+            if isinstance(item, dict) and _is_direct_link(item.get("link"))
+        ][: self.max_results]
+        for index, item in enumerate(organic, start=1):
+            parts.append(f"{index}. {item.get('title') or ''}\n{item['link']}\n{item.get('snippet') or ''}".strip())
+        return "\n\n".join(parts) if parts else f"No Google results for: {query}"
+
+
+class CloroAIAnswerInput(BaseModel):
+    """Input schema for CloroAIAnswerTool."""
+
+    prompt: str = Field(..., description="The question to ask the AI search engine.")
+    country: str | None = Field(default=None, description="Optional ISO 3166-1 alpha-2 country code, for example GB.")
+
+
+class CloroAIAnswerTool(_CloroTool):
+    """The answer an AI search engine gives to a prompt, with the sources it cites, through cloro."""
+
+    name: str = ""
+    description: str = ""
+    args_schema: type[BaseModel] = CloroAIAnswerInput
+    engine: Engine = Field(
+        default="google_ai_mode",
+        description="The AI search engine: google_ai_mode, bing_ai_mode, chatgpt or gemini.",
+    )
+
+    def model_post_init(self, context: Any) -> None:
+        label = _ENGINES[self.engine][1]
+        if not self.name:
+            self.name = f"cloro_{self.engine}"
+        if not self.description:
+            self.description = (
+                f"Ask {label} a question live and return the answer it shows users, as Markdown, "
+                "with the sources it cites. Use it to see what this AI engine says about a topic or a brand."
+            )
+        super().model_post_init(context)
+
+    def _run(self, prompt: str, country: str | None = None) -> str:
+        path, label = _ENGINES[self.engine]
+        if self.engine == "bing_ai_mode" and _encoded_length(prompt) > BING_PROMPT_LIMIT:
+            raise ValueError(
+                "The prompt is too long for Bing AI Mode: at most 3,500 characters after URL encoding. "
+                "Non-Latin scripts allow fewer characters."
+            )
+        result = self._post(
+            path, {"prompt": prompt, "country": (country or self.country).upper(), "include": {"markdown": True}}
+        )
+        answer = result.get("markdown") or result.get("text") or ""
+        text = f"{label} answer:\n{answer}" if answer else f"{label} returned no answer for: {prompt}"
+        sources = _sources(result.get("sources"))
+        if sources:
+            text += "\n\nSources:\n" + _format_sources(sources)
+        return text

crewai_cloro-0.1.0/tests/test_tools.py

@@ -0,0 +1,141 @@
+from unittest.mock import patch
+
+import httpx
+import pytest
+from crewai.tools import BaseTool
+
+from crewai_cloro import CloroAIAnswerTool, CloroError, CloroGoogleSearchTool
+
+
+def _response(status: int, body: dict) -> httpx.Response:
+    return httpx.Response(status, json=body, request=httpx.Request("POST", "https://api.cloro.dev"))
+
+
+GOOGLE = {
+    "success": True,
+    "result": {
+        "organicResults": [
+            {"position": 1, "title": "First", "link": "https://example.com/a", "snippet": "A."},
+            {"position": 2, "title": "Unresolved", "link": "", "snippet": "No link."},
+            {"position": 3, "title": "Redirect", "link": "https://www.google.com/goto?x=1", "snippet": "R."},
+            {"position": 4, "title": "Second", "link": "https://example.org/b", "snippet": "B."},
+        ],
+        "aioverview": {
+            "text": "An overview.",
+            "sources": [{"label": "Src", "url": "https://example.net"}],
+        },
+    },
+}
+
+ANSWER = {
+    "success": True,
+    "result": {
+        "text": "Plain.",
+        "markdown": "**Answer.**",
+        "sources": [
+            {"position": 1, "label": "Source", "url": "https://example.com"},
+            {"position": 2, "label": "Again", "url": "https://example.com"},
+            {"position": 3, "label": "Search page", "url": "https://www.google.com/search?q=x"},
+        ],
+    },
+}
+
+
+@pytest.fixture(autouse=True)
+def api_key(monkeypatch):
+    monkeypatch.setenv("CLORO_API_KEY", "env-key")
+
+
+def test_tools_are_crewai_tools():
+    assert isinstance(CloroGoogleSearchTool(), BaseTool)
+    assert isinstance(CloroAIAnswerTool(), BaseTool)
+    assert [e.name for e in CloroGoogleSearchTool().env_vars] == ["CLORO_API_KEY"]
+
+
+def test_missing_key(monkeypatch):
+    monkeypatch.delenv("CLORO_API_KEY")
+    with pytest.raises(ValueError, match="CLORO_API_KEY"):
+        CloroGoogleSearchTool()
+
+
+def test_explicit_key_wins():
+    with patch("crewai_cloro.tools.httpx.post", return_value=_response(200, GOOGLE)) as post:
+        CloroGoogleSearchTool(api_key="k").run(query="q")
+    assert post.call_args.kwargs["headers"]["Authorization"] == "Bearer k"
+
+
+@patch("crewai_cloro.tools.httpx.post")
+def test_google_search(post):
+    post.return_value = _response(200, GOOGLE)
+    out = CloroGoogleSearchTool(max_results=5).run(query="serp api", country="de")
+
+    assert post.call_args.args[0] == "https://api.cloro.dev/v1/monitor/google"
+    assert post.call_args.kwargs["json"] == {"query": "serp api", "country": "DE"}
+    assert out == "1. First\nhttps://example.com/a\nA.\n\n2. Second\nhttps://example.org/b\nB."
+
+
+@patch("crewai_cloro.tools.httpx.post")
+def test_google_search_with_ai_overview(post):
+    post.return_value = _response(200, GOOGLE)
+    out = CloroGoogleSearchTool(include_ai_overview=True, max_results=1).run(query="q")
+
+    assert post.call_args.kwargs["json"] == {"query": "q", "country": "US", "include": {"aioverview": True}}
+    assert out.startswith("Google AI Overview:\nAn overview.\nSources:\n- Src: https://example.net\n\n1. First")
+    assert "Second" not in out
+
+
+@patch("crewai_cloro.tools.httpx.post")
+def test_google_search_no_results(post):
+    post.return_value = _response(200, {"success": True, "result": {"organicResults": []}})
+    assert CloroGoogleSearchTool().run(query="nothing") == "No Google results for: nothing"
+
+
+@pytest.mark.parametrize(
+    ("engine", "path", "label"),
+    [
+        ("google_ai_mode", "/v1/monitor/aimode", "Google AI Mode"),
+        ("bing_ai_mode", "/v1/monitor/bing/aimode", "Bing AI Mode (Copilot Search in Bing)"),
+        ("chatgpt", "/v1/monitor/chatgpt", "ChatGPT"),
+        ("gemini", "/v1/monitor/gemini", "Gemini"),
+    ],
+)
+@patch("crewai_cloro.tools.httpx.post")
+def test_ai_answers(post, engine, path, label):
+    post.return_value = _response(200, ANSWER)
+    tool = CloroAIAnswerTool(engine=engine, country="gb")
+    out = tool.run(prompt="What is a SERP?")
+
+    assert tool.name == f"cloro_{engine}"
+    assert label in tool.description
+    assert post.call_args.args[0] == f"https://api.cloro.dev{path}"
+    expected = {"prompt": "What is a SERP?", "country": "GB", "include": {"markdown": True}}
+    assert post.call_args.kwargs["json"] == expected
+    assert out == f"{label} answer:\n**Answer.**\n\nSources:\n- Source: https://example.com"
+
+
+def test_custom_name_is_kept():
+    assert CloroAIAnswerTool(engine="gemini", name="ask_gemini").name == "ask_gemini"
+
+
+@patch("crewai_cloro.tools.httpx.post")
+def test_bing_prompt_too_long(post):
+    # 600 CJK characters are 5,400 characters once URL-encoded.
+    with pytest.raises(ValueError, match="too long for Bing AI Mode"):
+        CloroAIAnswerTool(engine="bing_ai_mode")._run(prompt="中" * 600)
+    post.assert_not_called()
+
+
+@patch("crewai_cloro.tools.httpx.post")
+def test_api_error(post):
+    post.return_value = _response(
+        402, {"success": False, "error": {"code": "INSUFFICIENT_CREDITS", "message": "Not enough credits"}}
+    )
+    with pytest.raises(CloroError, match="402: INSUFFICIENT_CREDITS Not enough credits"):
+        CloroAIAnswerTool(engine="gemini")._run(prompt="hi")
+
+
+@patch("crewai_cloro.tools.httpx.post")
+def test_network_error(post):
+    post.side_effect = httpx.ConnectError("down")
+    with pytest.raises(CloroError, match="failed"):
+        CloroGoogleSearchTool()._run(query="hi")