@gpt-platform/client 0.10.4 → 0.11.0

package/dist/namespaces/agents.d.ts

@@ -0,0 +1,1406 @@
+import type { Agent, AgentDeployment, AgentStats, AgentTestResult, AgentUsage, AgentVersion, AgentVersionComparison, AgentVersionRevision, FieldTemplate, TrainingExample, TrainingSession, WorkspaceAgentConfig } from "../_internal/types.gen";
+export type { AgentStats, AgentUsage, AgentVersionRevision, AgentVersionComparison, FieldTemplate, };
+/** Agent statistics response — re-exported from generated types. */
+export type AgentStatsResponse = AgentStats;
+/** Agent usage statistics response — re-exported from generated types. */
+export type AgentUsageResponse = AgentUsage;
+/** Agent prediction response. */
+export interface PredictionResponse {
+    [key: string]: unknown;
+}
+/** @public Input for the teach (training correction) operation on an agent. */
+export interface TeachParams {
+    data: {
+        attributes?: {
+            /** Field names to mark as confirmed (correct). */
+            confirmed_fields?: Array<string>;
+            /** Per-field human-readable reasons for corrections. */
+            correction_reasons?: Record<string, unknown>;
+            /** Map of field names to corrected values. */
+            corrections: Record<string, unknown>;
+            /** The document ID used as the training source. */
+            document_id: string;
+            /** Optional free-text note for training context. */
+            training_note?: string;
+            /** Implicitly verify untouched fields. */
+            verify_remaining?: boolean;
+        };
+        type?: "agent";
+    };
+}
+/** Agent training statistics response. */
+export interface TrainingStatsResponse {
+    [key: string]: unknown;
+}
+/** Agent test result response — re-exported from generated types. */
+export type AgentTestResultResponse = AgentTestResult;
+/** Agent version metrics response. */
+export interface VersionMetricsResponse {
+    [key: string]: unknown;
+}
+/** Agent version revision record — re-exported from generated types. */
+export type VersionRevision = AgentVersionRevision;
+/** Agent version comparison result — re-exported from generated types. */
+export type VersionComparisonResponse = AgentVersionComparison;
+/** Execution cost estimate response. */
+export interface ExecutionEstimateResponse {
+    [key: string]: unknown;
+}
+/** Execution tree response. */
+export interface ExecutionTreeResponse {
+    [key: string]: unknown;
+}
+/** Bulk delete response. */
+export interface BulkDeleteResponse {
+    deleted_count?: number;
+    [key: string]: unknown;
+}
+/** Attributes accepted when updating an agent (PATCH semantics). */
+export type UpdateAgentAttributes = {
+    name?: string;
+    description?: string;
+    instructions?: string;
+    tags?: string[];
+    execution_mode?: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating a new agent. */
+export type CreateAgentAttributes = {
+    description?: string;
+    instructions?: string;
+    vertical?: string;
+    tags?: string[];
+    execution_mode?: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating an agent version. */
+export type CreateAgentVersionAttributes = {
+    agent_id: string;
+    prompt_template?: unknown;
+    version_number?: number;
+    changes_summary?: string;
+    output_schema?: Record<string, unknown>;
+    input_schema?: Record<string, unknown>;
+    output_strict?: boolean;
+    input_strict?: boolean;
+    is_draft?: boolean;
+    [key: string]: unknown;
+};
+/** Attributes accepted when updating an agent version (PATCH semantics). */
+export type UpdateAgentVersionAttributes = {
+    output_schema?: Record<string, unknown>;
+    input_schema?: Record<string, unknown>;
+    output_strict?: boolean;
+    input_strict?: boolean;
+    prompt_template?: unknown;
+    changes_summary?: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating a test result. */
+export type CreateTestResultAttributes = {
+    agent_id: string;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating a training example via agents namespace. */
+export type CreateAgentTrainingExampleAttributes = {
+    agent_id?: string;
+    input_text: string;
+    output_json: Record<string, unknown>;
+    field_name?: string;
+    original_value?: string;
+    corrected_value?: string;
+    document_type?: string;
+    confidence_score?: number;
+    training_note?: string;
+    correction_reasons?: Record<string, string>;
+    is_confirmed?: boolean;
+    [key: string]: unknown;
+};
+/** Attributes accepted when updating a training example via agents namespace. */
+export type UpdateAgentTrainingExampleAttributes = {
+    input_text?: string;
+    output_json?: Record<string, unknown>;
+    field_name?: string;
+    original_value?: string;
+    corrected_value?: string;
+    training_note?: string;
+    correction_reasons?: Record<string, string>;
+    is_confirmed?: boolean;
+    [key: string]: unknown;
+};
+/** Attributes accepted when creating a field template. */
+export type CreateFieldTemplateAttributes = {
+    name: string;
+    [key: string]: unknown;
+};
+import type { RequestOptions } from "../base-client";
+import { RequestBuilder } from "../request-builder";
+import type { StreamOptions } from "../streaming";
+import type { ExecutionEvent } from "../execution-events";
+/**
+ * Execution record returned by the agent execution API.
+ */
+export interface Execution {
+    id: string;
+    agent_id: string;
+    workspace_id: string;
+    status: "pending" | "running" | "completed" | "failed" | "cancelled" | "awaiting_approval";
+    input: Record<string, unknown>;
+    result: Record<string, unknown> | null;
+    triggered_by_user_id: string | null;
+    total_tokens: number | null;
+    total_credits_charged: string | null;
+    model_used: string | null;
+    requested_model_id: string | null;
+    execution_mode: string | null;
+    error: Record<string, unknown> | null;
+    started_at: string | null;
+    completed_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Creates the `agents` namespace, providing methods for managing AI agents,
+ * their immutable versions, and inline training examples.
+ *
+ * Agents are the core building block of the platform. Each agent has a name,
+ * a prompt template, and an optional structured output schema. Agents can be
+ * versioned (published as immutable snapshots), tested against sample input,
+ * trained with input/output examples, and cloned to create new variants.
+ *
+ * @param rb - The `RequestBuilder` instance bound to the authenticated client.
+ * @returns An object containing all agent-related methods and sub-namespaces.
+ *
+ * @example
+ * const client = new GptClient({ apiKey: 'sk_app_...' });
+ * const agent = await client.agents.create('Triage Bot', 'You are a support triage assistant.');
+ * console.log(agent.id);
+ */
+export declare function createAgentsNamespace(rb: RequestBuilder): {
+    /**
+     * Lists agents in the workspace, with optional pagination controls.
+     *
+     * Returns a single page of agents. Use {@link listAll} to fetch every agent
+     * across all pages automatically.
+     *
+     * @param options - Optional pagination and request options.
+     * @param options.page - The page number to fetch (1-based). Defaults to 1.
+     * @param options.pageSize - Number of agents per page. Defaults to the server default.
+     * @returns A promise that resolves to an array of `Agent` objects on the requested page.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     *
+     * // First page with default page size
+     * const page1 = await client.agents.list();
+     *
+     * // Second page, 10 agents per page
+     * const page2 = await client.agents.list({ page: 2, pageSize: 10 });
+     */
+    list: (options?: {
+        page?: number;
+        pageSize?: number;
+    } & RequestOptions) => Promise<Agent[]>;
+    /**
+     * Fetches all agents in the workspace by transparently paginating through
+     * every page until exhausted.
+     *
+     * This is a convenience wrapper around {@link list} that handles cursor/page
+     * management automatically. For workspaces with a very large number of agents,
+     * prefer {@link list} with explicit pagination to control memory usage.
+     *
+     * @param options - Optional request options (e.g. custom headers, abort signal).
+     * @returns A promise that resolves to a flat array of every `Agent` in the workspace.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const allAgents = await client.agents.listAll();
+     * console.log(`Total agents: ${allAgents.length}`);
+     */
+    listAll: (options?: RequestOptions) => Promise<Agent[]>;
+    /**
+     * Permanently deletes an agent by its ID.
+     *
+     * This action is irreversible. All associated training examples, versions,
+     * and execution history will also be removed. If you only want to hide the
+     * agent from active use, consider archiving it instead.
+     *
+     * @param id - The UUID of the agent to delete.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to `true` on successful deletion.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * await client.agents.delete('agt_01HXYZ...');
+     */
+    delete: (id: string, options?: RequestOptions) => Promise<true>;
+    /**
+     * Fetches a single agent by its ID.
+     *
+     * @param id - The UUID of the agent to retrieve.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the full `Agent` object.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const agent = await client.agents.get('agt_01HXYZ...');
+     * console.log(agent.attributes.name);
+     */
+    get: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Look up an agent by its system_slug. Use this for ISV-provisioned agents
+     * where the slug is a stable identifier that survives database resets.
+     *
+     * @param slug - The system_slug of the agent (e.g., "chartless-session-prep-briefing").
+     * @param options - Optional request options.
+     * @returns The Agent record.
+     *
+     * @example
+     * ```ts
+     * const agent = await client.agents.getBySlug("chartless-session-prep-briefing");
+     * ```
+     */
+    getBySlug: (slug: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Creates a new agent with a blank initial version (v1).
+     *
+     * The agent is created with default settings. To set the prompt template,
+     * create or update a schema version after creation:
+     *
+     * ```typescript
+     * const agent = await client.agents.create('Invoice Parser');
+     * await client.agents.updateSchemaVersion(agent.id, versionId, {
+     *   prompt_template: 'You are an expert invoice parser...',
+     * });
+     * ```
+     *
+     * @param name - The display name for the agent.
+     * @param attributes - Optional agent attributes (description, instructions, tags, etc.).
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the created `Agent` object with its auto-generated v1.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     *
+     * const agent = await client.agents.create('Invoice Parser', {
+     *   description: 'Extracts structured data from invoices',
+     *   instructions: 'Focus on line items and totals',
+     * });
+     * console.log(`Created agent: ${agent.id}`);
+     */
+    create: (name: string, attributes?: CreateAgentAttributes, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Updates one or more attributes of an existing agent.
+     *
+     * Only the fields present in `attributes` are changed; all other fields
+     * remain unchanged (PATCH semantics).
+     *
+     * @param id - The UUID of the agent to update.
+     * @param attributes - A partial map of agent attributes to update
+     *   (e.g. `{ name: 'New Name', description: 'Updated description' }`).
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the updated `Agent` object.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     *
+     * const updated = await client.agents.update('agt_01HXYZ...', {
+     *   name: 'Invoice Parser v2',
+     *   temperature: 0.1,
+     * });
+     * console.log(updated.attributes.name); // 'Invoice Parser v2'
+     */
+    update: (id: string, attributes: UpdateAgentAttributes, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Runs the agent against a sample input to verify end-to-end behavior.
+     *
+     * This triggers a live LLM call using the agent's current prompt template and
+     * configuration. The result is returned without persisting any output. Useful
+     * for smoke-testing an agent before publishing a version or deploying it to
+     * production traffic.
+     *
+     * @param id - The UUID of the agent to test.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object annotated with test output.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const result = await client.agents.test('agt_01HXYZ...');
+     * console.log(result.attributes.last_test_output);
+     */
+    test: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Validates sample output against the agent's declared output schema.
+     *
+     * Runs schema validation logic on the agent's current output definition to
+     * confirm that structured fields are consistent, required fields are present,
+     * and type constraints are satisfied. Does not trigger an LLM call.
+     *
+     * @param id - The UUID of the agent to validate.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object annotated with validation results.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const result = await client.agents.validate('agt_01HXYZ...');
+     * console.log(result.attributes.validation_errors); // [] means valid
+     */
+    validate: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Creates a copy of the agent under a new identity.
+     *
+     * The cloned agent receives a new ID and a name derived from the original
+     * (e.g. `"Invoice Parser (copy)"`). All prompt template content, schema
+     * fields, and configuration are duplicated. Training examples and version
+     * history are NOT copied.
+     *
+     * @param id - The UUID of the agent to clone.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the newly created clone `Agent` object.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const clone = await client.agents.clone('agt_01HXYZ...');
+     * console.log(`New agent ID: ${clone.id}`); // different from original
+     */
+    clone: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Exports the agent's full configuration and training examples as a
+     * portable bundle.
+     *
+     * The export payload includes the agent's prompt template, schema definition,
+     * all training examples, and published version metadata. The format is
+     * suitable for importing into another workspace or backing up the agent.
+     *
+     * @param id - The UUID of the agent to export.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object containing the export payload.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const bundle = await client.agents.export('agt_01HXYZ...');
+     * console.log(bundle.attributes.export_data); // JSON-serializable bundle
+     */
+    export: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Runs AI-powered analysis over the agent's training examples to detect
+     * conflicts, coverage gaps, and quality issues.
+     *
+     * The analysis inspects all training examples associated with the agent and
+     * uses an LLM to identify: duplicate or near-duplicate examples, contradictory
+     * input/output pairs, missing coverage for common scenarios, and low-quality
+     * examples that may harm model performance. Results are returned as structured
+     * findings attached to the agent.
+     *
+     * @param id - The UUID of the agent to analyze.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object annotated with analysis findings.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const analysis = await client.agents.analyzeTraining('agt_01HXYZ...');
+     * const findings = analysis.attributes.training_analysis;
+     * console.log(`Conflicts found: ${findings.conflicts.length}`);
+     * console.log(`Coverage gaps: ${findings.gaps.length}`);
+     */
+    analyzeTraining: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Triggers a fine-tuning or in-context learning run for the agent.
+     *
+     * Initiates a teach job that ingests the agent's current training examples and
+     * incorporates them into the agent's behavior — either by running a supervised
+     * fine-tuning job (for supported model backends) or by compiling examples into
+     * an optimized few-shot prompt block. The returned agent reflects the updated
+     * training state once the job completes.
+     *
+     * @param id - The UUID of the agent to teach.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object with updated training metadata.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const taught = await client.agents.teach('agt_01HXYZ...');
+     * console.log(taught.attributes.last_trained_at); // ISO timestamp
+     */
+    teach: (id: string, params?: TeachParams, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Snapshots the agent's current state as a new immutable version.
+     *
+     * Published versions are permanent, append-only records of an agent at a
+     * specific point in time. They capture the prompt template, schema fields,
+     * model configuration, and training state. Once published, a version cannot
+     * be modified — only the live (draft) agent continues to change. Versions are
+     * used for rollback, A/B comparison, and production promotion workflows.
+     *
+     * @param id - The UUID of the agent to publish a version for.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object with updated version metadata.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     *
+     * // After making edits, lock the current state as a version
+     * const agent = await client.agents.publishVersion('agt_01HXYZ...');
+     * console.log(`Latest version: ${agent.attributes.current_version}`);
+     */
+    publishVersion: (id: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Restores the agent's live (draft) state to match a previously published version.
+     *
+     * Copies the prompt template, schema fields, and model configuration from the
+     * target version back onto the live agent. Existing training examples are not
+     * affected. After restoring, you can make further edits before publishing a
+     * new version.
+     *
+     * @param id - The UUID of the agent (or version) to restore from.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to the `Agent` object after restoration.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     *
+     * // Roll back to the previous known-good state
+     * const agent = await client.agents.restoreVersion('agt_01HXYZ...');
+     * console.log('Agent restored to previous version');
+     */
+    restoreVersion: (id: string, body?: {
+        version_id?: string;
+    }, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Retrieves usage statistics and performance metrics for an agent.
+     *
+     * Returns aggregated data such as total execution count, average latency,
+     * token consumption, error rates, and training example counts. Useful for
+     * monitoring agent health and understanding cost attribution.
+     *
+     * @param id - The UUID of the agent to retrieve stats for.
+     * @param options - Optional request options.
+     * @returns A promise that resolves to a map of metric names to their values.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const stats = await client.agents.stats('agt_01HXYZ...');
+     * console.log(`Total executions: ${stats.execution_count}`);
+     * console.log(`Avg latency (ms): ${stats.avg_latency_ms}`);
+     */
+    stats: (id: string, options?: RequestOptions) => Promise<AgentStatsResponse>;
+    /**
+     * Imports an agent from a portable export bundle.
+     *
+     * Accepts the JSON bundle produced by {@link export} and creates a new
+     * agent in the current workspace with all configuration, schema fields,
+     * and training examples from the bundle.
+     *
+     * @param data - The export bundle object.
+     * @param options - Optional request options.
+     * @returns The newly created Agent from the import.
+     *
+     * @example
+     * const imported = await client.agents.import(exportBundle);
+     */
+    import: (data: Record<string, unknown>, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Retrieves usage information for a single agent.
+     *
+     * Returns metrics about how the agent is being used, including
+     * execution counts, sharing status, and ownership details.
+     *
+     * @param id - The UUID of the agent.
+     * @param options - Optional request options.
+     * @returns Usage data for the agent.
+     *
+     * @example
+     * const usage = await client.agents.usage('agt_01HXYZ...');
+     */
+    usage: (id: string, options?: RequestOptions) => Promise<AgentUsageResponse>;
+    /**
+     * Retrieves usage information for all agents in the workspace.
+     *
+     * @param options - Optional request options.
+     * @returns Array of usage data for all agents.
+     *
+     * @example
+     * const allUsage = await client.agents.usageAll();
+     */
+    usageAll: (options?: RequestOptions) => Promise<AgentUsageResponse[]>;
+    /**
+     * Returns the existing draft version for this agent, or creates one.
+     *
+     * If a draft already exists, it is returned unchanged. If no draft exists
+     * and an active version is present, creates a draft by cloning the active
+     * version. If neither exists, creates an empty draft at v1.
+     *
+     * @param id - The UUID of the agent.
+     * @param options - Optional request options.
+     * @returns The draft AgentVersion.
+     *
+     * @example
+     * const draft = await client.agents.getOrCreateDraft('agt_01HXYZ...');
+     */
+    getOrCreateDraft: (id: string, options?: RequestOptions) => Promise<AgentVersion>;
+    /**
+     * Promotes the draft version to active, deactivating the previous active version.
+     *
+     * @param id - The UUID of the agent.
+     * @param options - Optional request options.
+     * @returns The newly activated AgentVersion.
+     *
+     * @example
+     * const published = await client.agents.publishDraft('agt_01HXYZ...');
+     */
+    publishDraft: (id: string, options?: RequestOptions) => Promise<AgentVersion>;
+    /**
+     * Clones an agent into a different workspace.
+     *
+     * @param agentId - The UUID of the agent to clone.
+     * @param targetWorkspaceId - The UUID of the destination workspace.
+     * @param options - Optional request options.
+     * @returns The cloned Agent in the target workspace.
+     *
+     * @example
+     * const cloned = await client.agents.cloneForWorkspace('agt_01...', 'ws_02...');
+     */
+    cloneForWorkspace: (agentId: string, targetWorkspaceId: string, options?: RequestOptions) => Promise<Agent>;
+    /**
+     * Retrieves training statistics for a single agent.
+     *
+     * @param id - The UUID of the agent.
+     * @param options - Optional request options.
+     * @returns Training statistics data.
+     *
+     * @example
+     * const stats = await client.agents.trainingStats('agt_01...');
+     */
+    trainingStats: (id: string, options?: RequestOptions) => Promise<TrainingStatsResponse>;
+    /**
+     * Records a test result for an agent.
+     *
+     * @param attributes - Test result attributes (agent_id, input, expected_output, actual_output, passed, etc.).
+     * @param options - Optional request options.
+     * @returns The created test result record.
+     *
+     * @example
+     * const result = await client.agents.createTestResult({
+     *   agent_id: 'agt_01...',
+     *   input: { text: 'test input' },
+     *   expected_output: { amount: 100 },
+     *   actual_output: { amount: 100 },
+     *   passed: true,
+     * });
+     */
+    createTestResult: (attributes: CreateTestResultAttributes, options?: RequestOptions) => Promise<AgentTestResultResponse>;
+    /**
+     * Sub-namespace for managing immutable agent versions.
+     *
+     * Agent versions are permanent snapshots of an agent's configuration at a
+     * specific point in time. They cannot be edited after creation. Use
+     * `agents.publishVersion(id)` to create a new version from the live agent
+     * state, and use these methods to inspect, compare, or delete past versions.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * const versions = await client.agents.versions.listAll();
+     * console.log(`Published versions: ${versions.length}`);
+     */
+    versions: {
+        /**
+         * Lists published agent versions with optional pagination controls.
+         *
+         * Returns a single page of versions. Use {@link listAll} to fetch every
+         * version across all pages automatically.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The page number to fetch (1-based).
+         * @param options.pageSize - Number of versions per page.
+         * @returns A promise that resolves to an array of `AgentVersion` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const versions = await client.agents.versions.list({ page: 1, pageSize: 20 });
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<AgentVersion[]>;
+        /**
+         * Fetches all published agent versions by transparently paginating through
+         * every page until exhausted.
+         *
+         * @param options - Optional request options.
+         * @returns A promise that resolves to a flat array of all `AgentVersion` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const allVersions = await client.agents.versions.listAll();
+         * const latest = allVersions.at(-1);
+         */
+        listAll: (options?: RequestOptions) => Promise<AgentVersion[]>;
+        /**
+         * Fetches a single published agent version by its ID.
+         *
+         * @param id - The UUID of the agent version to retrieve.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the full `AgentVersion` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const version = await client.agents.versions.get('ver_01HXYZ...');
+         * console.log(version.attributes.schema_snapshot);
+         */
+        get: (id: string, options?: RequestOptions) => Promise<AgentVersion>;
+        /**
+         * Permanently deletes a published agent version by its ID.
+         *
+         * Deleting a version does not affect the live agent. However, any
+         * production deployments pinned to this version will lose their reference.
+         * Ensure no active deployments depend on the version before deleting it.
+         *
+         * @param id - The UUID of the agent version to delete.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to `true` on successful deletion.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.agents.versions.delete('ver_01HXYZ...');
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Creates a new agent version directly from a set of attributes.
+         *
+         * In most cases you should use `agents.publishVersion(agentId)` to snapshot
+         * the live agent state. This lower-level method is provided for advanced
+         * workflows where version attributes must be specified explicitly (e.g.
+         * when importing a version from another workspace).
+         *
+         * @param attributes - The version attributes to set (e.g. schema snapshot, prompt).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the newly created `AgentVersion` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const version = await client.agents.versions.create({
+         *   agent_id: 'agt_01HXYZ...',
+         *   prompt_template: 'You are a helpful assistant.',
+         * });
+         */
+        create: (attributes: CreateAgentVersionAttributes, options?: RequestOptions) => Promise<AgentVersion>;
+        /**
+         * Adds a predefined platform system field to this version's output schema.
+         *
+         * System fields are underscore-prefixed metadata fields automatically
+         * populated during document processing (e.g. `_filename`, `_pages`,
+         * `_char_count`). Adding a system field makes it visible in exports and
+         * API responses for documents processed by this version.
+         *
+         * @param id - The UUID of the agent version to modify.
+         * @param fieldName - The name of the system field to add (e.g. `_filename`, `_pages`).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the updated `AgentVersion` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const version = await client.agents.versions.addSystemField('ver_01HXYZ...', '_filename');
+         * console.log(version.attributes.system_fields); // includes newly added field
+         */
+        addSystemField: (id: string, fieldName: string, options?: RequestOptions) => Promise<AgentVersion>;
+        /**
+         * Removes a system field from this version's output schema.
+         *
+         * After removal, the field will no longer appear in exports or API responses
+         * for documents processed by this version. Only system fields (underscore-
+         * prefixed) can be removed via this method; user-defined fields are managed
+         * through the agent update endpoint.
+         *
+         * @param id - The UUID of the agent version to modify.
+         * @param fieldName - The name of the system field to remove (e.g. `_filename`, `_pages`).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the updated `AgentVersion` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const version = await client.agents.versions.removeSystemField('ver_01HXYZ...', '_filename');
+         */
+        removeSystemField: (id: string, fieldName: string, options?: RequestOptions) => Promise<AgentVersion>;
+        /**
+         * Replaces the entire set of system fields on this version's schema in a
+         * single atomic batch operation.
+         *
+         * This is more efficient than calling `addSystemField` and `removeSystemField`
+         * repeatedly when reconfiguring which system metadata fields should appear in
+         * the output schema. All previously configured system fields not present in
+         * the new set will be removed.
+         *
+         * @param id - The UUID of the agent version to update.
+         * @param fieldNames - The complete list of system field names to set (e.g. `['_filename', '_pages']`).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the updated `AgentVersion` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * // Replace all system fields in one call
+         * const version = await client.agents.versions.setSystemFields('ver_01HXYZ...', ['_filename', '_pages']);
+         * console.log(version.attributes.system_fields);
+         */
+        setSystemFields: (id: string, fieldNames: string[], options?: RequestOptions) => Promise<AgentVersion>;
+        /**
+         * Retrieves performance metrics for an agent version.
+         *
+         * @param id - The UUID of the agent version.
+         * @param options - Optional request options.
+         * @returns Metrics data for the version.
+         *
+         * @example
+         * const metrics = await client.agents.versions.metrics('ver_01HXYZ...');
+         */
+        metrics: (id: string, options?: RequestOptions) => Promise<VersionMetricsResponse>;
+        /**
+         * Lists revision history for an agent version.
+         *
+         * Each revision represents a content change (prompt tweak, description
+         * update) within the same schema version.
+         *
+         * @param id - The UUID of the agent version.
+         * @param options - Optional request options.
+         * @returns Array of revision records.
+         *
+         * @example
+         * const revisions = await client.agents.versions.revisions('ver_01HXYZ...');
+         */
+        revisions: (id: string, options?: RequestOptions) => Promise<VersionRevision[]>;
+        /**
+         * Fetches a single revision by ID.
+         *
+         * @param id - The UUID of the revision.
+         * @param options - Optional request options.
+         * @returns The revision record.
+         *
+         * @example
+         * const revision = await client.agents.versions.getRevision('rev_01...');
+         */
+        getRevision: (id: string, options?: RequestOptions) => Promise<VersionRevision>;
+        /**
+         * Lists all revisions across all agent versions.
+         *
+         * @param options - Optional request options.
+         * @returns Array of all revision records.
+         *
+         * @example
+         * const allRevisions = await client.agents.versions.listAllRevisions();
+         */
+        listAllRevisions: (options?: RequestOptions) => Promise<VersionRevision[]>;
+        /**
+         * Compares two agent versions side-by-side.
+         *
+         * Returns a structured diff of schema fields, prompt templates, and
+         * configuration between version A and version B.
+         *
+         * @param versionAId - UUID of the first version.
+         * @param versionBId - UUID of the second version.
+         * @param options - Optional request options.
+         * @returns Comparison result with schema_diff and prompt_diff.
+         *
+         * @example
+         * const diff = await client.agents.versions.compare('ver_A...', 'ver_B...');
+         */
+        compare: (versionAId: string, versionBId: string, options?: RequestOptions) => Promise<VersionComparisonResponse>;
+        /**
+         * Sub-namespace for managing schema versions within an agent.
+         *
+         * Schema versions track structural changes (new fields, type changes)
+         * independently from content revisions (prompt tweaks).
+         */
+        schemaVersions: {
+            /**
+             * Lists all schema versions for an agent.
+             *
+             * @param agentId - The UUID of the agent.
+             * @param options - Optional request options.
+             * @returns Array of schema version records.
+             *
+             * @example
+             * const versions = await client.agents.versions.schemaVersions.list('agt_01...');
+             */
+            list: (agentId: string, options?: RequestOptions) => Promise<AgentVersion[]>;
+            /**
+             * Creates a new schema version for an agent.
+             *
+             * @param agentId - The UUID of the agent.
+             * @param attributes - Schema version attributes (fields, changes_summary).
+             * @param options - Optional request options.
+             * @returns The newly created schema version.
+             *
+             * @example
+             * const sv = await client.agents.versions.schemaVersions.create('agt_01...', {
+             *   output_schema: { type: 'object', properties: { amount: { type: 'number' } } },
+             * });
+             */
+            create: (agentId: string, attributes: CreateAgentVersionAttributes, options?: RequestOptions) => Promise<AgentVersion>;
+            /**
+             * Activates a schema version, making it the live version.
+             *
+             * @param agentId - The UUID of the agent.
+             * @param versionId - The UUID of the schema version to activate.
+             * @param options - Optional request options.
+             * @returns The activated schema version.
+             *
+             * @example
+             * await client.agents.versions.schemaVersions.activate('agt_01...', 'ver_01...');
+             */
+            activate: (agentId: string, versionId: string, options?: RequestOptions) => Promise<AgentVersion>;
+            /**
+             * Updates fields or metadata on an existing schema version.
+             *
+             * @param agentId - The UUID of the agent.
+             * @param versionId - The UUID of the schema version to update.
+             * @param attributes - Attributes to update (fields, changes_summary).
+             * @param options - Optional request options.
+             * @returns The updated schema version.
+             *
+             * @example
+             * await client.agents.versions.schemaVersions.update('agt_01...', 'ver_01...', {
+             *   output_schema: { type: 'object', properties: { total: { type: 'number' } } },
+             * });
+             */
+            update: (agentId: string, versionId: string, attributes: UpdateAgentVersionAttributes, options?: RequestOptions) => Promise<AgentVersion>;
+        };
+    };
+    /**
+     * Sub-namespace for managing training examples attached to agents.
+     *
+     * Training examples are input/output pairs that teach an agent how to behave.
+     * They are used both for fine-tuning jobs (via `agents.teach`) and as few-shot
+     * context injected into the agent's prompt. More high-quality, diverse examples
+     * generally lead to better and more consistent agent outputs.
+     *
+     * @example
+     * const client = new GptClient({ apiKey: 'sk_app_...' });
+     * await client.agents.training.create({
+     *   agent_id: 'agt_01HXYZ...',
+     *   input: 'What is the invoice total?',
+     *   output: '$1,234.56',
+     * });
+     */
+    training: {
+        /**
+         * Permanently deletes a training example by its ID.
+         *
+         * @param id - The UUID of the training example to delete.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to `true` on successful deletion.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * await client.agents.training.delete('tex_01HXYZ...');
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Lists training examples with optional pagination controls.
+         *
+         * Returns a single page of training examples. Use {@link listAll} to fetch
+         * every example across all pages automatically.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The page number to fetch (1-based).
+         * @param options.pageSize - Number of examples per page.
+         * @returns A promise that resolves to an array of `TrainingExample` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const examples = await client.agents.training.list({ pageSize: 50 });
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Fetches all training examples by transparently paginating through every
+         * page until exhausted.
+         *
+         * @param options - Optional request options.
+         * @returns A promise that resolves to a flat array of all `TrainingExample` objects.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const allExamples = await client.agents.training.listAll();
+         * console.log(`Total training examples: ${allExamples.length}`);
+         */
+        listAll: (options?: RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Fetches a single training example by its ID.
+         *
+         * @param id - The UUID of the training example to retrieve.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the full `TrainingExample` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         * const example = await client.agents.training.get('tex_01HXYZ...');
+         * console.log(example.attributes.input, '->', example.attributes.output);
+         */
+        get: (id: string, options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Creates a new training example for an agent.
+         *
+         * At minimum you must supply an `agent_id`, an `input` string, and an
+         * `output` string. Additional metadata such as `label`, `weight`, or
+         * `source_document_id` can be included in `attributes`.
+         *
+         * @param attributes - The training example attributes, including at least
+         *   `agent_id`, `input`, and `output`.
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the newly created `TrainingExample` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const example = await client.agents.training.create({
+         *   agent_id: 'agt_01HXYZ...',
+         *   input: 'Extract the vendor name from this invoice.',
+         *   output: 'Acme Corp',
+         * });
+         */
+        create: (attributes: CreateAgentTrainingExampleAttributes, options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Updates one or more attributes of an existing training example.
+         *
+         * Only the fields present in `attributes` are changed (PATCH semantics).
+         *
+         * @param id - The UUID of the training example to update.
+         * @param attributes - A partial map of attributes to update
+         *   (e.g. `{ output: 'Corrected answer' }`).
+         * @param options - Optional request options.
+         * @returns A promise that resolves to the updated `TrainingExample` object.
+         *
+         * @example
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const updated = await client.agents.training.update('tex_01HXYZ...', {
+         *   output: 'Corrected Corp',
+         *   label: 'reviewed',
+         * });
+         */
+        update: (id: string, attributes: UpdateAgentTrainingExampleAttributes, options?: RequestOptions) => Promise<TrainingExample>;
+        /**
+         * Creates multiple training examples in a single batch operation.
+         *
+         * @param examples - Array of training example attribute objects.
+         * @param options - Optional request options.
+         * @returns Array of created TrainingExample objects.
+         *
+         * @example
+         * const created = await client.agents.training.bulkCreate([
+         *   { agent_id: 'agt_01...', input_text: '...', output_json: {} },
+         *   { agent_id: 'agt_01...', input_text: '...', output_json: {} },
+         * ]);
+         */
+        bulkCreate: (examples: CreateAgentTrainingExampleAttributes[], options?: RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Deletes multiple training examples in a single batch operation.
+         *
+         * @param ids - Array of training example UUIDs to delete.
+         * @param options - Optional request options.
+         * @returns Deletion result payload.
+         *
+         * @example
+         * await client.agents.training.bulkDelete(['tex_01...', 'tex_02...']);
+         */
+        bulkDelete: (ids: string[], options?: RequestOptions) => Promise<BulkDeleteResponse>;
+        /**
+         * Performs semantic search over training examples using vector similarity.
+         *
+         * @param query - The search query text.
+         * @param options - Optional request options.
+         * @returns Array of matching TrainingExample objects ranked by similarity.
+         *
+         * @example
+         * const results = await client.agents.training.search('invoice total');
+         */
+        search: (query: string, options?: RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Lists training examples for a specific agent.
+         *
+         * @param agentId - The UUID of the agent.
+         * @param options - Optional request options.
+         * @returns Array of training examples for the agent.
+         *
+         * @example
+         * const examples = await client.agents.training.listForAgent('agt_01...');
+         */
+        listForAgent: (agentId: string, options?: RequestOptions) => Promise<TrainingExample[]>;
+        /**
+         * Deletes a training example for a specific agent.
+         *
+         * @param agentId - The UUID of the agent.
+         * @param exampleId - The UUID of the training example to delete.
+         * @param options - Optional request options.
+         * @returns True on successful deletion.
+         *
+         * @example
+         * await client.agents.training.deleteForAgent('agt_01...', 'tex_01...');
+         */
+        deleteForAgent: (agentId: string, exampleId: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Sub-namespace for managing training sessions.
+         *
+         * Training sessions group related training examples and track
+         * training progress over time.
+         */
+        sessions: {
+            /**
+             * Lists training sessions for a specific agent.
+             *
+             * @param agentId - The UUID of the agent.
+             * @param options - Optional request options.
+             * @returns Array of training session records.
+             *
+             * @example
+             * const sessions = await client.agents.training.sessions.list('agt_01...');
+             */
+            list: (agentId: string, options?: RequestOptions) => Promise<TrainingSession[]>;
+            /**
+             * Fetches a single training session by ID.
+             *
+             * @param id - The UUID of the training session.
+             * @param options - Optional request options.
+             * @returns The training session record.
+             *
+             * @example
+             * const session = await client.agents.training.sessions.get('ts_01...');
+             */
+            get: (id: string, options?: RequestOptions) => Promise<TrainingSession>;
+            /**
+             * Deletes a training session by ID.
+             *
+             * @param id - The UUID of the training session to delete.
+             * @param options - Optional request options.
+             * @returns True on successful deletion.
+             *
+             * @example
+             * await client.agents.training.sessions.delete('ts_01...');
+             */
+            delete: (id: string, options?: RequestOptions) => Promise<true>;
+        };
+    };
+    /**
+     * Sub-namespace for managing field templates.
+     *
+     * Field templates are reusable field definitions that can be applied
+     * to agent schemas. They include extraction hints, validation patterns,
+     * and LLM instructions for common field types.
+     */
+    fieldTemplates: {
+        /**
+         * Lists all available field templates.
+         *
+         * @param options - Optional request options.
+         * @returns Array of field template objects.
+         *
+         * @example
+         * const templates = await client.agents.fieldTemplates.list();
+         */
+        list: (options?: RequestOptions) => Promise<FieldTemplate[]>;
+        /**
+         * Fetches a single field template by ID.
+         *
+         * @param id - The UUID of the field template.
+         * @param options - Optional request options.
+         * @returns The field template object.
+         *
+         * @example
+         * const template = await client.agents.fieldTemplates.get('ftpl_01...');
+         */
+        get: (id: string, options?: RequestOptions) => Promise<FieldTemplate>;
+        /**
+         * Creates a new field template.
+         *
+         * @param attributes - Template attributes (name, category, field_type, etc.).
+         * @param options - Optional request options.
+         * @returns The newly created field template.
+         *
+         * @example
+         * const template = await client.agents.fieldTemplates.create({
+         *   name: 'Invoice Amount',
+         *   category: 'finance',
+         *   field_type: 'currency',
+         * });
+         */
+        create: (attributes: CreateFieldTemplateAttributes, options?: RequestOptions) => Promise<FieldTemplate>;
+        /**
+         * Deletes a field template by ID.
+         *
+         * @param id - The UUID of the field template to delete.
+         * @param options - Optional request options.
+         * @returns True on successful deletion.
+         *
+         * @example
+         * await client.agents.fieldTemplates.delete('ftpl_01...');
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+    };
+    /**
+     * Sub-namespace for managing agent executions.
+     *
+     * Executions represent a running instance of an agent processing input.
+     * Use {@link start} to begin an execution, {@link stream} to receive
+     * real-time token deltas and lifecycle events via SSE, and
+     * {@link approve}/{@link deny} to respond to human-in-the-loop prompts.
+     *
+     * @example
+     * const exec = await client.agents.executions.start('agt_01...', { task: 'Process invoice' });
+     * const stream = await client.agents.executions.stream(exec.id);
+     */
+    executions: {
+        /**
+         * Starts a new agent execution.
+         *
+         * Creates an execution record, performs credit balance validation,
+         * and enqueues the agent for processing. The returned execution
+         * object includes the execution ID needed for streaming and lifecycle
+         * management.
+         *
+         * @param agentId - The UUID of the agent to execute.
+         * @param input - Input data for the agent (task description, documents, etc.).
+         * @param opts - Additional execution options.
+         * @param opts.workspace_id - The workspace to execute in. **Required** unless
+         *   `workspaceId` was set in the `GptClient` constructor config.
+         * @param opts.model_id - Override model for this execution only (e.g., "anthropic/claude-sonnet-4").
+         *   Highest priority in the model resolution chain.
+         * @returns The created execution record with status `pending`.
+         *
+         * @example
+         * const exec = await client.agents.executions.start('agt_01...', {
+         *   task: 'Extract invoice fields',
+         *   document_id: 'doc_01...',
+         * }, { workspace_id: 'ws_abc123' });
+         * console.log(exec.id, exec.status); // 'pending'
+         *
+         * @example
+         * // With model override
+         * const exec = await client.agents.executions.start(
+         *   'agt_01...',
+         *   { task: 'Complex reasoning' },
+         *   { workspace_id: 'ws_abc123', model_id: 'anthropic/claude-sonnet-4' },
+         * );
+         */
+        start: (agentId: string, input: Record<string, unknown>, opts?: {
+            workspace_id?: string;
+            model_id?: string;
+        } & RequestOptions) => Promise<Execution>;
+        /**
+         * Estimates the credit cost of an execution before starting it.
+         *
+         * Returns a cost range (min/max) based on the agent's configuration,
+         * expected token usage, and tool call patterns. Useful for showing
+         * users the expected cost before confirming execution.
+         *
+         * @param agentId - The UUID of the agent.
+         * @param input - Input data (same format as {@link start}).
+         * @param opts - Additional options.
+         * @param opts.workspace_id - The workspace to estimate for. Required for `sk_app_` key auth.
+         * @returns Cost estimate with min/max credit ranges.
+         *
+         * @example
+         * const estimate = await client.agents.executions.estimate('agt_01...', {
+         *   task: 'Process batch',
+         * }, { workspace_id: 'ws_abc123' });
+         * console.log(`Estimated cost: ${estimate.min_credits} - ${estimate.max_credits}`);
+         */
+        estimate: (agentId: string, input: Record<string, unknown>, opts?: {
+            workspace_id?: string;
+        } & RequestOptions) => Promise<ExecutionEstimateResponse>;
+        /**
+         * Fetches a single execution by ID.
+         *
+         * Returns the full execution record including status, result,
+         * token usage, and credit charges.
+         *
+         * @param id - The UUID of the execution.
+         * @param options - Optional request options.
+         * @returns The execution record.
+         *
+         * @example
+         * const exec = await client.agents.executions.get('exec_01...');
+         * console.log(exec.status, exec.total_tokens);
+         */
+        get: (id: string, options?: RequestOptions) => Promise<Execution>;
+        /**
+         * Lists executions for the current user.
+         *
+         * Returns only executions triggered by the authenticated user,
+         * ordered by creation time descending.
+         *
+         * @param opts - Optional filtering and request options.
+         * @param opts.workspace_id - Filter to a specific workspace. Required for `sk_app_` key auth.
+         * @returns Array of execution records.
+         *
+         * @example
+         * const executions = await client.agents.executions.list({ workspace_id: 'ws_abc123' });
+         */
+        list: (opts?: {
+            workspace_id?: string;
+        } & RequestOptions) => Promise<Execution[]>;
+        /**
+         * Opens an SSE stream for real-time execution events.
+         *
+         * Yields typed {@link ExecutionEvent} objects including token deltas,
+         * tool calls, iteration completions, approval requests, and
+         * terminal events (done/error). The stream closes automatically
+         * when the execution completes or fails.
+         *
+         * @param id - The UUID of the execution to stream.
+         * @param options - Optional request and stream options (signal, timeout, maxChunks).
+         * @returns An async iterator of ExecutionEvent objects.
+         *
+         * @example
+         * const stream = await client.agents.executions.stream('exec_01...');
+         * for await (const event of stream) {
+         *   if (event.type === 'token_delta') process.stdout.write(event.data.content);
+         *   if (event.type === 'done') console.log('Complete');
+         * }
+         */
+        stream: (id: string, options?: RequestOptions & StreamOptions) => Promise<AsyncIterableIterator<ExecutionEvent>>;
+        /**
+         * Approves a pending human-in-the-loop tool call.
+         *
+         * When an execution encounters a sensitive or external tool that
+         * requires approval, it pauses and emits an `approval_required` event.
+         * Call this method to approve the tool call and resume execution.
+         *
+         * @param id - The UUID of the execution with a pending approval.
+         * @param options - Optional request options.
+         * @returns The updated execution record.
+         *
+         * @example
+         * await client.agents.executions.approve('exec_01...');
+         */
+        approve: (id: string, approvedData?: Record<string, unknown>, options?: RequestOptions) => Promise<Execution>;
+        /**
+         * Denies a pending human-in-the-loop tool call.
+         *
+         * The execution will record the denial and continue without executing
+         * the tool. The LLM receives the denial reason and can adjust its
+         * approach accordingly.
+         *
+         * @param id - The UUID of the execution.
+         * @param reason - Human-readable reason for denying the tool call.
+         * @param options - Optional request options.
+         * @returns The updated execution record.
+         *
+         * @example
+         * await client.agents.executions.deny('exec_01...', 'Not authorized to send emails');
+         */
+        deny: (id: string, reason: string, options?: RequestOptions) => Promise<Execution>;
+        /**
+         * Cancels a running or paused execution.
+         *
+         * The execution transitions to `cancelled` status. Any in-progress
+         * tool calls are abandoned. Credits charged up to the cancellation
+         * point are not refunded.
+         *
+         * @param id - The UUID of the execution to cancel.
+         * @param options - Optional request options.
+         * @returns The updated execution record with `cancelled` status.
+         *
+         * @example
+         * await client.agents.executions.cancel('exec_01...');
+         */
+        cancel: (id: string, options?: RequestOptions) => Promise<Execution>;
+        /**
+         * Lists child executions of a delegation chain.
+         *
+         * When an agent delegates sub-tasks to other agents, each delegation
+         * creates a child execution. This method returns all direct children.
+         *
+         * @param id - The UUID of the parent execution.
+         * @param options - Optional request options.
+         * @returns Array of child execution records.
+         *
+         * @example
+         * const children = await client.agents.executions.children('exec_01...');
+         */
+        children: (id: string, options?: RequestOptions) => Promise<Execution[]>;
+        /**
+         * Retrieves the full execution tree (depth-first).
+         *
+         * Returns a hierarchical view of the execution and all its descendants
+         * in the delegation chain.
+         *
+         * @param id - The UUID of the root execution.
+         * @param options - Optional request options.
+         * @returns Execution tree structure.
+         *
+         * @example
+         * const tree = await client.agents.executions.tree('exec_01...');
+         */
+        tree: (id: string, options?: RequestOptions) => Promise<ExecutionTreeResponse>;
+    };
+    /**
+     * Read-only access to agent deployments for the current application.
+     * Create/update/delete operations are available via the admin SDK.
+     */
+    deployments: {
+        /**
+         * Lists all agent deployments for the current application.
+         *
+         * @param options - Optional request options (pagination, filters).
+         * @returns A paginated list of agent deployments.
+         *
+         * @example
+         * const deployments = await client.agents.deployments.list();
+         */
+        list: (options?: RequestOptions) => Promise<AgentDeployment[]>;
+        /**
+         * Retrieves a single agent deployment by ID.
+         *
+         * @param id - The UUID of the deployment.
+         * @param options - Optional request options.
+         * @returns The agent deployment.
+         *
+         * @example
+         * const deployment = await client.agents.deployments.get('dep_01...');
+         */
+        get: (id: string, options?: RequestOptions) => Promise<AgentDeployment>;
+    };
+    /**
+     * Workspace-level agent configuration overrides.
+     * End users can read and update overrides; create/delete via admin SDK.
+     */
+    workspaceConfigs: {
+        /**
+         * Lists all workspace agent configs.
+         *
+         * @param options - Optional request options (pagination, filters).
+         * @returns A paginated list of workspace agent configs.
+         *
+         * @example
+         * const configs = await client.agents.workspaceConfigs.list();
+         */
+        list: (options?: RequestOptions) => Promise<WorkspaceAgentConfig[]>;
+        /**
+         * Retrieves a single workspace agent config by ID.
+         *
+         * @param id - The UUID of the config.
+         * @param options - Optional request options.
+         * @returns The workspace agent config.
+         *
+         * @example
+         * const config = await client.agents.workspaceConfigs.get('wac_01...');
+         */
+        get: (id: string, options?: RequestOptions) => Promise<WorkspaceAgentConfig>;
+        /**
+         * Updates a workspace agent config's overrides.
+         *
+         * @param id - The UUID of the config.
+         * @param attributes - Attributes to update (e.g. overrides).
+         * @param options - Optional request options.
+         * @returns The updated workspace agent config.
+         *
+         * @example
+         * await client.agents.workspaceConfigs.update('wac_01...', {
+         *   overrides: { prompt_template: 'Custom prompt...' },
+         * });
+         */
+        update: (id: string, attributes: Record<string, unknown>, options?: RequestOptions) => Promise<WorkspaceAgentConfig>;
+    };
+};
+//# sourceMappingURL=agents.d.ts.map