archastro.platform.v1.resources.agent_skills

View Source

  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: 296846bfd227
  4
  5from __future__ import annotations
  6
  7import builtins
  8from typing import Any, Required, TypedDict
  9
 10from ...runtime.http_client import HttpClient, SyncHttpClient
 11from ...types.common import AgentSkill, AgentSkillList
 12
 13
 14class AgentSkillCreateInput(TypedDict, total=False):
 15    "Enable a skill on an agent"
 16
 17    agent: Required[str]
 18    "Agent ID (`agt_...`) to attach the skill to."
 19    config: Required[str]
 20    "Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app."
 21    instruction: str | None
 22    "Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent."
 23    metadata: dict[str, Any] | None
 24    "Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels."
 25
 26
 27class AgentSkillUpdateInput(TypedDict, total=False):
 28    "Update an agent skill"
 29
 30    instruction: str | None
 31    "Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged."
 32    metadata: dict[str, Any] | None
 33    "Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged."
 34    template: str | None
 35    "Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults."
 36
 37
 38class AsyncAgentSkillResource:
 39    def __init__(self, http: HttpClient):
 40        self._http = http
 41
 42    async def list(self, *, agent: builtins.list[str] | None = None) -> AgentSkillList:
 43        """
 44        List agent skills
 45        Returns all agent skills belonging to the authenticated app. Results include
 46        skills in any status (`"active"` or `"inactive"`). Use the `agent` filter to
 47        narrow results to one or more specific agents.
 48        Requires an app-scoped API key. Supplying one or more `agent` values that
 49        cannot be resolved within the app returns 404.
 50
 51        Args:
 52            agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (`agt_...`) or lookup keys. Omit to return skills across all agents in the app.
 53
 54        Returns:
 55            List of agent skills matching the query.
 56        """
 57        query: dict[str, object] = {}
 58        if agent is not None:
 59            query["agent"] = agent
 60        return await self._http.request(
 61            "/api/v1/agent_skills",
 62            query=query,
 63            response_type=AgentSkillList,
 64        )
 65
 66    async def create(self, input: AgentSkillCreateInput) -> AgentSkill:
 67        """
 68        Enable a skill on an agent
 69        Attaches a skill config to an agent, creating an agent skill record and
 70        returning it with an initial status of `"inactive"`. Use the activate
 71        endpoint to make the skill available during agent runs.
 72        Requires an app-scoped API key. The `agent` and `config` must both belong
 73        to the authenticated app. Supplying a `config` that does not exist within
 74        the app returns 422. Returns 201 on success.
 75
 76        Args:
 77            input: Request body.
 78            input.agent: Agent ID (`agt_...`) to attach the skill to.
 79            input.config: Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app.
 80            input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
 81            input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
 82
 83        Returns:
 84            The newly created agent skill record.
 85        """
 86        return await self._http.request(
 87            "/api/v1/agent_skills",
 88            method="POST",
 89            body=input,
 90            response_type=AgentSkill,
 91        )
 92
 93    async def delete(self, agent_skill: str) -> None:
 94        """
 95        Remove a skill from an agent
 96        Permanently removes the specified agent skill, detaching the skill config
 97        from the agent. This action cannot be undone. To temporarily stop a skill
 98        from being invoked without removing it, use the deactivate endpoint instead.
 99        Requires an app-scoped API key. Returns 204 No Content on success.
100
101        Args:
102            agent_skill: Agent skill ID (`ask_...`) to remove.
103
104        Returns:
105            No content
106        """
107        await self._http.request(f"/api/v1/agent_skills/{agent_skill}", method="DELETE")
108
109    async def get(self, agent_skill: str) -> AgentSkill:
110        """
111        Retrieve an agent skill
112        Returns the agent skill identified by its ID. The skill must belong to
113        the authenticated app's scope.
114        Requires an app-scoped API key.
115
116        Args:
117            agent_skill: Agent skill ID (`ask_...`) to retrieve.
118
119        Returns:
120            The requested agent skill.
121        """
122        return await self._http.request(
123            f"/api/v1/agent_skills/{agent_skill}",
124            response_type=AgentSkill,
125        )
126
127    async def update(self, agent_skill: str, input: AgentSkillUpdateInput) -> AgentSkill:
128        """
129        Update an agent skill
130        Updates one or more mutable fields on the specified agent skill. All
131        parameters are optional; supply only the fields you want to change.
132        When `template` is provided, the platform re-resolves that skill template
133        and re-points the skill's underlying config in place. The skill's current
134        status is preserved. Any `instruction` or `metadata` supplied alongside
135        `template` override the template's defaults.
136        Requires an app-scoped API key. The skill must belong to the authenticated
137        app's scope.
138
139        Args:
140            agent_skill: Agent skill ID (`ask_...`) to update.
141            input: Request body.
142            input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
143            input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
144            input.template: Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults.
145
146        Returns:
147            The agent skill after the update has been applied.
148        """
149        return await self._http.request(
150            f"/api/v1/agent_skills/{agent_skill}",
151            method="PATCH",
152            body=input,
153            response_type=AgentSkill,
154        )
155
156    async def activate(self, agent_skill: str) -> AgentSkill:
157        """
158        Activate an agent skill
159        Sets the status of the specified agent skill to `"active"`, allowing the
160        skill to be invoked during agent runs. The skill must already exist on the
161        agent (created via the enable endpoint) and belong to the authenticated
162        app's scope.
163        Requires an app-scoped API key. Activating a skill that is already active
164        is a no-op and returns the skill unchanged.
165
166        Args:
167            agent_skill: Agent skill ID (`ask_...`) to activate.
168
169        Returns:
170            The agent skill after activation, with `status` set to `"active"`.
171        """
172        return await self._http.request(
173            f"/api/v1/agent_skills/{agent_skill}/activate",
174            method="POST",
175            response_type=AgentSkill,
176        )
177
178    async def deactivate(self, agent_skill: str) -> AgentSkill:
179        """
180        Deactivate an agent skill
181        Sets the status of the specified agent skill to `"inactive"`, preventing
182        the skill from being invoked during future agent runs. The skill record
183        is preserved and can be reactivated at any time.
184        Requires an app-scoped API key. Deactivating a skill that is already
185        inactive is a no-op and returns the skill unchanged.
186
187        Args:
188            agent_skill: Agent skill ID (`ask_...`) to deactivate.
189
190        Returns:
191            The agent skill after deactivation, with `status` set to `"inactive"`.
192        """
193        return await self._http.request(
194            f"/api/v1/agent_skills/{agent_skill}/deactivate",
195            method="POST",
196            response_type=AgentSkill,
197        )
198
199
200class AgentSkillResource:
201    def __init__(self, http: SyncHttpClient):
202        self._http = http
203
204    def list(self, *, agent: builtins.list[str] | None = None) -> AgentSkillList:
205        """
206        List agent skills
207        Returns all agent skills belonging to the authenticated app. Results include
208        skills in any status (`"active"` or `"inactive"`). Use the `agent` filter to
209        narrow results to one or more specific agents.
210        Requires an app-scoped API key. Supplying one or more `agent` values that
211        cannot be resolved within the app returns 404.
212
213        Args:
214            agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (`agt_...`) or lookup keys. Omit to return skills across all agents in the app.
215
216        Returns:
217            List of agent skills matching the query.
218        """
219        query: dict[str, object] = {}
220        if agent is not None:
221            query["agent"] = agent
222        return self._http.request(
223            "/api/v1/agent_skills",
224            query=query,
225            response_type=AgentSkillList,
226        )
227
228    def create(self, input: AgentSkillCreateInput) -> AgentSkill:
229        """
230        Enable a skill on an agent
231        Attaches a skill config to an agent, creating an agent skill record and
232        returning it with an initial status of `"inactive"`. Use the activate
233        endpoint to make the skill available during agent runs.
234        Requires an app-scoped API key. The `agent` and `config` must both belong
235        to the authenticated app. Supplying a `config` that does not exist within
236        the app returns 422. Returns 201 on success.
237
238        Args:
239            input: Request body.
240            input.agent: Agent ID (`agt_...`) to attach the skill to.
241            input.config: Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app.
242            input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
243            input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
244
245        Returns:
246            The newly created agent skill record.
247        """
248        return self._http.request(
249            "/api/v1/agent_skills",
250            method="POST",
251            body=input,
252            response_type=AgentSkill,
253        )
254
255    def delete(self, agent_skill: str) -> None:
256        """
257        Remove a skill from an agent
258        Permanently removes the specified agent skill, detaching the skill config
259        from the agent. This action cannot be undone. To temporarily stop a skill
260        from being invoked without removing it, use the deactivate endpoint instead.
261        Requires an app-scoped API key. Returns 204 No Content on success.
262
263        Args:
264            agent_skill: Agent skill ID (`ask_...`) to remove.
265
266        Returns:
267            No content
268        """
269        self._http.request(f"/api/v1/agent_skills/{agent_skill}", method="DELETE")
270
271    def get(self, agent_skill: str) -> AgentSkill:
272        """
273        Retrieve an agent skill
274        Returns the agent skill identified by its ID. The skill must belong to
275        the authenticated app's scope.
276        Requires an app-scoped API key.
277
278        Args:
279            agent_skill: Agent skill ID (`ask_...`) to retrieve.
280
281        Returns:
282            The requested agent skill.
283        """
284        return self._http.request(f"/api/v1/agent_skills/{agent_skill}", response_type=AgentSkill)
285
286    def update(self, agent_skill: str, input: AgentSkillUpdateInput) -> AgentSkill:
287        """
288        Update an agent skill
289        Updates one or more mutable fields on the specified agent skill. All
290        parameters are optional; supply only the fields you want to change.
291        When `template` is provided, the platform re-resolves that skill template
292        and re-points the skill's underlying config in place. The skill's current
293        status is preserved. Any `instruction` or `metadata` supplied alongside
294        `template` override the template's defaults.
295        Requires an app-scoped API key. The skill must belong to the authenticated
296        app's scope.
297
298        Args:
299            agent_skill: Agent skill ID (`ask_...`) to update.
300            input: Request body.
301            input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
302            input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
303            input.template: Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults.
304
305        Returns:
306            The agent skill after the update has been applied.
307        """
308        return self._http.request(
309            f"/api/v1/agent_skills/{agent_skill}",
310            method="PATCH",
311            body=input,
312            response_type=AgentSkill,
313        )
314
315    def activate(self, agent_skill: str) -> AgentSkill:
316        """
317        Activate an agent skill
318        Sets the status of the specified agent skill to `"active"`, allowing the
319        skill to be invoked during agent runs. The skill must already exist on the
320        agent (created via the enable endpoint) and belong to the authenticated
321        app's scope.
322        Requires an app-scoped API key. Activating a skill that is already active
323        is a no-op and returns the skill unchanged.
324
325        Args:
326            agent_skill: Agent skill ID (`ask_...`) to activate.
327
328        Returns:
329            The agent skill after activation, with `status` set to `"active"`.
330        """
331        return self._http.request(
332            f"/api/v1/agent_skills/{agent_skill}/activate",
333            method="POST",
334            response_type=AgentSkill,
335        )
336
337    def deactivate(self, agent_skill: str) -> AgentSkill:
338        """
339        Deactivate an agent skill
340        Sets the status of the specified agent skill to `"inactive"`, preventing
341        the skill from being invoked during future agent runs. The skill record
342        is preserved and can be reactivated at any time.
343        Requires an app-scoped API key. Deactivating a skill that is already
344        inactive is a no-op and returns the skill unchanged.
345
346        Args:
347            agent_skill: Agent skill ID (`ask_...`) to deactivate.
348
349        Returns:
350            The agent skill after deactivation, with `status` set to `"inactive"`.
351        """
352        return self._http.request(
353            f"/api/v1/agent_skills/{agent_skill}/deactivate",
354            method="POST",
355            response_type=AgentSkill,
356        )

