@builder.io/dev-tools/types/cli/utils/agent-parser.d.ts

Builder.io Visual CMS Devtools

/**
 * Agent definition parsing utilities
 * Handles parsing of custom agent definition files
 */
import type { QueueBehavior, QueueMode, ReasoningEffort, CodeGenPosition } from "#ai-utils";
export interface SubAgent {
    name: string;
    description?: string;
    systemPrompt?: string | string[];
    tools?: string[];
    model?: string;
    position?: CodeGenPosition;
    filePath?: string;
    includeMemories?: boolean;
    needDevServer?: boolean;
    needValidation?: boolean;
    resetAfterRun?: boolean;
    mcpServers?: boolean;
    /** Expressive queue behavior; preferred over the legacy `queueMode`. */
    queueBehavior?: QueueBehavior;
    /** @deprecated Use {@link SubAgent.queueBehavior} instead. */
    queueMode?: QueueMode;
    /** Maximum wall time (in milliseconds) before the agent watchdog aborts. */
    maxTimeoutMs?: number;
    /** Max LLM completion turns when spawned via the Agent tool (dev-tools). */
    maxCompletions?: number;
    /** Default reasoning effort level for this agent type. Overrides the session default. */
    reasoning?: ReasoningEffort;
    /**
     * Where this agent was discovered. Drives precedence on name collision:
     * `project` > `user` > `plugin`. Set by the discovery loader, not by the
     * parsed file itself.
     */
    scope?: "project" | "user" | "plugin";
    /**
     * Name of the plugin that contributed this agent, if any. Set by the
     * plugin loader (Phase 2); always `undefined` for project-level and
     * user-level standalone files (Phase 1).
     */
    pluginName?: string;
}
/**
 * Parses an agent definition file (Markdown with YAML frontmatter)
 * Expected format (following Claude Code sub-agents format):
 * ```yaml
 * ---
 * name: Agent Name
 * description: Description of what the agent does
 * model: sonnet  # Optional: supports shortcuts like sonnet, opus, haiku, mini
 * tools:         # Optional: list of tools to enable
 *   - Read
 *   - Grep
 *   - WebSearch
 * mode: quality-v4  # Optional: agent mode
 * maxCompletions: 120    # Optional: max Agent-tool spawn turns
 * ---
 * System prompt content here (Markdown)
 * ```
 * @param fileContent - The raw file content
 * @param filePath - The file path (used for fallback name)
 * @returns Parsed SubAgent or null if parsing fails
 */
export declare function parseAgentFile(fileContent: string, filePath: string): SubAgent | null;