archastro.platform.v1.resources.agents
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: 4f1a14996b49 4 5from __future__ import annotations 6 7import builtins 8from datetime import datetime 9from typing import Any, Literal, Required, TypedDict 10 11from pydantic import BaseModel, Field 12 13from ...runtime.http_client import HttpClient, SyncHttpClient 14from ...types.common import ( 15 Agent, 16 AgentComputer, 17 AgentComputerListResponse, 18 AgentCreateResponse, 19 AgentEnvVarMasked, 20 AgentEnvVarMaskedList, 21 AgentExport, 22 AgentHealth, 23 AgentListResponse, 24 AgentRoutine, 25 AgentSchedule, 26 AgentTool, 27 AgentToolListResponse, 28 AgentUpgradeResponse, 29 HealthActionListResponse, 30 Installation, 31 InstallationKindListResponse, 32 InstallationListResponse, 33 WorkingMemoryEntryListResponse, 34) 35from ...types.threads import Thread 36 37 38class AgentAgentComputerCreateInput(TypedDict, total=False): 39 "Provision a computer for an agent" 40 41 config: dict[str, Any] | None 42 "Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`." 43 lookup_key: str | None 44 "Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID." 45 metadata: dict[str, Any] | None 46 "Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads." 47 name: Required[str] 48 "Human-readable display name for the computer." 49 provider: str | None 50 'Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`.' 51 region: str | None 52 'Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted.' 53 54 55class AgentAgentEnvVarCreateInput(TypedDict, total=False): 56 "Create an agent environment variable" 57 58 description: str | None 59 "Optional human-readable note describing what the variable is used for." 60 key: Required[str] 61 "Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent." 62 value: Required[str] 63 "Plaintext secret value to store. The value is encrypted at rest and never returned in full." 64 65 66class AgentAgentInstallationCreateInputIntegration(TypedDict, total=False): 67 access_token: str | None 68 "OAuth access token or static API key used by `oauth` providers to authenticate requests on behalf of the user." 69 installation_id: str | None 70 "External installation identifier used by `app_installation` providers, e.g. a GitHub App installation ID or a Slack team ID." 71 metadata: dict[str, Any] | None 72 'Arbitrary provider-specific metadata, e.g. `{"bot_user_id": "U012AB3CD"}` for Slack. Stored alongside the integration and made available to connector logic.' 73 refresh_token: str | None 74 "OAuth refresh token used to obtain a new `access_token` when the current one expires. Omit for providers that do not issue refresh tokens." 75 workspace_key: str | None 76 "Provider-specific workspace or team identifier, e.g. a Slack workspace slug. Used to scope the integration to a particular workspace." 77 78 79class AgentAgentInstallationCreateInput(TypedDict, total=False): 80 "Create an installation" 81 82 config: dict[str, Any] | None 83 "Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration." 84 integration: AgentAgentInstallationCreateInputIntegration | None 85 "Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`." 86 kind: Required[str] 87 'Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values.' 88 lookup_key: str | None 89 "Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing." 90 shared_integration: str | None 91 "ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`." 92 93 94AgentAgentToolCreateInput = TypedDict( 95 "AgentAgentToolCreateInput", 96 { 97 "async": bool | None, 98 "builtin_tool_config": dict[str, Any] | None, 99 "builtin_tool_key": str | None, 100 "config": str | None, 101 "description": str | None, 102 "handler_type": str | None, 103 "kind": Required[str], # Tool kind. One of `"builtin"` or `"custom"`. 104 "lookup_key": str | None, 105 "metadata": dict[str, Any] | None, 106 "name": str | None, # Display name for the tool. Required when `kind` is `"custom"`. 107 "name_prefix": str | None, 108 "parameters": dict[str, Any] | None, 109 "status": str | None, 110 }, 111 total=False, 112) 113""" 114Create an agent tool 115 116Attributes: 117 async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 118 builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 119 builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 120 config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 121 description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 122 handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 123 kind: Tool kind. One of `"builtin"` or `"custom"`. 124 lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 125 metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 126 name: Display name for the tool. Required when `kind` is `"custom"`. 127 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 128 parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 129 status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 130""" 131 132 133class AgentCreateInputAclAddItem(TypedDict, total=False): 134 actions: Required[list[str]] 135 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 136 principal: str | None 137 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 138 principal_type: Required[str] 139 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 140 141 142class AgentCreateInputAclGrantsItem(TypedDict, total=False): 143 actions: Required[list[str]] 144 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 145 principal: str | None 146 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 147 principal_type: Required[str] 148 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 149 150 151class AgentCreateInputAclRemoveItem(TypedDict, total=False): 152 principal: str | None 153 'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.' 154 principal_type: Required[str] 155 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 156 157 158class AgentCreateInputAcl(TypedDict, total=False): 159 add: list[AgentCreateInputAclAddItem] | None 160 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 161 grants: list[AgentCreateInputAclGrantsItem] | None 162 "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`." 163 remove: list[AgentCreateInputAclRemoveItem] | None 164 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 165 166 167class AgentCreateInputProfilePicture(TypedDict): 168 data: str 169 "Base64-encoded binary content of the image." 170 filename: str 171 "Original filename of the image, e.g. `avatar.png`." 172 mime_type: str 173 "MIME type of the image, e.g. `image/png` or `image/jpeg`." 174 175 176class AgentCreateInputTemplateBundleConfigsItem(TypedDict, total=False): 177 content: Required[str] 178 "Full text content of the configuration file." 179 content_type: str | None 180 'MIME type of the configuration content, e.g. `"application/x-yaml"` or `"application/json"`. `null` if not specified.' 181 relative_path: Required[str] 182 "Bundle-relative path to this config file. The path determines the config kind and its storage identity within the installation." 183 184 185class AgentCreateInputTemplateBundleSetupActionsItem(TypedDict, total=False): 186 depends_on: list[str] | None 187 "List of other setup action identifiers that must be completed before this action becomes actionable." 188 description: str | None 189 "Markdown-formatted instructions or context shown beneath the checklist item. `null` if not provided." 190 kind: Required[str] 191 'Category of setup step. One of `"env_var"` (configure an environment variable), `"install"` (complete an installation step), `"custom"` (a user-defined action), or `"integration"` (authorize an OAuth-backed MCP server integration).' 192 params: dict[str, Any] | None 193 'Kind-specific configuration for the action. For `"env_var"` steps this typically includes `key` and `scope`; for `"install"` steps it includes `installation_kind`; for `"integration"` steps it includes `mcp_server_ref`. Shape varies by `kind`.' 194 required: bool | None 195 "When `true`, this action must be completed before the checklist progress bar reaches 100%. Defaults to `true`." 196 sort_order: int | None 197 "Numeric sort position controlling the display order of this action in the checklist. Defaults to `0` when not specified." 198 title: Required[str] 199 "Short human-readable label displayed in the setup checklist." 200 verify_config: dict[str, Any] | None 201 'Configuration passed to the runtime verifier to determine whether the action has been completed, e.g. `{"type": "secret_present"}`. `null` if no automated verification is configured.' 202 203 204class AgentCreateInputTemplateBundleSkillsItemFilesItem(TypedDict, total=False): 205 content: Required[str] 206 "Full text content of the file." 207 content_type: str | None 208 "MIME type of the file content. Defaults to a value inferred from the file extension when omitted." 209 relative_path: Required[str] 210 'Path of this file relative to the skill folder root, e.g. `"skills/my-skill/helpers.md"`.' 211 212 213class AgentCreateInputTemplateBundleSkillsItem(TypedDict, total=False): 214 content: Required[str] 215 "Full text content of the `SKILL.md` file." 216 content_type: str | None 217 "MIME type of the `SKILL.md` content. Defaults to `text/markdown` when omitted." 218 files: list[AgentCreateInputTemplateBundleSkillsItemFilesItem] | None 219 "Additional files nested inside the skill folder, each with its own path and content." 220 relative_path: Required[str] 221 'Bundle-relative path to the skill root, which must end in `/SKILL.md` (e.g. `"skills/my-skill/SKILL.md"`).' 222 223 224class AgentCreateInputTemplateBundleTemplate(TypedDict, total=False): 225 content: Required[str] 226 "Full text content of the agent template file, typically a YAML document." 227 content_type: str | None 228 "MIME type of the template content. Defaults to `application/x-yaml` when omitted." 229 relative_path: Required[str] 230 'Bundle-relative path to the template file, used to derive its storage identity (e.g. `"agent.yaml"`).' 231 232 233class AgentCreateInputTemplateBundle(TypedDict, total=False): 234 configs: list[AgentCreateInputTemplateBundleConfigsItem] | None 235 "Additional configuration resources (scripts, model configs, routine templates) referenced by `config_ref` entries in the template." 236 lookup_key_suffix: str | None 237 "A string appended to the lookup key of every uploaded config and rewritten into every `config_ref` in the template body. Should be stable for a given install and unique across installs to avoid key collisions." 238 setup_actions: list[AgentCreateInputTemplateBundleSetupActionsItem] | None 239 "Post-install checklist items created alongside the agent. Each action is inserted as a pending setup step that the user must complete before the agent is fully operational." 240 skills: list[AgentCreateInputTemplateBundleSkillsItem] | None 241 "Skill bundles referenced by the template. Each entry includes the skill root and any supporting files." 242 template: Required[AgentCreateInputTemplateBundleTemplate] 243 "The agent template definition to install, including its path and raw content." 244 245 246class AgentCreateInput(TypedDict, total=False): 247 "Create an agent" 248 249 acl: AgentCreateInputAcl | None 250 "Access control list controlling which users, teams, or orgs can read or manage this agent." 251 email: str | None 252 "Email address assigned to the agent. Used as the agent's contact identity." 253 identity: str | None 254 "System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn." 255 lookup_key: str | None 256 "Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org." 257 metadata: dict[str, Any] | None 258 "Arbitrary key-value map stored on the agent. Not interpreted by the platform." 259 model: str | None 260 "Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model." 261 name: str | None 262 "Display name for the agent. Required when neither `template` nor `template_bundle` is provided." 263 org: str | None 264 "Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`." 265 originator: str | None 266 "Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug." 267 phone_number: str | None 268 "Phone number assigned to the agent in E.164 format, e.g. `+15550001234`." 269 profile_picture: AgentCreateInputProfilePicture | None 270 "Profile picture to attach to the agent. All three subfields are required when this object is present." 271 team: str | None 272 "Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`." 273 template: str | None 274 "ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`." 275 template_bundle: AgentCreateInputTemplateBundle | None 276 "Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`." 277 user: str | None 278 "User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`." 279 280 281class AgentUpdateInputAclAddItem(TypedDict, total=False): 282 actions: Required[list[str]] 283 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 284 principal: str | None 285 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 286 principal_type: Required[str] 287 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 288 289 290class AgentUpdateInputAclGrantsItem(TypedDict, total=False): 291 actions: Required[list[str]] 292 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 293 principal: str | None 294 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 295 principal_type: Required[str] 296 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 297 298 299class AgentUpdateInputAclRemoveItem(TypedDict, total=False): 300 principal: str | None 301 'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.' 302 principal_type: Required[str] 303 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 304 305 306class AgentUpdateInputAcl(TypedDict, total=False): 307 add: list[AgentUpdateInputAclAddItem] | None 308 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 309 grants: list[AgentUpdateInputAclGrantsItem] | None 310 "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`." 311 remove: list[AgentUpdateInputAclRemoveItem] | None 312 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 313 314 315class AgentUpdateInputProfilePicture(TypedDict): 316 data: str 317 "Base64-encoded binary content of the image." 318 filename: str 319 "Original filename of the image, e.g. `avatar.png`." 320 mime_type: str 321 "MIME type of the image, e.g. `image/png` or `image/jpeg`." 322 323 324class AgentUpdateInput(TypedDict, total=False): 325 "Update an agent" 326 327 acl: AgentUpdateInputAcl | None 328 "Replacement access control list. Fully replaces the existing ACL." 329 email: str | None 330 "New email address for the agent." 331 identity: str | None 332 "Replacement identity system-prompt string describing who the agent is." 333 lookup_key: str | None 334 "New `lookup_key` slug. Must be unique within the owning app or org." 335 metadata: dict[str, Any] | None 336 "Replacement key-value metadata map. The entire map is replaced, not merged." 337 model: str | None 338 "New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model." 339 name: str | None 340 "New display name for the agent." 341 org: str | None 342 "Organization ID (`org_...`) to transfer ownership to." 343 originator: str | None 344 "Replacement originator label identifying the source or author of the agent." 345 phone_number: str | None 346 "New phone number for the agent in E.164 format, e.g. `+15550001234`." 347 profile_picture: AgentUpdateInputProfilePicture | None 348 "Replacement profile picture. All three subfields are required when this object is present." 349 team: str | None 350 "Team ID (`team_...`) to transfer ownership to." 351 user: str | None 352 "User ID (`usr_...`) to transfer ownership to." 353 354 355class AgentAgentRoutinesInputAclAddItem(TypedDict, total=False): 356 actions: Required[list[str]] 357 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 358 principal: str | None 359 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 360 principal_type: Required[str] 361 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 362 363 364class AgentAgentRoutinesInputAclGrantsItem(TypedDict, total=False): 365 actions: Required[list[str]] 366 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 367 principal: str | None 368 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 369 principal_type: Required[str] 370 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 371 372 373class AgentAgentRoutinesInputAclRemoveItem(TypedDict, total=False): 374 principal: str | None 375 'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.' 376 principal_type: Required[str] 377 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 378 379 380class AgentAgentRoutinesInputAcl(TypedDict, total=False): 381 add: list[AgentAgentRoutinesInputAclAddItem] | None 382 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 383 grants: list[AgentAgentRoutinesInputAclGrantsItem] | None 384 "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`." 385 remove: list[AgentAgentRoutinesInputAclRemoveItem] | None 386 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 387 388 389class AgentAgentRoutinesInputPresetConfigLlm(TypedDict, total=False): 390 model: str | None 391 'Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent\'s default model is used.' 392 393 394class AgentAgentRoutinesInputPresetConfig(TypedDict, total=False): 395 instructions: str | None 396 "Custom task or behavior instructions for the preset (max 10,000 chars)." 397 llm: AgentAgentRoutinesInputPresetConfigLlm | None 398 "LLM invocation settings (e.g. a `model` override for this routine/step)." 399 session_mode: str | None 400 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 401 session_scope: str | None 402 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 403 structured_message_template_ids: list[str] | None 404 "IDs of structured message templates that constrain the agent's responses to predefined structured formats." 405 406 407class AgentAgentRoutinesInputStepsItemPresetConfigLlm(TypedDict, total=False): 408 model: str | None 409 'Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent\'s default model is used.' 410 411 412class AgentAgentRoutinesInputStepsItemPresetConfig(TypedDict, total=False): 413 instructions: str | None 414 "Custom task or behavior instructions for the preset (max 10,000 chars)." 415 llm: AgentAgentRoutinesInputStepsItemPresetConfigLlm | None 416 "LLM invocation settings (e.g. a `model` override for this routine/step)." 417 session_mode: str | None 418 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 419 session_scope: str | None 420 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 421 structured_message_template_ids: list[str] | None 422 "IDs of structured message templates that constrain the agent's responses to predefined structured formats." 423 424 425class AgentAgentRoutinesInputStepsItem(TypedDict, total=False): 426 config: str | None 427 'ID of a saved config to use as the handler body. Required when `handler_type` is `"workflow_graph"`; also accepted for `"script"` as an alternative to an inline `script` value.' 428 handler_type: Required[str] 429 'Execution handler for this step. One of `"preset"`, `"script"`, or `"workflow_graph"`.' 430 inputs: dict[str, Any] | None 431 "Optional key-value map binding outputs from prior steps to this step's input variables." 432 name: str | None 433 "Optional label for this step. Must be unique within the chain when provided." 434 on_error: str | None 435 'Error handling policy for this step. One of `"halt"` (default), `"continue"`, or `"retry"`.' 436 output_key: str | None 437 "Key under which this step's result is stored and addressable by downstream steps. Defaults to `name` when omitted." 438 preset_config: AgentAgentRoutinesInputStepsItemPresetConfig | None 439 "Configuration overrides for the preset, using the same shape as the routine-level `preset_config`. You may include an `llm` key to override the agent's default model for this step. `null` if not provided." 440 preset_name: str | None 441 'Name of the preset to invoke. Required when `handler_type` is `"preset"`.' 442 script: str | None 443 'Inline script source code to execute. Used when `handler_type` is `"script"` and no `config` is provided.' 444 445 446class AgentAgentRoutinesInput(TypedDict, total=False): 447 "Create a routine" 448 449 acl: AgentAgentRoutinesInputAcl | None 450 "Access control list governing who can read or manage this routine." 451 config: str | None 452 'Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`.' 453 description: str | None 454 "Optional human-readable description of what this routine does." 455 event_config: dict[str, Any] | None 456 'Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).' 457 event_type: str | None 458 "Event type that triggers this routine. Deprecated use `event_config` instead." 459 handler_type: Required[str] 460 'Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.' 461 lookup_key: str | None 462 "Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app." 463 metadata: dict[str, Any] | None 464 "Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform." 465 name: Required[str] 466 "Human-readable display name for the routine." 467 preset_config: AgentAgentRoutinesInputPresetConfig | None 468 'Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`.' 469 preset_name: str | None 470 'Name of the registered preset to use. Required when `handler_type` is `"preset"`.' 471 schedule: str | None 472 'Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.' 473 script: str | None 474 'Inline script source. Required when `handler_type` is `"script"`.' 475 status: str | None 476 'Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`.' 477 steps: list[AgentAgentRoutinesInputStepsItem] | None 478 'Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step\'s `handler_type`.' 479 trigger_context: str | None 480 'Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`.' 481 482 483class AgentSearchInput(TypedDict, total=False): 484 "Search an agent's knowledge base" 485 486 max_results: int | None 487 "Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`." 488 mode: str | None 489 'Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.' 490 query: Required[str] 491 "Natural-language search query used to retrieve relevant knowledge items." 492 recency_days: int | None 493 "When set, restricts results to items indexed within the last N days." 494 source_types: list[str] | None 495 'Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types.' 496 497 498class AgentThreadsInputThread(TypedDict, total=False): 499 description: str | None 500 "Optional longer description of the thread's purpose." 501 is_unlisted: bool | None 502 "When `true`, the thread does not appear in standard thread lists. Defaults to `false`." 503 key: str | None 504 "Stable client-assigned key for the thread. Must be unique within the agent. Useful for idempotent creation if a thread with this key already exists it is returned instead of creating a duplicate." 505 metadata: dict[str, Any] | None 506 "Arbitrary key-value metadata you can attach to the thread. Values must be JSON-serializable." 507 muted: bool | None 508 "When `true`, notifications for activity in this thread are suppressed. Defaults to `false`." 509 org: str | None 510 "Organization ID (`org_...`) to associate with the thread. Used to scope the thread to a specific organization when the agent operates across multiple orgs." 511 settings: dict[str, Any] | None 512 "Thread-level settings map. Supports `agent_enabled` (boolean) to control whether the agent participates in this thread." 513 title: str | None 514 "Human-readable title for the thread. Displayed in thread lists and headers." 515 516 517class AgentThreadsInput(TypedDict, total=False): 518 "Create a thread for an agent" 519 520 skip_welcome_message: bool | None 521 "When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`." 522 thread: Required[AgentThreadsInputThread] 523 "Attributes for the new thread." 524 525 526class AgentUpgradeInput(TypedDict, total=False): 527 "Upgrade an agent from an AgentTemplate" 528 529 dry_run: bool | None 530 "When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply." 531 email: str | None 532 "Instance-specific email address override. Pins this value so the template upgrade does not overwrite it." 533 expected_review_fingerprint: str | None 534 "Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches." 535 identity: str | None 536 "Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it." 537 metadata: dict[str, Any] | None 538 "Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it." 539 mode: Literal["reapply", "replace"] | None 540 'Upgrade mode. `"reapply"` (default) refreshes the agent\'s tracked template; `"replace"` moves the agent to a different template (requires `template`).' 541 model: str | None 542 "Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model." 543 name: str | None 544 "Instance-specific name override. Pins this value so the template upgrade does not overwrite it." 545 originator: str | None 546 "Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it." 547 phone_number: str | None 548 "Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it." 549 template: str | None 550 'ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode.' 551 552 553class ScheduleListResponseDataItem(BaseModel): 554 agent: str | None = Field( 555 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 556 ) 557 app: str | None = Field( 558 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 559 ) 560 created_at: datetime | None = Field( 561 default=None, description="When the schedule was created (ISO 8601)." 562 ) 563 cron_expression: str | None = Field( 564 default=None, 565 description='Standard cron expression defining the recurrence pattern (e.g. `"0 9 * * 1"`). Present only when `schedule_type` is `"recurring"`. `null` for one-time schedules.', 566 ) 567 id: str = Field(..., description="Schedule ID (`asc_...`).") 568 instructions: str | None = Field( 569 default=None, 570 description="The task description the agent will execute when this schedule fires.", 571 ) 572 last_run_at: datetime | None = Field( 573 default=None, 574 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 575 ) 576 max_runs: int | None = Field( 577 default=None, 578 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 579 ) 580 metadata: dict[str, Any] | None = Field( 581 default=None, 582 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 583 ) 584 next_run_at: datetime | None = Field( 585 default=None, 586 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 587 ) 588 run_count: int | None = Field( 589 default=None, description="Total number of times this schedule has fired." 590 ) 591 schedule_type: str | None = Field( 592 default=None, 593 description='Determines how the schedule repeats. `"once"` fires a single time at `scheduled_at` then transitions to `"completed"`. `"recurring"` fires on the `cron_expression` and reschedules automatically.', 594 ) 595 scheduled_at: datetime | None = Field( 596 default=None, 597 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 598 ) 599 status: str | None = Field( 600 default=None, 601 description='Current lifecycle status of the schedule. One of `"active"` (will fire as planned), `"paused"` (temporarily suspended), `"completed"` (has run its last execution), `"cancelled"` (manually stopped), or `"expired"` (past its valid window).', 602 ) 603 thread: str | None = Field( 604 default=None, 605 description="Thread ID (`thr_...`) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. `null` for session-based schedules.", 606 ) 607 timezone: str | None = Field( 608 default=None, 609 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 610 ) 611 updated_at: datetime | None = Field( 612 default=None, description="When the schedule was last modified (ISO 8601)." 613 ) 614 615 616class ScheduleListResponse(BaseModel): 617 """ 618 Successful response 619 """ 620 621 data: list[ScheduleListResponseDataItem] | None = Field( 622 default=None, description="Array of agent schedule objects matching the query." 623 ) 624 625 626class AgentSearchResponse(BaseModel): 627 """ 628 Successful response 629 """ 630 631 data: list[dict[str, Any] | dict[str, Any]] = Field( 632 ..., 633 description='Ranked list of matching knowledge items. Each item is a `kind`-discriminated union either `"chunk"` (always present) or `"document"` (present only when the agent has an active `archastro/knowledge` installation). Sorted by relevance descending; capped at `max_results` total across both kinds.', 634 ) 635 636 637class AsyncAgentAgentComputerResource: 638 def __init__(self, http: HttpClient): 639 self._http = http 640 641 async def list(self, agent: str) -> AgentComputerListResponse: 642 """ 643 List computers 644 Returns all computers belonging to the authenticated app, ordered by creation 645 time descending. Pass `agent` to scope the results to a single agent's 646 computers. When `agent` is omitted, computers for all agents in the app are 647 returned. 648 Requires an app-scoped API key. If the specified agent does not exist or does 649 not belong to the app, the endpoint returns 404. 650 651 Args: 652 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 653 654 Returns: 655 Object containing a `data` array of computer records. 656 """ 657 return await self._http.request( 658 f"/api/v1/agents/{agent}/agent_computers", 659 response_type=AgentComputerListResponse, 660 ) 661 662 async def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 663 """ 664 Provision a computer for an agent 665 Creates and provisions a new computer resource associated with the specified 666 agent. The computer is allocated in the requested region (defaulting to `iad`) 667 and its status transitions from `provisioning` to `running` once it is ready. 668 Requires an app-scoped API key. The agent identified by `agent` must belong 669 to the same app. Supplying a `lookup_key` lets you retrieve this computer 670 later without storing its ID the key must be unique within the app. 671 672 Args: 673 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 674 input: Request body. 675 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 676 input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID. 677 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 678 input.name: Human-readable display name for the computer. 679 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`. 680 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 681 682 Returns: 683 The newly provisioned computer. 684 """ 685 return await self._http.request( 686 f"/api/v1/agents/{agent}/agent_computers", 687 method="POST", 688 body=input, 689 response_type=AgentComputer, 690 ) 691 692 693class AsyncAgentAgentEnvVarResource: 694 def __init__(self, http: HttpClient): 695 self._http = http 696 697 async def list(self, agent: str) -> AgentEnvVarMaskedList: 698 """ 699 List an agent's environment variables 700 Returns all environment variables defined for the specified agent. Variable 701 values are always masked in the response; only the last four characters are 702 visible. To inspect a specific variable, use the retrieve endpoint. 703 The authenticated user must have access to the agent's parent app. Pass the 704 app scope via the `app` parameter when calling with an API key that is scoped 705 to a specific app. Results are returned in an unordered flat list. 706 707 Args: 708 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 709 710 Returns: 711 List of environment variables for the agent, with values masked. 712 """ 713 return await self._http.request( 714 f"/api/v1/agents/{agent}/agent_env_vars", 715 response_type=AgentEnvVarMaskedList, 716 ) 717 718 async def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 719 """ 720 Create an agent environment variable 721 Creates a new environment variable for the specified agent. The variable is 722 stored securely and the plaintext `value` is never returned after creation; 723 subsequent reads return a masked representation showing only the last four 724 characters. 725 The authenticated user must have access to the agent's parent app. Pass the 726 app scope via the `app` parameter when calling with an API key that is scoped 727 to a specific app. Each `key` must be unique within the agent; attempting to 728 create a duplicate key returns a validation error. 729 730 Args: 731 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 732 input: Request body. 733 input.description: Optional human-readable note describing what the variable is used for. 734 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 735 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 736 737 Returns: 738 The newly created environment variable with its value masked. 739 """ 740 return await self._http.request( 741 f"/api/v1/agents/{agent}/agent_env_vars", 742 method="POST", 743 body=input, 744 response_type=AgentEnvVarMasked, 745 ) 746 747 748class AsyncAgentAgentInstallationResource: 749 def __init__(self, http: HttpClient): 750 self._http = http 751 752 async def list(self, agent: str) -> InstallationListResponse: 753 """ 754 List installations for an agent 755 Returns all installations belonging to the specified agent, across all kinds and 756 states. Use this endpoint to inspect which external services and enablement channels 757 an agent is connected to. 758 Results are scoped to the authenticated app and are returned in an unordered array. 759 To list installations across all agents in an app, use the top-level List 760 Installations endpoint instead. The caller must have app scope for the app that 761 owns the agent. 762 763 Args: 764 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 765 766 Returns: 767 The list of installations for the specified agent. 768 """ 769 return await self._http.request( 770 f"/api/v1/agents/{agent}/agent_installations", 771 response_type=InstallationListResponse, 772 ) 773 774 async def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 775 """ 776 Create an installation 777 Creates a new installation for an agent, connecting it to an external service or 778 enablement channel via the specified `kind`. The installation begins in a pending 779 state unless an integration is supplied at creation time, in which case it is 780 activated immediately. 781 Supply `shared_integration` to bind an existing org- or app-level integration, or 782 supply `integration` to create a new integration inline and activate the installation 783 in a single request. Supplying both fields returns 422. 784 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 785 search `source_refs`. The key must be unique within the app, org, and sandbox 786 combination. The caller must have app scope for the app that owns the agent. 787 788 Args: 789 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 790 input: Request body. 791 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 792 input.integration: Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`. 793 input.kind: Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values. 794 input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. 795 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 796 797 Returns: 798 The newly created installation. 799 """ 800 return await self._http.request( 801 f"/api/v1/agents/{agent}/agent_installations", 802 method="POST", 803 body=input, 804 response_type=Installation, 805 ) 806 807 async def kinds(self, agent: str) -> InstallationKindListResponse: 808 """ 809 List available installation kinds 810 Returns the full catalogue of installation kinds supported by the platform. Use 811 the returned `kind` values when calling the Create Installation endpoint. 812 The list is platform-wide and does not vary by agent. The `agent` parameter is 813 accepted for future per-agent filtering but is currently unused. The caller must 814 have app scope to call this endpoint. 815 816 Args: 817 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 818 819 Returns: 820 The list of all supported installation kinds. 821 """ 822 return await self._http.request( 823 f"/api/v1/agents/{agent}/agent_installations/kinds", 824 response_type=InstallationKindListResponse, 825 ) 826 827 828class AsyncAgentAgentToolResource: 829 def __init__(self, http: HttpClient): 830 self._http = http 831 832 async def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 833 """ 834 List agent tools 835 Returns all tools for the authenticated app, optionally filtered by agent 836 or tool kind. Both explicitly created tools and tools derived from connected 837 integrations (installation-sourced tools) are included in the response. 838 Installation-sourced tools appear with `source: "installation"` and 839 `status: "active"`. They are synthesized at request time from connected 840 integrations and do not have a persistent tool ID of the `atl_...` form; 841 their `id` is a composite of the installation ID and server tool type. 842 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 843 `agent` ID that does not belong to the authenticated app returns 404. 844 Requires app scope. 845 846 Args: 847 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 848 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 849 850 Returns: 851 List of tools matching the supplied filters. 852 """ 853 query: dict[str, object] = {} 854 if kind is not None: 855 query["kind"] = kind 856 return await self._http.request( 857 f"/api/v1/agents/{agent}/agent_tools", 858 query=query, 859 response_type=AgentToolListResponse, 860 ) 861 862 async def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 863 """ 864 Create an agent tool 865 Creates a new tool and attaches it to the specified agent. Tools can be 866 either `"builtin"` (a platform-provided capability identified by 867 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 868 description, parameter schema, and handler). 869 New tools are created in `"draft"` status by default unless `status: 870 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 871 during agent runs; call the activate endpoint to promote them. 872 For built-in tools that support multiple instances per agent (those whose 873 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 874 namespace the LLM-facing tool names. Requires app scope. 875 876 Args: 877 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 878 input: Request body. 879 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 880 input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 881 input.builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 882 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 883 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 884 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 885 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 886 input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 887 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 888 input.name: Display name for the tool. Required when `kind` is `"custom"`. 889 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 890 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 891 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 892 893 Returns: 894 The newly created tool. 895 """ 896 return await self._http.request( 897 f"/api/v1/agents/{agent}/agent_tools", 898 method="POST", 899 body=input, 900 response_type=AgentTool, 901 ) 902 903 904class AsyncScheduleResource: 905 def __init__(self, http: HttpClient): 906 self._http = http 907 908 async def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 909 """ 910 List schedules for an agent 911 Returns all schedules belonging to the specified agent in any status. Use the 912 `status` parameter to narrow results to a single lifecycle state. 913 Requires an app-scoped API key. The agent must belong to the app identified 914 by the key. 915 916 Args: 917 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 918 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 919 920 Returns: 921 Successful response 922 """ 923 query: dict[str, object] = {} 924 if status is not None: 925 query["status"] = status 926 return await self._http.request( 927 f"/api/v1/agents/{agent}/schedules", 928 query=query, 929 response_type=ScheduleListResponse, 930 ) 931 932 async def get(self, agent: str, schedule: str) -> AgentSchedule: 933 """ 934 Retrieve a schedule 935 Returns a single schedule belonging to the specified agent. Use this endpoint 936 to fetch the current state, next run time, and configuration of an individual 937 schedule. 938 Requires an app-scoped API key. Both the agent and the schedule must belong 939 to the app identified by the key. Returns 404 if the schedule does not exist 940 or belongs to a different agent. 941 942 Args: 943 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 944 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 945 946 Returns: 947 The requested agent schedule. 948 """ 949 return await self._http.request( 950 f"/api/v1/agents/{agent}/schedules/{schedule}", 951 response_type=AgentSchedule, 952 ) 953 954 955class AsyncAgentResource: 956 def __init__(self, http: HttpClient): 957 self._http = http 958 self.agent_computers = AsyncAgentAgentComputerResource(http) 959 self.agent_env_vars = AsyncAgentAgentEnvVarResource(http) 960 self.agent_installations = AsyncAgentAgentInstallationResource(http) 961 self.agent_tools = AsyncAgentAgentToolResource(http) 962 self.schedules = AsyncScheduleResource(http) 963 964 async def list( 965 self, 966 *, 967 page: int | None = None, 968 page_size: int | None = None, 969 search: str | None = None, 970 user: str | None = None, 971 org_id: str | None = None, 972 template_config: str | None = None, 973 solution_config: builtins.list[str] | None = None, 974 ) -> AgentListResponse: 975 """ 976 List agents 977 Returns a paginated list of agents visible to the authenticated caller. Results are 978 ordered by creation time descending. 979 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 980 to scope the list to a specific owner. Use `template_config` to find agents whose 981 last applied template matches a given config ID. Use `solution_config` to find 982 agents whose last applied template was imported as part of any of the given 983 Solution config IDs. 984 Pagination is page-based: pass `page` and `page_size` to navigate through large 985 result sets. When called under a developer app scope, only agents belonging to that 986 app are returned. 987 988 Args: 989 page: Page number to retrieve, 1-indexed. Defaults to `1`. 990 page_size: Number of agents to return per page. Defaults to `25`. 991 search: Free-text search string matched against the agent name, org, team, and owner fields. 992 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 993 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 994 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 995 solution_config: Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs. 996 997 Returns: 998 Paginated list of agents matching the supplied filters. 999 """ 1000 query: dict[str, object] = {} 1001 if page is not None: 1002 query["page"] = page 1003 if page_size is not None: 1004 query["page_size"] = page_size 1005 if search is not None: 1006 query["search"] = search 1007 if user is not None: 1008 query["user"] = user 1009 if org_id is not None: 1010 query["org_id"] = org_id 1011 if template_config is not None: 1012 query["template_config"] = template_config 1013 if solution_config is not None: 1014 query["solution_config"] = solution_config 1015 return await self._http.request( 1016 "/api/v1/agents", 1017 query=query, 1018 response_type=AgentListResponse, 1019 ) 1020 1021 async def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1022 """ 1023 Create an agent 1024 Creates a new agent. Supports two mutually exclusive provisioning modes. 1025 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1026 AgentTemplate config. The agent's tools, routines, skills, and installations are 1027 provisioned from that template's `config_ref` entries. 1028 **Bundle mode** pass `template_bundle` with a self-contained install payload 1029 (AgentTemplate body plus every skill, script, and config it references). The entire 1030 bundle commits in a single transaction; any failure rolls back the whole install and 1031 the response includes `installed_configs[]` one entry per persisted config. 1032 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1033 is required and a blank agent is created. Requires authentication; when called under 1034 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1035 for the target app. 1036 1037 Args: 1038 input: Request body. 1039 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1040 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1041 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1042 input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org. 1043 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1044 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1045 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1046 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1047 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1048 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1049 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1050 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1051 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1052 input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`. 1053 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1054 1055 Returns: 1056 The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` one entry per persisted config object, with `key` echoing the caller-supplied input identifier. 1057 """ 1058 return await self._http.request( 1059 "/api/v1/agents", 1060 method="POST", 1061 body=input, 1062 response_type=AgentCreateResponse, 1063 ) 1064 1065 async def delete(self, agent: str) -> None: 1066 """ 1067 Delete an agent 1068 Permanently deletes an agent and all of its associated resources. This action cannot 1069 be undone. 1070 The authenticated caller must own the agent or hold sufficient permissions within its 1071 owning org or team. When called under a developer app scope, the caller must hold the 1072 app scope for the target app. 1073 1074 Args: 1075 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1076 1077 Returns: 1078 Empty body. Returns HTTP 204 on success. 1079 """ 1080 await self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 1081 1082 async def get(self, agent: str) -> Agent: 1083 """ 1084 Retrieve an agent 1085 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1086 own the agent or hold sufficient permissions within its owning org or team. 1087 When called under a developer app scope, the agent must belong to that app. Use the 1088 list endpoint to retrieve many agents at once. 1089 1090 Args: 1091 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1092 1093 Returns: 1094 The requested agent. 1095 """ 1096 return await self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 1097 1098 async def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1099 """ 1100 Update an agent 1101 Updates one or more fields on an existing agent. Only the fields you supply are 1102 changed; omitted fields retain their current values. 1103 To clear the agent's default model, pass `model` as an empty string. The 1104 authenticated caller must own the agent or hold write permissions within its owning 1105 org or team. When called under a developer app scope, the caller must hold the app 1106 scope for the target app. 1107 1108 Args: 1109 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1110 input: Request body. 1111 input.acl: Replacement access control list. Fully replaces the existing ACL. 1112 input.email: New email address for the agent. 1113 input.identity: Replacement identity system-prompt string describing who the agent is. 1114 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1115 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1116 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1117 input.name: New display name for the agent. 1118 input.org: Organization ID (`org_...`) to transfer ownership to. 1119 input.originator: Replacement originator label identifying the source or author of the agent. 1120 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1121 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1122 input.team: Team ID (`team_...`) to transfer ownership to. 1123 input.user: User ID (`usr_...`) to transfer ownership to. 1124 1125 Returns: 1126 The updated agent with all current field values. 1127 """ 1128 return await self._http.request( 1129 f"/api/v1/agents/{agent}", 1130 method="PATCH", 1131 body=input, 1132 response_type=Agent, 1133 ) 1134 1135 async def agent_health_actions( 1136 self, 1137 agent: str, 1138 *, 1139 source: builtins.list[str] | None = None, 1140 status: builtins.list[str] | None = None, 1141 kind: builtins.list[str] | None = None, 1142 ) -> HealthActionListResponse: 1143 """ 1144 List health actions for an agent 1145 Returns all health actions associated with a given agent. Health actions 1146 represent required or recommended steps such as setting environment 1147 variables, completing OAuth installations, or running custom verifiers 1148 that an agent needs to reach a healthy state. 1149 Results are not paginated; the full list for the agent is returned. Use 1150 the `source`, `status`, and `kind` filters to narrow results to the 1151 subset your UI or workflow needs. Multiple values for the same filter 1152 are treated as OR (e.g. passing two statuses returns actions matching 1153 either). The caller must be authenticated and scoped to the app that 1154 owns the agent. 1155 1156 Args: 1157 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1158 source: Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages. 1159 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1160 kind: Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds. 1161 1162 Returns: 1163 Object containing a `data` array of health action objects for the specified agent. 1164 """ 1165 query: dict[str, object] = {} 1166 if source is not None: 1167 query["source"] = source 1168 if status is not None: 1169 query["status"] = status 1170 if kind is not None: 1171 query["kind"] = kind 1172 return await self._http.request( 1173 f"/api/v1/agents/{agent}/agent_health_actions", 1174 query=query, 1175 response_type=HealthActionListResponse, 1176 ) 1177 1178 async def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1179 """ 1180 Create a routine 1181 Creates a new routine and attaches it to the specified agent. Routines define 1182 how an agent responds to events or a cron schedule; the `handler_type` controls 1183 which execution model is used. 1184 The routine is created in `"draft"` status by default. To start processing 1185 events immediately, either pass `status: "active"` or call the activate 1186 endpoint after creation. Scheduled routines must run no more frequently than 1187 once per hour. Requires app scope. 1188 1189 Args: 1190 agent: Agent ID (`agt_...`) that this routine will be attached to. 1191 input: Request body. 1192 input.acl: Access control list governing who can read or manage this routine. 1193 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1194 input.description: Optional human-readable description of what this routine does. 1195 input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). 1196 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1197 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1198 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1199 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1200 input.name: Human-readable display name for the routine. 1201 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1202 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1203 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1204 input.script: Inline script source. Required when `handler_type` is `"script"`. 1205 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1206 input.steps: Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. 1207 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1208 1209 Returns: 1210 The newly created routine. 1211 """ 1212 return await self._http.request( 1213 f"/api/v1/agents/{agent}/agent_routines", 1214 method="POST", 1215 body=input, 1216 response_type=AgentRoutine, 1217 ) 1218 1219 async def agent_working_memory( 1220 self, 1221 agent: str, 1222 *, 1223 page: int | None = None, 1224 page_size: int | None = None, 1225 search: str | None = None, 1226 ) -> WorkingMemoryEntryListResponse: 1227 """ 1228 List working memory entries for an agent 1229 Returns a paginated list of working memory entries belonging to the specified 1230 agent. Entries are key-value pairs the agent stores for context between 1231 interactions. Results are ordered by creation time descending (newest first) 1232 and can be filtered with a substring search against the key name. 1233 Requires an app-scoped API key. The authenticated caller must have access to 1234 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1235 404 if the agent does not exist within the accessible scope. 1236 1237 Args: 1238 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1239 page: Page number to retrieve, starting at 1. Defaults to 1. 1240 page_size: Number of entries to return per page. Defaults to 25. 1241 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1242 1243 Returns: 1244 Paginated list of working memory entries for the agent. 1245 """ 1246 query: dict[str, object] = {} 1247 if page is not None: 1248 query["page"] = page 1249 if page_size is not None: 1250 query["page_size"] = page_size 1251 if search is not None: 1252 query["search"] = search 1253 return await self._http.request( 1254 f"/api/v1/agents/{agent}/agent_working_memory", 1255 query=query, 1256 response_type=WorkingMemoryEntryListResponse, 1257 ) 1258 1259 async def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 1260 """ 1261 Export an agent as an AgentTemplate 1262 Reconstructs an AgentTemplate config from a deployed agent and all of its 1263 sub-resources (tools, routines, skills, installations). Returns the template 1264 definition together with every dependent config file (scripts, workflows, skills, 1265 schemas) and their raw content, producing a fully self-contained export bundle. 1266 Use this endpoint to snapshot an agent's current configuration for backup, 1267 migration, or to seed a new Solution template. Pass `remove_identity: true` to 1268 strip instance-specific fields (email, phone number) before export. 1269 The authenticated caller must own the agent or hold sufficient permissions within 1270 its owning org or team. When called under a developer app scope, the caller must 1271 hold the app scope for the target app. 1272 1273 Args: 1274 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 1275 remove_identity: When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint. 1276 1277 Returns: 1278 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 1279 """ 1280 query: dict[str, object] = {} 1281 if remove_identity is not None: 1282 query["remove_identity"] = remove_identity 1283 return await self._http.request( 1284 f"/api/v1/agents/{agent}/export", 1285 query=query, 1286 response_type=AgentExport, 1287 ) 1288 1289 async def health(self, agent: str) -> AgentHealth: 1290 """ 1291 Retrieve an agent's health profile 1292 Returns an aggregate health profile for the specified agent, including an overall 1293 status, a numeric health score, recent activity metrics, and a list of recommended 1294 remediation actions. 1295 The health check is computed on demand at request time. The `checked_at` timestamp 1296 in the response reflects when the evaluation ran. Use this endpoint to surface 1297 diagnostics about tool availability, model configuration, and runtime activity in 1298 dashboards or monitoring workflows. 1299 The authenticated caller must own the agent or hold sufficient permissions within 1300 its owning org or team. When called under a developer app scope, the caller must 1301 hold the app scope for the target app. 1302 1303 Args: 1304 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 1305 1306 Returns: 1307 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 1308 """ 1309 return await self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 1310 1311 async def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 1312 """ 1313 Search an agent's knowledge base 1314 Performs a semantic search over an agent's knowledge base and returns a ranked, 1315 `kind`-discriminated list of matching items. 1316 Two item kinds may appear in `data`: 1317 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 1318 - `"document"` document-level results. Present only when the agent has an active 1319 `archastro/knowledge` installation. 1320 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 1321 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 1322 chunks appear before documents. The total number of results is capped at `max_results` 1323 across both kinds. 1324 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 1325 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 1326 1327 Args: 1328 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 1329 input: Request body. 1330 input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`. 1331 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 1332 input.query: Natural-language search query used to retrieve relevant knowledge items. 1333 input.recency_days: When set, restricts results to items indexed within the last N days. 1334 input.source_types: Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types. 1335 1336 Returns: 1337 Successful response 1338 """ 1339 return await self._http.request( 1340 f"/api/v1/agents/{agent}/search", 1341 method="POST", 1342 body=input, 1343 response_type=AgentSearchResponse, 1344 ) 1345 1346 async def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 1347 """ 1348 Create a thread for an agent 1349 Creates a new thread owned by the specified agent. The thread is scoped to the 1350 agent's identity and is immediately available for messaging. 1351 The authenticated caller must have access to the agent's parent app. If your 1352 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 1353 Attempting to create a thread for an agent you cannot access returns 404. 1354 By default the platform may send an automatic welcome message into the new 1355 thread. Pass `skip_welcome_message: true` to suppress this behavior. 1356 1357 Args: 1358 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 1359 input: Request body. 1360 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 1361 input.thread: Attributes for the new thread. 1362 1363 Returns: 1364 The newly created thread. 1365 """ 1366 return await self._http.request( 1367 f"/api/v1/agents/{agent}/threads", 1368 method="POST", 1369 body=input, 1370 response_type=Thread, 1371 ) 1372 1373 async def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 1374 """ 1375 Upgrade an agent from an AgentTemplate 1376 Upgrades an existing agent by reconciling it against an AgentTemplate from a 1377 Solution. Supports two modes: 1378 - `"reapply"` (default) re-applies the agent's currently tracked template, 1379 picking up any changes the template author has made since the last apply. 1380 - `"replace"` moves the agent to a different template. `template` is required 1381 in this mode. 1382 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 1383 removes, noops) without writing any changes. The response includes a 1384 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 1385 live apply to guard against the diff changing between review and execution. 1386 Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, 1387 `originator`, `model`) let you pin instance-specific values that should not be 1388 overwritten by the template during the upgrade. 1389 The authenticated caller must own the agent or hold write permissions within its 1390 owning org or team. When called under a developer app scope, the caller must hold 1391 the app scope for the target app. 1392 1393 Args: 1394 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 1395 input: Request body. 1396 input.dry_run: When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. 1397 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 1398 input.expected_review_fingerprint: Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. 1399 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 1400 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 1401 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 1402 input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. 1403 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 1404 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 1405 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 1406 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 1407 1408 Returns: 1409 The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted. 1410 """ 1411 return await self._http.request( 1412 f"/api/v1/agents/{agent}/upgrade", 1413 method="POST", 1414 body=input, 1415 response_type=AgentUpgradeResponse, 1416 ) 1417 1418 1419class AgentAgentComputerResource: 1420 def __init__(self, http: SyncHttpClient): 1421 self._http = http 1422 1423 def list(self, agent: str) -> AgentComputerListResponse: 1424 """ 1425 List computers 1426 Returns all computers belonging to the authenticated app, ordered by creation 1427 time descending. Pass `agent` to scope the results to a single agent's 1428 computers. When `agent` is omitted, computers for all agents in the app are 1429 returned. 1430 Requires an app-scoped API key. If the specified agent does not exist or does 1431 not belong to the app, the endpoint returns 404. 1432 1433 Args: 1434 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 1435 1436 Returns: 1437 Object containing a `data` array of computer records. 1438 """ 1439 return self._http.request( 1440 f"/api/v1/agents/{agent}/agent_computers", 1441 response_type=AgentComputerListResponse, 1442 ) 1443 1444 def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 1445 """ 1446 Provision a computer for an agent 1447 Creates and provisions a new computer resource associated with the specified 1448 agent. The computer is allocated in the requested region (defaulting to `iad`) 1449 and its status transitions from `provisioning` to `running` once it is ready. 1450 Requires an app-scoped API key. The agent identified by `agent` must belong 1451 to the same app. Supplying a `lookup_key` lets you retrieve this computer 1452 later without storing its ID the key must be unique within the app. 1453 1454 Args: 1455 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 1456 input: Request body. 1457 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 1458 input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID. 1459 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 1460 input.name: Human-readable display name for the computer. 1461 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`. 1462 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 1463 1464 Returns: 1465 The newly provisioned computer. 1466 """ 1467 return self._http.request( 1468 f"/api/v1/agents/{agent}/agent_computers", 1469 method="POST", 1470 body=input, 1471 response_type=AgentComputer, 1472 ) 1473 1474 1475class AgentAgentEnvVarResource: 1476 def __init__(self, http: SyncHttpClient): 1477 self._http = http 1478 1479 def list(self, agent: str) -> AgentEnvVarMaskedList: 1480 """ 1481 List an agent's environment variables 1482 Returns all environment variables defined for the specified agent. Variable 1483 values are always masked in the response; only the last four characters are 1484 visible. To inspect a specific variable, use the retrieve endpoint. 1485 The authenticated user must have access to the agent's parent app. Pass the 1486 app scope via the `app` parameter when calling with an API key that is scoped 1487 to a specific app. Results are returned in an unordered flat list. 1488 1489 Args: 1490 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1491 1492 Returns: 1493 List of environment variables for the agent, with values masked. 1494 """ 1495 return self._http.request( 1496 f"/api/v1/agents/{agent}/agent_env_vars", 1497 response_type=AgentEnvVarMaskedList, 1498 ) 1499 1500 def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 1501 """ 1502 Create an agent environment variable 1503 Creates a new environment variable for the specified agent. The variable is 1504 stored securely and the plaintext `value` is never returned after creation; 1505 subsequent reads return a masked representation showing only the last four 1506 characters. 1507 The authenticated user must have access to the agent's parent app. Pass the 1508 app scope via the `app` parameter when calling with an API key that is scoped 1509 to a specific app. Each `key` must be unique within the agent; attempting to 1510 create a duplicate key returns a validation error. 1511 1512 Args: 1513 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1514 input: Request body. 1515 input.description: Optional human-readable note describing what the variable is used for. 1516 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 1517 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 1518 1519 Returns: 1520 The newly created environment variable with its value masked. 1521 """ 1522 return self._http.request( 1523 f"/api/v1/agents/{agent}/agent_env_vars", 1524 method="POST", 1525 body=input, 1526 response_type=AgentEnvVarMasked, 1527 ) 1528 1529 1530class AgentAgentInstallationResource: 1531 def __init__(self, http: SyncHttpClient): 1532 self._http = http 1533 1534 def list(self, agent: str) -> InstallationListResponse: 1535 """ 1536 List installations for an agent 1537 Returns all installations belonging to the specified agent, across all kinds and 1538 states. Use this endpoint to inspect which external services and enablement channels 1539 an agent is connected to. 1540 Results are scoped to the authenticated app and are returned in an unordered array. 1541 To list installations across all agents in an app, use the top-level List 1542 Installations endpoint instead. The caller must have app scope for the app that 1543 owns the agent. 1544 1545 Args: 1546 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1547 1548 Returns: 1549 The list of installations for the specified agent. 1550 """ 1551 return self._http.request( 1552 f"/api/v1/agents/{agent}/agent_installations", 1553 response_type=InstallationListResponse, 1554 ) 1555 1556 def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 1557 """ 1558 Create an installation 1559 Creates a new installation for an agent, connecting it to an external service or 1560 enablement channel via the specified `kind`. The installation begins in a pending 1561 state unless an integration is supplied at creation time, in which case it is 1562 activated immediately. 1563 Supply `shared_integration` to bind an existing org- or app-level integration, or 1564 supply `integration` to create a new integration inline and activate the installation 1565 in a single request. Supplying both fields returns 422. 1566 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 1567 search `source_refs`. The key must be unique within the app, org, and sandbox 1568 combination. The caller must have app scope for the app that owns the agent. 1569 1570 Args: 1571 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1572 input: Request body. 1573 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 1574 input.integration: Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`. 1575 input.kind: Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values. 1576 input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. 1577 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 1578 1579 Returns: 1580 The newly created installation. 1581 """ 1582 return self._http.request( 1583 f"/api/v1/agents/{agent}/agent_installations", 1584 method="POST", 1585 body=input, 1586 response_type=Installation, 1587 ) 1588 1589 def kinds(self, agent: str) -> InstallationKindListResponse: 1590 """ 1591 List available installation kinds 1592 Returns the full catalogue of installation kinds supported by the platform. Use 1593 the returned `kind` values when calling the Create Installation endpoint. 1594 The list is platform-wide and does not vary by agent. The `agent` parameter is 1595 accepted for future per-agent filtering but is currently unused. The caller must 1596 have app scope to call this endpoint. 1597 1598 Args: 1599 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1600 1601 Returns: 1602 The list of all supported installation kinds. 1603 """ 1604 return self._http.request( 1605 f"/api/v1/agents/{agent}/agent_installations/kinds", 1606 response_type=InstallationKindListResponse, 1607 ) 1608 1609 1610class AgentAgentToolResource: 1611 def __init__(self, http: SyncHttpClient): 1612 self._http = http 1613 1614 def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 1615 """ 1616 List agent tools 1617 Returns all tools for the authenticated app, optionally filtered by agent 1618 or tool kind. Both explicitly created tools and tools derived from connected 1619 integrations (installation-sourced tools) are included in the response. 1620 Installation-sourced tools appear with `source: "installation"` and 1621 `status: "active"`. They are synthesized at request time from connected 1622 integrations and do not have a persistent tool ID of the `atl_...` form; 1623 their `id` is a composite of the installation ID and server tool type. 1624 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 1625 `agent` ID that does not belong to the authenticated app returns 404. 1626 Requires app scope. 1627 1628 Args: 1629 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 1630 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 1631 1632 Returns: 1633 List of tools matching the supplied filters. 1634 """ 1635 query: dict[str, object] = {} 1636 if kind is not None: 1637 query["kind"] = kind 1638 return self._http.request( 1639 f"/api/v1/agents/{agent}/agent_tools", 1640 query=query, 1641 response_type=AgentToolListResponse, 1642 ) 1643 1644 def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 1645 """ 1646 Create an agent tool 1647 Creates a new tool and attaches it to the specified agent. Tools can be 1648 either `"builtin"` (a platform-provided capability identified by 1649 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 1650 description, parameter schema, and handler). 1651 New tools are created in `"draft"` status by default unless `status: 1652 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 1653 during agent runs; call the activate endpoint to promote them. 1654 For built-in tools that support multiple instances per agent (those whose 1655 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 1656 namespace the LLM-facing tool names. Requires app scope. 1657 1658 Args: 1659 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 1660 input: Request body. 1661 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1662 input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 1663 input.builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 1664 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1665 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1666 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1667 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1668 input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 1669 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1670 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1671 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 1672 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1673 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1674 1675 Returns: 1676 The newly created tool. 1677 """ 1678 return self._http.request( 1679 f"/api/v1/agents/{agent}/agent_tools", 1680 method="POST", 1681 body=input, 1682 response_type=AgentTool, 1683 ) 1684 1685 1686class ScheduleResource: 1687 def __init__(self, http: SyncHttpClient): 1688 self._http = http 1689 1690 def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 1691 """ 1692 List schedules for an agent 1693 Returns all schedules belonging to the specified agent in any status. Use the 1694 `status` parameter to narrow results to a single lifecycle state. 1695 Requires an app-scoped API key. The agent must belong to the app identified 1696 by the key. 1697 1698 Args: 1699 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1700 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 1701 1702 Returns: 1703 Successful response 1704 """ 1705 query: dict[str, object] = {} 1706 if status is not None: 1707 query["status"] = status 1708 return self._http.request( 1709 f"/api/v1/agents/{agent}/schedules", 1710 query=query, 1711 response_type=ScheduleListResponse, 1712 ) 1713 1714 def get(self, agent: str, schedule: str) -> AgentSchedule: 1715 """ 1716 Retrieve a schedule 1717 Returns a single schedule belonging to the specified agent. Use this endpoint 1718 to fetch the current state, next run time, and configuration of an individual 1719 schedule. 1720 Requires an app-scoped API key. Both the agent and the schedule must belong 1721 to the app identified by the key. Returns 404 if the schedule does not exist 1722 or belongs to a different agent. 1723 1724 Args: 1725 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1726 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 1727 1728 Returns: 1729 The requested agent schedule. 1730 """ 1731 return self._http.request( 1732 f"/api/v1/agents/{agent}/schedules/{schedule}", 1733 response_type=AgentSchedule, 1734 ) 1735 1736 1737class AgentResource: 1738 def __init__(self, http: SyncHttpClient): 1739 self._http = http 1740 self.agent_computers = AgentAgentComputerResource(http) 1741 self.agent_env_vars = AgentAgentEnvVarResource(http) 1742 self.agent_installations = AgentAgentInstallationResource(http) 1743 self.agent_tools = AgentAgentToolResource(http) 1744 self.schedules = ScheduleResource(http) 1745 1746 def list( 1747 self, 1748 *, 1749 page: int | None = None, 1750 page_size: int | None = None, 1751 search: str | None = None, 1752 user: str | None = None, 1753 org_id: str | None = None, 1754 template_config: str | None = None, 1755 solution_config: builtins.list[str] | None = None, 1756 ) -> AgentListResponse: 1757 """ 1758 List agents 1759 Returns a paginated list of agents visible to the authenticated caller. Results are 1760 ordered by creation time descending. 1761 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 1762 to scope the list to a specific owner. Use `template_config` to find agents whose 1763 last applied template matches a given config ID. Use `solution_config` to find 1764 agents whose last applied template was imported as part of any of the given 1765 Solution config IDs. 1766 Pagination is page-based: pass `page` and `page_size` to navigate through large 1767 result sets. When called under a developer app scope, only agents belonging to that 1768 app are returned. 1769 1770 Args: 1771 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1772 page_size: Number of agents to return per page. Defaults to `25`. 1773 search: Free-text search string matched against the agent name, org, team, and owner fields. 1774 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 1775 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 1776 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 1777 solution_config: Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs. 1778 1779 Returns: 1780 Paginated list of agents matching the supplied filters. 1781 """ 1782 query: dict[str, object] = {} 1783 if page is not None: 1784 query["page"] = page 1785 if page_size is not None: 1786 query["page_size"] = page_size 1787 if search is not None: 1788 query["search"] = search 1789 if user is not None: 1790 query["user"] = user 1791 if org_id is not None: 1792 query["org_id"] = org_id 1793 if template_config is not None: 1794 query["template_config"] = template_config 1795 if solution_config is not None: 1796 query["solution_config"] = solution_config 1797 return self._http.request("/api/v1/agents", query=query, response_type=AgentListResponse) 1798 1799 def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1800 """ 1801 Create an agent 1802 Creates a new agent. Supports two mutually exclusive provisioning modes. 1803 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1804 AgentTemplate config. The agent's tools, routines, skills, and installations are 1805 provisioned from that template's `config_ref` entries. 1806 **Bundle mode** pass `template_bundle` with a self-contained install payload 1807 (AgentTemplate body plus every skill, script, and config it references). The entire 1808 bundle commits in a single transaction; any failure rolls back the whole install and 1809 the response includes `installed_configs[]` one entry per persisted config. 1810 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1811 is required and a blank agent is created. Requires authentication; when called under 1812 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1813 for the target app. 1814 1815 Args: 1816 input: Request body. 1817 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1818 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1819 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1820 input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org. 1821 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1822 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1823 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1824 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1825 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1826 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1827 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1828 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1829 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1830 input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`. 1831 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1832 1833 Returns: 1834 The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` one entry per persisted config object, with `key` echoing the caller-supplied input identifier. 1835 """ 1836 return self._http.request( 1837 "/api/v1/agents", 1838 method="POST", 1839 body=input, 1840 response_type=AgentCreateResponse, 1841 ) 1842 1843 def delete(self, agent: str) -> None: 1844 """ 1845 Delete an agent 1846 Permanently deletes an agent and all of its associated resources. This action cannot 1847 be undone. 1848 The authenticated caller must own the agent or hold sufficient permissions within its 1849 owning org or team. When called under a developer app scope, the caller must hold the 1850 app scope for the target app. 1851 1852 Args: 1853 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1854 1855 Returns: 1856 Empty body. Returns HTTP 204 on success. 1857 """ 1858 self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 1859 1860 def get(self, agent: str) -> Agent: 1861 """ 1862 Retrieve an agent 1863 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1864 own the agent or hold sufficient permissions within its owning org or team. 1865 When called under a developer app scope, the agent must belong to that app. Use the 1866 list endpoint to retrieve many agents at once. 1867 1868 Args: 1869 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1870 1871 Returns: 1872 The requested agent. 1873 """ 1874 return self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 1875 1876 def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1877 """ 1878 Update an agent 1879 Updates one or more fields on an existing agent. Only the fields you supply are 1880 changed; omitted fields retain their current values. 1881 To clear the agent's default model, pass `model` as an empty string. The 1882 authenticated caller must own the agent or hold write permissions within its owning 1883 org or team. When called under a developer app scope, the caller must hold the app 1884 scope for the target app. 1885 1886 Args: 1887 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1888 input: Request body. 1889 input.acl: Replacement access control list. Fully replaces the existing ACL. 1890 input.email: New email address for the agent. 1891 input.identity: Replacement identity system-prompt string describing who the agent is. 1892 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1893 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1894 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1895 input.name: New display name for the agent. 1896 input.org: Organization ID (`org_...`) to transfer ownership to. 1897 input.originator: Replacement originator label identifying the source or author of the agent. 1898 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1899 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1900 input.team: Team ID (`team_...`) to transfer ownership to. 1901 input.user: User ID (`usr_...`) to transfer ownership to. 1902 1903 Returns: 1904 The updated agent with all current field values. 1905 """ 1906 return self._http.request( 1907 f"/api/v1/agents/{agent}", 1908 method="PATCH", 1909 body=input, 1910 response_type=Agent, 1911 ) 1912 1913 def agent_health_actions( 1914 self, 1915 agent: str, 1916 *, 1917 source: builtins.list[str] | None = None, 1918 status: builtins.list[str] | None = None, 1919 kind: builtins.list[str] | None = None, 1920 ) -> HealthActionListResponse: 1921 """ 1922 List health actions for an agent 1923 Returns all health actions associated with a given agent. Health actions 1924 represent required or recommended steps such as setting environment 1925 variables, completing OAuth installations, or running custom verifiers 1926 that an agent needs to reach a healthy state. 1927 Results are not paginated; the full list for the agent is returned. Use 1928 the `source`, `status`, and `kind` filters to narrow results to the 1929 subset your UI or workflow needs. Multiple values for the same filter 1930 are treated as OR (e.g. passing two statuses returns actions matching 1931 either). The caller must be authenticated and scoped to the app that 1932 owns the agent. 1933 1934 Args: 1935 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1936 source: Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages. 1937 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1938 kind: Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds. 1939 1940 Returns: 1941 Object containing a `data` array of health action objects for the specified agent. 1942 """ 1943 query: dict[str, object] = {} 1944 if source is not None: 1945 query["source"] = source 1946 if status is not None: 1947 query["status"] = status 1948 if kind is not None: 1949 query["kind"] = kind 1950 return self._http.request( 1951 f"/api/v1/agents/{agent}/agent_health_actions", 1952 query=query, 1953 response_type=HealthActionListResponse, 1954 ) 1955 1956 def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1957 """ 1958 Create a routine 1959 Creates a new routine and attaches it to the specified agent. Routines define 1960 how an agent responds to events or a cron schedule; the `handler_type` controls 1961 which execution model is used. 1962 The routine is created in `"draft"` status by default. To start processing 1963 events immediately, either pass `status: "active"` or call the activate 1964 endpoint after creation. Scheduled routines must run no more frequently than 1965 once per hour. Requires app scope. 1966 1967 Args: 1968 agent: Agent ID (`agt_...`) that this routine will be attached to. 1969 input: Request body. 1970 input.acl: Access control list governing who can read or manage this routine. 1971 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1972 input.description: Optional human-readable description of what this routine does. 1973 input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). 1974 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1975 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1976 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1977 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1978 input.name: Human-readable display name for the routine. 1979 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1980 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1981 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1982 input.script: Inline script source. Required when `handler_type` is `"script"`. 1983 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1984 input.steps: Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. 1985 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1986 1987 Returns: 1988 The newly created routine. 1989 """ 1990 return self._http.request( 1991 f"/api/v1/agents/{agent}/agent_routines", 1992 method="POST", 1993 body=input, 1994 response_type=AgentRoutine, 1995 ) 1996 1997 def agent_working_memory( 1998 self, 1999 agent: str, 2000 *, 2001 page: int | None = None, 2002 page_size: int | None = None, 2003 search: str | None = None, 2004 ) -> WorkingMemoryEntryListResponse: 2005 """ 2006 List working memory entries for an agent 2007 Returns a paginated list of working memory entries belonging to the specified 2008 agent. Entries are key-value pairs the agent stores for context between 2009 interactions. Results are ordered by creation time descending (newest first) 2010 and can be filtered with a substring search against the key name. 2011 Requires an app-scoped API key. The authenticated caller must have access to 2012 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 2013 404 if the agent does not exist within the accessible scope. 2014 2015 Args: 2016 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2017 page: Page number to retrieve, starting at 1. Defaults to 1. 2018 page_size: Number of entries to return per page. Defaults to 25. 2019 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 2020 2021 Returns: 2022 Paginated list of working memory entries for the agent. 2023 """ 2024 query: dict[str, object] = {} 2025 if page is not None: 2026 query["page"] = page 2027 if page_size is not None: 2028 query["page_size"] = page_size 2029 if search is not None: 2030 query["search"] = search 2031 return self._http.request( 2032 f"/api/v1/agents/{agent}/agent_working_memory", 2033 query=query, 2034 response_type=WorkingMemoryEntryListResponse, 2035 ) 2036 2037 def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 2038 """ 2039 Export an agent as an AgentTemplate 2040 Reconstructs an AgentTemplate config from a deployed agent and all of its 2041 sub-resources (tools, routines, skills, installations). Returns the template 2042 definition together with every dependent config file (scripts, workflows, skills, 2043 schemas) and their raw content, producing a fully self-contained export bundle. 2044 Use this endpoint to snapshot an agent's current configuration for backup, 2045 migration, or to seed a new Solution template. Pass `remove_identity: true` to 2046 strip instance-specific fields (email, phone number) before export. 2047 The authenticated caller must own the agent or hold sufficient permissions within 2048 its owning org or team. When called under a developer app scope, the caller must 2049 hold the app scope for the target app. 2050 2051 Args: 2052 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 2053 remove_identity: When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint. 2054 2055 Returns: 2056 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 2057 """ 2058 query: dict[str, object] = {} 2059 if remove_identity is not None: 2060 query["remove_identity"] = remove_identity 2061 return self._http.request( 2062 f"/api/v1/agents/{agent}/export", 2063 query=query, 2064 response_type=AgentExport, 2065 ) 2066 2067 def health(self, agent: str) -> AgentHealth: 2068 """ 2069 Retrieve an agent's health profile 2070 Returns an aggregate health profile for the specified agent, including an overall 2071 status, a numeric health score, recent activity metrics, and a list of recommended 2072 remediation actions. 2073 The health check is computed on demand at request time. The `checked_at` timestamp 2074 in the response reflects when the evaluation ran. Use this endpoint to surface 2075 diagnostics about tool availability, model configuration, and runtime activity in 2076 dashboards or monitoring workflows. 2077 The authenticated caller must own the agent or hold sufficient permissions within 2078 its owning org or team. When called under a developer app scope, the caller must 2079 hold the app scope for the target app. 2080 2081 Args: 2082 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 2083 2084 Returns: 2085 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 2086 """ 2087 return self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 2088 2089 def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 2090 """ 2091 Search an agent's knowledge base 2092 Performs a semantic search over an agent's knowledge base and returns a ranked, 2093 `kind`-discriminated list of matching items. 2094 Two item kinds may appear in `data`: 2095 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 2096 - `"document"` document-level results. Present only when the agent has an active 2097 `archastro/knowledge` installation. 2098 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 2099 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 2100 chunks appear before documents. The total number of results is capped at `max_results` 2101 across both kinds. 2102 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 2103 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 2104 2105 Args: 2106 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 2107 input: Request body. 2108 input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`. 2109 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 2110 input.query: Natural-language search query used to retrieve relevant knowledge items. 2111 input.recency_days: When set, restricts results to items indexed within the last N days. 2112 input.source_types: Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types. 2113 2114 Returns: 2115 Successful response 2116 """ 2117 return self._http.request( 2118 f"/api/v1/agents/{agent}/search", 2119 method="POST", 2120 body=input, 2121 response_type=AgentSearchResponse, 2122 ) 2123 2124 def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 2125 """ 2126 Create a thread for an agent 2127 Creates a new thread owned by the specified agent. The thread is scoped to the 2128 agent's identity and is immediately available for messaging. 2129 The authenticated caller must have access to the agent's parent app. If your 2130 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 2131 Attempting to create a thread for an agent you cannot access returns 404. 2132 By default the platform may send an automatic welcome message into the new 2133 thread. Pass `skip_welcome_message: true` to suppress this behavior. 2134 2135 Args: 2136 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 2137 input: Request body. 2138 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 2139 input.thread: Attributes for the new thread. 2140 2141 Returns: 2142 The newly created thread. 2143 """ 2144 return self._http.request( 2145 f"/api/v1/agents/{agent}/threads", 2146 method="POST", 2147 body=input, 2148 response_type=Thread, 2149 ) 2150 2151 def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 2152 """ 2153 Upgrade an agent from an AgentTemplate 2154 Upgrades an existing agent by reconciling it against an AgentTemplate from a 2155 Solution. Supports two modes: 2156 - `"reapply"` (default) re-applies the agent's currently tracked template, 2157 picking up any changes the template author has made since the last apply. 2158 - `"replace"` moves the agent to a different template. `template` is required 2159 in this mode. 2160 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 2161 removes, noops) without writing any changes. The response includes a 2162 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 2163 live apply to guard against the diff changing between review and execution. 2164 Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, 2165 `originator`, `model`) let you pin instance-specific values that should not be 2166 overwritten by the template during the upgrade. 2167 The authenticated caller must own the agent or hold write permissions within its 2168 owning org or team. When called under a developer app scope, the caller must hold 2169 the app scope for the target app. 2170 2171 Args: 2172 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 2173 input: Request body. 2174 input.dry_run: When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. 2175 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 2176 input.expected_review_fingerprint: Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. 2177 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 2178 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 2179 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 2180 input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. 2181 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 2182 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 2183 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 2184 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 2185 2186 Returns: 2187 The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted. 2188 """ 2189 return self._http.request( 2190 f"/api/v1/agents/{agent}/upgrade", 2191 method="POST", 2192 body=input, 2193 response_type=AgentUpgradeResponse, 2194 )
class
AgentAgentComputerCreateInput(typing.TypedDict):
39class AgentAgentComputerCreateInput(TypedDict, total=False): 40 "Provision a computer for an agent" 41 42 config: dict[str, Any] | None 43 "Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`." 44 lookup_key: str | None 45 "Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID." 46 metadata: dict[str, Any] | None 47 "Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads." 48 name: Required[str] 49 "Human-readable display name for the computer." 50 provider: str | None 51 'Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`.' 52 region: str | None 53 'Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted.'
Provision a computer for an agent
config: dict[str, typing.Any] | None
Provider-specific configuration for the computer. Supported keys vary by provider. A top-level provider takes precedence over config.provider.
lookup_key: str | None
Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID.
metadata: dict[str, typing.Any] | None
Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads.
class
AgentAgentEnvVarCreateInput(typing.TypedDict):
56class AgentAgentEnvVarCreateInput(TypedDict, total=False): 57 "Create an agent environment variable" 58 59 description: str | None 60 "Optional human-readable note describing what the variable is used for." 61 key: Required[str] 62 "Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent." 63 value: Required[str] 64 "Plaintext secret value to store. The value is encrypted at rest and never returned in full."
Create an agent environment variable
class
AgentAgentInstallationCreateInputIntegration(typing.TypedDict):
67class AgentAgentInstallationCreateInputIntegration(TypedDict, total=False): 68 access_token: str | None 69 "OAuth access token or static API key used by `oauth` providers to authenticate requests on behalf of the user." 70 installation_id: str | None 71 "External installation identifier used by `app_installation` providers, e.g. a GitHub App installation ID or a Slack team ID." 72 metadata: dict[str, Any] | None 73 'Arbitrary provider-specific metadata, e.g. `{"bot_user_id": "U012AB3CD"}` for Slack. Stored alongside the integration and made available to connector logic.' 74 refresh_token: str | None 75 "OAuth refresh token used to obtain a new `access_token` when the current one expires. Omit for providers that do not issue refresh tokens." 76 workspace_key: str | None 77 "Provider-specific workspace or team identifier, e.g. a Slack workspace slug. Used to scope the integration to a particular workspace."
access_token: str | None
OAuth access token or static API key used by oauth providers to authenticate requests on behalf of the user.
installation_id: str | None
External installation identifier used by app_installation providers, e.g. a GitHub App installation ID or a Slack team ID.
metadata: dict[str, typing.Any] | None
Arbitrary provider-specific metadata, e.g. {"bot_user_id": "U012AB3CD"} for Slack. Stored alongside the integration and made available to connector logic.
refresh_token: str | None
OAuth refresh token used to obtain a new access_token when the current one expires. Omit for providers that do not issue refresh tokens.
class
AgentAgentInstallationCreateInput(typing.TypedDict):
80class AgentAgentInstallationCreateInput(TypedDict, total=False): 81 "Create an installation" 82 83 config: dict[str, Any] | None 84 "Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration." 85 integration: AgentAgentInstallationCreateInputIntegration | None 86 "Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`." 87 kind: Required[str] 88 'Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values.' 89 lookup_key: str | None 90 "Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing." 91 shared_integration: str | None 92 "ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`."
Create an installation
config: dict[str, typing.Any] | None
Kind-specific configuration object. Shape varies by kind; omit if the kind requires no initial configuration.
integration: AgentAgentInstallationCreateInputIntegration | None
Inline integration fields to create for integration/* kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with shared_integration.
kind: Required[str]
Installation kind that determines the external service being connected. Examples: "enablement/github_app", "enablement/slack_bot", "integration/github", "integration/gmail", "web/site". Use the List Kinds endpoint to retrieve all supported values.
lookup_key: str | None
Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search source_refs. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing.
class
AgentAgentToolCreateInput(typing.TypedDict):
Create an agent tool
Attributes:
- async: When
true, the tool executes asynchronously and the agent does not block waiting for a result. Applies to"custom"tools. - builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's
config_schemafor the chosenbuiltin_tool_key. Applies only to"builtin"tools. - builtin_tool_key: Key identifying the built-in tool type to add (e.g.
"knowledge_search"). Required whenkindis"builtin". Must match a key in the tool catalog. - config: Config ID (
cfg_...) referencing the script or workflow graph that implements the tool handler. Applies to"custom"tools. - description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to
"custom"tools. - handler_type: Execution handler for the tool. One of
"script"or"workflow_graph". Applies to"custom"tools. - kind: Tool kind. One of
"builtin"or"custom". - lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning.
- metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform.
- name: Display name for the tool. Required when
kindis"custom". - 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. Required for"namespaced"multi-instance tools; omit for single-instance tools. - parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to
"custom"tools. - status: Initial status of the tool. One of
"draft"or"active". Defaults to"draft"when omitted.
class
AgentCreateInputAclAddItem(typing.TypedDict):
134class AgentCreateInputAclAddItem(TypedDict, total=False): 135 actions: Required[list[str]] 136 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 137 principal: str | None 138 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 139 principal_type: Required[str] 140 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
actions: Required[list[str]]
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
AgentCreateInputAclGrantsItem(typing.TypedDict):
143class AgentCreateInputAclGrantsItem(TypedDict, total=False): 144 actions: Required[list[str]] 145 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 146 principal: str | None 147 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 148 principal_type: Required[str] 149 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
actions: Required[list[str]]
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
AgentCreateInputAclRemoveItem(typing.TypedDict):
152class AgentCreateInputAclRemoveItem(TypedDict, total=False): 153 principal: str | None 154 'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.' 155 principal_type: Required[str] 156 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
principal: str | None
The identifier of the principal to remove. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role". Omit when principal_type is "everyone".
class
AgentCreateInputAcl(typing.TypedDict):
159class AgentCreateInputAcl(TypedDict, total=False): 160 add: list[AgentCreateInputAclAddItem] | None 161 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 162 grants: list[AgentCreateInputAclGrantsItem] | None 163 "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`." 164 remove: list[AgentCreateInputAclRemoveItem] | None 165 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
add: list[AgentCreateInputAclAddItem] | None
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
grants: list[AgentCreateInputAclGrantsItem] | None
remove: list[AgentCreateInputAclRemoveItem] | None
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
AgentCreateInputProfilePicture(typing.TypedDict):
class
AgentCreateInputTemplateBundleConfigsItem(typing.TypedDict):
177class AgentCreateInputTemplateBundleConfigsItem(TypedDict, total=False): 178 content: Required[str] 179 "Full text content of the configuration file." 180 content_type: str | None 181 'MIME type of the configuration content, e.g. `"application/x-yaml"` or `"application/json"`. `null` if not specified.' 182 relative_path: Required[str] 183 "Bundle-relative path to this config file. The path determines the config kind and its storage identity within the installation."
class
AgentCreateInputTemplateBundleSetupActionsItem(typing.TypedDict):
186class AgentCreateInputTemplateBundleSetupActionsItem(TypedDict, total=False): 187 depends_on: list[str] | None 188 "List of other setup action identifiers that must be completed before this action becomes actionable." 189 description: str | None 190 "Markdown-formatted instructions or context shown beneath the checklist item. `null` if not provided." 191 kind: Required[str] 192 'Category of setup step. One of `"env_var"` (configure an environment variable), `"install"` (complete an installation step), `"custom"` (a user-defined action), or `"integration"` (authorize an OAuth-backed MCP server integration).' 193 params: dict[str, Any] | None 194 'Kind-specific configuration for the action. For `"env_var"` steps this typically includes `key` and `scope`; for `"install"` steps it includes `installation_kind`; for `"integration"` steps it includes `mcp_server_ref`. Shape varies by `kind`.' 195 required: bool | None 196 "When `true`, this action must be completed before the checklist progress bar reaches 100%. Defaults to `true`." 197 sort_order: int | None 198 "Numeric sort position controlling the display order of this action in the checklist. Defaults to `0` when not specified." 199 title: Required[str] 200 "Short human-readable label displayed in the setup checklist." 201 verify_config: dict[str, Any] | None 202 'Configuration passed to the runtime verifier to determine whether the action has been completed, e.g. `{"type": "secret_present"}`. `null` if no automated verification is configured.'
depends_on: list[str] | None
List of other setup action identifiers that must be completed before this action becomes actionable.
description: str | None
Markdown-formatted instructions or context shown beneath the checklist item. null if not provided.
kind: Required[str]
Category of setup step. One of "env_var" (configure an environment variable), "install" (complete an installation step), "custom" (a user-defined action), or "integration" (authorize an OAuth-backed MCP server integration).
params: dict[str, typing.Any] | None
Kind-specific configuration for the action. For "env_var" steps this typically includes key and scope; for "install" steps it includes installation_kind; for "integration" steps it includes mcp_server_ref. Shape varies by kind.
required: bool | None
When true, this action must be completed before the checklist progress bar reaches 100%. Defaults to true.
class
AgentCreateInputTemplateBundleSkillsItemFilesItem(typing.TypedDict):
205class AgentCreateInputTemplateBundleSkillsItemFilesItem(TypedDict, total=False): 206 content: Required[str] 207 "Full text content of the file." 208 content_type: str | None 209 "MIME type of the file content. Defaults to a value inferred from the file extension when omitted." 210 relative_path: Required[str] 211 'Path of this file relative to the skill folder root, e.g. `"skills/my-skill/helpers.md"`.'
class
AgentCreateInputTemplateBundleSkillsItem(typing.TypedDict):
214class AgentCreateInputTemplateBundleSkillsItem(TypedDict, total=False): 215 content: Required[str] 216 "Full text content of the `SKILL.md` file." 217 content_type: str | None 218 "MIME type of the `SKILL.md` content. Defaults to `text/markdown` when omitted." 219 files: list[AgentCreateInputTemplateBundleSkillsItemFilesItem] | None 220 "Additional files nested inside the skill folder, each with its own path and content." 221 relative_path: Required[str] 222 'Bundle-relative path to the skill root, which must end in `/SKILL.md` (e.g. `"skills/my-skill/SKILL.md"`).'
files: list[AgentCreateInputTemplateBundleSkillsItemFilesItem] | None
Additional files nested inside the skill folder, each with its own path and content.
class
AgentCreateInputTemplateBundleTemplate(typing.TypedDict):
225class AgentCreateInputTemplateBundleTemplate(TypedDict, total=False): 226 content: Required[str] 227 "Full text content of the agent template file, typically a YAML document." 228 content_type: str | None 229 "MIME type of the template content. Defaults to `application/x-yaml` when omitted." 230 relative_path: Required[str] 231 'Bundle-relative path to the template file, used to derive its storage identity (e.g. `"agent.yaml"`).'
class
AgentCreateInputTemplateBundle(typing.TypedDict):
234class AgentCreateInputTemplateBundle(TypedDict, total=False): 235 configs: list[AgentCreateInputTemplateBundleConfigsItem] | None 236 "Additional configuration resources (scripts, model configs, routine templates) referenced by `config_ref` entries in the template." 237 lookup_key_suffix: str | None 238 "A string appended to the lookup key of every uploaded config and rewritten into every `config_ref` in the template body. Should be stable for a given install and unique across installs to avoid key collisions." 239 setup_actions: list[AgentCreateInputTemplateBundleSetupActionsItem] | None 240 "Post-install checklist items created alongside the agent. Each action is inserted as a pending setup step that the user must complete before the agent is fully operational." 241 skills: list[AgentCreateInputTemplateBundleSkillsItem] | None 242 "Skill bundles referenced by the template. Each entry includes the skill root and any supporting files." 243 template: Required[AgentCreateInputTemplateBundleTemplate] 244 "The agent template definition to install, including its path and raw content."
configs: list[AgentCreateInputTemplateBundleConfigsItem] | None
Additional configuration resources (scripts, model configs, routine templates) referenced by config_ref entries in the template.
lookup_key_suffix: str | None
A string appended to the lookup key of every uploaded config and rewritten into every config_ref in the template body. Should be stable for a given install and unique across installs to avoid key collisions.
setup_actions: list[AgentCreateInputTemplateBundleSetupActionsItem] | None
Post-install checklist items created alongside the agent. Each action is inserted as a pending setup step that the user must complete before the agent is fully operational.
skills: list[AgentCreateInputTemplateBundleSkillsItem] | None
Skill bundles referenced by the template. Each entry includes the skill root and any supporting files.
template: Required[AgentCreateInputTemplateBundleTemplate]
The agent template definition to install, including its path and raw content.
class
AgentCreateInput(typing.TypedDict):
247class AgentCreateInput(TypedDict, total=False): 248 "Create an agent" 249 250 acl: AgentCreateInputAcl | None 251 "Access control list controlling which users, teams, or orgs can read or manage this agent." 252 email: str | None 253 "Email address assigned to the agent. Used as the agent's contact identity." 254 identity: str | None 255 "System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn." 256 lookup_key: str | None 257 "Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org." 258 metadata: dict[str, Any] | None 259 "Arbitrary key-value map stored on the agent. Not interpreted by the platform." 260 model: str | None 261 "Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model." 262 name: str | None 263 "Display name for the agent. Required when neither `template` nor `template_bundle` is provided." 264 org: str | None 265 "Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`." 266 originator: str | None 267 "Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug." 268 phone_number: str | None 269 "Phone number assigned to the agent in E.164 format, e.g. `+15550001234`." 270 profile_picture: AgentCreateInputProfilePicture | None 271 "Profile picture to attach to the agent. All three subfields are required when this object is present." 272 team: str | None 273 "Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`." 274 template: str | None 275 "ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`." 276 template_bundle: AgentCreateInputTemplateBundle | None 277 "Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`." 278 user: str | None 279 "User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`."
Create an agent
acl: AgentCreateInputAcl | None
Access control list controlling which users, teams, or orgs can read or manage this agent.
identity: str | None
System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
lookup_key: str | None
Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
metadata: dict[str, typing.Any] | None
Arbitrary key-value map stored on the agent. Not interpreted by the platform.
model: str | None
Default AI model identifier for this agent, e.g. claude-sonnet-4-5. Overridden per-request when the caller specifies a model.
name: str | None
Display name for the agent. Required when neither template nor template_bundle is provided.
originator: str | None
Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
profile_picture: AgentCreateInputProfilePicture | None
Profile picture to attach to the agent. All three subfields are required when this object is present.
template: str | None
ID (cfg_...) or lookup_key of an existing AgentTemplate config to provision from. Mutually exclusive with template_bundle.
template_bundle: AgentCreateInputTemplateBundle | None
Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with template.
class
AgentUpdateInputAclAddItem(typing.TypedDict):
282class AgentUpdateInputAclAddItem(TypedDict, total=False): 283 actions: Required[list[str]] 284 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 285 principal: str | None 286 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 287 principal_type: Required[str] 288 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
actions: Required[list[str]]
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
AgentUpdateInputAclGrantsItem(typing.TypedDict):
291class AgentUpdateInputAclGrantsItem(TypedDict, total=False): 292 actions: Required[list[str]] 293 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 294 principal: str | None 295 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 296 principal_type: Required[str] 297 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
actions: Required[list[str]]
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
AgentUpdateInputAclRemoveItem(typing.TypedDict):
300class AgentUpdateInputAclRemoveItem(TypedDict, total=False): 301 principal: str | None 302 'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.' 303 principal_type: Required[str] 304 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
principal: str | None
The identifier of the principal to remove. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role". Omit when principal_type is "everyone".
class
AgentUpdateInputAcl(typing.TypedDict):
307class AgentUpdateInputAcl(TypedDict, total=False): 308 add: list[AgentUpdateInputAclAddItem] | None 309 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 310 grants: list[AgentUpdateInputAclGrantsItem] | None 311 "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`." 312 remove: list[AgentUpdateInputAclRemoveItem] | None 313 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
add: list[AgentUpdateInputAclAddItem] | None
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
grants: list[AgentUpdateInputAclGrantsItem] | None
remove: list[AgentUpdateInputAclRemoveItem] | None
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
AgentUpdateInputProfilePicture(typing.TypedDict):
class
AgentUpdateInput(typing.TypedDict):
325class AgentUpdateInput(TypedDict, total=False): 326 "Update an agent" 327 328 acl: AgentUpdateInputAcl | None 329 "Replacement access control list. Fully replaces the existing ACL." 330 email: str | None 331 "New email address for the agent." 332 identity: str | None 333 "Replacement identity system-prompt string describing who the agent is." 334 lookup_key: str | None 335 "New `lookup_key` slug. Must be unique within the owning app or org." 336 metadata: dict[str, Any] | None 337 "Replacement key-value metadata map. The entire map is replaced, not merged." 338 model: str | None 339 "New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model." 340 name: str | None 341 "New display name for the agent." 342 org: str | None 343 "Organization ID (`org_...`) to transfer ownership to." 344 originator: str | None 345 "Replacement originator label identifying the source or author of the agent." 346 phone_number: str | None 347 "New phone number for the agent in E.164 format, e.g. `+15550001234`." 348 profile_picture: AgentUpdateInputProfilePicture | None 349 "Replacement profile picture. All three subfields are required when this object is present." 350 team: str | None 351 "Team ID (`team_...`) to transfer ownership to." 352 user: str | None 353 "User ID (`usr_...`) to transfer ownership to."
Update an agent
metadata: dict[str, typing.Any] | None
Replacement key-value metadata map. The entire map is replaced, not merged.
model: str | None
New default AI model identifier, e.g. claude-sonnet-4-5. Pass an empty string to clear the agent's default model.
profile_picture: AgentUpdateInputProfilePicture | None
Replacement profile picture. All three subfields are required when this object is present.
class
AgentAgentRoutinesInputAclAddItem(typing.TypedDict):
356class AgentAgentRoutinesInputAclAddItem(TypedDict, total=False): 357 actions: Required[list[str]] 358 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 359 principal: str | None 360 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 361 principal_type: Required[str] 362 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
actions: Required[list[str]]
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
AgentAgentRoutinesInputAclGrantsItem(typing.TypedDict):
365class AgentAgentRoutinesInputAclGrantsItem(TypedDict, total=False): 366 actions: Required[list[str]] 367 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 368 principal: str | None 369 'The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.' 370 principal_type: Required[str] 371 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
actions: Required[list[str]]
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None
The identifier of the principal. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role"; omit entirely when principal_type is "everyone".
class
AgentAgentRoutinesInputAclRemoveItem(typing.TypedDict):
374class AgentAgentRoutinesInputAclRemoveItem(TypedDict, total=False): 375 principal: str | None 376 'The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.' 377 principal_type: Required[str] 378 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.'
principal: str | None
The identifier of the principal to remove. A string ID for "user", "team", "org", and "agent" types; one of "admin", "member", or "viewer" for "org_role". Omit when principal_type is "everyone".
class
AgentAgentRoutinesInputAcl(typing.TypedDict):
381class AgentAgentRoutinesInputAcl(TypedDict, total=False): 382 add: list[AgentAgentRoutinesInputAclAddItem] | None 383 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 384 grants: list[AgentAgentRoutinesInputAclGrantsItem] | None 385 "Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`." 386 remove: list[AgentAgentRoutinesInputAclRemoveItem] | None 387 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
add: list[AgentAgentRoutinesInputAclAddItem] | None
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
grants: list[AgentAgentRoutinesInputAclGrantsItem] | None
remove: list[AgentAgentRoutinesInputAclRemoveItem] | None
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
AgentAgentRoutinesInputPresetConfigLlm(typing.TypedDict):
class
AgentAgentRoutinesInputPresetConfig(typing.TypedDict):
395class AgentAgentRoutinesInputPresetConfig(TypedDict, total=False): 396 instructions: str | None 397 "Custom task or behavior instructions for the preset (max 10,000 chars)." 398 llm: AgentAgentRoutinesInputPresetConfigLlm | None 399 "LLM invocation settings (e.g. a `model` override for this routine/step)." 400 session_mode: str | None 401 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 402 session_scope: str | None 403 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 404 structured_message_template_ids: list[str] | None 405 "IDs of structured message templates that constrain the agent's responses to predefined structured formats."
llm: AgentAgentRoutinesInputPresetConfigLlm | None
LLM invocation settings (e.g. a model override for this routine/step).
session_mode: str | None
Session mode: stateless (default, new session per trigger) or session (find-or-create a persistent session scoped by session_scope).
session_scope: str | None
When session_mode is session, controls session scoping: per_user (default), per_key, per_org, or global.
class
AgentAgentRoutinesInputStepsItemPresetConfigLlm(typing.TypedDict):
class
AgentAgentRoutinesInputStepsItemPresetConfig(typing.TypedDict):
413class AgentAgentRoutinesInputStepsItemPresetConfig(TypedDict, total=False): 414 instructions: str | None 415 "Custom task or behavior instructions for the preset (max 10,000 chars)." 416 llm: AgentAgentRoutinesInputStepsItemPresetConfigLlm | None 417 "LLM invocation settings (e.g. a `model` override for this routine/step)." 418 session_mode: str | None 419 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 420 session_scope: str | None 421 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 422 structured_message_template_ids: list[str] | None 423 "IDs of structured message templates that constrain the agent's responses to predefined structured formats."
llm: AgentAgentRoutinesInputStepsItemPresetConfigLlm | None
LLM invocation settings (e.g. a model override for this routine/step).
session_mode: str | None
Session mode: stateless (default, new session per trigger) or session (find-or-create a persistent session scoped by session_scope).
session_scope: str | None
When session_mode is session, controls session scoping: per_user (default), per_key, per_org, or global.
class
AgentAgentRoutinesInputStepsItem(typing.TypedDict):
426class AgentAgentRoutinesInputStepsItem(TypedDict, total=False): 427 config: str | None 428 'ID of a saved config to use as the handler body. Required when `handler_type` is `"workflow_graph"`; also accepted for `"script"` as an alternative to an inline `script` value.' 429 handler_type: Required[str] 430 'Execution handler for this step. One of `"preset"`, `"script"`, or `"workflow_graph"`.' 431 inputs: dict[str, Any] | None 432 "Optional key-value map binding outputs from prior steps to this step's input variables." 433 name: str | None 434 "Optional label for this step. Must be unique within the chain when provided." 435 on_error: str | None 436 'Error handling policy for this step. One of `"halt"` (default), `"continue"`, or `"retry"`.' 437 output_key: str | None 438 "Key under which this step's result is stored and addressable by downstream steps. Defaults to `name` when omitted." 439 preset_config: AgentAgentRoutinesInputStepsItemPresetConfig | None 440 "Configuration overrides for the preset, using the same shape as the routine-level `preset_config`. You may include an `llm` key to override the agent's default model for this step. `null` if not provided." 441 preset_name: str | None 442 'Name of the preset to invoke. Required when `handler_type` is `"preset"`.' 443 script: str | None 444 'Inline script source code to execute. Used when `handler_type` is `"script"` and no `config` is provided.'
config: str | None
ID of a saved config to use as the handler body. Required when handler_type is "workflow_graph"; also accepted for "script" as an alternative to an inline script value.
handler_type: Required[str]
Execution handler for this step. One of "preset", "script", or "workflow_graph".
inputs: dict[str, typing.Any] | None
Optional key-value map binding outputs from prior steps to this step's input variables.
on_error: str | None
Error handling policy for this step. One of "halt" (default), "continue", or "retry".
output_key: str | None
Key under which this step's result is stored and addressable by downstream steps. Defaults to name when omitted.
preset_config: AgentAgentRoutinesInputStepsItemPresetConfig | None
Configuration overrides for the preset, using the same shape as the routine-level preset_config. You may include an llm key to override the agent's default model for this step. null if not provided.
script: str | None
Inline script source code to execute. Used when handler_type is "script" and no config is provided.
class
AgentAgentRoutinesInput(typing.TypedDict):
447class AgentAgentRoutinesInput(TypedDict, total=False): 448 "Create a routine" 449 450 acl: AgentAgentRoutinesInputAcl | None 451 "Access control list governing who can read or manage this routine." 452 config: str | None 453 'Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`.' 454 description: str | None 455 "Optional human-readable description of what this routine does." 456 event_config: dict[str, Any] | None 457 'Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).' 458 event_type: str | None 459 "Event type that triggers this routine. Deprecated use `event_config` instead." 460 handler_type: Required[str] 461 'Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.' 462 lookup_key: str | None 463 "Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app." 464 metadata: dict[str, Any] | None 465 "Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform." 466 name: Required[str] 467 "Human-readable display name for the routine." 468 preset_config: AgentAgentRoutinesInputPresetConfig | None 469 'Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`.' 470 preset_name: str | None 471 'Name of the registered preset to use. Required when `handler_type` is `"preset"`.' 472 schedule: str | None 473 'Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.' 474 script: str | None 475 'Inline script source. Required when `handler_type` is `"script"`.' 476 status: str | None 477 'Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`.' 478 steps: list[AgentAgentRoutinesInputStepsItem] | None 479 'Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step\'s `handler_type`.' 480 trigger_context: str | None 481 'Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`.'
Create a routine
acl: AgentAgentRoutinesInputAcl | None
Access control list governing who can read or manage this routine.
event_config: dict[str, typing.Any] | None
Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a "filters" map and an optional "dedupe_key_path" (a JSON path used to deduplicate events, e.g. "$.thread.id").
handler_type: Required[str]
Execution model for this routine. One of "workflow_graph", "script", "preset", or "chain".
lookup_key: str | None
Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.
metadata: dict[str, typing.Any] | None
Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.
preset_config: AgentAgentRoutinesInputPresetConfig | None
Configuration passed to the preset at runtime. Used when handler_type is "preset".
preset_name: str | None
Name of the registered preset to use. Required when handler_type is "preset".
schedule: str | None
Cron expression for time-triggered routines (e.g. "0 9 * * 1"). Must not be more frequent than once per hour.
steps: list[AgentAgentRoutinesInputStepsItem] | None
Ordered list of steps for a chain handler. Required when handler_type is "chain"; must be omitted or empty otherwise. Each step must have exactly one handler body field (preset_name, script, or config) matching that step's handler_type.
class
AgentSearchInput(typing.TypedDict):
484class AgentSearchInput(TypedDict, total=False): 485 "Search an agent's knowledge base" 486 487 max_results: int | None 488 "Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`." 489 mode: str | None 490 'Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.' 491 query: Required[str] 492 "Natural-language search query used to retrieve relevant knowledge items." 493 recency_days: int | None 494 "When set, restricts results to items indexed within the last N days." 495 source_types: list[str] | None 496 'Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types.'
Search an agent's knowledge base
class
AgentThreadsInputThread(typing.TypedDict):
499class AgentThreadsInputThread(TypedDict, total=False): 500 description: str | None 501 "Optional longer description of the thread's purpose." 502 is_unlisted: bool | None 503 "When `true`, the thread does not appear in standard thread lists. Defaults to `false`." 504 key: str | None 505 "Stable client-assigned key for the thread. Must be unique within the agent. Useful for idempotent creation if a thread with this key already exists it is returned instead of creating a duplicate." 506 metadata: dict[str, Any] | None 507 "Arbitrary key-value metadata you can attach to the thread. Values must be JSON-serializable." 508 muted: bool | None 509 "When `true`, notifications for activity in this thread are suppressed. Defaults to `false`." 510 org: str | None 511 "Organization ID (`org_...`) to associate with the thread. Used to scope the thread to a specific organization when the agent operates across multiple orgs." 512 settings: dict[str, Any] | None 513 "Thread-level settings map. Supports `agent_enabled` (boolean) to control whether the agent participates in this thread." 514 title: str | None 515 "Human-readable title for the thread. Displayed in thread lists and headers."
is_unlisted: bool | None
When true, the thread does not appear in standard thread lists. Defaults to false.
key: str | None
Stable client-assigned key for the thread. Must be unique within the agent. Useful for idempotent creation if a thread with this key already exists it is returned instead of creating a duplicate.
metadata: dict[str, typing.Any] | None
Arbitrary key-value metadata you can attach to the thread. Values must be JSON-serializable.
muted: bool | None
When true, notifications for activity in this thread are suppressed. Defaults to false.
org: str | None
Organization ID (org_...) to associate with the thread. Used to scope the thread to a specific organization when the agent operates across multiple orgs.
class
AgentThreadsInput(typing.TypedDict):
518class AgentThreadsInput(TypedDict, total=False): 519 "Create a thread for an agent" 520 521 skip_welcome_message: bool | None 522 "When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`." 523 thread: Required[AgentThreadsInputThread] 524 "Attributes for the new thread."
Create a thread for an agent
class
AgentUpgradeInput(typing.TypedDict):
527class AgentUpgradeInput(TypedDict, total=False): 528 "Upgrade an agent from an AgentTemplate" 529 530 dry_run: bool | None 531 "When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply." 532 email: str | None 533 "Instance-specific email address override. Pins this value so the template upgrade does not overwrite it." 534 expected_review_fingerprint: str | None 535 "Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches." 536 identity: str | None 537 "Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it." 538 metadata: dict[str, Any] | None 539 "Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it." 540 mode: Literal["reapply", "replace"] | None 541 'Upgrade mode. `"reapply"` (default) refreshes the agent\'s tracked template; `"replace"` moves the agent to a different template (requires `template`).' 542 model: str | None 543 "Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model." 544 name: str | None 545 "Instance-specific name override. Pins this value so the template upgrade does not overwrite it." 546 originator: str | None 547 "Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it." 548 phone_number: str | None 549 "Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it." 550 template: str | None 551 'ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode.'
Upgrade an agent from an AgentTemplate
dry_run: bool | None
When true, computes and returns the full upgrade diff without persisting any changes. Use with expected_review_fingerprint to guard the live apply.
email: str | None
Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.
expected_review_fingerprint: str | None
Stale-review guard. Pass the review_fingerprint returned by a prior dry_run response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches.
identity: str | None
Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.
metadata: dict[str, typing.Any] | None
Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.
mode: Optional[Literal['reapply', 'replace']]
Upgrade mode. "reapply" (default) refreshes the agent's tracked template; "replace" moves the agent to a different template (requires template).
model: str | None
Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.
name: str | None
Instance-specific name override. Pins this value so the template upgrade does not overwrite it.
originator: str | None
Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.
class
ScheduleListResponseDataItem(pydantic.main.BaseModel):
554class ScheduleListResponseDataItem(BaseModel): 555 agent: str | None = Field( 556 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 557 ) 558 app: str | None = Field( 559 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 560 ) 561 created_at: datetime | None = Field( 562 default=None, description="When the schedule was created (ISO 8601)." 563 ) 564 cron_expression: str | None = Field( 565 default=None, 566 description='Standard cron expression defining the recurrence pattern (e.g. `"0 9 * * 1"`). Present only when `schedule_type` is `"recurring"`. `null` for one-time schedules.', 567 ) 568 id: str = Field(..., description="Schedule ID (`asc_...`).") 569 instructions: str | None = Field( 570 default=None, 571 description="The task description the agent will execute when this schedule fires.", 572 ) 573 last_run_at: datetime | None = Field( 574 default=None, 575 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 576 ) 577 max_runs: int | None = Field( 578 default=None, 579 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 580 ) 581 metadata: dict[str, Any] | None = Field( 582 default=None, 583 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 584 ) 585 next_run_at: datetime | None = Field( 586 default=None, 587 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 588 ) 589 run_count: int | None = Field( 590 default=None, description="Total number of times this schedule has fired." 591 ) 592 schedule_type: str | None = Field( 593 default=None, 594 description='Determines how the schedule repeats. `"once"` fires a single time at `scheduled_at` then transitions to `"completed"`. `"recurring"` fires on the `cron_expression` and reschedules automatically.', 595 ) 596 scheduled_at: datetime | None = Field( 597 default=None, 598 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 599 ) 600 status: str | None = Field( 601 default=None, 602 description='Current lifecycle status of the schedule. One of `"active"` (will fire as planned), `"paused"` (temporarily suspended), `"completed"` (has run its last execution), `"cancelled"` (manually stopped), or `"expired"` (past its valid window).', 603 ) 604 thread: str | None = Field( 605 default=None, 606 description="Thread ID (`thr_...`) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. `null` for session-based schedules.", 607 ) 608 timezone: str | None = Field( 609 default=None, 610 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 611 ) 612 updated_at: datetime | None = Field( 613 default=None, description="When the schedule was last modified (ISO 8601)." 614 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
cron_expression: str | None =
None
Standard cron expression defining the recurrence pattern (e.g. "0 9 * * 1"). Present only when schedule_type is "recurring". null for one-time schedules.
instructions: str | None =
None
The task description the agent will execute when this schedule fires.
last_run_at: datetime.datetime | None =
None
UTC datetime of the most recent successful execution. null if the schedule has never run.
max_runs: int | None =
None
Maximum number of times a recurring schedule may fire before automatically transitioning to "completed". null means no limit.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.
next_run_at: datetime.datetime | None =
None
UTC datetime of the next planned execution. null if the schedule has completed, been cancelled, or has not yet been computed.
schedule_type: str | None =
None
Determines how the schedule repeats. "once" fires a single time at scheduled_at then transitions to "completed". "recurring" fires on the cron_expression and reschedules automatically.
scheduled_at: datetime.datetime | None =
None
The exact UTC datetime at which a one-time schedule fires. Present only when schedule_type is "once". null for recurring schedules.
status: str | None =
None
Current lifecycle status of the schedule. One of "active" (will fire as planned), "paused" (temporarily suspended), "completed" (has run its last execution), "cancelled" (manually stopped), or "expired" (past its valid window).
thread: str | None =
None
Thread ID (thr_...) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. null for session-based schedules.
timezone: str | None =
None
IANA timezone name used to interpret the cron expression or scheduled_at (e.g. "America/New_York"). Defaults to "Etc/UTC".
class
ScheduleListResponse(pydantic.main.BaseModel):
617class ScheduleListResponse(BaseModel): 618 """ 619 Successful response 620 """ 621 622 data: list[ScheduleListResponseDataItem] | None = Field( 623 default=None, description="Array of agent schedule objects matching the query." 624 )
Successful response
class
AgentSearchResponse(pydantic.main.BaseModel):
627class AgentSearchResponse(BaseModel): 628 """ 629 Successful response 630 """ 631 632 data: list[dict[str, Any] | dict[str, Any]] = Field( 633 ..., 634 description='Ranked list of matching knowledge items. Each item is a `kind`-discriminated union either `"chunk"` (always present) or `"document"` (present only when the agent has an active `archastro/knowledge` installation). Sorted by relevance descending; capped at `max_results` total across both kinds.', 635 )
Successful response
data: list[dict[str, typing.Any]] =
PydanticUndefined
Ranked list of matching knowledge items. Each item is a kind-discriminated union either "chunk" (always present) or "document" (present only when the agent has an active archastro/knowledge installation). Sorted by relevance descending; capped at max_results total across both kinds.
class
AsyncAgentAgentComputerResource:
638class AsyncAgentAgentComputerResource: 639 def __init__(self, http: HttpClient): 640 self._http = http 641 642 async def list(self, agent: str) -> AgentComputerListResponse: 643 """ 644 List computers 645 Returns all computers belonging to the authenticated app, ordered by creation 646 time descending. Pass `agent` to scope the results to a single agent's 647 computers. When `agent` is omitted, computers for all agents in the app are 648 returned. 649 Requires an app-scoped API key. If the specified agent does not exist or does 650 not belong to the app, the endpoint returns 404. 651 652 Args: 653 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 654 655 Returns: 656 Object containing a `data` array of computer records. 657 """ 658 return await self._http.request( 659 f"/api/v1/agents/{agent}/agent_computers", 660 response_type=AgentComputerListResponse, 661 ) 662 663 async def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 664 """ 665 Provision a computer for an agent 666 Creates and provisions a new computer resource associated with the specified 667 agent. The computer is allocated in the requested region (defaulting to `iad`) 668 and its status transitions from `provisioning` to `running` once it is ready. 669 Requires an app-scoped API key. The agent identified by `agent` must belong 670 to the same app. Supplying a `lookup_key` lets you retrieve this computer 671 later without storing its ID the key must be unique within the app. 672 673 Args: 674 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 675 input: Request body. 676 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 677 input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID. 678 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 679 input.name: Human-readable display name for the computer. 680 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`. 681 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 682 683 Returns: 684 The newly provisioned computer. 685 """ 686 return await self._http.request( 687 f"/api/v1/agents/{agent}/agent_computers", 688 method="POST", 689 body=input, 690 response_type=AgentComputer, 691 )
AsyncAgentAgentComputerResource(http: archastro.platform.runtime.http_client.HttpClient)
642 async def list(self, agent: str) -> AgentComputerListResponse: 643 """ 644 List computers 645 Returns all computers belonging to the authenticated app, ordered by creation 646 time descending. Pass `agent` to scope the results to a single agent's 647 computers. When `agent` is omitted, computers for all agents in the app are 648 returned. 649 Requires an app-scoped API key. If the specified agent does not exist or does 650 not belong to the app, the endpoint returns 404. 651 652 Args: 653 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 654 655 Returns: 656 Object containing a `data` array of computer records. 657 """ 658 return await self._http.request( 659 f"/api/v1/agents/{agent}/agent_computers", 660 response_type=AgentComputerListResponse, 661 )
List computers
Returns all computers belonging to the authenticated app, ordered by creation
time descending. Pass agent to scope the results to a single agent's
computers. When agent is omitted, computers for all agents in the app are
returned.
Requires an app-scoped API key. If the specified agent does not exist or does
not belong to the app, the endpoint returns 404.
Arguments:
- agent: Agent ID (
agt_...). When provided, only computers belonging to this agent are returned.
Returns:
Object containing a
dataarray of computer records.
async def
create( self, agent: str, input: AgentAgentComputerCreateInput) -> archastro.platform.types.common.AgentComputer:
663 async def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 664 """ 665 Provision a computer for an agent 666 Creates and provisions a new computer resource associated with the specified 667 agent. The computer is allocated in the requested region (defaulting to `iad`) 668 and its status transitions from `provisioning` to `running` once it is ready. 669 Requires an app-scoped API key. The agent identified by `agent` must belong 670 to the same app. Supplying a `lookup_key` lets you retrieve this computer 671 later without storing its ID the key must be unique within the app. 672 673 Args: 674 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 675 input: Request body. 676 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 677 input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID. 678 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 679 input.name: Human-readable display name for the computer. 680 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`. 681 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 682 683 Returns: 684 The newly provisioned computer. 685 """ 686 return await self._http.request( 687 f"/api/v1/agents/{agent}/agent_computers", 688 method="POST", 689 body=input, 690 response_type=AgentComputer, 691 )
Provision a computer for an agent
Creates and provisions a new computer resource associated with the specified
agent. The computer is allocated in the requested region (defaulting to iad)
and its status transitions from provisioning to running once it is ready.
Requires an app-scoped API key. The agent identified by agent must belong
to the same app. Supplying a lookup_key lets you retrieve this computer
later without storing its ID the key must be unique within the app.
Arguments:
- agent: Agent ID (
agt_...). When provided, only computers belonging to this agent are returned. - input: Request body.
- input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level
providertakes precedence overconfig.provider. - input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID.
- input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads.
- input.name: Human-readable display name for the computer.
- input.provider: Compute backend for the computer:
"sprites"(Fly Sprites, the default) or"vercel"(Vercel Sandbox). Folded intoconfig.provider. - input.region: Region in which to provision the computer, e.g.
"iad". Defaults to"iad"when omitted.
Returns:
The newly provisioned computer.
class
AsyncAgentAgentEnvVarResource:
694class AsyncAgentAgentEnvVarResource: 695 def __init__(self, http: HttpClient): 696 self._http = http 697 698 async def list(self, agent: str) -> AgentEnvVarMaskedList: 699 """ 700 List an agent's environment variables 701 Returns all environment variables defined for the specified agent. Variable 702 values are always masked in the response; only the last four characters are 703 visible. To inspect a specific variable, use the retrieve endpoint. 704 The authenticated user must have access to the agent's parent app. Pass the 705 app scope via the `app` parameter when calling with an API key that is scoped 706 to a specific app. Results are returned in an unordered flat list. 707 708 Args: 709 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 710 711 Returns: 712 List of environment variables for the agent, with values masked. 713 """ 714 return await self._http.request( 715 f"/api/v1/agents/{agent}/agent_env_vars", 716 response_type=AgentEnvVarMaskedList, 717 ) 718 719 async def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 720 """ 721 Create an agent environment variable 722 Creates a new environment variable for the specified agent. The variable is 723 stored securely and the plaintext `value` is never returned after creation; 724 subsequent reads return a masked representation showing only the last four 725 characters. 726 The authenticated user must have access to the agent's parent app. Pass the 727 app scope via the `app` parameter when calling with an API key that is scoped 728 to a specific app. Each `key` must be unique within the agent; attempting to 729 create a duplicate key returns a validation error. 730 731 Args: 732 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 733 input: Request body. 734 input.description: Optional human-readable note describing what the variable is used for. 735 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 736 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 737 738 Returns: 739 The newly created environment variable with its value masked. 740 """ 741 return await self._http.request( 742 f"/api/v1/agents/{agent}/agent_env_vars", 743 method="POST", 744 body=input, 745 response_type=AgentEnvVarMasked, 746 )
AsyncAgentAgentEnvVarResource(http: archastro.platform.runtime.http_client.HttpClient)
698 async def list(self, agent: str) -> AgentEnvVarMaskedList: 699 """ 700 List an agent's environment variables 701 Returns all environment variables defined for the specified agent. Variable 702 values are always masked in the response; only the last four characters are 703 visible. To inspect a specific variable, use the retrieve endpoint. 704 The authenticated user must have access to the agent's parent app. Pass the 705 app scope via the `app` parameter when calling with an API key that is scoped 706 to a specific app. Results are returned in an unordered flat list. 707 708 Args: 709 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 710 711 Returns: 712 List of environment variables for the agent, with values masked. 713 """ 714 return await self._http.request( 715 f"/api/v1/agents/{agent}/agent_env_vars", 716 response_type=AgentEnvVarMaskedList, 717 )
List an agent's environment variables
Returns all environment variables defined for the specified agent. Variable
values are always masked in the response; only the last four characters are
visible. To inspect a specific variable, use the retrieve endpoint.
The authenticated user must have access to the agent's parent app. Pass the
app scope via the app parameter when calling with an API key that is scoped
to a specific app. Results are returned in an unordered flat list.
Arguments:
- agent: Agent ID (
agt_...). Returns environment variables belonging to this agent.
Returns:
List of environment variables for the agent, with values masked.
async def
create( self, agent: str, input: AgentAgentEnvVarCreateInput) -> archastro.platform.types.common.AgentEnvVarMasked:
719 async def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 720 """ 721 Create an agent environment variable 722 Creates a new environment variable for the specified agent. The variable is 723 stored securely and the plaintext `value` is never returned after creation; 724 subsequent reads return a masked representation showing only the last four 725 characters. 726 The authenticated user must have access to the agent's parent app. Pass the 727 app scope via the `app` parameter when calling with an API key that is scoped 728 to a specific app. Each `key` must be unique within the agent; attempting to 729 create a duplicate key returns a validation error. 730 731 Args: 732 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 733 input: Request body. 734 input.description: Optional human-readable note describing what the variable is used for. 735 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 736 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 737 738 Returns: 739 The newly created environment variable with its value masked. 740 """ 741 return await self._http.request( 742 f"/api/v1/agents/{agent}/agent_env_vars", 743 method="POST", 744 body=input, 745 response_type=AgentEnvVarMasked, 746 )
Create an agent environment variable
Creates a new environment variable for the specified agent. The variable is
stored securely and the plaintext value is never returned after creation;
subsequent reads return a masked representation showing only the last four
characters.
The authenticated user must have access to the agent's parent app. Pass the
app scope via the app parameter when calling with an API key that is scoped
to a specific app. Each key must be unique within the agent; attempting to
create a duplicate key returns a validation error.
Arguments:
- agent: Agent ID (
agt_...). Returns environment variables belonging to this agent. - input: Request body.
- input.description: Optional human-readable note describing what the variable is used for.
- input.key: Environment variable name, e.g.
WEBHOOK_SECRET. Must be unique within the agent. - input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full.
Returns:
The newly created environment variable with its value masked.
class
AsyncAgentAgentInstallationResource:
749class AsyncAgentAgentInstallationResource: 750 def __init__(self, http: HttpClient): 751 self._http = http 752 753 async def list(self, agent: str) -> InstallationListResponse: 754 """ 755 List installations for an agent 756 Returns all installations belonging to the specified agent, across all kinds and 757 states. Use this endpoint to inspect which external services and enablement channels 758 an agent is connected to. 759 Results are scoped to the authenticated app and are returned in an unordered array. 760 To list installations across all agents in an app, use the top-level List 761 Installations endpoint instead. The caller must have app scope for the app that 762 owns the agent. 763 764 Args: 765 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 766 767 Returns: 768 The list of installations for the specified agent. 769 """ 770 return await self._http.request( 771 f"/api/v1/agents/{agent}/agent_installations", 772 response_type=InstallationListResponse, 773 ) 774 775 async def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 776 """ 777 Create an installation 778 Creates a new installation for an agent, connecting it to an external service or 779 enablement channel via the specified `kind`. The installation begins in a pending 780 state unless an integration is supplied at creation time, in which case it is 781 activated immediately. 782 Supply `shared_integration` to bind an existing org- or app-level integration, or 783 supply `integration` to create a new integration inline and activate the installation 784 in a single request. Supplying both fields returns 422. 785 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 786 search `source_refs`. The key must be unique within the app, org, and sandbox 787 combination. The caller must have app scope for the app that owns the agent. 788 789 Args: 790 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 791 input: Request body. 792 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 793 input.integration: Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`. 794 input.kind: Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values. 795 input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. 796 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 797 798 Returns: 799 The newly created installation. 800 """ 801 return await self._http.request( 802 f"/api/v1/agents/{agent}/agent_installations", 803 method="POST", 804 body=input, 805 response_type=Installation, 806 ) 807 808 async def kinds(self, agent: str) -> InstallationKindListResponse: 809 """ 810 List available installation kinds 811 Returns the full catalogue of installation kinds supported by the platform. Use 812 the returned `kind` values when calling the Create Installation endpoint. 813 The list is platform-wide and does not vary by agent. The `agent` parameter is 814 accepted for future per-agent filtering but is currently unused. The caller must 815 have app scope to call this endpoint. 816 817 Args: 818 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 819 820 Returns: 821 The list of all supported installation kinds. 822 """ 823 return await self._http.request( 824 f"/api/v1/agents/{agent}/agent_installations/kinds", 825 response_type=InstallationKindListResponse, 826 )
AsyncAgentAgentInstallationResource(http: archastro.platform.runtime.http_client.HttpClient)
753 async def list(self, agent: str) -> InstallationListResponse: 754 """ 755 List installations for an agent 756 Returns all installations belonging to the specified agent, across all kinds and 757 states. Use this endpoint to inspect which external services and enablement channels 758 an agent is connected to. 759 Results are scoped to the authenticated app and are returned in an unordered array. 760 To list installations across all agents in an app, use the top-level List 761 Installations endpoint instead. The caller must have app scope for the app that 762 owns the agent. 763 764 Args: 765 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 766 767 Returns: 768 The list of installations for the specified agent. 769 """ 770 return await self._http.request( 771 f"/api/v1/agents/{agent}/agent_installations", 772 response_type=InstallationListResponse, 773 )
List installations for an agent Returns all installations belonging to the specified agent, across all kinds and states. Use this endpoint to inspect which external services and enablement channels an agent is connected to. Results are scoped to the authenticated app and are returned in an unordered array. To list installations across all agents in an app, use the top-level List Installations endpoint instead. The caller must have app scope for the app that owns the agent.
Arguments:
- agent: Agent ID (
agt_...) whose installations you want to retrieve.
Returns:
The list of installations for the specified agent.
async def
create( self, agent: str, input: AgentAgentInstallationCreateInput) -> archastro.platform.types.common.Installation:
775 async def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 776 """ 777 Create an installation 778 Creates a new installation for an agent, connecting it to an external service or 779 enablement channel via the specified `kind`. The installation begins in a pending 780 state unless an integration is supplied at creation time, in which case it is 781 activated immediately. 782 Supply `shared_integration` to bind an existing org- or app-level integration, or 783 supply `integration` to create a new integration inline and activate the installation 784 in a single request. Supplying both fields returns 422. 785 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 786 search `source_refs`. The key must be unique within the app, org, and sandbox 787 combination. The caller must have app scope for the app that owns the agent. 788 789 Args: 790 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 791 input: Request body. 792 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 793 input.integration: Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`. 794 input.kind: Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values. 795 input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. 796 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 797 798 Returns: 799 The newly created installation. 800 """ 801 return await self._http.request( 802 f"/api/v1/agents/{agent}/agent_installations", 803 method="POST", 804 body=input, 805 response_type=Installation, 806 )
Create an installation
Creates a new installation for an agent, connecting it to an external service or
enablement channel via the specified kind. The installation begins in a pending
state unless an integration is supplied at creation time, in which case it is
activated immediately.
Supply shared_integration to bind an existing org- or app-level integration, or
supply integration to create a new integration inline and activate the installation
in a single request. Supplying both fields returns 422.
Use lookup_key to assign a stable identifier you can reference later in knowledge
search source_refs. The key must be unique within the app, org, and sandbox
combination. The caller must have app scope for the app that owns the agent.
Arguments:
- agent: Agent ID (
agt_...) whose installations you want to retrieve. - input: Request body.
- input.config: Kind-specific configuration object. Shape varies by
kind; omit if the kind requires no initial configuration. - input.integration: Inline integration fields to create for
integration/*kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive withshared_integration. - input.kind: Installation kind that determines the external service being connected. Examples:
"enablement/github_app","enablement/slack_bot","integration/github","integration/gmail","web/site". Use the List Kinds endpoint to retrieve all supported values. - input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search
source_refs. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. - input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with
integration.
Returns:
The newly created installation.
808 async def kinds(self, agent: str) -> InstallationKindListResponse: 809 """ 810 List available installation kinds 811 Returns the full catalogue of installation kinds supported by the platform. Use 812 the returned `kind` values when calling the Create Installation endpoint. 813 The list is platform-wide and does not vary by agent. The `agent` parameter is 814 accepted for future per-agent filtering but is currently unused. The caller must 815 have app scope to call this endpoint. 816 817 Args: 818 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 819 820 Returns: 821 The list of all supported installation kinds. 822 """ 823 return await self._http.request( 824 f"/api/v1/agents/{agent}/agent_installations/kinds", 825 response_type=InstallationKindListResponse, 826 )
List available installation kinds
Returns the full catalogue of installation kinds supported by the platform. Use
the returned kind values when calling the Create Installation endpoint.
The list is platform-wide and does not vary by agent. The agent parameter is
accepted for future per-agent filtering but is currently unused. The caller must
have app scope to call this endpoint.
Arguments:
- agent: Agent ID (
agt_...) whose installations you want to retrieve.
Returns:
The list of all supported installation kinds.
class
AsyncAgentAgentToolResource:
829class AsyncAgentAgentToolResource: 830 def __init__(self, http: HttpClient): 831 self._http = http 832 833 async def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 834 """ 835 List agent tools 836 Returns all tools for the authenticated app, optionally filtered by agent 837 or tool kind. Both explicitly created tools and tools derived from connected 838 integrations (installation-sourced tools) are included in the response. 839 Installation-sourced tools appear with `source: "installation"` and 840 `status: "active"`. They are synthesized at request time from connected 841 integrations and do not have a persistent tool ID of the `atl_...` form; 842 their `id` is a composite of the installation ID and server tool type. 843 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 844 `agent` ID that does not belong to the authenticated app returns 404. 845 Requires app scope. 846 847 Args: 848 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 849 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 850 851 Returns: 852 List of tools matching the supplied filters. 853 """ 854 query: dict[str, object] = {} 855 if kind is not None: 856 query["kind"] = kind 857 return await self._http.request( 858 f"/api/v1/agents/{agent}/agent_tools", 859 query=query, 860 response_type=AgentToolListResponse, 861 ) 862 863 async def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 864 """ 865 Create an agent tool 866 Creates a new tool and attaches it to the specified agent. Tools can be 867 either `"builtin"` (a platform-provided capability identified by 868 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 869 description, parameter schema, and handler). 870 New tools are created in `"draft"` status by default unless `status: 871 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 872 during agent runs; call the activate endpoint to promote them. 873 For built-in tools that support multiple instances per agent (those whose 874 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 875 namespace the LLM-facing tool names. Requires app scope. 876 877 Args: 878 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 879 input: Request body. 880 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 881 input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 882 input.builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 883 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 884 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 885 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 886 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 887 input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 888 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 889 input.name: Display name for the tool. Required when `kind` is `"custom"`. 890 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 891 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 892 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 893 894 Returns: 895 The newly created tool. 896 """ 897 return await self._http.request( 898 f"/api/v1/agents/{agent}/agent_tools", 899 method="POST", 900 body=input, 901 response_type=AgentTool, 902 )
AsyncAgentAgentToolResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, agent: str, *, kind: str | None = None) -> archastro.platform.types.common.AgentToolListResponse:
833 async def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 834 """ 835 List agent tools 836 Returns all tools for the authenticated app, optionally filtered by agent 837 or tool kind. Both explicitly created tools and tools derived from connected 838 integrations (installation-sourced tools) are included in the response. 839 Installation-sourced tools appear with `source: "installation"` and 840 `status: "active"`. They are synthesized at request time from connected 841 integrations and do not have a persistent tool ID of the `atl_...` form; 842 their `id` is a composite of the installation ID and server tool type. 843 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 844 `agent` ID that does not belong to the authenticated app returns 404. 845 Requires app scope. 846 847 Args: 848 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 849 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 850 851 Returns: 852 List of tools matching the supplied filters. 853 """ 854 query: dict[str, object] = {} 855 if kind is not None: 856 query["kind"] = kind 857 return await self._http.request( 858 f"/api/v1/agents/{agent}/agent_tools", 859 query=query, 860 response_type=AgentToolListResponse, 861 )
List agent tools
Returns all tools for the authenticated app, optionally filtered by agent
or tool kind. Both explicitly created tools and tools derived from connected
integrations (installation-sourced tools) are included in the response.
Installation-sourced tools appear with source: "installation" and
status: "active". They are synthesized at request time from connected
integrations and do not have a persistent tool ID of the atl_... form;
their id is a composite of the installation ID and server tool type.
Use the agent filter to retrieve tools for a specific agent. Supplying an
agent ID that does not belong to the authenticated app returns 404.
Requires app scope.
Arguments:
- agent: Filter results to tools belonging to this agent (
agt_...). Omit to return tools across all agents in the app. - kind: Filter by tool kind. One of
"builtin"or"custom". Omit to return tools of all kinds.
Returns:
List of tools matching the supplied filters.
async def
create( self, agent: str, input: AgentAgentToolCreateInput) -> archastro.platform.types.common.AgentTool:
863 async def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 864 """ 865 Create an agent tool 866 Creates a new tool and attaches it to the specified agent. Tools can be 867 either `"builtin"` (a platform-provided capability identified by 868 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 869 description, parameter schema, and handler). 870 New tools are created in `"draft"` status by default unless `status: 871 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 872 during agent runs; call the activate endpoint to promote them. 873 For built-in tools that support multiple instances per agent (those whose 874 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 875 namespace the LLM-facing tool names. Requires app scope. 876 877 Args: 878 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 879 input: Request body. 880 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 881 input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 882 input.builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 883 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 884 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 885 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 886 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 887 input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 888 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 889 input.name: Display name for the tool. Required when `kind` is `"custom"`. 890 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 891 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 892 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 893 894 Returns: 895 The newly created tool. 896 """ 897 return await self._http.request( 898 f"/api/v1/agents/{agent}/agent_tools", 899 method="POST", 900 body=input, 901 response_type=AgentTool, 902 )
Create an agent tool
Creates a new tool and attaches it to the specified agent. Tools can be
either "builtin" (a platform-provided capability identified by
builtin_tool_key) or "custom" (a caller-defined tool with its own name,
description, parameter schema, and handler).
New tools are created in "draft" status by default unless status:
"active" is explicitly supplied. Draft tools are not exposed to the LLM
during agent runs; call the activate endpoint to promote them.
For built-in tools that support multiple instances per agent (those whose
catalog entry has a multi_instance_mode), supply name_prefix to
namespace the LLM-facing tool names. Requires app scope.
Arguments:
- agent: Filter results to tools belonging to this agent (
agt_...). Omit to return tools across all agents in the app. - input: Request body.
- input.async: When
true, the tool executes asynchronously and the agent does not block waiting for a result. Applies to"custom"tools. - input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's
config_schemafor the chosenbuiltin_tool_key. Applies only to"builtin"tools. - input.builtin_tool_key: Key identifying the built-in tool type to add (e.g.
"knowledge_search"). Required whenkindis"builtin". Must match a key in the tool catalog. - input.config: Config ID (
cfg_...) referencing the script or workflow graph that implements the tool handler. Applies to"custom"tools. - input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to
"custom"tools. - input.handler_type: Execution handler for the tool. One of
"script"or"workflow_graph". Applies to"custom"tools. - input.kind: Tool kind. One of
"builtin"or"custom". - input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning.
- input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform.
- input.name: Display name for the tool. Required when
kindis"custom". - 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. Required for"namespaced"multi-instance tools; omit for single-instance tools. - input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to
"custom"tools. - input.status: Initial status of the tool. One of
"draft"or"active". Defaults to"draft"when omitted.
Returns:
The newly created tool.
class
AsyncScheduleResource:
905class AsyncScheduleResource: 906 def __init__(self, http: HttpClient): 907 self._http = http 908 909 async def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 910 """ 911 List schedules for an agent 912 Returns all schedules belonging to the specified agent in any status. Use the 913 `status` parameter to narrow results to a single lifecycle state. 914 Requires an app-scoped API key. The agent must belong to the app identified 915 by the key. 916 917 Args: 918 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 919 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 920 921 Returns: 922 Successful response 923 """ 924 query: dict[str, object] = {} 925 if status is not None: 926 query["status"] = status 927 return await self._http.request( 928 f"/api/v1/agents/{agent}/schedules", 929 query=query, 930 response_type=ScheduleListResponse, 931 ) 932 933 async def get(self, agent: str, schedule: str) -> AgentSchedule: 934 """ 935 Retrieve a schedule 936 Returns a single schedule belonging to the specified agent. Use this endpoint 937 to fetch the current state, next run time, and configuration of an individual 938 schedule. 939 Requires an app-scoped API key. Both the agent and the schedule must belong 940 to the app identified by the key. Returns 404 if the schedule does not exist 941 or belongs to a different agent. 942 943 Args: 944 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 945 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 946 947 Returns: 948 The requested agent schedule. 949 """ 950 return await self._http.request( 951 f"/api/v1/agents/{agent}/schedules/{schedule}", 952 response_type=AgentSchedule, 953 )
AsyncScheduleResource(http: archastro.platform.runtime.http_client.HttpClient)
909 async def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 910 """ 911 List schedules for an agent 912 Returns all schedules belonging to the specified agent in any status. Use the 913 `status` parameter to narrow results to a single lifecycle state. 914 Requires an app-scoped API key. The agent must belong to the app identified 915 by the key. 916 917 Args: 918 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 919 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 920 921 Returns: 922 Successful response 923 """ 924 query: dict[str, object] = {} 925 if status is not None: 926 query["status"] = status 927 return await self._http.request( 928 f"/api/v1/agents/{agent}/schedules", 929 query=query, 930 response_type=ScheduleListResponse, 931 )
List schedules for an agent
Returns all schedules belonging to the specified agent in any status. Use the
status parameter to narrow results to a single lifecycle state.
Requires an app-scoped API key. The agent must belong to the app identified
by the key.
Arguments:
- agent: Agent ID (
agi_...). The agent whose schedules you want to retrieve. - status: Filter results by schedule status. One of
"active","paused","completed","cancelled", or"expired". Omit to return schedules in all statuses.
Returns:
Successful response
933 async def get(self, agent: str, schedule: str) -> AgentSchedule: 934 """ 935 Retrieve a schedule 936 Returns a single schedule belonging to the specified agent. Use this endpoint 937 to fetch the current state, next run time, and configuration of an individual 938 schedule. 939 Requires an app-scoped API key. Both the agent and the schedule must belong 940 to the app identified by the key. Returns 404 if the schedule does not exist 941 or belongs to a different agent. 942 943 Args: 944 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 945 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 946 947 Returns: 948 The requested agent schedule. 949 """ 950 return await self._http.request( 951 f"/api/v1/agents/{agent}/schedules/{schedule}", 952 response_type=AgentSchedule, 953 )
Retrieve a schedule Returns a single schedule belonging to the specified agent. Use this endpoint to fetch the current state, next run time, and configuration of an individual schedule. Requires an app-scoped API key. Both the agent and the schedule must belong to the app identified by the key. Returns 404 if the schedule does not exist or belongs to a different agent.
Arguments:
- agent: Agent ID (
agi_...). The agent whose schedules you want to retrieve. - schedule: Schedule ID (
asc_...). The schedule to retrieve.
Returns:
The requested agent schedule.
class
AsyncAgentResource:
956class AsyncAgentResource: 957 def __init__(self, http: HttpClient): 958 self._http = http 959 self.agent_computers = AsyncAgentAgentComputerResource(http) 960 self.agent_env_vars = AsyncAgentAgentEnvVarResource(http) 961 self.agent_installations = AsyncAgentAgentInstallationResource(http) 962 self.agent_tools = AsyncAgentAgentToolResource(http) 963 self.schedules = AsyncScheduleResource(http) 964 965 async def list( 966 self, 967 *, 968 page: int | None = None, 969 page_size: int | None = None, 970 search: str | None = None, 971 user: str | None = None, 972 org_id: str | None = None, 973 template_config: str | None = None, 974 solution_config: builtins.list[str] | None = None, 975 ) -> AgentListResponse: 976 """ 977 List agents 978 Returns a paginated list of agents visible to the authenticated caller. Results are 979 ordered by creation time descending. 980 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 981 to scope the list to a specific owner. Use `template_config` to find agents whose 982 last applied template matches a given config ID. Use `solution_config` to find 983 agents whose last applied template was imported as part of any of the given 984 Solution config IDs. 985 Pagination is page-based: pass `page` and `page_size` to navigate through large 986 result sets. When called under a developer app scope, only agents belonging to that 987 app are returned. 988 989 Args: 990 page: Page number to retrieve, 1-indexed. Defaults to `1`. 991 page_size: Number of agents to return per page. Defaults to `25`. 992 search: Free-text search string matched against the agent name, org, team, and owner fields. 993 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 994 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 995 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 996 solution_config: Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs. 997 998 Returns: 999 Paginated list of agents matching the supplied filters. 1000 """ 1001 query: dict[str, object] = {} 1002 if page is not None: 1003 query["page"] = page 1004 if page_size is not None: 1005 query["page_size"] = page_size 1006 if search is not None: 1007 query["search"] = search 1008 if user is not None: 1009 query["user"] = user 1010 if org_id is not None: 1011 query["org_id"] = org_id 1012 if template_config is not None: 1013 query["template_config"] = template_config 1014 if solution_config is not None: 1015 query["solution_config"] = solution_config 1016 return await self._http.request( 1017 "/api/v1/agents", 1018 query=query, 1019 response_type=AgentListResponse, 1020 ) 1021 1022 async def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1023 """ 1024 Create an agent 1025 Creates a new agent. Supports two mutually exclusive provisioning modes. 1026 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1027 AgentTemplate config. The agent's tools, routines, skills, and installations are 1028 provisioned from that template's `config_ref` entries. 1029 **Bundle mode** pass `template_bundle` with a self-contained install payload 1030 (AgentTemplate body plus every skill, script, and config it references). The entire 1031 bundle commits in a single transaction; any failure rolls back the whole install and 1032 the response includes `installed_configs[]` one entry per persisted config. 1033 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1034 is required and a blank agent is created. Requires authentication; when called under 1035 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1036 for the target app. 1037 1038 Args: 1039 input: Request body. 1040 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1041 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1042 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1043 input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org. 1044 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1045 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1046 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1047 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1048 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1049 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1050 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1051 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1052 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1053 input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`. 1054 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1055 1056 Returns: 1057 The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` one entry per persisted config object, with `key` echoing the caller-supplied input identifier. 1058 """ 1059 return await self._http.request( 1060 "/api/v1/agents", 1061 method="POST", 1062 body=input, 1063 response_type=AgentCreateResponse, 1064 ) 1065 1066 async def delete(self, agent: str) -> None: 1067 """ 1068 Delete an agent 1069 Permanently deletes an agent and all of its associated resources. This action cannot 1070 be undone. 1071 The authenticated caller must own the agent or hold sufficient permissions within its 1072 owning org or team. When called under a developer app scope, the caller must hold the 1073 app scope for the target app. 1074 1075 Args: 1076 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1077 1078 Returns: 1079 Empty body. Returns HTTP 204 on success. 1080 """ 1081 await self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 1082 1083 async def get(self, agent: str) -> Agent: 1084 """ 1085 Retrieve an agent 1086 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1087 own the agent or hold sufficient permissions within its owning org or team. 1088 When called under a developer app scope, the agent must belong to that app. Use the 1089 list endpoint to retrieve many agents at once. 1090 1091 Args: 1092 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1093 1094 Returns: 1095 The requested agent. 1096 """ 1097 return await self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 1098 1099 async def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1100 """ 1101 Update an agent 1102 Updates one or more fields on an existing agent. Only the fields you supply are 1103 changed; omitted fields retain their current values. 1104 To clear the agent's default model, pass `model` as an empty string. The 1105 authenticated caller must own the agent or hold write permissions within its owning 1106 org or team. When called under a developer app scope, the caller must hold the app 1107 scope for the target app. 1108 1109 Args: 1110 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1111 input: Request body. 1112 input.acl: Replacement access control list. Fully replaces the existing ACL. 1113 input.email: New email address for the agent. 1114 input.identity: Replacement identity system-prompt string describing who the agent is. 1115 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1116 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1117 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1118 input.name: New display name for the agent. 1119 input.org: Organization ID (`org_...`) to transfer ownership to. 1120 input.originator: Replacement originator label identifying the source or author of the agent. 1121 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1122 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1123 input.team: Team ID (`team_...`) to transfer ownership to. 1124 input.user: User ID (`usr_...`) to transfer ownership to. 1125 1126 Returns: 1127 The updated agent with all current field values. 1128 """ 1129 return await self._http.request( 1130 f"/api/v1/agents/{agent}", 1131 method="PATCH", 1132 body=input, 1133 response_type=Agent, 1134 ) 1135 1136 async def agent_health_actions( 1137 self, 1138 agent: str, 1139 *, 1140 source: builtins.list[str] | None = None, 1141 status: builtins.list[str] | None = None, 1142 kind: builtins.list[str] | None = None, 1143 ) -> HealthActionListResponse: 1144 """ 1145 List health actions for an agent 1146 Returns all health actions associated with a given agent. Health actions 1147 represent required or recommended steps such as setting environment 1148 variables, completing OAuth installations, or running custom verifiers 1149 that an agent needs to reach a healthy state. 1150 Results are not paginated; the full list for the agent is returned. Use 1151 the `source`, `status`, and `kind` filters to narrow results to the 1152 subset your UI or workflow needs. Multiple values for the same filter 1153 are treated as OR (e.g. passing two statuses returns actions matching 1154 either). The caller must be authenticated and scoped to the app that 1155 owns the agent. 1156 1157 Args: 1158 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1159 source: Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages. 1160 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1161 kind: Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds. 1162 1163 Returns: 1164 Object containing a `data` array of health action objects for the specified agent. 1165 """ 1166 query: dict[str, object] = {} 1167 if source is not None: 1168 query["source"] = source 1169 if status is not None: 1170 query["status"] = status 1171 if kind is not None: 1172 query["kind"] = kind 1173 return await self._http.request( 1174 f"/api/v1/agents/{agent}/agent_health_actions", 1175 query=query, 1176 response_type=HealthActionListResponse, 1177 ) 1178 1179 async def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1180 """ 1181 Create a routine 1182 Creates a new routine and attaches it to the specified agent. Routines define 1183 how an agent responds to events or a cron schedule; the `handler_type` controls 1184 which execution model is used. 1185 The routine is created in `"draft"` status by default. To start processing 1186 events immediately, either pass `status: "active"` or call the activate 1187 endpoint after creation. Scheduled routines must run no more frequently than 1188 once per hour. Requires app scope. 1189 1190 Args: 1191 agent: Agent ID (`agt_...`) that this routine will be attached to. 1192 input: Request body. 1193 input.acl: Access control list governing who can read or manage this routine. 1194 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1195 input.description: Optional human-readable description of what this routine does. 1196 input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). 1197 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1198 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1199 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1200 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1201 input.name: Human-readable display name for the routine. 1202 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1203 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1204 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1205 input.script: Inline script source. Required when `handler_type` is `"script"`. 1206 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1207 input.steps: Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. 1208 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1209 1210 Returns: 1211 The newly created routine. 1212 """ 1213 return await self._http.request( 1214 f"/api/v1/agents/{agent}/agent_routines", 1215 method="POST", 1216 body=input, 1217 response_type=AgentRoutine, 1218 ) 1219 1220 async def agent_working_memory( 1221 self, 1222 agent: str, 1223 *, 1224 page: int | None = None, 1225 page_size: int | None = None, 1226 search: str | None = None, 1227 ) -> WorkingMemoryEntryListResponse: 1228 """ 1229 List working memory entries for an agent 1230 Returns a paginated list of working memory entries belonging to the specified 1231 agent. Entries are key-value pairs the agent stores for context between 1232 interactions. Results are ordered by creation time descending (newest first) 1233 and can be filtered with a substring search against the key name. 1234 Requires an app-scoped API key. The authenticated caller must have access to 1235 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1236 404 if the agent does not exist within the accessible scope. 1237 1238 Args: 1239 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1240 page: Page number to retrieve, starting at 1. Defaults to 1. 1241 page_size: Number of entries to return per page. Defaults to 25. 1242 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1243 1244 Returns: 1245 Paginated list of working memory entries for the agent. 1246 """ 1247 query: dict[str, object] = {} 1248 if page is not None: 1249 query["page"] = page 1250 if page_size is not None: 1251 query["page_size"] = page_size 1252 if search is not None: 1253 query["search"] = search 1254 return await self._http.request( 1255 f"/api/v1/agents/{agent}/agent_working_memory", 1256 query=query, 1257 response_type=WorkingMemoryEntryListResponse, 1258 ) 1259 1260 async def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 1261 """ 1262 Export an agent as an AgentTemplate 1263 Reconstructs an AgentTemplate config from a deployed agent and all of its 1264 sub-resources (tools, routines, skills, installations). Returns the template 1265 definition together with every dependent config file (scripts, workflows, skills, 1266 schemas) and their raw content, producing a fully self-contained export bundle. 1267 Use this endpoint to snapshot an agent's current configuration for backup, 1268 migration, or to seed a new Solution template. Pass `remove_identity: true` to 1269 strip instance-specific fields (email, phone number) before export. 1270 The authenticated caller must own the agent or hold sufficient permissions within 1271 its owning org or team. When called under a developer app scope, the caller must 1272 hold the app scope for the target app. 1273 1274 Args: 1275 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 1276 remove_identity: When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint. 1277 1278 Returns: 1279 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 1280 """ 1281 query: dict[str, object] = {} 1282 if remove_identity is not None: 1283 query["remove_identity"] = remove_identity 1284 return await self._http.request( 1285 f"/api/v1/agents/{agent}/export", 1286 query=query, 1287 response_type=AgentExport, 1288 ) 1289 1290 async def health(self, agent: str) -> AgentHealth: 1291 """ 1292 Retrieve an agent's health profile 1293 Returns an aggregate health profile for the specified agent, including an overall 1294 status, a numeric health score, recent activity metrics, and a list of recommended 1295 remediation actions. 1296 The health check is computed on demand at request time. The `checked_at` timestamp 1297 in the response reflects when the evaluation ran. Use this endpoint to surface 1298 diagnostics about tool availability, model configuration, and runtime activity in 1299 dashboards or monitoring workflows. 1300 The authenticated caller must own the agent or hold sufficient permissions within 1301 its owning org or team. When called under a developer app scope, the caller must 1302 hold the app scope for the target app. 1303 1304 Args: 1305 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 1306 1307 Returns: 1308 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 1309 """ 1310 return await self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 1311 1312 async def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 1313 """ 1314 Search an agent's knowledge base 1315 Performs a semantic search over an agent's knowledge base and returns a ranked, 1316 `kind`-discriminated list of matching items. 1317 Two item kinds may appear in `data`: 1318 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 1319 - `"document"` document-level results. Present only when the agent has an active 1320 `archastro/knowledge` installation. 1321 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 1322 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 1323 chunks appear before documents. The total number of results is capped at `max_results` 1324 across both kinds. 1325 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 1326 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 1327 1328 Args: 1329 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 1330 input: Request body. 1331 input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`. 1332 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 1333 input.query: Natural-language search query used to retrieve relevant knowledge items. 1334 input.recency_days: When set, restricts results to items indexed within the last N days. 1335 input.source_types: Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types. 1336 1337 Returns: 1338 Successful response 1339 """ 1340 return await self._http.request( 1341 f"/api/v1/agents/{agent}/search", 1342 method="POST", 1343 body=input, 1344 response_type=AgentSearchResponse, 1345 ) 1346 1347 async def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 1348 """ 1349 Create a thread for an agent 1350 Creates a new thread owned by the specified agent. The thread is scoped to the 1351 agent's identity and is immediately available for messaging. 1352 The authenticated caller must have access to the agent's parent app. If your 1353 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 1354 Attempting to create a thread for an agent you cannot access returns 404. 1355 By default the platform may send an automatic welcome message into the new 1356 thread. Pass `skip_welcome_message: true` to suppress this behavior. 1357 1358 Args: 1359 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 1360 input: Request body. 1361 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 1362 input.thread: Attributes for the new thread. 1363 1364 Returns: 1365 The newly created thread. 1366 """ 1367 return await self._http.request( 1368 f"/api/v1/agents/{agent}/threads", 1369 method="POST", 1370 body=input, 1371 response_type=Thread, 1372 ) 1373 1374 async def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 1375 """ 1376 Upgrade an agent from an AgentTemplate 1377 Upgrades an existing agent by reconciling it against an AgentTemplate from a 1378 Solution. Supports two modes: 1379 - `"reapply"` (default) re-applies the agent's currently tracked template, 1380 picking up any changes the template author has made since the last apply. 1381 - `"replace"` moves the agent to a different template. `template` is required 1382 in this mode. 1383 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 1384 removes, noops) without writing any changes. The response includes a 1385 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 1386 live apply to guard against the diff changing between review and execution. 1387 Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, 1388 `originator`, `model`) let you pin instance-specific values that should not be 1389 overwritten by the template during the upgrade. 1390 The authenticated caller must own the agent or hold write permissions within its 1391 owning org or team. When called under a developer app scope, the caller must hold 1392 the app scope for the target app. 1393 1394 Args: 1395 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 1396 input: Request body. 1397 input.dry_run: When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. 1398 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 1399 input.expected_review_fingerprint: Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. 1400 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 1401 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 1402 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 1403 input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. 1404 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 1405 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 1406 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 1407 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 1408 1409 Returns: 1410 The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted. 1411 """ 1412 return await self._http.request( 1413 f"/api/v1/agents/{agent}/upgrade", 1414 method="POST", 1415 body=input, 1416 response_type=AgentUpgradeResponse, 1417 )
AsyncAgentResource(http: archastro.platform.runtime.http_client.HttpClient)
957 def __init__(self, http: HttpClient): 958 self._http = http 959 self.agent_computers = AsyncAgentAgentComputerResource(http) 960 self.agent_env_vars = AsyncAgentAgentEnvVarResource(http) 961 self.agent_installations = AsyncAgentAgentInstallationResource(http) 962 self.agent_tools = AsyncAgentAgentToolResource(http) 963 self.schedules = AsyncScheduleResource(http)
async def
list( self, *, page: int | None = None, page_size: int | None = None, search: str | None = None, user: str | None = None, org_id: str | None = None, template_config: str | None = None, solution_config: list[str] | None = None) -> archastro.platform.types.common.AgentListResponse:
965 async def list( 966 self, 967 *, 968 page: int | None = None, 969 page_size: int | None = None, 970 search: str | None = None, 971 user: str | None = None, 972 org_id: str | None = None, 973 template_config: str | None = None, 974 solution_config: builtins.list[str] | None = None, 975 ) -> AgentListResponse: 976 """ 977 List agents 978 Returns a paginated list of agents visible to the authenticated caller. Results are 979 ordered by creation time descending. 980 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 981 to scope the list to a specific owner. Use `template_config` to find agents whose 982 last applied template matches a given config ID. Use `solution_config` to find 983 agents whose last applied template was imported as part of any of the given 984 Solution config IDs. 985 Pagination is page-based: pass `page` and `page_size` to navigate through large 986 result sets. When called under a developer app scope, only agents belonging to that 987 app are returned. 988 989 Args: 990 page: Page number to retrieve, 1-indexed. Defaults to `1`. 991 page_size: Number of agents to return per page. Defaults to `25`. 992 search: Free-text search string matched against the agent name, org, team, and owner fields. 993 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 994 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 995 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 996 solution_config: Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs. 997 998 Returns: 999 Paginated list of agents matching the supplied filters. 1000 """ 1001 query: dict[str, object] = {} 1002 if page is not None: 1003 query["page"] = page 1004 if page_size is not None: 1005 query["page_size"] = page_size 1006 if search is not None: 1007 query["search"] = search 1008 if user is not None: 1009 query["user"] = user 1010 if org_id is not None: 1011 query["org_id"] = org_id 1012 if template_config is not None: 1013 query["template_config"] = template_config 1014 if solution_config is not None: 1015 query["solution_config"] = solution_config 1016 return await self._http.request( 1017 "/api/v1/agents", 1018 query=query, 1019 response_type=AgentListResponse, 1020 )
List agents
Returns a paginated list of agents visible to the authenticated caller. Results are
ordered by creation time descending.
Use search to filter by name, org, team, or owner fields. Use user or org_id
to scope the list to a specific owner. Use template_config to find agents whose
last applied template matches a given config ID. Use solution_config to find
agents whose last applied template was imported as part of any of the given
Solution config IDs.
Pagination is page-based: pass page and page_size to navigate through large
result sets. When called under a developer app scope, only agents belonging to that
app are returned.
Arguments:
- page: Page number to retrieve, 1-indexed. Defaults to
1. - page_size: Number of agents to return per page. Defaults to
25. - search: Free-text search string matched against the agent name, org, team, and owner fields.
- user: User ID (
usr_...) to filter by. Returns only agents owned by this user. - org_id: Organization ID (
org_...) to filter by. Returns only agents owned by this org. - template_config: Config ID (
cfg_...) orlookup_keyof an AgentTemplate. Returns only agents whose last applied template matches. - solution_config: Solution config IDs (
cfg_...) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs.
Returns:
Paginated list of agents matching the supplied filters.
async def
create( self, input: AgentCreateInput) -> archastro.platform.types.common.AgentCreateResponse:
1022 async def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1023 """ 1024 Create an agent 1025 Creates a new agent. Supports two mutually exclusive provisioning modes. 1026 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1027 AgentTemplate config. The agent's tools, routines, skills, and installations are 1028 provisioned from that template's `config_ref` entries. 1029 **Bundle mode** pass `template_bundle` with a self-contained install payload 1030 (AgentTemplate body plus every skill, script, and config it references). The entire 1031 bundle commits in a single transaction; any failure rolls back the whole install and 1032 the response includes `installed_configs[]` one entry per persisted config. 1033 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1034 is required and a blank agent is created. Requires authentication; when called under 1035 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1036 for the target app. 1037 1038 Args: 1039 input: Request body. 1040 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1041 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1042 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1043 input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org. 1044 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1045 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1046 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1047 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1048 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1049 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1050 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1051 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1052 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1053 input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`. 1054 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1055 1056 Returns: 1057 The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` one entry per persisted config object, with `key` echoing the caller-supplied input identifier. 1058 """ 1059 return await self._http.request( 1060 "/api/v1/agents", 1061 method="POST", 1062 body=input, 1063 response_type=AgentCreateResponse, 1064 )
Create an agent
Creates a new agent. Supports two mutually exclusive provisioning modes.
Template mode pass template with the ID or lookup_key of an existing
AgentTemplate config. The agent's tools, routines, skills, and installations are
provisioned from that template's config_ref entries.
Bundle mode pass template_bundle with a self-contained install payload
(AgentTemplate body plus every skill, script, and config it references). The entire
bundle commits in a single transaction; any failure rolls back the whole install and
the response includes installed_configs[] one entry per persisted config.
Pass exactly one of template or template_bundle. If neither is supplied, name
is required and a blank agent is created. Requires authentication; when called under
a developer app scope (/developer/apps/:app/...), the caller must hold the app scope
for the target app.
Arguments:
- input: Request body.
- input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent.
- input.email: Email address assigned to the agent. Used as the agent's contact identity.
- input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
- input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
- input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform.
- input.model: Default AI model identifier for this agent, e.g.
claude-sonnet-4-5. Overridden per-request when the caller specifies a model. - input.name: Display name for the agent. Required when neither
templatenortemplate_bundleis provided. - input.org: Organization ID (
org_...) that should own this agent. Mutually exclusive withteamanduser. - input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
- input.phone_number: Phone number assigned to the agent in E.164 format, e.g.
+15550001234. - input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present.
- input.team: Team ID (
team_...) that should own this agent. Mutually exclusive withorganduser. - input.template: ID (
cfg_...) orlookup_keyof an existing AgentTemplate config to provision from. Mutually exclusive withtemplate_bundle. - input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with
template. - input.user: User ID (
usr_...) that should own this agent. Mutually exclusive withorgandteam.
Returns:
The newly created agent. When
template_bundlewas supplied, the response also includesinstalled_configs[]one entry per persisted config object, withkeyechoing the caller-supplied input identifier.
async def
delete(self, agent: str) -> None:
1066 async def delete(self, agent: str) -> None: 1067 """ 1068 Delete an agent 1069 Permanently deletes an agent and all of its associated resources. This action cannot 1070 be undone. 1071 The authenticated caller must own the agent or hold sufficient permissions within its 1072 owning org or team. When called under a developer app scope, the caller must hold the 1073 app scope for the target app. 1074 1075 Args: 1076 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1077 1078 Returns: 1079 Empty body. Returns HTTP 204 on success. 1080 """ 1081 await self._http.request(f"/api/v1/agents/{agent}", method="DELETE")
Delete an agent Permanently deletes an agent and all of its associated resources. This action cannot be undone. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to delete.
Returns:
Empty body. Returns HTTP 204 on success.
1083 async def get(self, agent: str) -> Agent: 1084 """ 1085 Retrieve an agent 1086 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1087 own the agent or hold sufficient permissions within its owning org or team. 1088 When called under a developer app scope, the agent must belong to that app. Use the 1089 list endpoint to retrieve many agents at once. 1090 1091 Args: 1092 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1093 1094 Returns: 1095 The requested agent. 1096 """ 1097 return await self._http.request(f"/api/v1/agents/{agent}", response_type=Agent)
Retrieve an agent
Returns the agent identified by ID or lookup_key. The authenticated caller must
own the agent or hold sufficient permissions within its owning org or team.
When called under a developer app scope, the agent must belong to that app. Use the
list endpoint to retrieve many agents at once.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to retrieve.
Returns:
The requested agent.
async def
update( self, agent: str, input: AgentUpdateInput) -> archastro.platform.types.common.Agent:
1099 async def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1100 """ 1101 Update an agent 1102 Updates one or more fields on an existing agent. Only the fields you supply are 1103 changed; omitted fields retain their current values. 1104 To clear the agent's default model, pass `model` as an empty string. The 1105 authenticated caller must own the agent or hold write permissions within its owning 1106 org or team. When called under a developer app scope, the caller must hold the app 1107 scope for the target app. 1108 1109 Args: 1110 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1111 input: Request body. 1112 input.acl: Replacement access control list. Fully replaces the existing ACL. 1113 input.email: New email address for the agent. 1114 input.identity: Replacement identity system-prompt string describing who the agent is. 1115 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1116 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1117 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1118 input.name: New display name for the agent. 1119 input.org: Organization ID (`org_...`) to transfer ownership to. 1120 input.originator: Replacement originator label identifying the source or author of the agent. 1121 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1122 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1123 input.team: Team ID (`team_...`) to transfer ownership to. 1124 input.user: User ID (`usr_...`) to transfer ownership to. 1125 1126 Returns: 1127 The updated agent with all current field values. 1128 """ 1129 return await self._http.request( 1130 f"/api/v1/agents/{agent}", 1131 method="PATCH", 1132 body=input, 1133 response_type=Agent, 1134 )
Update an agent
Updates one or more fields on an existing agent. Only the fields you supply are
changed; omitted fields retain their current values.
To clear the agent's default model, pass model as an empty string. The
authenticated caller must own the agent or hold write permissions within its owning
org or team. When called under a developer app scope, the caller must hold the app
scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to update. - input: Request body.
- input.acl: Replacement access control list. Fully replaces the existing ACL.
- input.email: New email address for the agent.
- input.identity: Replacement identity system-prompt string describing who the agent is.
- input.lookup_key: New
lookup_keyslug. Must be unique within the owning app or org. - input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged.
- input.model: New default AI model identifier, e.g.
claude-sonnet-4-5. Pass an empty string to clear the agent's default model. - input.name: New display name for the agent.
- input.org: Organization ID (
org_...) to transfer ownership to. - input.originator: Replacement originator label identifying the source or author of the agent.
- input.phone_number: New phone number for the agent in E.164 format, e.g.
+15550001234. - input.profile_picture: Replacement profile picture. All three subfields are required when this object is present.
- input.team: Team ID (
team_...) to transfer ownership to. - input.user: User ID (
usr_...) to transfer ownership to.
Returns:
The updated agent with all current field values.
async def
agent_health_actions( self, agent: str, *, source: list[str] | None = None, status: list[str] | None = None, kind: list[str] | None = None) -> archastro.platform.types.common.HealthActionListResponse:
1136 async def agent_health_actions( 1137 self, 1138 agent: str, 1139 *, 1140 source: builtins.list[str] | None = None, 1141 status: builtins.list[str] | None = None, 1142 kind: builtins.list[str] | None = None, 1143 ) -> HealthActionListResponse: 1144 """ 1145 List health actions for an agent 1146 Returns all health actions associated with a given agent. Health actions 1147 represent required or recommended steps such as setting environment 1148 variables, completing OAuth installations, or running custom verifiers 1149 that an agent needs to reach a healthy state. 1150 Results are not paginated; the full list for the agent is returned. Use 1151 the `source`, `status`, and `kind` filters to narrow results to the 1152 subset your UI or workflow needs. Multiple values for the same filter 1153 are treated as OR (e.g. passing two statuses returns actions matching 1154 either). The caller must be authenticated and scoped to the app that 1155 owns the agent. 1156 1157 Args: 1158 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1159 source: Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages. 1160 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1161 kind: Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds. 1162 1163 Returns: 1164 Object containing a `data` array of health action objects for the specified agent. 1165 """ 1166 query: dict[str, object] = {} 1167 if source is not None: 1168 query["source"] = source 1169 if status is not None: 1170 query["status"] = status 1171 if kind is not None: 1172 query["kind"] = kind 1173 return await self._http.request( 1174 f"/api/v1/agents/{agent}/agent_health_actions", 1175 query=query, 1176 response_type=HealthActionListResponse, 1177 )
List health actions for an agent
Returns all health actions associated with a given agent. Health actions
represent required or recommended steps such as setting environment
variables, completing OAuth installations, or running custom verifiers
that an agent needs to reach a healthy state.
Results are not paginated; the full list for the agent is returned. Use
the source, status, and kind filters to narrow results to the
subset your UI or workflow needs. Multiple values for the same filter
are treated as OR (e.g. passing two statuses returns actions matching
either). The caller must be authenticated and scoped to the app that
owns the agent.
Arguments:
- agent: Agent ID (
agt_...) or lookup key of the agent whose health actions you want to list. - source: Filter results to actions from one or more lifecycle stages. Accepted values:
"setup"(actions created during agent installation) and"health"(ongoing health checks). Omit to return actions from all stages. - status: Filter results to actions in one or more statuses. Accepted values:
"pending","completed","skipped", and"degraded". Omit to return actions in all statuses. - kind: Filter results to actions of one or more kinds. Accepted values:
"env_var"(a required secret or config value),"install"(an OAuth or integration install step), and"custom"(a platform-defined check). Omit to return all kinds.
Returns:
Object containing a
dataarray of health action objects for the specified agent.
async def
agent_routines( self, agent: str, input: AgentAgentRoutinesInput) -> archastro.platform.types.common.AgentRoutine:
1179 async def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1180 """ 1181 Create a routine 1182 Creates a new routine and attaches it to the specified agent. Routines define 1183 how an agent responds to events or a cron schedule; the `handler_type` controls 1184 which execution model is used. 1185 The routine is created in `"draft"` status by default. To start processing 1186 events immediately, either pass `status: "active"` or call the activate 1187 endpoint after creation. Scheduled routines must run no more frequently than 1188 once per hour. Requires app scope. 1189 1190 Args: 1191 agent: Agent ID (`agt_...`) that this routine will be attached to. 1192 input: Request body. 1193 input.acl: Access control list governing who can read or manage this routine. 1194 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1195 input.description: Optional human-readable description of what this routine does. 1196 input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). 1197 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1198 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1199 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1200 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1201 input.name: Human-readable display name for the routine. 1202 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1203 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1204 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1205 input.script: Inline script source. Required when `handler_type` is `"script"`. 1206 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1207 input.steps: Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. 1208 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1209 1210 Returns: 1211 The newly created routine. 1212 """ 1213 return await self._http.request( 1214 f"/api/v1/agents/{agent}/agent_routines", 1215 method="POST", 1216 body=input, 1217 response_type=AgentRoutine, 1218 )
Create a routine
Creates a new routine and attaches it to the specified agent. Routines define
how an agent responds to events or a cron schedule; the handler_type controls
which execution model is used.
The routine is created in "draft" status by default. To start processing
events immediately, either pass status: "active" or call the activate
endpoint after creation. Scheduled routines must run no more frequently than
once per hour. Requires app scope.
Arguments:
- agent: Agent ID (
agt_...) that this routine will be attached to. - input: Request body.
- input.acl: Access control list governing who can read or manage this routine.
- input.config: Workflow config ID (
cfg_...). Required whenhandler_typeis"workflow_graph". - input.description: Optional human-readable description of what this routine does.
- input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a
"filters"map and an optional"dedupe_key_path"(a JSON path used to deduplicate events, e.g."$.thread.id"). - input.event_type: Event type that triggers this routine. Deprecated use
event_configinstead. - input.handler_type: Execution model for this routine. One of
"workflow_graph","script","preset", or"chain". - input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.
- input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.
- input.name: Human-readable display name for the routine.
- input.preset_config: Configuration passed to the preset at runtime. Used when
handler_typeis"preset". - input.preset_name: Name of the registered preset to use. Required when
handler_typeis"preset". - input.schedule: Cron expression for time-triggered routines (e.g.
"0 9 * * 1"). Must not be more frequent than once per hour. - input.script: Inline script source. Required when
handler_typeis"script". - input.status: Initial lifecycle status. One of
"draft"or"active". Defaults to"draft". - input.steps: Ordered list of steps for a chain handler. Required when
handler_typeis"chain"; must be omitted or empty otherwise. Each step must have exactly one handler body field (preset_name,script, orconfig) matching that step'shandler_type. - input.trigger_context: Context in which the routine is triggered. One of
"chat_session"or"event". Defaults to"event".
Returns:
The newly created routine.
async def
agent_working_memory( self, agent: str, *, page: int | None = None, page_size: int | None = None, search: str | None = None) -> archastro.platform.types.common.WorkingMemoryEntryListResponse:
1220 async def agent_working_memory( 1221 self, 1222 agent: str, 1223 *, 1224 page: int | None = None, 1225 page_size: int | None = None, 1226 search: str | None = None, 1227 ) -> WorkingMemoryEntryListResponse: 1228 """ 1229 List working memory entries for an agent 1230 Returns a paginated list of working memory entries belonging to the specified 1231 agent. Entries are key-value pairs the agent stores for context between 1232 interactions. Results are ordered by creation time descending (newest first) 1233 and can be filtered with a substring search against the key name. 1234 Requires an app-scoped API key. The authenticated caller must have access to 1235 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1236 404 if the agent does not exist within the accessible scope. 1237 1238 Args: 1239 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1240 page: Page number to retrieve, starting at 1. Defaults to 1. 1241 page_size: Number of entries to return per page. Defaults to 25. 1242 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1243 1244 Returns: 1245 Paginated list of working memory entries for the agent. 1246 """ 1247 query: dict[str, object] = {} 1248 if page is not None: 1249 query["page"] = page 1250 if page_size is not None: 1251 query["page_size"] = page_size 1252 if search is not None: 1253 query["search"] = search 1254 return await self._http.request( 1255 f"/api/v1/agents/{agent}/agent_working_memory", 1256 query=query, 1257 response_type=WorkingMemoryEntryListResponse, 1258 )
List working memory entries for an agent Returns a paginated list of working memory entries belonging to the specified agent. Entries are key-value pairs the agent stores for context between interactions. Results are ordered by creation time descending (newest first) and can be filtered with a substring search against the key name. Requires an app-scoped API key. The authenticated caller must have access to the app the agent belongs to. Returns 403 if the key is not app-scoped, and 404 if the agent does not exist within the accessible scope.
Arguments:
- agent: Agent ID (
agt_...) whose working memory entries to retrieve. - page: Page number to retrieve, starting at 1. Defaults to 1.
- page_size: Number of entries to return per page. Defaults to 25.
- search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys.
Returns:
Paginated list of working memory entries for the agent.
async def
export( self, agent: str, *, remove_identity: bool | None = None) -> archastro.platform.types.common.AgentExport:
1260 async def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 1261 """ 1262 Export an agent as an AgentTemplate 1263 Reconstructs an AgentTemplate config from a deployed agent and all of its 1264 sub-resources (tools, routines, skills, installations). Returns the template 1265 definition together with every dependent config file (scripts, workflows, skills, 1266 schemas) and their raw content, producing a fully self-contained export bundle. 1267 Use this endpoint to snapshot an agent's current configuration for backup, 1268 migration, or to seed a new Solution template. Pass `remove_identity: true` to 1269 strip instance-specific fields (email, phone number) before export. 1270 The authenticated caller must own the agent or hold sufficient permissions within 1271 its owning org or team. When called under a developer app scope, the caller must 1272 hold the app scope for the target app. 1273 1274 Args: 1275 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 1276 remove_identity: When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint. 1277 1278 Returns: 1279 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 1280 """ 1281 query: dict[str, object] = {} 1282 if remove_identity is not None: 1283 query["remove_identity"] = remove_identity 1284 return await self._http.request( 1285 f"/api/v1/agents/{agent}/export", 1286 query=query, 1287 response_type=AgentExport, 1288 )
Export an agent as an AgentTemplate
Reconstructs an AgentTemplate config from a deployed agent and all of its
sub-resources (tools, routines, skills, installations). Returns the template
definition together with every dependent config file (scripts, workflows, skills,
schemas) and their raw content, producing a fully self-contained export bundle.
Use this endpoint to snapshot an agent's current configuration for backup,
migration, or to seed a new Solution template. Pass remove_identity: true to
strip instance-specific fields (email, phone number) before export.
The authenticated caller must own the agent or hold sufficient permissions within
its owning org or team. When called under a developer app scope, the caller must
hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to export. - remove_identity: When
true, strips instance-unique identity fields (email,phone_number) from the exported template so it can be reused as a generic blueprint.
Returns:
Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content.
1290 async def health(self, agent: str) -> AgentHealth: 1291 """ 1292 Retrieve an agent's health profile 1293 Returns an aggregate health profile for the specified agent, including an overall 1294 status, a numeric health score, recent activity metrics, and a list of recommended 1295 remediation actions. 1296 The health check is computed on demand at request time. The `checked_at` timestamp 1297 in the response reflects when the evaluation ran. Use this endpoint to surface 1298 diagnostics about tool availability, model configuration, and runtime activity in 1299 dashboards or monitoring workflows. 1300 The authenticated caller must own the agent or hold sufficient permissions within 1301 its owning org or team. When called under a developer app scope, the caller must 1302 hold the app scope for the target app. 1303 1304 Args: 1305 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 1306 1307 Returns: 1308 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 1309 """ 1310 return await self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth)
Retrieve an agent's health profile
Returns an aggregate health profile for the specified agent, including an overall
status, a numeric health score, recent activity metrics, and a list of recommended
remediation actions.
The health check is computed on demand at request time. The checked_at timestamp
in the response reflects when the evaluation ran. Use this endpoint to surface
diagnostics about tool availability, model configuration, and runtime activity in
dashboards or monitoring workflows.
The authenticated caller must own the agent or hold sufficient permissions within
its owning org or team. When called under a developer app scope, the caller must
hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to evaluate.
Returns:
Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions.
1312 async def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 1313 """ 1314 Search an agent's knowledge base 1315 Performs a semantic search over an agent's knowledge base and returns a ranked, 1316 `kind`-discriminated list of matching items. 1317 Two item kinds may appear in `data`: 1318 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 1319 - `"document"` document-level results. Present only when the agent has an active 1320 `archastro/knowledge` installation. 1321 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 1322 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 1323 chunks appear before documents. The total number of results is capped at `max_results` 1324 across both kinds. 1325 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 1326 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 1327 1328 Args: 1329 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 1330 input: Request body. 1331 input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`. 1332 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 1333 input.query: Natural-language search query used to retrieve relevant knowledge items. 1334 input.recency_days: When set, restricts results to items indexed within the last N days. 1335 input.source_types: Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types. 1336 1337 Returns: 1338 Successful response 1339 """ 1340 return await self._http.request( 1341 f"/api/v1/agents/{agent}/search", 1342 method="POST", 1343 body=input, 1344 response_type=AgentSearchResponse, 1345 )
Search an agent's knowledge base
Performs a semantic search over an agent's knowledge base and returns a ranked,
kind-discriminated list of matching items.
Two item kinds may appear in data:
"chunk"chunk-level results from the agent's context store. Present for all agents."document"document-level results. Present only when the agent has an activearchastro/knowledgeinstallation. Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to be comparable across kinds, then merged into a single ranked list. On a relevance tie, chunks appear before documents. The total number of results is capped atmax_resultsacross both kinds. Usemodeto choose the retrieval strategy:"hybrid"(default) combines vector and full-text search;"vector"and"fulltext"select each strategy independently.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent whose knowledge base to search. - input: Request body.
- input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to
20; maximum is100. - input.mode: Retrieval strategy. One of
"hybrid"(default),"vector", or"fulltext". - input.query: Natural-language search query used to retrieve relevant knowledge items.
- input.recency_days: When set, restricts results to items indexed within the last N days.
- input.source_types: Array of source-type slugs used to filter chunk results, e.g.
["web", "file"]. Omit to include all source types.
Returns:
Successful response
async def
threads( self, agent: str, input: AgentThreadsInput) -> archastro.platform.types.threads.Thread:
1347 async def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 1348 """ 1349 Create a thread for an agent 1350 Creates a new thread owned by the specified agent. The thread is scoped to the 1351 agent's identity and is immediately available for messaging. 1352 The authenticated caller must have access to the agent's parent app. If your 1353 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 1354 Attempting to create a thread for an agent you cannot access returns 404. 1355 By default the platform may send an automatic welcome message into the new 1356 thread. Pass `skip_welcome_message: true` to suppress this behavior. 1357 1358 Args: 1359 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 1360 input: Request body. 1361 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 1362 input.thread: Attributes for the new thread. 1363 1364 Returns: 1365 The newly created thread. 1366 """ 1367 return await self._http.request( 1368 f"/api/v1/agents/{agent}/threads", 1369 method="POST", 1370 body=input, 1371 response_type=Thread, 1372 )
Create a thread for an agent
Creates a new thread owned by the specified agent. The thread is scoped to the
agent's identity and is immediately available for messaging.
The authenticated caller must have access to the agent's parent app. If your
API key is scoped to a specific app, pass that app's ID via the app parameter.
Attempting to create a thread for an agent you cannot access returns 404.
By default the platform may send an automatic welcome message into the new
thread. Pass skip_welcome_message: true to suppress this behavior.
Arguments:
- agent: Agent ID (
agt_...). The thread will be owned by this agent. - input: Request body.
- input.skip_welcome_message: When
true, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults tofalse. - input.thread: Attributes for the new thread.
Returns:
The newly created thread.
async def
upgrade( self, agent: str, input: AgentUpgradeInput) -> archastro.platform.types.common.AgentUpgradeResponse:
1374 async def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 1375 """ 1376 Upgrade an agent from an AgentTemplate 1377 Upgrades an existing agent by reconciling it against an AgentTemplate from a 1378 Solution. Supports two modes: 1379 - `"reapply"` (default) re-applies the agent's currently tracked template, 1380 picking up any changes the template author has made since the last apply. 1381 - `"replace"` moves the agent to a different template. `template` is required 1382 in this mode. 1383 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 1384 removes, noops) without writing any changes. The response includes a 1385 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 1386 live apply to guard against the diff changing between review and execution. 1387 Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, 1388 `originator`, `model`) let you pin instance-specific values that should not be 1389 overwritten by the template during the upgrade. 1390 The authenticated caller must own the agent or hold write permissions within its 1391 owning org or team. When called under a developer app scope, the caller must hold 1392 the app scope for the target app. 1393 1394 Args: 1395 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 1396 input: Request body. 1397 input.dry_run: When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. 1398 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 1399 input.expected_review_fingerprint: Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. 1400 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 1401 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 1402 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 1403 input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. 1404 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 1405 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 1406 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 1407 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 1408 1409 Returns: 1410 The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted. 1411 """ 1412 return await self._http.request( 1413 f"/api/v1/agents/{agent}/upgrade", 1414 method="POST", 1415 body=input, 1416 response_type=AgentUpgradeResponse, 1417 )
Upgrade an agent from an AgentTemplate Upgrades an existing agent by reconciling it against an AgentTemplate from a Solution. Supports two modes:
"reapply"(default) re-applies the agent's currently tracked template, picking up any changes the template author has made since the last apply."replace"moves the agent to a different template.templateis required in this mode. Setdry_run: trueto compute and return the full upgrade diff (adds, updates, removes, noops) without writing any changes. The response includes areview_fingerprintyou can pass back viaexpected_review_fingerprinton the live apply to guard against the diff changing between review and execution. Safe overrides (name,email,phone_number,metadata,identity,originator,model) let you pin instance-specific values that should not be overwritten by the template during the upgrade. The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to upgrade. - input: Request body.
- input.dry_run: When
true, computes and returns the full upgrade diff without persisting any changes. Use withexpected_review_fingerprintto guard the live apply. - input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.
- input.expected_review_fingerprint: Stale-review guard. Pass the
review_fingerprintreturned by a priordry_runresponse to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. - input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.
- input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.
- input.mode: Upgrade mode.
"reapply"(default) refreshes the agent's tracked template;"replace"moves the agent to a different template (requirestemplate). - input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.
- input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it.
- input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.
- input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it.
- input.template: ID (
cfg_...) orlookup_keyof the target AgentTemplate config. Optional in"reapply"mode; required in"replace"mode.
Returns:
The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (
upgrade_result) with status, dry-run flag, aggregate counts, and a per-resource change list. Whendry_runistrue,agentisnulland no changes are persisted.
class
AgentAgentComputerResource:
1420class AgentAgentComputerResource: 1421 def __init__(self, http: SyncHttpClient): 1422 self._http = http 1423 1424 def list(self, agent: str) -> AgentComputerListResponse: 1425 """ 1426 List computers 1427 Returns all computers belonging to the authenticated app, ordered by creation 1428 time descending. Pass `agent` to scope the results to a single agent's 1429 computers. When `agent` is omitted, computers for all agents in the app are 1430 returned. 1431 Requires an app-scoped API key. If the specified agent does not exist or does 1432 not belong to the app, the endpoint returns 404. 1433 1434 Args: 1435 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 1436 1437 Returns: 1438 Object containing a `data` array of computer records. 1439 """ 1440 return self._http.request( 1441 f"/api/v1/agents/{agent}/agent_computers", 1442 response_type=AgentComputerListResponse, 1443 ) 1444 1445 def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 1446 """ 1447 Provision a computer for an agent 1448 Creates and provisions a new computer resource associated with the specified 1449 agent. The computer is allocated in the requested region (defaulting to `iad`) 1450 and its status transitions from `provisioning` to `running` once it is ready. 1451 Requires an app-scoped API key. The agent identified by `agent` must belong 1452 to the same app. Supplying a `lookup_key` lets you retrieve this computer 1453 later without storing its ID the key must be unique within the app. 1454 1455 Args: 1456 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 1457 input: Request body. 1458 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 1459 input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID. 1460 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 1461 input.name: Human-readable display name for the computer. 1462 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`. 1463 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 1464 1465 Returns: 1466 The newly provisioned computer. 1467 """ 1468 return self._http.request( 1469 f"/api/v1/agents/{agent}/agent_computers", 1470 method="POST", 1471 body=input, 1472 response_type=AgentComputer, 1473 )
AgentAgentComputerResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1424 def list(self, agent: str) -> AgentComputerListResponse: 1425 """ 1426 List computers 1427 Returns all computers belonging to the authenticated app, ordered by creation 1428 time descending. Pass `agent` to scope the results to a single agent's 1429 computers. When `agent` is omitted, computers for all agents in the app are 1430 returned. 1431 Requires an app-scoped API key. If the specified agent does not exist or does 1432 not belong to the app, the endpoint returns 404. 1433 1434 Args: 1435 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 1436 1437 Returns: 1438 Object containing a `data` array of computer records. 1439 """ 1440 return self._http.request( 1441 f"/api/v1/agents/{agent}/agent_computers", 1442 response_type=AgentComputerListResponse, 1443 )
List computers
Returns all computers belonging to the authenticated app, ordered by creation
time descending. Pass agent to scope the results to a single agent's
computers. When agent is omitted, computers for all agents in the app are
returned.
Requires an app-scoped API key. If the specified agent does not exist or does
not belong to the app, the endpoint returns 404.
Arguments:
- agent: Agent ID (
agt_...). When provided, only computers belonging to this agent are returned.
Returns:
Object containing a
dataarray of computer records.
def
create( self, agent: str, input: AgentAgentComputerCreateInput) -> archastro.platform.types.common.AgentComputer:
1445 def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 1446 """ 1447 Provision a computer for an agent 1448 Creates and provisions a new computer resource associated with the specified 1449 agent. The computer is allocated in the requested region (defaulting to `iad`) 1450 and its status transitions from `provisioning` to `running` once it is ready. 1451 Requires an app-scoped API key. The agent identified by `agent` must belong 1452 to the same app. Supplying a `lookup_key` lets you retrieve this computer 1453 later without storing its ID the key must be unique within the app. 1454 1455 Args: 1456 agent: Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned. 1457 input: Request body. 1458 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 1459 input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID. 1460 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 1461 input.name: Human-readable display name for the computer. 1462 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default) or `"vercel"` (Vercel Sandbox). Folded into `config.provider`. 1463 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 1464 1465 Returns: 1466 The newly provisioned computer. 1467 """ 1468 return self._http.request( 1469 f"/api/v1/agents/{agent}/agent_computers", 1470 method="POST", 1471 body=input, 1472 response_type=AgentComputer, 1473 )
Provision a computer for an agent
Creates and provisions a new computer resource associated with the specified
agent. The computer is allocated in the requested region (defaulting to iad)
and its status transitions from provisioning to running once it is ready.
Requires an app-scoped API key. The agent identified by agent must belong
to the same app. Supplying a lookup_key lets you retrieve this computer
later without storing its ID the key must be unique within the app.
Arguments:
- agent: Agent ID (
agt_...). When provided, only computers belonging to this agent are returned. - input: Request body.
- input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level
providertakes precedence overconfig.provider. - input.lookup_key: Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID.
- input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads.
- input.name: Human-readable display name for the computer.
- input.provider: Compute backend for the computer:
"sprites"(Fly Sprites, the default) or"vercel"(Vercel Sandbox). Folded intoconfig.provider. - input.region: Region in which to provision the computer, e.g.
"iad". Defaults to"iad"when omitted.
Returns:
The newly provisioned computer.
class
AgentAgentEnvVarResource:
1476class AgentAgentEnvVarResource: 1477 def __init__(self, http: SyncHttpClient): 1478 self._http = http 1479 1480 def list(self, agent: str) -> AgentEnvVarMaskedList: 1481 """ 1482 List an agent's environment variables 1483 Returns all environment variables defined for the specified agent. Variable 1484 values are always masked in the response; only the last four characters are 1485 visible. To inspect a specific variable, use the retrieve endpoint. 1486 The authenticated user must have access to the agent's parent app. Pass the 1487 app scope via the `app` parameter when calling with an API key that is scoped 1488 to a specific app. Results are returned in an unordered flat list. 1489 1490 Args: 1491 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1492 1493 Returns: 1494 List of environment variables for the agent, with values masked. 1495 """ 1496 return self._http.request( 1497 f"/api/v1/agents/{agent}/agent_env_vars", 1498 response_type=AgentEnvVarMaskedList, 1499 ) 1500 1501 def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 1502 """ 1503 Create an agent environment variable 1504 Creates a new environment variable for the specified agent. The variable is 1505 stored securely and the plaintext `value` is never returned after creation; 1506 subsequent reads return a masked representation showing only the last four 1507 characters. 1508 The authenticated user must have access to the agent's parent app. Pass the 1509 app scope via the `app` parameter when calling with an API key that is scoped 1510 to a specific app. Each `key` must be unique within the agent; attempting to 1511 create a duplicate key returns a validation error. 1512 1513 Args: 1514 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1515 input: Request body. 1516 input.description: Optional human-readable note describing what the variable is used for. 1517 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 1518 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 1519 1520 Returns: 1521 The newly created environment variable with its value masked. 1522 """ 1523 return self._http.request( 1524 f"/api/v1/agents/{agent}/agent_env_vars", 1525 method="POST", 1526 body=input, 1527 response_type=AgentEnvVarMasked, 1528 )
AgentAgentEnvVarResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1480 def list(self, agent: str) -> AgentEnvVarMaskedList: 1481 """ 1482 List an agent's environment variables 1483 Returns all environment variables defined for the specified agent. Variable 1484 values are always masked in the response; only the last four characters are 1485 visible. To inspect a specific variable, use the retrieve endpoint. 1486 The authenticated user must have access to the agent's parent app. Pass the 1487 app scope via the `app` parameter when calling with an API key that is scoped 1488 to a specific app. Results are returned in an unordered flat list. 1489 1490 Args: 1491 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1492 1493 Returns: 1494 List of environment variables for the agent, with values masked. 1495 """ 1496 return self._http.request( 1497 f"/api/v1/agents/{agent}/agent_env_vars", 1498 response_type=AgentEnvVarMaskedList, 1499 )
List an agent's environment variables
Returns all environment variables defined for the specified agent. Variable
values are always masked in the response; only the last four characters are
visible. To inspect a specific variable, use the retrieve endpoint.
The authenticated user must have access to the agent's parent app. Pass the
app scope via the app parameter when calling with an API key that is scoped
to a specific app. Results are returned in an unordered flat list.
Arguments:
- agent: Agent ID (
agt_...). Returns environment variables belonging to this agent.
Returns:
List of environment variables for the agent, with values masked.
def
create( self, agent: str, input: AgentAgentEnvVarCreateInput) -> archastro.platform.types.common.AgentEnvVarMasked:
1501 def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 1502 """ 1503 Create an agent environment variable 1504 Creates a new environment variable for the specified agent. The variable is 1505 stored securely and the plaintext `value` is never returned after creation; 1506 subsequent reads return a masked representation showing only the last four 1507 characters. 1508 The authenticated user must have access to the agent's parent app. Pass the 1509 app scope via the `app` parameter when calling with an API key that is scoped 1510 to a specific app. Each `key` must be unique within the agent; attempting to 1511 create a duplicate key returns a validation error. 1512 1513 Args: 1514 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1515 input: Request body. 1516 input.description: Optional human-readable note describing what the variable is used for. 1517 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 1518 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 1519 1520 Returns: 1521 The newly created environment variable with its value masked. 1522 """ 1523 return self._http.request( 1524 f"/api/v1/agents/{agent}/agent_env_vars", 1525 method="POST", 1526 body=input, 1527 response_type=AgentEnvVarMasked, 1528 )
Create an agent environment variable
Creates a new environment variable for the specified agent. The variable is
stored securely and the plaintext value is never returned after creation;
subsequent reads return a masked representation showing only the last four
characters.
The authenticated user must have access to the agent's parent app. Pass the
app scope via the app parameter when calling with an API key that is scoped
to a specific app. Each key must be unique within the agent; attempting to
create a duplicate key returns a validation error.
Arguments:
- agent: Agent ID (
agt_...). Returns environment variables belonging to this agent. - input: Request body.
- input.description: Optional human-readable note describing what the variable is used for.
- input.key: Environment variable name, e.g.
WEBHOOK_SECRET. Must be unique within the agent. - input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full.
Returns:
The newly created environment variable with its value masked.
class
AgentAgentInstallationResource:
1531class AgentAgentInstallationResource: 1532 def __init__(self, http: SyncHttpClient): 1533 self._http = http 1534 1535 def list(self, agent: str) -> InstallationListResponse: 1536 """ 1537 List installations for an agent 1538 Returns all installations belonging to the specified agent, across all kinds and 1539 states. Use this endpoint to inspect which external services and enablement channels 1540 an agent is connected to. 1541 Results are scoped to the authenticated app and are returned in an unordered array. 1542 To list installations across all agents in an app, use the top-level List 1543 Installations endpoint instead. The caller must have app scope for the app that 1544 owns the agent. 1545 1546 Args: 1547 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1548 1549 Returns: 1550 The list of installations for the specified agent. 1551 """ 1552 return self._http.request( 1553 f"/api/v1/agents/{agent}/agent_installations", 1554 response_type=InstallationListResponse, 1555 ) 1556 1557 def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 1558 """ 1559 Create an installation 1560 Creates a new installation for an agent, connecting it to an external service or 1561 enablement channel via the specified `kind`. The installation begins in a pending 1562 state unless an integration is supplied at creation time, in which case it is 1563 activated immediately. 1564 Supply `shared_integration` to bind an existing org- or app-level integration, or 1565 supply `integration` to create a new integration inline and activate the installation 1566 in a single request. Supplying both fields returns 422. 1567 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 1568 search `source_refs`. The key must be unique within the app, org, and sandbox 1569 combination. The caller must have app scope for the app that owns the agent. 1570 1571 Args: 1572 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1573 input: Request body. 1574 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 1575 input.integration: Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`. 1576 input.kind: Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values. 1577 input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. 1578 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 1579 1580 Returns: 1581 The newly created installation. 1582 """ 1583 return self._http.request( 1584 f"/api/v1/agents/{agent}/agent_installations", 1585 method="POST", 1586 body=input, 1587 response_type=Installation, 1588 ) 1589 1590 def kinds(self, agent: str) -> InstallationKindListResponse: 1591 """ 1592 List available installation kinds 1593 Returns the full catalogue of installation kinds supported by the platform. Use 1594 the returned `kind` values when calling the Create Installation endpoint. 1595 The list is platform-wide and does not vary by agent. The `agent` parameter is 1596 accepted for future per-agent filtering but is currently unused. The caller must 1597 have app scope to call this endpoint. 1598 1599 Args: 1600 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1601 1602 Returns: 1603 The list of all supported installation kinds. 1604 """ 1605 return self._http.request( 1606 f"/api/v1/agents/{agent}/agent_installations/kinds", 1607 response_type=InstallationKindListResponse, 1608 )
AgentAgentInstallationResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1535 def list(self, agent: str) -> InstallationListResponse: 1536 """ 1537 List installations for an agent 1538 Returns all installations belonging to the specified agent, across all kinds and 1539 states. Use this endpoint to inspect which external services and enablement channels 1540 an agent is connected to. 1541 Results are scoped to the authenticated app and are returned in an unordered array. 1542 To list installations across all agents in an app, use the top-level List 1543 Installations endpoint instead. The caller must have app scope for the app that 1544 owns the agent. 1545 1546 Args: 1547 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1548 1549 Returns: 1550 The list of installations for the specified agent. 1551 """ 1552 return self._http.request( 1553 f"/api/v1/agents/{agent}/agent_installations", 1554 response_type=InstallationListResponse, 1555 )
List installations for an agent Returns all installations belonging to the specified agent, across all kinds and states. Use this endpoint to inspect which external services and enablement channels an agent is connected to. Results are scoped to the authenticated app and are returned in an unordered array. To list installations across all agents in an app, use the top-level List Installations endpoint instead. The caller must have app scope for the app that owns the agent.
Arguments:
- agent: Agent ID (
agt_...) whose installations you want to retrieve.
Returns:
The list of installations for the specified agent.
def
create( self, agent: str, input: AgentAgentInstallationCreateInput) -> archastro.platform.types.common.Installation:
1557 def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 1558 """ 1559 Create an installation 1560 Creates a new installation for an agent, connecting it to an external service or 1561 enablement channel via the specified `kind`. The installation begins in a pending 1562 state unless an integration is supplied at creation time, in which case it is 1563 activated immediately. 1564 Supply `shared_integration` to bind an existing org- or app-level integration, or 1565 supply `integration` to create a new integration inline and activate the installation 1566 in a single request. Supplying both fields returns 422. 1567 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 1568 search `source_refs`. The key must be unique within the app, org, and sandbox 1569 combination. The caller must have app scope for the app that owns the agent. 1570 1571 Args: 1572 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1573 input: Request body. 1574 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 1575 input.integration: Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`. 1576 input.kind: Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values. 1577 input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. 1578 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 1579 1580 Returns: 1581 The newly created installation. 1582 """ 1583 return self._http.request( 1584 f"/api/v1/agents/{agent}/agent_installations", 1585 method="POST", 1586 body=input, 1587 response_type=Installation, 1588 )
Create an installation
Creates a new installation for an agent, connecting it to an external service or
enablement channel via the specified kind. The installation begins in a pending
state unless an integration is supplied at creation time, in which case it is
activated immediately.
Supply shared_integration to bind an existing org- or app-level integration, or
supply integration to create a new integration inline and activate the installation
in a single request. Supplying both fields returns 422.
Use lookup_key to assign a stable identifier you can reference later in knowledge
search source_refs. The key must be unique within the app, org, and sandbox
combination. The caller must have app scope for the app that owns the agent.
Arguments:
- agent: Agent ID (
agt_...) whose installations you want to retrieve. - input: Request body.
- input.config: Kind-specific configuration object. Shape varies by
kind; omit if the kind requires no initial configuration. - input.integration: Inline integration fields to create for
integration/*kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive withshared_integration. - input.kind: Installation kind that determines the external service being connected. Examples:
"enablement/github_app","enablement/slack_bot","integration/github","integration/gmail","web/site". Use the List Kinds endpoint to retrieve all supported values. - input.lookup_key: Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search
source_refs. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing. - input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with
integration.
Returns:
The newly created installation.
1590 def kinds(self, agent: str) -> InstallationKindListResponse: 1591 """ 1592 List available installation kinds 1593 Returns the full catalogue of installation kinds supported by the platform. Use 1594 the returned `kind` values when calling the Create Installation endpoint. 1595 The list is platform-wide and does not vary by agent. The `agent` parameter is 1596 accepted for future per-agent filtering but is currently unused. The caller must 1597 have app scope to call this endpoint. 1598 1599 Args: 1600 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1601 1602 Returns: 1603 The list of all supported installation kinds. 1604 """ 1605 return self._http.request( 1606 f"/api/v1/agents/{agent}/agent_installations/kinds", 1607 response_type=InstallationKindListResponse, 1608 )
List available installation kinds
Returns the full catalogue of installation kinds supported by the platform. Use
the returned kind values when calling the Create Installation endpoint.
The list is platform-wide and does not vary by agent. The agent parameter is
accepted for future per-agent filtering but is currently unused. The caller must
have app scope to call this endpoint.
Arguments:
- agent: Agent ID (
agt_...) whose installations you want to retrieve.
Returns:
The list of all supported installation kinds.
class
AgentAgentToolResource:
1611class AgentAgentToolResource: 1612 def __init__(self, http: SyncHttpClient): 1613 self._http = http 1614 1615 def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 1616 """ 1617 List agent tools 1618 Returns all tools for the authenticated app, optionally filtered by agent 1619 or tool kind. Both explicitly created tools and tools derived from connected 1620 integrations (installation-sourced tools) are included in the response. 1621 Installation-sourced tools appear with `source: "installation"` and 1622 `status: "active"`. They are synthesized at request time from connected 1623 integrations and do not have a persistent tool ID of the `atl_...` form; 1624 their `id` is a composite of the installation ID and server tool type. 1625 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 1626 `agent` ID that does not belong to the authenticated app returns 404. 1627 Requires app scope. 1628 1629 Args: 1630 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 1631 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 1632 1633 Returns: 1634 List of tools matching the supplied filters. 1635 """ 1636 query: dict[str, object] = {} 1637 if kind is not None: 1638 query["kind"] = kind 1639 return self._http.request( 1640 f"/api/v1/agents/{agent}/agent_tools", 1641 query=query, 1642 response_type=AgentToolListResponse, 1643 ) 1644 1645 def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 1646 """ 1647 Create an agent tool 1648 Creates a new tool and attaches it to the specified agent. Tools can be 1649 either `"builtin"` (a platform-provided capability identified by 1650 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 1651 description, parameter schema, and handler). 1652 New tools are created in `"draft"` status by default unless `status: 1653 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 1654 during agent runs; call the activate endpoint to promote them. 1655 For built-in tools that support multiple instances per agent (those whose 1656 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 1657 namespace the LLM-facing tool names. Requires app scope. 1658 1659 Args: 1660 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 1661 input: Request body. 1662 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1663 input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 1664 input.builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 1665 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1666 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1667 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1668 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1669 input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 1670 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1671 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1672 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 1673 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1674 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1675 1676 Returns: 1677 The newly created tool. 1678 """ 1679 return self._http.request( 1680 f"/api/v1/agents/{agent}/agent_tools", 1681 method="POST", 1682 body=input, 1683 response_type=AgentTool, 1684 )
AgentAgentToolResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, agent: str, *, kind: str | None = None) -> archastro.platform.types.common.AgentToolListResponse:
1615 def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 1616 """ 1617 List agent tools 1618 Returns all tools for the authenticated app, optionally filtered by agent 1619 or tool kind. Both explicitly created tools and tools derived from connected 1620 integrations (installation-sourced tools) are included in the response. 1621 Installation-sourced tools appear with `source: "installation"` and 1622 `status: "active"`. They are synthesized at request time from connected 1623 integrations and do not have a persistent tool ID of the `atl_...` form; 1624 their `id` is a composite of the installation ID and server tool type. 1625 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 1626 `agent` ID that does not belong to the authenticated app returns 404. 1627 Requires app scope. 1628 1629 Args: 1630 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 1631 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 1632 1633 Returns: 1634 List of tools matching the supplied filters. 1635 """ 1636 query: dict[str, object] = {} 1637 if kind is not None: 1638 query["kind"] = kind 1639 return self._http.request( 1640 f"/api/v1/agents/{agent}/agent_tools", 1641 query=query, 1642 response_type=AgentToolListResponse, 1643 )
List agent tools
Returns all tools for the authenticated app, optionally filtered by agent
or tool kind. Both explicitly created tools and tools derived from connected
integrations (installation-sourced tools) are included in the response.
Installation-sourced tools appear with source: "installation" and
status: "active". They are synthesized at request time from connected
integrations and do not have a persistent tool ID of the atl_... form;
their id is a composite of the installation ID and server tool type.
Use the agent filter to retrieve tools for a specific agent. Supplying an
agent ID that does not belong to the authenticated app returns 404.
Requires app scope.
Arguments:
- agent: Filter results to tools belonging to this agent (
agt_...). Omit to return tools across all agents in the app. - kind: Filter by tool kind. One of
"builtin"or"custom". Omit to return tools of all kinds.
Returns:
List of tools matching the supplied filters.
def
create( self, agent: str, input: AgentAgentToolCreateInput) -> archastro.platform.types.common.AgentTool:
1645 def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 1646 """ 1647 Create an agent tool 1648 Creates a new tool and attaches it to the specified agent. Tools can be 1649 either `"builtin"` (a platform-provided capability identified by 1650 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 1651 description, parameter schema, and handler). 1652 New tools are created in `"draft"` status by default unless `status: 1653 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 1654 during agent runs; call the activate endpoint to promote them. 1655 For built-in tools that support multiple instances per agent (those whose 1656 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 1657 namespace the LLM-facing tool names. Requires app scope. 1658 1659 Args: 1660 agent: Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app. 1661 input: Request body. 1662 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1663 input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools. 1664 input.builtin_tool_key: Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog. 1665 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1666 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1667 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1668 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1669 input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning. 1670 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1671 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1672 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. Required for `"namespaced"` multi-instance tools; omit for single-instance tools. 1673 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1674 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1675 1676 Returns: 1677 The newly created tool. 1678 """ 1679 return self._http.request( 1680 f"/api/v1/agents/{agent}/agent_tools", 1681 method="POST", 1682 body=input, 1683 response_type=AgentTool, 1684 )
Create an agent tool
Creates a new tool and attaches it to the specified agent. Tools can be
either "builtin" (a platform-provided capability identified by
builtin_tool_key) or "custom" (a caller-defined tool with its own name,
description, parameter schema, and handler).
New tools are created in "draft" status by default unless status:
"active" is explicitly supplied. Draft tools are not exposed to the LLM
during agent runs; call the activate endpoint to promote them.
For built-in tools that support multiple instances per agent (those whose
catalog entry has a multi_instance_mode), supply name_prefix to
namespace the LLM-facing tool names. Requires app scope.
Arguments:
- agent: Filter results to tools belonging to this agent (
agt_...). Omit to return tools across all agents in the app. - input: Request body.
- input.async: When
true, the tool executes asynchronously and the agent does not block waiting for a result. Applies to"custom"tools. - input.builtin_tool_config: Configuration object for the built-in tool. Shape is defined by the catalog entry's
config_schemafor the chosenbuiltin_tool_key. Applies only to"builtin"tools. - input.builtin_tool_key: Key identifying the built-in tool type to add (e.g.
"knowledge_search"). Required whenkindis"builtin". Must match a key in the tool catalog. - input.config: Config ID (
cfg_...) referencing the script or workflow graph that implements the tool handler. Applies to"custom"tools. - input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to
"custom"tools. - input.handler_type: Execution handler for the tool. One of
"script"or"workflow_graph". Applies to"custom"tools. - input.kind: Tool kind. One of
"builtin"or"custom". - input.lookup_key: Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning.
- input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform.
- input.name: Display name for the tool. Required when
kindis"custom". - 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. Required for"namespaced"multi-instance tools; omit for single-instance tools. - input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to
"custom"tools. - input.status: Initial status of the tool. One of
"draft"or"active". Defaults to"draft"when omitted.
Returns:
The newly created tool.
class
ScheduleResource:
1687class ScheduleResource: 1688 def __init__(self, http: SyncHttpClient): 1689 self._http = http 1690 1691 def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 1692 """ 1693 List schedules for an agent 1694 Returns all schedules belonging to the specified agent in any status. Use the 1695 `status` parameter to narrow results to a single lifecycle state. 1696 Requires an app-scoped API key. The agent must belong to the app identified 1697 by the key. 1698 1699 Args: 1700 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1701 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 1702 1703 Returns: 1704 Successful response 1705 """ 1706 query: dict[str, object] = {} 1707 if status is not None: 1708 query["status"] = status 1709 return self._http.request( 1710 f"/api/v1/agents/{agent}/schedules", 1711 query=query, 1712 response_type=ScheduleListResponse, 1713 ) 1714 1715 def get(self, agent: str, schedule: str) -> AgentSchedule: 1716 """ 1717 Retrieve a schedule 1718 Returns a single schedule belonging to the specified agent. Use this endpoint 1719 to fetch the current state, next run time, and configuration of an individual 1720 schedule. 1721 Requires an app-scoped API key. Both the agent and the schedule must belong 1722 to the app identified by the key. Returns 404 if the schedule does not exist 1723 or belongs to a different agent. 1724 1725 Args: 1726 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1727 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 1728 1729 Returns: 1730 The requested agent schedule. 1731 """ 1732 return self._http.request( 1733 f"/api/v1/agents/{agent}/schedules/{schedule}", 1734 response_type=AgentSchedule, 1735 )
ScheduleResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1691 def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 1692 """ 1693 List schedules for an agent 1694 Returns all schedules belonging to the specified agent in any status. Use the 1695 `status` parameter to narrow results to a single lifecycle state. 1696 Requires an app-scoped API key. The agent must belong to the app identified 1697 by the key. 1698 1699 Args: 1700 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1701 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 1702 1703 Returns: 1704 Successful response 1705 """ 1706 query: dict[str, object] = {} 1707 if status is not None: 1708 query["status"] = status 1709 return self._http.request( 1710 f"/api/v1/agents/{agent}/schedules", 1711 query=query, 1712 response_type=ScheduleListResponse, 1713 )
List schedules for an agent
Returns all schedules belonging to the specified agent in any status. Use the
status parameter to narrow results to a single lifecycle state.
Requires an app-scoped API key. The agent must belong to the app identified
by the key.
Arguments:
- agent: Agent ID (
agi_...). The agent whose schedules you want to retrieve. - status: Filter results by schedule status. One of
"active","paused","completed","cancelled", or"expired". Omit to return schedules in all statuses.
Returns:
Successful response
1715 def get(self, agent: str, schedule: str) -> AgentSchedule: 1716 """ 1717 Retrieve a schedule 1718 Returns a single schedule belonging to the specified agent. Use this endpoint 1719 to fetch the current state, next run time, and configuration of an individual 1720 schedule. 1721 Requires an app-scoped API key. Both the agent and the schedule must belong 1722 to the app identified by the key. Returns 404 if the schedule does not exist 1723 or belongs to a different agent. 1724 1725 Args: 1726 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1727 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 1728 1729 Returns: 1730 The requested agent schedule. 1731 """ 1732 return self._http.request( 1733 f"/api/v1/agents/{agent}/schedules/{schedule}", 1734 response_type=AgentSchedule, 1735 )
Retrieve a schedule Returns a single schedule belonging to the specified agent. Use this endpoint to fetch the current state, next run time, and configuration of an individual schedule. Requires an app-scoped API key. Both the agent and the schedule must belong to the app identified by the key. Returns 404 if the schedule does not exist or belongs to a different agent.
Arguments:
- agent: Agent ID (
agi_...). The agent whose schedules you want to retrieve. - schedule: Schedule ID (
asc_...). The schedule to retrieve.
Returns:
The requested agent schedule.
class
AgentResource:
1738class AgentResource: 1739 def __init__(self, http: SyncHttpClient): 1740 self._http = http 1741 self.agent_computers = AgentAgentComputerResource(http) 1742 self.agent_env_vars = AgentAgentEnvVarResource(http) 1743 self.agent_installations = AgentAgentInstallationResource(http) 1744 self.agent_tools = AgentAgentToolResource(http) 1745 self.schedules = ScheduleResource(http) 1746 1747 def list( 1748 self, 1749 *, 1750 page: int | None = None, 1751 page_size: int | None = None, 1752 search: str | None = None, 1753 user: str | None = None, 1754 org_id: str | None = None, 1755 template_config: str | None = None, 1756 solution_config: builtins.list[str] | None = None, 1757 ) -> AgentListResponse: 1758 """ 1759 List agents 1760 Returns a paginated list of agents visible to the authenticated caller. Results are 1761 ordered by creation time descending. 1762 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 1763 to scope the list to a specific owner. Use `template_config` to find agents whose 1764 last applied template matches a given config ID. Use `solution_config` to find 1765 agents whose last applied template was imported as part of any of the given 1766 Solution config IDs. 1767 Pagination is page-based: pass `page` and `page_size` to navigate through large 1768 result sets. When called under a developer app scope, only agents belonging to that 1769 app are returned. 1770 1771 Args: 1772 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1773 page_size: Number of agents to return per page. Defaults to `25`. 1774 search: Free-text search string matched against the agent name, org, team, and owner fields. 1775 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 1776 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 1777 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 1778 solution_config: Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs. 1779 1780 Returns: 1781 Paginated list of agents matching the supplied filters. 1782 """ 1783 query: dict[str, object] = {} 1784 if page is not None: 1785 query["page"] = page 1786 if page_size is not None: 1787 query["page_size"] = page_size 1788 if search is not None: 1789 query["search"] = search 1790 if user is not None: 1791 query["user"] = user 1792 if org_id is not None: 1793 query["org_id"] = org_id 1794 if template_config is not None: 1795 query["template_config"] = template_config 1796 if solution_config is not None: 1797 query["solution_config"] = solution_config 1798 return self._http.request("/api/v1/agents", query=query, response_type=AgentListResponse) 1799 1800 def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1801 """ 1802 Create an agent 1803 Creates a new agent. Supports two mutually exclusive provisioning modes. 1804 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1805 AgentTemplate config. The agent's tools, routines, skills, and installations are 1806 provisioned from that template's `config_ref` entries. 1807 **Bundle mode** pass `template_bundle` with a self-contained install payload 1808 (AgentTemplate body plus every skill, script, and config it references). The entire 1809 bundle commits in a single transaction; any failure rolls back the whole install and 1810 the response includes `installed_configs[]` one entry per persisted config. 1811 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1812 is required and a blank agent is created. Requires authentication; when called under 1813 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1814 for the target app. 1815 1816 Args: 1817 input: Request body. 1818 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1819 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1820 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1821 input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org. 1822 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1823 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1824 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1825 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1826 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1827 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1828 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1829 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1830 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1831 input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`. 1832 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1833 1834 Returns: 1835 The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` one entry per persisted config object, with `key` echoing the caller-supplied input identifier. 1836 """ 1837 return self._http.request( 1838 "/api/v1/agents", 1839 method="POST", 1840 body=input, 1841 response_type=AgentCreateResponse, 1842 ) 1843 1844 def delete(self, agent: str) -> None: 1845 """ 1846 Delete an agent 1847 Permanently deletes an agent and all of its associated resources. This action cannot 1848 be undone. 1849 The authenticated caller must own the agent or hold sufficient permissions within its 1850 owning org or team. When called under a developer app scope, the caller must hold the 1851 app scope for the target app. 1852 1853 Args: 1854 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1855 1856 Returns: 1857 Empty body. Returns HTTP 204 on success. 1858 """ 1859 self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 1860 1861 def get(self, agent: str) -> Agent: 1862 """ 1863 Retrieve an agent 1864 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1865 own the agent or hold sufficient permissions within its owning org or team. 1866 When called under a developer app scope, the agent must belong to that app. Use the 1867 list endpoint to retrieve many agents at once. 1868 1869 Args: 1870 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1871 1872 Returns: 1873 The requested agent. 1874 """ 1875 return self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 1876 1877 def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1878 """ 1879 Update an agent 1880 Updates one or more fields on an existing agent. Only the fields you supply are 1881 changed; omitted fields retain their current values. 1882 To clear the agent's default model, pass `model` as an empty string. The 1883 authenticated caller must own the agent or hold write permissions within its owning 1884 org or team. When called under a developer app scope, the caller must hold the app 1885 scope for the target app. 1886 1887 Args: 1888 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1889 input: Request body. 1890 input.acl: Replacement access control list. Fully replaces the existing ACL. 1891 input.email: New email address for the agent. 1892 input.identity: Replacement identity system-prompt string describing who the agent is. 1893 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1894 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1895 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1896 input.name: New display name for the agent. 1897 input.org: Organization ID (`org_...`) to transfer ownership to. 1898 input.originator: Replacement originator label identifying the source or author of the agent. 1899 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1900 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1901 input.team: Team ID (`team_...`) to transfer ownership to. 1902 input.user: User ID (`usr_...`) to transfer ownership to. 1903 1904 Returns: 1905 The updated agent with all current field values. 1906 """ 1907 return self._http.request( 1908 f"/api/v1/agents/{agent}", 1909 method="PATCH", 1910 body=input, 1911 response_type=Agent, 1912 ) 1913 1914 def agent_health_actions( 1915 self, 1916 agent: str, 1917 *, 1918 source: builtins.list[str] | None = None, 1919 status: builtins.list[str] | None = None, 1920 kind: builtins.list[str] | None = None, 1921 ) -> HealthActionListResponse: 1922 """ 1923 List health actions for an agent 1924 Returns all health actions associated with a given agent. Health actions 1925 represent required or recommended steps such as setting environment 1926 variables, completing OAuth installations, or running custom verifiers 1927 that an agent needs to reach a healthy state. 1928 Results are not paginated; the full list for the agent is returned. Use 1929 the `source`, `status`, and `kind` filters to narrow results to the 1930 subset your UI or workflow needs. Multiple values for the same filter 1931 are treated as OR (e.g. passing two statuses returns actions matching 1932 either). The caller must be authenticated and scoped to the app that 1933 owns the agent. 1934 1935 Args: 1936 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1937 source: Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages. 1938 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1939 kind: Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds. 1940 1941 Returns: 1942 Object containing a `data` array of health action objects for the specified agent. 1943 """ 1944 query: dict[str, object] = {} 1945 if source is not None: 1946 query["source"] = source 1947 if status is not None: 1948 query["status"] = status 1949 if kind is not None: 1950 query["kind"] = kind 1951 return self._http.request( 1952 f"/api/v1/agents/{agent}/agent_health_actions", 1953 query=query, 1954 response_type=HealthActionListResponse, 1955 ) 1956 1957 def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1958 """ 1959 Create a routine 1960 Creates a new routine and attaches it to the specified agent. Routines define 1961 how an agent responds to events or a cron schedule; the `handler_type` controls 1962 which execution model is used. 1963 The routine is created in `"draft"` status by default. To start processing 1964 events immediately, either pass `status: "active"` or call the activate 1965 endpoint after creation. Scheduled routines must run no more frequently than 1966 once per hour. Requires app scope. 1967 1968 Args: 1969 agent: Agent ID (`agt_...`) that this routine will be attached to. 1970 input: Request body. 1971 input.acl: Access control list governing who can read or manage this routine. 1972 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1973 input.description: Optional human-readable description of what this routine does. 1974 input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). 1975 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1976 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1977 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1978 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1979 input.name: Human-readable display name for the routine. 1980 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1981 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1982 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1983 input.script: Inline script source. Required when `handler_type` is `"script"`. 1984 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1985 input.steps: Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. 1986 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1987 1988 Returns: 1989 The newly created routine. 1990 """ 1991 return self._http.request( 1992 f"/api/v1/agents/{agent}/agent_routines", 1993 method="POST", 1994 body=input, 1995 response_type=AgentRoutine, 1996 ) 1997 1998 def agent_working_memory( 1999 self, 2000 agent: str, 2001 *, 2002 page: int | None = None, 2003 page_size: int | None = None, 2004 search: str | None = None, 2005 ) -> WorkingMemoryEntryListResponse: 2006 """ 2007 List working memory entries for an agent 2008 Returns a paginated list of working memory entries belonging to the specified 2009 agent. Entries are key-value pairs the agent stores for context between 2010 interactions. Results are ordered by creation time descending (newest first) 2011 and can be filtered with a substring search against the key name. 2012 Requires an app-scoped API key. The authenticated caller must have access to 2013 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 2014 404 if the agent does not exist within the accessible scope. 2015 2016 Args: 2017 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2018 page: Page number to retrieve, starting at 1. Defaults to 1. 2019 page_size: Number of entries to return per page. Defaults to 25. 2020 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 2021 2022 Returns: 2023 Paginated list of working memory entries for the agent. 2024 """ 2025 query: dict[str, object] = {} 2026 if page is not None: 2027 query["page"] = page 2028 if page_size is not None: 2029 query["page_size"] = page_size 2030 if search is not None: 2031 query["search"] = search 2032 return self._http.request( 2033 f"/api/v1/agents/{agent}/agent_working_memory", 2034 query=query, 2035 response_type=WorkingMemoryEntryListResponse, 2036 ) 2037 2038 def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 2039 """ 2040 Export an agent as an AgentTemplate 2041 Reconstructs an AgentTemplate config from a deployed agent and all of its 2042 sub-resources (tools, routines, skills, installations). Returns the template 2043 definition together with every dependent config file (scripts, workflows, skills, 2044 schemas) and their raw content, producing a fully self-contained export bundle. 2045 Use this endpoint to snapshot an agent's current configuration for backup, 2046 migration, or to seed a new Solution template. Pass `remove_identity: true` to 2047 strip instance-specific fields (email, phone number) before export. 2048 The authenticated caller must own the agent or hold sufficient permissions within 2049 its owning org or team. When called under a developer app scope, the caller must 2050 hold the app scope for the target app. 2051 2052 Args: 2053 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 2054 remove_identity: When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint. 2055 2056 Returns: 2057 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 2058 """ 2059 query: dict[str, object] = {} 2060 if remove_identity is not None: 2061 query["remove_identity"] = remove_identity 2062 return self._http.request( 2063 f"/api/v1/agents/{agent}/export", 2064 query=query, 2065 response_type=AgentExport, 2066 ) 2067 2068 def health(self, agent: str) -> AgentHealth: 2069 """ 2070 Retrieve an agent's health profile 2071 Returns an aggregate health profile for the specified agent, including an overall 2072 status, a numeric health score, recent activity metrics, and a list of recommended 2073 remediation actions. 2074 The health check is computed on demand at request time. The `checked_at` timestamp 2075 in the response reflects when the evaluation ran. Use this endpoint to surface 2076 diagnostics about tool availability, model configuration, and runtime activity in 2077 dashboards or monitoring workflows. 2078 The authenticated caller must own the agent or hold sufficient permissions within 2079 its owning org or team. When called under a developer app scope, the caller must 2080 hold the app scope for the target app. 2081 2082 Args: 2083 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 2084 2085 Returns: 2086 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 2087 """ 2088 return self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 2089 2090 def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 2091 """ 2092 Search an agent's knowledge base 2093 Performs a semantic search over an agent's knowledge base and returns a ranked, 2094 `kind`-discriminated list of matching items. 2095 Two item kinds may appear in `data`: 2096 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 2097 - `"document"` document-level results. Present only when the agent has an active 2098 `archastro/knowledge` installation. 2099 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 2100 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 2101 chunks appear before documents. The total number of results is capped at `max_results` 2102 across both kinds. 2103 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 2104 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 2105 2106 Args: 2107 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 2108 input: Request body. 2109 input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`. 2110 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 2111 input.query: Natural-language search query used to retrieve relevant knowledge items. 2112 input.recency_days: When set, restricts results to items indexed within the last N days. 2113 input.source_types: Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types. 2114 2115 Returns: 2116 Successful response 2117 """ 2118 return self._http.request( 2119 f"/api/v1/agents/{agent}/search", 2120 method="POST", 2121 body=input, 2122 response_type=AgentSearchResponse, 2123 ) 2124 2125 def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 2126 """ 2127 Create a thread for an agent 2128 Creates a new thread owned by the specified agent. The thread is scoped to the 2129 agent's identity and is immediately available for messaging. 2130 The authenticated caller must have access to the agent's parent app. If your 2131 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 2132 Attempting to create a thread for an agent you cannot access returns 404. 2133 By default the platform may send an automatic welcome message into the new 2134 thread. Pass `skip_welcome_message: true` to suppress this behavior. 2135 2136 Args: 2137 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 2138 input: Request body. 2139 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 2140 input.thread: Attributes for the new thread. 2141 2142 Returns: 2143 The newly created thread. 2144 """ 2145 return self._http.request( 2146 f"/api/v1/agents/{agent}/threads", 2147 method="POST", 2148 body=input, 2149 response_type=Thread, 2150 ) 2151 2152 def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 2153 """ 2154 Upgrade an agent from an AgentTemplate 2155 Upgrades an existing agent by reconciling it against an AgentTemplate from a 2156 Solution. Supports two modes: 2157 - `"reapply"` (default) re-applies the agent's currently tracked template, 2158 picking up any changes the template author has made since the last apply. 2159 - `"replace"` moves the agent to a different template. `template` is required 2160 in this mode. 2161 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 2162 removes, noops) without writing any changes. The response includes a 2163 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 2164 live apply to guard against the diff changing between review and execution. 2165 Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, 2166 `originator`, `model`) let you pin instance-specific values that should not be 2167 overwritten by the template during the upgrade. 2168 The authenticated caller must own the agent or hold write permissions within its 2169 owning org or team. When called under a developer app scope, the caller must hold 2170 the app scope for the target app. 2171 2172 Args: 2173 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 2174 input: Request body. 2175 input.dry_run: When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. 2176 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 2177 input.expected_review_fingerprint: Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. 2178 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 2179 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 2180 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 2181 input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. 2182 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 2183 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 2184 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 2185 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 2186 2187 Returns: 2188 The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted. 2189 """ 2190 return self._http.request( 2191 f"/api/v1/agents/{agent}/upgrade", 2192 method="POST", 2193 body=input, 2194 response_type=AgentUpgradeResponse, 2195 )
AgentResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1739 def __init__(self, http: SyncHttpClient): 1740 self._http = http 1741 self.agent_computers = AgentAgentComputerResource(http) 1742 self.agent_env_vars = AgentAgentEnvVarResource(http) 1743 self.agent_installations = AgentAgentInstallationResource(http) 1744 self.agent_tools = AgentAgentToolResource(http) 1745 self.schedules = ScheduleResource(http)
def
list( self, *, page: int | None = None, page_size: int | None = None, search: str | None = None, user: str | None = None, org_id: str | None = None, template_config: str | None = None, solution_config: list[str] | None = None) -> archastro.platform.types.common.AgentListResponse:
1747 def list( 1748 self, 1749 *, 1750 page: int | None = None, 1751 page_size: int | None = None, 1752 search: str | None = None, 1753 user: str | None = None, 1754 org_id: str | None = None, 1755 template_config: str | None = None, 1756 solution_config: builtins.list[str] | None = None, 1757 ) -> AgentListResponse: 1758 """ 1759 List agents 1760 Returns a paginated list of agents visible to the authenticated caller. Results are 1761 ordered by creation time descending. 1762 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 1763 to scope the list to a specific owner. Use `template_config` to find agents whose 1764 last applied template matches a given config ID. Use `solution_config` to find 1765 agents whose last applied template was imported as part of any of the given 1766 Solution config IDs. 1767 Pagination is page-based: pass `page` and `page_size` to navigate through large 1768 result sets. When called under a developer app scope, only agents belonging to that 1769 app are returned. 1770 1771 Args: 1772 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1773 page_size: Number of agents to return per page. Defaults to `25`. 1774 search: Free-text search string matched against the agent name, org, team, and owner fields. 1775 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 1776 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 1777 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 1778 solution_config: Solution config IDs (`cfg_...`) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs. 1779 1780 Returns: 1781 Paginated list of agents matching the supplied filters. 1782 """ 1783 query: dict[str, object] = {} 1784 if page is not None: 1785 query["page"] = page 1786 if page_size is not None: 1787 query["page_size"] = page_size 1788 if search is not None: 1789 query["search"] = search 1790 if user is not None: 1791 query["user"] = user 1792 if org_id is not None: 1793 query["org_id"] = org_id 1794 if template_config is not None: 1795 query["template_config"] = template_config 1796 if solution_config is not None: 1797 query["solution_config"] = solution_config 1798 return self._http.request("/api/v1/agents", query=query, response_type=AgentListResponse)
List agents
Returns a paginated list of agents visible to the authenticated caller. Results are
ordered by creation time descending.
Use search to filter by name, org, team, or owner fields. Use user or org_id
to scope the list to a specific owner. Use template_config to find agents whose
last applied template matches a given config ID. Use solution_config to find
agents whose last applied template was imported as part of any of the given
Solution config IDs.
Pagination is page-based: pass page and page_size to navigate through large
result sets. When called under a developer app scope, only agents belonging to that
app are returned.
Arguments:
- page: Page number to retrieve, 1-indexed. Defaults to
1. - page_size: Number of agents to return per page. Defaults to
25. - search: Free-text search string matched against the agent name, org, team, and owner fields.
- user: User ID (
usr_...) to filter by. Returns only agents owned by this user. - org_id: Organization ID (
org_...) to filter by. Returns only agents owned by this org. - template_config: Config ID (
cfg_...) orlookup_keyof an AgentTemplate. Returns only agents whose last applied template matches. - solution_config: Solution config IDs (
cfg_...) to filter by. Returns only agents whose last applied template was imported as part of any of the listed Solutions. Pass one or more IDs.
Returns:
Paginated list of agents matching the supplied filters.
1800 def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1801 """ 1802 Create an agent 1803 Creates a new agent. Supports two mutually exclusive provisioning modes. 1804 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1805 AgentTemplate config. The agent's tools, routines, skills, and installations are 1806 provisioned from that template's `config_ref` entries. 1807 **Bundle mode** pass `template_bundle` with a self-contained install payload 1808 (AgentTemplate body plus every skill, script, and config it references). The entire 1809 bundle commits in a single transaction; any failure rolls back the whole install and 1810 the response includes `installed_configs[]` one entry per persisted config. 1811 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1812 is required and a blank agent is created. Requires authentication; when called under 1813 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1814 for the target app. 1815 1816 Args: 1817 input: Request body. 1818 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1819 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1820 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1821 input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org. 1822 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1823 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1824 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1825 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1826 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1827 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1828 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1829 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1830 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1831 input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`. 1832 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1833 1834 Returns: 1835 The newly created agent. When `template_bundle` was supplied, the response also includes `installed_configs[]` one entry per persisted config object, with `key` echoing the caller-supplied input identifier. 1836 """ 1837 return self._http.request( 1838 "/api/v1/agents", 1839 method="POST", 1840 body=input, 1841 response_type=AgentCreateResponse, 1842 )
Create an agent
Creates a new agent. Supports two mutually exclusive provisioning modes.
Template mode pass template with the ID or lookup_key of an existing
AgentTemplate config. The agent's tools, routines, skills, and installations are
provisioned from that template's config_ref entries.
Bundle mode pass template_bundle with a self-contained install payload
(AgentTemplate body plus every skill, script, and config it references). The entire
bundle commits in a single transaction; any failure rolls back the whole install and
the response includes installed_configs[] one entry per persisted config.
Pass exactly one of template or template_bundle. If neither is supplied, name
is required and a blank agent is created. Requires authentication; when called under
a developer app scope (/developer/apps/:app/...), the caller must hold the app scope
for the target app.
Arguments:
- input: Request body.
- input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent.
- input.email: Email address assigned to the agent. Used as the agent's contact identity.
- input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
- input.lookup_key: Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
- input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform.
- input.model: Default AI model identifier for this agent, e.g.
claude-sonnet-4-5. Overridden per-request when the caller specifies a model. - input.name: Display name for the agent. Required when neither
templatenortemplate_bundleis provided. - input.org: Organization ID (
org_...) that should own this agent. Mutually exclusive withteamanduser. - input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
- input.phone_number: Phone number assigned to the agent in E.164 format, e.g.
+15550001234. - input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present.
- input.team: Team ID (
team_...) that should own this agent. Mutually exclusive withorganduser. - input.template: ID (
cfg_...) orlookup_keyof an existing AgentTemplate config to provision from. Mutually exclusive withtemplate_bundle. - input.template_bundle: Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with
template. - input.user: User ID (
usr_...) that should own this agent. Mutually exclusive withorgandteam.
Returns:
The newly created agent. When
template_bundlewas supplied, the response also includesinstalled_configs[]one entry per persisted config object, withkeyechoing the caller-supplied input identifier.
def
delete(self, agent: str) -> None:
1844 def delete(self, agent: str) -> None: 1845 """ 1846 Delete an agent 1847 Permanently deletes an agent and all of its associated resources. This action cannot 1848 be undone. 1849 The authenticated caller must own the agent or hold sufficient permissions within its 1850 owning org or team. When called under a developer app scope, the caller must hold the 1851 app scope for the target app. 1852 1853 Args: 1854 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1855 1856 Returns: 1857 Empty body. Returns HTTP 204 on success. 1858 """ 1859 self._http.request(f"/api/v1/agents/{agent}", method="DELETE")
Delete an agent Permanently deletes an agent and all of its associated resources. This action cannot be undone. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to delete.
Returns:
Empty body. Returns HTTP 204 on success.
1861 def get(self, agent: str) -> Agent: 1862 """ 1863 Retrieve an agent 1864 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1865 own the agent or hold sufficient permissions within its owning org or team. 1866 When called under a developer app scope, the agent must belong to that app. Use the 1867 list endpoint to retrieve many agents at once. 1868 1869 Args: 1870 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1871 1872 Returns: 1873 The requested agent. 1874 """ 1875 return self._http.request(f"/api/v1/agents/{agent}", response_type=Agent)
Retrieve an agent
Returns the agent identified by ID or lookup_key. The authenticated caller must
own the agent or hold sufficient permissions within its owning org or team.
When called under a developer app scope, the agent must belong to that app. Use the
list endpoint to retrieve many agents at once.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to retrieve.
Returns:
The requested agent.
1877 def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1878 """ 1879 Update an agent 1880 Updates one or more fields on an existing agent. Only the fields you supply are 1881 changed; omitted fields retain their current values. 1882 To clear the agent's default model, pass `model` as an empty string. The 1883 authenticated caller must own the agent or hold write permissions within its owning 1884 org or team. When called under a developer app scope, the caller must hold the app 1885 scope for the target app. 1886 1887 Args: 1888 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1889 input: Request body. 1890 input.acl: Replacement access control list. Fully replaces the existing ACL. 1891 input.email: New email address for the agent. 1892 input.identity: Replacement identity system-prompt string describing who the agent is. 1893 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1894 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1895 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1896 input.name: New display name for the agent. 1897 input.org: Organization ID (`org_...`) to transfer ownership to. 1898 input.originator: Replacement originator label identifying the source or author of the agent. 1899 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1900 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1901 input.team: Team ID (`team_...`) to transfer ownership to. 1902 input.user: User ID (`usr_...`) to transfer ownership to. 1903 1904 Returns: 1905 The updated agent with all current field values. 1906 """ 1907 return self._http.request( 1908 f"/api/v1/agents/{agent}", 1909 method="PATCH", 1910 body=input, 1911 response_type=Agent, 1912 )
Update an agent
Updates one or more fields on an existing agent. Only the fields you supply are
changed; omitted fields retain their current values.
To clear the agent's default model, pass model as an empty string. The
authenticated caller must own the agent or hold write permissions within its owning
org or team. When called under a developer app scope, the caller must hold the app
scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to update. - input: Request body.
- input.acl: Replacement access control list. Fully replaces the existing ACL.
- input.email: New email address for the agent.
- input.identity: Replacement identity system-prompt string describing who the agent is.
- input.lookup_key: New
lookup_keyslug. Must be unique within the owning app or org. - input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged.
- input.model: New default AI model identifier, e.g.
claude-sonnet-4-5. Pass an empty string to clear the agent's default model. - input.name: New display name for the agent.
- input.org: Organization ID (
org_...) to transfer ownership to. - input.originator: Replacement originator label identifying the source or author of the agent.
- input.phone_number: New phone number for the agent in E.164 format, e.g.
+15550001234. - input.profile_picture: Replacement profile picture. All three subfields are required when this object is present.
- input.team: Team ID (
team_...) to transfer ownership to. - input.user: User ID (
usr_...) to transfer ownership to.
Returns:
The updated agent with all current field values.
def
agent_health_actions( self, agent: str, *, source: list[str] | None = None, status: list[str] | None = None, kind: list[str] | None = None) -> archastro.platform.types.common.HealthActionListResponse:
1914 def agent_health_actions( 1915 self, 1916 agent: str, 1917 *, 1918 source: builtins.list[str] | None = None, 1919 status: builtins.list[str] | None = None, 1920 kind: builtins.list[str] | None = None, 1921 ) -> HealthActionListResponse: 1922 """ 1923 List health actions for an agent 1924 Returns all health actions associated with a given agent. Health actions 1925 represent required or recommended steps such as setting environment 1926 variables, completing OAuth installations, or running custom verifiers 1927 that an agent needs to reach a healthy state. 1928 Results are not paginated; the full list for the agent is returned. Use 1929 the `source`, `status`, and `kind` filters to narrow results to the 1930 subset your UI or workflow needs. Multiple values for the same filter 1931 are treated as OR (e.g. passing two statuses returns actions matching 1932 either). The caller must be authenticated and scoped to the app that 1933 owns the agent. 1934 1935 Args: 1936 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1937 source: Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages. 1938 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1939 kind: Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds. 1940 1941 Returns: 1942 Object containing a `data` array of health action objects for the specified agent. 1943 """ 1944 query: dict[str, object] = {} 1945 if source is not None: 1946 query["source"] = source 1947 if status is not None: 1948 query["status"] = status 1949 if kind is not None: 1950 query["kind"] = kind 1951 return self._http.request( 1952 f"/api/v1/agents/{agent}/agent_health_actions", 1953 query=query, 1954 response_type=HealthActionListResponse, 1955 )
List health actions for an agent
Returns all health actions associated with a given agent. Health actions
represent required or recommended steps such as setting environment
variables, completing OAuth installations, or running custom verifiers
that an agent needs to reach a healthy state.
Results are not paginated; the full list for the agent is returned. Use
the source, status, and kind filters to narrow results to the
subset your UI or workflow needs. Multiple values for the same filter
are treated as OR (e.g. passing two statuses returns actions matching
either). The caller must be authenticated and scoped to the app that
owns the agent.
Arguments:
- agent: Agent ID (
agt_...) or lookup key of the agent whose health actions you want to list. - source: Filter results to actions from one or more lifecycle stages. Accepted values:
"setup"(actions created during agent installation) and"health"(ongoing health checks). Omit to return actions from all stages. - status: Filter results to actions in one or more statuses. Accepted values:
"pending","completed","skipped", and"degraded". Omit to return actions in all statuses. - kind: Filter results to actions of one or more kinds. Accepted values:
"env_var"(a required secret or config value),"install"(an OAuth or integration install step), and"custom"(a platform-defined check). Omit to return all kinds.
Returns:
Object containing a
dataarray of health action objects for the specified agent.
def
agent_routines( self, agent: str, input: AgentAgentRoutinesInput) -> archastro.platform.types.common.AgentRoutine:
1957 def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1958 """ 1959 Create a routine 1960 Creates a new routine and attaches it to the specified agent. Routines define 1961 how an agent responds to events or a cron schedule; the `handler_type` controls 1962 which execution model is used. 1963 The routine is created in `"draft"` status by default. To start processing 1964 events immediately, either pass `status: "active"` or call the activate 1965 endpoint after creation. Scheduled routines must run no more frequently than 1966 once per hour. Requires app scope. 1967 1968 Args: 1969 agent: Agent ID (`agt_...`) that this routine will be attached to. 1970 input: Request body. 1971 input.acl: Access control list governing who can read or manage this routine. 1972 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1973 input.description: Optional human-readable description of what this routine does. 1974 input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`). 1975 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1976 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1977 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1978 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1979 input.name: Human-readable display name for the routine. 1980 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1981 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1982 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1983 input.script: Inline script source. Required when `handler_type` is `"script"`. 1984 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1985 input.steps: Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`. 1986 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1987 1988 Returns: 1989 The newly created routine. 1990 """ 1991 return self._http.request( 1992 f"/api/v1/agents/{agent}/agent_routines", 1993 method="POST", 1994 body=input, 1995 response_type=AgentRoutine, 1996 )
Create a routine
Creates a new routine and attaches it to the specified agent. Routines define
how an agent responds to events or a cron schedule; the handler_type controls
which execution model is used.
The routine is created in "draft" status by default. To start processing
events immediately, either pass status: "active" or call the activate
endpoint after creation. Scheduled routines must run no more frequently than
once per hour. Requires app scope.
Arguments:
- agent: Agent ID (
agt_...) that this routine will be attached to. - input: Request body.
- input.acl: Access control list governing who can read or manage this routine.
- input.config: Workflow config ID (
cfg_...). Required whenhandler_typeis"workflow_graph". - input.description: Optional human-readable description of what this routine does.
- input.event_config: Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a
"filters"map and an optional"dedupe_key_path"(a JSON path used to deduplicate events, e.g."$.thread.id"). - input.event_type: Event type that triggers this routine. Deprecated use
event_configinstead. - input.handler_type: Execution model for this routine. One of
"workflow_graph","script","preset", or"chain". - input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.
- input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.
- input.name: Human-readable display name for the routine.
- input.preset_config: Configuration passed to the preset at runtime. Used when
handler_typeis"preset". - input.preset_name: Name of the registered preset to use. Required when
handler_typeis"preset". - input.schedule: Cron expression for time-triggered routines (e.g.
"0 9 * * 1"). Must not be more frequent than once per hour. - input.script: Inline script source. Required when
handler_typeis"script". - input.status: Initial lifecycle status. One of
"draft"or"active". Defaults to"draft". - input.steps: Ordered list of steps for a chain handler. Required when
handler_typeis"chain"; must be omitted or empty otherwise. Each step must have exactly one handler body field (preset_name,script, orconfig) matching that step'shandler_type. - input.trigger_context: Context in which the routine is triggered. One of
"chat_session"or"event". Defaults to"event".
Returns:
The newly created routine.
def
agent_working_memory( self, agent: str, *, page: int | None = None, page_size: int | None = None, search: str | None = None) -> archastro.platform.types.common.WorkingMemoryEntryListResponse:
1998 def agent_working_memory( 1999 self, 2000 agent: str, 2001 *, 2002 page: int | None = None, 2003 page_size: int | None = None, 2004 search: str | None = None, 2005 ) -> WorkingMemoryEntryListResponse: 2006 """ 2007 List working memory entries for an agent 2008 Returns a paginated list of working memory entries belonging to the specified 2009 agent. Entries are key-value pairs the agent stores for context between 2010 interactions. Results are ordered by creation time descending (newest first) 2011 and can be filtered with a substring search against the key name. 2012 Requires an app-scoped API key. The authenticated caller must have access to 2013 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 2014 404 if the agent does not exist within the accessible scope. 2015 2016 Args: 2017 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2018 page: Page number to retrieve, starting at 1. Defaults to 1. 2019 page_size: Number of entries to return per page. Defaults to 25. 2020 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 2021 2022 Returns: 2023 Paginated list of working memory entries for the agent. 2024 """ 2025 query: dict[str, object] = {} 2026 if page is not None: 2027 query["page"] = page 2028 if page_size is not None: 2029 query["page_size"] = page_size 2030 if search is not None: 2031 query["search"] = search 2032 return self._http.request( 2033 f"/api/v1/agents/{agent}/agent_working_memory", 2034 query=query, 2035 response_type=WorkingMemoryEntryListResponse, 2036 )
List working memory entries for an agent Returns a paginated list of working memory entries belonging to the specified agent. Entries are key-value pairs the agent stores for context between interactions. Results are ordered by creation time descending (newest first) and can be filtered with a substring search against the key name. Requires an app-scoped API key. The authenticated caller must have access to the app the agent belongs to. Returns 403 if the key is not app-scoped, and 404 if the agent does not exist within the accessible scope.
Arguments:
- agent: Agent ID (
agt_...) whose working memory entries to retrieve. - page: Page number to retrieve, starting at 1. Defaults to 1.
- page_size: Number of entries to return per page. Defaults to 25.
- search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys.
Returns:
Paginated list of working memory entries for the agent.
def
export( self, agent: str, *, remove_identity: bool | None = None) -> archastro.platform.types.common.AgentExport:
2038 def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 2039 """ 2040 Export an agent as an AgentTemplate 2041 Reconstructs an AgentTemplate config from a deployed agent and all of its 2042 sub-resources (tools, routines, skills, installations). Returns the template 2043 definition together with every dependent config file (scripts, workflows, skills, 2044 schemas) and their raw content, producing a fully self-contained export bundle. 2045 Use this endpoint to snapshot an agent's current configuration for backup, 2046 migration, or to seed a new Solution template. Pass `remove_identity: true` to 2047 strip instance-specific fields (email, phone number) before export. 2048 The authenticated caller must own the agent or hold sufficient permissions within 2049 its owning org or team. When called under a developer app scope, the caller must 2050 hold the app scope for the target app. 2051 2052 Args: 2053 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 2054 remove_identity: When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint. 2055 2056 Returns: 2057 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 2058 """ 2059 query: dict[str, object] = {} 2060 if remove_identity is not None: 2061 query["remove_identity"] = remove_identity 2062 return self._http.request( 2063 f"/api/v1/agents/{agent}/export", 2064 query=query, 2065 response_type=AgentExport, 2066 )
Export an agent as an AgentTemplate
Reconstructs an AgentTemplate config from a deployed agent and all of its
sub-resources (tools, routines, skills, installations). Returns the template
definition together with every dependent config file (scripts, workflows, skills,
schemas) and their raw content, producing a fully self-contained export bundle.
Use this endpoint to snapshot an agent's current configuration for backup,
migration, or to seed a new Solution template. Pass remove_identity: true to
strip instance-specific fields (email, phone number) before export.
The authenticated caller must own the agent or hold sufficient permissions within
its owning org or team. When called under a developer app scope, the caller must
hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to export. - remove_identity: When
true, strips instance-unique identity fields (email,phone_number) from the exported template so it can be reused as a generic blueprint.
Returns:
Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content.
2068 def health(self, agent: str) -> AgentHealth: 2069 """ 2070 Retrieve an agent's health profile 2071 Returns an aggregate health profile for the specified agent, including an overall 2072 status, a numeric health score, recent activity metrics, and a list of recommended 2073 remediation actions. 2074 The health check is computed on demand at request time. The `checked_at` timestamp 2075 in the response reflects when the evaluation ran. Use this endpoint to surface 2076 diagnostics about tool availability, model configuration, and runtime activity in 2077 dashboards or monitoring workflows. 2078 The authenticated caller must own the agent or hold sufficient permissions within 2079 its owning org or team. When called under a developer app scope, the caller must 2080 hold the app scope for the target app. 2081 2082 Args: 2083 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 2084 2085 Returns: 2086 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 2087 """ 2088 return self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth)
Retrieve an agent's health profile
Returns an aggregate health profile for the specified agent, including an overall
status, a numeric health score, recent activity metrics, and a list of recommended
remediation actions.
The health check is computed on demand at request time. The checked_at timestamp
in the response reflects when the evaluation ran. Use this endpoint to surface
diagnostics about tool availability, model configuration, and runtime activity in
dashboards or monitoring workflows.
The authenticated caller must own the agent or hold sufficient permissions within
its owning org or team. When called under a developer app scope, the caller must
hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to evaluate.
Returns:
Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions.
2090 def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 2091 """ 2092 Search an agent's knowledge base 2093 Performs a semantic search over an agent's knowledge base and returns a ranked, 2094 `kind`-discriminated list of matching items. 2095 Two item kinds may appear in `data`: 2096 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 2097 - `"document"` document-level results. Present only when the agent has an active 2098 `archastro/knowledge` installation. 2099 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 2100 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 2101 chunks appear before documents. The total number of results is capped at `max_results` 2102 across both kinds. 2103 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 2104 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 2105 2106 Args: 2107 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 2108 input: Request body. 2109 input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`. 2110 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 2111 input.query: Natural-language search query used to retrieve relevant knowledge items. 2112 input.recency_days: When set, restricts results to items indexed within the last N days. 2113 input.source_types: Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types. 2114 2115 Returns: 2116 Successful response 2117 """ 2118 return self._http.request( 2119 f"/api/v1/agents/{agent}/search", 2120 method="POST", 2121 body=input, 2122 response_type=AgentSearchResponse, 2123 )
Search an agent's knowledge base
Performs a semantic search over an agent's knowledge base and returns a ranked,
kind-discriminated list of matching items.
Two item kinds may appear in data:
"chunk"chunk-level results from the agent's context store. Present for all agents."document"document-level results. Present only when the agent has an activearchastro/knowledgeinstallation. Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to be comparable across kinds, then merged into a single ranked list. On a relevance tie, chunks appear before documents. The total number of results is capped atmax_resultsacross both kinds. Usemodeto choose the retrieval strategy:"hybrid"(default) combines vector and full-text search;"vector"and"fulltext"select each strategy independently.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent whose knowledge base to search. - input: Request body.
- input.max_results: Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to
20; maximum is100. - input.mode: Retrieval strategy. One of
"hybrid"(default),"vector", or"fulltext". - input.query: Natural-language search query used to retrieve relevant knowledge items.
- input.recency_days: When set, restricts results to items indexed within the last N days.
- input.source_types: Array of source-type slugs used to filter chunk results, e.g.
["web", "file"]. Omit to include all source types.
Returns:
Successful response
def
threads( self, agent: str, input: AgentThreadsInput) -> archastro.platform.types.threads.Thread:
2125 def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 2126 """ 2127 Create a thread for an agent 2128 Creates a new thread owned by the specified agent. The thread is scoped to the 2129 agent's identity and is immediately available for messaging. 2130 The authenticated caller must have access to the agent's parent app. If your 2131 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 2132 Attempting to create a thread for an agent you cannot access returns 404. 2133 By default the platform may send an automatic welcome message into the new 2134 thread. Pass `skip_welcome_message: true` to suppress this behavior. 2135 2136 Args: 2137 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 2138 input: Request body. 2139 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 2140 input.thread: Attributes for the new thread. 2141 2142 Returns: 2143 The newly created thread. 2144 """ 2145 return self._http.request( 2146 f"/api/v1/agents/{agent}/threads", 2147 method="POST", 2148 body=input, 2149 response_type=Thread, 2150 )
Create a thread for an agent
Creates a new thread owned by the specified agent. The thread is scoped to the
agent's identity and is immediately available for messaging.
The authenticated caller must have access to the agent's parent app. If your
API key is scoped to a specific app, pass that app's ID via the app parameter.
Attempting to create a thread for an agent you cannot access returns 404.
By default the platform may send an automatic welcome message into the new
thread. Pass skip_welcome_message: true to suppress this behavior.
Arguments:
- agent: Agent ID (
agt_...). The thread will be owned by this agent. - input: Request body.
- input.skip_welcome_message: When
true, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults tofalse. - input.thread: Attributes for the new thread.
Returns:
The newly created thread.
def
upgrade( self, agent: str, input: AgentUpgradeInput) -> archastro.platform.types.common.AgentUpgradeResponse:
2152 def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 2153 """ 2154 Upgrade an agent from an AgentTemplate 2155 Upgrades an existing agent by reconciling it against an AgentTemplate from a 2156 Solution. Supports two modes: 2157 - `"reapply"` (default) re-applies the agent's currently tracked template, 2158 picking up any changes the template author has made since the last apply. 2159 - `"replace"` moves the agent to a different template. `template` is required 2160 in this mode. 2161 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 2162 removes, noops) without writing any changes. The response includes a 2163 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 2164 live apply to guard against the diff changing between review and execution. 2165 Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, 2166 `originator`, `model`) let you pin instance-specific values that should not be 2167 overwritten by the template during the upgrade. 2168 The authenticated caller must own the agent or hold write permissions within its 2169 owning org or team. When called under a developer app scope, the caller must hold 2170 the app scope for the target app. 2171 2172 Args: 2173 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 2174 input: Request body. 2175 input.dry_run: When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply. 2176 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 2177 input.expected_review_fingerprint: Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. 2178 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 2179 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 2180 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 2181 input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model. 2182 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 2183 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 2184 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 2185 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 2186 2187 Returns: 2188 The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (`upgrade_result`) with status, dry-run flag, aggregate counts, and a per-resource change list. When `dry_run` is `true`, `agent` is `null` and no changes are persisted. 2189 """ 2190 return self._http.request( 2191 f"/api/v1/agents/{agent}/upgrade", 2192 method="POST", 2193 body=input, 2194 response_type=AgentUpgradeResponse, 2195 )
Upgrade an agent from an AgentTemplate Upgrades an existing agent by reconciling it against an AgentTemplate from a Solution. Supports two modes:
"reapply"(default) re-applies the agent's currently tracked template, picking up any changes the template author has made since the last apply."replace"moves the agent to a different template.templateis required in this mode. Setdry_run: trueto compute and return the full upgrade diff (adds, updates, removes, noops) without writing any changes. The response includes areview_fingerprintyou can pass back viaexpected_review_fingerprinton the live apply to guard against the diff changing between review and execution. Safe overrides (name,email,phone_number,metadata,identity,originator,model) let you pin instance-specific values that should not be overwritten by the template during the upgrade. The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.
Arguments:
- agent: ID (
agi_...) orlookup_keyof the agent to upgrade. - input: Request body.
- input.dry_run: When
true, computes and returns the full upgrade diff without persisting any changes. Use withexpected_review_fingerprintto guard the live apply. - input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.
- input.expected_review_fingerprint: Stale-review guard. Pass the
review_fingerprintreturned by a priordry_runresponse to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches. - input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.
- input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.
- input.mode: Upgrade mode.
"reapply"(default) refreshes the agent's tracked template;"replace"moves the agent to a different template (requirestemplate). - input.model: Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.
- input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it.
- input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.
- input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it.
- input.template: ID (
cfg_...) orlookup_keyof the target AgentTemplate config. Optional in"reapply"mode; required in"replace"mode.
Returns:
The upgrade outcome, including the updated agent, the source Solution and template summaries, and the full diff (
upgrade_result) with status, dry-run flag, aggregate counts, and a per-resource change list. Whendry_runistrue,agentisnulland no changes are persisted.