class AgentSkillCreateInput(typing.TypedDict): View Source

15class AgentSkillCreateInput(TypedDict, total=False):
16    "Enable a skill on an agent"
17
18    agent: Required[str]
19    "Agent ID (`agt_...`) to attach the skill to."
20    config: Required[str]
21    "Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app."
22    instruction: str | None
23    "Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent."
24    metadata: dict[str, Any] | None
25    "Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels."

Enable a skill on an agent

agent: Required[str]

Agent ID (agt_...) to attach the skill to.

config: Required[str]

Skill config ID (cfg_...) that defines the skill's behavior. Must belong to the authenticated app.

instruction: str | None

Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.

metadata: dict[str, typing.Any] | None

Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.

class AgentSkillUpdateInput(typing.TypedDict): View Source

28class AgentSkillUpdateInput(TypedDict, total=False):
29    "Update an agent skill"
30
31    instruction: str | None
32    "Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged."
33    metadata: dict[str, Any] | None
34    "Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged."
35    template: str | None
36    "Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults."

Update an agent skill

instruction: str | None

Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.

metadata: dict[str, typing.Any] | None

Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.

template: str | None

Agent skill template config ID (cfg_...), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any instruction or metadata values provided alongside template override the template defaults.

class AsyncAgentSkillResource: View Source

 39class AsyncAgentSkillResource:
 40    def __init__(self, http: HttpClient):
 41        self._http = http
 42
 43    async def list(self, *, agent: builtins.list[str] | None = None) -> AgentSkillList:
 44        """
 45        List agent skills
 46        Returns all agent skills belonging to the authenticated app. Results include
 47        skills in any status (`"active"` or `"inactive"`). Use the `agent` filter to
 48        narrow results to one or more specific agents.
 49        Requires an app-scoped API key. Supplying one or more `agent` values that
 50        cannot be resolved within the app returns 404.
 51
 52        Args:
 53            agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (`agt_...`) or lookup keys. Omit to return skills across all agents in the app.
 54
 55        Returns:
 56            List of agent skills matching the query.
 57        """
 58        query: dict[str, object] = {}
 59        if agent is not None:
 60            query["agent"] = agent
 61        return await self._http.request(
 62            "/api/v1/agent_skills",
 63            query=query,
 64            response_type=AgentSkillList,
 65        )
 66
 67    async def create(self, input: AgentSkillCreateInput) -> AgentSkill:
 68        """
 69        Enable a skill on an agent
 70        Attaches a skill config to an agent, creating an agent skill record and
 71        returning it with an initial status of `"inactive"`. Use the activate
 72        endpoint to make the skill available during agent runs.
 73        Requires an app-scoped API key. The `agent` and `config` must both belong
 74        to the authenticated app. Supplying a `config` that does not exist within
 75        the app returns 422. Returns 201 on success.
 76
 77        Args:
 78            input: Request body.
 79            input.agent: Agent ID (`agt_...`) to attach the skill to.
 80            input.config: Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app.
 81            input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
 82            input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
 83
 84        Returns:
 85            The newly created agent skill record.
 86        """
 87        return await self._http.request(
 88            "/api/v1/agent_skills",
 89            method="POST",
 90            body=input,
 91            response_type=AgentSkill,
 92        )
 93
 94    async def delete(self, agent_skill: str) -> None:
 95        """
 96        Remove a skill from an agent
 97        Permanently removes the specified agent skill, detaching the skill config
 98        from the agent. This action cannot be undone. To temporarily stop a skill
 99        from being invoked without removing it, use the deactivate endpoint instead.
100        Requires an app-scoped API key. Returns 204 No Content on success.
101
102        Args:
103            agent_skill: Agent skill ID (`ask_...`) to remove.
104
105        Returns:
106            No content
107        """
108        await self._http.request(f"/api/v1/agent_skills/{agent_skill}", method="DELETE")
109
110    async def get(self, agent_skill: str) -> AgentSkill:
111        """
112        Retrieve an agent skill
113        Returns the agent skill identified by its ID. The skill must belong to
114        the authenticated app's scope.
115        Requires an app-scoped API key.
116
117        Args:
118            agent_skill: Agent skill ID (`ask_...`) to retrieve.
119
120        Returns:
121            The requested agent skill.
122        """
123        return await self._http.request(
124            f"/api/v1/agent_skills/{agent_skill}",
125            response_type=AgentSkill,
126        )
127
128    async def update(self, agent_skill: str, input: AgentSkillUpdateInput) -> AgentSkill:
129        """
130        Update an agent skill
131        Updates one or more mutable fields on the specified agent skill. All
132        parameters are optional; supply only the fields you want to change.
133        When `template` is provided, the platform re-resolves that skill template
134        and re-points the skill's underlying config in place. The skill's current
135        status is preserved. Any `instruction` or `metadata` supplied alongside
136        `template` override the template's defaults.
137        Requires an app-scoped API key. The skill must belong to the authenticated
138        app's scope.
139
140        Args:
141            agent_skill: Agent skill ID (`ask_...`) to update.
142            input: Request body.
143            input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
144            input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
145            input.template: Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults.
146
147        Returns:
148            The agent skill after the update has been applied.
149        """
150        return await self._http.request(
151            f"/api/v1/agent_skills/{agent_skill}",
152            method="PATCH",
153            body=input,
154            response_type=AgentSkill,
155        )
156
157    async def activate(self, agent_skill: str) -> AgentSkill:
158        """
159        Activate an agent skill
160        Sets the status of the specified agent skill to `"active"`, allowing the
161        skill to be invoked during agent runs. The skill must already exist on the
162        agent (created via the enable endpoint) and belong to the authenticated
163        app's scope.
164        Requires an app-scoped API key. Activating a skill that is already active
165        is a no-op and returns the skill unchanged.
166
167        Args:
168            agent_skill: Agent skill ID (`ask_...`) to activate.
169
170        Returns:
171            The agent skill after activation, with `status` set to `"active"`.
172        """
173        return await self._http.request(
174            f"/api/v1/agent_skills/{agent_skill}/activate",
175            method="POST",
176            response_type=AgentSkill,
177        )
178
179    async def deactivate(self, agent_skill: str) -> AgentSkill:
180        """
181        Deactivate an agent skill
182        Sets the status of the specified agent skill to `"inactive"`, preventing
183        the skill from being invoked during future agent runs. The skill record
184        is preserved and can be reactivated at any time.
185        Requires an app-scoped API key. Deactivating a skill that is already
186        inactive is a no-op and returns the skill unchanged.
187
188        Args:
189            agent_skill: Agent skill ID (`ask_...`) to deactivate.
190
191        Returns:
192            The agent skill after deactivation, with `status` set to `"inactive"`.
193        """
194        return await self._http.request(
195            f"/api/v1/agent_skills/{agent_skill}/deactivate",
196            method="POST",
197            response_type=AgentSkill,
198        )

