Class AgentResource

Index

Constructors

constructor

new AgentResource(http: HttpClient): AgentResource
Parameters
- http: HttpClient
Returns AgentResource
- Defined in packages/sdk/src/v1/resources/agents.ts:259

Properties

`Readonly`agent_computers

agent_computers: AgentAgentComputerResource

`Readonly`agent_env_vars

agent_env_vars: AgentAgentEnvVarResource

`Readonly`agent_installations

agent_installations: AgentAgentInstallationResource

`Readonly`agent_tools

agent_tools: AgentAgentToolResource

`Readonly`schedules

schedules: ScheduleResource

Methods

agentHealthActions

agentHealthActions(
agent: string,
params?: { kind?: string[]; source?: string[]; status?: string[] },
): Promise<HealthActionListResponse>
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.
Parameters
- agent: string
  Agent ID (agt_...) or lookup key of the agent whose health actions you want to list.
- Optionalparams: { kind?: string[]; source?: string[]; status?: string[] }
  Query parameters.
  - Optionalkind?: string[]
    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.
  - Optionalsource?: string[]
    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.
  - Optionalstatus?: string[]
    Filter results to actions in one or more statuses. Accepted values: "pending", "completed", "skipped", and "degraded". Omit to return actions in all statuses.
Returns Promise<HealthActionListResponse>
Object containing a data array of health action objects for the specified agent.
- Defined in packages/sdk/src/v1/resources/agents.ts:427

agentRoutines

agentRoutines(
    agent: string,
    input: {
        acl?: {
            add?: {
                actions: string[];
                principal?: string;
                principal_type: string;
            }[];
            grants?: {
                actions: string[];
                principal?: string;
                principal_type: string;
            }[];
            remove?: { principal?: string; principal_type: string }[];
        };
        config?: string;
        description?: string;
        event_config?: Record<string, unknown>;
        event_type?: string;
        handler_type: string;
        lookup_key?: string;
        metadata?: Record<string, unknown>;
        name: string;
        preset_config?: {
            instructions?: string;
            llm?: { model?: string };
            session_mode?: string;
            session_scope?: string;
            structured_message_template_ids?: string[];
        };
        preset_name?: string;
        schedule?: string;
        script?: string;
        status?: string;
        steps?: {
            config?: string;
            handler_type: string;
            inputs?: Record<string, unknown>;
            name?: string;
            on_error?: string;
            output_key?: string;
            preset_config?: {
                instructions?: string;
                llm?: { model?: string };
                session_mode?: string;
                session_scope?: string;
                structured_message_template_ids?: string[];
            };
            preset_name?: string;
            script?: string;
        }[];
        trigger_context?: string;
    },
): Promise<AgentRoutine>
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.
Parameters
- agent: string
  Agent ID (agt_...) that this routine will be attached to.
