Integrations

Use Canonical with popular AI agent frameworks. The Python SDK works as a drop-in tool for LangChain, AutoGen, CrewAI, Agno, and any framework that supports Python functions.

Before you start

Every example below builds on the same two steps. Do these first, then jump to your framework.

Install the Canonical SDK.
```
pip install canonical-search
```
Get an API key. Create one in Settings → API Keys — it's the YOUR_API_KEY in every snippet. Store it in an environment variable, not in source. See Authentication for details.
Install your agent framework. Each framework ships as its own package — the exact install command is shown with its example below.

LangChain

Install: pip install langchain-core

from langchain_core.tools import tool
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="YOUR_API_KEY")

@tool
def search_companies(query: str, top_k: int = 25) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

AutoGen

Install: pip install "ag2[openai]" — this uses the classic register_function API (AutoGen v0.2 / AG2), not the newer autogen-agentchat 0.4+ package. The [openai] extra is what lets AssistantAgent talk to a model.

from autogen import register_function
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="YOUR_API_KEY")

def search_companies(query: str, top_k: int = 25) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

register_function(
    search_companies,
    caller=assistant,
    executor=executor,
    description="Search for companies using natural language",
)

CrewAI

Install: pip install crewai

from crewai.tools import tool
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="YOUR_API_KEY")

@tool("Company Search")
def search_companies(query: str, top_k: int = 25) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

Agno

Install: pip install agno

from agno.tools import tool
from canonical_search import CanonicalClient

client = CanonicalClient(api_key="YOUR_API_KEY")

@tool
def search_companies(query: str, top_k: int = 25) -> str:
    """Search for companies using natural language."""
    return client.search(query, top_k).model_dump_json()

Any Python Framework

The SDK returns Pydantic models, so it works with any framework that accepts Python functions. Use .model_dump_json() for string output or .model_dump() for dict output. Every method has an async twin (a-prefixed) for async agents.

The examples above wrap search as a single tool. The SDK exposes the full company-graph — expose each method as its own tool so your agent can discover, disambiguate, drill in, and check credits:

from canonical_search import CanonicalClient, StructuredFilters, StructuredLocation

client = CanonicalClient(api_key="YOUR_API_KEY")

# 1. Natural-language search
def search(query: str, top_k: int = 25) -> str:
    return client.search(query, top_k).model_dump_json()

# 2. Structured search — filter by location, size, funding, founding year
def search_by_filters(description: str, country: str, min_employees: int) -> str:
    filters = StructuredFilters(
        location=StructuredLocation(countries=[country]),
        employee_count_min=min_employees,
    )
    return client.search_structured(description, filters=filters).model_dump_json()

# 3. Find look-alike companies from a seed domain
def find_similar(company_domain: str, top_k: int = 25) -> str:
    return client.find_similar_companies(company_domain, top_k).model_dump_json()

# 4. Resolve a name to a domain before drilling in
def lookup(names: list[str]) -> str:
    return client.lookup_companies(names).model_dump_json()

# 5. Drill into one company (profile, people, corporate family)
def company_details(company_domain: str) -> str:
    return client.get_company_details(company_domain).model_dump_json()

# 6. Check remaining credits / plan / rate limits (free)
def account_status() -> str:
    return client.get_account_status().model_dump_json()

Register these with any framework the same way as the search examples above (LangChain @tool, CrewAI @tool("..."), AutoGen register_function, Agno @tool).