AsyncAgentSkillResource(http: archastro.platform.runtime.http_client.HttpClient) View Source

40    def __init__(self, http: HttpClient):
41        self._http = http

async def list( self, *, agent: list[str] | None = None) -> archastro.platform.types.common.AgentSkillList: View Source

43    async def list(self, *, agent: builtins.list[str] | None = None) -> AgentSkillList:
44        """
45        List agent skills
46        Returns all agent skills belonging to the authenticated app. Results include
47        skills in any status (`"active"` or `"inactive"`). Use the `agent` filter to
48        narrow results to one or more specific agents.
49        Requires an app-scoped API key. Supplying one or more `agent` values that
50        cannot be resolved within the app returns 404.
51
52        Args:
53            agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (`agt_...`) or lookup keys. Omit to return skills across all agents in the app.
54
55        Returns:
56            List of agent skills matching the query.
57        """
58        query: dict[str, object] = {}
59        if agent is not None:
60            query["agent"] = agent
61        return await self._http.request(
62            "/api/v1/agent_skills",
63            query=query,
64            response_type=AgentSkillList,
65        )

List agent skills Returns all agent skills belonging to the authenticated app. Results include skills in any status ("active" or "inactive"). Use the agent filter to narrow results to one or more specific agents. Requires an app-scoped API key. Supplying one or more agent values that cannot be resolved within the app returns 404.

