archastro.platform.v1.resources.agent_tools

  1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 6a731ed08220
  4
  5from __future__ import annotations
  6
  7import builtins
  8from typing import Any, TypedDict
  9
 10from ...runtime.http_client import HttpClient, SyncHttpClient
 11from ...types.common import AgentTool, AgentToolListResponse, BuiltinToolCatalogEntry
 12
 13AgentToolUpdateInput = TypedDict(
 14    "AgentToolUpdateInput",
 15    {
 16        "async": bool | None,
 17        "builtin_tool_config": dict[str, Any] | None,
 18        "config": str | None,
 19        "description": str | None,
 20        "handler_type": str | None,
 21        "instruction": str | None,
 22        "lookup_key": str | None,
 23        "metadata": dict[str, Any] | None,
 24        "name": str | None,  # Display name for the tool. Applies to `"custom"` tools.
 25        "name_prefix": str | None,
 26        "parameters": dict[str, Any] | None,
 27        "parameters_config": str | None,
 28        "template": str | None,
 29    },
 30    total=False,
 31)
 32"""
 33Update an agent tool
 34
 35Attributes:
 36    async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools.
 37    builtin_tool_config: 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.
 38    config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools.
 39    description: Human-readable description of what the tool does, shown to the LLM as context. Applies primarily to `"custom"` tools.
 40    handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools.
 41    instruction: Additional natural-language instruction provided to the LLM describing when and how to call this tool. Supplements the tool's `description`.
 42    lookup_key: Stable identifier you can use to look up this tool without its ID. Must be unique within the app.
 43    metadata: Arbitrary key-value metadata to attach to the tool. Replaces the existing metadata when supplied.
 44    name: Display name for the tool. Applies to `"custom"` tools.
 45    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.
 46    parameters: JSON Schema object describing the tool's input parameters. Replaces the existing parameter schema when supplied.
 47    parameters_config: Config ID (`cfg_...`) referencing a reusable JSON Schema definition for this tool's input parameters. Takes precedence over an inline `parameters` value.
 48    template: 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.
 49"""
 50
 51
 52class AsyncAgentToolResource:
 53    def __init__(self, http: HttpClient):
 54        self._http = http
 55
 56    async def list(
 57        self, *, agent: builtins.list[str] | None = None, kind: str | None = None
 58    ) -> AgentToolListResponse:
 59        """
 60        List agent tools
 61        Returns all tools for the authenticated app, optionally filtered by agent
 62        or tool kind. Both explicitly created tools and tools derived from connected
 63        integrations (installation-sourced tools) are included in the response.
 64        Installation-sourced tools appear with `source: "installation"` and
 65        `status: "active"`. They are synthesized at request time from connected
 66        integrations and do not have a persistent tool ID of the `atl_...` form;
 67        their `id` is a composite of the installation ID and server tool type.
 68        Use the `agent` filter to retrieve tools for a specific agent. Supplying an
 69        `agent` ID that does not belong to the authenticated app returns 404.
 70        Requires app scope.
 71
 72        Args:
 73            agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd.
 74            kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds.
 75
 76        Returns:
 77            List of tools matching the supplied filters.
 78        """
 79        query: dict[str, object] = {}
 80        if agent is not None:
 81            query["agent"] = agent
 82        if kind is not None:
 83            query["kind"] = kind
 84        return await self._http.request(
 85            "/api/v1/agent_tools",
 86            query=query,
 87            response_type=AgentToolListResponse,
 88        )
 89
 90    async def catalog(self) -> builtins.list[BuiltinToolCatalogEntry]:
 91        """
 92        List built-in tool categories
 93        Returns the full catalog of built-in tool categories available on the platform.
 94        Each entry describes a tool type that can be added to an agent, including its
 95        key, display label, configuration schema, and the individual tools it exposes
 96        to the LLM.
 97        The catalog is global it is not filtered by app or agent. Use the `key` from
 98        each entry as the `builtin_tool_key` when creating a built-in tool. Entries
 99        whose `requires_integration` is `true` require a connected integration before
100        the tool can be activated on an agent.
101        Requires app scope.
102
103        Returns:
104            Array of built-in tool catalog entries, one per registered tool category.
105        """
106        return await self._http.request(
107            "/api/v1/agent_tools/catalog",
108            response_type=list[BuiltinToolCatalogEntry],
109        )
110
111    async def delete(self, tool: str) -> None:
112        """
113        Delete an agent tool
114        Permanently removes a tool from the agent. This action cannot be undone.
115        Both `"draft"` and `"active"` tools can be deleted. If you only want to
116        stop the agent from using a tool without removing it, use the deactivate
117        endpoint instead.
118        Requires app scope. The authenticated caller must own the tool's parent agent.
119
120        Args:
121            tool: Tool ID (`atl_...`) of the tool to delete.
122
123        Returns:
124            Empty response. Returns HTTP 204 on success.
125        """
126        await self._http.request(f"/api/v1/agent_tools/{tool}", method="DELETE")
127
128    async def get(self, tool: str) -> AgentTool:
129        """
130        Retrieve an agent tool
131        Returns the tool identified by `tool`. The tool must belong to an agent
132        owned by the authenticated app.
133        Use this endpoint to inspect a tool's current configuration, status, and
134        metadata. To retrieve all tools for an agent or app, use the list endpoint.
135        Requires app scope.
136
137        Args:
138            tool: Tool ID (`atl_...`) of the tool to retrieve.
139
140        Returns:
141            The requested tool.
142        """
143        return await self._http.request(f"/api/v1/agent_tools/{tool}", response_type=AgentTool)
144
145    async def update(self, tool: str, input: AgentToolUpdateInput) -> AgentTool:
146        """
147        Update an agent tool
148        Updates the configuration of an existing tool. All parameters are optional;
149        supply only the fields you want to change. Unspecified fields are left as-is.
150        You can update both `"draft"` and `"active"` tools. Updating an active tool
151        takes effect on the next agent run; any run already in progress continues
152        with the configuration it loaded at start.
153        Supplying `template` re-resolves the referenced AgentToolTemplate and patches
154        the tool in place, preserving its `status`, `lookup_key`, `kind`, and agent
155        association. Any other params you supply alongside `template` override the
156        template defaults.
157        Requires app scope. The authenticated caller must own the tool's parent agent.
158
159        Args:
160            tool: Tool ID (`atl_...`) of the tool to update.
161            input: Request body.
162            input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools.
163            input.builtin_tool_config: 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.
164            input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools.
165            input.description: Human-readable description of what the tool does, shown to the LLM as context. Applies primarily to `"custom"` tools.
166            input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools.
167            input.instruction: Additional natural-language instruction provided to the LLM describing when and how to call this tool. Supplements the tool's `description`.
168            input.lookup_key: Stable identifier you can use to look up this tool without its ID. Must be unique within the app.
169            input.metadata: Arbitrary key-value metadata to attach to the tool. Replaces the existing metadata when supplied.
170            input.name: Display name for the tool. Applies to `"custom"` tools.
171            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.
172            input.parameters: JSON Schema object describing the tool's input parameters. Replaces the existing parameter schema when supplied.
173            input.parameters_config: Config ID (`cfg_...`) referencing a reusable JSON Schema definition for this tool's input parameters. Takes precedence over an inline `parameters` value.
174            input.template: 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.
175
176        Returns:
177            The updated tool.
178        """
179        return await self._http.request(
180            f"/api/v1/agent_tools/{tool}",
181            method="PATCH",
182            body=input,
183            response_type=AgentTool,
184        )
185
186    async def activate(self, tool: str) -> AgentTool:
187        """
188        Activate an agent tool
189        Transitions a tool from `"draft"` status to `"active"`, making it available
190        for the agent to use during runs. Only tools in `"draft"` status can be
191        activated; calling this on an already-active tool is a no-op that returns the
192        current tool state.
193        Activation validates that all required configuration is present. For built-in
194        tools, this means the `builtin_tool_key` must resolve to a registered tool
195        type and any required integration must be connected. Returns 422 if
196        prerequisite checks fail.
197        Requires app scope. The authenticated caller must own the tool's parent agent.
198
199        Args:
200            tool: Tool ID (`atl_...`) of the tool to activate.
201
202        Returns:
203            The updated tool with `status: "active"`.
204        """
205        return await self._http.request(
206            f"/api/v1/agent_tools/{tool}/activate",
207            method="POST",
208            response_type=AgentTool,
209        )
210
211    async def deactivate(self, tool: str) -> AgentTool:
212        """
213        Deactivate an agent tool
214        Transitions a tool from `"active"` status back to `"draft"`, removing it
215        from the set of tools the agent can use during future runs. Calling this on a
216        tool that is already in `"draft"` status is a no-op that returns the current
217        tool state.
218        Deactivation does not delete the tool or its configuration. To remove the
219        tool permanently, use the delete endpoint.
220        Requires app scope. The authenticated caller must own the tool's parent agent.
221
222        Args:
223            tool: Tool ID (`atl_...`) of the tool to deactivate.
224
225        Returns:
226            The updated tool with `status: "draft"`.
227        """
228        return await self._http.request(
229            f"/api/v1/agent_tools/{tool}/deactivate",
230            method="POST",
231            response_type=AgentTool,
232        )
233
234
235class AgentToolResource:
236    def __init__(self, http: SyncHttpClient):
237        self._http = http
238
239    def list(
240        self, *, agent: builtins.list[str] | None = None, kind: str | None = None
241    ) -> AgentToolListResponse:
242        """
243        List agent tools
244        Returns all tools for the authenticated app, optionally filtered by agent
245        or tool kind. Both explicitly created tools and tools derived from connected
246        integrations (installation-sourced tools) are included in the response.
247        Installation-sourced tools appear with `source: "installation"` and
248        `status: "active"`. They are synthesized at request time from connected
249        integrations and do not have a persistent tool ID of the `atl_...` form;
250        their `id` is a composite of the installation ID and server tool type.
251        Use the `agent` filter to retrieve tools for a specific agent. Supplying an
252        `agent` ID that does not belong to the authenticated app returns 404.
253        Requires app scope.
254
255        Args:
256            agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd.
257            kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds.
258
259        Returns:
260            List of tools matching the supplied filters.
261        """
262        query: dict[str, object] = {}
263        if agent is not None:
264            query["agent"] = agent
265        if kind is not None:
266            query["kind"] = kind
267        return self._http.request(
268            "/api/v1/agent_tools",
269            query=query,
270            response_type=AgentToolListResponse,
271        )
272
273    def catalog(self) -> builtins.list[BuiltinToolCatalogEntry]:
274        """
275        List built-in tool categories
276        Returns the full catalog of built-in tool categories available on the platform.
277        Each entry describes a tool type that can be added to an agent, including its
278        key, display label, configuration schema, and the individual tools it exposes
279        to the LLM.
280        The catalog is global it is not filtered by app or agent. Use the `key` from
281        each entry as the `builtin_tool_key` when creating a built-in tool. Entries
282        whose `requires_integration` is `true` require a connected integration before
283        the tool can be activated on an agent.
284        Requires app scope.
285
286        Returns:
287            Array of built-in tool catalog entries, one per registered tool category.
288        """
289        return self._http.request(
290            "/api/v1/agent_tools/catalog",
291            response_type=list[BuiltinToolCatalogEntry],
292        )
293
294    def delete(self, tool: str) -> None:
295        """
296        Delete an agent tool
297        Permanently removes a tool from the agent. This action cannot be undone.
298        Both `"draft"` and `"active"` tools can be deleted. If you only want to
299        stop the agent from using a tool without removing it, use the deactivate
300        endpoint instead.
301        Requires app scope. The authenticated caller must own the tool's parent agent.
302
303        Args:
304            tool: Tool ID (`atl_...`) of the tool to delete.
305
306        Returns:
307            Empty response. Returns HTTP 204 on success.
308        """
309        self._http.request(f"/api/v1/agent_tools/{tool}", method="DELETE")
310
311    def get(self, tool: str) -> AgentTool:
312        """
313        Retrieve an agent tool
314        Returns the tool identified by `tool`. The tool must belong to an agent
315        owned by the authenticated app.
316        Use this endpoint to inspect a tool's current configuration, status, and
317        metadata. To retrieve all tools for an agent or app, use the list endpoint.
318        Requires app scope.
319
320        Args:
321            tool: Tool ID (`atl_...`) of the tool to retrieve.
322
323        Returns:
324            The requested tool.
325        """
326        return self._http.request(f"/api/v1/agent_tools/{tool}", response_type=AgentTool)
327
328    def update(self, tool: str, input: AgentToolUpdateInput) -> AgentTool:
329        """
330        Update an agent tool
331        Updates the configuration of an existing tool. All parameters are optional;
332        supply only the fields you want to change. Unspecified fields are left as-is.
333        You can update both `"draft"` and `"active"` tools. Updating an active tool
334        takes effect on the next agent run; any run already in progress continues
335        with the configuration it loaded at start.
336        Supplying `template` re-resolves the referenced AgentToolTemplate and patches
337        the tool in place, preserving its `status`, `lookup_key`, `kind`, and agent
338        association. Any other params you supply alongside `template` override the
339        template defaults.
340        Requires app scope. The authenticated caller must own the tool's parent agent.
341
342        Args:
343            tool: Tool ID (`atl_...`) of the tool to update.
344            input: Request body.
345            input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools.
346            input.builtin_tool_config: 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.
347            input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools.
348            input.description: Human-readable description of what the tool does, shown to the LLM as context. Applies primarily to `"custom"` tools.
349            input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools.
350            input.instruction: Additional natural-language instruction provided to the LLM describing when and how to call this tool. Supplements the tool's `description`.
351            input.lookup_key: Stable identifier you can use to look up this tool without its ID. Must be unique within the app.
352            input.metadata: Arbitrary key-value metadata to attach to the tool. Replaces the existing metadata when supplied.
353            input.name: Display name for the tool. Applies to `"custom"` tools.
354            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.
355            input.parameters: JSON Schema object describing the tool's input parameters. Replaces the existing parameter schema when supplied.
356            input.parameters_config: Config ID (`cfg_...`) referencing a reusable JSON Schema definition for this tool's input parameters. Takes precedence over an inline `parameters` value.
357            input.template: 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.
358
359        Returns:
360            The updated tool.
361        """
362        return self._http.request(
363            f"/api/v1/agent_tools/{tool}",
364            method="PATCH",
365            body=input,
366            response_type=AgentTool,
367        )
368
369    def activate(self, tool: str) -> AgentTool:
370        """
371        Activate an agent tool
372        Transitions a tool from `"draft"` status to `"active"`, making it available
373        for the agent to use during runs. Only tools in `"draft"` status can be
374        activated; calling this on an already-active tool is a no-op that returns the
375        current tool state.
376        Activation validates that all required configuration is present. For built-in
377        tools, this means the `builtin_tool_key` must resolve to a registered tool
378        type and any required integration must be connected. Returns 422 if
379        prerequisite checks fail.
380        Requires app scope. The authenticated caller must own the tool's parent agent.
381
382        Args:
383            tool: Tool ID (`atl_...`) of the tool to activate.
384
385        Returns:
386            The updated tool with `status: "active"`.
387        """
388        return self._http.request(
389            f"/api/v1/agent_tools/{tool}/activate",
390            method="POST",
391            response_type=AgentTool,
392        )
393
394    def deactivate(self, tool: str) -> AgentTool:
395        """
396        Deactivate an agent tool
397        Transitions a tool from `"active"` status back to `"draft"`, removing it
398        from the set of tools the agent can use during future runs. Calling this on a
399        tool that is already in `"draft"` status is a no-op that returns the current
400        tool state.
401        Deactivation does not delete the tool or its configuration. To remove the
402        tool permanently, use the delete endpoint.
403        Requires app scope. The authenticated caller must own the tool's parent agent.
404
405        Args:
406            tool: Tool ID (`atl_...`) of the tool to deactivate.
407
408        Returns:
409            The updated tool with `status: "draft"`.
410        """
411        return self._http.request(
412            f"/api/v1/agent_tools/{tool}/deactivate",
413            method="POST",
414            response_type=AgentTool,
415        )