Open History to see the last commit
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
16}
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]
25}
26
27export interface CreateExecutePromptToolConfig {
28 adapter: AnyTextAdapter
29 system?: string
30 inner: ExecutePromptInnerChat
31 maxTokens?: number
32 onEvent?: (event: ExecutePromptEvent) => void
33}
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).
74`
75}
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 }
139}