Arguments:

agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (agt_...) or lookup keys. Omit to return skills across all agents in the app.

Returns:

List of agent skills matching the query.

async def create( self, input: AgentSkillCreateInput) -> archastro.platform.types.common.AgentSkill: View Source

67    async def create(self, input: AgentSkillCreateInput) -> AgentSkill:
68        """
69        Enable a skill on an agent
70        Attaches a skill config to an agent, creating an agent skill record and
71        returning it with an initial status of `"inactive"`. Use the activate
72        endpoint to make the skill available during agent runs.
73        Requires an app-scoped API key. The `agent` and `config` must both belong
74        to the authenticated app. Supplying a `config` that does not exist within
75        the app returns 422. Returns 201 on success.
76
77        Args:
78            input: Request body.
79            input.agent: Agent ID (`agt_...`) to attach the skill to.
80            input.config: Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app.
81            input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
82            input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
83
84        Returns:
85            The newly created agent skill record.
86        """
87        return await self._http.request(
88            "/api/v1/agent_skills",
89            method="POST",
90            body=input,
91            response_type=AgentSkill,
92        )

Enable a skill on an agent Attaches a skill config to an agent, creating an agent skill record and returning it with an initial status of "inactive". Use the activate endpoint to make the skill available during agent runs. Requires an app-scoped API key. The agent and config must both belong to the authenticated app. Supplying a config that does not exist within the app returns 422. Returns 201 on success.

