Class AgentToolResource

Index

Constructors

constructor

Methods

activate catalog deactivate delete get list update

Constructors

constructor

new AgentToolResource(http: HttpClient): AgentToolResource
Parameters
- http: HttpClient
Returns AgentToolResource
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:9

Methods

activate

activate(tool: string): Promise<AgentTool>
Activate an agent tool Transitions a tool from "draft" status to "active", making it available for the agent to use during runs. Only tools in "draft" status can be activated; calling this on an already-active tool is a no-op that returns the current tool state. Activation validates that all required configuration is present. For built-in tools, this means the builtin_tool_key must resolve to a registered tool type and any required integration must be connected. Returns 422 if prerequisite checks fail. Requires app scope. The authenticated caller must own the tool's parent agent.
Parameters
- tool: string
  Tool ID (atl_...) of the tool to activate.
Returns Promise<AgentTool>
The updated tool with status: "active".
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:132

catalog

catalog(): Promise<BuiltinToolCatalogEntry[]>
List built-in tool categories Returns the full catalog of built-in tool categories available on the platform. Each entry describes a tool type that can be added to an agent, including its key, display label, configuration schema, and the individual tools it exposes to the LLM. The catalog is global — it is not filtered by app or agent. Use the key from each entry as the builtin_tool_key when creating a built-in tool. Entries whose requires_integration is true require a connected integration before the tool can be activated on an agent. Requires app scope.

Returns Promise<BuiltinToolCatalogEntry[]>
Array of built-in tool catalog entries, one per registered tool category.
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:53

deactivate

deactivate(tool: string): Promise<AgentTool>
Deactivate an agent tool Transitions a tool from "active" status back to "draft", removing it from the set of tools the agent can use during future runs. Calling this on a tool that is already in "draft" status is a no-op that returns the current tool state. Deactivation does not delete the tool or its configuration. To remove the tool permanently, use the delete endpoint. Requires app scope. The authenticated caller must own the tool's parent agent.
Parameters
- tool: string
  Tool ID (atl_...) of the tool to deactivate.
Returns Promise<AgentTool>
The updated tool with status: "draft".
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:148

delete

delete(tool: string): Promise<void>
Delete an agent tool Permanently removes a tool from the agent. This action cannot be undone. Both "draft" and "active" tools can be deleted. If you only want to stop the agent from using a tool without removing it, use the deactivate endpoint instead. Requires app scope. The authenticated caller must own the tool's parent agent.
Parameters
- tool: string
  Tool ID (atl_...) of the tool to delete.
Returns Promise<void>
Empty response. Returns HTTP 204 on success.
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:67

get

get(tool: string): Promise<AgentTool>
Retrieve an agent tool Returns the tool identified by tool. The tool must belong to an agent owned by the authenticated app. Use this endpoint to inspect a tool's current configuration, status, and metadata. To retrieve all tools for an agent or app, use the list endpoint. Requires app scope.
Parameters
- tool: string
  Tool ID (atl_...) of the tool to retrieve.
Returns Promise<AgentTool>
The requested tool.
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:81

list

list(params?: { agent?: string; kind?: string }): Promise<AgentToolListResponse>
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.
Parameters
- Optionalparams: { agent?: string; kind?: string }
  Query parameters.
  - Optionalagent?: string
    Filter results to tools belonging to this agent (agt_...). Omit to return tools across all agents in the app.
  - Optionalkind?: string
    Filter by tool kind. One of "builtin" or "custom". Omit to return tools of all kinds.
Returns Promise<AgentToolListResponse>
List of tools matching the supplied filters.
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:28

update

update(
    tool: string,
    input: {
        async?: boolean;
        builtin_tool_config?: Record<string, unknown>;
        config?: string;
        description?: string;
        handler_type?: string;
        instruction?: string;
        lookup_key?: string;
        metadata?: Record<string, unknown>;
        name?: string;
        name_prefix?: string;
        parameters?: Record<string, unknown>;
        parameters_config?: string;
        template?: string;
    },
): Promise<AgentTool>
Update an agent tool Updates the configuration of an existing tool. All parameters are optional; supply only the fields you want to change. Unspecified fields are left as-is. You can update both "draft" and "active" tools. Updating an active tool takes effect on the next agent run; any run already in progress continues with the configuration it loaded at start. Supplying template re-resolves the referenced AgentToolTemplate and patches the tool in place, preserving its status, lookup_key, kind, and agent association. Any other params you supply alongside template override the template defaults. Requires app scope. The authenticated caller must own the tool's parent agent.
Parameters
- tool: string
  Tool ID (atl_...) of the tool to update.
