Agentic Tools system
Relevant source files
The following files were used as context for generating this wiki page:
The Agentic Tools system in ThinkEx is a modular framework that enables AI models to interact with external data and the user's workspace. It allows the assistant to perform actions such as searching the web, analyzing specific URLs, and reading or modifying workspace items like documents, quizzes, and flashcards.
The system is designed to provide "user-controlled context," where the AI utilizes tools to fetch content only when needed, rather than flooding the initial context window with raw data. This is achieved through a combination of server-side tool definitions and client-side UI components that visualize tool execution and results.
Sources: README.md, src/lib/utils/format-workspace-context.ts:70-85
Core Architecture and Data Flow
The tool system operates within the chat completion lifecycle. When a user submits a message, the system prompt informs the AI of available tools and the current workspace state. If the AI determines a tool is required, it generates a toolCall, which is executed on the server.
This diagram shows the end-to-end flow from a user request to tool execution and UI visualization.
Sources: src/app/api/chat/route.ts:160-200, src/app/api/workspaces/autogen/route.ts:25-50
System Prompt Integration
The AI is instructed to use tools like readWorkspace or searchWorkspace to fetch full content, as the initial context only contains item paths and metadata. The instructions specify that the AI should never mention internal tool names or raw JSON in its natural language responses to the user.
Sources: src/lib/utils/format-workspace-context.ts:88-115
Key Agentic Tools
The system provides several specialized tools for information retrieval and workspace management.
Web Search and URL Processing
ThinkEx uses Google's Gemini models to perform grounded web searches and deep URL analysis.
| Tool Name | Purpose | Key Parameters |
|---|---|---|
webSearch | Searches the web for current, real-time information. | query (string) |
processUrls | Analyzes specific web pages, articles, or documentation. | urls (string[]), instruction (string) |
Sources: src/lib/ai/tools/web-search.ts:125-135, src/lib/ai/tools/process-urls.ts:18-30
Workspace Management Tools
Tools allow the AI to interact directly with the user's file system (FS) and items.
- readWorkspace: Fetches full content of items (e.g., PDF OCR text, document markdown).
- editItem: Modifies existing items like flashcards or quizzes using JSON payloads.
- bulkCreate: Used primarily in
autogenworkflows to populate a workspace with multiple items at once.
Sources: src/lib/utils/format-workspace-context.ts:120-130, src/app/api/workspaces/autogen/route.ts:510-530
Tool Execution Logic
Web Search Flow
The executeWebSearch function utilizes gemini-2.5-flash-lite with the googleSearch tool. It includes a redirection resolver to handle Vertex AI search links, ensuring the AI receives final, reachable URLs.
This sequence illustrates how web search results are processed and redirect URLs are sanitized before being returned to the AI.
Sources: src/lib/ai/tools/web-search.ts:10-40, src/lib/ai/tools/web-search.ts:98-120
URL Contextualization
The processUrls tool uses the google.tools.urlContext to extract content and metadata from specific links. It filters out internal Supabase or YouTube URLs to prevent incorrect tool usage, as those are handled by native file processing.
Sources: src/lib/ai/tools/process-urls.ts:25-45
Content Formatting and Constraints
The system enforces strict formatting rules for any content generated or modified by tools, particularly for documents and quizzes.
- Math Formatting: Tools must use single
$for inline and$$for block LaTeX. Dollar signs for currency must be escaped as\$to avoid being parsed as math. - Citations: The AI is encouraged to use
<citation>REF</citation>tags in chat responses, where REF can be a URL, workspace path, or specific PDF page (e.g.,pdfs/Syllabus.pdf | p. 3). - Tool Output Sanitization: Historical tool results are sanitized before being sent back to the model to remove redundant internal fields like
version,itemId, oreventpayloads, saving context tokens.
Sources: src/lib/utils/format-workspace-context.ts:150-180, src/lib/ai/tools/tests/tool-utils-sanitize.test.ts:40-60
Tool Result Validation
Results from tools are validated against Zod schemas before being rendered in the Assistant UI.
| Schema | Associated Tools | Fields |
|---|---|---|
WorkspaceResultSchema | createDocument, editItem | success, message, itemId |
EditItemResultSchema | editItem | diff, filediff (additions/deletions) |
QuizResultSchema | createQuiz | quizId, title, questionCount |
Sources: src/lib/ai/tool-result-schemas.ts:13-60
Summary
The Agentic Tools system acts as the bridge between the AI's reasoning capabilities and the ThinkEx workspace environment. By utilizing specialized tools for web search, URL analysis, and workspace item manipulation, it enables the assistant to provide accurate, grounded responses while maintaining a persistent and organized knowledge base for the user.