Arguments:

input: Request body.
input.agent: Agent ID (agt_...) to attach the skill to.
input.config: Skill config ID (cfg_...) that defines the skill's behavior. Must belong to the authenticated app.
input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.

Returns:

The newly created agent skill record.

async def delete(self, agent_skill: str) -> None: View Source

 94    async def delete(self, agent_skill: str) -> None:
 95        """
 96        Remove a skill from an agent
 97        Permanently removes the specified agent skill, detaching the skill config
 98        from the agent. This action cannot be undone. To temporarily stop a skill
 99        from being invoked without removing it, use the deactivate endpoint instead.
100        Requires an app-scoped API key. Returns 204 No Content on success.
101
102        Args:
103            agent_skill: Agent skill ID (`ask_...`) to remove.
104
105        Returns:
106            No content
107        """
108        await self._http.request(f"/api/v1/agent_skills/{agent_skill}", method="DELETE")

Remove a skill from an agent Permanently removes the specified agent skill, detaching the skill config from the agent. This action cannot be undone. To temporarily stop a skill from being invoked without removing it, use the deactivate endpoint instead. Requires an app-scoped API key. Returns 204 No Content on success.

Arguments:

agent_skill: Agent skill ID (ask_...) to remove.

Returns:

No content

async def get(self, agent_skill: str) -> archastro.platform.types.common.AgentSkill: View Source

110    async def get(self, agent_skill: str) -> AgentSkill:
111        """
112        Retrieve an agent skill
113        Returns the agent skill identified by its ID. The skill must belong to
114        the authenticated app's scope.
115        Requires an app-scoped API key.
116
117        Args:
118            agent_skill: Agent skill ID (`ask_...`) to retrieve.
119
120        Returns:
121            The requested agent skill.
122        """
123        return await self._http.request(
124            f"/api/v1/agent_skills/{agent_skill}",
125            response_type=AgentSkill,
126        )

Retrieve an agent skill Returns the agent skill identified by its ID. The skill must belong to the authenticated app's scope. Requires an app-scoped API key.

Arguments:

agent_skill: Agent skill ID (ask_...) to retrieve.

Returns:

The requested agent skill.

async def update( self, agent_skill: str, input: AgentSkillUpdateInput) -> archastro.platform.types.common.AgentSkill: View Source

128    async def update(self, agent_skill: str, input: AgentSkillUpdateInput) -> AgentSkill:
129        """
130        Update an agent skill
131        Updates one or more mutable fields on the specified agent skill. All
132        parameters are optional; supply only the fields you want to change.
133        When `template` is provided, the platform re-resolves that skill template
134        and re-points the skill's underlying config in place. The skill's current
135        status is preserved. Any `instruction` or `metadata` supplied alongside
136        `template` override the template's defaults.
137        Requires an app-scoped API key. The skill must belong to the authenticated
138        app's scope.
139
140        Args:
141            agent_skill: Agent skill ID (`ask_...`) to update.
142            input: Request body.
143            input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
144            input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
145            input.template: Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults.
146
147        Returns:
148            The agent skill after the update has been applied.
149        """
150        return await self._http.request(
151            f"/api/v1/agent_skills/{agent_skill}",
152            method="PATCH",
153            body=input,
154            response_type=AgentSkill,
155        )

Update an agent skill Updates one or more mutable fields on the specified agent skill. All parameters are optional; supply only the fields you want to change. When template is provided, the platform re-resolves that skill template and re-points the skill's underlying config in place. The skill's current status is preserved. Any instruction or metadata supplied alongside template override the template's defaults. Requires an app-scoped API key. The skill must belong to the authenticated app's scope.

Arguments:

agent_skill: Agent skill ID (ask_...) to update.
input: Request body.
input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
input.template: Agent skill template config ID (cfg_...), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any instruction or metadata values provided alongside template override the template defaults.

Returns:

The agent skill after the update has been applied.

async def activate(self, agent_skill: str) -> archastro.platform.types.common.AgentSkill: View Source

157    async def activate(self, agent_skill: str) -> AgentSkill:
158        """
159        Activate an agent skill
160        Sets the status of the specified agent skill to `"active"`, allowing the
161        skill to be invoked during agent runs. The skill must already exist on the
162        agent (created via the enable endpoint) and belong to the authenticated
163        app's scope.
164        Requires an app-scoped API key. Activating a skill that is already active
165        is a no-op and returns the skill unchanged.
166
167        Args:
168            agent_skill: Agent skill ID (`ask_...`) to activate.
169
170        Returns:
171            The agent skill after activation, with `status` set to `"active"`.
172        """
173        return await self._http.request(
174            f"/api/v1/agent_skills/{agent_skill}/activate",
175            method="POST",
176            response_type=AgentSkill,
177        )

