crewai-cloro

CrewAI tools for cloro. 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.

Installation

pip install crewai-cloro

Get an API key at dashboard.cloro.dev. The free plan includes 500 credits each month. Set the key as CLORO_API_KEY, or pass api_key=... to a tool.

Usage

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:

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

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.

License

MIT