@alexkroman1/aai-cli 0.9.0

package/templates/smart-research/agent.ts

@@ -0,0 +1,164 @@
+import { defineAgent, tool } from "@alexkroman1/aai";
+import type { HookContext, StepInfo } from "@alexkroman1/aai";
+import { z } from "zod";
+
+/**
+ * Smart Research Agent — demonstrates all 5 advanced features:
+ * 1. toolChoice: "required" — forces the LLM to use tools every step
+ * 2. ctx.messages — tools can read conversation history
+ * 3. onStep — logs each step's tool calls
+ * 4. onBeforeStep — restricts available tools based on research phase
+ * 5. maxSteps as function — adapts max steps based on session complexity
+ */
+
+type ResearchState = {
+  phase: "gather" | "analyze" | "respond";
+  sources: string[];
+  stepCount: number;
+  complexity: "simple" | "deep";
+};
+
+export default defineAgent({
+  name: "Smart Research Agent",
+  instructions: `You are a research assistant that gathers information, \
+analyzes it, then responds. You work in three phases:
+1. Gather: Use search and fetch tools to collect information.
+2. Analyze: Use the analyze tool to synthesize your findings.
+3. Respond: Deliver your final answer.
+
+Always search first, then analyze, then answer. Be thorough but concise.`,
+  greeting:
+    "I'm your research assistant. Ask me anything and I'll dig into it.",
+  builtinTools: ["web_search"],
+
+  // Feature 1: toolChoice — force the LLM to always use a tool
+  toolChoice: "required",
+
+  // Feature 5: maxSteps as function — more steps for complex research
+  maxSteps: (ctx: HookContext<ResearchState>) => {
+    const state = ctx.state;
+    return state.complexity === "deep" ? 10 : 5;
+  },
+
+  state: (): ResearchState => ({
+    phase: "gather",
+    sources: [],
+    stepCount: 0,
+    complexity: "simple",
+  }),
+
+  // Feature 3: onStep — track what tools were called each step
+  onStep: (step: StepInfo, ctx: HookContext<ResearchState>) => {
+    const state = ctx.state;
+    state.stepCount++;
+    for (const tc of step.toolCalls) {
+      console.log(
+        `[step ${step.stepNumber}] ${tc.toolName} (phase: ${state.phase})`,
+      );
+    }
+  },
+
+  // Feature 4: onBeforeStep — restrict tools per research phase
+  onBeforeStep: (
+    _stepNumber: number,
+    ctx: HookContext<ResearchState>,
+  ) => {
+    const state = ctx.state;
+    if (state.phase === "gather") {
+      return {
+        activeTools: [
+          "web_search",
+          "save_source",
+          "mark_complex",
+          "advance_phase",
+        ],
+      };
+    }
+    if (state.phase === "analyze") {
+      return {
+        activeTools: [
+          "analyze",
+          "conversation_summary",
+          "advance_phase",
+        ],
+      };
+    }
+    // respond phase: no tools needed, LLM responds with text directly
+    return { activeTools: [] };
+  },
+
+  tools: {
+    save_source: tool<z.ZodObject<{ url: z.ZodString; title: z.ZodString }>, ResearchState>({
+      description: "Save a source URL found during research for later analysis",
+      parameters: z.object({
+        url: z.string().describe("The source URL"),
+        title: z.string().describe("Brief title or description"),
+      }),
+      execute: ({ url, title }, ctx) => {
+        const state = ctx.state;
+        state.sources.push(`${title}: ${url}`);
+        return { saved: true, totalSources: state.sources.length };
+      },
+    }),
+
+    mark_complex: {
+      description:
+        "Mark this research query as complex, allowing more search steps",
+      execute: (_args, ctx) => {
+        const state = ctx.state;
+        state.complexity = "deep";
+        return { complexity: "deep", maxSteps: 10 };
+      },
+    },
+
+    advance_phase: {
+      description:
+        "Move to the next research phase (gather -> analyze -> respond)",
+      execute: (_args, ctx) => {
+        const state = ctx.state;
+        if (state.phase === "gather") {
+          state.phase = "analyze";
+        } else if (state.phase === "analyze") {
+          state.phase = "respond";
+        }
+        return { phase: state.phase };
+      },
+    },
+
+    // Feature 2: ctx.messages — access conversation history in tools
+    analyze: tool<z.ZodObject<{ focus: z.ZodString }>, ResearchState>({
+      description:
+        "Analyze all gathered sources and conversation context to form a conclusion",
+      parameters: z.object({
+        focus: z.string().describe("What aspect to focus the analysis on"),
+      }),
+      execute: ({ focus }, ctx) => {
+        const state = ctx.state;
+        // Use ctx.messages to see what's been discussed
+        const userMessages = ctx.messages.filter((m) => m.role === "user");
+        return {
+          focus,
+          sources: state.sources,
+          conversationTurns: userMessages.length,
+          totalMessages: ctx.messages.length,
+          phase: state.phase,
+        };
+      },
+    }),
+
+    conversation_summary: {
+      description: "Get a summary of the conversation so far",
+      execute: (_args, ctx) => {
+        const msgs = ctx.messages;
+        return {
+          totalMessages: msgs.length,
+          byRole: {
+            user: msgs.filter((m) => m.role === "user").length,
+            assistant: msgs.filter((m) => m.role === "assistant").length,
+            tool: msgs.filter((m) => m.role === "tool").length,
+          },
+        };
+      },
+    },
+  },
+});

package/templates/smart-research/client.tsx

@@ -0,0 +1,3 @@
+import "@alexkroman1/aai-ui/styles.css";
+import { App, mount } from "@alexkroman1/aai-ui";
+mount(App);