Activate an agent skill Sets the status of the specified agent skill to "active", allowing the skill to be invoked during agent runs. The skill must already exist on the agent (created via the enable endpoint) and belong to the authenticated app's scope. Requires an app-scoped API key. Activating a skill that is already active is a no-op and returns the skill unchanged.

Arguments:

agent_skill: Agent skill ID (ask_...) to activate.

Returns:

The agent skill after activation, with status set to "active".

async def deactivate(self, agent_skill: str) -> archastro.platform.types.common.AgentSkill: View Source

179    async def deactivate(self, agent_skill: str) -> AgentSkill:
180        """
181        Deactivate an agent skill
182        Sets the status of the specified agent skill to `"inactive"`, preventing
183        the skill from being invoked during future agent runs. The skill record
184        is preserved and can be reactivated at any time.
185        Requires an app-scoped API key. Deactivating a skill that is already
186        inactive is a no-op and returns the skill unchanged.
187
188        Args:
189            agent_skill: Agent skill ID (`ask_...`) to deactivate.
190
191        Returns:
192            The agent skill after deactivation, with `status` set to `"inactive"`.
193        """
194        return await self._http.request(
195            f"/api/v1/agent_skills/{agent_skill}/deactivate",
196            method="POST",
197            response_type=AgentSkill,
198        )

Deactivate an agent skill Sets the status of the specified agent skill to "inactive", preventing the skill from being invoked during future agent runs. The skill record is preserved and can be reactivated at any time. Requires an app-scoped API key. Deactivating a skill that is already inactive is a no-op and returns the skill unchanged.

Arguments:

agent_skill: Agent skill ID (ask_...) to deactivate.

Returns:

The agent skill after deactivation, with status set to "inactive".

class AgentSkillResource: View Source

201class AgentSkillResource:
202    def __init__(self, http: SyncHttpClient):
203        self._http = http
204
205    def list(self, *, agent: builtins.list[str] | None = None) -> AgentSkillList:
206        """
207        List agent skills
208        Returns all agent skills belonging to the authenticated app. Results include
209        skills in any status (`"active"` or `"inactive"`). Use the `agent` filter to
210        narrow results to one or more specific agents.
211        Requires an app-scoped API key. Supplying one or more `agent` values that
212        cannot be resolved within the app returns 404.
213
214        Args:
215            agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (`agt_...`) or lookup keys. Omit to return skills across all agents in the app.
216
217        Returns:
218            List of agent skills matching the query.
219        """
220        query: dict[str, object] = {}
221        if agent is not None:
222            query["agent"] = agent
223        return self._http.request(
224            "/api/v1/agent_skills",
225            query=query,
226            response_type=AgentSkillList,
227        )
228
229    def create(self, input: AgentSkillCreateInput) -> AgentSkill:
230        """
231        Enable a skill on an agent
232        Attaches a skill config to an agent, creating an agent skill record and
233        returning it with an initial status of `"inactive"`. Use the activate
234        endpoint to make the skill available during agent runs.
235        Requires an app-scoped API key. The `agent` and `config` must both belong
236        to the authenticated app. Supplying a `config` that does not exist within
237        the app returns 422. Returns 201 on success.
238
239        Args:
240            input: Request body.
241            input.agent: Agent ID (`agt_...`) to attach the skill to.
242            input.config: Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app.
243            input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
244            input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
245
246        Returns:
247            The newly created agent skill record.
248        """
249        return self._http.request(
250            "/api/v1/agent_skills",
251            method="POST",
252            body=input,
253            response_type=AgentSkill,
254        )
255
256    def delete(self, agent_skill: str) -> None:
257        """
258        Remove a skill from an agent
259        Permanently removes the specified agent skill, detaching the skill config
260        from the agent. This action cannot be undone. To temporarily stop a skill
261        from being invoked without removing it, use the deactivate endpoint instead.
262        Requires an app-scoped API key. Returns 204 No Content on success.
263
264        Args:
265            agent_skill: Agent skill ID (`ask_...`) to remove.
266
267        Returns:
268            No content
269        """
270        self._http.request(f"/api/v1/agent_skills/{agent_skill}", method="DELETE")
271
272    def get(self, agent_skill: str) -> AgentSkill:
273        """
274        Retrieve an agent skill
275        Returns the agent skill identified by its ID. The skill must belong to
276        the authenticated app's scope.
277        Requires an app-scoped API key.
278
279        Args:
280            agent_skill: Agent skill ID (`ask_...`) to retrieve.
281
282        Returns:
283            The requested agent skill.
284        """
285        return self._http.request(f"/api/v1/agent_skills/{agent_skill}", response_type=AgentSkill)
286
287    def update(self, agent_skill: str, input: AgentSkillUpdateInput) -> AgentSkill:
288        """
289        Update an agent skill
290        Updates one or more mutable fields on the specified agent skill. All
291        parameters are optional; supply only the fields you want to change.
292        When `template` is provided, the platform re-resolves that skill template
293        and re-points the skill's underlying config in place. The skill's current
294        status is preserved. Any `instruction` or `metadata` supplied alongside
295        `template` override the template's defaults.
296        Requires an app-scoped API key. The skill must belong to the authenticated
297        app's scope.
298
299        Args:
300            agent_skill: Agent skill ID (`ask_...`) to update.
301            input: Request body.
302            input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
303            input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
304            input.template: Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults.
305
306        Returns:
307            The agent skill after the update has been applied.
308        """
309        return self._http.request(
310            f"/api/v1/agent_skills/{agent_skill}",
311            method="PATCH",
312            body=input,
313            response_type=AgentSkill,
314        )
315
316    def activate(self, agent_skill: str) -> AgentSkill:
317        """
318        Activate an agent skill
319        Sets the status of the specified agent skill to `"active"`, allowing the
320        skill to be invoked during agent runs. The skill must already exist on the
321        agent (created via the enable endpoint) and belong to the authenticated
322        app's scope.
323        Requires an app-scoped API key. Activating a skill that is already active
324        is a no-op and returns the skill unchanged.
325
326        Args:
327            agent_skill: Agent skill ID (`ask_...`) to activate.
328
329        Returns:
330            The agent skill after activation, with `status` set to `"active"`.
331        """
332        return self._http.request(
333            f"/api/v1/agent_skills/{agent_skill}/activate",
334            method="POST",
335            response_type=AgentSkill,
336        )
337
338    def deactivate(self, agent_skill: str) -> AgentSkill:
339        """
340        Deactivate an agent skill
341        Sets the status of the specified agent skill to `"inactive"`, preventing
342        the skill from being invoked during future agent runs. The skill record
343        is preserved and can be reactivated at any time.
344        Requires an app-scoped API key. Deactivating a skill that is already
345        inactive is a no-op and returns the skill unchanged.
346
347        Args:
348            agent_skill: Agent skill ID (`ask_...`) to deactivate.
349
350        Returns:
351            The agent skill after deactivation, with `status` set to `"inactive"`.
352        """
353        return self._http.request(
354            f"/api/v1/agent_skills/{agent_skill}/deactivate",
355            method="POST",
356            response_type=AgentSkill,
357        )

