archastro.platform.v1.resources.agent_tools

  1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved.
  2# This file is auto-generated by @archastro/sdk-generator. Do not edit.
  3# Content hash: 3576c55aa9ad
  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: 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 this agent (`agt_...`). Omit to return tools across all agents in the app.
 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(self, *, agent: str | None = None, kind: str | None = None) -> AgentToolListResponse:
240        """
241        List agent tools
242        Returns all tools for the authenticated app, optionally filtered by agent
243        or tool kind. Both explicitly created tools and tools derived from connected
244        integrations (installation-sourced tools) are included in the response.
245        Installation-sourced tools appear with `source: "installation"` and
246        `status: "active"`. They are synthesized at request time from connected
247        integrations and do not have a persistent tool ID of the `atl_...` form;
248        their `id` is a composite of the installation ID and server tool type.
249        Use the `agent` filter to retrieve tools for a specific agent. Supplying an
250        `agent` ID that does not belong to the authenticated app returns 404.
251        Requires app scope.
252
253        Args:
254            agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app.
255            kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds.
256
257        Returns:
258            List of tools matching the supplied filters.
259        """
260        query: dict[str, object] = {}
261        if agent is not None:
262            query["agent"] = agent
263        if kind is not None:
264            query["kind"] = kind
265        return self._http.request(
266            "/api/v1/agent_tools",
267            query=query,
268            response_type=AgentToolListResponse,
269        )
270
271    def catalog(self) -> builtins.list[BuiltinToolCatalogEntry]:
272        """
273        List built-in tool categories
274        Returns the full catalog of built-in tool categories available on the platform.
275        Each entry describes a tool type that can be added to an agent, including its
276        key, display label, configuration schema, and the individual tools it exposes
277        to the LLM.
278        The catalog is global it is not filtered by app or agent. Use the `key` from
279        each entry as the `builtin_tool_key` when creating a built-in tool. Entries
280        whose `requires_integration` is `true` require a connected integration before
281        the tool can be activated on an agent.
282        Requires app scope.
283
284        Returns:
285            Array of built-in tool catalog entries, one per registered tool category.
286        """
287        return self._http.request(
288            "/api/v1/agent_tools/catalog",
289            response_type=list[BuiltinToolCatalogEntry],
290        )
291
292    def delete(self, tool: str) -> None:
293        """
294        Delete an agent tool
295        Permanently removes a tool from the agent. This action cannot be undone.
296        Both `"draft"` and `"active"` tools can be deleted. If you only want to
297        stop the agent from using a tool without removing it, use the deactivate
298        endpoint instead.
299        Requires app scope. The authenticated caller must own the tool's parent agent.
300
301        Args:
302            tool: Tool ID (`atl_...`) of the tool to delete.
303
304        Returns:
305            Empty response. Returns HTTP 204 on success.
306        """
307        self._http.request(f"/api/v1/agent_tools/{tool}", method="DELETE")
308
309    def get(self, tool: str) -> AgentTool:
310        """
311        Retrieve an agent tool
312        Returns the tool identified by `tool`. The tool must belong to an agent
313        owned by the authenticated app.
314        Use this endpoint to inspect a tool's current configuration, status, and
315        metadata. To retrieve all tools for an agent or app, use the list endpoint.
316        Requires app scope.
317
318        Args:
319            tool: Tool ID (`atl_...`) of the tool to retrieve.
320
321        Returns:
322            The requested tool.
323        """
324        return self._http.request(f"/api/v1/agent_tools/{tool}", response_type=AgentTool)
325
326    def update(self, tool: str, input: AgentToolUpdateInput) -> AgentTool:
327        """
328        Update an agent tool
329        Updates the configuration of an existing tool. All parameters are optional;
330        supply only the fields you want to change. Unspecified fields are left as-is.
331        You can update both `"draft"` and `"active"` tools. Updating an active tool
332        takes effect on the next agent run; any run already in progress continues
333        with the configuration it loaded at start.
334        Supplying `template` re-resolves the referenced AgentToolTemplate and patches
335        the tool in place, preserving its `status`, `lookup_key`, `kind`, and agent
336        association. Any other params you supply alongside `template` override the
337        template defaults.
338        Requires app scope. The authenticated caller must own the tool's parent agent.
339
340        Args:
341            tool: Tool ID (`atl_...`) of the tool to update.
342            input: Request body.
343            input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools.
344            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.
345            input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools.
346            input.description: Human-readable description of what the tool does, shown to the LLM as context. Applies primarily to `"custom"` tools.
347            input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools.
348            input.instruction: Additional natural-language instruction provided to the LLM describing when and how to call this tool. Supplements the tool's `description`.
349            input.lookup_key: Stable identifier you can use to look up this tool without its ID. Must be unique within the app.
350            input.metadata: Arbitrary key-value metadata to attach to the tool. Replaces the existing metadata when supplied.
351            input.name: Display name for the tool. Applies to `"custom"` tools.
352            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.
353            input.parameters: JSON Schema object describing the tool's input parameters. Replaces the existing parameter schema when supplied.
354            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.
355            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.
356
357        Returns:
358            The updated tool.
359        """
360        return self._http.request(
361            f"/api/v1/agent_tools/{tool}",
362            method="PATCH",
363            body=input,
364            response_type=AgentTool,
365        )
366
367    def activate(self, tool: str) -> AgentTool:
368        """
369        Activate an agent tool
370        Transitions a tool from `"draft"` status to `"active"`, making it available
371        for the agent to use during runs. Only tools in `"draft"` status can be
372        activated; calling this on an already-active tool is a no-op that returns the
373        current tool state.
374        Activation validates that all required configuration is present. For built-in
375        tools, this means the `builtin_tool_key` must resolve to a registered tool
376        type and any required integration must be connected. Returns 422 if
377        prerequisite checks fail.
378        Requires app scope. The authenticated caller must own the tool's parent agent.
379
380        Args:
381            tool: Tool ID (`atl_...`) of the tool to activate.
382
383        Returns:
384            The updated tool with `status: "active"`.
385        """
386        return self._http.request(
387            f"/api/v1/agent_tools/{tool}/activate",
388            method="POST",
389            response_type=AgentTool,
390        )
391
392    def deactivate(self, tool: str) -> AgentTool:
393        """
394        Deactivate an agent tool
395        Transitions a tool from `"active"` status back to `"draft"`, removing it
396        from the set of tools the agent can use during future runs. Calling this on a
397        tool that is already in `"draft"` status is a no-op that returns the current
398        tool state.
399        Deactivation does not delete the tool or its configuration. To remove the
400        tool permanently, use the delete endpoint.
401        Requires app scope. The authenticated caller must own the tool's parent agent.
402
403        Args:
404            tool: Tool ID (`atl_...`) of the tool to deactivate.
405
406        Returns:
407            The updated tool with `status: "draft"`.
408        """
409        return self._http.request(
410            f"/api/v1/agent_tools/{tool}/deactivate",
411            method="POST",
412            response_type=AgentTool,
413        )