Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

create-execute-prompt-tool.ts

139 lines3.9 KB

1/**
2 * Example: nested `execute_prompt` tool — not part of @tanstack/ai-code-mode.
3 * Compose with `createCodeMode` (or any inner tools + system prompt).
4 */
5import { chat, toolDefinition } from '@tanstack/ai'
6import { z } from 'zod'
7import { maxTokensModelOptions } from './max-tokens-model-options'
8import type { AnyTextAdapter, ServerTool } from '@tanstack/ai'
9import type { CodeModeTool } from '@tanstack/ai-code-mode'
10​
11export interface ExecutePromptEvent {
12 type: string
13 message: string
14 data?: unknown
15 timestamp: number
17​
18export type ExecutePromptInnerChat =
19 | { tool: CodeModeTool; systemPrompt: string }
20 | { tools: Array<CodeModeTool>; systemPrompt: string }
21​
22function innerChatToolList(inner: ExecutePromptInnerChat): Array<CodeModeTool> {
23 if ('tools' in inner) return inner.tools
24 return [inner.tool]
26​
27export interface CreateExecutePromptToolConfig {
28 adapter: AnyTextAdapter
29 system?: string
30 inner: ExecutePromptInnerChat
31 maxTokens?: number
32 onEvent?: (event: ExecutePromptEvent) => void
34​
35const executePromptInputSchema = z.object({
36 prompt: z
37 .string()
38 .describe(
39 'Natural-language instruction for the inner agent (what to compute or retrieve).',
40 ),
41})
42​
43const executePromptOutputSchema = z.object({
44 data: z
45 .unknown()
46 .describe('Parsed JSON result from the inner agent, or raw text metadata'),
47})
48​
49export type ExecutePromptToolInput = z.infer<typeof executePromptInputSchema>
50export type ExecutePromptToolOutput = z.infer<typeof executePromptOutputSchema>
51​
52const DEFAULT_SYSTEM = `You are a data agent. The user will describe what they need.
53Use the available tools to obtain or compute the answer.
54Return JSON in whatever format you think is an appropriate response
55to the query. Output only the JSON in your final message, nothing else.`
56​
57function buildExecutePromptSystemPrompt(): string {
58 return `## execute_prompt (nested agent)
59​
60You can call \`execute_prompt\` to run a **separate** inner agent with its own tools and instructions. The inner agent returns structured JSON.
61​
62### When to use
63​
64- Use \`execute_prompt\` when the user needs multi-step work that fits the inner agent's capabilities.
65- For simple requests, prefer calling tools directly.
66​
67### Arguments
68​
69- \`prompt\`: Clear natural-language instruction for the inner agent.
70​
71### Result
72​
73- \`data\`: Parsed JSON from the inner agent's final message (or raw text metadata if parsing fails).
76​
77export function createExecutePromptTool(
78 config: CreateExecutePromptToolConfig,
79): {
80 tool: ServerTool<
81 typeof executePromptInputSchema,
82 typeof executePromptOutputSchema,
83 'execute_prompt'
84 >
85 systemPrompt: string
86} {
87 const { adapter, system, maxTokens, onEvent, inner } = config
88​
89 const definition = toolDefinition({
90 name: 'execute_prompt' as const,
91 description:
92 'Run a nested inner agent with its own tools; returns parsed JSON in `data`.',
93 inputSchema: executePromptInputSchema,
94 outputSchema: executePromptOutputSchema,
95 })
96​
97 const tool = definition.server(async (input) => {
98 const { prompt } = input
99​
100 onEvent?.({
101 type: 'inner:ready',
102 message: 'Inner chat starting',
103 timestamp: Date.now(),
104 })
105​
106 const baseSystem = system ?? DEFAULT_SYSTEM
107 const text = await chat({
108 adapter,
109 systemPrompts: [baseSystem, inner.systemPrompt],
110 messages: [{ role: 'user', content: prompt }],
111 tools: innerChatToolList(inner),
112 stream: false as const,
113 // Sampling lives in provider-native `modelOptions` now; map the generic
114 // cap to the resolved adapter's wire key.
115 modelOptions: maxTokensModelOptions(adapter, maxTokens),
116 })
117​
118 let data: unknown
119 try {
120 data = JSON.parse(text)
121 } catch {
122 data = { raw: text, parseError: true }
123 }
124​
125 onEvent?.({
126 type: 'inner:complete',
127 message: 'Result ready',
128 data,
129 timestamp: Date.now(),
130 })
131​
132 return { data }
133 })
134​
135 return {
136 tool,
137 systemPrompt: buildExecutePromptSystemPrompt(),
138 }