Skip to content
RelationalAI Docs

Tool

relationalai.agent.cortex.tool

Abstract base class for the RAI tool behind a Cortex agent.

An agent serves one model through one Tool, which init_tools returns. The Tool answers every RAI procedure the agent calls:

  • Discovery: the model’s description, key concepts and queries
  • Verbalization: detailed model structure and relationships
  • Explanation: business rules and semantics for specific concepts
  • Querying: structured queries against the model

Implement this interface to create a custom tool, or use DefaultTool for a standard RAI model.

Methods

.model()

Tool.model() -> rai.Model

Return the model this tool answers from.

Agent deploy, and every procedure call, point this model at the agent’s model_deployment.

Returns:

  • relationalai.semantics.Model - The tool’s model.

.description()

Tool.description() -> str

Return a human-readable description of this tool’s purpose.

Returns:

  • str - A description of the tool.

.concepts()

Tool.concepts() -> List[str]

Return list of key concept names available in this tool’s domain.

Returns:

  • list of str - Concept names available in this tool.

.verbalize()

Tool.verbalize() -> str

Return detailed structure and relationships for the entire model.

Returns:

  • str - A natural language description of the model structure.

.explain()

Tool.explain(concept: str) -> str

Return detailed explanation of business rules for a specific concept.

Parameters:

  • concept

    (str) - The name of the concept to explain.

Returns:

  • str - A natural language explanation of the concept.

.capabilities()

Tool.capabilities() -> Set[Capability]

Return the capabilities this tool supports.

Override to add Capability.QUERY when Tool.query is implemented.

Returns:

  • set of Capability - DISCOVER, VERBALIZE and EXPLAIN by default.

.queries()

Tool.queries() -> QueriesMeta

Return a typed view of the available pre-defined queries.

Returns:

  • QueriesMeta - Typed view exposing QueriesMeta.mode, QueriesMeta.catalog_entries, and the raw underlying dict. When no Queries provider is configured, mode is None and QueriesMeta.message carries a human-readable note.

.query()

Tool.query(params: dict) -> Union[rai.Fragment, pandas.DataFrame]

Execute a query against this tool’s model and return results.

Parameters:

  • params

    (dict) - Query parameters including "id" (query identifier) and "args" (query arguments).

Returns:

  • relationalai.semantics.Fragment or pandas.DataFrame - Query results.

Raises:

  • ValueError - If queries capability is not configured.
  • KeyError - If query ID is not found.

Inheritance Hierarchy

Toolabc.ABC

Subclassed By