- input: {
      acl?: {
          add?: { actions: string[]; principal?: string; principal_type: string }[];
          grants?: { actions: string[]; principal?: string; principal_type: string }[];
          remove?: { principal?: string; principal_type: string }[];
      };
      config?: string;
      description?: string;
      event_config?: Record<string, unknown>;
      event_type?: string;
      handler_type: string;
      lookup_key?: string;
      metadata?: Record<string, unknown>;
      name: string;
      preset_config?: {
          instructions?: string;
          llm?: { model?: string };
          session_mode?: string;
          session_scope?: string;
          structured_message_template_ids?: string[];
      };
      preset_name?: string;
      schedule?: string;
      script?: string;
      status?: string;
      steps?: {
          config?: string;
          handler_type: string;
          inputs?: Record<string, unknown>;
          name?: string;
          on_error?: string;
          output_key?: string;
          preset_config?: {
              instructions?: string;
              llm?: { model?: string };
              session_mode?: string;
              session_scope?: string;
              structured_message_template_ids?: string[];
          };
          preset_name?: string;
          script?: string;
      }[];
      trigger_context?: string;
  }
  Request body.
  - Optionalacl?: {
        add?: { actions: string[]; principal?: string; principal_type: string }[];
        grants?: { actions: string[]; principal?: string; principal_type: string }[];
        remove?: { principal?: string; principal_type: string }[];
    }
    Access control list governing who can read or manage this routine.
  - Optionalconfig?: string
    Workflow config ID (cfg_...). Required when handler_type is "workflow_graph".
  - Optionaldescription?: string
    Optional human-readable description of what this routine does.
  - Optionalevent_config?: Record<string, unknown>
    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").
  - Optionalevent_type?: string
    Event type that triggers this routine. Deprecated — use event_config instead.
  - handler_type: string
    Execution model for this routine. One of "workflow_graph", "script", "preset", or "chain".
  - Optionallookup_key?: string
    Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.
  - Optionalmetadata?: Record<string, unknown>
    Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.
  - name: string
    Human-readable display name for the routine.
  - Optionalpreset_config?: {
        instructions?: string;
        llm?: { model?: string };
        session_mode?: string;
        session_scope?: string;
        structured_message_template_ids?: string[];
    }
    Configuration passed to the preset at runtime. Used when handler_type is "preset".
  - Optionalpreset_name?: string
    Name of the registered preset to use. Required when handler_type is "preset".
  - Optionalschedule?: string
    Cron expression for time-triggered routines (e.g. "0 9 * * 1"). Must not be more frequent than once per hour.
  - Optionalscript?: string
    Inline script source. Required when handler_type is "script".
  - Optionalstatus?: string
    Initial lifecycle status. One of "draft" or "active". Defaults to "draft".
  - Optionalsteps?: {
        config?: string;
        handler_type: string;
        inputs?: Record<string, unknown>;
        name?: string;
        on_error?: string;
        output_key?: string;
        preset_config?: {
            instructions?: string;
            llm?: { model?: string };
            session_mode?: string;
            session_scope?: string;
            structured_message_template_ids?: string[];
        };
        preset_name?: string;
        script?: string;
    }[]
    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.
  - Optionaltrigger_context?: string
    Context in which the routine is triggered. One of "chat_session" or "event". Defaults to "event".
Returns Promise<AgentRoutine>
The newly created routine.
- Defined in packages/sdk/src/v1/resources/agents.ts:471

agentWorkingMemory

agentWorkingMemory(
agent: string,
params?: { page?: number; pageSize?: number; search?: string },
): Promise<WorkingMemoryEntryListResponse>
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.
Parameters
- agent: string
  Agent ID (agt_...) whose working memory entries to retrieve.
- Optionalparams: { page?: number; pageSize?: number; search?: string }
  Query parameters.
  - Optionalpage?: number
    Page number to retrieve, starting at 1. Defaults to 1.
  - OptionalpageSize?: number
    Number of entries to return per page. Defaults to 25.
  - Optionalsearch?: string
    Substring filter applied to entry keys (case-insensitive). Omit to return all keys.
Returns Promise<WorkingMemoryEntryListResponse>
Paginated list of working memory entries for the agent.
- Defined in packages/sdk/src/v1/resources/agents.ts:491

create

