Function loadLocalAgents

sdk/src/agents/load-agents.ts:201–312

({
  agentsPath,
  verbose = false,
  validate = false,
}: {
  agentsPath?: string
  verbose?: boolean
  validate?: boolean
})

// Implementation
export async function loadLocalAgents({
  agentsPath,
  verbose = false,
  validate = false,
}: {
  agentsPath?: string
  verbose?: boolean
  validate?: boolean
}): Promise<LoadedAgents | LoadLocalAgentsResult> {
  const agents: LoadedAgents = {}

  const agentDirs = agentsPath ? [agentsPath] : getDefaultAgentDirs()
  const allAgentFiles = agentDirs.flatMap((dir) => getAllAgentFiles(dir))

  if (allAgentFiles.length === 0) {
    return validate ? { agents, validationErrors: [] } : agents
  }

  for (const fullPath of allAgentFiles) {
    try {
      const agentModule = await importAgentModule(fullPath)
      if (!agentModule) {
        continue
      }
      const agentDefinition = agentModule.default ?? agentModule

      if (!agentDefinition?.id || !agentDefinition?.model) {
        if (verbose) {
          console.error(
            `Agent definition missing required attributes (id, model): ${fullPath}`,
          )
        }
        continue
      }

      const processedAgentDefinition: LoadedAgentDefinition = {
        ...agentDefinition,
        _sourceFilePath: fullPath,
      }
      if (agentDefinition.handleSteps) {
        processedAgentDefinition.handleSteps =
          agentDefinition.handleSteps.toString()
      }

      // Resolve $env references in MCP server configs
      try {
        resolveAgentMcpEnv(processedAgentDefinition)
      } catch (error) {
        if (verbose) {
          console.error(error instanceof Error ? error.message : String(error))
        }
        continue
      }

      agents[processedAgentDefinition.id] = processedAgentDefinition
    } catch (error) {
      if (verbose) {
        console.error(