llama-index-tools-cloro

LlamaIndex 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 llama-index-tools-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=....

Usage

With an agent

import asyncio

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.cloro import CloroToolSpec

cloro = CloroToolSpec(country="US", include_ai_overview=True)
agent = FunctionAgent(
    tools=cloro.to_tool_list(),
    llm=OpenAI(model="gpt-4.1"),
    system_prompt="Answer with live search results. Cite the URLs you use.",
)


async def main() -> None:
    print(await agent.run("What do Google AI Mode and ChatGPT say are the best SERP APIs?"))


asyncio.run(main())

To give the agent only some tools, filter the list:

tools = [t for t in cloro.to_tool_list() if t.metadata.name in ("google_search", "google_ai_mode")]

Direct calls

from llama_index.tools.cloro import CloroToolSpec

cloro = CloroToolSpec()

for doc in cloro.google_search("retrieval-augmented generation", max_results=5, country="GB"):
    print(doc.metadata["title"], doc.metadata["url"])

answer = cloro.google_ai_mode("What is retrieval-augmented generation?")[0]
print(answer.text)
print(answer.metadata["sources"])

Each tool returns a list of Document. The text is what the agent reads:

• google_search: one Document per result. The text is the title, the URL and the snippet. metadata has title, url and position. Results with an empty link or a Google redirect link are skipped. With the AI Overview turned on, the first Document is the AI Overview and its sources, with metadata["engine"] == "google_ai_overview".
• The AI answer tools: one Document. The text is the answer as Markdown, then a "Sources" list. metadata has engine, prompt and sources (a list of title and url).

Parameters

CloroToolSpec(api_key=None, country="US", timeout=180.0, include_ai_overview=False)

• 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. Each tool also takes country per call.
• timeout: request timeout in seconds. An AI answer can take 15 to 60 seconds.
• include_ai_overview: make google_search also return the Google AI Overview. It costs 2 more credits per search.

Limits

• Bing AI Mode accepts a prompt of up to 3,500 characters after URL encoding. Non-Latin scripts allow fewer characters. bing_ai_mode 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 --with 'llama-index-core>=0.13,<0.15' --with httpx --with pytest -- python -m pytest tests

The tests mock the network. The API reference is at cloro.dev/docs.

License

MIT