create(
    input: {
        acl?: {
            add?: {
                actions: string[];
                principal?: string;
                principal_type: string;
            }[];
            grants?: {
                actions: string[];
                principal?: string;
                principal_type: string;
            }[];
            remove?: { principal?: string; principal_type: string }[];
        };
        email?: string;
        identity?: string;
        lookup_key?: string;
        metadata?: Record<string, unknown>;
        model?: string;
        name?: string;
        org?: string;
        originator?: string;
        phone_number?: string;
        profile_picture?: { data: string; filename: string; mime_type: string };
        team?: string;
        template?: string;
        template_bundle?: {
            configs?: {
                content: string;
                content_type?: string;
                relative_path: string;
            }[];
            lookup_key_suffix?: string;
            setup_actions?: {
                depends_on?: string[];
                description?: string;
                kind: string;
                params?: Record<string, unknown>;
                required?: boolean;
                sort_order?: number;
                title: string;
                verify_config?: Record<string, unknown>;
            }[];
            skills?: {
                content: string;
                content_type?: string;
                files?: {
                    content: string;
                    content_type?: string;
                    relative_path: string;
                }[];
                relative_path: string;
            }[];
            template: {
                content: string;
                content_type?: string;
                relative_path: string;
            };
        };
        user?: string;
    },
): Promise<AgentCreateResponse>
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.
Parameters
- input: {
      acl?: {
          add?: { actions: string[]; principal?: string; principal_type: string }[];
          grants?: { actions: string[]; principal?: string; principal_type: string }[];
          remove?: { principal?: string; principal_type: string }[];
      };
      email?: string;
      identity?: string;
      lookup_key?: string;
      metadata?: Record<string, unknown>;
      model?: string;
      name?: string;
      org?: string;
      originator?: string;
      phone_number?: string;
      profile_picture?: { data: string; filename: string; mime_type: string };
      team?: string;
      template?: string;
      template_bundle?: {
          configs?: {
              content: string;
              content_type?: string;
              relative_path: string;
          }[];
          lookup_key_suffix?: string;
          setup_actions?: {
              depends_on?: string[];
              description?: string;
              kind: string;
              params?: Record<string, unknown>;
              required?: boolean;
              sort_order?: number;
              title: string;
              verify_config?: Record<string, unknown>;
          }[];
          skills?: {
              content: string;
              content_type?: string;
              files?: { content: string; content_type?: string; relative_path: string }[];
              relative_path: string;
          }[];
          template: {
              content: string;
              content_type?: string;
              relative_path: string;
          };
      };
      user?: string;
  }
  Request body.
  - Optionalacl?: {
        add?: { actions: string[]; principal?: string; principal_type: string }[];
        grants?: { actions: string[]; principal?: string; principal_type: string }[];
        remove?: { principal?: string; principal_type: string }[];
    }
    Access control list controlling which users, teams, or orgs can read or manage this agent.
  - Optionalemail?: string
    Email address assigned to the agent. Used as the agent's contact identity.
  - Optionalidentity?: string
    System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
  - Optionallookup_key?: string
    Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
  - Optionalmetadata?: Record<string, unknown>
    Arbitrary key-value map stored on the agent. Not interpreted by the platform.
  - Optionalmodel?: string
    Default AI model identifier for this agent, e.g. claude-sonnet-4-5. Overridden per-request when the caller specifies a model.
  - Optionalname?: string
    Display name for the agent. Required when neither template nor template_bundle is provided.
  - Optionalorg?: string
    Organization ID (org_...) that should own this agent. Mutually exclusive with team and user.
  - Optionaloriginator?: string
    Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
  - Optionalphone_number?: string
    Phone number assigned to the agent in E.164 format, e.g. +15550001234.
  - Optionalprofile_picture?: { data: string; filename: string; mime_type: string }
    Profile picture to attach to the agent. All three subfields are required when this object is present.
  - Optionalteam?: string
    Team ID (team_...) that should own this agent. Mutually exclusive with org and user.
  - Optionaltemplate?: string
    ID (cfg_...) or lookup_key of an existing AgentTemplate config to provision from. Mutually exclusive with template_bundle.
  - Optionaltemplate_bundle?: {
        configs?: {
            content: string;
            content_type?: string;
            relative_path: string;
        }[];
        lookup_key_suffix?: string;
        setup_actions?: {
            depends_on?: string[];
            description?: string;
            kind: string;
            params?: Record<string, unknown>;
            required?: boolean;
            sort_order?: number;
            title: string;
            verify_config?: Record<string, unknown>;
        }[];
        skills?: {
            content: string;
            content_type?: string;
            files?: { content: string; content_type?: string; relative_path: string }[];
            relative_path: string;
        }[];
        template: { content: string; content_type?: string; relative_path: string };
    }
    Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with template.
  - Optionaluser?: string
    User ID (usr_...) that should own this agent. Mutually exclusive with org and team.