- input: {
      async?: boolean;
      builtin_tool_config?: Record<string, unknown>;
      config?: string;
      description?: string;
      handler_type?: string;
      instruction?: string;
      lookup_key?: string;
      metadata?: Record<string, unknown>;
      name?: string;
      name_prefix?: string;
      parameters?: Record<string, unknown>;
      parameters_config?: string;
      template?: string;
  }
  Request body.
  - Optionalasync?: boolean
    When true, the tool executes asynchronously and the agent does not block waiting for a result. Applies to "custom" tools.
  - Optionalbuiltin_tool_config?: Record<string, unknown>
    Configuration object for the built-in tool. Shape is defined by the catalog entry's config_schema for the tool's builtin_tool_key. Applies to "builtin" tools.
  - Optionalconfig?: string
    Config ID (cfg_...) referencing the script or workflow graph that implements the tool handler. Applies to "custom" tools.
  - Optionaldescription?: string
    Human-readable description of what the tool does, shown to the LLM as context. Applies primarily to "custom" tools.
  - Optionalhandler_type?: string
    Execution handler for the tool. One of "script" or "workflow_graph". Applies to "custom" tools.
  - Optionalinstruction?: string
    Additional natural-language instruction provided to the LLM describing when and how to call this tool. Supplements the tool's description.
  - Optionallookup_key?: string
    Stable identifier you can use to look up this tool without its ID. Must be unique within the app.
  - Optionalmetadata?: Record<string, unknown>
    Arbitrary key-value metadata to attach to the tool. Replaces the existing metadata when supplied.
  - Optionalname?: string
    Display name for the tool. Applies to "custom" tools.
  - Optionalname_prefix?: string
    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.
  - Optionalparameters?: Record<string, unknown>
    JSON Schema object describing the tool's input parameters. Replaces the existing parameter schema when supplied.
  - Optionalparameters_config?: string
    Config ID (cfg_...) referencing a reusable JSON Schema definition for this tool's input parameters. Takes precedence over an inline parameters value.
  - Optionaltemplate?: string
    Config ID or lookup key of an AgentToolTemplate. When provided, re-resolves the template and patches the tool in place, preserving its status, lookup_key, kind, and agent association. Other params you supply alongside template override the template defaults.
Returns Promise<AgentTool>
The updated tool.
- Defined in packages/sdk/src/v1/resources/agent_tools.ts:114

Class AgentToolResource

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns AgentToolResource

Methods

activate

Parameters

Returns Promise<AgentTool>

catalog

Returns Promise<BuiltinToolCatalogEntry[]>

deactivate

Parameters

Returns Promise<AgentTool>

delete

Parameters

Returns Promise<void>

get

Parameters

Returns Promise<AgentTool>

list

Parameters

Optionalagent?: string

Optionalkind?: string

Returns Promise<AgentToolListResponse>

update

Parameters

Optionalasync?: boolean

Optionalbuiltin_tool_config?: Record<string, unknown>

Optionalconfig?: string

Optionaldescription?: string

Optionalhandler_type?: string

Optionalinstruction?: string

Optionallookup_key?: string

Optionalmetadata?: Record<string, unknown>

Optionalname?: string

Optionalname_prefix?: string

Optionalparameters?: Record<string, unknown>

Optionalparameters_config?: string

Optionaltemplate?: string

Returns Promise<AgentTool>

Settings

On This Page

`Optional`agent?: string

`Optional`kind?: string

`Optional`async?: boolean

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

`Optional`config?: string

`Optional`description?: string

`Optional`handler_type?: string

`Optional`instruction?: string

`Optional`lookup_key?: string

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

`Optional`name?: string

`Optional`name_prefix?: string

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

`Optional`parameters_config?: string

`Optional`template?: string