Agents

Pathfinder uses two Kani-based agents: the main unified agent and sub-agents for delegated tasks. Both extend Kani with tools and prompts tailored to VEuPathDB strategy building.

Agent Comparison

Agent	Purpose	Tools	When Used
PathfinderAgent	Unified chat agent	All tools (catalog, strategy, research, delegation)	Every chat conversation
SubtaskAgent	Delegated sub-task	Same minus delegation	Multi-step builds via sub-kani
ExperimentAssistantAgent	Experiment wizard helper	Research + catalog + gene lookup	POST /api/v1/experiments/ai-assist
WorkbenchAgent	Workbench analysis chat	7 tool mixins (research, gene, catalog, refinement, analysis, workbench)	Workbench conversations

PathfinderAgent (Unified)

Purpose: The single agent for all conversations. Handles research (catalog exploration, literature search, control tests, optimization) and execution (graph building, strategy composition) in a unified tool set. The model decides per-turn which capabilities to use. For multi-step builds, delegates to sub-kanis.

Inherits: veupath_chatbot.ai.tools.unified_registry.UnifiedToolRegistryMixin, Kani

Tools: Catalog (list_sites, get_record_types, search_for_searches, etc.), strategy tools (create_step, list_current_steps, build_strategy, delete_step, update_step, etc.), conversation tools (save_strategy, load_strategy), research (web_search, literature_search), validation (run_control_tests, optimize_search_parameters, lookup_gene_records), artifacts (save_planning_artifact), and delegate_strategy_subtasks.

Tip

The unified agent has no separate “plan mode” or “execute mode”. The model autonomously decides per-turn whether to research, plan, or build. This matches how researchers naturally describe goals.

Kani agent runtime (class + subkani orchestration).

class veupath_chatbot.ai.agents.executor.PathfinderAgent(engine, site_id, user_id=None, chat_history=None, strategy_graph=None, selected_nodes=None, mentioned_context=None, disable_rag=False, desired_response_tokens=None)

Bases: UnifiedToolRegistryMixin, Kani

Unified VEuPathDB Strategy Agent — research, planning, and execution.

Combines executor (graph building, delegation, WDK execution) and planner (gene lookup, control tests, parameter optimization, artifacts) capabilities in a single agent. The model decides per-turn whether to research/plan or build/execute.

functions: dict[str, AIFunction]

__init__(engine, site_id, user_id=None, chat_history=None, strategy_graph=None, selected_nodes=None, mentioned_context=None, disable_rag=False, desired_response_tokens=None)

async do_function_call(call, tool_call_id=None)

Execute a tool call, then auto-build if the graph is ready.

After any graph-mutating tool, if the graph has exactly one root and hasn’t been pushed to WDK yet, build it. The result (or error) is appended to the tool’s return message so the model sees it.

Return type:

FunctionCallResult

async delegate_strategy_subtasks(goal, plan=None)

Spawn sub-kanis to discover searches and parameters (nested plan).

Return type:

JSONObject

SubtaskAgent (Sub-kani)

Purpose: Sub-agent spawned by the orchestrator for one delegated task. Has the same tools as the main agent (catalog, strategy) but no delegation. Each sub-kani creates exactly one step (or edits one) and returns the result.

Inherits: veupath_chatbot.ai.tools.registry.AgentToolRegistryMixin, Kani

Tools: Same as PathfinderAgent minus delegate_strategy_subtasks.

When used: Internally by veupath_chatbot.ai.orchestration.subkani.orchestrator.delegate_strategy_subtasks() for each task node in the delegation plan.

Sub-agent used for decomposed strategy-building tasks.

class veupath_chatbot.ai.agents.subtask.SubtaskAgent(engine, site_id, session, graph_id, chat_history)

Bases: AgentToolRegistryMixin, Kani

Sub-kani agent for search discovery and parameter lookup.

__init__(engine, site_id, session, graph_id, chat_history)

ExperimentAssistantAgent

Purpose: Lightweight AI assistant for the workbench experiment wizard. Scoped to research capabilities (web search, literature search, catalog tools, gene lookup) for helping users configure experiment steps.

Inherits: ResearchToolsMixin, Kani

Tools: web_search, literature_search, catalog tools, gene lookup. No strategy mutation or delegation tools.

When used: By the experiment wizard AI-assist endpoint (POST /api/v1/experiments/ai-assist).

Lightweight AI assistant agent for the Experiment Lab wizard.

Uses the same Kani framework and research tools as the main agents but with a much narrower scope: help the user navigate wizard steps (search selection, parameter configuration, control gene discovery, run configuration).

class veupath_chatbot.ai.agents.experiment.ExperimentAssistantAgent(engine, site_id, system_prompt, chat_history=None)

Bases: ResearchToolsMixin, Kani

Scoped assistant for experiment wizard steps.

Has access to: - Web search and literature search (via ResearchToolsMixin) - VEuPathDB catalog tools (record types, searches, parameters) - Gene lookup (site-search based)

__init__(engine, site_id, system_prompt, chat_history=None)

async get_record_types()

List record types available on the current VEuPathDB site.

Return type:

JSONObject

async list_searches(record_type)

List available WDK searches for a record type.

Return type:

JSONObject

async search_for_searches(query)

Find VEuPathDB searches matching a research question or keyword.

Return type:

JSONObject

async get_search_parameters(record_type, search_name)

Get parameter specifications for a WDK search.

Return type:

JSONObject

async lookup_genes(query, organism=None, limit=10)

Search for gene records on the current VEuPathDB site.

Returns gene IDs, names, organisms, and product descriptions. Useful for resolving gene names from literature to VEuPathDB IDs that the user can add as controls.

Return type:

JSONObject

WorkbenchAgent

Purpose: Full-featured conversational AI agent for the workbench. Provides experiment result exploration, gene set analysis, strategy refinement, and literature research within the context of a specific experiment.

Inherits: Composes 7 tool mixins (research, gene, catalog, refinement, analysis, workbench read, workbench mutation) + Kani

When used: By the workbench chat endpoint, scoped to a (user_id, experiment_id) pair.

Workbench AI chat agent.

Conversational agent for experiment result exploration. Composes research, catalog, analysis, refinement, gene, and workbench tool mixins.

class veupath_chatbot.ai.agents.workbench.WorkbenchAgent(engine, site_id, experiment_id, user_id=None, system_prompt='', chat_history=None)

Bases: WorkbenchReadToolsMixin, RefinementToolsMixin, _AnalysisToolsMixin, GeneToolsMixin, WorkbenchToolsMixin, CatalogToolsMixin, ResearchToolsMixin, Kani

Conversational AI agent for the workbench.

Has access to all tool categories from the design spec: - Research (web search, literature search) - Gene data (lookup, detail, compare, distributions) - WDK catalog (search discovery, parameters, record types) - Strategy modification (refine, filter, re-evaluate) - Workbench reads (metrics, enrichment, confidence, contributions) - Workbench actions (gene sets: create, enrich, list)

__init__(engine, site_id, experiment_id, user_id=None, system_prompt='', chat_history=None)

Agent Factory

Purpose: Build the agent with the right engine and model. Resolves model ID from override, persisted state, or server default.

See AI & Agent for full reference.