Returns Promise<AgentCreateResponse>
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.
- Defined in packages/sdk/src/v1/resources/agents.ts:348

delete

delete(agent: string): Promise<void>
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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent to delete.
Returns Promise<void>
Empty body. Returns HTTP 204 on success.
- Defined in packages/sdk/src/v1/resources/agents.ts:362

export

export(
agent: string,
params?: { removeIdentity?: boolean },
): Promise<AgentExport>
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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent to export.
- Optionalparams: { removeIdentity?: boolean }
  Query parameters.
  - OptionalremoveIdentity?: boolean
    When true, strips instance-unique identity fields (email, phone_number) from the exported template so it can be reused as a generic blueprint.
Returns Promise<AgentExport>
Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content.
- Defined in packages/sdk/src/v1/resources/agents.ts:523

get

get(agent: string): Promise<Agent>
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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent to retrieve.
Returns Promise<Agent>
The requested agent.
- Defined in packages/sdk/src/v1/resources/agents.ts:375

health

health(agent: string): Promise<AgentHealth>
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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent to evaluate.
Returns Promise<AgentHealth>
Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions.
- Defined in packages/sdk/src/v1/resources/agents.ts:547

list

list(
    params?: {
        orgId?: string;
        page?: number;
        pageSize?: number;
        search?: string;
        solutionConfig?: string[];
        templateConfig?: string;
        user?: string;
    },
): Promise<AgentListResponse>
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.
Parameters
- Optionalparams: {
      orgId?: string;
      page?: number;
      pageSize?: number;
      search?: string;
      solutionConfig?: string[];
      templateConfig?: string;
      user?: string;
  }
  Query parameters.
  - OptionalorgId?: string
    Organization ID (org_...) to filter by. Returns only agents owned by this org.
  - Optionalpage?: number
    Page number to retrieve, 1-indexed. Defaults to 1.
  - OptionalpageSize?: number
    Number of agents to return per page. Defaults to 25.
  - Optionalsearch?: string
    Free-text search string matched against the agent name, org, team, and owner fields.
  - OptionalsolutionConfig?: string[]
    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.
  - OptionaltemplateConfig?: string
    Config ID (cfg_...) or lookup_key of an AgentTemplate. Returns only agents whose last applied template matches.
  - Optionaluser?: string
    User ID (usr_...) to filter by. Returns only agents owned by this user.
Returns Promise<AgentListResponse>
Paginated list of agents matching the supplied filters.
- Defined in packages/sdk/src/v1/resources/agents.ts:289

search

search(
    agent: string,
    input: {
        max_results?: number;
        mode?: string;
        query: string;
        recency_days?: number;
        source_types?: string[];
    },
): Promise<
    {
        data: | {
            content?: string;
            content_type?: string;
            created_at?: string;
            id: string;
            kind: "chunk";
            metadata?: Record<string, unknown>;
            raw_content?: Record<string, unknown>;
            type?: string;
        }
        | {
            id: string;
            kind: "document";
            metadata?: Record<string, unknown>;
            snippet?: string;
            title?: string;
            total_lines?: number;
            total_size?: number;
        }[];
    },
>
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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent whose knowledge base to search.
- input: {
      max_results?: number;
      mode?: string;
      query: string;
      recency_days?: number;
      source_types?: string[];
  }
  Request body.
  - Optionalmax_results?: number
    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.
  - Optionalmode?: string
    Retrieval strategy. One of "hybrid" (default), "vector", or "fulltext".
  - query: string
    Natural-language search query used to retrieve relevant knowledge items.
  - Optionalrecency_days?: number
    When set, restricts results to items indexed within the last N days.
  - Optionalsource_types?: string[]
    Array of source-type slugs used to filter chunk results, e.g. ["web", "file"]. Omit to include all source types.
Returns Promise<
    {
        data: | {
            content?: string;
            content_type?: string;
            created_at?: string;
            id: string;
            kind: "chunk";
            metadata?: Record<string, unknown>;
            raw_content?: Record<string, unknown>;
            type?: string;
        }
        | {
            id: string;
            kind: "document";
            metadata?: Record<string, unknown>;
            snippet?: string;
            title?: string;
            total_lines?: number;
            total_size?: number;
        }[];
    },
