lookup_agent_info tool

jahooma · jahooma · commit d9eb2be8a0a8 · 2025-09-23T21:13:23.000-07:00
diff --git a/.agents/factory/base.ts b/.agents/factory/base.ts
@@ -38,6 +38,7 @@ export const base = (
     'run_terminal_command',
     'str_replace',
     'write_file',
+    'lookup_agent_info',
     'spawn_agents',
     'spawn_agent_inline',
     'add_subgoal',
diff --git a/.agents/types/agent-definition.ts b/.agents/types/agent-definition.ts
@@ -14,8 +14,8 @@
  *   export default definition
  */
 
-import type { Message, ToolResultOutput, JsonObjectSchema } from './util-types'
 import type * as Tools from './tools'
+import type { Message, ToolResultOutput, JsonObjectSchema } from './util-types'
 type ToolName = Tools.ToolName
 
 // ============================================================================
@@ -196,6 +196,7 @@ export interface AgentDefinition {
 
 export interface AgentState {
   agentId: string
+  runId: string
   parentId: string | undefined
 
   /** The agent's conversation history: messages from the user and the assistant. */
diff --git a/.agents/types/tools.ts b/.agents/types/tools.ts
@@ -1,5 +1,3 @@
-import type { Message } from './util-types'
-
 /**
  * Union type of all available tool names
  */
@@ -8,6 +6,7 @@ export type ToolName =
   | 'code_search'
   | 'end_turn'
   | 'find_files'
+  | 'lookup_agent_info'
   | 'read_docs'
   | 'read_files'
   | 'run_file_change_hooks'
@@ -28,6 +27,7 @@ export interface ToolParamsMap {
   code_search: CodeSearchParams
   end_turn: EndTurnParams
   find_files: FindFilesParams
+  lookup_agent_info: LookupAgentInfoParams
   read_docs: ReadDocsParams
   read_files: ReadFilesParams
   run_file_change_hooks: RunFileChangeHooksParams
@@ -59,6 +59,8 @@ export interface CodeSearchParams {
   flags?: string
   /** Optional working directory to search within, relative to the project root. Defaults to searching the entire project. */
   cwd?: string
+  /** Maximum number of results to return. Defaults to 30. */
+  maxResults?: number
 }
 
 /**
@@ -74,15 +76,23 @@ export interface FindFilesParams {
   prompt: string
 }
 
+/**
+ * Retrieve information about an agent by ID
+ */
+export interface LookupAgentInfoParams {
+  /** Agent ID (short local or full published format) */
+  agentId: string
+}
+
 /**
  * Fetch up-to-date documentation for libraries and frameworks using Context7 API.
  */
 export interface ReadDocsParams {
-  /** The exact library or framework name (e.g., "Next.js", "MongoDB", "React"). Use the official name as it appears in documentation, not a search query. */
+  /** The library or framework name (e.g., "Next.js", "MongoDB", "React"). Use the official name as it appears in documentation if possible. Only public libraries available in Context7's database are supported, so small or private libraries may not be available. */
   libraryTitle: string
-  /** Optional specific topic to focus on (e.g., "routing", "hooks", "authentication") */
-  topic?: string
-  /** Optional maximum number of tokens to return. Defaults to 10000. Values less than 10000 are automatically increased to 10000. */
+  /** Specific topic to focus on (e.g., "routing", "hooks", "authentication") */
+  topic: string
+  /** Optional maximum number of tokens to return. Defaults to 20000. Values less than 10000 are automatically increased to 10000. */
   max_tokens?: number
 }
 
@@ -120,7 +130,7 @@ export interface RunTerminalCommandParams {
  * Set the conversation history to the provided messages.
  */
 export interface SetMessagesParams {
-  messages: Message[]
+  messages: any
 }
 
 /**
@@ -129,7 +139,7 @@ export interface SetMessagesParams {
 export interface SetOutputParams {}
 
 /**
- * Spawn multiple agents and send a prompt to each of them.
+ * Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead.
  */
 export interface SpawnAgentsParams {
   agents: {
diff --git a/backend/src/tools/definitions/list.ts b/backend/src/tools/definitions/list.ts
@@ -7,6 +7,7 @@ import { codeSearchTool } from './tool/code-search'
 import { createPlanTool } from './tool/create-plan'
 import { endTurnTool } from './tool/end-turn'
 import { findFilesTool } from './tool/find-files'
+import { lookupAgentInfoTool } from './tool/lookup-agent-info'
 import { readDocsTool } from './tool/read-docs'
 import { readFilesTool } from './tool/read-files'
 import { runFileChangeHooksTool } from './tool/run-file-change-hooks'
@@ -34,6 +35,7 @@ const toolDescriptions = {
   create_plan: createPlanTool,
   end_turn: endTurnTool,
   find_files: findFilesTool,
+  lookup_agent_info: lookupAgentInfoTool,
   read_docs: readDocsTool,
   read_files: readFilesTool,
   run_file_change_hooks: runFileChangeHooksTool,
diff --git a/backend/src/tools/definitions/tool/lookup-agent-info.ts b/backend/src/tools/definitions/tool/lookup-agent-info.ts
@@ -0,0 +1,16 @@
+import { getToolCallString } from '@codebuff/common/tools/utils'
+
+import type { ToolDescription } from '../tool-def-type'
+
+const toolName = 'lookup_agent_info'
+export const lookupAgentInfoTool = {
+  toolName,
+  description: `
+Retrieve information about an agent by ID for proper spawning. Use this when you see a request with a full agent ID like "@publisher/agent-id@version" to validate the agent exists and get its metadata. Only agents that are published under a publisher and version are supported for this tool. 
+
+Example:
+${getToolCallString(toolName, {
+  agentId: 'codebuff/researcher@0.0.1',
+})}
+    `.trim(),
+} satisfies ToolDescription
diff --git a/backend/src/tools/handlers/list.ts b/backend/src/tools/handlers/list.ts
@@ -5,6 +5,7 @@ import { handleCodeSearch } from './tool/code-search'
 import { handleCreatePlan } from './tool/create-plan'
 import { handleEndTurn } from './tool/end-turn'
 import { handleFindFiles } from './tool/find-files'
+import { handleLookupAgentInfo } from './tool/lookup-agent-info'
 import { handleReadDocs } from './tool/read-docs'
 import { handleReadFiles } from './tool/read-files'
 import { handleRunFileChangeHooks } from './tool/run-file-change-hooks'
@@ -40,6 +41,7 @@ export const codebuffToolHandlers = {
   create_plan: handleCreatePlan,
   end_turn: handleEndTurn,
   find_files: handleFindFiles,
+  lookup_agent_info: handleLookupAgentInfo,
   read_docs: handleReadDocs,
   read_files: handleReadFiles,
   run_file_change_hooks: handleRunFileChangeHooks,
diff --git a/backend/src/tools/handlers/tool/lookup-agent-info.ts b/backend/src/tools/handlers/tool/lookup-agent-info.ts
@@ -0,0 +1,90 @@
+import { removeUndefinedProps } from '@codebuff/common/util/object'
+import { getAgentTemplate } from '../../../templates/agent-registry'
+
+import type { CodebuffToolHandlerFunction } from '../handler-function-type'
+import z from 'zod/v4'
+
+export const handleLookupAgentInfo: CodebuffToolHandlerFunction<
+  'lookup_agent_info'
+> = (params) => {
+  const { agentId } = params.toolCall.input
+
+  return {
+    result: (async () => {
+      const agentTemplate = await getAgentTemplate(
+        agentId,
+        params.state.localAgentTemplates || {},
+      )
+
+      if (!agentTemplate) {
+        return [
+          {
+            type: 'json',
+            value: {
+              found: false,
+              error: `Agent '${agentId}' not found`,
+            },
+          },
+        ]
+      }
+      const {
+        id,
+        displayName,
+        model,
+        includeMessageHistory,
+        inputSchema,
+        spawnerPrompt,
+        outputMode,
+        outputSchema,
+        toolNames,
+        spawnableAgents,
+      } = agentTemplate
+
+      return [
+        {
+          type: 'json',
+          value: {
+            found: true,
+            agent: {
+              ...removeUndefinedProps({
+                fullAgentId: agentId,
+                id,
+                displayName,
+                model,
+                toolNames,
+                spawnableAgents,
+                includeMessageHistory,
+                spawnerPrompt,
+                ...(inputSchema && {
+                  inputSchema: inputSchemaToJSONSchema(inputSchema),
+                }),
+                outputMode,
+                ...(outputSchema && {
+                  outputSchema: toJSONSchema(outputSchema),
+                }),
+              }),
+            },
+          },
+        },
+      ]
+    })(),
+  }
+}
+
+const toJSONSchema = (schema: z.ZodSchema) => {
+  const jsonSchema = z.toJSONSchema(schema, { io: 'input' }) as {
+    [key: string]: any
+  }
+  delete jsonSchema['$schema']
+  return jsonSchema
+}
+
+const inputSchemaToJSONSchema = (inputSchema: {
+  prompt?: z.ZodSchema
+  params?: z.ZodSchema
+}) => {
+  return removeUndefinedProps({
+    prompt: inputSchema.prompt ? toJSONSchema(inputSchema.prompt) : undefined,
+    params: inputSchema.params ? toJSONSchema(inputSchema.params) : undefined,
+  })
+}
diff --git a/common/src/templates/initial-agents-dir/types/tools.ts b/common/src/templates/initial-agents-dir/types/tools.ts
@@ -6,6 +6,7 @@ export type ToolName =
   | 'code_search'
   | 'end_turn'
   | 'find_files'
+  | 'lookup_agent_info'
   | 'read_docs'
   | 'read_files'
   | 'run_file_change_hooks'
@@ -26,6 +27,7 @@ export interface ToolParamsMap {
   code_search: CodeSearchParams
   end_turn: EndTurnParams
   find_files: FindFilesParams
+  lookup_agent_info: LookupAgentInfoParams
   read_docs: ReadDocsParams
   read_files: ReadFilesParams
   run_file_change_hooks: RunFileChangeHooksParams
@@ -74,6 +76,14 @@ export interface FindFilesParams {
   prompt: string
 }
 
+/**
+ * Retrieve information about an agent by ID
+ */
+export interface LookupAgentInfoParams {
+  /** Agent ID (short local or full published format) */
+  agentId: string
+}
+
 /**
  * Fetch up-to-date documentation for libraries and frameworks using Context7 API.
  */
diff --git a/common/src/tools/constants.ts b/common/src/tools/constants.ts
@@ -25,6 +25,7 @@ export const toolNames = [
   'create_plan',
   'end_turn',
   'find_files',
+  'lookup_agent_info',
   'read_docs',
   'read_files',
   'run_file_change_hooks',
@@ -46,6 +47,7 @@ export const publishedTools = [
   'code_search',
   'end_turn',
   'find_files',
+  'lookup_agent_info',
   'read_docs',
   'read_files',
   'run_file_change_hooks',
diff --git a/common/src/tools/list.ts b/common/src/tools/list.ts
@@ -8,6 +8,7 @@ import { codeSearchParams } from './params/tool/code-search'
 import { createPlanParams } from './params/tool/create-plan'
 import { endTurnParams } from './params/tool/end-turn'
 import { findFilesParams } from './params/tool/find-files'
+import { lookupAgentInfoParams } from './params/tool/lookup-agent-info'
 import { readDocsParams } from './params/tool/read-docs'
 import { readFilesParams } from './params/tool/read-files'
 import { runFileChangeHooksParams } from './params/tool/run-file-change-hooks'
@@ -43,6 +44,7 @@ export const $toolParams = {
   create_plan: createPlanParams,
   end_turn: endTurnParams,
   find_files: findFilesParams,
+  lookup_agent_info: lookupAgentInfoParams,
   read_docs: readDocsParams,
   read_files: readFilesParams,
   run_file_change_hooks: runFileChangeHooksParams,
diff --git a/common/src/tools/params/tool/lookup-agent-info.ts b/common/src/tools/params/tool/lookup-agent-info.ts
@@ -0,0 +1,22 @@
+import z from 'zod/v4'
+
+import { jsonValueSchema } from '../../../types/json'
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'lookup_agent_info'
+const endsAgentStep = false
+export const lookupAgentInfoParams = {
+  toolName,
+  endsAgentStep,
+  parameters: z
+    .object({
+      agentId: z.string().describe('Agent ID (short local or full published format)'),
+    })
+    .describe('Retrieve information about an agent by ID'),
+  outputs: z.tuple([
+    z.object({
+      type: z.literal('json'),
+      value: jsonValueSchema,
+    }),
+  ]),
+} satisfies $ToolParams
diff --git a/common/src/util/object.ts b/common/src/util/object.ts
@@ -1,6 +1,8 @@
 import { isEqual, mapValues, union } from 'lodash'
 
-export const removeUndefinedProps = <T extends object>(obj: T): T => {
+export const removeUndefinedProps = <T extends object>(
+  obj: T
+): { [K in keyof T as T[K] extends undefined ? never : K]: Exclude<T[K], undefined> } => {
   const newObj: any = {}
 
   for (const key of Object.keys(obj)) {
diff --git a/npm-app/src/utils/tool-renderers.ts b/npm-app/src/utils/tool-renderers.ts
@@ -344,4 +344,7 @@ export const toolRenderers: Record<ToolName, ToolCallRenderer> = {
       return null
     },
   },
+  lookup_agent_info: {
+    ...defaultToolCallRenderer,
+  },
 }
