feat(agent):Supports custom agent and chat experience with refactoring (#957)

* feat: add agent management functionality with creation, editing, and deletion

* feat: enhance agent creation and chat experience

- Added AgentWelcome component to display agent description on new thread creation.
- Improved agent name validation with availability check during agent creation.
- Updated NewAgentPage to handle agent creation flow more effectively, including enhanced error handling and user feedback.
- Refactored chat components to streamline message handling and improve user experience.
- Introduced new bootstrap skill for personalized onboarding conversations, including detailed conversation phases and a structured SOUL.md template.
- Updated localization files to reflect new features and error messages.
- General code cleanup and optimizations across various components and hooks.

* Refactor workspace layout and agent management components

- Updated WorkspaceLayout to use useLayoutEffect for sidebar state initialization.
- Removed unused AgentFormDialog and related edit functionality from AgentCard.
- Introduced ArtifactTrigger component to manage artifact visibility.
- Enhanced ChatBox to handle artifact selection and display.
- Improved message list rendering logic to avoid loading states.
- Updated localization files to remove deprecated keys and add new translations.
- Refined hooks for local settings and thread management to improve performance and clarity.
- Added temporal awareness guidelines to deep research skill documentation.

* feat: refactor chat components and introduce thread management hooks

* feat: improve artifact file detail preview logic and clean up console logs

* feat: refactor lead agent creation logic and improve logging details

* feat: validate agent name format and enhance error handling in agent setup

* feat: simplify thread search query by removing unnecessary metadata

* feat: update query key in useDeleteThread and useRenameThread for consistency

* feat: add isMock parameter to thread and artifact handling for improved testing

* fix: reorder import of setup_agent for consistency in builtins module

* feat: append mock parameter to thread links in CaseStudySection for testing purposes

* fix: update load_agent_soul calls to use cfg.name for improved clarity

* fix: update date format in apply_prompt_template for consistency

* feat: integrate isMock parameter into artifact content loading for enhanced testing

* docs: add license section to SKILL.md for clarity and attribution

* feat(agent): enhance model resolution and agent configuration handling

* chore: remove unused import of _resolve_model_name from agents

* feat(agent): remove unused field

* fix(agent): set default value for requested_model_name in _resolve_model_name function

* feat(agent): update get_available_tools call to handle optional agent_config and improve middleware function signature

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

frontend/src/core/agents/api.ts

@@ -0,0 +1,67 @@
+import { getBackendBaseURL } from "@/core/config";
+
+import type { Agent, CreateAgentRequest, UpdateAgentRequest } from "./types";
+
+export async function listAgents(): Promise<Agent[]> {
+  const res = await fetch(`${getBackendBaseURL()}/api/agents`);
+  if (!res.ok) throw new Error(`Failed to load agents: ${res.statusText}`);
+  const data = (await res.json()) as { agents: Agent[] };
+  return data.agents;
+}
+
+export async function getAgent(name: string): Promise<Agent> {
+  const res = await fetch(`${getBackendBaseURL()}/api/agents/${name}`);
+  if (!res.ok) throw new Error(`Agent '${name}' not found`);
+  return res.json() as Promise<Agent>;
+}
+
+export async function createAgent(request: CreateAgentRequest): Promise<Agent> {
+  const res = await fetch(`${getBackendBaseURL()}/api/agents`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request),
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(err.detail ?? `Failed to create agent: ${res.statusText}`);
+  }
+  return res.json() as Promise<Agent>;
+}
+
+export async function updateAgent(
+  name: string,
+  request: UpdateAgentRequest,
+): Promise<Agent> {
+  const res = await fetch(`${getBackendBaseURL()}/api/agents/${name}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request),
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(err.detail ?? `Failed to update agent: ${res.statusText}`);
+  }
+  return res.json() as Promise<Agent>;
+}
+
+export async function deleteAgent(name: string): Promise<void> {
+  const res = await fetch(`${getBackendBaseURL()}/api/agents/${name}`, {
+    method: "DELETE",
+  });
+  if (!res.ok) throw new Error(`Failed to delete agent: ${res.statusText}`);
+}
+
+export async function checkAgentName(
+  name: string,
+): Promise<{ available: boolean; name: string }> {
+  const res = await fetch(
+    `${getBackendBaseURL()}/api/agents/check?name=${encodeURIComponent(name)}`,
+  );
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(
+      err.detail ?? `Failed to check agent name: ${res.statusText}`,
+    );
+  }
+  return res.json() as Promise<{ available: boolean; name: string }>;
+}

frontend/src/core/agents/hooks.ts

@@ -0,0 +1,64 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import {
+  createAgent,
+  deleteAgent,
+  getAgent,
+  listAgents,
+  updateAgent,
+} from "./api";
+import type { CreateAgentRequest, UpdateAgentRequest } from "./types";
+
+export function useAgents() {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["agents"],
+    queryFn: () => listAgents(),
+  });
+  return { agents: data ?? [], isLoading, error };
+}
+
+export function useAgent(name: string | null | undefined) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["agents", name],
+    queryFn: () => getAgent(name!),
+    enabled: !!name,
+  });
+  return { agent: data ?? null, isLoading, error };
+}
+
+export function useCreateAgent() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (request: CreateAgentRequest) => createAgent(request),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["agents"] });
+    },
+  });
+}
+
+export function useUpdateAgent() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      name,
+      request,
+    }: {
+      name: string;
+      request: UpdateAgentRequest;
+    }) => updateAgent(name, request),
+    onSuccess: (_data, { name }) => {
+      void queryClient.invalidateQueries({ queryKey: ["agents"] });
+      void queryClient.invalidateQueries({ queryKey: ["agents", name] });
+    },
+  });
+}
+
+export function useDeleteAgent() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (name: string) => deleteAgent(name),
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["agents"] });
+    },
+  });
+}

frontend/src/core/agents/index.ts

@@ -0,0 +1,3 @@
+export * from "./api";
+export * from "./hooks";
+export * from "./types";

frontend/src/core/agents/types.ts

@@ -0,0 +1,22 @@
+export interface Agent {
+  name: string;
+  description: string;
+  model: string | null;
+  tool_groups: string[] | null;
+  soul?: string | null;
+}
+
+export interface CreateAgentRequest {
+  name: string;
+  description?: string;
+  model?: string | null;
+  tool_groups?: string[] | null;
+  soul?: string;
+}
+
+export interface UpdateAgentRequest {
+  description?: string | null;
+  model?: string | null;
+  tool_groups?: string[] | null;
+  soul?: string | null;
+}

frontend/src/core/api/api-client.ts

@@ -5,9 +5,9 @@ import { Client as LangGraphClient } from "@langchain/langgraph-sdk/client";
 import { getLangGraphBaseURL } from "../config";
 
 let _singleton: LangGraphClient | null = null;
-export function getAPIClient(): LangGraphClient {
+export function getAPIClient(isMock?: boolean): LangGraphClient {
   _singleton ??= new LangGraphClient({
-    apiUrl: getLangGraphBaseURL(),
+    apiUrl: getLangGraphBaseURL(isMock),
   });
   return _singleton;
 }

frontend/src/core/artifacts/hooks.ts

@@ -17,17 +17,18 @@ export function useArtifactContent({
   const isWriteFile = useMemo(() => {
     return filepath.startsWith("write-file:");
   }, [filepath]);
-  const { thread } = useThread();
+  const { thread, isMock } = useThread();
   const content = useMemo(() => {
     if (isWriteFile) {
       return loadArtifactContentFromToolCall({ url: filepath, thread });
     }
     return null;
   }, [filepath, isWriteFile, thread]);
+
   const { data, isLoading, error } = useQuery({
-    queryKey: ["artifact", filepath, threadId],
+    queryKey: ["artifact", filepath, threadId, isMock],
     queryFn: () => {
-      return loadArtifactContent({ filepath, threadId });
+      return loadArtifactContent({ filepath, threadId, isMock });
     },
     enabled,
     // Cache artifact content for 5 minutes to avoid repeated fetches (especially for .skill ZIP extraction)

frontend/src/core/artifacts/loader.ts

@@ -1,4 +1,4 @@
-import type { UseStream } from "@langchain/langgraph-sdk/react";
+import type { BaseStream } from "@langchain/langgraph-sdk/react";
 
 import type { AgentThreadState } from "../threads";
 
@@ -7,15 +7,17 @@ import { urlOfArtifact } from "./utils";
 export async function loadArtifactContent({
   filepath,
   threadId,
+  isMock,
 }: {
   filepath: string;
   threadId: string;
+  isMock?: boolean;
 }) {
   let enhancedFilepath = filepath;
   if (filepath.endsWith(".skill")) {
     enhancedFilepath = filepath + "/SKILL.md";
   }
-  const url = urlOfArtifact({ filepath: enhancedFilepath, threadId });
+  const url = urlOfArtifact({ filepath: enhancedFilepath, threadId, isMock });
   const response = await fetch(url);
   const text = await response.text();
   return text;
@@ -26,7 +28,7 @@ export function loadArtifactContentFromToolCall({
   thread,
 }: {
   url: string;
-  thread: UseStream<AgentThreadState>;
+  thread: BaseStream<AgentThreadState>;
 }) {
   const url = new URL(urlString);
   const toolCallId = url.searchParams.get("tool_call_id");

frontend/src/core/artifacts/utils.ts

@@ -5,11 +5,16 @@ export function urlOfArtifact({
   filepath,
   threadId,
   download = false,
+  isMock = false,
 }: {
   filepath: string;
   threadId: string;
   download?: boolean;
+  isMock?: boolean;
 }) {
+  if (isMock) {
+    return `${getBackendBaseURL()}/mock/api/threads/${threadId}/artifacts${filepath}${download ? "?download=true" : ""}`;
+  }
   return `${getBackendBaseURL()}/api/threads/${threadId}/artifacts${filepath}${download ? "?download=true" : ""}`;
 }
 

frontend/src/core/config/index.ts

@@ -8,9 +8,14 @@ export function getBackendBaseURL() {
   }
 }
 
-export function getLangGraphBaseURL() {
+export function getLangGraphBaseURL(isMock?: boolean) {
   if (env.NEXT_PUBLIC_LANGGRAPH_BASE_URL) {
     return env.NEXT_PUBLIC_LANGGRAPH_BASE_URL;
+  } else if (isMock) {
+    if (typeof window !== "undefined") {
+      return `${window.location.origin}/mock/api`;
+    }
+    return "http://localhost:3000/mock/api";
   } else {
     // LangGraph SDK requires a full URL, construct it from current origin
     if (typeof window !== "undefined") {

frontend/src/core/i18n/locales/en-US.ts

@@ -151,6 +151,41 @@ export const enUS: Translations = {
     chats: "Chats",
     recentChats: "Recent chats",
     demoChats: "Demo chats",
+    agents: "Agents",
+  },
+
+  // Agents
+  agents: {
+    title: "Agents",
+    description:
+      "Create and manage custom agents with specialized prompts and capabilities.",
+    newAgent: "New Agent",
+    emptyTitle: "No custom agents yet",
+    emptyDescription:
+      "Create your first custom agent with a specialized system prompt.",
+    chat: "Chat",
+    delete: "Delete",
+    deleteConfirm:
+      "Are you sure you want to delete this agent? This action cannot be undone.",
+    deleteSuccess: "Agent deleted",
+    newChat: "New chat",
+    createPageTitle: "Design your Agent",
+    createPageSubtitle:
+      "Describe the agent you want — I'll help you create it through conversation.",
+    nameStepTitle: "Name your new Agent",
+    nameStepHint:
+      "Letters, digits, and hyphens only — stored lowercase (e.g. code-reviewer)",
+    nameStepPlaceholder: "e.g. code-reviewer",
+    nameStepContinue: "Continue",
+    nameStepInvalidError:
+      "Invalid name — use only letters, digits, and hyphens",
+    nameStepAlreadyExistsError: "An agent with this name already exists",
+    nameStepCheckError: "Could not verify name availability — please try again",
+    nameStepBootstrapMessage:
+      "The new custom agent name is {name}. Let's bootstrap it's **SOUL**.",
+    agentCreated: "Agent created!",
+    startChatting: "Start chatting",
+    backToGallery: "Back to Gallery",
   },
 
   // Breadcrumb

frontend/src/core/i18n/locales/types.ts

@@ -99,6 +99,34 @@ export interface Translations {
     newChat: string;
     chats: string;
     demoChats: string;
+    agents: string;
+  };
+
+  // Agents
+  agents: {
+    title: string;
+    description: string;
+    newAgent: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    chat: string;
+    delete: string;
+    deleteConfirm: string;
+    deleteSuccess: string;
+    newChat: string;
+    createPageTitle: string;
+    createPageSubtitle: string;
+    nameStepTitle: string;
+    nameStepHint: string;
+    nameStepPlaceholder: string;
+    nameStepContinue: string;
+    nameStepInvalidError: string;
+    nameStepAlreadyExistsError: string;
+    nameStepCheckError: string;
+    nameStepBootstrapMessage: string;
+    agentCreated: string;
+    startChatting: string;
+    backToGallery: string;
   };
 
   // Breadcrumb

frontend/src/core/i18n/locales/zh-CN.ts

@@ -148,6 +148,36 @@ export const zhCN: Translations = {
     chats: "对话",
     recentChats: "最近的对话",
     demoChats: "演示对话",
+    agents: "智能体",
+  },
+
+  // Agents
+  agents: {
+    title: "智能体",
+    description: "创建和管理具有专属 Prompt 与能力的自定义智能体。",
+    newAgent: "新建智能体",
+    emptyTitle: "还没有自定义智能体",
+    emptyDescription: "创建你的第一个自定义智能体，设置专属系统提示词。",
+    chat: "对话",
+    delete: "删除",
+    deleteConfirm: "确定要删除该智能体吗？此操作不可撤销。",
+    deleteSuccess: "智能体已删除",
+    newChat: "新对话",
+    createPageTitle: "设计你的智能体",
+    createPageSubtitle: "描述你想要的智能体，我来帮你通过对话创建。",
+    nameStepTitle: "给新智能体起个名字",
+    nameStepHint:
+      "只允许字母、数字和连字符，存储时自动转为小写（例如 code-reviewer）",
+    nameStepPlaceholder: "例如 code-reviewer",
+    nameStepContinue: "继续",
+    nameStepInvalidError: "名称无效，只允许字母、数字和连字符",
+    nameStepAlreadyExistsError: "已存在同名智能体",
+    nameStepCheckError: "无法验证名称可用性，请稍后重试",
+    nameStepBootstrapMessage:
+      "新智能体的名称是 {name}，现在开始为它生成 **SOUL**。",
+    agentCreated: "智能体已创建！",
+    startChatting: "开始对话",
+    backToGallery: "返回 Gallery",
   },
 
   // Breadcrumb

frontend/src/core/settings/hooks.ts

@@ -1,5 +1,4 @@
-import { useCallback, useState } from "react";
-import { useEffect } from "react";
+import { useCallback, useLayoutEffect, useState } from "react";
 
 import {
   DEFAULT_LOCAL_SETTINGS,
@@ -17,7 +16,7 @@ export function useLocalSettings(): [
 ] {
   const [mounted, setMounted] = useState(false);
   const [state, setState] = useState<LocalSettings>(DEFAULT_LOCAL_SETTINGS);
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (!mounted) {
       setState(getLocalSettings());
     }
@@ -28,6 +27,7 @@ export function useLocalSettings(): [
       key: keyof LocalSettings,
       value: Partial<LocalSettings[keyof LocalSettings]>,
     ) => {
+      if (!mounted) return;
       setState((prev) => {
         const newState = {
           ...prev,
@@ -40,7 +40,7 @@ export function useLocalSettings(): [
         return newState;
       });
     },
-    [],
+    [mounted],
   );
   return [state, setter];
 }

frontend/src/core/threads/hooks.ts

@@ -1,42 +1,63 @@
-import type { HumanMessage } from "@langchain/core/messages";
 import type { AIMessage } from "@langchain/langgraph-sdk";
 import type { ThreadsClient } from "@langchain/langgraph-sdk/client";
 import { useStream, type UseStream } from "@langchain/langgraph-sdk/react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback } from "react";
+import { useCallback, useState } from "react";
 import { toast } from "sonner";
 
 import type { PromptInputMessage } from "@/components/ai-elements/prompt-input";
 
 import { getAPIClient } from "../api";
+import type { LocalSettings } from "../settings";
 import { useUpdateSubtask } from "../tasks/context";
 import { uploadFiles } from "../uploads";
 
-import type {
-  AgentThread,
-  AgentThreadContext,
-  AgentThreadState,
-} from "./types";
+import type { AgentThread, AgentThreadState } from "./types";
+
+export type ToolEndEvent = {
+  name: string;
+  data: unknown;
+};
+
+export type ThreadStreamOptions = {
+  threadId?: string | null | undefined;
+  context: LocalSettings["context"];
+  isMock?: boolean;
+  onStart?: (threadId: string) => void;
+  onFinish?: (state: AgentThreadState) => void;
+  onToolEnd?: (event: ToolEndEvent) => void;
+};
 
 export function useThreadStream({
   threadId,
-  isNewThread,
+  context,
+  isMock,
+  onStart,
   onFinish,
-}: {
-  isNewThread: boolean;
-  threadId: string | null | undefined;
-  onFinish?: (state: AgentThreadState) => void;
-}) {
+  onToolEnd,
+}: ThreadStreamOptions) {
+  const [_threadId, setThreadId] = useState<string | null>(threadId ?? null);
   const queryClient = useQueryClient();
   const updateSubtask = useUpdateSubtask();
   const thread = useStream<AgentThreadState>({
-    client: getAPIClient(),
+    client: getAPIClient(isMock),
     assistantId: "lead_agent",
-    threadId: isNewThread ? undefined : threadId,
+    threadId: _threadId,
     reconnectOnMount: true,
     fetchStateHistory: { limit: 1 },
+    onCreated(meta) {
+      setThreadId(meta.thread_id);
+      onStart?.(meta.thread_id);
+    },
+    onLangChainEvent(event) {
+      if (event.event === "on_tool_end") {
+        onToolEnd?.({
+          name: event.name,
+          data: event.data,
+        });
+      }
+    },
     onCustomEvent(event: unknown) {
-      console.info(event);
       if (
         typeof event === "object" &&
         event !== null &&
@@ -76,25 +97,13 @@ export function useThreadStream({
       );
     },
   });
-  return thread;
-}
 
-export function useSubmitThread({
-  threadId,
-  thread,
-  threadContext,
-  isNewThread,
-  afterSubmit,
-}: {
-  isNewThread: boolean;
-  threadId: string | null | undefined;
-  thread: UseStream<AgentThreadState>;
-  threadContext: Omit<AgentThreadContext, "thread_id">;
-  afterSubmit?: () => void;
-}) {
-  const queryClient = useQueryClient();
-  const callback = useCallback(
-    async (message: PromptInputMessage) => {
+  const sendMessage = useCallback(
+    async (
+      threadId: string,
+      message: PromptInputMessage,
+      extraContext?: Record<string, unknown>,
+    ) => {
       const text = message.text.trim();
 
       // Upload files first if any
@@ -163,10 +172,10 @@ export function useSubmitThread({
                 },
               ],
             },
-          ] as HumanMessage[],
+          ],
         },
         {
-          threadId: isNewThread ? threadId! : undefined,
+          threadId: threadId,
           streamSubgraphs: true,
           streamResumable: true,
           streamMode: ["values", "messages-tuple", "custom"],
@@ -174,17 +183,21 @@ export function useSubmitThread({
             recursion_limit: 1000,
           },
           context: {
-            ...threadContext,
+            ...extraContext,
+            ...context,
+            thinking_enabled: context.mode !== "flash",
+            is_plan_mode: context.mode === "pro" || context.mode === "ultra",
+            subagent_enabled: context.mode === "ultra",
             thread_id: threadId,
           },
         },
       );
       void queryClient.invalidateQueries({ queryKey: ["threads", "search"] });
-      afterSubmit?.();
+      // afterSubmit?.();
     },
-    [thread, isNewThread, threadId, threadContext, queryClient, afterSubmit],
+    [thread, context, queryClient],
   );
-  return callback;
+  return [thread, sendMessage] as const;
 }
 
 export function useThreads(

frontend/src/core/threads/types.ts

@@ -1,11 +1,10 @@
-import { type BaseMessage } from "@langchain/core/messages";
-import type { Thread } from "@langchain/langgraph-sdk";
+import type { Message, Thread } from "@langchain/langgraph-sdk";
 
 import type { Todo } from "../todos";
 
 export interface AgentThreadState extends Record<string, unknown> {
   title: string;
-  messages: BaseMessage[];
+  messages: Message[];
   artifacts: string[];
   todos?: Todo[];
 }
@@ -19,4 +18,5 @@ export interface AgentThreadContext extends Record<string, unknown> {
   is_plan_mode: boolean;
   subagent_enabled: boolean;
   reasoning_effort?: "minimal" | "low" | "medium" | "high";
+  agent_name?: string;
 }

frontend/src/core/threads/utils.ts

@@ -1,4 +1,4 @@
-import type { BaseMessage } from "@langchain/core/messages";
+import type { Message } from "@langchain/langgraph-sdk";
 
 import type { AgentThread } from "./types";
 
@@ -6,12 +6,15 @@ export function pathOfThread(threadId: string) {
   return `/workspace/chats/${threadId}`;
 }
 
-export function textOfMessage(message: BaseMessage) {
+export function textOfMessage(message: Message) {
   if (typeof message.content === "string") {
     return message.content;
   } else if (Array.isArray(message.content)) {
-    return message.content.find((part) => part.type === "text" && part.text)
-      ?.text as string;
+    for (const part of message.content) {
+      if (part.type === "text") {
+        return part.text;
+      }
+    }
   }
   return null;
 }