@salesforce/agents/lib/agents/agentBase.d.ts

Client side APIs for working with Salesforce agents

import { Connection } from '@salesforce/core';
import { AgentPreviewInterface, type AgentPreviewSendResponse, type PlannerResponse, PreviewMetadata } from '../types';
import { SessionHistoryBuffer, TranscriptEntry } from '../utils';
/**
 * Abstract base class for agent preview functionality.
 * Contains shared properties and methods between ScriptAgent and ProductionAgent.
 */
export declare abstract class AgentBase {
    /**
     * The display name of the agent (user-friendly name, not API name)
     */
    name: string | undefined;
    /**
     * The Connection passed in by the caller. Used as the lookup key into the ConnectionManager
     * cache (see managerFor()) — never used directly for SFAP or org API calls. Subclasses go
     * through getJwtConnection() / getStandardConnection() so that JWT and standard connections
     * remain isolated.
     */
    protected readonly connection: Connection;
    protected sessionId: string | undefined;
    protected historyDir: string | undefined;
    protected historyBuffer: SessionHistoryBuffer | undefined;
    protected turnCounter: number;
    protected apexDebugging: boolean | undefined;
    protected planIds: Set<string>;
    abstract preview: AgentPreviewInterface;
    protected constructor(connection: Connection);
    /**
     * Refreshes the access token on the standard connection.
     *
     * Retained for backward compatibility. The caller's original Connection is never mutated
     * by agent operations, so this only refreshes the internal standard connection owned by
     * the ConnectionManager.
     */
    restoreConnection(): Promise<void>;
    setSessionId(sessionId: string): void;
    getHistoryDir(): Promise<string>;
    /**
     * Resume an existing session by loading session state from disk
     *
     * @param sessionId The session ID to resume
     */
    resumeSession(sessionId: string): Promise<void>;
    /**
     * Returns the connection to use for SFAP API calls (api.salesforce.com/einstein/ai-agent).
     * Always the JWT-upgraded connection from the ConnectionManager — never the caller's
     * original Connection.
     */
    protected getJwtConnection(): Promise<Connection>;
    /**
     * Returns the standard org connection for SOQL queries, tooling API, and metadata
     * operations. Always the manager's isolated standard connection — never the caller's
     * original Connection — to keep JWT and org auth fully separate.
     */
    protected getStandardConnection(): Promise<Connection>;
    /**
     * Get all traces from the current session
     * Reads traces from the session directory if available, otherwise fetches from API
     */
    protected getAllTracesFromDisc(): Promise<PlannerResponse[]>;
    /**
     * Save the complete session data to disk by copying the session directory.
     * The session directory is already populated during the session with:
     * - Transcript entries (transcript.jsonl)
     * - Traces (traces/*.json)
     * - Session metadata (metadata.json)
     *
     * Session directory structure:
     * .sfdx/agents/<agentId>/sessions/<sessionId>/
     * ├── transcript.jsonl    # All transcript entries (one per line)
     * ├── traces/             # Individual trace files
     * │   ├── <planId1>.json
     * │   └── <planId2>.json
     * └── metadata.json       # Session metadata (start time, end time, planIds, etc.)
     *
     * @param outputDir Optional output directory. If not provided, uses default location.
     * @returns The path to the copied session directory
     */
    protected saveSessionTo(outputDir: string): Promise<string>;
    /**
     * Set the Apex debugging mode for the agent preview.
     * This can be called before starting a session.
     *
     * @param apexDebugging true to enable Apex debugging, false to disable
     */
    protected setApexDebugging(apexDebugging: boolean): void;
    /**
     * Send a message to the agent using the session ID obtained by calling `start()`.
     *
     * @param message A message to send to the agent.
     * @returns `AgentPreviewSendResponse`
     */
    protected abstract sendMessage(message: string): Promise<AgentPreviewSendResponse>;
    /**
     * Get the agent ID to use for storage/transcript purposes
     */
    protected abstract getAgentIdForStorage(): string | Promise<string>;
    /**
     * Check if Apex debugging should be enabled for this agent type
     */
    protected abstract canApexDebug(): boolean;
    /**
     * Handle Apex debugging setup before sending a message
     */
    protected abstract handleApexDebuggingSetup(): Promise<void>;
    protected abstract getTrace(planId: string): Promise<PlannerResponse | undefined>;
    protected abstract getHistoryFromDisc(): Promise<{
        metadata: PreviewMetadata | null;
        transcript: TranscriptEntry[];
        traces: PlannerResponse[];
    }>;
}