@archastro/sdk 0.5.2 → 0.6.0

package/dist/v1/resources/agents.d.ts

@@ -1,23 +1,123 @@
 import { HttpClient } from "../../runtime/http-client.js";
-import type { Agent, AgentComputer, AgentComputerListResponse, AgentExport, AgentListResponse, AgentRoutine, AgentSchedule, AgentTool, AgentToolListResponse } from "../../types/agents.js";
-import type { Installation, InstallationKindListResponse, InstallationListResponse, WorkingMemoryEntryListResponse } from "../../types/common.js";
+import type { Agent, AgentComputer, AgentComputerListResponse, AgentCreateResponse, AgentEnvVarMasked, AgentEnvVarMaskedList, AgentExport, AgentHealth, AgentListResponse, AgentRoutine, AgentSchedule, AgentTool, AgentToolListResponse, AgentUpgradeResponse, HealthActionListResponse, Installation, InstallationKindListResponse, InstallationListResponse, WorkingMemoryEntryListResponse } from "../../types/common.js";
 import type { Thread } from "../../types/threads.js";
 export declare class AgentAgentComputerResource {
     private http;
     constructor(http: HttpClient);
+    /**
+     * List computers
+     * Returns all computers belonging to the authenticated app, ordered by creation
+     * time descending. Pass `agent` to scope the results to a single agent's
+     * computers. When `agent` is omitted, computers for all agents in the app are
+     * returned.
+     * Requires an app-scoped API key. If the specified agent does not exist or does
+     * not belong to the app, the endpoint returns 404.
+     * @param agent - Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned.
+     * @returns Object containing a `data` array of computer records.
+     */
     list(agent: string): Promise<AgentComputerListResponse>;
+    /**
+     * Provision a computer for an agent
+     * Creates and provisions a new computer resource associated with the specified
+     * agent. The computer is allocated in the requested region (defaulting to `iad`)
+     * and its status transitions from `provisioning` to `running` once it is ready.
+     * Requires an app-scoped API key. The agent identified by `agent` must belong
+     * to the same app. Supplying a `lookup_key` lets you retrieve this computer
+     * later without storing its ID — the key must be unique within the app.
+     * @param agent - Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned.
+     * @param input - Request body.
+     * @param input.config - Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`.
+     * @param input.lookup_key - Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID.
+     * @param input.metadata - Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads.
+     * @param input.name - Human-readable display name for the computer.
+     * @param input.provider - Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`.
+     * @param input.region - Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted.
+     * @returns The newly provisioned computer.
+     */
     create(agent: string, input: {
         config?: Record<string, unknown> | undefined;
         lookup_key?: string | undefined;
         metadata?: Record<string, unknown> | undefined;
         name: string;
+        provider?: string | undefined;
         region?: string | undefined;
     }): Promise<AgentComputer>;
 }