AgentSkillResource(http: archastro.platform.runtime.http_client.SyncHttpClient) View Source

202    def __init__(self, http: SyncHttpClient):
203        self._http = http

def list( self, *, agent: list[str] | None = None) -> archastro.platform.types.common.AgentSkillList: View Source

205    def list(self, *, agent: builtins.list[str] | None = None) -> AgentSkillList:
206        """
207        List agent skills
208        Returns all agent skills belonging to the authenticated app. Results include
209        skills in any status (`"active"` or `"inactive"`). Use the `agent` filter to
210        narrow results to one or more specific agents.
211        Requires an app-scoped API key. Supplying one or more `agent` values that
212        cannot be resolved within the app returns 404.
213
214        Args:
215            agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (`agt_...`) or lookup keys. Omit to return skills across all agents in the app.
216
217        Returns:
218            List of agent skills matching the query.
219        """
220        query: dict[str, object] = {}
221        if agent is not None:
222            query["agent"] = agent
223        return self._http.request(
224            "/api/v1/agent_skills",
225            query=query,
226            response_type=AgentSkillList,
227        )

Arguments:

agent: Filter results to skills belonging to the specified agent(s). Accepts one or more agent IDs (agt_...) or lookup keys. Omit to return skills across all agents in the app.

Returns:

List of agent skills matching the query.

def create( self, input: AgentSkillCreateInput) -> archastro.platform.types.common.AgentSkill: View Source

229    def create(self, input: AgentSkillCreateInput) -> AgentSkill:
230        """
231        Enable a skill on an agent
232        Attaches a skill config to an agent, creating an agent skill record and
233        returning it with an initial status of `"inactive"`. Use the activate
234        endpoint to make the skill available during agent runs.
235        Requires an app-scoped API key. The `agent` and `config` must both belong
236        to the authenticated app. Supplying a `config` that does not exist within
237        the app returns 422. Returns 201 on success.
238
239        Args:
240            input: Request body.
241            input.agent: Agent ID (`agt_...`) to attach the skill to.
242            input.config: Skill config ID (`cfg_...`) that defines the skill's behavior. Must belong to the authenticated app.
243            input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
244            input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.
245
246        Returns:
247            The newly created agent skill record.
248        """
249        return self._http.request(
250            "/api/v1/agent_skills",
251            method="POST",
252            body=input,
253            response_type=AgentSkill,
254        )

Arguments:

input: Request body.
input.agent: Agent ID (agt_...) to attach the skill to.
input.config: Skill config ID (cfg_...) that defines the skill's behavior. Must belong to the authenticated app.
input.instruction: Optional plain-text instruction override. When supplied, replaces the default instruction from the skill config for this agent.
input.metadata: Arbitrary key-value metadata to store with the agent skill. Useful for tracking provisioning context or custom labels.

Returns:

The newly created agent skill record.

def delete(self, agent_skill: str) -> None: View Source