>
Successful response
- Defined in packages/sdk/src/v1/resources/agents.ts:574

threads

threads(
    agent: string,
    input: {
        skip_welcome_message?: boolean;
        thread: {
            description?: string;
            is_unlisted?: boolean;
            key?: string;
            metadata?: Record<string, unknown>;
            muted?: boolean;
            org?: string;
            settings?: Record<string, unknown>;
            title?: string;
        };
    },
): Promise<Thread>
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.
Parameters
- agent: string
  Agent ID (agt_...). The thread will be owned by this agent.
- input: {
      skip_welcome_message?: boolean;
      thread: {
          description?: string;
          is_unlisted?: boolean;
          key?: string;
          metadata?: Record<string, unknown>;
          muted?: boolean;
          org?: string;
          settings?: Record<string, unknown>;
          title?: string;
      };
  }
  Request body.
  - Optionalskip_welcome_message?: boolean
    When true, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to false.
  - thread: {
        description?: string;
        is_unlisted?: boolean;
        key?: string;
        metadata?: Record<string, unknown>;
        muted?: boolean;
        org?: string;
        settings?: Record<string, unknown>;
        title?: string;
    }
    Attributes for the new thread.
Returns Promise<Thread>
The newly created thread.
- Defined in packages/sdk/src/v1/resources/agents.ts:593

update