+export declare class AgentAgentEnvVarResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List an agent's environment variables
+     * Returns all environment variables defined for the specified agent. Variable
+     * values are always masked in the response; only the last four characters are
+     * visible. To inspect a specific variable, use the retrieve endpoint.
+     * The authenticated user must have access to the agent's parent app. Pass the
+     * app scope via the `app` parameter when calling with an API key that is scoped
+     * to a specific app. Results are returned in an unordered flat list.
+     * @param agent - Agent ID (`agt_...`). Returns environment variables belonging to this agent.
+     * @returns List of environment variables for the agent, with values masked.
+     */
+    list(agent: string): Promise<AgentEnvVarMaskedList>;
+    /**
+     * Create an agent environment variable
+     * Creates a new environment variable for the specified agent. The variable is
+     * stored securely and the plaintext `value` is never returned after creation;
+     * subsequent reads return a masked representation showing only the last four
+     * characters.
+     * The authenticated user must have access to the agent's parent app. Pass the
+     * app scope via the `app` parameter when calling with an API key that is scoped
+     * to a specific app. Each `key` must be unique within the agent; attempting to
+     * create a duplicate key returns a validation error.
+     * @param agent - Agent ID (`agt_...`). Returns environment variables belonging to this agent.
+     * @param input - Request body.
+     * @param input.description - Optional human-readable note describing what the variable is used for.
+     * @param input.key - Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent.
+     * @param input.value - Plaintext secret value to store. The value is encrypted at rest and never returned in full.
+     * @returns The newly created environment variable with its value masked.
+     */
+    create(agent: string, input: {
+        description?: string | undefined;
+        key: string;
+        value: string;
+    }): Promise<AgentEnvVarMasked>;
+}
 export declare class AgentAgentInstallationResource {
     private http;
     constructor(http: HttpClient);
+    /**
+     * List installations for an agent
+     * Returns all installations belonging to the specified agent, across all kinds and
+     * states. Use this endpoint to inspect which external services and enablement channels
+     * an agent is connected to.
+     * Results are scoped to the authenticated app and are returned in an unordered array.
+     * To list installations across all agents in an app, use the top-level List
+     * Installations endpoint instead. The caller must have app scope for the app that
+     * owns the agent.
+     * @param agent - Agent ID (`agt_...`) whose installations you want to retrieve.
+     * @returns The list of installations for the specified agent.
+     */
     list(agent: string): Promise<InstallationListResponse>;
+    /**
+     * Create an installation
+     * Creates a new installation for an agent, connecting it to an external service or
+     * enablement channel via the specified `kind`. The installation begins in a pending
+     * state unless an integration is supplied at creation time, in which case it is
+     * activated immediately.
+     * Supply `shared_integration` to bind an existing org- or app-level integration, or
+     * supply `integration` to create a new integration inline and activate the installation
+     * in a single request. Supplying both fields returns 422.
+     * Use `lookup_key` to assign a stable identifier you can reference later in knowledge
+     * search `source_refs`. The key must be unique within the app, org, and sandbox
+     * combination. The caller must have app scope for the app that owns the agent.
+     * @param agent - Agent ID (`agt_...`) whose installations you want to retrieve.
+     * @param input - Request body.
+     * @param input.config - Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration.
+     * @param input.integration - Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`.
+     * @param input.kind - Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values.
+     * @param input.lookup_key - Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing.
+     * @param input.shared_integration - ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`.
+     * @returns The newly created installation.
+     */
     create(agent: string, input: {
         config?: Record<string, unknown> | undefined;
         integration?: {
@@ -28,17 +128,75 @@ export declare class AgentAgentInstallationResource {
             workspace_key?: string | undefined;
         } | undefined;
         kind: string;
+        lookup_key?: string | undefined;
         shared_integration?: string | undefined;
     }): Promise<Installation>;
+    /**
+     * List available installation kinds
+     * Returns the full catalogue of installation kinds supported by the platform. Use
+     * the returned `kind` values when calling the Create Installation endpoint.
+     * The list is platform-wide and does not vary by agent. The `agent` parameter is
+     * accepted for future per-agent filtering but is currently unused. The caller must
+     * have app scope to call this endpoint.
+     * @param agent - Agent ID (`agt_...`) whose installations you want to retrieve.
+     * @returns The list of all supported installation kinds.
+     */
     kinds(agent: string): Promise<InstallationKindListResponse>;
 }
 export declare class AgentAgentToolResource {
     private http;
     constructor(http: HttpClient);
+    /**
+     * List agent tools
+     * Returns all tools for the authenticated app, optionally filtered by agent
+     * or tool kind. Both explicitly created tools and tools derived from connected
+     * integrations (installation-sourced tools) are included in the response.
+     * Installation-sourced tools appear with `source: "installation"` and
+     * `status: "active"`. They are synthesized at request time from connected
+     * integrations and do not have a persistent tool ID of the `atl_...` form;
+     * their `id` is a composite of the installation ID and server tool type.
+     * Use the `agent` filter to retrieve tools for a specific agent. Supplying an
+     * `agent` ID that does not belong to the authenticated app returns 404.
+     * Requires app scope.
+     * @param agent - Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app.
+     * @param params - Query parameters.
+     * @param params.kind - Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds.
+     * @returns List of tools matching the supplied filters.
+     */
     list(agent: string, params?: {
         kind?: string;
     }): Promise<AgentToolListResponse>;
+    /**
+     * Create an agent tool
+     * Creates a new tool and attaches it to the specified agent. Tools can be
+     * either `"builtin"` (a platform-provided capability identified by
+     * `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name,
+     * description, parameter schema, and handler).
+     * New tools are created in `"draft"` status by default unless `status:
+     * "active"` is explicitly supplied. Draft tools are not exposed to the LLM
+     * during agent runs; call the activate endpoint to promote them.
+     * For built-in tools that support multiple instances per agent (those whose
+     * catalog entry has a `multi_instance_mode`), supply `name_prefix` to
+     * namespace the LLM-facing tool names. Requires app scope.
+     * @param agent - Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app.
+     * @param input - Request body.
+     * @param input.async - When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools.
+     * @param input.builtin_tool_config - Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools.
+     * @param input.builtin_tool_key - Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog.
+     * @param input.config - Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools.
+     * @param input.description - Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools.
+     * @param input.handler_type - Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools.
+     * @param input.kind - Tool kind. One of `"builtin"` or `"custom"`.
+     * @param input.lookup_key - Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning.
+     * @param input.metadata - Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform.
+     * @param input.name - Display name for the tool. Required when `kind` is `"custom"`.
+     * @param input.name_prefix - Per-instance namespace for built-in tools that support multiple instances per agent. Stamped onto LLM-facing tool names (e.g. `"org"` produces `"org_knowledge_search"`). Must match `^[a-z][a-z0-9_]*$` and be at most 24 characters. Required for `"namespaced"` multi-instance tools; omit for single-instance tools.
+     * @param input.parameters - JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools.
+     * @param input.status - Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted.
+     * @returns The newly created tool.
+     */
     create(agent: string, input: {
+        async?: boolean | undefined;
         builtin_tool_config?: Record<string, unknown> | undefined;
         builtin_tool_key?: string | undefined;
         config?: string | undefined;
@@ -48,6 +206,7 @@ export declare class AgentAgentToolResource {
         lookup_key?: string | undefined;
         metadata?: Record<string, unknown> | undefined;
         name?: string | undefined;
+        name_prefix?: string | undefined;
         parameters?: Record<string, unknown> | undefined;
         status?: string | undefined;
     }): Promise<AgentTool>;
@@ -55,6 +214,17 @@ export declare class AgentAgentToolResource {
 export declare class ScheduleResource {
     private http;
     constructor(http: HttpClient);
+    /**
+     * List schedules for an agent
+     * Returns all schedules belonging to the specified agent in any status. Use the
+     * `status` parameter to narrow results to a single lifecycle state.
+     * Requires an app-scoped API key. The agent must belong to the app identified
+     * by the key.
+     * @param agent - Agent ID (`agi_...`). The agent whose schedules you want to retrieve.
+     * @param params - Query parameters.
+     * @param params.status - Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses.
+     * @returns Successful response
+     */
     list(agent: string, params?: {
         status?: string;
     }): Promise<{
@@ -78,21 +248,91 @@ export declare class ScheduleResource {
             updated_at?: string | undefined;
         }[] | undefined;
     }>;
+    /**
+     * Retrieve a schedule
+     * Returns a single schedule belonging to the specified agent. Use this endpoint
+     * to fetch the current state, next run time, and configuration of an individual
+     * schedule.
+     * Requires an app-scoped API key. Both the agent and the schedule must belong
+     * to the app identified by the key. Returns 404 if the schedule does not exist
+     * or belongs to a different agent.
+     * @param agent - Agent ID (`agi_...`). The agent whose schedules you want to retrieve.
+     * @param schedule - Schedule ID (`asc_...`). The schedule to retrieve.
+     * @returns The requested agent schedule.
+     */
     get(agent: string, schedule: string): Promise<AgentSchedule>;
 }
 export declare class AgentResource {
     private http;
     readonly agent_computers: AgentAgentComputerResource;
+    readonly agent_env_vars: AgentAgentEnvVarResource;
     readonly agent_installations: AgentAgentInstallationResource;
     readonly agent_tools: AgentAgentToolResource;
     readonly schedules: ScheduleResource;
     constructor(http: HttpClient);
+    /**
+     * List agents
+     * Returns a paginated list of agents visible to the authenticated caller. Results are
+     * ordered by creation time descending.
+     * Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id`
+     * to scope the list to a specific owner. Use `template_config` to find agents whose
+     * last applied template matches a given config ID. Use `solution_config` to find
+     * agents whose last applied template was imported as part of any of the given
+     * Solution config IDs.
+     * Pagination is page-based: pass `page` and `page_size` to navigate through large
+     * result sets. When called under a developer app scope, only agents belonging to that
+     * app are returned.
+     * @param params - Query parameters.
+     * @param params.page - Page number to retrieve, 1-indexed. Defaults to `1`.
+     * @param params.pageSize - Number of agents to return per page. Defaults to `25`.
+     * @param params.search - Free-text search string matched against the agent name, org, team, and owner fields.
+     * @param params.user - User ID (`usr_...`) to filter by. Returns only agents owned by this user.
+     * @param params.orgId - Organization ID (`org_...`) to filter by. Returns only agents owned by this org.
+     * @param params.templateConfig - Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches.
+     * @param params.solutionConfig - Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs.
+     * @returns Paginated list of agents matching the supplied filters.
+     */
     list(params?: {
         page?: number;
         pageSize?: number;
         search?: string;
         user?: string;
+        orgId?: string;
+        templateConfig?: string;
+        solutionConfig?: string[];
     }): Promise<AgentListResponse>;
+    /**
+     * Create an agent
+     * Creates a new agent. Supports two mutually exclusive provisioning modes.
+     * **Template mode** — pass `template` with the ID or `lookup_key` of an existing
+     * AgentTemplate config. The agent's tools, routines, skills, and installations are
+     * provisioned from that template's `config_ref` entries.
+     * **Bundle mode** — pass `template_bundle` with a self-contained install payload
+     * (AgentTemplate body plus every skill, script, and config it references). The entire
+     * bundle commits in a single transaction; any failure rolls back the whole install and
+     * the response includes `installed_configs[]` — one entry per persisted config.
+     * Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name`
+     * is required and a blank agent is created. Requires authentication; when called under
+     * a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope
+     * for the target app.
+     * @param input - Request body.
+     * @param input.acl - Access control list controlling which users, teams, or orgs can read or manage this agent.
+     * @param input.email - Email address assigned to the agent. Used as the agent's contact identity.
+     * @param input.identity - System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
+     * @param input.lookup_key - Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
+     * @param input.metadata - Arbitrary key-value map stored on the agent. Not interpreted by the platform.
+     * @param input.model - Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model.
+     * @param input.name - Display name for the agent. Required when neither `template` nor `template_bundle` is provided.
+     * @param input.org - Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`.
+     * @param input.originator - Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
+     * @param input.phone_number - Phone number assigned to the agent in E.164 format, e.g. `+15550001234`.
+     * @param input.profile_picture - Profile picture to attach to the agent. All three subfields are required when this object is present.
+     * @param input.team - Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`.
+     * @param input.template - ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`.
+     * @param input.template_bundle - Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`.
+     * @param input.user - User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`.
+     * @returns The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` — one entry per persisted config object, with `key` echoing the caller-supplied input identifier.
+     */
     create(input: {
         acl?: {
             add?: {
@@ -117,6 +357,7 @@ export declare class AgentResource {
         model?: string | undefined;
         name?: string | undefined;
         org?: string | undefined;
+        originator?: string | undefined;
         phone_number?: string | undefined;
         profile_picture?: {
             data: string;
@@ -125,10 +366,87 @@ export declare class AgentResource {
         } | undefined;
         team?: string | undefined;
         template?: string | undefined;
+        template_bundle?: {
+            configs?: {
+                content: string;
+                content_type?: string | undefined;
+                relative_path: string;
+            }[] | undefined;
+            lookup_key_suffix?: string | undefined;
+            setup_actions?: {
+                depends_on?: string[] | undefined;
+                description?: string | undefined;
+                kind: string;
+                params?: Record<string, unknown> | undefined;
+                required?: boolean | undefined;
+                sort_order?: number | undefined;
+                title: string;
+                verify_config?: Record<string, unknown> | undefined;
+            }[] | undefined;
+            skills?: {
+                content: string;
+                content_type?: string | undefined;
+                files?: {
+                    content: string;
+                    content_type?: string | undefined;
+                    relative_path: string;
+                }[] | undefined;
+                relative_path: string;
+            }[] | undefined;
+            template: {
+                content: string;
+                content_type?: string | undefined;
+                relative_path: string;
+            };
+        } | undefined;
         user?: string | undefined;
-    }): Promise<Agent>;
+    }): Promise<AgentCreateResponse>;
+    /**
+     * Delete an agent
+     * Permanently deletes an agent and all of its associated resources. This action cannot
+     * be undone.
+     * The authenticated caller must own the agent or hold sufficient permissions within its
+     * owning org or team. When called under a developer app scope, the caller must hold the
+     * app scope for the target app.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent to delete.
+     * @returns Empty body. Returns HTTP 204 on success.
+     */
     delete(agent: string): Promise<void>;
+    /**
+     * Retrieve an agent
+     * Returns the agent identified by ID or `lookup_key`. The authenticated caller must
+     * own the agent or hold sufficient permissions within its owning org or team.
+     * When called under a developer app scope, the agent must belong to that app. Use the
+     * list endpoint to retrieve many agents at once.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent to retrieve.
+     * @returns The requested agent.
+     */
     get(agent: string): Promise<Agent>;
+    /**
+     * Update an agent
+     * Updates one or more fields on an existing agent. Only the fields you supply are
+     * changed; omitted fields retain their current values.
+     * To clear the agent's default model, pass `model` as an empty string. The
+     * authenticated caller must own the agent or hold write permissions within its owning
+     * org or team. When called under a developer app scope, the caller must hold the app
+     * scope for the target app.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent to update.
+     * @param input - Request body.
+     * @param input.acl - Replacement access control list. Fully replaces the existing ACL.
+     * @param input.email - New email address for the agent.
+     * @param input.identity - Replacement identity system-prompt string describing who the agent is.
+     * @param input.lookup_key - New `lookup_key` slug. Must be unique within the owning app or org.
+     * @param input.metadata - Replacement key-value metadata map. The entire map is replaced, not merged.
+     * @param input.model - New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model.
+     * @param input.name - New display name for the agent.
+     * @param input.org - Organization ID (`org_...`) to transfer ownership to.
+     * @param input.originator - Replacement originator label identifying the source or author of the agent.
+     * @param input.phone_number - New phone number for the agent in E.164 format, e.g. `+15550001234`.
+     * @param input.profile_picture - Replacement profile picture. All three subfields are required when this object is present.
+     * @param input.team - Team ID (`team_...`) to transfer ownership to.
+     * @param input.user - User ID (`usr_...`) to transfer ownership to.
+     * @returns The updated agent with all current field values.
+     */
     update(agent: string, input: {
         acl?: {
             add?: {
@@ -153,6 +471,7 @@ export declare class AgentResource {
         model?: string | undefined;
         name?: string | undefined;
         org?: string | undefined;
+        originator?: string | undefined;
         phone_number?: string | undefined;
         profile_picture?: {
             data: string;
@@ -162,6 +481,59 @@ export declare class AgentResource {
         team?: string | undefined;
         user?: string | undefined;
     }): Promise<Agent>;
+    /**
+     * List health actions for an agent
+     * Returns all health actions associated with a given agent. Health actions
+     * represent required or recommended steps — such as setting environment
+     * variables, completing OAuth installations, or running custom verifiers —
+     * that an agent needs to reach a healthy state.
+     * Results are not paginated; the full list for the agent is returned. Use
+     * the `source`, `status`, and `kind` filters to narrow results to the
+     * subset your UI or workflow needs. Multiple values for the same filter
+     * are treated as OR (e.g. passing two statuses returns actions matching
+     * either). The caller must be authenticated and scoped to the app that
+     * owns the agent.
+     * @param agent - Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list.
+     * @param params - Query parameters.
+     * @param params.source - Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages.
+     * @param params.status - Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses.
+     * @param params.kind - Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds.
+     * @returns Object containing a `data` array of health action objects for the specified agent.
+     */
+    agentHealthActions(agent: string, params?: {
+        source?: string[];
+        status?: string[];
+        kind?: string[];
+    }): Promise<HealthActionListResponse>;
+    /**
+     * Create a routine
+     * Creates a new routine and attaches it to the specified agent. Routines define
+     * how an agent responds to events or a cron schedule; the `handler_type` controls
+     * which execution model is used.
+     * The routine is created in `"draft"` status by default. To start processing
+     * events immediately, either pass `status: "active"` or call the activate
+     * endpoint after creation. Scheduled routines must run no more frequently than
+     * once per hour. Requires app scope.
+     * @param agent - Agent ID (`agt_...`) that this routine will be attached to.
+     * @param input - Request body.
+     * @param input.acl - Access control list governing who can read or manage this routine.
+     * @param input.config - Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`.
+     * @param input.description - Optional human-readable description of what this routine does.
+     * @param input.event_config - Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).
+     * @param input.event_type - Event type that triggers this routine. Deprecated — use `event_config` instead.
+     * @param input.handler_type - Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.
+     * @param input.lookup_key - Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.
+     * @param input.metadata - Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.
+     * @param input.name - Human-readable display name for the routine.
+     * @param input.preset_config - Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`.
+     * @param input.preset_name - Name of the registered preset to use. Required when `handler_type` is `"preset"`.
+     * @param input.schedule - Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.
+     * @param input.script - Inline script source. Required when `handler_type` is `"script"`.
+     * @param input.status - Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`.
+     * @param input.steps - Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`.
+     * @param input.trigger_context - Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`.
+     * @returns The newly created routine.
+     */
     agentRoutines(agent: string, input: {
         acl?: {
             add?: {
@@ -221,19 +593,86 @@ export declare class AgentResource {
         }[] | undefined;
         trigger_context?: string | undefined;
     }): Promise<AgentRoutine>;
+    /**
+     * List working memory entries for an agent
+     * Returns a paginated list of working memory entries belonging to the specified
+     * agent. Entries are key-value pairs the agent stores for context between
+     * interactions. Results are ordered by creation time descending (newest first)
+     * and can be filtered with a substring search against the key name.
+     * Requires an app-scoped API key. The authenticated caller must have access to
+     * the app the agent belongs to. Returns 403 if the key is not app-scoped, and
+     * 404 if the agent does not exist within the accessible scope.
+     * @param agent - Agent ID (`agt_...`) whose working memory entries to retrieve.
+     * @param params - Query parameters.
+     * @param params.page - Page number to retrieve, starting at 1. Defaults to 1.
+     * @param params.pageSize - Number of entries to return per page. Defaults to 25.
+     * @param params.search - Substring filter applied to entry keys (case-insensitive). Omit to return all keys.
+     * @returns Paginated list of working memory entries for the agent.
+     */
     agentWorkingMemory(agent: string, params?: {
         page?: number;
         pageSize?: number;
         search?: string;
     }): Promise<WorkingMemoryEntryListResponse>;
     /**
-     * Export agent as AgentTemplate
-     * Reconstructs an AgentTemplate config from a deployed agent and its sub-resources
-     * (tools, routines, skills, installations). Returns the template plus all dependent
-     * config files (scripts, workflows, skills, schemas) with their raw content for a
-     * fully self-contained export.
+     * Export an agent as an AgentTemplate
+     * Reconstructs an AgentTemplate config from a deployed agent and all of its
+     * sub-resources (tools, routines, skills, installations). Returns the template
+     * definition together with every dependent config file (scripts, workflows, skills,
+     * schemas) and their raw content, producing a fully self-contained export bundle.
+     * Use this endpoint to snapshot an agent's current configuration for backup,
+     * migration, or to seed a new Solution template. Pass `remove_identity: true` to
+     * strip instance-specific fields (email, phone number) before export.
+     * The authenticated caller must own the agent or hold sufficient permissions within
+     * its owning org or team. When called under a developer app scope, the caller must
+     * hold the app scope for the target app.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent to export.
+     * @param params - Query parameters.
+     * @param params.removeIdentity - When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint.
+     * @returns Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content.
+     */
+    export(agent: string, params?: {
+        removeIdentity?: boolean;
+    }): Promise<AgentExport>;
+    /**
+     * Retrieve an agent's health profile
+     * Returns an aggregate health profile for the specified agent, including an overall
+     * status, a numeric health score, recent activity metrics, and a list of recommended
+     * remediation actions.
+     * The health check is computed on demand at request time. The `checked_at` timestamp
+     * in the response reflects when the evaluation ran. Use this endpoint to surface
+     * diagnostics about tool availability, model configuration, and runtime activity in
+     * dashboards or monitoring workflows.
+     * The authenticated caller must own the agent or hold sufficient permissions within
+     * its owning org or team. When called under a developer app scope, the caller must
+     * hold the app scope for the target app.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent to evaluate.
+     * @returns Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions.
+     */
+    health(agent: string): Promise<AgentHealth>;
+    /**
+     * Search an agent's knowledge base
+     * Performs a semantic search over an agent's knowledge base and returns a ranked,
+     * `kind`-discriminated list of matching items.
+     * Two item kinds may appear in `data`:
+     * - `"chunk"` — chunk-level results from the agent's context store. Present for all agents.
+     * - `"document"` — document-level results. Present only when the agent has an active
+     * `archastro/knowledge` installation.
+     * Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to
+     * be comparable across kinds, then merged into a single ranked list. On a relevance tie,
+     * chunks appear before documents. The total number of results is capped at `max_results`
+     * across both kinds.
+     * Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and
+     * full-text search; `"vector"` and `"fulltext"` select each strategy independently.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search.
+     * @param input - Request body.
+     * @param input.max_results - Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`.
+     * @param input.mode - Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.
+     * @param input.query - Natural-language search query used to retrieve relevant knowledge items.
+     * @param input.recency_days - When set, restricts results to items indexed within the last N days.
+     * @param input.source_types - Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types.
+     * @returns Successful response
      */
-    export(agent: string): Promise<AgentExport>;
     search(agent: string, input: {
         max_results?: number | undefined;
         mode?: string | undefined;
@@ -246,11 +685,35 @@ export declare class AgentResource {
             content_type?: string | undefined;
             created_at?: string | undefined;
             id: string;
+            kind: "chunk";
             metadata?: Record<string, unknown> | undefined;
             raw_content?: Record<string, unknown> | undefined;
             type?: string | undefined;
+        } | {
+            id: string;
+            kind: "document";
+            metadata?: Record<string, unknown> | undefined;
+            snippet?: string | undefined;
+            title?: string | undefined;
+            total_lines?: number | undefined;
+            total_size?: number | undefined;
         }[];
     }>;
+    /**
+     * Create a thread for an agent
+     * Creates a new thread owned by the specified agent. The thread is scoped to the
+     * agent's identity and is immediately available for messaging.
+     * The authenticated caller must have access to the agent's parent app. If your
+     * API key is scoped to a specific app, pass that app's ID via the `app` parameter.
+     * Attempting to create a thread for an agent you cannot access returns 404.
+     * By default the platform may send an automatic welcome message into the new
+     * thread. Pass `skip_welcome_message: true` to suppress this behavior.
+     * @param agent - Agent ID (`agt_...`). The thread will be owned by this agent.
+     * @param input - Request body.
+     * @param input.skip_welcome_message - When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`.
+     * @param input.thread - Attributes for the new thread.
+     * @returns The newly created thread.
+     */
     threads(agent: string, input: {
         skip_welcome_message?: boolean | undefined;
         thread: {
@@ -258,10 +721,57 @@ export declare class AgentResource {
             is_unlisted?: boolean | undefined;
             key?: string | undefined;
             metadata?: Record<string, unknown> | undefined;
+            muted?: boolean | undefined;
             org?: string | undefined;
             settings?: Record<string, unknown> | undefined;
             title?: string | undefined;
         };
     }): Promise<Thread>;
+    /**
+     * Upgrade an agent from an AgentTemplate
+     * Upgrades an existing agent by reconciling it against an AgentTemplate from a
+     * Solution. Supports two modes:
+     * - `"reapply"` (default) — re-applies the agent's currently tracked template,
+     * picking up any changes the template author has made since the last apply.
+     * - `"replace"` — moves the agent to a different template. `template` is required
+     * in this mode.
+     * Set `dry_run: true` to compute and return the full upgrade diff (adds, updates,
+     * removes, noops) without writing any changes. The response includes a
+     * `review_fingerprint` you can pass back via `expected_review_fingerprint` on the
+     * live apply to guard against the diff changing between review and execution.
+     * Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`,
+     * `originator`, `model`) let you pin instance-specific values that should not be
+     * overwritten by the template during the upgrade.
+     * The authenticated caller must own the agent or hold write permissions within its
+     * owning org or team. When called under a developer app scope, the caller must hold
+     * the app scope for the target app.
+     * @param agent - ID (`agi_...`) or `lookup_key` of the agent to upgrade.
+     * @param input - Request body.
+     * @param input.dry_run - When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply.
+     * @param input.email - Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.
+     * @param input.expected_review_fingerprint - Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches.
+     * @param input.identity - Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.
+     * @param input.metadata - Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.
+     * @param input.mode - Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`).
+     * @param input.model - Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.
+     * @param input.name - Instance-specific name override. Pins this value so the template upgrade does not overwrite it.
+     * @param input.originator - Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.
+     * @param input.phone_number - Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it.
+     * @param input.template - ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode.
+     * @returns The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted.
+     */
+    upgrade(agent: string, input: {
+        dry_run?: boolean | undefined;
+        email?: string | undefined;
+        expected_review_fingerprint?: string | undefined;
+        identity?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        mode?: "reapply" | "replace" | undefined;
+        model?: string | undefined;
+        name?: string | undefined;
+        originator?: string | undefined;
+        phone_number?: string | undefined;
+        template?: string | undefined;
+    }): Promise<AgentUpgradeResponse>;
 }
 //# sourceMappingURL=agents.d.ts.map