256    def delete(self, agent_skill: str) -> None:
257        """
258        Remove a skill from an agent
259        Permanently removes the specified agent skill, detaching the skill config
260        from the agent. This action cannot be undone. To temporarily stop a skill
261        from being invoked without removing it, use the deactivate endpoint instead.
262        Requires an app-scoped API key. Returns 204 No Content on success.
263
264        Args:
265            agent_skill: Agent skill ID (`ask_...`) to remove.
266
267        Returns:
268            No content
269        """
270        self._http.request(f"/api/v1/agent_skills/{agent_skill}", method="DELETE")

Arguments:

agent_skill: Agent skill ID (ask_...) to remove.

Returns:

No content

def get(self, agent_skill: str) -> archastro.platform.types.common.AgentSkill: View Source

272    def get(self, agent_skill: str) -> AgentSkill:
273        """
274        Retrieve an agent skill
275        Returns the agent skill identified by its ID. The skill must belong to
276        the authenticated app's scope.
277        Requires an app-scoped API key.
278
279        Args:
280            agent_skill: Agent skill ID (`ask_...`) to retrieve.
281
282        Returns:
283            The requested agent skill.
284        """
285        return self._http.request(f"/api/v1/agent_skills/{agent_skill}", response_type=AgentSkill)

Retrieve an agent skill Returns the agent skill identified by its ID. The skill must belong to the authenticated app's scope. Requires an app-scoped API key.

Arguments:

agent_skill: Agent skill ID (ask_...) to retrieve.

Returns:

The requested agent skill.

def update( self, agent_skill: str, input: AgentSkillUpdateInput) -> archastro.platform.types.common.AgentSkill: View Source

287    def update(self, agent_skill: str, input: AgentSkillUpdateInput) -> AgentSkill:
288        """
289        Update an agent skill
290        Updates one or more mutable fields on the specified agent skill. All
291        parameters are optional; supply only the fields you want to change.
292        When `template` is provided, the platform re-resolves that skill template
293        and re-points the skill's underlying config in place. The skill's current
294        status is preserved. Any `instruction` or `metadata` supplied alongside
295        `template` override the template's defaults.
296        Requires an app-scoped API key. The skill must belong to the authenticated
297        app's scope.
298
299        Args:
300            agent_skill: Agent skill ID (`ask_...`) to update.
301            input: Request body.
302            input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
303            input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
304            input.template: Agent skill template config ID (`cfg_...`), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any `instruction` or `metadata` values provided alongside `template` override the template defaults.
305
306        Returns:
307            The agent skill after the update has been applied.
308        """
309        return self._http.request(
310            f"/api/v1/agent_skills/{agent_skill}",
311            method="PATCH",
312            body=input,
313            response_type=AgentSkill,
314        )

Arguments:

agent_skill: Agent skill ID (ask_...) to update.
input: Request body.
input.instruction: Plain-text instruction override for this agent skill. Replaces the default instruction from the skill config. Omit to leave the current value unchanged.
input.metadata: Arbitrary key-value metadata to store with the agent skill. Omit to leave the current value unchanged.
input.template: Agent skill template config ID (cfg_...), virtual path, or lookup key. When supplied, re-resolves the template and updates the skill's underlying config in place, refreshing template provenance while preserving the skill's current status. Any instruction or metadata values provided alongside template override the template defaults.

Returns:

The agent skill after the update has been applied.

def activate(self, agent_skill: str) -> archastro.platform.types.common.AgentSkill: View Source

316    def activate(self, agent_skill: str) -> AgentSkill:
317        """
318        Activate an agent skill
319        Sets the status of the specified agent skill to `"active"`, allowing the
320        skill to be invoked during agent runs. The skill must already exist on the
321        agent (created via the enable endpoint) and belong to the authenticated
322        app's scope.
323        Requires an app-scoped API key. Activating a skill that is already active
324        is a no-op and returns the skill unchanged.
325
326        Args:
327            agent_skill: Agent skill ID (`ask_...`) to activate.
328
329        Returns:
330            The agent skill after activation, with `status` set to `"active"`.
331        """
332        return self._http.request(
333            f"/api/v1/agent_skills/{agent_skill}/activate",
334            method="POST",
335            response_type=AgentSkill,
336        )

Arguments:

agent_skill: Agent skill ID (ask_...) to activate.

Returns:

The agent skill after activation, with status set to "active".

def deactivate(self, agent_skill: str) -> archastro.platform.types.common.AgentSkill: View Source

338    def deactivate(self, agent_skill: str) -> AgentSkill:
339        """
340        Deactivate an agent skill
341        Sets the status of the specified agent skill to `"inactive"`, preventing
342        the skill from being invoked during future agent runs. The skill record
343        is preserved and can be reactivated at any time.
344        Requires an app-scoped API key. Deactivating a skill that is already
345        inactive is a no-op and returns the skill unchanged.
346
347        Args:
348            agent_skill: Agent skill ID (`ask_...`) to deactivate.
349
350        Returns:
351            The agent skill after deactivation, with `status` set to `"inactive"`.
352        """
353        return self._http.request(
354            f"/api/v1/agent_skills/{agent_skill}/deactivate",
355            method="POST",
356            response_type=AgentSkill,
357        )

Arguments:

agent_skill: Agent skill ID (ask_...) to deactivate.

Returns:

The agent skill after deactivation, with status set to "inactive".