Agent Tools¶

This page documents the agent tools available to the conversational agents, including the default toolset used when none is specified.

Default Toolset¶

The following tools are enabled by default (from DEFAULT_TOOL_NAMES):

search_nihai — Docs: NihAI Search
ask_nihai — Docs: NihAI Ask

Available Tools¶

ask_nihai¶

async def _tool_wrap_nihai_ask(messages: list[dict[str, str]] | None = None, profile: str | None = None, max_results: int = 8, query: str | None = None) -> SearchResult

Ask NihAI to answer using the current conversation context.

Parameters: - messages: Conversation history as a list of objects like {"role": "user"|"assistant", "content": "..."}. The final user message should contain the question to answer. - profile: Optional patient profile string (location, age, pregnancy status, etc.). - max_results: Maximum number of NihAI entries to return after enrichment. - query: Backward‑compatibility single‑string query. If provided and messages is empty, a single user message is synthesized.

Behavior: - If NihAI lacks an answer, the system enriches the knowledge base using Perplexity sources, writes a normalized Q&A entry, then re-queries NihAI.

Guidance: - This tool can be slower and more resource intensive than search_nihai and may write to the NihAI knowledge base. Use search_nihai FIRST, and only call this if retrieval is insufficient.

Returns: SearchSuccess with FAQs and references, or SearchFailure with error details Related Search Docs: NihAI Ask

ask_nihai_older¶

async def _tool_wrap_nihai_ask_older(messages: list[dict[str, str]] | None = None, profile: str | None = None, max_results: int = 8, query: str | None = None) -> list[dict]

Ask NihAI but target the OLDER_NIHAI_COLLECTION explicitly.

ask_nihai_openai¶

async def _tool_wrap_nihai_ask_openai(messages: list[dict[str, str]] | None = None, profile: str | None = None, max_results: int = 8, query: str | None = None) -> SearchResult

Ask NihAI to answer using OpenAI web search for knowledge base enrichment.

Same as ask_nihai but uses OpenAI with web search instead of Perplexity when enriching the knowledge base with new information.

Parameters: - messages: Conversation history as a list of objects like {"role": "user"|"assistant", "content": "..."}. - profile: Optional patient profile string (location, age, pregnancy status, etc.). - max_results: Maximum number of NihAI entries to return after enrichment. - query: Backward‑compatibility single‑string query.

Returns: SearchSuccess with FAQs and references, or SearchFailure with error details

depricate_nihai_faq¶

async def _tool_wrap_nihai_depricate(uuid: str, collection: str | None = None) -> dict

Mark a NihAI FAQ entry inactive (soft deprecation).

search_googlesheet_faqs¶

async def _tool_wrap_googlesheet(query: str, max_results: int = 3, relevance_threshold: float = 0.3) -> list[dict]

Related Search Docs: Googlesheet

search_nihai¶

async def _tool_wrap_search_nihai(query: str, max_results: int = 3) -> SearchResult

Search NihAI FAQ database for medical information.

Args: query: Medical question or topic to search max_results: Maximum FAQ entries to return (1-10)

Returns: SearchSuccess with FAQs and references, or SearchFailure with error details Related Search Docs: NihAI Search

search_nihai_older¶

async def _tool_wrap_search_nihai_older(query: str, max_results: int = 3) -> list[dict]

search_noora_faq¶

async def _tool_wrap_noora_faq(query: str, max_results: int = 3) -> list[dict]

Direct RAG search against the Noora FAQ collection.

Not enabled by default; callers must include 'search_noora_faq' in tools list. Requires NOORA_FAQ_COLLECTION_NAME env var.

search_openai¶

async def _tool_wrap_openai(query: str, source_type: str | None = None, medical_category: str | None = None, max_results: int = 5) -> PerplexitySuccess | PerplexityFailure

Wrap search_openai for agent tool usage.

Args: query: Medical search query source_type: Optional filter by source type medical_category: Optional filter by medical category max_results: Maximum number of results to return (default: 5)

Returns: PerplexitySuccess with answer and sources, or PerplexityFailure with error (Note: We reuse PerplexitySuccess/Failure models for consistency)

Note: We no longer normalize or restrict source_type. Any provided value is passed through to the underlying implementation.

search_perplexity¶

async def _tool_wrap_perplexity(query: str, source_type: str | None = None, medical_category: str | None = None, max_results: int = 5) -> PerplexityResult

Perplexity medical search fallback tool.

Args: query: Medical question or topic source_type: Source filter (e.g., "pubmed", "medline") medical_category: Medical category filter (optional) max_results: Maximum sources to return

Returns: PerplexitySuccess with answer and sources, or PerplexityFailure with error

Note: We no longer normalize or restrict source_type. Any provided value is passed through to the underlying implementation. Related Search Docs: Perplexity Med

search_pubmed¶

async def _tool_wrap_pubmed(query: str, max_results: int = 3, email: str | None = None) -> list[dict]

Related Search Docs: PubMed

search_september¶

async def _tool_wrap_september(query: str, max_results: int = 3, section_filter: str | None = None) -> list[dict]

Related Search Docs: September

write_nihai¶

async def _tool_wrap_nihai_write(question: str, answer: str, references: list[dict] | None = None, condition_area: str | None = None, topic: str | None = None, is_verified: bool = False, approvers: str = '', source: str = 'perplexity', accuracy_confidence: float | None = 0.6) -> WriteResult

Write a NihAI FAQ entry and return its UUID.

Use this only after verifying that no suitable existing entry covers the need.

Args: question: Medical question answer: Detailed answer references: List of source references (optional) condition_area: Medical condition category (optional) topic: Specific topic tag (optional) is_verified: Whether this entry is verified by medical experts approvers: Comma-separated list of approvers (optional) source: Source system (default: "perplexity") accuracy_confidence: Confidence score 0-1 (optional)

Returns: WriteSuccess with UUID, or WriteFailure with error details

write_nihai_from_openai¶

async def _tool_wrap_nihai_write_from_openai(question: str, condition_area: str | None = None, topic: str | None = None, category: str | None = None, topic_area: str | None = None, max_tokens: int = 500, return_details: bool = False, model: str = 'gpt-5-mini') -> SearchResult

Fetch an answer + sources from OpenAI (with web search) and write into NihAI in one step.

Requirements: - question: Must be written in English. If the user's input is not English, the agent MUST rewrite the question to English before calling this tool. - The answer will also be stored in English.

Returns: SearchSuccess with the newly created FAQ entry, or SearchFailure with error

write_nihai_from_perplexity¶

async def _tool_wrap_nihai_write_from_perplexity(question: str, condition_area: str | None = None, topic: str | None = None, category: str | None = None, topic_area: str | None = None, max_tokens: int = 500, return_details: bool = False) -> SearchResult

Fetch an answer + sources from Perplexity and write into NihAI in one step.

Requirements: - question: Must be written in English. If the user's input is not English, the agent MUST rewrite the question to English before calling this tool. - The answer will also be stored in English.

Returns: SearchSuccess with the newly created FAQ entry, or SearchFailure with error

Source: agents/tools.py