update(
    agent: string,
    input: {
        acl?: {
            add?: {
                actions: string[];
                principal?: string;
                principal_type: string;
            }[];
            grants?: {
                actions: string[];
                principal?: string;
                principal_type: string;
            }[];
            remove?: { principal?: string; principal_type: string }[];
        };
        email?: string;
        identity?: string;
        lookup_key?: string;
        metadata?: Record<string, unknown>;
        model?: string;
        name?: string;
        org?: string;
        originator?: string;
        phone_number?: string;
        profile_picture?: { data: string; filename: string; mime_type: string };
        team?: string;
        user?: 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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent to update.
- input: {
      acl?: {
          add?: { actions: string[]; principal?: string; principal_type: string }[];
          grants?: { actions: string[]; principal?: string; principal_type: string }[];
          remove?: { principal?: string; principal_type: string }[];
      };
      email?: string;
      identity?: string;
      lookup_key?: string;
      metadata?: Record<string, unknown>;
      model?: string;
      name?: string;
      org?: string;
      originator?: string;
      phone_number?: string;
      profile_picture?: { data: string; filename: string; mime_type: string };
      team?: string;
      user?: string;
  }
  Request body.
  - Optionalacl?: {
        add?: { actions: string[]; principal?: string; principal_type: string }[];
        grants?: { actions: string[]; principal?: string; principal_type: string }[];
        remove?: { principal?: string; principal_type: string }[];
    }
    Replacement access control list. Fully replaces the existing ACL.
  - Optionalemail?: string
    New email address for the agent.
  - Optionalidentity?: string
    Replacement identity system-prompt string describing who the agent is.
  - Optionallookup_key?: string
    New lookup_key slug. Must be unique within the owning app or org.
  - Optionalmetadata?: Record<string, unknown>
    Replacement key-value metadata map. The entire map is replaced, not merged.
  - Optionalmodel?: string
    New default AI model identifier, e.g. claude-sonnet-4-5. Pass an empty string to clear the agent's default model.
  - Optionalname?: string
    New display name for the agent.
  - Optionalorg?: string
    Organization ID (org_...) to transfer ownership to.
  - Optionaloriginator?: string
    Replacement originator label identifying the source or author of the agent.
  - Optionalphone_number?: string
    New phone number for the agent in E.164 format, e.g. +15550001234.
  - Optionalprofile_picture?: { data: string; filename: string; mime_type: string }
    Replacement profile picture. All three subfields are required when this object is present.
  - Optionalteam?: string
    Team ID (team_...) to transfer ownership to.
  - Optionaluser?: string
    User ID (usr_...) to transfer ownership to.
Returns Promise<Agent>
The updated agent with all current field values.
- Defined in packages/sdk/src/v1/resources/agents.ts:404

upgrade

upgrade(
    agent: string,
    input: {
        dry_run?: boolean;
        email?: string;
        expected_review_fingerprint?: string;
        identity?: string;
        metadata?: Record<string, unknown>;
        mode?: "reapply" | "replace";
        model?: string;
        name?: string;
        originator?: string;
        phone_number?: string;
        template?: string;
    },
): Promise<AgentUpgradeResponse>
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.
Parameters
- agent: string
  ID (agi_...) or lookup_key of the agent to upgrade.
- input: {
      dry_run?: boolean;
      email?: string;
      expected_review_fingerprint?: string;
      identity?: string;
      metadata?: Record<string, unknown>;
      mode?: "reapply" | "replace";
      model?: string;
      name?: string;
      originator?: string;
      phone_number?: string;
      template?: string;
  }
  Request body.
  - Optionaldry_run?: boolean
    When true, computes and returns the full upgrade diff without persisting any changes. Use with expected_review_fingerprint to guard the live apply.
  - Optionalemail?: string
    Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.
  - Optionalexpected_review_fingerprint?: string
    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.
  - Optionalidentity?: string
    Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.
  - Optionalmetadata?: Record<string, unknown>
    Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.
  - Optionalmode?: "reapply" | "replace"
    Upgrade mode. "reapply" (default) refreshes the agent's tracked template; "replace" moves the agent to a different template (requires template).
  - Optionalmodel?: string
    Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.
  - Optionalname?: string
    Instance-specific name override. Pins this value so the template upgrade does not overwrite it.
  - Optionaloriginator?: string
    Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.
  - Optionalphone_number?: string
    Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it.
  - Optionaltemplate?: string
    ID (cfg_...) or lookup_key of the target AgentTemplate config. Optional in "reapply" mode; required in "replace" mode.
Returns Promise<AgentUpgradeResponse>
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.
- Defined in packages/sdk/src/v1/resources/agents.ts:630

Class AgentResource

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns AgentResource

Properties

Readonlyagent_computers

Readonlyagent_env_vars

Readonlyagent_installations

Readonlyagent_tools

Readonlyschedules

Methods

agentHealthActions

Parameters

Optionalkind?: string[]

Optionalsource?: string[]

Optionalstatus?: string[]

Returns Promise<HealthActionListResponse>

agentRoutines

Parameters

Optionalacl?: { add?: { actions: string[]; principal?: string; principal_type: string }[]; grants?: { actions: string[]; principal?: string; principal_type: string }[]; remove?: { principal?: string; principal_type: string }[];}

Optionalconfig?: string

Optionaldescription?: string

Optionalevent_config?: Record<string, unknown>

Optionalevent_type?: string

handler_type: string

Optionallookup_key?: string

Optionalmetadata?: Record<string, unknown>

name: string

Optionalpreset_config?: { instructions?: string; llm?: { model?: string }; session_mode?: string; session_scope?: string; structured_message_template_ids?: string[];}

Optionalpreset_name?: string

Optionalschedule?: string

Optionalscript?: string

Optionalstatus?: string

Optionaltrigger_context?: string

Returns Promise<AgentRoutine>

agentWorkingMemory

Parameters

Optionalpage?: number

OptionalpageSize?: number

Optionalsearch?: string

Returns Promise<WorkingMemoryEntryListResponse>

create

Parameters

Optionalacl?: { add?: { actions: string[]; principal?: string; principal_type: string }[]; grants?: { actions: string[]; principal?: string; principal_type: string }[]; remove?: { principal?: string; principal_type: string }[];}

Optionalemail?: string

Optionalidentity?: string

Optionallookup_key?: string

Optionalmetadata?: Record<string, unknown>

Optionalmodel?: string

Optionalname?: string

Optionalorg?: string

Optionaloriginator?: string

Optionalphone_number?: string

Optionalprofile_picture?: { data: string; filename: string; mime_type: string }

Optionalteam?: string

Optionaltemplate?: string

Optionaluser?: string

Returns Promise<AgentCreateResponse>

delete

Parameters

Returns Promise<void>

export

Parameters

OptionalremoveIdentity?: boolean

Returns Promise<AgentExport>

get

Parameters

Returns Promise<Agent>

health

Parameters

Returns Promise<AgentHealth>

list

Parameters

OptionalorgId?: string

Optionalpage?: number

`Readonly`agent_computers

`Readonly`agent_env_vars

`Readonly`agent_installations

`Readonly`agent_tools

`Readonly`schedules

`Optional`kind?: string[]

`Optional`source?: string[]

`Optional`status?: string[]

`Optional`acl?: {
add?: { actions: string[]; principal?: string; principal_type: string }[];
grants?: { actions: string[]; principal?: string; principal_type: string }[];
remove?: { principal?: string; principal_type: string }[];
}

`Optional`config?: string

`Optional`description?: string

`Optional`event_config?: Record<string, unknown>

`Optional`event_type?: string

`Optional`lookup_key?: string

`Optional`metadata?: Record<string, unknown>

`Optional`preset_config?: {
instructions?: string;
llm?: { model?: string };
session_mode?: string;
session_scope?: string;
structured_message_template_ids?: string[];
}

`Optional`preset_name?: string

`Optional`schedule?: string

`Optional`script?: string

`Optional`status?: string

`Optional`trigger_context?: string

`Optional`page?: number

`Optional`pageSize?: number

`Optional`search?: string

`Optional`acl?: {
add?: { actions: string[]; principal?: string; principal_type: string }[];
grants?: { actions: string[]; principal?: string; principal_type: string }[];
remove?: { principal?: string; principal_type: string }[];
}

`Optional`email?: string

`Optional`identity?: string

`Optional`lookup_key?: string

`Optional`metadata?: Record<string, unknown>

`Optional`model?: string

`Optional`name?: string

`Optional`org?: string

`Optional`originator?: string

`Optional`phone_number?: string

`Optional`profile_picture?: { data: string; filename: string; mime_type: string }

`Optional`team?: string

`Optional`template?: string

`Optional`user?: string

`Optional`removeIdentity?: boolean

`Optional`orgId?: string

`Optional`page?: number

`Optional`pageSize?: number

`Optional`search?: string

`Optional`solutionConfig?: string[]

`Optional`templateConfig?: string

`Optional`user?: string

`Optional`max_results?: number

`Optional`mode?: string

`Optional`recency_days?: number

`Optional`source_types?: string[]

`Optional`skip_welcome_message?: boolean

thread: {
description?: string;
is_unlisted?: boolean;
key?: string;
metadata?: Record<string, unknown>;
muted?: boolean;
org?: string;
settings?: Record<string, unknown>;
title?: string;
}

`Optional`acl?: {
add?: { actions: string[]; principal?: string; principal_type: string }[];
grants?: { actions: string[]; principal?: string; principal_type: string }[];
remove?: { principal?: string; principal_type: string }[];
}

`Optional`email?: string

`Optional`identity?: string

`Optional`lookup_key?: string

`Optional`metadata?: Record<string, unknown>

`Optional`model?: string

`Optional`name?: string

`Optional`org?: string

`Optional`originator?: string

`Optional`phone_number?: string

`Optional`profile_picture?: { data: string; filename: string; mime_type: string }

`Optional`team?: string

`Optional`user?: string

`Optional`dry_run?: boolean

`Optional`email?: string

`Optional`expected_review_fingerprint?: string

`Optional`identity?: string

`Optional`metadata?: Record<string, unknown>

`Optional`mode?: "reapply" | "replace"

`Optional`model?: string

`Optional`name?: string

`Optional`originator?: string

`Optional`phone_number?: string

`Optional`template?: string